plain-forge 1.0.11 → 1.0.13

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
@@ -95,39 +95,26 @@ Each deprecated file is confirmed individually before it's deleted — you'll se
 
 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)
-
-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
+#### Removing an install
 
 ```bash
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent claude-code
-```
-
-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
+npx plain-forge uninstall
 ```
 
-Without the reload the skills won't appear in the current session.
+`uninstall` reads the install manifest (`<agent-dir>/.plain-forge/manifest.json`) and deletes **exactly** the files plain-forge wrote, then the manifest itself, then any directory left empty (including the agent directory). Your own skills and third-party content are never in the manifest, so they are never touched.
 
-#### Codex native plugin flow
-
-Requires the [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference). From your shell:
+By default it removes **every** agent layout in the **project** scope (the current folder). Narrow it with flags:
 
 ```bash
-codex plugin marketplace add Codeplain-ai/plain-forge
+npx plain-forge uninstall --agent claude --scope global
 ```
 
-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.)
+| Flag | Default | Values |
+|------|---------|--------|
+| `--agent` | `*` (all agents) | `claude`, `codex`, `forgecode`, `universal`, or `*` |
+| `--scope` | `project` | `project` (cwd) or `global` (home directory) |
+
+If an install has **no manifest** (e.g. one that predates manifests), `uninstall` cannot tell which files are plain-forge's, so it refuses to delete anything: it prints an error, lists the directories to clean up by hand, and exits non-zero. Refresh such an install with `update` first (which writes a manifest going forward), then `uninstall`.
 
 ## Usage
 
@@ -188,49 +175,23 @@ Hit a bug in the rendered app, a failing test, or behavior that doesn't match wh
 
 ## Repository Structure
 
-plain-forge keeps a single canonical source of truth under `forge/` and uses tiny per-runtime adapters to regenerate the directory layout each AI tool expects. The generated outputs are committed so existing install commands keep working — no build step is needed for end users.
+plain-forge keeps a single canonical source of truth under `forge/`. The `plain-forge install` CLI copies that content straight into whichever agent directory you choose — there is no build step and no generated, committed output to keep in sync.
 
 ```
-forge/                       # canonical, runtime-neutral content
+forge/                       # canonical content, copied verbatim on install
   skills/                    # all skills used during spec writing
-  rules/                     # workspace rules for spec validation
-
-runtimes/                    # per-runtime adapters
-  claude/
-    build.ts                 # generates .claude/ + .claude-plugin/ from forge/
-    templates/               # Claude-specific files: settings.json, hook script, plugin manifests
-  codex/
-    build.ts                 # generates .codex-plugin/ and .agents/plugins/ (manifest points at forge/skills/)
-    templates/               # Codex-specific files: plugin.json, marketplace catalog
-  opencode/
-    build.ts                 # generates .opencode/ from forge/
-    templates/               # OpenCode-specific files: package.json, .gitignore
+  rules/                     # spec-writing rules (installed as workspace instructions)
 
 bin/
-  forge-build.ts             # orchestrator: runs every runtimes/*/build.ts
-  lib.ts                     # shared symlink/copy helpers
-
-# Generated outputs (committed, do not edit by hand):
-.claude/                     # Claude Code plugin layout
-.claude-plugin/              # Claude Code plugin manifests
-.codex-plugin/               # Codex plugin manifest (its "skills" field points at forge/skills/)
-.agents/plugins/             # Codex marketplace catalog
-.opencode/                   # OpenCode plugin layout
-```
+  cli.mjs                    # the `plain-forge` CLI — `install` and `update` commands
 
-### Contributing
+test/
+  cli.test.mjs               # tests for the install / update CLI
 
-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
+package.json                 # ships only `bin/cli.mjs` and `forge/` to npm
 ```
 
-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`.
+On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.codex/`, `.forgecode/`, or `.agents/`), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely.
 
 ## Available Skills
 

package/bin/cli.mjs

@@ -78,8 +78,9 @@ function usage() {
   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
+  install     Install plain-forge into an agent directory
+  update      Refresh every existing plain-forge install in cwd and $HOME
+  uninstall   Remove a plain-forge install using its manifest
 
 Install options:
   --agent <claude|codex|forgecode|universal>   Target agent layout
@@ -90,16 +91,25 @@ Update options:
   -y, --yes                                    Remove deprecated files without
                                                confirming each one
 
+Uninstall options:
+  --agent <claude|codex|forgecode|universal|*> Which install to remove
+                                               (default: * — every agent)
+  --scope <project|global>                     Where to look (default: project)
+
 Examples:
   plain-forge install --agent claude --scope project
   plain-forge install --agent universal --scope global
   plain-forge update
   plain-forge update --yes
+  plain-forge uninstall
+  plain-forge uninstall --agent claude --scope global
 
 "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.`);
+(confirming each removal), leaving your own and third-party skills untouched.
+"uninstall" deletes exactly the files recorded in the install manifest, then
+the manifest itself; an install with no manifest is reported and left in place.`);
 }
 
 function parseArgs(argv) {
@@ -488,6 +498,95 @@ async function cmdUpdate(args) {
   }
 }
 
+async function cmdUninstall(args) {
+  printBanner();
+
+  const scope = args.scope ?? "project";
+  if (!SCOPES.includes(scope)) {
+    console.error(`unknown scope "${scope}". valid: ${SCOPES.join(", ")}`);
+    process.exit(2);
+  }
+
+  // Default agent is "*" — every agent layout. A named agent narrows to one.
+  const agentArg = args.agent ?? "*";
+  let agents;
+  if (agentArg === "*" || agentArg === "all") {
+    agents = Object.keys(AGENTS);
+  } else if (Object.hasOwn(AGENTS, agentArg)) {
+    agents = [agentArg];
+  } else {
+    console.error(
+      `unknown agent "${agentArg}". valid: ${Object.keys(AGENTS).join(", ")}, or "*" for all`,
+    );
+    process.exit(2);
+  }
+
+  const root = scope === "global" ? os.homedir() : process.cwd();
+
+  let found = 0;
+  let removed = 0;
+  let hadError = false;
+
+  for (const agent of agents) {
+    const baseDir = path.join(root, AGENTS[agent]);
+    if (!fs.existsSync(baseDir)) continue;
+
+    const manifest = readManifest(baseDir);
+    const legacy = !manifest && hasForgeSignature(baseDir);
+    if (!manifest && !legacy) continue; // not a plain-forge install
+    found++;
+
+    // No manifest → we have no record of which files are ours, so deleting
+    // would risk touching the user's own content. Refuse and point at the
+    // directories to clean by hand.
+    if (!manifest) {
+      hadError = true;
+      console.error(`cannot uninstall ${agent} (${scope}) — ${baseDir}`);
+      console.error(
+        `  the install manifest (${MANIFEST_REL}) is missing, so automatic deletion is not supported.`,
+      );
+      console.error(`  please remove plain-forge's files manually from:`);
+      for (const dir of CONTENT_DIRS) {
+        const p = path.join(baseDir, dir);
+        if (fs.existsSync(p)) console.error(`    ${p}`);
+      }
+      console.error("");
+      continue;
+    }
+
+    let deleted = 0;
+    let failed = 0;
+    for (const rel of manifest.files) {
+      if (deleteForgeFile(baseDir, rel)) deleted++;
+      else failed++;
+    }
+    // Finally remove the manifest itself, then prune the now-empty .plain-forge
+    // directory and the agent directory if nothing else remains in it.
+    fs.rmSync(manifestPathFor(baseDir), { force: true });
+    removeEmptyDirsUpward(
+      path.join(baseDir, path.dirname(MANIFEST_REL)),
+      baseDir,
+    );
+    removeEmptyDirsUpward(baseDir, root);
+
+    console.log(`uninstalled ${agent} (${scope}) from ${baseDir}`);
+    console.log(
+      `  removed ${deleted} file(s)${failed ? `, ${failed} could not be removed` : ""} + manifest`,
+    );
+    console.log();
+    removed++;
+  }
+
+  if (found === 0) {
+    console.log(`no plain-forge installation found in ${root} (scope: ${scope}).`);
+    return;
+  }
+  if (removed > 0) {
+    console.log(`uninstalled ${removed} installation(s).`);
+  }
+  if (hadError) process.exit(1);
+}
+
 function printNextSteps(agent) {
   const bold = (s) => `\x1b[1;97m${s}\x1b[0m`;
   const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -548,6 +647,9 @@ async function main() {
     case "update":
       await cmdUpdate(args);
       break;
+    case "uninstall":
+      await cmdUninstall(args);
+      break;
     default:
       console.error(`unknown command "${cmd}"`);
       usage();
@@ -557,8 +659,21 @@ async function main() {
 
 // 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;
+// `__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;
+  }
+}
+const invokedDirectly = isInvokedDirectly();
 if (invokedDirectly) {
   main().catch((err) => {
     if (err instanceof Error && err.message === "cancelled") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {