@gjsify/cli 0.44.0 → 0.46.0

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

@@ -0,0 +1,330 @@
+import type { HostOs, StagedFile } from './types.js';
+/**
+ * The positional `gjsify ship <os>` takes, in ADR 0024 § A2's spelling.
+ *
+ * NOT the same vocabulary as {@link HostOs}, and the difference is deliberate
+ * rather than sloppy: § A2 writes `gjsify ship windows --stage`, while the
+ * repo-wide target spelling is `${process.platform}-${process.arch}` and
+ * therefore `win32-x64` (root AGENTS.md § Runtime & platform model). Both are
+ * accepted on the command line and exactly one is ever RECORDED — the stage
+ * manifest's `target.os` is a `HostOs`, so `--expect-target win32-x64` keeps
+ * meaning what it meant.
+ */
+export type LayoutName = 'linux' | 'darwin' | 'windows';
+/** The layout-affecting half of `ShipSettings` — a display name and a binary name, nothing else. */
+export interface LayoutIdentity {
+    /** Package name: the launcher's own filename. */
+    binaryName: string;
+    /** Human-readable display name — the `<App>.app` directory a user sees in Finder. */
+    name: string;
+}
+/**
+ * What a layout needs to render the metadata it OWNS.
+ *
+ * `LayoutIdentity` plus the three fields an `Info.plist` names the app by. It
+ * EXTENDS the identity rather than sitting beside it so `placeStage` keeps taking
+ * one argument and `ShipSettings` satisfies it structurally — no call site has to
+ * assemble a second object, and adding a field here is a compile error at exactly
+ * the rows that would have to answer for it.
+ *
+ * Everything here comes from the consumer's own `gjsify.ship` block. Nothing in
+ * this file is derived from gjsify's tree and nothing has a gjsify-specific
+ * default, which is the same line {@link LayoutDirs} draws for directories.
+ */
+export interface LayoutMetadataInput extends LayoutIdentity {
+    /** Reverse-DNS application id — `CFBundleIdentifier`, and what the data tree is keyed on. */
+    appId: string;
+    /** Upstream version — `CFBundleShortVersionString`. */
+    version: string;
+    /** Packaging revision within one upstream version — the second half of `CFBundleVersion`. */
+    release: string;
+    /**
+     * `process.arch` the payload is LABELLED for — what `--arch` names.
+     *
+     * Here because a layout can own a PROGRAM and not only a manifest, and a
+     * program has an architecture: the windows row emits an x86-64 GUI launcher,
+     * and staging it into a tree labelled `arm64` would make
+     * `assertPayloadMatchesArch` refuse a stage over a file the author never
+     * named. `Layout.arches` already says the windows layout has no other
+     * architecture; this is the same fact where the file is written.
+     */
+    arch: string;
+}
+/** The four places a payload file can belong, as stage-relative directories. */
+export interface LayoutDirs {
+    /** Where the launcher lives. */
+    launcher: string;
+    /** Where the app's own bundle tree lives. */
+    bundle: string;
+    /** Where the typelibs and shared libraries the app CARRIES live. */
+    native: string;
+    /** Where the XDG-shaped data tree lives (icons, schemas, metainfo, locale). */
+    data: string;
+    /**
+     * Where a prefix-relative path that sorts into none of the above goes.
+     *
+     * Reachable only through `gjsify.ship.extraFiles`, whose destinations are
+     * documented as prefix-relative and may name anything. On macOS that has to
+     * land inside `Contents/`, or the file sits beside it where nothing in the
+     * bundle can address it and `codesign` later refuses the bundle.
+     */
+    other: string;
+}
+/**
+ * One operating system's layout.
+ *
+ * Data, not code: adding a fourth OS is a row here plus a launcher form, the same
+ * way adding a format is a row in `FORMATS`. The one function is {@link place},
+ * and it is shared by all three.
+ */
+export interface Layout {
+    /** The positional that selects this layout. */
+    name: LayoutName;
+    /** The `process.platform` token recorded in the stage manifest's `target.os`. */
+    os: HostOs;
+    /**
+     * The runtime ADR 0024 § 4 DERIVES for a shipped artifact on this OS.
+     *
+     * Recorded, not obeyed: it is what #1354 M0's platform packages implement,
+     * and it is NOT what the staged launcher execs today. Linux takes GJS from
+     * the distribution and the emitted `Depends: gjs` backs it; both other OSes
+     * take Node, because Node + `@gjsify/node-gi` + `@gjsify/gtk-runtime-<os>-<arch>`
+     * is the only combination either OS's CI proves.
+     *
+     * Keeping it as DATA rather than as a launcher decision is the whole of what
+     * M1 may honestly claim. A layout with no packer produces no installable
+     * artifact, so writing `exec node` into a stage assembled from a `--app gjs`
+     * bundle would put a runtime that cannot read the payload in front of it —
+     * the exact defect `resolveShipApp`'s refusal exists to prevent, produced by the
+     * code meant to prevent it. Measured before this was data: `gjsify ship
+     * darwin --stage` on a project with no `gjsify.app` key exited 0 and staged
+     * `exec node "$contents/Resources/lib/gjs.js"` in front of a bundle whose
+     * first line is `import Gtk from 'gi://Gtk?version=4.0'`.
+     */
+    shippedRuntime: 'gjs' | 'node';
+    /**
+     * Why the staged launcher cannot name {@link shippedRuntime} yet, or absent
+     * when it already does.
+     *
+     * PRINTED at stage time rather than left as a comment: a tree whose launcher
+     * execs an interpreter the target OS may not have is a fact its author has to
+     * know, and it is the same fact that retires this field when M0 lands.
+     */
+    runtimeGap?: string;
+    /**
+     * Why a face in the payload's `share/fonts` may not be REACHED on this OS, or
+     * absent where nothing stands in its way.
+     *
+     * Optional, mirroring {@link runtimeGap} rather than {@link metadata}'s
+     * required-and-empty shape, because it asks the same kind of question: is there
+     * something true about this OS that the staged tree cannot show? Linux answers
+     * by having none.
+     *
+     * THE GAP IS NOT THE PATH (ADR 0038). The faces are STAGED identically on all
+     * three layouts and `planStage` emits one plan for them; what differs is what
+     * READS the directory. On Linux fontconfig does, expanding
+     * `<dir prefix="xdg">fonts</dir>` over the `XDG_DATA_DIRS` every launcher
+     * already exports — measured in eight independent fontconfigs — so that row has
+     * nothing to report. On the other two the reader is a property of
+     * `@gjsify/gtk-runtime-<target>` rather than of this payload, and it is not
+     * fontconfig in either: CoreText on macOS, DirectWrite on Windows, the latter
+     * measured on hardware (`LAYOUTS.windows.fontGap` carries the numbers).
+     * `gjsify ship` prints this only when the payload actually carries a face, so a
+     * project shipping none is told nothing.
+     */
+    fontGap?: string;
+    /** Suffix the launcher's filename carries, `''` where the OS needs none. */
+    launcherExt: string;
+    /**
+     * The directory inside the STAGE that this layout hangs under, or `''` when
+     * the stage root IS the layout root.
+     *
+     * The asymmetry is the OS's, not ours. A `<App>.app` is the artifact — it is
+     * dragged to `/Applications` as one unit, so the stage has to carry the
+     * directory itself. A Windows program directory is NOT: the installer chooses
+     * `C:\Program Files\<Publisher>\<App>` and lays the stage's contents into it,
+     * so a wrapper directory here would become a doubled path there.
+     */
+    root: (identity: LayoutIdentity) => string;
+    /** The four destinations, resolved against one app's names. */
+    dirs: (identity: LayoutIdentity) => LayoutDirs;
+    /**
+     * Files this layout OWNS, already in stage-relative form — `[]` where it owns none.
+     *
+     * The seam {@link place} structurally cannot provide, and that is why it is a
+     * second function rather than another prefix rule. `Contents/Info.plist` has no
+     * prefix-relative counterpart to be mapped FROM: `planStage` emits one plan in
+     * the Linux/XDG shape, everything unmatched falls to `dirs.other`, and
+     * `assertInsidePrefix` forbids a plan entry from escaping upward — so no
+     * `gjsify.ship.extraFiles` value and no planner rule can put a file at the
+     * bundle root. The layout has to add it.
+     *
+     * REQUIRED on every row, not optional. An optional field is one a fourth OS can
+     * forget; a required one that returns `[]` is a row that has ANSWERED "this
+     * layout owns nothing", which is a different statement and the one worth being
+     * able to read. Linux and Windows both answer that today — a program directory
+     * and a `/usr` prefix have no manifest of their own — so the whole difference
+     * between "no metadata yet" and "no metadata ever" stays visible.
+     *
+     * The result is placed by `placeStage`, which applies the SAME uniqueness check
+     * it applies to mapped files: an `extraFiles` destination that lands on
+     * `Contents/Info.plist` is refused rather than silently replacing it.
+     *
+     * IT TAKES THE PAYLOAD, in the prefix-relative shape, because a manifest is a
+     * statement ABOUT a tree and one key already has to be (ADR 0038):
+     * `ATSApplicationFontsPath` names the directory the bundle's faces are in, and
+     * emitting it over a bundle that carries none would point macOS at a path that
+     * is not there. That is also the seam `CFBundleDocumentTypes` will need, which
+     * is ADR 0024 stages 4 and 5 — so the parameter is the payload rather than a
+     * `hasFonts` flag: the next key to need it will need a different question
+     * answered about the same tree.
+     */
+    metadata: (input: LayoutMetadataInput, payload: readonly StagedFile[]) => StagedFile[];
+    /**
+     * The `process.arch` values this layout can be assembled for, or `null` when
+     * it imposes no limit of its own.
+     *
+     * REQUIRED on every row, like {@link metadata}, and for the same reason: `null`
+     * is an ANSWER ("this layout constrains nothing"), while an optional field is
+     * one a fourth OS forgets and then silently inherits Linux's answer. Linux is
+     * the `null` row — a `.deb` exists for every architecture Debian has, and
+     * `DEBIAN_ARCH`/`RPM_ARCH` in `formats.ts` already refuse the ones this project
+     * has no name for.
+     *
+     * WHY IT IS ON THE LAYOUT AND NOT ONLY ON THE FORMAT, since
+     * {@link assertLayoutSupportsArch} runs in `packOne` — the same phase
+     * `FormatDescriptor.archName` does, and this field buys neither an earlier
+     * refusal nor a different one. It buys the two things a table lookup cannot:
+     *
+     *  * a REASON. `archName` answers "no Windows architecture is known for
+     *    `process.arch` \"arm64\"", which reads as a gap in our table. The truth is
+     *    that gvsbuild publishes no arm64 GTK, the blocker is upstream, and #1117
+     *    is where it is tracked — and the difference between "unsupported" and
+     *    "here is what would have to change" is the whole value of the message.
+     *  * a STAGE-TIME warning at the flag that caused it (`commands/ship.ts`), for
+     *    a phase that deliberately does not refuse — `tests/e2e/ship-layout`
+     *    assembles all three layouts from ONE payload on purpose, and that
+     *    payload's native file has an architecture.
+     *
+     * The constraint is also a fact about the layout's RUNTIME story — which GTK
+     * closure and which interpreter exist for it — rather than about any one
+     * container, which is why the format rows read it back instead of restating it.
+     */
+    arches: LayoutArches | null;
+}
+/** The architectures one layout is assemblable for, and why the others are not. */
+export interface LayoutArches {
+    /** `process.arch` spellings — the same vocabulary `--arch` takes. */
+    only: readonly string[];
+    /** What a reader must know to act on the refusal: who blocks it, and where it is tracked. */
+    why: string;
+}
+export declare const LAYOUTS: Record<LayoutName, Layout>;
+/** Every layout name, derived from the table so a new row cannot be missed. */
+export declare const LAYOUT_NAMES: LayoutName[];
+/** Stage-relative path of the launcher this layout puts in front of the app. */
+export declare function launcherPath(layout: Layout, identity: LayoutIdentity): string;
+/**
+ * Stage-relative path of the windows layout's GUI launcher.
+ *
+ * IT MUST BE `<launcherPath minus `.cmd`>.exe` AND THE STUB DEPENDS ON IT:
+ * `buildGuiLauncher` finds its `.cmd` by overwriting the last three characters of
+ * its own module filename, which is a three-character store instead of a path
+ * search only because the two names differ in exactly those bytes. Deriving both
+ * from `LAYOUTS.windows.launcherExt` here is what keeps that true — renaming the
+ * batch launcher to `.bat` would otherwise leave a stub looking for a file that
+ * is not there, at exit 0, with a window that never appears.
+ */
+export declare function windowsGuiLauncherPath(identity: LayoutIdentity): string;
+/**
+ * What the windows GUI launcher calls the file it writes under `%TEMP%`.
+ *
+ * Named after the binary rather than the display name: `%TEMP%` is shared by
+ * every application on the machine, and `binaryName` is the one identifier this
+ * project already refuses to let collide.
+ */
+export declare function windowsLaunchLogLeaf(identity: LayoutIdentity): string;
+/**
+ * The layout for one `process.platform` token, refusing every alias.
+ *
+ * STRICT, and that is the difference from {@link resolveLayout}, which is for a
+ * word a human typed. This one is for the stage manifest's `target.os` — a
+ * cross-host WIRE FORMAT with exactly one legal spelling per OS. Accepting
+ * `"windows"` there and silently comparing it as `win32` would mean
+ * `--expect-target win32-x64` no longer compares against the file's content:
+ * two manifests with different bytes in that field would both match, and the
+ * flag's whole job is to catch a job that downloaded the wrong artifact.
+ */
+export declare function layoutForOs(os: string): Layout;
+/**
+ * Resolve the positional to a layout.
+ *
+ * Accepts BOTH vocabularies (`windows` and `win32`) for the reason
+ * {@link LayoutName} records: the ADR writes one and `--expect-target` prints the
+ * other, and refusing whichever the user has in front of them is a papercut with
+ * no upside. The canonical answer is a single `Layout`, so nothing downstream has
+ * two spellings to reconcile. NOT for the stage manifest — see {@link layoutForOs}.
+ */
+export declare function resolveLayout(raw: string): Layout;
+/**
+ * The layout for the host this process is running on.
+ *
+ * What `gjsify ship` picks when the positional is absent, so a bare `gjsify ship`
+ * on Linux keeps assembling the Linux layout and packing `.deb` + `.rpm` exactly
+ * as before. A host whose platform has no layout is refused BY NAME rather than
+ * silently treated as Linux — a payload laid out for `/usr` and labelled for a
+ * FreeBSD would install and not run.
+ */
+export declare function hostLayout(platform?: string): Layout;
+/**
+ * Refuse an architecture this layout cannot be assembled for, naming the blocker.
+ *
+ * AT STAGE TIME, which is the whole point — see {@link Layout.arches}. The
+ * message carries the row's own `why` rather than a generic "unsupported", because
+ * the two refusals a reader can act on are different jobs: `x64` is what a Windows
+ * artifact is built for TODAY, and `win32-arm64` is blocked in a repository we do
+ * not own. Telling an author "unknown architecture" for the second one would send
+ * them to look for a flag.
+ *
+ * `process.arch` spelling on both sides, so the value quoted back is the one the
+ * user typed after `--arch`.
+ */
+export declare function assertLayoutSupportsArch(layout: Layout, arch: string): void;
+/**
+ * Map one PREFIX-RELATIVE planned path to where this layout keeps it.
+ *
+ * The plan is written once, in the Linux/XDG shape, and this is the only place
+ * that knows any other. Order matters: `lib/<name>/gi/` is tested before
+ * `lib/<name>/`, because on macOS those two go to different directories.
+ */
+export declare function place(layout: Layout, identity: LayoutIdentity, rel: string): string;
+/**
+ * Apply a layout to a whole planned payload, and add what the layout itself owns.
+ *
+ * THREE SOURCES, one destination namespace. The mapped files come from
+ * `planStage`'s prefix-relative plan; {@link Layout.metadata} adds the files that
+ * have no prefix-relative counterpart at all (`Contents/Info.plist`); `carried`
+ * adds the runtime the artifact ships inside itself (#1354 M2b — the interpreter,
+ * the relocated GTK closure, the node-gi addon). All three go through the same
+ * uniqueness check, which is what makes the other two safe: an `extraFiles`
+ * destination that maps onto a metadata path is refused by name instead of
+ * silently replacing the file that makes the bundle a bundle.
+ *
+ * `carried` is already stage-relative and deliberately NOT mapped. A relocated
+ * closure's every internal relation is relative — `@loader_path/<leaf>` install
+ * names, `@loader_path/../../..` in `loaders.cache`, `@loader_path/gtk/lib` on the
+ * addon — so the tree survives the copy only if it is copied as a tree. Routing it
+ * through the prefix-relative plan would put it through
+ * `gjsify.ship.bundledTypelibs`'s flattening (`plan.ts`: `posix.join(libDir, 'gi',
+ * basename(file))`), which destroys all three at once.
+ *
+ * The uniqueness check is not decoration for the mapped half either. `planStage`
+ * deduplicates on the PREFIX-RELATIVE path — that is how `gjsify.ship.extraFiles`
+ * is documented to override a default — but the MAP can bring two distinct
+ * prefix-relative paths together: on Windows the launcher becomes
+ * `<binaryName>.cmd` at the program root, which an `extraFiles` destination can
+ * name directly. Without this the second one silently wins and which one that is
+ * depends on plan order — the "installs cleanly, does nothing" class this command
+ * is built against.
+ */
+export declare function placeStage(layout: Layout, identity: LayoutMetadataInput, files: readonly StagedFile[], carried?: readonly StagedFile[]): StagedFile[];