@bobfrankston/npmglobalize 1.0.195 → 1.0.197

package/README.md

@@ -590,14 +590,43 @@ Before transforming or publishing anything, `npmglobalize` builds `file:` depend
 
 For each project visited (the target and every transitive `file:` dep):
 
-- If `tsconfig.json` is missing or has `"noEmit": true` → **skip** (not a TypeScript build).
-- If `tsconfig.json` exists but `package.json` has no `"build"` script → **prompt** to add `"build": "tsc"`. Decline and that project is skipped.
+- If `tsconfig.json` is missing or has `"noEmit": true` → **skip** (not a TypeScript build), unless the `build` script runs `importgen` — a plain-JS browser app still needs its import map regenerated.
+- If `tsconfig.json` exists but `package.json` has no `"build"` script → **prompt** to add `"build": "tsc"` (plus a `tsc -p <dir>` per sub-project — see below). Decline and that project is skipped.
 - Otherwise → run `npm run build`. A failure halts the cascade unless `-force` is passed.
 
 Cycle-safe via a shared visited set; each project is built at most once per run.
 
 This complements the existing publish cascade (which ensures version refs are correct) by closing the build-freshness gap that `npm install` alone left open.
 
+#### Import maps (`importgen`) as a build step
+
+Browser projects that use [`importgen`](https://www.npmjs.com/package/@bobfrankston/importgen) have historically regenerated their import map from `.vscode/tasks.json`, which only runs when VS Code opens the folder — so a command-line or CI build could publish a stale map. `npmglobalize` treats the import map as a build product and moves the step into the package's own `build` script, where every build path picks it up.
+
+Before building each project, it checks whether the project is an importgen project, in this order:
+
+1. `.vscode/tasks.json` has a task whose `command` is `importgen` (the HTML file, if the task names one, is reused).
+2. A root-level `.htm`/`.html` file already contains a `<script type="importmap">` block (`index.html`, `default.html`, `default.htm` are checked first, so a stray `temp.htm` doesn't win).
+3. `importgen` is in `dependencies`/`devDependencies` **and** the project has one of those HTML files — the HTML requirement keeps packages that merely *use* importgen as a library from matching.
+
+If a signal matches and the `build` script doesn't already run `importgen`, you're prompted to rewrite it — e.g. `"build": "tsc"` → `"build": "importgen default.htm && tsc"`. The HTML file is named explicitly so importgen doesn't have to guess. Decline and `"importgen": false` is written to `.globalize.json5`, which suppresses the prompt for good; `-noimportgen` does the same from the command line.
+
+Once wired, the freshness check gains a second condition: a project whose build runs importgen is only considered up to date if the generated HTML is at least as new as `package.json`. Adding a dependency changes the import map without touching any `.ts` file, which the source-vs-output comparison alone would miss.
+
+#### Sub-projects (a second `tsconfig.json` in a sub-directory)
+
+A package can hold more than one TypeScript project. The common shape is a service worker in `Sw/` with its own `tsconfig.json` (`lib: ["WebWorker"]`, its own `outDir`) that the root `tsconfig.json` lists under `exclude` — so a bare `"build": "tsc"` compiles everything *except* the service worker, and the stale `sw2.js` ships. As with import maps, these have historically been built only by a second `.vscode/tasks.json` watcher, which runs on folder open and nowhere else.
+
+Before building, `npmglobalize` looks for sub-projects, in this order:
+
+1. `.vscode/tasks.json` has a task that runs `tsc` with `"options": { "cwd": "${workspaceFolder}/Sw" }` or with `-p`/`--project` naming a sub-directory (authoritative — it's how the project is actually built today; the task's `label` is quoted back in the prompt).
+2. An immediate sub-directory containing its own `tsconfig.json`. Build output and vendored trees (`node_modules`, `prev`, `dist`, `built`, `out`, `wwwroot`, `coverage`, `temp`, `preflight`, dot-directories) are never scanned.
+
+Nothing is detected when the root `tsconfig.json` uses project `references` — that build graph belongs to `tsc -b` and isn't second-guessed.
+
+When the `build` script is `tsc`-driven and doesn't already compile a detected sub-project, you're prompted to append it — `"build": "tsc"` → `"build": "tsc && tsc -p Sw"`, or for an importgen project `"build": "importgen default.htm && tsc && tsc -p Sw"`. Already-wired scripts are recognized in any of their spellings (`tsc -p Sw`, `tsc --project ./Sw/tsconfig.json`, `cd Sw && tsc`), and the directory is emitted with its real on-disk casing so the script still works on WSL and CI. Decline and `"subProjects": false` is written to `.globalize.json5`, suppressing the prompt for good; a `"subProjects": ["Sw"]` array pins the list instead of detecting it.
+
+Sub-projects the build actually compiles are also folded into the freshness check — the package rebuilds when a sub-project's sources are newer than its output. A sub-project that emits *outside* its own directory (`"outDir": ".."`, the usual service-worker case) always reports stale: comparing its sources against the whole package would prove nothing.
+
 #### TypeScript 6 `types` auto-fix
 
 TypeScript 6 dropped the legacy behavior of auto-including every installed `@types/*` package. A `tsconfig.json` with no explicit `compilerOptions.types` then loses the Node globals (`process`, `Buffer`, …) and the build fails with `TS2591`.

package/cli.js

@@ -73,7 +73,9 @@ Install Options:
   -freeze        Freeze node_modules (replace symlinks with real copies for network shares)
   -nofreeze      Disable freeze
   -importgen     Run importgen to update import maps before publishing
-  -noimportgen   Disable importgen
+                 (auto-detected from .vscode/tasks.json or an import map in the
+                 project's HTML — npmglobalize offers to add it to the build script)
+  -noimportgen   Disable importgen (recorded in .globalize.json5, stops the prompt)
   -once          Don't persist flags to .globalize.json5
 
 Mode Options:

package/lib.d.ts

@@ -101,6 +101,11 @@ export interface GlobalizeOptions {
     once?: boolean;
     /** Run importgen to update import maps before publishing */
     importgen?: boolean;
+    /** Sub-directories with their own tsconfig.json that `build` must also compile
+     *  (e.g. a service worker in `Sw/`). undefined: auto-detect from
+     *  .vscode/tasks.json + nested tsconfigs. An array pins the list.
+     *  false: never ask about sub-projects here. */
+    subProjects?: string[] | false;
     /** Use filesystem paths for `file:` deps (default true). Set false to
      *  mark a package as publishable/installable even when sibling checkouts
      *  are absent. Currently declarative (recorded in config and displayed);
@@ -324,6 +329,42 @@ export declare function ensureFileDepModules(cwd: string, verbose?: boolean, vis
  *  ignored — npmglobalize itself rewrites it around every publish, which would
  *  otherwise force a rebuild on every run. */
 export declare function isBuildUpToDate(cwd: string): boolean;
+/** Detect whether a package is an importgen project — a browser app whose HTML
+ *  carries a generated `<script type="importmap">`. Signals, in order:
+ *    1. `.vscode/tasks.json` runs `importgen` (how these projects are driven
+ *       today: VS Code starts an importgen watcher on folder open),
+ *    2. a root HTML file already contains an import map,
+ *    3. importgen is a declared dependency.
+ *  Returns the HTML file importgen should update plus the signal that matched,
+ *  or null when this isn't an importgen project. */
+export declare function detectImportgen(cwd: string): {
+    htmlFile?: string;
+    reason: string;
+} | null;
+/** Wire `importgen` into the package's own `build` script when the project turns
+ *  out to be an importgen project. The import map is a build product, so it
+ *  belongs in `npm run build` — that way it regenerates everywhere (VS Code, CI,
+ *  a bare command line, npmglobalize) instead of only when VS Code happens to
+ *  start its watcher on folder open. Declining records `importgen: false` in
+ *  .globalize.json5 so it stops asking. */
+export declare function ensureImportgenInBuild(cwd: string): Promise<void>;
+/** Sub-directories that need their own `tsc -p <dir>` pass. A package can hold
+ *  more than one tsconfig — a service worker compiled with `lib: WebWorker`, say,
+ *  which the root tsconfig `exclude`s — and the root `tsc` silently skips them.
+ *  Signals, in order:
+ *    1. `.vscode/tasks.json` runs tsc with `options.cwd` or `-p` pointing at a
+ *       sub-dir (authoritative: it's how the developer actually builds today),
+ *    2. an immediate sub-directory holding its own tsconfig.json.
+ *  Returns nothing when the root tsconfig uses project `references` — `tsc -b`
+ *  owns that build graph and shouldn't be second-guessed. */
+export declare function detectSubProjects(cwd: string): Array<{
+    dir: string;
+    reason: string;
+}>;
+/** Append `tsc -p <dir>` for every sub-project the existing build script misses.
+ *  Only touches tsc-driven builds — a bundler-driven `build` has its own idea of
+ *  what to compile. Declining records `subProjects: false` in .globalize.json5. */
+export declare function ensureSubProjectsInBuild(cwd: string): Promise<void>;
 /** Build a single project: detect tsconfig, prompt to add `build: tsc` if a
  *  TypeScript project lacks a build script, run `npm run build`, record
  *  failures. Returns true if build succeeded (or was skipped because no
@@ -416,6 +457,14 @@ export declare function fixPuppeteerCorruptedCache(combined: string): {
     repaired: string[];
     removed: string[];
 };
+/** Every package in `dir`'s dependency closure that shares its scope — our
+ *  own packages, published by this same tool. Walks node_modules for
+ *  transitive own-scope deps, since a cascade dep can carry its own
+ *  postinstall and only its installed copy lists its dependencies.
+ *
+ *  Returns [] for an unscoped package: there's no way to tell an unscoped
+ *  package of ours from a third-party one by name alone. */
+export declare function ownScopePackages(dir: string): string[];
 /** Run a command and return success status */
 export declare function runCommand(cmd: string, args: string[], options?: {
     silent?: boolean;

package/lib.js

@@ -299,6 +299,10 @@ export function writeConfig(dir, config, explicitKeys) {
                 comment = '  // Resolve file: deps from sibling checkouts (set false for standalone packages)';
             else if (key === 'allowTs')
                 comment = '  // Keep .ts source (and *.map, tsconfig.json) in the published npm tarball';
+            else if (key === 'importgen')
+                comment = '  // Regenerate browser import maps (false = never ask about importgen here)';
+            else if (key === 'subProjects')
+                comment = '  // Sub-dirs with their own tsconfig that build must compile (false = never ask)';
             lines.push(`  "${key}": ${jsonValue}${comma}${comment}`);
         });
         lines.push('');
@@ -321,6 +325,8 @@ export function writeConfig(dir, config, explicitKeys) {
     lines.push('  // "freeze": false              // Freeze node_modules (replace symlinks with real copies)');
     lines.push('  // "usePaths": true              // Resolve file: deps from siblings; false = use latest npm version (standalone)');
     lines.push('  // "allowTs": false              // Include .ts source in npm tarball (auto-true for noEmit projects)');
+    lines.push('  // "importgen": auto             // Detected from .vscode/tasks.json / import map in HTML; false = never ask');
+    lines.push('  // "subProjects": auto           // Sub-dirs with their own tsconfig (e.g. ["Sw"]); detected from .vscode/tasks.json; false = never ask');
     lines.push('}');
     fs.writeFileSync(configPath, lines.join('\n') + '\n');
 }
@@ -2400,12 +2406,372 @@ export function isBuildUpToDate(cwd) {
     }
     return configTime <= newestOut;
 }
+/** HTML files importgen looks for when none is named, in its preference order. */
+const IMPORTGEN_HTML_CANDIDATES = ['index.html', 'default.html', 'default.htm'];
+/** Resolve the HTML file importgen would update in `cwd`. */
+function findImportgenHtml(cwd, preferred) {
+    if (preferred && fs.existsSync(path.join(cwd, preferred)))
+        return preferred;
+    for (const name of IMPORTGEN_HTML_CANDIDATES) {
+        if (fs.existsSync(path.join(cwd, name)))
+            return name;
+    }
+    return undefined;
+}
+/** True when a script string invokes importgen (`importgen`, `npx importgen`,
+ *  `importgen default.htm`, …) — used to tell a wired build from an unwired one. */
+function scriptRunsImportgen(script) {
+    return /(^|[\s/\\&|])importgen(\s|$)/.test(script);
+}
+/** Detect whether a package is an importgen project — a browser app whose HTML
+ *  carries a generated `<script type="importmap">`. Signals, in order:
+ *    1. `.vscode/tasks.json` runs `importgen` (how these projects are driven
+ *       today: VS Code starts an importgen watcher on folder open),
+ *    2. a root HTML file already contains an import map,
+ *    3. importgen is a declared dependency.
+ *  Returns the HTML file importgen should update plus the signal that matched,
+ *  or null when this isn't an importgen project. */
+export function detectImportgen(cwd) {
+    // 1. .vscode/tasks.json — JSON5 because VS Code allows comments/trailing commas
+    try {
+        const tasks = JSON5.parse(fs.readFileSync(path.join(cwd, '.vscode', 'tasks.json'), 'utf-8'));
+        for (const task of Array.isArray(tasks?.tasks) ? tasks.tasks : []) {
+            const command = typeof task?.command === 'string' ? task.command : '';
+            const args = Array.isArray(task?.args) ? task.args.filter((a) => typeof a === 'string') : [];
+            if (!scriptRunsImportgen(command))
+                continue;
+            const named = args.find(a => /\.html?$/i.test(a));
+            return { htmlFile: findImportgenHtml(cwd, named), reason: '.vscode/tasks.json runs importgen' };
+        }
+    }
+    catch {
+        // No tasks.json, or unparsable — fall through to the other signals
+    }
+    // 2. A root HTML file that already holds an import map. Check importgen's own
+    //    candidates first so `default.htm` wins over a stray `temp.htm` copy.
+    let htmlFiles = [];
+    try {
+        htmlFiles = fs.readdirSync(cwd).filter(f => /\.html?$/i.test(f));
+    }
+    catch {
+        // Unreadable directory — nothing to detect
+    }
+    htmlFiles.sort((a, b) => {
+        const rank = (f) => {
+            const i = IMPORTGEN_HTML_CANDIDATES.indexOf(f.toLowerCase());
+            return i === -1 ? IMPORTGEN_HTML_CANDIDATES.length : i;
+        };
+        return rank(a) - rank(b) || a.localeCompare(b);
+    });
+    for (const name of htmlFiles) {
+        try {
+            const html = fs.readFileSync(path.join(cwd, name), 'utf-8');
+            if (/<script\s+type=["']importmap["']/i.test(html)) {
+                return { htmlFile: name, reason: `${name} contains an import map` };
+            }
+        }
+        catch {
+            // Unreadable file — try the next one
+        }
+    }
+    // 3. importgen declared as a dependency AND an HTML file to inject into.
+    //    The HTML requirement matters: a package can depend on importgen as a
+    //    library (npmglobalize itself does) without being a browser app.
+    const htmlFile = findImportgenHtml(cwd);
+    if (htmlFile) {
+        try {
+            const pkg = readPackageJson(cwd);
+            for (const key of ['dependencies', 'devDependencies']) {
+                const deps = pkg?.[key];
+                if (!deps || typeof deps !== 'object')
+                    continue;
+                if (Object.keys(deps).some(n => n === 'importgen' || n.endsWith('/importgen'))) {
+                    return { htmlFile, reason: `importgen is in ${key}` };
+                }
+            }
+        }
+        catch {
+            // No package.json — caller handles that
+        }
+    }
+    return null;
+}
+/** Wire `importgen` into the package's own `build` script when the project turns
+ *  out to be an importgen project. The import map is a build product, so it
+ *  belongs in `npm run build` — that way it regenerates everywhere (VS Code, CI,
+ *  a bare command line, npmglobalize) instead of only when VS Code happens to
+ *  start its watcher on folder open. Declining records `importgen: false` in
+ *  .globalize.json5 so it stops asking. */
+export async function ensureImportgenInBuild(cwd) {
+    const config = readConfig(cwd);
+    if (config.importgen === false)
+        return;
+    let pkg;
+    try {
+        pkg = readPackageJson(cwd);
+    }
+    catch {
+        return;
+    }
+    const buildScript = typeof pkg.scripts?.build === 'string' ? pkg.scripts.build : '';
+    if (scriptRunsImportgen(buildScript))
+        return; // already wired
+    const detected = config.importgen === true
+        ? { htmlFile: findImportgenHtml(cwd), reason: 'importgen: true in .globalize.json5' }
+        : detectImportgen(cwd);
+    if (!detected)
+        return;
+    const name = pkg.name || path.basename(cwd);
+    // Name the HTML file explicitly: importgen's own search order may pick a
+    // different file than the one this project actually ships.
+    const command = detected.htmlFile ? `importgen ${detected.htmlFile}` : 'importgen';
+    const newScript = buildScript ? `${command} && ${buildScript}` : command;
+    console.log(colors.yellow(`${name} looks like an importgen project (${detected.reason}) but its build script doesn't run importgen.`));
+    const addIt = await confirm(`Set "build": "${newScript}" in ${name}'s package.json?`, true);
+    if (!addIt) {
+        writeConfig(cwd, { ...config, importgen: false }, new Set(['importgen']));
+        console.log(colors.dim(`  Recorded importgen: false in .globalize.json5 — won't ask again.`));
+        return;
+    }
+    if (!pkg.scripts)
+        pkg.scripts = {};
+    pkg.scripts.build = newScript;
+    writePackageJson(cwd, pkg);
+    console.log(colors.green(`✓ Added importgen to ${name}'s build script`));
+}
+/** True when the generated import map is at least as new as the package.json it
+ *  is generated from. `isBuildUpToDate` only compares .ts sources to emitted
+ *  .js, so it can't see a dependency added to package.json — which is exactly
+ *  what changes an import map. */
+function isImportMapUpToDate(cwd) {
+    const htmlFile = findImportgenHtml(cwd, detectImportgen(cwd)?.htmlFile);
+    if (!htmlFile)
+        return false; // can't tell which file — let the build run
+    const mtime = (p) => { try {
+        return fs.statSync(p).mtimeMs;
+    }
+    catch {
+        return 0;
+    } };
+    const htmlTime = mtime(path.join(cwd, htmlFile));
+    return htmlTime > 0 && htmlTime >= mtime(path.join(cwd, 'package.json'));
+}
+/** Directories never worth scanning for a nested tsconfig — build output, vendored
+ *  code, and the prev/ archive all carry stray tsconfigs that aren't sub-projects. */
+const SUBPROJECT_SKIP_DIRS = new Set([
+    'node_modules', 'prev', 'built', 'build', 'dist', 'out', 'output',
+    'wwwroot', 'coverage', 'temp', 'tmp', 'preflight'
+]);
+/** True when a script string invokes `tsc` (`tsc`, `npx tsc`, `tsc -p Sw`, …). */
+function scriptRunsTsc(script) {
+    return /(^|[\s&|(])(npx\s+)?tsc(\s|$)/.test(script);
+}
+/** Normalize a path as written in a script/task (quotes, backslashes, `./`,
+ *  a trailing `tsconfig.json`) down to a comparable relative directory. */
+function normalizeProjectPath(raw) {
+    return raw
+        .replace(/^["']|["']$/g, '')
+        .replace(/\$\{workspaceFolder\}/gi, '')
+        .replace(/\\/g, '/')
+        .replace(/^\.\//, '')
+        .replace(/\/tsconfig\.json$/i, '')
+        .replace(/^\/+|\/+$/g, '');
+}
+/** Match `rel` against what's actually on disk so the emitted script uses the
+ *  real casing (`Sw`, not `sw`) — Windows compares case-insensitively, but the
+ *  script also has to run on WSL/CI where it doesn't. Returns null if absent. */
+function resolveOnDiskCase(base, rel) {
+    const parts = rel.split('/').filter(Boolean);
+    let dir = base;
+    const out = [];
+    for (const part of parts) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            return null;
+        }
+        const match = entries.find(e => e.toLowerCase() === part.toLowerCase());
+        if (!match)
+            return null;
+        out.push(match);
+        dir = path.join(dir, match);
+    }
+    return out.length ? out.join('/') : null;
+}
+/** True when `script` already compiles the tsconfig in `dir` — `tsc -p Sw`,
+ *  `tsc --project ./Sw/tsconfig.json`, or `cd Sw && tsc`. */
+function scriptBuildsSubProject(script, dir) {
+    const target = normalizeProjectPath(dir).toLowerCase();
+    if (!target)
+        return false;
+    for (const re of [/(?:^|\s)(?:-p|--project)[\s=]+("[^"]+"|'[^']+'|\S+)/g,
+        /(?:^|[\s&|(])cd\s+("[^"]+"|'[^']+'|\S+)/g]) {
+        for (const m of script.matchAll(re)) {
+            if (normalizeProjectPath(m[1]).toLowerCase() === target)
+                return true;
+        }
+    }
+    return false;
+}
+/** Sub-directories that need their own `tsc -p <dir>` pass. A package can hold
+ *  more than one tsconfig — a service worker compiled with `lib: WebWorker`, say,
+ *  which the root tsconfig `exclude`s — and the root `tsc` silently skips them.
+ *  Signals, in order:
+ *    1. `.vscode/tasks.json` runs tsc with `options.cwd` or `-p` pointing at a
+ *       sub-dir (authoritative: it's how the developer actually builds today),
+ *    2. an immediate sub-directory holding its own tsconfig.json.
+ *  Returns nothing when the root tsconfig uses project `references` — `tsc -b`
+ *  owns that build graph and shouldn't be second-guessed. */
+export function detectSubProjects(cwd) {
+    try {
+        const root = JSON5.parse(fs.readFileSync(path.join(cwd, 'tsconfig.json'), 'utf-8'));
+        if (Array.isArray(root?.references) && root.references.length > 0)
+            return [];
+    }
+    catch {
+        // No root tsconfig (or unparsable) — nested ones still count
+    }
+    const found = new Map(); // on-disk relative dir → reason
+    const add = (raw, reason) => {
+        const rel = normalizeProjectPath(raw);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+            return;
+        if (rel.split('/').some(p => SUBPROJECT_SKIP_DIRS.has(p.toLowerCase()) || p.startsWith('.')))
+            return;
+        const onDisk = resolveOnDiskCase(cwd, rel);
+        if (!onDisk)
+            return;
+        if (!fs.existsSync(path.join(cwd, onDisk, 'tsconfig.json')))
+            return;
+        if (!found.has(onDisk))
+            found.set(onDisk, reason);
+    };
+    // 1. .vscode/tasks.json — JSON5 because VS Code allows comments/trailing commas
+    try {
+        const tasks = JSON5.parse(fs.readFileSync(path.join(cwd, '.vscode', 'tasks.json'), 'utf-8'));
+        for (const task of Array.isArray(tasks?.tasks) ? tasks.tasks : []) {
+            const command = typeof task?.command === 'string' ? task.command : '';
+            const args = Array.isArray(task?.args) ? task.args.filter((a) => typeof a === 'string') : [];
+            if (!scriptRunsTsc([command, ...args].join(' ')))
+                continue;
+            const label = typeof task?.label === 'string' ? task.label : 'a tsc task';
+            const projIdx = args.findIndex(a => a === '-p' || a === '--project');
+            if (projIdx !== -1 && args[projIdx + 1]) {
+                add(args[projIdx + 1], `.vscode/tasks.json "${label}" builds it`);
+            }
+            else if (typeof task?.options?.cwd === 'string') {
+                add(task.options.cwd, `.vscode/tasks.json "${label}" runs tsc there`);
+            }
+        }
+    }
+    catch {
+        // No tasks.json, or unparsable — fall through to the filesystem scan
+    }
+    // 2. Immediate sub-directories with their own tsconfig.json
+    try {
+        for (const e of fs.readdirSync(cwd, { withFileTypes: true })) {
+            if (!e.isDirectory() || e.isSymbolicLink())
+                continue;
+            if (e.name.startsWith('.') || SUBPROJECT_SKIP_DIRS.has(e.name.toLowerCase()))
+                continue;
+            if (fs.existsSync(path.join(cwd, e.name, 'tsconfig.json'))) {
+                add(e.name, `${e.name}/tsconfig.json`);
+            }
+        }
+    }
+    catch {
+        // Unreadable directory — nothing more to detect
+    }
+    return [...found].map(([dir, reason]) => ({ dir, reason }));
+}
+/** The sub-projects to wire, honoring `.globalize.json5`: `false` disables the
+ *  whole check, an array pins the list instead of detecting it. */
+function configuredSubProjects(cwd, config) {
+    if (config.subProjects === false)
+        return [];
+    if (Array.isArray(config.subProjects)) {
+        return config.subProjects
+            .map(d => ({ dir: resolveOnDiskCase(cwd, normalizeProjectPath(d)) || d, reason: 'listed in .globalize.json5' }))
+            .filter(s => fs.existsSync(path.join(cwd, s.dir, 'tsconfig.json')));
+    }
+    return detectSubProjects(cwd);
+}
+/** Quote a path for a package.json script only when it needs it. */
+function quoteScriptPath(p) {
+    return /[\s&|<>]/.test(p) ? `"${p}"` : p;
+}
+/** Append `tsc -p <dir>` for every sub-project the existing build script misses.
+ *  Only touches tsc-driven builds — a bundler-driven `build` has its own idea of
+ *  what to compile. Declining records `subProjects: false` in .globalize.json5. */
+export async function ensureSubProjectsInBuild(cwd) {
+    const config = readConfig(cwd);
+    if (config.subProjects === false)
+        return;
+    let pkg;
+    try {
+        pkg = readPackageJson(cwd);
+    }
+    catch {
+        return;
+    }
+    const buildScript = typeof pkg.scripts?.build === 'string' ? pkg.scripts.build.trim() : '';
+    if (!buildScript || !scriptRunsTsc(buildScript))
+        return;
+    const missing = configuredSubProjects(cwd, config)
+        .filter(s => !scriptBuildsSubProject(buildScript, s.dir));
+    if (missing.length === 0)
+        return;
+    const name = pkg.name || path.basename(cwd);
+    const newScript = [buildScript, ...missing.map(s => `tsc -p ${quoteScriptPath(s.dir)}`)].join(' && ');
+    // Default to yes only when tasks.json says the developer already builds these
+    // — a bare nested tsconfig (tests, examples) is a weaker signal, and this
+    // prompt rewrites a build script that currently works.
+    const strong = missing.every(s => s.reason.startsWith('.vscode/tasks.json') || s.reason.startsWith('listed in'));
+    console.log(colors.yellow(`${name}'s build script doesn't compile ${missing.length === 1 ? 'a sub-project' : 'its sub-projects'}:`));
+    for (const s of missing)
+        console.log(colors.yellow(`  ${s.dir}/ — ${s.reason}`));
+    const addIt = await confirm(`Set "build": "${newScript}" in ${name}'s package.json?`, strong);
+    if (!addIt) {
+        writeConfig(cwd, { ...config, subProjects: false }, new Set(['subProjects']));
+        console.log(colors.dim(`  Recorded subProjects: false in .globalize.json5 — won't ask again.`));
+        return;
+    }
+    pkg.scripts.build = newScript;
+    writePackageJson(cwd, pkg);
+    console.log(colors.green(`✓ Added ${missing.map(s => `tsc -p ${s.dir}`).join(' && ')} to ${name}'s build script`));
+}
+/** Freshness for the sub-projects the build script actually compiles. A
+ *  sub-project that emits outside its own directory (a service worker with
+ *  `outDir: ".."`, say) reports stale: `isBuildUpToDate` would then be comparing
+ *  its sources against the whole package, which proves nothing. */
+function areSubProjectsUpToDate(cwd, subs) {
+    for (const s of subs) {
+        const dir = path.join(cwd, s.dir);
+        let co;
+        try {
+            co = JSON5.parse(fs.readFileSync(path.join(dir, 'tsconfig.json'), 'utf-8')).compilerOptions || {};
+        }
+        catch {
+            return false;
+        }
+        if (typeof co.outDir === 'string' && path.relative(dir, path.resolve(dir, co.outDir)).startsWith('..'))
+            return false;
+        if (!isBuildUpToDate(dir))
+            return false;
+    }
+    return true;
+}
 /** Build a single project: detect tsconfig, prompt to add `build: tsc` if a
  *  TypeScript project lacks a build script, run `npm run build`, record
  *  failures. Returns true if build succeeded (or was skipped because no
  *  tsconfig / noEmit / no build script after declining the prompt / output
  *  already up to date). Pass `forceBuild` to skip the freshness check. */
 export async function buildProject(cwd, opts = {}) {
+    // Do this before the tsconfig check: an importgen project may be plain JS
+    // with no tsconfig at all, and still need its import map regenerated.
+    await ensureImportgenInBuild(cwd);
     let shouldBuild = false;
     try {
         const tsconfigPath = path.join(cwd, 'tsconfig.json');
@@ -2416,25 +2782,60 @@ export async function buildProject(cwd, opts = {}) {
     catch {
         // No tsconfig — skip
     }
-    if (!shouldBuild)
+    let earlyPkg;
+    try {
+        earlyPkg = readPackageJson(cwd);
+    }
+    catch {
         return true;
-    const pkg = readPackageJson(cwd);
-    if (!pkg.scripts?.build) {
+    }
+    const runsImportgen = scriptRunsImportgen(typeof earlyPkg.scripts?.build === 'string' ? earlyPkg.scripts.build : '');
+    // A build script that regenerates the import map is worth running even when
+    // there's nothing for tsc to emit.
+    if (!shouldBuild && !runsImportgen)
+        return true;
+    const pkg = earlyPkg;
+    const existingBuild = typeof pkg.scripts?.build === 'string' ? pkg.scripts.build.trim() : '';
+    // A build script ensureImportgenInBuild just created for a package that had
+    // none still needs its tsc pass — treat importgen-only as "no build yet".
+    const importgenOnly = !!existingBuild && existingBuild.split(/\s*&&\s*/).every(scriptRunsImportgen);
+    if (shouldBuild && (!existingBuild || importgenOnly)) {
+        // Compile the sub-projects (service worker, …) in the same breath: the
+        // root tsc excludes them, so a bare "tsc" would leave them unbuilt.
+        const subs = configuredSubProjects(cwd, readConfig(cwd));
+        const tscParts = ['tsc', ...subs.map(s => `tsc -p ${quoteScriptPath(s.dir)}`)];
+        const newScript = [...(existingBuild ? [existingBuild] : []), ...tscParts].join(' && ');
         console.log(colors.yellow(`TypeScript project has no "build" script in ${pkg.name || cwd}`));
-        const addIt = await confirm(`Add "build": "tsc" to ${pkg.name || path.basename(cwd)}'s package.json?`, true);
+        for (const s of subs)
+            console.log(colors.yellow(`  sub-project ${s.dir}/ — ${s.reason}`));
+        const addIt = await confirm(`Add "build": "${newScript}" to ${pkg.name || path.basename(cwd)}'s package.json?`, true);
         if (addIt) {
             if (!pkg.scripts)
                 pkg.scripts = {};
-            pkg.scripts.build = 'tsc';
+            pkg.scripts.build = newScript;
             writePackageJson(cwd, pkg);
-            console.log(colors.green(`✓ Added "build": "tsc" to ${pkg.name || path.basename(cwd)}`));
+            console.log(colors.green(`✓ Added "build": "${newScript}" to ${pkg.name || path.basename(cwd)}`));
         }
         else {
             return true;
         }
     }
+    else if (existingBuild) {
+        await ensureSubProjectsInBuild(cwd);
+        try {
+            const refreshed = readPackageJson(cwd);
+            if (typeof refreshed.scripts?.build === 'string')
+                pkg.scripts.build = refreshed.scripts.build;
+        }
+        catch { /* keep the script we already have */ }
+    }
     ensureTsconfigNodeTypes(cwd);
-    if (!opts.forceBuild && isBuildUpToDate(cwd)) {
+    // Only the sub-projects the final build script really compiles count toward
+    // freshness — one the user declined to wire in isn't this build's business.
+    const finalBuild = typeof pkg.scripts?.build === 'string' ? pkg.scripts.build : '';
+    const wiredSubs = detectSubProjects(cwd).filter(s => scriptBuildsSubProject(finalBuild, s.dir));
+    if (!opts.forceBuild && isBuildUpToDate(cwd) && areSubProjectsUpToDate(cwd, wiredSubs)
+        && (!runsImportgen || isImportMapUpToDate(cwd))) {
         console.log(colors.dim(`– Build up to date (${pkg.name || path.basename(cwd)})`));
         return true;
     }
@@ -2870,18 +3271,142 @@ export function fixPuppeteerCorruptedCache(combined) {
     }
     return { repaired: [], removed: [] };
 }
-/** npm 11.17+ gates lifecycle scripts behind `allowScripts` — non-covered
- *  scripts are skipped and the install still exits 0. A skipped postinstall
- *  can leave the package broken at runtime (puppeteer without its browser,
- *  native modules unbuilt), so surface the warning instead of burying it in
- *  the captured output. */
-function warnSkippedScripts(combined) {
+// ─── allowScripts policy: trust our own packages, gate everyone else ──
+//
+// npm 11.17+ skips install-time lifecycle scripts (preinstall/install/
+// postinstall) for packages that aren't on an allowlist, and a global
+// install has no project package.json to record approvals in — so a
+// postinstall we wrote ourselves silently never runs while the install
+// still exits 0. (@bobfrankston/msger's postinstall copies its native
+// binary into the per-user bin dir its launcher reads from; skipping it
+// leaves a stale exe behind a green checkmark.)
+//
+// npmglobalize only ever installs a package it just built and published
+// from the user's own source, so own-scope packages are trusted. Third-
+// party deps are not: they stay gated and keep surfacing through
+// warnSkippedScripts. That's deliberately narrower than a blanket
+// --dangerously-allow-all-scripts — it keeps the warning meaningful
+// instead of turning it into dead code.
+//
+// The policy matcher has no scope wildcard (`@scope/*` matches nothing —
+// see arborist's script-allowed.js), so the allowlist must name every
+// own-scope package in the tree explicitly.
+let _allowScriptsSupported = null;
+let _wslAllowScriptsSupported = null;
+/** Probe output for a config key npm doesn't define. */
+const isUnknownConfig = (out) => {
+    const v = out.trim();
+    return v === '' || v === 'undefined';
+};
+/** Does this npm know the allowScripts policy (11.17+)? Older npm runs all
+ *  install scripts unconditionally, and passing the flag there just prints
+ *  "Unknown cli config" on every install. Probed once per process.
+ *
+ *  Probes the boolean sibling flag rather than `allow-scripts` itself: an
+ *  unset list config also prints empty, which is indistinguishable from
+ *  "not supported". Both flags landed in the same npm release. */
+function npmSupportsAllowScripts() {
+    if (_allowScriptsSupported === null) {
+        const r = runCommand('npm', ['config', 'get', 'dangerously-allow-all-scripts'], { silent: true });
+        _allowScriptsSupported = r.success && !isUnknownConfig(r.output);
+    }
+    return _allowScriptsSupported;
+}
+/** Same probe against WSL's npm, which is a separate install and can lag
+ *  behind the Windows one. */
+async function wslNpmSupportsAllowScripts() {
+    if (_wslAllowScriptsSupported === null) {
+        const r = await runCommandAsync('wsl', ['npm', 'config', 'get', 'dangerously-allow-all-scripts'], { silent: true });
+        _wslAllowScriptsSupported = r.success && !isUnknownConfig(r.output);
+    }
+    return _wslAllowScriptsSupported;
+}
+/** Every package in `dir`'s dependency closure that shares its scope — our
+ *  own packages, published by this same tool. Walks node_modules for
+ *  transitive own-scope deps, since a cascade dep can carry its own
+ *  postinstall and only its installed copy lists its dependencies.
+ *
+ *  Returns [] for an unscoped package: there's no way to tell an unscoped
+ *  package of ours from a third-party one by name alone. */
+export function ownScopePackages(dir) {
+    let pkg;
+    try {
+        pkg = readPackageJson(dir);
+    }
+    catch {
+        return [];
+    }
+    const name = pkg.name || '';
+    const slash = name.indexOf('/');
+    if (!name.startsWith('@') || slash < 2)
+        return [];
+    const scope = name.slice(0, slash + 1); // '@bobfrankston/'
+    // npm hoists, so a dep's own deps usually sit in the root node_modules
+    // rather than nested under it — check both.
+    const resolveDep = (dep, from) => {
+        for (const cand of [path.join(from, 'node_modules', dep), path.join(dir, 'node_modules', dep)]) {
+            if (fs.existsSync(path.join(cand, 'package.json')))
+                return cand;
+        }
+        return null;
+    };
+    const found = new Set([name]);
+    const walk = (manifest, from) => {
+        const deps = { ...(manifest.dependencies || {}), ...(manifest.optionalDependencies || {}) };
+        for (const dep of Object.keys(deps)) {
+            if (!dep.startsWith(scope) || found.has(dep))
+                continue;
+            found.add(dep);
+            const depDir = resolveDep(dep, from);
+            if (!depDir)
+                continue; // not installed here — the name is still allowed
+            try {
+                walk(JSON.parse(fs.readFileSync(path.join(depDir, 'package.json'), 'utf-8')), depDir);
+            }
+            catch { /* unreadable dep manifest — the name is still allowed */ }
+        }
+    };
+    walk(pkg, dir);
+    return [...found];
+}
+/** npm args allowing install scripts for our own packages only. Empty when
+ *  npm predates the policy (it runs the scripts anyway) or the package is
+ *  unscoped.
+ *
+ *  Note: the CLI layer *replaces* the .npmrc layer rather than merging with
+ *  it (first source with any config wins, per npm's resolve-allow-scripts),
+ *  so passing this suppresses any allow-scripts entries in .npmrc for this
+ *  install. Third-party approvals therefore belong on the command line too,
+ *  not in .npmrc. */
+function allowOwnScriptsArgs(dir) {
+    if (!npmSupportsAllowScripts())
+        return [];
+    const own = ownScopePackages(dir);
+    return own.length ? ['--allow-scripts', own.join(',')] : [];
+}
+/** A skipped postinstall can leave a package broken at runtime (puppeteer
+ *  without its browser, native modules unbuilt), so surface the warning
+ *  instead of burying it in the captured output. Own-scope packages are
+ *  reported separately and louder: those were supposed to be allowed, so
+ *  one showing up here means the allowlist missed it. */
+function warnSkippedScripts(combined, allowed = []) {
     const pkgs = [...combined.matchAll(/^npm warn allow-scripts\s+(\S+@[^\s(]+) \(/gm)];
     if (!pkgs.length)
         return;
-    const names = pkgs.map(m => m[1].replace(/@[^@]+$/, ''));
-    console.log(colors.yellow(`  ⚠ npm skipped install scripts (allowScripts): ${pkgs.map(m => m[1]).join(', ')}`));
-    console.log(colors.yellow(`    Package may be broken at runtime. Allow with: npm config set allow-scripts=${names.join(',')} --location=user`));
+    const nameOf = (spec) => spec.replace(/@[^@]+$/, '');
+    const first = allowed[0] || '';
+    const scope = first.startsWith('@') ? first.slice(0, first.indexOf('/') + 1) : '';
+    const ours = scope ? pkgs.filter(m => nameOf(m[1]).startsWith(scope)) : [];
+    const others = pkgs.filter(m => !ours.includes(m));
+    if (ours.length) {
+        console.log(colors.red(`  ⚠ Own-scope install scripts still skipped: ${ours.map(m => m[1]).join(', ')}`));
+        console.log(colors.red(`    npmglobalize allowlisted ${allowed.length} own package(s) but missed these — likely transitive deps not present in the local node_modules tree.`));
+    }
+    if (others.length) {
+        const names = [...new Set(others.map(m => nameOf(m[1])))];
+        console.log(colors.yellow(`  ⚠ npm skipped install scripts for third-party packages: ${others.map(m => m[1]).join(', ')}`));
+        console.log(colors.yellow(`    Package may be broken at runtime. Allow with: npm install -g <pkg> --allow-scripts ${names.join(',')}`));
+    }
 }
 /** Run npm install -g with retries for registry propagation delay.
  *  Brand-new packages (first-time publish) take much longer to become
@@ -2900,16 +3425,20 @@ async function installGlobalWithRetry(pkgSpec, cwd, isNewPackage = false, maxRet
     let result = { success: false, output: '', stderr: '' };
     let attempt = 0;
     let cacheFixRounds = 0;
+    // Our own packages are trusted — we just built and published them from
+    // this very directory — so their install scripts run. Everything else
+    // stays behind npm's allowScripts gate.
+    const allowArgs = allowOwnScriptsArgs(cwd);
     while (true) {
-        console.log(colors.cyan(`> npm install -g ${pkgSpec}`));
-        result = await runCommandAsync('npm', ['install', '-g', pkgSpec], { cwd, silent: true });
+        console.log(colors.cyan(`> npm install -g ${pkgSpec}${allowArgs.length ? ` ${allowArgs.join(' ')}` : ''}`));
+        result = await runCommandAsync('npm', ['install', '-g', pkgSpec, ...allowArgs], { cwd, silent: true });
         const combined = `${result.output}\n${result.stderr}`;
         fullLog += `===== attempt ${attempt + 1}: npm install -g ${pkgSpec} =====\n${combined}\n`;
         if (result.success) {
             const added = combined.match(/^(?:added|changed|removed) \d+ packages?.*$/m);
             if (added)
                 console.log(colors.dim(`  ${added[0]}`));
-            warnSkippedScripts(combined);
+            warnSkippedScripts(combined, allowArgs.length ? allowArgs[1].split(',') : []);
             // A truncated puppeteer browser extraction exits 0, so the install
             // LOOKS fine while the cache is poisoned for every future install.
             // Verify now, while the leftover archive still allows a repair.
@@ -3147,6 +3676,14 @@ async function waitForNpmVersionInWsl(spec, maxWaitMs = 180000) {
     return false;
 }
 export async function installInWsl(wslArgs, opts = {}) {
+    // Same trust rule as the Windows installs: allow our own packages'
+    // install scripts, leave third-party ones gated. Probed against WSL's
+    // npm, which is a separate install from the Windows one.
+    if (opts.cwd && wslArgs.includes('install') && await wslNpmSupportsAllowScripts()) {
+        const own = ownScopePackages(opts.cwd);
+        if (own.length)
+            wslArgs = [...wslArgs, '--allow-scripts', own.join(',')];
+    }
     const runOnce = async () => {
         console.log(colors.cyan(`> wsl ${wslArgs.join(' ')}`));
         const r = await runCommandAsync('wsl', wslArgs, { cwd: opts.cwd, silent: true });
@@ -3634,29 +4171,39 @@ function getAuthInstructions() {
     return `
 Authentication Options:
 
-1. ${colors.yellow('Create a Granular Access Token')} (recommended):
+1. ${colors.yellow('Interactive login')} (recommended):
+   - Run: ${colors.green('npm login')}
+   - Web-based: completes 2FA in the browser and writes the token for you.
+   - The path that survives npm's token changes (see the note below).
+
+2. ${colors.yellow('Create a Granular Access Token')} (unattended use):
    - Go to: https://www.npmjs.com/settings/[username]/tokens
    - Click "Generate New Token" → "Granular Access Token"
    - Set permissions: ${colors.green('Read and write')} for packages
-   - Enable: ${colors.green('Bypass 2FA requirement')} (if available)
-   - Copy the token and save it securely
+   - Scope it to the packages you actually publish, and set an expiry
+   - ${colors.red('Do NOT enable "Bypass 2FA"')} — npm is retiring it:
+       · since early Aug 2026, bypass tokens no longer skip 2FA for token,
+         package-access, maintainer, org or team changes
+       · around Jan 2027, they lose direct publish entirely (read + stage
+         only; publication needs human 2FA approval)
 
-2. ${colors.yellow('Set token via environment variable')}:
+3. ${colors.yellow('Set token via environment variable')}:
    - Set: ${colors.green('NPM_TOKEN=npm_xxx...')}
    - Or run: ${colors.green('$env:NPM_TOKEN="npm_xxx..."')} (PowerShell)
 
-3. ${colors.yellow('Set token in .npmrc')}:
+4. ${colors.yellow('Set token in .npmrc')}:
    - Edit: ${colors.green(npmrcPath)}
    - Add: ${colors.green('//registry.npmjs.org/:_authToken=npm_xxx...')}
 
-4. ${colors.yellow('Use classic login')} (may require 2FA):
-   - Run: ${colors.green('npm login')}
-   - Follow interactive prompts
+5. ${colors.yellow('Publishing from CI')}:
+   - Prefer trusted publishing (OIDC) over any long-lived token — nothing to
+     rotate, and it is the supported path once bypass tokens lose publish.
 
 ${colors.italic('Note: y:\\dev\\utils\\npmglobalize has set-npm-token.ps1 that may help fix token')}
 ${colors.italic('      problems, but no promises.')}
 
-Note: npm now requires either 2FA or a granular token with bypass enabled.
+Note: unattended local publishing with a long-lived token is on a deprecation
+path. Plan for OIDC publishing from CI, or a publish step you approve with 2FA.
 `;
 }
 function loadIgnorePatterns() {
@@ -4588,7 +5135,7 @@ async function doLocalInstall(cwd, options) {
             console.log('  [dry-run] Would run: wsl npm install -g .');
         return true;
     }
-    const result = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+    const result = await runCommandAsync('npm', ['install', '-g', '.', ...allowOwnScriptsArgs(cwd)], { cwd, silent: false, showCommand: true });
     if (result.success) {
         console.log(colors.green(`✓ Installed locally: ${pkgName}@${pkgVersion}`));
     }
@@ -4599,7 +5146,7 @@ async function doLocalInstall(cwd, options) {
     }
     if (wsl) {
         console.log(`Installing ${pkgName} in WSL (local)...`);
-        const wslResult = await runCommandAsync('wsl', ['npm', 'install', '-g', '.'], { cwd, silent: false, showCommand: true });
+        const wslResult = await installInWsl(['npm', 'install', '-g', '.'], { cwd });
         if (wslResult.success) {
             console.log(colors.green(`✓ Installed in WSL: ${pkgName}@${pkgVersion}`));
         }
@@ -4704,7 +5251,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 console.log('  [dry-run] Would run: wsl npm install -g .');
             return true;
         }
-        const result = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+        const result = await runCommandAsync('npm', ['install', '-g', '.', ...allowOwnScriptsArgs(cwd)], { cwd, silent: false, showCommand: true });
         if (result.success) {
             console.log(colors.green(`✓ Installed locally: ${pkgName}@${pkgVersion}`));
         }
@@ -4715,7 +5262,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         }
         if (wsl) {
             console.log(`Installing ${pkgName} in WSL (local)...`);
-            const wslResult = runCommand('wsl', ['npm', 'install', '-g', '.'], { cwd, silent: false, showCommand: true });
+            const wslResult = await installInWsl(['npm', 'install', '-g', '.'], { cwd });
             if (wslResult.success) {
                 console.log(colors.green(`✓ Installed in WSL: ${pkgName}@${pkgVersion}`));
             }
@@ -5200,8 +5747,10 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             console.log('  [dry-run] Would run: npm run build');
         }
     }
-    // Run importgen if enabled (update import maps in HTML files)
-    if (options.importgen) {
+    // Run importgen if explicitly enabled and the build script isn't already
+    // doing it (the CLI wires it into `build` for detected importgen projects).
+    const buildRunsImportgen = scriptRunsImportgen(typeof pkg.scripts?.build === 'string' ? pkg.scripts.build : '');
+    if (options.importgen && !buildRunsImportgen) {
         try {
             if (!dryRun) {
                 const igResult = runImportgen(cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.195",
+  "version": "1.0.197",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bobfrankston/freezepak": "^0.1.9",
-    "@bobfrankston/importgen": "^0.1.38",
+    "@bobfrankston/importgen": "^0.1.39",
     "@bobfrankston/themecolors": "^0.1.8",
     "@bobfrankston/userconfig": "^1.0.10",
     "@npmcli/package-json": "^7.0.4",
@@ -60,7 +60,7 @@
   ".transformedSnapshot": {
     "dependencies": {
       "@bobfrankston/freezepak": "^0.1.9",
-      "@bobfrankston/importgen": "^0.1.38",
+      "@bobfrankston/importgen": "^0.1.39",
       "@bobfrankston/themecolors": "^0.1.8",
       "@bobfrankston/userconfig": "^1.0.10",
       "@npmcli/package-json": "^7.0.4",