agent-method 1.5.12

package/lib/boundaries.js

@@ -0,0 +1,247 @@
+/**
+ * Configurable project boundaries — path resolution, visibility, distribution.
+ * Reads `boundaries` section from PROTOCOL.yaml. Falls back to DEFAULTS
+ * when no boundaries section exists (backward compatible).
+ *
+ * Used by: every CLI command that reads/writes project registries.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Defaults — match current hardcoded paths exactly
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  registries: {
+    tokens: "registry/doc-tokens.yaml",
+    docs_map: ".context/DOCS-MAP.md",
+    index: ".context/INDEX.yaml",
+    feature_registry: "registry/feature-registry.yaml",
+    output: "docs/internal/",
+  },
+  visibility: {
+    internal: [".context/", "registry/", "research/", "todos/", "docs/internal/"],
+    release: [
+      "docs/architecture/",
+      "docs/workflow/",
+      "docs/guides/",
+      "templates/",
+      "case-studies/",
+    ],
+  },
+  scan: {
+    include: ["docs/", ".context/", "templates/", "registry/"],
+    exclude: ["node_modules/", ".git/", "dist/", "build/"],
+  },
+  distribution: {
+    git: {
+      exclude: [
+        "STATE.md", "PLAN.md", "ROADMAP.md", "SUMMARY.md",
+        ".context/", "research/", "todos/",
+      ],
+    },
+    npm: {
+      include: ["bin/", "lib/", "templates/"],
+      exclude: ["docs/internal/", ".context/", "research/"],
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Cache — one parse per directory per CLI invocation
+// ---------------------------------------------------------------------------
+
+const _cache = new Map();
+
+/** Deep merge source into target (source wins, arrays replaced not concatenated). */
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === "object" &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === "object" &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Core loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load boundaries from PROTOCOL.yaml, deep-merged with DEFAULTS.
+ * PROTOCOL.yaml path is hardcoded — it's the anchor.
+ */
+export async function loadBoundaries(dir) {
+  const d = resolve(dir);
+  if (_cache.has(d)) return _cache.get(d);
+
+  const protocolPath = join(d, ".context", "PROTOCOL.yaml");
+  let boundaries = { ...DEFAULTS };
+
+  if (existsSync(protocolPath)) {
+    try {
+      const yaml = (await import("js-yaml")).default;
+      const raw = readFileSync(protocolPath, "utf-8");
+      const parsed = yaml.load(raw);
+      if (parsed?.boundaries) {
+        boundaries = deepMerge(DEFAULTS, parsed.boundaries);
+      }
+    } catch {
+      // Parse error — use defaults
+    }
+  }
+
+  // Legacy fallback: if resolved registry paths don't exist, check .context/
+  for (const key of ["tokens", "feature_registry"]) {
+    const resolved = join(d, boundaries.registries[key]);
+    if (!existsSync(resolved)) {
+      const legacyName = key === "tokens" ? "doc-tokens.yaml" : "feature-registry.yaml";
+      const legacy = join(d, ".context", legacyName);
+      if (existsSync(legacy)) {
+        boundaries.registries[key] = `.context/${legacyName}`;
+      }
+    }
+  }
+
+  _cache.set(d, boundaries);
+  return boundaries;
+}
+
+// ---------------------------------------------------------------------------
+// Path resolvers
+// ---------------------------------------------------------------------------
+
+/** Resolve path to the token registry (doc-tokens.yaml). */
+export async function resolveTokensPath(dir) {
+  const b = await loadBoundaries(dir);
+  return join(resolve(dir), b.registries.tokens);
+}
+
+/** Resolve path to the docs map (DOCS-MAP.md). */
+export async function resolveDocsMapPath(dir) {
+  const b = await loadBoundaries(dir);
+  return join(resolve(dir), b.registries.docs_map);
+}
+
+/** Resolve path to the project index (INDEX.yaml). */
+export async function resolveIndexPath(dir) {
+  const b = await loadBoundaries(dir);
+  return join(resolve(dir), b.registries.index);
+}
+
+/** Resolve path to the feature registry. */
+export async function resolveFeatureRegistryPath(dir) {
+  const b = await loadBoundaries(dir);
+  return join(resolve(dir), b.registries.feature_registry);
+}
+
+/** Resolve path to the output directory (docs/internal/ by default). */
+export async function resolveOutputDir(dir) {
+  const b = await loadBoundaries(dir);
+  return join(resolve(dir), b.registries.output);
+}
+
+// ---------------------------------------------------------------------------
+// Centralized doc graph loader (replaces 3 duplicate functions)
+// ---------------------------------------------------------------------------
+
+/** Load doc_graph from the project's token registry (handles split layout). */
+export async function loadDocGraph(dir) {
+  const tokensPath = await resolveTokensPath(dir);
+  if (!existsSync(tokensPath)) return null;
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(tokensPath, "utf-8");
+    const parsed = yaml.load(raw);
+
+    // Check for externalized doc_graph component
+    if (parsed?.components?.doc_graph) {
+      const componentPath = join(dirname(tokensPath), parsed.components.doc_graph);
+      if (existsSync(componentPath)) {
+        const cParsed = yaml.load(readFileSync(componentPath, "utf-8"));
+        return cParsed?.doc_graph || cParsed || null;
+      }
+    }
+
+    return parsed?.doc_graph || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load the full token registry, assembling externalized sections.
+ * Returns the complete parsed object with all sections merged.
+ */
+export async function loadTokensAssembled(dir) {
+  const tokensPath = await resolveTokensPath(dir);
+  if (!existsSync(tokensPath)) return null;
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(tokensPath, "utf-8");
+    const parsed = yaml.load(raw);
+    if (!parsed) return null;
+
+    // Assemble externalized sections
+    if (parsed.components) {
+      const tokensDir = dirname(tokensPath);
+      for (const [section, relPath] of Object.entries(parsed.components)) {
+        const componentPath = join(tokensDir, relPath);
+        if (existsSync(componentPath)) {
+          const cParsed = yaml.load(readFileSync(componentPath, "utf-8"));
+          parsed[section] = cParsed?.[section] || cParsed;
+        }
+      }
+      delete parsed.components;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Visibility helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a file path falls within internal (dev-only) boundaries. */
+export function isInternal(filePath, boundaries) {
+  const p = filePath.replace(/\\/g, "/");
+  return (boundaries.visibility?.internal || []).some((prefix) =>
+    p.startsWith(prefix)
+  );
+}
+
+/** Check if a file path falls within release boundaries. */
+export function isRelease(filePath, boundaries) {
+  const p = filePath.replace(/\\/g, "/");
+  return (boundaries.visibility?.release || []).some((prefix) =>
+    p.startsWith(prefix)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** Clear the boundaries cache (for testing). */
+export function clearCache() {
+  _cache.clear();
+}
+
+/** Get the raw DEFAULTS object (for init seeding). */
+export function getDefaults() {
+  return DEFAULTS;
+}

package/lib/cli/add.js

@@ -0,0 +1,170 @@
+/**
+ * wwa add — append structured content to methodology files (Phase 7p).
+ * Targets: backlog, decision, finding, session, summary.
+ * Uses safeWriteFile; only .md/.yaml/.yml. Optional --dry-run.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { findSessionLog } from "./helpers.js";
+import { safeWriteFile, isSafeToWrite } from "./helpers.js";
+
+const ADD_TYPES = ["backlog", "decision", "finding", "session", "summary"];
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readStdin() {
+  return new Promise((resolveStdin) => {
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolveStdin(chunks.join("").trim()));
+  });
+}
+
+export function register(program) {
+  program
+    .command("add <type> [content...]")
+    .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)) {
+          console.error(`File not found: ${fpath}`);
+          process.exit(1);
+        }
+        content = readFileSync(fpath, "utf-8").trim();
+      } else if (contentParts && contentParts.length > 0) {
+        content = contentParts.join(" ").trim();
+      } else if (type === "session" || type === "summary") {
+        content = await readStdin();
+        if (!content) {
+          console.error("Provide content via stdin or --file for session/summary.");
+          process.exit(1);
+        }
+      } else {
+        console.error(`Provide content as argument or --file for type: ${type}`);
+        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);
+      }
+
+      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);
+        }
+        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;
+        }
+        console.error(`File not found: ${targetPath}. Create it first or run from project root.`);
+        process.exit(1);
+      }
+
+      const existing = readFileSync(targetPath, "utf-8");
+      safeWriteFile(targetPath, existing + toAppend);
+      console.log("Appended to", targetPath);
+      remindCascade(dir);
+    });
+}
+
+/** Remind to check PROTOCOL cascade after file change (respect PROTOCOL). */
+function remindCascade(dir) {
+  const p = join(dir, ".context", "PROTOCOL.yaml");
+  if (existsSync(p)) {
+    console.log("Reminder: after file changes, check PROTOCOL cascade (.context/PROTOCOL.yaml).");
+  }
+}