@gjsify/cli 0.40.0 → 0.42.0

package/lib/utils/npm-oidc.js

@@ -80,11 +80,14 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does. Do NOT
-    // use `URL.searchParams.set` + `.href`: under GJS that serialization dropped the `audience`
-    // param, so GitHub issued an id-token with the DEFAULT audience (the repo API URL) and npm
-    // rejected an otherwise-valid token with 401 — repository/workflow_ref/sub all matched the
-    // Trusted Publisher, only `aud` was wrong.
+    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does.
+    //
+    // fixed upstream in gjsify: `URL.searchParams.set` + `.href` used to DROP the parameter under
+    // GJS — the mutation never reached the serialisation — so GitHub issued an id-token with the
+    // DEFAULT audience (the repo API URL) and npm rejected an otherwise-valid token with 401:
+    // repository/workflow_ref/sub all matched the Trusted Publisher, only `aud` was wrong. The
+    // URL live view now works, so the ban is lifted; the concatenation stays because it is what
+    // the reference implementation does, not because the alternative is broken.
     const sep = url.includes('?') ? '&' : '?';
     const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
     log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);

package/lib/utils/prune-prefix.d.ts

@@ -0,0 +1,83 @@
+import { type PlatformDeclaration, type PlatformTarget, type PlatformVerdict } from './platform-check.js';
+/** One package directory found under a prefix's `node_modules` tree. */
+export interface InstalledPackage {
+    /** `name` from its manifest, or the directory path when the manifest is unreadable. */
+    name: string;
+    version: string;
+    /** Absolute path to the package directory. */
+    dir: string;
+    /**
+     * A symlink, i.e. a workspace source tree linked into `node_modules` rather than
+     * a copy the installer extracted. Never pruned and never descended: the installer
+     * refuses to remove one for the same reason, and following it would walk the
+     * user's own sources.
+     */
+    linked: boolean;
+    /** The `os`/`cpu`/`libc` slice, absent when the manifest declares none. */
+    platform?: PlatformDeclaration;
+}
+export interface PruneEntry {
+    pkg: InstalledPackage;
+    /** Apparent size of the package directory, summed from `statSync().size`. */
+    bytes: number;
+    verdict: PlatformVerdict;
+}
+export interface PrunePlan {
+    prefix: string;
+    target: PlatformTarget;
+    /** How many package directories were examined, so an empty plan is distinguishable from an empty scan. */
+    scanned: number;
+    entries: PruneEntry[];
+    bytes: number;
+}
+export interface PruneResult {
+    plan: PrunePlan;
+    removed: PruneEntry[];
+    failed: Array<{
+        entry: PruneEntry;
+        error: string;
+    }>;
+    bytes: number;
+    /** `.bin` entries removed because they were symlinks with no target left. */
+    binLinks: string[];
+}
+/** Every package directory under `<prefix>/node_modules`, at any depth. */
+export declare function scanPrefix(prefix: string): InstalledPackage[];
+/**
+ * The packages `target` cannot use. Pure — no filesystem, no `process.*` — so every
+ * OS/arch/libc branch is decidable from any host.
+ */
+export declare function planPlatformPrune(pkgs: readonly InstalledPackage[], target: PlatformTarget): PruneEntry[];
+/** Apparent size of a directory tree — what the files claim, not what the block device spent. */
+export declare function dirBytes(dir: string): number;
+export declare function planPrune(opts: {
+    prefix: string;
+    target: PlatformTarget;
+}): PrunePlan;
+/**
+ * Remove a plan's entries.
+ *
+ * `remove` is injected so the failure path is testable without a filesystem that
+ * can fail on demand. Nothing here throws: this runs as housekeeping at the end of
+ * an install, and an install that already succeeded must not be reported as failed
+ * because a directory could not be unlinked.
+ */
+export declare function executePrune(plan: PrunePlan, opts?: {
+    dryRun?: boolean;
+    remove?: (dir: string) => void;
+}): PruneResult;
+export declare function formatPruneReport(result: PruneResult, opts: {
+    dryRun: boolean;
+    verbose: boolean;
+}): string;
+/** Why an automatic pass declined to run, or null when it may proceed. */
+export declare function automaticPruneRefusal(env: Record<string, string | undefined>, immutable: boolean): string | null;
+/**
+ * The automatic pass: prune what this install would not have placed, report one
+ * line, and never fail the install that called it.
+ */
+export declare function pruneAfterInstall(prefix: string, target: PlatformTarget, opts?: {
+    env?: Record<string, string | undefined>;
+    immutable?: boolean;
+    hint?: string;
+}): void;

package/lib/utils/prune-prefix.js

@@ -0,0 +1,333 @@
+// Remove what an install prefix holds that THIS host cannot use.
+//
+// An install prefix is a write-only union today: `applyPlatformFilter` keeps a
+// foreign-platform package from being installed, and nothing ever removes one that
+// an EARLIER install placed. Measured on a workstation whose user-global prefix was
+// created in May and whose CLI was current: 638 MB, of which `@rolldown` alone was
+// 258 MB across sixteen platform bindings on a host that can load exactly one.
+//
+// The residue is ACCRETION, not a live filter defect, and the on-disk versions are
+// what prove it: the foreign `@rolldown/binding-*` dirs were a minor version behind
+// the `rolldown` that pins all of them, and every foreign `@gjsify/*-<os>-<arch>`
+// was at the release that first SHIPPED the filter. They were written by the
+// previous CLI, during the self-update that installed the fix. A filter cannot
+// remove what predates it, which is why this exists as its own pass.
+//
+// ## What this is allowed to decide
+//
+// One rule, and it is a pure manifest read: npm's own `os`/`cpu`/`libc` fields,
+// through the SAME `checkPlatform` the installer filters with — so a pruned prefix
+// converges on what a fresh install would have placed, rather than on this module's
+// opinion. A package that declares nothing is never touched: `@rolldown/binding-
+// wasm32-wasi` is unusable here and says so nowhere, and guessing from its name is
+// how a prune starts deleting things it cannot justify.
+//
+// Reachability ("nothing installed points at this any more") would catch that one
+// and more, but it needs a record of what the prefix was ASSEMBLED FROM, which no
+// prefix carries yet. Uncertain means keep — see ADR 0025 and
+// `status/open-todos.md`.
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkPlatform, declaresPlatform, describePlatformTarget, readPlatformOverrides, } from './platform-check.js';
+/** Directory entries under `node_modules` that are never packages. */
+function isReservedEntry(name) {
+    // `.bin` holds launchers, `.gjsify-install-lock` is the LIVE cross-process lock
+    // directory — removing it mid-install would hand the prefix to a second writer.
+    return name.startsWith('.');
+}
+function readManifest(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        const platform = {
+            os: raw.os,
+            cpu: raw.cpu,
+            libc: raw.libc,
+        };
+        return {
+            name: typeof raw.name === 'string' ? raw.name : undefined,
+            version: typeof raw.version === 'string' ? raw.version : undefined,
+            platform: declaresPlatform(platform) ? platform : undefined,
+        };
+    }
+    catch {
+        // An unreadable or half-written manifest declares nothing, which makes the
+        // package un-prunable by the only rule this module has. That is the safe
+        // direction: the one thing worse than 638 MB of residue is deleting a
+        // package because its manifest could not be parsed.
+        return null;
+    }
+}
+function collect(nodeModules, out) {
+    let entries;
+    try {
+        entries = readdirSync(nodeModules, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (isReservedEntry(entry.name))
+            continue;
+        const full = join(nodeModules, entry.name);
+        if (entry.name.startsWith('@')) {
+            let scoped;
+            try {
+                scoped = readdirSync(full, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const inner of scoped) {
+                if (isReservedEntry(inner.name))
+                    continue;
+                addPackage(join(full, inner.name), out);
+            }
+            continue;
+        }
+        addPackage(full, out);
+    }
+}
+function addPackage(dir, out) {
+    let linked = false;
+    try {
+        linked = lstatSync(dir).isSymbolicLink();
+    }
+    catch {
+        return;
+    }
+    const manifest = readManifest(dir);
+    out.push({
+        name: manifest?.name ?? dir,
+        version: manifest?.version ?? '0.0.0',
+        dir,
+        linked,
+        platform: manifest?.platform,
+    });
+    // A linked package is the user's own source tree — its `node_modules` is not
+    // this prefix's to prune.
+    if (!linked)
+        collect(join(dir, 'node_modules'), out);
+}
+/** Every package directory under `<prefix>/node_modules`, at any depth. */
+export function scanPrefix(prefix) {
+    const out = [];
+    collect(join(prefix, 'node_modules'), out);
+    return out;
+}
+/**
+ * The packages `target` cannot use. Pure — no filesystem, no `process.*` — so every
+ * OS/arch/libc branch is decidable from any host.
+ */
+export function planPlatformPrune(pkgs, target) {
+    const entries = [];
+    for (const pkg of pkgs) {
+        if (pkg.linked || !pkg.platform)
+            continue;
+        const verdict = checkPlatform(pkg.platform, target);
+        if (!verdict.ok)
+            entries.push({ pkg, bytes: 0, verdict });
+    }
+    return entries;
+}
+/** Apparent size of a directory tree — what the files claim, not what the block device spent. */
+export function dirBytes(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += statSync(full).size;
+                }
+                catch {
+                    // A file that vanished mid-walk contributes nothing; a size is a
+                    // report, and refusing to produce one over a race would be worse.
+                }
+            }
+        }
+    }
+    return total;
+}
+export function planPrune(opts) {
+    const pkgs = scanPrefix(opts.prefix);
+    const entries = planPlatformPrune(pkgs, opts.target);
+    for (const entry of entries)
+        entry.bytes = dirBytes(entry.pkg.dir);
+    return {
+        prefix: opts.prefix,
+        target: opts.target,
+        scanned: pkgs.length,
+        entries,
+        bytes: entries.reduce((sum, e) => sum + e.bytes, 0),
+    };
+}
+/**
+ * Remove a plan's entries.
+ *
+ * `remove` is injected so the failure path is testable without a filesystem that
+ * can fail on demand. Nothing here throws: this runs as housekeeping at the end of
+ * an install, and an install that already succeeded must not be reported as failed
+ * because a directory could not be unlinked.
+ */
+export function executePrune(plan, opts = {}) {
+    const removed = [];
+    const failed = [];
+    const binLinks = [];
+    // `maxRetries` mirrors the installer's own removal: on Windows a handle held by
+    // a virus scanner or an indexer makes the first unlink fail and the third work.
+    const remove = opts.remove ?? ((dir) => rmSync(dir, { recursive: true, force: true, maxRetries: 10 }));
+    if (!opts.dryRun) {
+        for (const entry of plan.entries) {
+            try {
+                remove(entry.pkg.dir);
+                removed.push(entry);
+            }
+            catch (err) {
+                failed.push({ entry, error: err.message });
+            }
+        }
+        binLinks.push(...pruneDeadBinLinks(plan.prefix));
+    }
+    return {
+        plan,
+        removed,
+        failed,
+        bytes: removed.reduce((sum, e) => sum + e.bytes, 0),
+        binLinks,
+    };
+}
+/**
+ * Drop `.bin` entries that are SYMLINKS whose target is gone.
+ *
+ * Only symlinks, and only dangling ones: that is the case where deadness is
+ * provable from the filesystem alone. A `.bin` entry that is a real file may be a
+ * launcher script this prefix still needs, and deciding that would mean reading it —
+ * a second, weaker rule for a few hundred bytes.
+ */
+function pruneDeadBinLinks(prefix) {
+    const binDir = join(prefix, 'node_modules', '.bin');
+    const dropped = [];
+    let entries;
+    try {
+        entries = readdirSync(binDir, { withFileTypes: true });
+    }
+    catch {
+        return dropped;
+    }
+    for (const entry of entries) {
+        const full = join(binDir, entry.name);
+        try {
+            if (!lstatSync(full).isSymbolicLink())
+                continue;
+            if (existsSync(full))
+                continue;
+            unlinkSync(full);
+            dropped.push(entry.name);
+        }
+        catch {
+            // Same reasoning as `executePrune`: housekeeping never fails the caller.
+        }
+    }
+    return dropped;
+}
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+/** How many entries a non-verbose report lists before summarising the rest. */
+const REPORT_HEAD = 10;
+export function formatPruneReport(result, opts) {
+    const { plan } = result;
+    const lines = [
+        `${plan.prefix} · target ${describePlatformTarget(plan.target)} · scanned ${plan.scanned} package(s)`,
+    ];
+    if (plan.entries.length === 0) {
+        // Not "every package declares a platform this host can use": most declare
+        // none at all, and saying otherwise reports a check that did not happen.
+        lines.push('nothing to prune — no installed package declares a platform this target cannot use.');
+        return lines.join('\n');
+    }
+    const shown = opts.verbose ? plan.entries : plan.entries.slice(0, REPORT_HEAD);
+    for (const entry of shown) {
+        const required = JSON.stringify(entry.verdict.required);
+        lines.push(`  ${entry.pkg.name}@${entry.pkg.version}  ${humanBytes(entry.bytes)}  requires ${required}`);
+    }
+    if (shown.length < plan.entries.length) {
+        lines.push(`  … and ${plan.entries.length - shown.length} more (--verbose to list them)`);
+    }
+    // The byte figure is APPARENT size, summed from the files themselves. `du`
+    // reports allocated blocks and will disagree; saying so here is cheaper than
+    // the bug report that difference otherwise produces.
+    lines.push(opts.dryRun
+        ? `would free ${humanBytes(plan.bytes)} across ${plan.entries.length} package(s) (apparent size)`
+        : `freed ${humanBytes(result.bytes)} across ${result.removed.length} package(s) (apparent size)`);
+    if (result.binLinks.length > 0) {
+        lines.push(`removed ${result.binLinks.length} dangling .bin link(s): ${result.binLinks.join(', ')}`);
+    }
+    for (const f of result.failed) {
+        lines.push(`FAILED ${f.entry.pkg.name}: ${f.error}`);
+    }
+    return lines.join('\n');
+}
+/** Why an automatic pass declined to run, or null when it may proceed. */
+export function automaticPruneRefusal(env, immutable) {
+    // THE data-loss guard. `--os/--cpu/--libc` are legal on `gjsify install -g`, and
+    // they reach here as npm config keys. Pruning against a target the USER TYPED
+    // would make `gjsify install -g foo --os=darwin` delete every linux package in
+    // the real shared prefix — the engine set, the bundler bindings, the CLI's own.
+    // An explicit `gjsify prune --os=darwin` stays legal; it is a request, not a
+    // side effect.
+    if (Object.keys(readPlatformOverrides(env)).length > 0) {
+        return 'the platform target was overridden on the command line';
+    }
+    // `--immutable` promises the tree is not modified. Resolution-only would be a
+    // defensible reading, but it is not the one the flag's users have, and
+    // `ensureProjectGjsEngine` already declines under it for the same reason.
+    if (immutable)
+        return '--immutable';
+    return null;
+}
+/**
+ * The automatic pass: prune what this install would not have placed, report one
+ * line, and never fail the install that called it.
+ */
+export function pruneAfterInstall(prefix, target, opts = {}) {
+    try {
+        const refusal = automaticPruneRefusal(opts.env ?? process.env, opts.immutable ?? false);
+        if (refusal)
+            return;
+        const plan = planPrune({ prefix, target });
+        if (plan.entries.length === 0)
+            return;
+        const result = executePrune(plan);
+        if (result.removed.length === 0)
+            return;
+        const hint = opts.hint ? ` (${opts.hint} to review)` : '';
+        console.log(`gjsify: pruned ${result.removed.length} package(s) this host cannot use, ` +
+            `freeing ${humanBytes(result.bytes)}${hint}`);
+    }
+    catch (err) {
+        if (process.env.GJSIFY_DEBUG)
+            console.error(`gjsify: prune skipped — ${err.message}`);
+    }
+}

package/lib/utils/run-gjs.d.ts

@@ -1,4 +1,5 @@
 import { type NativeEnv } from './detect-native-packages.js';
+import { type SpawnCompletionContract } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -15,6 +16,16 @@ export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: stri
  * bundle's own node_modules tree.
  */
 export interface RunGjsBundleOptions {
+    /**
+     * The teardown contract of the command that will end this process — the same field,
+     * and the same reason, `spawnToCompletion` demands. Required rather than defaulted:
+     * absent, a caller silently inherited the side that ARMS the GJS main loop.
+     *
+     * Distinct from {@link exitOnSuccess}, which asks WHO performs the exit. `gjsify test`
+     * is `'exit'` — its handler exits at the end of `commands/test.ts` — while leaving
+     * `exitOnSuccess` off, because an exit HERE would truncate its multi-runtime loop.
+     */
+    completion: SpawnCompletionContract;
     /**
      * Exit this process with code 0 once the child succeeds. Under GJS, `ensureMainLoop()`
      * (armed by spawn) keeps the parent's GLib loop alive after the child exits, so a TERMINAL
@@ -31,4 +42,4 @@ export interface RunGjsBundleOptions {
      */
     quiet?: boolean;
 }
-export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;
+export declare function runGjsBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -9,9 +9,9 @@
 //
 // Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
 // assert the env without spawning gjs.
-import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
+import { describeExit, spawnToCompletion } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -40,7 +40,7 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
         .join(' ');
     return { env, envPrefix };
 }
-export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
+export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
     const env = {
         ...process.env,
@@ -52,36 +52,29 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
-    const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
-    let failed = false;
-    // The CHILD's own exit code, re-raised verbatim; a spawn error (no `gjs` on PATH) has none
-    // of its own and falls back to 1. Collapsing every failure to 1 lost information callers
-    // act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1 for both.
-    let childCode = 1;
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0) {
-                childCode = code ?? 1;
-                reject(new Error(`gjs exited with code ${code}`));
-            }
-            else {
-                resolvePromise();
-            }
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    // The CHILD's own exit code is re-raised verbatim; a spawn error (no `gjs` on PATH) has
+    // none of its own and falls back to 1. Collapsing every failure to 1 lost information
+    // callers act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1
+    // for both.
+    const failed = (code) => {
+        // `process.exitCode` is set BEFORE exiting because `gjsify run <script>` dispatches a
+        // nested `gjsify run <bundle>` IN PROCESS: the outer command reads `process.exitCode`
+        // to propagate. Without it a failing `test:gjs` returned 0 through the `test` chain,
+        // and through `gjsify foreach test` in CI. The `return` guards a fall-through exit.
+        process.exitCode = code;
+        return process.exit(code);
+    };
+    let result;
+    try {
+        result = await spawnToCompletion('gjs', gjsArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        failed = true;
-    });
-    if (failed) {
-        // Set `process.exitCode` synchronously BEFORE exiting: under GJS `process.exit()` is
-        // deferred (the GLib main loop is armed), so under run.ts's in-process script dispatch
-        // execution returns to the caller, which propagates by reading `process.exitCode`.
-        // Without it, `gjsify run <script>` wrapping `gjsify run <bundle>` swallowed a non-zero
-        // gjs exit and returned 0 — masking a failing `test:gjs` in the `test` chain, and via
-        // `gjsify foreach test` in CI. The `return` guards a fall-through second `exit`.
-        process.exitCode = childCode;
-        return process.exit(childCode);
+        return failed(1);
+    }
+    if (result.code !== 0) {
+        console.error(`gjs exited with ${describeExit(result)}`);
+        return failed(result.code ?? 1);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
     // mid-flow callers (test.ts's runtime loop) keep the process alive.

package/lib/utils/run-node.d.ts

@@ -1,4 +1,5 @@
 import { type ExampleRuntime } from './runtimes.js';
+import { type SpawnCompletionContract } from './spawn.js';
 /**
  * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
  * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
@@ -19,6 +20,8 @@ export declare function resolveNodeGiForBundle(bundlePath: string, cwd: string):
 /** Pick the node executable: the current one when on Node, else PATH `node`. */
 export declare function nodeBinary(): string;
 export interface RunNodeBundleOptions {
+    /** The caller's teardown contract — see `RunGjsBundleOptions.completion`. */
+    completion: SpawnCompletionContract;
     /** Exit this process with code 0 once the child succeeds (terminal callers). */
     exitOnSuccess?: boolean;
     /** Suppress the `$ <env> node …` echo — see `RunGjsBundleOptions.quiet`. */
@@ -28,12 +31,14 @@ export interface RunNodeBundleOptions {
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
  * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
-export declare function runNodeBundle(bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;
+export declare function runNodeBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunNodeBundleOptions): Promise<void>;
 /**
  * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
  * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
- * WITHOUT node-gi installed, which is why the check is conditional here and not unconditional
- * like the storybook path.
+ * WITHOUT node-gi installed, which is why the check is conditional rather than a flat "this is a
+ * node bundle, demand node-gi". The supervised launcher (`utils/watch-loop.ts`) asks the same
+ * question for the same reason: `gjsify dev` on a web-server template builds a node bundle that
+ * never reaches a typelib.
  */
 export declare function bundleRequiresNodeGi(bundlePath: string): boolean;
 /**
@@ -44,4 +49,4 @@ export declare function bundleRequiresNodeGi(bundlePath: string): boolean;
  *
  * `gjs` is intentionally NOT handled here — the caller dispatches it to {@link runGjsBundle}.
  */
-export declare function runRuntimeBundle(runtime: Exclude<ExampleRuntime, 'gjs'>, bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;
+export declare function runRuntimeBundle(runtime: Exclude<ExampleRuntime, 'gjs'>, bundlePath: string, extraArgs: string[] | undefined, options: RunNodeBundleOptions): Promise<void>;