docks-kit 0.17.1 → 0.17.3

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

@@ -10,11 +10,11 @@ import {
   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, type Invocation } from "./os"
+  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, type Invocation } from "./os";
 
 /** A tool this host cannot resolve, shaped like the failed spawn it replaces. */
 const notFound = (command: string): SpawnSyncReturns<string> => ({
@@ -24,8 +24,8 @@ const notFound = (command: string): SpawnSyncReturns<string> => ({
   stderr: "",
   status: null,
   signal: null,
-  error: new Error(`command not found on PATH: ${command}`)
-})
+  error: new Error(`command not found on PATH: ${command}`),
+});
 
 /**
  * Every synchronous child starts here, because two host facts must never be
@@ -37,150 +37,161 @@ export const spawnHost = (
   command: string,
   args: ReadonlyArray<string>,
   overrides: SpawnSyncOptions = {},
-  host: HostOs = hostOs()
+  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
+  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)
+    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)
+    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)
-}
+    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 {
-  return parts.join("/")
+  return parts.join("/");
 }
 
 export interface AsyncProcessResult {
-  readonly exitCode: number | null
-  readonly stdout: string
-  readonly stderr: string
-  readonly error?: Error
+  readonly exitCode: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly error?: Error;
 }
 
 export interface AsyncProcessOptions {
-  readonly stdio?: SpawnOptions["stdio"]
+  readonly stdio?: SpawnOptions["stdio"];
   /** Host whose executable resolution and argv shaping apply; tests inject it. */
-  readonly host?: HostOs
+  readonly host?: HostOs;
 }
 
 export function spawnProcess(
   cmd: string,
   args: ReadonlyArray<string>,
-  options: AsyncProcessOptions = {}
+  options: AsyncProcessOptions = {},
 ): Promise<AsyncProcessResult> {
-  const { promise, resolve } = Promise.withResolvers<AsyncProcessResult>()
-  const host = options.host ?? hostOs()
-  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "")
-  const executablePath = resolvesSuffixes ? which(cmd, host.executableSuffixes) : cmd
+  const { promise, resolve } = Promise.withResolvers<AsyncProcessResult>();
+  const host = options.host ?? hostOs();
+  const resolvesSuffixes = host.executableSuffixes.some((suffix) => suffix !== "");
+  const executablePath = resolvesSuffixes ? which(cmd, host.executableSuffixes) : cmd;
   if (executablePath === "") {
     // Never hand a pathless name to a host that resolves suffixes: CreateProcess
     // searches the parent's current directory before the system one, so an
     // untrusted checkout could answer for a missing tool.
-    resolve({ exitCode: null, stdout: "", stderr: "", error: new Error(`command not found on PATH: ${cmd}`) })
-    return promise
+    resolve({
+      exitCode: null,
+      stdout: "",
+      stderr: "",
+      error: new Error(`command not found on PATH: ${cmd}`),
+    });
+    return promise;
   }
-  let child: ChildProcess
+  let child: ChildProcess;
   try {
     // Inside the try: a host whose invocation encoding rejects a value it
     // cannot represent reports it like any other spawn failure.
-    const invocation = host.invoke(executablePath, args)
+    const invocation = host.invoke(executablePath, args);
     child = spawn(invocation.command, [...invocation.args], {
       stdio: options.stdio ?? ["ignore", "pipe", "ignore"],
-      windowsVerbatimArguments: invocation.windowsVerbatimArguments
-    })
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
   } catch (cause) {
-    const error = cause instanceof Error ? cause : new Error(String(cause))
-    resolve({ exitCode: null, stdout: "", stderr: "", error })
-    return promise
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    resolve({ exitCode: null, stdout: "", stderr: "", error });
+    return promise;
   }
-  let stdout = ""
-  let stderr = ""
-  let error: Error | undefined
+  let stdout = "";
+  let stderr = "";
+  let error: Error | undefined;
 
   if (child.stdout !== null) {
-    child.stdout.setEncoding("utf8")
+    child.stdout.setEncoding("utf8");
     child.stdout.on("data", (chunk: string) => {
-      stdout += chunk
-    })
+      stdout += chunk;
+    });
     child.stdout.on("error", (cause) => {
-      error ??= cause
-    })
+      error ??= cause;
+    });
   }
   if (child.stderr !== null) {
-    child.stderr.setEncoding("utf8")
+    child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk: string) => {
-      stderr += chunk
-    })
+      stderr += chunk;
+    });
     child.stderr.on("error", (cause) => {
-      error ??= cause
-    })
+      error ??= cause;
+    });
   }
   child.once("error", (cause) => {
-    error ??= cause
-  })
+    error ??= cause;
+  });
   child.once("close", (exitCode) => {
-    resolve({ exitCode, stdout, stderr, ...(error !== undefined ? { error } : {}) })
-  })
-  return promise
+    resolve({ exitCode, stdout, stderr, ...(error !== undefined ? { error } : {}) });
+  });
+  return promise;
 }
 
 export async function capture(cmd: string, args: ReadonlyArray<string>): Promise<string> {
-  const res = await spawnProcess(cmd, args, { stdio: ["ignore", "pipe", "ignore"] })
-  if (res.error !== undefined || res.exitCode !== 0) return ""
-  return res.stdout.replace(/[\r\n]+$/, "")
+  const res = await spawnProcess(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+  if (res.error !== undefined || res.exitCode !== 0) return "";
+  return res.stdout.replace(/[\r\n]+$/, "");
 }
 
 /** `command -v` — resolve an executable name on PATH. */
-export function which(name: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): string {
+export function which(
+  name: string,
+  suffixes: ReadonlyArray<string> = hostOs().executableSuffixes,
+): string {
   const runnableCandidate = (base: string): string => {
     for (const suffix of suffixes) {
-      const candidate = `${base}${suffix}`
-      if (isExecutable(candidate, suffixes)) return candidate
+      const candidate = `${base}${suffix}`;
+      if (isExecutable(candidate, suffixes)) return candidate;
     }
-    return ""
-  }
+    return "";
+  };
 
-  if (isAbsolute(name) || name.includes("/")) return runnableCandidate(name)
+  if (isAbsolute(name) || name.includes("/")) return runnableCandidate(name);
   for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
-    if (dir === "") continue
-    const candidate = runnableCandidate(join(dir, name))
-    if (candidate !== "") return candidate
+    if (dir === "") continue;
+    const candidate = runnableCandidate(join(dir, name));
+    if (candidate !== "") return candidate;
   }
-  return ""
+  return "";
 }
 
 export function commandExists(name: string): boolean {
-  return which(name) !== ""
+  return which(name) !== "";
 }
 
-function isExecutable(path: string, suffixes: ReadonlyArray<string> = hostOs().executableSuffixes): boolean {
+function isExecutable(
+  path: string,
+  suffixes: ReadonlyArray<string> = hostOs().executableSuffixes,
+): boolean {
   try {
-    if (!statSync(path).isFile()) return false
+    if (!statSync(path).isFile()) return false;
     if (suffixes.some((suffix) => suffix !== "")) {
-      const lowerPath = path.toLowerCase()
+      const lowerPath = path.toLowerCase();
       return suffixes.some((suffix) =>
-        suffix === "" ? extname(path) === "" : lowerPath.endsWith(suffix.toLowerCase())
-      )
+        suffix === "" ? extname(path) === "" : lowerPath.endsWith(suffix.toLowerCase()),
+      );
     }
-    accessSync(path, constants.X_OK)
-    return true
+    accessSync(path, constants.X_OK);
+    return true;
   } catch {
-    return false
+    return false;
   }
 }
 
@@ -189,14 +200,14 @@ function isExecutable(path: string, suffixes: ReadonlyArray<string> = hostOs().e
 
 /** Write only when the content differs; returns whether a write happened. */
 export function writeTextIfChanged(path: string, content: string): boolean {
-  if (existsSync(path) && readFileSync(path, "utf8") === content) return false
-  writeFileSync(path, content)
-  return true
+  if (existsSync(path) && readFileSync(path, "utf8") === content) return false;
+  writeFileSync(path, content);
+  return true;
 }
 
 export function writeBytesIfChanged(path: string, content: Uint8Array): boolean {
-  const bytes = Buffer.from(content)
-  if (existsSync(path) && readFileSync(path).equals(bytes)) return false
-  writeFileSync(path, bytes)
-  return true
+  const bytes = Buffer.from(content);
+  if (existsSync(path) && readFileSync(path).equals(bytes)) return false;
+  writeFileSync(path, bytes);
+  return true;
 }

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

@@ -3,7 +3,7 @@
  * plugin command that exits non-zero is recorded here so engineSync can list
  * it and exit non-zero instead of reporting a clean sync.
  */
-import type { Ctx } from "./index"
+import type { Ctx } from "./index";
 
 /**
  * Record a failed harness-CLI operation. The warning still prints immediately so
@@ -11,6 +11,6 @@ import type { Ctx } from "./index"
  * list the failure in the summary and exit non-zero.
  */
 export function recordFailure(ctx: Ctx, message: string): void {
-  ctx.failures.push(message)
-  ctx.services.logger.warn(message)
+  ctx.failures.push(message);
+  ctx.services.logger.warn(message);
 }

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

@@ -4,153 +4,143 @@
  * undefined so callers resolve it to LEGACY_SELECTION and existing machines
  * keep today's behavior.
  */
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { homedir } from "node:os"
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 
-import { p } from "./exec"
+import { p } from "./exec";
+import type { OmpSessionModel } from "./sharedTypes";
 
-export type Harness = "claude" | "codex" | "agents" | "omp"
+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 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 type { OmpSessionModel };
 
 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"
+  return value === "claude" || value === "codex" || value === "agents" || value === "omp";
 }
 
 function normalizeHarnesses(selection: ReadonlyArray<unknown>): Array<Harness> {
-  const selected = new Set<Harness>()
+  const selected = new Set<Harness>();
   for (const value of selection) {
-    if (isHarness(value)) selected.add(value)
+    if (isHarness(value)) selected.add(value);
   }
-  return HARNESSES.filter((harness) => selected.has(harness))
+  return HARNESSES.filter((harness) => selected.has(harness));
 }
 
 /** Resolve the engine home root from HOME with the platform home as fallback. */
 export function engineHome(env: NodeJS.ProcessEnv = process.env): string {
-  const home = env["HOME"]
-  return home !== undefined && home !== "" ? home : homedir()
+  const home = env["HOME"];
+  return home !== undefined && home !== "" ? home : homedir();
 }
 
 export function harnessStateFile(home: string): string {
-  return p(home, ".docks-kit", "state.json")
+  return p(home, ".docks-kit", "state.json");
 }
 
 // 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
+  let parsed: unknown;
   try {
-    parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown
+    parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown;
   } catch {
-    return undefined
+    return undefined;
   }
 
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
-  const state = parsed as Record<string, unknown>
-  if (state["version"] !== 1) return undefined
-  return state
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  const state = parsed as Record<string, unknown>;
+  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`
+  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)
+  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 state = readWholeState(home);
+  if (state === undefined || !Array.isArray(state["harnesses"])) return undefined;
 
-  const selection = normalizeHarnesses(state["harnesses"])
-  return selection.length > 0 ? selection : undefined
+  const selection = normalizeHarnesses(state["harnesses"]);
+  return selection.length > 0 ? selection : undefined;
 }
 
 export function writeHarnessSelection(home: string, selection: ReadonlyArray<Harness>): void {
   if (selection.length === 0) {
-    throw new Error("Cannot write an empty harness selection because sync would become a no-op")
+    throw new Error("Cannot write an empty harness selection because sync would become a no-op");
   }
 
-  const harnesses = normalizeHarnesses(selection)
+  const harnesses = normalizeHarnesses(selection);
   if (harnesses.length === 0) {
-    throw new Error("Harness selection must contain at least one known harness name")
+    throw new Error("Harness selection must contain at least one known harness name");
   }
 
-  writeWholeState(home, { harnesses })
+  writeWholeState(home, { harnesses });
 }
 
 function isNonBlankString(value: unknown): value is string {
-  return typeof value === "string" && value.trim() !== ""
+  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>
+  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
+    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 } = {
+  const thinking = record["thinking"];
+  const advisorThinking = record["advisorThinking"];
+  const model: OmpSessionModel = {
     selector: record["selector"],
-  }
-  if (isNonBlankString(record["thinking"])) {
-    model.thinking = record["thinking"]
-  }
-  if (isNonBlankString(record["advisorThinking"])) {
-    model.advisorThinking = record["advisorThinking"]
-  }
-  return model
+    ...(isNonBlankString(thinking) ? { thinking } : {}),
+    ...(isNonBlankString(advisorThinking) ? { 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")
+    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 } = {
+  const thinking = model.thinking;
+  const advisorThinking = model.advisorThinking;
+  const entry: OmpSessionModel = {
     selector: model.selector,
-  }
-  if (isNonBlankString(model.thinking)) {
-    entry.thinking = model.thinking
-  }
-  if (isNonBlankString(model.advisorThinking)) {
-    entry.advisorThinking = model.advisorThinking
-  }
+    ...(isNonBlankString(thinking) ? { thinking } : {}),
+    ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
+  };
 
-  writeWholeState(home, { ompSession: entry })
+  writeWholeState(home, { ompSession: entry });
 }