@gjsify/cli 0.40.0 → 0.41.0

package/lib/cli-app.js

@@ -18,7 +18,7 @@
 import yargs from 'yargs';
 import { classifyCliFailure } from './cli-fail.js';
 import { cliVersion } from './utils/publish-headers.js';
-import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -120,6 +120,7 @@ export async function runCli(argv) {
         .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
         .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
         .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
+        .command(prune.command, prune.description, prune.builder, prune.handler)
         .command(upgrade.command, upgrade.description, upgrade.builder, upgrade.handler)
         .command(format.command, format.description, format.builder, format.handler)
         .command(lint.command, lint.description, lint.builder, lint.handler)

package/lib/commands/create.d.ts

@@ -1,7 +1,10 @@
+import type { PackageManager } from '@gjsify/create-app';
 import type { Command } from '../types/index.js';
 interface CreateOptions {
     'project-name': string;
     template?: string;
+    runtime?: string;
+    'package-manager'?: PackageManager;
     force: boolean;
     install: boolean;
 }

package/lib/commands/create.js

@@ -1,11 +1,15 @@
-import { createProject, discoverTemplates } from '@gjsify/create-app';
-import { promptTemplate } from '@gjsify/create-app/prompt';
+import { createProject, discoverTemplates, PACKAGE_MANAGERS, supportedRuntimes } from '@gjsify/create-app';
+import { isCancelled, promptSetup, promptTemplate } from '@gjsify/create-app/prompt';
 export const createCommand = {
     command: 'create [project-name]',
     description: 'Scaffold a new Gjsify project in a new directory.',
     builder: (yargs) => {
         const templates = discoverTemplates();
         const templateChoices = templates.map((t) => t.name);
+        // DERIVED from the shipped templates, never a hand-written list:
+        // accepting `--runtime deno` is a claim that some template runs there,
+        // and only the templates can make it.
+        const runtimeChoices = [...new Set(templates.flatMap((t) => supportedRuntimes(t)))];
         return yargs
             .positional('project-name', {
             describe: 'Name of the project directory to create',
@@ -17,6 +21,12 @@ export const createCommand = {
             describe: 'Template to scaffold from',
             type: 'string',
             choices: templateChoices.length > 0 ? templateChoices : undefined,
+        })
+            .option('runtime', {
+            alias: 'r',
+            describe: 'Runtime to set the project up for. Decides which package managers are offered and which start script the next steps name.',
+            type: 'string',
+            choices: runtimeChoices.length > 0 ? runtimeChoices : undefined,
         })
             .option('force', {
             alias: 'f',
@@ -25,30 +35,63 @@ export const createCommand = {
             default: false,
         })
             .option('install', {
-            describe: 'Run npm install after scaffolding',
+            describe: 'Install dependencies after scaffolding',
             type: 'boolean',
             default: false,
+        })
+            .option('package-manager', {
+            alias: 'p',
+            describe: 'Package manager to install with, and to name in the printed next steps. Must be one the chosen runtime can install for. `gjsify` is the only one that works on a host with no Node.js.',
+            type: 'string',
+            choices: PACKAGE_MANAGERS,
         });
     },
     handler: async (args) => {
+        const interactive = Boolean(process.stdin.isTTY);
+        const templates = discoverTemplates();
         let template = args.template;
         if (!template) {
-            const templates = discoverTemplates();
-            if (!process.stdin.isTTY) {
+            if (!interactive) {
                 const list = templates.map((t) => t.name).join(', ');
                 console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
                 // `return` — the deferred GJS exit otherwise fell through into
                 // the interactive template prompt on a non-TTY.
                 return process.exit(1);
             }
-            const picked = await promptTemplate(templates);
+            // Ctrl+C is an abort, not a crash.
+            const picked = await promptTemplate(templates).catch((error) => {
+                if (!isCancelled(error))
+                    throw error;
+                console.error('Cancelled.');
+                return undefined;
+            });
+            if (picked === undefined)
+                return process.exit(1);
             template = picked.name;
         }
+        // The SAME decision layer `npm create @gjsify/app` runs, not a second
+        // one. Wired late: this command used to pass neither runtime nor package
+        // manager, so `createProject` fell back to the host runtime and the first
+        // manager for it — meaning `gjsify create --install` on a Node host ran
+        // `npm install` without ever saying so, the one default that reaches the
+        // user's disk and the one the standalone bin refuses to guess.
+        const info = templates.find((t) => t.name === template);
+        const setup = await promptSetup({
+            offered: info ? supportedRuntimes(info) : [],
+            runtime: args.runtime,
+            packageManager: args['package-manager'],
+            install: args.install,
+            interactive,
+        });
+        if (setup === undefined)
+            return process.exit(1);
         await createProject({
             projectName: args['project-name'],
             template,
+            runtime: setup.runtime,
             force: args.force,
             install: args.install,
+            packageManager: setup.packageManager,
         });
     },
 };

package/lib/commands/index.d.ts

@@ -26,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';

package/lib/commands/index.js

@@ -26,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';

package/lib/commands/install.d.ts

@@ -7,6 +7,7 @@ interface InstallOptions {
     'save-peer'?: boolean;
     'save-optional'?: boolean;
     immutable?: boolean;
+    prune?: boolean;
     'refresh-lockfile'?: boolean;
     verbose: boolean;
     quiet?: boolean;

package/lib/commands/install.js

@@ -32,6 +32,8 @@ import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { pruneAfterInstall } from '../utils/prune-prefix.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -125,6 +127,11 @@ export const installCommand = {
         description: 'Install a REQUIRED dependency even when its os/cpu/libc excludes the target, instead of failing with EBADPLATFORM (npm config key `force`). Incompatible OPTIONAL dependencies stay skipped — npm ignores --force for those too, and a binary that cannot load is not worth downloading.',
         type: 'boolean',
         default: false,
+    })
+        .option('prune', {
+        description: 'After installing, remove packages an earlier install left behind that this host cannot use (foreign os/cpu/libc). Use --no-prune to disable. Skipped automatically under --immutable, and whenever --os/--cpu/--libc is given: an install must never delete against a target the user typed.',
+        type: 'boolean',
+        default: true,
     }),
     handler: async (args) => {
         // Must run before anything resolves — `--os/--cpu/--libc/--force` are npm
@@ -161,7 +168,7 @@ export const installCommand = {
                     console.warn(`gjsify install --global ignores --${flag}: global installs do not modify a project package.json.`);
                 }
             }
-            await installGlobalAndLink(args.packages, { verbose: args.verbose });
+            await installGlobalAndLink(args.packages, { verbose: args.verbose, prune: args.prune });
             return;
         }
         // Before the heavy install, so the skew is visible even if a later phase
@@ -170,6 +177,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
             return;
         }
@@ -217,6 +225,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
         }
         catch (err) {
@@ -1198,6 +1207,14 @@ async function installGlobalAndLink(specs, opts) {
             const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
             await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
         }
+        // Before the LINK on purpose: `linkGlobalBins`' launchers bake the resolved
+        // prebuild directories into GI_TYPELIB_PATH/LD_LIBRARY_PATH, and must not name
+        // a directory this pass is about to delete.
+        if (opts.prune !== false) {
+            pruneAfterInstall(layout.prefix, resolveHostPlatform({ env: {} }), {
+                hint: 'gjsify prune -g --dry-run',
+            });
+        }
         const created = linkGlobalBins(packageNames, layout);
         reportLinkedBins(created, layout.binDir);
     }
@@ -1205,6 +1222,20 @@ async function installGlobalAndLink(specs, opts) {
         lock.release();
     }
 }
+/**
+ * The automatic pass for a PROJECT prefix.
+ *
+ * Hooked at the command level rather than inside `installPackages`, so `dlx`'s
+ * throwaway cache prefix — created, used once and dropped — pays nothing for it.
+ */
+function pruneProjectPrefix(args) {
+    if (args.prune === false)
+        return;
+    pruneAfterInstall(process.cwd(), resolveHostPlatform({ env: {} }), {
+        immutable: args.immutable === true,
+        hint: 'gjsify prune --dry-run',
+    });
+}
 function reportLinkedBins(created, binDir) {
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');

package/lib/commands/prune.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface PruneOptions {
+    global: boolean;
+    dryRun: boolean;
+    verbose: boolean;
+    os?: string;
+    cpu?: string;
+    libc?: string;
+}
+export declare const pruneCommand: Command<unknown, PruneOptions>;
+export {};

package/lib/commands/prune.js

@@ -0,0 +1,84 @@
+// `gjsify prune` — remove installed packages this target cannot use.
+//
+// The repair half of ADR 0025. `install`/`self-update` prune what they would not
+// have placed, but only going forward: a prefix that accreted foreign-platform
+// packages under an older CLI is only reachable by asking. That is this command,
+// and it is why it exists at all rather than the automatic pass alone.
+//
+// `--os/--cpu/--libc` are accepted here and deliberately NOT honoured by the
+// automatic pass: typed on `prune` they are a request ("show me what a darwin-arm64
+// host could not use"), while inherited by an install they would delete the host's
+// own packages. See `automaticPruneRefusal`.
+import { existsSync } from 'node:fs';
+import { acquireInstallLock } from '../utils/install-lock.js';
+import { defaultGlobalLayout } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { executePrune, formatPruneReport, planPrune } from '../utils/prune-prefix.js';
+export const pruneCommand = {
+    command: 'prune',
+    description: 'Remove installed packages this host cannot use (foreign os/cpu/libc). ' +
+        'Reads each package manifest — a package that declares no platform is never touched.',
+    builder: (yargs) => yargs
+        .option('global', {
+        description: 'Prune the user-global XDG prefix (the `install -g` target) instead of the project.',
+        type: 'boolean',
+        alias: 'g',
+        default: false,
+    })
+        .option('dry-run', {
+        description: 'Report what would be removed without touching the filesystem.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('verbose', {
+        description: 'List every package rather than the first few.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('os', {
+        description: 'Prune AS IF the host were this OS (linux, darwin, win32). Defaults to this host.',
+        type: 'string',
+    })
+        .option('cpu', {
+        description: 'Prune AS IF the host were this architecture (x64, arm64, …). Defaults to this host.',
+        type: 'string',
+    })
+        .option('libc', {
+        description: 'Prune AS IF the host used this libc (glibc, musl). Defaults to this host.',
+        type: 'string',
+    }),
+    handler: async (args) => {
+        const layout = args.global ? defaultGlobalLayout() : null;
+        const prefix = layout ? layout.prefix : process.cwd();
+        if (!existsSync(`${prefix}/node_modules`)) {
+            console.log(`gjsify prune: nothing installed at ${prefix}`);
+            return;
+        }
+        // The flags are read HERE rather than through the npm config keys, so the
+        // automatic pass — which refuses to act on an overridden target — cannot be
+        // reached by way of this command's own options.
+        const target = resolveHostPlatform({
+            env: {
+                ...(args.os ? { npm_config_os: args.os } : {}),
+                ...(args.cpu ? { npm_config_cpu: args.cpu } : {}),
+                ...(args.libc ? { npm_config_libc: args.libc } : {}),
+            },
+        });
+        // A prune racing an install's extract would delete a half-written tree. The
+        // lock is the same one every writer of this prefix takes (ADR 0001).
+        const lock = await acquireInstallLock(prefix, {});
+        let result;
+        try {
+            result = executePrune(planPrune({ prefix, target }), { dryRun: args.dryRun });
+        }
+        finally {
+            lock.release();
+        }
+        console.log(formatPruneReport(result, { dryRun: args.dryRun, verbose: args.verbose }));
+        // Removing nothing is a SUCCESS — idempotent housekeeping, unlike `uninstall`
+        // where naming a package that is not there is a mistake worth reporting. Only
+        // a removal the user asked for and did not get is a failure.
+        if (result.failed.length > 0)
+            return process.exit(1);
+    },
+};

package/lib/commands/self-update.d.ts

@@ -4,6 +4,7 @@ interface SelfUpdateOptions {
     force?: boolean;
     tag: string;
     skipDeps?: boolean;
+    prune?: boolean;
 }
 export declare const selfUpdateCommand: Command<unknown, SelfUpdateOptions>;
 /** Verdict of the post-install "did this change what runs?" check. */

package/lib/commands/self-update.js

@@ -25,7 +25,10 @@ import { dirname, join, posix, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
+import { classifyInstall } from '../utils/install-provenance.js';
 import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { pruneAfterInstall } from '../utils/prune-prefix.js';
 const PACKAGE_NAME = '@gjsify/cli';
 export const selfUpdateCommand = {
     command: 'self-update',
@@ -45,6 +48,11 @@ export const selfUpdateCommand = {
         description: 'npm dist-tag or pinned version to install (e.g. `latest`, `next`, `0.5.0`).',
         type: 'string',
         default: 'latest',
+    })
+        .option('prune', {
+        description: 'After updating, remove packages an earlier install left behind that this host cannot use (foreign os/cpu/libc). Use --no-prune to disable.',
+        type: 'boolean',
+        default: true,
     })
         .option('skip-deps', {
         description: 'Update only the @gjsify/cli bundle itself; do not pull its runtime dependencies ' +
@@ -60,6 +68,24 @@ export const selfUpdateCommand = {
         const currentVersion = readCurrentVersion();
         const installedAtPrefix = existsSync(installedPkgJson);
         console.log(`Current ${PACKAGE_NAME}: v${currentVersion ?? '(unknown)'}`);
+        // REFUSE, do not warn-and-continue, when something else owns this install.
+        //
+        // Everything below writes the user-global XDG prefix. Under a `.deb`,
+        // `.rpm` or Flatpak that produces a SECOND copy which shadows the one the
+        // package manager tracks — so the next `apt upgrade` reverts it, or the two
+        // diverge, and the user's report is "I updated and nothing changed". A
+        // clean refusal naming the right command is strictly more useful than a
+        // successful write to the wrong place; #1064 is the same lesson one layer
+        // down, where the write succeeded and PATH still resolved the old binary.
+        const provenance = classifyInstall({ selfDir: readSelfDir(), xdgPrefix: layout.prefix });
+        if (provenance.managedElsewhere) {
+            console.error(`\ngjsify self-update: this gjsify is managed by something else — ${provenance.evidence}.\n` +
+                `Updating it from here would write ${layout.prefix} and leave you running two installs.\n\n` +
+                `Update with: ${provenance.updateWith}\n`);
+            // `return process.exit()` — a bare `process.exit()` is DEFERRED under
+            // GJS and the handler would run on into the install it just refused.
+            return process.exit(1);
+        }
         if (!installedAtPrefix) {
             console.warn(`\nWarning: no @gjsify/cli install found under ${layout.prefix}.\n` +
                 `self-update only manages installs created by install.mjs or \`gjsify install -g\`.\n` +
@@ -157,6 +183,13 @@ export const selfUpdateCommand = {
         if (pullDeps) {
             await installGjsEnginePackages(layout.prefix, target, { verbose: false });
         }
+        // Same ordering reason as `install -g`: before the LINK, whose launchers bake
+        // the resolved prebuild directories into their env.
+        if (args.prune !== false) {
+            pruneAfterInstall(layout.prefix, resolveHostPlatform({ env: {} }), {
+                hint: 'gjsify prune -g --dry-run',
+            });
+        }
         const linked = linkGlobalBins([PACKAGE_NAME], layout);
         if (linked.length === 0) {
             console.warn('self-update: install completed but no bins were linked — package.json may be missing a `bin` field.');
@@ -246,6 +279,28 @@ export function verifyPathResolution(opts) {
  * `import.meta.url` (the bundle file under GJS, or `lib/index.js` under
  * Node) until it finds a package.json with `name === '@gjsify/cli'`.
  */
+/**
+ * The directory of the running CLI's own package — the input the provenance
+ * question is actually about.
+ *
+ * The same upward walk `readCurrentVersion()` does, and for the same reason: it
+ * works from `lib/index.js` under Node and from the published `dist/cli.gjs.mjs`
+ * bundle under GJS. Honours the same `GJSIFY_CLI_PACKAGE_JSON` escape hatch, so a
+ * test can place a synthetic install anywhere without a real one.
+ */
+function readSelfDir() {
+    const override = process.env.GJSIFY_CLI_PACKAGE_JSON;
+    if (override)
+        return dirname(resolve(override));
+    const here = fileURLToPath(import.meta.url);
+    let dir = dirname(resolve(here));
+    for (let i = 0; i < 8 && dir !== dirname(dir); i++) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        dir = dirname(dir);
+    }
+    return dirname(resolve(here));
+}
 function readCurrentVersion() {
     try {
         // Escape hatch for tests: point GJSIFY_CLI_PACKAGE_JSON at a synthetic

package/lib/templates/install.mjs.tmpl

@@ -188,9 +188,14 @@ function checkGjsVersion() {
     if (major < 1 || (major === 1 && minor < 86)) {
         error(`gjs ${major}.${minor} is too old — gjsify requires gjs 1.86 or newer.`);
         error('Install hints:');
-        error('  Fedora 43+:  sudo dnf install gjs');
-        error('  Debian 13+:  sudo apt install gjs');
-        error('  Arch:        sudo pacman -S gjs');
+        error('  Fedora 43+:      sudo dnf install gjs');
+        error('  Arch:            sudo pacman -S gjs');
+        // NOT "Debian 13+". Measured 2026-08-16 against tracker.debian.org: trixie
+        // (13, stable) ships 1.82.3, forky (testing) 1.88.1, sid 1.89.2 — 1.84 and
+        // 1.86 were skipped entirely. Sending a trixie user to `apt install gjs`
+        // hands them the very version this branch just rejected, from the branch
+        // that rejected it. Same fact, same wording as `utils/ship/depends.ts`.
+        error('  Debian forky/sid: sudo apt install gjs   (trixie ships 1.82.3 — too old)');
         exit(1);
     }
 }

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

@@ -126,8 +126,8 @@ export declare const PACKAGE_DEPS: Record<string, string[]>;
  */
 export declare function runAllChecks(cwd: string): DepCheck[];
 /**
- * Minimal checks needed to run any GJS example (Node + GJS binaries only).
- * Used by `gjsify showcase` for examples that have no native deps.
+ * Minimal checks needed to run any GJS example (the GJS binary; Node is reported but
+ * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
 /**

package/lib/utils/check-system-deps.js

@@ -18,6 +18,7 @@ import { readFileSync, existsSync, readdirSync } from 'node:fs';
 // The zero-dependency subpath, deliberately: importing the plugin root would
 // pull vite/execa/minify-xml into a system CHECK.
 import { resolveBlueprintCompiler } from '@gjsify/vite-plugin-blueprint/resolve';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
     try {
@@ -378,13 +379,41 @@ export function runAllChecks(cwd) {
     ];
 }
 /**
- * Minimal checks needed to run any GJS example (Node + GJS binaries only).
- * Used by `gjsify showcase` for examples that have no native deps.
+ * Is a Node.js runtime available — asked of the host rather than asserted.
+ *
+ * This row used to be the literal `{found: true, version: process.version}`, which is
+ * a lie on three of the four hosts: `@gjsify/process` stubs `process.version` to
+ * `"v20.0.0"` for npm compatibility (Bun and Deno fake `process.versions.node` for the
+ * same reason), so `gjsify system-check` under GJS reported `✓ Node.js (v20.0.0)` on a
+ * machine with no Node on it — under the NODE-FREE toolchain, whose entire premise is
+ * that there is none. `cli-app.ts`'s `runtimeLabel()` already had to know better; one
+ * question gets one answer, so this asks the same module.
+ *
+ * Under Node the running process IS the answer and its version cannot be faked from
+ * inside; elsewhere it is a PATH question whose answer may legitimately be "no".
+ *
+ * `isNode()` rather than `hostRuntime() === 'node'`: the latter RETURNS `'node'` as its
+ * fallback for an unrecognised host, which would put an exotic runtime's possibly-stubbed
+ * `process.version` on the trusted branch. `isNode()` demands positive evidence.
+ *
+ * `optional`, never `required`: `gjsify showcase` and `gjsify install` both treat a
+ * missing `required` row as fatal, and a GJS showcase needs no Node. The old row could
+ * not have failed either gate — it was constant — so nothing that used to pass now
+ * fails; what changes is only that the printed line is true.
+ */
+function checkNodeRuntime() {
+    if (isNode()) {
+        return { id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'optional' };
+    }
+    return checkBinary('nodejs', 'Node.js', 'node', ['--version'], 'optional');
+}
+/**
+ * Minimal checks needed to run any GJS example (the GJS binary; Node is reported but
+ * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export function runMinimalChecks() {
     const results = [];
-    // Node.js — always present
-    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'required' });
+    results.push(checkNodeRuntime());
     // GJS
     results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], 'required', (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
     // The one win32 system dependency that is real and was undiagnosed (#997).
@@ -528,6 +557,7 @@ function runOptionalChecks(needed, cwd) {
 // Entries with multiple space-separated packages are intentional (one dep needs multiple system pkgs).
 const PM_PACKAGES = {
     apt: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
@@ -553,6 +583,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-dev',
     },
     dnf: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf-pkg-config',
@@ -578,6 +609,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-devel',
     },
     pacman: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -603,6 +635,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy',
     },
     zypper: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
@@ -628,6 +661,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-devel',
     },
     apk: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -675,6 +709,7 @@ const PM_PACKAGES = {
     // Recorded here so the next reader does not "fix" the gap by guessing a name;
     // both are genuine platform gaps, not table omissions.
     brew: {
+        nodejs: 'node',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -750,8 +785,10 @@ export function buildInstallCommand(pm, missing) {
                 'mingw-w64-ucrt-x86_64-libadwaita   # inside MSYS2; found automatically afterwards');
             continue;
         }
-        if (dep.id === 'nodejs')
-            continue; // can't be missing if we're running
+        // No `continue` for `nodejs`. It USED to be unmissable — the row was the
+        // literal `found: true` — and since it became a real probe it can report
+        // absent under GJS, so skipping it here printed "Missing optional: Node.js"
+        // above an install command that did not install it.
         const pkg = pkgMap[dep.id];
         if (pkg)
             pkgs.push(pkg);

package/lib/utils/install-provenance.d.ts

@@ -0,0 +1,44 @@
+/** Where the running CLI came from. */
+export type InstallProvenanceKind = 
+/** `install.mjs` or `gjsify install -g` — the layout `self-update` manages. */
+'xdg-global'
+/** Inside a Flatpak sandbox. */
+ | 'flatpak'
+/** A distro package (`.deb`/`.rpm`) staged under a system prefix. */
+ | 'system-package'
+/** `npm install -g` (or yarn/pnpm global) — a `node_modules` tree elsewhere. */
+ | 'npm-global'
+/** A checkout, a container image, an unpacked tarball — anything else. */
+ | 'unknown';
+export interface InstallProvenance {
+    kind: InstallProvenanceKind;
+    /** What the decision was made ON, so a wrong verdict is debuggable. */
+    evidence: string;
+    /** How the user should update, when it is not `self-update`'s job. */
+    updateWith?: string;
+    /** True when `self-update` must refuse rather than write the XDG prefix. */
+    managedElsewhere: boolean;
+}
+export interface ProvenanceInput {
+    /** Absolute path of the running CLI's own package directory. */
+    selfDir: string;
+    /** `defaultGlobalLayout().prefix` — the layout `self-update` owns. */
+    xdgPrefix: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Classify an installation from its path and environment.
+ *
+ * ORDER MATTERS and is not alphabetical:
+ *
+ *  1. **Flatpak first.** Its `/app` prefix would also satisfy no other test, but
+ *     `FLATPAK_ID` is the unambiguous signal and is present even when the tree is
+ *     mounted somewhere unusual.
+ *  2. **XDG before system.** The XDG prefix is under `$HOME`, so it can never be
+ *     `/usr` — but a user whose `$HOME` is `/opt/someuser` exists, and asking the
+ *     narrow question first means that user is not told to run `dnf`.
+ *  3. **System before npm.** A `.deb` stages a `node_modules`-shaped tree under
+ *     `/usr/lib`, so the npm test alone would claim it.
+ */
+export declare function classifyInstall(input: ProvenanceInput): InstallProvenance;