docks-kit 0.17.0 → 0.17.2

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

@@ -0,0 +1,222 @@
+/**
+ * Modifier and effort mapping for the EngineNative flag layer: deploy-time
+ * modifier metadata, scalar-modifier setters, compact-window and opt-in
+ * plugin parsing, and post-parse modifier validation. Pure apart from the
+ * injected ctx seam; help output and the early-exit error come from
+ * parseHelp.ts.
+ */
+
+import type { Ctx, ModifierFlag } from "./index";
+import type { ScalarModifierFlag } from "./sharedTypes";
+import {
+  CLAUDE_ADVISOR_STATES,
+  advisorCatalog,
+  advisorValueGrammar,
+  effortCatalog,
+  effortValueGrammar,
+  isEffortModifierValue,
+} from "../efforts";
+import { printModels, validateClaudeModel, validateCodexModel } from "./models";
+import { ExitError, printCatalog } from "./parseHelp";
+
+export const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"];
+
+interface ModifierMetadata {
+  readonly target: "claude" | "codex";
+  readonly ignoredWarning: string;
+  readonly hasValue: (ctx: Ctx) => boolean;
+  readonly clear: (ctx: Ctx) => void;
+}
+
+const MODIFIER_METADATA = {
+  "--claude-model": {
+    target: "claude",
+    ignoredWarning: "--claude-model ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeModel !== "",
+    clear: (ctx) => {
+      ctx.claudeModel = "";
+    },
+  },
+  "--claude-effort": {
+    target: "claude",
+    ignoredWarning: "--claude-effort ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeEffort !== "",
+    clear: (ctx) => {
+      ctx.claudeEffort = "";
+    },
+  },
+  "--claude-advisor": {
+    target: "claude",
+    ignoredWarning: "--claude-advisor ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeAdvisor !== "",
+    clear: (ctx) => {
+      ctx.claudeAdvisor = "";
+    },
+  },
+  "--claude-compact-window": {
+    target: "claude",
+    ignoredWarning: "--claude-compact-window ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudeCompactWindow !== "",
+    clear: (ctx) => {
+      ctx.claudeCompactWindow = "";
+    },
+  },
+  "--claude-permissive": {
+    target: "claude",
+    ignoredWarning: "--claude-permissive ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePermissive,
+    clear: (ctx) => {
+      ctx.claudePermissive = false;
+    },
+  },
+  "--claude-plugin": {
+    target: "claude",
+    ignoredWarning: "--claude-plugin ignored: claude target not selected",
+    hasValue: (ctx) => ctx.claudePlugins.length > 0,
+    clear: (ctx) => {
+      ctx.claudePlugins = [];
+    },
+  },
+  "--codex-model": {
+    target: "codex",
+    ignoredWarning: "--codex-model ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexModel !== "",
+    clear: (ctx) => {
+      ctx.codexModel = "";
+    },
+  },
+  "--codex-effort": {
+    target: "codex",
+    ignoredWarning: "--codex-effort ignored: codex target not selected",
+    hasValue: (ctx) => ctx.codexEffort !== "",
+    clear: (ctx) => {
+      ctx.codexEffort = "";
+    },
+  },
+} satisfies Record<ModifierFlag, ModifierMetadata>;
+
+export type { ScalarModifierFlag };
+
+const SCALAR_MODIFIER_FLAGS: Record<ScalarModifierFlag, true> = {
+  "--claude-model": true,
+  "--claude-effort": true,
+  "--claude-advisor": true,
+  "--codex-model": true,
+  "--codex-effort": true,
+};
+
+/** 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;
+}
+
+export function parseClaudePlugin(name: string, err: (message: string) => void): string {
+  if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
+    err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`);
+    throw new ExitError(2);
+  }
+  return name;
+}
+
+export function markModifier(ctx: Ctx, flag: ModifierFlag): void {
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>();
+  flags.add(flag);
+  ctx.modifierFlags = flags;
+}
+
+export function addClaudePlugin(ctx: Ctx, name: string): void {
+  if (name === "") {
+    printCatalog(
+      ctx,
+      `Available Claude optional plugins:\n${KNOWN_CLAUDE_OPTIN_PLUGINS.map((plugin) => `  ${plugin}`).join("\n")}`,
+    );
+    ctx.services.logger.err(
+      `Invalid Claude plugin '' — valid: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}`,
+    );
+    throw new ExitError(2);
+  }
+  ctx.claudePlugins.push(parseClaudePlugin(name, ctx.services.logger.err));
+  markModifier(ctx, "--claude-plugin");
+}
+
+export function setModifier(ctx: Ctx, flag: ScalarModifierFlag, value: string): void {
+  switch (flag) {
+    case "--claude-model":
+      ctx.claudeModel = value;
+      break;
+    case "--claude-effort":
+      ctx.claudeEffort = value;
+      break;
+    case "--claude-advisor":
+      ctx.claudeAdvisor = value;
+      break;
+    case "--codex-model":
+      ctx.codexModel = value;
+      break;
+    case "--codex-effort":
+      ctx.codexEffort = value;
+      break;
+  }
+  markModifier(ctx, flag);
+}
+
+export function isScalarModifierFlag(value: string): value is ScalarModifierFlag {
+  return SCALAR_MODIFIER_FLAGS[value as ScalarModifierFlag] === true;
+}
+
+export function validateModifierFlags(ctx: Ctx): void {
+  const { err, warn } = ctx.services.logger;
+  const supplied = (flag: ModifierFlag): boolean =>
+    MODIFIER_METADATA[flag].hasValue(ctx) || ctx.modifierFlags?.has(flag) === true;
+
+  for (const flag of Object.keys(MODIFIER_METADATA) as Array<ModifierFlag>) {
+    const metadata = MODIFIER_METADATA[flag];
+    const targetSelected = metadata.target === "claude" ? ctx.syncClaude : ctx.syncCodex;
+    if (!targetSelected && supplied(flag)) {
+      warn(metadata.ignoredWarning);
+      metadata.clear(ctx);
+      ctx.modifierFlags?.delete(flag);
+    }
+  }
+
+  if (supplied("--claude-model")) {
+    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);
+    }
+  }
+  if (supplied("--claude-effort")) {
+    if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
+      printCatalog(ctx, effortCatalog("claude"));
+      err(`Invalid Claude effort '${ctx.claudeEffort}' — valid: ${effortValueGrammar("claude")}`);
+      throw new ExitError(2);
+    }
+  }
+  if (supplied("--claude-advisor")) {
+    if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
+      printCatalog(ctx, advisorCatalog());
+      err(`Invalid Claude advisor state '${ctx.claudeAdvisor}' — valid: ${advisorValueGrammar()}`);
+      throw new ExitError(2);
+    }
+  }
+  if (supplied("--codex-model")) {
+    if (!validateCodexModel(ctx, ctx.codexModel)) {
+      printModels(ctx, "codex");
+      err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`);
+      throw new ExitError(2);
+    }
+  }
+  if (supplied("--codex-effort")) {
+    if (!isEffortModifierValue("codex", ctx.codexEffort)) {
+      printCatalog(ctx, effortCatalog("codex"));
+      err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`);
+      throw new ExitError(2);
+    }
+  }
+}

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

@@ -14,71 +14,71 @@ import {
   type DependencySpec,
   type ProbeExecutor,
   type ProbeResult,
-  type ToolId
-} from "./deps"
-import { makeLogger, type Logger, type LoggerSinks } from "./logger"
-import { platformName, rawPlatform, type PlatformName } from "./os"
+  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 type { Logger } from "./logger";
 
 export interface DependencyManager {
-  readonly spec: (id: ToolId) => DependencySpec
-  readonly probe: (id: ToolId) => ProbeResult
-  readonly version: (id: ToolId) => Promise<string>
-  readonly path: (id: ToolId) => Promise<string>
-  readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void
+  readonly spec: (id: ToolId) => DependencySpec;
+  readonly probe: (id: ToolId) => ProbeResult;
+  readonly version: (id: ToolId) => Promise<string>;
+  readonly path: (id: ToolId) => Promise<string>;
+  readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void;
 }
 
 export interface Platform {
-  readonly raw: () => NodeJS.Platform
-  readonly name: () => PlatformName
+  readonly raw: () => NodeJS.Platform;
+  readonly name: () => PlatformName;
 }
 
 export interface EngineServices {
-  readonly logger: Logger
-  readonly deps: DependencyManager
-  readonly platform: Platform
+  readonly logger: Logger;
+  readonly deps: DependencyManager;
+  readonly platform: Platform;
 }
 
 export interface EngineServiceOptions {
-  readonly sinks?: LoggerSinks
+  readonly sinks?: LoggerSinks;
 }
 
 /** Platform view over an injectable platform id. */
 export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
   raw: () => pf,
-  name: () => platformName(pf)
-})
+  name: () => platformName(pf),
+});
 
 /** DependencyManager whose hints default to the INJECTED platform, not the host. */
 export const makeDependencyManager = (
   platform: Platform,
-  exec: ProbeExecutor = defaultProbeExecutor
+  exec: ProbeExecutor = defaultProbeExecutor,
 ): DependencyManager => {
-  const warned = new Set<ToolId>()
+  const warned = new Set<ToolId>();
   return {
     spec: (id) => {
-      const s = DEPENDENCIES[id]
-      return { ...s, installHint: (pf = platform.raw()) => s.installHint(pf) }
+      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()),
     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}`)
-    }
-  }
-}
+      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 ?? {})
+  const platform = makePlatform();
+  const logger = makeLogger(opts?.sinks ?? {});
   return {
     logger,
     deps: makeDependencyManager(platform),
-    platform
-  }
-}
+    platform,
+  };
+};

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

@@ -4,11 +4,11 @@
  * 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"
+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)
+  return deepMerge(user, repo);
 }
 
 /**
@@ -16,27 +16,27 @@ export function reconcileSettings(repo: Json, user: Json): Json {
  * `unique` — i.e. codepoint-sorted and deduplicated, matching jq).
  */
 export function mergeSettings(repo: Json, user: Json): Json {
-  const candidate = deepMerge(user, repo)
-  if (!isObject(candidate)) return candidate
-  const merged = { ...candidate }
-  const permissions = isObject(merged["permissions"]) ? merged["permissions"] : {}
+  const candidate = deepMerge(user, repo);
+  if (!isObject(candidate)) return candidate;
+  const merged = { ...candidate };
+  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
+    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)])
+  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") : []
+  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") : [];
 }

package/cli/src/engine-native/sharedTypes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * EngineNative shared shapes: each cross-cutting data shape is defined once
+ * here so pipelines import one canonical definition instead of redeclaring
+ * structurally identical anonymous types. Types only — no runtime code.
+ */
+import type { Json } from "./jq";
+import type { ModifierFlag } from "./engineCtx";
+
+/** Manifest-record object: the `{ [key]: Json }` shape redeclared across manifest readers. */
+export type JsonObject = { [key: string]: Json };
+
+/**
+ * Shared core of per-tool settings-edit descriptors (Claude JSON modifiers,
+ * Codex TOML passes). Each tool narrows `key` to its own vocabulary and keeps
+ * tool-only fields (such as Claude's dry-run preview) on its local extension.
+ */
+export interface SettingEdit<TKey extends string> {
+  readonly tag: string;
+  readonly key: TKey;
+  readonly value: string | undefined;
+  readonly changed: string;
+  readonly unchanged: string;
+}
+
+/**
+ * omp session model (moved from harnesses.ts, which re-exports it so existing
+ * import paths keep working).
+ */
+export interface OmpSessionModel {
+  readonly selector: string;
+  // Session ceiling; absent when the model publishes no ladder, so no
+  // invented level ever reaches a selector that omp must resolve.
+  readonly thinking?: string;
+  // Advisor level; absent when the model publishes no ladder.
+  readonly advisorThinking?: string;
+}
+
+/**
+ * Scalar modifier flags: the ModifierFlag subset taking a value through
+ * setModifier. Derived by exclusion so a new ModifierFlag forces an explicit
+ * scalar/non-scalar decision here.
+ */
+export type ScalarModifierFlag = Exclude<
+  ModifierFlag,
+  "--claude-compact-window" | "--claude-permissive" | "--claude-plugin"
+>;

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

@@ -0,0 +1,105 @@
+/**
+ * EngineNative universal-skill install pass (`npx skills@<pin> add`) with
+ * Claude symlink healing. Split from skillsSync.ts; the orchestration still
+ * lives there. The prune pass (skillsPrune.ts) shares `skillsCli`.
+ */
+import { p, spawnProcess } from "./exec";
+import type { Ctx } from "./index";
+import { ExitError } from "./parseArgs";
+import { healClaudeSymlink, isDir } from "./skillsLinks";
+import { normalizeManifest } from "./skillsManifest";
+import { field } from "./toolchain";
+
+export interface SkillsState {
+  present: number;
+}
+
+/** skills::_skills_cli — the pinned npx package spec. */
+export function skillsCli(ctx: Ctx): string {
+  const version = field("skills-cli", "verified");
+  if (version !== "") return `skills@${version}`;
+  ctx.services.logger.err(
+    "Universal skills sync aborted because SoT/toolchain.json has no verified skills-cli pin",
+  );
+  throw new ExitError(1);
+}
+
+export async function syncUniversal(
+  ctx: Ctx,
+  state: SkillsState,
+  skillsDir: string,
+  manifest: string,
+): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
+  if (ctx.services.deps.probe("npx").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "npx",
+      ctx.services.logger,
+      "skipping universal skills bootstrap",
+    );
+    return;
+  }
+
+  let added = 0;
+  let already = 0;
+  let failed = 0;
+  let healed = 0;
+
+  for (const slug of normalizeManifest(manifest)) {
+    const base = slug.slice(slug.lastIndexOf("/") + 1);
+
+    if (ctx.dryRun) {
+      if (isDir(p(skillsDir, base))) {
+        echo(`[dry-run] universal skill present: ${base}`);
+        healClaudeSymlink(ctx, skillsDir, base);
+      } else {
+        echo(`[dry-run] npx ${skillsCli(ctx)} add ${slug} -g -y -a claude-code codex`);
+      }
+      continue;
+    }
+
+    if (isDir(p(skillsDir, base))) {
+      already++;
+      if (healClaudeSymlink(ctx, skillsDir, base)) healed++;
+      continue;
+    }
+
+    progress(`Installing universal skill ${slug}...`);
+    const res = await spawnProcess(
+      "npx",
+      ["--yes", skillsCli(ctx), "add", slug, "-g", "-y", "-a", "claude-code", "codex"],
+      {
+        stdio: "ignore",
+      },
+    );
+    clearProgress();
+    if (res.error === undefined && res.exitCode === 0) {
+      added++;
+    } else {
+      warn(`Failed to install universal skill: ${slug}`);
+      failed++;
+    }
+  }
+
+  if (ctx.dryRun) return;
+
+  state.present = added + already;
+
+  if (added > 0) {
+    change(`Universal skills synced (+${added} new, ${already} already present)`);
+    ctx.nextStepTriggers.skillsRestart = true;
+  } else {
+    verbose(`Universal skills already in sync (${already} present)`);
+  }
+  if (healed > 0) {
+    change(
+      `Claude per-tool symlinks healed (+${healed}) — canonical present, ~/.claude/skills/<name> was missing or broken`,
+    );
+    ctx.nextStepTriggers.skillsRestart = true;
+  }
+  if (failed > 0) {
+    warn(
+      `${failed} skill install(s) failed — re-run sync or install manually with: npx skills add <slug> -g -y -a claude-code codex`,
+    );
+  }
+}