@gjsify/cli 0.44.0 → 0.46.0

package/lib/utils/ship/payload.js

@@ -6,6 +6,9 @@
 // reads what the first wrote. A packer fed straight from the planner could
 // drift from the staged tree and nothing would notice.
 import { statSync } from 'node:fs';
+import { launcherPath } from './layout.js';
+import { SCHEMA_CACHE } from './schemas.js';
+import { isUnder, SHARE } from './share-dirs.js';
 /**
  * The build stamp every header gets.
  *
@@ -45,16 +48,540 @@ export function buildTimestamp(bundlePath, env = process.env) {
 export function readPayloadFacts(entries) {
     const paths = entries.map((entry) => entry.path);
     return {
-        hasDesktopEntry: paths.some((path) => path.startsWith('share/applications/') && path.endsWith('.desktop')),
-        hasIcons: paths.some((path) => path.startsWith('share/icons/hicolor/')),
-        hasSchemas: paths.some((path) => path.startsWith('share/glib-2.0/schemas/') && path.endsWith('.gschema.xml')),
-        hasMimeTypes: paths.some((path) => path.startsWith('share/mime/packages/') && path.endsWith('.xml')),
+        hasDesktopEntry: paths.some((path) => isUnder(path, SHARE.applications) && path.endsWith('.desktop')),
+        hasIcons: paths.some((path) => isUnder(path, SHARE.icons)),
+        hasSchemas: paths.some((path) => isUnder(path, SHARE.schemas) && path.endsWith('.gschema.xml')),
+        hasMimeTypes: paths.some((path) => isUnder(path, SHARE.mime) && path.endsWith('.xml')),
         // Anywhere in the payload, not only `lib/<name>/gi/`: `gjsify.ship.extraFiles` can place
         // one elsewhere, and a typelib the package carries is a typelib the package must not also
         // declare a distro dependency for, wherever it sits.
         bundledTypelibs: paths.filter((path) => path.endsWith('.typelib')),
     };
 }
+/**
+ * Every interpreter the STAGED launcher could exec, resolved to a bare name.
+ *
+ * WHY THIS IS READ BACK AT ALL, when `settings.app` already says so. Because
+ * `settings.app` says what the launcher was RENDERED from, and the dependency is
+ * a claim about what the installed package will RUN. Those were once two
+ * different things: the Node dependency was derived from a filename glob over
+ * the staged tree while `renderLauncher` execed `gjs` unconditionally, and the
+ * packer emitted `Depends: gjs (>= 1.86), nodejs (>= 24)` for a package that
+ * runs neither combination. Nothing in the pipeline compared them, and no
+ * structural check could: both artifacts were individually well-formed.
+ *
+ * A LIST, and every `exec` rather than one of them. The first cut took the first
+ * match while its own comment claimed the last — `/\nexec\s+/` is not global, so
+ * the two disagreed and the comment was the wrong one. Neither is right for a
+ * script this tree did not write: a launcher may exec different interpreters on
+ * different branches, and picking one branch's answer is a guess. Collecting
+ * them lets {@link assertLauncherMatchesInterpreter} ask the only question that
+ * is safe on a foreign script — see there.
+ *
+ * NAMES, not the tokens as written. `exec /usr/bin/gjs -m …` execs gjs, and an
+ * `env` prefix (`exec env NODE_OPTIONS=… node …`) execs whatever follows its
+ * assignments. Both are things `gjsify.ship.extraFiles` legitimately writes, and
+ * the raw-token version REFUSED them: measured, an untouched `--app gjs` project
+ * whose `extraFiles` replaced the launcher with `exec /usr/bin/gjs -m …` failed
+ * the pack at exit 1 with "execs `/usr/bin/gjs`, but this package would declare
+ * a dependency on `gjs`" — a working artifact rejected over a parser, which is
+ * exactly what the `null` branch was written to prevent and did not.
+ */
+export function readLauncherInterpreters(payload, layout, identity) {
+    // THE LAYOUT'S launcher, which is what this function's doc has always claimed
+    // and what it did not do. It looked up `bin/<binaryName>` — the PREFIX-RELATIVE
+    // path — so off Linux it matched nothing and returned `[]`, i.e. it was vacuous
+    // for the darwin tree (`<App>.app/Contents/MacOS/<name>`) and the windows one
+    // (`<name>.cmd`). Harmless while every format that called it wrapped the Linux
+    // layout; a real hole the moment a darwin format exists, because `[]` is the
+    // value `assertLauncherMatchesInterpreter` treats as "nothing to check".
+    const launcher = payload.find((entry) => entry.path === launcherPath(layout, identity));
+    if (launcher === undefined)
+        return [];
+    const text = new TextDecoder().decode(launcher.data);
+    const dialect = layout.name === 'windows' ? 'cmd' : 'sh';
+    const found = [];
+    for (const command of dialect === 'cmd' ? batchCommands(text) : shellExecLines(text)) {
+        const name = interpreterOf(command, dialect);
+        if (name !== null)
+            found.push(name);
+    }
+    return [...new Set(found)];
+}
+/**
+ * The argument of every `exec` in a POSIX-shell launcher.
+ *
+ * `[ \t]*` because a branching launcher indents the `exec` inside its `if`, and a
+ * pattern anchored hard to the newline silently sees only the last, unindented one
+ * — measured: a two-branch script reported `gjs` alone. A comment (`# exec gjs …`)
+ * still cannot match, since `#` is not whitespace.
+ */
+function shellExecLines(text) {
+    return [...`\n${text}`.matchAll(/\n[ \t]*exec\s+([^\n]*)/g)].map((match) => match[1].trim());
+}
+/**
+ * Batch keywords that can never be the program a `.cmd` line runs.
+ *
+ * The list is what makes {@link batchCommands} a filter rather than a parser, and
+ * it is deliberately only the keywords that CARRY NOTHING: `rem`, `echo`, `title`
+ * and `pause` take no command at all, `goto` takes a label, `exit` takes a code,
+ * `set`/`setlocal`/`endlocal` take a variable. A keyword missing from it costs a
+ * SILENT non-answer, never a wrong one — an unrecognised first word is handed to
+ * `interpreterOf`, which resolves it to `gjs`, to `node`, or to something
+ * `assertLauncherMatchesInterpreter` ignores.
+ *
+ * `if`, `else` and `for` are NOT here, and an earlier draft put them here with a
+ * doc claiming every entry "takes no program". That was false in the way batch
+ * actually gets written, and measured through the built reader:
+ *
+ *     IF defined X (node x)          → []      ← the whole reader, on one line
+ *     for %f in (*) do node %f       → []
+ *
+ * `[]` is the value `assertLauncherMatchesInterpreter` treats as "nothing to
+ * check", so a `gjsify.ship.extraFiles` launcher written as
+ * `if exist "%HERE%gjs.exe" ("%HERE%gjs.exe" -m …)` under `gjsify.app: "node"`
+ * passed. That is the same class as the POSIX form's un-indented-`exec` incident,
+ * one dialect over, so it gets the same treatment: {@link batchPrefix} REDUCES
+ * those three to the command they carry rather than dropping the line.
+ *
+ * `call` and `start` stay unhandled and stay silent: both DO invoke a program and
+ * both also take non-program arguments (`call :label`, `start "title"`), and
+ * guessing at that would be the parser answering confidently wrong.
+ */
+const BATCH_NON_PROGRAMS = new Set([
+    'rem',
+    'set',
+    'setlocal',
+    'endlocal',
+    'echo',
+    'goto',
+    'exit',
+    'title',
+    'pause',
+    'shift',
+    'cd',
+    'chdir',
+    'pushd',
+    'popd',
+    'color',
+    'cls',
+    'verify',
+    'prompt',
+]);
+/**
+ * One `cmd.exe` command line, split the way `cmd.exe` splits it.
+ *
+ * QUOTE-AWARE, and that is the whole reason it is not `line.split(/\s+/)`: a
+ * condition operand is routinely a path, and a program directory lives under
+ * `C:\Program Files\…`. Splitting `if exist "%HERE%My App\x" node y` on
+ * whitespace and then dropping "two tokens" would drop half the path and leave
+ * the rest as the program.
+ */
+function cmdTokens(line) {
+    const tokens = [];
+    let at = 0;
+    while (at < line.length) {
+        if (/\s/.test(line[at])) {
+            at += 1;
+            continue;
+        }
+        const start = at;
+        let quoted = false;
+        while (at < line.length && (quoted || !/\s/.test(line[at]))) {
+            if (line[at] === '"')
+                quoted = !quoted;
+            at += 1;
+        }
+        tokens.push({ text: line.slice(start, at), end: at });
+    }
+    return tokens;
+}
+/**
+ * Split `( … ) rest` into the block's body and whatever follows it.
+ *
+ * Depth-counting and quote-aware, because `(A) else (B)` is how a batch launcher
+ * writes two branches and BOTH have to be read — the POSIX form collects every
+ * `exec`, and a reader that saw one arm of an `if`/`else` would answer for a
+ * branch the user may never take. `null` when the parenthesis is unbalanced,
+ * which is a line this reader cannot honestly split.
+ */
+function splitBatchBlock(line) {
+    let depth = 0;
+    let quoted = false;
+    for (let at = 0; at < line.length; at++) {
+        const ch = line[at];
+        if (ch === '"')
+            quoted = !quoted;
+        else if (!quoted && ch === '(')
+            depth += 1;
+        else if (!quoted && ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return [line.slice(1, at).trim(), line.slice(at + 1).trim()];
+        }
+    }
+    return null;
+}
+/** Conditions whose operand is one token: `if exist FILE …`, `if defined VAR …`. */
+const BATCH_UNARY_CONDITIONS = new Set(['exist', 'defined', 'errorlevel']);
+/** `if a EQU b …` — three tokens where `a==b` is one. */
+const BATCH_COMPARISONS = new Set(['equ', 'neq', 'lss', 'leq', 'gtr', 'geq']);
+/**
+ * Strip one batch construct that WRAPS a command, or `null` when the line carries
+ * none this reader can reach.
+ *
+ * Returns the pieces for another round — `if defined X (node a) else (gjs -m b)`
+ * reduces to `["node a", "else (gjs -m b)"]` — which is what makes a compound line
+ * answerable at all, and what keeps BOTH arms of a branch in the answer.
+ * `undefined` means "nothing to strip", i.e. the line already IS the command.
+ *
+ * The `if` conditions are enumerated rather than guessed: three unary forms, the
+ * `a==b` form (one token, because `==` needs no spaces), and the six comparison
+ * operators. A shape not in that list returns `null` rather than a best guess,
+ * because the failure mode of guessing here is not silence — it is naming
+ * whichever token happened to land in the program position.
+ */
+function batchPrefix(line) {
+    if (line.startsWith('(')) {
+        const split = splitBatchBlock(line);
+        return split === null ? null : [split[0], split[1]];
+    }
+    const tokens = cmdTokens(line);
+    const word = (index) => (tokens[index]?.text ?? '').toLowerCase();
+    const after = (index) => [line.slice(tokens[index]?.end ?? line.length).trim()];
+    if (word(0) === 'else')
+        return after(0);
+    if (word(0) === 'for') {
+        const doAt = tokens.findIndex((token) => token.text.toLowerCase() === 'do');
+        return doAt === -1 ? null : after(doAt);
+    }
+    if (word(0) !== 'if')
+        return undefined;
+    // `not` and `/i` are modifiers, in either order and both optional.
+    let at = 1;
+    while (word(at) === 'not' || word(at) === '/i')
+        at += 1;
+    if (BATCH_UNARY_CONDITIONS.has(word(at)))
+        return after(at + 1);
+    if (word(at).includes('=='))
+        return after(at);
+    if (BATCH_COMPARISONS.has(word(at + 1)))
+        return after(at + 2);
+    return null;
+}
+/**
+ * Every command in a `.cmd` that could run a program.
+ *
+ * NOT an `exec` scan, because `cmd.exe` has no `exec`: the last command a batch
+ * file runs IS what the launcher runs, and its exit status is the script's. So
+ * where the POSIX form has a keyword to anchor on, this one has to rule lines OUT
+ * — see {@link BATCH_NON_PROGRAMS} for why ruling one out too few is the safe
+ * direction and ruling one out too many is not.
+ *
+ * `@` comes off first (`@echo off` is `echo` with output suppressed), and `::` is
+ * the label-abuse comment form, which no first-word test would otherwise catch.
+ * Lines are split on CR LF *or* LF: the form this tree writes is CRLF, and a
+ * launcher that arrived from `gjsify.ship.extraFiles` may be neither.
+ *
+ * The work list is BOUNDED. `if defined X (if defined Y (node a))` is legal batch
+ * and each round strips one construct; a cap turns a pathological line into a
+ * silent non-answer instead of a hang, which is the same trade `interpreterOf`
+ * makes for `env`.
+ */
+const BATCH_REDUCTION_STEPS = 32;
+function batchCommands(text) {
+    const commands = [];
+    const pending = text.split(/\r?\n/).map((raw) => raw.trim().replace(/^@+/, '').trim());
+    for (let step = 0; step < BATCH_REDUCTION_STEPS && pending.length > 0; step++) {
+        const line = pending.shift();
+        if (line === '' || line === ')' || line.startsWith('::'))
+            continue;
+        const first = (cmdTokens(line)[0]?.text ?? '').toLowerCase();
+        if (BATCH_NON_PROGRAMS.has(first))
+            continue;
+        const reduced = batchPrefix(line);
+        if (reduced === undefined)
+            commands.push(line);
+        else if (reduced !== null)
+            pending.unshift(...reduced);
+    }
+    return commands;
+}
+/**
+ * The program a command line runs, as a bare name, or `null` when the line is
+ * not one this reader can honestly resolve.
+ *
+ * TWO DIALECTS, because the two launchers are two languages and the difference is
+ * not cosmetic — it is what made the first Windows reading VACUOUS. See
+ * {@link cmdProgramOf}.
+ *
+ * `env` is followed through because it is the documented way to pass variables
+ * to an interpreter and says nothing about which one runs. Everything past the
+ * first non-assignment word is arguments, so the walk stops there. There is no
+ * `env` on Windows, so the hop is the POSIX branch's alone.
+ */
+function interpreterOf(line, dialect) {
+    if (dialect === 'cmd')
+        return cmdProgramOf(line);
+    let words = line.split(/\s+/).filter((word) => word.length > 0);
+    for (let hop = 0; hop < 2 && words.length > 0; hop++) {
+        const program = basenameOf(words[0]);
+        if (program !== 'env')
+            return program === '' ? null : program;
+        // Past `env`: skip its flags and `NAME=value` assignments to reach the
+        // program. `-S` takes the rest of the line as one string, which the split
+        // above has already flattened into words — the right answer either way.
+        words = words.slice(1).filter((word) => !word.startsWith('-') && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word));
+    }
+    return null;
+}
+/**
+ * The program one `cmd.exe` command line runs, as a bare, extension-free name.
+ *
+ * THREE DIALECT RULES, and every one of them is the difference between a check
+ * and a vacuous pass. Measured on the launcher `gjsify ship windows` writes
+ * (`"%HERE%node.exe" "%HERE%app\app.node.mjs" %*`), reading it with the POSIX
+ * path alone:
+ *
+ *   1. there is no `exec` keyword in batch, so the scan matched NOTHING and the
+ *      whole reader returned `[]` — the value `assertLauncherMatchesInterpreter`
+ *      treats as "nothing to check". {@link batchCommands} is that half.
+ *   2. `%~dp0` ALREADY ENDS IN A SEPARATOR, so the renderer concatenates with
+ *      none: the token is `%HERE%node.exe`, which splits on `[/\\]` to itself.
+ *      Stripping one leading `%NAME%` is what makes the basename a basename —
+ *      and a token that is nothing BUT an expansion (`%NODE%`) strips to empty
+ *      and stays `null`, which is the honest answer.
+ *   3. Windows executables carry `.exe` and this vocabulary does not
+ *      (`'gjs' | 'node'`). PATHEXT makes `node` and `node.exe` the same program,
+ *      so the suffix comes off. `.cmd` and `.bat` deliberately do NOT: those are
+ *      batch files, not interpreters, and resolving one to a bare name would be
+ *      this reader claiming to know what that script runs.
+ *
+ * The first token is taken the way `cmd.exe` takes it — a quoted run up to the
+ * closing quote, otherwise up to the first whitespace — rather than by splitting
+ * on spaces, because a program directory under `C:\Program Files\…` is exactly
+ * the case a naive split gets wrong.
+ */
+function cmdProgramOf(line) {
+    const quoted = /^"([^"]*)"/.exec(line);
+    const token = quoted !== null ? quoted[1] : (line.split(/\s+/)[0] ?? '');
+    const expanded = token.replace(/^%[^%\s]*%/, '');
+    const leaf = expanded.split(/[/\\]/).pop() ?? '';
+    const bare = leaf.replace(/\.exe$/i, '');
+    return bare === '' ? null : bare;
+}
+/**
+ * Last path segment of a shell TOKEN, POSIX or Windows.
+ *
+ * The quotes come off first, and that is not cosmetic. #1354 M2b makes the macOS
+ * launcher exec `"$here/node"` — the interpreter the bundle carries, named by a
+ * layout-relative path because macOS has no system Node to find on `PATH`.
+ * Without the strip this reader answered `node"`, which is neither `node` nor
+ * `gjs`, so {@link assertLauncherMatchesInterpreter} took its "a program that is
+ * neither" branch and passed. Not a wrong answer — a VACUOUS one, on exactly the
+ * layout that made the check matter, and green.
+ *
+ * Both quote characters, and only as a surrounding pair: a shell token is
+ * `"…"`, `'…'` or bare, and stripping a lone quote from the middle of a word
+ * would be this function guessing at a syntax it does not parse. The `$here`
+ * inside survives as a literal, which is fine — this reader wants the last
+ * SEGMENT, and no expansion can change which segment that is.
+ */
+function basenameOf(token) {
+    const parts = unquote(token).split(/[/\\]/);
+    return parts[parts.length - 1] ?? '';
+}
+/** `"x"` and `'x'` → `x`; everything else unchanged. */
+function unquote(token) {
+    const first = token[0];
+    if ((first === '"' || first === "'") && token.length > 1 && token[token.length - 1] === first) {
+        return token.slice(1, -1);
+    }
+    return token;
+}
+/**
+ * Refuse a package whose launcher execs an interpreter the package does not
+ * depend on.
+ *
+ * THE RULE, and it is deliberately asymmetric: fail ONLY when the launcher
+ * positively names the OTHER known interpreter and never names the declared one.
+ * Everything else passes — no launcher, no `exec` this reader resolves, a program
+ * that is neither `gjs` nor `node`, or a script whose branches include the
+ * declared one.
+ *
+ * That asymmetry is the correction. The first cut failed whenever the resolved
+ * token was not equal to the declared interpreter, and its own doc comment
+ * claimed the opposite ("`null` is SILENT ... refusing a package because this
+ * function did not understand a launcher somebody else wrote would fail a
+ * working artifact over a parser"). The parser's failure mode is not `null` — it
+ * answers confidently wrong. Measured on an otherwise untouched `--app gjs`
+ * project whose `gjsify.ship.extraFiles` replaced `bin/<name>`:
+ *
+ *     exec /usr/bin/gjs -m …        → exit 1, "execs `/usr/bin/gjs`"
+ *     exec env NODE_OPTIONS=… node… → exit 1, "execs `env`"
+ *
+ * Both worked before the check existed. A guard that turns working packages into
+ * failures buys nothing over the defect it prevents.
+ *
+ * The advice in the message is also fixed. It used to say "re-run the `--stage`
+ * phase", which is FALSE for the case that actually reaches a user: re-staging
+ * an `extraFiles` override reproduces it forever. The two real causes are named
+ * instead.
+ */
+export function assertLauncherMatchesInterpreter(payload, layout, identity, interpreter) {
+    const found = readLauncherInterpreters(payload, layout, identity);
+    if (found.length === 0 || found.includes(interpreter))
+        return;
+    const other = interpreter === 'gjs' ? 'node' : 'gjs';
+    if (!found.includes(other))
+        return;
+    throw new Error(`gjsify ship: the launcher ${launcherPath(layout, identity)} execs \`${other}\`, but this package ` +
+        `would declare a dependency on \`${interpreter}\`.\n` +
+        '    An installed package that depends on one interpreter and runs another installs cleanly and ' +
+        'fails\n' +
+        "    at first launch, on the user's machine.\n" +
+        // THIS TARGET's key, and not `gjsify.app`. Since #1486 the runtime is
+        // resolved per target, so sending the reader to the project field to
+        // fix ONE layout's launcher moves every other layout's `Depends:` with
+        // it — the defect § A22 exists to close, reintroduced by the message
+        // that reports it. Named as a project edit because `--from-stage`
+        // reaches here too, and that host has no config to change.
+        `    Either set \`gjsify.ship.app.${layout.os}\` to "${other}" in the project this was staged ` +
+        'from — it overrides\n' +
+        '    `gjsify.app` for that target alone — or fix the launcher: if it comes from ' +
+        '`gjsify.ship.extraFiles`,\n' +
+        '    that override is what decides which interpreter runs and it must match the declaration.');
+}
+/**
+ * What each known `share/` directory costs a layout with no install step.
+ *
+ * Keyed on {@link SHARE}, so the compiler — not a comment — is what keeps this in
+ * step with where `plan.ts` stages the files and which directory
+ * `cacheRefreshCommands` refreshes. The previous version claimed exactly that in
+ * prose over five independent string literals, and pointing one rule at a
+ * directory matching nothing silently dropped a file from the printed warning
+ * with the whole suite green at exit 0.
+ *
+ * The verdict is a FUNCTION of the payload rather than a constant, and exactly
+ * one row uses that: the schema directory's cost depends on whether the compiled
+ * cache is in the tree with it. Making it a function keeps that in the table
+ * instead of as a branch in the loop — one place still answers "what does this
+ * directory cost", which is the property the five string literals cost us.
+ */
+const SHARE_VERDICTS = [
+    [
+        SHARE.schemas,
+        // The `aborts` branch is what #1354 M2a removed the cause of, and it is
+        // deliberately still REACHABLE: a stage assembled before the compile step
+        // existed, or one whose cache was deleted, classifies as `aborts` again
+        // with no rule to remember to re-add. A rule that can no longer fire is a
+        // comment; this one is a mechanism.
+        ({ hasCompiledSchemas }) => hasCompiledSchemas
+            ? [
+                'inert',
+                'the schema SOURCE; `gschemas.compiled` is staged beside it and that is what ' +
+                    'GSettings reads, so this file is carried and never opened',
+            ]
+            : [
+                'aborts',
+                'needs `glib-compile-schemas`, and the launcher points XDG_DATA_DIRS here — ' +
+                    'GSettings ABORTS on a schema directory with no `gschemas.compiled`',
+            ],
+    ],
+    [SHARE.mime, () => ['inert', 'needs `update-mime-database`; detection runs off the compiled cache']],
+    [SHARE.icons, () => ['inert', 'needs `gtk-update-icon-cache`; neither OS reads the hicolor theme']],
+    [SHARE.applications, () => ['inert', 'a freedesktop desktop entry; neither OS reads one']],
+    [SHARE.metainfo, () => ['inert', 'an AppStream component; neither OS reads one']],
+];
+/**
+ * Paths that survive the trip, so the rule below can be an INVERSE one.
+ *
+ * Three entries and they are different SHAPES, which is why the check below tests
+ * both containment and equality:
+ *
+ *  - `share/locale` is a DIRECTORY. A `.mo` is read straight off disk by
+ *    `bindtextdomain`, with no install step anywhere, and the launcher hands the
+ *    directory over on all three layouts.
+ *  - `share/fonts` is a directory too, and it is here for a NARROWER reason than
+ *    the one next to it (ADR 0038). What this list means is "no package install
+ *    step makes this correct", and that is true of a face on every layout: nothing
+ *    compiles it, nothing reindexes it, and on Linux fontconfig scans the
+ *    directory and caches lazily per user. What it deliberately does NOT claim is
+ *    that a face is FOUND on the other two — macOS reaches it through
+ *    `Info.plist`'s `ATSApplicationFontsPath` and Windows only through a call the
+ *    app makes itself. Those are `Layout.fontGap`, printed separately, because
+ *    they are facts about an OS rather than about a missing scriptlet, and folding
+ *    them in here would report the answer under a heading that names the wrong
+ *    question.
+ *  - `gschemas.compiled` is one FILE, and it is here because it is not a cost —
+ *    it is the thing that removes one. Reported under a warning headed "whose
+ *    Linux correctness comes from a package install step" it would name the fix
+ *    as if it were the problem, and it would be the sixth line of a five-line
+ *    list nobody asked to grow.
+ */
+const SHARE_PORTABLE = [SHARE.locale, SHARE.fonts, SCHEMA_CACHE];
+/**
+ * Every `share/` entry a non-Linux layout carries, classified — including the
+ * ones nothing here has a rule for.
+ *
+ * WHY THIS EXISTS, and it is the hole the layout axis opened. `planStage` emits
+ * one prefix-relative plan and every layout carries it, so the darwin and windows
+ * trees hold the same `share/…` files the `.deb` does — and on Linux most of those
+ * are only correct because `cacheRefreshCommands` compiles or reindexes them at
+ * install time (`scripts.ts`), which is a `.deb`/`.rpm` scriptlet and nothing else.
+ *
+ * The equality `tests/e2e/ship-layout` checks — same file set, same bytes, modulo
+ * the map — is structurally blind to all of it, because SAMENESS IS THE DEFECT:
+ * the Linux tree is right for a reason the other two do not have.
+ *
+ * EXHAUSTIVE, not an allow-list, and that direction is the point. A closed list of
+ * five was measured to say "carries 5 file(s)" for a payload carrying six — a
+ * `share/dbus-1/services/*.service` added through `gjsify.ship.extraFiles` is
+ * meaningful on Linux only because the package installs it into a system prefix,
+ * and it went unnamed. Anything under `share/` that is neither classified nor
+ * known-portable comes back as `unknown` rather than silently passing.
+ *
+ * ONE ENTRY IS ANSWERED BY THE SET, not by its own path: the GSettings schema
+ * directory aborts the app when it holds a source `.gschema.xml` and no compiled
+ * cache, and is merely inert when the cache is beside it. #1354 M2a compiles that
+ * cache into every non-Linux stage, so the `aborts` branch is empty for a stage
+ * this gjsify wrote — and it is still REACHABLE, which is the point: a stage
+ * assembled before the compile step existed, or one whose cache was removed,
+ * classifies as `aborts` again with no rule to remember to re-add.
+ *
+ * What the rest BECOME — an `Info.plist` `CFBundleDocumentTypes`, a Windows
+ * registry association, or nothing — is ADR 0024 stages 4 and 5. The `.app`
+ * container exists as of M2a; the file-type and icon halves do not.
+ */
+export function linuxInstallDependent(entries) {
+    const out = [];
+    // Asked of the WHOLE payload once, not per entry: "does this tree carry a
+    // compiled schema cache" is a fact about the set, and asking it inside the
+    // loop would make the answer depend on iteration order.
+    const context = { hasCompiledSchemas: entries.some((entry) => entry.path === SCHEMA_CACHE) };
+    for (const entry of entries) {
+        if (!isUnder(entry.path, 'share'))
+            continue;
+        if (SHARE_PORTABLE.some((portable) => entry.path === portable || isUnder(entry.path, portable)))
+            continue;
+        const rule = SHARE_VERDICTS.find(([dir]) => isUnder(entry.path, dir));
+        if (rule === undefined) {
+            out.push({
+                path: entry.path,
+                verdict: 'unknown',
+                why: 'nothing here classifies this directory — it may need an install step no ' +
+                    'non-Linux layout runs, or it may be inert; say which before shipping it',
+            });
+            continue;
+        }
+        const [verdict, why] = rule[1](context);
+        out.push({ path: entry.path, verdict, why });
+    }
+    // `aborts` first: a list sorted by path buried the one entry that stops the
+    // application behind four that merely do nothing.
+    const rank = { aborts: 0, unknown: 1, inert: 2 };
+    return out.sort((a, b) => rank[a.verdict] - rank[b.verdict] || (a.path < b.path ? -1 : 1));
+}
 /**
  * The interpreters the payload's own executables need, read off their shebangs.
  *
@@ -148,15 +675,44 @@ const MACHO_CPUTYPE_TO_ARCH = {
     0x01000007: 'x64',
     0x0100000c: 'arm64',
 };
+/**
+ * PE/COFF `IMAGE_FILE_HEADER.Machine` → `process.arch`.
+ *
+ * The same three rows `manifest-conformance/lib/binary.mjs` carries, restated
+ * rather than imported because `@gjsify/manifest-conformance` is `"private": true`
+ * and `@gjsify/cli` is published: a published package cannot depend on a workspace
+ * package that is never on npm. (An earlier version of this note said the CLI must
+ * not depend on it because the rules are `portable` — `portable` is a `RuleScope`
+ * on individual conformance RULES, and the ban it states runs the other way: a
+ * portable rule must not import the CLI.) The values themselves are Microsoft's
+ * architecture constants, so agreeing with that file is not agreeing with
+ * ourselves.
+ */
+const PE_MACHINE_TO_ARCH = {
+    0x014c: 'ia32',
+    0x8664: 'x64',
+    0xaa64: 'arm64',
+};
 /**
  * The `process.arch` token an image says it is built for, or `null` when the
  * question cannot be answered from the bytes.
  *
- * `null` covers three different things on purpose, and all three must stay
- * silent: a file that is not a native binary at all (most of a payload), a PE
- * (whose COFF machine field this tree has never parsed — `isNativeBinary` reads
- * `MZ` and stops), and a Mach-O fat archive, which carries several
- * architectures and therefore matches any label a caller could pass.
+ * `null` still covers three different things on purpose, and all three must stay
+ * silent: a file that is not a native binary at all (most of a payload), an image
+ * whose machine constant is not in the tables above, and a Mach-O fat archive,
+ * which carries several architectures and therefore matches any label a caller
+ * could pass.
+ *
+ * PE WAS A FOURTH, AND IT WAS THE WORST ONE. This comment used to say PE was
+ * silent because "this tree has never parsed" the COFF machine field — true, and
+ * it made `assertPayloadMatchesArch` VACUOUS on the one layout whose native format
+ * IS PE. #1354 M2b made that check non-vacuous for darwin by staging Mach-O into a
+ * `.app`; M3 stages `node.exe` and a win32 GTK closure into a Windows program
+ * directory, so a windows stage built with the wrong `--arch` would have carried
+ * x64 DLLs under an `arm64` label with nothing to notice. Two reads — `e_lfanew`
+ * at 0x3c, then `Machine` four bytes past the `PE\0\0` signature — close it. A
+ * truncated `MZ` with no reachable PE header stays `null`, which is what
+ * `packers.spec.ts` has always asserted and still does.
  */
 export function readBinaryArch(data) {
     if (data.byteLength < 20)
@@ -174,6 +730,18 @@ export function readBinaryArch(data) {
     if (magic === 0xcefaedfe || magic === 0xcffaedfe) {
         return MACHO_CPUTYPE_TO_ARCH[((data[7] << 24) | (data[6] << 16) | (data[5] << 8) | data[4]) >>> 0] ?? null;
     }
+    // PE/COFF: `MZ`, then `IMAGE_DOS_HEADER.e_lfanew` at 0x3c points at `PE\0\0`,
+    // and `IMAGE_FILE_HEADER.Machine` is the u16 right after it. Every field here
+    // is little-endian regardless of the machine it names.
+    if (data[0] === 0x4d && data[1] === 0x5a && data.byteLength >= 0x40) {
+        const peOffset = (data[0x3c] | (data[0x3d] << 8) | (data[0x3e] << 16) | (data[0x3f] << 24)) >>> 0;
+        if (peOffset + 6 > data.byteLength)
+            return null;
+        const signature = (data[peOffset] | (data[peOffset + 1] << 8) | (data[peOffset + 2] << 16)) >>> 0;
+        if (signature !== 0x004550 || data[peOffset + 3] !== 0x00)
+            return null;
+        return PE_MACHINE_TO_ARCH[data[peOffset + 4] | (data[peOffset + 5] << 8)] ?? null;
+    }
     return null;
 }
 /**
@@ -214,20 +782,37 @@ export function assertPayloadMatchesArch(payload, arch) {
             'actually have.');
     }
 }
-/** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */
-function isNativeBinary(data) {
+/**
+ * Which executable format these bytes are, or `null` for anything else.
+ *
+ * The FAMILY and not merely "is it native", because the signer needs the
+ * distinction: `codesign` signs Mach-O and `signtool` signs PE, and an ELF in a
+ * darwin payload is neither — it is a file that should not be there. A caller
+ * asking only "is this native" would have handed one to `codesign`, whose
+ * refusal names a file rather than the mistake.
+ *
+ * Magic numbers rather than suffixes, and that is load-bearing on darwin: a GTK
+ * closure names its images `.dylib`, `.so`, `.node` and nothing at all (the
+ * interpreter), so a suffix list signs three of those four.
+ */
+export function classifyBinary(data) {
     if (data.byteLength < 4)
-        return false;
+        return null;
     const magic = (data[0] << 24) | (data[1] << 16) | (data[2] << 8) | data[3];
     switch (magic >>> 0) {
         case 0x7f454c46: // \x7fELF
+            return 'elf';
         case 0xfeedface: // Mach-O 32
         case 0xfeedfacf: // Mach-O 64
         case 0xcefaedfe: // Mach-O 32, byte-swapped
         case 0xcffaedfe: // Mach-O 64, byte-swapped
         case 0xcafebabe: // Mach-O universal binary
-            return true;
+            return 'macho';
         default:
-            return data[0] === 0x4d && data[1] === 0x5a; // MZ — PE/COFF
+            return data[0] === 0x4d && data[1] === 0x5a ? 'pe' : null; // MZ — PE/COFF
     }
 }
+/** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */
+function isNativeBinary(data) {
+    return classifyBinary(data) !== null;
+}