@gjsify/cli 0.52.0 → 0.54.0

package/lib/utils/bundle-inputs.js

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: MIT
+// The SECOND half of "what are this bundle's build inputs" — what the BUNDLER
+// read, recorded at build time beside the bundle it produced.
+//
+// `package-inputs.ts` answers the other half by walking the package, and that
+// walk cannot see outside the package. A consumer's test bundle routinely reads
+// outside it: a workspace package reached through `node_modules/<name>` — a
+// SYMLINK into a sibling directory — is a file the build read and the walk
+// never enumerates. An edit there left `gjsify test` judging a fresh bundle and
+// rerunning it: a stale GREEN, the worst kind of wrong, and the only remedy a
+// consumer had was `rm -rf dist`.
+//
+// The set is recorded from the bundler's own module graph rather than guessed
+// from a directory list: a bare specifier's resolution is known to the bundler
+// and to nobody else, and a list of "likely dirs" is wrong for every layout
+// nobody anticipated — the same failure `package-inputs.ts` documents twice.
+//
+// TWO halves, because the bundler is not the only reader: a `transform`
+// observer sees every MODULE, and the engine's watch list carries what a plugin
+// read and declared itself (a stylesheet's `@import` chain is read by
+// `gjsify-css-as-string`, not by the bundler, so no graph names it). Neither
+// engine reports both, so the recorder takes the union. Deciding freshness
+// stays cheap: the manifest is written once per build and read as `stat` calls.
+//
+// `package-inputs.ts` is not replaced by this. Its walk answers "what MAY this
+// package's build read", which covers a file the current build does not import
+// yet; this answers "what DID this build read", which reaches outside the
+// package. The union is the honest input set, and both halves must exist.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+/**
+ * Bumped when the shape changes; a manifest of any other version is ignored.
+ *
+ * v2 adds `watchList`. A v1 manifest says nothing about whether the engine that
+ * wrote it could report a watch list at all, and the safe reading of "unknown"
+ * is "do not trust it": see {@link readBundleInputs}.
+ */
+export const BUNDLE_INPUTS_VERSION = 2;
+/** The manifest that belongs to `outfile`. */
+export function bundleInputsPath(outfile) {
+    return `${outfile}.inputs.json`;
+}
+/**
+ * A module id as a path, or `null` when it names no file we can stat.
+ *
+ * A query or a hash is PART OF THE ID, not of the path: `@scope/pkg/x.css?raw`
+ * and `main-window.blp?shared-tree` (the blueprint plugin's shared-tree exit)
+ * both stat as ENOENT, and dropping the id silently would drop the file with
+ * it. `\0` is the bundler's virtual-module marker — no file, ever.
+ */
+function idToPath(id) {
+    if (id === '' || id.startsWith('\0'))
+        return null;
+    const cut = id.search(/[?#]/);
+    if (cut === -1)
+        return id;
+    const stripped = id.slice(0, cut);
+    // The fallback is not a nicety: `#` is LEGAL in a Linux filename, and
+    // `a#b.blp` is that file's whole name. Stripping turned it into `a`, which
+    // does not exist, and the input was dropped. So the unstripped id gets its
+    // turn — and when neither is a file, `inputs()` drops it as before.
+    return isFile(stripped) ? stripped : id;
+}
+function isFile(abs) {
+    try {
+        return statSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Files the TOOLCHAIN writes and deletes between builds, which therefore must
+ * never enter the input set.
+ *
+ * Not a filter on staleness but on membership: a vanished recorded input forces
+ * a rebuild (see {@link newestBundleInputMtimeMs}), so recording the
+ * globals-inject stub — `node_modules/.cache/gjsify/auto-globals-<hash>.mjs`,
+ * rewritten per build and DELETED when its config changes — would rebuild every
+ * run, forever. The same directory holds the cached GJS plugin bundles, which
+ * carry their own freshness rule (`bundleFileForGjsCached`).
+ *
+ * **Not a `tmpdir()` test**, which is the obvious wrong answer and the one this
+ * started as: the stub is written into the project's own cache directory
+ * (`utils/scan-globals.ts`), never to a temp dir, while a PROJECT under
+ * `/tmp` is a project — a CI job, a container, this suite's own fixtures. A
+ * freshness check that goes blind in those trees is the defect being fixed,
+ * reached from the other side.
+ */
+function isToolchainScratch(abs) {
+    return abs.includes(`${sep}node_modules${sep}.cache${sep}`);
+}
+/**
+ * The resolution files of the package a recorded input belongs to: the nearest
+ * `package.json` above it, and the `tsconfig.json` beside it when there is one.
+ *
+ * Neither is ever a module. A workspace package reached through a symlink
+ * contributes its files, but a `package.json#exports` edit — which moves what
+ * every bare specifier in the app resolves to — or a `tsconfig.json` that turns
+ * on a `paths` mapping changes the output with no file of its own in the graph.
+ * Per package, deduplicated, so the walk is a handful of stats however many
+ * modules that package contributed.
+ */
+function resolutionFilesFor(abs) {
+    const found = [];
+    for (let dir = dirname(abs);; dir = dirname(dir)) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            found.push(manifest);
+            const tsconfig = join(dir, 'tsconfig.json');
+            if (existsSync(tsconfig))
+                found.push(tsconfig);
+            return found;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return found;
+    }
+}
+/**
+ * A plugin that records every module the build transforms, plus the writer for
+ * the manifest.
+ *
+ * `transform` rather than a graph API (`getModuleIds`/`getModuleInfo`) because
+ * it is the one hook both engines run and the native bridge translates
+ * (`bundler-pick.ts` picks it verbatim). Every module that reaches the
+ * transform stage was LOADED from disk, so the observed set is what the build
+ * read — the modules it then tree-shook away are still inputs of the next
+ * build, which is the direction that errs safely.
+ *
+ * The observation is KEPT alongside {@link BundleInputsRecorder.addWatchFiles}
+ * rather than replaced by it, and neither engine is the reason: the native
+ * engine has no watch list to hand over (`BundleResult` carries warnings and
+ * output only, and its JS context had no `addWatchFile` at all until
+ * `rolldown-native` grew one), so on GJS the observed set is the only account
+ * of the modules; on npm the watch list is a superset of it. Union: the cost of
+ * a redundant path is a `stat`, the cost of a missing one is a stale green.
+ */
+export function createBundleInputsRecorder(outfile) {
+    const seen = new Set();
+    // Sticky, and pessimistic: ONE pass without a watch list is enough to know
+    // the build cannot see a plugin-read input, and the artifact must not be
+    // judged fresh on the strength of the passes that could.
+    let watchList = true;
+    const record = (raw) => {
+        const abs = idToPath(raw);
+        if (abs !== null)
+            seen.add(abs);
+    };
+    const plugin = {
+        name: 'gjsify:bundle-inputs',
+        transform(_code, id) {
+            record(id);
+            return undefined;
+        },
+    };
+    const inputs = () => {
+        const out = [];
+        const packages = new Set();
+        for (const abs of seen) {
+            let isFile;
+            try {
+                isFile = statSync(abs).isFile();
+            }
+            catch {
+                continue;
+            }
+            if (!isFile || isToolchainScratch(abs))
+                continue;
+            out.push(abs);
+            // `resolutionFilesFor` walks to the package root; one call per
+            // DIRECTORY keeps a 1000-module bundle from walking 1000 times.
+            const dir = dirname(abs);
+            if (packages.has(dir))
+                continue;
+            packages.add(dir);
+            for (const meta of resolutionFilesFor(abs))
+                out.push(meta);
+        }
+        return [...new Set(out)].sort();
+    };
+    return {
+        plugin,
+        addWatchFiles(watch) {
+            if (!watch.reportedByEngine)
+                watchList = false;
+            for (const id of watch.files)
+                record(id);
+        },
+        inputs,
+        write() {
+            const path = bundleInputsPath(outfile);
+            const manifest = { version: BUNDLE_INPUTS_VERSION, inputs: inputs(), watchList };
+            const tmp = `${path}.tmp`;
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                // Rename, not write: a manifest is read by the NEXT process, and
+                // a half-written one is a parse error there — which reads as "no
+                // manifest" and silently degrades the check to the package walk.
+                writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+                renameSync(tmp, path);
+            }
+            catch (err) {
+                try {
+                    rmSync(tmp, { force: true });
+                }
+                catch {
+                    // Nothing left to clean up — the write never got that far.
+                }
+                console.warn(`[gjsify test] could not record the build inputs beside ${path} (${err.message}) — ` +
+                    'the next run judges freshness by the package walk alone, which cannot see outside this package.');
+            }
+        },
+    };
+}
+/**
+ * The inputs recorded for `outfile` by the build that wrote it, or `null` when
+ * there is none to trust — never written, unreadable, or written by another
+ * version of this shape. `null` is the fallback the caller must handle, not an
+ * error: a bundle built by an older CLI, or copied in from elsewhere, has no
+ * manifest and is judged by the package walk alone.
+ */
+export function readBundleInputs(outfile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(bundleInputsPath(outfile), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed?.version !== BUNDLE_INPUTS_VERSION || !Array.isArray(parsed.inputs))
+        return null;
+    return {
+        inputs: parsed.inputs.filter((abs) => typeof abs === 'string'),
+        // v2 only, so a missing flag cannot be v2 — but the pessimistic reading
+        // is kept anyway: a manifest that does not vouch for its engine's watch
+        // list is not one to judge freshness on.
+        watchList: parsed.watchList === true,
+    };
+}
+/**
+ * Newest mtime (ms) among recorded inputs, or 0 for an empty set.
+ *
+ * A recorded input that has since VANISHED counts as CHANGED, exactly as the
+ * package walk counts one that vanished mid-walk: an input we cannot read is
+ * not evidence that the artifact is current. A workspace-package source deleted
+ * while the bundle still imports it is precisely that case, and skipping it
+ * would rerun a bundle built from a file that no longer exists.
+ *
+ * Safe only because the toolchain's own scratch is never RECORDED
+ * ({@link isToolchainScratch}): the globals-inject stub and the cached plugin
+ * bundles are written and deleted between builds, and treating their absence as
+ * a change would rebuild on every run, forever.
+ */
+export function newestBundleInputMtimeMs(inputs) {
+    let newest = 0;
+    for (const abs of inputs) {
+        try {
+            const { mtimeMs } = statSync(abs);
+            if (mtimeMs > newest)
+                newest = mtimeMs;
+        }
+        catch {
+            return Number.POSITIVE_INFINITY;
+        }
+    }
+    return newest;
+}

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

@@ -1,3 +1,4 @@
+import { type Win32ResolveContext } from './win32-command.js';
 export type DepSeverity = 'required' | 'optional';
 export interface DepCheck {
     /** Stable key used for install command lookup, e.g. "gjs" */
@@ -15,7 +16,8 @@ export interface DepCheck {
 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).
+ * instead of shelling out to `which`(1), honouring `PATHEXT` on win32 — see
+ * `findOnPath` in `win32-command.ts`, which owns the walk.
  *
  * `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
@@ -31,7 +33,7 @@ export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew
  * 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;
+export declare function isOnPath(cmd: string, ctx?: Win32ResolveContext): boolean;
 /**
  * The package manager whose install command we may suggest.
  *

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

@@ -1,5 +1,5 @@
 // System dependency checker for gjsify CLI.
-// Uses execFileSync with explicit argument arrays — no shell injection possible.
+// Uses spawnSync with explicit argument arrays — no shell injection possible.
 // All binary names are hardcoded constants, never derived from user input.
 //
 // Severity model:
@@ -10,25 +10,31 @@
 // optional system deps are only checked if the corresponding @gjsify/* package
 // is in the project's dependency tree. A user with only @gjsify/fs in their
 // project never sees a warning about libmanette.
-import { execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { findSystemTypelib } from './gi-typelib.js';
+import { toSpawnable } from './spawn.js';
+import { findOnPath } from './win32-command.js';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
-    try {
-        return execFileSync(binary, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    }
-    catch {
-        return null;
-    }
+    // `spawnSync`, not `execFileSync`: only the former takes the verbatim-argv
+    // flag the cmd.exe route of `toSpawnable` needs.
+    const inv = toSpawnable(binary, args);
+    const r = spawnSync(inv.cmd, inv.args, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        windowsVerbatimArguments: inv.windowsVerbatimArguments,
+    });
+    return r.error || r.status !== 0 ? null : r.stdout.trim();
 }
 /**
  * True when `cmd` is on PATH. Walks `process.env.PATH` with `existsSync`
- * instead of shelling out to `which`(1).
+ * instead of shelling out to `which`(1), honouring `PATHEXT` on win32 — see
+ * `findOnPath` in `win32-command.ts`, which owns the walk.
  *
  * `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
@@ -44,23 +50,12 @@ function tryExecFile(binary, args) {
  * reason. It stays a second copy on purpose: it is `.mjs` under `tests/` and
  * cannot be imported from the shipped CLI.
  */
-export function isOnPath(cmd) {
-    const pathVar = process.env.PATH;
-    if (!pathVar)
-        return false;
-    const sep = process.platform === 'win32' ? ';' : ':';
-    for (const dir of pathVar.split(sep)) {
-        if (!dir)
-            continue;
-        try {
-            if (existsSync(join(dir, cmd)))
-                return true;
-        }
-        catch {
-            // An inaccessible PATH entry is not an answer about `cmd`.
-        }
-    }
-    return false;
+export function isOnPath(cmd, ctx = hostPathContext()) {
+    return findOnPath(cmd, ctx) !== undefined;
+}
+/** This process's PATH, filesystem and platform — what {@link isOnPath} asks by default. */
+function hostPathContext() {
+    return { platform: process.platform, env: process.env, exists: existsSync, join };
 }
 /** Check if a binary exists and optionally capture its version output. */
 function checkBinary(id, name, binary, versionArgs, severity, parseVersion, requiredBy) {

package/lib/utils/dev-link.d.ts

@@ -184,11 +184,14 @@ export declare function assertDevLinksBuilt(links: readonly DevLink[]): void;
 /**
  * Make `.gjsify-link.json` invisible to git WITHOUT editing a tracked file.
  *
- * `.git/info/exclude` is git's own per-clone ignore list: it is not committed and
- * not shared, which is exactly the lifetime of the thing it hides. Writing to
- * `.gitignore` instead would put a developer's local override into everyone
- * else's diff — the manifest edit this whole feature exists to avoid, one file
- * over.
+ * `info/exclude` is git's own per-clone ignore list: it is not committed and
+ * not shared between clones, which is exactly the lifetime of the thing it
+ * hides. Writing to `.gitignore` instead would put a developer's local override
+ * into everyone else's diff — the manifest edit this whole feature exists to
+ * avoid, one file over. A WORKTREE is the case to get right: the file is
+ * written under the repository's COMMON dir, because `info/exclude` is shared
+ * across a repository's worktrees and the worktree's own gitdir is not read
+ * (see {@link resolveGitDir}).
  *
  * Returns what it did, so the caller can say so. A consumer that is not a git
  * repository is not an error: nothing can commit the file there either. A
@@ -199,7 +202,7 @@ export declare function ensureLocallyIgnored(consumerRoot: string): 'added' | 'a
 /**
  * Undo {@link ensureLocallyIgnored} — the other half of `unlink`.
  *
- * Measured: the `.git/info/exclude` block outlived `gjsify unlink` (idempotently,
+ * Measured: the `info/exclude` block outlived `gjsify unlink` (idempotently,
  * so it never grew — it just never left). A command that promises to undo itself
  * and leaves a line behind is not an undo, and the leftover is a rule about a file
  * that no longer exists, which the next reader has to research to delete.

package/lib/utils/dev-link.js

@@ -484,11 +484,14 @@ const IGNORE_COMMENT = '# gjsify link — local development override, never comm
 /**
  * Make `.gjsify-link.json` invisible to git WITHOUT editing a tracked file.
  *
- * `.git/info/exclude` is git's own per-clone ignore list: it is not committed and
- * not shared, which is exactly the lifetime of the thing it hides. Writing to
- * `.gitignore` instead would put a developer's local override into everyone
- * else's diff — the manifest edit this whole feature exists to avoid, one file
- * over.
+ * `info/exclude` is git's own per-clone ignore list: it is not committed and
+ * not shared between clones, which is exactly the lifetime of the thing it
+ * hides. Writing to `.gitignore` instead would put a developer's local override
+ * into everyone else's diff — the manifest edit this whole feature exists to
+ * avoid, one file over. A WORKTREE is the case to get right: the file is
+ * written under the repository's COMMON dir, because `info/exclude` is shared
+ * across a repository's worktrees and the worktree's own gitdir is not read
+ * (see {@link resolveGitDir}).
  *
  * Returns what it did, so the caller can say so. A consumer that is not a git
  * repository is not an error: nothing can commit the file there either. A
@@ -497,12 +500,12 @@ const IGNORE_COMMENT = '# gjsify link — local development override, never comm
  */
 export function ensureLocallyIgnored(consumerRoot) {
     const found = resolveGitDir(consumerRoot);
-    if (!found.gitDir)
+    if (!found.commonDir)
         return found.why;
     const gitignore = join(consumerRoot, '.gitignore');
     if (existsSync(gitignore) && fileMentionsPattern(gitignore, DEV_LINK_FILE))
         return 'already-ignored';
-    const excludePath = join(found.gitDir, 'info', 'exclude');
+    const excludePath = join(found.commonDir, 'info', 'exclude');
     if (existsSync(excludePath) && fileMentionsPattern(excludePath, DEV_LINK_FILE))
         return 'already-ignored';
     mkdirSync(dirname(excludePath), { recursive: true });
@@ -514,7 +517,7 @@ export function ensureLocallyIgnored(consumerRoot) {
 /**
  * Undo {@link ensureLocallyIgnored} — the other half of `unlink`.
  *
- * Measured: the `.git/info/exclude` block outlived `gjsify unlink` (idempotently,
+ * Measured: the `info/exclude` block outlived `gjsify unlink` (idempotently,
  * so it never grew — it just never left). A command that promises to undo itself
  * and leaves a line behind is not an undo, and the leftover is a rule about a file
  * that no longer exists, which the next reader has to research to delete.
@@ -525,9 +528,9 @@ export function ensureLocallyIgnored(consumerRoot) {
  */
 export function removeLocalIgnore(consumerRoot) {
     const found = resolveGitDir(consumerRoot);
-    if (!found.gitDir)
+    if (!found.commonDir)
         return found.why;
-    const excludePath = join(found.gitDir, 'info', 'exclude');
+    const excludePath = join(found.commonDir, 'info', 'exclude');
     let text;
     try {
         text = readFileSync(excludePath, 'utf-8');
@@ -568,10 +571,21 @@ function fileMentionsPattern(file, pattern) {
     });
 }
 /**
- * The `.git` directory for `root` — following the `gitdir:` pointer file a
- * worktree or submodule has in place of a directory. Skipping that indirection
- * would write an `info/exclude` inside a plain file's parent and silently ignore
- * nothing at all.
+ * The COMMON dir of `root`'s repository — the one whose `info/exclude` git
+ * actually reads. Two indirections get there, and in a worktree neither the
+ * repository root nor the gitdir it points at IS that directory.
+ *
+ * The first is `.git`: a directory in a clone, a `gitdir:` pointer file in a
+ * submodule, and a `gitdir:` pointer to `<common>/worktrees/<name>` in a worktree.
+ * Skipping that indirection would write an `info/exclude` inside a plain file's
+ * parent and silently ignore nothing at all.
+ *
+ * The second is `commondir`, and it is the one that was missed: `info/exclude` is
+ * SHARED across a repository's worktrees (git-worktree(1)), so in a worktree the
+ * pointer leads AWAY from the file git reads. Measured: with the entry written
+ * under `<common>/worktrees/<name>/info/exclude`, `git status` in the worktree
+ * still printed `?? .gjsify-link.json` and `git check-ignore` named no rule — one
+ * `git add -A` from committing the override this feature exists to keep out.
  *
  * TWO outcomes, not one. "There is no repository here" and "there is one and its
  * pointer does not parse" call for opposite reactions — the first is fine, the
@@ -585,22 +599,60 @@ function resolveGitDir(root) {
         stat = statSync(dotGit);
     }
     catch {
-        return { gitDir: null, why: 'no-git' };
+        return { commonDir: null, why: 'no-git' };
     }
     if (stat.isDirectory())
-        return { gitDir: dotGit, why: 'no-git' };
+        return { commonDir: dotGit, why: 'no-git' };
     let pointer;
     try {
         pointer = readFileSync(dotGit, 'utf-8').trim();
     }
     catch {
-        return { gitDir: null, why: 'unreadable-git' };
+        return { commonDir: null, why: 'unreadable-git' };
     }
     const match = /^gitdir:\s*(.+)$/.exec(pointer);
     const target = match?.[1]?.trim();
     if (!target)
-        return { gitDir: null, why: 'unreadable-git' };
-    return { gitDir: isAbsolute(target) ? target : resolve(root, target), why: 'no-git' };
+        return { commonDir: null, why: 'unreadable-git' };
+    return followCommondir(isAbsolute(target) ? target : resolve(root, target));
+}
+/**
+ * The shared directory of the gitdir a `gitdir:` pointer named.
+ *
+ * A plain clone and a submodule have no `commondir` file: there the gitdir IS the
+ * common dir, and nothing changes. A worktree has one — `../..`, relative to the
+ * worktree gitdir, is what `git worktree add` writes — and an absolute path is
+ * honored rather than resolved against the gitdir, where it would name a
+ * directory that does not exist.
+ *
+ * A `commondir` that names NOTHING is not read as absent, which is the decision
+ * this shape exists to force. Measured against real git, all three such shapes
+ * exit 128: blank → "error reading …/commondir", a directory → the same, a path
+ * that is not there → "not a git repository". So there is no answer to fall back
+ * to, and `no-git` would announce "nothing here can commit the file" about a
+ * repository that just refused to be one — the same "I could not tell" that is not
+ * a "yes", as everywhere else in this file.
+ */
+function followCommondir(gitDir) {
+    const file = join(gitDir, 'commondir');
+    if (!existsSync(file))
+        return { commonDir: gitDir, why: 'no-git' };
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf-8');
+    }
+    catch {
+        return { commonDir: null, why: 'unreadable-git' };
+    }
+    const target = raw.trim();
+    if (!target)
+        return { commonDir: null, why: 'unreadable-git' };
+    const commonDir = isAbsolute(target) ? target : resolve(gitDir, target);
+    // The third shape git refuses: writing an `info/exclude` under a directory that
+    // is not there would create a tree that nothing ever reads.
+    if (!existsSync(commonDir))
+        return { commonDir: null, why: 'unreadable-git' };
+    return { commonDir, why: 'no-git' };
 }
 /**
  * `--immutable` must never accept an active override — FAIL CLOSED.