docks-kit 0.15.0 → 0.15.2

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

@@ -4,7 +4,7 @@
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
-import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, isAbsolute, join } from "node:path"
 
 /** Keep engine paths slash-separated so rendered output is host-stable. */
@@ -101,23 +101,10 @@ export function isExecutable(p: string): boolean {
   }
 }
 
-export function fileExists(p: string): boolean {
-  return existsSync(p)
-}
-
 // Change-detection primitives (Output Policy in DESIGN.md): operations report
 // changed:boolean so unchanged repeat runs log at verbose instead of [ok].
 
 /** Write only when the content differs; returns whether a write happened. */
-/** Add missing +x bits; returns whether a repair actually happened. */
-export function ensureExecutable(path: string): boolean {
-  const mode = statSync(path).mode
-  const want = mode | 0o111
-  if (mode === want) return false
-  chmodSync(path, want)
-  return true
-}
-
 export function writeTextIfChanged(path: string, content: string): boolean {
   if (existsSync(path) && readFileSync(path, "utf8") === content) return false
   writeFileSync(path, content)

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

@@ -17,12 +17,15 @@ import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } f
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { normalizeManifest, skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+import { ExitError, parseArgs, parseClaudePlugin, parseCompactWindow, validateModifierFlags } from "./parseArgs"
 
 export type ModifierFlag =
   | "--claude-model"
   | "--claude-effort"
   | "--claude-advisor"
+  | "--claude-compact-window"
+  | "--claude-permissive"
+  | "--claude-plugin"
   | "--codex-model"
   | "--codex-effort"
 
@@ -117,6 +120,16 @@ export interface Ctx {
 function makeCtx(services: EngineServices): Ctx {
   const env = process.env
   const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir()
+  const compactWindowSource = env["CLAUDE_COMPACT_WINDOW"] ?? ""
+  const claudeCompactWindow = compactWindowSource === "" ? "" : parseCompactWindow(compactWindowSource)
+  if (claudeCompactWindow === undefined) {
+    services.logger.err("CLAUDE_COMPACT_WINDOW expects a token count (e.g. 680000 or 680k)")
+    throw new ExitError(2)
+  }
+  const claudePlugins = (env["CLAUDE_PLUGINS"] ?? "")
+    .split(" ")
+    .filter((plugin) => plugin !== "")
+    .map((plugin) => parseClaudePlugin(plugin, services.logger.err))
   return {
     repoDir: kitHome(),
     home,
@@ -128,9 +141,9 @@ function makeCtx(services: EngineServices): Ctx {
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
     assumeYes: env["ASSUME_YES"] === "1",
-    claudeCompactWindow: env["CLAUDE_COMPACT_WINDOW"] ?? "",
+    claudeCompactWindow,
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
-    claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
+    claudePlugins,
     claudeModel: env["CLAUDE_MODEL"] ?? "",
     claudeEffort: "",
     claudeAdvisor: "",
@@ -278,8 +291,8 @@ export async function runEngineNative(argv: ReadonlyArray<string>, services?: En
     deps: baseServices.deps,
     platform: baseServices.platform
   }
-  ctx = makeCtx(runServices)
   try {
+    ctx = makeCtx(runServices)
     switch (argv[0]) {
       case "model":
         return modeModel(ctx, argv.slice(1))

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

@@ -6,16 +6,9 @@ import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { payloadDisplayPath, payloadText } from "../payload"
 
-function catalog(): Json | undefined {
-  try {
-    return parseJson(payloadText("SoT/models.json"))
-  } catch {
-    return undefined
-  }
-}
 
 function toolEntry(tool: string): { [k: string]: Json } | undefined {
-  const doc = catalog()
+  const doc = parseJson(payloadText("SoT/models.json"))
   if (doc === undefined || !isObject(doc)) return undefined
   const entry = doc[tool]
   return entry !== undefined && isObject(entry) ? entry : undefined
@@ -37,7 +30,7 @@ export function printModels(ctx: Ctx, tool: string): void {
   const { echo, warn } = ctx.services.logger
   const entry = toolEntry(tool)
   if (entry === undefined) {
-    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json", ctx.repoDir)})`)
+    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`)
     return
   }
   const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"

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

@@ -37,19 +37,29 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   if (value === "") {
     if (tool === "claude") {
       const deployed = p(ctx.home, ".claude", "settings.json")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.claude/settings.json missing")
         return 0
       }
-      echo(`deployed: ${jsonModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.claude/settings.json: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${jsonModelText(result.data)}`)
       echo(`SoT:      ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`)
     } else {
       const deployed = p(ctx.home, ".codex", "config.toml")
-      if (!fileReadable(deployed)) {
+      const result = readConfig(deployed)
+      if (result.kind === "missing") {
         warn("~/.codex/config.toml missing")
         return 0
       }
-      echo(`deployed: ${tomlModelField(deployed)}`)
+      if (result.kind === "read-error") {
+        err(`Failed to read ~/.codex/config.toml: ${String(result.error)}`)
+        return 1
+      }
+      echo(`deployed: ${tomlModelText(result.data)}`)
       echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`)
     }
     printModels(ctx, tool)
@@ -74,20 +84,23 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
-function fileReadable(p: string): boolean {
+type ConfigReadResult =
+  | { readonly kind: "missing" }
+  | { readonly kind: "read-error"; readonly error: unknown }
+  | { readonly kind: "data"; readonly data: string }
+
+function readConfig(file: string): ConfigReadResult {
   try {
-    readFileSync(p)
-    return true
-  } catch {
-    return false
+    return { kind: "data", data: readFileSync(file, "utf8") }
+  } catch (error) {
+    const code =
+      typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : undefined
+    return code === "ENOENT" ? { kind: "missing" } : { kind: "read-error", error }
   }
 }
 
-/** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
-function jsonModelField(file: string): string {
-  return jsonModelText(readFileSync(file, "utf8"))
-}
-
 function jsonModelText(text: string): string {
   const doc = parseJson(text)
   if (doc === undefined) return ""
@@ -97,9 +110,6 @@ function jsonModelText(text: string): string {
 }
 
 /** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
-function tomlModelField(file: string): string {
-  return tomlModelText(readFileSync(file, "utf8"))
-}
 
 function tomlModelText(text: string): string {
   for (const line of text.split("\n")) {
@@ -110,9 +120,9 @@ function tomlModelText(text: string): string {
 
 export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { err } = ctx.services.logger
-  const words = args.filter((a) => !a.startsWith("--"))
-  const op = words[0] ?? args[0] ?? "check"
-  const tool = words[1] ?? args[1] ?? ""
+  const words = args.filter((arg) => !arg.startsWith("--"))
+  const op = words[0] ?? "check"
+  const tool = words[1] ?? ""
   for (const arg of args) {
     if (arg === "--yes") ctx.assumeYes = true
     else if (arg === "--verbose") {
@@ -128,7 +138,7 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
     err("Usage: toolchain [check|ensure <tool>] [--yes]")
     return 2
   }
-  if (tool === "" || tool === "--yes") {
+  if (tool === "") {
     err("Usage: toolchain ensure <tool> [--yes]")
     return 2
   }

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

@@ -14,11 +14,3 @@ export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName
   return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : "unknown"
 }
 
-export function isLinux(): boolean {
-  return rawPlatform() === "linux"
-}
-
-/** Shell-rc exports apply only on supported hosts. */
-export function shellRcApplicable(): boolean {
-  return platformName() !== "unknown"
-}

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
@@ -86,13 +169,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 +205,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 +223,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
@@ -190,6 +292,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 +347,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 +373,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

@@ -36,8 +36,6 @@ export interface DependencyManager {
 export interface Platform {
   readonly raw: () => NodeJS.Platform
   readonly name: () => PlatformName
-  readonly isLinux: () => boolean
-  readonly shellRcApplicable: () => boolean
 }
 
 export interface EngineServices {
@@ -53,9 +51,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. */

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,