@gjsify/cli 0.36.0 → 0.38.0

package/lib/config.d.ts

@@ -10,5 +10,19 @@ export declare class Config {
     private readPackageJSON;
     /** Loads tsconfig.json of the current project */
     private readTSConfig;
+    /**
+     * The globals policy for a `gjsify run --node-script` bundle, resolved from the
+     * package that OWNS THE SCRIPT — not the cwd, which during a monorepo build is the
+     * repo root. `gjsify.nodeScript` overrides either key (see `ConfigData.nodeScript`).
+     *
+     * CONFIG AND NOT A FLAG because on a host with no `node` the caller is a
+     * `package.json` spelling `node scripts/x.mjs`, re-entering the CLI through the shim
+     * `writeNodeShim()` writes: no call site to hang a flag on, on exactly the hosts this
+     * exists for.
+     */
+    forNodeScript(scriptPath: string): Promise<{
+        globals?: string;
+        excludeGlobals?: string[];
+    }>;
     forBuild(cliArgs: ArgumentsCamelCase<CliBuildOptions>): Promise<ConfigData>;
 }

package/lib/config.js

@@ -1,6 +1,6 @@
 import { APP_NAME } from './constants.js';
 import { cosmiconfig } from 'cosmiconfig';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildAppForRuntime } from './utils/runtimes.js';
@@ -216,6 +216,23 @@ export class Config {
         const tsconfig = getTsconfig(dirPath)?.config || {};
         return tsconfig;
     }
+    /**
+     * The globals policy for a `gjsify run --node-script` bundle, resolved from the
+     * package that OWNS THE SCRIPT — not the cwd, which during a monorepo build is the
+     * repo root. `gjsify.nodeScript` overrides either key (see `ConfigData.nodeScript`).
+     *
+     * CONFIG AND NOT A FLAG because on a host with no `node` the caller is a
+     * `package.json` spelling `node scripts/x.mjs`, re-entering the CLI through the shim
+     * `writeNodeShim()` writes: no call site to hang a flag on, on exactly the hosts this
+     * exists for.
+     */
+    async forNodeScript(scriptPath) {
+        const { config } = await this.load(dirname(scriptPath));
+        return {
+            globals: config.nodeScript?.globals ?? config.globals,
+            excludeGlobals: config.nodeScript?.excludeGlobals ?? config.excludeGlobals,
+        };
+    }
     async forBuild(cliArgs) {
         const configFile = await this.load(process.cwd());
         const configData = { ...configFile.config };

package/lib/templates/install.mjs.tmpl

@@ -1,40 +1,21 @@
 #!/usr/bin/env -S gjs -m
 /**
- * gjsify universal installer — bootstraps `@gjsify/cli` (or any GJS app
- * published to npm) on a system that has only `gjs` (and `curl`/`wget`)
- * available, without requiring Node.js or `npm`.
+ * gjsify universal installer — bootstraps `@gjsify/cli` (or any GJS app on npm)
+ * on a system that has only `gjs` and libsoup: no Node, no npm. Decision and
+ * history: docs/adr/0002-bootstrap-bundle-minimization.md.
  *
- * Usage:
- *   gjs -m install.mjs                    # install / update @gjsify/cli
- *   gjs -m install.mjs --target @scope/x  # install any other GJS-runnable npm package
- *   gjs -m install.mjs --tag next         # pick an npm dist-tag or pinned version
- *   gjs -m install.mjs --force            # reinstall even if already present
- *   gjs -m install.mjs --help
+ * Two stages: download a self-contained GJS bundle of `@gjsify/cli`
+ * (`cli.gjs.mjs`) from this repo's GitHub releases and verify its SHA-256, then
+ * spawn it as `gjs -m <bundle> install -g <target>@<tag>`. Dependency
+ * resolution, native prebuilds, lockfiles and the `~/.local/bin` launchers all
+ * live in that bundle — this bootstrapper re-implements none of it on purpose.
  *
- * How it works (two-stage bootstrap):
- *   1. Download a small self-contained GJS bundle of the @gjsify/cli
- *      (`cli.gjs.mjs`) from this repo's GitHub releases. Verify SHA-256.
- *   2. Spawn that bundle: `gjs -m <bundle> install -g <target>@<tag>`. The
- *      bundle handles transitive dependency resolution, native prebuilds,
- *      lockfiles, and the `~/.local/bin` launchers — all the things this
- *      thin bootstrapper deliberately does NOT re-implement.
+ * `gjsify generate-installer` re-emits this file for end-user GJS apps with the
+ * marked constants substituted.
  *
- * Generated by `gjsify generate-installer` for end-user GJS apps: in that
- * mode the constants below (BOOTSTRAP_URL, DEFAULT_TARGET, DEFAULT_BIN_NAME)
- * are pre-substituted to the consumer's package + custom bootstrap URL.
- *
- * Test hooks (set by tests/e2e/install-script/run.mjs):
- *   GJSIFY_INSTALL_BOOTSTRAP_URL  override the cli.gjs.mjs download origin
- *                                 (accepts file:// for offline tests)
- *   GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL  override the .sha256 companion URL.
- *                                 An EMPTY string is the only way to install
- *                                 without verification, and it warns loudly; a
- *                                 digest URL that is set but unreachable is a
- *                                 hard failure, never a silent downgrade.
- *   GJSIFY_GLOBAL_PREFIX          override install prefix (forwarded to cli)
- *   GJSIFY_GLOBAL_BIN_DIR         override bin dir (forwarded to cli)
- *   GJSIFY_INSTALL_REGISTRY       override npm registry (forwarded as npm_config_registry)
- *   GJSIFY_INSTALL_BOOTSTRAP_CACHE  override the bootstrap cache dir
+ * `--help` documents the user-facing flags and env vars. Two more exist only for
+ * tests/e2e/install-script/run.mjs: GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL and
+ * GJSIFY_INSTALL_BOOTSTRAP_CACHE.
  */
 
 import GLib from 'gi://GLib';
@@ -53,17 +34,16 @@ const DEFAULT_BOOTSTRAP_SHA256_URL = `${DEFAULT_BOOTSTRAP_URL}.sha256`;
 
 const USER_AGENT = 'gjsify-installer/1.0';
 
-// The bootstrap cache is CONTENT-ADDRESSED: `cli-<sha256>.gjs.mjs`. See
-// `resolveBootstrap()` for why the digest, not a fixed name, keys it.
+// Content-addressed cache: `cli-<sha256>.gjs.mjs`. Why the digest and not a
+// fixed name keys it: `resolveBootstrap()`.
 const CACHE_PREFIX = 'cli-';
 const CACHE_SUFFIX = '.gjs.mjs';
 
 /**
- * Under `--fetch-only` the ONLY thing on stdout must be the bundle path, so
- * progress goes to stderr instead. A caller does
- * `BOOTSTRAP=$(gjs -m install.mjs --fetch-only)`, and one stray `info()` line
- * would make that a path with a log message glued to the front — a failure that
- * surfaces as a confusing "file not found" rather than as bad output.
+ * Under `--fetch-only` stdout carries nothing but the bundle path, so progress
+ * goes to stderr. A caller does `BOOTSTRAP=$(gjs -m install.mjs --fetch-only)`,
+ * where one stray `info()` line glues a log message to the front of the path and
+ * surfaces later as a confusing "file not found".
  */
 let logToStderr = false;
 
@@ -139,7 +119,7 @@ Examples:
 }
 
 function checkGjsVersion() {
-    // imports.system.version is packed: major*10000 + minor*100 + micro
+    // `system.version` is packed: major*10000 + minor*100 + micro
     const v = system?.version;
     if (typeof v !== 'number') return;
     const major = Math.floor(v / 10000);
@@ -154,6 +134,62 @@ function checkGjsVersion() {
     }
 }
 
+/** Total attempts per URL, and the wait before each retry. Override for tests / slow links. */
+const FETCH_ATTEMPTS = Number(GLib.getenv('GJSIFY_INSTALL_FETCH_ATTEMPTS') || '5');
+const RETRY_BACKOFF_MS = [1000, 2000, 4000, 8000];
+
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        GLib.timeout_add(GLib.PRIORITY_DEFAULT, ms, () => {
+            resolve();
+            return GLib.SOURCE_REMOVE;
+        });
+    });
+}
+
+async function fetchOnce(session, url, { forceHttp1 = false } = {}) {
+    const message = Soup.Message.new('GET', url);
+    message.request_headers.append('User-Agent', USER_AGENT);
+    // The failure this retries against announces its own protocol — libsoup reports it
+    // verbatim as `HTTP/2 Error: NO_ERROR`, a stream closed mid-response. Retrying over
+    // HTTP/1.1 sidesteps the multiplexing that produces it, so the first attempt keeps the
+    // faster protocol and every retry drops to the one that cannot fail that way. Guarded:
+    // `set_force_http1` is libsoup 3.4+, and this script must still run on older hosts.
+    if (forceHttp1 && typeof message.set_force_http1 === 'function') message.set_force_http1(true);
+    const bytes = await session.send_and_read_async(message, GLib.PRIORITY_DEFAULT, null);
+    const status = message.get_status();
+    if (status !== Soup.Status.OK) {
+        const err = new Error(`HTTP ${status} from ${url}`);
+        err.httpStatus = status;
+        throw err;
+    }
+    return bytes.get_data();
+}
+
+/**
+ * A dropped connection is a HICCUP; an HTTP answer is an ANSWER.
+ *
+ * THE INCIDENT. `https://github.com/gjsify/gjsify/releases/latest/download/…` dropped
+ * HTTP/2 connections for a stretch on 2026-08-12 and took four CI jobs across two PRs
+ * with it, each dying in `gjsify-setup` before a line of the change under test ran.
+ * Measured from a workstation during the same window: one in three `curl` attempts
+ * returned `Connection died, tried 5 times before giving up`. A single-shot fetch turns
+ * that into "Refusing to install an UNVERIFIED bootstrap bundle", which reads like the
+ * digest is missing or hostile — the one message that must never be a false alarm, since
+ * the correct response to it is to disable verification.
+ *
+ * So retries are scoped to what CANNOT be an answer: a transport failure (no status at
+ * all), plus 429 and 5xx. A 404 is the registry saying the asset does not exist and a 403
+ * is it saying no; retrying either would only delay the same result while making a real
+ * outage look like a hang.
+ *
+ * FIVE attempts, not three, and the numbers come from a run rather than a preference:
+ * with three the CI log showed `retry 2/3` and `retry 3/3` and still failed, because each
+ * attempt takes ~20 s to give up — so the 500ms/1500ms backoff was noise beside it and the
+ * whole sequence covered barely 40 s of a longer wobble. 1/2/4/8 s over five attempts
+ * covers about two minutes. Beyond that it is an outage, not a hiccup, and waiting longer
+ * only turns a clear failure into a hang.
+ */
 async function fetchBytes(session, url) {
     if (url.startsWith('file://')) {
         const path = url.slice('file://'.length);
@@ -161,14 +197,22 @@ async function fetchBytes(session, url) {
         const [, bytes] = file.load_contents(null);
         return bytes;
     }
-    const message = Soup.Message.new('GET', url);
-    message.request_headers.append('User-Agent', USER_AGENT);
-    const bytes = await session.send_and_read_async(message, GLib.PRIORITY_DEFAULT, null);
-    const status = message.get_status();
-    if (status !== Soup.Status.OK) {
-        throw new Error(`HTTP ${status} from ${url}`);
+    const attempts = Number.isFinite(FETCH_ATTEMPTS) && FETCH_ATTEMPTS >= 1 ? FETCH_ATTEMPTS : 1;
+    let lastErr = null;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fetchOnce(session, url, { forceHttp1: attempt > 1 });
+        } catch (err) {
+            lastErr = err;
+            const status = err.httpStatus;
+            const retriable = status === undefined || status === 429 || status >= 500;
+            if (!retriable || attempt === attempts) break;
+            const wait = RETRY_BACKOFF_MS[Math.min(attempt - 1, RETRY_BACKOFF_MS.length - 1)];
+            info(`Fetch of ${url} failed (${err.message}) — retry ${attempt + 1}/${attempts} in ${wait}ms`);
+            await sleepMs(wait);
+        }
     }
-    return bytes.get_data();
+    throw lastErr;
 }
 
 function sha256Hex(bytes) {
@@ -197,18 +241,17 @@ function readBytesOrNull(path) {
         const [, bytes] = Gio.File.new_for_path(path).load_contents(null);
         return bytes;
     } catch {
-        // An absent — or unreadable, e.g. truncated by a killed earlier run —
-        // cache entry is a MISS, not an error. `load_contents` is a real
-        // `throws="1"` GIR call, so this catch has a genuine throw path.
+        // An absent or unreadable entry (truncated by a killed earlier run) is a
+        // MISS, not an error. `load_contents` is `throws="1"`, so this catch has
+        // a genuine throw path.
         return null;
     }
 }
 
 /**
- * Drop every other cached bootstrap so the content-addressed cache stays
- * bounded. Each entry is a ~6.6 MB bundle and the digest changes with every
- * release — without this, keying the cache by content would trade "the cache
- * can never be warm" for "the cache grows forever".
+ * Drop every other cached bootstrap. Each entry is a ~6.6 MB bundle and the
+ * digest changes every release, so without pruning, content-addressing would
+ * trade "the cache can never be warm" for "the cache grows forever".
  */
 function pruneCache(dir, keepBasename) {
     const children = Gio.File.new_for_path(dir).enumerate_children('standard::name', Gio.FileQueryInfoFlags.NONE, null);
@@ -221,24 +264,53 @@ function pruneCache(dir, keepBasename) {
     }
 }
 
+/**
+ * The newest cached bootstrap whose CONTENTS hash to the digest in its own name, or
+ * null. Re-hashing is the whole point: the filename is a claim, and a truncated entry
+ * keeps its name — the same reason the warm-cache path below re-hashes rather than
+ * trusting it.
+ */
+function newestCachedBootstrap(dir) {
+    let best = null;
+    let children;
+    try {
+        children = Gio.File.new_for_path(dir).enumerate_children(
+            'standard::name,time::modified',
+            Gio.FileQueryInfoFlags.NONE,
+            null,
+        );
+    } catch {
+        // No cache directory yet — `enumerate_children` is `throws="1"`.
+        return null;
+    }
+    for (;;) {
+        const entry = children.next_file(null);
+        if (entry === null) break;
+        const name = entry.get_name();
+        if (!name.startsWith(CACHE_PREFIX) || !name.endsWith(CACHE_SUFFIX)) continue;
+        const claimed = name.slice(CACHE_PREFIX.length, name.length - CACHE_SUFFIX.length).toLowerCase();
+        if (!/^[0-9a-f]{64}$/.test(claimed)) continue;
+        const path = GLib.build_filenamev([dir, name]);
+        const bytes = readBytesOrNull(path);
+        if (!bytes || sha256Hex(bytes).toLowerCase() !== claimed) continue;
+        const mtime = entry.get_modification_date_time()?.to_unix() ?? 0;
+        if (!best || mtime > best.mtime) best = { path, basename: name, mtime };
+    }
+    return best;
+}
+
 /**
  * Resolve a VERIFIED bootstrap bundle and return its path.
  *
- * The digest is fetched BEFORE the bundle, and the cache is keyed by it. That
- * ordering is the mechanism, not an optimisation — it fixes two independent
- * defects that both came from doing it the other way round:
- *
- *   1. Verification was skippable by anyone who could break ONE request. The
- *      bundle was downloaded first and verified after, and a failed `.sha256`
- *      fetch merely logged "skipping verification" and carried on — so a proxy,
- *      a 404, or a captive portal silently downgraded the install to no
- *      verification at all. Fetching the digest first makes that impossible:
- *      no digest, no install.
- *   2. The cache could never be warm. It wrote a fixed `cli.gjs.mjs` and never
- *      read it back, so every run re-downloaded ~6.6 MB. A content-addressed
- *      name lets a matching entry short-circuit the download entirely.
+ * Fetching the digest BEFORE the bundle, and keying the cache by it, is the
+ * mechanism rather than an optimisation; the reverse order cost two defects.
+ * Verifying after downloading made verification skippable by anyone who could
+ * break ONE request — a failed `.sha256` fetch logged "skipping verification"
+ * and carried on, so a proxy, a 404 or a captive portal silently downgraded the
+ * install. And a fixed `cli.gjs.mjs` name that was never read back meant every
+ * run re-downloaded ~6.6 MB; a content-addressed name short-circuits that.
  *
- * Skipping verification is still possible, but only as an EXPLICIT act
+ * Skipping verification remains possible only as an EXPLICIT act
  * (`GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL=''`), and it says so on stderr.
  */
 async function resolveBootstrap(session, bootstrapUrl, sha256Url) {
@@ -249,6 +321,26 @@ async function resolveBootstrap(session, bootstrapUrl, sha256Url) {
         try {
             sumBytes = await fetchBytes(session, sha256Url);
         } catch (err) {
+            // Before refusing: a bundle already in the cache carries its own digest in
+            // its NAME, and re-hashing the bytes proves the name. Those bytes were
+            // verified against a digest that WAS fetched, on an earlier run — so reusing
+            // them installs nothing unverified. That is a different thing from the defect
+            // this function's header records, where a failed digest fetch waved a FRESH
+            // download through with no digest at all.
+            //
+            // What it does concede is FRESHNESS: someone who can block the network can
+            // hold you on the release you already have. So it is loud, it names the
+            // digest, and it only ever runs after the retries above are exhausted — which
+            // on 2026-08-12 was a GitHub release CDN dropping every connection from the
+            // CI runners for over an hour, with a warm cache sitting right there, unusable
+            // because the digest fetch comes first.
+            const cached = newestCachedBootstrap(cacheDir());
+            if (cached) {
+                error(`Could not fetch ${sha256Url}: ${err.message}`);
+                info(`Falling back to the cached bootstrap verified earlier: ${cached.basename}`);
+                info('It may be OLDER than `latest` — re-run once the network recovers.');
+                return cached.path;
+            }
             error(`Could not fetch ${sha256Url}: ${err.message}`);
             error('Refusing to install an UNVERIFIED bootstrap bundle.');
             error("To bootstrap without verification, set GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL='' explicitly.");
@@ -313,14 +405,12 @@ function buildSpec(target, tag) {
 }
 
 async function runInstall(bundlePath, spec) {
-    // `gjsify install -g <spec>` is always idempotent — it rewrites the tree
-    // unconditionally. There is no separate "force" flag to forward; the
-    // installer's own `--force` is satisfied by the fact that we always
-    // re-download the bootstrap and re-invoke the CLI.
+    // `gjsify install -g <spec>` rewrites the tree unconditionally, so there is
+    // no force flag to forward and `--force` needs nothing here.
     info(`Running: gjs -m <bootstrap> install -g ${spec}`);
     const argv = ['gjs', '-m', bundlePath, 'install', '-g', spec];
-    // Forward env vars verbatim so override paths set by tests / power-users
-    // reach the spawned CLI.
+    // No `envp`: the launcher inherits ours, so override env vars set by tests
+    // and power-users reach the spawned CLI.
     const launcher = new Gio.SubprocessLauncher({
         flags: Gio.SubprocessFlags.NONE,
     });
@@ -349,7 +439,6 @@ async function main() {
     }
 
     if (opts.fetchOnly) {
-        // The one thing on stdout. Everything above went to stderr.
         print(bundlePath);
         exit(0);
     }

package/lib/types/cli-build-options.d.ts

@@ -1,106 +1,72 @@
 import type { App } from '@gjsify/rolldown-plugin-gjsify';
 export interface CliBuildOptions {
-    /**
-     * This is an array of files that each serve as an input to the bundling algorithm.
-     * @see https://esbuild.github.io/api/#entry-points
-     */
+    /** Input files to the bundling algorithm. */
     entryPoints?: string[];
-    /** Switch on the verbose mode */
     verbose?: boolean;
-    /**
-     * When enabled, the generated code will be minified instead of pretty-printed.
-     * @see https://esbuild.github.io/api/#minify
-     */
+    /** Minify the generated code instead of pretty-printing it. */
     minify?: boolean;
-    /**
-     * Override the default output format.
-     * @see https://esbuild.github.io/api/#format
-     */
+    /** Override the default output format. */
     format?: 'iife' | 'esm' | 'cjs';
-    /** Use this if you want to build an application or test, the platform node is usually only used internally to build the tests for Gjsify */
+    /** Build an application or test. `node` is mostly internal, for gjsify's tests. */
     app?: App;
-    /** Use this if you want to build a library for Gjsify */
+    /** Build a library rather than an application. */
     library?: boolean;
-    /**
-     * This option sets the output file name for the build operation.
-     * This is only applicable if there is a single entry point.
-     * If there are multiple entry points, you must use the outdir option instead to specify an output directory.
-     * @see https://esbuild.github.io/api/#outfile
-     */
+    /** Output file name. Single entry point only — otherwise use `outdir`. */
     outfile?: string;
-    /**
-     * This option sets the output directory for the build operation.
-     * @see https://esbuild.github.io/api/#outdir
-     */
     outdir?: string;
-    /** Enables TypeScript types on runtime using Deepkit's type compiler */
+    /** Enables TypeScript types at runtime using Deepkit's type compiler. */
     reflection?: boolean;
-    /**
-     * The log level can be changed to prevent esbuild from printing warning and/or error messages to the terminal
-     * @see https://esbuild.github.io/api/#log-level
-     */
+    /** How much the bundler prints to the terminal. */
     logLevel: 'silent' | 'error' | 'warning' | 'info' | 'debug' | 'verbose';
-    /** An array of glob patterns to exclude matches and aliases */
+    /** Glob patterns excluding matches and aliases. */
     exclude?: string[];
     /**
-     * Inject a console shim into GJS builds for clean output (no GLib prefix, ANSI colors work).
-     * Use --no-console-shim to disable. Only applies to GJS app builds. Default: true.
+     * Inject a console shim into GJS app builds for clean output (no GLib prefix,
+     * working ANSI colors). Disable with `--no-console-shim`. Default: true.
      */
     consoleShim?: boolean;
     /**
-     * Comma-separated list of global identifiers your code needs (e.g.
-     * `"fetch,Buffer,process,URL,crypto"`). Each identifier is mapped to the
-     * corresponding `@gjsify/<pkg>/register` module and injected into the
-     * bundle. Only applies to GJS app builds.
+     * Comma-separated global identifiers the code needs, e.g.
+     * `"fetch,Buffer,process,URL,crypto"`. Each maps to the corresponding
+     * `@gjsify/<pkg>/register` module, injected into the bundle. GJS app builds only.
      */
     globals?: string;
     /**
-     * Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output file and mark
-     * it executable (chmod 755). Only applies to GJS app builds with a single
-     * `--outfile`. Default: false.
+     * Prepend a `#!/usr/bin/env -S gjs -m` shebang and chmod 755. GJS app builds with
+     * a single `--outfile` only. Default: false.
      */
     shebang?: boolean;
     /**
-     * Module names that should NOT be bundled. Each name remains as a literal
-     * `import`/`require` in the output and is resolved by the runtime against
-     * its own `node_modules` (or equivalent) at execution time.
-     *
-     * Repeat the flag or pass a comma-separated value:
-     * `--external typedoc,prettier --external typescript`. Glob-style wildcards
-     * (`@inquirer/*`, `lodash-*`) are forwarded as-is to esbuild.
-     *
-     * @see https://esbuild.github.io/api/#external
+     * Module names that must NOT be bundled: each stays a literal `import`/`require`
+     * in the output, resolved by the runtime at execution time. Repeat the flag or
+     * pass a comma-separated value (`--external typedoc,prettier --external
+     * typescript`); glob-style wildcards (`@inquirer/*`, `lodash-*`) pass through to
+     * the bundler unchanged.
      */
     external?: string[];
     /**
-     * Substitute compile-time constants in the bundle. Each entry is a
-     * `KEY=VALUE` pair where `VALUE` is an arbitrary JS expression — string
-     * literals must be quoted (`--define VERSION='"1.2.3"'`). Useful for
-     * upstream packages that read a build-time constant via
+     * Compile-time constants as `KEY=VALUE`, where `VALUE` is an arbitrary JS
+     * expression — string literals must be quoted (`--define VERSION='"1.2.3"'`).
+     * For upstream packages reading a build-time constant via
      * `typeof __FOO__ !== 'undefined'`.
-     *
-     * @see https://esbuild.github.io/api/#define
      */
     define?: string[];
     /**
-     * Map module specifiers to alternative targets at bundle time. Each entry
-     * is `FROM=TO` where `FROM` is the imported package name and `TO` is the
-     * substitute (typically `@gjsify/empty` to drop a heavy dep that the test
-     * scenario never executes). Layered on top of the built-in alias map.
+     * Remap module specifiers at bundle time as `FROM=TO`, typically to
+     * `@gjsify/empty` to drop a heavy dep the scenario never executes. Layered on top
+     * of the built-in alias map.
      */
     alias?: string[];
     /**
-     * Comma-separated global identifiers to remove from the auto-detected set.
-     * Useful for false positives from dead browser-compat code in npm deps
-     * whose polyfills require unavailable native libraries.
-     * Example: `--exclude-globals fetch,XMLHttpRequest`
+     * Comma-separated global identifiers to drop from the auto-detected set — for
+     * false positives from dead browser-compat code in npm deps whose polyfills need
+     * unavailable native libraries. Example: `--exclude-globals fetch,XMLHttpRequest`.
      */
     excludeGlobals?: string[];
     /**
-     * Watch source files and rebuild on change. Logs each rebuild with
-     * duration; SIGINT/SIGTERM cleanly closes the watcher. Only valid with
-     * `--app gjs|node|browser` (rejected with `--library`). Requires the
-     * npm `rolldown` engine — run under Node.
+     * Watch and rebuild on change; SIGINT/SIGTERM closes the watcher cleanly. Valid
+     * only with `--app gjs|node|browser`, rejected with `--library`, and requires the
+     * npm `rolldown` engine — so run it under Node.
      */
     watch?: boolean;
 }

package/lib/types/command.d.ts

@@ -8,19 +8,16 @@ export interface Command<T = unknown, U = T> {
     deprecated?: boolean | string;
 }
 /**
- * A command that definitely runs something — the shape of every command except
- * the builder-only parents.
+ * A command that definitely runs something — every command except the
+ * builder-only parents. Annotate any command a standalone entry invokes directly.
  *
- * WHY IT EXISTS: `Command.handler` has to stay optional for parent commands,
- * but that optionality then lands on every CALL site, including the ones
- * outside `cli-app.ts`'s yargs registration where a missing handler would be a
- * silent no-op rather than a type error. `src/affected-entry.ts` — the entry
- * the committed `dist/affected.gjs.mjs` is built from — invoked
- * `affectedCommand.handler(...)` through a cast that suppressed exactly that,
- * and nothing noticed for as long as the package's tsconfig scoped the compile
- * to the import closure of `src/index.ts`. Annotate a command that a standalone
- * entry invokes directly with this type, and the guarantee is in the type
- * instead of in a cast.
+ * `Command.handler` must stay optional for parent commands, but that optionality
+ * then lands on every CALL site, including those outside `cli-app.ts`'s yargs
+ * registration, where a missing handler is a silent no-op rather than a type
+ * error. `src/affected-entry.ts` — the entry `dist/affected.gjs.mjs` is built
+ * from — invoked `affectedCommand.handler(...)` through a cast that suppressed
+ * exactly that, unnoticed for as long as the tsconfig scoped the compile to the
+ * import closure of `src/index.ts`. This puts the guarantee in the type instead.
  */
 export type LeafCommand<T = unknown, U = T> = Command<T, U> & {
     handler: NonNullable<Command<T, U>['handler']>;