archgen-skill 0.0.6 → 0.1.0

package/README.md

@@ -42,6 +42,13 @@ copies are backed up to `.archgen/.backup/<timestamp>/` before refresh, and lega
 dual-copy layouts are migrated to symlinks automatically. Verify anytime with
 `archgen-skill doctor`.
 
+Every destructive step is behind a rail: the project root is asserted **before**
+anything is written or deleted, a symlinked target is never written through, the
+store swap is atomic (the old store is moved aside, not deleted, and restored if
+the swap fails), and a restore puts back exactly the paths the snapshot recorded
+— never a sibling skill. `archgen-skill uninstall <dir>` removes that project;
+the global uninstall happens only when no project is named.
+
 **Or install globally** into every detected harness:
 
 ```bash
@@ -80,7 +87,7 @@ by git.
 | `npx archgen-skill init [dir]` | Prepare a project: canonical skill store at `.agents/skills/archgen`, Claude symlink adapter, AGENTS.md hub + CLAUDE.md bridge |
 | `npx archgen-skill install [--copy]` | Install into global harness skill dirs (symlinks by default, real copies with `--copy`) |
 | `npx archgen-skill uninstall` | Remove globally-installed copies (manifest-recorded, safe removal) |
-| `npx archgen-skill uninstall --project [dir]` | Remove a project install: strips managed blocks, symlink, and store **only if unmodified** — `.archgen/` feature folders and all user content are preserved |
+| `npx archgen-skill uninstall [dir]` | Remove a **project** install (same as `--project [dir]`): strips managed blocks, symlink, the store **only if unmodified**, and the dead `.archgen/.runtime/` extension state — `.archgen/` feature folders and all user content are preserved |
 | `npx archgen-skill doctor [dir] [--check]` | Verify and auto-repair an installation: store integrity, version stamp, Claude link, managed blocks, manifest (`--check` reports without fixing) |
 | `npx archgen-skill update [dir]` | Check npm for a newer `archgen-skill`, upgrade the global install if outdated, then re-init the project and run doctor against the new version |
 | `npx archgen-skill restore` | List backup snapshots; `--snapshot <ts>` restores one (current state is backed up first) |
@@ -128,15 +135,6 @@ Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Antigravity — and any
 agentskills.io-compatible harness. Both global install and project-local `init`
 are supported for all of them.
 
-## VS Code extension (optional)
-
-A visual layer that renders `.archgen/` as a live task DAG, your
-code-dependency graph, and rendered docs — with a ▶ button that hands any task to
-your agent. Install it from the VS Code Marketplace or from a `.vsix` on
-[GitHub Releases](https://github.com/akashmaurya99/archgen/releases). It never
-edits your plan, your tasks, or your code — only its own runtime state under
-`.archgen/.runtime/`, so uninstalling it loses nothing.
-
 ## Documentation
 
 | Doc | Contents |

package/bin/archgen.mjs

@@ -22,7 +22,7 @@ import { uninstallProject } from '../lib/uninstall-project.js';
 import { restoreMain } from '../lib/restore.js';
 import { migrateMain } from '../lib/migrate.js';
 import { compareSemver, fetchLatestVersion } from '../lib/version.js';
-import { npmInvocation, whichOnPath } from '../lib/spawn-npm.js';
+import { npmInvocation, whichOnPath, globalBinPath } from '../lib/spawn-npm.js';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 
@@ -35,7 +35,13 @@ function cliVersion() {
 function runInitAndDoctor(dir) {
   const r = initProject(dir, PACKAGE_ROOT);
   console.log('  = store refreshed at ' + r.storePath);
-  doctorProject(dir, PACKAGE_ROOT, {});
+  const d = doctorProject(dir, PACKAGE_ROOT, {});
+  // A failed doctor must fail the update too: the project was NOT brought to
+  // the new version.
+  if (d.failures > 0) {
+    console.error('  ! doctor reported ' + d.failures + ' failure(s)');
+    process.exitCode = 1;
+  }
 }
 
 const HELP = `archgen — architecture generation & autonomous task execution for coding agents
@@ -45,20 +51,29 @@ Usage:
                                 store at .agents/skills/archgen, symlink
                                 .claude/skills/archgen -> ../../.agents/skills/archgen,
                                 and generate AGENTS.md / CLAUDE.md pointer blocks.
+    [--project <dir>]              the project directory (same as the positional
+                                   form; give it once, not both)
     [--force]                     proceed automatically; divergent copies are
                                   backed up to .archgen/.backup/ (never destroyed)
     [--no-codegraph]              skip the CodeGraph bootstrap
     [--no-mcp]                   skip wiring the archgen MCP server
+    [--location-project]          wire the PROJECT-local harness configs too
+                                   (by default only the global ones are wired,
+                                   so a project carries no MCP configuration)
   npx archgen-skill doctor [dir]      Health-check a project install: store integrity,
                                 version stamp, claude link, managed blocks,
                                 manifest. Repairs safe issues in place.
+    [--project <dir>]              the project directory (same as the positional form)
     [--check]                     report only - change nothing
   npx archgen-skill install           Install into global harness skill dirs
     [--copy]                      real copies instead of symlinks
     [--uninstall]                 remove manifest-recorded entries
     [--no-codegraph]              skip the CodeGraph bootstrap
     [--no-mcp]                   skip wiring the archgen MCP server
-  npx archgen-skill uninstall         Remove globally-installed copies (manifest-based)
+  npx archgen-skill uninstall [dir]     Remove archgen from a project (the same
+                                 as the positional form); without a directory
+                                 the globally-installed copies are removed
+                                 (manifest-based)
     --project [dir]               remove archgen from a project: claude link,
                                   managed blocks, canonical store (kept when
                                   customized) and manifest; .archgen feature
@@ -89,8 +104,63 @@ function flag(name) {
   return true;
 }
 
-function positionalDir() {
-  return rest[0] ? resolve(rest[0]) : process.cwd();
+/**
+ * Consume an option that takes a value: `--name <value>` or `--name=<value>`.
+ *
+ * Returns null when the option is absent, '' when it is present with no
+ * value ("use the default"), and the value otherwise.
+ */
+function takeValue(name) {
+  const eq = rest.findIndex((a) => a.startsWith(name + '='));
+  if (eq !== -1) {
+    const v = rest[eq].slice(name.length + 1);
+    rest.splice(eq, 1);
+    return v;
+  }
+  const i = rest.indexOf(name);
+  if (i === -1) return null;
+  rest.splice(i, 1);
+  const v = rest[i];
+  if (v === undefined || v.startsWith('-')) return '';
+  rest.splice(i, 1);
+  return v;
+}
+
+/**
+ * The project directory for a command.
+ *
+ * Accepts a POSITIONAL dir (`init myproj`) and `--project <dir>` alike. The
+ * same flag name is used by `uninstall` and `restore`, and the MCP server's
+ * own commands take `--project` too — so a user who typed one form must
+ * never get a directory literally named "--project" created in their cwd.
+ *
+ * Extra positional arguments are REFUSED: silently ignoring the second one
+ * would install into a directory the user did not name.
+ */
+function targetDir() {
+  const explicit = takeValue('--project');
+  const positionals = rest.filter((a) => !a.startsWith('-'));
+  if (positionals.length > 1) {
+    throw new Error(`unexpected argument: ${positionals[1]} — give the project directory once`);
+  }
+  const positional = positionals[0];
+  const explicitDir = explicit === null ? null : (explicit === '' ? process.cwd() : resolve(explicit));
+  if (explicitDir !== null && positional !== undefined && explicitDir !== resolve(positional)) {
+    throw new Error('give the project directory once: either positionally or with --project');
+  }
+  return explicitDir ?? (positional !== undefined ? resolve(positional) : process.cwd());
+}
+
+/**
+ * Refuse an option we do not understand.
+ *
+ * An unknown flag is a TYPO. It is never a directory name — creating a
+ * directory called "--no-mcp" because the flag was misspelled is exactly the
+ * kind of silent mess this check exists to prevent.
+ */
+function assertNoUnknownFlags() {
+  const unknown = rest.find((a) => a.startsWith('-'));
+  if (unknown) throw new Error(`unknown option: ${unknown}`);
 }
 
 try {
@@ -99,7 +169,17 @@ try {
       flag('--force');
       const noCodegraph = flag('--no-codegraph');
       const noMcp = flag('--no-mcp');
-      const r = initProject(positionalDir(), PACKAGE_ROOT, { codegraph: !noCodegraph, mcp: !noMcp });
+      // The harness configs live in the user's home by default, so a project
+      // carries no MCP configuration of its own. `--location project` opts
+      // into wiring the project-local configs instead.
+      const location = flag('--location-project') ? 'project' : 'global';
+      const dir = targetDir();
+      assertNoUnknownFlags();
+      const r = initProject(dir, PACKAGE_ROOT, {
+        codegraph: !noCodegraph,
+        mcp: !noMcp,
+        location,
+      });
       console.log('archgen: project ready (single-store layout)');
       console.log('  + store ' + r.storePath);
       if (r.claudeLink === 'created') console.log('  + link  .claude/skills/archgen -> ../../.agents/skills/archgen');
@@ -117,7 +197,9 @@ try {
     }
     case 'doctor': {
       const check = flag('--check');
-      const r = doctorProject(positionalDir(), PACKAGE_ROOT, { check });
+      const dir = targetDir();
+      assertNoUnknownFlags();
+      const r = doctorProject(dir, PACKAGE_ROOT, { check });
       console.log('archgen doctor — ' + r.root + (check ? '  (check mode: no changes made)' : ''));
       for (const c of r.checks) console.log(`  [${c.status.toLowerCase().padEnd(9)}] ${c.msg}`);
       const t = r.tally;
@@ -129,7 +211,11 @@ try {
       const copy = flag('--copy');
       const noCodegraph = flag('--no-codegraph');
       const noMcp = flag('--no-mcp');
-      if (flag('--uninstall')) { uninstall(); break; }
+      const uninstallMode = flag('--uninstall');
+      assertNoUnknownFlags();
+      const stray = rest.find((a) => !a.startsWith('-'));
+      if (stray) throw new Error(`unexpected argument: ${stray} — install takes no directory`);
+      if (uninstallMode) { uninstall(); break; }
       const r = installGlobal({ copy, codegraph: !noCodegraph, mcp: !noMcp });
       console.log('archgen: global harness install (mode: ' + (copy ? 'copy' : 'symlink') + ')');
       for (const [status, mode, path] of r.rows) console.log(`  ${status.padEnd(7)} ${mode.padEnd(5)} ${path}`);
@@ -138,14 +224,32 @@ try {
       break;
     }
     case 'uninstall': {
-      if (flag('--project')) {
-        const r = uninstallProject(positionalDir(), PACKAGE_ROOT);
+      // `--project` may carry a directory (`uninstall --project myproj`) or
+      // stand alone (`uninstall --project` → this directory). A POSITIONAL
+      // directory (`uninstall myproj`) is a project uninstall as well: the
+      // GLOBAL uninstall happens only when no project was named at all.
+      const explicit = takeValue('--project');
+      const positionals = rest.filter((a) => !a.startsWith('-'));
+      assertNoUnknownFlags();
+      if (positionals.length > 1) {
+        throw new Error(`unexpected argument: ${positionals[1]} — give the project directory once`);
+      }
+      const positional = positionals[0];
+      const projectTarget = explicit !== null
+        ? (explicit === '' ? process.cwd() : resolve(explicit))
+        : (positional !== undefined ? resolve(positional) : null);
+      if (explicit !== null && positional !== undefined && projectTarget !== resolve(positional)) {
+        throw new Error('give the project directory once: either positionally or with --project');
+      }
+      if (projectTarget !== null) {
+        const r = uninstallProject(projectTarget, PACKAGE_ROOT);
         console.log('archgen: project uninstall — ' + r.root);
         if (r.linkRemoved) console.log('  - .claude/skills/archgen (link)');
         if (r.strippedBlocks.length) console.log('  - managed blocks stripped from ' + r.strippedBlocks.join(', '));
         if (r.storeRemoved) console.log('  - .agents/skills/archgen (unmodified store)');
         if (r.storeKept) console.log('  = .agents/skills/archgen KEPT (customized)');
         if (r.manifestRemoved) console.log('  - .archgen/.install-manifest.json');
+        if (r.runtimeRemoved) console.log('  - .archgen/.runtime (legacy extension state)');
         for (const m of r.mcpRemoved ?? []) console.log(`  - ${m} (archgen MCP entry)`);
         for (const w of r.warnings) console.log('  note: ' + w);
         console.log('  .archgen feature folders and backups are preserved.');
@@ -166,7 +270,8 @@ try {
       break;
     }
     case 'update': {
-      const dir = positionalDir();
+      const dir = targetDir();
+      assertNoUnknownFlags();
       const current = cliVersion();
       console.log('archgen update — running v' + current + ', checking npm registry…');
       const latest = fetchLatestVersion('archgen-skill');
@@ -175,6 +280,14 @@ try {
         break;
       }
       const cmp = compareSemver(latest, current);
+      if (cmp === null) {
+        // The registry answered with something that is not a semver (e.g. a
+        // "beta" dist-tag). It is NOT "already the latest version" — refuse
+        // instead, and never interpolate it into a command line.
+        console.error('  ! registry returned a non-semver version string; refusing: ' + JSON.stringify(latest));
+        process.exitCode = 1;
+        break;
+      }
       if (cmp === 0) {
         console.log('  = already on the latest published version (' + latest + ').');
         console.log('  Refreshing this project against it anyway…');
@@ -204,7 +317,9 @@ try {
         break;
       }
       // The running process is the OLD code; re-exec the freshly installed binary.
-      const freshBin = whichOnPath('archgen-skill');
+      // The PATH search would find the FIRST match — often the OLD global
+      // install — so the binary npm actually wrote is preferred.
+      const freshBin = globalBinPath('archgen-skill') ?? whichOnPath('archgen-skill');
       if (!freshBin) {
         console.log('\nUpgraded to v' + latest + '. Now finish per project with:\n  npx archgen-skill@latest init');
         break;
@@ -218,7 +333,13 @@ try {
         process.exitCode = upInit.status ?? 1;
         break;
       }
-      spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      const upDoctor = spawnSync(freshBin, ['doctor', dir], { stdio: 'inherit' });
+      if (upDoctor.status !== 0) {
+        // A failed doctor must fail the update too — the project was NOT
+        // brought to the new version.
+        console.error('  ! doctor failed during update (see message above)');
+        process.exitCode = upDoctor.status ?? 1;
+      }
       break;
     }
     case '--version': case '-v': {
@@ -243,5 +364,6 @@ function uninstall() {
   const r = uninstallGlobal();
   if (r.noop) { console.log('archgen: nothing to uninstall (no manifest found).'); return; }
   console.log(`archgen: removed ${r.removed} entr${r.removed === 1 ? 'y' : 'ies'}` + (r.failed ? `, ${r.failed} FAILED` : ''));
+  for (const b of r.backups ?? []) console.log('  ~ backup ' + b + ' (edited copy saved before removal)');
   if (r.failed > 0) process.exitCode = 1;
 }

package/lib/block.js

@@ -16,7 +16,7 @@
 // place on the next init/doctor pass and detectBlockVersion() lets doctor
 // report stale formats precisely.
 
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { loadConfig } from './config.js';
 import { assertNotSymlink } from './store.js';
 
@@ -171,11 +171,14 @@ export function upsertBlock(existing, block, eol = '\n') {
     if (s === -1 || e === -1) {
       throw new Error('found only one archgen marker - fix or remove it manually');
     }
+    const prefix = trimmed.slice(0, s);
     const tail = stripCompleteBlocks(trimmed.slice(e + END.length));
-    if (tail.includes(START) || tail.includes(END)) {
+    // An orphan marker ANYWHERE (before the first block as well as after it)
+    // would survive the rewrite and leave the file broken — refuse instead.
+    if (prefix.includes(START) || prefix.includes(END) || tail.includes(START) || tail.includes(END)) {
       throw new Error('found only one archgen marker - fix or remove it manually');
     }
-    return trimmed.slice(0, s) + fresh + tail;
+    return prefix + fresh + tail;
   }
 
   const startIdx = trimmed.indexOf(START);
@@ -209,13 +212,37 @@ function splitBom(raw) {
   return { bom, body: bom ? raw.slice(1) : raw };
 }
 
-/** Write via sibling temp file + rename so readers never observe partial content. */
-function atomicWrite(absPath, data) {
-  const tmp = absPath + '.tmp-' + process.pid + '-' + Date.now();
-  // 'wx' (O_CREAT|O_EXCL): if the tmp name already exists — e.g. an attacker
-  // planted a symlink there to redirect the write — fail instead of following.
-  writeFileSync(tmp, data, { flag: 'wx' });
-  renameSync(tmp, absPath);
+/**
+ * Write via sibling temp file + rename so readers never observe partial content.
+ * @param {string} absPath target file
+ * @param {string} data contents
+ */
+export function atomicWrite(absPath, data) {
+  let tmp = absPath + '.tmp-' + process.pid + '-' + Date.now();
+  for (let attempt = 0; ; attempt++) {
+    try {
+      // 'wx' (O_CREAT|O_EXCL): if the tmp name already exists — e.g. an attacker
+      // planted a symlink there to redirect the write — fail instead of following.
+      writeFileSync(tmp, data, { flag: 'wx' });
+      break;
+    } catch (e) {
+      // A collision (two writes inside the same millisecond) is not a failure:
+      // retry with a fresh name instead of failing the whole write.
+      if (e && e.code === 'EEXIST' && attempt < 10) {
+        tmp = absPath + '.tmp-' + process.pid + '-' + Date.now() + '-' + (attempt + 1);
+        continue;
+      }
+      throw e;
+    }
+  }
+  try {
+    renameSync(tmp, absPath);
+  } catch (e) {
+    // Never leave the temp file behind: a failed rename must not litter the
+    // project with half-written siblings.
+    try { unlinkSync(tmp); } catch { /* original intact; leftover tmp is harmless */ }
+    throw e;
+  }
 }
 
 /**
@@ -250,6 +277,20 @@ export function importsAgents(absPath) {
   return body.split(/\r?\n/).some((l) => l.trim() === '@AGENTS.md');
 }
 
+/**
+ * True when the file carries a COMPLETE managed block (both markers).
+ *
+ * A file with a hand-written `@AGENTS.md` import has none — that import is
+ * the user's, not ours, and must survive untouched. A file WITH a managed
+ * block is ours: its provenance stamp is refreshed on every init, exactly
+ * like the AGENTS.md block.
+ */
+export function hasManagedBlock(absPath) {
+  let raw = '';
+  try { raw = readFileSync(absPath, 'utf8'); } catch { return false; }
+  return raw.includes(START) && raw.includes(END);
+}
+
 /** Strip the managed block from a file on disk, preserving BOM. */
 export function stripManagedFile(absPath) {
   assertNotSymlink(absPath);

package/lib/bootstrap.js

@@ -3,37 +3,43 @@
 //
 // The CLI used to shell out to the skill's scripts/codegraph.mjs. That script
 // no longer exists: ALL deterministic capability now lives in the archgen MCP
-// server, so the CLI drives THAT instead. One implementation, three ways in
-// (agent -> MCP stdio, CLI -> `archgen-mcp bootstrap`, extension -> exec).
+// server, so the CLI drives THAT instead. One implementation, two ways in
+// (agent -> MCP stdio, CLI -> `archgen-mcp bootstrap`).
 //
 // The bootstrap does two things in one pass:
 //   1. wires the archgen MCP entry into every detected harness
 //   2. ensures CodeGraph: its CLI, its MCP entry, and the project index
 //
 // NEVER FATAL: no npm, no network, a read-only config, or a missing MCP
-// server must still leave a working skill install. Failures are REPORTED,
-// never thrown.
+// server must still leave a working skill install. Failures are REPORTED to
+// the caller (ok:false + detail) and rendered as a warning by it — never
+// thrown, and never swallowed.
 import { bootstrapMcp, resolveMcpBinary } from './mcp-server.js';
+import { ensureGlobalServer, serverVersion } from './global-server.js';
 
 /**
  * @param {{
  *   projectDir: string,
+ *   packageRoot?: string,
  *   location?: 'project'|'global'|'both',
  *   log?: (line: string) => void,
  *   env?: Record<string, string|undefined>,
  *   noCodegraph?: boolean,
  *   noMcp?: boolean,
+ *   global?: boolean,
  * }} opts
  * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
  */
 export function bootstrapServers(opts) {
   const {
     projectDir,
+    packageRoot = null,
     location = 'both',
     log = () => {},
     env = process.env,
     noCodegraph = false,
     noMcp = false,
+    global = true,
   } = opts;
 
   // ARCHGEN_CODEGRAPH=0 skips the bootstrap (no spawn, no network, no writes)
@@ -45,8 +51,25 @@ export function bootstrapServers(opts) {
     return { ok: true, skipped: '--no-mcp and --no-codegraph passed' };
   }
 
+  // ONE server for every harness. A global install gives every harness the
+  // same binary at a stable path, so a harness config can name an absolute
+  // executable that keeps working — instead of pointing into npm's npx
+  // CACHE, which `npm cache clean` removes out from under it.
+  //
+  // The server is refreshed to the version THIS CLI ships with: the CLI and
+  // the server are released together, so an older server is an older
+  // implementation of the very tools the CLI wires.
+  let serverNote = '';
+  if (global && !noMcp) {
+    const version = packageRoot ? serverVersion(packageRoot) : 'latest';
+    const installed = ensureGlobalServer({ env, version });
+    serverNote = installed.note;
+    if (installed.detail) serverNote += ` (${installed.detail})`;
+  }
+
   const resolved = resolveMcpBinary({ projectRoot: projectDir, env });
   log(`  + mcp server: ${resolved.bin ?? 'npx -y archgen-mcp'} (${resolved.source})`);
+  if (serverNote) log(`  + mcp server: ${serverNote}`);
 
   if (noMcp) {
     log('  ! archgen MCP wiring skipped (--no-mcp)');
@@ -56,15 +79,18 @@ export function bootstrapServers(opts) {
   }
 
   const r = bootstrapMcp({
-    projectDir,
+    projectRoot: projectDir,
     location,
     approved: true,
     env,
   });
 
   if (!r.report) {
+    // The bootstrap did NOT run: report it as a failure so the caller tells
+    // the user. The skill install itself still succeeded — this is a warning,
+    // not a fatal error — but it must never be swallowed silently.
     return {
-      ok: true, // never fatal — the skill install itself succeeded
+      ok: false,
       detail: `server bootstrap incomplete: ${r.detail ?? 'unknown error'}`,
     };
   }
@@ -96,7 +122,7 @@ export function bootstrapServers(opts) {
     return {
       ok: false,
       report,
-      detail: 'one or more server bootstrap steps failed',
+      detail: r.detail ? `server bootstrap incomplete: ${r.detail}` : 'one or more server bootstrap steps failed',
     };
   }
   return { ok: true, report };

package/lib/config.js

@@ -2,8 +2,9 @@
 //
 // WHY: the version, managed-block marker strings, and well-known filenames
 // were hardcoded independently in block.js, store.js, install.js, install.sh,
-// and SKILL.md frontmatter — and drifted (SKILL.md advertised 1.0.0 while the
-// CLI shipped 0.0.x). The canonical file lives at <repo-root>/archgen.config.json;
+// and SKILL.md frontmatter — and drifted (SKILL.md advertised a version the
+// CLI had never shipped). The canonical file lives at
+// <repo-root>/archgen.config.json;
 // a byte-identical derived copy ships inside the published npm package at
 // vendor/skills/archgen/archgen.config.json (kept in sync by
 // scripts/sync-config.mjs + scripts/sync-vendor.mjs).