WIP vtlib typescript/Deno library

.github/workflows/docs.yaml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Set up Deno
+        uses: denoland/setup-deno@v1
+        with:
+          deno-version: "2.x"
+
+      - name: Check out the code
+        uses: actions/checkout@v2
+
+      - name: Generate documentation
+        run: deno task doc
+
+      - name: Upload the docs to Val Town Electric
+        run: cd docs && deno run -A https://esm.town/v/wolf/VTDocs/cli/mod.ts upload
+        env:
+          ELECTRIC_ROOT_URL: https://vt-docs.val.run
+          ELECTRIC_MASTER_BEARER: ${{ secrets.ELECTRIC_MASTER_BEARER }}

.gitignore

@@ -1,4 +1,5 @@
 tinker
+docs
 
 # Created by https://www.toptal.com/developers/gitignore/api/deno
 # Edit at https://www.toptal.com/developers/gitignore?templates=deno
@@ -16,4 +17,4 @@ tinker
 
 # End of https://www.toptal.com/developers/gitignore/api/deno
 
-.DS_Store
+.DS_Store

deno.json

@@ -11,7 +11,9 @@
     "test:cmd": "env DENO_NO_PROMPT=1 deno test -A --trace-leaks --fail-fast ./src/cmd",
     "test:lib": "env DENO_NO_PROMPT=1 deno test -A --trace-leaks --parallel ./src/vt/lib",
     "check": "env DENO_NO_PROMPT=1 deno check .",
-    "fmt:check": "env DENO_NO_PROMPT=1 deno fmt --check"
+    "fmt": "env DENO_NO_PROMPT=1 deno fmt --ignore=docs",
+    "fmt:check": "env DENO_NO_PROMPT=1 deno fmt --check",
+    "doc": "deno doc --html --name='vtlib' --output=docs mod.ts"
   },
   "imports": {
     "@std/random": "jsr:@std/random@^0.1.0",

mod.ts

@@ -1 +1,81 @@
+#!/usr/bin/env -S deno run --allow-read --allow-write --allow-env --allow-net --allow-sys --allow-run
+import { launch } from "./vt.ts";
+
+/**
+ * # vtlib
+ *
+ * ### What is `vtlib`?
+ * `vtlib` is the internal library used by `vt`, the Val Town CLI. `vtlib` lets
+ * you do `push`ing, `pull`ing, `clone`ing, and more, from a Deno context, so
+ * that you can reuse much of the internal syncing functionality of `vt`.
+ *
+ * Primary library functions include
+ *
+ * - {@link checkout} Check out a branch from a Val Town project
+ * - {@link clone} Clone a Val Town project to a local directory
+ * - {@link create} Create a new Val Town project from local files
+ * - {@link pull} Pull changes from a Val Town project to a local directory
+ * - {@link push} Push local changes to a Val Town project
+ * - {@link remix} Create a new project based on an existing project
+ * - {@link status} Check the status of local files compared to a Val Town project
+ *
+ * @example Clone a project to a directory
+ * ```typescript
+ * import { clone } from "@valtown/vt";
+ *
+ * const result = await clone({
+ *   projectId: "d23e2d8d-9cc8-40e3-bbf4-107c42efe6c1",
+ *   branchId: "0e73994d-f9bd-4e59-a255-7f4593127623",
+ *   targetDir: "./my-project"
+ * });
+ * ```
+ *
+ * @example Push changes to a project
+ * ```typescript
+ * import { push } from "@valtown/vt";
+ *
+ * const result = await push({
+ *   projectId: "c085baed-ec07-4a2e-811a-216f567b5ef1",
+ *   targetDir: "."
+ * });
+ * ```
+ *
+ * @example Create a new project from local files
+ * ```typescript
+ * import { create } from "@valtown/vt";
+ *
+ * const result = await create({
+ *   projectId: "01b34cb3-f581-47c9-8024-ae126c0f0b1e",
+ *   sourceDir: "./my-code"
+ * });
+ * ```
+ *
+ * @example Check status of local files compared to remote
+ * ```typescript
+ * import { status } from "@valtown/vt";
+ *
+ * const result = await status({
+ *   projectId: "79af7bd7-3e5b-4492-8b14-dac502cdbce6",
+ *   targetDir: "."
+ * });
+ * ```
+ *
+ * @example Remix an existing project
+ * ```typescript
+ * import { remix } from "@valtown/vt";
+ *
+ * const result = await remix({
+ *   srcProjectId: "a35e5f60-5a47-4201-9d82-b6a60bd57d4d",
+ *   projectName: "My Remix",
+ *   targetDir: "./remixed-project"
+ * });
+ * ```
+ *
+ * @module
+ */
+
+if (import.meta.main) {
+  await launch();
+}
+
 export * from "~/vt/lib/mod.ts";

src/cmd/lib/branch.ts

@@ -1,5 +1,5 @@
 import { Command } from "@cliffy/command";
-import sdk, { branchNameToBranch } from "~/sdk.ts";
+import sdk, { branchNameToBranch } from "../../utils/sdk.ts";
 import { colors } from "@cliffy/ansi/colors";
 import { Table } from "@cliffy/table";
 import { doWithSpinner } from "~/cmd/utils.ts";

src/cmd/lib/browse.ts

@@ -1,6 +1,6 @@
 import { Command } from "@cliffy/command";
 import open from "open";
-import sdk from "~/sdk.ts";
+import sdk from "../../utils/sdk.ts";
 import { doWithSpinner } from "~/cmd/utils.ts";
 import VTClient from "~/vt/vt/VTClient.ts";
 import { findVtRoot } from "~/vt/vt/utils.ts";

src/cmd/lib/checkout.ts

@@ -6,7 +6,7 @@ import { findVtRoot } from "~/vt/vt/utils.ts";
 import { colors } from "@cliffy/ansi/colors";
 import { Confirm } from "@cliffy/prompt";
 import { tty } from "@cliffy/ansi/tty";
-import sdk, { getCurrentUser } from "~/sdk.ts";
+import sdk, { getCurrentUser } from "../../utils/sdk.ts";
 import { displayFileStateChanges } from "~/cmd/lib/utils/displayFileStatus.ts";
 import { noChangesDryRunMsg } from "~/cmd/lib/utils/messages.ts";
 

src/cmd/lib/clone.ts

@@ -1,7 +1,7 @@
 import { Command } from "@cliffy/command";
 import { Input } from "@cliffy/prompt/input";
 import { colors } from "@cliffy/ansi/colors";
-import sdk, { getCurrentUser } from "~/sdk.ts";
+import sdk, { getCurrentUser } from "../../utils/sdk.ts";
 import VTClient from "~/vt/vt/VTClient.ts";
 import { relative } from "@std/path";
 import { doWithSpinner, getClonePath } from "~/cmd/utils.ts";
@@ -10,7 +10,7 @@ import { Confirm } from "@cliffy/prompt";
 import { ensureAddEditorFiles } from "~/cmd/lib/utils/messages.ts";
 import { parseValUrl } from "~/cmd/parsing.ts";
 import { DEFAULT_BRANCH_NAME, DEFAULT_EDITOR_TEMPLATE } from "~/consts.ts";
-import { arrayFromAsyncN } from "~/utils.ts";
+import { arrayFromAsyncN } from "~/utils/mod.ts";
 
 export const cloneCmd = new Command()
   .name("clone")