docks-kit 0.3.0 → 0.5.0

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

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process"
+import { rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+
+import { p } from "./exec"
+import type { Ctx } from "./index"
+import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
+import type { EngineServices } from "./services"
+import { field } from "./toolchain"
+
+export type BunRuntimeState =
+  | { readonly kind: "ready"; readonly executable: string }
+  | { readonly kind: "deferred"; readonly reason: "missing-curl" | "install-failed" }
+
+function remember(ctx: Ctx, state: BunRuntimeState): BunRuntimeState {
+  ctx.bunRuntime = state
+  return state
+}
+
+function predictedExecutable(ctx: Ctx, services: EngineServices): string {
+  const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
+    ? process.env["BUN_INSTALL"]!
+    : p(ctx.home, ".bun")
+  return p(root, "bin", services.platform.isWindows() ? "bun.exe" : "bun")
+}
+
+function windowsDownloadScript(installer: string): string {
+  return `$ErrorActionPreference = 'Stop'; Invoke-WebRequest -Uri ${powerShellLiteral("https://bun.sh/install.ps1")} -OutFile ${powerShellLiteral(installer)}`
+}
+
+function installBun(ctx: Ctx, services: EngineServices, pin: string, installer: string): void {
+  if (services.platform.isWindows()) {
+    const encoded = encodePowerShellCommand(windowsDownloadScript(installer))
+    const download = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], { stdio: "ignore" })
+    if (download.error === undefined && download.status === 0) {
+      spawnSync(
+        "powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", installer, "-Version", pin, "-DownloadWithoutCurl"],
+        { stdio: "ignore" }
+      )
+    }
+    return
+  }
+
+  const download = spawnSync("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
+  if (download.error === undefined && download.status === 0) {
+    spawnSync("bash", [installer, `bun-v${pin}`], { stdio: "ignore" })
+  }
+}
+
+export function bunBootstrap(ctx: Ctx, services: EngineServices): BunRuntimeState {
+  if (ctx.bunRuntime !== undefined) return ctx.bunRuntime
+
+  const existing = services.deps.path("bun")
+  if (existing !== "") return remember(ctx, { kind: "ready", executable: existing })
+
+  const pin = field(ctx, "bun", "verified")
+  if (pin === "") {
+    services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin")
+    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+  }
+  if (!services.platform.isWindows() && services.deps.probe("curl").state === "missing") {
+    services.deps.warnMissing("curl", services.logger, "cannot bootstrap Bun; install Bun manually, then re-run sync")
+    return remember(ctx, { kind: "deferred", reason: "missing-curl" })
+  }
+  if (ctx.dryRun) {
+    const executable = predictedExecutable(ctx, services)
+    services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
+    return remember(ctx, { kind: "ready", executable })
+  }
+  services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
+  const installer = p(tmpdir(), `bun-install-${process.pid}.${services.platform.isWindows() ? "ps1" : "sh"}`)
+  try {
+    installBun(ctx, services, pin, installer)
+  } finally {
+    rmSync(installer, { force: true })
+  }
+
+  const installed = services.deps.path("bun")
+  if (installed === "") {
+    services.logger.warn("Bun install failed. Install manually from https://bun.sh/docs/installation, then re-run sync.")
+    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+  }
+  const version = services.deps.version("bun")
+  services.logger.change(`Bun installed (${version !== "" ? version : "version unknown"})`)
+  return remember(ctx, { kind: "ready", executable: installed })
+}

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

@@ -0,0 +1,132 @@
+import { p } from "./exec"
+import { isObject, parseJson, type Json } from "./jq"
+import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
+import type { Platform } from "./services"
+
+const BUN_SENTINEL = "__DOCKS_KIT_BUN__"
+const SESSION_START_SENTINEL = "__DOCKS_KIT_SESSION_START__"
+const NOTIFY_SENTINEL = "__DOCKS_KIT_NOTIFY__"
+const STATUSLINE_SENTINEL = "__DOCKS_KIT_STATUSLINE__"
+
+export interface ClaudeRuntimePaths {
+  readonly bun: string
+  readonly statusline: string
+  readonly sessionStart: string
+  readonly notify: string
+}
+
+export function claudeRuntimePaths(claudeDir: string, bun: string): ClaudeRuntimePaths {
+  return {
+    bun,
+    statusline: p(claudeDir, "bin", "statusline.mjs"),
+    sessionStart: p(claudeDir, "bin", "session-start.mjs"),
+    notify: p(claudeDir, "bin", "notify.mjs")
+  }
+}
+
+function cloneJson(value: Json): Json {
+  const cloned = parseJson(JSON.stringify(value))
+  if (cloned === undefined) throw new Error("Claude settings template cannot be serialized")
+  return cloned
+}
+
+function countString(value: Json, expected: string): number {
+  if (value === expected) return 1
+  if (Array.isArray(value)) return value.reduce<number>((total, item) => total + countString(item, expected), 0)
+  if (!isObject(value)) return 0
+  return Object.values(value).reduce<number>((total, item) => total + countString(item, expected), 0)
+}
+
+function hooksObject(template: Json): { [key: string]: Json } {
+  if (!isObject(template) || !isObject(template["hooks"])) throw new Error("Claude settings hooks object is missing")
+  return template["hooks"]
+}
+
+function commandHandler(template: Json, event: "SessionStart" | "Notification"): { [key: string]: Json } {
+  const entries = hooksObject(template)[event]
+  if (!Array.isArray(entries) || entries.length !== 1 || !isObject(entries[0])) {
+    throw new Error(`${event} sentinel location is invalid`)
+  }
+  const handlers = entries[0]["hooks"]
+  if (!Array.isArray(handlers) || handlers.length !== 1 || !isObject(handlers[0])) {
+    throw new Error(`${event} sentinel handler is invalid`)
+  }
+  return handlers[0]
+}
+
+function oneArg(handler: { [key: string]: Json }, sentinel: string, event: string): void {
+  const args = handler["args"]
+  if (!Array.isArray(args) || args.length !== 1 || args[0] !== sentinel) {
+    throw new Error(`${event} argument sentinel location is invalid`)
+  }
+}
+
+function validateTemplate(template: Json): void {
+  const sessionStart = commandHandler(template, "SessionStart")
+  const notification = commandHandler(template, "Notification")
+  if (sessionStart["command"] !== BUN_SENTINEL) throw new Error("SessionStart Bun sentinel location is invalid")
+  if (notification["command"] !== BUN_SENTINEL) throw new Error("Notification Bun sentinel location is invalid")
+  oneArg(sessionStart, SESSION_START_SENTINEL, "SessionStart")
+  oneArg(notification, NOTIFY_SENTINEL, "Notification")
+
+  const hooks = hooksObject(template)
+  if (hooks["Stop"] !== undefined) throw new Error("hooks.Stop must be absent from the Claude settings template")
+  if (!isObject(template) || !isObject(template["statusLine"]) || template["statusLine"]["command"] !== STATUSLINE_SENTINEL) {
+    throw new Error("Statusline sentinel location is invalid")
+  }
+  const counts: ReadonlyArray<[string, string, number]> = [
+    ["Bun", BUN_SENTINEL, 2],
+    ["SessionStart", SESSION_START_SENTINEL, 1],
+    ["notify", NOTIFY_SENTINEL, 1],
+    ["statusline", STATUSLINE_SENTINEL, 1]
+  ]
+  for (const [label, sentinel, expected] of counts) {
+    if (countString(template, sentinel) !== expected) throw new Error(`${label} sentinel residue/cardinality is invalid`)
+  }
+}
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export function statusLineCommand(runtime: ClaudeRuntimePaths, platform: Platform): string {
+  if (!platform.isWindows()) {
+    const bun = posixLiteral(runtime.bun)
+    const script = posixLiteral(runtime.statusline)
+    return `test -x ${bun} && test -f ${script} && exec ${bun} ${script} || true`
+  }
+  const bun = powerShellLiteral(runtime.bun.replaceAll("\\", "/"))
+  const script = powerShellLiteral(runtime.statusline.replaceAll("\\", "/"))
+  const guard = `$ProgressPreference = 'SilentlyContinue'; if ((Test-Path -LiteralPath ${bun} -PathType Leaf) -and (Test-Path -LiteralPath ${script} -PathType Leaf)) { & ${bun} ${script} }`
+  return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${encodePowerShellCommand(guard)}`
+}
+
+export function materializeClaudeSettings(
+  template: Json,
+  runtime: ClaudeRuntimePaths | undefined,
+  platform: Platform
+): Json {
+  validateTemplate(template)
+  const result = cloneJson(template)
+  const hooks = hooksObject(result)
+  if (runtime === undefined) {
+    delete hooks["SessionStart"]
+    delete hooks["Notification"]
+    if (!isObject(result)) throw new Error("Claude settings template must be an object")
+    delete result["statusLine"]
+  } else {
+    const sessionStart = commandHandler(result, "SessionStart")
+    sessionStart["command"] = runtime.bun
+    sessionStart["args"] = [runtime.sessionStart]
+    const notification = commandHandler(result, "Notification")
+    notification["command"] = runtime.bun
+    notification["args"] = [runtime.notify]
+    if (!isObject(result) || !isObject(result["statusLine"])) throw new Error("Claude statusLine object is missing")
+    result["statusLine"]["command"] = statusLineCommand(runtime, platform)
+  }
+
+  for (const sentinel of [BUN_SENTINEL, SESSION_START_SENTINEL, NOTIFY_SENTINEL, STATUSLINE_SENTINEL]) {
+    if (countString(result, sentinel) !== 0) throw new Error(`Claude settings sentinel residue: ${sentinel}`)
+  }
+  return result
+}

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

@@ -0,0 +1,101 @@
+/** Atomic top-level Claude settings modifiers, including direct model mode. */
+import { p } from "./exec"
+import { readFileSync, renameSync, writeFileSync } from "node:fs"
+
+import { resolveEffort } from "../efforts"
+import type { Ctx } from "./index"
+import { isObject, jqStringify, parseJson } from "./jq"
+
+interface ClaudeSettingEdit {
+  readonly tag: string
+  readonly key: "model" | "effortLevel" | "advisorModel"
+  readonly value: string | undefined
+  readonly dryRun: string
+  readonly changed: string
+  readonly unchanged: string
+}
+
+function syncClaudeSetting(ctx: Ctx, edit: ClaudeSettingEdit): void {
+  const { change, echo, err, verbose, warn } = ctx.services.logger
+  const userSettings = p(ctx.home, ".claude", "settings.json")
+
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
+    return
+  }
+
+  let text: string
+  try {
+    text = readFileSync(userSettings, "utf8")
+  } catch {
+    warn(`(${edit.tag}) ${userSettings} missing — skipped`)
+    return
+  }
+  const doc = parseJson(text)
+  if (doc === undefined) {
+    err(`(${edit.tag}) ${userSettings} is not valid JSON — skipped`)
+    return
+  }
+  if (isObject(doc)) {
+    if (edit.value === undefined) delete doc[edit.key]
+    else doc[edit.key] = edit.value
+  }
+  const out = jqStringify(doc)
+  if (out === text) {
+    verbose(edit.unchanged)
+    return
+  }
+  writeFileSync(`${userSettings}.tmp`, out)
+  renameSync(`${userSettings}.tmp`, userSettings)
+  change(edit.changed)
+  ctx.nextStepTriggers.claudeRestart = true
+}
+
+export function syncClaudeModel(ctx: Ctx, model: string): void {
+  if (model === "") return
+  const unset = model === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-model",
+    key: "model",
+    value: unset ? undefined : model,
+    dryRun: unset ? "delete .model (account default applies)" : `set .model=${model}`,
+    changed: `Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Model: deployed settings model already ${unset ? "unset (account default)" : model}`
+  })
+}
+
+export function syncClaudeEffort(ctx: Ctx, effort: string): void {
+  if (effort === "") return
+  const resolved = resolveEffort("claude", effort)
+  const useDefault = effort === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-effort",
+    key: "effortLevel",
+    value: resolved,
+    dryRun: `set .effortLevel=${resolved}`,
+    changed: useDefault
+      ? `Effort: deployed settings effortLevel set to ${resolved} (SoT default)`
+      : `Effort: deployed settings effortLevel set to ${resolved} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Effort: deployed settings effortLevel already ${resolved}`
+  })
+}
+
+export function syncClaudeAdvisor(ctx: Ctx, state: string): void {
+  if (state === "") return
+  const enabled = state === "on"
+  const useDefault = state === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-advisor",
+    key: "advisorModel",
+    value: enabled ? "fable" : undefined,
+    dryRun: enabled ? "set .advisorModel=fable" : "delete .advisorModel (advisor disabled)",
+    changed: enabled
+      ? "Advisor: deployed settings advisorModel set to fable (SoT unchanged; flag-less sync reverts)"
+      : useDefault
+        ? "Advisor: deployed settings advisorModel unset (SoT default: off)"
+        : "Advisor: deployed settings advisorModel unset (--claude-advisor=off; SoT unchanged)",
+    unchanged: enabled
+      ? "Advisor: deployed settings advisorModel already fable"
+      : `Advisor: deployed settings advisorModel already unset (${useDefault ? "SoT default: off" : "advisor off"})`
+  })
+}