docks-kit 0.1.4 → 0.2.0

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

@@ -6,40 +6,34 @@
 import { spawnSync } from "node:child_process"
 import {
   appendFileSync,
-  chmodSync,
   copyFileSync,
-  cpSync,
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   renameSync,
   rmSync,
-  statSync,
   writeFileSync
 } from "node:fs"
 import { tmpdir } from "node:os"
 import { syncClaudeModel } from "./claudeModel"
-import { capture, commandExists, p } from "./exec"
+import { copyFileIfChanged, copyTreeIfChanged, ensureExecutable, p, writeFileIfChanged } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, type Json } from "./jq"
-import { echo, err, log, warn } from "./output"
+import type { EngineServices } from "./services"
 import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
 
 export function claudeSync(ctx: Ctx): void {
+  const { warn } = ctx.services.logger
   const claudeDir = p(ctx.home, ".claude")
 
   if (!ctx.dryRun) mkdirSync(claudeDir, { recursive: true })
 
-  if (!commandExists("claude")) {
-    const hint =
-      process.platform === "win32"
-        ? "winget install Anthropic.ClaudeCode"
-        : "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh"
+  if (ctx.services.deps.probe("claude").state === "missing") {
     warn(
-      `claude CLI not found - config deploys, but plugin passes are skipped. Install Claude Code: ${hint} | docs: https://code.claude.com/docs/en/setup`
+      `claude CLI not found - config deploys, but plugin passes are skipped. Install Claude Code: ${ctx.services.deps.spec("claude").installHint()} | docs: https://code.claude.com/docs/en/setup`
     )
   }
 
@@ -62,11 +56,12 @@ export function claudeSync(ctx: Ctx): void {
 // ------------------------------------------------------------------ rtk ----
 
 /** RTK toolchain install callback. */
-export function rtkInstall(ctx: Ctx): (mode: "install" | "upgrade", version: string) => number {
-  return (mode, version) => {
+export function rtkInstall(ctx: Ctx): (mode: "install" | "upgrade", version: string, services: EngineServices) => number {
+  return (mode, version, services) => {
+    const { change, err, verbose, warn } = services.logger
     const installerRef = version !== "" ? `refs/tags/v${version}` : "refs/heads/master"
 
-    if (mode === "upgrade") log(`Upgrading RTK${version !== "" ? ` to ${version}` : ""}...`)
+    if (mode === "upgrade") verbose(`Upgrading RTK${version !== "" ? ` to ${version}` : ""}...`)
     else warn(`RTK not found. Installing${version !== "" ? ` ${version}` : ""}...`)
     const installer = p(tmpdir(), `rtk-install-${process.pid}.sh`)
     const dl = spawnSync("curl", ["-fsSL", `https://raw.githubusercontent.com/rtk-ai/rtk/${installerRef}/install.sh`, "-o", installer], {
@@ -80,9 +75,9 @@ export function rtkInstall(ctx: Ctx): (mode: "install" | "upgrade", version: str
     }
     rmSync(installer, { force: true })
     process.env["PATH"] = `${ctx.home}/.local/bin:${ctx.home}/.cargo/bin:${process.env["PATH"] ?? ""}`
-    if (commandExists("rtk")) {
-      const v = capture("rtk", ["--version"])
-      log(`RTK ready (${v !== "" ? v : "version unknown"})`)
+    const installed = services.deps.version("rtk")
+    if (services.deps.probe("rtk").state === "present") {
+      change(`RTK ready (${installed !== "" ? installed : "version unknown"})`)
       return 0
     }
     err("RTK install failed. Install manually: https://github.com/rtk-ai/rtk")
@@ -91,13 +86,14 @@ export function rtkInstall(ctx: Ctx): (mode: "install" | "upgrade", version: str
 }
 
 function syncRtk(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose, warn } = ctx.services.logger
   if (ctx.skipRtk) {
     warn("Skipping RTK (--skip-rtk)")
     return
   }
 
-  if (process.platform === "win32") {
-    if (!commandExists("rtk")) {
+  if (ctx.services.platform.isWindows()) {
+    if (ctx.services.deps.probe("rtk").state === "missing") {
       warn("rtk not installed — the kit's auto-install is Unix-only. Install natively (winget, or the rtk-*-windows-msvc.zip release), then re-run sync")
       return
     }
@@ -105,7 +101,7 @@ function syncRtk(ctx: Ctx, claudeDir: string): void {
     warn("RTK bootstrap failed — continuing sync without it")
   }
 
-  if (!commandExists("rtk")) return
+  if (ctx.services.deps.probe("rtk").state === "missing") return
   if (!existsSync(p(claudeDir, "RTK.md"))) {
     if (ctx.dryRun) {
       echo("[dry-run] rtk init --global (RTK.md missing; runs before the settings merge, which normalizes rtk's settings rewrite)")
@@ -115,30 +111,35 @@ function syncRtk(ctx: Ctx, claudeDir: string): void {
     // sync before the success log and before any settings/plugin mutation.
     const res = spawnSync("rtk", ["init", "--global"], { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) throw new ExitError(res.status ?? 1)
-    log("RTK initialized (RTK.md generated; the following settings merge re-asserts the SoT hooks)")
+    change("RTK initialized (RTK.md generated; the following settings merge re-asserts the SoT hooks)")
   } else if (!ctx.dryRun) {
-    log("RTK already initialized")
+    verbose("RTK already initialized")
   }
 }
 
 // ------------------------------------------------------ scripts + hooks ----
 
 function syncScripts(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] cp statusline.sh, fetch-usage.sh, notification.mp3")
     return
   }
 
+  let changed = false
   for (const script of ["statusline.sh", "fetch-usage.sh"]) {
     const src = p(ctx.repoDir, "SoT", ".claude", script)
     if (existsSync(src)) {
-      copyFileSync(src, p(claudeDir, script))
-      chmodSync(p(claudeDir, script), statSync(p(claudeDir, script)).mode | 0o111)
+      if (copyFileIfChanged(src, p(claudeDir, script))) changed = true
+      if (ensureExecutable(p(claudeDir, script))) changed = true
     }
   }
   const mp3 = p(ctx.repoDir, "notification.mp3")
-  if (existsSync(mp3)) copyFileSync(mp3, p(claudeDir, "notification.mp3"))
-  log("Scripts synced (statusline, fetch-usage, notification)")
+  if (existsSync(mp3) && copyFileIfChanged(mp3, p(claudeDir, "notification.mp3"))) changed = true
+  if (changed) {
+    change("Scripts synced (statusline, fetch-usage, notification)")
+    ctx.nextStepTriggers.claudeRestart = true
+  } else verbose("Scripts already in sync (statusline, fetch-usage, notification)")
 }
 
 function shellScriptCount(hooksDir: string): number {
@@ -150,6 +151,7 @@ function shellScriptCount(hooksDir: string): number {
 }
 
 function syncHooks(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   const sotHooks = p(ctx.repoDir, "SoT", ".claude", "hooks")
   if (!existsSync(sotHooks)) return
 
@@ -160,19 +162,31 @@ function syncHooks(ctx: Ctx, claudeDir: string): void {
 
   const hooksDir = p(claudeDir, "hooks")
   mkdirSync(hooksDir, { recursive: true })
-  cpSync(sotHooks, hooksDir, { recursive: true })
+  let changed = copyTreeIfChanged(sotHooks, hooksDir)
   for (const e of readdirSync(hooksDir, { withFileTypes: true })) {
     if (e.isFile() && e.name.endsWith(".sh")) {
-      chmodSync(p(hooksDir, e.name), statSync(p(hooksDir, e.name)).mode | 0o111)
+      if (ensureExecutable(p(hooksDir, e.name))) changed = true
     }
   }
-  log(`Hooks synced (${shellScriptCount(hooksDir)} scripts)`)
+  if (changed) {
+    change(`Hooks synced (${shellScriptCount(hooksDir)} scripts)`)
+    ctx.nextStepTriggers.claudeRestart = true
+  } else verbose(`Hooks already in sync (${shellScriptCount(hooksDir)} scripts)`)
 }
 
 function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
+  // The @RTK.md import only resolves once `rtk init` has generated
+  // ~/.claude/RTK.md (the rtk phase runs before this). Deploying the import
+  // without the file leaves a dangling reference in every Claude session
+  // (seen on Windows, where rtk never auto-installs) — strip it while the
+  // file is absent; a later sync after rtk init restores it.
+  const rtkMdAbsent = !existsSync(p(claudeDir, "RTK.md"))
   if (ctx.dryRun) {
     if (ctx.skipRtk) {
       echo("[dry-run] cp SoT/.claude/CLAUDE.md -> ~/.claude/CLAUDE.md (stripping @RTK.md import: --skip-rtk)")
+    } else if (rtkMdAbsent) {
+      echo("[dry-run] cp SoT/.claude/CLAUDE.md -> ~/.claude/CLAUDE.md (would strip @RTK.md import while ~/.claude/RTK.md is absent)")
     } else {
       echo("[dry-run] cp SoT/.claude/CLAUDE.md -> ~/.claude/CLAUDE.md")
     }
@@ -180,22 +194,28 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
   }
 
   const src = p(ctx.repoDir, "SoT", ".claude", "CLAUDE.md")
-  if (ctx.skipRtk) {
+  const stripReason = ctx.skipRtk ? "--skip-rtk" : rtkMdAbsent ? "~/.claude/RTK.md absent (rtk not initialized)" : ""
+  if (stripReason !== "") {
     const stripped = readFileSync(src, "utf8")
       .split("\n")
       .filter((l) => l !== "@RTK.md")
       .join("\n")
-    writeFileSync(p(claudeDir, "CLAUDE.md"), stripped)
-    log("CLAUDE.md synced (@RTK.md import stripped: --skip-rtk)")
+    if (writeFileIfChanged(p(claudeDir, "CLAUDE.md"), stripped)) {
+      change(`CLAUDE.md synced (@RTK.md import stripped: ${stripReason})`)
+    } else {
+      verbose("CLAUDE.md already in sync")
+    }
+  } else if (copyFileIfChanged(src, p(claudeDir, "CLAUDE.md"))) {
+    change("CLAUDE.md synced")
   } else {
-    copyFileSync(src, p(claudeDir, "CLAUDE.md"))
-    log("CLAUDE.md synced")
+    verbose("CLAUDE.md already in sync")
   }
 }
 
 // ------------------------------------------------------------- settings ----
 
 function syncSettings(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, err, verbose } = ctx.services.logger
   const repoSettings = p(ctx.repoDir, "SoT", ".claude", "settings.json")
   const userSettings = p(claudeDir, "settings.json")
 
@@ -212,7 +232,8 @@ function syncSettings(ctx: Ctx, claudeDir: string): void {
 
   if (!existsSync(userSettings)) {
     copyFileSync(repoSettings, userSettings)
-    log("Settings installed")
+    change("Settings installed")
+    ctx.nextStepTriggers.claudeRestart = true
     return
   }
 
@@ -224,35 +245,47 @@ function syncSettings(ctx: Ctx, claudeDir: string): void {
   }
   const repo = parseJson(readFileSync(repoSettings, "utf8"))!
 
-  copyFileSync(userSettings, `${userSettings}.bak`)
   const merged = ctx.reconcile ? reconcileSettings(repo, user) : mergeSettings(repo, user)
-  writeFileSync(`${userSettings}.tmp`, jqStringify(merged))
+  const out = jqStringify(merged)
+  if (out === readFileSync(userSettings, "utf8")) {
+    verbose("Settings already in sync")
+    return
+  }
+  copyFileSync(userSettings, `${userSettings}.bak`)
+  writeFileSync(`${userSettings}.tmp`, out)
   renameSync(`${userSettings}.tmp`, userSettings)
+  ctx.nextStepTriggers.claudeRestart = true
   if (ctx.reconcile) {
-    log("Settings reconciled (backup at settings.json.bak; user-only keys preserved, permissions arrays replaced by SoT)")
+    change("Settings reconciled (backup at settings.json.bak; user-only keys preserved, permissions arrays replaced by SoT)")
   } else {
-    log("Settings merged (backup at settings.json.bak)")
+    change("Settings merged (backup at settings.json.bak)")
   }
 }
 
 /** Shared shape of the three jq-edit modifiers (compact window, permissive). */
-function jqEditSettings(claudeDir: string, tag: string, edit: (doc: Json) => void): void {
+function jqEditSettings(ctx: Ctx, claudeDir: string, tag: string, edit: (doc: Json) => void): boolean {
+  const { err, warn } = ctx.services.logger
   const userSettings = p(claudeDir, "settings.json")
   if (!existsSync(userSettings)) {
     warn(`(${tag}) ${userSettings} missing — skipped`)
-    return
+    return false
   }
-  const doc = parseJson(readFileSync(userSettings, "utf8"))
+  const before = readFileSync(userSettings, "utf8")
+  const doc = parseJson(before)
   if (doc === undefined) {
     err(`(${tag}) ${userSettings} is not valid JSON — skipped`)
-    return
+    return false
   }
   edit(doc)
-  writeFileSync(`${userSettings}.tmp`, jqStringify(doc))
+  const out = jqStringify(doc)
+  if (out === before) return false
+  writeFileSync(`${userSettings}.tmp`, out)
   renameSync(`${userSettings}.tmp`, userSettings)
+  return true
 }
 
 function syncCompactWindow(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (ctx.claudeCompactWindow === "") return
 
   if (ctx.dryRun) {
@@ -260,16 +293,21 @@ function syncCompactWindow(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  jqEditSettings(claudeDir, "--claude-compact-window", (doc) => {
+  const changed = jqEditSettings(ctx, claudeDir, "--claude-compact-window", (doc) => {
     if (!isObject(doc)) return
     const env = isObject(doc["env"]) ? doc["env"] : {}
     env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = ctx.claudeCompactWindow
     doc["env"] = env
   })
-  log(`Compact window: set to ${ctx.claudeCompactWindow} tokens in deployed settings (SoT and model unchanged; flag-less sync reverts)`)
+  if (changed) {
+    change(`Compact window: set to ${ctx.claudeCompactWindow} tokens in deployed settings (SoT and model unchanged; flag-less sync reverts)`)
+    ctx.nextStepTriggers.claudeRestart = true
+  }
+  else verbose(`Compact window: already set to ${ctx.claudeCompactWindow} tokens in deployed settings`)
 }
 
 function syncPermissive(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose } = ctx.services.logger
   if (!ctx.claudePermissive) return
 
   if (ctx.dryRun) {
@@ -277,19 +315,24 @@ function syncPermissive(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  jqEditSettings(claudeDir, "--claude-permissive", (doc) => {
+  const changed = jqEditSettings(ctx, claudeDir, "--claude-permissive", (doc) => {
     if (!isObject(doc)) return
     const permissions = isObject(doc["permissions"]) ? doc["permissions"] : {}
     permissions["ask"] = []
     permissions["deny"] = []
     doc["permissions"] = permissions
   })
-  log("Permissive mode: permissions.ask/deny emptied in deployed settings (sandbox use; SoT unchanged)")
+  if (changed) {
+    change("Permissive mode: permissions.ask/deny emptied in deployed settings (sandbox use; SoT unchanged)")
+    ctx.nextStepTriggers.claudeRestart = true
+  }
+  else verbose("Permissive mode: permissions.ask/deny already empty in deployed settings")
 }
 
 // ---------------------------------------------------------- claude.json ----
 
 function syncClaudeJson(ctx: Ctx): void {
+  const { change, echo, err, verbose } = ctx.services.logger
   const claudeJson = p(ctx.home, ".claude.json")
   const mcpSot = p(ctx.repoDir, "SoT", ".claude", "mcp-servers.json")
 
@@ -311,37 +354,49 @@ function syncClaudeJson(ctx: Ctx): void {
     }
   }
 
+  let changed = true
   if (existsSync(claudeJson)) {
-    const doc = parseJson(readFileSync(claudeJson, "utf8"))
+    const before = readFileSync(claudeJson, "utf8")
+    const doc = parseJson(before)
     if (doc === undefined) {
       err("Skipping ~/.claude.json edit: not valid JSON. Fix or delete it.")
       return
     }
     const obj = isObject(doc) ? doc : {}
     applyFilter(obj)
-    writeFileSync(`${claudeJson}.tmp`, jqStringify(obj))
-    renameSync(`${claudeJson}.tmp`, claudeJson)
+    const out = jqStringify(obj)
+    if (out === before) {
+      changed = false
+    } else {
+      writeFileSync(`${claudeJson}.tmp`, out)
+      renameSync(`${claudeJson}.tmp`, claudeJson)
+    }
   } else {
     const obj: { [k: string]: Json } = {}
     applyFilter(obj)
     writeFileSync(claudeJson, jqStringify(obj))
   }
-  log(`~/.claude.json updated (showTurnDuration${haveMcp ? ", mcpServers" : ""})`)
+  if (changed) {
+    change(`~/.claude.json updated (showTurnDuration${haveMcp ? ", mcpServers" : ""})`)
+    ctx.nextStepTriggers.claudeRestart = true
+  }
+  else verbose(`~/.claude.json already in sync (showTurnDuration${haveMcp ? ", mcpServers" : ""})`)
 }
 
 // -------------------------------------------------------- connector env ----
 
 function syncConnectorEnv(ctx: Ctx): void {
+  const { change, echo, verbose, warn } = ctx.services.logger
   // win32: Claude Code launches from PowerShell/GUI, so the flag must be a
   // real user env var (setx), not a Git-Bash-only shell-rc export. Never
   // clobbers an existing value (set =true yourself to keep connectors).
-  if (process.platform === "win32") {
+  if (ctx.services.platform.isWindows()) {
     const existing = spawnSync("reg", ["query", "HKCU\\Environment", "/v", "ENABLE_CLAUDEAI_MCP_SERVERS"], {
       stdio: "ignore"
     })
     if (existing.error === undefined && existing.status === 0) {
       if (ctx.dryRun) echo("[dry-run] ENABLE_CLAUDEAI_MCP_SERVERS already in user environment — would skip")
-      else log("claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in user environment (left as-is)")
+      else verbose("claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in user environment (left as-is)")
       return
     }
     if (ctx.dryRun) {
@@ -350,7 +405,8 @@ function syncConnectorEnv(ctx: Ctx): void {
     }
     const res = spawnSync("setx", ["ENABLE_CLAUDEAI_MCP_SERVERS", "false"], { stdio: "ignore" })
     if (res.error === undefined && res.status === 0) {
-      log("claude.ai connectors disabled via setx (open a new terminal to apply)")
+      change("claude.ai connectors disabled via setx (open a new terminal to apply)")
+      ctx.nextStepTriggers.claudeRestart = true
     } else {
       warn("setx ENABLE_CLAUDEAI_MCP_SERVERS false failed — set it manually in System Properties > Environment Variables")
     }
@@ -366,7 +422,7 @@ function syncConnectorEnv(ctx: Ctx): void {
       if (ctx.dryRun) {
         echo(`[dry-run] ENABLE_CLAUDEAI_MCP_SERVERS already in ${f} — would skip`)
       } else {
-        log(`claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in ${f} (left as-is)`)
+        verbose(`claude.ai connectors: ENABLE_CLAUDEAI_MCP_SERVERS already set in ${f} (left as-is)`)
       }
       return
     }
@@ -382,7 +438,8 @@ function syncConnectorEnv(ctx: Ctx): void {
   }
 
   appendFileSync(target, `\n${marker}\n${line}\n`)
-  log(`claude.ai connectors disabled via ${target} (start a new shell to apply)`)
+  change(`claude.ai connectors disabled via ${target} (start a new shell to apply)`)
+  ctx.nextStepTriggers.claudeRestart = true
 }
 
 // ------------------------------------------------------------- removals ----
@@ -439,6 +496,7 @@ function pruneJsonKeys(ctx: Ctx, file: string, keys: Array<string>): number {
 }
 
 function syncRemovals(ctx: Ctx, claudeDir: string): void {
+  const { change, echo } = ctx.services.logger
   let hooksRemoved = 0
   let filesRemoved = 0
 
@@ -474,7 +532,8 @@ function syncRemovals(ctx: Ctx, claudeDir: string): void {
   }
 
   if (hooksRemoved + filesRemoved + skeys + cjkeys > 0) {
-    log(`Pruned stale artifacts (hooks: ${hooksRemoved}, files: ${filesRemoved}, settings keys: ${skeys}, claude.json keys: ${cjkeys})`)
+    change(`Pruned stale artifacts (hooks: ${hooksRemoved}, files: ${filesRemoved}, settings keys: ${skeys}, claude.json keys: ${cjkeys})`)
+    ctx.nextStepTriggers.claudeRestart = true
   }
 }
 
@@ -504,6 +563,7 @@ function pluginUserScopeInstalled(installedPlugins: string, pluginId: string): b
 }
 
 function syncPlugins(ctx: Ctx, claudeDir: string): void {
+  const { change, echo, verbose, warn } = ctx.services.logger
   const repoSettingsFile = p(ctx.repoDir, "SoT", ".claude", "settings.json")
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
@@ -516,10 +576,18 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  if (!commandExists("claude")) {
+  if (ctx.services.deps.probe("claude").state === "missing") {
     warn("claude CLI not in PATH — skipping plugin reconcile (run /plugin marketplace add + /plugin install manually)")
     return
   }
+  if (ctx.services.deps.probe("git").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "git",
+      ctx.services.logger,
+      "plugin marketplaces are git repos — Claude plugin passes skipped; re-run sync after installing"
+    )
+    return
+  }
 
   const repoSettings = readJsonFile(repoSettingsFile)
   const repoObj = repoSettings !== undefined && isObject(repoSettings) ? repoSettings : {}
@@ -599,29 +667,37 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   }
 
   // Pass 6 — re-assert SoT enabled-state in the user settings.
-  reassertEnabledState(repoObj, p(claudeDir, "settings.json"))
+  if (reassertEnabledState(ctx, repoObj, p(claudeDir, "settings.json"))) {
+    change("Plugin enable-state re-asserted from SoT in settings.json")
+    ctx.nextStepTriggers.claudePlugins = true
+  }
 
   const failed = f1 + f2 + f4 + f5
   if (addedMp > 0 || addedPl > 0 || updatedPl > 0 || removedPl > 0 || removedMp > 0) {
-    log(`Plugins synced (marketplaces: +${addedMp} -${removedMp}, plugins: +${addedPl} ~${updatedPl} -${removedPl})`)
+    change(`Plugins synced (marketplaces: +${addedMp} -${removedMp}, plugins: +${addedPl} ~${updatedPl} -${removedPl})`)
+    ctx.nextStepTriggers.claudePlugins = true
   } else {
-    log("Plugins already in sync")
+    verbose("Plugins already in sync")
   }
   if (failed > 0) {
     warn(`${failed} plugin operation(s) failed — re-run sync or install manually`)
   }
 }
 
-function reassertEnabledState(repoObj: { [k: string]: Json }, userSettingsFile: string): void {
-  if (!existsSync(userSettingsFile)) return
+function reassertEnabledState(ctx: Ctx, repoObj: { [k: string]: Json }, userSettingsFile: string): boolean {
+  const { warn } = ctx.services.logger
+  if (!existsSync(userSettingsFile)) return false
   const sotPlugins = isObject(repoObj["enabledPlugins"]) ? repoObj["enabledPlugins"] : {}
 
+  let cliDisabled = false
   for (const [pluginId, value] of Object.entries(sotPlugins)) {
     if (value !== false) continue
     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 (!cli(["plugin", "disable", pluginId]).ok) {
+    if (cli(["plugin", "disable", pluginId]).ok) {
+      cliDisabled = true
+    } else {
       warn(`Failed to disable SoT-false plugin: ${pluginId} (will retry next sync)`)
     }
   }
@@ -629,44 +705,66 @@ function reassertEnabledState(repoObj: { [k: string]: Json }, userSettingsFile:
   const user = readJsonFile(userSettingsFile)
   if (user === undefined || !isObject(user)) {
     warn("enabledPlugins re-assert failed — false-keyed plugins may be left enabled")
-    return
+    return false
   }
+  const beforeCanonical = jqStringify(user)
   user["enabledPlugins"] = deepMerge(isObject(user["enabledPlugins"]) ? user["enabledPlugins"] : {}, sotPlugins)
-  writeFileSync(`${userSettingsFile}.tmp`, jqStringify(user))
+  const out = jqStringify(user)
+  if (out === beforeCanonical) return cliDisabled
+  writeFileSync(`${userSettingsFile}.tmp`, out)
   renameSync(`${userSettingsFile}.tmp`, userSettingsFile)
+  return true
 }
 
 // ------------------------------------------------------ optional plugins ----
 
-function enableOptionalPlugin(claudeDir: string, pluginId: string, marketplaceRepo: string): void {
+function enableOptionalPlugin(ctx: Ctx, claudeDir: string, pluginId: string, marketplaceRepo: string): boolean {
+  const { change, verbose, warn } = 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)
 
+  let marketplaceAdded = false
   if (marketplaceRepo !== "") {
     const known = readJsonFile(knownMarketplaces)
     const has = known !== undefined && isObject(known) && known[mpName] !== undefined && known[mpName] !== null && known[mpName] !== false
-    if (!has && !cli(["plugin", "marketplace", "add", marketplaceRepo]).ok) {
-      warn(`Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
-      return
+    if (!has) {
+      if (!cli(["plugin", "marketplace", "add", marketplaceRepo]).ok) {
+        warn(`Failed to add marketplace ${marketplaceRepo} for ${pluginId}`)
+        return false
+      }
+      marketplaceAdded = true
     }
   }
 
-  if (!pluginUserScopeInstalled(installedPlugins, pluginId)) {
+  const wasInstalled = pluginUserScopeInstalled(installedPlugins, pluginId)
+  if (!wasInstalled) {
     if (!cli(["plugin", "install", pluginId]).ok) {
+      if (marketplaceAdded) change(`Optional plugin ${pluginId}: marketplace added (install failed — will retry next sync)`)
       warn(`Failed to install optional plugin ${pluginId}`)
-      return
+      return marketplaceAdded
     }
   }
 
-  if (cli(["plugin", "enable", pluginId]).ok) {
-    log(`Optional plugin opted in: ${pluginId}`)
-  } else {
+  const settingsDoc = readJsonFile(p(claudeDir, "settings.json"))
+  const wasEnabled =
+    settingsDoc !== undefined && isObject(settingsDoc) && isObject(settingsDoc["enabledPlugins"])
+      ? (settingsDoc["enabledPlugins"] as { [k: string]: Json })[pluginId] === true
+      : false
+
+  if (!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}`)
+    return marketplaceAdded || !wasInstalled
   }
+  const changed = marketplaceAdded || !wasInstalled || !wasEnabled
+  if (changed) change(`Optional plugin opted in: ${pluginId}`)
+  else verbose(`Optional plugin already opted in: ${pluginId} (enable re-asserted)`)
+  return changed
 }
 
 function syncOptionalPlugins(ctx: Ctx, claudeDir: string): void {
+  const { echo, warn } = ctx.services.logger
   if (ctx.claudePlugins.length === 0) return
 
   if (ctx.dryRun) {
@@ -679,16 +777,16 @@ function syncOptionalPlugins(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  if (!commandExists("claude")) {
+  if (ctx.services.deps.probe("claude").state === "missing") {
     warn("claude CLI not in PATH — cannot opt in optional plugins (--claude-plugin)")
     return
   }
 
   if (ctx.claudePlugins.includes("supabase")) {
-    enableOptionalPlugin(claudeDir, "supabase@claude-plugins-official", "")
+    if (enableOptionalPlugin(ctx, claudeDir, "supabase@claude-plugins-official", "")) ctx.nextStepTriggers.claudePlugins = true
   }
   if (ctx.claudePlugins.includes("n8n")) {
-    enableOptionalPlugin(claudeDir, "n8n-mcp-skills@n8n-mcp-skills", "czlonkowski/n8n-skills")
+    if (enableOptionalPlugin(ctx, claudeDir, "n8n-mcp-skills@n8n-mcp-skills", "czlonkowski/n8n-skills")) ctx.nextStepTriggers.claudePlugins = true
   }
 }
 
@@ -700,6 +798,7 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
 }
 
 function syncLspServers(ctx: Ctx): void {
+  const { change, echo, verbose, warn } = ctx.services.logger
   const sot = readJsonFile(p(ctx.repoDir, "SoT", ".claude", "settings.json"))
   const enabled = sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"]) ? sot["enabledPlugins"] : undefined
   if (enabled === undefined) return
@@ -708,17 +807,17 @@ function syncLspServers(ctx: Ctx): void {
   if (!hasPhp && !hasTs) return
 
   const missing: Array<string> = []
-  if (hasPhp && !commandExists("intelephense")) missing.push(lspPkg(ctx, "intelephense", "intelephense"))
+  if (hasPhp && ctx.services.deps.probe("intelephense").state === "missing") missing.push(lspPkg(ctx, "intelephense", "intelephense"))
   if (hasTs) {
-    if (!commandExists("typescript-language-server")) missing.push(lspPkg(ctx, "typescript-language-server", "typescript-language-server"))
-    if (!commandExists("tsc")) missing.push(lspPkg(ctx, "tsc", "typescript"))
+    if (ctx.services.deps.probe("typescript-language-server").state === "missing") missing.push(lspPkg(ctx, "typescript-language-server", "typescript-language-server"))
+    if (ctx.services.deps.probe("tsc").state === "missing") missing.push(lspPkg(ctx, "tsc", "typescript"))
   }
 
   if (missing.length === 0) {
     if (ctx.dryRun) {
       echo("[dry-run] LSP server binaries present")
     } else {
-      log("LSP server binaries present")
+      verbose("LSP server binaries present")
     }
     return
   }
@@ -729,14 +828,19 @@ function syncLspServers(ctx: Ctx): void {
     return
   }
 
-  if (!commandExists("npm")) {
-    warn(`npm not found — cannot install LSP servers (${specs}); the php-lsp/typescript-lsp plugins stay no-ops. Install Node.js, then re-run sync.`)
+  if (ctx.services.deps.probe("npm").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "npm",
+      ctx.services.logger,
+      `cannot install LSP servers (${specs}); the php-lsp/typescript-lsp plugins stay no-ops`
+    )
     return
   }
 
-  log(`Installing LSP servers via npm: ${specs}...`)
+  verbose(`Installing LSP servers via npm: ${specs}...`)
   if (spawnSync("npm", ["install", "-g", ...missing], { stdio: "ignore" }).status === 0) {
-    log(`LSP servers installed (${specs})`)
+    change(`LSP servers installed (${specs})`)
+    ctx.nextStepTriggers.claudeRestart = true
   } else {
     warn(`npm install -g ${specs} failed. Try manually: npm install -g ${specs}`)
   }
@@ -745,17 +849,18 @@ function syncLspServers(ctx: Ctx): void {
 // -------------------------------------------------------------- summary ----
 
 export function claudeSummary(ctx: Ctx): void {
+  const { echo } = ctx.services.logger
   const claudeDir = p(ctx.home, ".claude")
   echo(`Claude:   ${claudeDir}`)
   if (!ctx.dryRun) {
     echo(`Hooks:    ${shellScriptCount(p(claudeDir, "hooks"))} scripts`)
-    if (commandExists("rtk")) {
-      const v = capture("rtk", ["--version"])
-      echo(`RTK:      ${v !== "" ? v : "installed"}`)
+    if (ctx.services.deps.probe("rtk").state === "present") {
+      const version = ctx.services.deps.version("rtk")
+      echo(`RTK:      ${version !== "" ? version : "installed"}`)
     } else {
       echo("RTK:      not installed")
     }
-    if (commandExists("claude")) {
+    if (ctx.services.deps.probe("claude").state === "present") {
       const installed = readJsonFile(p(claudeDir, "plugins", "installed_plugins.json"))
       const count = installed !== undefined && isObject(installed) && isObject(installed["plugins"]) ? Object.keys(installed["plugins"]).length : 0
       echo(`Plugins:  ${count} installed (from SoT enabledPlugins + Anthropic auto-installs)`)
@@ -765,7 +870,13 @@ export function claudeSummary(ctx: Ctx): void {
   }
 }
 
-export function claudeNextSteps(): void {
-  echo("In a Claude Code session, run /reload-plugins to pick up newly installed plugins.")
-  echo("Restart Claude Code for hook/env-var changes to take effect.")
+export function claudeNextSteps(ctx: Ctx): Array<string> {
+  const lines: Array<string> = []
+  if (ctx.verbose || ctx.nextStepTriggers.claudePlugins) {
+    lines.push("In a Claude Code session, run /reload-plugins to pick up newly installed plugins.")
+  }
+  if (ctx.verbose || ctx.nextStepTriggers.claudeRestart) {
+    lines.push("Restart Claude Code for hook/env-var changes to take effect.")
+  }
+  return lines
 }