docks-kit 0.1.0 → 0.1.2

package/cli/src/engine.ts

@@ -1,21 +1,30 @@
-import { Command as Subprocess } from "@effect/platform"
 import { Console, Effect } from "effect"
+import { spawnSync } from "node:child_process"
+import { runEngineNative } from "./engine-native"
 import { kitHome } from "./kitHome"
 
 /**
- * The single seam between the typed CLI and the bash engine. All mutation runs
- * through lib/engine.sh (same flag vocabulary as this CLI), so the engine stays
- * independently usable as the zero-dependency escape hatch.
+ * The single seam between the typed CLI and EngineNative. Engine execution
+ * stays in-process after @effect/cli has parsed pickers and flag spellings.
  */
+const bashRemovedMessage = "bash engine removed — recover at tag bash-engine-final"
+const bashEngineRequested = (): boolean => process.env["DOCKS_KIT_ENGINE"] === "bash"
+
+// bun build --compile runs the embedded entry from a virtual path
+// ("/$bunfs/root/…" on POSIX, "B:\~BUN\root\…" on Windows). There
+// process.execPath IS the CLI, so a re-spawn must not pass main.ts.
+// The Windows check is anchored to the drive-rooted "~BUN" segment so a
+// real checkout under a ~BUN-named directory can't false-positive.
+export const compiled =
+  process.argv[1] !== undefined &&
+  (process.argv[1].startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/i.test(process.argv[1]))
+
 export const engine = (args: ReadonlyArray<string>) =>
   Effect.gen(function* () {
-    const code = yield* Subprocess.make("bash", join("lib/engine.sh"), ...args).pipe(
-      Subprocess.workingDirectory(kitHome()),
-      Subprocess.stdin("inherit"),
-      Subprocess.stdout("inherit"),
-      Subprocess.stderr("inherit"),
-      Subprocess.exitCode
-    )
+    if (bashEngineRequested()) {
+      yield* bail(bashRemovedMessage, 2)
+    }
+    const code = yield* Effect.sync(() => runEngineNative(args))
     if (code !== 0) {
       yield* Effect.sync(() => process.exit(code))
     }
@@ -23,13 +32,21 @@ export const engine = (args: ReadonlyArray<string>) =>
 
 /** Run the engine capturing stdout (engine logs/warns go to stderr and pass through). */
 export const engineCapture = (args: ReadonlyArray<string>) =>
-  Subprocess.make("bash", join("lib/engine.sh"), ...args).pipe(
-    Subprocess.workingDirectory(kitHome()),
-    Subprocess.stderr("inherit"),
-    Subprocess.string
-  )
-
-const join = (rel: string): string => `${kitHome()}/${rel}`
+  bashEngineRequested()
+    ? bail(bashRemovedMessage, 2)
+    : Effect.sync(() => {
+      // Child process (raw channel): runEngineNative writes straight to
+      // process.stdout, so in-process capture isn't possible.
+      const res = spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
+        env: { ...process.env, DOCKS_KIT_ENGINE: "native-raw" },
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "inherit"]
+      })
+      if (res.error !== undefined || res.status !== 0) {
+        process.stderr.write(`\x1b[1;33m[warn]\x1b[0m engine capture failed (${args.join(" ")} exited ${res.status ?? "spawn-error"})\n`)
+      }
+      return res.stdout ?? ""
+    })
 
 /** Print a message to stderr and exit — for CLI-side validation failures. */
 export const bail = (message: string, code = 2) =>

package/cli/src/kitHome.ts

@@ -2,19 +2,19 @@ import { existsSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 
 const isKitHome = (dir: string): boolean =>
-  existsSync(join(dir, "SoT")) && existsSync(join(dir, "lib", "engine.sh"))
+  existsSync(join(dir, "SoT")) && existsSync(join(dir, "package.json"))
 
 /**
- * Resolve the kit home (the directory holding SoT/ + lib/engine.sh):
+ * Resolve the kit home (the directory holding SoT/ + package.json):
  * DOCKS_KIT_HOME env → nearest ancestor of cwd (repo-checkout usage) →
  * the package's own root (bunx / bun add -g usage: main.ts lives at
- * <root>/cli/src, and the npm package bundles SoT/ + lib/ alongside).
+ * <root>/cli/src, and the npm package bundles SoT/ alongside).
  */
 export const kitHome = (): string => {
   const env = process.env["DOCKS_KIT_HOME"]
   if (env !== undefined && env !== "") {
     if (isKitHome(env)) return env
-    throw new Error(`DOCKS_KIT_HOME=${env} does not contain SoT/ + lib/engine.sh`)
+    throw new Error(`DOCKS_KIT_HOME=${env} does not contain SoT/ + package.json`)
   }
   let dir = process.cwd()
   for (;;) {

package/cli/src/main.ts

@@ -10,12 +10,14 @@ import { skillsCommand } from "./commands/skills"
 import { statusCommand } from "./commands/status"
 import { syncCommand } from "./commands/sync"
 import { toolchainCommand } from "./commands/toolchain"
+import { updateCommand } from "./commands/update"
 
 const root = Command.make("docks-kit", {}, () =>
   Effect.gen(function* () {
     yield* Console.log("docks-kit — portable AI coding agent config kit")
     yield* Console.log("")
     yield* Console.log("  docks-kit sync [claude] [codex] [agents]   deploy the SoT to this machine")
+    yield* Console.log("  docks-kit update [--no-sync]              self-update the kit, then sync")
     yield* Console.log("  docks-kit model <claude|codex> [value]     get/set the deployed model")
     yield* Console.log("  docks-kit models [tool]                    kit-verified model catalog")
     yield* Console.log("  docks-kit toolchain [check|ensure <tool>]  verified-version floors")
@@ -25,7 +27,7 @@ const root = Command.make("docks-kit", {}, () =>
     yield* Console.log("  docks-kit docs [topic]                     self-documentation")
     yield* Console.log("")
     yield* Console.log("Run 'docks-kit --help' for full option listings (also: --wizard, --completions).")
-    yield* Console.log("Zero-dependency escape hatch: bash lib/engine.sh <same subcommands/flags>")
+    yield* Console.log("No-Bun recovery path: use a platform release binary.")
   })
 ).pipe(
   Command.withDescription(
@@ -33,6 +35,7 @@ const root = Command.make("docks-kit", {}, () =>
   ),
   Command.withSubcommands([
     syncCommand,
+    updateCommand,
     modelCommand,
     modelsCommand,
     toolchainCommand,
@@ -43,6 +46,16 @@ const root = Command.make("docks-kit", {}, () =>
   ])
 )
 
+// Harness-private raw channel:
+// `DOCKS_KIT_ENGINE=native-raw` bypasses @effect/cli and hands the raw engine
+// argv to EngineNative so golden tests drive the internal vocabulary directly.
+// PUBLIC engine execution lives at the engine.ts seam after the CLI has
+// parsed/normalized pickers, --flag value forms, and non-engine commands.
+if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
+  const { runEngineNative } = await import("./engine-native")
+  process.exit(runEngineNative(process.argv.slice(2)))
+}
+
 const cli = Command.run(root, {
   name: "docks-kit",
   version: "0.1.0"

package/cli/src/manifests.ts

@@ -1,7 +1,10 @@
 import { readFileSync, readdirSync, readlinkSync, existsSync } from "node:fs"
+import { homedir } from "node:os"
 import { join } from "node:path"
 import { kitHome } from "./kitHome"
 
+export { homedir }
+
 export interface ModelEntry {
   readonly id: string
   readonly kind: "alias" | "id"
@@ -44,8 +47,6 @@ export const sotCodexModel = (): string | undefined =>
 export const deployedCodexModel = (): string | undefined =>
   tomlModel(join(homedir(), ".codex", "config.toml"))
 
-export const homedir = (): string => process.env["HOME"] ?? "~"
-
 /** Installed plugins (user scope) vs SoT enabledPlugins tri-state. */
 export const pluginsView = (): Array<{
   plugin: string

package/cli/tsconfig.json

@@ -10,5 +10,5 @@
     "forceConsistentCasingInFileNames": true,
     "verbatimModuleSyntax": true
   },
-  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "test/**/*.ts"]
 }

package/docks-kit

@@ -2,7 +2,7 @@
 # docks-kit — launcher. Resolution order:
 #   1. compiled binary in cli/dist/ (bun build --compile output)
 #   2. Bun from source (auto-installs Bun + node_modules when missing)
-# Zero-dependency escape hatch (no Bun at all): bash lib/engine.sh <args>
+# No-Bun recovery path: download a release binary for your platform.
 set -euo pipefail
 
 REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -12,6 +12,9 @@ case "$(uname -s)-$(uname -m)" in
   Linux-aarch64)  KIT_BIN="docks-kit-linux-arm64" ;;
   Darwin-x86_64)  KIT_BIN="docks-kit-darwin-x64" ;;
   Darwin-arm64)   KIT_BIN="docks-kit-darwin-arm64" ;;
+  # Git Bash unames look like MINGW64_NT-10.0-19045-x86_64. The compiled
+  # binary is the supported Windows path; the Bun fallback below is Unix-shaped.
+  MINGW*-x86_64|MSYS*-x86_64|CYGWIN*-x86_64) KIT_BIN="docks-kit-windows-x64.exe" ;;
   *)              KIT_BIN="" ;;
 esac
 if [[ -n "$KIT_BIN" && -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
@@ -33,7 +36,7 @@ find_bun() {
 if ! BUN="$(find_bun)"; then
   echo "[docks-kit] Bun not found — installing (download-then-run)..." >&2
   if ! command -v curl >/dev/null 2>&1; then
-    echo "[docks-kit] curl missing too. Install Bun manually (https://bun.sh) or use the escape hatch: bash $REPO_DIR/lib/engine.sh" >&2
+    echo "[docks-kit] curl missing too. Install Bun manually (https://bun.sh) or download a docks-kit release binary." >&2
     exit 1
   fi
   # Pin the Bun release to the kit-verified version when jq can read it
@@ -46,7 +49,7 @@ if ! BUN="$(find_bun)"; then
   curl -fsSL https://bun.sh/install -o "$tmp_installer" && bash "$tmp_installer" ${BUN_PIN:+"bun-v$BUN_PIN"} >/dev/null 2>&1 || true
   rm -f "$tmp_installer"
   if ! BUN="$(find_bun)"; then
-    echo "[docks-kit] Bun install failed. Escape hatch: bash $REPO_DIR/lib/engine.sh <args>" >&2
+    echo "[docks-kit] Bun install failed. Download a docks-kit release binary for a no-Bun recovery path." >&2
     exit 1
   fi
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,6 @@
     "cli/src",
     "cli/docs",
     "cli/tsconfig.json",
-    "lib",
     "SoT",
     "notification.mp3",
     "docks-kit",
@@ -24,7 +23,10 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit -p cli",
-    "build:binaries": "bash cli/build-binaries.sh"
+    "build:binaries": "bash cli/build-binaries.sh",
+    "golden:dryrun": "bun cli/test/golden-dryrun.ts",
+    "golden:mutation": "bun cli/test/golden-mutation.ts",
+    "test:unit": "vitest run"
   },
   "dependencies": {
     "@effect/cli": "0.75.2",
@@ -33,7 +35,9 @@
     "effect": "3.21.4"
   },
   "devDependencies": {
+    "@effect/vitest": "0.29.0",
     "@types/bun": "^1.3.0",
-    "typescript": "^5.7.2"
+    "typescript": "7.0.2",
+    "vitest": "3.2.7"
   }
 }