docks-kit 0.19.0 → 0.19.1

package/README.md

@@ -53,7 +53,7 @@ docks-kit toolchain [check|ensure <tool>|outdated]  verified-version floors for
 docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed
 docks-kit skills list [--json]                  universal skills vs manifest
-docks-kit docs [topic]                          self-documentation (10 topics)
+docks-kit docs [topic]                          self-documentation (11 topics)
 --help --version --wizard --completions    built-in
 ```
 
@@ -100,7 +100,8 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
   the full doctor table. Bun is the one managed install and is pinned to its
   verified version.
 - **Model catalog** — enabled harnesses provide live Claude, Codex, or omp
-  model IDs; `SoT/models.json` supplies aliases, notes, and the offline fallback.
+  model IDs; `SoT/models.json` supplies Claude and Codex aliases, notes, and the
+  offline fallback. omp has no curated fallback list.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
   programs for statusline, SessionStart, and Notification. Quota display uses
   Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,

package/cli/docs/overview.md

@@ -13,7 +13,7 @@ AI-assisted dev environment on every machine.
 | `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom |
-| `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
+| `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
 | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain and the `docks-kit omp` session overlay |

package/cli/src/commands/docs.ts

@@ -24,8 +24,14 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
     summary: "Deploy-time modifiers and the flag-less-sync-reverts contract",
     body: modifiers,
   },
-  models: { summary: "Model catalog, validation rules, model get/set", body: models },
-  toolchain: { summary: "Verified-version floors and the doctor table", body: toolchain },
+  models: {
+    summary: "Live model lists, the curated overlay, validation, model get/set",
+    body: models,
+  },
+  toolchain: {
+    summary: "Verified-version floors, the doctor table, and the upstream outdated report",
+    body: toolchain,
+  },
   plugins: { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
   install: {
     summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers",

package/cli/src/commands/toolchain.ts

@@ -29,10 +29,12 @@ export const toolchainCommand = Command.make(
     Effect.gen(function* () {
       const operation = Option.getOrElse(config.op, () => "check");
       const flags = config.verbose ? ["--verbose"] : [];
+      const operand = Option.getOrUndefined(config.tool);
+      const words = operand === undefined ? [] : [operand];
 
       switch (operation) {
         case "check":
-          return yield* engine(["toolchain", "check", ...(config.verbose ? ["--verbose"] : [])]);
+          return yield* engine(["toolchain", "check", ...words, ...flags]);
         case "ensure": {
           const t = Option.getOrUndefined(config.tool);
           if (t === undefined || !MANAGED.includes(t)) {
@@ -41,7 +43,12 @@ export const toolchainCommand = Command.make(
           return yield* engine(["toolchain", "ensure", t, ...flags]);
         }
         case "outdated":
-          return yield* engine(["toolchain", "outdated", ...(config.refresh ? ["--refresh"] : [])]);
+          return yield* engine([
+            "toolchain",
+            "outdated",
+            ...words,
+            ...(config.refresh ? ["--refresh"] : []),
+          ]);
         default:
           return yield* bail(
             `Unknown toolchain op '${operation}' (valid: check, ensure, outdated)`,

package/cli/src/commands/update.ts

@@ -60,9 +60,8 @@ const capturePackageRoot: CapturePackageRoot = (command, args) => {
 
 /**
  * A Bun global home is `<root>/.bun/install/global/node_modules/<pkg>`. Windows
- * reports that path with backslashes, so containment is tested on a normalized
- * copy — but only on Windows, because a backslash is a legal POSIX filename
- * character and must never be read as a separator there.
+ * reports that path with backslashes and compares it without case sensitivity.
+ * On POSIX, a backslash remains a legal filename character, not a separator.
  */
 export const packageManagerForHome = (
   home: string,
@@ -70,13 +69,14 @@ export const packageManagerForHome = (
   host: HostOs = hostOs(),
 ): PackageManager => {
   const normalize = (value: string): string =>
-    host.id === "windows" ? value.replaceAll("\\", "/") : value;
+    host.id === "windows" ? value.replaceAll("\\", "/").toLowerCase() : value;
   const normalizedHome = normalize(home);
   const underEnvironmentRoot = (name: "BUN_INSTALL_GLOBAL_DIR" | "BUN_INSTALL"): boolean => {
     const root = environment[name]?.trim();
     if (root === undefined || root === "") return false;
-    const normalizedRoot = normalize(root);
-    return normalizedHome === normalizedRoot || normalizedHome.startsWith(`${normalizedRoot}/`);
+    const normalizedRoot = normalize(root).replace(/\/+$/, "") || "/";
+    const prefix = normalizedRoot.endsWith("/") ? normalizedRoot : `${normalizedRoot}/`;
+    return normalizedHome === normalizedRoot || normalizedHome.startsWith(prefix);
   };
   return normalizedHome.includes("/.bun/") ||
     underEnvironmentRoot("BUN_INSTALL_GLOBAL_DIR") ||

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

@@ -19,6 +19,9 @@ import {
 import { payloadText } from "../payload";
 import type { JsonObject } from "./sharedTypes";
 
+/** Claude Code's built-in marketplace: always present, never added or pruned by the kit. */
+const OFFICIAL_MARKETPLACE = "claude-plugins-official";
+
 export async function cli(
   args: Array<string>,
 ): Promise<{ ok: boolean; out: string; detail: string }> {
@@ -113,20 +116,31 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     ? repoObj["extraKnownMarketplaces"]
     : {};
   const sotPlugins = isObject(repoObj["enabledPlugins"]) ? repoObj["enabledPlugins"] : {};
-
-  // Pass 1 — add missing marketplaces (SoT insertion order, like to_entries).
-  let addedMp = 0;
-  let f1 = 0;
-  for (const [mpName, mpValue] of Object.entries(sotMarketplaces)) {
+  const knownMarketplace = (mpName: string): boolean => {
     const known = readJsonFile(knownMarketplaces);
-    if (
+    return (
       known !== undefined &&
       isObject(known) &&
       known[mpName] !== undefined &&
       known[mpName] !== null &&
       known[mpName] !== false
-    )
-      continue;
+    );
+  };
+  const addedMarketplaces = new Set<string>();
+  // The official marketplace is built in; a successful add is usable before its inventory is written.
+  // A missing inventory proves absence (fresh home); an unreadable one does not, so refresh as before.
+  const marketplaceReady = (mpName: string): boolean => {
+    if (mpName === OFFICIAL_MARKETPLACE || addedMarketplaces.has(mpName)) return true;
+    if (!existsSync(knownMarketplaces)) return false;
+    const known = readJsonFile(knownMarketplaces);
+    return known === undefined || !isObject(known) || knownMarketplace(mpName);
+  };
+
+  // Pass 1 — add missing marketplaces (SoT insertion order, like to_entries).
+  let addedMp = 0;
+  let f1 = 0;
+  for (const [mpName, mpValue] of Object.entries(sotMarketplaces)) {
+    if (knownMarketplace(mpName)) continue;
     const repo =
       isObject(mpValue) && isObject(mpValue["source"])
         ? String((mpValue["source"] as JsonObject)["repo"] ?? "")
@@ -136,6 +150,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     clearProgress();
     if (marketplaceResult.ok) {
       addedMp++;
+      addedMarketplaces.add(mpName);
     } else {
       recordFailure(
         ctx,
@@ -156,7 +171,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (pluginUserScopeInstalled(installedPlugins, pluginId)) continue;
     const separator = pluginId.lastIndexOf("@");
     const mpName = separator > 0 ? pluginId.slice(separator + 1) : "";
-    if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
+    if (mpName !== "" && marketplaceReady(mpName) && !refreshedMarketplaces.has(mpName)) {
       progress(`Refreshing marketplace ${mpName}...`);
       const refreshResult = await cli(["plugin", "marketplace", "update", mpName]);
       clearProgress();
@@ -207,7 +222,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   // would duplicate one failure in the ledger and in the failed-operation count.
   if (!ctx.skipPluginRefresh) {
     for (const mpName of [...kitMarketplaces].sort(compareCodepoints)) {
-      if (refreshedMarketplaces.has(mpName)) continue;
+      if (refreshedMarketplaces.has(mpName) || !marketplaceReady(mpName)) continue;
       progress(`Refreshing marketplace ${mpName}...`);
       const refreshResult = await cli(["plugin", "marketplace", "update", mpName]);
       clearProgress();
@@ -263,7 +278,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     // Pass 6 — prune-gated marketplace removal.
     const known = readJsonFile(knownMarketplaces);
     for (const mpName of sortedKeys(known)) {
-      if (mpName === "claude-plugins-official") continue;
+      if (mpName === OFFICIAL_MARKETPLACE) continue;
       if (nonUserMarketplaces.has(mpName)) continue;
       if (kitMarketplaces.has(mpName)) continue;
       progress(`Removing marketplace ${mpName}...`);

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

@@ -7,7 +7,7 @@
 import { copyFileSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 
 import { payloadDisplayPath } from "../payload";
-import { mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
+import { isTomlHeaderLine, mergeTableSettings, mergeTopLevelSettings } from "./codexToml";
 import type { Ctx } from "./index";
 
 // --------------------------------------------------------------- config ----
@@ -68,14 +68,14 @@ function scrubDeprecatedFeaturesText(content: string): string {
   let changed = false;
   for (const line of lines) {
     if (inFeatures) {
-      if (line.startsWith("[")) {
+      if (isTomlHeaderLine(line)) {
         inFeatures = false;
         if (keep) out += `${header}\n${body}`;
         else changed = true;
         out += `${line}\n`;
         continue;
       }
-      if (/^use_legacy_landlock[ \t]*=/.test(line)) {
+      if (/^[ \t]*use_legacy_landlock[ \t]*=/.test(line)) {
         changed = true;
         continue;
       }
@@ -83,7 +83,7 @@ function scrubDeprecatedFeaturesText(content: string): string {
       if (/[^ \t\f\v\r]/.test(line)) keep = true;
       continue;
     }
-    if (/^\[features\][ \t]*$/.test(line)) {
+    if (/^[ \t]*\[features\][ \t]*$/.test(line)) {
       inFeatures = true;
       header = line;
       body = "";
@@ -111,7 +111,7 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
   change("Codex: scrubbed deprecated [features].use_legacy_landlock");
 }
 
-export const PLUGIN_TABLE_HEADER = /^\[plugins\."([^"]+)"\][ \t]*$/;
+export const PLUGIN_TABLE_HEADER = /^[ \t]*\[plugins\."([^"]+)"\][ \t]*$/;
 /** Plugin ids the kit retired; their deployed tables are stripped on every sync. */
 const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = {
   "effect-kit@docks": true,
@@ -130,7 +130,7 @@ export function removeRetiredPluginTablesText(content: string): string {
       skipping = RETIRED_PLUGIN_IDS[header[1]!] === true;
       if (skipping) continue;
     } else if (skipping) {
-      if (!line.startsWith("[")) continue;
+      if (!isTomlHeaderLine(line)) continue;
       skipping = false;
     }
     out += `${line}\n`;

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/modes.ts

@@ -14,6 +14,7 @@ import { printModels, validateClaudeModel, validateCodexModel } from "./models";
 import { defaultLiveInputs, resolveCatalog } from "./liveModels";
 import { bunBootstrap } from "./bun";
 import { installedVersion, outdatedReport, present, report } from "./toolchain";
+import { topLevelTomlString } from "../manifests";
 
 export async function modeModel(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { echo, err, warn } = ctx.services.logger;
@@ -59,8 +60,8 @@ export async function modeModel(ctx: Ctx, args: ReadonlyArray<string>): Promise<
         err(`Failed to read ~/.codex/config.toml: ${String(result.error)}`);
         return 1;
       }
-      echo(`deployed: ${tomlModelText(result.data)}`);
-      echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`);
+      echo(`deployed: ${topLevelTomlString(result.data, "model") ?? ""}`);
+      echo(`SoT:      ${topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model") ?? ""}`);
     }
     printModels(ctx, catalog);
     return 0;
@@ -112,15 +113,6 @@ function jsonModelText(text: string): string {
   return typeof v === "string" ? v : JSON.stringify(v);
 }
 
-/** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
-
-function tomlModelText(text: string): string {
-  for (const line of text.split("\n")) {
-    if (/^model[ \t]*=/.test(line)) return line.split('"')[1] ?? "";
-  }
-  return "";
-}
-
 export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
   const { echo, err, verbose } = ctx.services.logger;
   const words = args.filter((arg) => !arg.startsWith("--"));
@@ -129,6 +121,10 @@ export async function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): Prom
   for (const arg of args) {
     if (arg === "--verbose") ctx.verbose = true;
   }
+  if (words.length > (op === "ensure" ? 2 : 1)) {
+    err("Usage: toolchain [check|ensure <tool>|outdated [--refresh]]");
+    return 2;
+  }
 
   if (op === "check") {
     await report(ctx);

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.19.0"
+export const GENERATED_PACKAGE_VERSION = "0.19.1"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/cli/src/main.ts

@@ -32,8 +32,8 @@ const root = Command.make("docks-kit", {}, () =>
       "  docks-kit update [--no-sync]              self-update the kit, then sync",
     );
     yield* Console.log("  docks-kit model <claude|codex> [value]     get/set the deployed model");
-    yield* Console.log("  docks-kit models [tool]                    kit-verified model catalog");
-    yield* Console.log("  docks-kit toolchain [check|ensure <tool>]  verified-version floors");
+    yield* Console.log("  docks-kit models [tool] [--refresh]        live model lists per harness");
+    yield* Console.log("  docks-kit toolchain [check|ensure|outdated] verified-version floors");
     yield* Console.log("  docks-kit status                           deployed-vs-SoT doctor view");
     yield* Console.log("  docks-kit plugins list                     plugin tri-state");
     yield* Console.log("  docks-kit skills list                      universal skills");

package/cli/src/manifests.ts

@@ -23,8 +23,8 @@ export const deployedClaudeSettings = (): any | undefined => {
 export function topLevelTomlString(text: string, setting: string): string | undefined {
   for (const line of text.split(/\r?\n/)) {
     if (/^\s*\[/.test(line)) return undefined;
-    const assignment = line.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*"([^"]+)"/);
-    if (assignment?.[1] === setting) return assignment[2];
+    const assignment = line.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*(?:"([^"]+)"|'([^']*)')/);
+    if (assignment?.[1] === setting) return assignment[2] ?? assignment[3];
   }
   return undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",