@gjsify/cli 0.39.0 → 0.41.0

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/cli-runtime-closure.d.ts

@@ -0,0 +1,23 @@
+import type { Workspace } from '@gjsify/workspace';
+export declare function moduleSpecifiers(code: string): string[];
+export interface CliRuntimeClosureOptions {
+    /**
+     * File to start the walk from. Defaults to the running CLI's Node entry
+     * (`bin.gjsify`), which is what a spawned child loads.
+     */
+    entry?: string | null;
+    /** The CLI's own manifest, for its optional peers. Read from disk by default. */
+    cliManifest?: {
+        peerDependencies?: Record<string, string>;
+    } | null;
+}
+/**
+ * Workspace packages the running CLI imports, so a parallel sweep can build them
+ * first instead of underneath itself.
+ *
+ * Empty is the correct answer in three real situations and none of them is an
+ * error: a consumer project (its `@gjsify/*` deps are not workspaces, so nothing
+ * the sweep builds can tear), a relocated bundle with no reachable manifest, and
+ * a CLI whose entry has not been built.
+ */
+export declare function cliRuntimeClosure(workspaces: readonly Workspace[], options?: CliRuntimeClosureOptions): Set<string>;

package/lib/utils/cli-runtime-closure.js

@@ -0,0 +1,274 @@
+// Which workspace packages does the RUNNING CLI import at runtime?
+//
+// WHY THE SCHEDULER NEEDS THIS
+//
+// `gjsify foreach <script> -p` spawns children, and every child is another
+// `gjsify` process: it BOOTS the CLI before it runs anything. So while a parallel
+// sweep rebuilds the workspace, each child is reading the very `lib/` trees its
+// siblings are writing. Measured on the macOS leg (run 31130155911,
+// darwin-arm64), on the first full build that leg ever reached:
+//
+//     [gjsify foreach] start @gjsify/native-platform (49/160 done, 3 in flight)
+//     [gjsify foreach] start @gjsify/npm-registry    (50/160 done, 3 in flight)
+//     [@gjsify/native-platform] ERR_MODULE_NOT_FOUND
+//       .../npm-registry/lib/esm/_virtual/_rolldown/runtime.js
+//       imported from .../npm-registry/lib/esm/auth.js
+//
+// `auth.js` was on disk and its rolldown chunk was not — a torn write, not a
+// corrupt build. `foreach` uses this set to build those packages BEFORE the
+// parallel sweep starts, so nothing rewrites them while a child boots.
+//
+// WHY IT IS DERIVED AND NOT LISTED
+//
+// The four names a root script once carried by hand (`semver`, `npm-registry`,
+// `tar`, `workspace`) were never the whole answer, and a hand-written list is the
+// same defect one level up: it is right until an import changes. Two measured
+// alternatives were rejected before this one:
+//
+//   * the MANIFEST closure of `@gjsify/cli` (transitive workspace `dependencies`)
+//     selects 110 of the ~160 packages a full sweep builds — it counts the
+//     umbrella polyfill metas the CLI declares for the alias layer and never
+//     imports under Node. Serialising 110 packages is not a fix, it is the end of
+//     parallelism;
+//   * a regex over the sources reports 27, because `commands/storybook.ts` emits
+//     GENERATED CODE containing `import { … } from '@gjsify/storybook';` inside a
+//     template literal. A text scan cannot tell a program from a string, and that
+//     one string drags the whole GTK storybook subtree into the prefix.
+//
+// So the graph is PARSED, from the entry the children actually boot, and the
+// answer was checked against ground truth: a Node loader hook recording every
+// `file:` URL `gjsify --version` loads reports exactly the ten packages this walk
+// returns (see `cli-runtime-closure.spec.ts` for the shape the walk must keep).
+//
+// THE ONE THING A PARSE CANNOT SEE
+//
+// A COMPUTED dynamic import. `bundler-pick.ts` loads the bundler engine as
+// `await import(target)` where `target` is a resolved file URL, and
+// `rolldown-plugin-gjsify`'s `css-as-string.ts` does the same for lightningcss —
+// deliberately, so tsc and rolldown do not resolve an optional peer at build
+// time. Those are invisible to any static walk, and they are invisible to npm for
+// the same reason, which is exactly why the convention is to declare them as
+// optional PEER dependencies. So the peers of every package in the graph are
+// added: one declaration closes both blind spots, and it stays a declaration the
+// package owns rather than a list this file keeps.
+import * as acorn from 'acorn';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { cliPackageDir } from './publish-headers.js';
+/**
+ * Split a bare specifier into a WORKSPACE package name + its `exports` key, or
+ * `null` when it names no workspace.
+ *
+ * Matched against the workspace index rather than against the `@gjsify/` scope: a
+ * scope literal would be a second place that has to be edited when the project is
+ * vendored, forked or renamed, and the question here is only ever "is this one of
+ * OUR packages". Scoped names take two segments, unscoped one.
+ */
+function splitWorkspaceSpecifier(specifier, byName) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.includes(':'))
+        return null;
+    const parts = specifier.split('/');
+    const candidates = specifier.startsWith('@') ? [2] : [1];
+    for (const depth of candidates) {
+        const name = parts.slice(0, depth).join('/');
+        if (!byName.has(name))
+            continue;
+        const rest = parts.slice(depth).join('/');
+        return { name, subpath: rest ? `./${rest}` : '.' };
+    }
+    return null;
+}
+/**
+ * The string a module specifier node names, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ */
+function literalSpecifier(node) {
+    if (node?.type === 'Literal')
+        return typeof node.value === 'string' ? node.value : null;
+    if (node?.type === 'TemplateLiteral' && node.expressions?.length === 0) {
+        const cooked = node.quasis?.[0]?.value?.cooked;
+        return typeof cooked === 'string' ? cooked : null;
+    }
+    return null;
+}
+export function moduleSpecifiers(code) {
+    let ast;
+    try {
+        ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        const n = node;
+        if (n.type === 'ImportDeclaration' ||
+            n.type === 'ExportNamedDeclaration' ||
+            n.type === 'ExportAllDeclaration' ||
+            n.type === 'ImportExpression') {
+            const specifier = literalSpecifier(n.source);
+            if (specifier !== null)
+                out.push(specifier);
+        }
+        for (const [key, value] of Object.entries(n)) {
+            if (key === 'type' || key === 'start' || key === 'end' || key === 'loc')
+                continue;
+            visit(value);
+        }
+    };
+    visit(ast);
+    return out;
+}
+/** The file a relative specifier names, probing the extensionless spellings Node accepts. */
+function resolveRelative(fromFile, specifier) {
+    const base = resolvePath(dirname(fromFile), specifier);
+    for (const candidate of [base, `${base}.js`, `${base}.mjs`, join(base, 'index.js')]) {
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* not this spelling */
+        }
+    }
+    return null;
+}
+/**
+ * The file a workspace package's `<subpath>` resolves to, read from its own
+ * manifest. `subpath` is `'.'` for a bare package specifier.
+ *
+ * The `exports` conditions are walked in the order the CHILD's runtime resolves
+ * them; `main`/`module` is the pre-`exports` fallback. Deliberately NOT
+ * `import.meta.resolve`: that answers only for the runtime doing the asking, and
+ * this walk must give the same answer from Node and from GJS, from a spec with a
+ * fixture tree as from a real install. Resolving the SUBPATH rather than the
+ * package root matters — `@gjsify/rolldown-plugin-gjsify/runtime` is a leaf, and
+ * substituting the root barrel for it would drag in everything the barrel
+ * re-exports and nothing imports.
+ */
+function workspaceEntry(ws, subpath) {
+    const manifest = ws.manifest;
+    const pick = (node) => {
+        if (typeof node === 'string')
+            return node;
+        if (!node || typeof node !== 'object' || Array.isArray(node))
+            return null;
+        const record = node;
+        for (const condition of ['node', 'import', 'default', 'gjs']) {
+            if (condition in record) {
+                const picked = pick(record[condition]);
+                if (picked)
+                    return picked;
+            }
+        }
+        return null;
+    };
+    let target = null;
+    if (typeof manifest.exports === 'string')
+        target = subpath === '.' ? manifest.exports : null;
+    else if (manifest.exports && typeof manifest.exports === 'object') {
+        target = pick(manifest.exports[subpath]);
+    }
+    if (!target && subpath === '.') {
+        target = typeof manifest.module === 'string' ? manifest.module : null;
+        target ??= typeof manifest.main === 'string' ? manifest.main : null;
+    }
+    if (!target)
+        return null;
+    const file = resolvePath(ws.location, target);
+    return existsSync(file) ? file : null;
+}
+/** `peerDependencies` of `manifest` that name a workspace package. */
+function workspacePeers(manifest, byName) {
+    return Object.keys(manifest.peerDependencies ?? {}).filter((name) => byName.has(name));
+}
+/**
+ * Workspace packages the running CLI imports, so a parallel sweep can build them
+ * first instead of underneath itself.
+ *
+ * Empty is the correct answer in three real situations and none of them is an
+ * error: a consumer project (its `@gjsify/*` deps are not workspaces, so nothing
+ * the sweep builds can tear), a relocated bundle with no reachable manifest, and
+ * a CLI whose entry has not been built.
+ */
+export function cliRuntimeClosure(workspaces, options = {}) {
+    const byName = new Map(workspaces.map((ws) => [ws.name, ws]));
+    const found = new Set();
+    let entry = options.entry;
+    let cliManifest = options.cliManifest;
+    if (entry === undefined || cliManifest === undefined) {
+        const packageDir = cliPackageDir();
+        let manifest = null;
+        if (packageDir) {
+            try {
+                manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+            }
+            catch {
+                /* unreadable — the closure degrades to empty, which is a no-op prefix */
+            }
+        }
+        cliManifest ??= manifest;
+        if (entry === undefined) {
+            // The npm `bin` entry, NOT `gjsify.bin`: the GJS bundle is self-contained,
+            // so walking it would report nothing, while a GJS child still loads the
+            // engine facades through the peers below. The `lib/` graph is a superset
+            // of what either entry reaches, and one code path beats two.
+            const bin = manifest?.bin;
+            const relative = typeof bin === 'string' ? bin : (bin?.['gjsify'] ?? manifest?.main);
+            entry = packageDir && relative ? resolvePath(packageDir, relative) : null;
+        }
+    }
+    for (const peer of workspacePeers(cliManifest ?? {}, byName))
+        found.add(peer);
+    if (!entry || !existsSync(entry))
+        return found;
+    const seen = new Set();
+    const queue = [entry];
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const specifier of moduleSpecifiers(code)) {
+            if (specifier.startsWith('.')) {
+                const next = resolveRelative(file, specifier);
+                if (next)
+                    queue.push(next);
+                continue;
+            }
+            const split = splitWorkspaceSpecifier(specifier, byName);
+            const ws = split ? byName.get(split.name) : undefined;
+            if (!split || !ws)
+                continue;
+            found.add(split.name);
+            for (const peer of workspacePeers(ws.manifest, byName))
+                found.add(peer);
+            // Queued per SUBPATH, not per package: `seen` dedupes files, so a
+            // package imported through two subpaths is walked through both. A
+            // package-level visited set would stop at whichever subpath came
+            // first and miss what the other one reaches.
+            const next = workspaceEntry(ws, split.subpath);
+            if (next)
+                queue.push(next);
+        }
+    }
+    return found;
+}

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;

package/lib/utils/install-provenance.js

@@ -0,0 +1,106 @@
+// How was THIS gjsify installed?
+//
+// `self-update` re-runs the `gjsify install -g` pipeline, which writes into the
+// user-global XDG prefix. That is correct for an install that came from
+// `install.mjs` or `gjsify install -g`, and WRONG for one a package manager owns:
+// it would lay a second copy into `~/.local` that shadows — or is shadowed by —
+// the one apt/dnf/flatpak is tracking, and the package manager would then be
+// managing a file the user no longer runs. The next `apt upgrade` reverts or
+// diverges, silently, and "I updated it and nothing changed" is the report.
+//
+// Before `gjsify ship` there was only one non-XDG case worth naming (`npm -g`),
+// and the command warned and continued. Now that gjsify ships as `.deb`, `.rpm`
+// and Flatpak, continuing is the defect. So the question gets a real answer, and
+// the answer carries the command the user should run instead.
+//
+// Everything here is derived from where the RUNNING code sits, never from a
+// build-time constant: one tarball is unpacked by all of these routes, so a flag
+// baked at build time would describe the builder rather than the installation.
+import { posix, win32 } from 'node:path';
+/** System prefixes a distro package stages into. POSIX only — win32 handled separately. */
+const SYSTEM_PREFIXES = ['/usr/', '/opt/', '/snap/'];
+/** Inside a Flatpak the whole app tree lives under this prefix. */
+const FLATPAK_PREFIX = '/app/';
+/**
+ * The TARGET platform's path module, never the host's.
+ *
+ * Same rule as `pathFor` in `install-global.ts`, and for the same reason: this
+ * function ACCEPTS a `platform` and must therefore answer for it. Reading the
+ * host's `node:path` instead makes every POSIX-shaped case unanswerable from a
+ * Windows runner — which is exactly what happened. Four of these tests went red on
+ * the win32 leg, on `main`, because `resolve('/app/lib')` there is `C:\app\lib`
+ * and `sep` is a backslash.
+ */
+function pathFor(platform) {
+    return platform === 'win32' ? win32 : posix;
+}
+/** Does `child` sit inside `parent`? Both must be absolute and already resolved. */
+function isInside(child, parent, platform) {
+    const p = pathFor(platform);
+    if (!p.isAbsolute(child) || !p.isAbsolute(parent))
+        return false;
+    const withSep = parent.endsWith(p.sep) ? parent : parent + p.sep;
+    return child === parent || child.startsWith(withSep);
+}
+/**
+ * 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 function classifyInstall(input) {
+    const env = input.env ?? process.env;
+    const platform = input.platform ?? process.platform;
+    const p = pathFor(platform);
+    const selfDir = p.resolve(input.selfDir);
+    if (env.FLATPAK_ID || isInside(selfDir, FLATPAK_PREFIX, platform)) {
+        const id = env.FLATPAK_ID ?? 'io.github.gjsify.Cli';
+        return {
+            kind: 'flatpak',
+            evidence: env.FLATPAK_ID ? `FLATPAK_ID=${env.FLATPAK_ID}` : `running from ${FLATPAK_PREFIX}`,
+            updateWith: `flatpak update ${id}`,
+            managedElsewhere: true,
+        };
+    }
+    if (isInside(selfDir, p.resolve(input.xdgPrefix), platform)) {
+        return {
+            kind: 'xdg-global',
+            evidence: `running from the user-global prefix ${input.xdgPrefix}`,
+            managedElsewhere: false,
+        };
+    }
+    if (platform !== 'win32' && SYSTEM_PREFIXES.some((pfx) => isInside(selfDir, pfx, platform))) {
+        return {
+            kind: 'system-package',
+            evidence: `running from the system prefix ${selfDir}`,
+            // Not `apt` or `dnf` specifically: the same path serves both, and
+            // guessing wrong sends the user to a package manager that does not
+            // know this file. The release assets are named because they are the
+            // one answer that is true on every distribution.
+            updateWith: 'your distribution package manager (`apt upgrade` / `dnf upgrade` / …), or install the newer package from ' +
+                'https://github.com/gjsify/gjsify/releases/latest',
+            managedElsewhere: true,
+        };
+    }
+    if (selfDir.split(p.sep).includes('node_modules')) {
+        return {
+            kind: 'npm-global',
+            evidence: `running from a node_modules tree at ${selfDir}`,
+            updateWith: 'npm install -g @gjsify/cli@latest (or switch to the Node-free bootstrap)',
+            managedElsewhere: true,
+        };
+    }
+    return {
+        kind: 'unknown',
+        evidence: `running from ${selfDir}, which matches no known install layout`,
+        managedElsewhere: false,
+    };
+}

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;