@gjsify/cli 0.51.0 → 0.52.0

package/lib/commands/ship.js

@@ -35,12 +35,13 @@ import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
+import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
 import { assertHostCanFinish, assertKindCanPack, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
 import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
 import { isNodeRuntimeTarget, resolveNodeRuntime } from '../utils/ship/node-runtime.js';
 import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
-import { compileSchemasForStage } from '../utils/ship/schemas.js';
+import { compileSchemasForPayload, compileSchemasForStage } from '../utils/ship/schemas.js';
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
 import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
@@ -416,7 +417,14 @@ async function assemble(args) {
     // `.deb`/`.rpm` postinst compiles the SYSTEM directory at install time
     // (`utils/ship/scripts.ts`), where our schemas merge with every other
     // package's — shipping a prebuilt cache there would be a file the install step
-    // overwrites. So the compile is conditional on the layout and nothing else.
+    // overwrites, and one `rpm -e` takes away with it.
+    //
+    // WHICH IS WHY THIS CONDITION IS ABOUT THE STAGE AND NOT ABOUT INSTALL STEPS,
+    // a distinction that used to be invisible because the two agreed. They stopped
+    // agreeing when the AppImage landed: it takes the Linux layout and has no
+    // install step at all. It does not get its cache from here — a Linux stage
+    // serves three formats and only one of them wants one — it compiles its own
+    // into the AppDir, on its own pack path (`packOne`, `case 'appimage'`).
     const planned = [
         ...planStage(settings, stageInputs),
         ...(layout.os === 'linux'
@@ -426,7 +434,24 @@ async function assemble(args) {
                 workDir: join(outRoot, 'schemas'),
             })),
     ];
-    const staged = placeStage(layout, settings, planned, runtime.files);
+    // THE APPLICATION ICON, rendered once for the sizes this layout's writers
+    // embed — six for the `.exe`'s resource directory, seven for the `.icns` —
+    // and nothing for a CLI or for Linux, where the theme carries the SVG the
+    // project declared. `resolveAppIcon` REFUSES an app that has no source for a
+    // size rather than staging without it: the released artifacts this closes
+    // shipped for a year with the generic icon on two platforms, and the only
+    // reason was that nothing said so (`utils/ship/icons.ts`).
+    const icon = settings.kind === 'app' && layout.icon !== undefined
+        ? await resolveAppIcon({
+            iconFiles: settings.iconFiles,
+            appId: settings.appId,
+            sizes: layout.icon.sizes,
+            target: layout.icon.writes,
+        })
+        : undefined;
+    if (icon !== undefined)
+        console.log(`${LOG} icon: ${iconSizes(icon).join('/')} px, ${icon.source}`);
+    const staged = placeStage(layout, { ...settings, icon }, planned, runtime.files);
     writeStage(stageDir, staged);
     console.log(`${LOG} staged ${staged.length} file(s) for ${layout.name} in ${relative(projectDir, stageDir)}/`);
     if (args.verbose)
@@ -988,7 +1013,24 @@ async function packOne(input) {
                 bundledTypelibs: facts.bundledTypelibs,
             });
             const appDir = appDirFor(outRoot);
-            const tree = appDirPayload(settings, payload, hostRequirements);
+            // THE ONE FILE THIS FORMAT ADDS TO THE PAYLOAD, and the reason it is
+            // added HERE and not where every other layout's is (the stage, above).
+            // An AppImage has no install step; the Linux layout it inherits assumes
+            // one, because until this format existed every Linux artifact had a
+            // `postinst`. The compile cannot move up into the stage: the Linux stage
+            // is shared with the `.deb` and the `.rpm`, whose `share/glib-2.0/schemas`
+            // is `/usr/share/glib-2.0/schemas` — the SYSTEM directory — and a cache
+            // staged there is this app's 700 bytes installed over every other
+            // package's schemas, then taken away with `rpm -e`.
+            //
+            // FROM THE PAYLOAD, like the host requirements two lines up and for the
+            // same reason: `--from-stage` has the schema BYTES and not the project
+            // directory they were read from.
+            const schemaCache = await compileSchemasForPayload({
+                payload,
+                workDir: join(outRoot, 'appimage-schemas'),
+            });
+            const tree = appDirPayload(settings, payload, hostRequirements, schemaCache);
             // ONE `writePayload` FOR THE WHOLE AppDir, prefix and root files
             // together, because that call WIPES: two of them would leave the
             // previous run's `<appId>.desktop` and icon at a root the second call

package/lib/types/config-data.d.ts

@@ -771,7 +771,7 @@ export interface ConfigDataFlatpak extends AppMetadata {
     command?: string;
     /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
     finishArgs?: string[];
-    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
+    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. a GI library the runtime lacks). */
     extraModules?: unknown[];
     /**
      * Full replacement for the manifest's `modules` array: used verbatim, with

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

@@ -118,7 +118,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 +130,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

@@ -15,9 +15,6 @@ 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';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
@@ -393,7 +390,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 +451,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 +512,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 +558,6 @@ const PM_PACKAGES = {
     apt: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
         ninja: 'ninja-build',
@@ -622,7 +583,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 +608,6 @@ const PM_PACKAGES = {
     pacman: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -674,7 +633,6 @@ const PM_PACKAGES = {
     zypper: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
         meson: 'meson',
         ninja: 'ninja',
@@ -700,7 +658,6 @@ const PM_PACKAGES = {
     apk: {
         nodejs: 'nodejs',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -748,7 +705,6 @@ const PM_PACKAGES = {
     brew: {
         nodejs: 'node',
         gjs: 'gjs',
-        'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
         meson: 'meson',
         ninja: 'ninja',
@@ -804,24 +760,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 +785,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,222 @@
+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.
+ *
+ * `.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.
+ *
+ * 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 `.git/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;