@gjsify/cli 0.51.1 → 0.53.0

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.
  *
@@ -118,7 +120,7 @@ export declare const PACKAGE_DEPS: Record<string, string[]>;
  * Run all dependency checks. Used by `gjsify check` to show full system status.
  *
  * Required deps (gjs, gtk4, libsoup3, libadwaita, gobject-introspection,
- * blueprint-compiler, pkg-config, meson) are always checked.
+ * pkg-config, meson) are always checked.
  *
  * Optional deps are checked conditionally based on which @gjsify/* packages
  * the project (resolved from cwd) actually consumes. If no project context
@@ -130,22 +132,6 @@ export declare function runAllChecks(cwd: string): DepCheck[];
  * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
-/**
- * Is a blueprint-compiler reachable, by the SAME rule the build uses?
- *
- * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
- * here, because the two answers must not be able to disagree: on win32 the
- * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
- * PATH-only check would report "missing" on a host where every `.blp` builds
- * fine — a check failing for the wrong reason, which is the failure mode this
- * file's own history is made of.
- *
- * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
- * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
- * resolved pair is the honest answer, and the `source` is worth reporting
- * because "found via msys2" explains an install PATH does not show.
- */
-export declare function checkBlueprintCompiler(requiredBy?: string[]): DepCheck;
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export declare function checkGwebgl(cwd: string): DepCheck;
 /**

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,28 +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';
-// 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';
 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
@@ -47,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) {
@@ -393,7 +385,7 @@ function computeNeededOptionalDeps(cwd) {
  * Run all dependency checks. Used by `gjsify check` to show full system status.
  *
  * Required deps (gjs, gtk4, libsoup3, libadwaita, gobject-introspection,
- * blueprint-compiler, pkg-config, meson) are always checked.
+ * pkg-config, meson) are always checked.
  *
  * Optional deps are checked conditionally based on which @gjsify/* packages
  * the project (resolved from cwd) actually consumes. If no project context
@@ -454,53 +446,19 @@ export function runMinimalChecks() {
         results.push(checkMsvcRuntime());
     return results;
 }
-/**
- * Is a blueprint-compiler reachable, by the SAME rule the build uses?
- *
- * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
- * here, because the two answers must not be able to disagree: on win32 the
- * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
- * PATH-only check would report "missing" on a host where every `.blp` builds
- * fine — a check failing for the wrong reason, which is the failure mode this
- * file's own history is made of.
- *
- * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
- * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
- * resolved pair is the honest answer, and the `source` is worth reporting
- * because "found via msys2" explains an install PATH does not show.
- */
-export function checkBlueprintCompiler(requiredBy) {
-    const resolved = resolveBlueprintCompiler();
-    return {
-        id: 'blueprint-compiler',
-        name: 'blueprint-compiler (.blp templates)',
-        found: resolved !== null,
-        version: resolved ? `found via ${resolved.source}` : undefined,
-        severity: 'optional',
-        requiredBy,
-    };
-}
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export function checkGwebgl(cwd) {
     return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd, 'optional', ['@gjsify/webgl']);
 }
 /**
  * Required system dependencies — always checked, missing → exit 1.
- * Includes the core build toolchain (pkg-config, meson, blueprint-compiler)
- * and the foundational libraries (gtk4, libadwaita, libsoup3,
- * gobject-introspection) that nearly every gjsify app needs.
+ * Includes the core build toolchain (pkg-config, meson) and the foundational
+ * libraries (gtk4, libadwaita, libsoup3, gobject-introspection) that nearly
+ * every gjsify app needs.
  */
 function runRequiredChecks(_cwd) {
     const results = [];
-    // Build toolchain. NO blueprint-compiler here: it is checked by
-    // `checkBlueprintCompiler()` among the build toolchain below, through the
-    // SAME resolver the build uses. A second `checkBinary` probe lived here and
-    // was wrong twice over — it reported a PATH miss on win32, where the
-    // compiler is normally an MSYS2 script deliberately off PATH (the exact case
-    // that function's comment exists to explain), and it made `system-check`
-    // exit 1 on any host without it, `.blp` files in the project or not. It also
-    // printed a second entry under a second display name and put
-    // `blueprint-compiler` into the install hint twice.
+    // Build toolchain.
     results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version'], 'required'));
     results.push(checkBinary('meson', 'Meson', 'meson', ['--version'], 'required'));
     // Foundational libraries — by TYPELIB, the runtime question. See checkGiLibrary.
@@ -549,13 +507,12 @@ function runNativeBuildToolchainChecks() {
     // Narrower on purpose: only the three bridges that link an upstream Rust
     // crate by Cargo path-dependency need a Rust toolchain.
     const rustBridges = ['@gjsify/lightningcss-native', '@gjsify/oxfmt-native', '@gjsify/rolldown-native'];
-    // Every showcase/app whose window comes from a `.blp` template. NOT a Vala
-    // bridge and nothing to do with meson — it is a BUILD-time toolchain in the
-    // same sense, and it belongs here so `gjsify system-check` names it before a
-    // build does.
-    const blueprintConsumers = ['@gjsify/vite-plugin-blueprint'];
+    // NO blueprint-compiler row, and it is a deletion rather than an omission: ADR 0053 clause 5
+    // moved the `.blp` transform into `@gjsify/blueprint`, so a `.blp` template asks nothing of
+    // this host any more. A row for it would be this command asking for a toolchain the build
+    // cannot use — the exact "check failing for the wrong reason" its own history is made of.
+    // ADR 0063 is the deletion and what the compiler is still FOR.
     return [
-        checkBlueprintCompiler(blueprintConsumers),
         checkBinary('ninja', 'Ninja', 'ninja', ['--version'], 'optional', undefined, valaBridges),
         checkBinary('vala', 'Vala', 'valac', ['--version'], 'optional', (out) => out.replace(/^Vala\s+/i, ''), valaBridges),
         checkBinary('cargo', 'Cargo (Rust)', 'cargo', ['--version'], 'optional', (out) => out.replace(/^cargo\s+/i, '').split(' ')[0] ?? out, rustBridges),
@@ -596,7 +553,6 @@ const PM_PACKAGES = {
     apt: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
         ninja: 'ninja-build',
@@ -622,7 +578,6 @@ const PM_PACKAGES = {
     dnf: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf-pkg-config',
         meson: 'meson',
         ninja: 'ninja-build',
@@ -648,7 +603,6 @@ const PM_PACKAGES = {
     pacman: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -674,7 +628,6 @@ const PM_PACKAGES = {
     zypper: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
         ninja: 'ninja',
@@ -700,7 +653,6 @@ const PM_PACKAGES = {
     apk: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -748,7 +700,6 @@ const PM_PACKAGES = {
     brew: {
         nodejs: 'node',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -804,24 +755,11 @@ export function buildInstallCommand(pm, missing) {
     const pkgMap = PM_PACKAGES[pm];
     const pkgs = [];
     const npmDeps = [];
-    const standalone = [];
     for (const dep of missing) {
         if (dep.id === 'gwebgl') {
             npmDeps.push('@gjsify/webgl');
             continue;
         }
-        // blueprint-compiler on Windows is the one dep whose install command is
-        // not this host's package manager. winget has no package for it, and it
-        // cannot get one that works: the tool needs PyGObject, which publishes
-        // no Windows wheel, so MSYS2 — which ships Python, PyGObject and the
-        // typelibs already fitted together — is the only source. Its command is
-        // not `winget install`-shaped, so it cannot live in PM_PACKAGES without
-        // producing a line that looks right and fails.
-        if (dep.id === 'blueprint-compiler' && process.platform === 'win32') {
-            standalone.push('pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 ' +
-                'mingw-w64-ucrt-x86_64-libadwaita   # inside MSYS2; found automatically afterwards');
-            continue;
-        }
         // 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"
@@ -842,7 +780,6 @@ export function buildInstallCommand(pm, missing) {
     if (npmDeps.length > 0) {
         lines.push(`npm install ${npmDeps.join(' ')}`);
     }
-    lines.push(...standalone);
     return lines.length > 0 ? lines.join('\n  ') : null;
 }
 /**

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

@@ -0,0 +1,225 @@
+import { type Workspace } from '@gjsify/workspace';
+/** The consumer-local override file. Git-ignored; never committed. */
+export declare const DEV_LINK_FILE = ".gjsify-link.json";
+/**
+ * What `.gjsify-link.json` holds.
+ *
+ * A POINTER plus a selector, never a materialised list of package names: `link`
+ * and `install` then derive the same set from the same two inputs, so a checkout
+ * that gains or loses a workspace package cannot leave the two disagreeing about
+ * what is linked.
+ */
+export interface DevLinkOverride {
+    /** Format version — an unknown one is refused rather than guessed at. */
+    version: 1;
+    /** The gjsify checkout to link from. Absolute, as written by `gjsify link`. */
+    checkout: string;
+    /**
+     * Name globs selecting which of its workspace packages take part. EMPTY means
+     * every one of them — deliberately not `["*"]`, which would select NOTHING:
+     * measured, `@gjsify/workspace`'s glob dialect maps `*` to `[^/]*`, so a bare
+     * star never matches a SCOPED name. The spelling for a whole scope is
+     * `@gjsify/*`, the same dialect `gjsify foreach --include` takes.
+     */
+    packages: string[];
+}
+/** One `node_modules/<name>` → checkout package directory link. */
+export interface DevLink {
+    name: string;
+    /** Absolute path of the workspace package in the checkout. */
+    target: string;
+    /** Absolute path of the link inside the consumer's `node_modules`. */
+    linkPath: string;
+}
+/** An override that has been read, validated and turned into a link plan. */
+export interface ActiveDevLinks {
+    /** Absolute path of the override file, for every message that names it. */
+    overridePath: string;
+    /** The consumer root the override belongs to. */
+    consumerRoot: string;
+    /** The validated checkout it points at. */
+    checkout: string;
+    links: DevLink[];
+    /** Just the names — what the installer excludes from its fetch set. */
+    names: Set<string>;
+}
+export declare function devLinkPath(root: string): string;
+/**
+ * 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 declare function readDevLinkOverride(root: string): DevLinkOverride | null;
+export declare function writeDevLinkOverride(root: string, override: DevLinkOverride): string;
+/** Remove the override file; returns its path when one was there. */
+export declare function removeDevLinkOverride(root: string): string | null;
+/**
+ * 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 declare function devLinkRoot(startDir: string): string;
+/**
+ * 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 declare function resolveCheckoutWorkspaces(checkout: string, overridePath: string): Workspace[];
+/**
+ * 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 declare function consumerKnownNames(consumerRoot: string): Set<string>;
+/**
+ * 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 declare function planDevLinks(opts: {
+    consumerRoot: string;
+    workspaces: readonly Workspace[];
+    patterns: readonly string[];
+    knownNames: ReadonlySet<string>;
+}): DevLink[];
+/**
+ * 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 declare function prepareDevLinks(consumerRoot: string): ActiveDevLinks | null;
+/**
+ * (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 declare function applyDevLinks(links: readonly DevLink[]): DevLink[];
+/**
+ * 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 declare function removeDevLinks(links: readonly DevLink[]): DevLink[];
+/**
+ * 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 declare function scanDevLinks(consumerRoot: string, checkouts: readonly string[]): DevLink[];
+/**
+ * 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 declare function retireDevLinks(consumerRoot: string, checkouts: readonly string[], keep: ReadonlySet<string>): DevLink[];
+/** A linked package that cannot be imported, and why not. */
+export interface UnbuiltDevLink {
+    link: DevLink;
+    reason: string;
+}
+/**
+ * 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 declare function unbuiltDevLinks(links: readonly DevLink[]): UnbuiltDevLink[];
+/** The refusal text for {@link unbuiltDevLinks}, naming every path and the build. */
+export declare function formatUnbuiltDevLinks(unbuilt: readonly UnbuiltDevLink[]): string;
+/**
+ * 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 declare function assertDevLinksBuilt(links: readonly DevLink[]): void;
+/**
+ * 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 declare function ensureLocallyIgnored(consumerRoot: string): 'added' | 'already-ignored' | 'no-git' | 'unreadable-git';
+/**
+ * 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 declare function removeLocalIgnore(consumerRoot: string): 'removed' | 'absent' | 'no-git' | 'unreadable-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 declare function assertNoDevLinkUnderImmutable(startDir: string): void;