@bobfrankston/npmglobalize 1.0.214 → 1.0.216

package/README.md

@@ -562,6 +562,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

package/cli.js

@@ -2,7 +2,7 @@
 /**
  * npmglobalize CLI - Transform file: dependencies to npm versions for publishing
  */
-import { globalize, globalizeWorkspace, installCleanupHandlers, readConfig, readPackageJson, readUserNpmConfig, writeConfig, writePackageJson, getBuildIssues, clearBuildIssues, ensureFileDepModules, buildProject, buildFileDepsTopologically, reportTs7Deprecations, fixTs7Deprecations } from './lib.js';
+import { globalize, globalizeWorkspace, installCleanupHandlers, readConfig, readPackageJson, readUserNpmConfig, writeConfig, writePackageJson, getBuildIssues, clearBuildIssues, ensureFileDepModules, buildProject, buildFileDepsTopologically, reportTs7Deprecations, fixTs7Deprecations, canonicalCase } from './lib.js';
 import fs from 'fs';
 import path from 'path';
 import { colors } from './colors.js';
@@ -549,6 +549,19 @@ export async function main() {
             process.exit(1);
         }
     }
+    // 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction.
+    // `process.cwd()` carries whatever letter case the shell was started with
+    // (`y:\dev\...` from a lowercase prompt). Every `file:` junction npm writes
+    // inherits that case, and mixed `y:`/`Y:` junction targets are exactly what
+    // makes arborist crash with "Cannot read properties of null (reading
+    // 'package')" — see `caseDiffers` in lib.ts. Canonicalizing once up front
+    // means every npm the cascade spawns writes junctions with the on-disk
+    // spelling, so the repair in verifyDepPathCase stops being needed again.
+    const canonicalCwd = canonicalCase(cwd);
+    if (canonicalCwd && canonicalCwd !== cwd) {
+        cwd = canonicalCwd;
+        process.chdir(cwd);
+    }
     // Report-only TS7-readiness scan (no transform / build / publish).
     if (cliOptions.ts7Report) {
         printTs7Report(cwd);

package/lib.d.ts

@@ -287,6 +287,25 @@ export type UnpublishedDep = {
     path: string;
     reason: 'new' | 'update';
 };
+/** The canonical on-disk spelling of `target`, or null if it does not exist.
+ *  Windows answers path queries case-insensitively, so the only way to learn how
+ *  a directory is really spelled is to ask its parent to list it — a segment at a
+ *  time, from the root down. The drive letter is always uppercased.
+ *
+ *  2026-09-06 — Claude Code (Fable 5.1), at Bob's direction: exported so cli.ts can
+ *  canonicalize the working directory at startup (see there for why). Deliberately
+ *  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.
  *

package/lib.js

@@ -1323,8 +1323,13 @@ function hasLocalChanges(packageName, version, targetPath, verbose) {
 /** The canonical on-disk spelling of `target`, or null if it does not exist.
  *  Windows answers path queries case-insensitively, so the only way to learn how
  *  a directory is really spelled is to ask its parent to list it — a segment at a
- *  time, from the root down. */
-function canonicalCase(target) {
+ *  time, from the root down. The drive letter is always uppercased.
+ *
+ *  2026-09-06 — Claude Code (Fable 5.1), at Bob's direction: exported so cli.ts can
+ *  canonicalize the working directory at startup (see there for why). Deliberately
+ *  NOT `fs.realpathSync.native`: that would also resolve a junction the user is
+ *  standing inside, which is a behaviour change nobody asked for. */
+export function canonicalCase(target) {
     const full = path.resolve(target);
     if (!fs.existsSync(full))
         return null;
@@ -1347,12 +1352,43 @@ function canonicalCase(target) {
     return cur;
 }
 /** True when two paths name the same place but are spelled with different case
- *  in a directory name. A bare drive-letter difference (`y:` vs `Y:`) doesn't
- *  count — it resolves identically everywhere, including WSL's /mnt/y. */
+ *  anywhere — the drive letter included.
+ *
+ *  2026-09-06 — Claude Code (Fable 5.1), at Bob's direction. This used to strip the
+ *  root before comparing, on the theory that `y:` vs `Y:` "resolves identically
+ *  everywhere". It does on the filesystem; it does NOT inside npm's arborist.
+ *  Traced with an instrumented `loadActual` on dbitemx / pings / itemw: arborist
+ *  keeps the junction target's case in `realpath` (an exact-string index) but
+ *  computes `location` with `path.win32.relative`, which folds drive-letter case.
+ *  One directory reached as `Y:\...` and `y:\...` becomes two target nodes at one
+ *  location; the second clobbers the first, every Link into the first is left with
+ *  `target === null`, and the next same-case Link crashes on `target.package` —
+ *  the "Cannot read properties of null (reading 'package')" failure. npm writes
+ *  the junction target with whatever drive case the cwd had, so a lowercase shell
+ *  is all it takes. Full trace: `.llm/arborist-trace.md`. */
 function caseDiffers(a, b) {
-    const strip = (p) => p.replace(/[\\/]+$/, '').slice(path.parse(p).root.length);
+    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.
  *
@@ -2311,6 +2347,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);
@@ -3488,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));
@@ -3497,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)
@@ -6124,6 +6181,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) {

package/package.json

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