agent-method 1.5.12 → 1.5.15

package/lib/cli/upgrade.js

@@ -1,4 +1,9 @@
-/** wwa upgrade — brownfield-safe methodology update. */
+/**
+ * wwa upgrade — brownfield-safe methodology update.
+ *
+ * Invariant (all wwa commands): canonical names persist in the working directory;
+ * versioned/archived copies live only under .wwa-archive/ (see helpers.WWA_ARCHIVE_DIR).
+ */
 
 import {
   readFileSync, existsSync, mkdirSync, copyFileSync, unlinkSync,
@@ -6,7 +11,7 @@ import {
 import { resolve, join, dirname } from "node:path";
 import {
   findEntryPoint, readMethodVersion, basename_of, pkg, packageRoot,
-  safeWriteFile, safeCopyFile,
+  safeWriteFile, safeCopyFile, WWA_ARCHIVE_DIR,
 } from "./helpers.js";
 
 export function register(program) {
@@ -206,6 +211,67 @@ export function register(program) {
         }
       }
 
+      // 6. Non-destructive template/schema upgrades (archived originals + live latest)
+      //
+      // When templates or schemas change, we never delete user content. Instead we:
+      //  - Archive the existing file into a subdirectory (e.g. .wwa-archive/entry-points/CLAUDE.md)
+      //  - Replace the live file with the latest template/schema
+      //  - Add a backlog entry pointing to the archived copy so migration can be reviewed.
+
+      // 6a. Entry point templates (CLAUDE.md / .cursorrules / AGENT.md)
+      if (ep) {
+        const entryName = basename_of(ep); // e.g. CLAUDE.md
+        const templatePath = join(srcDir, entryName);
+        if (existsSync(templatePath)) {
+          const change = classifyMarkdownChange(templatePath, ep);
+          if (change === "present_diverged_user") {
+            const archiveDir = join(d, WWA_ARCHIVE_DIR, "entry-points");
+            const baseArchivePath = join(archiveDir, entryName);
+            const archivePath = nextVersionedPathInsideArchive(archiveDir, entryName);
+            const relArchive = archivePath.replace(d, "").replace(/^[\\/]/, "");
+            actions.push(`Archive existing entry point to ${relArchive} and replace with latest template`);
+            if (!opts.dryRun) {
+              mkdirSync(dirname(archivePath), { recursive: true });
+              safeCopyFile(ep, archivePath);
+              safeCopyFile(templatePath, ep);
+            }
+            ensureBacklogEntry(
+              d,
+              relArchive,
+              `- [ ] **Review upgraded entry point** — Existing entry point archived at ${relArchive}. Compare with current ${entryName} and reconcile any custom conventions.`
+            );
+          }
+        }
+      }
+
+      // 6b. Registry/doc-tokens schema (YAML)
+      const projectTokensPath = join(d, "registry", "doc-tokens.yaml");
+      const templateTokensPath = join(
+        packageRoot,
+        "docs",
+        "internal",
+        "doc-tokens.yaml"
+      );
+      if (existsSync(projectTokensPath) && existsSync(templateTokensPath)) {
+        const change = classifyYamlChange(templateTokensPath, projectTokensPath);
+        if (change === "schema_changed" || change === "present_diverged_user") {
+          const archiveDir = join(d, WWA_ARCHIVE_DIR, "registry");
+          const archivePath = nextVersionedPathInsideArchive(archiveDir, "doc-tokens.yaml");
+          const relArchive = archivePath.replace(d, "").replace(/^[\\/]/, "");
+          actions.push(`Archive existing registry/doc-tokens.yaml to ${relArchive} and replace with latest schema`);
+          if (!opts.dryRun) {
+            mkdirSync(dirname(archivePath), { recursive: true });
+            safeCopyFile(projectTokensPath, archivePath);
+            safeCopyFile(templateTokensPath, projectTokensPath);
+          }
+          ensureBacklogEntry(
+            d,
+            relArchive,
+            `- [ ] **Review doc-tokens schema migration** — Previous schema archived at ${relArchive}. Confirm that tooling and docs are compatible with the updated registry/doc-tokens.yaml.`
+          );
+        }
+      }
+
       // Report
       if (actions.length === 0) {
         console.log(`Project at ${directory} is up to date (v${pkg.version}).`);
@@ -220,3 +286,79 @@ export function register(program) {
       }
     });
 }
+
+// ---------------------------------------------------------------------------
+// Helper functions — change classification, archive paths, backlog entries
+// ---------------------------------------------------------------------------
+//
+// Versioned filenames are only ever created inside the archive subdirectory,
+// never in the working directory, so canonical names (CLAUDE.md, doc-tokens.yaml)
+// always persist in place.
+
+function classifyMarkdownChange(templatePath, projectPath) {
+  if (!existsSync(projectPath) || !existsSync(templatePath)) return "missing";
+  const tmpl = readFileSync(templatePath, "utf-8");
+  const proj = readFileSync(projectPath, "utf-8");
+  if (tmpl === proj) return "present_identical";
+  return "present_diverged_user";
+}
+
+function classifyYamlChange(templatePath, projectPath) {
+  if (!existsSync(projectPath) || !existsSync(templatePath)) return "missing";
+  const tmpl = readFileSync(templatePath, "utf-8");
+  const proj = readFileSync(projectPath, "utf-8");
+  if (tmpl === proj) return "present_identical";
+  // Treat any content difference as a schema-level change for now; this is
+  // conservative but guarantees we keep the original file intact.
+  return "schema_changed";
+}
+
+/**
+ * Return a path for an archived copy, with a version suffix only inside the archive dir.
+ * Ensures we never write *.v2.* in the working directory — only under archiveDir.
+ */
+function nextVersionedPathInsideArchive(archiveDir, filename) {
+  const match = filename.match(/^(.*)(\.[^./\\]+)$/);
+  const stem = match ? match[1] : filename;
+  const ext = match ? match[2] : "";
+  let counter = 2;
+  for (;;) {
+    const candidate = join(archiveDir, `${stem}.v${counter}${ext}`);
+    if (!existsSync(candidate)) return candidate;
+    counter += 1;
+  }
+}
+
+function ensureBacklogEntry(projectDir, markerPath, line) {
+  const backlogCandidates = [
+    join(projectDir, "todos", "backlog.md"),
+    join(projectDir, "backlog.md"),
+  ];
+
+  let targetPath = null;
+  let content = "";
+
+  for (const p of backlogCandidates) {
+    if (existsSync(p)) {
+      const existing = readFileSync(p, "utf-8");
+      if (existing.includes(markerPath)) {
+        return; // entry already present
+      }
+      targetPath = p;
+      content = existing;
+      break;
+    }
+  }
+
+  if (!targetPath) {
+    targetPath = backlogCandidates[0];
+    mkdirSync(dirname(targetPath), { recursive: true });
+    content = "# Backlog\n\n";
+  }
+
+  if (content && !content.endsWith("\n")) {
+    content += "\n";
+  }
+  content += `${line}\n`;
+  safeWriteFile(targetPath, content, "utf-8");
+}

package/lib/init.js

@@ -57,8 +57,7 @@ export async function initProject(projectType, directory, opts = {}) {
 
   const templateDir = join(methodRoot, "templates", tier);
   if (!existsSync(templateDir)) {
-    console.error(`Template directory not found: ${templateDir}`);
-    process.exit(1);
+    throw new Error(`Template directory not found: ${templateDir}`);
   }
 
   console.log(`\nSetting up ${FRIENDLY_NAMES[projectType] || projectType} project`);