@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/dev-link.js

@@ -0,0 +1,684 @@
+// `gjsify link` — a development OVERRIDE that points a consumer's `@gjsify/*`
+// dependencies at a local gjsify checkout, without touching what the consumer
+// COMMITS.
+//
+// THE NEED (ADR 0065). A consumer repo — Learn6502 is the measured one — pins
+// `@gjsify/*` to registry versions (`^0.51.1`) and commits `gjsify-lock.json`.
+// Developing a change that spans the platform and the app then means waiting for
+// an npm release for every iteration, because the installer knows exactly two
+// spec shapes: a registry range and `workspace:`. ADR 0060 § P6 recommended
+// against `link:`/`portal:` "unless a specific unfixable need appears" — this is
+// that need, and the answer it takes is deliberately NOT a resolution protocol.
+//
+// WHY AN OVERRIDE AND NOT A MANIFEST EDIT. A `link:` spec in `package.json` (or a
+// rewritten lockfile) makes the development tree part of what CI, Flatpak and
+// `--immutable` build. Those three must keep building exactly what is committed,
+// so the override lives in a local, git-ignored file — `.gjsify-link.json` — that
+// only the developer's own installs read.
+//
+// THE TRAP THIS EXISTS TO CLOSE. A bare `npm link` is undone by the next
+// `npm install`: the link is replaced by the registry copy and nothing says so.
+// Here the installer READS the override, excludes the linked names from its
+// fetch/extract set and re-wires the links on every run — and says which ones, so
+// a linked tree is never a silent build input.
+//
+// WHY THE INSTALLER MUST EXCLUDE THEM RATHER THAN RE-LINK AFTERWARDS. Measured:
+// with `node_modules/@gjsify/<name>` a symlink OUT of `node_modules`,
+// `assertNodeModulesDest` (install-backend-native.ts) refuses the extract and
+// aborts the WHOLE install — correctly, since `rmSync` through that link would
+// delete the checkout's own source. Re-linking after the fact is therefore not an
+// option: there is no "after" to link in.
+//
+// WHY THE EXCLUSION IS NOT `workspaceNames`. That option is also handed to
+// `resolveDeps`, which drops the whole subtree from the RESOLVE — and the resolve
+// is what writes `gjsify-lock.json`. Reusing it would rewrite the consumer's
+// committed lockfile the moment a link is active, which is the one thing this
+// feature promises not to do. `linkedNames` therefore applies after the lockfile
+// is written and only to what gets fetched.
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
+import { linkDirSync } from './dir-link.js';
+import { readPackageJson } from './pkg-json.js';
+import { scanPrefix } from './prune-prefix.js';
+import { findWorkspaceRoot } from './workspace-root.js';
+/** The consumer-local override file. Git-ignored; never committed. */
+export const DEV_LINK_FILE = '.gjsify-link.json';
+export function devLinkPath(root) {
+    return join(root, DEV_LINK_FILE);
+}
+/**
+ * Read the override at `root`, or `null` when there is none.
+ *
+ * A file that exists but does not parse is an ERROR, not a `null`: this decides
+ * where a build's inputs come from, and "unreadable" must never be answered with
+ * the registry's copy while the developer believes their checkout is in play.
+ */
+export function readDevLinkOverride(root) {
+    const path = devLinkPath(root);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`gjsify link: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Fix it or run \`gjsify unlink\`.`);
+    }
+    if (!raw || typeof raw !== 'object') {
+        throw new Error(`gjsify link: ${path} must contain a JSON object.`);
+    }
+    const record = raw;
+    if (record.version !== 1) {
+        throw new Error(`gjsify link: ${path} declares version ${JSON.stringify(record.version)}; this CLI understands version 1 only.`);
+    }
+    if (typeof record.checkout !== 'string' || record.checkout.trim() === '') {
+        throw new Error(`gjsify link: ${path} has no "checkout" path.`);
+    }
+    return {
+        version: 1,
+        // Relative is tolerated on the READ side — a hand-edited file is a
+        // legitimate way to move a link — and resolved against the consumer root,
+        // which is the only directory the file's own location pins down.
+        checkout: isAbsolute(record.checkout) ? record.checkout : resolve(root, record.checkout),
+        packages: Array.isArray(record.packages)
+            ? record.packages.filter((p) => typeof p === 'string')
+            : [],
+    };
+}
+export function writeDevLinkOverride(root, override) {
+    const path = devLinkPath(root);
+    writeFileSync(path, JSON.stringify(override, null, 2) + '\n');
+    return path;
+}
+/** Remove the override file; returns its path when one was there. */
+export function removeDevLinkOverride(root) {
+    const path = devLinkPath(root);
+    if (!existsSync(path))
+        return null;
+    rmSync(path);
+    return path;
+}
+/**
+ * Which directory's override governs an install started in `startDir`.
+ *
+ * Same walk `projectInstallNative` does for the install itself: a member of a
+ * workspace installs the workspace, so the override that applies is the
+ * workspace root's — otherwise `gjsify install` inside a member would silently
+ * ignore a link the root declares.
+ */
+export function devLinkRoot(startDir) {
+    if (existsSync(devLinkPath(startDir)))
+        return startDir;
+    const wsRoot = findWorkspaceRoot(startDir);
+    if (wsRoot && existsSync(devLinkPath(wsRoot)))
+        return wsRoot;
+    return startDir;
+}
+/**
+ * Turn `override.checkout` into the workspace list behind it, or refuse.
+ *
+ * A DEAD LINK IS AN ERROR WITH A PATH, never a quiet fall back to the registry:
+ * the developer asked for their checkout, and installing the published copy
+ * instead produces a build that looks like the one they wanted and is not. Both
+ * refusals print the measured path, because "it points somewhere wrong" is only
+ * actionable with the somewhere in it.
+ */
+export function resolveCheckoutWorkspaces(checkout, overridePath) {
+    if (!existsSync(checkout)) {
+        throw new Error(`gjsify link: the linked checkout ${checkout} does not exist (named by ${overridePath}). ` +
+            `Point it at a gjsify checkout, or run \`gjsify unlink\`.`);
+    }
+    const manifest = readPackageJson(join(checkout, 'package.json'));
+    if (!manifest || manifest.workspaces === undefined) {
+        throw new Error(`gjsify link: ${checkout} is not a gjsify workspace — ${join(checkout, 'package.json')} ` +
+            `${manifest ? 'declares no "workspaces" field' : 'is missing or unreadable'} (named by ${overridePath}).`);
+    }
+    let workspaces;
+    try {
+        workspaces = discoverWorkspaces(checkout);
+    }
+    catch (err) {
+        throw new Error(`gjsify link: ${checkout} declares "workspaces" but they could not be discovered ` +
+            `(${err instanceof Error ? err.message : String(err)}); named by ${overridePath}.`);
+    }
+    if (workspaces.length === 0) {
+        throw new Error(`gjsify link: ${checkout} declares "workspaces" but none were found (named by ${overridePath}).`);
+    }
+    return workspaces;
+}
+/**
+ * The dependency names the consumer would otherwise take from the registry.
+ *
+ * Two readers, one answer: what its manifests DECLARE (so a fresh clone can be
+ * linked before it has ever installed) and what its `node_modules` already HOLDS
+ * (so transitive `@gjsify/*` packages — the ones nobody declares and every build
+ * loads — are covered too).
+ */
+export function consumerKnownNames(consumerRoot) {
+    const names = new Set();
+    const manifests = [readPackageJson(join(consumerRoot, 'package.json'))];
+    try {
+        for (const ws of discoverWorkspaces(consumerRoot))
+            manifests.push(ws.manifest);
+    }
+    catch {
+        // Not a workspace, or an unreadable member — the root manifest and the
+        // installed tree still answer the question.
+    }
+    for (const manifest of manifests) {
+        if (!manifest)
+            continue;
+        for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+            const block = manifest[kind];
+            if (!block || typeof block !== 'object')
+                continue;
+            for (const name of Object.keys(block))
+                names.add(name);
+        }
+    }
+    for (const pkg of scanPrefix(consumerRoot))
+        names.add(pkg.name);
+    return names;
+}
+/**
+ * The links an override asks for: the checkout's workspace packages, narrowed by
+ * the name globs, INTERSECTED with what the consumer actually depends on.
+ *
+ * The intersection is the point. Linking every workspace package of a 200-member
+ * monorepo into a consumer that uses eight would put 200 directories it never
+ * declared into its tree, and leave `gjsify unlink` with no honest answer about
+ * what to restore. Pure, so every selection rule is decidable without a
+ * filesystem.
+ */
+export function planDevLinks(opts) {
+    // No pattern is NOT `['*']` — see {@link DevLinkOverride.packages}: a bare star
+    // matches no scoped name, so spelling the default as one would select nothing.
+    const selected = opts.patterns.length > 0
+        ? filterWorkspaces(opts.workspaces, { include: [...opts.patterns] })
+        : [...opts.workspaces];
+    const links = [];
+    for (const ws of selected) {
+        if (!ws.name)
+            continue;
+        if (!opts.knownNames.has(ws.name))
+            continue;
+        links.push({
+            name: ws.name,
+            target: ws.location,
+            linkPath: join(opts.consumerRoot, 'node_modules', ws.name),
+        });
+    }
+    links.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return links;
+}
+/**
+ * Read + validate the override at `consumerRoot` and plan its links, or `null`
+ * when no override is there. Throws for every other shape — see
+ * {@link resolveCheckoutWorkspaces}.
+ */
+export function prepareDevLinks(consumerRoot) {
+    const override = readDevLinkOverride(consumerRoot);
+    if (!override)
+        return null;
+    const overridePath = devLinkPath(consumerRoot);
+    const workspaces = resolveCheckoutWorkspaces(override.checkout, overridePath);
+    const links = planDevLinks({
+        consumerRoot,
+        workspaces,
+        patterns: override.packages,
+        knownNames: consumerKnownNames(consumerRoot),
+    });
+    return {
+        overridePath,
+        consumerRoot,
+        checkout: override.checkout,
+        links,
+        names: new Set(links.map((l) => l.name)),
+    };
+}
+/**
+ * (Re)create every planned link. Idempotent — a link already pointing at the
+ * right target is left alone, so a re-run costs no unlink/relink race against a
+ * process reading through it.
+ *
+ * Returns the links it actually wrote.
+ */
+export function applyDevLinks(links) {
+    // FAIL CLOSED, over EVERY link and before the first write. Not only over the
+    // ones this call would rewrite: the idempotent skip below is exactly how the
+    // measured defect stayed invisible — the link was already correct, the checkout
+    // had meanwhile lost its `dist/`, `gjsify install` re-ran, skipped the write,
+    // printed "development link ACTIVE" and left a tree whose first import died
+    // with MODULE_NOT_FOUND. `dist/`/`lib/` are git-ignored, so a branch switch in
+    // the checkout produces this state as a matter of course.
+    assertDevLinksBuilt(links);
+    const written = [];
+    for (const link of links) {
+        if (linkAlreadyPointsAt(link.linkPath, link.target))
+            continue;
+        mkdirSync(dirname(link.linkPath), { recursive: true });
+        // Whatever is there — the registry copy, a stale link, a leftover file.
+        // `force` so a missing entry is not an error on the first link.
+        rmSync(link.linkPath, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+        linkDirSync(link.linkPath, link.target);
+        written.push(link);
+    }
+    return written;
+}
+/**
+ * Remove the links an override produced.
+ *
+ * ONLY a symlink whose target is inside the checkout is removed. A real
+ * directory at that path is the registry copy — some other tool's, or an install
+ * that ran with the override already gone — and deleting it would turn `unlink`
+ * into a destructive command for a tree it did not create. Same asymmetry
+ * `install-extraneous.ts` reasons from: a wrong deletion loses work, a wrong
+ * refusal costs one message.
+ */
+export function removeDevLinks(links) {
+    const removed = [];
+    for (const link of links) {
+        let isLink = false;
+        try {
+            isLink = lstatSync(link.linkPath).isSymbolicLink();
+        }
+        catch {
+            continue; // Not there at all.
+        }
+        if (!isLink)
+            continue;
+        if (!linkAlreadyPointsAt(link.linkPath, link.target))
+            continue;
+        rmSync(link.linkPath, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+        removed.push(link);
+    }
+    return removed;
+}
+/**
+ * Does `linkPath` already resolve to `target`?
+ *
+ * Compares REAL paths, not the stored string: `dirLinkTarget` spells a POSIX
+ * target relative to the link's own directory and a Windows junction absolutely,
+ * so a string comparison would answer "different" on one platform and "same" on
+ * the other for the identical link.
+ */
+function linkAlreadyPointsAt(linkPath, target) {
+    try {
+        if (!lstatSync(linkPath).isSymbolicLink())
+            return false;
+        return realpathSync(linkPath) === realpathSync(target);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every `node_modules/<name>` symlink that resolves INSIDE one of `checkouts`.
+ *
+ * The PLAN is not a census. `removeDevLinks` only ever visits the links the
+ * CURRENT override asks for, so a link the previous override made and the new one
+ * dropped is invisible to it — measured: link everything, relink with
+ * `--packages 'is-odd'`, and `node_modules/is-number` stays pointing into the
+ * checkout while nothing in the plan names it. From there `assertNodeModulesDest`
+ * aborted EVERY later `gjsify install`, and `gjsify unlink` could not help because
+ * it removed the override (the escape route) before hitting the same abort. Only a
+ * hand-written `rm` got the project back.
+ *
+ * So the ground truth for "what is linked" is the tree, not the file. Reads one
+ * level of `node_modules` plus one level into each `@scope/`, which is where
+ * top-level links live; `.bin` and real directories are skipped by construction.
+ */
+export function scanDevLinks(consumerRoot, checkouts) {
+    const roots = [];
+    for (const checkout of checkouts) {
+        try {
+            roots.push(realpathSync(checkout));
+        }
+        catch {
+            // Gone or unreadable: nothing can resolve into it, so it contributes
+            // no links. A DANGLING link is not this function's business either —
+            // the installer extracts straight over one.
+        }
+    }
+    if (roots.length === 0)
+        return [];
+    const nodeModules = join(consumerRoot, 'node_modules');
+    const found = [];
+    const consider = (name) => {
+        const linkPath = join(nodeModules, name);
+        let target;
+        try {
+            if (!lstatSync(linkPath).isSymbolicLink())
+                return;
+            target = realpathSync(linkPath);
+        }
+        catch {
+            return;
+        }
+        if (!roots.some((root) => target === root || target.startsWith(root + sep)))
+            return;
+        found.push({ name, target, linkPath });
+    };
+    let entries;
+    try {
+        entries = readdirSync(nodeModules);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.'))
+            continue;
+        if (entry.startsWith('@')) {
+            let scoped;
+            try {
+                scoped = readdirSync(join(nodeModules, entry));
+            }
+            catch {
+                continue;
+            }
+            for (const inner of scoped)
+                consider(`${entry}/${inner}`);
+            continue;
+        }
+        consider(entry);
+    }
+    found.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return found;
+}
+/**
+ * Remove every dev link into `checkouts` that `keep` does not name.
+ *
+ * What makes re-linking with a narrower `--packages` a RE-selection rather than an
+ * addition, and what makes `unlink` leave the tree as it found it. Pass an empty
+ * `keep` to retire all of them.
+ */
+export function retireDevLinks(consumerRoot, checkouts, keep) {
+    const stale = scanDevLinks(consumerRoot, checkouts).filter((link) => !keep.has(link.name));
+    return removeDevLinks(stale);
+}
+/**
+ * Which of these links point at something that is not built.
+ *
+ * Candidates are the string entry points a manifest can carry — `main`, `module`
+ * and the string leaves under `exports["."]`. ANY of them existing is enough: a
+ * package legitimately declares entries it does not ship on every platform, and a
+ * refusal that fires on a healthy tree is a refusal people learn to route around.
+ * An entry-LESS manifest is fine, because nothing was promised that could be
+ * missing.
+ *
+ * An UNREADABLE manifest is NOT fine, and that is a flip from the first draft,
+ * which answered "built" for it. "I could not tell" is not "yes" in a check whose
+ * whole job is to stop a silently unusable tree.
+ */
+export function unbuiltDevLinks(links) {
+    const out = [];
+    for (const link of links) {
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(join(link.target, 'package.json'), 'utf-8'));
+        }
+        catch (err) {
+            out.push({
+                link,
+                reason: `its package.json is missing or unreadable (${err instanceof Error ? err.message : String(err)})`,
+            });
+            continue;
+        }
+        const candidates = [];
+        for (const key of ['main', 'module']) {
+            const value = manifest[key];
+            if (typeof value === 'string')
+                candidates.push(value);
+        }
+        const exportsField = manifest.exports;
+        if (typeof exportsField === 'string')
+            candidates.push(exportsField);
+        else if (exportsField && typeof exportsField === 'object') {
+            collectStringLeaves(exportsField['.'], candidates);
+        }
+        if (candidates.length === 0)
+            continue;
+        if (candidates.some((rel) => existsSync(join(link.target, rel))))
+            continue;
+        out.push({ link, reason: `none of its declared entry points exist yet (${candidates.join(', ')})` });
+    }
+    return out;
+}
+/** The refusal text for {@link unbuiltDevLinks}, naming every path and the build. */
+export function formatUnbuiltDevLinks(unbuilt) {
+    const rows = unbuilt.map((u) => `  ${u.link.name}  ${u.link.target}\n      ${u.reason}`).join('\n');
+    return (`gjsify link: ${unbuilt.length} linked package(s) are not built, so linking them would hand the ` +
+        `consumer a tree whose first import fails with MODULE_NOT_FOUND:\n${rows}\n` +
+        `  Build them in the checkout (\`gjsify run build\` there) and re-run, or narrow the selection with ` +
+        `\`gjsify link <checkout> --packages <glob>\`. A link does not build.`);
+}
+/**
+ * FAIL CLOSED on a link to something unbuilt.
+ *
+ * `dist/`/`lib/` are git-ignored in a gjsify checkout, so "the entry point is not
+ * there right now" is the ordinary consequence of a branch switch, not an exotic
+ * state. Measured: with the entry file deleted, `gjsify install` re-linked and
+ * printed only "development link ACTIVE"; the consumer then died on
+ * MODULE_NOT_FOUND with a message naming the consumer, not the checkout.
+ */
+export function assertDevLinksBuilt(links) {
+    const unbuilt = unbuiltDevLinks(links);
+    if (unbuilt.length === 0)
+        return;
+    throw new Error(formatUnbuiltDevLinks(unbuilt));
+}
+function collectStringLeaves(value, out) {
+    if (typeof value === 'string') {
+        out.push(value);
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    for (const nested of Object.values(value))
+        collectStringLeaves(nested, out);
+}
+/** The comment line `ensureLocallyIgnored` writes above the pattern. */
+const IGNORE_COMMENT = '# gjsify link — local development override, never commit';
+/**
+ * Make `.gjsify-link.json` invisible to git WITHOUT editing a tracked file.
+ *
+ * `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
+ * consumer whose `.git` POINTER cannot be followed IS worth a word, though —
+ * there the file stays visible to `git status` and one `git add -A` commits it.
+ */
+export function ensureLocallyIgnored(consumerRoot) {
+    const found = resolveGitDir(consumerRoot);
+    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.commonDir, 'info', 'exclude');
+    if (existsSync(excludePath) && fileMentionsPattern(excludePath, DEV_LINK_FILE))
+        return 'already-ignored';
+    mkdirSync(dirname(excludePath), { recursive: true });
+    const existing = existsSync(excludePath) ? readFileSync(excludePath, 'utf-8') : '';
+    const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    writeFileSync(excludePath, `${existing}${prefix}${IGNORE_COMMENT}\n${DEV_LINK_FILE}\n`);
+    return 'added';
+}
+/**
+ * Undo {@link ensureLocallyIgnored} — the other half of `unlink`.
+ *
+ * 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.
+ *
+ * ONLY the two lines this module wrote, matched as a pair: a `.gitignore` entry or
+ * a hand-written exclude line is someone else's decision, and removing it would be
+ * the same overreach `removeDevLinks` refuses.
+ */
+export function removeLocalIgnore(consumerRoot) {
+    const found = resolveGitDir(consumerRoot);
+    if (!found.commonDir)
+        return found.why;
+    const excludePath = join(found.commonDir, 'info', 'exclude');
+    let text;
+    try {
+        text = readFileSync(excludePath, 'utf-8');
+    }
+    catch {
+        return 'absent';
+    }
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    let removed = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (!removed &&
+            lines[i]?.trim() === IGNORE_COMMENT &&
+            (lines[i + 1]?.trim() === DEV_LINK_FILE || lines[i + 1]?.trim() === `/${DEV_LINK_FILE}`)) {
+            i++; // skip the pattern line too
+            removed = true;
+            continue;
+        }
+        out.push(lines[i] ?? '');
+    }
+    if (!removed)
+        return 'absent';
+    writeFileSync(excludePath, out.join('\n'));
+    return 'removed';
+}
+/** A line naming exactly this pattern, ignoring comments and whitespace. */
+function fileMentionsPattern(file, pattern) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    return text.split(/\r?\n/).some((line) => {
+        const trimmed = line.trim();
+        return trimmed === pattern || trimmed === `/${pattern}`;
+    });
+}
+/**
+ * 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
+ * second leaves the override exposed to the next `git add -A` — and answering
+ * both with `null` made the second announce the first.
+ */
+function resolveGitDir(root) {
+    const dotGit = join(root, '.git');
+    let stat;
+    try {
+        stat = statSync(dotGit);
+    }
+    catch {
+        return { commonDir: null, why: 'no-git' };
+    }
+    if (stat.isDirectory())
+        return { commonDir: dotGit, why: 'no-git' };
+    let pointer;
+    try {
+        pointer = readFileSync(dotGit, 'utf-8').trim();
+    }
+    catch {
+        return { commonDir: null, why: 'unreadable-git' };
+    }
+    const match = /^gitdir:\s*(.+)$/.exec(pointer);
+    const target = match?.[1]?.trim();
+    if (!target)
+        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.
+ *
+ * CI, a Flatpak build and a release all run `--immutable`, and all three exist to
+ * build exactly what is committed. An override is a developer's local tree, so
+ * consuming one here would produce an artifact whose inputs are not in any
+ * commit and whose build reported nothing unusual. Refusing names the file,
+ * because the fix is to delete it and the message is the only place its path
+ * appears.
+ */
+export function assertNoDevLinkUnderImmutable(startDir) {
+    const root = devLinkRoot(startDir);
+    const path = devLinkPath(root);
+    if (!existsSync(path))
+        return;
+    let checkout = '(unreadable)';
+    try {
+        checkout = readDevLinkOverride(root)?.checkout ?? checkout;
+    }
+    catch {
+        // A malformed override still blocks: the question `--immutable` asks is
+        // "is a development tree in play", and an unparseable answer is not a no.
+    }
+    throw new Error(`gjsify install --immutable: a development link override is active — ${path}\n` +
+        `It points at ${checkout}, so this install would build from a local checkout instead of ` +
+        `what ${join(root, 'gjsify-lock.json')} pins. --immutable builds only what is committed.\n` +
+        `Run \`gjsify unlink\` (in ${root}) or delete ${DEV_LINK_FILE}, then re-run.`);
+}