@gjsify/cli 0.44.0 → 0.45.0

package/lib/utils/ship/payload.d.ts

@@ -1,3 +1,4 @@
+import { type Layout, type LayoutIdentity } from './layout.js';
 /** One file in the payload, with its bytes. */
 export interface PayloadEntry {
     /** Prefix-relative path, POSIX-separated, e.g. `bin/learn6502`. */
@@ -46,6 +47,14 @@ export declare function buildTimestamp(bundlePath: string, env?: Record<string,
  * Path-only, on purpose — `isArchIndependent` is the sibling that reads BYTES, and the two answer
  * different questions from the same payload. The same split as `plan.ts`'s `isExecutableAsset`
  * (by name) versus this module's magic sniffing (by content).
+ *
+ * NOT EVERY QUESTION BELONGS HERE, and one that does not was briefly added: "does this package need
+ * a Node interpreter", derived from a `*.node.mjs` filename anywhere in the tree. Every fact above
+ * is about something the package INSTALLS at a well-known path, which is why a path answers it.
+ * That one was about what the launcher EXECS — and `discoverPayload` stages the whole directory
+ * beside the bundle, so a `--app gjs` project that also builds a Node bundle carried the file and
+ * ran neither. It lives on `settings.app` now, with `assertLauncherMatchesInterpreter` below as the
+ * check. Before adding a field here, ask whether a path can answer it or only correlate with it.
  */
 export interface PayloadFacts {
     /** The payload installs a `share/applications/*.desktop`. */
@@ -70,6 +79,123 @@ export interface PayloadFacts {
 export declare function readPayloadFacts(entries: readonly {
     path: string;
 }[]): PayloadFacts;
+/**
+ * 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 declare function readLauncherInterpreters(payload: readonly PayloadEntry[], layout: Layout, identity: LayoutIdentity): string[];
+/**
+ * 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 declare function assertLauncherMatchesInterpreter(payload: readonly PayloadEntry[], layout: Layout, identity: LayoutIdentity, interpreter: 'gjs' | 'node'): void;
+/**
+ * How a `share/` entry behaves once it leaves the layout a Linux package installs.
+ *
+ * `aborts` and `inert` are not one severity, and printing them as one was a
+ * measured presentation defect: every launcher exports `XDG_DATA_DIRS` at the
+ * staged `share/`, so a `.app` built from a stage with an UNCOMPILED schema
+ * directory points GSettings at an `.xml` with no `gschemas.compiled` beside it —
+ * `g_settings_new()` ABORTS. The others merely do nothing. Ranking them
+ * identically in a list of five buried the one that stops the app.
+ *
+ * #1354 M2a compiles that cache into every non-Linux stage, so `aborts` is empty
+ * for a stage this gjsify wrote. The variant STAYS, and reachable — see
+ * {@link SHARE_VERDICTS}'s schema row.
+ */
+export type ShareVerdict = 'aborts' | 'inert' | 'unknown';
+/** One `share/` entry a non-Linux layout carries, and what happens to it there. */
+export interface CarriedShareEntry {
+    path: string;
+    verdict: ShareVerdict;
+    why: string;
+}
+/**
+ * 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 declare function linuxInstallDependent(entries: readonly {
+    path: string;
+}[]): CarriedShareEntry[];
 /**
  * The interpreters the payload's own executables need, read off their shebangs.
  *
@@ -108,11 +234,22 @@ export declare function isArchIndependent(payload: readonly PayloadEntry[]): boo
  * 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 declare function readBinaryArch(data: Uint8Array): string | null;
 /**
@@ -139,3 +276,17 @@ export declare function readBinaryArch(data: Uint8Array): string | null;
  * comparison would refuse the very case the split exists to allow.
  */
 export declare function assertPayloadMatchesArch(payload: readonly PayloadEntry[], arch: string): void;
+/**
+ * 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 declare function classifyBinary(data: Uint8Array): 'elf' | 'macho' | 'pe' | null;