@gjsify/cli 0.46.0 → 0.48.0

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--`.");
+    });
+}

package/lib/utils/publish-readback.d.ts

@@ -0,0 +1,132 @@
+/** One registry answer, classified. `absent` and `error` are NOT the same fact. */
+export type ReadbackProbe = {
+    state: 'present';
+    status: number;
+    tarball: string;
+} | {
+    state: 'absent';
+    status: number;
+    detail: string;
+}
+/**
+ * We do not KNOW. A 5xx, a timeout, unparseable JSON — treating any of them
+ * as "absent" would fabricate a "never published" verdict out of a registry
+ * hiccup, the same distinction `verify-published-closure.mjs` draws between
+ * `false` and an `Error`.
+ */
+ | {
+    state: 'error';
+    status?: number;
+    detail: string;
+};
+export interface ReadbackResult {
+    /** True iff a probe saw the exact version with a tarball on it. */
+    confirmed: boolean;
+    /** Probes actually sent (≥ 1). */
+    attempts: number;
+    elapsedMs: number;
+    /** The URL that was asked, verbatim — it belongs in the failure message. */
+    url: string;
+    /** What the registry said last. On `confirmed` this is the `present` probe. */
+    last: ReadbackProbe;
+}
+export interface VerifyPublishedVersionInput {
+    /** Registry URL, with or without a trailing slash. */
+    registry: string;
+    /** Full package name including scope. */
+    name: string;
+    version: string;
+    /** Total polling budget in ms. Must be > 0 — a disabled read-back is the caller's decision. */
+    budgetMs: number;
+    /** Per-probe request timeout. Default 30 s, matching the closure script. */
+    probeTimeoutMs?: number;
+    /**
+     * The `authorization` header the PUT used, forwarded verbatim.
+     *
+     * A registry that requires a credential to READ answers 401/403 to an
+     * anonymous packument GET, which classifies as `error` — so an intact
+     * publish to GitHub Packages, an Artifactory repo or a Verdaccio with
+     * `access: $authenticated` reports `publish-unconfirmed` and, on the fatal
+     * default, exits 1 after the whole budget on a publish that worked.
+     * Measured against the first version of this file: 15 read-back GETs, every
+     * one anonymous, one second after a PUT that carried a token. Same origin,
+     * same credential, one request later — it adds no exposure the PUT did not
+     * already have.
+     */
+    authorization?: string;
+    /** Injected in tests; resolved at call time so a `globalThis.fetch` stub is honoured. */
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Called once per probe under `GJSIFY_PUBLISH_DEBUG`. */
+    log?: (msg: string) => void;
+}
+/** Delay before probe `round + 2`. Past the table's end the last value repeats. */
+export declare function backoffFor(round: number): number;
+/**
+ * A probe's request timeout: what was configured, never more than the budget has
+ * left to spend — but never less than a probe needs to answer.
+ *
+ * Configured and budget are otherwise independent, and that makes
+ * `--verify-timeout 5` — what the 199-package sweep passes — a promise the code
+ * does not keep: one unanswered request may block for the 30 s default, six times
+ * the budget it was given, and 199 of those cost ~100 min against the ~11% the
+ * deferral is argued on. Clamping bounds the wall clock at
+ * `budget + MIN_PROBE_TIMEOUT_MS` instead. The floor is the other half of the
+ * same honesty: clamping all the way to zero traded a 30 s overshoot for an
+ * `error` verdict on a probe that was about to return the 404 (measured — it
+ * turned the incident's own e2e row from `absent: 404` into `request failed
+ * (This operation was aborted)`).
+ */
+export declare function probeTimeoutFor(configuredMs: number, remainingMs: number): number;
+/**
+ * Default polling budget: 300 s.
+ *
+ * The measured maximum lag between a 2xx and the registry recording the version
+ * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
+ * turns npm's normal queueing into a false red — and a false red at release time
+ * costs a manual re-run of a workflow that did its job. 300 s clears that
+ * maximum and is still short enough that a genuinely lost write is reported by
+ * the job that lost it rather than by a later sweep.
+ *
+ * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
+ * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
+ * middle ones, which is the shape of a distribution cut off by the observation
+ * rather than one decaying to zero. One release is one sample, so a lag past
+ * 300 s is not ruled out; what makes 300 s affordable anyway is that the
+ * remediation is verified rather than assumed. The re-run this reports lands on
+ * the 409 path, and that path READS BACK too (see the conflict branch in
+ * `commands/publish.ts`), so a window that turns out to be too short costs one
+ * re-run that confirms — it does not hand back an unverified success.
+ */
+export declare const DEFAULT_VERIFY_BUDGET_MS = 300000;
+/**
+ * Poll the registry until `name@version` resolves, or the budget runs out.
+ *
+ * No side effects, no exits, no printing beyond the injected `log` — the caller
+ * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
+ */
+export declare function verifyPublishedVersion(input: VerifyPublishedVersionInput): Promise<ReadbackResult>;
+/**
+ * The unconfirmed-publish diagnostic, ready for stderr.
+ *
+ * The message has to answer three questions the incident log could not, which is
+ * why it needed the registry to reconstruct at all: what was PUT, what was asked,
+ * and what came back.
+ */
+export declare function formatUnconfirmedPublish(opts: {
+    name: string;
+    version: string;
+    putUrl: string;
+    putStatus: number;
+    putStatusText: string;
+    payloadBytes: number;
+    readback: ReadbackResult;
+    /**
+     * What npm claimed before the read-back disagreed. `accepted` is a 2xx;
+     * `already-published` is a tolerated 409, where the remediation is the
+     * opposite one — a re-run answers the same conflict.
+     */
+    claim?: 'accepted' | 'already-published';
+}): string;