@gjsify/cli 0.4.14 → 0.4.16

package/lib/actions/barrels-generate.d.ts

@@ -0,0 +1,31 @@
+export type BarrelExtension = 'js' | 'ts' | 'none';
+export interface BarrelsArgs {
+    /** Directories to scan. Each gets an `index.ts` re-exporting its sibling source files. */
+    paths: string[];
+    /** Import-specifier extension. `js`/`ts`/`none`. */
+    extension: BarrelExtension;
+    /** Resolve `paths` against this directory. Default: `process.cwd()`. */
+    baseDir: string;
+    /** Skip files whose names match any regex. */
+    exclude: RegExp[];
+    /** Header comment prepended to every generated file. */
+    header: string;
+    /** Omit trailing `;` on each export line. */
+    noSemicolon: boolean;
+    /** Use `'` quotes (default). When false, uses `"`. */
+    singleQuotes: boolean;
+    /** Report drift without writing. Returns drift count from generator. */
+    check: boolean;
+    /** Log each file scanned + written. */
+    verbose: boolean;
+}
+export declare const DEFAULT_BARRELS_HEADER = "// Auto-generated by `gjsify barrels` \u2014 do not edit by hand.";
+export declare const DEFAULT_BARRELS_EXCLUDES: readonly string[];
+/**
+ * Regenerate `index.ts` in every directory in `args.paths`.
+ *
+ * Returns the number of files that drifted from the canonical output —
+ * always 0 when `check` is false (drift is rewritten in-place); non-zero
+ * under `check: true` signals CI failure.
+ */
+export declare function generateBarrels(args: BarrelsArgs): Promise<number>;

package/lib/actions/barrels-generate.js

@@ -0,0 +1,78 @@
+// `gjsify barrels` action — regenerate `index.ts` barrel files for one or
+// more directories. Pure async generator, decoupled from yargs so it can
+// be unit-tested in isolation.
+//
+// Adapted from beabee-communityrm/monorepo apps/dev-cli's `generate-index`
+// action (refs/dev-cli — not vendored here): same separation of action vs.
+// command module, same `types/`-dir auto-detection that emits
+// `export type *`, same `export {};` fallback for empty directories,
+// same sorted-output principle. Rewritten for gjsify's yargs CommandModule
+// and `@gjsify/unit` test framework; no external deps. Replaces
+// `barrelsby` (unmaintained since 2022) at consumer sites.
+//
+// Original: Copyright (c) Beabee Community Repo contributors. AGPL-3.0.
+// Reimplemented for gjsify under the project's MIT license.
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+export const DEFAULT_BARRELS_HEADER = '// Auto-generated by `gjsify barrels` — do not edit by hand.';
+export const DEFAULT_BARRELS_EXCLUDES = [
+    '\\.test\\.',
+    '\\.spec\\.',
+    '\\.test-data\\.',
+];
+const SOURCE_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+/**
+ * Regenerate `index.ts` in every directory in `args.paths`.
+ *
+ * Returns the number of files that drifted from the canonical output —
+ * always 0 when `check` is false (drift is rewritten in-place); non-zero
+ * under `check: true` signals CI failure.
+ */
+export async function generateBarrels(args) {
+    const quote = args.singleQuotes ? "'" : '"';
+    const semicolon = args.noSemicolon ? '' : ';';
+    const extSuffix = args.extension === 'none' ? '' : `.${args.extension}`;
+    let drift = 0;
+    for (const p of args.paths) {
+        const dir = resolve(args.baseDir, p);
+        const isTypesDir = basename(dir) === 'types';
+        let entries;
+        try {
+            entries = (await readdir(dir, { withFileTypes: true }))
+                .filter((e) => e.isFile())
+                .filter((e) => SOURCE_FILE_RE.test(e.name))
+                .filter((e) => e.name !== 'index.ts')
+                .filter((e) => !args.exclude.some((r) => r.test(e.name)))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (err) {
+            if (args.verbose)
+                console.error(`[gjsify barrels] skip ${dir}: ${err.message}`);
+            continue;
+        }
+        const lines = entries.map((e) => {
+            const stem = basename(e.name, extname(e.name));
+            const keyword = isTypesDir ? 'export type *' : 'export *';
+            return `${keyword} from ${quote}./${stem}${extSuffix}${quote}${semicolon}`;
+        });
+        const body = lines.length ? `${lines.join('\n')}\n` : 'export {};\n';
+        const out = `${args.header}\n\n${body}`;
+        const indexPath = join(dir, 'index.ts');
+        const previous = await readFile(indexPath, 'utf-8').catch(() => '');
+        if (previous === out) {
+            if (args.verbose)
+                console.log(`[gjsify barrels] up-to-date: ${indexPath}`);
+            continue;
+        }
+        if (args.check) {
+            console.error(`[gjsify barrels] drift: ${indexPath}`);
+            drift++;
+        }
+        else {
+            await writeFile(indexPath, out, 'utf-8');
+            if (args.verbose)
+                console.log(`[gjsify barrels] wrote: ${indexPath}`);
+        }
+    }
+    return drift;
+}

package/lib/commands/barrels.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from '../types/index.js';
+import { type BarrelExtension } from '../actions/barrels-generate.js';
+interface BarrelsOptions {
+    paths?: string[];
+    ext?: BarrelExtension;
+    baseDir?: string;
+    exclude?: string[];
+    header?: string;
+    semicolon?: boolean;
+    singleQuotes?: boolean;
+    check?: boolean;
+    verbose?: boolean;
+}
+export declare const barrelsCommand: Command<unknown, BarrelsOptions>;
+export {};

package/lib/commands/barrels.js

@@ -0,0 +1,103 @@
+// `gjsify barrels` — regenerate `index.ts` barrel files for a set of
+// directories. Drop-in replacement for `barrelsby` (unmaintained 2022+).
+//
+// Examples:
+//   gjsify barrels src/systems src/components       # regenerate two barrels
+//   gjsify barrels --check src/types                # CI guard — exit 1 on drift
+//   gjsify barrels --ext js src/utils               # NodeNext-style import-extensions
+//
+// Conventions:
+//   - A directory literally named `types/` emits `export type *` (type-only
+//     re-export) — avoids dragging value imports through type-only barrels.
+//   - An empty directory yields `export {};` so TypeScript still parses the
+//     file as a module.
+//   - Output is sorted by file name (locale-compare) — deterministic diffs.
+//   - `--check` exits non-zero on drift without writing (pre-commit / CI use).
+import { DEFAULT_BARRELS_EXCLUDES, DEFAULT_BARRELS_HEADER, generateBarrels, } from '../actions/barrels-generate.js';
+export const barrelsCommand = {
+    command: 'barrels [paths..]',
+    description: 'Regenerate `index.ts` barrel files for the given directories. Drop-in replacement for `barrelsby`.',
+    builder: (yargs) => {
+        return yargs
+            .positional('paths', {
+            description: 'Directories whose `index.ts` to (re)generate. May also be passed via `--paths`.',
+            type: 'string',
+            array: true,
+        })
+            .option('paths', {
+            alias: 'p',
+            description: 'Alternative to positional — repeatable list of directories.',
+            type: 'string',
+            array: true,
+        })
+            .option('ext', {
+            description: 'Import-specifier extension. Default: `none` (bundler-mode resolution).',
+            type: 'string',
+            choices: ['js', 'ts', 'none'],
+            default: 'none',
+        })
+            .option('base-dir', {
+            alias: 'b',
+            description: 'Resolve `paths` against this directory. Default: cwd.',
+            type: 'string',
+        })
+            .option('exclude', {
+            description: 'Regex(es) of file names to skip. Repeatable. Defaults: `\\.test\\.`, `\\.spec\\.`, `\\.test-data\\.`.',
+            type: 'string',
+            array: true,
+        })
+            .option('header', {
+            description: 'Header comment prepended to every generated file.',
+            type: 'string',
+        })
+            .option('semicolon', {
+            description: 'Emit trailing `;` on each export line. Negate with `--no-semicolon`. Default: omitted.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('single-quotes', {
+            description: 'Use `\'` for import specifiers. Default: true. Pass `--no-single-quotes` for `"`.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('check', {
+            description: 'Report drift without modifying files; exit non-zero if any barrel is stale.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            description: 'Log each file scanned + written.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        // Both positional (`gjsify barrels src/a src/b`) and the named option
+        // (`--paths src/a --paths src/b`) land in `args.paths` since they share
+        // the same name. Yargs concatenates when both are present.
+        const paths = Array.from(new Set((args.paths ?? []).filter(Boolean)));
+        if (paths.length === 0) {
+            console.error('[gjsify barrels] no paths provided. Pass directories as positional arguments or via --paths.');
+            process.exitCode = 1;
+            return;
+        }
+        const excludePatterns = args.exclude?.length
+            ? args.exclude
+            : [...DEFAULT_BARRELS_EXCLUDES];
+        const drift = await generateBarrels({
+            paths,
+            extension: args.ext ?? 'none',
+            baseDir: args.baseDir ?? process.cwd(),
+            exclude: excludePatterns.map((src) => new RegExp(src)),
+            header: args.header ?? DEFAULT_BARRELS_HEADER,
+            noSemicolon: args.semicolon === false || args.semicolon === undefined,
+            singleQuotes: args.singleQuotes !== false,
+            check: args.check ?? false,
+            verbose: args.verbose ?? false,
+        });
+        if (args.check && drift > 0) {
+            console.error(`[gjsify barrels] ${drift} barrel file(s) drifted. Run without --check to fix.`);
+            process.exitCode = 1;
+        }
+    },
+};

package/lib/commands/index.d.ts

@@ -22,3 +22,4 @@ export * from './format.js';
 export * from './lint.js';
 export * from './fix.js';
 export * from './upgrade.js';
+export * from './barrels.js';

package/lib/commands/index.js

@@ -22,3 +22,4 @@ export * from './format.js';
 export * from './lint.js';
 export * from './fix.js';
 export * from './upgrade.js';
+export * from './barrels.js';

package/lib/commands/install.js

@@ -11,9 +11,12 @@
 // subprocess flow (useful as escape-hatch for projects that hit a
 // missing native-backend feature).
 //
-// Workspace-aware install (`gjsify install` in a monorepo root with a
-// `"workspaces"` field) is Phase D.3 — for now we detect and surface a
-// clear error pointing at the in-progress work.
+// Workspace install (`gjsify install` in a monorepo root with a
+// `"workspaces"` field) hoists every workspace's externals into the root
+// `node_modules/` and symlinks `workspace:*` / `workspace:^` / `workspace:~`
+// refs to their target source. Open follow-ups (see STATUS.md "Open TODOs"):
+// per-workspace dedup of conflicting transitive version ranges (first-match
+// wins today).
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -115,7 +118,7 @@ async function projectInstallNative(args) {
             'not PnP-aware yet. Use `yarn install` or set ' +
             'GJSIFY_INSTALL_BACKEND=npm.');
     }
-    // Workspace install (no args, root pkg.json has `workspaces`) — Phase D.3.
+    // Workspace install (no args, root pkg.json has `workspaces`).
     // Project-local `gjsify install <pkg>` inside a workspace child still
     // goes through the single-package code path below (this branch only
     // fires for the root no-args case, which is the `yarn install`
@@ -199,8 +202,7 @@ function syncLockfileRequested(cwd, specs) {
     }
 }
 /**
- * Phase D.3 — workspace-aware install. Mirrors what `yarn install` does
- * at a monorepo root:
+ * Workspace-aware install. Mirrors what `yarn install` does at a monorepo root:
  *   1. Discover every workspace under the root.
  *   2. Aggregate the union of their external (non-`workspace:`) deps.
  *   3. Run the native install backend ONCE at the root prefix so all
@@ -211,9 +213,9 @@ function syncLockfileRequested(cwd, specs) {
  *      directory into the requesting workspace's `node_modules/<dep>`
  *      so `import '@gjsify/utils'` resolves to the local source.
  *
- * Hoisting strategy is intentionally minimal — D.3 ships the working
- * baseline; per-workspace dedup + nested `node_modules/` for version
- * conflicts are tracked as a follow-up in STATUS.md "Open TODOs".
+ * Hoisting strategy is intentionally minimal — per-workspace dedup +
+ * nested `node_modules/` for version conflicts are tracked as a follow-up
+ * in STATUS.md "Open TODOs".
  */
 async function workspaceInstall(cwd, args) {
     const workspaces = discoverWorkspaces(cwd, { includeRoot: true });

package/lib/commands/publish.d.ts

@@ -7,6 +7,8 @@ interface PublishOptions {
     provenance?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
+    trusted?: boolean | 'auto';
+    'check-trusted'?: boolean;
 }
 export declare const publishCommand: Command<any, PublishOptions>;
 export {};

package/lib/commands/publish.js

@@ -37,6 +37,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { DEFAULT_REGISTRY, parseNpmrc, registryFor, buildHeaders, } from '@gjsify/npm-registry';
 import { packWorkspace } from './pack.js';
+import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError, } from '../utils/npm-oidc.js';
 export const publishCommand = {
     command: 'publish [path]',
     description: 'Pack + upload the workspace at <path> (default: cwd) to its npm registry. Drop-in for `npm publish` with workspace:^ rewrite handled automatically.',
@@ -70,6 +71,19 @@ export const publishCommand = {
         description: 'Emit publish metadata as JSON on stdout.',
         type: 'boolean',
         default: false,
+    })
+        .option('trusted', {
+        description: 'Authenticate via npm Trusted Publishing (OIDC): exchange the GitHub Actions id-token for a short-lived npm token. ' +
+            'Pass `--trusted` to force this mode (errors if env vars missing). ' +
+            'Omit to auto-detect: OIDC is used iff `ACTIONS_ID_TOKEN_REQUEST_URL`+`_TOKEN` are set AND no `_authToken` is present in the resolved npmrc; otherwise the long-lived token path is used. ' +
+            'Requires the calling workflow to declare `permissions: id-token: write` AND the target package to have a Trusted Publisher configured on npmjs.com.',
+        type: 'boolean',
+        default: undefined,
+    })
+        .option('check-trusted', {
+        description: 'Diagnostic mode: perform the OIDC id-token request + npm token exchange, report success/failure, then exit WITHOUT publishing. Useful as a bulk-verifier (e.g. via `gjsify foreach publish --check-trusted`) to confirm Trusted Publisher config across many packages.',
+        type: 'boolean',
+        default: false,
     }),
     handler: async (args) => {
         const wsDir = resolve(args.path ?? process.cwd());
@@ -78,9 +92,56 @@ export const publishCommand = {
         const tolerate = args['tolerate-republish'] === true;
         const provenance = args.provenance === true;
         const dryRun = args['dry-run'] === true;
+        const checkTrustedOnly = args['check-trusted'] === true;
+        const trustedFlag = args.trusted;
+        const verbose = Boolean(process.env.GJSIFY_PUBLISH_DEBUG);
         if (provenance) {
             console.warn('gjsify publish: --provenance recorded but not signed (no sigstore integration yet).');
         }
+        // `--check-trusted` short-circuits the entire pack + publish flow.
+        // Reports the OIDC exchange result for the workspace's package and
+        // exits 0 either way — by design, so `gjsify foreach publish
+        // --check-trusted` walks every workspace without bailing on the
+        // first misconfigured one. CI can grep `^✗ ` (or parse `--json`
+        // entries with `ok: false`) to surface failures.
+        if (checkTrustedOnly) {
+            const rawPkgPath = join(wsDir, 'package.json');
+            const rawPkg = JSON.parse(readFileSync(rawPkgPath, 'utf-8'));
+            if (typeof rawPkg.name !== 'string') {
+                process.stderr.write(`gjsify publish --check-trusted: ${rawPkgPath} has no \`name\` field\n`);
+                process.exit(2);
+            }
+            if (rawPkg.private === true) {
+                const out = { ok: true, action: 'check-trusted', name: rawPkg.name, skipped: 'private' };
+                if (args.json)
+                    process.stdout.write(`${JSON.stringify(out)}\n`);
+                else
+                    process.stdout.write(`- ${rawPkg.name}: skipped (private package)\n`);
+                return;
+            }
+            const npmrcCheck = await loadNpmrc(wsDir);
+            const registry = process.env.npm_config_registry ?? registryFor(rawPkg.name, npmrcCheck) ?? DEFAULT_REGISTRY;
+            try {
+                await getNpmTrustedToken({
+                    packageName: rawPkg.name,
+                    registry,
+                    log: verbose ? (m) => console.error(m) : undefined,
+                });
+                const out = { ok: true, action: 'check-trusted', name: rawPkg.name, registry };
+                if (args.json)
+                    process.stdout.write(`${JSON.stringify(out)}\n`);
+                else
+                    process.stdout.write(`✓ ${rawPkg.name}: trusted publisher OK\n`);
+                return;
+            }
+            catch (err) {
+                handleOidcFailure(err, rawPkg.name, args.json === true);
+                // Report-mode: exit 0 so `gjsify foreach` keeps walking. The
+                // `✗ <name>: <reason>` (or JSON `ok:false`) line is the
+                // failure signal for CI to grep / parse.
+                return;
+            }
+        }
         // 1. Pack the workspace (rewrites workspace:^, computes integrity)
         const packOpts = { dryRun: true };
         const packed = await packWorkspace(wsDir, packOpts);
@@ -159,10 +220,45 @@ export const publishCommand = {
         const headers = buildHeaders(url, { npmrc });
         headers['content-type'] = 'application/json';
         headers['accept'] = '*/*';
-        if (process.env.GJSIFY_PUBLISH_DEBUG) {
+        // 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
+        // `NODE_AUTH_TOKEN` is set. With `NODE_AUTH_TOKEN` set the user has
+        // explicitly opted into token auth, so we don't shadow their choice.
+        const wantTrusted = trustedFlag === true ||
+            (trustedFlag === undefined && hasGithubOidcEnv() && !process.env.NODE_AUTH_TOKEN);
+        let authMode = 'token';
+        if (wantTrusted) {
+            try {
+                const { token: oidcToken, audience } = await getNpmTrustedToken({
+                    packageName: packed.name,
+                    registry,
+                    log: verbose ? (m) => console.error(m) : undefined,
+                });
+                headers['authorization'] = `Bearer ${oidcToken}`;
+                authMode = 'oidc';
+                if (verbose) {
+                    console.error(`gjsify publish: OIDC token obtained (audience=${audience})`);
+                }
+            }
+            catch (err) {
+                if (trustedFlag === true) {
+                    // Explicit --trusted: bail with a clear error.
+                    handleOidcFailure(err, packed.name, args.json === true);
+                    process.exit(1);
+                }
+                // Auto-detect: fall back to whatever buildHeaders found.
+                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`);
+                }
+            }
+        }
+        if (verbose) {
             console.error(`gjsify publish: PUT ${url} (${packed.name}@${packed.version})`);
+            console.error(`  auth-mode:     ${authMode}`);
             console.error(`  authorization: ${headers['authorization'] ? '(set)' : '(none)'}`);
-            console.error(`  payload size: ${JSON.stringify(payload).length} bytes`);
+            console.error(`  payload size:  ${JSON.stringify(payload).length} bytes`);
         }
         const res = await fetch(url, {
             method: 'PUT',
@@ -317,3 +413,28 @@ function base64Encode(bytes) {
     }
     return btoa(str);
 }
+function handleOidcFailure(err, packageName, asJson) {
+    if (err instanceof OidcUnavailableError) {
+        const msg = `gjsify publish: OIDC not available — ${err.message}`;
+        if (asJson)
+            process.stdout.write(`${JSON.stringify({ ok: false, name: packageName, error: 'oidc-unavailable', reason: err.reason, message: err.message })}\n`);
+        else
+            process.stderr.write(`${msg}\n`);
+        return;
+    }
+    if (err instanceof OidcExchangeError) {
+        const friendly = err.status === 401 || err.status === 403
+            ? `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.stderr.write(`✗ ${packageName}: ${friendly}\n`);
+        return;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    if (asJson)
+        process.stdout.write(`${JSON.stringify({ ok: false, name: packageName, error: 'unknown', message: msg })}\n`);
+    else
+        process.stderr.write(`✗ ${packageName}: ${msg}\n`);
+}

package/lib/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 // `parseAsync()` instead of `.argv` so the top-level await keeps the
 // process alive until command handlers complete. Under Node this is
@@ -35,6 +35,7 @@ await yargs(hideBin(process.argv))
     .command(format.command, format.description, format.builder, format.handler)
     .command(lint.command, lint.description, lint.builder, lint.handler)
     .command(fix.command, fix.description, fix.builder, fix.handler)
+    .command(barrels.command, barrels.description, barrels.builder, barrels.handler)
     .demandCommand(1)
     .help()
     .parseAsync();

package/lib/utils/install-backend-native.js

@@ -71,6 +71,11 @@ export async function installPackagesNative(opts) {
     // behavior). Sub-deps are not included.
     return topLevelResolutions(opts.specs, nodes);
 }
+function errMsg(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
 function topLevelResolutions(specs, nodes) {
     // Top-level installs live at `node_modules/<name>` (no nesting). Build
     // a name → root-node lookup limited to the top-level set.
@@ -131,7 +136,12 @@ async function resolveDeps(specs, npmrc, log, overrides) {
         const cached = packumentCache.get(name);
         if (cached)
             return cached;
-        const fresh = fetchPackument(name, { npmrc });
+        const fresh = fetchPackument(name, {
+            npmrc,
+            onRetry: ({ attempt, error, delayMs }) => {
+                log("packument %s: retry %d after %dms (%s)", name, attempt, delayMs, errMsg(error));
+            },
+        });
         packumentCache.set(name, fresh);
         return fresh;
     };
@@ -455,6 +465,9 @@ async function extractOne(node, prefix, npmrc, log) {
     const bytes = await fetchTarball(node.tarballUrl, {
         npmrc,
         integrity: node.integrity,
+        onRetry: ({ attempt, error, delayMs }) => {
+            log("tarball %s@%s: retry %d after %dms (%s)", node.name, node.version, attempt, delayMs, errMsg(error));
+        },
     });
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });

package/lib/utils/npm-oidc.d.ts

@@ -0,0 +1,53 @@
+interface OidcExchangeOptions {
+    /** Full package name including scope, e.g. `@gjsify/cli`. */
+    packageName: string;
+    /** Registry URL, e.g. `https://registry.npmjs.org`. */
+    registry: string;
+    /** Optional verbose logger — receives single-line strings. */
+    log?: (msg: string) => void;
+}
+export interface OidcExchangeResult {
+    /** Short-lived npm token (`Authorization: Bearer <token>`-compatible). */
+    token: string;
+    /** Audience used for the GitHub OIDC token request. */
+    audience: string;
+}
+export declare class OidcUnavailableError extends Error {
+    readonly reason: 'no-env' | 'fetch-id-token' | 'no-id-token';
+    constructor(message: string, reason: 'no-env' | 'fetch-id-token' | 'no-id-token');
+}
+export declare class OidcExchangeError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly packageName: string;
+    constructor(message: string, status: number, body: string, packageName: string);
+}
+/**
+ * Probe whether OIDC publishing is available in the current process —
+ * cheap env-var check, no network access. Used by `gjsify publish` to
+ * decide between OIDC and token-based auth in auto-detect mode.
+ */
+export declare function hasGithubOidcEnv(): boolean;
+/**
+ * Request a GitHub Actions OIDC ID token for the given audience.
+ * Throws `OidcUnavailableError` when the required env vars are missing
+ * (caller can fall back to token auth) or when GitHub rejects the request.
+ */
+export declare function fetchGithubOidcToken(audience: string, log?: (msg: string) => void): Promise<string>;
+/**
+ * Exchange a GitHub OIDC JWT for a short-lived npm publish token at
+ * `/-/npm/v1/oidc/token/exchange/package/<escaped-name>`. The npm
+ * registry validates the JWT against the package's Trusted Publisher
+ * config — if no Trusted Publisher is configured, or the JWT comes from
+ * a repo/workflow that doesn't match, the exchange returns a 4xx with
+ * a descriptive body which we propagate as `OidcExchangeError`.
+ */
+export declare function exchangeOidcForNpmToken(args: OidcExchangeOptions & {
+    idToken: string;
+}): Promise<string>;
+/**
+ * End-to-end: probe env → fetch id-token → exchange for npm token.
+ * One-shot convenience for `gjsify publish` and the verification command.
+ */
+export declare function getNpmTrustedToken(opts: OidcExchangeOptions): Promise<OidcExchangeResult>;
+export {};