ddduck 0.1.0 → 0.1.2

package/scripts/lib/skill-installer.mjs

@@ -1,3 +1,14 @@
+/**
+ * Installer for the bundled update-ddduck-specs agent skill, behind `ddduck
+ * install skill`. Selects a host topology from the repository state (codex
+ * .agents/, claude-code .claude/, or shared via symlink), plans create,
+ * upgrade, or no-op against the canonical SKILL.md and the
+ * .ddduck/agent-skills.lock.json lock, and applies the plan with atomic
+ * writes plus rollback of everything touched on failure. Conflicting host
+ * state or a locally modified canonical file refuses with a nextAction
+ * naming the exact path to resolve.
+ */
+
 import {
   lstatSync,
   mkdirSync,
@@ -112,12 +123,22 @@ const installTopologies = [
   },
 ];
 
+/**
+ * Install (or upgrade) the bundled skill into a repository: load, plan, apply.
+ * @param {{repository: string, skillName: string, skillPath: string, packageVersion: string, operations?: object}} options - Repository root, skill identity, bundled asset path, and ddduck version for the lock.
+ * @returns {{action: "create"|"upgrade"|"no-op", skillSha256: string, canonicalPath: string, lockPath: string}} The installation result.
+ */
 export function installSkill(options) {
   const bundle = loadSkillBundle(options);
   const plan = planSkillInstall({ ...options, bundle });
   return applySkillInstall({ ...options, bundle, plan });
 }
 
+/**
+ * Read the bundled skill asset and compute its sha256.
+ * @param {{skillName: string, skillPath: string, operations?: object}} options - Skill name, SKILL.md path, and fs overrides for tests.
+ * @returns {{name: string, bytes: Buffer, sha256: string}} The loaded bundle.
+ */
 export function loadSkillBundle({ skillName, skillPath, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
   if (pathState(skillPath, resolvedOperations).type !== "file") {
@@ -127,6 +148,13 @@ export function loadSkillBundle({ skillName, skillPath, operations = {} }) {
   return { name: skillName, bytes, sha256: sha256(bytes) };
 }
 
+/**
+ * Inspect the repository's lock, canonical file, and host adapters and decide
+ * the action: create, upgrade, or no-op — or throw on conflicting host state,
+ * an incomplete lock, or a locally modified canonical skill.
+ * @param {{repository: string, skillName: string, bundle: {sha256: string}, operations?: object}} options - Repository root, skill name, loaded bundle, and fs overrides.
+ * @returns {{action: string, paths: object, topology: object, adaptersToMaterialize: object[], writeCanonical: boolean}} The install plan for applySkillInstall.
+ */
 export function planSkillInstall({ repository, skillName, bundle, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
   const root = path.resolve(repository);
@@ -149,13 +177,16 @@ export function planSkillInstall({ repository, skillName, bundle, operations = {
       canonical.type === "absent" &&
       resolvedOperations.readdirSync(paths.canonicalDirectory).length > 0
     ) {
-      throw new Error(`Conflicting canonical skill directory: ${paths.canonicalDirectory}`);
+      throw conflictingHostState(
+        `Conflicting canonical skill directory: ${paths.canonicalDirectory}`,
+        paths.canonicalDirectory,
+      );
     }
     if (canonical.type === "absent") {
       return createPlan({ paths, adapters, writeCanonical: true });
     }
     if (canonical.type !== "file" || sha256(resolvedOperations.readFileSync(paths.canonical)) !== bundle.sha256) {
-      throw new Error(`Conflicting canonical skill destination: ${paths.canonical}`);
+      throw conflictingHostState(`Conflicting canonical skill destination: ${paths.canonical}`, paths.canonical);
     }
     return createPlan({ paths, adapters, writeCanonical: false });
   }
@@ -178,6 +209,13 @@ export function planSkillInstall({ repository, skillName, bundle, operations = {
   };
 }
 
+/**
+ * Execute an install plan: atomically write the canonical skill, materialize
+ * host adapters, and write the lock; on failure roll back everything touched
+ * and report any recovery failures in the thrown error.
+ * @param {{packageVersion: string, bundle: {name: string, bytes: Buffer, sha256: string}, plan: object, operations?: object}} options - ddduck version for the lock, loaded bundle, plan from planSkillInstall, and fs overrides.
+ * @returns {{action: string, skillSha256: string, canonicalPath: string, lockPath: string}} The installation result.
+ */
 export function applySkillInstall({ packageVersion, bundle, plan, operations = {} }) {
   const resolvedOperations = { ...defaultOperations, ...operations };
   if (plan.action === "no-op") return installResult("no-op", bundle, plan);
@@ -347,7 +385,18 @@ function expectedAdapters(topology) {
 
 function conflictingHostAdapter({ adapter }, paths) {
   const label = adapter.host === "claude-code" ? "Claude Code" : adapter.host;
-  return new Error(`Conflicting ${label} adapter: ${paths.adapters[adapter.host]}`);
+  return conflictingHostState(
+    `Conflicting ${label} adapter: ${paths.adapters[adapter.host]}`,
+    paths.adapters[adapter.host],
+  );
+}
+
+// Host-state conflicts are environment failures, not input failures: name the
+// pre-existing path the user must resolve instead of the usage hint.
+function conflictingHostState(message, conflictingPath) {
+  const error = new Error(message);
+  error.nextAction = `Move ${conflictingPath} aside or remove it, then re-run ddduck install skill update-ddduck-specs.`;
+  return error;
 }
 
 function atomicWrite(destination, content, operations, touched) {
@@ -392,7 +441,11 @@ function restoreAfterFailure({ plan, originalCanonical, canonicalWritten, materi
 }
 
 function incompleteLock(lockPath) {
-  return new Error(`Incomplete or inconsistent skill lock: ${lockPath}`);
+  const error = new Error(`Incomplete or inconsistent skill lock: ${lockPath}`);
+  // Deleting the lock is safe: the next install rebuilds it from the repository
+  // state, and any canonical mismatch then surfaces as its own conflict.
+  error.nextAction = `Delete ${lockPath}, then re-run ddduck install skill update-ddduck-specs to rebuild it.`;
+  return error;
 }
 
 function locallyModifiedCanonical(canonicalPath) {

package/scripts/query-model.mjs

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 
-import path from "node:path";
+/**
+ * Implements `ddduck query`, the read-only query surface: dispatches the
+ * operations node, neighbors, impact, anchors, spec, and context to
+ * lib/product-query.mjs and lib/context-pack.mjs, emitting exactly one JSON
+ * document on stdout. The product root auto-resolves (enclosing directory,
+ * config, or unique discovery) unless --root is passed; busy or interrupted
+ * roots are refused before any answer is served. Also imported by ddduck.mjs
+ * and the agent-readiness evals as the runQuery entry point.
+ */
+
 import { fileURLToPath } from "node:url";
 import { resolveContextPack } from "./lib/context-pack.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
@@ -14,6 +23,12 @@ import {
 } from "./lib/product-query.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
 
+/**
+ * Parse and run one query invocation, writing the JSON document to stdout.
+ * @param {string[]} args - Arguments after the `query` command word.
+ * @param {{cwd?: string, stdout?: {write: (chunk: string) => unknown}}} [io] - Working directory for root resolution and the output stream (used by the evals harness to capture output).
+ * @returns {void}
+ */
 export function runQuery(args, { cwd = process.cwd(), stdout = process.stdout } = {}) {
   if (args.includes("--help")) {
     stdout.write(renderHelp("query"));
@@ -30,14 +45,10 @@ export function runQuery(args, { cwd = process.cwd(), stdout = process.stdout }
   const ids = options.id;
   const id = ids[0];
   if (operation !== "context" && ids.length > 1) throw new CliUsageError(`query ${operation} accepts exactly one --id`);
-  if (operation === "context") {
-    if (options.history) throw new CliUsageError("query context does not support --history");
-    if (!options.root) throw new CliUsageError("query context requires --root <product-root>");
-  }
+  if (operation === "context" && options.history) throw new CliUsageError("query context does not support --history");
   if (operation !== "spec" && !id) throw new CliUsageError(`query ${operation} requires --id <model-node-id>`);
 
-  const root =
-    operation === "context" ? path.resolve(cwd, options.root) : resolveProductRoot({ cwd, explicitRoot: options.root });
+  const root = resolveProductRoot({ cwd, explicitRoot: options.root });
   const product = loadQueryProduct(root, { history: options.history });
   if (operation === "spec" && id && id !== product.rootModelId) {
     throw new CliUsageError(`query spec --id must be ${product.rootModelId}`);

package/scripts/run-agent-readiness-evals.mjs

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 
+/**
+ * CLI wrapper for the agent-readiness eval harness: reads a JSONL file of eval
+ * records (--input) that each name a product root below --repo-root, a query
+ * to run, and candidate evidence to verify, then delegates to
+ * lib/agent-readiness-evals.mjs. Emits one JSON result document on stdout,
+ * optionally mirrors it to --output (contained below the repo root, never
+ * .git), and exits 1 unless every case passed.
+ */
+
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { format } from "prettier";
 import { runAgentReadinessEvals } from "./lib/agent-readiness-evals.mjs";
 import { resolveContainedOutput } from "./lib/product-paths.mjs";
 
@@ -10,7 +18,9 @@ try {
   const options = parseArgs(process.argv.slice(2));
   const outputTarget = options.output ? resolveOutputPath(options.repoRoot, options.output) : null;
   const result = runAgentReadinessEvals(options);
-  const output = await format(JSON.stringify(result), { parser: "json", printWidth: 120 });
+  // Deterministic serialization with no runtime formatter dependency: the
+  // published package must run without devDependencies.
+  const output = `${JSON.stringify(result, null, 2)}\n`;
   process.stdout.write(output);
   if (outputTarget) writeOutput(outputTarget, output);
   process.exitCode = result.passed ? 0 : 1;
@@ -19,6 +29,12 @@ try {
   process.exitCode = 1;
 }
 
+/**
+ * Parse the --input/--repo-root/--output arguments, rejecting duplicates and
+ * missing values.
+ * @param {string[]} args - Raw CLI arguments.
+ * @returns {{inputPath: string, repoRoot: string, output: string|undefined}} Resolved option paths.
+ */
 function parseArgs(args) {
   const options = {};
   for (let index = 0; index < args.length; index += 1) {

package/skills/update-ddduck-specs/SKILL.md

@@ -10,7 +10,7 @@ Maintain or bootstrap a repository's ddduck product model from evidence visible
 ## Inputs and boundaries
 
 - Resolve the repository root, read all applicable repository instructions, and inspect Git status before analysis.
-- Use an explicitly requested product root; otherwise let ddduck resolve it in its own order: the enclosing product root of the current directory, else the `productRoot` in `.ddduck/config.json`, else the unique discovered product root in the repository. `ddduck query spec` reports the resolved root. Ambiguous resolution is a stop condition: report the candidates and ask; never bootstrap a second product root beside an existing one.
+- Use an explicitly requested product root; otherwise let ddduck resolve it in its own order: the enclosing product root of the current directory, else the `productRoot` in `.ddduck/config.json`, else the unique discovered product root in the repository (the ddduck CLI reference documents the full order, including the example-candidate fallback). `ddduck query spec` reports the resolved root. Ambiguous resolution is a stop condition: report the candidates and ask; never bootstrap a second product root beside an existing one.
 - Default to plan-only. Mutate files only when the current user request explicitly authorizes application, including prose that clearly authorizes the evidence-backed changes. `--root <path>` and `--apply` may be convenient shorthand, but ordinary prose must work.
 - Preserve unrelated and uncommitted work. Stop when intended target files overlap user changes inseparably.
 - Write only `<root>/product.yaml`, `<root>/model/**`, `<root>/decisions/**`, and regenerated `<root>/generated/**`.