@gjsify/cli 0.30.0 → 0.31.0

package/lib/commands/install.js

@@ -31,7 +31,7 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, syml
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { forceExit } from '../utils/force-exit.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
@@ -42,7 +42,7 @@ import { acquireInstallLock } from '../utils/install-lock.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -198,7 +198,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
             return;
         }
         // Overall wall-clock budget for the install (default 30 min — big
@@ -263,7 +263,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
         }
         catch (err) {
             if (overallController !== null && overallController.signal.aborted && isAbortedFromOverallTimeout(err)) {
@@ -345,21 +345,6 @@ function isAbortedFromOverallTimeout(err) {
         return true;
     return false;
 }
-/**
- * Force a non-zero process exit that is honored on BOTH runtimes.
- *
- * Node exits at natural shutdown once `process.exitCode` is set, but GJS has
- * no atexit hook, so `imports.system.exit` is called directly there —
- * SpiderMonkey raises its uncatchable exit exception from any context,
- * including the `setTimeout` continuation the backstop timer runs in. Mirrors
- * the entry wrapper (`index.ts`) and `setOxcExitCode` (`oxc-resolve.ts`).
- */
-function forceExit(code) {
-    process.exitCode = code;
-    if (gjsExit(code))
-        return;
-    process.exit(code);
-}
 const CLI_PACKAGE_NAME = '@gjsify/cli';
 /** Read a `version` from a package.json IFF its `name` is `@gjsify/cli`. */
 function readCliVersionFrom(pkgJsonPath) {
@@ -1419,7 +1404,33 @@ function reportLinkedBins(created, binDir) {
             `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
-async function runPostInstallChecks() {
+export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const hasEngine = deps.hasEngineFn ?? hasBundlerEngineInstalled;
+    if (!existsSync(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')))
+        return;
+    if (!gjsFound)
+        return;
+    if (hasEngine(cwd))
+        return;
+    if (args.immutable) {
+        // Name the DURABLE fix, not a transient one: a frozen CI install cannot
+        // be repaired by anything that happens at this moment, so the answer is
+        // to put the engine in the lockfile.
+        console.warn(`\nWarning: \`gjsify build\` will fail under GJS — ${BUNDLER_ENGINE_PACKAGE} is not installed, and\n` +
+            '  --immutable cannot add it (the lockfile does not name it). Declare it so the lockfile carries it:\n' +
+            `    gjsify install ${BUNDLER_ENGINE_PACKAGE}\n` +
+            '  Under Node the npm `rolldown` engine is used instead and this does not apply.');
+        return;
+    }
+    const cliVersion = readCliVersionFrom(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')) ?? 'latest';
+    console.log(`\n${BUNDLER_ENGINE_PACKAGE} is missing and this host can run gjs, so \`gjsify build\` would have no\n` +
+        `  bundler engine (there is no npm \`rolldown\` fallback under GJS). Installing the GJS engine set at\n` +
+        `  ${cliVersion}, in lockstep with the CLI.`);
+    const install = deps.installFn ?? installGjsEnginePackages;
+    await install(cwd, cliVersion, { verbose: args.verbose });
+}
+async function runPostInstallChecks(args) {
     console.log('\n--- gjsify post-install checks ---');
     // 1. System deps that GJS apps typically need.
     const results = runMinimalChecks();
@@ -1437,8 +1448,14 @@ async function runPostInstallChecks() {
     else {
         console.log('System dependencies OK.');
     }
-    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    // 2. Close #1005 before reporting the prebuild set, so the report reflects
+    //    what the tree ACTUALLY has rather than what it had a moment ago.
+    await ensureProjectGjsEngine(args, results.find((r) => r.id === 'gjs')?.found ?? false);
+    // 3. Surface @gjsify/* packages with native prebuilds — `gjsify run`
     //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    //    Runs AFTER step 2 on purpose: an engine installed a moment ago belongs
+    //    in this list, and a consumer reading "Detected N …" needs it to be the
+    //    tree's current state rather than its state on entry.
     const native = detectNativePackages(process.cwd());
     if (native.length > 0) {
         console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);

package/lib/commands/run.js

@@ -296,12 +296,15 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
     if (monorepoRoot && monorepoRoot !== cwd) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
-    // Under GJS, the GJS-runnable `gjsify` shim (see `ensureGjsifyShimOnPath`)
-    // MUST shadow the workspace `node_modules/.bin/gjsify`, which is the Node
-    // entry and unusable in a node-free sandbox. So put the shim dir ahead of
-    // the `.bin` dirs in the child's PATH — otherwise a compound script like
-    // `gjsify run a && gjsify run b` resolves `gjsify` to the Node bin and
-    // fails. `GJSIFY_SHIM_DIR` is only set under GJS, so this is a no-op on Node.
+    // The self-shim (see `ensureGjsifyShimOnPath`) MUST shadow the workspace
+    // `node_modules/.bin/gjsify`, so put its dir ahead of the `.bin` dirs in the
+    // child's PATH — otherwise a compound script like `gjsify run a && gjsify
+    // run b` resolves `gjsify` to the workspace bin. Two trees need that:
+    // under GJS the bin is the Node entry and is unusable in a node-free
+    // sandbox, and under a BOOTSTRAP Node CLI (npx / global install) the bin
+    // dispatches to build outputs that a cold tree has not produced yet.
+    // `GJSIFY_SHIM_DIR` is unset whenever the tree's own CLI is the one
+    // running, which keeps that case byte-for-byte unchanged.
     if (process.env.GJSIFY_SHIM_DIR) {
         binDirs.unshift(process.env.GJSIFY_SHIM_DIR);
     }
@@ -342,6 +345,22 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
         process.env.npm_package_version = env.npm_package_version;
         if (env.FORCE_COLOR !== undefined)
             process.env.FORCE_COLOR = env.FORCE_COLOR;
+        // …and the working directory, for the same reason. The spawn path below
+        // passes `cwd` to `spawn()`; this path used to pass it nowhere, so a
+        // `gjsify run -w <ws> <script>` resolved the WORKSPACE and then ran the
+        // command in the CALLER's directory. Every relative path in the script
+        // — `src/app/main.ts`, `dist/…`, `tests/test.mts` — then resolved
+        // against the monorepo root.
+        //
+        // Only this branch was affected, which is why it survived: the fast path
+        // fires exactly when the script is a SINGLE `gjsify <subcommand>`, so a
+        // compound script (`a && b`) took the shell path and worked. Measured on
+        // the two consumers: bauplaner's cli scripts are all single commands and
+        // it documents the gap in its AGENTS.md, sidestepping it with
+        // `cd cli && …`; buchhaltung's one `-w` use is `build:meson`, a compound
+        // command, and it works.
+        if (cwd !== process.cwd())
+            process.chdir(cwd);
         // Track the failure LOCALLY rather than through `process.exitCode`.
         // Under GJS `process.exit()` is deferred (see the note below), so the
         // `process.exit(1)` that used to live in the catch returned instead of

package/lib/commands/test.js

@@ -194,10 +194,10 @@ async function runTestBundle(outfile, runtime) {
         return;
     }
     await new Promise((resolvePromise, reject) => {
-        // `nodeBinary()`, never a bare `'node'`: under the committed GJS bundle
-        // `process.execPath` is the bundle itself, and on a host without Node a
-        // bare literal dies `spawn node ENOENT` — which is how a fully passing
-        // GJS suite was reported as a failed run.
+        // `nodeBinary()`, never a bare `'node'`: under GJS `process.execPath` is
+        // the `gjs` interpreter, which cannot run a `--app node` bundle, and on a
+        // host without Node a bare literal dies `spawn node ENOENT` — which is
+        // how a fully passing GJS suite was reported as a failed run.
         const child = spawn(nodeBinary(), [outfile], { stdio: 'inherit' });
         child.on('error', reject);
         child.on('exit', (code) => {

package/lib/commands/tsc.js

@@ -22,6 +22,10 @@ import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { detectNativePackages, buildNativeEnv } from '../utils/detect-native-packages.js';
+import { isOnPath } from '../utils/check-system-deps.js';
+import { existsSync } from 'node:fs';
+import { forceExit } from '../utils/force-exit.js';
+import { nodeBinary } from '../utils/run-node.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const tscCommand = {
     command: 'tsc [tscArgs..]',
@@ -104,9 +108,12 @@ export const tscCommand = {
         if (!bundlePath && !nodeTscPath) {
             console.error('gjsify tsc: neither @gjsify/tsc (GJS bundle) nor npm `typescript` (Node) is installed.');
             console.error('  Install with: gjsify install --save-dev @gjsify/tsc   (or add `typescript`).');
-            // `return` — a bare `process.exit()` is deferred under GJS and the
-            // handler would try to spawn a compiler that is not there.
-            return process.exit(1);
+            // `return` — the handler must not fall through and try to spawn a
+            // compiler that is not there. `forceExit` and not `process.exit`
+            // because the latter is idle-scheduled under GJS, and NOTHING here
+            // armed a main loop to deliver it: the process would reach natural
+            // shutdown and report 0 while printing the message above.
+            return forceExit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
         // typescript-the-bundle code path that reaches a native bridge
@@ -118,13 +125,54 @@ export const tscCommand = {
             ...process.env,
             ...nativeEnv,
         };
-        // Run upstream `typescript` under this Node — the Node-only fallback.
+        // Run upstream `typescript` under Node — the Node fallback.
+        //
+        // `nodeBinary()`, NEVER a bare `process.execPath`: under the GJS bundle
+        // `process.execPath` is the GJS interpreter (`/proc/self/exe` →
+        // `gjs-console`), so `spawn(process.execPath, [tsc.js])` hands
+        // TypeScript's CommonJS CLI to GJS, which dies on the first `module`
+        // reference — or, where execPath resolves to a gjsify launcher instead,
+        // re-executes the CLI with the tsc entry as an unknown argument. Both
+        // were reached from a COLD tree: `@gjsify/tsc`'s `dist/tsc.gjs.mjs` is a
+        // build output, and `build:infra` builds `@gjsify/create-app` (its first
+        // `gjsify tsc` caller) long before `@gjsify/tsc` produces it, so the
+        // fallback below is the NORMAL path there, not an edge case.
+        // `run-node.ts` owns the one correct answer; every other spawn site in
+        // this CLI already routes through it.
         const runNodeTsc = () => {
-            const child = spawn(process.execPath, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
-            child.on('close', (code) => process.exit(code ?? 1));
+            const nodeBin = nodeBinary();
+            // PRE-FLIGHT, deliberately NOT the spawn's `'error'` event.
+            //
+            // Under the GJS bundle that event is not delivered when the program
+            // is missing: the handler below never runs, the command returns
+            // normally, and `gjsify tsc` exits **0 in total silence** having
+            // compiled nothing. Measured in CI by `tests/e2e/tsc-node-fallback`'s
+            // "FAILS LOUDLY …" case, whose assertion printed an EMPTY captured
+            // output — no stderr at all, so nothing had reported anything.
+            //
+            // Deciding it here, synchronously, is what makes the failure
+            // reportable: the exit happens on the caller's own stack rather than
+            // in a continuation that may never be scheduled.
+            const runnable = nodeBin.includes('/') || nodeBin.includes('\\') ? existsSync(nodeBin) : isOnPath(nodeBin);
+            if (!runnable) {
+                console.error(`gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and \`${nodeBin}\` cannot be run, ` +
+                    'so upstream `typescript` cannot run either.');
+                console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                console.error('  …or install Node.js so the upstream `typescript` fallback can be spawned.');
+                return forceExit(1);
+            }
+            const child = spawn(nodeBin, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
+            child.on('close', (code) => forceExit(code ?? 1));
             child.on('error', (err) => {
-                console.error(`gjsify tsc (node typescript): ${err.message}`);
-                process.exit(1);
+                if (err.code === 'ENOENT') {
+                    console.error('gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and `node` is not on PATH, ' +
+                        'so upstream `typescript` cannot run either.');
+                    console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                }
+                else {
+                    console.error(`gjsify tsc (node typescript): ${err.message}`);
+                }
+                forceExit(1);
             });
         };
         // Prefer GJS — the Node-free @gjsify/tsc bundle — when it resolves. If
@@ -144,7 +192,7 @@ export const tscCommand = {
                 child.on('close', (code) => {
                     if (gjsSpawnFailed)
                         return;
-                    process.exit(code ?? 1);
+                    forceExit(code ?? 1);
                 });
                 child.on('error', (err) => {
                     gjsSpawnFailed = true;
@@ -155,11 +203,11 @@ export const tscCommand = {
                     else if (err.code === 'ENOENT') {
                         console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
                         console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
-                        process.exit(1);
+                        forceExit(1);
                     }
                     else {
                         console.error(`gjsify tsc: ${err.message}`);
-                        process.exit(1);
+                        forceExit(1);
                     }
                 });
                 // Never resolves naturally — process.exit() above terminates the

package/lib/commands/workspace.js

@@ -24,6 +24,7 @@ import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsi
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { usingSelfShim } from '../utils/gjsify-shim.js';
 import { suggestClosest } from '../utils/suggest.js';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
@@ -279,6 +280,18 @@ export function detectPackageManager() {
     // orchestration work in the Flatpak sandbox.
     if (isGjs())
         return 'gjsify';
+    // Same answer for a BOOTSTRAP CLI on Node, for a reason one level deeper
+    // than it looks. `ensureGjsifyShimOnPath()` puts a working `gjsify` ahead of
+    // the tree's `node_modules/.bin` — but npm RE-PREPENDS `node_modules/.bin`
+    // for every lifecycle script it starts, so delegating to npm here restores
+    // the tree's not-yet-built shim one level down and undoes the repair.
+    // Measured on a cold tree: `run build:infra` cleared its first clause and
+    // then died inside `npm run build` with `Cannot find module
+    // …/packages/infra/cli/lib/index.js`. Running the script ourselves keeps the
+    // bootstrap CLI's identity all the way down — which is exactly what the GJS
+    // branch above already relies on, and why Linux CI never saw this.
+    if (usingSelfShim())
+        return 'gjsify';
     const ua = process.env.npm_config_user_agent ?? '';
     if (ua.startsWith('yarn/'))
         return 'yarn';

package/lib/config.js

@@ -223,8 +223,12 @@ export class Config {
         const pkg = (await this.readPackageJSON(configFilePath));
         const tsConfig = (await this.readTSConfig(configFilePath));
         tsConfig.reflection ||= cliArgs.reflection;
-        // TODO(open-todos: 10 small API gaps): replace with `cliArgs.logLevel`
-        configData.verbose = cliArgs.verbose || false;
+        // `--verbose` and `--log-level` are two spellings of one question, and
+        // only the boolean reached here — so `--log-level debug` turned the
+        // BUNDLER's logging up (see the mapping further down, which sets
+        // `bundler.logLevel`) while the CLI's own verbose output stayed off.
+        // Either spelling now answers it; neither silences the other.
+        configData.verbose = cliArgs.verbose || cliArgs.logLevel === 'debug' || cliArgs.logLevel === 'verbose';
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;

package/lib/index.js

@@ -17,7 +17,24 @@ catch (err) {
     // a scary `Gjs-CRITICAL **: Module … threw an exception` that buries the
     // real, already-actionable message (e.g. "gjsify build: no usable bundler
     // engine under GJS — build the facade first or run under Node"). See #597.
-    console.error(err instanceof Error ? err.message : String(err));
+    //
+    // The `code` is printed WITH the message, not dropped. Errors in this CLI
+    // carry npm's own codes on purpose — `badPlatformError()` documents that it
+    // reproduces npm's `EBADPLATFORM` payload "so a consumer's error handling
+    // (and a human reading the message) sees what npm reports" — and npm itself
+    // prints the code (`npm ERR! code EBADPLATFORM`) rather than only the prose.
+    //
+    // It has to be explicit here because this catch became the SINGLE printer:
+    // before the `.fail()` handler in `cli-app.ts`, yargs logged the error OBJECT
+    // and the code came along for free. Printing `err.message` alone silently
+    // dropped it for every coded error, which is what turned
+    // `tests/e2e/install-optional-both-blocks` red on `main` — it asserts the
+    // code is visible, and the prose it still printed did not contain it.
+    const code = typeof err === 'object' && err !== null && typeof err.code === 'string'
+        ? err.code
+        : '';
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(code && !message.includes(code) ? `${code}: ${message}` : message);
     if (process.env.GJSIFY_DEBUG && err instanceof Error && err.stack)
         console.error(err.stack);
     // `process.exitCode` is the gentle Node idiom (streams flush). GJS has no

package/lib/templates/install.mjs.tmpl

@@ -58,8 +58,18 @@ const USER_AGENT = 'gjsify-installer/1.0';
 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.
+ */
+let logToStderr = false;
+
 function info(msg) {
-    print(`[gjsify] ${msg}`);
+    if (logToStderr) printerr(`[gjsify] ${msg}`);
+    else print(`[gjsify] ${msg}`);
 }
 function error(msg) {
     printerr(`[gjsify] ERROR: ${msg}`);
@@ -71,6 +81,7 @@ function parseArgs() {
     let tag = 'latest';
     let force = false;
     let help = false;
+    let fetchOnly = false;
     let bootstrapUrl = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_URL') || DEFAULT_BOOTSTRAP_URL;
     let bootstrapSha256Url = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL');
     if (bootstrapSha256Url === null || bootstrapSha256Url === undefined) {
@@ -87,8 +98,9 @@ function parseArgs() {
         else if (a.startsWith('--tag=')) tag = a.slice('--tag='.length);
         else if (a === '--bootstrap-url') bootstrapUrl = argv[++i];
         else if (a.startsWith('--bootstrap-url=')) bootstrapUrl = a.slice('--bootstrap-url='.length);
+        else if (a === '--fetch-only') fetchOnly = true;
     }
-    return { target, tag, force, help, bootstrapUrl, bootstrapSha256Url };
+    return { target, tag, force, help, bootstrapUrl, bootstrapSha256Url, fetchOnly };
 }
 
 function printUsage() {
@@ -102,6 +114,10 @@ Options:
   --tag <tag>        npm dist-tag or version  (default: latest)
   --force, -f        Reinstall even when present.
   --bootstrap-url <url>  Override the cli.gjs.mjs download URL.
+  --fetch-only       Download + verify the bootstrap bundle, print its cached
+                     path to stdout and exit — no install. Lets a caller (CI)
+                     reuse this downloader instead of growing a second one
+                     beside it; progress goes to stderr so stdout is the path.
   --help, -h         Show this message.
 
 Env vars:
@@ -318,6 +334,9 @@ async function main() {
         printUsage();
         exit(0);
     }
+    // Set BEFORE the first `info()` — resolveBootstrap logs while downloading,
+    // and those lines would otherwise land on stdout ahead of the path.
+    logToStderr = opts.fetchOnly;
     checkGjsVersion();
 
     const session = new Soup.Session();
@@ -329,6 +348,12 @@ async function main() {
         exit(1);
     }
 
+    if (opts.fetchOnly) {
+        // The one thing on stdout. Everything above went to stderr.
+        print(bundlePath);
+        exit(0);
+    }
+
     const spec = buildSpec(opts.target, opts.tag);
     try {
         await runInstall(bundlePath, spec);

package/lib/types/command.d.ts

@@ -7,3 +7,21 @@ export interface Command<T = unknown, U = T> {
     middlewares?: MiddlewareFunction[];
     deprecated?: boolean | string;
 }
+/**
+ * A command that definitely runs something — the shape of every command except
+ * the builder-only parents.
+ *
+ * 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.
+ */
+export type LeafCommand<T = unknown, U = T> = Command<T, U> & {
+    handler: NonNullable<Command<T, U>['handler']>;
+};

package/lib/utils/check-system-deps.d.ts

@@ -12,7 +12,26 @@ export interface DepCheck {
     /** For optional deps: which @gjsify/* packages need this lib */
     requiredBy?: string[];
 }
-export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew' | 'unknown';
+export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew' | 'winget' | 'unknown';
+/**
+ * True when `cmd` is on PATH. Walks `process.env.PATH` with `existsSync`
+ * instead of shelling out to `which`(1).
+ *
+ * `which` is NOT a probe you can rely on: the Fedora 43/44 minimal containers
+ * CI runs in ship without it (only the `which-2.x` rpm provides it), so a
+ * `which`-based check silently answers "missing" for EVERY command. That is
+ * exactly where this file's answer matters most — `detectPackageManager()`
+ * returning `unknown` makes `buildInstallCommand()` return null, so the
+ * distro-specific install hint for a missing system library prints nothing on
+ * the hosts that needed it. Measured twice on 2026-08-05: ts-for-gir#437 had to
+ * discover `json-glib` by hand, bauplaner#40 `libsoup3` — both in such a
+ * container, both while this file already declared the dependency.
+ *
+ * `tests/e2e/helpers.mjs`'s `hasCommand()` carries the same walk for the same
+ * reason. It stays a second copy on purpose: it is `.mjs` under `tests/` and
+ * cannot be imported from the shipped CLI.
+ */
+export declare function isOnPath(cmd: string): boolean;
 /**
  * The package manager whose install command we may suggest.
  *
@@ -28,6 +47,29 @@ export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew
  * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
  */
 export declare function detectPackageManager(): PackageManager;
+/**
+ * The Visual C++ runtime — an undeclared, undiagnosed win32 prerequisite (#997).
+ *
+ * `@gjsify/gtk-runtime-win32-x64` is built with gvsbuild, i.e. against the MSVC
+ * ABI, and its DLLs load into stock (also MSVC-ABI) Node. On a Windows host
+ * WITHOUT the Visual C++ redistributable that load fails — and nothing in the
+ * toolchain said so. The precedent for why that matters is PR #994: a missing
+ * load-time library made a typelib unloadable and the user-visible message was
+ * `Unsupported type void, deriving from fundamental void`, which names nothing
+ * a user could act on.
+ *
+ * Probed by FILE PRESENCE in the system directory rather than by asking a
+ * package database: the redistributable can arrive with Visual Studio, with
+ * another application's installer, or as part of a Windows image, and only one
+ * of those routes is visible to a package manager. What the loader actually
+ * needs is the DLL, so that is what is checked.
+ *
+ * `vcruntime140.dll` and `msvcp140.dll` are the C and C++ halves;
+ * `vcruntime140_1.dll` carries the x64 exception-handling machinery and is
+ * absent from pre-2019 redistributables, which is exactly the "installed, but
+ * too old" case that otherwise fails at first use rather than at load.
+ */
+export declare function checkMsvcRuntime(): DepCheck;
 interface OptionalDep {
     /** DepCheck id */
     id: string;
@@ -38,6 +80,29 @@ interface OptionalDep {
 }
 /** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
 export declare const OPTIONAL_DEPS: Record<string, OptionalDep>;
+/**
+ * The declared system libraries a single `@gjsify/*` package needs that are NOT
+ * present on this host.
+ *
+ * Exists so a FAILURE can answer the question this file already knows the answer
+ * to. The tables below have declared `@gjsify/rolldown-native → json-glib` since
+ * #994, complete with per-distro package names — but the only reader was
+ * `runAllChecks()`, i.e. `gjsify system-check`, a command the user has to think
+ * to run. So when the engine was installed and simply would not LOAD, the build
+ * said "@gjsify/rolldown-native is NOT INSTALLED … install it" (it was) or
+ * guessed at a bypassed launcher. Two repositories spent a CI round rediscovering
+ * a library this file could have named: ts-for-gir#437, bauplaner#40.
+ *
+ * Cannot throw, by construction rather than by a catch: `checkPkgConfig` goes
+ * through `tryExecFile`, which returns null on any failure. That matters because
+ * the caller is `diagnoseNativeEngine()`, which runs *while explaining another
+ * failure* — a probe that dies there would replace the diagnosis with its own
+ * stack.
+ *
+ * Returns `[]` for an unknown package or one with no declared deps, so a caller
+ * needs no special case for "nothing to say".
+ */
+export declare function missingSystemDepsFor(packageName: string): DepCheck[];
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
  * Generated by walking each package's `gi://` imports (excluding the always-