@gjsify/cli 0.47.0 → 0.48.0

package/lib/commands/affected-classify.js

@@ -146,6 +146,27 @@ const SCRIPT_COUPLINGS = [
         runE2E: true,
         why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
     },
+    {
+        // THE SAME SHAPE AS `.githooks/` ABOVE, one layer up: the guard's trigger names
+        // the TEST's path instead of the thing under test. `AppRegistry.runApplication`
+        // holds three lines observable only by RUNNING the loop —
+        // `registerBuiltinWidgets()`, the `toShellOptions` passthrough and
+        // `provideWindowChrome()` — and their one external observer is
+        // `tests/e2e/react-native-devtools`, which main.yml's `e2e` job now runs under
+        // xvfb + a session bus (#1550). Without this entry a change confined to
+        // `packages/framework/react-native/**` seeds its own workspace, the e2e tier
+        // stays OFF (it turns on for a `tests/e2e/**` touch), and the suite is silent
+        // for exactly the PRs it exists to catch. Measured on #1540: deleting
+        // `provideWindowChrome()` left format, lint, tsc and all in-process assertions
+        // green while the application drew two header bars.
+        //
+        // No extra seeds — the package is a workspace and already seeds itself. The
+        // TIER is the point, as for `.githooks/`.
+        match: /^packages\/framework\/react-native\//,
+        seeds: [],
+        runE2E: true,
+        why: 'tests/e2e/react-native-devtools is the only external observer of AppRegistry.runApplication',
+    },
 ];
 export function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
@@ -255,7 +276,15 @@ export function classifyAndExpand(workspaces, changedFiles) {
             global: false,
             reason: `test-only (${remaining.length} file(s) in ${only})`,
             workspaces: [only],
-            runE2E: touchedE2E,
+            // `|| couplingRunE2E`: this shortcut skips CLOSURE EXPANSION, and a
+            // declared tier is not part of the closure. Dropping it here made a
+            // coupling's reach depend on the SHAPE of the changed path — the
+            // `.githooks/` entry survived only because a hook is not a spec file,
+            // while `packages/framework/react-native/src/widgets.spec.ts` fell
+            // through and turned the e2e tier back off. Measured by the vector
+            // "a react-native spec file ALSO turns the e2e tier on", which was RED
+            // when it was written (#1550).
+            runE2E: touchedE2E || couplingRunE2E,
             runIntegration: touchedIntegration || isIntegrationWorkspace(only),
             skipAll: false,
         };

package/lib/commands/dlx.js

@@ -13,6 +13,7 @@
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { cacheDirFor, createCacheKey, getValidCachedPkg, makePrepareDir, resolveInstalledPkgDir, symlinkSwap, } from '../utils/dlx-cache.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 export const dlxCommand = {
@@ -25,7 +26,11 @@ export const dlxCommand = {
         // --help` shows ts-for-gir's --help instead of gjsify dlx's.
         // Without `populate--`, the trailing `--help` is consumed at
         // the gjsify level and the bundle never sees it.
-        .parserConfiguration({ 'populate--': true })
+        // `parse-positional-numbers: false` alongside it: the `--` tail and the
+        // `[extraArgs..]` positional are the caller's argv, not numbers, and yargs
+        // otherwise retypes a bare `5` (#1531). `--cache-max-age` declares
+        // `type: 'number'` and is unaffected.
+        .parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })
         .positional('spec', {
         description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
         type: 'string',
@@ -84,8 +89,7 @@ export const dlxCommand = {
         // number)[]`), so flags like `--help` reach the bundle untouched.
         // Merge those into the positional extraArgs the splitter sees so
         // both call shapes share one downstream path.
-        const passthroughDoubleDash = (args['--'] ?? []).map((v) => String(v));
-        const extraArgsCombined = [...(args.extraArgs ?? []), ...passthroughDoubleDash];
+        const extraArgsCombined = [...(args.extraArgs ?? []), ...doubleDashArgs(args)];
         const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, extraArgsCombined);
         const entry = resolveGjsEntry(pkgDir, binName);
         if (entry.fromFallback) {

package/lib/commands/foreach.js

@@ -15,6 +15,7 @@ import { affectedClosure, buildDependencyGraph, discoverWorkspaces, filterWorksp
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { cliRuntimeClosure } from '../utils/cli-runtime-closure.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 // The ONE runner-selection rule, shared rather than re-derived. This file used to
 // carry its own copy; `workspace.ts` grew the bootstrap-CLI branch and the copy
@@ -267,6 +268,12 @@ export const foreachCommand = {
         //   gjsify foreach --exec -- npm publish --tag latest
         // without yargs grabbing --tag/--access/etc.
         'populate--': true,
+        // …and keep that tail as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array as a `number`,
+        // which is how `--verify-timeout 5 --tag latest` reached 209
+        // npm publishes as `--verify-timeout --tag latest` (#1531).
+        // Declared `type: 'number'` options (`--jobs`) are unaffected.
+        'parse-positional-numbers': false,
     }),
     handler: async (args) => {
         // Walk up to the monorepo root — foreach is sometimes invoked
@@ -286,7 +293,7 @@ export const foreachCommand = {
             // 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');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0)
                 cmdArgs = [...cmdArgs, ...fromDoubleDash];
         }
@@ -294,7 +301,7 @@ export const foreachCommand = {
             // With populate--:true, anything after the literal `--`
             // separator lands in top-level args['--']. yargs DOES NOT
             // attach it to args._ — it's a sibling array.
-            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0) {
                 if (!cmd) {
                     cmd = fromDoubleDash[0];

package/lib/commands/publish.js

@@ -42,6 +42,7 @@
 import { readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { base64Encode } from '../utils/base64.js';
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers.js';
 import { packWorkspace } from './pack.js';
@@ -789,14 +790,6 @@ function buildPublishPayload(opts) {
         payload.access = access;
     return payload;
 }
-function base64Encode(bytes) {
-    let str = '';
-    const chunk = 0x8000;
-    for (let i = 0; i < bytes.length; i += chunk) {
-        str += String.fromCharCode(...bytes.subarray(i, i + chunk));
-    }
-    return btoa(str);
-}
 function handleOidcFailure(err, packageName, asJson) {
     if (err instanceof OidcUnavailableError) {
         const msg = `gjsify publish: OIDC not available — ${err.message}`;

package/lib/commands/run.js

@@ -15,6 +15,7 @@
 // to disambiguate can pass `./<file>` explicitly.
 import { readFileSync, statSync } from 'node:fs';
 import { basename, delimiter, join, resolve } from 'node:path';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
@@ -93,6 +94,11 @@ export const runCommand = {
         // Without this, anything after `--` lands in args._ and is
         // silently dropped by the handler.
         'populate--': true,
+        // …and hand that tail on as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array — and in the
+        // `[args..]` positional — as a `number`, which the reader below
+        // used to drop outright (#1531).
+        'parse-positional-numbers': false,
         // Forward UNKNOWN flags to the target without requiring `--`:
         //   gjsify run dist/app.gjs.mjs serve --port 8080 --year 2025
         // Without this, the top-level `.strict()` (cli-app.ts) rejects
@@ -111,8 +117,7 @@ export const runCommand = {
         // than silently discarding them (without it they land in args._ and
         // are never forwarded to the child).
         const positionalArgs = args.args ?? [];
-        const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
-        const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        const extraArgs = [...positionalArgs, ...doubleDashArgs(args)];
         // `--node-script` (explicit) → run an UNBUNDLED Node-style script on the
         // host runtime; under GJS it is bundled `--app gjs` on the fly first.
         // Checked before `--runtime` and `--workspace`: it is a file mode, and

package/lib/commands/ship.js

@@ -42,13 +42,14 @@ import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
 import { compileSchemasForStage } from '../utils/ship/schemas.js';
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
+import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
 import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
 import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
-import { declaredBundlePath, resolveShipApp, resolveShipSettings, } from '../utils/ship/settings.js';
+import { resolveShipApp, resolveShipBundle, resolveShipSettings, } from '../utils/ship/settings.js';
 import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
 import { directorySize, readStage, writePayload, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
@@ -280,12 +281,22 @@ async function assemble(args) {
             assertCanPack(format);
     if (!args['skip-build'])
         await runProjectBuild(projectDir);
+    // THE OTHER HALF of the resolution above, and they are one decision: the
+    // runtime a target execs and the entry it hands that runtime (#1545). Two
+    // keys, resolved by two twin functions, compared by `assertEntryRunsUnder`
+    // as soon as both answers and the file exist.
+    const resolvedBundle = resolveShipBundle({ pkg, ship, layoutOs: layout.os });
+    if (resolvedBundle.overridden) {
+        console.log(`${LOG} entry for ${layout.name}: ${resolvedBundle.declared} — \`${resolvedBundle.key}\` ` +
+            'overrides `gjsify.main`.');
+    }
     const discovered = discoverPayload({
         projectDir,
         pkg,
         ship,
         flatpakIcon: flatpak.icon,
-        declaredBundle: declaredBundlePath(pkg, ship),
+        declaredBundle: resolvedBundle.declared,
+        foreignBundles: resolvedBundle.foreign,
     });
     const { settings, metadata, warnings } = resolveShipSettings({
         projectDir,
@@ -308,6 +319,21 @@ async function assemble(args) {
     // the packing host.
     for (const format of formats)
         assertFormatCanRunInterpreter(format, settings.app);
+    // The entry, read ONCE: the pair check below and the namespace scan further
+    // down both ask what this file imports, and a bundle is the biggest file in
+    // the project.
+    const bundleSource = readFileSync(settings.bundlePath, 'utf-8');
+    // BEFORE anything is staged, for the reason above and one more: this is the
+    // refusal that says the artifact could never have started, and the run that
+    // reports it must not also print a stage path.
+    assertEntryRunsUnder({
+        interpreter: settings.app,
+        source: bundleSource,
+        entry: relative(projectDir, settings.bundlePath) || settings.bundlePath,
+        appKey: resolvedApp.key,
+        bundleKey: resolvedBundle.key,
+        layoutOs: layout.os,
+    });
     const mtime = buildTimestamp(settings.bundlePath);
     const metadataInputs = {
         appId: settings.appId,
@@ -354,6 +380,8 @@ async function assemble(args) {
         metainfo: translated.metainfo,
         desktopEntry: translated.desktopEntry,
         licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
+        changelogText: settings.changelogFile === undefined ? undefined : readFileSync(settings.changelogFile, 'utf-8'),
+        mtime,
     };
     const outRoot = resolve(projectDir, settings.outDir);
     const stageDir = join(outRoot, 'stage');
@@ -466,7 +494,7 @@ async function assemble(args) {
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
     // tell which staged file is the entry.
-    const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
+    const namespaces = scanGiNamespaces(bundleSource);
     if (args.verbose)
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
     // PLACED, like the payload, and through the same map. `planOverlay` answers a
@@ -481,7 +509,7 @@ async function assemble(args) {
     // overlay reaches it by the same route.
     const overlay = new Map();
     for (const format of formats) {
-        overlay.set(format.id, planOverlay(settings, format, stageInputs).map((file) => ({
+        overlay.set(format.id, (await planOverlay(settings, format, stageInputs)).map((file) => ({
             ...file,
             path: place(layout, settings, file.path),
         })));

package/lib/types/config-data.d.ts

@@ -464,14 +464,27 @@ export interface ConfigDataShip extends AppMetadata {
     /**
      * The built bundle `bin/<name>` executes. Default: `gjsify.main`, then
      * `package.json#main`. Its whole directory is staged into `lib/<name>/`.
+     *
+     * A STRING is one entry for every target; a TABLE names one per OS, keyed
+     * like {@link ShipAppOptions} and resolved beside it. An application with two
+     * hosts has two bundles built from one source — `gjsify.app` decides which
+     * runtime a target execs, and this decides which of those bundles it hands
+     * that runtime (#1545).
      */
-    bundle?: string;
+    bundle?: string | ShipBundleOptions;
     /** Icon file, or a directory of them. Sizes are read from the path or the filename. */
     icon?: string;
     /** A `*.gschema.xml` file, or a directory of them. */
     schemas?: string;
     /** Licence file. Default: the first of LICENSE, LICENSE.md, LICENSE.txt, COPYING. */
     licenseFile?: string;
+    /**
+     * The project's own changelog, rendered into the `.deb`'s
+     * `share/doc/<package>/changelog.Debian.gz` (Debian Policy § 4.4).
+     * Default: the first of CHANGELOG.md, CHANGELOG, CHANGELOG.txt, NEWS.md,
+     * searched up to the repository root exactly as `licenseFile` is.
+     */
+    changelogFile?: string;
     /** deb `Section:`. Default: derived from `categories`. */
     section?: string;
     /** rpm `Group:`. Default: derived from `categories`. */
@@ -611,6 +624,29 @@ export interface ShipAppOptions {
     /** What a Windows program directory carries. `node` is the only value its formats accept. */
     win32?: 'gjs' | 'node';
 }
+/**
+ * `gjsify.ship.bundle` — the ENTRY per OS, the twin of {@link ShipAppOptions}.
+ *
+ * The two answer one question between them, and answering only half of it is
+ * what #1545 measured: `gjsify.ship.app.darwin: "node"` pointed the launcher at
+ * `node` while the payload stayed the project's `main` — a `--app gjs` bundle,
+ * because Linux is that project's primary target. Both halves were honoured,
+ * they contradicted each other, and the `.app` died on its first import.
+ *
+ * Same OS spelling as everywhere else in this block (`process.platform`), and
+ * the same fall-through: a target with no key here keeps `gjsify.main`. What it
+ * does NOT keep is another target's entry — a bundle declared for one OS is
+ * dropped from every other OS's payload, since no interpreter but that one can
+ * load it.
+ */
+export interface ShipBundleOptions {
+    /** The entry a `.deb`/`.rpm`/Flatpak installs. */
+    linux?: string;
+    /** The entry `<App>.app/Contents/Resources/lib/` carries. */
+    darwin?: string;
+    /** The entry the Windows program directory carries. */
+    win32?: string;
+}
 /**
  * `gjsify.ship.sign` — an IDENTITY per OS, and never a certificate.
  *

package/lib/utils/base64.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Base64 for the CLI's own Node entry, which may not reach `@gjsify/buffer`.
+ *
+ * `@gjsify/buffer` exports exactly these two functions and this file duplicates
+ * them — deliberately, and the reason is a LAYER, not taste. The CLI's Node entry
+ * is the bootstrap artifact (ADR 0002): `gjsify install` links it before anything
+ * in this tree is built. `scripts/bootstrap-native-facades.mjs` emits `lib/esm`
+ * for its link-time runtime deps with plain `tsc`, and `buildCliRuntimeDeps()`
+ * resolves each one under `packages/infra/<name>`. `@gjsify/buffer` lives under
+ * `packages/node/` and its own `build` is `gjsify run build:gjsify && …`, i.e. it
+ * needs the BUNDLER — the artifact the bootstrap exists to produce. Importing it
+ * from here inverts that order, and the failure is not a type error: the ESM link
+ * fails at `bootstrap-native-facades`, so `build:infra` dies on every host before
+ * a single test runs.
+ *
+ * Measured: with `import { base64Encode } from '@gjsify/buffer'` in the CLI's Node
+ * entry, ten CI legs failed identically — "Missing at ESM link time:
+ * packages/infra/cli/node_modules/@gjsify/buffer/lib/esm/index.js, imported from
+ * lib/utils/ship/stage-manifest.js" — while all three REQUIRED checks stayed green,
+ * because `check-build-infra-order` holds the declaration order for TYPES and this
+ * is a runtime edge.
+ *
+ * So: one copy inside the CLI, imported by both call sites, rather than the two
+ * that prompted the deduplication in the first place. If the CLI ever gains a
+ * general way to reach `packages/node/*` at bootstrap time, this file is what
+ * should go.
+ */
+/**
+ * Chunked because `String.fromCharCode(...bytes)` is a spread: a tarball-sized
+ * array blows the argument limit and throws `RangeError: Maximum call stack size
+ * exceeded`. 0x8000 is the size the CLI's publish path has always used.
+ */
+export declare function base64Encode(bytes: Uint8Array): string;
+export declare function base64Decode(text: string): Uint8Array;

package/lib/utils/base64.js

@@ -0,0 +1,47 @@
+/**
+ * Base64 for the CLI's own Node entry, which may not reach `@gjsify/buffer`.
+ *
+ * `@gjsify/buffer` exports exactly these two functions and this file duplicates
+ * them — deliberately, and the reason is a LAYER, not taste. The CLI's Node entry
+ * is the bootstrap artifact (ADR 0002): `gjsify install` links it before anything
+ * in this tree is built. `scripts/bootstrap-native-facades.mjs` emits `lib/esm`
+ * for its link-time runtime deps with plain `tsc`, and `buildCliRuntimeDeps()`
+ * resolves each one under `packages/infra/<name>`. `@gjsify/buffer` lives under
+ * `packages/node/` and its own `build` is `gjsify run build:gjsify && …`, i.e. it
+ * needs the BUNDLER — the artifact the bootstrap exists to produce. Importing it
+ * from here inverts that order, and the failure is not a type error: the ESM link
+ * fails at `bootstrap-native-facades`, so `build:infra` dies on every host before
+ * a single test runs.
+ *
+ * Measured: with `import { base64Encode } from '@gjsify/buffer'` in the CLI's Node
+ * entry, ten CI legs failed identically — "Missing at ESM link time:
+ * packages/infra/cli/node_modules/@gjsify/buffer/lib/esm/index.js, imported from
+ * lib/utils/ship/stage-manifest.js" — while all three REQUIRED checks stayed green,
+ * because `check-build-infra-order` holds the declaration order for TYPES and this
+ * is a runtime edge.
+ *
+ * So: one copy inside the CLI, imported by both call sites, rather than the two
+ * that prompted the deduplication in the first place. If the CLI ever gains a
+ * general way to reach `packages/node/*` at bootstrap time, this file is what
+ * should go.
+ */
+/**
+ * Chunked because `String.fromCharCode(...bytes)` is a spread: a tarball-sized
+ * array blows the argument limit and throws `RangeError: Maximum call stack size
+ * exceeded`. 0x8000 is the size the CLI's publish path has always used.
+ */
+export function base64Encode(bytes) {
+    let str = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        str += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(str);
+}
+export function base64Decode(text) {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}

package/lib/utils/cli-runtime-closure.d.ts

@@ -1,4 +1,65 @@
 import type { Workspace } from '@gjsify/workspace';
+/**
+ * Literal module specifiers of `code`: static `import`/`export … from`, plus
+ * `import('<literal>')`.
+ *
+ * acorn rather than a regex — see the header. `allowHashBang` because the CLI's
+ * own entry is a bin (`#!/usr/bin/env node`), and a parse failure yields NO
+ * specifiers, which under-selects rather than mis-selects.
+ */
+export interface SpecifierNode {
+    type?: string;
+    value?: unknown;
+    expressions?: unknown[];
+    quasis?: Array<{
+        value?: {
+            cooked?: unknown;
+        };
+    }>;
+}
+/**
+ * The string a node names statically, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `utils/ship/gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
+ */
+export declare function staticStringValue(node: SpecifierNode | undefined): string | null;
+/** One node of the walk: whatever acorn produced, seen as a bag of properties. */
+export type AstNode = {
+    type?: string;
+} & Record<string, unknown>;
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the two readers of a built bundle
+ * would drift apart: {@link moduleSpecifiers} answers "what does this file
+ * import" and `utils/ship/gi-namespaces.ts` answers "which GI namespaces does
+ * it load", and the second question has an answer the first cannot see — a
+ * `--app node` bundle carries no `gi://` specifier at all, only the
+ * `requireGi()` calls the bundler rewrote them into. One walker, two readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export declare function walkModuleAst(code: string, visit: (node: AstNode) => void): void;
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`utils/ship/gi-namespaces.ts`).
+ */
+export declare function importedSpecifier(node: AstNode): string | null;
 export declare function moduleSpecifiers(code: string): string[];
 export interface CliRuntimeClosureOptions {
     /**

package/lib/utils/cli-runtime-closure.js

@@ -79,14 +79,19 @@ function splitWorkspaceSpecifier(specifier, byName) {
     return null;
 }
 /**
- * The string a module specifier node names, or `null` when it is computed.
+ * The string a node names statically, or `null` when it is computed.
  *
  * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
  * skipping it is not hypothetical: the minifier rewrites `await
  * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
  * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `utils/ship/gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
  */
-function literalSpecifier(node) {
+export function staticStringValue(node) {
     if (node?.type === 'Literal')
         return typeof node.value === 'string' ? node.value : null;
     if (node?.type === 'TemplateLiteral' && node.expressions?.length === 0) {
@@ -95,39 +100,71 @@ function literalSpecifier(node) {
     }
     return null;
 }
-export function moduleSpecifiers(code) {
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the two readers of a built bundle
+ * would drift apart: {@link moduleSpecifiers} answers "what does this file
+ * import" and `utils/ship/gi-namespaces.ts` answers "which GI namespaces does
+ * it load", and the second question has an answer the first cannot see — a
+ * `--app node` bundle carries no `gi://` specifier at all, only the
+ * `requireGi()` calls the bundler rewrote them into. One walker, two readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export function walkModuleAst(code, visit) {
     let ast;
     try {
         ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
     }
     catch {
-        return [];
+        return;
     }
-    const out = [];
-    const visit = (node) => {
+    const descend = (node) => {
         if (!node || typeof node !== 'object')
             return;
         if (Array.isArray(node)) {
             for (const child of node)
-                visit(child);
+                descend(child);
             return;
         }
         const n = node;
-        if (n.type === 'ImportDeclaration' ||
-            n.type === 'ExportNamedDeclaration' ||
-            n.type === 'ExportAllDeclaration' ||
-            n.type === 'ImportExpression') {
-            const specifier = literalSpecifier(n.source);
-            if (specifier !== null)
-                out.push(specifier);
-        }
+        visit(n);
         for (const [key, value] of Object.entries(n)) {
             if (key === 'type' || key === 'start' || key === 'end' || key === 'loc')
                 continue;
-            visit(value);
+            descend(value);
         }
     };
-    visit(ast);
+    descend(ast);
+}
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`utils/ship/gi-namespaces.ts`).
+ */
+export function importedSpecifier(node) {
+    if (node.type !== 'ImportDeclaration' &&
+        node.type !== 'ExportNamedDeclaration' &&
+        node.type !== 'ExportAllDeclaration' &&
+        node.type !== 'ImportExpression') {
+        return null;
+    }
+    return staticStringValue(node.source);
+}
+export function moduleSpecifiers(code) {
+    const out = [];
+    walkModuleAst(code, (node) => {
+        const specifier = importedSpecifier(node);
+        if (specifier !== null)
+            out.push(specifier);
+    });
     return out;
 }
 /** The file a relative specifier names, probing the extensionless spellings Node accepts. */

package/lib/utils/double-dash-args.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Everything after the `--` separator, as an argv.
+ *
+ * @param args a yargs-parsed argument object from a command whose builder sets
+ *   `parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })`
+ * @throws if an entry is not a string, i.e. if that configuration is missing
+ */
+export declare function doubleDashArgs(args: object): string[];

package/lib/utils/double-dash-args.js

@@ -0,0 +1,64 @@
+// The argv a caller wrote after `--`, read back off yargs.
+//
+// THE INCIDENT (#1531). `foreach.ts` and `run.ts` each read `args['--']` and
+// narrowed it with `.filter((v): v is string => typeof v === 'string')`. That
+// reads like a type narrowing and is a DELETION: yargs types a bare number in
+// its `populate--` array as a `number`, so the value disappears and the option
+// in front of it swallows the next flag. Measured against this repo's own
+// yargs 18.0.0:
+//
+//   in    : gjsify publish --verify-timeout 5 --tag latest
+//   raw   : ["gjsify","publish","--verify-timeout",5,"--tag","latest"]
+//   filter: ["gjsify","publish","--verify-timeout","--tag","latest"]
+//
+// That argv shipped: `npm:publish` passes `--verify-timeout 5 --tag latest`,
+// and release run 33804937881 echoed `--verify-timeout --tag latest` 209 times
+// — `--verify-timeout` taking `--tag` as its value, `latest` a stray
+// positional, `--tag latest` gone. Nobody noticed because npm's default
+// dist-tag IS `latest`, which is luck rather than design.
+//
+// TWO HALVES, AND THE FIRST ONE IS THE FIX. A coercion here (`String(v)`) would
+// recover the value and still lose its SPELLING — measured against yargs 18.0.0,
+// `1.0` comes back as 1, `0.10` as 0.1, `0x10` as 16 and `1e3` as 1000, and an
+// argv is text, not arithmetic. (A leading zero is NOT in that set: `007` stays
+// the string yargs was given. It reads like the obvious example and is the one
+// shape here that never broke.) So the parse is corrected at
+// the source: every command that sets `populate--` also sets
+// `parse-positional-numbers: false`, which leaves `_`, the variadic positionals
+// and the `--` tail as the strings the user typed while option values declared
+// `type: 'number'` are still parsed (measured: `--jobs 4` stays `4` the number).
+//
+// This function is the second half. It does NOT coerce — with the parser
+// configured as above a non-string cannot arrive, so one that does means the
+// configuration was dropped, and that is the failure to name rather than to
+// paper over. A silent `.filter()` over a parser-produced array is the wrong
+// tool wherever the array is data rather than a union.
+//
+// ONE reader for all of it, because there were three and they disagreed:
+// `foreach.ts` (twice) and `run.ts` filtered, `dlx.ts` coerced. The drifted
+// copies are the ones that shipped the wrong argv.
+/**
+ * Everything after the `--` separator, as an argv.
+ *
+ * @param args a yargs-parsed argument object from a command whose builder sets
+ *   `parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })`
+ * @throws if an entry is not a string, i.e. if that configuration is missing
+ */
+export function doubleDashArgs(args) {
+    const raw = args['--'];
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new Error(`gjsify: internal error — yargs' \`--\` slot holds a ${typeof raw} rather than an array, so the ` +
+            'arguments after `--` cannot be forwarded. The command builder must set ' +
+            "`parserConfiguration({ 'populate--': true })`.");
+    }
+    return raw.map((value, index) => {
+        if (typeof value === 'string')
+            return value;
+        throw new Error(`gjsify: internal error — the argument after \`--\` at position ${index} arrived as a ` +
+            `${typeof value} (${String(value)}) instead of a string, so forwarding it would change what ` +
+            'the caller wrote. The command builder must set ' +
+            "`parserConfiguration({ 'parse-positional-numbers': false })` alongside `populate--`.");
+    });
+}