docks-kit 0.3.0 → 0.5.0

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

@@ -10,11 +10,19 @@ import { homedir } from "node:os"
 
 import { kitHome } from "../kitHome"
 import { makeEngineServices, type EngineServices, type Logger } from "./services"
+import type { BunRuntimeState } from "./bun"
 import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, preflight, validateModelFlags } from "./parseArgs"
+import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+
+export type ModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--codex-model"
+  | "--codex-effort"
 
 export interface Ctx {
   readonly repoDir: string
@@ -30,9 +38,15 @@ export interface Ctx {
   claudePermissive: boolean
   claudePlugins: Array<string>
   claudeModel: string
+  claudeEffort: string
+  claudeAdvisor: string
   codexModel: string
+  codexEffort: string
+  /** Distinguishes an explicitly empty modifier from an option that was not supplied. */
+  modifierFlags?: Set<ModifierFlag>
   /** Injected capability seam (logger/deps/platform) — see services.ts. */
   readonly services: EngineServices
+  bunRuntime?: BunRuntimeState
   targetFilterSet: boolean
   syncClaude: boolean
   syncCodex: boolean
@@ -64,7 +78,11 @@ function makeCtx(services: EngineServices): Ctx {
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
     claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
     claudeModel: env["CLAUDE_MODEL"] ?? "",
+    claudeEffort: "",
+    claudeAdvisor: "",
     codexModel: env["CODEX_MODEL"] ?? "",
+    codexEffort: "",
+    modifierFlags: new Set(),
     services,
     targetFilterSet: false,
     syncClaude: false,
@@ -77,11 +95,10 @@ function makeCtx(services: EngineServices): Ctx {
 function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo } = ctx.services.logger
   parseArgs(ctx, args)
-  preflight(ctx)
-  validateModelFlags(ctx)
+  validateModifierFlags(ctx)
 
   const claudeRan = ctx.syncClaude
-  if (claudeRan) claudeSync(ctx)
+  const claudeRuntime = claudeRan ? claudeSync(ctx) : undefined
 
   const codexRan = ctx.syncCodex
   if (codexRan) codexSync(ctx)
@@ -91,7 +108,7 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   echo("")
   echo("--- Sync complete ---")
   echo(`Repo:     ${ctx.repoDir}`)
-  if (claudeRan) claudeSummary(ctx)
+  if (claudeRuntime !== undefined) claudeSummary(ctx, claudeRuntime)
   if (codexRan) codexSummary(ctx)
   if (skillsState !== undefined) skillsSummary(ctx, skillsState)
 

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

@@ -6,13 +6,14 @@ import { p } from "./exec"
 import { readFileSync } from "node:fs"
 import { payloadText } from "../payload"
 
-import { syncClaudeModel } from "./claudeModel"
+import { syncClaudeModel } from "./claudeSettingsModifiers"
 import { syncCodexModel } from "./codexToml"
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
-import { rtkInstall } from "./claudeSync"
-import { agentBrowserInstall, bunBootstrap, effectSolutionsInstall } from "./skillsSync"
+import { ensureRtk } from "./claudeSync"
+import { bunBootstrap } from "./bun"
+import { agentBrowserInstall, effectSolutionsInstall } from "./skillsSync"
 import { ensure, report } from "./toolchain"
 
 export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
@@ -134,10 +135,9 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
   }
   switch (tool) {
     case "rtk":
-      return ensure(ctx, "rtk", rtkInstall(ctx))
+      return ensureRtk(ctx, "cannot download RTK installer; toolchain ensure rtk aborted", 1)
     case "bun":
-      // skills::_bun_bootstrap >/dev/null — the found-bun stdout is discarded.
-      return bunBootstrap(ctx, ctx.services) !== "" ? 0 : 1
+      return bunBootstrap(ctx, ctx.services).kind === "ready" ? 0 : 1
     case "effect-solutions":
       return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     case "agent-browser":

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

@@ -1,10 +1,20 @@
 /**
  * EngineNative flag layer: usage / target selection / compact-window parsing /
- * optional-plugin parsing / model validation / preflight. ExitError mirrors an
+ * optional-plugin parsing / model validation. ExitError mirrors an
  * early parser exit and is caught once in runEngineNative.
  */
 
-import type { Ctx } from "./index"
+import type { Ctx, ModifierFlag } from "./index"
+import {
+  CLAUDE_ADVISOR_STATES,
+  advisorCatalog,
+  advisorFlagGrammar,
+  advisorValueGrammar,
+  effortCatalog,
+  effortFlagGrammar,
+  effortValueGrammar,
+  isEffortModifierValue
+} from "../efforts"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 
 export class ExitError extends Error {
@@ -14,6 +24,13 @@ export class ExitError extends Error {
 }
 
 const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+const MODIFIER_FLAGS = new Set<ModifierFlag>([
+  "--claude-model",
+  "--claude-effort",
+  "--claude-advisor",
+  "--codex-model",
+  "--codex-effort"
+])
 
 function usage(ctx: Ctx): void {
   const { echo } = ctx.services.logger
@@ -41,6 +58,8 @@ function usage(ctx: Ctx): void {
   echo(
     "  --claude-model=<m>            set deployed ~/.claude/settings.json model (aliases: best|opus|fable|sonnet|haiku, full claude-* IDs, or 'default' to unset)"
   )
+  echo(`  ${effortFlagGrammar("claude").padEnd(39)} set deployed effortLevel`)
+  echo(`  ${advisorFlagGrammar().padEnd(39)} set deployed advisor state`)
   echo(
     "  --claude-compact-window=<n>   set deployed autocompact window in tokens (e.g. 680000 or 680k) for disposable sessions"
   )
@@ -48,6 +67,7 @@ function usage(ctx: Ctx): void {
     "  --claude-permissive           empty permissions.ask/deny in deployed settings (sandboxes/containers; unattended commits + pushes)"
   )
   echo("  --codex-model=<m>             set deployed ~/.codex/config.toml model (e.g. gpt-5.5)")
+  echo(`  ${effortFlagGrammar("codex").padEnd(39)} set deployed model_reasoning_effort`)
   echo("")
   echo("Sticky opt-ins (installed + enabled until --prune)")
   echo(
@@ -81,9 +101,42 @@ function selectTarget(ctx: Ctx, target: string): void {
   ctx.targetFilterSet = true
 }
 
+function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
+  switch (flag) {
+    case "--claude-model":
+      ctx.claudeModel = value
+      break
+    case "--claude-effort":
+      ctx.claudeEffort = value
+      break
+    case "--claude-advisor":
+      ctx.claudeAdvisor = value
+      break
+    case "--codex-model":
+      ctx.codexModel = value
+      break
+    case "--codex-effort":
+      ctx.codexEffort = value
+      break
+  }
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
+  flags.add(flag)
+  ctx.modifierFlags = flags
+}
+
+function isModifierFlag(value: string): value is ModifierFlag {
+  return MODIFIER_FLAGS.has(value as ModifierFlag)
+}
+
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   const { err } = ctx.services.logger
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? ""
+    if (isModifierFlag(arg) && args[index + 1] === "") {
+      setModifier(ctx, arg, "")
+      index += 1
+      continue
+    }
     switch (arg) {
       case "claude":
       case "codex":
@@ -116,6 +169,18 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         printModels(ctx, "codex")
         err("--codex-model requires a value: --codex-model=<model>")
         throw new ExitError(2)
+      case "--claude-effort":
+        printCatalog(ctx, effortCatalog("claude"))
+        err(`--claude-effort requires a value: ${effortFlagGrammar("claude")}`)
+        throw new ExitError(2)
+      case "--codex-effort":
+        printCatalog(ctx, effortCatalog("codex"))
+        err(`--codex-effort requires a value: ${effortFlagGrammar("codex")}`)
+        throw new ExitError(2)
+      case "--claude-advisor":
+        printCatalog(ctx, advisorCatalog())
+        err(`--claude-advisor requires a value: ${advisorFlagGrammar()}`)
+        throw new ExitError(2)
       case "--claude-compact-window":
         err("--claude-compact-window requires a value: --claude-compact-window=<tokens> (e.g. 680k)")
         throw new ExitError(2)
@@ -159,9 +224,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         break
     }
     if (arg.startsWith("--claude-model=")) {
-      ctx.claudeModel = arg.slice("--claude-model=".length)
+      setModifier(ctx, "--claude-model", arg.slice("--claude-model=".length))
     } else if (arg.startsWith("--codex-model=")) {
-      ctx.codexModel = arg.slice("--codex-model=".length)
+      setModifier(ctx, "--codex-model", arg.slice("--codex-model=".length))
+    } else if (arg.startsWith("--claude-effort=")) {
+      setModifier(ctx, "--claude-effort", arg.slice("--claude-effort=".length))
+    } else if (arg.startsWith("--codex-effort=")) {
+      setModifier(ctx, "--codex-effort", arg.slice("--codex-effort=".length))
+    } else if (arg.startsWith("--claude-advisor=")) {
+      setModifier(ctx, "--claude-advisor", arg.slice("--claude-advisor=".length))
     } else if (arg.startsWith("--claude-compact-window=")) {
       const parsed = parseCompactWindow(arg.slice("--claude-compact-window=".length))
       if (parsed === undefined) {
@@ -184,25 +255,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   }
 }
 
-export function preflight(ctx: Ctx): void {
-  const { err } = ctx.services.logger
-  if (ctx.syncClaude || ctx.syncCodex) {
-    if (ctx.services.deps.probe("jq").state === "missing") {
-      err(`jq is required (deployed statusline/hooks call it). Install: ${ctx.services.deps.spec("jq").installHint()}`)
-      throw new ExitError(1)
-    }
-  }
-  if (ctx.syncClaude) {
-    if (ctx.services.deps.probe("curl").state === "missing") {
-      err(`curl is required. Install: ${ctx.services.deps.spec("curl").installHint()}`)
-      throw new ExitError(1)
-    }
-  }
+function printCatalog(ctx: Ctx, catalog: string): void {
+  for (const line of catalog.split("\n")) ctx.services.logger.echo(line)
 }
 
-export function validateModelFlags(ctx: Ctx): void {
+export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
-  if (ctx.claudeModel !== "") {
+  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 = ""
@@ -212,7 +273,27 @@ export function validateModelFlags(ctx: Ctx): void {
       throw new ExitError(2)
     }
   }
-  if (ctx.codexModel !== "") {
+  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)) {
+      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)) {
+      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 = ""
@@ -222,4 +303,14 @@ export function validateModelFlags(ctx: Ctx): void {
       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)) {
+      printCatalog(ctx, effortCatalog("codex"))
+      err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`)
+      throw new ExitError(2)
+    }
+  }
 }

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

@@ -0,0 +1,11 @@
+export function powerShellLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`
+}
+
+export function encodePowerShellCommand(script: string): string {
+  return Buffer.from(script, "utf16le").toString("base64")
+}
+
+export function decodePowerShellCommand(encoded: string): string {
+  return Buffer.from(encoded, "base64").toString("utf16le")
+}

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

@@ -6,8 +6,8 @@
  */
 import { spawnSync } from "node:child_process"
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs"
-import { tmpdir } from "node:os"
 import { p, writeFileIfChanged } from "./exec"
+import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
 import type { EngineServices, Platform } from "./services"
@@ -277,39 +277,6 @@ function syncAgentBrowserCli(ctx: Ctx, manifest: string): void {
   }
 }
 
-/** skills::_find_bun — resolved bun path or "". */
-function findBun(ctx: Ctx): string {
-  return ctx.services.deps.path("bun")
-}
-
-/** skills::_bun_bootstrap — bun path or "" after a failed bootstrap. */
-export function bunBootstrap(ctx: Ctx, services: EngineServices): string {
-  const { change, warn } = services.logger
-  let bun = findBun(ctx)
-  if (bun !== "") return bun
-
-  if (services.deps.probe("curl").state === "missing") {
-    warn("Bun and curl both missing — cannot bootstrap Bun. Install Bun manually, then re-run sync.")
-    return ""
-  }
-  const pin = field(ctx, "bun", "verified")
-  warn(`Bun not found — installing Bun${pin !== "" ? ` ${pin} (kit-verified)` : ""}...`)
-  const installer = p(tmpdir(), `bun-install-${process.pid}.sh`)
-  const dl = spawnSync("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
-  if (dl.error === undefined && dl.status === 0) {
-    spawnSync("bash", [installer, ...(pin !== "" ? [`bun-v${pin}`] : [])], { stdio: "ignore" })
-  }
-  rmSync(installer, { force: true })
-  bun = findBun(ctx)
-  if (bun === "") {
-    warn("Bun install failed. Install manually: curl -fsSL https://bun.sh/install -o /tmp/bun.sh && bash /tmp/bun.sh")
-    return ""
-  }
-  const version = services.deps.version("bun")
-  change(`Bun installed (${version !== "" ? version : "version unknown"})`)
-  return bun
-}
-
 /** skills::_effect_solutions_install. */
 export function effectSolutionsInstall(
   ctx: Ctx
@@ -319,8 +286,9 @@ export function effectSolutionsInstall(
     const verb = mode === "upgrade" ? "Upgrading" : "Installing"
     const pkg = `effect-solutions@${version !== "" ? version : "latest"}`
 
-    const bun = bunBootstrap(ctx, services)
-    if (bun === "") return 1
+    const bunState = bunBootstrap(ctx, services)
+    if (bunState.kind === "deferred") return 1
+    const bun = bunState.executable
 
     verbose(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
     if (spawnSync(bun, ["add", "-g", pkg], { stdio: "ignore" }).status !== 0) {