docks-kit 0.16.8 → 0.16.10

package/AGENTS.md

@@ -78,6 +78,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
 ## Engineering rules
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
+- **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `index.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, a missing `SoT/toolchain.json` pin, and an unavailable plugin inventory stay warn-only with exit 0, and `ompSync.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
 - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.11` (inside the `@effect/vitest` peer range `>=4.1.0 <5.0.0`; 4.1.11 fixes GHSA-82fw-gwwq-j7x9). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.

package/cli/docs/plugins.md

@@ -21,6 +21,17 @@ is absent from user settings.
 5. Re-assert SoT enabled-state (undoes install's enable side effect on
    false-keyed plugins)
 
+## Failed operations fail the sync
+
+A marketplace or plugin command that exits non-zero is warned in place AND
+recorded, then listed under a `--- Failures ---` block after the summary; the
+sync exits 1. A stale plugin therefore no longer looks like a clean sync.
+
+Not a failure: a missing harness CLI, missing git, a missing
+`SoT/toolchain.json` pin, and an unavailable plugin inventory. Those stay
+warn-and-skip with exit 0, so a host without Claude, Codex, or omp installed
+still syncs its deployed config cleanly.
+
 ## Optional opt-ins
 
 Situational plugins are kept OUT of the SoT and opted in per machine:

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

@@ -5,14 +5,25 @@
  */
 import { existsSync, renameSync, writeFileSync } from "node:fs"
 import { p, spawnProcess } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, readJsonFile, type Json } from "./jq"
 import { field } from "./toolchain"
 import { payloadText } from "../payload"
 
-async function cli(args: Array<string>): Promise<{ ok: boolean; out: string }> {
+async function cli(args: Array<string>): Promise<{ ok: boolean; out: string; detail: string }> {
   const res = await spawnProcess("claude", args, { stdio: ["ignore", "pipe", "pipe"] })
-  return { ok: res.error === undefined && res.exitCode === 0, out: `${res.stdout}${res.stderr}` }
+  // A spawn error carries its cause in `error`, not in either stream, and that
+  // is the case a failure message cannot afford to drop: it names an
+  // unresolvable launcher instead of a rejected command.
+  const out = res.error !== undefined ? res.error.message : `${res.stdout}${res.stderr}`
+  const detail = out.split("\n").map((line) => line.trim()).find((line) => line !== "") ?? "unknown error"
+  return { ok: res.error === undefined && res.exitCode === 0, out, detail }
+}
+
+/** Failure message tail: the cause, then the command to re-run by hand. */
+function manually(detail: string, args: Array<string>): string {
+  return `${detail}; run manually: claude ${args.join(" ")}`
 }
 
 function sortedKeys(obj: Json | undefined): Array<string> {
@@ -95,7 +106,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (marketplaceResult.ok) {
       addedMp++
     } else {
-      warn(`Failed to add marketplace: ${mpName} (${repo})`)
+      recordFailure(
+        ctx,
+        `Failed to add marketplace: ${mpName} (${repo}): ${manually(marketplaceResult.detail, ["plugin", "marketplace", "add", repo])}`
+      )
       f1++
     }
   }
@@ -104,6 +118,8 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   // refreshing each source marketplace once so the install resolves a current snapshot.
   let addedPl = 0
   let f2 = 0
+  let f3 = 0
+  let f4 = 0
   const refreshedMarketplaces = new Set<string>()
   for (const pluginId of sortedKeys(sotPlugins)) {
     if (pluginUserScopeInstalled(installedPlugins, pluginId)) continue
@@ -111,8 +127,15 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     const mpName = separator > 0 ? pluginId.slice(separator + 1) : ""
     if (mpName !== "" && !refreshedMarketplaces.has(mpName)) {
       progress(`Refreshing marketplace ${mpName}...`)
-      await cli(["plugin", "marketplace", "update", mpName])
+      const refreshResult = await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
+      if (!refreshResult.ok) {
+        recordFailure(
+          ctx,
+          `Failed to refresh marketplace: ${mpName}: ${manually(refreshResult.detail, ["plugin", "marketplace", "update", mpName])}`
+        )
+        f3++
+      }
       refreshedMarketplaces.add(mpName)
     }
     progress(`Installing plugin ${pluginId}...`)
@@ -121,7 +144,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     if (installResult.ok) {
       addedPl++
     } else {
-      warn(`Failed to install plugin: ${pluginId}`)
+      recordFailure(
+        ctx,
+        `Failed to install plugin: ${pluginId}: ${manually(installResult.detail, ["plugin", "install", pluginId])}`
+      )
       f2++
     }
   }
@@ -143,12 +169,24 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
   }
 
   // Pass 3 — refresh the kit-owned marketplaces unless the update command
-  // selected its install-missing-only fast path.
+  // selected its install-missing-only fast path. Pass 2 already refreshed the
+  // source marketplace of every plugin it installed, so skip those: a second
+  // fetch seconds later cannot resolve a newer snapshot, and re-running it
+  // 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
       progress(`Refreshing marketplace ${mpName}...`)
-      await cli(["plugin", "marketplace", "update", mpName])
+      const refreshResult = await cli(["plugin", "marketplace", "update", mpName])
       clearProgress()
+      refreshedMarketplaces.add(mpName)
+      if (!refreshResult.ok) {
+        recordFailure(
+          ctx,
+          `Failed to refresh marketplace: ${mpName}: ${manually(refreshResult.detail, ["plugin", "marketplace", "update", mpName])}`
+        )
+        f3++
+      }
     }
     // Pass 4 — update the kit-owned installed plugins.
     for (const pluginId of [...kitPluginIds].sort(compareCodepoints)) {
@@ -156,7 +194,15 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       progress(`Updating plugin ${pluginId}...`)
       const updateResult = await cli(["plugin", "update", pluginId, "--scope", "user"])
       clearProgress()
-      if (updateResult.out.includes("Successfully updated")) updatedPl++
+      if (!updateResult.ok) {
+        recordFailure(
+          ctx,
+          `Failed to update plugin: ${pluginId}: ${manually(updateResult.detail, ["plugin", "update", pluginId, "--scope", "user"])}`
+        )
+        f4++
+      } else if (updateResult.out.includes("Successfully updated")) {
+        updatedPl++
+      }
     }
   }
 
@@ -175,7 +221,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (uninstallResult.ok) {
         removedPl++
       } else {
-        warn(`Failed to uninstall plugin: ${pluginId}`)
+        recordFailure(
+          ctx,
+          `Failed to uninstall plugin: ${pluginId}: ${manually(uninstallResult.detail, ["plugin", "uninstall", "-y", "--scope", "user", pluginId])}`
+        )
         f5++
       }
     }
@@ -191,7 +240,10 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
       if (removeResult.ok) {
         removedMp++
       } else {
-        warn(`Failed to remove marketplace: ${mpName}`)
+        recordFailure(
+          ctx,
+          `Failed to remove marketplace: ${mpName}: ${manually(removeResult.detail, ["plugin", "marketplace", "remove", mpName])}`
+        )
         f6++
       }
     }
@@ -203,7 +255,7 @@ export async function syncPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
     ctx.nextStepTriggers.claudePlugins = true
   }
 
-  const failed = f1 + f2 + f5 + f6
+  const failed = f1 + f2 + f3 + f4 + f5 + f6
   if (addedMp > 0 || addedPl > 0 || updatedPl > 0 || removedPl > 0 || removedMp > 0) {
     change(`Plugins synced (marketplaces: +${addedMp} -${removedMp}, plugins: +${addedPl} ~${updatedPl} -${removedPl})`)
     ctx.nextStepTriggers.claudePlugins = true
@@ -226,10 +278,14 @@ async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, us
     const user = readJsonFile(userSettingsFile)
     const enabled = user !== undefined && isObject(user) && isObject(user["enabledPlugins"]) ? (user["enabledPlugins"] as { [k: string]: Json })[pluginId] : undefined
     if (enabled !== true) continue
-    if ((await cli(["plugin", "disable", pluginId])).ok) {
+    const disableResult = await cli(["plugin", "disable", pluginId])
+    if (disableResult.ok) {
       cliDisabled = true
     } else {
-      warn(`Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
+      recordFailure(
+        ctx,
+        `Failed to disable SoT-false plugin: ${pluginId} (will retry next sync): ${manually(disableResult.detail, ["plugin", "disable", pluginId])}`
+      )
     }
   }
 
@@ -250,7 +306,7 @@ async function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, us
 // ------------------------------------------------------ optional plugins ----
 
 async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): Promise<boolean> {
-  const { change, clearProgress, progress, verbose, warn } = ctx.services.logger
+  const { change, clearProgress, progress, verbose } = ctx.services.logger
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
   const mpName = pluginId.slice(pluginId.lastIndexOf("@") + 1)
@@ -261,7 +317,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
     const has = known !== undefined && isObject(known) && known[mpName] !== undefined && known[mpName] !== null && known[mpName] !== false
     if (!has) {
       if (!(await cli(["plugin", "marketplace", "add", marketplaceRepo])).ok) {
-        warn(`Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
+        recordFailure(ctx, `Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
         return false
       }
       marketplaceAdded = true
@@ -275,7 +331,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
     clearProgress()
     if (!installResult.ok) {
       if (marketplaceAdded) change(`Optional plugin ${pluginId}: marketplace added (install failed — will retry next sync)`)
-      warn(`Failed to install optional plugin ${pluginId}`)
+      recordFailure(ctx, `Failed to install optional plugin ${pluginId}`)
       return marketplaceAdded
     }
   }
@@ -288,7 +344,7 @@ async function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: strin
 
   if (!(await cli(["plugin", "enable", pluginId])).ok) {
     if (marketplaceAdded || !wasInstalled) change(`Optional plugin ${pluginId}: installed (enable failed — will retry next sync)`)
-    warn(`Failed to enable optional plugin ${pluginId}`)
+    recordFailure(ctx, `Failed to enable optional plugin ${pluginId}`)
     return marketplaceAdded || !wasInstalled
   }
   const changed = marketplaceAdded || !wasInstalled || !wasEnabled

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

@@ -7,6 +7,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync,
 
 import { mergeTableSettings, mergeTopLevelSettings, syncCodexEffort, syncCodexModel } from "./codexToml"
 import { p, spawnProcess } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { hostOs } from "./os"
@@ -466,7 +467,7 @@ function marketplaceSource(marketplace: string, configFile: string): string {
 }
 
 async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promise<void> {
-  const { change, echo, warn } = ctx.services.logger
+  const { change, echo } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] remove legacy configured Codex Docks marketplace when personal marketplace is deployed")
     return
@@ -481,7 +482,7 @@ async function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): Promi
     change("Removed legacy configured Codex Docks marketplace; using personal marketplace file")
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    warn("Failed to remove legacy configured Codex Docks marketplace")
+    recordFailure(ctx, "Failed to remove legacy configured Codex Docks marketplace")
   }
 }
 
@@ -592,13 +593,15 @@ async function syncPlugins(ctx: Ctx, sotConfigText: string): Promise<void> {
     if (res.error === undefined && res.exitCode === 0) {
       refreshed++
     } else if (addOut.includes("could not find a Codex CLI binary")) {
-      warn(
+      recordFailure(
+        ctx,
         `Codex plugin refresh hit a stale launcher/wrapper on PATH - install current standalone Codex with: ${standaloneInstallCommand(ctx)}`
       )
       failed++
     } else {
       const failureLine = addOut.split("\n")[0] ?? ""
-      warn(
+      recordFailure(
+        ctx,
         `Codex plugin refresh failed for ${pluginId}: ${failureLine !== "" ? failureLine : "unknown error"}; run manually: codex plugin add ${pluginId}`
       )
       failed++

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

@@ -0,0 +1,16 @@
+/**
+ * Failure ledger for harness-CLI operations. A kit-managed marketplace or
+ * 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"
+
+/**
+ * Record a failed harness-CLI operation. The warning still prints immediately so
+ * position in the output is preserved; the recorded message also lets engineSync
+ * 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)
+}

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

@@ -117,6 +117,8 @@ export interface Ctx {
     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. */
@@ -170,7 +172,8 @@ function makeCtx(services: EngineServices): Ctx {
       codexRestart: false,
       skillsRestart: false,
       ompRestart: false
-    }
+    },
+    failures: []
   }
 }
 
@@ -291,6 +294,12 @@ async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number
     echo("")
     for (const line of advice) echo(line)
   }
+  if (ctx.failures.length > 0) {
+    echo("")
+    echo("--- Failures ---")
+    for (const failure of ctx.failures) echo(`- ${failure}`)
+    return 1
+  }
   return 0
 }
 

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

@@ -1,7 +1,8 @@
 /**
- * EngineNative `sync omp` pipeline. config.yml and models.yml merge through
- * mergeOmpConfig to preserve user-only keys. Paths come from ompPaths because
- * profiles, PI_CONFIG_DIR, PI_CODING_AGENT_DIR, and XDG roots each move them.
+ * EngineNative `sync omp` pipeline. config.yml merges through mergeOmpConfig
+ * and models.yml through mergeOmpModels. Both preserve user-only keys.
+ * Paths come from ompPaths because profiles, PI_CONFIG_DIR,
+ * PI_CODING_AGENT_DIR, and XDG roots each move them.
  * Resolution stays within the environment and filesystem probes so no omp
  * subcommand runs under ctx.dryRun.
  */
@@ -11,6 +12,7 @@ import { basename, isAbsolute, resolve } from "node:path"
 import { payloadDisplayPath, payloadText, type PayloadPath } from "../payload"
 import { bunBootstrap } from "./bun"
 import { p, spawnProcess, type AsyncProcessResult } from "./exec"
+import { recordFailure } from "./failures"
 import type { Ctx } from "./index"
 import { isObject, parseJson } from "./jq"
 import { ompPaths } from "./ompPaths"
@@ -190,7 +192,7 @@ function firstOutputLine(result: AsyncProcessResult): string {
  * adoption and leaves the active registry present.
  */
 async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFile?: string): Promise<void> {
-  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger
+  const { change, clearProgress, echo, progress, verbose } = ctx.services.logger
   const registered = registryHasDocks(registryFile)
   const adoptable = !registered && legacyRegistryFile !== undefined && registryHasDocks(legacyRegistryFile)
 
@@ -206,6 +208,13 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     return
   }
 
+  // syncPlugins owns the single skip message for both missing CLIs, and it runs
+  // right after this pass. Without omp no marketplace command can run at all,
+  // and without git a marketplace clone cannot resolve, so both are deliberate
+  // skips: return silently instead of spawning and recording a failure.
+  if (ctx.services.deps.probe("omp").state === "missing") return
+  if (ctx.services.deps.probe("git").state === "missing") return
+
   if (!registered && !adoptable) {
     progress("Registering omp docks marketplace...")
     const result = await spawnProcess("omp", ["plugin", "marketplace", "add", MARKETPLACE_SOURCE], {
@@ -215,7 +224,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     if (result.error === undefined && result.exitCode === 0) {
       change("omp docks marketplace registered")
     } else {
-      warn(
+      recordFailure(
+        ctx,
         `omp docks marketplace registration failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace add ${MARKETPLACE_SOURCE}`
       )
     }
@@ -239,7 +249,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
     if (listed.error === undefined && listed.exitCode === 0) {
       change("omp docks marketplace registry adopted; refresh-only update skipped")
     } else {
-      warn(
+      recordFailure(
+        ctx,
         `omp docks marketplace adoption failed: ${firstOutputLine(listed)}; run manually: omp plugin marketplace list`
       )
     }
@@ -254,7 +265,8 @@ async function syncMarketplace(ctx: Ctx, registryFile: string, legacyRegistryFil
   if (result.error === undefined && result.exitCode === 0) {
     verbose("omp docks marketplace refreshed")
   } else {
-    warn(
+    recordFailure(
+      ctx,
       `omp docks marketplace update failed: ${firstOutputLine(result)}; run manually: omp plugin marketplace update ${MARKETPLACE_NAME}`
     )
   }
@@ -308,13 +320,14 @@ async function runPluginCommand(
   plugin: string,
   args: ReadonlyArray<string>
 ): Promise<boolean> {
-  const { clearProgress, progress, warn } = ctx.services.logger
+  const { clearProgress, progress } = ctx.services.logger
   progress(`Updating omp plugin ${plugin}...`)
   const result = await spawnProcess("omp", args, { stdio: ["ignore", "pipe", "pipe"] })
   clearProgress()
   if (result.error === undefined && result.exitCode === 0) return true
 
-  warn(
+  recordFailure(
+    ctx,
     `omp plugin operation failed for ${plugin}: ${firstOutputLine(result)}; run manually: omp ${args.join(" ")}`
   )
   return false

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.16.8"
+export const GENERATED_PACKAGE_VERSION = "0.16.10"
 
 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/package.json

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