@bobfrankston/npmglobalize 1.0.217 → 1.0.218

package/README.md

@@ -736,7 +736,7 @@ Browser projects that use [`importgen`](https://www.npmjs.com/package/@bobfranks
 
 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).
+1. `.vscode/tasks.json` has a task whose `command` is `importgen` (the HTML file, if the task names one, is reused). The task's `"options": { "cwd": ... }` is honored too: a plain sub-directory (`www/`) yields `importgen www/index.html`, while a sub-directory that is a package of its own (`client/package.json`) is not a root importgen project at all — its own build script owns the import map and the root build delegates to it (see Sub-projects below).
 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.
 
@@ -744,20 +744,25 @@ If a signal matches and the `build` script doesn't already run `importgen`, you'
 
 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)
+#### Sub-projects (a sub-directory with its own build script or `tsconfig.json`)
 
-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.
+A package can hold more than one project. Two shapes, treated differently:
+
+- **A sub-package** — `client/` with its own `package.json` whose `build` script (`importgen index.html && tsc`) already says how the client builds. That script is the single source of truth, so the root build **delegates** to it: `npm run build --prefix client`. The root never re-implements the client's recipe (no `importgen client/index.html && tsc -p client` in the root script), and the sub-package's own build script gets the same importgen check the root does.
+- **A plain tsconfig sub-directory** — 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. It has no build of its own, so the root runs `tsc -p Sw`.
+
+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.
+1. `.vscode/tasks.json` has a task that runs `tsc` or `importgen` with `"options": { "cwd": "${workspaceFolder}/client" }`, or runs `tsc` 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 `package.json` build script or `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.
+When the `build` script is `tsc`-driven and doesn't already build a detected sub-project, you're prompted to append it — `"build": "tsc"` → `"build": "tsc && npm run build --prefix client"` or `"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`, `npm run build --prefix client`, `npm -C client run build`), 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.
+Sub-projects the build actually runs are also folded into the freshness check — the package rebuilds when a sub-project's sources are newer than its output (for a sub-package, also when its import map is older than its `package.json`). 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
 

package/lib.d.ts

@@ -427,22 +427,30 @@ export declare function detectImportgen(cwd: string): {
  *  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.
+/** A sub-directory the root build must build, and how. */
+interface SubProject {
+    dir: string; /** Relative directory with its on-disk casing */
+    kind: 'package' | 'tsconfig'; /** package: delegate to its build script; tsconfig: `tsc -p` */
+    reason: string; /** The signal that found it, quoted in prompts */
+}
+/** Sub-directories the root build must build itself. A package can hold more
+ *  than one project — a service worker compiled with `lib: WebWorker` that the
+ *  root tsconfig `exclude`s, or a browser client that is a package of its own
+ *  with its own build script — 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.
+ *    1. `.vscode/tasks.json` runs tsc or importgen 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 package.json build script
+ *       or 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 detectSubProjects(cwd: string): SubProject[];
+/** Append a build step for every sub-project the existing build script misses:
+ *  `npm run build --prefix <dir>` for a sub-package, `tsc -p <dir>` for a plain
+ *  tsconfig. 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

package/lib.js

@@ -344,7 +344,7 @@ const VALUE_COMMENTS = {
     gitVisibility: 'private (default) or public',
     npmVisibility: 'private (default) or public',
     bump: 'patch (default), minor, or major',
-    subProjects: 'Sub-dirs with their own tsconfig that build must compile (false = never ask)'
+    subProjects: 'Sub-dirs with their own build script or tsconfig that build must run (false = never ask)'
 };
 /** Write .globalize.json5 config file */
 export function writeConfig(dir, config, explicitKeys) {
@@ -450,7 +450,7 @@ export function writeConfig(dir, config, explicitKeys) {
         ['"usePaths": true', 'true = resolve file: deps from siblings; false = use latest npm version (standalone)'],
         ['"allowTs": false', 'true = include .ts source in npm tarball (auto-true for noEmit projects)'],
         ['"importgen": auto', 'Detected from .vscode/tasks.json / import map in HTML; false = never ask'],
-        ['"subProjects": auto', 'Sub-dirs with their own tsconfig (e.g. ["Sw"]); detected from .vscode/tasks.json; false = never ask']
+        ['"subProjects": auto', 'Sub-dirs with their own build script or tsconfig (e.g. ["client", "Sw"]); detected from .vscode/tasks.json; false = never ask']
     ];
     const refWidth = Math.max(...reference.map(([decl]) => decl.length));
     for (const [decl, note] of reference) {
@@ -3019,7 +3019,27 @@ export function detectImportgen(cwd) {
             if (!scriptRunsImportgen(command))
                 continue;
             const named = args.find(a => /\.html?$/i.test(a));
-            return { htmlFile: findImportgenHtml(cwd, named), reason: '.vscode/tasks.json runs importgen' };
+            // 2026-09-06 — Claude Code (Fable 5.1), at Bob's direction.
+            // Honor the task's `options.cwd`. itemw runs importgen with cwd
+            // `${workspaceFolder}/client` because its HTML is client/index.html;
+            // ignoring that made us search the root, find nothing, and wire a bare
+            // `importgen` that failed with "No HTML file found".
+            //   - cwd is a sub-PACKAGE (has its own package.json): its own build
+            //     script owns the import map, and the root build delegates to it
+            //     (see detectSubProjects). Not a root importgen project.
+            //   - cwd is a plain sub-directory (www/ with just the HTML): run
+            //     `importgen www/index.html` from the root — importgen resolves
+            //     positional paths against cwd and finds package.json by walking up.
+            const taskCwd = typeof task?.options?.cwd === 'string' ? task.options.cwd : '';
+            let subdir = normalizeProjectPath(taskCwd);
+            if (path.isAbsolute(subdir))
+                subdir = ''; // some other machine's absolute path — nothing we can build from
+            if (subdir && fs.existsSync(path.join(cwd, subdir, 'package.json')))
+                return null;
+            const searchDir = subdir ? path.join(cwd, subdir) : cwd;
+            const found = findImportgenHtml(searchDir, named);
+            const htmlFile = found && subdir ? `${subdir}/${found}` : found;
+            return { htmlFile, reason: '.vscode/tasks.json runs importgen' };
         }
     }
     catch {
@@ -3178,13 +3198,34 @@ function resolveOnDiskCase(base, rel) {
     }
     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`. */
+/** Classify `rel` under `cwd`: a package with its own build script, a plain
+ *  tsconfig sub-project, or null when it's neither. */
+function subProjectKind(cwd, rel) {
+    try {
+        const pkg = readPackageJson(path.join(cwd, rel));
+        if (typeof pkg?.scripts?.build === 'string' && pkg.scripts.build.trim())
+            return 'package';
+    }
+    catch {
+        // No package.json there — fall through to the tsconfig test
+    }
+    return fs.existsSync(path.join(cwd, rel, 'tsconfig.json')) ? 'tsconfig' : null;
+}
+/** The command the root build script runs for a sub-project. */
+function subProjectBuildCommand(s) {
+    return s.kind === 'package'
+        ? `npm run build --prefix ${quoteScriptPath(s.dir)}`
+        : `tsc -p ${quoteScriptPath(s.dir)}`;
+}
+/** True when `script` already builds `dir` — `tsc -p Sw`,
+ *  `tsc --project ./Sw/tsconfig.json`, `cd Sw && tsc`, or for a package
+ *  `npm run build --prefix client` / `npm -C client run build`. */
 function scriptBuildsSubProject(script, dir) {
     const target = normalizeProjectPath(dir).toLowerCase();
     if (!target)
         return false;
     for (const re of [/(?:^|\s)(?:-p|--project)[\s=]+("[^"]+"|'[^']+'|\S+)/g,
+        /(?:^|\s)(?:-C|--prefix)[\s=]+("[^"]+"|'[^']+'|\S+)/g,
         /(?:^|[\s&|(])cd\s+("[^"]+"|'[^']+'|\S+)/g]) {
         for (const m of script.matchAll(re)) {
             if (normalizeProjectPath(m[1]).toLowerCase() === target)
@@ -3193,13 +3234,16 @@ function scriptBuildsSubProject(script, dir) {
     }
     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.
+/** Sub-directories the root build must build itself. A package can hold more
+ *  than one project — a service worker compiled with `lib: WebWorker` that the
+ *  root tsconfig `exclude`s, or a browser client that is a package of its own
+ *  with its own build script — 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.
+ *    1. `.vscode/tasks.json` runs tsc or importgen 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 package.json build script
+ *       or 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) {
@@ -3211,7 +3255,7 @@ export function detectSubProjects(cwd) {
     catch {
         // No root tsconfig (or unparsable) — nested ones still count
     }
-    const found = new Map(); // on-disk relative dir → reason
+    const found = new Map(); // on-disk relative dir → entry
     const add = (raw, reason) => {
         const rel = normalizeProjectPath(raw);
         if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
@@ -3221,10 +3265,11 @@ export function detectSubProjects(cwd) {
         const onDisk = resolveOnDiskCase(cwd, rel);
         if (!onDisk)
             return;
-        if (!fs.existsSync(path.join(cwd, onDisk, 'tsconfig.json')))
+        const kind = subProjectKind(cwd, onDisk);
+        if (!kind)
             return;
         if (!found.has(onDisk))
-            found.set(onDisk, reason);
+            found.set(onDisk, { dir: onDisk, kind, reason });
     };
     // 1. .vscode/tasks.json — JSON5 because VS Code allows comments/trailing commas
     try {
@@ -3232,37 +3277,39 @@ export function detectSubProjects(cwd) {
         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(' ')))
+            const line = [command, ...args].join(' ');
+            const tool = scriptRunsTsc(line) ? 'tsc' : scriptRunsImportgen(line) ? 'importgen' : null;
+            if (!tool)
                 continue;
-            const label = typeof task?.label === 'string' ? task.label : 'a tsc task';
+            const label = typeof task?.label === 'string' ? task.label : `a ${tool} task`;
             const projIdx = args.findIndex(a => a === '-p' || a === '--project');
-            if (projIdx !== -1 && args[projIdx + 1]) {
+            if (tool === 'tsc' && 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`);
+                add(task.options.cwd, `.vscode/tasks.json "${label}" runs ${tool} there`);
             }
         }
     }
     catch {
         // No tasks.json, or unparsable — fall through to the filesystem scan
     }
-    // 2. Immediate sub-directories with their own tsconfig.json
+    // 2. Immediate sub-directories with their own build script or 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`);
-            }
+            const kind = subProjectKind(cwd, e.name);
+            if (kind)
+                add(e.name, kind === 'package' ? `${e.name}/package.json has a build script` : `${e.name}/tsconfig.json`);
         }
     }
     catch {
         // Unreadable directory — nothing more to detect
     }
-    return [...found].map(([dir, reason]) => ({ dir, reason }));
+    return [...found.values()];
 }
 /** The sub-projects to wire, honoring `.globalize.json5`: `false` disables the
  *  whole check, an array pins the list instead of detecting it. */
@@ -3270,9 +3317,14 @@ 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')));
+        const listed = [];
+        for (const d of config.subProjects) {
+            const dir = resolveOnDiskCase(cwd, normalizeProjectPath(d)) || d;
+            const kind = subProjectKind(cwd, dir);
+            if (kind)
+                listed.push({ dir, kind, reason: 'listed in .globalize.json5' });
+        }
+        return listed;
     }
     return detectSubProjects(cwd);
 }
@@ -3280,9 +3332,11 @@ function configuredSubProjects(cwd, config) {
 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. */
+/** Append a build step for every sub-project the existing build script misses:
+ *  `npm run build --prefix <dir>` for a sub-package, `tsc -p <dir>` for a plain
+ *  tsconfig. 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)
@@ -3297,12 +3351,18 @@ export async function ensureSubProjectsInBuild(cwd) {
     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));
+    const subs = configuredSubProjects(cwd, config);
+    // A sub-package owns its own import map: give its build script the same
+    // importgen check the root gets, so delegating to it is enough.
+    for (const s of subs) {
+        if (s.kind === 'package')
+            await ensureImportgenInBuild(path.join(cwd, s.dir));
+    }
+    const missing = subs.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(' && ');
+    const newScript = [buildScript, ...missing.map(subProjectBuildCommand)].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.
@@ -3318,7 +3378,7 @@ export async function ensureSubProjectsInBuild(cwd) {
     }
     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`));
+    console.log(colors.green(`✓ Added ${missing.map(subProjectBuildCommand).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
@@ -3327,6 +3387,22 @@ export async function ensureSubProjectsInBuild(cwd) {
 function areSubProjectsUpToDate(cwd, subs) {
     for (const s of subs) {
         const dir = path.join(cwd, s.dir);
+        if (s.kind === 'package') {
+            // Its own build script decides what it emits; judge it the way the
+            // root is judged — sources vs output, plus the import map if it has one.
+            if (!isBuildUpToDate(dir))
+                return false;
+            let subBuild = '';
+            try {
+                subBuild = readPackageJson(dir).scripts?.build ?? '';
+            }
+            catch {
+                return false;
+            }
+            if (scriptRunsImportgen(subBuild) && !isImportMapUpToDate(dir))
+                return false;
+            continue;
+        }
         let co;
         try {
             co = JSON5.parse(fs.readFileSync(path.join(dir, 'tsconfig.json'), 'utf-8')).compilerOptions || {};
@@ -3395,7 +3471,7 @@ export async function buildProject(cwd, opts = {}) {
         // 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 tscParts = ['tsc', ...subs.map(subProjectBuildCommand)];
         const newScript = [...(existingBuild ? [existingBuild] : []), ...tscParts].join(' && ');
         console.log(colors.yellow(`TypeScript project has no "build" script in ${pkg.name || cwd}`));
         for (const s of subs)

package/package.json

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