docks-kit 0.15.1 → 0.15.3

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

@@ -9,6 +9,7 @@ import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from ".
 import { p, spawnProcess } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { hostOs } from "./os"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
 export async function codexSync(ctx: Ctx): Promise<void> {
@@ -70,7 +71,10 @@ async function ensureBubblewrap(ctx: Ctx): Promise<void> {
     return
   }
 
-  if ((await spawnProcess("unshare", ["-Ur", "true"], { stdio: "ignore" })).exitCode === 0) {
+  const namespaceProbe = await spawnProcess("unshare", ["-Ur", "true"], { stdio: "ignore" })
+  if (namespaceProbe.error !== undefined) {
+    warn(`Could not run unshare to check user namespaces: ${namespaceProbe.error.message}`)
+  } else if (namespaceProbe.exitCode === 0) {
     change(`bubblewrap installed and functional (${await ctx.services.deps.version("bwrap")})`)
   } else {
     warn(
@@ -81,10 +85,11 @@ async function ensureBubblewrap(ctx: Ctx): Promise<void> {
 
 function bwrapSupportedOs(ctx: Ctx): boolean {
   const { warn } = ctx.services.logger
-  const pn = ctx.services.platform.name()
-  if (pn === "linux") return true
-  if (pn === "darwin") return false
-  warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
+  const os = hostOs(ctx.services.platform.name())
+  if (os.supportsBubblewrap) return true
+  if (os.id === "unknown") {
+    warn("Unknown OS — skipping bubblewrap check; Codex sandbox may not work")
+  }
   return false
 }
 
@@ -100,10 +105,14 @@ function bwrapDetectPmInstallCmd(ctx: Ctx): string {
 
 function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml", ctx.repoDir)
+  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml")
 
   if (ctx.dryRun) {
-    echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
+    if (existsSync(userConfig)) {
+      echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
+    } else {
+      echo(`[dry-run] install ${sotConfig} -> ${userConfig}`)
+    }
     return
   }
 
@@ -119,7 +128,8 @@ function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   // overwrite the recovery copy with already-merged content.
   const before = readFileSync(userConfig, "utf8")
   const staging = `${userConfig}.merge.tmp`
-  writeFileSync(staging, before)
+  // Normalize once before record transforms because CR bytes change table-header identity.
+  writeFileSync(staging, before.replace(/\r\n/g, "\n"))
 
   scrubDeprecatedFeatures(ctx, staging)
   removeRetiredPluginTables(ctx, staging)
@@ -146,15 +156,20 @@ export function scrubDeprecatedFeaturesText(content: string): string {
   let header = ""
   let body = ""
   let keep = false
+  let changed = false
   for (const line of lines) {
     if (inFeatures) {
       if (line.startsWith("[")) {
         inFeatures = false
         if (keep) out += `${header}\n${body}`
+        else changed = true
         out += `${line}\n`
         continue
       }
-      if (/^use_legacy_landlock[ \t]*=/.test(line)) continue
+      if (/^use_legacy_landlock[ \t]*=/.test(line)) {
+        changed = true
+        continue
+      }
       body += `${line}\n`
       if (/[^ \t\f\v\r]/.test(line)) keep = true
       continue
@@ -168,24 +183,31 @@ export function scrubDeprecatedFeaturesText(content: string): string {
     }
     out += `${line}\n`
   }
-  if (inFeatures && keep) out += `${header}\n${body}`
-  return out
+  if (inFeatures) {
+    if (keep) out += `${header}\n${body}`
+    else changed = true
+  }
+  return changed ? out : content
 }
 
 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
+  const next = scrubDeprecatedFeaturesText(content)
+  if (next === content) return
 
-  writeFileSync(`${userConfig}.tmp`, scrubDeprecatedFeaturesText(content))
+  writeFileSync(`${userConfig}.tmp`, next)
   renameSync(`${userConfig}.tmp`, userConfig)
   change("Codex: scrubbed deprecated [features].use_legacy_landlock")
 }
 
 const PLUGIN_TABLE_HEADER = /^\[plugins\."([^"]+)"\][ \t]*$/
 /** Plugin ids the kit retired; their deployed tables are stripped on every sync. */
-const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = { "session-relay@docks": true }
+const RETIRED_PLUGIN_IDS: Readonly<Record<string, true>> = {
+  "effect-kit@docks": true,
+  "session-relay@docks": true
+}
 
 /** codex::remove_retired_plugin_tables — drop [plugins."<id>"] blocks for retired ids. */
 export function removeRetiredPluginTablesText(content: string): string {
@@ -236,38 +258,134 @@ function mergeTopLevelSettings(sotConfigText: string, userConfig: string): void
   }
 }
 
-function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+interface TomlTableHeader {
+  readonly path: string
+}
+
+const TOML_BASIC_ESCAPES: Readonly<Record<string, string>> = {
+  b: "\b",
+  t: "\t",
+  n: "\n",
+  f: "\f",
+  r: "\r",
+  '"': '"',
+  "\\": "\\"
+}
+
+function tomlBasicEscape(line: string, offset: number): { readonly next: number; readonly value: string } | undefined {
+  const escaped = line[offset]
+  const simple = escaped === undefined ? undefined : TOML_BASIC_ESCAPES[escaped]
+  if (simple !== undefined) return { next: offset + 1, value: simple }
+  const digits = escaped === "u" ? 4 : escaped === "U" ? 8 : 0
+  if (digits === 0) return undefined
+  const hex = line.slice(offset + 1, offset + 1 + digits)
+  if (hex.length !== digits || !/^[0-9A-Fa-f]+$/.test(hex)) return undefined
+  const codePoint = Number.parseInt(hex, 16)
+  if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return undefined
+  return { next: offset + 1 + digits, value: String.fromCodePoint(codePoint) }
+}
+
+/** Decode a table header to the TOML path that determines managed ownership. */
+function tomlTableHeader(line: string): TomlTableHeader | undefined {
+  let offset = 0
+  const skipWhitespace = (): void => {
+    while (line[offset] === " " || line[offset] === "\t") offset++
+  }
+
+  skipWhitespace()
+  if (line[offset] !== "[") return undefined
+  offset++
+  const array = line[offset] === "["
+  if (array) offset++
+
+  const keys: Array<string> = []
+  while (true) {
+    skipWhitespace()
+    const quote = line[offset]
+    let key = ""
+    if (quote === '"' || quote === "'") {
+      offset++
+      let closed = false
+      while (offset < line.length) {
+        const char = line[offset]!
+        if (char === quote) {
+          offset++
+          closed = true
+          break
+        }
+        if (quote === '"' && char === "\\") {
+          const escape = tomlBasicEscape(line, offset + 1)
+          if (escape === undefined) return undefined
+          key += escape.value
+          offset = escape.next
+          continue
+        }
+        if (char === "\n" || char === "\r") return undefined
+        key += char
+        offset++
+      }
+      if (!closed) return undefined
+    } else {
+      const start = offset
+      while (offset < line.length && /[A-Za-z0-9_-]/.test(line[offset]!)) offset++
+      if (offset === start) return undefined
+      key = line.slice(start, offset)
+    }
+    keys.push(key)
+
+    skipWhitespace()
+    if (line[offset] === ".") {
+      offset++
+      continue
+    }
+    if (line[offset] !== "]") return undefined
+    offset++
+    if (array) {
+      if (line[offset] !== "]") return undefined
+      offset++
+    }
+    skipWhitespace()
+    if (offset < line.length && line[offset] !== "#") return undefined
+    return { path: JSON.stringify(keys) }
+  }
+}
+
+function mergeTableSettingsText(sotConfigText: string, userConfigText: string): string {
   const sotLines = sotConfigText.split("\n")
-  for (const tableHeader of sotLines.filter((l) => /^\[[^\]]+\]/.test(l))) {
-    // Extract the SoT block: from the exact header line to (excluding) the
-    // next table header; `$(...)` strips trailing newlines.
-    let printing = false
+  let merged = userConfigText
+  for (let tableOffset = 0; tableOffset < sotLines.length; tableOffset++) {
+    const managedHeader = tomlTableHeader(sotLines[tableOffset]!)
+    if (managedHeader === undefined) continue
+
     const block: Array<string> = []
-    for (const line of sotLines) {
-      if (line === tableHeader) printing = true
-      else if (printing && line.startsWith("[")) break
-      if (printing) block.push(line)
+    for (let blockOffset = tableOffset; blockOffset < sotLines.length; blockOffset++) {
+      const line = sotLines[blockOffset]!
+      if (blockOffset !== tableOffset && tomlTableHeader(line) !== undefined) break
+      block.push(line)
     }
     const tableBlock = block.join("\n").replace(/\n+$/, "")
 
-    // Remove the existing block from the user config…
-    const userLines = readFileSync(userConfig, "utf8").split("\n")
+    const userLines = merged.split("\n")
     if (userLines[userLines.length - 1] === "") userLines.pop()
     let skip = false
     const kept: Array<string> = []
     for (const line of userLines) {
-      if (line === tableHeader) {
-        skip = true
-        continue
+      const header = tomlTableHeader(line)
+      if (header !== undefined) {
+        skip = header.path === managedHeader.path
+        if (skip) continue
       }
-      if (skip && line.startsWith("[")) skip = false
       if (!skip) kept.push(line)
     }
-    // …and append the SoT block (printf '\n'; printf '%s\n' "$block").
-    const next = `${kept.join("\n")}\n\n${tableBlock}\n`
-    writeFileSync(`${userConfig}.tmp`, next)
-    renameSync(`${userConfig}.tmp`, userConfig)
+    merged = `${kept.join("\n")}\n\n${tableBlock}\n`
   }
+  return merged
+}
+
+function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+  const next = mergeTableSettingsText(sotConfigText, readFileSync(userConfig, "utf8"))
+  writeFileSync(`${userConfig}.tmp`, next)
+  renameSync(`${userConfig}.tmp`, userConfig)
 }
 
 // ------------------------------------------------------- rules + agents ----
@@ -276,7 +394,7 @@ function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir:
   const { change, echo, verbose } = ctx.services.logger
   const firstRule = sotRules[0]
   if (firstRule === undefined) return
-  const firstDisplay = payloadDisplayPath(firstRule, ctx.repoDir)
+  const firstDisplay = payloadDisplayPath(firstRule)
   const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"))
 
   if (ctx.dryRun) {
@@ -306,7 +424,7 @@ function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir:
 
 function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md", ctx.repoDir)
+  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md")
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotAgentsMd} -> ${userAgentsMd}`)
@@ -326,26 +444,32 @@ function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string):
 // ---------------------------------------------------------- marketplace ----
 
 function syncMarketplace(ctx: Ctx, sotMarketplaceText: string, userMarketplace: string): void {
-  const { change, echo, err, verbose } = ctx.services.logger
-  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json", ctx.repoDir)
+  const { change, echo, verbose } = ctx.services.logger
+  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json")
+  const repo = parseJson(sotMarketplaceText)
+  if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
+
+  const userText = existsSync(userMarketplace) ? readFileSync(userMarketplace, "utf8") : undefined
+  const user = userText === undefined ? undefined : parseJson(userText)
+  if (userText !== undefined && user === undefined) {
+    throw new Error(`invalid deployed Codex marketplace JSON: ${userMarketplace}. Fix or delete it.`)
+  }
+  const out = user === undefined ? undefined : jqStringify(mergeMarketplace(repo, user))
 
   if (ctx.dryRun) {
-    echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
+    if (userText === undefined) {
+      echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
+    } else if (out === userText) {
+      verbose("Codex marketplace already in sync")
+    } else {
+      echo(`[dry-run] merge ${sotMarketplace} -> ${userMarketplace} (backup at ${userMarketplace}.bak)`)
+    }
     return
   }
 
   mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true })
-  const repo = parseJson(sotMarketplaceText)
-  if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
-
-  if (existsSync(userMarketplace)) {
-    const user = parseJson(readFileSync(userMarketplace, "utf8"))
-    if (user === undefined) {
-      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")) {
+  if (userText !== undefined && out !== undefined) {
+    if (out === userText) {
       verbose("Codex marketplace already in sync")
       return
     }

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

@@ -5,7 +5,7 @@
  * historical record-oriented behavior.
  */
 import { p } from "./exec"
-import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"
 
 import { resolveEffort } from "../efforts"
 import type { Ctx } from "./index"
@@ -61,17 +61,22 @@ function syncCodexSetting(ctx: Ctx, edit: CodexSettingEdit): void {
   const { change, echo, verbose, warn } = ctx.services.logger
   const userCodexSettings = p(ctx.home, ".codex", "config.toml")
 
-  if (ctx.dryRun) {
-    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
+  if (!existsSync(userCodexSettings)) {
+    // A dry-run sync already previewed installing the file, so the edit is not skipped.
+    // The `docks-kit model codex <m>` command creates no file, so the skip stands.
+    if (ctx.dryRun && ctx.syncCodex) {
+      echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
+      return
+    }
+    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
     return
   }
 
-  try {
-    readFileSync(userCodexSettings)
-  } catch {
-    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
     return
   }
+
   if (replaceTopLevelSettingInFile(userCodexSettings, edit.key, `${edit.key} = "${edit.value}"`)) {
     change(edit.changed)
     ctx.nextStepTriggers.codexRestart = true

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

@@ -2,17 +2,17 @@
  * DependencyManager — one home for external-tool identity, presence probing,
  * and platform-correct install hints (Output Policy in DESIGN.md).
  *
- * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors,
- * pin policy, and managed install/upgrade orchestration; this registry owns
- * WHICH external tools exist, whether they are required, and the one-line
- * command that installs a missing one.
+ * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors, pin
+ * policy, and the doctor report, while bun.ts bunBootstrap owns the one managed
+ * install; this registry owns WHICH external tools exist, whether they are
+ * required, and the one-line command that installs a missing one.
  */
 import { homedir } from "node:os"
 import { isAbsolute } from "node:path"
 
 import { capture, commandExists, p, which } from "./exec"
 import { isObject, parseJson } from "./jq"
-import { rawPlatform } from "./os"
+import { hostOs, platformName, rawPlatform } from "./os"
 
 export type ToolId =
   | "git"
@@ -25,7 +25,6 @@ export type ToolId =
   | "codex"
   | "bun"
   | "bwrap"
-  | "effect-solutions"
   | "ffplay"
   | "intelephense"
   | "typescript-language-server"
@@ -42,11 +41,6 @@ export type ProbeResult =
   | { readonly state: "present"; readonly path?: string }
   | { readonly state: "missing" }
 
-export interface DependencyLocation {
-  readonly path: string
-  readonly binDir: string
-}
-
 export interface ProbeExecutor {
   readonly commandExists: (name: string) => boolean
   readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>
@@ -61,16 +55,12 @@ export interface DependencySpec {
   readonly installHint: (platform?: NodeJS.Platform) => string
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
   readonly version?: (exec: ProbeExecutor) => Promise<string>
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
-  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 interface SpecOptions {
   readonly versionArgs?: ReadonlyArray<string>
   readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult
   readonly version?: (exec: ProbeExecutor) => Promise<string>
-  readonly locate?: (exec: ProbeExecutor, platform: NodeJS.Platform) => Promise<DependencyLocation>
-  readonly latest?: (exec: ProbeExecutor) => Promise<string>
 }
 
 const spec = (
@@ -84,16 +74,17 @@ const spec = (
   versionArgs: options.versionArgs ?? ["--version"],
   installHint,
   resolve: options.resolve,
-  version: options.version,
-  locate: options.locate,
-  latest: options.latest
+  version: options.version
 })
 
+// Presence is the injected executor's verdict; `which` only resolves WHERE the
+// tool is, which on Windows is the `.cmd`/`.exe` candidate rather than the name.
 const pathProbe = (id: string): ((exec: ProbeExecutor) => ProbeResult) =>
-  (exec) =>
-    exec.commandExists(id)
-      ? { state: "present", path: exec.which(id) }
-      : { state: "missing" }
+  (exec) => {
+    if (!exec.commandExists(id)) return { state: "missing" }
+    const path = exec.which(id)
+    return path === "" ? { state: "present" } : { state: "present", path }
+  }
 
 const versionProbe = (
   id: string,
@@ -107,11 +98,11 @@ const home = (): string => {
   return envHome !== undefined && envHome !== "" ? envHome : homedir()
 }
 
-
-// The resolved path gets persisted into global direct-exec hooks, so a
-// relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
-// break outside the sync working directory.
-
+/**
+ * The resolved path gets persisted into global direct-exec hooks, so a
+ * relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
+ * break outside the sync working directory.
+ */
 const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
   const onPath = exec.which("bun")
   if (onPath !== "" && isAbsolute(onPath)) {
@@ -135,33 +126,6 @@ const resolveBun = (exec: ProbeExecutor): ProbeResult => {
     : { state: "present", path: bun.path }
 }
 
-const resolveEffectSolutions = (exec: ProbeExecutor): ProbeResult => {
-  return exec.commandExists("effect-solutions")
-    ? { state: "present", path: exec.which("effect-solutions") }
-    : { state: "missing" }
-}
-
-const versionBunCommand = (exec: ProbeExecutor): string =>
-  exec.commandExists("bun") ? "bun" : p(home(), ".bun", "bin", "bun")
-
-const versionEffectSolutions = async (exec: ProbeExecutor): Promise<string> => {
-  const bun = versionBunCommand(exec)
-  if (bun !== "bun" && exec.which(bun) === "") return ""
-  const match = /effect-solutions@([0-9][0-9.]*)/.exec(await exec.capture(bun, ["pm", "-g", "ls"]))
-  return match?.[1] ?? ""
-}
-
-const locateEffectSolutions = async (exec: ProbeExecutor): Promise<DependencyLocation> => {
-  const strictBun = findBun(exec)
-  const pathBun = exec.which("bun")
-  const bun = strictBun ?? (pathBun !== "" ? { command: "bun", path: pathBun } : undefined)
-  if (bun === undefined) return { path: "", binDir: "" }
-  const globalBin = await exec.capture(bun.command, ["pm", "-g", "bin"])
-  const path = globalBin !== "" ? p(globalBin, "effect-solutions") : ""
-  const resolved = path !== "" && exec.which(path) !== "" ? path : ""
-  return { path: resolved, binDir: globalBin }
-}
-
 const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>()
 
 const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }> => {
@@ -185,31 +149,21 @@ const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }
 const versionNpmGlobal = (pkg: string) => async (exec: ProbeExecutor): Promise<string> =>
   (await npmGlobalVersions(exec))[pkg] ?? ""
 
-const latestNpm = (id: "effect-solutions") => async (exec: ProbeExecutor): Promise<string> =>
-  exec.commandExists("npm") ? await exec.capture("npm", ["view", id, "version"]) : ""
-
 export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which }
 
 export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   git: spec(
     "git",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "darwin"
-        ? "brew install git"
-        : "sudo apt install -y git (or your distro's package manager)",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git"),
     { version: versionProbe("git") }
   ),
-  jq: spec("jq", "optional", (pf = rawPlatform()) =>
-    pf === "darwin"
-      ? "brew install jq"
-      : "sudo apt install -y jq",
-    { version: versionProbe("jq") }
-  ),
-  curl: spec("curl", "optional", (pf = rawPlatform()) =>
-    pf === "darwin" ? "brew install curl" : "sudo apt install -y curl",
-    { version: versionProbe("curl") }
-  ),
+  jq: spec("jq", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq"), {
+    version: versionProbe("jq")
+  }),
+  curl: spec("curl", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl"), {
+    version: versionProbe("curl")
+  }),
   node: spec("node", "optional", () => "install Node.js via https://nodejs.org (or your package manager)", {
     version: versionProbe("node")
   }),
@@ -218,13 +172,13 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
   claude: spec(
     "claude",
     "optional",
-    () => "curl -fsSL https://claude.ai/install.sh -o /tmp/claude-install.sh && bash /tmp/claude-install.sh",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude"),
     { version: versionProbe("claude") }
   ),
   codex: spec(
     "codex",
     "optional",
-    () => 'tmp=$(mktemp) && curl -fsSL https://chatgpt.com/codex/install.sh -o "$tmp" && CODEX_NON_INTERACTIVE=1 sh "$tmp"',
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex"),
     { version: versionProbe("codex") }
   ),
   bun: spec(
@@ -233,24 +187,20 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     () => "curl -fsSL https://bun.sh/install | bash",
     {
       resolve: resolveBun,
-      version: (exec) => exec.capture(versionBunCommand(exec), ["--version"]),
-      locate: async (exec) => ({ path: findBun(exec)?.path ?? "", binDir: "" })
+      version: async (exec) => {
+        const bun = findBun(exec)
+        if (bun === undefined) return ""
+        return await exec.capture(bun.command, ["--version"])
+      }
     }
   ),
   bwrap: spec("bwrap", "optional", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)", {
     version: versionProbe("bwrap")
   }),
-  "effect-solutions": spec("effect-solutions", "optional", () => "bun add -g effect-solutions", {
-    resolve: resolveEffectSolutions,
-    version: versionEffectSolutions,
-    locate: locateEffectSolutions,
-    latest: latestNpm("effect-solutions")
-  }),
   ffplay: spec(
     "ffplay",
     "optional",
-    (pf = rawPlatform()) =>
-      pf === "darwin" ? "brew install ffmpeg" : "sudo apt install -y ffmpeg",
+    (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"),
     { versionArgs: ["-version"], version: versionProbe("ffplay", ["-version"]), resolve: pathProbe("ffplay") }
   ),
   intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
@@ -286,20 +236,11 @@ export async function resolveVersion(specification: DependencySpec, exec: ProbeE
   return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(exec)
 }
 
-export async function resolveLocation(
-  specification: DependencySpec,
-  exec: ProbeExecutor,
-  platform: NodeJS.Platform = rawPlatform()
-): Promise<DependencyLocation> {
-  if (specification.locate !== undefined) return await specification.locate(exec, platform)
-  const result = resolveDependency(specification, exec, platform)
-  return { path: result.state === "present" ? (result.path ?? exec.which(specification.id)) : "", binDir: "" }
-}
-
 export async function resolvePath(
   specification: DependencySpec,
   exec: ProbeExecutor,
-  platform?: NodeJS.Platform
+  platform: NodeJS.Platform = rawPlatform()
 ): Promise<string> {
-  return (await resolveLocation(specification, exec, platform)).path
+  const result = resolveDependency(specification, exec, platform)
+  return result.state === "present" ? (result.path ?? exec.which(specification.id)) : ""
 }