docks-kit 0.17.1 → 0.17.3

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

@@ -7,12 +7,12 @@
  * install; this registry owns WHICH external tools exist, whether they are
  * required, and the one-line command that installs a missing one.
  */
-import { homedir } from "node:os"
-import { isAbsolute } from "node:path"
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
 
-import { capture, commandExists, p, which } from "./exec"
-import { isObject, parseJson } from "./jq"
-import { hostOs, platformName, rawPlatform } from "./os"
+import { capture, commandExists, p, which } from "./exec";
+import { isObject, parseJson } from "./jq";
+import { hostOs, platformName, rawPlatform } from "./os";
 
 export type ToolId =
   | "git"
@@ -35,71 +35,74 @@ export type ToolId =
   | "apt-get"
   | "dnf"
   | "pacman"
-  | "zypper"
+  | "zypper";
 
 /** required = the engine aborts when missing; optional = warn + degrade. */
-export type Requirement = "required" | "optional"
+export type Requirement = "required" | "optional";
 
 export type ProbeResult =
   | { readonly state: "present"; readonly path?: string }
-  | { readonly state: "missing" }
+  | { readonly state: "missing" };
 
 export interface ProbeExecutor {
-  readonly commandExists: (name: string) => boolean
-  readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>
-  readonly which: (name: string) => string
+  readonly commandExists: (name: string) => boolean;
+  readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>;
+  readonly which: (name: string) => string;
 }
 
 export interface DependencySpec {
-  readonly id: ToolId
-  readonly requirement: Requirement
-  readonly versionArgs: ReadonlyArray<string>
+  readonly id: ToolId;
+  readonly requirement: Requirement;
+  readonly versionArgs: ReadonlyArray<string>;
   /** Platform-correct one-line install command (param injectable for tests). */
-  readonly installHint: (platform?: NodeJS.Platform) => string
-  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
-  readonly version?: (exec: ProbeExecutor) => Promise<string>
+  readonly installHint: (platform?: NodeJS.Platform) => string;
+  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult;
+  readonly version?: (exec: ProbeExecutor) => Promise<string>;
 }
 
 interface SpecOptions {
-  readonly versionArgs?: ReadonlyArray<string>
-  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
-  readonly version?: (exec: ProbeExecutor) => Promise<string>
+  readonly versionArgs?: ReadonlyArray<string>;
+  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult;
+  readonly version?: (exec: ProbeExecutor) => Promise<string>;
 }
 
 const spec = (
   id: ToolId,
   requirement: Requirement,
   installHint: (platform?: NodeJS.Platform) => string,
-  options: SpecOptions = {}
+  options: SpecOptions = {},
 ): DependencySpec => ({
   id,
   requirement,
   versionArgs: options.versionArgs ?? ["--version"],
   installHint,
   resolve: options.resolve,
-  version: options.version
-})
+  version: options.version,
+});
 
 // Presence is the injected executor's verdict; `which` only resolves WHERE the
 // tool is, which on Windows is the `.cmd`/`.exe` candidate rather than the name.
-const pathProbe = (id: string): ((exec: ProbeExecutor) => ProbeResult) =>
+const pathProbe =
+  (id: string): ((exec: ProbeExecutor) => ProbeResult) =>
   (exec) => {
-    if (!exec.commandExists(id)) return { state: "missing" }
-    const path = exec.which(id)
-    return path === "" ? { state: "present" } : { state: "present", path }
-  }
+    if (!exec.commandExists(id)) return { state: "missing" };
+    const path = exec.which(id);
+    return path === "" ? { state: "present" } : { state: "present", path };
+  };
 
-const versionProbe = (
-  id: string,
-  versionArgs: ReadonlyArray<string> = ["--version"],
-  parse: (out: string) => string = (out) => out
-): ((exec: ProbeExecutor) => Promise<string>) =>
-  async (exec) => parse(await exec.capture(id, versionArgs))
+const versionProbe =
+  (
+    id: string,
+    versionArgs: ReadonlyArray<string> = ["--version"],
+    parse: (out: string) => string = (out) => out,
+  ): ((exec: ProbeExecutor) => Promise<string>) =>
+  async (exec) =>
+    parse(await exec.capture(id, versionArgs));
 
 const home = (): string => {
-  const envHome = process.env["HOME"]
-  return envHome !== undefined && envHome !== "" ? envHome : homedir()
-}
+  const envHome = process.env["HOME"];
+  return envHome !== undefined && envHome !== "" ? envHome : homedir();
+};
 
 /**
  * The resolved path gets persisted into global direct-exec hooks, so a
@@ -107,156 +110,190 @@ const home = (): string => {
  * break outside the sync working directory.
  */
 const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
-  const onPath = exec.which("bun")
+  const onPath = exec.which("bun");
   if (onPath !== "" && isAbsolute(onPath)) {
-    return { command: "bun", path: onPath }
+    return { command: "bun", path: onPath };
   }
   const root =
     process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
       ? process.env["BUN_INSTALL"]!
-      : p(home(), ".bun")
+      : p(home(), ".bun");
   for (const candidate of [p(root, "bin", "bun"), p(home(), ".bun", "bin", "bun")]) {
-    const found = exec.which(candidate)
-    if (found !== "" && isAbsolute(found)) return { command: found, path: found }
+    const found = exec.which(candidate);
+    if (found !== "" && isAbsolute(found)) return { command: found, path: found };
   }
-  return undefined
-}
+  return undefined;
+};
 
 const resolveBun = (exec: ProbeExecutor): ProbeResult => {
-  const bun = findBun(exec)
-  return bun === undefined
-    ? { state: "missing" }
-    : { state: "present", path: bun.path }
-}
+  const bun = findBun(exec);
+  return bun === undefined ? { state: "missing" } : { state: "present", path: bun.path };
+};
 
-const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>()
+const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>();
 
 const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }> => {
-  const hit = npmGlobalCache.get(exec)
-  if (hit !== undefined) return hit
+  const hit = npmGlobalCache.get(exec);
+  if (hit !== undefined) return hit;
   const pending = (async (): Promise<{ [k: string]: string }> => {
-    const out: { [k: string]: string } = {}
+    const out: { [k: string]: string } = {};
     if (exec.commandExists("npm")) {
-      const doc = parseJson(await exec.capture("npm", ["ls", "-g", "--depth=0", "--json"]))
-      const deps = doc !== undefined && isObject(doc) && isObject(doc["dependencies"]) ? doc["dependencies"] : {}
+      const doc = parseJson(await exec.capture("npm", ["ls", "-g", "--depth=0", "--json"]));
+      const deps =
+        doc !== undefined && isObject(doc) && isObject(doc["dependencies"])
+          ? doc["dependencies"]
+          : {};
       for (const [name, value] of Object.entries(deps)) {
-        if (isObject(value) && typeof value["version"] === "string") out[name] = value["version"]
+        if (isObject(value) && typeof value["version"] === "string") out[name] = value["version"];
       }
     }
-    return out
-  })()
-  npmGlobalCache.set(exec, pending)
-  return pending
-}
+    return out;
+  })();
+  npmGlobalCache.set(exec, pending);
+  return pending;
+};
 
-const versionNpmGlobal = (pkg: string) => async (exec: ProbeExecutor): Promise<string> =>
-  (await npmGlobalVersions(exec))[pkg] ?? ""
+const versionNpmGlobal =
+  (pkg: string) =>
+  async (exec: ProbeExecutor): Promise<string> =>
+    (await npmGlobalVersions(exec))[pkg] ?? "";
 
-export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
+export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which };
 
 export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   git: spec(
     "git",
     "optional",
     (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git"),
-    { version: versionProbe("git") }
+    { version: versionProbe("git") },
   ),
   jq: spec("jq", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq"), {
-    version: versionProbe("jq")
-  }),
-  curl: spec("curl", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl"), {
-    version: versionProbe("curl")
-  }),
-  node: spec("node", "optional", () => "install Node.js via https://nodejs.org (or your package manager)", {
-    version: versionProbe("node")
+    version: versionProbe("jq"),
   }),
-  npm: spec("npm", "optional", () => "ships with Node.js — install via https://nodejs.org (or your package manager)"),
-  npx: spec("npx", "optional", () => "ships with Node.js — install via https://nodejs.org (or your package manager)"),
+  curl: spec(
+    "curl",
+    "optional",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl"),
+    {
+      version: versionProbe("curl"),
+    },
+  ),
+  node: spec(
+    "node",
+    "optional",
+    () => "install Node.js via https://nodejs.org (or your package manager)",
+    {
+      version: versionProbe("node"),
+    },
+  ),
+  npm: spec(
+    "npm",
+    "optional",
+    () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
+  ),
+  npx: spec(
+    "npx",
+    "optional",
+    () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
+  ),
   claude: spec(
     "claude",
     "optional",
     (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude"),
-    { version: versionProbe("claude") }
+    { version: versionProbe("claude") },
   ),
   codex: spec(
     "codex",
     "optional",
     (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex"),
-    { version: versionProbe("codex") }
+    { version: versionProbe("codex") },
   ),
   omp: spec(
     "omp",
     "optional",
-    () => "install omp from https://github.com/can1357/oh-my-pi (an existing install self-updates with `omp update`)",
-    { version: versionProbe("omp", ["--version"], (out) => out.trim().replace(/^omp[/v]/, "")) }
+    () =>
+      "install omp from https://github.com/can1357/oh-my-pi (an existing install self-updates with `omp update`)",
+    { version: versionProbe("omp", ["--version"], (out) => out.trim().replace(/^omp[/v]/, "")) },
   ),
-  bun: spec(
-    "bun",
+  bun: spec("bun", "optional", () => "curl -fsSL https://bun.sh/install | bash", {
+    resolve: resolveBun,
+    version: async (exec) => {
+      const bun = findBun(exec);
+      if (bun === undefined) return "";
+      return await exec.capture(bun.command, ["--version"]);
+    },
+  }),
+  bwrap: spec(
+    "bwrap",
     "optional",
-    () => "curl -fsSL https://bun.sh/install | bash",
+    () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)",
     {
-      resolve: resolveBun,
-      version: async (exec) => {
-        const bun = findBun(exec)
-        if (bun === undefined) return ""
-        return await exec.capture(bun.command, ["--version"])
-      }
-    }
+      version: versionProbe("bwrap"),
+    },
   ),
-  bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)", {
-    version: versionProbe("bwrap")
-  }),
   ffplay: spec(
     "ffplay",
     "optional",
     (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"),
-    { versionArgs: ["-version"], version: versionProbe("ffplay", ["-version"]), resolve: pathProbe("ffplay") }
+    {
+      versionArgs: ["-version"],
+      version: versionProbe("ffplay", ["-version"]),
+      resolve: pathProbe("ffplay"),
+    },
   ),
   intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
     resolve: pathProbe("intelephense"),
-    version: versionNpmGlobal("intelephense")
+    version: versionNpmGlobal("intelephense"),
   }),
   "typescript-language-server": spec(
     "typescript-language-server",
     "optional",
     () => "npm install -g typescript-language-server typescript",
-    { resolve: pathProbe("typescript-language-server"), version: versionProbe("typescript-language-server") }
+    {
+      resolve: pathProbe("typescript-language-server"),
+      version: versionProbe("typescript-language-server"),
+    },
   ),
   tsc: spec("tsc", "optional", () => "npm install -g typescript", {
     resolve: pathProbe("tsc"),
-    version: versionProbe("tsc")
+    version: versionProbe("tsc"),
   }),
   "rust-analyzer": spec("rust-analyzer", "optional", () => "rustup component add rust-analyzer", {
     resolve: pathProbe("rust-analyzer"),
-    version: versionProbe("rust-analyzer")
+    version: versionProbe("rust-analyzer"),
   }),
   rustup: spec("rustup", "optional", () => "install the Rust toolchain from https://rustup.rs", {
-    version: versionProbe("rustup")
+    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"),
-  zypper: spec("zypper", "optional", () => "install zypper via your Linux distribution")
-}
+  zypper: spec("zypper", "optional", () => "install zypper via your Linux distribution"),
+};
 
 export function resolveDependency(
   specification: DependencySpec,
   exec: ProbeExecutor,
-  platform: NodeJS.Platform = rawPlatform()
+  platform: NodeJS.Platform = rawPlatform(),
 ): ProbeResult {
-  return (specification.resolve ?? pathProbe(specification.id))(exec, platform)
+  return (specification.resolve ?? pathProbe(specification.id))(exec, platform);
 }
 
-export async function resolveVersion(specification: DependencySpec, exec: ProbeExecutor): Promise<string> {
-  if (resolveDependency(specification, exec).state !== "present") return ""
-  return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
+export async function resolveVersion(
+  specification: DependencySpec,
+  exec: ProbeExecutor,
+): Promise<string> {
+  if (resolveDependency(specification, exec).state !== "present") return "";
+  return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(
+    exec,
+  );
 }
 
 export async function resolvePath(
   specification: DependencySpec,
   exec: ProbeExecutor,
-  platform: NodeJS.Platform = rawPlatform()
+  platform: NodeJS.Platform = rawPlatform(),
 ): Promise<string> {
-  const result = resolveDependency(specification, exec, platform)
-  return result.state === "present" ? (result.path ?? exec.which(specification.id)) : ""
+  const result = resolveDependency(specification, exec, platform);
+  return result.state === "present" ? (result.path ?? exec.which(specification.id)) : "";
 }

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

@@ -0,0 +1,126 @@
+/**
+ * EngineNative run context: the shared `Ctx` shape plus its construction from
+ * the environment. Split from index.ts, which re-exports the public surface
+ * so existing import paths keep working.
+ */
+import { p } from "./exec";
+import { engineHome } from "./harnesses";
+import type { TerminalLease } from "./logger";
+import type { BunRuntimeState } from "./bun";
+import { kitHome } from "../kitHome";
+import { ExitError, parseClaudePlugin, parseCompactWindow } from "./parseArgs";
+import type { EngineServices } from "./services";
+import type { SyncConcurrency } from "./syncConcurrency";
+
+export type ModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--claude-compact-window"
+  | "--claude-permissive"
+  | "--claude-plugin"
+  | "--codex-model"
+  | "--codex-effort";
+
+export interface Ctx {
+  readonly repoDir: string;
+  readonly home: string;
+  readonly agentsDir: string;
+  readonly interactive: boolean;
+  dryRun: boolean;
+  verbose: boolean;
+  skipBubblewrap: boolean;
+  skipPluginRefresh?: boolean;
+  reconcile: boolean;
+  prune: boolean;
+  claudeCompactWindow: string;
+  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;
+  syncConcurrency: SyncConcurrency;
+  terminalLease?: TerminalLease;
+  bunRuntime?: Promise<BunRuntimeState>;
+  targetFilterSet: boolean;
+  syncClaude: boolean;
+  syncCodex: boolean;
+  syncAgents: boolean;
+  syncOmp: boolean;
+  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
+  readonly nextStepTriggers: {
+    claudePlugins: boolean;
+    claudeRestart: boolean;
+    codexRestart: boolean;
+    skillsRestart: boolean;
+    ompRestart: boolean;
+  };
+  /** Harness-CLI operations that failed this run; a non-empty list fails the sync. */
+  readonly failures: Array<string>;
+}
+
+/** Globals default from env using the historical ${VAR:-default} contract. */
+export function makeCtx(services: EngineServices): Ctx {
+  const env = process.env;
+  const home = engineHome(env);
+  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,
+    agentsDir:
+      env["AGENTS_DIR"] !== undefined && env["AGENTS_DIR"] !== ""
+        ? env["AGENTS_DIR"]
+        : p(home, ".agents"),
+    interactive:
+      env["DOCKS_KIT_INTERACTIVE"] === "1" ||
+      (env["DOCKS_KIT_INTERACTIVE"] !== "0" &&
+        process.stdout.isTTY === true &&
+        process.stdin.isTTY === true),
+    dryRun: env["DRY_RUN"] === "1",
+    verbose: env["DOCKS_KIT_VERBOSE"] === "1",
+    skipBubblewrap: env["SKIP_BUBBLEWRAP"] === "1",
+    skipPluginRefresh: false,
+    reconcile: env["RECONCILE"] === "1",
+    prune: env["PRUNE"] === "1",
+    claudeCompactWindow,
+    claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
+    claudePlugins,
+    claudeModel: env["CLAUDE_MODEL"] ?? "",
+    claudeEffort: "",
+    claudeAdvisor: "",
+    codexModel: env["CODEX_MODEL"] ?? "",
+    codexEffort: "",
+    modifierFlags: new Set(),
+    syncConcurrency: 3,
+    services,
+    targetFilterSet: false,
+    syncClaude: false,
+    syncCodex: false,
+    syncAgents: false,
+    syncOmp: false,
+    nextStepTriggers: {
+      claudePlugins: false,
+      claudeRestart: false,
+      codexRestart: false,
+      skillsRestart: false,
+      ompRestart: false,
+    },
+    failures: [],
+  };
+}