docks-kit 0.1.5 → 0.2.0

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

@@ -4,13 +4,12 @@
  * change. Guard order, message strings, and backup behavior are golden-tested.
  */
 import { spawnSync } from "node:child_process"
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
 import { syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
-import { capture, commandExists, p } from "./exec"
+import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
-import { echo, err, log, warn } from "./output"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
@@ -31,14 +30,15 @@ export function codexSync(ctx: Ctx): void {
 // ---------------------------------------------------------- bubblewrap ----
 
 function ensureBubblewrap(ctx: Ctx): void {
-  if (!bwrapSupportedOs()) return
+  const { change, echo, warn } = ctx.services.logger
+  if (!bwrapSupportedOs(ctx)) return
 
   if (ctx.dryRun) {
     echo("[dry-run] verify bubblewrap installed (recommended Codex Linux sandbox runtime)")
     return
   }
 
-  if (commandExists("bwrap")) return
+  if (ctx.services.deps.probe("bwrap").state === "present") return
 
   if (ctx.skipRtk) {
     warn(
@@ -47,7 +47,7 @@ function ensureBubblewrap(ctx: Ctx): void {
     return
   }
 
-  const pmInstall = bwrapDetectPmInstallCmd()
+  const pmInstall = bwrapDetectPmInstallCmd(ctx)
   if (pmInstall === "") {
     warn(
       "bubblewrap not installed and no supported package manager found (apt-get/dnf/pacman/zypper). Codex may use its bundled helper if user namespaces work; install system bubblewrap manually when possible."
@@ -62,14 +62,13 @@ function ensureBubblewrap(ctx: Ctx): void {
     return
   }
 
-  if (!commandExists("bwrap")) {
+  if (ctx.services.deps.probe("bwrap").state === "missing") {
     warn("Package install reported success but bwrap not on PATH — check installation manually")
     return
   }
 
   if (spawnSync("unshare", ["-Ur", "true"], { stdio: "ignore" }).status === 0) {
-    const version = capture("bwrap", ["--version"]).split("\n")[0] ?? ""
-    log(`bubblewrap installed and functional (${version})`)
+    change(`bubblewrap installed and functional (${ctx.services.deps.version("bwrap")})`)
   } else {
     warn(
       "bubblewrap installed but unprivileged user namespaces appear blocked. On Ubuntu 24.04+, prefer loading the AppArmor bwrap-userns-restrict profile; fallback: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0"
@@ -77,24 +76,27 @@ function ensureBubblewrap(ctx: Ctx): void {
   }
 }
 
-function bwrapSupportedOs(): boolean {
-  if (process.platform === "linux") return true
-  if (process.platform === "darwin" || process.platform === "win32") return false
+function bwrapSupportedOs(ctx: Ctx): boolean {
+  const { warn } = ctx.services.logger
+  const pn = ctx.services.platform.name()
+  if (pn === "linux") return true
+  if (pn === "darwin" || pn === "windows") return false
   warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
   return false
 }
 
-function bwrapDetectPmInstallCmd(): string {
-  if (commandExists("apt-get")) return "sudo apt-get install -y bubblewrap"
-  if (commandExists("dnf")) return "sudo dnf install -y bubblewrap"
-  if (commandExists("pacman")) return "sudo pacman -S --noconfirm bubblewrap"
-  if (commandExists("zypper")) return "sudo zypper install -y bubblewrap"
+function bwrapDetectPmInstallCmd(ctx: Ctx): string {
+  if (ctx.services.deps.probe("apt-get").state === "present") return "sudo apt-get install -y bubblewrap"
+  if (ctx.services.deps.probe("dnf").state === "present") return "sudo dnf install -y bubblewrap"
+  if (ctx.services.deps.probe("pacman").state === "present") return "sudo pacman -S --noconfirm bubblewrap"
+  if (ctx.services.deps.probe("zypper").state === "present") return "sudo zypper install -y bubblewrap"
   return ""
 }
 
 // --------------------------------------------------------------- config ----
 
 function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (!existsSync(sotConfig)) return
 
   if (ctx.dryRun) {
@@ -104,17 +106,31 @@ function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
 
   if (!existsSync(userConfig)) {
     copyFileSync(sotConfig, userConfig)
-    log("Codex config installed")
+    change("Codex config installed")
+    ctx.nextStepTriggers.codexRestart = true
     return
   }
 
-  copyFileSync(userConfig, `${userConfig}.bak`)
+  // Merge into a staging copy so `.bak` is written only when the config
+  // actually changes — an unconditional early backup lets a later no-op run
+  // overwrite the recovery copy with already-merged content.
+  const before = readFileSync(userConfig, "utf8")
+  const staging = `${userConfig}.merge.tmp`
+  writeFileSync(staging, before)
 
-  scrubDeprecatedFeatures(userConfig)
-  mergeTopLevelSettings(sotConfig, userConfig)
-  mergeTableSettings(sotConfig, userConfig)
+  scrubDeprecatedFeatures(ctx, staging)
+  mergeTopLevelSettings(sotConfig, staging)
+  mergeTableSettings(sotConfig, staging)
 
-  log("Codex config merged (backup at config.toml.bak; user-only keys/tables preserved)")
+  if (readFileSync(staging, "utf8") === before) {
+    rmSync(staging, { force: true })
+    verbose("Codex config already in sync")
+  } else {
+    copyFileSync(userConfig, `${userConfig}.bak`)
+    renameSync(staging, userConfig)
+    change("Codex config merged (backup at config.toml.bak; user-only keys/tables preserved)")
+    ctx.nextStepTriggers.codexRestart = true
+  }
 }
 
 /** codex::scrub_deprecated_features — the [features].use_legacy_landlock awk pass. */
@@ -152,14 +168,15 @@ export function scrubDeprecatedFeaturesText(content: string): string {
   return out
 }
 
-function scrubDeprecatedFeatures(userConfig: string): void {
+function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
+  const { change } = ctx.services.logger
   if (!existsSync(userConfig)) return
   const content = readFileSync(userConfig, "utf8")
   if (!content.split("\n").some((l) => /^use_legacy_landlock[ \t]*=/.test(l))) return
 
   writeFileSync(`${userConfig}.tmp`, scrubDeprecatedFeaturesText(content))
   renameSync(`${userConfig}.tmp`, userConfig)
-  log("Codex: scrubbed deprecated [features].use_legacy_landlock")
+  change("Codex: scrubbed deprecated [features].use_legacy_landlock")
 }
 
 function mergeTopLevelSettings(sotConfig: string, userConfig: string): void {
@@ -209,6 +226,7 @@ function mergeTableSettings(sotConfig: string, userConfig: string): void {
 // ------------------------------------------------------- rules + agents ----
 
 function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (!existsSync(sotRulesDir)) return
 
   if (ctx.dryRun) {
@@ -217,21 +235,29 @@ function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
   }
 
   mkdirSync(userRulesDir, { recursive: true })
-  let rulesSynced = false
+  let sawRules = false
+  let rulesChanged = false
   const ruleFiles = readdirSync(sotRulesDir, { withFileTypes: true })
     .filter((e) => e.isFile() && e.name.endsWith(".rules"))
     .map((e) => p(sotRulesDir, e.name))
     .sort(compareCodepoints)
   for (const ruleFile of ruleFiles) {
+    sawRules = true
     const userRuleFile = p(userRulesDir, ruleFile.slice(ruleFile.lastIndexOf("/") + 1))
+    const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(readFileSync(ruleFile))
+    if (identical) continue
     if (existsSync(userRuleFile)) copyFileSync(userRuleFile, `${userRuleFile}.bak`)
     copyFileSync(ruleFile, userRuleFile)
-    rulesSynced = true
+    rulesChanged = true
   }
-  if (rulesSynced) log("Codex rules synced")
+  if (rulesChanged) {
+    change("Codex rules synced")
+    ctx.nextStepTriggers.codexRestart = true
+  } else if (sawRules) verbose("Codex rules already in sync")
 }
 
 function syncAgentsMd(ctx: Ctx, sotAgentsMd: string, userAgentsMd: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (!existsSync(sotAgentsMd)) return
 
   if (ctx.dryRun) {
@@ -239,14 +265,20 @@ function syncAgentsMd(ctx: Ctx, sotAgentsMd: string, userAgentsMd: string): void
     return
   }
 
+  if (existsSync(userAgentsMd) && readFileSync(userAgentsMd).equals(readFileSync(sotAgentsMd))) {
+    verbose("Codex AGENTS.md already in sync")
+    return
+  }
   if (existsSync(userAgentsMd)) copyFileSync(userAgentsMd, `${userAgentsMd}.bak`)
   copyFileSync(sotAgentsMd, userAgentsMd)
-  log("Codex AGENTS.md synced")
+  change("Codex AGENTS.md synced")
+  ctx.nextStepTriggers.codexRestart = true
 }
 
 // ---------------------------------------------------------- marketplace ----
 
 function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: string): void {
+  const { change, echo, err, verbose } = ctx.services.logger
   if (!existsSync(sotMarketplace)) return
 
   if (ctx.dryRun) {
@@ -264,13 +296,20 @@ function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: stri
       err(`Skipping marketplace sync: ${userMarketplace} is not valid JSON. Fix or delete it.`)
       return
     }
+    const out = jqStringify(mergeMarketplace(repo, user))
+    if (out === readFileSync(userMarketplace, "utf8")) {
+      verbose("Codex marketplace already in sync")
+      return
+    }
     copyFileSync(userMarketplace, `${userMarketplace}.bak`)
-    writeFileSync(`${userMarketplace}.tmp`, jqStringify(mergeMarketplace(repo, user)))
+    writeFileSync(`${userMarketplace}.tmp`, out)
     renameSync(`${userMarketplace}.tmp`, userMarketplace)
-    log("Codex marketplace merged (backup at marketplace.json.bak)")
+    change("Codex marketplace merged (backup at marketplace.json.bak)")
+    ctx.nextStepTriggers.codexRestart = true
   } else {
     copyFileSync(sotMarketplace, userMarketplace)
-    log("Codex marketplace installed")
+    change("Codex marketplace installed")
+    ctx.nextStepTriggers.codexRestart = true
   }
 }
 
@@ -326,28 +365,27 @@ export function marketplaceSource(marketplace: string, configFile: string): stri
 }
 
 function removeLegacyDocksMarketplace(ctx: Ctx, userConfig: string): void {
+  const { change, echo, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] remove legacy configured Codex Docks marketplace when personal marketplace is deployed")
     return
   }
 
-  if (!commandExists("codex")) return
+  if (ctx.services.deps.probe("codex").state === "missing") return
 
   const source = marketplaceSource("docks", userConfig)
   if (source !== "https://github.com/DocksDocks/docks.git" && source !== "DocksDocks/docks") return
   const res = spawnSync("codex", ["plugin", "marketplace", "remove", "docks"], { stdio: "ignore" })
   if (res.error === undefined && res.status === 0) {
-    log("Removed legacy configured Codex Docks marketplace; using personal marketplace file")
+    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")
   }
 }
 
 /** codex::_standalone_install_command — per-OS official standalone installer. */
-const standaloneInstallCommand = (): string =>
-  process.platform === "win32"
-    ? `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`
-    : 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"'
+const standaloneInstallCommand = (ctx: Ctx): string => ctx.services.deps.spec("codex").installHint()
 
 /** codex::_enabled_plugin_ids — [plugins."<id>"] tables with enabled = true. */
 export function enabledPluginIds(configFile: string): Array<string> {
@@ -386,20 +424,24 @@ function manualPluginRefreshCommand(sotConfig: string): string {
 }
 
 function syncPlugins(ctx: Ctx, sotConfig: string): void {
+  const { change, echo, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] add enabled Codex plugins from SoT")
     return
   }
 
-  if (!commandExists("codex")) {
+  if (ctx.services.deps.probe("codex").state === "missing") {
     warn(
-      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand()} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfig)}`
+      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfig)}`
     )
     return
   }
-  if (!commandExists("git")) {
-    const hint = process.platform === "win32" ? "winget install Git.Git (then open a new terminal)" : "install git via your package manager"
-    warn(`git not found — Codex plugin marketplaces are git repos, so plugin refresh would fail. Skipping. Install: ${hint}, then re-run sync`)
+  if (ctx.services.deps.probe("git").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "git",
+      ctx.services.logger,
+      "plugin marketplaces are git repos — Codex plugin refresh skipped; re-run sync after installing"
+    )
     return
   }
 
@@ -412,7 +454,7 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
       refreshed++
     } else if (addOut.includes("could not find a Codex CLI binary")) {
       warn(
-        `Codex plugin refresh hit a stale launcher/wrapper on PATH - install current standalone Codex with: ${standaloneInstallCommand()}`
+        `Codex plugin refresh hit a stale launcher/wrapper on PATH - install current standalone Codex with: ${standaloneInstallCommand(ctx)}`
       )
       failed++
     } else {
@@ -424,13 +466,17 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
     }
   }
 
-  if (refreshed > 0) log(`Codex plugins synced (plugins: ~${refreshed})`)
+  if (refreshed > 0) {
+    change(`Codex plugins synced (plugins: ~${refreshed})`)
+    ctx.nextStepTriggers.codexRestart = true
+  }
   if (failed > 0) warn(`${failed} Codex plugin operation(s) failed — re-run sync or install manually`)
 }
 
 // -------------------------------------------------------------- summary ----
 
 export function codexSummary(ctx: Ctx): void {
+  const { echo } = ctx.services.logger
   const codexDir = p(ctx.home, ".codex")
   echo(`Codex:    ${codexDir}`)
   if (!ctx.dryRun) {
@@ -439,6 +485,8 @@ export function codexSummary(ctx: Ctx): void {
   }
 }
 
-export function codexNextSteps(): void {
-  echo("Restart Codex to load any refreshed plugins, skills, or tools.")
+export function codexNextSteps(ctx: Ctx): Array<string> {
+  return ctx.verbose || ctx.nextStepTriggers.codexRestart
+    ? ["Restart Codex to load any refreshed plugins, skills, or tools."]
+    : []
 }

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

@@ -8,7 +8,6 @@ import { p } from "./exec"
 import { readFileSync, renameSync, writeFileSync } from "node:fs"
 
 import type { Ctx } from "./index"
-import { echo, log, warn } from "./output"
 
 export function replaceTopLevelSetting(content: string, key: string, replacement: string): string {
   const lines = content.split("\n")
@@ -40,13 +39,17 @@ export function replaceTopLevelSetting(content: string, key: string, replacement
   return `${out.join("\n")}\n`
 }
 
-export function replaceTopLevelSettingInFile(file: string, key: string, replacement: string): void {
-  const next = replaceTopLevelSetting(readFileSync(file, "utf8"), key, replacement)
+export function replaceTopLevelSettingInFile(file: string, key: string, replacement: string): boolean {
+  const before = readFileSync(file, "utf8")
+  const next = replaceTopLevelSetting(before, key, replacement)
+  if (next === before) return false
   writeFileSync(`${file}.tmp`, next)
   renameSync(`${file}.tmp`, file)
+  return true
 }
 
 export function syncCodexModel(ctx: Ctx, model: string): void {
+  const { change, echo, verbose, warn } = ctx.services.logger
   const userCodexSettings = p(ctx.home, ".codex", "config.toml")
 
   if (model === "") return
@@ -62,6 +65,10 @@ export function syncCodexModel(ctx: Ctx, model: string): void {
     warn(`(--codex-model) ${userCodexSettings} missing — skipped`)
     return
   }
-  replaceTopLevelSettingInFile(userCodexSettings, "model", `model = "${model}"`)
-  log(`Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+  if (replaceTopLevelSettingInFile(userCodexSettings, "model", `model = "${model}"`)) {
+    change(`Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+    ctx.nextStepTriggers.codexRestart = true
+  } else {
+    verbose(`Model: deployed Codex model already ${model}`)
+  }
 }