agent-method 1.5.13 → 1.5.15

package/docs/internal/doc-tokens.yaml

@@ -30,7 +30,7 @@ tokens:
   watcher_start: "npx agent-method watch"
   project_name: "wwa"
   repo_url: "https://github.com/anthropics/wwa.git"
-  npm_version: "1.5.1"
+  npm_version: "1.5.14"
   registry_version: "v1.6"
   feature_count: 36
   domain_count: 8

package/lib/cli/add.js

@@ -24,25 +24,172 @@ function readStdin() {
   });
 }
 
+/**
+ * Core implementation for `wwa add` and MCP write-safe tools.
+ * Returns a structured result instead of printing or exiting.
+ */
+export async function runAdd(type, content, options = {}) {
+  const dir = resolve(options.directory || ".");
+  const dryRun = options.dryRun || false;
+
+  if (!ADD_TYPES.includes(type)) {
+    const error = new Error(
+      `Unknown type: ${type}. Use one of: ${ADD_TYPES.join(", ")}`
+    );
+    error.code = "INVALID_TYPE";
+    throw error;
+  }
+
+  if (!content || !content.trim()) {
+    const error = new Error("Content is required for add operation.");
+    error.code = "NO_CONTENT";
+    throw error;
+  }
+
+  let targetPath;
+  let toAppend;
+
+  switch (type) {
+    case "backlog": {
+      targetPath = join(dir, "todos", "backlog.md");
+      if (!existsSync(join(dir, "todos"))) {
+        targetPath = join(dir, "backlog.md");
+      }
+      if (!existsSync(targetPath)) {
+        targetPath = join(dir, "todos", "backlog.md");
+      }
+      const title = content.includes(" — ") ? content.split(" — ")[0].trim() : content;
+      const rest = content.includes(" — ")
+        ? content.split(" — ").slice(1).join(" — ").trim()
+        : "";
+      toAppend = `\n- [ ] **${title}**${rest ? ` — ${rest}` : ""}\n`;
+      break;
+    }
+    case "decision": {
+      targetPath = join(dir, "STATE.md");
+      const parts = content.includes(" | ")
+        ? content.split(" | ").map((s) => s.trim())
+        : [content, ""];
+      const decision = parts[0];
+      const rationale = parts[1] || "";
+      toAppend = `\n| ${today()} | ${decision} | ${rationale} |\n`;
+      break;
+    }
+    case "finding": {
+      const reviewDir = join(dir, "docs", "internal", "review");
+      const findingsPath = join(reviewDir, "findings.md");
+      const fallbackPath = join(reviewDir, "installation-improvements.md");
+      if (existsSync(findingsPath)) {
+        targetPath = findingsPath;
+      } else if (existsSync(fallbackPath)) {
+        targetPath = fallbackPath;
+      } else {
+        targetPath = findingsPath;
+        if (!existsSync(join(dir, "docs", "internal", "review"))) {
+          const alt = join(dir, "agentWorkflows", "observations.md");
+          targetPath = existsSync(join(dir, "agentWorkflows")) ? alt : findingsPath;
+        }
+      }
+      toAppend = `\n### ${today()}\n\n- ${content}\n\n`;
+      break;
+    }
+    case "session": {
+      const sessionLog = findSessionLog(dir) || join(dir, "SESSION-LOG.md");
+      targetPath = sessionLog;
+      toAppend = content.endsWith("\n") ? content : content + "\n";
+      break;
+    }
+    case "summary": {
+      targetPath = join(dir, "SUMMARY.md");
+      toAppend = content.endsWith("\n") ? content : content + "\n";
+      break;
+    }
+    default: {
+      const error = new Error(`Unsupported add type: ${type}`);
+      error.code = "INVALID_TYPE";
+      throw error;
+    }
+  }
+
+  if (!isSafeToWrite(targetPath)) {
+    const error = new Error(
+      `Safety: refusing to write to ${targetPath} (only .md, .yaml, .yml allowed).`
+    );
+    error.code = "UNSAFE_TARGET";
+    throw error;
+  }
+
+  if (dryRun) {
+    return {
+      directory: dir,
+      type,
+      target: targetPath,
+      content: toAppend,
+      dryRun: true,
+      wrote: false,
+    };
+  }
+
+  const dirToEnsure = resolve(targetPath, "..");
+  if (!existsSync(dirToEnsure)) {
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(dirToEnsure, { recursive: true });
+  }
+
+  if (!existsSync(targetPath)) {
+    if (type !== "finding") {
+      const error = new Error(
+        `File not found: ${targetPath}. Create it first or run from project root.`
+      );
+      error.code = "MISSING_TARGET";
+      throw error;
+    }
+    // For findings, create a new file with header.
+    safeWriteFile(
+      targetPath,
+      `# Findings\n\n<!-- Appended by wwa add finding -->\n${toAppend}`
+    );
+    remindCascade(dir);
+    return {
+      directory: dir,
+      type,
+      target: targetPath,
+      content: toAppend,
+      dryRun: false,
+      wrote: true,
+      createdFile: true,
+    };
+  }
+
+  const existing = readFileSync(targetPath, "utf-8");
+  safeWriteFile(targetPath, existing + toAppend);
+  remindCascade(dir);
+  return {
+    directory: dir,
+    type,
+    target: targetPath,
+    content: toAppend,
+    dryRun: false,
+    wrote: true,
+    createdFile: false,
+  };
+}
+
 export function register(program) {
   program
     .command("add <type> [content...]")
-    .description("Append content to methodology files (backlog, decision, finding, session, summary)")
+    .description(
+      "Append content to methodology files (backlog, decision, finding, session, summary)"
+    )
     .option("-d, --directory <path>", "Project directory", ".")
     .option("--file <path>", "Read content from file (for session/summary)")
     .option("--dry-run", "Show what would be written without writing")
     .option("--json", "Output target path and content as JSON")
     .action(async (type, contentParts, opts) => {
       const dir = resolve(opts.directory);
-      const dryRun = opts.dryRun || false;
       const asJson = opts.json || false;
-
-      if (!ADD_TYPES.includes(type)) {
-        console.error(`Unknown type: ${type}. Use one of: ${ADD_TYPES.join(", ")}`);
-        process.exit(1);
-      }
-
       let content;
+
       if (opts.file) {
         const fpath = resolve(opts.file);
         if (!existsSync(fpath)) {
@@ -63,101 +210,28 @@ export function register(program) {
         process.exit(1);
       }
 
-      let targetPath;
-      let toAppend;
-
-      switch (type) {
-        case "backlog": {
-          targetPath = join(dir, "todos", "backlog.md");
-          if (!existsSync(join(dir, "todos"))) {
-            targetPath = join(dir, "backlog.md");
-          }
-          if (!existsSync(targetPath)) {
-            targetPath = join(dir, "todos", "backlog.md");
-          }
-          const title = content.includes(" — ") ? content.split(" — ")[0].trim() : content;
-          const rest = content.includes(" — ") ? content.split(" — ").slice(1).join(" — ").trim() : "";
-          toAppend = `\n- [ ] **${title}**${rest ? ` — ${rest}` : ""}\n`;
-          break;
-        }
-        case "decision": {
-          targetPath = join(dir, "STATE.md");
-          const parts = content.includes(" | ") ? content.split(" | ").map((s) => s.trim()) : [content, ""];
-          const decision = parts[0];
-          const rationale = parts[1] || "";
-          toAppend = `\n| ${today()} | ${decision} | ${rationale} |\n`;
-          break;
-        }
-        case "finding": {
-          const reviewDir = join(dir, "docs", "internal", "review");
-          const findingsPath = join(reviewDir, "findings.md");
-          const fallbackPath = join(reviewDir, "installation-improvements.md");
-          if (existsSync(findingsPath)) {
-            targetPath = findingsPath;
-          } else if (existsSync(fallbackPath)) {
-            targetPath = fallbackPath;
-          } else {
-            targetPath = findingsPath;
-            if (!existsSync(join(dir, "docs", "internal", "review"))) {
-              const alt = join(dir, "agentWorkflows", "observations.md");
-              targetPath = existsSync(join(dir, "agentWorkflows")) ? alt : findingsPath;
-            }
-          }
-          toAppend = `\n### ${today()}\n\n- ${content}\n\n`;
-          break;
-        }
-        case "session": {
-          const sessionLog = findSessionLog(dir) || join(dir, "SESSION-LOG.md");
-          targetPath = sessionLog;
-          toAppend = content.endsWith("\n") ? content : content + "\n";
-          break;
-        }
-        case "summary": {
-          targetPath = join(dir, "SUMMARY.md");
-          toAppend = content.endsWith("\n") ? content : content + "\n";
-          break;
-        }
-        default:
-          process.exit(1);
-      }
-
-      if (!isSafeToWrite(targetPath)) {
-        console.error(`Safety: refusing to write to ${targetPath} (only .md, .yaml, .yml allowed).`);
-        process.exit(1);
-      }
+      try {
+        const result = await runAdd(type, content, {
+          directory: dir,
+          dryRun: opts.dryRun || false,
+        });
 
-      if (dryRun || asJson) {
         if (asJson) {
-          console.log(JSON.stringify({ target: targetPath, content: toAppend, dryRun }, null, 2));
-        } else {
-          console.log("Target:", targetPath);
-          console.log("Content to append:");
-          console.log(toAppend);
+          console.log(JSON.stringify(result, null, 2));
+          return;
         }
-        return;
-      }
 
-      const dirToEnsure = resolve(targetPath, "..");
-      if (!existsSync(dirToEnsure)) {
-        const { mkdirSync } = await import("node:fs");
-        mkdirSync(dirToEnsure, { recursive: true });
-      }
-
-      if (!existsSync(targetPath)) {
-        if (type === "finding") {
-          safeWriteFile(targetPath, `# Findings\n\n<!-- Appended by wwa add finding -->\n${toAppend}`);
-          console.log("Appended to", targetPath);
-          remindCascade(dir);
-          return;
+        if (result.dryRun) {
+          console.log("Target:", result.target);
+          console.log("Content to append:");
+          console.log(result.content);
+        } else {
+          console.log("Appended to", result.target);
         }
-        console.error(`File not found: ${targetPath}. Create it first or run from project root.`);
+      } catch (e) {
+        console.error(e.message);
         process.exit(1);
       }
-
-      const existing = readFileSync(targetPath, "utf-8");
-      safeWriteFile(targetPath, existing + toAppend);
-      console.log("Appended to", targetPath);
-      remindCascade(dir);
     });
 }
 

package/lib/cli/casestudy.js

@@ -15,6 +15,133 @@ import { resolveTokensPath, resolveDocsMapPath } from "../boundaries.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+export async function runCasestudy(directory, opts = {}) {
+  const dir = resolve(directory || ".");
+  const options = {
+    output: opts.output || null,
+    name: opts.name || null,
+    json: !!opts.json,
+    yamlOnly: !!opts.yamlOnly,
+    internalRegistry: !!opts.internalRegistry,
+  };
+
+  // Gather all project data
+  const data = await gatherProjectData(dir, options.name);
+
+  // Load internal registry if requested
+  if (options.internalRegistry) {
+    const { loadInternalRegistry } = await import("./doc-review.js");
+    const registry = await loadInternalRegistry(dir);
+    if (registry) {
+      data.internalRegistry = registry;
+    } else {
+      data.warnings.push(
+        "No docs/internal/doc-registry.yaml found — run `wwa doc-review` to generate it"
+      );
+    }
+  }
+
+  if (data.errors.length > 0 && data.sessions.length === 0) {
+    const error = new Error(
+      "Cannot generate case study: " + data.errors.map((e) => `- ${e}`).join(" ")
+    );
+    error.details = { errors: data.errors };
+    throw error;
+  }
+
+  // JSON-only path (no writes unless output is specified)
+  if (options.json) {
+    const resultJson = JSON.stringify(data, null, 2);
+    if (options.output) {
+      safeWriteFile(options.output, resultJson);
+      return {
+        mode: "json_to_file",
+        output: options.output,
+        sessions: data.sessions.length,
+        warnings: data.warnings,
+      };
+    }
+    return {
+      mode: "json_inline",
+      data,
+      warnings: data.warnings,
+    };
+  }
+
+  const created = {
+    mode: options.yamlOnly ? "yaml_only" : "markdown_plus_yaml",
+    markdownPath: null,
+    yamlPath: null,
+    sessions: data.sessions.length,
+    warnings: data.warnings,
+  };
+
+  // YAML-only mode: write a single .yaml artifact with all structured data.
+  if (options.yamlOnly) {
+    const baseDir = join(dir, "case-studies");
+    const baseSlug = slugify(data.projectName);
+    let yamlOutputPath = options.output || join(baseDir, `${baseSlug}.yaml`);
+
+    // Avoid overwriting existing case studies when using the default path.
+    if (!options.output) {
+      let counter = 1;
+      while (existsSync(yamlOutputPath)) {
+        yamlOutputPath = join(baseDir, `${baseSlug}-${counter}.yaml`);
+        counter += 1;
+      }
+    }
+
+    const yamlDir = resolve(yamlOutputPath, "..");
+    if (!existsSync(yamlDir)) {
+      mkdirSync(yamlDir, { recursive: true });
+    }
+
+    const ok = await writeCaseStudyYaml(yamlOutputPath, data);
+    if (!ok) {
+      const error = new Error("Failed to write YAML case study.");
+      error.details = { target: yamlOutputPath };
+      throw error;
+    }
+
+    created.yamlPath = yamlOutputPath;
+    return created;
+  }
+
+  // Default: write markdown case study plus companion YAML.
+  const baseDir = join(dir, "case-studies");
+  const baseSlug = slugify(data.projectName);
+  let markdownPath = options.output || join(baseDir, `${baseSlug}.md`);
+
+  // Avoid overwriting existing case studies when using the default path.
+  if (!options.output) {
+    let counter = 1;
+    while (existsSync(markdownPath)) {
+      markdownPath = join(baseDir, `${baseSlug}-${counter}.md`);
+      counter += 1;
+    }
+  }
+
+  const outputDir = resolve(markdownPath, "..");
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const caseStudy = generateCaseStudy(data);
+  safeWriteFile(markdownPath, caseStudy);
+
+  const yamlPath = markdownPath.replace(/\.md$/, ".yaml");
+  const yamlResult = await writeCaseStudyYaml(yamlPath, data);
+  if (!yamlResult) {
+    const error = new Error("Failed to write companion YAML case study.");
+    error.details = { markdownPath, yamlPath };
+    throw error;
+  }
+
+  created.markdownPath = markdownPath;
+  created.yamlPath = yamlPath;
+  return created;
+}
+
 export function register(program) {
   program
     .command("casestudy [directory]")
@@ -30,108 +157,41 @@ export function register(program) {
     )
     .option("--internal-registry", "Include docs/internal/doc-registry.yaml data in output")
     .action(async (directory, opts) => {
-      directory = directory || ".";
-      const d = resolve(directory);
-
-      // Gather all project data
-      const data = await gatherProjectData(d, opts.name);
-
-      // Load internal registry if requested
-      if (opts.internalRegistry) {
-        const { loadInternalRegistry } = await import("./doc-review.js");
-        const registry = await loadInternalRegistry(d);
-        if (registry) {
-          data.internalRegistry = registry;
-        } else {
-          data.warnings.push(
-            "No docs/internal/doc-registry.yaml found — run `wwa doc-review` to generate it"
-          );
-        }
-      }
-
-      if (data.errors.length > 0 && data.sessions.length === 0) {
-        console.error("Cannot generate case study:");
-        for (const e of data.errors) console.error(`  - ${e}`);
-        process.exit(1);
-      }
-
-      if (opts.json) {
-        const output = opts.output;
-        const result = JSON.stringify(data, null, 2);
-        if (output) {
-          safeWriteFile(output, result);
-          console.log(`Case study data written to ${output}`);
-        } else {
-          console.log(result);
-        }
-        return;
-      }
-
-      // YAML-only mode: write a single .yaml artifact with all structured data.
-      if (opts.yamlOnly) {
-        const baseDir = join(d, "case-studies");
-        const baseSlug = slugify(data.projectName);
-        let yamlOutputPath = opts.output || join(baseDir, `${baseSlug}.yaml`);
-
-        // Avoid overwriting existing case studies when using the default path.
-        if (!opts.output) {
-          let counter = 1;
-          while (existsSync(yamlOutputPath)) {
-            yamlOutputPath = join(baseDir, `${baseSlug}-${counter}.yaml`);
-            counter += 1;
+      try {
+        const result = await runCasestudy(directory, opts);
+
+        if (opts.json) {
+          if (result.mode === "json_inline") {
+            console.log(JSON.stringify(result.data, null, 2));
+          } else {
+            console.log(
+              `Case study data written to ${result.output} (${result.sessions} sessions)`
+            );
           }
+          return;
         }
 
-        const yamlDir = resolve(yamlOutputPath, "..");
-        if (!existsSync(yamlDir)) {
-          mkdirSync(yamlDir, { recursive: true });
-        }
-
-        const ok = await writeCaseStudyYaml(yamlOutputPath, data);
-        if (ok) {
+        if (result.mode === "yaml_only") {
           console.log(
-            `Case study YAML written to ${yamlOutputPath} (${data.sessions.length} sessions)`
+            `Case study YAML written to ${result.yamlPath} (${result.sessions} sessions)`
           );
         } else {
-          console.error("Failed to write YAML case study.");
-          process.exit(1);
-        }
-      } else {
-        // Default: write markdown case study plus companion YAML.
-        const baseDir = join(d, "case-studies");
-        const baseSlug = slugify(data.projectName);
-        let markdownPath = opts.output || join(baseDir, `${baseSlug}.md`);
-
-        // Avoid overwriting existing case studies when using the default path.
-        if (!opts.output) {
-          let counter = 1;
-          while (existsSync(markdownPath)) {
-            markdownPath = join(baseDir, `${baseSlug}-${counter}.md`);
-            counter += 1;
-          }
+          console.log(
+            `Case study written to ${result.markdownPath} (${result.sessions} sessions)`
+          );
+          console.log(`Case study YAML written to ${result.yamlPath}`);
         }
 
-        const outputDir = resolve(markdownPath, "..");
-        if (!existsSync(outputDir)) {
-          mkdirSync(outputDir, { recursive: true });
+        if (result.warnings && result.warnings.length > 0) {
+          console.log("\nWarnings:");
+          for (const w of result.warnings) console.log(`  - ${w}`);
         }
-
-        const caseStudy = generateCaseStudy(data);
-        safeWriteFile(markdownPath, caseStudy);
-        console.log(
-          `Case study written to ${markdownPath} (${data.sessions.length} sessions)`
-        );
-
-        const yamlPath = markdownPath.replace(/\.md$/, ".yaml");
-        const yamlResult = await writeCaseStudyYaml(yamlPath, data);
-        if (yamlResult) {
-          console.log(`Case study YAML written to ${yamlPath}`);
+      } catch (e) {
+        console.error(e.message || "Failed to generate case study.");
+        if (e.details?.errors) {
+          for (const err of e.details.errors) console.error(`  - ${err}`);
         }
-      }
-
-      if (data.warnings.length > 0) {
-        console.log("\nWarnings:");
-        for (const w of data.warnings) console.log(`  - ${w}`);
+        process.exit(1);
       }
     });
 }