claudemd-cli 0.74.2 → 0.76.0

package/README.md

@@ -35,7 +35,7 @@ Then bootstrap the **current** session (skip the wait-for-next-session restart)
 
 Fallback (no slash command — e.g. scripting outside CC): `node ~/.claude/plugins/cache/claudemd/claudemd/<version>/scripts/install.js`. Find `<version>` with `ls ~/.claude/plugins/cache/claudemd/claudemd/ | sort -V | tail -1`.
 
-> ⚠️ **`~/.claude/CLAUDE.md` is shared real estate.** Claude Code reads this file as your user-global instructions across every project. If you've hand-written personal instructions there (`Always reply in 中文`, `My name is X`, etc.), install moves your existing files to `~/.claude/backup-<ISO>/` (last 5 kept automatically) before writing the spec. Since v0.5.3, install prints a `[claudemd] WARN: …` line to stderr when the existing file does not look like a claudemd spec. To bring your personal instructions back on uninstall, run `CLAUDEMD_SPEC_ACTION=restore /claudemd-uninstall`.
+> ⚠️ **`~/.claude/CLAUDE.md` is shared real estate.** Claude Code reads this file as your user-global instructions across every project. If you've hand-written personal instructions there (`Always reply in 中文`, `My name is X`, etc.), install moves your existing files to `~/.claude/backup-<ISO>/` (last 5 kept automatically) before writing the spec. Since v0.5.3, install prints a `[claudemd] WARN: …` line to stderr when the existing file does not look like a claudemd spec — visible when you run `/claudemd-install` (or `install.js`) yourself. Since v0.75.0 the **SessionStart** bootstrap, where that stderr goes to `claudemd-bootstrap.log` instead, raises the same notice as an in-session banner naming the backup path (silence it with `DISABLE_USER_CONTENT_BANNER=1`). To bring your personal instructions back on uninstall, run `CLAUDEMD_SPEC_ACTION=restore /claudemd-uninstall`.
 
 ---
 
@@ -209,6 +209,29 @@ export DISABLE_COMPACT_REREAD_REMINDER=1   # v0.27.0+ — only the post-compacti
                                            # source=="compact"); compact events still
                                            # skip bootstrap/upgrade-banner either way.
 
+export CLAUDEMD_FORCE_ASYNC_BOOTSTRAP=1    # v0.75.0+ — restores the pre-0.75.0 detached
+                                           # bootstrap on the FRESH-install path (no
+                                           # manifest yet), which otherwise runs install.js
+                                           # synchronously inside the 5s SessionStart
+                                           # budget so ~/.claude/CLAUDE.md is on disk
+                                           # before Claude Code assembles context. Set it
+                                           # if a slow/networked $HOME makes that wait
+                                           # unacceptable; the cost is that the spec first
+                                           # reaches the model one session later. Upgrades
+                                           # are detached either way.
+
+export DISABLE_USER_CONTENT_BANNER=1       # v0.75.0+ — only the SessionStart notice
+                                           # that install.js moved a hand-written
+                                           # ~/.claude/CLAUDE.md into a backup dir.
+                                           # The backup and the install-time stderr
+                                           # WARN still happen; what stops is the
+                                           # in-session banner naming the backup
+                                           # path and the restore command. The hook
+                                           # still consumes its sentinel on this
+                                           # path, so opting out leaves no residue
+                                           # and cannot fire a late banner naming a
+                                           # since-pruned backup dir.
+
 export DISABLE_BOOTSTRAP_FAIL_BANNER=1     # v0.50.0+ — only the SessionStart banner
                                            # reporting that a PRIOR session's background
                                            # install.js upgrade failed; the failure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudemd-cli",
-  "version": "0.74.2",
+  "version": "0.76.0",
   "description": "Standalone CLI for §10-V banned-vocab + transcript scanning. Companion to the claudemd Claude Code plugin (github.com/sdsrss/claudemd) for use in git pre-commit hooks, GitHub Actions, and other agents.",
   "type": "module",
   "bin": {

package/scripts/lib/argv.js

@@ -11,6 +11,9 @@
 // Caller catches `ArgvError` and exits 2 (distinct from numeric-validation
 // exit 1) so wrappers can tell parsing-shape errors from validation errors.
 
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
 export class ArgvError extends Error {
   constructor(message) {
     super(message);
@@ -18,6 +21,31 @@ export class ArgvError extends Error {
   }
 }
 
+// invokedAsMain(import.meta.url) — "did node start the program at THIS file?"
+//
+// The obvious spelling compares `import.meta.url` against a `file://` string
+// built from process.argv[1]. Both halves of that comparison lie:
+//   - node resolves import.meta.url through symlinks, argv[1] stays as typed,
+//     so a plugin dir reached through a link (a dotfiles ~/.claude, a
+//     `git worktree`, macOS /var -> /private/var) compares unequal;
+//   - a URL percent-encodes what a path spells literally, so one space in the
+//     path is `%20` on one side and ` ` on the other.
+// Either way the main block does not run: the CLI exits 0 having printed
+// nothing, which every caller reads as success. install.js failing this way
+// returns "ok" while writing no manifest, so SessionStart re-enters the
+// fresh-install branch forever (2026-09-05 audit P0-1).
+//
+// realpath BOTH sides and the two failure modes collapse into one comparison.
+// Throwing inputs (argv[1] undefined under `node -e`, a path that no longer
+// exists) mean "not the program" — false, never a crash.
+export function invokedAsMain(importMetaUrl) {
+  try {
+    return fs.realpathSync(fileURLToPath(importMetaUrl)) === fs.realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
 // Discoverability helper: when `--help` or `-h` is the first non-empty arg
 // (or anywhere in argv for scripts with no flags), print usage to stdout and
 // exit 0. Caller invokes BEFORE parseStrict so unknown-arg rejection doesn't
@@ -122,6 +150,23 @@ export function parseStrict(argv, { bools = [], values = [] } = {}) {
   }
   return out;
 }
+// parseStrictOrExit — parseStrict with the exit contract every CLI in this repo
+// repeated verbatim: an ArgvError is a usage error, so print the one-line reason
+// and exit 2; anything else is a bug and keeps its stack. Seventeen main blocks
+// spelled this out by hand (jscpd's nine largest non-test clones were all this
+// block), which is seventeen chances for one of them to swallow the rethrow or
+// exit with a different code than its own USAGE documents.
+export function parseStrictOrExit(argv, spec = {}) {
+  try {
+    return parseStrict(argv, spec);
+  } catch (e) {
+    if (e instanceof ArgvError) {
+      console.error(e.message);
+      process.exit(2);
+    }
+    throw e;
+  }
+}
 
 // Space-form argv validator for the published `claudemd-cli` binary.
 //