plain-forge 1.0.9 → 1.0.11

package/README.md

@@ -81,7 +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.
+
+#### Updating an existing install
+
+```bash
+npx plain-forge@latest update
+```
+
+`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.
+
+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.
+
+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.
 
 ### Alternative install paths (skills only — no rules or docs)
 

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,40 @@ async function main() {
   }
 }
 
-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);
-});
+// Only run the CLI when executed directly — importing this module (e.g. from
+// the test suite) must not trigger main() or process.exit().
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === __filename;
+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/forge/rules/integrations.md

@@ -44,8 +44,10 @@ A single `.plain` module can (and typically will) reference many resources. That
 
 Documentation lies — it goes stale, omits undocumented fields, describes a different API version, papers over breaking changes. Every integration spec must be grounded in what the API really returns, not what the docs claim it returns.
 
+- **Discover the documentation links with web search first, then `fetch` all of them.** Documentation moves, gets reorganized, and is versioned — so never assume a doc URL from memory. Begin every topic by issuing **web searches with human-readable queries** to find the canonical pages, then `fetch` **every** relevant link the search surfaces — the endpoint reference, the auth guide, the webhook catalog, the error reference, the pagination/rate-limit docs, the changelog. The search step finds *which* URLs are authoritative and current; the `fetch` step retrieves their actual content. Do not stop at the first hit — fetch the full set so a topic is grounded in all of its sources, not a single page.
+  - If the environment has **no web-search tool** (only URL-based `fetch` is available), say so explicitly, construct the URL from the provider's well-known documentation root and crawl outward by `fetch`-ing that root and following its links, and ask the user for the canonical URL whenever you cannot reach the right page that way. Never substitute memory for the search-then-fetch step.
 - **Always `fetch` the provider's documentation — even if you already "know" the API.** The only acceptable source of truth for what the API looks like *today* is the provider's own live documentation, retrieved with `fetch` at spec-authoring time. This applies without exception — there is no API well-known enough to skip this step, and a spec authored from memory is a spec authored against the wrong contract. Concretely:
-  - Before authoring **any** endpoint, auth, error, pagination, or webhook concept, `fetch` the relevant documentation page(s) and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
+  - Before authoring **any** endpoint, auth, error, pagination, or webhook concept, **web-search to locate the relevant documentation page(s), then `fetch` each one** and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
   - Save the fetched documentation snapshot under `resources/docs/<provider>/<page>.md` (or `.html` if structure matters) so the spec has a stable doc artifact the renderer and reviewers can consult, independent of the live URL changing or going behind auth.
   - If a documentation page is unreachable (paywall, login wall, JS-only render that `fetch` can't see), say so explicitly and ask the user for the canonical content rather than filling the gap from memory.
   - **The fetched documentation is then cross-checked against the live API** — see the rest of this section.
@@ -133,4 +135,5 @@ A production-ready integration spec captures every corner case the API can throw
 - **Authoring against unverified credentials.** Validate first; if the user has no credentials yet, flag it in the module's frontmatter description and re-validate once credentials arrive
 - **`requires`-ing a separate-stack module** (a Python backend `requires`-ing a React frontend, or vice versa) — see [`requires-modules.md`](requires-modules.md). Use a shared API schema in `resources/` instead
 - **Authoring Phase 1 specs from the docs first and "reconciling" with the live API later.** Probe the API as you reach each topic; the live response is the source of truth from the moment it's captured
-- **Writing any integration spec from memory of the provider's API instead of `fetch`-ing its documentation first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the documentation must be retrieved with `fetch` at spec-authoring time and saved under `resources/docs/<provider>/` — see *Live API must be cross-checked against the documentation*. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call
+- **Writing any integration spec from memory of the provider's API instead of web-searching for its documentation and `fetch`-ing every relevant page first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the canonical pages must be located with web search and then retrieved with `fetch` at spec-authoring time and saved under `resources/docs/<provider>/` — see *Live API must be cross-checked against the documentation*. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call
+- **Guessing a documentation URL from memory and `fetch`-ing it without searching first.** A remembered URL may 404, redirect to a stale version, or miss the page that actually documents the topic. Search to find the authoritative, current links, then fetch the full set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "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",