docks-kit 0.1.5 → 0.3.0

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

@@ -4,23 +4,26 @@
  */
 import { p } from "./exec"
 import { readFileSync } from "node:fs"
+import { payloadText } from "../payload"
 
 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 {
+  const { echo, err, warn } = ctx.services.logger
   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 === "--verbose") {
+      ctx.verbose = true
+    } else if (arg === "claude" || arg === "codex") tool = arg
     else if (arg.startsWith("-")) {
       err(`Unknown flag for model: ${arg}`)
       return 2
@@ -39,7 +42,7 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
         return 0
       }
       echo(`deployed: ${jsonModelField(deployed)}`)
-      echo(`SoT:      ${jsonModelField(p(ctx.repoDir, "SoT", ".claude", "settings.json"))}`)
+      echo(`SoT:      ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`)
     } else {
       const deployed = p(ctx.home, ".codex", "config.toml")
       if (!fileReadable(deployed)) {
@@ -47,22 +50,22 @@ export function modeModel(ctx: Ctx, args: ReadonlyArray<string>): number {
         return 0
       }
       echo(`deployed: ${tomlModelField(deployed)}`)
-      echo(`SoT:      ${tomlModelField(p(ctx.repoDir, "SoT", ".codex", "config.toml"))}`)
+      echo(`SoT:      ${tomlModelText(payloadText("SoT/.codex/config.toml"))}`)
     }
-    printModels(ctx.repoDir, tool)
+    printModels(ctx, tool)
     return 0
   }
 
   if (tool === "claude") {
-    if (!validateClaudeModel(ctx.repoDir, value)) {
-      printModels(ctx.repoDir, "claude")
+    if (!validateClaudeModel(ctx, value)) {
+      printModels(ctx, "claude")
       err(`Invalid Claude model '${value}'`)
       return 2
     }
     syncClaudeModel(ctx, value)
   } else {
-    if (!validateCodexModel(ctx.repoDir, value)) {
-      printModels(ctx.repoDir, "codex")
+    if (!validateCodexModel(ctx, value)) {
+      printModels(ctx, "codex")
       err(`Invalid Codex model '${value}'`)
       return 2
     }
@@ -82,7 +85,11 @@ function fileReadable(p: string): boolean {
 
 /** `jq -r '.model // "default (unset)"'` — empty on unparseable input. */
 function jsonModelField(file: string): string {
-  const doc = parseJson(readFileSync(file, "utf8"))
+  return jsonModelText(readFileSync(file, "utf8"))
+}
+
+function jsonModelText(text: string): string {
+  const doc = parseJson(text)
   if (doc === undefined) return ""
   const v: Json | undefined = isObject(doc) ? doc["model"] : undefined
   if (v === undefined || v === null || v === false) return "default (unset)"
@@ -91,17 +98,26 @@ function jsonModelField(file: string): string {
 
 /** `awk -F'"' '/^model[[:space:]]*=/{print $2; exit}'`. */
 function tomlModelField(file: string): string {
-  for (const line of readFileSync(file, "utf8").split("\n")) {
+  return tomlModelText(readFileSync(file, "utf8"))
+}
+
+function tomlModelText(text: string): string {
+  for (const line of text.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] ?? ""
+  const { err } = ctx.services.logger
+  const words = args.filter((a) => !a.startsWith("--"))
+  const op = words[0] ?? args[0] ?? "check"
+  const tool = words[1] ?? args[1] ?? ""
   for (const arg of args) {
     if (arg === "--yes") ctx.assumeYes = true
+    else if (arg === "--verbose") {
+      ctx.verbose = true
+    }
   }
 
   if (op === "check") {
@@ -121,7 +137,7 @@ export function modeToolchain(ctx: Ctx, args: ReadonlyArray<string>): number {
       return ensure(ctx, "rtk", rtkInstall(ctx))
     case "bun":
       // skills::_bun_bootstrap >/dev/null — the found-bun stdout is discarded.
-      return bunBootstrap(ctx) !== "" ? 0 : 1
+      return bunBootstrap(ctx, ctx.services) !== "" ? 0 : 1
     case "effect-solutions":
       return ensure(ctx, "effect-solutions", effectSolutionsInstall(ctx))
     case "agent-browser":

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

@@ -0,0 +1,29 @@
+/**
+ * Platform capability seam (Output Policy in DESIGN.md) — the only engine
+ * module that reads process.platform besides exec.ts's PATH/executability
+ * primitives. Per-tool package identifiers stay in deps.ts; symlink handling
+ * stays try-then-fallback at the call site (capability-driven, not predicted).
+ */
+
+export type PlatformName = "linux" | "darwin" | "windows" | "unknown"
+
+export function rawPlatform(): NodeJS.Platform {
+  return process.platform
+}
+
+export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName {
+  return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : pf === "win32" ? "windows" : "unknown"
+}
+
+export function isWindows(): boolean {
+  return rawPlatform() === "win32"
+}
+
+export function isLinux(): boolean {
+  return rawPlatform() === "linux"
+}
+
+/** Shell-rc exports (bashrc/zshrc) apply only off Windows. */
+export function shellRcApplicable(): boolean {
+  return !isWindows()
+}

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

@@ -4,10 +4,8 @@
  * 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) {
@@ -18,6 +16,7 @@ export class ExitError extends Error {
 const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
 
 function usage(ctx: Ctx): void {
+  const { echo } = ctx.services.logger
   const argv0 = "docks-kit sync"
   echo(`Usage: ${argv0} [claude] [codex] [agents] [flags]`)
   echo("")
@@ -36,6 +35,7 @@ function usage(ctx: Ctx): void {
   )
   echo("  --skip-rtk        skip optional tool bootstrap (RTK, bubblewrap)")
   echo("  --yes             auto-accept toolchain prompts (containers/CI)")
+  echo("  --verbose         also print no-op confirmations (already in sync, up to date, left as-is)")
   echo("")
   echo("Deploy-time modifiers (deployed config only; SoT untouched; a later flag-less sync reverts)")
   echo(
@@ -66,6 +66,7 @@ export function parseCompactWindow(v: string): string | undefined {
 }
 
 function addClaudePlugin(ctx: Ctx, name: string): void {
+  const { err } = ctx.services.logger
   if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
     err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`)
     throw new ExitError(2)
@@ -81,6 +82,7 @@ function selectTarget(ctx: Ctx, target: string): void {
 }
 
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
+  const { err } = ctx.services.logger
   for (const arg of args) {
     switch (arg) {
       case "claude":
@@ -103,12 +105,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
       case "--yes":
         ctx.assumeYes = true
         continue
+      case "--verbose":
+        ctx.verbose = true
+        continue
       case "--claude-model":
-        printModels(ctx.repoDir, "claude")
+        printModels(ctx, "claude")
         err("--claude-model requires a value: --claude-model=<model>")
         throw new ExitError(2)
       case "--codex-model":
-        printModels(ctx.repoDir, "codex")
+        printModels(ctx, "codex")
         err("--codex-model requires a value: --codex-model=<model>")
         throw new ExitError(2)
       case "--claude-compact-window":
@@ -180,32 +185,29 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
 }
 
 export function preflight(ctx: Ctx): void {
+  const { err } = ctx.services.logger
   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}`)
+    if (ctx.services.deps.probe("jq").state === "missing") {
+      err(`jq is required (deployed statusline/hooks call it). Install: ${ctx.services.deps.spec("jq").installHint()}`)
       throw new ExitError(1)
     }
   }
   if (ctx.syncClaude) {
-    if (!commandExists("curl")) {
-      err("curl is required.")
+    if (ctx.services.deps.probe("curl").state === "missing") {
+      err(`curl is required. Install: ${ctx.services.deps.spec("curl").installHint()}`)
       throw new ExitError(1)
     }
   }
 }
 
 export function validateModelFlags(ctx: Ctx): void {
+  const { err, warn } = ctx.services.logger
   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")
+    } else if (!validateClaudeModel(ctx, ctx.claudeModel)) {
+      printModels(ctx, "claude")
       err(`Invalid Claude model '${ctx.claudeModel}' — use an alias above or a full claude-* ID`)
       throw new ExitError(2)
     }
@@ -214,8 +216,8 @@ export function validateModelFlags(ctx: Ctx): void {
     if (!ctx.syncCodex) {
       warn("--codex-model ignored: codex target not selected")
       ctx.codexModel = ""
-    } else if (!validateCodexModel(ctx.repoDir, ctx.codexModel)) {
-      printModels(ctx.repoDir, "codex")
+    } else if (!validateCodexModel(ctx, ctx.codexModel)) {
+      printModels(ctx, "codex")
       err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`)
       throw new ExitError(2)
     }

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

@@ -0,0 +1,96 @@
+/**
+ * Shared service factory — the single construction point for the engine's
+ * injectable capabilities (Output Policy in DESIGN.md). The Effect rim wraps
+ * these in Layers (cli/src/services.ts); the harness-private native-raw entry
+ * and engineCapture's parent-side warn call it directly, so every execution
+ * path shares one implementation.
+ */
+import {
+  DEPENDENCIES,
+  defaultProbeExecutor,
+  resolveDependency,
+  resolveLocation,
+  resolvePath,
+  resolveVersion,
+  type DependencySpec,
+  type DependencyLocation,
+  type ProbeExecutor,
+  type ProbeResult,
+  type ToolId
+} from "./deps"
+import { makeLogger, type Logger, type LoggerSinks } from "./logger"
+import { platformName, rawPlatform, type PlatformName } from "./os"
+
+export type { Logger } from "./logger"
+
+export interface DependencyManager {
+  readonly spec: (id: ToolId) => DependencySpec
+  readonly probe: (id: ToolId) => ProbeResult
+  readonly version: (id: ToolId) => string
+  readonly path: (id: ToolId) => string
+  readonly location: (id: ToolId) => DependencyLocation
+  readonly latest: (id: ToolId) => string
+  readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void
+}
+
+export interface Platform {
+  readonly raw: () => NodeJS.Platform
+  readonly name: () => PlatformName
+  readonly isWindows: () => boolean
+  readonly isLinux: () => boolean
+  readonly shellRcApplicable: () => boolean
+}
+
+export interface EngineServices {
+  readonly logger: Logger
+  readonly deps: DependencyManager
+  readonly platform: Platform
+}
+
+export interface EngineServiceOptions {
+  readonly sinks?: LoggerSinks
+}
+
+/** Platform view over an injectable platform id (tests pass e.g. "win32"). */
+export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
+  raw: () => pf,
+  name: () => platformName(pf),
+  isWindows: () => pf === "win32",
+  isLinux: () => pf === "linux",
+  shellRcApplicable: () => pf !== "win32"
+})
+
+/** DependencyManager whose hints default to the INJECTED platform, not the host. */
+export const makeDependencyManager = (
+  platform: Platform,
+  exec: ProbeExecutor = defaultProbeExecutor
+): DependencyManager => {
+  const warned = new Set<ToolId>()
+  return {
+    spec: (id) => {
+      const s = DEPENDENCIES[id]
+      return { ...s, installHint: (pf = platform.raw()) => s.installHint(pf) }
+    },
+    probe: (id) => resolveDependency(DEPENDENCIES[id], exec, platform.raw()),
+    version: (id) => resolveVersion(DEPENDENCIES[id], exec),
+    path: (id) => resolvePath(DEPENDENCIES[id], exec, platform.raw()),
+    location: (id) => resolveLocation(DEPENDENCIES[id], exec, platform.raw()),
+    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? "",
+    warnMissing: (id, logger, context) => {
+      if (warned.has(id)) return
+      warned.add(id)
+      const suffix = context !== undefined && context !== "" ? ` (${context})` : ""
+      logger.warn(`${id} not installed — ${DEPENDENCIES[id].installHint(platform.raw())}${suffix}`)
+    }
+  }
+}
+
+export const makeEngineServices = (opts?: EngineServiceOptions): EngineServices => {
+  const platform = makePlatform()
+  const logger = makeLogger(opts?.sinks ?? {})
+  return {
+    logger,
+    deps: makeDependencyManager(platform),
+    platform
+  }
+}