@gjsify/cli 0.4.44 → 0.5.1

package/lib/commands/foreach.js

@@ -9,9 +9,166 @@
 // matching yarn's interactive flow. Exit code is non-zero if any child
 // process failed; first failure's stderr is forwarded.
 import { spawn } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
 import { cpus } from 'node:os';
 import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { prefixLines } from '../utils/prefixed-output.js';
+// Every child spawned by spawnPrefixed registers here so fail-fast can
+// terminate the whole in-flight set instead of waiting on it. On CI a
+// single failed package used to leave foreach awaiting its still-running
+// siblings — whose nested gjs chains can stall for hours (issue #497).
+const activeChildren = new Set();
+// Grace window between SIGTERM and the SIGKILL escalation.
+const KILL_GRACE_MS = 5_000;
+// Hard deadline for the in-flight set to drain after a fail-fast kill. A
+// killed child whose grandchildren inherit (and keep open) the stdio pipe
+// never emits 'close', so we must not wait on it unboundedly.
+const DRAIN_DEADLINE_MS = 15_000;
+// Read the direct child PIDs of `pid` from /proc/<pid>/task/*/children
+// (Linux, CONFIG_PROC_CHILDREN — standard on every mainstream kernel). When
+// the per-task children files are unavailable, fall back to one full
+// /proc/*/stat scan building a ppid→children map. Both paths use only
+// `node:fs` reads, so they behave identically under Node and GJS
+// (@gjsify/fs) — unlike a process-group kill, which GJS cannot issue
+// (`@gjsify/process.kill` shells out `kill <sig> <pid>` where a negative
+// PID parses as an option, and Gio.Subprocess has no group-signal API).
+function readDirectChildren(pid) {
+    let taskIds;
+    try {
+        taskIds = readdirSync(`/proc/${pid}/task`);
+    }
+    catch {
+        // Process already gone (common) or /proc unavailable.
+        return null;
+    }
+    const kids = [];
+    let readAny = false;
+    for (const tid of taskIds) {
+        try {
+            const data = readFileSync(`/proc/${pid}/task/${tid}/children`, 'utf-8');
+            readAny = true;
+            for (const tok of data.trim().split(/\s+/)) {
+                const n = Number(tok);
+                if (Number.isInteger(n) && n > 0)
+                    kids.push(n);
+            }
+        }
+        catch {
+            // Thread vanished mid-walk, or kernel lacks CONFIG_PROC_CHILDREN.
+        }
+    }
+    return readAny ? kids : null;
+}
+// Fallback: scan every /proc/<pid>/stat once and build ppid → children.
+// O(#processes) small reads — fine for the rare kill path.
+function buildPpidMap() {
+    const map = new Map();
+    let entries = [];
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return map;
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            // comm (field 2) may contain spaces/parens — parse after last ')'.
+            const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const ppid = Number(rest[1]);
+            if (!Number.isInteger(ppid) || ppid <= 0)
+                continue;
+            const siblings = map.get(ppid);
+            if (siblings)
+                siblings.push(pid);
+            else
+                map.set(ppid, [pid]);
+        }
+        catch {
+            // Process exited between readdir and read — fine.
+        }
+    }
+    return map;
+}
+// Snapshot every transitive descendant of `pid`, breadth-first (so
+// reversing the list yields deepest-first order for signalling).
+function collectDescendants(pid) {
+    const result = [];
+    const seen = new Set([pid]);
+    const queue = [pid];
+    let ppidMap = null;
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        let kids = readDirectChildren(cur);
+        if (kids === null) {
+            // children files unreadable — use (and lazily build) the
+            // full-scan fallback for this and subsequent levels.
+            ppidMap ??= buildPpidMap();
+            kids = ppidMap.get(cur) ?? [];
+        }
+        for (const kid of kids) {
+            if (seen.has(kid))
+                continue;
+            seen.add(kid);
+            result.push(kid);
+            queue.push(kid);
+        }
+    }
+    return result;
+}
+// Signal an already-collected descendant set deepest-first, then the direct
+// child itself. Snapshot-then-signal (not signal-while-walking) so killing
+// the parent can't orphan grandchildren before we enumerated them. The
+// snapshot has the usual tree-kill PID-reuse race (a descendant exits and
+// the kernel recycles its PID before our signal lands) — accepted, same as
+// Node's tree-kill packages; the window is milliseconds.
+function signalTree(child, descendants, signal) {
+    for (let i = descendants.length - 1; i >= 0; i--) {
+        try {
+            process.kill(descendants[i], signal);
+        }
+        catch {
+            // already gone — fine
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // already gone — fine
+    }
+}
+function killActiveChildren() {
+    // The direct child is `npm run <script>` — killing only it leaves the
+    // npm-spawned shell → gjs/node build grandchildren alive (observed: an
+    // orphaned gjs bundler at 100% CPU for 19+ min after a fail-fast kill).
+    // So terminate the whole process TREE of each child via a /proc walk.
+    const termSnapshots = new Map();
+    for (const child of activeChildren) {
+        const descendants = child.pid ? collectDescendants(child.pid) : [];
+        termSnapshots.set(child, descendants);
+        signalTree(child, descendants, 'SIGTERM');
+    }
+    const escalate = setTimeout(() => {
+        for (const child of activeChildren) {
+            // Union a FRESH walk (catches processes spawned after the TERM)
+            // with the TERM-time snapshot (catches survivors that were
+            // reparented to init when their parent died on SIGTERM — a
+            // fresh walk from child.pid can no longer see those).
+            const union = new Set(child.pid ? collectDescendants(child.pid) : []);
+            for (const pid of termSnapshots.get(child) ?? [])
+                union.add(pid);
+            signalTree(child, [...union], 'SIGKILL');
+        }
+    }, KILL_GRACE_MS);
+    // Don't let the escalation timer keep the process alive (Node returns a
+    // Timeout with unref(); GJS returns a plain handle without it).
+    escalate.unref?.();
+}
 export const foreachCommand = {
     command: 'foreach [script] [args..]',
     description: 'Run a workspace script across all (or filtered) workspaces. Drop-in for `yarn workspaces foreach`: -A/--all, -p/--parallel, -t/--topological, --include, --exclude, --no-private. Pass --exec to run an arbitrary command instead of a script.',
@@ -101,6 +258,14 @@ export const foreachCommand = {
         // --tag/--access/etc. as its own options.
         let cmd = args.script;
         let cmdArgs = args.args ?? [];
+        if (!exec) {
+            // Script mode silently DROPPED everything after `--` (only --exec
+            // consumed args['--']). Forward them to each child invocation,
+            // matching `yarn workspaces foreach run <script> -- <flags>`.
+            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            if (fromDoubleDash.length > 0)
+                cmdArgs = [...cmdArgs, ...fromDoubleDash];
+        }
         if (exec) {
             // With populate--:true, anything after the literal `--`
             // separator lands in top-level args['--']. yargs DOES NOT
@@ -172,6 +337,10 @@ export const foreachCommand = {
             }
         }
         catch (err) {
+            // Plain --parallel rejects on the FIRST failure (Promise.all) while
+            // sibling children are still running — terminate them so we don't
+            // leave orphans holding the CI step's stdio open.
+            killActiveChildren();
             console.error(err.message);
             process.exit(1);
         }
@@ -220,10 +389,57 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
         remaining.set(ws.name, wsDeps);
     }
     const byName = new Map(workspaces.map((w) => [w.name, w]));
+    const total = workspaces.length;
     const done = new Set();
     let inflight = 0;
+    // Stall observability + self-protection. With prefixed output BUFFERED on
+    // non-tty sinks (flush-on-close), a CI log shows only COMPLETED children —
+    // when the run stalls, nothing identifies who is stuck (issue #497's
+    // 3h45-silence-to-the-cap pattern). So on non-tty (or --verbose) every
+    // start is echoed live on foreach's own stderr, a watchdog WARNS once no
+    // workspace has completed for a while, and after a hard stall budget the
+    // run aborts with the in-flight set named instead of riding the CI job cap.
+    const liveProgress = !process.stdout.isTTY || verbose;
+    const inflightStarts = new Map();
+    const STALL_WARN_MS = 5 * 60_000;
+    const stallAbortMinutes = Number(process.env['GJSIFY_FOREACH_STALL_MINUTES'] ?? '20');
+    const STALL_ABORT_MS = (Number.isFinite(stallAbortMinutes) && stallAbortMinutes > 0 ? stallAbortMinutes : 20) * 60_000;
     return new Promise((resolve, reject) => {
         let error = null;
+        let lastActivity = Date.now();
+        const describeInflight = () => [...inflightStarts.entries()]
+            .map(([n, t]) => `${n} (${Math.round((Date.now() - t) / 1000)}s)`)
+            .join(', ');
+        const failFast = (e) => {
+            // First error wins. KILL the in-flight siblings instead of
+            // waiting for them (yarn waits — but a sibling's nested build
+            // chain can stall for hours on CI, see issue #497), and bound
+            // the drain with a hard deadline in case a killed child's pipe
+            // never closes.
+            if (error)
+                return;
+            error = e;
+            killActiveChildren();
+            const deadline = setTimeout(() => settle(), DRAIN_DEADLINE_MS);
+            deadline.unref?.();
+        };
+        const watchdog = setInterval(() => {
+            const idle = Date.now() - lastActivity;
+            if (idle < STALL_WARN_MS || inflightStarts.size === 0)
+                return;
+            console.error(`[gjsify foreach] WARNING: no workspace completed for ${Math.round(idle / 60_000)}min — in-flight: ${describeInflight()}`);
+            if (idle >= STALL_ABORT_MS) {
+                failFast(new Error(`gjsify foreach: stalled — no workspace completed for ${Math.round(idle / 60_000)}min (override via GJSIFY_FOREACH_STALL_MINUTES); killed in-flight: ${describeInflight()}`));
+            }
+        }, 60_000);
+        watchdog.unref?.();
+        const settle = () => {
+            clearInterval(watchdog);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
         const pump = () => {
             if (error)
                 return;
@@ -236,26 +452,44 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
                 const next = ready.sort()[0];
                 remaining.delete(next);
                 inflight++;
+                inflightStarts.set(next, Date.now());
+                if (liveProgress) {
+                    console.error(`[gjsify foreach] start ${next} (${done.size}/${total} done, ${inflight} in flight)`);
+                }
                 runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose, exec)
                     .then(() => {
-                    inflight--;
                     done.add(next);
-                    if (remaining.size === 0 && inflight === 0) {
-                        resolve();
-                        return;
-                    }
-                    pump();
                 })
                     .catch((e) => {
-                    error = e instanceof Error ? e : new Error(String(e));
-                    // Wait for in-flight tasks to finish (yarn does the
-                    // same — surfaces all errors instead of abruptly
-                    // killing siblings).
-                    if (inflight === 0)
-                        reject(error);
+                    failFast(e instanceof Error ? e : new Error(String(e)));
+                })
+                    .finally(() => {
+                    // Release the slot on BOTH success AND failure. The old
+                    // code decremented `inflight` only in `.then`, so a
+                    // FAILED task left `inflight` stuck above 0 → the
+                    // `inflight === 0` guard never held → the promise never
+                    // settled → hang. Under Node the empty event loop bails
+                    // it out (exiting 0, silently masking the failure);
+                    // under GJS `ensureMainLoop()` keeps the process alive
+                    // forever (the 6-hour CI timeout). Settling here fixes
+                    // both: fail-fast with the real error, on either runtime.
+                    inflight--;
+                    inflightStarts.delete(next);
+                    lastActivity = Date.now();
+                    if (error) {
+                        if (inflight === 0)
+                            settle();
+                    }
+                    else if (remaining.size === 0 && inflight === 0) {
+                        settle();
+                    }
+                    else {
+                        pump();
+                    }
                 });
             }
             if (remaining.size > 0 && inflight === 0 && !error) {
+                clearInterval(watchdog);
                 reject(new Error(`gjsify foreach --topological: stuck — workspaces ${[...remaining.keys()].join(', ')} have unsatisfied deps in the selected set`));
             }
         };
@@ -307,32 +541,36 @@ function spawnPrefixed(cmd, args, cwd, prefix) {
             stdio: prefix ? ['ignore', 'pipe', 'pipe'] : 'inherit',
             env: { ...process.env, ...colorEnv },
         });
+        activeChildren.add(child);
+        // Under GJS, `process.stdout.write` is a BLOCKING `Gio.write_all`.
+        // Writing each prefixed line LIVE during a PARALLEL foreach to a
+        // backpressuring pipe (a CI log collector that drains slowly) stalls
+        // the single GLib main loop on a full pipe → every parallel child's
+        // pipe backs up → their reads stall → the whole run HANGS. (A tty or a
+        // file sink never backpressures, which is why it only bites in CI.)
+        // On a NON-tty sink we therefore BUFFER each child's prefixed output
+        // and flush it as ONE write when that child closes: the child is
+        // already done by then, so its own read can't stall, and concurrent
+        // flushes serialize into brief loop stalls instead of a deadlock. On a
+        // tty (interactive) we keep live line-prefixing for responsive output.
+        const buffered = !process.stdout.isTTY;
+        const flushers = [];
         if (prefix && child.stdout && child.stderr) {
-            prefixLines(child.stdout, process.stdout, prefix);
-            prefixLines(child.stderr, process.stderr, prefix);
+            flushers.push(prefixLines(child.stdout, process.stdout, prefix, buffered));
+            flushers.push(prefixLines(child.stderr, process.stderr, prefix, buffered));
         }
         child.on('close', (code) => {
+            activeChildren.delete(child);
+            for (const flush of flushers)
+                flush();
             if (code === 0)
                 resolve();
             else
                 reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
         });
-        child.on('error', (err) => reject(err));
-    });
-}
-function prefixLines(src, sink, prefix) {
-    let buf = '';
-    src.setEncoding('utf-8');
-    src.on('data', (chunk) => {
-        buf += chunk;
-        let idx;
-        while ((idx = buf.indexOf('\n')) !== -1) {
-            sink.write(prefix + buf.slice(0, idx + 1));
-            buf = buf.slice(idx + 1);
-        }
-    });
-    src.on('end', () => {
-        if (buf.length > 0)
-            sink.write(prefix + buf + '\n');
+        child.on('error', (err) => {
+            activeChildren.delete(child);
+            reject(err);
+        });
     });
 }

package/lib/commands/format.js

@@ -16,7 +16,7 @@
 // trailing-comma all, semicolons always, arrow parens always).
 import { existsSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { OxcNotFoundError, findOxfmtConfig, loadOxfmtTemplate, loadOxlintTemplate, printOxcNotFound, runOxfmt, } from '../utils/oxc-resolve.js';
+import { OxcNotFoundError, findOxfmtConfig, loadOxfmtTemplate, loadOxlintTemplate, printOxcNotFound, runOxfmt, setOxcExitCode, } from '../utils/oxc-resolve.js';
 export const formatCommand = {
     command: 'format [paths..]',
     description: 'Format JS/TS source files via oxfmt (CSS/JSON formatting is not supported).',
@@ -83,12 +83,12 @@ export const formatCommand = {
         oxfmtArgs.push(...paths);
         try {
             const code = await runOxfmt(oxfmtArgs, { cwd, verbose: args.verbose });
-            process.exitCode = code;
+            setOxcExitCode(code);
         }
         catch (err) {
             if (err instanceof OxcNotFoundError) {
                 printOxcNotFound(err);
-                process.exitCode = 1;
+                setOxcExitCode(1);
                 return;
             }
             throw err;

package/lib/commands/install.js

@@ -385,6 +385,17 @@ async function workspaceInstall(cwd, args, signal) {
         }
     }
     console.log(`gjsify install: ${workspaces.length} workspace(s), ${externalSpecs.size} external dep spec(s), ${symlinks.length} workspace symlink(s)`);
+    // Write workspace bin shims EARLY — before the download/extract phase.
+    // The shims are cheap derived artifacts (workspace manifests only), and
+    // the heavy phase that follows can fail or die mid-way (network errors,
+    // timeouts, runtime crashes). Writing them up-front guarantees the
+    // workspace never loses its runner shim (`node_modules/.bin/gjsify`) to
+    // a failed install, and an in-place re-install on an already-materialized
+    // tree refreshes a stale shim even when a later phase aborts. The same
+    // shims are re-written at the end of this function so the GJS-preamble
+    // (GI_TYPELIB_PATH for native prebuilds) reflects the freshly installed
+    // tree — see the final `writeWorkspaceBinShims` call below.
+    writeWorkspaceBinShims(cwd, workspaces);
     // Read top-level package.json's `overrides` (npm-native) or `resolutions`
     // (yarn-native, kept as the existing field name in pre-Phase-D.8 repos).
     // Flat `name → range` entries become global overrides applied to every
@@ -601,18 +612,42 @@ async function workspaceInstall(cwd, args, signal) {
     if (rootHoisted > 0) {
         console.log(`gjsify install: hoisted ${rootHoisted} workspace(s) to root node_modules/`);
     }
-    // Link workspace bins into `node_modules/.bin/`. Without this,
-    // `npm run <script>` (or any `node_modules/.bin`-PATH consumer)
-    // cannot find the `gjsify` binary on a fresh checkout — yarn
-    // creates these shims at install time; we need to match.
-    //
-    // Each workspace's `bin` entry maps `<binName>` → `<relative-target>`.
-    // For GJS-runnable bins, `gjsify.bin` is preferred — its target is the
-    // committed `dist/cli.gjs.mjs` bundle that exists on a fresh checkout,
-    // versus the `bin` field which typically points at `lib/index.js`
-    // (a build artifact that may not yet exist). The shim wraps the
-    // target in a shell script that picks the right interpreter (`gjs -m`
-    // for `.mjs` bundles, `node` for `.js` files).
+    // Re-write workspace bins into `node_modules/.bin/` now that the tree is
+    // fully materialized. The early pass at the top of this function already
+    // guaranteed the shims exist; this final pass refreshes their GJS-preamble
+    // with the native prebuild dirs that only became discoverable after the
+    // install (fresh checkout: `detectNativePackages` finds nothing before the
+    // packages are extracted). Running last also keeps workspace shims
+    // authoritative over any same-named external bin linked by the install
+    // backend (yarn semantics: workspace bins win).
+    const wsBinsCreated = writeWorkspaceBinShims(cwd, workspaces);
+    if (wsBinsCreated > 0) {
+        console.log(`gjsify install: linked ${wsBinsCreated} workspace bin(s) into node_modules/.bin/`);
+    }
+}
+/**
+ * (Re)write the shell shims for every workspace-declared bin into the root
+ * `node_modules/.bin/`. Without this, `npm run <script>` (or any
+ * `node_modules/.bin`-PATH consumer) cannot find the `gjsify` binary on a
+ * fresh checkout — yarn creates these shims at install time; we match.
+ *
+ * Each workspace's `bin` entry maps `<binName>` → `<relative-target>`.
+ * For GJS-runnable bins, `gjsify.bin` is preferred — its target is the
+ * committed `dist/cli.gjs.mjs` bundle that exists on a fresh checkout,
+ * versus the `bin` field which typically points at `lib/index.js`
+ * (a build artifact that may not yet exist). The shim wraps the
+ * target in a shell script that picks the right interpreter (`gjs -m`
+ * for `.mjs` bundles, `node` for `.js` files).
+ *
+ * IDEMPOTENT + UNCONDITIONAL: shims are derived artifacts and are always
+ * regenerated — never skipped because a file already exists, never a
+ * failure because one is missing. `workspaceInstall` calls this twice:
+ * once BEFORE the download/extract phase (so a failed/aborted install can
+ * never leave the workspace without its runner shim, and a stale shim is
+ * refreshed even when a later phase dies) and once after (to pick up
+ * native prebuild dirs that only exist post-extract).
+ */
+function writeWorkspaceBinShims(cwd, workspaces) {
     const wsBinDir = join(cwd, 'node_modules', '.bin');
     // Discover native prebuilds reachable from the workspace cwd so the
     // workspace-local `node_modules/.bin/gjsify` shim sets GI_TYPELIB_PATH /
@@ -652,9 +687,7 @@ async function workspaceInstall(cwd, args, signal) {
             wsBinsCreated++;
         }
     }
-    if (wsBinsCreated > 0) {
-        console.log(`gjsify install: linked ${wsBinsCreated} workspace bin(s) into node_modules/.bin/`);
-    }
+    return wsBinsCreated;
 }
 function extractOverrides(rootManifest) {
     if (!rootManifest)
@@ -741,7 +774,26 @@ function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = []
                 `export GI_TYPELIB_PATH LD_LIBRARY_PATH\n`);
         })();
     if (nodeAbs && gjsAbs) {
-        return `#!/bin/sh\nif [ -f "${nodeAbs}" ]; then\n  exec node "${nodeAbs}" "$@"\nfi\n${gjsPreamble}exec gjs -m "${gjsAbs}" "$@"\n`;
+        // GJS-FIRST: prefer the committed Node-free GJS bundle when `gjs` is on
+        // PATH AND the bundle exists; fall back to the Node entry otherwise (a
+        // Node-only machine, or before the bundle is built). gjsify is
+        // GJS-first but stays fully runnable under Node.
+        //
+        // Safe to default to GJS now that the blockers earlier flip attempts
+        // surfaced are all fixed: css-as-string file://-resolve, `foreach`
+        // fail-fast, the @gjsify/tsc lib-refresh race, native-rolldown
+        // node-target externals — and the make-or-break one, the nested-gjs
+        // build thrash: `gjsify run` now dispatches a single `gjsify <cmd>`
+        // script IN-PROCESS under GJS (see cli-app.ts) instead of spawning yet
+        // another gjs, so the build no longer chains ~5 heavyweight gjs per
+        // package and oversubscribes CI's few cores. Verified: the faithful
+        // `foreach build -tp --jobs 4` over @gjsify/* with a piped stdout
+        // completes in ~83s under GJS (was a multi-hour hang).
+        return (`#!/bin/sh\n` +
+            `if command -v gjs >/dev/null 2>&1 && [ -f "${gjsAbs}" ]; then\n` +
+            `${gjsPreamble}exec gjs -m "${gjsAbs}" "$@"\n` +
+            `fi\n` +
+            `exec node "${nodeAbs}" "$@"\n`);
     }
     if (nodeAbs)
         return `#!/bin/sh\nexec node "${nodeAbs}" "$@"\n`;

package/lib/commands/lint.js

@@ -7,7 +7,7 @@
 // report-only. Pass `--fix` for oxlint's safe-fix mode, or use `gjsify fix`
 // for the combined oxfmt + oxlint --fix surface.
 import { resolve } from 'node:path';
-import { OxcNotFoundError, findOxlintConfig, printOxcNotFound, runOxlint } from '../utils/oxc-resolve.js';
+import { OxcNotFoundError, findOxlintConfig, printOxcNotFound, runOxlint, setOxcExitCode, } from '../utils/oxc-resolve.js';
 export const lintCommand = {
     command: 'lint [paths..]',
     description: 'Run oxlint diagnostics (spawned via its Node launcher to support JS plugins).',
@@ -46,12 +46,12 @@ export const lintCommand = {
         oxlintArgs.push(...paths);
         try {
             const code = await runOxlint(oxlintArgs, { cwd, verbose: args.verbose });
-            process.exitCode = code;
+            setOxcExitCode(code);
         }
         catch (err) {
             if (err instanceof OxcNotFoundError) {
                 printOxcNotFound(err);
-                process.exitCode = 1;
+                setOxcExitCode(1);
                 return;
             }
             throw err;

package/lib/commands/publish.js

@@ -35,7 +35,8 @@
 // in-the-wild publish payloads.
 import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { DEFAULT_REGISTRY, registryFor, buildHeaders } from '@gjsify/npm-registry';
+import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
+import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers.js';
 import { packWorkspace } from './pack.js';
 import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError } from '../utils/npm-oidc.js';
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
@@ -208,18 +209,12 @@ export const publishCommand = {
         const npmrc = await loadNpmrc(wsDir);
         const registry = process.env.npm_config_registry ?? registryFor(packed.name, npmrc) ?? DEFAULT_REGISTRY;
         const registryClean = registry.endsWith('/') ? registry.slice(0, -1) : registry;
-        // npm-package-arg's escapedName convention for scoped packages:
-        // `@${scope-without-leading-@}%2f${name}` (lowercase %2f, literal @).
-        // Unscoped: `encodeURIComponent(name)`. Match it exactly — the
-        // npm registry is picky about the publish PUT URL shape.
-        const escapedName = packed.name.startsWith('@')
-            ? (() => {
-                const slash = packed.name.indexOf('/');
-                const scope = packed.name.slice(1, slash);
-                const base = packed.name.slice(slash + 1);
-                return `@${encodeURIComponent(scope)}%2f${encodeURIComponent(base)}`;
-            })()
-            : encodeURIComponent(packed.name);
+        // npm-package-arg's escapedName convention (npa.js:188):
+        // `name.replace('/', '%2f')` — scoped `@scope/name` → `@scope%2fname`
+        // (literal @, lowercase %2f, segments NOT otherwise re-encoded);
+        // unscoped names pass through. Match it exactly — the npm registry is
+        // picky about the publish PUT URL shape.
+        const escapedName = escapePackageName(packed.name);
         const url = `${registryClean}/${escapedName}`;
         // npm publish convention: the dist.tarball URL + _attachments key both
         // use the UNSCOPED basename — `cli-0.4.5.tgz`, not
@@ -241,14 +236,15 @@ export const publishCommand = {
             packed: { ...packed, wireFilename },
             provenance,
         });
-        const headers = buildHeaders(url, { npmrc });
-        headers['content-type'] = 'application/json';
-        headers['accept'] = '*/*';
-        // 2FA OTP — sent as the `npm-otp` header (npm-registry-fetch convention,
-        // verified in refs/npm-cli/node_modules/npm-registry-fetch/lib/index.js
-        // line ~243: `if (opts.otp) headers['npm-otp'] = opts.otp`).
-        if (otp)
-            headers['npm-otp'] = otp;
+        // Build the publish-PUT headers to match what `npm publish` sends via
+        // npm-registry-fetch's `getHeaders` — critically `npm-command: publish`
+        // (the routing header npm's create-package frontdoor keys on; without it
+        // a first-publish of a brand-new scoped package returns a bare 404
+        // `Not Found`), plus `npm-auth-type` (legacy when --otp, else web), a
+        // real `user-agent`, and `npm-otp` when an OTP is supplied. See
+        // `utils/publish-headers.ts` for the field-by-field refs/npm-cli
+        // evidence.
+        const headers = buildPublishHeaders(url, { npmrc, otp });
         // Trusted Publishing path. `--trusted` forces OIDC (errors if env
         // vars are missing); the default `undefined` triggers auto-detect:
         // OIDC is used iff GitHub OIDC env vars are present AND no
@@ -301,7 +297,8 @@ export const publishCommand = {
                     handleOidcFailure(err, packed.name, args.json === true);
                     process.exit(1);
                 }
-                // Auto-detect: fall back to whatever buildHeaders found.
+                // Auto-detect: fall back to the npmrc token auth that
+                // buildPublishHeaders already resolved into `headers`.
                 if (verbose) {
                     const msg = err instanceof Error ? err.message : String(err);
                     console.error(`gjsify publish: OIDC auto-detect failed (${msg}) — falling back to token auth`);
@@ -587,9 +584,25 @@ function handleOidcFailure(err, packageName, asJson) {
             ? `npm rejected the OIDC exchange (${err.status}) — check that ${packageName} has a Trusted Publisher configured at https://www.npmjs.com/package/${encodeURIComponent(packageName)}/access pointing at this workflow.`
             : err.message;
         if (asJson)
-            process.stdout.write(`${JSON.stringify({ ok: false, name: packageName, error: 'oidc-exchange', status: err.status, body: err.body, message: err.message })}\n`);
-        else
+            process.stdout.write(`${JSON.stringify({ ok: false, name: packageName, error: 'oidc-exchange', status: err.status, body: err.body, claims: err.claims, message: err.message })}\n`);
+        else {
             process.stderr.write(`✗ ${packageName}: ${friendly}\n`);
+            // Diagnostics: the raw npm body often names the rejected claim, and
+            // the decoded JWT claims are exactly what the TP config must match
+            // (repository + workflow_ref + environment). Print both so a 401 is
+            // actionable without re-running in --json/--verbose mode.
+            if (err.body)
+                process.stderr.write(`    ↳ npm said: ${err.body.slice(0, 300)}\n`);
+            if (err.claims) {
+                const c = err.claims;
+                const shown = ['aud', 'iss', 'repository', 'repository_owner', 'workflow_ref', 'job_workflow_ref', 'ref', 'environment', 'sub']
+                    .filter((k) => c[k] !== undefined)
+                    .map((k) => `${k}=${JSON.stringify(c[k])}`)
+                    .join(', ');
+                if (shown)
+                    process.stderr.write(`    ↳ JWT claims npm received: ${shown}\n`);
+            }
+        }
         return;
     }
     const msg = err instanceof Error ? err.message : String(err);