docks-kit 0.18.1 → 0.19.1

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

@@ -14,6 +14,7 @@ import {
 
 import { payloadDisplayPath } from "../payload";
 import { PLUGIN_TABLE_HEADER } from "./codexConfig";
+import { isTomlHeaderLine } from "./codexToml";
 import { p, spawnProcess } from "./exec";
 import { recordFailure } from "./failures";
 import type { Ctx } from "./index";
@@ -107,20 +108,20 @@ function mergeMarketplace(repo: Json, user: Json): Json {
 // -------------------------------------------------------------- plugins ----
 
 /** codex::_marketplace_source — first `source =` inside [marketplaces.<name>]. */
-function marketplaceSource(marketplace: string, configFile: string): string {
+export function marketplaceSource(marketplace: string, configFile: string): string {
   if (!existsSync(configFile)) return "";
   let inMarketplace = false;
   for (const line of readFileSync(configFile, "utf8").split("\n")) {
-    if (line === `[marketplaces.${marketplace}]`) {
+    if (line.trim() === `[marketplaces.${marketplace}]`) {
       inMarketplace = true;
       continue;
     }
-    if (line.startsWith("[")) inMarketplace = false;
+    if (isTomlHeaderLine(line)) inMarketplace = false;
     if (inMarketplace && /^[ \t]*source[ \t]*=/.test(line)) {
       return line
         .replace(/^[^=]+=[ \t]*/, "")
         .replace(/[ \t]*#.*/, "")
-        .replace(/^"|"$/g, "");
+        .replace(/^(["'])(.*)\1$/, "$2");
     }
   }
   return "";
@@ -175,7 +176,7 @@ function enabledPluginIdsFromText(configText: string): Array<string> {
       enabled = false;
       continue;
     }
-    if (line.startsWith("[")) {
+    if (isTomlHeaderLine(line)) {
       flush();
       plugin = "";
       enabled = false;

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

@@ -12,15 +12,19 @@ import { resolveEffort } from "../efforts";
 import type { Ctx } from "./index";
 import type { SettingEdit } from "./sharedTypes";
 
+export function isTomlHeaderLine(line: string): boolean {
+  return /^[ \t]*\[/.test(line);
+}
+
 export function replaceTopLevelSetting(content: string, key: string, replacement: string): string {
   const lines = content.split("\n");
   if (lines[lines.length - 1] === "") lines.pop(); // awk records exclude a trailing empty split artifact
-  const keyRe = new RegExp(`^${key}[ \\t]*=`);
+  const keyRe = new RegExp(`^[ \\t]*${key}[ \\t]*=`);
   const out: Array<string> = [];
   let inTable = false;
   let replaced = false;
   for (const line of lines) {
-    if (line.startsWith("[")) {
+    if (isTomlHeaderLine(line)) {
       if (!replaced) {
         out.push(replacement);
         replaced = true;
@@ -113,11 +117,11 @@ export function syncCodexEffort(ctx: Ctx, effort: string): void {
 
 export function mergeTopLevelSettings(sotConfigText: string, userConfig: string): void {
   for (const line of sotConfigText.split("\n")) {
-    if (line.startsWith("[")) break;
+    if (isTomlHeaderLine(line)) break;
     if (/^[ \t]*($|#)/.test(line)) continue;
-    if (!/^[A-Za-z0-9_.-]+[ \t]*=/.test(line)) continue;
-    const key = line.slice(0, line.indexOf("=")).replace(/[ \t]+$/, "");
-    replaceTopLevelSettingInFile(userConfig, key, line);
+    const setting = /^[ \t]*([A-Za-z0-9_.-]+)[ \t]*=/.exec(line);
+    if (setting === null) continue;
+    replaceTopLevelSettingInFile(userConfig, setting[1]!, line);
   }
 }
 

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

@@ -1,13 +1,11 @@
 /**
- * Per-machine harness selection at ~/.docks-kit/state.json. The selection keeps
- * the omp harness opt-in. A missing or unreadable state file is represented by
- * undefined so callers resolve it to LEGACY_SELECTION and existing machines
- * keep today's behavior.
+ * Per-machine harness selection and omp session model, stored in ~/.docks-kit/kit.db (kitDb.ts).
+ * The selection keeps the omp harness opt-in. A missing or unreadable store is
+ * represented by undefined so callers resolve it to LEGACY_SELECTION.
  */
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 
-import { p } from "./exec";
+import { inTransaction, isNonBlankString, nonBlankOrNull, withKitDb } from "./kitDb";
 import type { OmpSessionModel } from "./sharedTypes";
 
 export type Harness = "claude" | "codex" | "agents" | "omp";
@@ -41,49 +39,21 @@ export function engineHome(env: NodeJS.ProcessEnv = process.env): string {
   return home !== undefined && home !== "" ? home : homedir();
 }
 
-export function harnessStateFile(home: string): string {
-  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;
+/** Read the stored selection; corruption, a too-new schema, or I/O errors yield undefined. */
+export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
   try {
-    parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown;
+    const selection = withKitDb(home, "read", (db) =>
+      normalizeHarnesses(
+        db
+          .prepare("SELECT harness FROM harness_selection")
+          .all()
+          .map((row) => row["harness"]),
+      ),
+    );
+    return selection !== undefined && selection.length > 0 ? selection : undefined;
   } catch {
     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;
-}
-
-// 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;
 }
 
 export function writeHarnessSelection(home: string, selection: ReadonlyArray<Harness>): void {
@@ -96,34 +66,37 @@ export function writeHarnessSelection(home: string, selection: ReadonlyArray<Har
     throw new Error("Harness selection must contain at least one known harness name");
   }
 
-  writeWholeState(home, { harnesses });
-}
-
-function isNonBlankString(value: unknown): value is string {
-  return typeof value === "string" && value.trim() !== "";
+  withKitDb(home, "write", (db) =>
+    inTransaction(db, () => {
+      db.exec("DELETE FROM harness_selection");
+      const insert = db.prepare("INSERT INTO harness_selection (harness) VALUES (?)");
+      for (const harness of harnesses) insert.run(harness);
+    }),
+  );
 }
 
-// Read the stored session model without throwing so a corrupt entry falls
+// Read the stored session model without throwing so a corrupt store 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"])) {
+  try {
+    return withKitDb(home, "read", (db) => {
+      const row = db
+        .prepare("SELECT selector, thinking, advisor_thinking FROM omp_session WHERE id = 1")
+        .get();
+      const selector = row?.["selector"];
+      if (!isNonBlankString(selector)) return undefined;
+      const thinking = row?.["thinking"];
+      const advisorThinking = row?.["advisor_thinking"];
+      const model: OmpSessionModel = {
+        selector,
+        ...(isNonBlankString(thinking) ? { thinking } : {}),
+        ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
+      };
+      return model;
+    });
+  } catch {
     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 thinking = record["thinking"];
-  const advisorThinking = record["advisorThinking"];
-  const model: OmpSessionModel = {
-    selector: record["selector"],
-    ...(isNonBlankString(thinking) ? { thinking } : {}),
-    ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
-  };
-  return model;
 }
 
 export function writeOmpSessionModel(home: string, model: OmpSessionModel): void {
@@ -132,15 +105,16 @@ export function writeOmpSessionModel(home: string, model: OmpSessionModel): void
   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 thinking = model.thinking;
-  const advisorThinking = model.advisorThinking;
-  const entry: OmpSessionModel = {
-    selector: model.selector,
-    ...(isNonBlankString(thinking) ? { thinking } : {}),
-    ...(isNonBlankString(advisorThinking) ? { advisorThinking } : {}),
-  };
-
-  writeWholeState(home, { ompSession: entry });
+  // Store blank or absent levels as NULL so a switch to a level-free model
+  // leaves no stale level behind.
+  const thinking = nonBlankOrNull(model.thinking);
+  const advisorThinking = nonBlankOrNull(model.advisorThinking);
+  withKitDb(home, "write", (db) =>
+    db
+      .prepare(
+        `INSERT INTO omp_session (id, selector, thinking, advisor_thinking) VALUES (1, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET selector = excluded.selector, thinking = excluded.thinking, advisor_thinking = excluded.advisor_thinking`,
+      )
+      .run(model.selector, thinking, advisorThinking),
+  );
 }

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

@@ -48,7 +48,7 @@ export async function runEngineNative(
     ctx = makeCtx(runServices);
     switch (argv[0]) {
       case "model":
-        return modeModel(ctx, argv.slice(1));
+        return await modeModel(ctx, argv.slice(1));
       case "toolchain":
         return await modeToolchain(ctx, argv.slice(1));
       case "sync":

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

@@ -0,0 +1,250 @@
+/**
+ * Per-machine kit store at ~/.docks-kit/kit.db. This module is the only code
+ * that opens the database: it applies the schema migrations, imports the
+ * legacy ~/.docks-kit/state.json once, and serves the network lookup cache.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+
+import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
+import { p } from "./exec";
+
+/**
+ * Append-only. Never edit or reorder a shipped entry. A release that changes the
+ * schema appends one SQL string. State tables (harness_selection, omp_session)
+ * get data-preserving migrations; cache_entry may be dropped and recreated
+ * because every row can be refetched.
+ */
+const MIGRATIONS: ReadonlyArray<string> = [
+  `CREATE TABLE harness_selection (
+  harness TEXT PRIMARY KEY CHECK (harness IN ('claude','codex','agents','omp'))
+) STRICT, WITHOUT ROWID;
+CREATE TABLE omp_session (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  selector TEXT NOT NULL CHECK (trim(selector) <> ''),
+  thinking TEXT CHECK (thinking IS NULL OR trim(thinking) <> ''),
+  advisor_thinking TEXT CHECK (advisor_thinking IS NULL OR trim(advisor_thinking) <> '')
+) STRICT;
+CREATE TABLE cache_entry (
+  key TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL,
+  fetched_at INTEGER NOT NULL,
+  payload TEXT NOT NULL
+) STRICT, WITHOUT ROWID;`,
+];
+
+export const KIT_DB_SCHEMA_VERSION: number = MIGRATIONS.length;
+
+export class KitDbTooNewError extends Error {}
+
+export function kitDbFile(home: string): string {
+  return p(home, ".docks-kit", "kit.db");
+}
+
+function userVersion(db: DatabaseSync): number {
+  const version = db.prepare("PRAGMA user_version").get()?.["user_version"];
+  return typeof version === "number" ? version : 0;
+}
+
+/** Run fn inside BEGIN IMMEDIATE; roll back and rethrow on any error. */
+export function inTransaction<T>(db: DatabaseSync, fn: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // SQLite already rolled back (for example on SQLITE_FULL); keep the original error.
+    }
+    throw error;
+  }
+}
+
+function tooNew(version: number): KitDbTooNewError {
+  return new KitDbTooNewError(
+    `~/.docks-kit/kit.db uses schema ${version}; this docks-kit knows schema ${KIT_DB_SCHEMA_VERSION}. Upgrade docks-kit (docks-kit update).`,
+  );
+}
+
+/** Returns true when this call applied migrations. */
+function migrate(db: DatabaseSync): boolean {
+  const current = userVersion(db);
+  if (current > KIT_DB_SCHEMA_VERSION) throw tooNew(current);
+  if (current === KIT_DB_SCHEMA_VERSION) return false;
+  return inTransaction(db, () => {
+    // Another process, possibly a newer kit, can migrate between the first
+    // read and the lock; never lower its version.
+    const locked = userVersion(db);
+    if (locked > KIT_DB_SCHEMA_VERSION) throw tooNew(locked);
+    if (locked === KIT_DB_SCHEMA_VERSION) return false;
+    for (const sql of MIGRATIONS.slice(locked)) db.exec(sql);
+    db.exec(`PRAGMA user_version = ${KIT_DB_SCHEMA_VERSION}`);
+    return true;
+  });
+}
+
+interface LegacyState {
+  readonly harnesses: ReadonlyArray<string>;
+  readonly session?: { selector: string; thinking: string | null; advisorThinking: string | null };
+}
+
+export function isNonBlankString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/** A blank or non-string value is stored as NULL. */
+export function nonBlankOrNull(value: unknown): string | null {
+  return isNonBlankString(value) ? value : null;
+}
+
+// Same validation the JSON store applied: root object, version 1, non-blank
+// selector and levels. Unknown or duplicate harness names are dropped by the
+// table's CHECK and PRIMARY KEY through INSERT OR IGNORE.
+function parseLegacyState(file: string): LegacyState | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  if (!("version" in parsed) || parsed.version !== 1) return undefined;
+
+  const rawHarnesses = "harnesses" in parsed ? parsed.harnesses : undefined;
+  const harnesses = Array.isArray(rawHarnesses)
+    ? rawHarnesses.filter((value): value is string => typeof value === "string")
+    : [];
+  const entry = "ompSession" in parsed ? parsed.ompSession : undefined;
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return { harnesses };
+  const selector = nonBlankOrNull("selector" in entry ? entry.selector : undefined);
+  if (selector === null) return { harnesses };
+  return {
+    harnesses,
+    session: {
+      selector,
+      thinking: nonBlankOrNull("thinking" in entry ? entry.thinking : undefined),
+      advisorThinking: nonBlankOrNull(
+        "advisorThinking" in entry ? entry.advisorThinking : undefined,
+      ),
+    },
+  };
+}
+
+function importLegacyState(db: DatabaseSync, legacy: string): void {
+  inTransaction(db, () => {
+    const rows = db
+      .prepare(
+        "SELECT (SELECT count(*) FROM harness_selection) + (SELECT count(*) FROM omp_session) AS n",
+      )
+      .get()?.["n"];
+    if (rows !== 0) return;
+    const state = parseLegacyState(legacy);
+    if (state === undefined) return;
+    const insertHarness = db.prepare(
+      "INSERT OR IGNORE INTO harness_selection (harness) VALUES (?)",
+    );
+    for (const harness of state.harnesses) insertHarness.run(harness);
+    if (state.session !== undefined) {
+      db.prepare(
+        "INSERT INTO omp_session (id, selector, thinking, advisor_thinking) VALUES (1, ?, ?, ?)",
+      ).run(state.session.selector, state.session.thinking, state.session.advisorThinking);
+    }
+  });
+  // An invalid file is renamed too, so no later run parses it again.
+  try {
+    renameSync(legacy, `${legacy}.migrated`);
+  } catch (error) {
+    // A parallel process renamed it first.
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : "";
+    if (code !== "ENOENT") throw error;
+  }
+}
+
+/**
+ * Open kit.db, migrate it, import the legacy state file once, and run fn.
+ * A read with neither kit.db nor state.json present creates nothing and
+ * returns undefined.
+ */
+export function withKitDb<T>(
+  home: string,
+  access: "read" | "write",
+  fn: (db: DatabaseSync) => T,
+): T | undefined {
+  const file = kitDbFile(home);
+  const legacy = p(home, ".docks-kit", "state.json");
+  if (access === "read" && !existsSync(file) && !existsSync(legacy)) return undefined;
+
+  const directory = p(home, ".docks-kit");
+  // `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);
+
+  const db = new DatabaseSync(file);
+  try {
+    // SQLite gives the -wal and -shm files the mode of the main file.
+    if (process.platform !== "win32") chmodSync(file, 0o600);
+    // busy_timeout first: the switch to WAL needs a lock.
+    db.exec(
+      "PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA foreign_keys = ON;",
+    );
+    const migrated = migrate(db);
+    const importing = existsSync(legacy);
+    if (importing) importLegacyState(db, legacy);
+    const result = fn(db);
+    // Fold the WAL into kit.db so a copy of kit.db alone holds every row.
+    // Reads can migrate or import too, so they checkpoint after writing.
+    if (access === "write" || migrated || importing) {
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    return result;
+  } finally {
+    db.close();
+  }
+}
+
+// A new kit release refetches every cached row.
+const CACHE_FINGERPRINT = GENERATED_PACKAGE_VERSION;
+
+/** Return a fresh cached payload; every failure is a miss. */
+export function readCache(
+  home: string,
+  key: string,
+  maxAgeMs: number,
+  now: number,
+): string | undefined {
+  try {
+    return withKitDb(home, "read", (db) => {
+      const row = db
+        .prepare("SELECT fingerprint, fetched_at, payload FROM cache_entry WHERE key = ?")
+        .get(key);
+      const fetchedAt = row?.["fetched_at"];
+      const payload = row?.["payload"];
+      if (row?.["fingerprint"] !== CACHE_FINGERPRINT) return undefined;
+      if (typeof fetchedAt !== "number" || typeof payload !== "string") return undefined;
+      return now - fetchedAt <= maxAgeMs ? payload : undefined;
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/** Store a successful lookup; a failed write does nothing. */
+export function writeCache(home: string, key: string, payload: string, now: number): void {
+  try {
+    withKitDb(home, "write", (db) =>
+      inTransaction(db, () => {
+        db.prepare("DELETE FROM cache_entry WHERE fingerprint <> ?").run(CACHE_FINGERPRINT);
+        db.prepare(
+          `INSERT INTO cache_entry (key, fingerprint, fetched_at, payload) VALUES (?, ?, ?, ?)
+ON CONFLICT(key) DO UPDATE SET fingerprint = excluded.fingerprint, fetched_at = excluded.fetched_at, payload = excluded.payload`,
+        ).run(key, CACHE_FINGERPRINT, now, payload);
+      }),
+    );
+  } catch {
+    // The cache is an optimization; the next run fetches again.
+  }
+}