@gjsify/cli 0.51.1 → 0.53.0

package/lib/commands/publish.js

@@ -48,7 +48,8 @@ import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers
 import { packWorkspace } from './pack.js';
 import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError } from '../utils/npm-oidc.js';
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
-import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, verifyPublishedVersion, } from '../utils/publish-readback.js';
+import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, probePackageName, verifyPublishedVersion, } from '../utils/publish-readback.js';
+import { collectWorkspacePins, REQUIRED_BLOCK } from '../utils/publish-pins.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -81,7 +82,7 @@ export const publishCommand = {
         default: false,
     })
         .option('verify-timeout', {
-        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path.',
+        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path; the success line then reads `UNVERIFIED` and says so, because a publish nothing checked must never look like one that was checked.',
         type: 'number',
         default: DEFAULT_VERIFY_BUDGET_MS / 1000,
     })
@@ -305,6 +306,55 @@ export async function publishWorkspace(input) {
     // Base headers (npm-command: publish routing header etc.). The OTP is added
     // per-PUT by `doPut` so `withOtpRetry` can retry with different codes.
     const headers = buildPublishHeaders(url, { npmrc });
+    // 5. Do not PUT a tarball whose required intra-repo pins point at a name
+    //    this registry does not have (#1713).
+    //
+    //    The question is PRESENCE OF THE NAME, never a version, and that is what
+    //    makes it safe to gate on: a version is eventually consistent for
+    //    minutes after its own 2xx, so a version gate would manufacture a red on
+    //    a publish that worked. A name does not move once its first version
+    //    lands. `unknown` — a 5xx, a timeout, an auth wall — is not `absent` and
+    //    never blocks.
+    const assumePresent = new Set(input.assumePresent ?? []);
+    const pins = collectWorkspacePins(pkg, rewrittenPkg).filter((pin) => !assumePresent.has(pin.name));
+    if (pins.length > 0) {
+        const probed = await Promise.all(pins.map(async (pin) => ({
+            pin,
+            presence: await probePackageName({
+                registry,
+                name: pin.name,
+                authorization: headers['authorization'],
+            }),
+        })));
+        const missing = [];
+        for (const { pin, presence } of probed) {
+            if (presence.state === 'present')
+                continue;
+            const where = `${pin.block}.${pin.name}@${pin.spec}`;
+            if (presence.state === 'unknown') {
+                console.error(`gjsify publish: could not establish whether ${pin.name} exists (${presence.detail}) — not blocking on ${where}`);
+                continue;
+            }
+            if (pin.block !== REQUIRED_BLOCK) {
+                // npm and pnpm skip an unresolvable optional edge in silence;
+                // Yarn refuses the whole install. Loud, not fatal.
+                console.error(`gjsify publish: ${where} names a package ${registry} does not have — npm installs around it, Yarn (\`YN0035\`) does not`);
+                continue;
+            }
+            missing.push(pin);
+        }
+        if (missing.length > 0) {
+            return {
+                ok: tolerateUntrustedNew,
+                action: 'blocked-missing-dependency',
+                name: packed.name,
+                version: packed.version,
+                registry,
+                tolerated: tolerateUntrustedNew,
+                missing,
+            };
+        }
+    }
     // Trusted Publishing (OIDC) path — `--trusted` forces it, `undefined`
     // auto-detects from the GitHub OIDC env. Unused by `gjsify onboard` (local
     // token auth), preserved verbatim for `gjsify publish` in CI.
@@ -414,7 +464,7 @@ export async function publishWorkspace(input) {
         //
         //   NOT CONFIRMED YET — the other 19. Here the read-back waits out
         //   npm's own write queue, and those residual lags SUM TO 2554 s: a
-        //   sweep that waited them all out with the 300 s default would have
+        //   sweep that waited them all out under the fatal default would have
         //   added ~43 min to that 33 min job. That single number decides the
         //   shape below.
         //
@@ -438,7 +488,7 @@ export async function publishWorkspace(input) {
         //
         // Hence BOTH, split along that cost. The read-back runs per package
         // everywhere and is FATAL by default — that is what turns the
-        // incident's green single-package job red, for up to 300 s of
+        // incident's green single-package job red, for up to 600 s of
         // patience on a job that otherwise ran 59 s. The
         // 199-package sweep passes `--verify-defer --verify-timeout 5`: it
         // still CONFIRMS nine packages in ten and still names the suspect
@@ -458,7 +508,7 @@ export async function publishWorkspace(input) {
             // decoration: it is the only client-side measurement of when a
             // version became RESOLVABLE, as against `time[version]`, which is
             // when the registry recorded the write. The two are assumed equal by
-            // the 4.2-minute figure and the 300 s window, and nothing had ever
+            // the 4.2-minute figure and the default window, and nothing had ever
             // measured the gap. The pre-registered comparison — and what each
             // outcome would change — is in #1509's description; this line, under
             // GJSIFY_PUBLISH_DEBUG (which release.yml sets), is its input. Note
@@ -534,6 +584,7 @@ export async function publishWorkspace(input) {
             name: packed.name,
             version: packed.version,
             status: res.status,
+            registry: registryClean,
             readback,
         };
     }
@@ -568,9 +619,68 @@ export async function publishWorkspace(input) {
  * re-checks the same set afterwards. It is policy, so it lives here and not in
  * {@link publishWorkspace}, which stays a pure fact-finder.
  */
+/**
+ * What the success line SAYS it established — the half of the read-back that
+ * was missing.
+ *
+ * AN INSTRUMENT STATES WHAT IT MEASURED, and `+ name@version` states nothing.
+ * It is the identical string from a CLI that polled the registry and read a
+ * tarball back, from one run with `--verify-timeout 0`, and from any
+ * `@gjsify/cli` older than v0.47.0, which had no read-back at all. That is not a
+ * hypothetical: ts-for-gir's v5.1.0 release (run 34899018849) printed twelve
+ * `+ <name>@5.1.0` lines with `GJSIFY_PUBLISH_DEBUG=1` set and not one
+ * `response:` or read-back line among them, because the job's
+ * `PATH="$WS_PATH/node_modules/.bin:$PATH"` put that workspace's pinned
+ * `@gjsify/cli@^0.44.0` ahead of the 0.51.1 it had just bootstrapped. Three of
+ * the twelve were not on the registry. The marker could not have told anyone,
+ * and nobody could have known to look.
+ *
+ * So every terminal success marker now carries its verification clause, and an
+ * unverified one says UNVERIFIED in a word a log sweep can grep for. A bare
+ * `+ name@version` with no clause is now itself the signature of a CLI too old
+ * to check.
+ */
+function describeVerification(readback, registry) {
+    if (!readback?.confirmed) {
+        return {
+            verified: false,
+            clause: '(UNVERIFIED — read-back disabled by --verify-timeout 0)',
+            json: null,
+        };
+    }
+    const seconds = (readback.elapsedMs / 1000).toFixed(1);
+    return {
+        verified: true,
+        clause: `(verified on ${registry} — ${readback.attempts} probe(s), ${seconds}s)`,
+        json: {
+            registry,
+            verdict: readback.verdict,
+            probes: readback.attempts,
+            elapsedMs: readback.elapsedMs,
+            tarball: readback.last.state === 'present' ? readback.last.tarball : null,
+        },
+    };
+}
+/**
+ * An unverified SUCCESS gets an Actions annotation too.
+ *
+ * `--verify-timeout 0` is a legitimate escape hatch for a registry with no
+ * packument read path, and it restores exactly the behaviour every incident in
+ * this file came out of. A disabled verifier that announces itself is a
+ * decision; one that stays quiet is the original defect wearing a hat — and the
+ * channel is the one `--verify-defer` already uses, beside the job rather than
+ * in a log nobody re-reads. stderr, because `--json` owns stdout.
+ */
+function warnUnverified(name, version, registry) {
+    if (!process.env.GITHUB_ACTIONS)
+        return;
+    process.stderr.write(`::warning title=Publish unverified::${name}@${version} was published with the read-back disabled ` +
+        `(--verify-timeout 0) — nothing confirmed that ${registry} serves it\n`);
+}
 function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
     switch (outcome.action) {
         case 'published': {
+            const verification = describeVerification(outcome.readback, outcome.registry);
             const out = {
                 ok: true,
                 name: outcome.name,
@@ -580,11 +690,15 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                 integrity: outcome.integrity,
                 tag: outcome.tag,
                 registry: outcome.registry,
+                verified: verification.verified,
+                verification: verification.json,
             };
             if (asJson)
                 process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
             else
-                process.stdout.write(`+ ${outcome.name}@${outcome.version}\n`);
+                process.stdout.write(`+ ${outcome.name}@${outcome.version} ${verification.clause}\n`);
+            if (!verification.verified)
+                warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
         case 'publish-unconfirmed': {
@@ -602,6 +716,9 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     elapsedMs: outcome.readback.elapsedMs,
                     readbackUrl: outcome.readback.url,
                     readbackState: outcome.readback.last.state,
+                    verdict: outcome.readback.verdict,
+                    verdictDetail: outcome.readback.verdictDetail,
+                    recordedAt: outcome.readback.recordedAt ?? null,
                     deferred: deferUnconfirmed,
                 }, null, 2)}\n`);
             }
@@ -619,24 +736,31 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     const claimed = outcome.claim === 'already-published' ? 'was reported already published' : 'was accepted';
                     process.stderr.write(`::warning title=Publish unconfirmed::${outcome.name}@${outcome.version} ${claimed} ` +
                         `(HTTP ${outcome.putStatus}) but did not resolve on ${outcome.registry} within ` +
-                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s — the release-closure job must confirm it\n`);
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s [${outcome.readback.verdict}] — ` +
+                        'the release-closure job must confirm it\n');
                 }
                 return;
             }
             return process.exit(1);
         }
         case 'republish-tolerated': {
+            const verification = describeVerification(outcome.readback, outcome.registry);
             const out = {
                 ok: true,
                 action: 'republish-tolerated',
                 name: outcome.name,
                 version: outcome.version,
                 status: outcome.status,
+                registry: outcome.registry,
+                verified: verification.verified,
+                verification: verification.json,
             };
             if (asJson)
                 process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
             else
-                process.stdout.write(`= ${outcome.name}@${outcome.version} (already published, tolerated)\n`);
+                process.stdout.write(`= ${outcome.name}@${outcome.version} (already published, tolerated) ${verification.clause}\n`);
+            if (!verification.verified)
+                warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
         case 'skipped-untrusted-new': {
@@ -654,6 +778,27 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
             }
             return;
         }
+        case 'blocked-missing-dependency': {
+            const edges = outcome.missing.map((m) => `${m.block}.${m.name}@${m.spec}`).join(', ');
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: outcome.ok,
+                    action: 'blocked-missing-dependency',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    tolerated: outcome.tolerated,
+                    missing: outcome.missing,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`~ ${outcome.name}@${outcome.version} (NOT published — ${outcome.missing.length} required pin(s) name a package ${outcome.registry} does not have: ${edges})\n`);
+            }
+            console.error(`gjsify publish: every consumer install of ${outcome.name} would fail with \`npm error 404\`, on every package manager — a required edge is not skippable. Bootstrap the target first (docs/publishing.md § New \`@gjsify/*\` package), then re-run. See #1713.`);
+            if (!outcome.tolerated)
+                return process.exit(1);
+            return;
+        }
         case 'otp-required': {
             console.error(`gjsify publish: npm requires a 2FA one-time code — re-run with \`--otp <code>\``);
             return process.exit(1);

package/lib/commands/self-update.js

@@ -27,6 +27,7 @@ import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { classifyInstall } from '../utils/install-provenance.js';
 import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
+import { pathWithoutSelfShim } from '../utils/gjsify-shim.js';
 import { resolveHostPlatform } from '../utils/platform-check.js';
 import { pruneAfterInstall } from '../utils/prune-prefix.js';
 const PACKAGE_NAME = '@gjsify/cli';
@@ -210,7 +211,7 @@ export const selfUpdateCommand = {
             const verdict = verifyPathResolution({
                 binName: BIN_NAME,
                 binDir: layout.binDir,
-                resolvedBin: resolveBinOnPath(BIN_NAME),
+                resolvedBin: resolveBinOnPath(BIN_NAME, { pathValue: pathWithoutSelfShim() }),
                 runningVersion: currentVersion,
                 targetVersion: target,
             });

package/lib/commands/ship.js

@@ -35,6 +35,7 @@ import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
+import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
 import { assertHostCanFinish, assertKindCanPack, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
 import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
@@ -433,7 +434,24 @@ async function assemble(args) {
                 workDir: join(outRoot, 'schemas'),
             })),
     ];
-    const staged = placeStage(layout, settings, planned, runtime.files);
+    // THE APPLICATION ICON, rendered once for the sizes this layout's writers
+    // embed — six for the `.exe`'s resource directory, seven for the `.icns` —
+    // and nothing for a CLI or for Linux, where the theme carries the SVG the
+    // project declared. `resolveAppIcon` REFUSES an app that has no source for a
+    // size rather than staging without it: the released artifacts this closes
+    // shipped for a year with the generic icon on two platforms, and the only
+    // reason was that nothing said so (`utils/ship/icons.ts`).
+    const icon = settings.kind === 'app' && layout.icon !== undefined
+        ? await resolveAppIcon({
+            iconFiles: settings.iconFiles,
+            appId: settings.appId,
+            sizes: layout.icon.sizes,
+            target: layout.icon.writes,
+        })
+        : undefined;
+    if (icon !== undefined)
+        console.log(`${LOG} icon: ${iconSizes(icon).join('/')} px, ${icon.source}`);
+    const staged = placeStage(layout, { ...settings, icon }, planned, runtime.files);
     writeStage(stageDir, staged);
     console.log(`${LOG} staged ${staged.length} file(s) for ${layout.name} in ${relative(projectDir, stageDir)}/`);
     if (args.verbose)

package/lib/commands/test.d.ts

@@ -10,16 +10,25 @@ interface TestOptions {
 }
 export declare const testCommand: Command<unknown, TestOptions>;
 /**
- * True when `outfile` is at least as new as every build input of the package
- * at `cwd`.
+ * True when `outfile` is at least as new as every input of the build that
+ * wrote it.
  *
- * The set is {@link packageBuildInputs}, the same one the build cache hashes.
- * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
- * there, so `src/**` was never walked: a change to the code UNDER TEST left
- * the bundle "fresh" and `gjsify test` reran the previous build and reported
- * on it. That went both ways inside one dependency bump — a green run
- * measuring a version that was no longer installed, then a red one after the
- * source had already been repaired (#1651).
+ * The set is the union of two answers, because neither covers the question
+ * alone: {@link packageBuildInputs} — what may this PACKAGE's build read, the
+ * same walk the build cache hashes — and the manifest the build itself wrote
+ * beside `outfile` ({@link readBundleInputs}), what this build DID read. The
+ * second is what reaches a workspace package through a `node_modules` symlink
+ * into a sibling directory: the package walk is blind to it by construction,
+ * so an edit there left the bundle "fresh" and the run reported on code that
+ * was no longer on disk — a stale green, worse than a slow build. The first is
+ * what the walk alone never managed: it was `dirname(entry)`, `tests/` for any
+ * package whose suite lives there, so `src/**` was never seen and `gjsify test`
+ * reran the previous build and reported on it, in both directions inside one
+ * dependency bump (#1651).
+ *
+ * A missing manifest is NOT an answer: it is the pre-recorder shape, and the
+ * package walk then decides alone — never weaker than before, and the next
+ * build writes one.
  *
  * `outdir` is subtracted as this command's own output; `entry` is added
  * because `--entry ../shared/test.mts` may point outside the package.

package/lib/commands/test.js

@@ -7,6 +7,7 @@
 // exit codes.
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, relative, sep } from 'node:path';
+import { newestBundleInputMtimeMs, readBundleInputs, createBundleInputsRecorder } from '../utils/bundle-inputs.js';
 import { newestDepSignalMtimeMs, newestInputMtimeMs, packageBuildInputs } from '../utils/package-inputs.js';
 import { isRuntimeAvailable, RUNTIMES } from '../utils/runtimes.js';
 import { nodeBinary } from '../utils/run-node.js';
@@ -180,13 +181,39 @@ async function buildTestBundle(entry, outfile, runtime, verbose) {
     // bundler.output.file from the surrounding project don't redirect the
     // bundle elsewhere.
     configData.library = { ...configData.library };
+    // Record what this build READ, so the next `isFresh` can judge against the
+    // bundle's real dependencies rather than this package's tree. A recorder
+    // rides the same plugin chain a user's `bundler.plugins` entry does, and
+    // the auto-globals pre-build pass therefore feeds it too — a superset of
+    // the final graph, which errs towards a rebuild and never towards a stale
+    // green. Appended last so it observes whatever the earlier hooks loaded.
+    const recorder = createBundleInputsRecorder(outfile);
     configData.bundler = {
         ...configData.bundler,
         input: [entry],
         output: { ...configData.bundler?.output, file: outfile },
+        plugins: [...(configData.bundler?.plugins ?? []), recorder.plugin],
     };
     const action = new BuildAction(configData);
-    await action.start({ app: runtime, library: false });
+    // `onWatchFiles` is the half the transform observer cannot reach: a file a
+    // plugin read itself and declared (a stylesheet's `@import` chain). The
+    // recorder takes the union — npm reports its module set too, the native
+    // engine reports nothing but the declarations, and each engine alone would
+    // leave a class of input unrecorded.
+    await action.start({
+        app: runtime,
+        library: false,
+        onWatchFiles: (watch) => recorder.addWatchFiles(watch),
+    });
+    // Written AFTER the build resolves, and that ordering is the whole of what
+    // a failure leaves behind: a build that fails BEFORE writing an artifact
+    // (parse, resolve, a plugin hook) throws out of `start()` and never reaches
+    // this line, so the previous manifest still describes the previous bundle.
+    // A failure in a POST-WRITE gate is the other case and is not ours to
+    // paper over: `actions/build.ts` has already replaced the bundle, the
+    // manifest is rewritten beside it, and both then describe the same build —
+    // the next run re-runs the failing bundle rather than the one before it.
+    recorder.write();
 }
 /** Run a single test bundle and reject on non-zero exit. */
 async function runTestBundle(outfile, runtime) {
@@ -206,16 +233,25 @@ async function runTestBundle(outfile, runtime) {
         throw new Error(`node exited with ${describeExit(result)}`);
 }
 /**
- * True when `outfile` is at least as new as every build input of the package
- * at `cwd`.
+ * True when `outfile` is at least as new as every input of the build that
+ * wrote it.
+ *
+ * The set is the union of two answers, because neither covers the question
+ * alone: {@link packageBuildInputs} — what may this PACKAGE's build read, the
+ * same walk the build cache hashes — and the manifest the build itself wrote
+ * beside `outfile` ({@link readBundleInputs}), what this build DID read. The
+ * second is what reaches a workspace package through a `node_modules` symlink
+ * into a sibling directory: the package walk is blind to it by construction,
+ * so an edit there left the bundle "fresh" and the run reported on code that
+ * was no longer on disk — a stale green, worse than a slow build. The first is
+ * what the walk alone never managed: it was `dirname(entry)`, `tests/` for any
+ * package whose suite lives there, so `src/**` was never seen and `gjsify test`
+ * reran the previous build and reported on it, in both directions inside one
+ * dependency bump (#1651).
  *
- * The set is {@link packageBuildInputs}, the same one the build cache hashes.
- * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
- * there, so `src/**` was never walked: a change to the code UNDER TEST left
- * the bundle "fresh" and `gjsify test` reran the previous build and reported
- * on it. That went both ways inside one dependency bump — a green run
- * measuring a version that was no longer installed, then a red one after the
- * source had already been repaired (#1651).
+ * A missing manifest is NOT an answer: it is the pre-recorder shape, and the
+ * package walk then decides alone — never weaker than before, and the next
+ * build writes one.
  *
  * `outdir` is subtracted as this command's own output; `entry` is added
  * because `--entry ../shared/test.mts` may point outside the package.
@@ -229,7 +265,16 @@ export function isFresh(outfile, entry, cwd, outdir) {
         const outdirRel = relative(cwd, outdir).split(sep).join('/');
         if (outdirRel !== '' && !outdirRel.startsWith('../'))
             extraOutputs.push(outdirRel);
-        const newest = Math.max(newestInputMtimeMs(packageBuildInputs(cwd, { extraOutputs })), statSync(entry).mtimeMs, 
+        const bundleInputs = readBundleInputs(outfile);
+        // A build whose engine could report NO watch list never entered a file
+        // only a PLUGIN read — a stylesheet's `@import` chain, an inlined
+        // `readFileSync` — into the set below, and no mtime comparison can
+        // recover it. Judging such a bundle fresh IS the stale green, so the
+        // answer is no: rebuild, on every run, and say why. `bundler-pick.ts`
+        // prints the skew once; the manifest carries it across processes.
+        if (bundleInputs !== null && !bundleInputs.watchList)
+            return false;
+        const newest = Math.max(newestInputMtimeMs(packageBuildInputs(cwd, { extraOutputs })), bundleInputs === null ? 0 : newestBundleInputMtimeMs(bundleInputs.inputs), statSync(entry).mtimeMs, 
         // A dependency bump changes no file in the package — and that is
         // the shape #1651 was found in. `node_modules` is far too large
         // to stat per run, so the lockfile stands in for it.

package/lib/commands/tsc.js

@@ -128,10 +128,10 @@ export const tscCommand = {
         // Run upstream `typescript` under Node — the Node fallback.
         //
         // `nodeBinary()`, NEVER a bare `process.execPath`: under the GJS bundle
-        // `process.execPath` is the GJS interpreter (`/proc/self/exe` →
-        // `gjs-console`), so `spawn(process.execPath, [tsc.js])` hands
-        // TypeScript's CommonJS CLI to GJS, which dies on the first `module`
-        // reference — or, where execPath resolves to a gjsify launcher instead,
+        // `process.execPath` is the GJS interpreter (`hostExecPath()`:
+        // `/proc/self/exe` on Linux, the PATH lookup of `gjs` on macOS), so
+        // `spawn(process.execPath, [tsc.js])` hands TypeScript's CommonJS CLI to
+        // GJS, which dies on the first `module` reference — or, where execPath resolves to a gjsify launcher instead,
         // re-executes the CLI with the tsc entry as an unknown argument. Both
         // were reached from a COLD tree: `@gjsify/tsc`'s `dist/tsc.gjs.mjs` is a
         // build output, and `build:infra` builds `@gjsify/create-app` (its first

package/lib/commands/upgrade.d.ts

@@ -29,6 +29,21 @@ export declare const upgradeCommand: Command<unknown, UpgradeOptions>;
  * Returns the number of offending declarations so the caller can exit once for both arms.
  */
 export declare function reportInexactRanges(groups: readonly DependencyGroup[]): number;
+/**
+ * Check that every lockfile resolution satisfies the ranges declared for it.
+ *
+ * `gjsify upgrade --check` compares declared ranges against each other across
+ * workspaces. It does NOT compare the resolution against any of them, so a
+ * lockfile entry that violates every declaration in the repo passes silently.
+ *
+ * This check reads the lockfile, resolves each entry's version, and verifies
+ * it satisfies at least one declared range for that dependency.
+ *
+ * @param groups dependency groups with declared ranges
+ * @param cwd working directory
+ * @returns number of violations
+ */
+export declare function checkLockfileRangeViolations(groups: readonly DependencyGroup[], cwd: string): number;
 /**
  * The range a dependency will be WRITTEN at.
  *

package/lib/commands/upgrade.js

@@ -36,7 +36,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
-import { parse } from '@gjsify/semver';
+import { parse, satisfies } from '@gjsify/semver';
 import { DEFAULT_REGISTRY, fetchPackument, parseNpmrc } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
@@ -325,7 +325,81 @@ export function reportInexactRanges(groups) {
     }
     return total;
 }
-function runCheckMode(groups, exact = false) {
+/**
+ * Check that every lockfile resolution satisfies the ranges declared for it.
+ *
+ * `gjsify upgrade --check` compares declared ranges against each other across
+ * workspaces. It does NOT compare the resolution against any of them, so a
+ * lockfile entry that violates every declaration in the repo passes silently.
+ *
+ * This check reads the lockfile, resolves each entry's version, and verifies
+ * it satisfies at least one declared range for that dependency.
+ *
+ * @param groups dependency groups with declared ranges
+ * @param cwd working directory
+ * @returns number of violations
+ */
+export function checkLockfileRangeViolations(groups, cwd) {
+    const lockPath = join(cwd, 'gjsify-lock.json');
+    if (!existsSync(lockPath))
+        return 0;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
+    }
+    catch {
+        return 0;
+    }
+    if (!lock.packages)
+        return 0;
+    // Build a map: dep name -> set of declared ranges
+    const declaredRanges = new Map();
+    for (const g of groups) {
+        const ranges = declaredRanges.get(g.name) ?? new Set();
+        for (const occ of g.occurrences) {
+            ranges.add(occ.currentRange);
+        }
+        declaredRanges.set(g.name, ranges);
+    }
+    let violations = 0;
+    for (const [key, entry] of Object.entries(lock.packages)) {
+        if (!entry.version)
+            continue;
+        // Only check direct dependencies — the single-segment "node_modules/<name>" form.
+        // A deep transitive resolution (e.g. "node_modules/a/node_modules/b") is pinned by
+        // its parent, not by the root's declared range, and must not be checked against it.
+        const parts = key.split('node_modules/');
+        if (parts.length !== 2)
+            continue;
+        const depName = parts[1];
+        const ranges = declaredRanges.get(depName);
+        if (!ranges || ranges.size === 0)
+            continue;
+        // Check if the resolved version satisfies at least one declared range
+        let satisfied = false;
+        for (const range of ranges) {
+            try {
+                if (entry.version && satisfies(entry.version, range)) {
+                    satisfied = true;
+                    break;
+                }
+            }
+            catch {
+                // Invalid range, skip
+            }
+        }
+        if (!satisfied) {
+            console.error(`  ${depName}: lockfile has ${entry.version}, but declared ranges are ${[...ranges].join(', ')}`);
+            violations++;
+        }
+    }
+    if (violations > 0) {
+        console.error(`gjsify upgrade --check: FAIL. ${violations} lockfile entr${violations === 1 ? 'y' : 'ies'} violate declared ranges:\n`);
+    }
+    return violations;
+}
+function runCheckMode(groups, exact = false, cwd = process.cwd()) {
+    const lockfileViolations = checkLockfileRangeViolations(groups, cwd);
     const inexact = exact ? reportInexactRanges(groups) : 0;
     const inconsistencies = findInconsistencies(groups);
     if (inconsistencies.length === 0 && inexact > 0) {

package/lib/commands/webext/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from '../../types/index.js';
+export declare const webextCommand: Command;

package/lib/commands/webext/index.js

@@ -0,0 +1,15 @@
+// `gjsify webext` — yargs subcommand-group dispatcher (ADR 0077).
+//
+// Wires {build, zip, dev}; each is a self-contained `Command<>` in `subcommands.ts`,
+// the same composition `flatpak/index.ts` uses.
+import { webextBuildCommand, webextDevCommand, webextZipCommand } from './subcommands.js';
+export const webextCommand = {
+    command: 'webext <subcommand>',
+    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox and Safari.',
+    builder: (yargs) => yargs
+        .command(webextBuildCommand.command, webextBuildCommand.description, webextBuildCommand.builder, webextBuildCommand.handler)
+        .command(webextZipCommand.command, webextZipCommand.description, webextZipCommand.builder, webextZipCommand.handler)
+        .command(webextDevCommand.command, webextDevCommand.description, webextDevCommand.builder, webextDevCommand.handler)
+        .demandCommand(1)
+        .strict(),
+};

package/lib/commands/webext/subcommands.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from '../../types/index.js';
+interface WebextArgs {
+    target?: string[];
+    outDir?: string;
+    define: string[];
+    mode?: string;
+    launch: boolean;
+    browserBinary?: string;
+    profile?: string;
+    headless: boolean;
+    debounce: number;
+}
+export declare const webextBuildCommand: Command<unknown, WebextArgs>;
+export declare const webextZipCommand: Command<unknown, WebextArgs>;
+export declare const webextDevCommand: Command<unknown, WebextArgs>;
+export {};