docks-kit 0.16.16 → 0.17.0

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

@@ -402,43 +402,10 @@ async function nodeBelowServerFloor(ctx: Ctx): Promise<string> {
   return belowFloor(installed, floor) ? installed : ""
 }
 
-export async function syncLspServers(ctx: Ctx): Promise<void> {
+/** npm-global channel: intelephense, typescript-language-server, typescript. */
+async function installNpmServers(ctx: Ctx, missing: ReadonlyArray<string>): Promise<void> {
   const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
-  const sot = parseJson(payloadText("SoT/.claude/settings.json"))
-  const enabled = sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"]) ? sot["enabledPlugins"] : undefined
-  if (enabled === undefined) return
-  const hasPhp = Object.prototype.hasOwnProperty.call(enabled, "php-lsp@claude-plugins-official")
-  const hasTs = Object.prototype.hasOwnProperty.call(enabled, "typescript-lsp@claude-plugins-official")
-  if (!hasPhp && !hasTs) return
-
-  const phpMissing = hasPhp && ctx.services.deps.probe("intelephense").state === "missing"
-  const tsServerMissing = hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing"
-  const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing"
-  const missingToolCount = Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing)
-  const blockingNode = tsServerMissing ? await nodeBelowServerFloor(ctx) : ""
-  if (blockingNode !== "") {
-    warn(
-      `Skipping typescript-language-server install: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node, then re-run sync.`
-    )
-  }
-  const missing = [
-    phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
-    tsServerMissing && blockingNode === ""
-      ? lspPkg(ctx, "typescript-language-server", "typescript-language-server")
-      : undefined,
-    tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined
-  ].filter((spec): spec is string => spec !== undefined)
-
-  if (missingToolCount === 0) {
-    if (ctx.dryRun) {
-      echo("[dry-run] LSP server binaries present")
-    } else {
-      verbose("LSP server binaries present")
-    }
-    return
-  }
   if (missing.length === 0) return
-
   const specs = missing.join(" ")
   if (ctx.dryRun) {
     echo(`[dry-run] would install: npm install -g ${specs}`)
@@ -465,3 +432,79 @@ export async function syncLspServers(ctx: Ctx): Promise<void> {
     warn(`npm install -g ${specs} failed. Try manually: npm install -g ${specs}`)
   }
 }
+
+/**
+ * rustup channel: rust-analyzer ships no npm package, and upstream's first
+ * recommendation is the rustup component, which tracks the toolchain the host
+ * already trusts. The component version therefore follows that toolchain, so
+ * the manifest row carries no verified pin - the stance bubblewrap already
+ * takes for a distro package.
+ */
+async function installRustAnalyzer(ctx: Ctx): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
+  if (ctx.dryRun) {
+    echo("[dry-run] would install: rustup component add rust-analyzer")
+    return
+  }
+  verbose("Installing rust-analyzer via rustup...")
+  progress("Installing rust-analyzer via rustup...")
+  const result = await spawnProcess("rustup", ["component", "add", "rust-analyzer"], { stdio: "ignore" })
+  clearProgress()
+  if (result.exitCode === 0) {
+    change("LSP server installed (rust-analyzer via rustup)")
+    ctx.nextStepTriggers.claudeRestart = true
+  } else {
+    warn("rustup component add rust-analyzer failed. Try manually: rustup component add rust-analyzer")
+  }
+}
+
+export async function syncLspServers(ctx: Ctx): Promise<void> {
+  const { echo, verbose, warn } = ctx.services.logger
+  const sot = parseJson(payloadText("SoT/.claude/settings.json"))
+  const enabled = sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"]) ? sot["enabledPlugins"] : undefined
+  if (enabled === undefined) return
+  const enables = (plugin: string): boolean => Object.prototype.hasOwnProperty.call(enabled, plugin)
+  const hasPhp = enables("php-lsp@claude-plugins-official")
+  const hasTs = enables("typescript-lsp@claude-plugins-official")
+  const hasRust = enables("rust-analyzer-lsp@claude-plugins-official")
+  if (!hasPhp && !hasTs && !hasRust) return
+
+  const phpMissing = hasPhp && ctx.services.deps.probe("intelephense").state === "missing"
+  const tsServerMissing = hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing"
+  const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing"
+  const rustMissing = hasRust && ctx.services.deps.probe("rust-analyzer").state === "missing"
+  // A host without rustup does no Rust work, so the plugin has nothing to
+  // serve there. Installing is impossible and warning every sync would name no
+  // action the user wants, so that host is not counted as missing a tool.
+  const rustInstallable = rustMissing && ctx.services.deps.probe("rustup").state === "present"
+  if (rustMissing && !rustInstallable) {
+    verbose("Skipping rust-analyzer: rustup is not installed, so the rust-analyzer-lsp plugin stays a no-op")
+  }
+
+  const missingToolCount = Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing) + Number(rustInstallable)
+  if (missingToolCount === 0) {
+    if (ctx.dryRun) {
+      echo("[dry-run] LSP server binaries present")
+    } else {
+      verbose("LSP server binaries present")
+    }
+    return
+  }
+
+  const blockingNode = tsServerMissing ? await nodeBelowServerFloor(ctx) : ""
+  if (blockingNode !== "") {
+    warn(
+      `Skipping typescript-language-server install: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node, then re-run sync.`
+    )
+  }
+  const missing = [
+    phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
+    tsServerMissing && blockingNode === ""
+      ? lspPkg(ctx, "typescript-language-server", "typescript-language-server")
+      : undefined,
+    tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined
+  ].filter((spec): spec is string => spec !== undefined)
+
+  await installNpmServers(ctx, missing)
+  if (rustInstallable) await installRustAnalyzer(ctx)
+}

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

@@ -30,6 +30,8 @@ export type ToolId =
   | "intelephense"
   | "typescript-language-server"
   | "tsc"
+  | "rust-analyzer"
+  | "rustup"
   | "apt-get"
   | "dnf"
   | "pacman"
@@ -224,6 +226,13 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     resolve: pathProbe("tsc"),
     version: versionProbe("tsc")
   }),
+  "rust-analyzer": spec("rust-analyzer", "optional", () => "rustup component add rust-analyzer", {
+    resolve: pathProbe("rust-analyzer"),
+    version: versionProbe("rust-analyzer")
+  }),
+  rustup: spec("rustup", "optional", () => "install the Rust toolchain from https://rustup.rs", {
+    version: versionProbe("rustup")
+  }),
   "apt-get": spec("apt-get", "optional", () => "install apt via your Linux distribution"),
   dnf: spec("dnf", "optional", () => "install dnf via your Linux distribution"),
   pacman: spec("pacman", "optional", () => "install pacman via your Linux distribution"),

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

@@ -3,10 +3,62 @@
  * the intended binary with deterministic argv, and capture() mirrors command
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
-import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"
+import {
+  spawn,
+  spawnSync,
+  type ChildProcess,
+  type SpawnOptions,
+  type SpawnSyncOptions,
+  type SpawnSyncOptionsWithStringEncoding,
+  type SpawnSyncReturns
+} from "node:child_process"
 import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, extname, isAbsolute, join } from "node:path"
-import { hostOs, type HostOs } from "./os"
+import { hostOs, type HostOs, type Invocation } from "./os"
+
+/** A tool this host cannot resolve, shaped like the failed spawn it replaces. */
+const notFound = (command: string): SpawnSyncReturns<string> => ({
+  pid: 0,
+  output: [],
+  stdout: "",
+  stderr: "",
+  status: null,
+  signal: null,
+  error: new Error(`command not found on PATH: ${command}`)
+})
+
+/**
+ * Every synchronous child starts here, because two host facts must never be
+ * separated from the argv they describe: a Windows shim invocation is only
+ * correct with the verbatim-arguments flag, and a pathless name would let
+ * CreateProcess search the parent's current directory before the system one.
+ */
+export const spawnHost = (
+  command: string,
+  args: ReadonlyArray<string>,
+  overrides: SpawnSyncOptions = {},
+  host: HostOs = hostOs()
+): SpawnSyncReturns<string> => {
+  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
+  const executablePath = resolvesSuffixes ? which(command, host.executableSuffixes) : command
+  if (executablePath === "") return notFound(command)
+  let invocation: Invocation
+  try {
+    invocation = host.invoke(executablePath, args)
+  } catch (cause) {
+    // A value this host cannot put on a command line at all. Print the encoder's
+    // reason and exit, matching how a caller reports a failed child.
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
+    return process.exit(2)
+  }
+  const options: SpawnSyncOptionsWithStringEncoding = {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...overrides,
+    encoding: "utf8",
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments
+  }
+  return spawnSync(invocation.command, [...invocation.args], options)
+}
 
 /** Keep engine paths slash-separated so rendered output is host-stable. */
 export function p(...parts: Array<string>): string {

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

@@ -14,6 +14,21 @@ export type Harness = "claude" | "codex" | "agents" | "omp"
 export const HARNESSES: ReadonlyArray<Harness> = ["claude", "codex", "agents", "omp"]
 export const LEGACY_SELECTION: ReadonlyArray<Harness> = ["claude", "codex", "agents"]
 
+export interface OmpSessionModel {
+  readonly selector: string
+  // Session ceiling; absent when the model publishes no ladder, so no
+  // invented level ever reaches a selector that omp must resolve.
+  readonly thinking?: string
+  // Advisor level; absent when the model publishes no ladder.
+  readonly advisorThinking?: string
+}
+
+export const DEFAULT_OMP_SESSION_MODEL: OmpSessionModel = {
+  selector: "opencode-zen/muse-spark-1.3-contributor-free",
+  thinking: "xhigh",
+  advisorThinking: "medium",
+}
+
 function isHarness(value: unknown): value is Harness {
   return value === "claude" || value === "codex" || value === "agents" || value === "omp"
 }
@@ -36,8 +51,9 @@ export function harnessStateFile(home: string): string {
   return p(home, ".docks-kit", "state.json")
 }
 
-/** Read valid local state without allowing corruption to make sync unusable. */
-export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
+// Read the whole state record so one key writer keeps sibling keys intact.
+// A corrupt file degrades to undefined so callers fall back to defaults.
+function readWholeState(home: string): Record<string, unknown> | undefined {
   let parsed: unknown
   try {
     parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown
@@ -47,7 +63,30 @@ export function readHarnessSelection(home: string): ReadonlyArray<Harness> | und
 
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
   const state = parsed as Record<string, unknown>
-  if (state["version"] !== 1 || !Array.isArray(state["harnesses"])) return undefined
+  if (state["version"] !== 1) return undefined
+  return state
+}
+
+// Merge the patch over the stored record so independent keys never erase
+// each other when only one writer runs.
+function writeWholeState(home: string, patch: Record<string, unknown>): void {
+  const existing = readWholeState(home) ?? {}
+  const next = { ...existing, ...patch, version: 1 }
+  const directory = p(home, ".docks-kit")
+  const file = harnessStateFile(home)
+  const text = `${JSON.stringify(next, null, 2)}\n`
+  // `mode` applies only when mkdir creates the path, so an existing permissive
+  // ~/.docks-kit would keep its mode.
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  chmodSync(directory, 0o700)
+  writeFileSync(file, text, { mode: 0o600 })
+  chmodSync(file, 0o600)
+}
+
+/** Read valid local state without allowing corruption to make sync unusable. */
+export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
+  const state = readWholeState(home)
+  if (state === undefined || !Array.isArray(state["harnesses"])) return undefined
 
   const selection = normalizeHarnesses(state["harnesses"])
   return selection.length > 0 ? selection : undefined
@@ -63,13 +102,55 @@ export function writeHarnessSelection(home: string, selection: ReadonlyArray<Har
     throw new Error("Harness selection must contain at least one known harness name")
   }
 
-  const directory = p(home, ".docks-kit")
-  const file = harnessStateFile(home)
-  const text = `${JSON.stringify({ version: 1, harnesses }, null, 2)}\n`
-  // `mode` applies only when mkdir creates the path, so an existing permissive
-  // ~/.docks-kit would keep its mode.
-  mkdirSync(directory, { recursive: true, mode: 0o700 })
-  chmodSync(directory, 0o700)
-  writeFileSync(file, text, { mode: 0o600 })
-  chmodSync(file, 0o600)
+  writeWholeState(home, { harnesses })
+}
+
+function isNonBlankString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== ""
+}
+
+// Read the stored session model without throwing so a corrupt entry falls
+// back to the default instead of breaking sync.
+export function readOmpSessionModel(home: string): OmpSessionModel | undefined {
+  const state = readWholeState(home)
+  if (state === undefined) return undefined
+  const entry = state["ompSession"]
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return undefined
+  const record = entry as Record<string, unknown>
+  if (!isNonBlankString(record["selector"])) {
+    return undefined
+  }
+  // Each level stands alone, so a level-free model reads back with no
+  // levels while a half-corrupt entry keeps the valid level.
+  const model: { selector: string; thinking?: string; advisorThinking?: string } = {
+    selector: record["selector"],
+  }
+  if (isNonBlankString(record["thinking"])) {
+    model.thinking = record["thinking"]
+  }
+  if (isNonBlankString(record["advisorThinking"])) {
+    model.advisorThinking = record["advisorThinking"]
+  }
+  return model
+}
+
+export function writeOmpSessionModel(home: string, model: OmpSessionModel): void {
+  // A blank selector would make omp resolve an arbitrary model, so reject it
+  // before anything reaches disk.
+  if (!isNonBlankString(model.selector)) {
+    throw new Error("Omp session model selector must be a non-empty string")
+  }
+  // Persist only non-blank levels so a switch to a level-free model leaves
+  // no stale level behind in the stored record.
+  const entry: { selector: string; thinking?: string; advisorThinking?: string } = {
+    selector: model.selector,
+  }
+  if (isNonBlankString(model.thinking)) {
+    entry.thinking = model.thinking
+  }
+  if (isNonBlankString(model.advisorThinking)) {
+    entry.advisorThinking = model.advisorThinking
+  }
+
+  writeWholeState(home, { ompSession: entry })
 }

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

@@ -0,0 +1,174 @@
+/**
+ * Run overlay for `docks-kit omp`. The overlay merges over the deployed omp
+ * config for one run only, so every key that can cause paid spend is set here
+ * and every other key falls through to the deployed paid config.
+ */
+import { createHash } from "node:crypto"
+import type { OmpSessionModel } from "./harnesses"
+
+export interface CatalogModel {
+  readonly selector: string
+  readonly name: string
+  readonly thinking: ReadonlyArray<string>
+  readonly contextWindow: number
+}
+
+/** Thinking levels from lowest to highest effort. */
+export const THINKING_LADDER: ReadonlyArray<string> = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]
+
+/**
+ * One overlay file per model, so a second launcher on another model cannot
+ * rewrite the file a running session still reads. A selector carries a slash
+ * and may carry other characters a host rejects in a file name, so unsafe
+ * characters become hyphens. That mapping alone is not injective, because
+ * `a/b` and `a-b` both fold to `a-b`, so a digest of the exact selector keeps
+ * two distinct models on two distinct files.
+ */
+export function overlayFileName(selector: string): string {
+  const safe = selector.replace(/[^A-Za-z0-9._-]/g, "-")
+  const digest = createHash("sha256").update(selector).digest("hex").slice(0, 8)
+  return `omp-free-${safe}-${digest}.yml`
+}
+
+/** Role keys in the order used by SoT/.omp/config.yml for readable diffs. */
+const ROLE_ORDER: ReadonlyArray<string> = [
+  "smol",
+  "advisor",
+  "designer",
+  "plan",
+  "commit",
+  "task",
+  "vision",
+  "tiny",
+  "default",
+  "slow",
+  "fable",
+  "switch_fable",
+]
+
+/** Retry chain keys in the order used by SoT/.omp/config.yml. */
+const FALLBACK_ORDER: ReadonlyArray<string> = [
+  "default",
+  "advisor",
+  "task",
+  "vision",
+  "smol",
+  "tiny",
+  "commit",
+  "switch_fable",
+  "fable",
+]
+
+/**
+ * Collect free models from parsed `omp models --json` output. The function is
+ * total because catalog output varies across omp versions, and one malformed
+ * row must not discard the remaining picker list.
+ */
+export function parseFreeModels(catalogJson: unknown): ReadonlyArray<CatalogModel> {
+  if (typeof catalogJson !== "object" || catalogJson === null || Array.isArray(catalogJson)) {
+    return []
+  }
+  const models = (catalogJson as Record<string, unknown>)["models"]
+  if (!Array.isArray(models)) return []
+  const found: Array<CatalogModel> = []
+  for (const row of models) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) continue
+    const record = row as Record<string, unknown>
+    const selector = record["selector"]
+    if (typeof selector !== "string" || selector.length === 0) continue
+    const cost = record["cost"]
+    if (typeof cost !== "object" || cost === null || Array.isArray(cost)) continue
+    const charges = cost as Record<string, unknown>
+    if (charges["input"] !== 0 || charges["output"] !== 0) continue
+    const rawName = record["name"]
+    const name = typeof rawName === "string" && rawName.length > 0 ? rawName : selector
+    const rawLevels = record["thinking"]
+    // Keep only known ladder levels in ladder order so an unknown future
+    // level never reaches a role value that omp would reject.
+    const thinking = THINKING_LADDER.filter(
+      (level) => Array.isArray(rawLevels) && (rawLevels as Array<unknown>).includes(level),
+    )
+    const rawWindow = record["contextWindow"]
+    const contextWindow =
+      typeof rawWindow === "number" && Number.isFinite(rawWindow) ? rawWindow : 0
+    found.push({ selector, name, thinking, contextWindow })
+  }
+  // Sort by selector so the picker list is stable across catalog orderings.
+  found.sort((a, b) => (a.selector < b.selector ? -1 : a.selector > b.selector ? 1 : 0))
+  return found
+}
+
+/**
+ * Resolve the highest ladder level a model supports. A model without a
+ * recognized ladder yields undefined so callers never invent a level the
+ * model would reject at session start.
+ */
+export function ladderCeiling(levels: ReadonlyArray<string>): string | undefined {
+  for (let index = THINKING_LADDER.length - 1; index >= 0; index -= 1) {
+    if (levels.includes(THINKING_LADDER[index] as string)) return THINKING_LADDER[index] as string
+  }
+  return undefined
+}
+
+/**
+ * Resolve the advisor level from the model own ladder. The advisor runs
+ * quick review passes, so it takes the highest level at or below medium,
+ * and the lowest level when the ladder starts above medium. The result
+ * never exceeds the ladder ceiling by construction.
+ */
+export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefined {
+  const known = THINKING_LADDER.filter((level) => levels.includes(level))
+  if (known.length === 0) return undefined
+  const mediumIndex = THINKING_LADDER.indexOf("medium")
+  let advisor: string | undefined
+  for (const level of known) {
+    if ((THINKING_LADDER.indexOf(level) as number) <= (mediumIndex as number)) advisor = level
+  }
+  return advisor ?? (known[0] as string)
+}
+
+/**
+ * Render the run overlay as YAML text. Empty fallback chains keep a retry
+ * from falling back onto a paid model. A model without a level renders bare
+ * selectors with no thinking keys so the deployed values apply.
+ */
+export function renderFreeOverlay(model: OmpSessionModel): string {
+  const thinking = typeof model.thinking === "string" && model.thinking.trim() !== "" ? model.thinking : undefined
+  const lines: Array<string> = ["# Generated per run by docks-kit omp. Edits are overwritten."]
+  if (thinking !== undefined) {
+    lines.push(`defaultThinkingLevel: ${thinking}`, "modelRoles:")
+    const advisor =
+      typeof model.advisorThinking === "string" && model.advisorThinking.trim() !== ""
+        ? model.advisorThinking
+        : thinking
+    for (const role of ROLE_ORDER) {
+      lines.push(`  ${role}: ${model.selector}:${role === "advisor" ? advisor : thinking}`)
+    }
+    lines.push("task:", `  maxEffort: ${thinking}`)
+  } else {
+    lines.push("modelRoles:")
+    for (const role of ROLE_ORDER) {
+      lines.push(`  ${role}: ${model.selector}`)
+    }
+  }
+  lines.push("retry:", "  fallbackChains:")
+  for (const chain of FALLBACK_ORDER) {
+    lines.push(`    ${chain}: []`)
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** Build the omp argv with the overlay flag ahead of the forwarded args. */
+export function buildOmpArgs(
+  overlayPath: string,
+  passthrough: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  return ["--config", overlayPath, ...passthrough]
+}

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

@@ -67,6 +67,9 @@ export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string>
       return (await version()).replace(/^jq-/, "")
     case "curl":
     case "tsc":
+    // `rust-analyzer --version` prints "rust-analyzer <version>", where the
+    // version tail also carries a commit and a date in parentheses.
+    case "rust-analyzer":
       return firstLineField(await version(), 1)
     case "bun":
     case "omp":