docks-kit 0.14.3 → 0.14.4

package/cli/src/engine-native/services.ts

@@ -26,10 +26,10 @@ export type { Logger } from "./logger"
 export interface DependencyManager {
   readonly spec: (id: ToolId) => DependencySpec
   readonly probe: (id: ToolId) => ProbeResult
-  readonly version: (id: ToolId) => string
-  readonly path: (id: ToolId) => string
-  readonly location: (id: ToolId) => DependencyLocation
-  readonly latest: (id: ToolId) => string
+  readonly version: (id: ToolId) => Promise<string>
+  readonly path: (id: ToolId) => Promise<string>
+  readonly location: (id: ToolId) => Promise<DependencyLocation>
+  readonly latest: (id: ToolId) => Promise<string>
   readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void
 }
 
@@ -73,7 +73,7 @@ export const makeDependencyManager = (
     version: (id) => resolveVersion(DEPENDENCIES[id], exec),
     path: (id) => resolvePath(DEPENDENCIES[id], exec, platform.raw()),
     location: (id) => resolveLocation(DEPENDENCIES[id], exec, platform.raw()),
-    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? "",
+    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? Promise.resolve(""),
     warnMissing: (id, logger, context) => {
       if (warned.has(id)) return
       warned.add(id)

package/cli/src/engine-native/skillsSync.ts

@@ -4,9 +4,8 @@
  * the kit-managed snapshot, the effect-solutions toolchain callback, and the
  * snapshot write.
  */
-import { spawnSync } from "node:child_process"
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
-import { p, writeFileIfChanged } from "./exec"
+import { p, spawnProcess, writeFileIfChanged } from "./exec"
 import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
@@ -18,7 +17,7 @@ export interface SkillsState {
   present: number
 }
 
-export function skillsSync(ctx: Ctx): SkillsState {
+export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
   const state: SkillsState = { present: 0 }
   const skillsDir = p(ctx.agentsDir, "skills")
   const manifest = payloadText("SoT/.agents/skills.txt")
@@ -26,9 +25,9 @@ export function skillsSync(ctx: Ctx): SkillsState {
 
   if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true })
 
-  syncUniversal(ctx, state, skillsDir, manifest)
-  if (ctx.prune) reconcileRemovals(ctx, manifest, snapshot)
-  syncEffectSolutionsCli(ctx)
+  await syncUniversal(ctx, state, skillsDir, manifest)
+  if (ctx.prune) await reconcileRemovals(ctx, manifest, snapshot)
+  await syncEffectSolutionsCli(ctx)
   updateSnapshot(ctx, manifest, snapshot)
   return state
 }
@@ -55,7 +54,7 @@ function readSlugs(file: string): Array<string> {
   return existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : []
 }
 
-function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): void {
+async function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
   if (ctx.services.deps.probe("npx").state === "missing") {
     ctx.services.deps.warnMissing("npx", ctx.services.logger, "skipping universal skills bootstrap")
@@ -87,11 +86,11 @@ function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest
     }
 
     progress(`Installing universal skill ${slug}...`)
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"], {
       stdio: "ignore"
     })
     clearProgress()
-    if (res.error === undefined && res.status === 0) {
+    if (res.error === undefined && res.exitCode === 0) {
       added++
     } else {
       warn(`Failed to install universal skill: ${slug}`)
@@ -221,26 +220,26 @@ function linkOrCopyWithWarnings(target: string, link: string, services: EngineSe
 /** skills::_effect_solutions_install. */
 export function effectSolutionsInstall(
   ctx: Ctx
-): (mode: "install" | "upgrade", version: string, services: EngineServices) => number {
-  return (mode, version, services) => {
+): (mode: "install" | "upgrade", version: string, services: EngineServices) => Promise<number> {
+  return async (mode, version, services) => {
     const { change, clearProgress, progress, verbose, warn } = services.logger
     const verb = mode === "upgrade" ? "Upgrading" : "Installing"
     const pkg = `effect-solutions@${version !== "" ? version : "latest"}`
 
-    const bunState = bunBootstrap(ctx, services)
+    const bunState = await bunBootstrap(ctx, services)
     if (bunState.kind === "deferred") return 1
     const bun = bunState.executable
 
     verbose(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
     progress(`${verb} effect-solutions CLI...`)
-    const installResult = spawnSync(bun, ["add", "-g", pkg], { stdio: "ignore" })
+    const installResult = await spawnProcess(bun, ["add", "-g", pkg], { stdio: "ignore" })
     clearProgress()
-    if (installResult.status !== 0) {
+    if (installResult.exitCode !== 0) {
       warn(`bun add -g ${pkg} failed. Try manually: bun add -g ${pkg}`)
       return 1
     }
 
-    const location = services.deps.location("effect-solutions")
+    const location = await services.deps.location("effect-solutions")
     const gbin = location.binDir
     if (location.path !== "") {
       mkdirSync(p(ctx.home, ".local", "bin"), { recursive: true })
@@ -254,12 +253,12 @@ export function effectSolutionsInstall(
   }
 }
 
-function syncEffectSolutionsCli(ctx: Ctx): void {
+async function syncEffectSolutionsCli(ctx: Ctx): Promise<void> {
   const { clearProgress, progress, warn } = ctx.services.logger
   if (!/"effect-kit@docks"[ \t]*:[ \t]*true/.test(payloadText("SoT/.claude/settings.json"))) return
 
   progress("Checking effect-solutions CLI...")
-  const result = ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+  const result = await ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
   clearProgress()
   if (result !== 0) {
     warn("effect-solutions bootstrap failed — continuing sync")
@@ -268,7 +267,7 @@ function syncEffectSolutionsCli(ctx: Ctx): void {
 
 // ----------------------------------------------------- prune + snapshot ----
 
-function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
+async function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Promise<void> {
   const { change, clearProgress, echo, progress, warn } = ctx.services.logger
   if (!existsSync(snapshot)) {
     if (ctx.dryRun) {
@@ -290,11 +289,11 @@ function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
       continue
     }
     progress(`Removing universal skill ${base}...`)
-    const res = spawnSync("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
+    const res = await spawnProcess("npx", ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"], {
       stdio: "ignore"
     })
     clearProgress()
-    if (res.error === undefined && res.status === 0) {
+    if (res.error === undefined && res.exitCode === 0) {
       removed++
     } else {
       warn(`Failed to remove kit-managed skill: ${base}`)

package/cli/src/engine-native/toolchain.ts

@@ -10,7 +10,11 @@ import { compareCodepoints, isObject, parseJson, type Json } from "./jq"
 import type { EngineServices } from "./services"
 import { payloadText } from "../payload"
 
-type InstallFn = (mode: "install" | "upgrade", version: string, services: EngineServices) => number
+type InstallFn = (
+  mode: "install" | "upgrade",
+  version: string,
+  services: EngineServices
+) => number | Promise<number>
 
 function manifest(): { [k: string]: Json } {
   const doc = parseJson(payloadText("SoT/toolchain.json"))
@@ -47,40 +51,40 @@ function firstLineField(out: string, index: number): string {
   return fields[index === -1 ? fields.length - 1 : index] ?? ""
 }
 
-export function installedVersion(ctx: Ctx, tool: ToolId): string {
-  const version = (): string => ctx.services.deps.version(tool)
+export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string> {
+  const version = () => ctx.services.deps.version(tool)
   switch (tool) {
     case "claude":
-      return firstLineField(version(), 0)
+      return firstLineField(await version(), 0)
     case "codex":
-      return firstLineField(version(), -1)
+      return firstLineField(await version(), -1)
     case "git":
-      return firstLineField(version(), 2)
+      return firstLineField(await version(), 2)
     case "node":
-      return version().replace(/^v/, "")
+      return (await version()).replace(/^v/, "")
     case "jq":
-      return version().replace(/^jq-/, "")
+      return (await version()).replace(/^jq-/, "")
     case "curl":
     case "tsc":
-      return firstLineField(version(), 1)
+      return firstLineField(await version(), 1)
     case "bun":
     case "effect-solutions":
     case "npm":
-      return version()
+      return await version()
     case "bwrap":
-      return firstLineField(version(), 1)
+      return firstLineField(await version(), 1)
     case "ffplay":
-      return firstLineField(version(), 2).replace(/-.*$/, "")
+      return firstLineField(await version(), 2).replace(/-.*$/, "")
     case "intelephense":
     case "typescript-language-server":
-      return version().trim()
+      return (await version()).trim()
     default:
       return ""
   }
 }
 
-export function latestVersion(ctx: Ctx, tool: ToolId): string {
-  return ctx.services.deps.latest(tool)
+export async function latestVersion(ctx: Ctx, tool: ToolId): Promise<string> {
+  return await ctx.services.deps.latest(tool)
 }
 
 /** Blocking TTY prompt matching bash `read -r -p` (prompt on stderr). */
@@ -108,7 +112,12 @@ export function promptLine(
 }
 
 /** toolchain::_gate — { proceed, target } ("" target = latest). */
-function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: string): { proceed: boolean; target: string } {
+async function gate(
+  ctx: Ctx,
+  tool: string,
+  mode: "install" | "upgrade",
+  latest: string
+): Promise<{ proceed: boolean; target: string }> {
   const { warn } = ctx.services.logger
   const verified = field(ctx, tool, "verified")
   const pinnable = field(ctx, tool, "pinnable")
@@ -122,7 +131,11 @@ function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: strin
 
   if (process.stdin.isTTY === true) {
     ctx.services.logger.warn(`${tool} ${latest} is not kit-verified (verified: ${verified}).`)
-    const answer = promptLine(`Install ${tool} ${latest} anyway? [y/N] `)
+    const question = `Install ${tool} ${latest} anyway? [y/N] `
+    const answer =
+      ctx.terminalLease === undefined
+        ? promptLine(question)
+        : await ctx.terminalLease.withExclusive(() => promptLine(question))
     if (/^[yY]/.test(answer)) return { proceed: true, target: "" }
   }
 
@@ -136,12 +149,12 @@ function gate(ctx: Ctx, tool: string, mode: "install" | "upgrade", latest: strin
   return { proceed: false, target: "" }
 }
 
-export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
+export async function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): Promise<number> {
   const { echo, verbose, warn } = ctx.services.logger
   const policy = field(ctx, tool, "policy")
 
   if (!present(ctx, tool)) {
-    const latest = latestVersion(ctx, tool)
+    const latest = await latestVersion(ctx, tool)
     if (ctx.dryRun) {
       echo(`[dry-run] would install ${tool} (${latest !== "" ? latest : "latest"}, gated by toolchain.json verified pin)`)
       return 0
@@ -156,14 +169,14 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
         warn(`${tool} latest version unknown (offline?) and not pinnable — installing latest unverified`)
       }
     } else {
-      const g = gate(ctx, tool, "install", latest)
+      const g = await gate(ctx, tool, "install", latest)
       if (!g.proceed) return 0
       target = g.target
     }
-    return installFn("install", target !== "" ? target : latest, ctx.services)
+    return await installFn("install", target !== "" ? target : latest, ctx.services)
   }
 
-  const installed = installedVersion(ctx, tool)
+  const installed = await installedVersion(ctx, tool)
   const installedLabel = installed !== "" ? installed : "version unknown"
 
   if (policy !== "track") {
@@ -175,7 +188,7 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
     return 0
   }
 
-  const latest = latestVersion(ctx, tool)
+  const latest = await latestVersion(ctx, tool)
   if (latest === "") {
     if (ctx.dryRun) {
       echo(`[dry-run] ${tool} present (${installedLabel}); latest unknown (offline?) — no action`)
@@ -190,9 +203,9 @@ export function ensure(ctx: Ctx, tool: ToolId, installFn: InstallFn): number {
       echo(`[dry-run] would upgrade ${tool} (${installed !== "" ? installed : "unknown"} -> ${latest}, gated by toolchain.json verified pin)`)
       return 0
     }
-    const g = gate(ctx, tool, "upgrade", latest)
+    const g = await gate(ctx, tool, "upgrade", latest)
     if (!g.proceed) return 0
-    return installFn("upgrade", g.target !== "" ? g.target : latest, ctx.services)
+    return await installFn("upgrade", g.target !== "" ? g.target : latest, ctx.services)
   }
 
   if (ctx.dryRun) {
@@ -208,7 +221,7 @@ function row(cells: [string, string, string, string, string, string]): string {
   return cells.map((c, i) => (i < widths.length ? c.padEnd(widths[i]!) : c)).join(" ")
 }
 
-export function report(ctx: Ctx): void {
+export async function report(ctx: Ctx): Promise<void> {
   const { echo } = ctx.services.logger
   echo(row(["TOOL", "KIND", "INSTALLED", "FLOOR", "VERIFIED", "STATUS"]))
   const pn = ctx.services.platform.name()
@@ -228,7 +241,7 @@ export function report(ctx: Ctx): void {
     let status: string
     const toolId = tool as ToolId
     if (present(ctx, toolId)) {
-      installed = installedVersion(ctx, toolId)
+      installed = await installedVersion(ctx, toolId)
       status = "ok"
       if (floor !== "" && installed !== "" && isNewer(floor, installed)) {
         status = "below-floor"

package/cli/src/engine.ts

@@ -37,7 +37,7 @@ export const engine = (args: ReadonlyArray<string>) =>
     const logger = yield* LoggerService
     const deps = yield* DependencyManagerService
     const platform = yield* PlatformService
-    const code = yield* Effect.sync(() => runEngineNative(args, { logger, deps, platform }))
+    const code = yield* Effect.promise(() => runEngineNative(args, { logger, deps, platform }))
     if (code !== 0) {
       yield* Effect.sync(() => process.exit(code))
     }

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.14.3"
+export const GENERATED_PACKAGE_VERSION = "0.14.4"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/cli/src/main.ts

@@ -57,7 +57,7 @@ const root = Command.make("docks-kit", {}, () =>
 // 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)))
+  process.exit(await runEngineNative(process.argv.slice(2)))
 }
 
 const cli = Command.run(root, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",