@bobfrankston/npmglobalize 1.0.215 → 1.0.217

package/README.md

@@ -142,19 +142,24 @@ npmglobalize --update-major
 
 ### 🔒 Security Auditing
 
-**Check vulnerabilities**:
-```bash
-npmglobalize              # Shows audit at end
-```
+Every run ends with an `npm audit` report. The **Release Summary** (or Transform Summary
+with `-nopublish`) carries an `Audit:` row — `✓ no vulnerabilities`, the severity counts,
+or `not run` with npm's reason (typically `ENOLOCK` when there is no lockfile). Critical
+and high findings are listed one per package in the **Issues Summary** at the very end,
+each with the advisory title and URL, how the package got in (`through …` / `pulled in
+by …` / `direct dependency`), and what would clear it:
 
-**Auto-fix vulnerabilities**:
-```bash
-npmglobalize --fix        # Runs npm audit fix
-```
+- `fix: npm audit fix` — a compatible update exists; the next run's fix step takes it
+- `fix: npm audit fix --force → node-gyp@13.0.2 (breaking — not run automatically)` — only a
+  semver-major bump clears it; npmglobalize never passes `--force`, that is your call
+- `fix: none published yet` — wait for upstream
+
+**Auto-fix** (`-fix`, **on by default**, remembered as `"fix": true` in `.globalize.json5`):
+`npm audit fix` runs before the pre-release commit, so a changed lockfile is committed with
+the release. It only ever installs semver-compatible updates.
 
-**Disable audit**:
 ```bash
-npmglobalize --no-fix
+npmglobalize -no-fix      # report only, no fix attempt
 ```
 
 ### 🧩 Install Scripts (npm `allowScripts`)
@@ -409,8 +414,9 @@ not what you meant to publish, so npmglobalize lists the conflicted files and st
 -no-publish-deps, -npd   Skip auto-publishing file: dependencies
 -no-prescan, -nps        Skip upfront dep-graph prescan
 -force-publish           Republish dependencies even if version exists
--fix                     Run npm audit fix after transformation
--no-fix                  Don't run npm audit
+-fix, -no-fix            Run npm audit fix before the pre-release commit (default on,
+                         never --force). The audit REPORT always runs; critical/high
+                         findings are listed in the Issues Summary with a fix hint.
 -no-use-paths, -nup      Declare package standalone; do not resolve file: deps
                          from sibling checkouts (see Configuration File)
 ```
@@ -562,6 +568,23 @@ Settings can be saved in `.globalize.json5`:
 
 Configuration persists across runs. CLI flags override config file.
 
+### `.stale` — retired directories
+
+A directory that is no longer live or maintained can be retired in place by
+dropping a `.stale` file into it — empty, or better holding one line saying why
+and when. It is a marker file, not a setting in `.globalize.json5`, because
+stale is a property of the directory (most retired directories never had a
+config) and a file is findable without parsing.
+
+npmglobalize refuses to build, publish or install a directory marked `.stale`,
+and refuses to cascade into a `file:` dependency that is marked. Both are
+reported as **errors**, not skips: a live package that depends on a retired one
+has a reference that needs fixing. Remove the marker to make the directory live
+again.
+
+`cleanprev.ps1` (in `%OneDrive%\xfer\bin`) strips `node_modules`, lock files and
+tsc output from every `.stale` directory the same way it does for `prev/`.
+
 ### `usePaths` — Standalone packages
 
 Default: `true`. Set to `false` (or pass `-no-use-paths` / `-nup`) to mark a
@@ -686,12 +709,15 @@ npmglobalize --dry-run     # See what would happen
 11. **Pushes** to git (with push-protection detection and auto-bypass)
 12. **Installs** globally (if `--install`)
 13. **Restores** file: references (if `--files`, default)
-14. **Runs audit** (shows security status)
+14. **Runs audit** — `Audit:` row in the Release Summary; critical/high findings explained in the Issues Summary
 
 ## Operational Details
 
 ### Build Cascade
 
+Before anything is built, every project in the `file:` tree with missing deps gets an `npm install`. If one fails, the run **stops** there — the compiler/linker/npm lines that name the failure are printed (the full output goes to a log under `%TEMP%
+pmglobalize-logs`), the failure is repeated in the Issues Summary, and nothing is built, published, or installed on top of a broken tree. `-force` continues anyway. A stale-lockfile / junction failure offers a clean reinstall (delete `node_modules/` + `package-lock.json`, retry once); a compiler or linker error does not, since a reinstall would reach the same line.
+
 Before transforming or publishing anything, `npmglobalize` builds `file:` dependencies in topological order — deps before consumers — and then builds the target itself. This guarantees the target's `tsc` reads up-to-date `.d.ts` and `.js` from sibling checkouts even when a dep's source has changed since its last build.
 
 For each project visited (the target and every transitive `file:` dep):

package/cli.js

@@ -60,7 +60,9 @@ Dependency Options:
                            to date (freshness check compares .ts/tsconfig
                            mtimes against emitted .js/.d.ts)
   -force-publish           Republish dependencies even if version exists
-  -fix                     Run npm audit fix after transformation
+  -fix, -no-fix            Run npm audit fix before the pre-release commit (default on,
+                           never --force). The audit REPORT always runs; critical/high
+                           findings are listed in the Issues Summary with a fix hint.
   -no-use-paths, -nup      Declare this package standalone — file: deps shouldn't
                            be resolved from sibling checkouts (persisted as
                            usePaths:false in .globalize.json5; FYI for now)
@@ -596,7 +598,17 @@ export async function main() {
     // Ensures consumers' tsc sees up-to-date `.d.ts` from sibling checkouts
     // whose source has changed since their last build.
     if (!cliOptions.cleanup) {
-        await ensureFileDepModules(cwd, !!cliOptions.verbose);
+        // 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction: a failed npm install used
+        // to be reported and then walked past — the run went on to "Build up to date" and a
+        // green "Installed locally" for a package with no node_modules. Stop here instead.
+        const modulesOk = await ensureFileDepModules(cwd, !!cliOptions.verbose);
+        if (!modulesOk && !cliOptions.force) {
+            console.error(colors.error('npm install failed — stopping before build/publish (-force continues anyway).'));
+            printBuildSummary();
+            process.exit(1);
+        }
+        if (!modulesOk)
+            console.log(colors.warn('Continuing with -force despite npm install failure...'));
         const depsOk = await buildFileDepsTopologically(cwd, { verbose: !!cliOptions.verbose, force: !!cliOptions.force, forceBuild: !!cliOptions.forceBuild });
         if (!depsOk && !cliOptions.force) {
             printBuildSummary();

package/lib.d.ts

@@ -101,7 +101,8 @@ export interface GlobalizeOptions {
     publicDeps?: boolean;
     /** Force republish dependencies even if version exists on npm */
     forcePublish?: boolean;
-    /** Run npm audit and fix vulnerabilities */
+    /** Run `npm audit fix` before the pre-release commit (default true; never `--force`). The audit
+     *  REPORT always runs regardless — this only controls the fix attempt. */
     fix?: boolean;
     /** Automatically fix version/tag mismatches */
     fixTags?: boolean;
@@ -297,6 +298,15 @@ export type UnpublishedDep = {
  *  NOT `fs.realpathSync.native`: that would also resolve a junction the user is
  *  standing inside, which is a behaviour change nobody asked for. */
 export declare function canonicalCase(target: string): string;
+/** A directory retired in place carries a `.stale` marker file (Bob's convention,
+ *  2026-09-06; `cleanprev.ps1` strips such directories like a `prev/`). The file
+ *  is empty or holds a line saying why and when. Returns that line (or a fixed
+ *  phrase when empty), or null when the directory is not marked.
+ *
+ *  2026-09-06 — Claude Code (Fable 5.1), at Bob's direction. A marker file rather
+ *  than a flag in .globalize.json5: stale is a property of a directory, most stale
+ *  directories never had a config, and a file is findable without parsing. */
+export declare function staleMarker(dir: string): string;
 /** Vet the casing of every `file:` dependency path, in BOTH places it is recorded:
  *  the spec in package.json and the junction npm created in node_modules.
  *
@@ -369,7 +379,10 @@ export declare function parseVersionTag(tag: string): number[] | null;
 export declare function compareVersions(a: number[], b: number[]): number;
 /** Fix version/tag mismatches */
 export declare function fixVersionTagMismatch(cwd: string, pkg: any, verbose?: boolean): boolean;
-export declare function printPnpmSuggestionSummary(): void;
+/** Lines from a failed install that name the actual failure: linker / compiler / msbuild
+ *  errors from a native addon build, and node-gyp's own verdict. npm's "npm error " prefix is
+ *  stripped so a line is recognised whether npm relayed it or node-gyp printed it directly. */
+export declare function distillBuildErrors(combined: string): string[];
 /** Return declared deps (dependencies + devDependencies) that don't resolve from
  *  `pkgDir`. Skips `workspace:`/`link:` specs (handled by workspace tooling /
  *  rarely used). `file:` deps are checked: npm installs them as junctions
@@ -383,7 +396,7 @@ export declare function missingDeps(pkgDir: string, pkg: any): string[];
  *  "fresh clone, no `node_modules/`" and "dep added but `npm install` not
  *  re-run" (partial-sync) cases. Also covers `cwd` itself on the first call.
  *  Cycle-safe via the shared `visited` set. */
-export declare function ensureFileDepModules(cwd: string, verbose?: boolean, visited?: Set<string>): Promise<void>;
+export declare function ensureFileDepModules(cwd: string, verbose?: boolean, visited?: Set<string>): Promise<boolean>;
 /** Cheap freshness check so the build cascade can skip packages whose output is
  *  already current. Returns true only when provably up to date:
  *  - outDir projects: newest source (.ts/.tsx/.mts/.cts + tsconfig*.json) must
@@ -490,7 +503,7 @@ export declare function fixTs7Deprecations(cwd: string): {
 export declare function ensureWorkspaceDepModules(rootDir: string, members: Array<{
     dir: string;
     pkg: any;
-}>, verbose?: boolean): Promise<void>;
+}>, verbose?: boolean): Promise<boolean>;
 /** Extract the lines a human needs from a failed npm command's output: the
  *  `npm error` lines minus stack frames and brace-only object-dump fragments,
  *  deduped. The full output belongs in a log file (saveNpmLog), not the terminal. */
@@ -613,13 +626,48 @@ export declare function promptChoice(message: string, choices: string[]): Promis
 export declare function adoptExistingRemote(cwd: string, repoUrl: string, defaultBranch: string, dryRun: boolean): Promise<boolean>;
 /** Initialize git repository */
 export declare function initGit(cwd: string, visibility: 'private' | 'public', dryRun: boolean, allowTs?: boolean): Promise<boolean>;
-/** Main globalize function */
-/** Run npm audit and optionally fix vulnerabilities */
-export declare function runNpmAudit(cwd: string, fix?: boolean, verbose?: boolean): Promise<{
-    success: boolean;
-    report: string;
-    hasVulnerabilities: boolean;
-}>;
+/** Vulnerability severity as reported by `npm audit --json` */
+export type AuditSeverity = 'critical' | 'high' | 'moderate' | 'low' | 'info';
+/** One vulnerable package from `npm audit --json` */
+export interface AuditFinding {
+    /** Package name */
+    name: string;
+    severity: AuditSeverity;
+    /** Vulnerable version range, e.g. "<7.5.4" */
+    range: string;
+    /** Declared directly in this package.json (vs. pulled in transitively) */
+    isDirect: boolean;
+    /** Advisory titles + URLs. Empty when the package is vulnerable only because of a dep it uses. */
+    advisories: {
+        title: string;
+        url: string;
+    }[];
+    /** Vulnerable deps this package is affected THROUGH (npm's string `via` entries) */
+    via: string[];
+    /** Packages that are affected BECAUSE of this one (npm's `effects`) */
+    effects: string[];
+    /** 'plain' = `npm audit fix` clears it; 'major' = needs `--force` (breaking); 'none' = no fix published */
+    fix: 'plain' | 'major' | 'none';
+    /** The top-level package@version the fix would install (npm names it when the fix is an object) */
+    fixTarget: string;
+}
+/** Outcome of an `npm audit --json` run */
+export interface AuditResult {
+    /** false when npm audit itself could not run (no lockfile, registry down...) — see error */
+    ran: boolean;
+    error: string;
+    counts: Record<AuditSeverity, number> & {
+        total: number;
+    };
+    findings: AuditFinding[];
+}
+/** Run `npm audit fix` (never `--force`: that installs semver-major bumps and can break the
+ *  build; the summary tells the user when that is what it would take). Silent on purpose —
+ *  the report that follows shows what is left. */
+export declare function runNpmAuditFix(cwd: string): Promise<void>;
+/** Run `npm audit --json` (read-only) and parse it into an AuditResult. Never throws; a run
+ *  that could not happen comes back with ran=false and the reason in error. */
+export declare function runNpmAudit(cwd: string): AuditResult;
 /** Get the version of npmglobalize itself */
 export declare function getToolVersion(): string;
 export declare function globalize(cwd: string, options?: GlobalizeOptions, configOptions?: Partial<GlobalizeOptions>): Promise<boolean>;

package/lib.js

@@ -29,7 +29,6 @@ function spawnSafe(cmd, args, options = {}) {
     return spawnSync(cmd, args, opts);
 }
 import readline from 'readline';
-import { styleText } from 'util';
 import libversion from 'libnpmversion';
 import JSON5 from 'json5';
 import { fileURLToPath } from 'url';
@@ -332,7 +331,7 @@ const BOOL_COMMENTS = {
     force: { on: 'Continue despite git errors', off: 'Stop on git errors' },
     quiet: { on: 'Suppress npm warnings', off: 'Show npm warnings' },
     verbose: { on: 'Show detailed output', off: 'Normal output detail' },
-    fix: { on: 'Auto-run npm audit fix', off: 'Do NOT run npm audit fix' },
+    fix: { on: 'Auto-run npm audit fix (default)', off: 'Do NOT run npm audit fix (audit report still runs)' },
     local: { on: 'Local install only (skip transform/publish)', off: 'Normal transform/publish flow' },
     noPublish: { on: 'Transform but don\'t publish', off: 'Publish normally' },
     freeze: { on: 'Freeze node_modules (replace symlinks with real copies)', off: 'Leave node_modules symlinks as-is' },
@@ -444,7 +443,7 @@ export function writeConfig(dir, config, explicitKeys) {
         ['"verbose": false', 'true = show detailed output'],
         ['"gitVisibility": "private"', 'Git repo: private or public'],
         ['"npmVisibility": "private"', 'npm package: private or public'],
-        ['"fix": false', 'true = auto-run npm audit fix'],
+        ['"fix": true', 'true = auto-run npm audit fix (never --force); false = report only'],
         ['"local": false', 'true = local install only (skip transform/publish); clear with -global'],
         ['"noPublish": false', 'true = transform but don\'t publish'],
         ['"freeze": false', 'true = freeze node_modules (replace symlinks with real copies)'],
@@ -1370,6 +1369,25 @@ function caseDiffers(a, b) {
     const strip = (p) => p.replace(/[\\/]+$/, '');
     return strip(a) !== strip(b);
 }
+/** A directory retired in place carries a `.stale` marker file (Bob's convention,
+ *  2026-09-06; `cleanprev.ps1` strips such directories like a `prev/`). The file
+ *  is empty or holds a line saying why and when. Returns that line (or a fixed
+ *  phrase when empty), or null when the directory is not marked.
+ *
+ *  2026-09-06 — Claude Code (Fable 5.1), at Bob's direction. A marker file rather
+ *  than a flag in .globalize.json5: stale is a property of a directory, most stale
+ *  directories never had a config, and a file is findable without parsing. */
+export function staleMarker(dir) {
+    const marker = path.join(dir, '.stale');
+    if (!fs.existsSync(marker))
+        return null;
+    let note = '';
+    try {
+        note = fs.readFileSync(marker, 'utf8').split(/\r?\n/).map(l => l.trim()).find(l => l) || '';
+    }
+    catch { /* unreadable note: still stale */ }
+    return note || 'no reason recorded in .stale';
+}
 /** Vet the casing of every `file:` dependency path, in BOTH places it is recorded:
  *  the spec in package.json and the junction npm created in node_modules.
  *
@@ -2050,73 +2068,67 @@ export function fixVersionTagMismatch(cwd, pkg, verbose = false) {
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-/** User-requested pnpm-eval hook (2026-05-14). The first local `npm install`
- *  failure in a process prints a yellow-on-red banner and pauses 60s so the
- *  user can read it. Every failure (first and subsequent) is captured in
- *  `_pnpmFailureContexts` so `printPnpmSuggestionSummary()` can re-emit the
- *  banner — listing all failure sites — at end-of-run, in case the live
- *  banner scrolled past. Remove once pnpm-vs-npm decision is made. */
-let _pnpmSuggestionShown = false;
-const _pnpmFailureContexts = [];
-function _pnpmBanner(contexts) {
-    const width = 76;
-    const wrap = (s) => styleText(['yellow', 'bgRed', 'bold'], ' ' + s.padEnd(width - 2) + ' ');
-    const body = [
-        '',
-        contexts.length > 1
-            ? `npm install FAILED  --  ${contexts.length} sites  --  consider trying pnpm`
-            : 'npm install FAILED  --  consider trying pnpm',
-        '',
-    ];
-    for (const c of contexts) {
-        const label = `  - ${c}`;
-        body.push(label.length > width - 2 ? label.slice(0, width - 5) + '...' : label);
-    }
-    body.push('', 'pnpm uses a content-addressed store with strict node_modules and', 'much faster installs. Commands mirror npm; great workspace support.', '', 'Try:   npm i -g pnpm  &&  pnpm import  &&  pnpm install', '');
-    return body.map(wrap);
-}
-async function suggestPnpmOnInstallFailure(context) {
-    _pnpmFailureContexts.push(context);
-    if (_pnpmSuggestionShown)
-        return;
-    _pnpmSuggestionShown = true;
-    const lines = _pnpmBanner([context]);
-    console.error('');
-    for (const l of lines)
-        console.error(l);
-    console.error(styleText(['yellow', 'bgRed', 'bold'], ' ' + 'Pausing 60s so you can read this. Ctrl+C to abort.'.padEnd(74) + ' '));
-    console.error('');
-    await new Promise(resolve => setTimeout(resolve, 60_000));
-}
-/** Re-emit the pnpm banner at end-of-run if any `npm install` failed.
- *  No-op when nothing failed. Safe to call from multiple summary paths —
- *  guarded so the summary banner prints at most once per process. */
-let _pnpmSummaryPrinted = false;
-export function printPnpmSuggestionSummary() {
-    if (_pnpmSummaryPrinted)
-        return;
-    if (_pnpmFailureContexts.length === 0)
-        return;
-    _pnpmSummaryPrinted = true;
-    console.error('');
-    for (const l of _pnpmBanner(_pnpmFailureContexts))
-        console.error(l);
-    console.error('');
-}
-/** Run `npm install` in `dir`; on failure, offer to delete `node_modules/`
- *  and `package-lock.json` and retry once — the standard fix for arborist's
- *  null-`package` crash on stale lockfile / junction state — before falling
- *  back to the pnpm suggestion banner. Returns true if install succeeded.
- *  `rmSync` unlinks junctions without descending, so file: sibling targets
- *  are never touched. */
+// 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction: the pnpm-eval banner that used
+// to live here ("npm install FAILED -- consider trying pnpm", plus a 60-second pause) is
+// gone. pnpm was evaluated and judged not feasible, so the suggestion was noise that
+// delayed the run and hid the real error. A failed install is now reported by
+// reportInstallFailure (the actual compiler/linker/npm lines, plus a log file) and stops
+// the run — see ensureFileDepModules and its callers.
+/** Lines from a failed install that name the actual failure: linker / compiler / msbuild
+ *  errors from a native addon build, and node-gyp's own verdict. npm's "npm error " prefix is
+ *  stripped so a line is recognised whether npm relayed it or node-gyp printed it directly. */
+export function distillBuildErrors(combined) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of combined.split('\n')) {
+        const line = raw.replace(/^npm (?:error|ERR!)\s?/, '').trimEnd();
+        if (!/fatal error|\berror (?:LNK|C|MSB|TS)\d+|gyp ERR! (?:build|configure|rebuild) error/.test(line))
+            continue;
+        if (seen.has(line))
+            continue;
+        seen.add(line);
+        out.push(line);
+    }
+    return out.slice(0, 12);
+}
+/** Print why an `npm install` failed and keep the whole output in a log file. Native-build
+ *  errors (LNK1117 and friends) come first — they are the cause; npm's own "command failed"
+ *  lines only say that something did. Was: the first 5 lines of stderr, which for a node-gyp
+ *  failure are "npm error code 1 / path / command failed / command ..." and never the error. */
+function reportInstallFailure(dir, r, attempt) {
+    const combined = [r.output, r.stderr].filter(Boolean).join('\n');
+    const logFile = saveNpmLog(`install-${path.basename(dir)}`, combined);
+    const buildErrors = distillBuildErrors(combined);
+    const npmErrors = distillNpmErrors(combined).filter(l => !buildErrors.includes(l));
+    console.error(colors.red(`  ✗ npm install failed in ${dir}${attempt}`));
+    for (const l of buildErrors)
+        console.error(colors.red(`    ${l}`));
+    for (const l of npmErrors.slice(0, buildErrors.length > 0 ? 4 : 8))
+        console.error(colors.dim(`    ${l}`));
+    if (logFile)
+        console.error(colors.dim(`    full output: ${logFile}`));
+    const headline = buildErrors.find(l => /fatal error|\berror /.test(l))
+        || buildErrors[0]
+        || npmErrors.find(l => !/^(code \d+|path |command )/.test(l))
+        || 'see log';
+    return { isBuildError: buildErrors.length > 0, headline, logFile };
+}
+/** Run `npm install` in `dir`. On failure, offer to delete `node_modules/` and
+ *  `package-lock.json` and retry once — the standard fix for arborist's null-`package`
+ *  crash on stale lockfile / junction state. Not offered when the output holds a
+ *  compiler / linker error: that is a broken native build, not a broken tree, and the
+ *  reinstall would spend a minute reaching the same line. Returns true if install
+ *  succeeded; a failure is recorded for the Issues Summary. `rmSync` unlinks junctions
+ *  without descending, so file: sibling targets are never touched. */
 async function npmInstallWithCleanRetry(dir, verbose, context) {
     let r = await runCommandAsync('npm', ['install'], { cwd: dir, silent: !verbose });
     if (r.success)
         return true;
-    console.error(colors.red(`  ✗ npm install failed in ${dir}`));
-    if (r.stderr)
-        console.error(colors.dim(r.stderr.split('\n').slice(0, 5).join('\n')));
-    if (await confirm(`  Delete node_modules/ and package-lock.json in ${dir} and retry npm install?`, true)) {
+    let failure = reportInstallFailure(dir, r, '');
+    if (failure.isBuildError) {
+        console.error(colors.dim('    (compiler/linker error — a clean reinstall would hit the same line, so not offering one)'));
+    }
+    else if (await confirm(`  Delete node_modules/ and package-lock.json in ${dir} and retry npm install?`, true)) {
         try {
             fs.rmSync(path.join(dir, 'node_modules'), { recursive: true, force: true });
         }
@@ -2131,11 +2143,9 @@ async function npmInstallWithCleanRetry(dir, verbose, context) {
             console.log(colors.green(`  ✓ clean reinstall succeeded in ${dir}`));
             return true;
         }
-        console.error(colors.red(`  ✗ npm install still failing in ${dir} after clean reinstall`));
-        if (r.stderr)
-            console.error(colors.dim(r.stderr.split('\n').slice(0, 5).join('\n')));
+        failure = reportInstallFailure(dir, r, ' after clean reinstall');
     }
-    await suggestPnpmOnInstallFailure(context);
+    recordBuildIssue(path.basename(dir), 'error', `npm install failed (${context}): ${failure.headline}${failure.logFile ? ` — log: ${failure.logFile}` : ''}`);
     return false;
 }
 /** Wait for a package version to appear on the npm registry.
@@ -2289,17 +2299,22 @@ function formatMissingReason(missing) {
  *  "fresh clone, no `node_modules/`" and "dep added but `npm install` not
  *  re-run" (partial-sync) cases. Also covers `cwd` itself on the first call.
  *  Cycle-safe via the shared `visited` set. */
+// 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction ("if the install failed why
+// continue"): returns false when any npm install in the tree failed. Every dep is still
+// attempted so one run reports all failures; the CALLER stops before building/publishing
+// on false (unless -force).
 export async function ensureFileDepModules(cwd, verbose = false, visited = new Set()) {
     const abs = path.resolve(cwd);
     if (visited.has(abs))
-        return;
+        return true;
     visited.add(abs);
+    let ok = true;
     let pkg;
     try {
         pkg = readPackageJson(cwd);
     }
     catch {
-        return;
+        return true; // no package.json here: nothing to install, nothing failed
     }
     const cwdMissing = missingDeps(abs, pkg);
     if (cwdMissing.length > 0) {
@@ -2316,7 +2331,8 @@ export async function ensureFileDepModules(cwd, verbose = false, visited = new S
             catch { /* best-effort */ }
         }
         console.log(colors.yellow(`↻ installing node_modules in ${pkg?.name || abs} (${formatMissingReason(cwdMissing)})`));
-        await npmInstallWithCleanRetry(abs, verbose, `ensureFileDepModules (cwd): ${abs}`);
+        if (!await npmInstallWithCleanRetry(abs, verbose, `ensureFileDepModules (cwd): ${abs}`))
+            ok = false;
     }
     for (const key of ['dependencies', 'devDependencies']) {
         const deps = pkg?.[key];
@@ -2328,6 +2344,15 @@ export async function ensureFileDepModules(cwd, verbose = false, visited = new S
             const target = path.resolve(cwd, spec.slice('file:'.length));
             if (!fs.existsSync(path.join(target, 'package.json')))
                 continue;
+            // 2026-09-06 — Claude Code (Fable 5.1): never install into, or walk
+            // through, a dep that is retired (`.stale`). Reported as an error so the
+            // stale reference in package.json gets fixed rather than papered over.
+            const targetStale = staleMarker(target);
+            if (targetStale) {
+                console.error(colors.red(`✗ file: dependency ${name} -> ${target} is marked .stale (${targetStale}); not installing into a retired directory.`));
+                recordBuildIssue(pkg?.name || abs, 'error', `file: dependency ${name} (${target}) is marked .stale (${targetStale}).`);
+                continue;
+            }
             let targetPkg;
             try {
                 targetPkg = readPackageJson(target);
@@ -2348,11 +2373,14 @@ export async function ensureFileDepModules(cwd, verbose = false, visited = new S
                     catch { /* best-effort */ }
                 }
                 console.log(colors.yellow(`↻ restoring node_modules in ${name} (${target}) (${formatMissingReason(targetMissing)})`));
-                await npmInstallWithCleanRetry(target, verbose, `ensureFileDepModules (file: dep ${name}): ${target}`);
+                if (!await npmInstallWithCleanRetry(target, verbose, `ensureFileDepModules (file: dep ${name}): ${target}`))
+                    ok = false;
             }
-            await ensureFileDepModules(target, verbose, visited);
+            if (!await ensureFileDepModules(target, verbose, visited))
+                ok = false;
         }
     }
+    return ok;
 }
 /** Cached major version of the global `tsc`. null = not yet probed,
  *  0 = probe failed / tsc not found. TypeScript 6 stopped auto-including
@@ -3505,7 +3533,7 @@ export async function buildFileDepsTopologically(cwd, opts = {}, visited = new S
         const deps = pkg?.[key];
         if (!deps || typeof deps !== 'object')
             continue;
-        for (const [, spec] of Object.entries(deps)) {
+        for (const [name, spec] of Object.entries(deps)) {
             if (typeof spec !== 'string' || !spec.startsWith('file:'))
                 continue;
             const target = path.resolve(cwd, spec.slice('file:'.length));
@@ -3514,6 +3542,18 @@ export async function buildFileDepsTopologically(cwd, opts = {}, visited = new S
             const targetAbs = path.resolve(target);
             if (visited.has(targetAbs))
                 continue;
+            // 2026-09-06 — Claude Code (Fable 5.1): a retired (`.stale`) dep is not
+            // built. Counts as a failed dep so the consumer's build stops here too,
+            // unless -force says to carry on.
+            const targetStale = staleMarker(target);
+            if (targetStale) {
+                console.error(colors.red(`✗ file: dependency ${name} -> ${target} is marked .stale (${targetStale}); not building a retired directory.`));
+                recordBuildIssue(pkg?.name || abs, 'error', `file: dependency ${name} (${target}) is marked .stale (${targetStale}).`);
+                allOk = false;
+                if (!opts.force)
+                    return false;
+                continue;
+            }
             // Recurse first (deps before consumer)
             const childOk = await buildFileDepsTopologically(target, opts, visited);
             if (!childOk)
@@ -3730,7 +3770,7 @@ export async function ensureWorkspaceDepModules(rootDir, members, verbose = fals
         rootPkg = readPackageJson(root);
     }
     catch {
-        return;
+        return true;
     }
     const allMissing = new Set();
     for (const name of missingDeps(root, rootPkg))
@@ -3740,10 +3780,10 @@ export async function ensureWorkspaceDepModules(rootDir, members, verbose = fals
             allMissing.add(name);
     }
     if (allMissing.size === 0)
-        return;
+        return true;
     const list = [...allMissing];
     console.log(colors.yellow(`↻ installing workspace node_modules in ${rootPkg?.name || path.basename(root)} (${formatMissingReason(list)})`));
-    await npmInstallWithCleanRetry(root, verbose, `ensureWorkspaceDepModules: ${root}`);
+    return npmInstallWithCleanRetry(root, verbose, `ensureWorkspaceDepModules: ${root}`);
 }
 /** Extract the lines a human needs from a failed npm command's output: the
  *  `npm error` lines minus stack frames and brace-only object-dump fragments,
@@ -5979,54 +6019,140 @@ export async function initGit(cwd, visibility, dryRun, allowTs) {
     }
     return true;
 }
-/** Main globalize function */
-/** Run npm audit and optionally fix vulnerabilities */
-export async function runNpmAudit(cwd, fix = false, verbose = false) {
-    if (fix) {
-        await runCommandAsync('npm', ['audit', 'fix'], { cwd, silent: true });
-    }
-    // Check remaining vulnerabilities
-    const auditResult = spawnSafe('npm', ['audit', '--json'], {
-        cwd, encoding: 'utf-8', stdio: 'pipe', shell: true
-    });
-    let hasVulnerabilities = false;
-    let report = '';
+/** Run `npm audit fix` (never `--force`: that installs semver-major bumps and can break the
+ *  build; the summary tells the user when that is what it would take). Silent on purpose —
+ *  the report that follows shows what is left. */
+export async function runNpmAuditFix(cwd) {
+    await runCommandAsync('npm', ['audit', 'fix'], { cwd, silent: true });
+}
+/** Classify npm's `fixAvailable` — true | false | { name, version, isSemVerMajor } */
+function classifyFix(fixAvailable) {
+    if (fixAvailable === true)
+        return { fix: 'plain', fixTarget: '' };
+    if (fixAvailable && typeof fixAvailable === 'object') {
+        const f = fixAvailable;
+        const fixTarget = f.name ? `${f.name}@${f.version ?? '?'}` : '';
+        return { fix: f.isSemVerMajor ? 'major' : 'plain', fixTarget };
+    }
+    return { fix: 'none', fixTarget: '' };
+}
+/** Run `npm audit --json` (read-only) and parse it into an AuditResult. Never throws; a run
+ *  that could not happen comes back with ran=false and the reason in error. */
+export function runNpmAudit(cwd) {
+    const counts = { critical: 0, high: 0, moderate: 0, low: 0, info: 0, total: 0 };
+    const result = { ran: false, error: '', counts, findings: [] };
+    const proc = spawnSafe('npm', ['audit', '--json'], { cwd, encoding: 'utf-8', stdio: 'pipe', shell: true });
+    // The JSON shape is npm's, not ours — narrowed field by field below, hence the any.
+    let data;
     try {
-        const auditData = JSON.parse(auditResult.stdout || '{}');
-        const m = auditData.metadata?.vulnerabilities || {};
-        const critical = m.critical || 0;
-        const high = m.high || 0;
-        const moderate = m.moderate || 0;
-        const low = m.low || 0;
-        const total = critical + high + moderate + low + (m.info || 0);
-        if (total > 0) {
-            hasVulnerabilities = true;
-            const parts = [];
-            if (critical > 0)
-                parts.push(colors.red(`${critical} critical`));
-            if (high > 0)
-                parts.push(colors.red(`${high} high`));
-            if (moderate > 0)
-                parts.push(colors.yellow(`${moderate} moderate`));
-            if (low > 0)
-                parts.push(`${low} low`);
-            report = `${total} vulnerabilities`;
-            // Only show if high/critical remain after fix
-            if (critical > 0 || high > 0) {
-                console.log(colors.red(`  Audit: ${parts.join(', ')}`));
-            }
-            else if (verbose) {
-                console.log(colors.dim(`  Audit: ${parts.join(', ')}`));
-            }
-        }
-        else {
-            report = 'No vulnerabilities';
-        }
+        data = JSON.parse(proc.stdout || '');
     }
-    catch {
-        report = 'Audit check failed';
+    catch (error) {
+        // Not a swallow: the failure becomes result.error, which the summary prints as "Audit: not run".
+        const stderr = (proc.stderr || '').trim().split('\n')[0];
+        result.error = stderr || `npm audit produced no JSON (${error.message})`;
+        return result;
     }
-    return { success: true, report, hasVulnerabilities };
+    if (data?.error) {
+        // npm reports its own failures (ENOLOCK, network...) as JSON on stdout
+        result.error = [data.error.code, data.error.summary].filter(Boolean).join(': ');
+        return result;
+    }
+    result.ran = true;
+    const m = data.metadata?.vulnerabilities || {};
+    for (const sev of ['critical', 'high', 'moderate', 'low', 'info']) {
+        counts[sev] = m[sev] || 0;
+        counts.total += counts[sev];
+    }
+    const vulns = data.vulnerabilities || {};
+    for (const name of Object.keys(vulns)) {
+        const v = vulns[name];
+        const viaList = Array.isArray(v.via) ? v.via : [];
+        const advisories = viaList
+            .filter((x) => !!x && typeof x === 'object')
+            .map(x => ({ title: x.title || '', url: x.url || '' }));
+        const via = viaList.filter((x) => typeof x === 'string');
+        result.findings.push({
+            name,
+            severity: v.severity,
+            range: v.range || '',
+            isDirect: !!v.isDirect,
+            advisories,
+            via,
+            effects: Array.isArray(v.effects) ? v.effects : [],
+            ...classifyFix(v.fixAvailable)
+        });
+    }
+    const order = ['critical', 'high', 'moderate', 'low', 'info'];
+    result.findings.sort((a, b) => order.indexOf(a.severity) - order.indexOf(b.severity) || a.name.localeCompare(b.name));
+    return result;
+}
+/** One-line explanation of a finding for the Issues Summary: what, why it is here, how to clear it. */
+function describeAuditFinding(f) {
+    const parts = [`audit ${f.severity.toUpperCase()}: ${f.name} ${f.range}`.trim()];
+    if (f.advisories.length > 0) {
+        // One advisory named in full; the rest counted. tar alone carries 12 and a line per
+        // title would bury the Issues Summary. The URL leads to the complete list.
+        const a = f.advisories[0];
+        const more = f.advisories.length - 1;
+        parts.push(`${a.title}${a.url ? ` (${a.url})` : ''}${more > 0 ? ` +${more} more` : ''}`);
+    }
+    if (f.via.length > 0)
+        parts.push(`through ${f.via.join(', ')}`);
+    if (f.isDirect)
+        parts.push('direct dependency');
+    else if (f.effects.length > 0)
+        parts.push(`pulled in by ${f.effects.join(', ')}`);
+    switch (f.fix) {
+        case 'plain':
+            parts.push('fix: npm audit fix');
+            break;
+        case 'major':
+            parts.push(`fix: npm audit fix --force → ${f.fixTarget || 'a semver-major bump'} (breaking — not run automatically)`);
+            break;
+        case 'none':
+            parts.push('fix: none published yet');
+            break;
+    }
+    return parts.join(' — ');
+}
+/** Run the audit report and put critical/high findings into the Issues Summary. Call once,
+ *  right before the end-of-run summary. */
+function auditForSummary(cwd, moduleName) {
+    const audit = runNpmAudit(cwd);
+    for (const f of audit.findings) {
+        if (f.severity === 'critical' || f.severity === 'high') {
+            recordBuildIssue(moduleName, 'warning', describeAuditFinding(f));
+        }
+    }
+    return audit;
+}
+/** The "Audit:" row for the Release / Transform Summary. */
+function auditSummaryRow(audit, dryRun) {
+    if (dryRun)
+        return `  Audit: ${colors.dim('skipped (dry-run)')}`;
+    if (!audit)
+        return `  Audit: ${colors.dim('not run')}`;
+    if (!audit.ran)
+        return `  Audit: ${colors.yellow('not run')} ${colors.dim(audit.error)}`;
+    if (audit.counts.total === 0)
+        return `  Audit: ${colors.green('✓')} no vulnerabilities`;
+    const c = audit.counts;
+    const parts = [];
+    if (c.critical > 0)
+        parts.push(colors.red(`${c.critical} critical`));
+    if (c.high > 0)
+        parts.push(colors.red(`${c.high} high`));
+    if (c.moderate > 0)
+        parts.push(colors.yellow(`${c.moderate} moderate`));
+    if (c.low > 0)
+        parts.push(`${c.low} low`);
+    if (c.info > 0)
+        parts.push(`${c.info} info`);
+    const serious = c.critical > 0 || c.high > 0;
+    const mark = serious ? colors.red('✗') : colors.yellow('!');
+    const hint = serious ? colors.dim(' (details in Issues Summary)') : '';
+    return `  Audit: ${mark} ${parts.join(', ')}${hint}`;
 }
 /** Get the version of npmglobalize itself */
 export function getToolVersion() {
@@ -6141,6 +6267,17 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     publishDepsYes = false, // -pd: auto-yes to dep-cascade prompts (private only)
     publicDeps = false, // -public-deps: cascade public visibility to all deps
     noPrescan = false, forcePublish = false, fix = true, fixTags = false, rebase = false, show = false, local = false, freeze = false, usePaths = true, allowTs, adopt = false, importCheck = false } = options;
+    // 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction: a directory marked
+    // `.stale` is retired. Refuse to build, publish or install it — and because the
+    // dep cascade reaches deps through this same function, refuse to cascade into
+    // one too. The refusal is an error, not a skip: a live package depending on a
+    // stale one is a fact the user has to act on.
+    const staleNote = staleMarker(cwd);
+    if (staleNote) {
+        console.error(colors.red(`✗ ${cwd} is marked .stale (${staleNote}). Not publishing a retired directory.`));
+        recordBuildIssue(path.basename(cwd), 'error', `Directory is marked .stale (${staleNote}); remove the marker to publish it again.`);
+        return false;
+    }
     // Show tool version only for recursive dep calls (CLI already prints it at startup)
     const toolVersion = getToolVersion();
     if (!options._fromWorkspace && !options._fromCli) {
@@ -6636,8 +6773,15 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     // before doing anything else. Independent of build script presence — a dep
     // with new declared deps still needs its own `npm install` even if it has
     // no build step. CLI entrypoint already ran this, so skip when _fromCli.
-    if (!options._fromCli && !dryRun)
-        await ensureFileDepModules(cwd, verbose);
+    if (!options._fromCli && !dryRun) {
+        const modulesOk = await ensureFileDepModules(cwd, verbose);
+        if (!modulesOk && !force) {
+            console.error(colors.red(`npm install failed in ${pkg.name || cwd} — stopping before build/publish (-force continues anyway).`));
+            return false;
+        }
+        if (!modulesOk)
+            console.log(colors.yellow('Continuing with -force despite npm install failure...'));
+    }
     // Run build step if package.json has a build script (skip if CLI already built)
     if (pkg.scripts?.build && !options._fromCli) {
         console.log(`${timestamp()} Running build...`);
@@ -7275,19 +7419,17 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             }
         }
     }
-    // Run npm audit if requested or if dependencies were transformed
-    if ((fix || updateDeps) && (transformResult.transformed || alreadyTransformed || updateDeps)) {
+    // 2026-09-06 — Claude Code (Fable 5.1): fix step only here (before the pre-release commit,
+    // so a changed lockfile is committed). The report moved next to the summaries so its
+    // result is shown where the user is looking, not scrolled off under the git output.
+    if (fix) {
         if (!dryRun) {
-            await runNpmAudit(cwd, fix, verbose);
+            await runNpmAuditFix(cwd);
         }
         else {
-            console.log('  [dry-run] Would run npm audit');
+            console.log('  [dry-run] Would run npm audit fix');
         }
     }
-    else if (fix && !dryRun) {
-        // Run fix even if no deps changed
-        await runNpmAudit(cwd, fix, verbose);
-    }
     if (noPublish) {
         console.log('Transform complete (--nopublish mode).');
         if (freeze && !dryRun) {
@@ -7339,11 +7481,11 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         console.log(`  Package: ${colors.green(finalPkg2.name)}`);
         console.log(`  Version: ${colors.green('v' + finalPkg2.version)}`);
         console.log(`  Published: ${colors.red('✗')}`);
+        console.log(auditSummaryRow(dryRun ? null : auditForSummary(cwd, finalPkg2.name), dryRun));
         for (const s of surprises)
             console.log(`  ${colors.yellow('!')} ${s}`);
         console.log(colors.yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
         console.log('');
-        printPnpmSuggestionSummary();
         return true;
     }
     // Skip if private
@@ -8421,11 +8563,6 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     // publish so the version recorded is the one that actually shipped.
     await recordUpstream(cwd, dryRun, verbose);
     console.log(`${timestamp()} Done!`);
-    // Run final audit report if not already run
-    const auditAlreadyRun = (fix || updateDeps) && (transformResult.transformed || alreadyTransformed || updateDeps);
-    if (!auditAlreadyRun && (fix || updateDeps || transformResult.transformed) && !dryRun) {
-        await runNpmAudit(cwd, false, verbose); // Just report, don't fix again
-    }
     // Print summary
     console.log('');
     console.log(colors.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
@@ -8438,6 +8575,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     console.log(`  Version: ${colors.green('v' + finalPkg.version)}`);
     console.log(`  Published: ${colors.green('✓')} (${accessLabel})`);
     console.log(`  Git pushed: ${colors.green('✓')}`);
+    console.log(auditSummaryRow(dryRun ? null : auditForSummary(cwd, finalPkg.name), dryRun));
     if (explicitKeys?.has('gitVisibility')) {
         console.log(`  Git visibility: ${colors.green(gitVisibility.toUpperCase())}`);
     }
@@ -8486,7 +8624,6 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     }
     console.log(colors.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     console.log('');
-    printPnpmSuggestionSummary();
     // Only show "To use run" message if package provides commands (has bin field)
     if (finalPkg.bin) {
         const commandName = finalPkg.name.includes('/') ? finalPkg.name.split('/')[1] : finalPkg.name;
@@ -8699,7 +8836,13 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
     // the case where a dep was added to a member package.json but `npm install`
     // wasn't re-run — the builds would otherwise fail resolving the new dep.
     if (!options.dryRun) {
-        await ensureWorkspaceDepModules(rootDir, packages.map(p => ({ dir: p.dir, pkg: p.pkg })), !!options.verbose);
+        const modulesOk = await ensureWorkspaceDepModules(rootDir, packages.map(p => ({ dir: p.dir, pkg: p.pkg })), !!options.verbose);
+        if (!modulesOk && !options.force) {
+            console.error(colors.red('npm install failed — stopping before build/publish (-force continues anyway).'));
+            return { success: false, packages: [], publishOrder: [] };
+        }
+        if (!modulesOk)
+            console.log(colors.yellow('Continuing with -force despite npm install failure...'));
     }
     // Prescan: decide which packages actually need processing so we don't waste
     // time rebuilding+republishing ones with no relevant changes.
@@ -8840,7 +8983,6 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
     }
     console.log(colors.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     console.log('');
-    printPnpmSuggestionSummary();
     // Global install of the workspace root (monorepo CLI)
     const { install = false, link = false, wsl = false, dryRun = false, verbose = false } = options;
     const rootPkgFinal = readPackageJson(rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.215",
+  "version": "1.0.217",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",