docks-kit 0.17.0 → 0.17.2

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

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from "node:async_hooks"
+import { AsyncLocalStorage } from "node:async_hooks";
 
 /**
  * Leveled stderr logger, one run-scoped terminal lease, and stdout data
@@ -10,43 +10,42 @@ import { AsyncLocalStorage } from "node:async_hooks"
  */
 export interface TerminalLease {
   /** Replace the coordinator-owned transient line. */
-  readonly update: (message: string) => void
+  readonly update: (message: string) => void;
   /** Serialize terminal input owners and suspend transient redraw while held. */
-  readonly withExclusive: <T>(action: () => T | Promise<T>) => Promise<T>
+  readonly withExclusive: <T>(action: () => T | Promise<T>) => Promise<T>;
   /** Clear coordinator progress and return ownership to ordinary progress calls. */
-  readonly release: () => void
+  readonly release: () => void;
 }
 
-
 export interface Logger {
   /** `[ok]` green — an operation actually mutated something. Always visible. */
-  readonly change: (msg: string) => void
+  readonly change: (msg: string) => void;
   /** Dim, transient single-line status for blocking work. */
-  readonly progress: (msg: string) => void
+  readonly progress: (msg: string) => void;
   /** Erase a pending transient status line. */
-  readonly clearProgress: () => void
+  readonly clearProgress: () => void;
   /** `[ok]` green — status-quo confirmation; visible only with verbosity on. */
-  readonly verbose: (msg: string) => void
-  readonly warn: (msg: string) => void
-  readonly err: (msg: string) => void
+  readonly verbose: (msg: string) => void;
+  readonly warn: (msg: string) => void;
+  readonly err: (msg: string) => void;
   /** stdout data line (dry-run report, summary, usage) — never filtered. */
-  readonly echo: (line: string) => void
+  readonly echo: (line: string) => void;
   /** Acquire the run-scoped coordinator lease for terminal progress and input. */
-  readonly acquireTerminal: (message: string) => TerminalLease
+  readonly acquireTerminal: (message: string) => TerminalLease;
 }
 
 export interface LoggerSinks {
-  readonly stderr?: (chunk: string) => void
-  readonly progress?: (chunk: string) => void
-  readonly stdout?: (chunk: string) => void
+  readonly stderr?: (chunk: string) => void;
+  readonly progress?: (chunk: string) => void;
+  readonly stdout?: (chunk: string) => void;
 }
 
 interface WritableStreamLike {
-  write: (chunk: string) => unknown
-  on?: (event: "error", listener: (error: unknown) => void) => unknown
+  write: (chunk: string) => unknown;
+  on?: (event: "error", listener: (error: unknown) => void) => unknown;
 }
 
-const epipeGuarded = new WeakSet<WritableStreamLike>()
+const epipeGuarded = new WeakSet<WritableStreamLike>();
 
 /**
  * A downstream reader may close the pipe early (`docks-kit toolchain check |
@@ -55,144 +54,143 @@ const epipeGuarded = new WeakSet<WritableStreamLike>()
  */
 export function writeIgnoringEpipe(stream: WritableStreamLike, chunk: string): void {
   if (!epipeGuarded.has(stream)) {
-    epipeGuarded.add(stream)
+    epipeGuarded.add(stream);
     stream.on?.("error", (error) => {
-      if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error
-    })
+      if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error;
+    });
   }
   try {
-    stream.write(chunk)
+    stream.write(chunk);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error
+    if ((error as NodeJS.ErrnoException | null)?.code !== "EPIPE") throw error;
   }
 }
 
 export function makeLogger(sinks: LoggerSinks): Logger {
-  const errWrite = sinks.stderr ?? ((chunk: string) => writeIgnoringEpipe(process.stderr, chunk))
-  const outWrite = sinks.stdout ?? ((chunk: string) => writeIgnoringEpipe(process.stdout, chunk))
+  const errWrite = sinks.stderr ?? ((chunk: string) => writeIgnoringEpipe(process.stderr, chunk));
+  const outWrite = sinks.stdout ?? ((chunk: string) => writeIgnoringEpipe(process.stdout, chunk));
   const progressWrite =
     sinks.progress ??
     (sinks.stderr === undefined && process.stderr.isTTY === true
       ? (chunk: string) => writeIgnoringEpipe(process.stderr, chunk)
-      : undefined)
-  let progressPending = false
-  let activeLease: TerminalLease | undefined
-  let exclusiveActive = false
-  const exclusiveContext = new AsyncLocalStorage<{ active: boolean }>()
-  const durableBuffer: Array<() => void> = []
-
+      : undefined);
+  let progressPending = false;
+  let activeLease: TerminalLease | undefined;
+  let exclusiveActive = false;
+  const exclusiveContext = new AsyncLocalStorage<{ active: boolean }>();
+  const durableBuffer: Array<() => void> = [];
 
   const eraseProgress = (): void => {
-    if (!progressPending || progressWrite === undefined) return
-    progressWrite("\r\x1b[2K")
-    progressPending = false
-  }
+    if (!progressPending || progressWrite === undefined) return;
+    progressWrite("\r\x1b[2K");
+    progressPending = false;
+  };
   const drawProgress = (message: string): void => {
-    if (progressWrite === undefined) return
-    progressWrite(`\r\x1b[2K\x1b[2m${message}\x1b[0m`)
-    progressPending = true
-  }
+    if (progressWrite === undefined) return;
+    progressWrite(`\r\x1b[2K\x1b[2m${message}\x1b[0m`);
+    progressPending = true;
+  };
   const clearProgress = (): void => {
-    if (activeLease !== undefined) return
-    eraseProgress()
-  }
+    if (activeLease !== undefined) return;
+    eraseProgress();
+  };
   const writeDurable = (write: () => void): void => {
     if (exclusiveActive) {
-      durableBuffer.push(write)
-      return
+      durableBuffer.push(write);
+      return;
     }
-    eraseProgress()
-    write()
-  }
+    eraseProgress();
+    write();
+  };
   const flushDurable = (): void => {
-    let firstError: unknown
+    let firstError: unknown;
     while (durableBuffer.length > 0) {
       for (const write of durableBuffer.splice(0)) {
         try {
-          write()
+          write();
         } catch (error) {
-          firstError ??= error
+          firstError ??= error;
         }
       }
     }
-    if (firstError !== undefined) throw firstError
-  }
+    if (firstError !== undefined) throw firstError;
+  };
   const ok = (msg: string): void => {
-    writeDurable(() => errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`))
-  }
+    writeDurable(() => errWrite(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`));
+  };
 
   const acquireTerminal = (message: string): TerminalLease => {
-    if (activeLease !== undefined) throw new Error("terminal lease already acquired")
+    if (activeLease !== undefined) throw new Error("terminal lease already acquired");
 
-    let released = false
-    let coordinatorMessage = message
-    let exclusiveTail = Promise.resolve()
-    let exclusivePending = 0
+    let released = false;
+    let coordinatorMessage = message;
+    let exclusiveTail = Promise.resolve();
+    let exclusivePending = 0;
     const lease: TerminalLease = {
       update: (nextMessage) => {
-        if (released) return
-        coordinatorMessage = nextMessage
-        if (exclusivePending === 0) drawProgress(coordinatorMessage)
+        if (released) return;
+        coordinatorMessage = nextMessage;
+        if (exclusivePending === 0) drawProgress(coordinatorMessage);
       },
       withExclusive: async <T>(action: () => T | Promise<T>): Promise<T> => {
         if (exclusiveContext.getStore()?.active === true) {
-          throw new Error("terminal lease withExclusive cannot be re-entered")
+          throw new Error("terminal lease withExclusive cannot be re-entered");
         }
-        if (released) return await action()
-        exclusivePending += 1
-        const previous = exclusiveTail
-        let unlock!: () => void
+        if (released) return await action();
+        exclusivePending += 1;
+        const previous = exclusiveTail;
+        let unlock!: () => void;
         exclusiveTail = new Promise<void>((resolve) => {
-          unlock = resolve
-        })
-        await previous
-        eraseProgress()
-        exclusiveActive = true
-        const owner = { active: true }
+          unlock = resolve;
+        });
+        await previous;
+        eraseProgress();
+        exclusiveActive = true;
+        const owner = { active: true };
         try {
-          return await exclusiveContext.run(owner, action)
+          return await exclusiveContext.run(owner, action);
         } finally {
-          owner.active = false
+          owner.active = false;
           try {
-            flushDurable()
+            flushDurable();
           } finally {
-            exclusiveActive = false
-            exclusivePending -= 1
-            unlock()
-            if (!released && exclusivePending === 0) drawProgress(coordinatorMessage)
+            exclusiveActive = false;
+            exclusivePending -= 1;
+            unlock();
+            if (!released && exclusivePending === 0) drawProgress(coordinatorMessage);
           }
         }
       },
       release: () => {
-        if (released) return
-        released = true
-        if (activeLease === lease) activeLease = undefined
-        eraseProgress()
-      }
-    }
-    activeLease = lease
-    drawProgress(coordinatorMessage)
-    return lease
-  }
+        if (released) return;
+        released = true;
+        if (activeLease === lease) activeLease = undefined;
+        eraseProgress();
+      },
+    };
+    activeLease = lease;
+    drawProgress(coordinatorMessage);
+    return lease;
+  };
 
   return {
     change: ok,
     verbose: ok,
     progress: (msg) => {
-      if (activeLease !== undefined) return
-      drawProgress(msg)
+      if (activeLease !== undefined) return;
+      drawProgress(msg);
     },
     clearProgress,
     warn: (msg) => {
-      writeDurable(() => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`))
+      writeDurable(() => errWrite(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`));
     },
     err: (msg) => {
-      eraseProgress()
-      errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`)
+      eraseProgress();
+      errWrite(`\x1b[1;31m[err]\x1b[0m ${msg}\n`);
     },
     echo: (line) => {
-      writeDurable(() => outWrite(`${line}\n`))
+      writeDurable(() => outWrite(`${line}\n`));
     },
-    acquireTerminal
-  }
+    acquireTerminal,
+  };
 }

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

@@ -2,31 +2,32 @@
  * Model-catalog helpers: manifest listing plus Claude/Codex model validation.
  * Message strings are covered by the golden suites.
  */
-import type { Ctx } from "./index"
-import { isObject, parseJson, type Json } from "./jq"
-import { payloadDisplayPath, payloadText } from "../payload"
+import type { Ctx } from "./index";
+import { isObject, parseJson } from "./jq";
+import { payloadDisplayPath, payloadText } from "../payload";
+import type { JsonObject } from "./sharedTypes";
 
 export interface ModelEntry {
-  readonly id: string
-  readonly kind: "alias" | "id"
-  readonly note?: string
+  readonly id: string;
+  readonly kind: "alias" | "id";
+  readonly note?: string;
 }
 
 export interface ModelCatalog {
-  readonly verified: string
-  readonly models: ReadonlyArray<ModelEntry>
+  readonly verified: string;
+  readonly models: ReadonlyArray<ModelEntry>;
 }
 
-function toolEntry(tool: string): { [k: string]: Json } | undefined {
-  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
+function toolEntry(tool: string): JsonObject | undefined {
+  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;
 }
 
-function modelEntries(entry: { [k: string]: Json } | undefined): Array<{ [k: string]: Json }> {
-  const models = entry?.["models"]
-  return Array.isArray(models) ? models.filter(isObject) : []
+function modelEntries(entry: JsonObject | undefined): Array<JsonObject> {
+  const models = entry?.["models"];
+  return Array.isArray(models) ? models.filter(isObject) : [];
 }
 
 /**
@@ -35,53 +36,57 @@ function modelEntries(entry: { [k: string]: Json } | undefined): Array<{ [k: str
  * yields `verified: "?"` and no models.
  */
 export function modelCatalog(tool: string): ModelCatalog {
-  const entry = toolEntry(tool)
-  const verified = entry?.["verified"]
-  const models: Array<ModelEntry> = []
+  const entry = toolEntry(tool);
+  const verified = entry?.["verified"];
+  const models: Array<ModelEntry> = [];
   for (const m of modelEntries(entry)) {
-    const id = m["id"]
-    const kind = m["kind"]
-    if (typeof id !== "string" || (kind !== "alias" && kind !== "id")) continue
-    const note = m["note"]
-    models.push(typeof note === "string" ? { id, kind, note } : { id, kind })
+    const id = m["id"];
+    const kind = m["kind"];
+    if (typeof id !== "string" || (kind !== "alias" && kind !== "id")) continue;
+    const note = m["note"];
+    models.push(typeof note === "string" ? { id, kind, note } : { id, kind });
   }
-  return { verified: typeof verified === "string" ? verified : "?", models }
+  return { verified: typeof verified === "string" ? verified : "?", models };
 }
 
 export function printModels(ctx: Ctx, tool: string): void {
-  const { echo, warn } = ctx.services.logger
-  const entry = toolEntry(tool)
+  const { echo, warn } = ctx.services.logger;
+  const entry = toolEntry(tool);
   if (entry === undefined) {
-    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`)
-    return
+    warn(`Model catalog unavailable (${payloadDisplayPath("SoT/models.json")})`);
+    return;
   }
-  const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"
-  const lines = [`Available ${tool} models (kit-verified ${verified} — SoT/models.json):`]
+  const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?";
+  const lines = [`Available ${tool} models (kit-verified ${verified} — SoT/models.json):`];
   for (const m of modelEntries(entry)) {
-    const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : ""
-    lines.push(`  ${String(m["id"] ?? "")}${note}`)
+    const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : "";
+    lines.push(`  ${String(m["id"] ?? "")}${note}`);
   }
-  if (tool === "claude") lines.push("  (full claude-* model IDs outside the catalog are accepted with a warning)")
-  if (tool === "codex") lines.push("  (well-formed IDs outside the catalog are accepted with a warning)")
-  for (const line of lines) echo(line)
+  if (tool === "claude")
+    lines.push("  (full claude-* model IDs outside the catalog are accepted with a warning)");
+  if (tool === "codex")
+    lines.push("  (well-formed IDs outside the catalog are accepted with a warning)");
+  for (const line of lines) echo(line);
 }
 
 export function validateClaudeModel(ctx: Ctx, m: string): boolean {
-  if (m === "") return false
-  if (modelCatalog("claude").models.some((entry) => entry.id === m)) return true
+  if (m === "") return false;
+  if (modelCatalog("claude").models.some((entry) => entry.id === m)) return true;
   if (m.startsWith("claude-")) {
-    ctx.services.logger.warn(`Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`)
-    return true
+    ctx.services.logger.warn(
+      `Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`,
+    );
+    return true;
   }
-  return false
+  return false;
 }
 
 export function validateCodexModel(ctx: Ctx, m: string): boolean {
-  if (!/^[A-Za-z0-9._-]+$/.test(m)) return false
+  if (!/^[A-Za-z0-9._-]+$/.test(m)) return false;
   if (!modelCatalog("codex").models.some((entry) => entry.id === m)) {
     ctx.services.logger.warn(
-      `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`
-    )
+      `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`,
+    );
   }
-  return true
+  return true;
 }