plain-forge 1.0.12 → 1.0.13

package/README.md

@@ -95,6 +95,27 @@ 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.
 
+#### Removing an install
+
+```bash
+npx plain-forge uninstall
+```
+
+`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.
+
+By default it removes **every** agent layout in the **project** scope (the current folder). Narrow it with flags:
+
+```bash
+npx plain-forge uninstall --agent claude --scope global
+```
+
+| 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
 
 ### Prerequisites
@@ -154,36 +175,24 @@ 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
+
+test/
+  cli.test.mjs               # tests for the install / update CLI
+
+package.json                 # ships only `bin/cli.mjs` and `forge/` to npm
 ```
 
+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
 
 ### Core Workflow

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();

package/package.json

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