docks-kit 0.15.1 → 0.15.3

package/cli/src/engine-native/os/windows.ts

@@ -0,0 +1,176 @@
+import { win32 } from "node:path"
+import { p } from "../exec"
+import type { HostOs } from "./types"
+
+function powershellLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`
+}
+
+function encodedPowerShellCommand(script: string): string {
+  const encoded = Buffer.from(script, "utf16le").toString("base64")
+  return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${encoded}`
+}
+
+/**
+ * Windows shim encoding handles three hazards: Windows argv parsing, cmd
+ * metacharacter parsing, and percent/newline values that cmd cannot escape.
+ * The encoders are ported from cross-spawn's escape.js and its parseNonShell
+ * assembly, based on:
+ * https://github.com/moxystudio/node-cross-spawn
+ * https://qntm.org/cmd
+ * https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
+ * https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd
+ */
+const metaCharsRegExp = /([()\][%!^"`<>&|;, *?])/g
+
+function escapeCommand(arg: string): string {
+  return arg.replace(metaCharsRegExp, "^$1")
+}
+
+function escapeArgument(arg: string, doubleEscapeMetaChars: boolean): string {
+  arg = `${arg}`
+  arg = arg.replace(/(?=(\\+?)?)\1"/g, "$1$1\\\"")
+  arg = arg.replace(/(?=(\\+?)?)\1$/, "$1$1")
+  arg = `"${arg}"`
+  arg = arg.replace(metaCharsRegExp, "^$1")
+  if (doubleEscapeMetaChars) {
+    arg = arg.replace(metaCharsRegExp, "^$1")
+  }
+  return arg
+}
+
+function assertCommandLineValue(value: string, kind: "executable path" | "argument"): void {
+  const unsupported = value.includes("%")
+    ? "percent sign (%)"
+    : value.includes("\r")
+      ? "carriage return (CR)"
+      : value.includes("\n")
+        ? "line feed (LF)"
+        : undefined
+  if (unsupported === undefined) return
+
+  const executablePercentHint =
+    kind === "executable path" && unsupported === "percent sign (%)"
+      ? " The tool must be reached through its .exe or moved out of a directory whose name contains a percent sign."
+      : ""
+  throw new Error(
+    `${kind} ${JSON.stringify(value)} contains a ${unsupported}, which cannot be escaped on a cmd command line; the caller must pass the value another way.${executablePercentHint}`
+  )
+}
+
+/**
+ * Always absolute. A pathless name lets CreateProcess and libuv search the
+ * parent's current directory before System32, so an untrusted checkout holding
+ * a cmd.exe would win. ComSpec is the documented interpreter, honoured only
+ * when it is an absolute path; otherwise it is rebuilt under SystemRoot.
+ */
+function commandInterpreter(environment: NodeJS.ProcessEnv = process.env): string {
+  const comSpec = environment["ComSpec"] ?? ""
+  if (win32.isAbsolute(comSpec)) return comSpec
+  const systemRoot = environment["SystemRoot"] ?? ""
+  const root = win32.isAbsolute(systemRoot) ? systemRoot : "C:\\Windows"
+  return win32.join(root, "System32", "cmd.exe")
+}
+
+function commandShimInvocation(executablePath: string, args: ReadonlyArray<string>) {
+  assertCommandLineValue(executablePath, "executable path")
+  for (const arg of args) assertCommandLineValue(arg, "argument")
+
+  const normalizedPath = win32.normalize(executablePath)
+  const doubleEscapeMetaChars = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(normalizedPath)
+  const commandLine = [
+    escapeCommand(normalizedPath),
+    ...args.map((arg) => escapeArgument(arg, doubleEscapeMetaChars))
+  ].join(" ")
+  return {
+    command: commandInterpreter(),
+    args: ["/d", "/v:off", "/s", "/c", `"${commandLine}"`],
+    windowsVerbatimArguments: true
+  } as const
+}
+
+// Authored now, but unreachable until the supported-host admission gate opens.
+export const windows: HostOs = {
+  id: "windows",
+  toolchainOs: "windows",
+  supportsBubblewrap: false,
+  directoryLinkKinds: ["symlink", "junction"],
+  executableSuffixes: [".exe", ".cmd", ".bat", ""],
+  invoke: (executablePath, args) =>
+    /\.(?:cmd|bat)$/i.test(executablePath)
+      ? commandShimInvocation(executablePath, args)
+      : { command: executablePath, args },
+  bunExecutableName: "bun.exe",
+  bunInstaller: (pin, directory) => {
+    const scriptPath = p(directory, "install.ps1")
+    return {
+      scriptPath,
+      download: {
+        command: "curl",
+        args: ["-fsSL", "https://bun.sh/install.ps1", "-o", scriptPath]
+      },
+      run: {
+        command: "powershell.exe",
+        args: [
+          "-NoProfile",
+          "-NonInteractive",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-File",
+          scriptPath,
+          "-Version",
+          pin
+        ]
+      }
+    }
+  },
+  environmentSetting: (name, value) => ({
+    kind: "command",
+    probe: {
+      command: "reg",
+      args: ["query", "HKCU\\Environment", "/v", name]
+    },
+    apply: {
+      command: "setx",
+      args: [name, value]
+    },
+    location: "user environment",
+    manualHint: "set it manually in System Properties > Environment Variables"
+  }),
+  statusLineCommand: (bun, script) => {
+    const bunLiteral = powershellLiteral(bun)
+    const scriptLiteral = powershellLiteral(script)
+    // Module auto-loading reports "Preparing modules for first use" as a
+    // progress record, which a redirected host serializes to stderr as CLIXML.
+    // Claude runs this command every turn, and the records recur across runs, so
+    // silencing progress inside the stored command keeps its streams clean.
+    return encodedPowerShellCommand(
+      `$ProgressPreference = 'SilentlyContinue'; if ((Test-Path -LiteralPath ${bunLiteral} -PathType Leaf) -and (Test-Path -LiteralPath ${scriptLiteral} -PathType Leaf)) { & ${bunLiteral} ${scriptLiteral} }`
+    )
+  },
+  failureHookCommand: (command) => {
+    const prefix = "echo '"
+    if (!command.startsWith(prefix) || !command.endsWith("'")) return command
+    const quotedPayload = command.slice(prefix.length, -1)
+    const posixApostrophe = `'"'"'`
+    if (quotedPayload.replaceAll(posixApostrophe, "").includes("'")) return command
+    const payload = quotedPayload.replaceAll(posixApostrophe, "'")
+    return encodedPowerShellCommand(`Write-Output ${powershellLiteral(payload)}`)
+  },
+  installHint: (tool) => {
+    switch (tool) {
+      case "git":
+        return "winget install --id Git.Git -e"
+      case "jq":
+        return "winget install --id jqlang.jq -e"
+      case "curl":
+        return "winget install --id cURL.cURL -e"
+      case "ffplay":
+        return "winget install --id Gyan.FFmpeg -e"
+      case "claude":
+        return "$tmp = Join-Path $env:TEMP 'claude-install.ps1'; curl.exe -fsSL https://claude.ai/install.ps1 -o $tmp; if ($LASTEXITCODE -eq 0) { powershell.exe -NoProfile -ExecutionPolicy Bypass -File $tmp }"
+      case "codex":
+        return "$tmp = Join-Path $env:TEMP 'codex-install.ps1'; curl.exe -fsSL https://chatgpt.com/codex/install.ps1 -o $tmp; if ($LASTEXITCODE -eq 0) { $env:CODEX_NON_INTERACTIVE = '1'; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $tmp }"
+    }
+  }
+}

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

@@ -24,13 +24,96 @@ export class ExitError extends Error {
 }
 
 export const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
-const MODIFIER_FLAGS = new Set<ModifierFlag>([
-  "--claude-model",
-  "--claude-effort",
-  "--claude-advisor",
-  "--codex-model",
-  "--codex-effort"
-])
+
+interface ModifierMetadata {
+  readonly target: "claude" | "codex"
+  readonly ignoredWarning: string
+  readonly hasValue: (ctx: Ctx) => boolean
+  readonly clear: (ctx: Ctx) => void
+}
+
+const MODIFIER_METADATA = {
+  "--claude-model": {
+    target: "claude",
+    ignoredWarning: "--claude-model ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeModel !== "",
+    clear: (ctx) => {
+      ctx.claudeModel = ""
+    }
+  },
+  "--claude-effort": {
+    target: "claude",
+    ignoredWarning: "--claude-effort ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeEffort !== "",
+    clear: (ctx) => {
+      ctx.claudeEffort = ""
+    }
+  },
+  "--claude-advisor": {
+    target: "claude",
+    ignoredWarning: "--claude-advisor ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeAdvisor !== "",
+    clear: (ctx) => {
+      ctx.claudeAdvisor = ""
+    }
+  },
+  "--claude-compact-window": {
+    target: "claude",
+    ignoredWarning: "--claude-compact-window ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeCompactWindow !== "",
+    clear: (ctx) => {
+      ctx.claudeCompactWindow = ""
+    }
+  },
+  "--claude-permissive": {
+    target: "claude",
+    ignoredWarning: "--claude-permissive ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePermissive,
+    clear: (ctx) => {
+      ctx.claudePermissive = false
+    }
+  },
+  "--claude-plugin": {
+    target: "claude",
+    ignoredWarning: "--claude-plugin ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePlugins.length > 0,
+    clear: (ctx) => {
+      ctx.claudePlugins = []
+    }
+  },
+  "--codex-model": {
+    target: "codex",
+    ignoredWarning: "--codex-model ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexModel !== "",
+    clear: (ctx) => {
+      ctx.codexModel = ""
+    }
+  },
+  "--codex-effort": {
+    target: "codex",
+    ignoredWarning: "--codex-effort ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexEffort !== "",
+    clear: (ctx) => {
+      ctx.codexEffort = ""
+    }
+  }
+} satisfies Record<ModifierFlag, ModifierMetadata>
+
+type ScalarModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--codex-model"
+  | "--codex-effort"
+
+const SCALAR_MODIFIER_FLAGS: Record<ScalarModifierFlag, true> = {
+  "--claude-model": true,
+  "--claude-effort": true,
+  "--claude-advisor": true,
+  "--codex-model": true,
+  "--codex-effort": true
+}
+
 
 function usage(ctx: Ctx): void {
   const { echo } = ctx.services.logger
@@ -52,7 +135,6 @@ function usage(ctx: Ctx): void {
   )
   echo("  --skip-bubblewrap skip optional bubblewrap bootstrap (Codex Linux sandbox)")
   echo("  --skip-plugin-refresh  install missing plugins but skip refresh-only updates")
-  echo("  --yes             auto-accept toolchain prompts (containers/CI)")
   echo("  --verbose         also print no-op confirmations (already in sync, up to date, left as-is)")
   echo("")
   echo("Deploy-time modifiers (deployed config only; SoT untouched; a later flag-less sync reverts)")
@@ -86,13 +168,33 @@ export function parseCompactWindow(v: string): string | undefined {
   return /^[0-9]+$/.test(v) ? v : undefined
 }
 
-function addClaudePlugin(ctx: Ctx, name: string): void {
-  const { err } = ctx.services.logger
+export function parseClaudePlugin(name: string, err: (message: string) => void): string {
   if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
     err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`)
     throw new ExitError(2)
   }
-  ctx.claudePlugins.push(name)
+  return name
+}
+
+function markModifier(ctx: Ctx, flag: ModifierFlag): void {
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
+  flags.add(flag)
+  ctx.modifierFlags = flags
+}
+
+function addClaudePlugin(ctx: Ctx, name: string): void {
+  if (name === "") {
+    printCatalog(
+      ctx,
+      `Available Claude optional plugins:\n${KNOWN_CLAUDE_OPTIN_PLUGINS.map((plugin) => `  ${plugin}`).join("\n")}`
+    )
+    ctx.services.logger.err(
+      `Invalid Claude plugin '' — valid: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}`
+    )
+    throw new ExitError(2)
+  }
+  ctx.claudePlugins.push(parseClaudePlugin(name, ctx.services.logger.err))
+  markModifier(ctx, "--claude-plugin")
 }
 
 function selectTarget(ctx: Ctx, target: string): void {
@@ -102,7 +204,7 @@ function selectTarget(ctx: Ctx, target: string): void {
   ctx.targetFilterSet = true
 }
 
-function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
+function setModifier(ctx: Ctx, flag: ScalarModifierFlag, value: string): void {
   switch (flag) {
     case "--claude-model":
       ctx.claudeModel = value
@@ -120,20 +222,19 @@ function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
       ctx.codexEffort = value
       break
   }
-  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
-  flags.add(flag)
-  ctx.modifierFlags = flags
+  markModifier(ctx, flag)
 }
 
-function isModifierFlag(value: string): value is ModifierFlag {
-  return MODIFIER_FLAGS.has(value as ModifierFlag)
+function isScalarModifierFlag(value: string): value is ScalarModifierFlag {
+  return SCALAR_MODIFIER_FLAGS[value as ScalarModifierFlag] === true
 }
 
+
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   const { err } = ctx.services.logger
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index] ?? ""
-    if (isModifierFlag(arg) && args[index + 1] === "") {
+    if (isScalarModifierFlag(arg) && args[index + 1] === "") {
       setModifier(ctx, arg, "")
       index += 1
       continue
@@ -159,9 +260,6 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
       case "--prune":
         ctx.prune = true
         continue
-      case "--yes":
-        ctx.assumeYes = true
-        continue
       case "--verbose":
         ctx.verbose = true
         continue
@@ -190,6 +288,7 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         throw new ExitError(2)
       case "--claude-permissive":
         ctx.claudePermissive = true
+        markModifier(ctx, "--claude-permissive")
         continue
       case "--claude-plugin":
         err(`--claude-plugin requires a value: --claude-plugin=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`)
@@ -244,8 +343,12 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         throw new ExitError(2)
       }
       ctx.claudeCompactWindow = parsed
+      markModifier(ctx, "--claude-compact-window")
     } else if (arg.startsWith("--claude-plugin=")) {
       addClaudePlugin(ctx, arg.slice("--claude-plugin=".length))
+    } else if (arg.startsWith("--claude-permissive=")) {
+      err("--claude-permissive does not take a value")
+      throw new ExitError(2)
     } else {
       err(`Unknown arg: ${arg}`)
       throw new ExitError(2)
@@ -266,53 +369,49 @@ function printCatalog(ctx: Ctx, catalog: string): void {
 
 export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
-  const supplied = (flag: ModifierFlag, value: string): boolean =>
-    value !== "" || ctx.modifierFlags?.has(flag) === true
-  if (supplied("--claude-model", ctx.claudeModel)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-model ignored: claude target not selected")
-      ctx.claudeModel = ""
-    } else if (!validateClaudeModel(ctx, ctx.claudeModel)) {
+  const supplied = (flag: ModifierFlag): boolean =>
+    MODIFIER_METADATA[flag].hasValue(ctx) || ctx.modifierFlags?.has(flag) === true
+
+  for (const flag of Object.keys(MODIFIER_METADATA) as Array<ModifierFlag>) {
+    const metadata = MODIFIER_METADATA[flag]
+    const targetSelected = metadata.target === "claude" ? ctx.syncClaude : ctx.syncCodex
+    if (!targetSelected && supplied(flag)) {
+      warn(metadata.ignoredWarning)
+      metadata.clear(ctx)
+      ctx.modifierFlags?.delete(flag)
+    }
+  }
+
+  if (supplied("--claude-model")) {
+    if (!validateClaudeModel(ctx, ctx.claudeModel)) {
       printModels(ctx, "claude")
       err(`Invalid Claude model '${ctx.claudeModel}' — use an alias above or a full claude-* ID`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--claude-effort", ctx.claudeEffort)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-effort ignored: claude target not selected")
-      ctx.claudeEffort = ""
-    } else if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
+  if (supplied("--claude-effort")) {
+    if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
       printCatalog(ctx, effortCatalog("claude"))
       err(`Invalid Claude effort '${ctx.claudeEffort}' — valid: ${effortValueGrammar("claude")}`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--claude-advisor", ctx.claudeAdvisor)) {
-    if (!ctx.syncClaude) {
-      warn("--claude-advisor ignored: claude target not selected")
-      ctx.claudeAdvisor = ""
-    } else if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
+  if (supplied("--claude-advisor")) {
+    if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
       printCatalog(ctx, advisorCatalog())
       err(`Invalid Claude advisor state '${ctx.claudeAdvisor}' — valid: ${advisorValueGrammar()}`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--codex-model", ctx.codexModel)) {
-    if (!ctx.syncCodex) {
-      warn("--codex-model ignored: codex target not selected")
-      ctx.codexModel = ""
-    } else if (!validateCodexModel(ctx, ctx.codexModel)) {
+  if (supplied("--codex-model")) {
+    if (!validateCodexModel(ctx, ctx.codexModel)) {
       printModels(ctx, "codex")
       err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`)
       throw new ExitError(2)
     }
   }
-  if (supplied("--codex-effort", ctx.codexEffort)) {
-    if (!ctx.syncCodex) {
-      warn("--codex-effort ignored: codex target not selected")
-      ctx.codexEffort = ""
-    } else if (!isEffortModifierValue("codex", ctx.codexEffort)) {
+  if (supplied("--codex-effort")) {
+    if (!isEffortModifierValue("codex", ctx.codexEffort)) {
       printCatalog(ctx, effortCatalog("codex"))
       err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`)
       throw new ExitError(2)

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

@@ -9,11 +9,9 @@ import {
   DEPENDENCIES,
   defaultProbeExecutor,
   resolveDependency,
-  resolveLocation,
   resolvePath,
   resolveVersion,
   type DependencySpec,
-  type DependencyLocation,
   type ProbeExecutor,
   type ProbeResult,
   type ToolId
@@ -28,16 +26,12 @@ export interface DependencyManager {
   readonly probe: (id: ToolId) => ProbeResult
   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
 }
 
 export interface Platform {
   readonly raw: () => NodeJS.Platform
   readonly name: () => PlatformName
-  readonly isLinux: () => boolean
-  readonly shellRcApplicable: () => boolean
 }
 
 export interface EngineServices {
@@ -53,9 +47,7 @@ export interface EngineServiceOptions {
 /** Platform view over an injectable platform id. */
 export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
   raw: () => pf,
-  name: () => platformName(pf),
-  isLinux: () => pf === "linux",
-  shellRcApplicable: () => pf === "linux" || pf === "darwin"
+  name: () => platformName(pf)
 })
 
 /** DependencyManager whose hints default to the INJECTED platform, not the host. */
@@ -72,8 +64,6 @@ export const makeDependencyManager = (
     probe: (id) => resolveDependency(DEPENDENCIES[id], exec, platform.raw()),
     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) ?? Promise.resolve(""),
     warnMissing: (id, logger, context) => {
       if (warned.has(id)) return
       warned.add(id)

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

@@ -16,8 +16,9 @@ export function reconcileSettings(repo: Json, user: Json): Json {
  * `unique` — i.e. codepoint-sorted and deduplicated, matching jq).
  */
 export function mergeSettings(repo: Json, user: Json): Json {
-  const merged = deepMerge(user, repo)
-  if (!isObject(merged)) return merged
+  const candidate = deepMerge(user, repo)
+  if (!isObject(candidate)) return candidate
+  const merged = { ...candidate }
   const permissions = isObject(merged["permissions"]) ? merged["permissions"] : {}
   merged["permissions"] = {
     ...permissions,