plain-forge 1.0.10 → 1.0.12

package/README.md

@@ -42,9 +42,9 @@ Each skill operates on the same one-question-at-a-time, write-immediately, refin
 
 plain-forge ships as a set of skills, rules, and docs that plug into your AI coding tool of choice. Install it once, then invoke `forge-plain` (or `add-feature` to add a feature to an existing ***plain project) from any project.
 
-### Install with `npx plain-forge install` (recommended)
+### Install with `npx plain-forge install`
 
-The primary install path. Works for every supported runtime and is the only installer that ships **all** plain-forge content (skills, rules, **and** docs) — the other methods below are limited or agent-specific.
+The one and only way to install plain-forge. It works for every supported runtime and ships **all** plain-forge content (skills, rules, **and** docs).
 
 ```bash
 npx plain-forge install
@@ -81,41 +81,19 @@ Each install writes three subfolders under the chosen directory:
   docs/      # shared reference docs
 ```
 
-Re-running `npx plain-forge install` overwrites the destination silently, so it doubles as the upgrade path — `npx plain-forge@latest install` pulls the newest release every time.
+`install` refuses to run if plain-forge is already present at the target directory — it prints a message pointing you at `update` and exits non-zero. Use `update` (below) to refresh an existing install.
 
-### Alternative install paths (skills only — no rules or docs)
-
-These work but only install the skill files. Rules and docs do **not** travel with them, so use them only if you have a reason not to use `npx plain-forge install`.
-
-#### `npx skills` CLI
+#### Updating an existing install
 
 ```bash
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent claude-code
+npx plain-forge@latest update
 ```
 
-Replace `--agent claude-code` with `codex` or `opencode` to target a different runtime, or repeat the flag for several at once.
-
-#### Claude Code native plugin flow
-
-Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). Inside a Claude Code session, run the following **three commands** one after the other:
-
-```text
-/plugin marketplace add Codeplain-ai/plain-forge
-/plugin install plain-forge@plain-forge
-/reload-plugins
-```
-
-Without the reload the skills won't appear in the current session.
-
-#### Codex native plugin flow
-
-Requires the [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference). From your shell:
+`update` auto-detects every plain-forge install in the current folder and in your home directory (across all agent layouts) and refreshes each one in place — no agent/scope prompts. For each install it compares the version recorded in the manifest against the version you're running: if the package version did not increase, it leaves that install untouched and tells you it's already up to date. Unlike `install`, it also **prunes** files that were removed from the package (e.g. a deleted skill) by consulting a manifest (`<agent-dir>/.plain-forge/manifest.json`) that records exactly which files plain-forge wrote. Your own skills and any third-party skills sharing the same directory are never in that manifest, so they are never touched.
 
-```bash
-codex plugin marketplace add Codeplain-ai/plain-forge
-```
+Each deprecated file is confirmed individually before it's deleted — you'll see its path and a `[y/N]` prompt. Denied files stay on disk and remain tracked, so the next `update` re-offers them. Pass `--yes` (or `-y`) to remove all deprecated files without prompting (useful in CI); when there's no interactive terminal and `--yes` is not given, nothing is deleted.
 
-Then, inside Codex, open the plugin directory, pick the `plain-forge` marketplace, and install the plugin from there. (Codex's CLI does not currently expose a `codex plugin install` equivalent.)
+Installs that predate the manifest (anyone who installed before this feature existed) have no manifest to read. `update` still finds them by their skill footprint: if the `forge-plain`, `add-feature`, `debug-specs`, and `load-plain-reference` skills are all present in an agent directory, it's treated as a plain-forge install. Such installs are refreshed without pruning (overwrite-only), and gain a manifest going forward so later updates can prune.
 
 ## Usage
 
@@ -206,20 +184,6 @@ bin/
 .opencode/                   # OpenCode plugin layout
 ```
 
-### Contributing
-
-After editing anything under `forge/` or `runtimes/*/templates/`, regenerate the runtime outputs:
-
-```bash
-npm install        # required after every fresh clone (node_modules/ is gitignored)
-npm run build      # regenerate runtime outputs for Claude, Codex, OpenCode
-npm run clean      # remove generated outputs and rebuild from scratch
-```
-
-If `npm run build` errors with `sh: tsx: command not found`, it means `node_modules/` is missing — run `npm install` first.
-
-The build is idempotent — re-running it produces no `git diff`.
-
 ## Available Skills
 
 ### Core Workflow

package/bin/cli.mjs

@@ -17,6 +17,30 @@ const AGENTS = {
 };
 const SCOPES = ["project", "global"];
 
+// Subfolders plain-forge writes under an agent directory.
+const CONTENT_DIRS = ["skills", "rules", "docs"];
+// Manifest recording exactly which files this package installed, so `update`
+// can prune our own stale files without touching user or third-party content.
+const MANIFEST_REL = path.join(".plain-forge", "manifest.json");
+// Flagship skills every plain-forge install ships. Used to recognize legacy
+// installs that predate the manifest: if all of these skill directories are
+// present, plain-forge is installed even without a manifest.
+const FORGE_SIGNATURE_SKILLS = [
+  "forge-plain",
+  "add-feature",
+  "debug-specs",
+  "load-plain-reference",
+];
+
+// True when baseDir looks like a plain-forge install by its skill footprint
+// alone (the manifest-less fallback). Requires every flagship skill so an
+// unrelated agent dir with one similarly-named skill is not misdetected.
+function hasForgeSignature(baseDir) {
+  return FORGE_SIGNATURE_SKILLS.every((skill) =>
+    fs.existsSync(path.join(baseDir, "skills", skill)),
+  );
+}
+
 const BANNER = `\x1b[38;2;224;255;110m██████╗ ██╗      █████╗ ██╗███╗   ██╗      ███████╗ ██████╗ ██████╗  ██████╗ ███████╗
 ██╔══██╗██║     ██╔══██╗██║████╗  ██║      ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
 ██████╔╝██║     ███████║██║██╔██╗ ██║█████╗█████╗  ██║   ██║██████╔╝██║  ███╗█████╗
@@ -51,18 +75,31 @@ function printBanner() {
 }
 
 function usage() {
-  console.log(`Usage: plain-forge install [options]
+  console.log(`Usage: plain-forge <command> [options]
+
+Commands:
+  install   Install plain-forge into an agent directory
+  update    Refresh every existing plain-forge install in cwd and $HOME
 
-Options:
+Install options:
   --agent <claude|codex|forgecode|universal>   Target agent layout
   --scope <project|global>                     Install into cwd or $HOME
   -h, --help                                   Show this help
 
+Update options:
+  -y, --yes                                    Remove deprecated files without
+                                               confirming each one
+
 Examples:
   plain-forge install --agent claude --scope project
   plain-forge install --agent universal --scope global
+  plain-forge update
+  plain-forge update --yes
 
-Missing flags are prompted interactively.`);
+"install" fails if plain-forge is already installed at the target — use
+"update" to refresh it. Missing install flags are prompted interactively.
+"update" auto-detects installs and prunes only files plain-forge wrote
+(confirming each removal), leaving your own and third-party skills untouched.`);
 }
 
 function parseArgs(argv) {
@@ -71,6 +108,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--agent") out.agent = argv[++i];
     else if (a === "--scope") out.scope = argv[++i];
+    else if (a === "-y" || a === "--yes") out.yes = true;
     else if (a === "-h" || a === "--help") out.help = true;
     else out._.push(a);
   }
@@ -141,21 +179,191 @@ function promptChoice(question, choices) {
   });
 }
 
-function copyTree(srcDir, destDir) {
-  if (!fs.existsSync(srcDir)) return 0;
-  fs.mkdirSync(destDir, { recursive: true });
-  let count = 0;
-  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    const src = path.join(srcDir, entry.name);
-    const dest = path.join(destDir, entry.name);
-    if (entry.isDirectory()) {
-      fs.cpSync(src, dest, { recursive: true, force: true, dereference: true });
+// Ask a yes/no question. Defaults to "no" when stdin is not a TTY, so a
+// non-interactive run never deletes anything without an explicit --yes.
+function promptConfirm(question) {
+  const input = process.stdin;
+  const output = process.stdout;
+  if (!input.isTTY) return Promise.resolve(false);
+
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+const toPosix = (p) => p.split(path.sep).join("/");
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"),
+    );
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// Compare two dotted numeric versions. Returns 1 if a > b, -1 if a < b, 0 if
+// equal, or null when either version is not purely numeric (e.g. "unknown").
+function compareVersions(a, b) {
+  const parse = (v) => String(v).split(".").map(Number);
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa.some(Number.isNaN) || pb.some(Number.isNaN)) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+// An install is up to date when the package version did not increase over the
+// version recorded in its manifest. Indeterminate versions ("unknown", or a
+// missing manifest version) are never treated as up to date, so the refresh
+// proceeds rather than silently skipping.
+function isUpToDate(installedVersion, currentVersion) {
+  const cmp = compareVersions(currentVersion, installedVersion);
+  return cmp !== null && cmp <= 0;
+}
+
+// Copy srcDir into destDir file-by-file (dereferencing symlinks), returning the
+// list of file paths written, each relative to destDir.
+function copyTreeTracked(srcDir, destDir) {
+  const written = [];
+  if (!fs.existsSync(srcDir)) return written;
+
+  const walk = (rel) => {
+    const srcPath = path.join(srcDir, rel);
+    const destPath = path.join(destDir, rel);
+    const stat = fs.statSync(srcPath); // follows symlinks → dereferences
+    if (stat.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      for (const entry of fs.readdirSync(srcPath)) {
+        walk(path.join(rel, entry));
+      }
     } else {
-      fs.copyFileSync(src, dest);
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      written.push(rel);
+    }
+  };
+
+  for (const entry of fs.readdirSync(srcDir)) {
+    walk(entry);
+  }
+  return written;
+}
+
+// Copy every content dir into baseDir. Returns the flat list of files written
+// (each relative to baseDir, for the manifest) and the per-dir counts. A count
+// is the number of top-level items in that dir — i.e. the number of skills
+// (each a directory) or rules, not the total file count, since a single skill
+// can span several files.
+function writeContent(baseDir) {
+  const counts = {};
+  const files = [];
+  for (const dir of CONTENT_DIRS) {
+    const written = copyTreeTracked(
+      path.join(forgeDir, dir),
+      path.join(baseDir, dir),
+    );
+    const topLevel = new Set(written.map((rel) => rel.split(path.sep)[0]));
+    counts[dir] = topLevel.size;
+    for (const rel of written) files.push(path.join(dir, rel));
+  }
+  return { counts, files };
+}
+
+function manifestPathFor(baseDir) {
+  return path.join(baseDir, MANIFEST_REL);
+}
+
+function readManifest(baseDir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(manifestPathFor(baseDir), "utf8"));
+    if (data && Array.isArray(data.files)) return data;
+  } catch {
+    /* missing or malformed manifest → treat as absent */
+  }
+  return null;
+}
+
+function writeManifest(baseDir, files) {
+  const target = manifestPathFor(baseDir);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const manifest = {
+    name: "plain-forge",
+    version: readPkgVersion(),
+    files: files.map(toPosix).sort(),
+  };
+  fs.writeFileSync(target, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// Remove now-empty directories from `dir` upward, stopping at (and never
+// removing) stopAt.
+function removeEmptyDirsUpward(dir, stopAt) {
+  let cur = dir;
+  while (cur !== stopAt && cur.startsWith(stopAt + path.sep)) {
+    try {
+      if (fs.readdirSync(cur).length > 0) break;
+      fs.rmdirSync(cur);
+      cur = path.dirname(cur);
+    } catch {
+      break;
+    }
+  }
+}
+
+// Files present in the prior manifest but absent from the fresh copy, that
+// still exist on disk. Only paths plain-forge itself recorded are ever
+// considered — user/third-party files are never in the manifest.
+function collectPruneCandidates(baseDir, oldFiles, newFiles) {
+  const keep = new Set(newFiles.map(toPosix));
+  const candidates = [];
+  for (const rel of oldFiles) {
+    if (keep.has(toPosix(rel))) continue;
+    if (fs.existsSync(path.join(baseDir, rel))) candidates.push(toPosix(rel));
+  }
+  return candidates;
+}
+
+function deleteForgeFile(baseDir, rel) {
+  const target = path.join(baseDir, rel);
+  try {
+    fs.rmSync(target, { force: true });
+    removeEmptyDirsUpward(path.dirname(target), baseDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Find every plain-forge install in cwd and $HOME. An install is recognized by
+// its manifest, or — for installs predating the manifest — by the presence of
+// the flagship skill.
+function detectInstalls() {
+  const installs = [];
+  for (const scope of SCOPES) {
+    const root = scope === "global" ? os.homedir() : process.cwd();
+    for (const [agent, dirName] of Object.entries(AGENTS)) {
+      const baseDir = path.join(root, dirName);
+      if (!fs.existsSync(baseDir)) continue;
+      const manifest = readManifest(baseDir);
+      const isLegacy = !manifest && hasForgeSignature(baseDir);
+      if (manifest || isLegacy) {
+        installs.push({ agent, scope, baseDir, manifest });
+      }
     }
-    count++;
   }
-  return count;
+  return installs;
 }
 
 async function cmdInstall(args) {
@@ -180,27 +388,106 @@ async function cmdInstall(args) {
   const root = scope === "global" ? os.homedir() : process.cwd();
   const baseDir = path.join(root, AGENTS[agent]);
 
-  const skillsCount = copyTree(
-    path.join(forgeDir, "skills"),
-    path.join(baseDir, "skills"),
-  );
-  const rulesCount = copyTree(
-    path.join(forgeDir, "rules"),
-    path.join(baseDir, "rules"),
-  );
-  const docsCount = copyTree(
-    path.join(forgeDir, "docs"),
-    path.join(baseDir, "docs"),
-  );
+  const alreadyInstalled =
+    readManifest(baseDir) !== null || hasForgeSignature(baseDir);
+  if (alreadyInstalled) {
+    console.error(`plain-forge is already installed in ${baseDir}.`);
+    console.error(`run "plain-forge update" to refresh it.`);
+    process.exit(1);
+  }
+
+  const { counts, files } = writeContent(baseDir);
+  writeManifest(baseDir, files);
 
   console.log(`installed into ${baseDir}`);
-  console.log(`  skills: ${skillsCount}`);
-  console.log(`  rules:  ${rulesCount}`);
-  console.log(`  docs:   ${docsCount}`);
+  console.log(`  skills: ${counts.skills}`);
+  console.log(`  rules:  ${counts.rules}`);
+  console.log(`  docs:   ${counts.docs}`);
   console.log();
   printNextSteps(agent);
 }
 
+async function cmdUpdate(args) {
+  printBanner();
+
+  const installs = detectInstalls();
+  if (installs.length === 0) {
+    console.log(
+      "no existing plain-forge installations found in this folder or your home directory.",
+    );
+    console.log(`run "plain-forge install" to set one up.`);
+    return;
+  }
+
+  const version = readPkgVersion();
+  let updated = 0;
+  for (const inst of installs) {
+    const hasManifest = inst.manifest != null;
+
+    // The up-to-date check applies only to manifest-tracked installs. With no
+    // manifest there is no recorded version to compare against, so the version
+    // check is skipped and the install is always refreshed — a manifest is then
+    // written for it at the end of this iteration (see writeManifest below).
+    if (hasManifest && isUpToDate(inst.manifest.version, version)) {
+      console.log(
+        `${inst.agent} (${inst.scope}) is already up to date (v${inst.manifest.version}).`,
+      );
+      console.log();
+      continue;
+    }
+
+    const oldFiles = inst.manifest?.files ?? [];
+    const { counts, files } = writeContent(inst.baseDir);
+
+    console.log(`updated ${inst.agent} (${inst.scope}) → ${inst.baseDir}`);
+    console.log(
+      `  skills: ${counts.skills}  rules: ${counts.rules}  docs: ${counts.docs}`,
+    );
+
+    // Pruning only applies to manifest-tracked installs. Each deprecated file
+    // is confirmed individually before removal; denied files stay on disk and
+    // remain tracked so the next update re-offers them.
+    const kept = [];
+    if (!hasManifest) {
+      console.log(`  pruned: skipped (no manifest from prior install)`);
+    } else {
+      const candidates = collectPruneCandidates(inst.baseDir, oldFiles, files);
+      let pruned = 0;
+      for (const rel of candidates) {
+        console.log(
+          `  The file corresponds to a plain-forge file that has been deprecated or removed:`,
+        );
+        console.log(`    ${rel}`);
+        const remove = args.yes
+          ? true
+          : await promptConfirm("  Please confirm its removal.");
+        if (remove && deleteForgeFile(inst.baseDir, rel)) {
+          pruned++;
+        } else {
+          kept.push(rel);
+        }
+      }
+      console.log(
+        `  pruned: ${pruned}${kept.length ? `  kept: ${kept.length}` : ""}`,
+      );
+    }
+
+    // Manifest reflects what's actually on disk: the fresh files plus any
+    // deprecated files the user chose to keep.
+    writeManifest(inst.baseDir, files.concat(kept));
+    console.log();
+    updated++;
+  }
+
+  if (updated === 0) {
+    console.log(
+      `you are already using the up-to-date plain-forge (v${version}).`,
+    );
+  } else {
+    console.log(`updated ${updated} installation(s) to v${version}.`);
+  }
+}
+
 function printNextSteps(agent) {
   const bold = (s) => `\x1b[1;97m${s}\x1b[0m`;
   const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -258,6 +545,9 @@ async function main() {
     case "install":
       await cmdInstall(args);
       break;
+    case "update":
+      await cmdUpdate(args);
+      break;
     default:
       console.error(`unknown command "${cmd}"`);
       usage();
@@ -265,10 +555,53 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  if (err instanceof Error && err.message === "cancelled") {
-    process.exit(130);
+// Only run the CLI when executed directly — importing this module (e.g. from
+// the test suite) must not trigger main() or process.exit().
+// `__filename` (from import.meta.url) is realpath-resolved by Node, but
+// process.argv[1] is the path as invoked — under npx / a global install it's a
+// symlink in node_modules/.bin or the npx cache. Resolve both through realpath
+// so the comparison survives symlinked bins; otherwise main() silently never
+// runs (spinner, then nothing).
+function isInvokedDirectly() {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return fs.realpathSync(invoked) === __filename;
+  } catch {
+    return path.resolve(invoked) === __filename;
   }
-  console.error(err instanceof Error ? (err.stack ?? err.message) : err);
-  process.exit(1);
-});
+}
+const invokedDirectly = isInvokedDirectly();
+if (invokedDirectly) {
+  main().catch((err) => {
+    if (err instanceof Error && err.message === "cancelled") {
+      process.exit(130);
+    }
+    console.error(err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(1);
+  });
+}
+
+export {
+  AGENTS,
+  SCOPES,
+  CONTENT_DIRS,
+  MANIFEST_REL,
+  FORGE_SIGNATURE_SKILLS,
+  hasForgeSignature,
+  parseArgs,
+  toPosix,
+  readPkgVersion,
+  compareVersions,
+  isUpToDate,
+  copyTreeTracked,
+  writeContent,
+  manifestPathFor,
+  readManifest,
+  writeManifest,
+  removeEmptyDirsUpward,
+  collectPruneCandidates,
+  deleteForgeFile,
+  detectInstalls,
+  promptConfirm,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {
@@ -32,7 +32,8 @@
   ],
   "scripts": {
     "build": "tsx bin/forge-build.ts",
-    "clean": "tsx bin/forge-build.ts --clean"
+    "clean": "tsx bin/forge-build.ts --clean",
+    "test": "node --test \"test/**/*.test.mjs\""
   },
   "devDependencies": {
     "@types/node": "^22.10.0",