docks-kit 0.1.0 → 0.1.2

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

@@ -0,0 +1,63 @@
+/**
+ * jq-semantics primitives for EngineNative.
+ *
+ * Some deployed JSON contracts were defined by jq behavior, so EngineNative
+ * reproduces three jq behaviors exactly:
+ *   - `*` (recursive object merge): right side wins; objects merge
+ *     recursively; arrays and scalars are REPLACED, never concatenated;
+ *     merged key order = left object's order, then right-only keys appended.
+ *   - `unique`: sorts (jq's total order — for our string arrays, Unicode
+ *     codepoint order) and deduplicates.
+ *   - output formatting: 2-space indent, UTF-8 raw, trailing newline.
+ */
+
+export type Json = null | boolean | number | string | Array<Json> | { [key: string]: Json }
+
+export function isObject(v: Json): v is { [key: string]: Json } {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+/** jq `$left * $right`. */
+export function deepMerge(left: Json, right: Json): Json {
+  if (!isObject(left) || !isObject(right)) return right
+  const out: { [key: string]: Json } = { ...left }
+  for (const [k, v] of Object.entries(right)) {
+    const lv = out[k]
+    out[k] = lv !== undefined && isObject(lv) && isObject(v) ? deepMerge(lv, v) : v
+  }
+  return out
+}
+
+/** jq `unique` over an array of strings: codepoint sort + dedup. */
+export function uniqueStrings(arr: Array<string>): Array<string> {
+  return [...new Set(arr)].sort(compareCodepoints)
+}
+
+export function compareCodepoints(a: string, b: string): number {
+  const ia = a[Symbol.iterator]()
+  const ib = b[Symbol.iterator]()
+  for (;;) {
+    const ra = ia.next()
+    const rb = ib.next()
+    if (ra.done && rb.done) return 0
+    if (ra.done) return -1
+    if (rb.done) return 1
+    const ca = ra.value.codePointAt(0)!
+    const cb = rb.value.codePointAt(0)!
+    if (ca !== cb) return ca - cb
+  }
+}
+
+/** jq's default pretty-printer for the documents this kit writes. */
+export function jqStringify(v: Json): string {
+  return `${JSON.stringify(v, null, 2)}\n`
+}
+
+/** jq `empty` validation: parse or null. */
+export function parseJson(text: string): Json | undefined {
+  try {
+    return JSON.parse(text) as Json
+  } catch {
+    return undefined
+  }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Model-catalog helpers: manifest listing plus Claude/Codex model validation.
+ * Message strings are covered by the golden suites.
+ */
+import { p } from "./exec"
+import { readFileSync } from "node:fs"
+
+import { isObject, parseJson, type Json } from "./jq"
+import { warn } from "./output"
+
+function catalog(repoDir: string): Json | undefined {
+  try {
+    return parseJson(readFileSync(p(repoDir, "SoT", "models.json"), "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+function toolEntry(repoDir: string, tool: string): { [k: string]: Json } | undefined {
+  const doc = catalog(repoDir)
+  if (doc === undefined || !isObject(doc)) return undefined
+  const entry = doc[tool]
+  return entry !== undefined && isObject(entry) ? entry : undefined
+}
+
+function modelEntries(repoDir: string, tool: string): Array<{ [k: string]: Json }> {
+  const entry = toolEntry(repoDir, tool)
+  const models = entry?.["models"]
+  return Array.isArray(models) ? models.filter(isObject) : []
+}
+
+export function modelsFromManifest(repoDir: string, tool: string): Array<string> {
+  return modelEntries(repoDir, tool)
+    .map((m) => m["id"])
+    .filter((id): id is string => typeof id === "string")
+}
+
+export function printModels(repoDir: string, tool: string): void {
+  const entry = toolEntry(repoDir, tool)
+  if (entry === undefined) {
+    warn(`Model catalog unavailable (${p(repoDir, "SoT", "models.json")})`)
+    return
+  }
+  const verified = typeof entry["verified"] === "string" ? entry["verified"] : "?"
+  const lines = [`Available ${tool} models (kit-verified ${verified} — SoT/models.json):`]
+  for (const m of modelEntries(repoDir, tool)) {
+    const note = typeof m["note"] === "string" ? `  — ${m["note"]}` : ""
+    lines.push(`  ${String(m["id"] ?? "")}${note}`)
+  }
+  if (tool === "claude") lines.push("  (full claude-* model IDs outside the catalog are accepted with a warning)")
+  if (tool === "codex") lines.push("  (well-formed IDs outside the catalog are accepted with a warning)")
+  process.stderr.write(`${lines.join("\n")}\n`)
+}
+
+export function validateClaudeModel(repoDir: string, m: string): boolean {
+  if (m === "") return false
+  if (modelsFromManifest(repoDir, "claude").includes(m)) return true
+  if (m.startsWith("claude-")) {
+    warn(`Claude model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway`)
+    return true
+  }
+  return false
+}
+
+export function validateCodexModel(repoDir: string, m: string): boolean {
+  if (!/^[A-Za-z0-9._-]+$/.test(m)) return false
+  if (!modelsFromManifest(repoDir, "codex").includes(m)) {
+    warn(
+      `Codex model '${m}' is not in the kit-verified catalog (SoT/models.json) — applying anyway (check ~/.codex/config.toml if Codex rejects it)`
+    )
+  }
+  return true
+}

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

@@ -0,0 +1,133 @@
+/**
+ * Direct modes for `model` and `toolchain`. Same public argv vocabulary,
+ * golden-tested messages, same exit codes.
+ */
+import { p } from "./exec"
+import { readFileSync } from "node:fs"
+
+import { syncClaudeModel } from "./claudeModel"
+import { syncCodexModel } from "./codexToml"
+import type { Ctx } from "./index"
+import { isObject, parseJson, type Json } from "./jq"
+import { printModels, validateClaudeModel, validateCodexModel } from "./models"
+import { echo, err, warn } from "./output"
+import { rtkInstall } from "./claudeSync"
+import { agentBrowserInstall, bunBootstrap, effectSolutionsInstall } from "./skillsSync"
+import { ensure, report } from "./toolchain"
+
+export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
+  let tool = ""
+  let value = ""
+  for (const arg of args) {
+    if (arg === "--dry-run") ctx.dryRun = true
+    else if (arg === "claude" || arg === "codex") tool = arg
+    else if (arg.startsWith("-")) {
+      err(`Unknown flag for model: ${arg}`)
+      return 2
+    } else value = arg
+  }
+  if (tool === "") {
+    err("Usage: model <claude|codex> [value] [--dry-run]")
+    return 2
+  }
+
+  if (value === "") {
+    if (tool === "claude") {
+      const deployed = p(ctx.home, ".claude", "settings.json")
+      if (!fileReadable(deployed)) {
+        warn("~/.claude/settings.json missing")
+        return 0
+      }
+      echo(`deployed: ${jsonModelField(deployed)}`)
+      echo(`SoT:      ${jsonModelField(p(ctx.repoDir, "SoT", ".claude", "settings.json"))}`)
+    } else {
+      const deployed = p(ctx.home, ".codex", "config.toml")
+      if (!fileReadable(deployed)) {
+        warn("~/.codex/config.toml missing")
+        return 0
+      }
+      echo(`deployed: ${tomlModelField(deployed)}`)
+      echo(`SoT:      ${tomlModelField(p(ctx.repoDir, "SoT", ".codex", "config.toml"))}`)
+    }
+    printModels(ctx.repoDir, tool)
+    return 0
+  }
+
+  if (tool === "claude") {
+    if (!validateClaudeModel(ctx.repoDir, value)) {
+      printModels(ctx.repoDir, "claude")
+      err(`Invalid Claude model '${value}'`)
+      return 2
+    }
+    syncClaudeModel(ctx, value)
+  } else {
+    if (!validateCodexModel(ctx.repoDir, value)) {
+      printModels(ctx.repoDir, "codex")
+      err(`Invalid Codex model '${value}'`)
+      return 2
+    }
+    syncCodexModel(ctx, value)
+  }
+  return 0
+}
+
+function fileReadable(p: string): boolean {
+  try {
+    readFileSync(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
+function jsonModelField(file: string): string {
+  const doc = parseJson(readFileSync(file, "utf8"))
+  if (doc === undefined) return ""
+  const v: Json | undefined = isObject(doc) ? doc["model"] : undefined
+  if (v === undefined || v === null || v === false) return "default (unset)"
+  return typeof v === "string" ? v : JSON.stringify(v)
+}
+
+/** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
+function tomlModelField(file: string): string {
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (/^model[ \t]*=/.test(line)) return line.split('"')[1] ?? ""
+  }
+  return ""
+}
+
+export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
+  const op = args[0] ?? "check"
+  const tool = args[1] ?? ""
+  for (const arg of args) {
+    if (arg === "--yes") ctx.assumeYes = true
+  }
+
+  if (op === "check") {
+    report(ctx)
+    return 0
+  }
+  if (op !== "ensure") {
+    err("Usage: toolchain [check|ensure <tool>] [--yes]")
+    return 2
+  }
+  if (tool === "" || tool === "--yes") {
+    err("Usage: toolchain ensure <tool> [--yes]")
+    return 2
+  }
+  switch (tool) {
+    case "rtk":
+      return ensure(ctx, "rtk", rtkInstall(ctx))
+    case "bun":
+      // skills::_bun_bootstrap >/dev/null — the found-bun stdout is discarded.
+      return bunBootstrap(ctx) !== "" ? 0 : 1
+    case "effect-solutions":
+      return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
+    case "agent-browser":
+      return ensure(ctx, "agent-browser", agentBrowserInstall)
+    default:
+      err("toolchain ensure supports managed tools only (rtk, bun, effect-solutions, agent-browser)")
+      return 2
+  }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Shared log/warn/err and dry-run emitters. Prefixes go to stderr with stable
+ * ANSI codes; dry-run lines go to stdout.
+ */
+
+export function log(msg: string): void {
+  process.stderr.write(`\x1b[1;32m[ok]\x1b[0m ${msg}\n`)
+}
+
+export function warn(msg: string): void {
+  process.stderr.write(`\x1b[1;33m[warn]\x1b[0m ${msg}\n`)
+}
+
+export function err(msg: string): void {
+  process.stderr.write(`\x1b[1;31m[err]\x1b[0m ${msg}\n`)
+}
+
+export function echo(line: string): void {
+  process.stdout.write(`${line}\n`)
+}

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

@@ -0,0 +1,223 @@
+/**
+ * EngineNative flag layer: usage / target selection / compact-window parsing /
+ * optional-plugin parsing / model validation / preflight. ExitError mirrors an
+ * early parser exit and is caught once in runEngineNative.
+ */
+
+import { commandExists } from "./exec"
+import type { Ctx } from "./index"
+import { printModels, validateClaudeModel, validateCodexModel } from "./models"
+import { echo, err, warn } from "./output"
+
+export class ExitError extends Error {
+  constructor(readonly code: number) {
+    super(`exit ${code}`)
+  }
+}
+
+const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+
+function usage(ctx: Ctx): void {
+  const argv0 = "docks-kit sync"
+  echo(`Usage: ${argv0} [claude] [codex] [agents] [flags]`)
+  echo("")
+  echo("Targets (positional; default: all three)")
+  echo("  claude            sync the Claude Code SoT")
+  echo("  codex             sync the Codex SoT")
+  echo("  agents            sync universal agent skills")
+  echo("")
+  echo("Global flags")
+  echo("  --dry-run         preview without applying")
+  echo(
+    "  --reconcile       reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)"
+  )
+  echo(
+    "  --prune           uninstall kit-managed installs not in SoT (plugins, marketplaces, skills in SoT/.agents/skills.txt)"
+  )
+  echo("  --skip-rtk        skip optional tool bootstrap (RTK, bubblewrap)")
+  echo("  --yes             auto-accept toolchain prompts (containers/CI)")
+  echo("")
+  echo("Deploy-time modifiers (deployed config only; SoT untouched; a later flag-less sync reverts)")
+  echo(
+    "  --claude-model=<m>            set deployed ~/.claude/settings.json model (aliases: best|opus|fable|sonnet|haiku, full claude-* IDs, or 'default' to unset)"
+  )
+  echo(
+    "  --claude-compact-window=<n>   set deployed autocompact window in tokens (e.g. 680000 or 680k) for disposable sessions"
+  )
+  echo(
+    "  --claude-permissive           empty permissions.ask/deny in deployed settings (sandboxes/containers; unattended commits + pushes)"
+  )
+  echo("  --codex-model=<m>             set deployed ~/.codex/config.toml model (e.g. gpt-5.5)")
+  echo("")
+  echo("Sticky opt-ins (installed + enabled until --prune)")
+  echo(
+    `  --claude-plugin=<name>        opt an optional plugin into this machine (known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}; repeatable)`
+  )
+}
+
+/** common::parse_compact_window — normalized tokens or undefined on junk. */
+export function parseCompactWindow(v: string): string | undefined {
+  if (/[kK]$/.test(v)) {
+    const n = v.slice(0, -1)
+    if (!/^[0-9]+$/.test(n)) return undefined
+    return String(parseInt(n, 10) * 1000)
+  }
+  return /^[0-9]+$/.test(v) ? v : undefined
+}
+
+function addClaudePlugin(ctx: Ctx, name: string): void {
+  if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
+    err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`)
+    throw new ExitError(2)
+  }
+  ctx.claudePlugins.push(name)
+}
+
+function selectTarget(ctx: Ctx, target: string): void {
+  if (target === "claude") ctx.syncClaude = true
+  else if (target === "codex") ctx.syncCodex = true
+  else ctx.syncAgents = true
+  ctx.targetFilterSet = true
+}
+
+export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
+  for (const arg of args) {
+    switch (arg) {
+      case "claude":
+      case "codex":
+      case "agents":
+        selectTarget(ctx, arg)
+        continue
+      case "--dry-run":
+        ctx.dryRun = true
+        continue
+      case "--skip-rtk":
+        ctx.skipRtk = true
+        continue
+      case "--reconcile":
+        ctx.reconcile = true
+        continue
+      case "--prune":
+        ctx.prune = true
+        continue
+      case "--yes":
+        ctx.assumeYes = true
+        continue
+      case "--claude-model":
+        printModels(ctx.repoDir, "claude")
+        err("--claude-model requires a value: --claude-model=<model>")
+        throw new ExitError(2)
+      case "--codex-model":
+        printModels(ctx.repoDir, "codex")
+        err("--codex-model requires a value: --codex-model=<model>")
+        throw new ExitError(2)
+      case "--claude-compact-window":
+        err("--claude-compact-window requires a value: --claude-compact-window=<tokens> (e.g. 680k)")
+        throw new ExitError(2)
+      case "--claude-permissive":
+        ctx.claudePermissive = true
+        continue
+      case "--claude-plugin":
+        err(`--claude-plugin requires a value: --claude-plugin=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`)
+        throw new ExitError(2)
+      case "--claude":
+      case "--codex":
+      case "--agents":
+        err(`${arg} was renamed: pass the target as a word, e.g. 'sync ${arg.slice(2)}'`)
+        throw new ExitError(2)
+      case "--force":
+        err("--force was renamed to --reconcile")
+        throw new ExitError(2)
+      case "--remove-plugins":
+        err("--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)")
+        throw new ExitError(2)
+      case "--680k":
+        err("--680k was renamed to --claude-compact-window=680k")
+        throw new ExitError(2)
+      case "--permissive":
+        err("--permissive was renamed to --claude-permissive")
+        throw new ExitError(2)
+      case "--supabase":
+        err("--supabase was renamed to --claude-plugin=supabase")
+        throw new ExitError(2)
+      case "--n8n":
+        err("--n8n was renamed to --claude-plugin=n8n")
+        throw new ExitError(2)
+      case "--no-rtk":
+        err("--no-rtk was renamed to --skip-rtk")
+        throw new ExitError(2)
+      case "-h":
+      case "--help":
+        usage(ctx)
+        throw new ExitError(0)
+      default:
+        break
+    }
+    if (arg.startsWith("--claude-model=")) {
+      ctx.claudeModel = arg.slice("--claude-model=".length)
+    } else if (arg.startsWith("--codex-model=")) {
+      ctx.codexModel = arg.slice("--codex-model=".length)
+    } else if (arg.startsWith("--claude-compact-window=")) {
+      const parsed = parseCompactWindow(arg.slice("--claude-compact-window=".length))
+      if (parsed === undefined) {
+        err("--claude-compact-window expects a token count (e.g. 680000 or 680k)")
+        throw new ExitError(2)
+      }
+      ctx.claudeCompactWindow = parsed
+    } else if (arg.startsWith("--claude-plugin=")) {
+      addClaudePlugin(ctx, arg.slice("--claude-plugin=".length))
+    } else {
+      err(`Unknown arg: ${arg}`)
+      throw new ExitError(2)
+    }
+  }
+
+  if (!ctx.targetFilterSet) {
+    ctx.syncClaude = true
+    ctx.syncCodex = true
+    ctx.syncAgents = true
+  }
+}
+
+export function preflight(ctx: Ctx): void {
+  if (ctx.syncClaude || ctx.syncCodex) {
+    if (!commandExists("jq")) {
+      const hint = process.platform === "win32"
+        ? "winget install jqlang.jq (then open a new terminal)"
+        : process.platform === "darwin"
+          ? "brew install jq"
+          : "sudo apt install -y jq"
+      err(`jq is required (deployed statusline/hooks call it). Install: ${hint}`)
+      throw new ExitError(1)
+    }
+  }
+  if (ctx.syncClaude) {
+    if (!commandExists("curl")) {
+      err("curl is required.")
+      throw new ExitError(1)
+    }
+  }
+}
+
+export function validateModelFlags(ctx: Ctx): void {
+  if (ctx.claudeModel !== "") {
+    if (!ctx.syncClaude) {
+      warn("--claude-model ignored: claude target not selected")
+      ctx.claudeModel = ""
+    } else if (!validateClaudeModel(ctx.repoDir, ctx.claudeModel)) {
+      printModels(ctx.repoDir, "claude")
+      err(`Invalid Claude model '${ctx.claudeModel}' — use an alias above or a full claude-* ID`)
+      throw new ExitError(2)
+    }
+  }
+  if (ctx.codexModel !== "") {
+    if (!ctx.syncCodex) {
+      warn("--codex-model ignored: codex target not selected")
+      ctx.codexModel = ""
+    } else if (!validateCodexModel(ctx.repoDir, ctx.codexModel)) {
+      printModels(ctx.repoDir, "codex")
+      err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`)
+      throw new ExitError(2)
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * `~/.claude/settings.json` merge helpers. Pure functions take the two parsed
+ * documents and return the merged document; the FS step (backup, tmp+rename,
+ * log line) lives in the sync orchestrator. jq-oracle equivalence is covered by
+ * cli/test/unit/settings.test.ts and deployed behavior by the golden suites.
+ */
+import { deepMerge, isObject, uniqueStrings, type Json } from "./jq"
+
+/** `$user * $repo` — SoT keys win, permissions arrays replaced wholesale. */
+export function reconcileSettings(repo: Json, user: Json): Json {
+  return deepMerge(user, repo)
+}
+
+/**
+ * `($user * $repo)` + permissions.{allow,deny,ask} unioned (user + repo,
+ * `unique` — i.e. codepoint-sorted and deduplicated, matching jq).
+ */
+export function mergeSettings(repo: Json, user: Json): Json {
+  const merged = deepMerge(user, repo)
+  if (!isObject(merged)) return merged
+  const permissions = isObject(merged["permissions"]) ? merged["permissions"] : {}
+  merged["permissions"] = {
+    ...permissions,
+    allow: unionPermissions(user, repo, "allow"),
+    deny: unionPermissions(user, repo, "deny"),
+    ask: unionPermissions(user, repo, "ask")
+  }
+  return merged
+}
+
+function unionPermissions(user: Json, repo: Json, key: string): Array<string> {
+  return uniqueStrings([...permissionArray(user, key), ...permissionArray(repo, key)])
+}
+
+function permissionArray(doc: Json, key: string): Array<string> {
+  if (!isObject(doc)) return []
+  const permissions = doc["permissions"]
+  if (!isObject(permissions)) return []
+  const arr = permissions[key]
+  return Array.isArray(arr) ? arr.filter((x): x is string => typeof x === "string") : []
+}