@gjsify/cli 0.42.0 → 0.44.0

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

@@ -1,9 +1,12 @@
-/** One file in the payload, addressed relative to the install prefix. */
-export interface StagedFile {
+/** One planned path and the mode the PLAN gives it. */
+export interface StagedMode {
     /** Prefix-relative path, e.g. `bin/learn6502`, `share/applications/x.desktop`. */
     path: string;
     /** POSIX mode bits. */
     mode: number;
+}
+/** One file in the payload, addressed relative to the install prefix. */
+export interface StagedFile extends StagedMode {
     /** Where the bytes come from. */
     source: {
         kind: 'text';
@@ -13,6 +16,18 @@ export interface StagedFile {
         path: string;
     };
 }
+/**
+ * What {@link readStage} checks a staged tree against.
+ *
+ * `bytes` is present only when the plan came from a stage manifest, i.e. when
+ * the tree travelled between hosts and there is something to compare against.
+ * The single-host run plans and writes in one process, so there is no transfer
+ * to check and no second opinion to check it with.
+ */
+export interface StagePlanEntry extends StagedMode {
+    /** Size the manifest recorded for this path, when one was recorded. */
+    bytes?: number;
+}
 /** A packed artifact on disk. */
 export interface ShipArtifact {
     format: FormatId;
@@ -21,7 +36,71 @@ export interface ShipArtifact {
     /** Size in bytes. */
     size: number;
 }
-export type FormatId = 'deb' | 'rpm';
+export type FormatId = 'deb' | 'rpm' | 'flatpak';
+/**
+ * The formats whose ARTIFACT carries a distro dependency list.
+ *
+ * Not every `FormatId`, and this is where the difference is written down once
+ * instead of being rediscovered per call site. A `.deb` says
+ * `Depends: gir1.2-gtk-4.0`, an `.rpm` says `Requires: gtk4`, and both are
+ * package names in a distribution's namespace. A Flatpak has no such field: it
+ * declares ONE dependency, its runtime (`org.gnome.Platform//50`), in the
+ * manifest — and inside that runtime a typelib is either present or nothing on
+ * the system provides it, so there is no package to name and no gap a name
+ * could close.
+ *
+ * `Extract<…>` rather than a fresh literal union, so this cannot outlive
+ * `FormatId`: dropping a member there shrinks this and reds every table keyed on
+ * it. The other direction is covered by {@link FormatDescriptor.depends} being
+ * REQUIRED — a new format cannot be added without saying which side it is on.
+ */
+export type DistroFormatId = Extract<FormatId, 'deb' | 'rpm'>;
+/** An operating system in the repo-wide `process.platform` spelling (root AGENTS.md § Runtime & platform model). */
+export type HostOs = 'linux' | 'darwin' | 'win32';
+/**
+ * Where a format can be FINISHED, and who can read the result back (ADR 0024 § A3).
+ *
+ * Three fields rather than one `hostOs`, because the three questions have
+ * different answers. `finishOn` is not the LAYOUT — a `<App>.app` tree is
+ * assembled anywhere while the `.dmg` around it needs macOS. `requiredTools` is
+ * not implied by `finishOn` — `.deb` and `.rpm` are written by this tree and
+ * exec nothing, which is the whole reason `rpm` could become an independent
+ * oracle and catch the dpkg-`$1` defect in the first artifact. And `oracle` is
+ * derivable from neither: a format built by the platform's own tool forfeits
+ * that independence unless a reader from a DIFFERENT implementation family
+ * exists, which is exactly what `selfReading` is the honest confession of.
+ */
+export interface HostRequirement {
+    /** OSes whose tooling can finish this format. `'any'` = pure JS, under GJS, offline. */
+    finishOn: 'any' | readonly HostOs[];
+    /** Commands the packer EXECS. Empty iff this tree writes the format itself. */
+    requiredTools: readonly string[];
+    /**
+     * How to install {@link requiredTools}, in this format's own words.
+     *
+     * DATA, because the refusal that names it is one generic function. The
+     * first cut hardcoded `sudo dnf install flatpak flatpak-builder` inside
+     * `assertToolsInstalled`, which is correct for exactly one format and would
+     * have told the first `.dmg` or `.msi` user to install flatpak — from the
+     * same branchless dispatch this whole table exists to keep branchless.
+     * Required whenever `requiredTools` is non-empty; `flatpak.spec.ts` holds
+     * that, the same way it holds `selfReading`.
+     */
+    installHint?: string;
+    oracle: {
+        /** Readers from a DIFFERENT implementation family than the packer. */
+        readWith: readonly string[];
+        /** Where each reader runs. A Linux-runnable reader is worth more — every CI leg has one. */
+        readOn: readonly HostOs[];
+        /**
+         * No independent discriminator yet. Legal to DECLARE while a format is
+         * being built; illegal to release — `flatpak.spec.ts` is what turns that
+         * sentence into a red test, so flipping it is a decision somebody makes
+         * rather than a field nobody reads.
+         */
+        selfReading: boolean;
+    };
+}
 /**
  * Everything that is per-FORMAT, as data.
  *
@@ -33,6 +112,13 @@ export interface FormatDescriptor {
     id: FormatId;
     /** Install prefix the format's contents hang under. */
     prefix: string;
+    /** Where this format can be packed, what it execs, and who reads it back. */
+    host: HostRequirement;
+    /**
+     * The key this format's dependency list is spelled under, or `null` when its
+     * dependencies are not a package list at all — see {@link DistroFormatId}.
+     */
+    depends: DistroFormatId | null;
     /** Where the project's licence text goes in this format's overlay. */
     licenseDest: (binaryName: string) => string;
     /**
@@ -49,19 +135,69 @@ export interface FormatDescriptor {
      * arm64 machine it runs on perfectly. One `.so` in the payload flips it.
      */
     archName: (arch: string, archIndependent: boolean) => string;
-    /** Artifact filename, given the resolved settings and the resolved arch label. */
-    fileName: (settings: ShipSettings, archLabel: string) => string;
+    /** Artifact filename, given the pack-time settings and the resolved arch label. */
+    fileName: (settings: PackSettings, archLabel: string) => string;
 }
-/** The resolved, fully defaulted configuration for one `gjsify ship` run. */
-export interface ShipSettings {
-    /** Absolute path to the project being shipped. */
-    projectDir: string;
-    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
-    appId: string;
-    /** Human-readable display name. */
-    name: string;
+/** One shared-mime-info type definition (`gjsify.ship.mimeTypes`). */
+export interface ShipMimeType {
+    type: string;
+    comment: string;
+    globs?: string[];
+    subClassOf?: string;
+    genericIcon?: string;
+}
+/**
+ * The half of the configuration that survives the host boundary.
+ *
+ * `gjsify ship --from-stage` runs on a machine that has the staged tree and
+ * NOTHING else: no project directory, no `package.json`, no built bundle. So
+ * the two phases exchange exactly this object, serialised into the stage's
+ * `.gjsify-ship-stage.json`, and that is why the split is a TYPE rather than a
+ * convention — the packers take a `PackSettings`, so a `settings.bundlePath`
+ * read added to `deb.ts` or `rpm.ts` is a compile error until the field is
+ * moved here, and moving it here is what puts it in the manifest.
+ *
+ * Every field below has a MEASURED reader in the pack path
+ * (`deb.ts`, `rpm.ts`, `depends.ts`, `formats.ts#fileName`). Nothing is here
+ * "because ship needs it": a settings dump is what ADR 0024 § A2 rejects, and
+ * a dumped field that happens to be an absolute path is a path the packing host
+ * cannot open.
+ *
+ * NOT here, deliberately, and each with the reason it is not:
+ *  - `projectDir`, `outDir` — nothing in the pack path reads either; the
+ *    finishing host has its own output root.
+ *  - `bundlePath`, `bundleDir` — build-tree paths. Their three readers are all
+ *    phase 1: the build stamp (carried as the manifest's `mtime`), the
+ *    launcher's exec target (already rendered into the staged `bin/<name>`),
+ *    and the GI-namespace scan (carried as the manifest's `namespaces`).
+ *  - `iconFiles`, `schemaFiles`, `typelibFiles` — the pack path reads them only
+ *    to ask what the PAYLOAD contains, which the payload answers itself; see
+ *    `readPayloadFacts`.
+ *  - `licenseFile`, `extraFiles` — phase 1 reads their bytes into the plan.
+ *  - `localeFiles` — same, and the reason is worth stating because the field
+ *    arrived (#1263) AFTER this split was written and carries a build-host
+ *    `abs` path: `planStage` reads each catalogue into the staged tree at
+ *    `share/locale/<rel>`, and no packer reads the field. So translations
+ *    cross in the payload, where they belong, and the `abs` path does not
+ *    cross at all. This list being explicit is what caught that.
+ *  - `name`, `kind`, `execArgs` — read by the planner and the metadata
+ *    renderers, all of which have run by the time a stage exists. `appId` was
+ *    on this line and MOVED: the Flatpak packer needs it at pack time twice
+ *    over — it is the manifest's `id` and the ref `flatpak build-bundle`
+ *    exports — and neither is derivable from the payload, because the desktop
+ *    entry that carries the id is only staged for `kind: 'app'`.
+ *  - `arch` — carried by the manifest's `target`, which is also the value a
+ *    mismatched stage is refused on, so it lives in exactly one place.
+ *  - `mimeTypes` — phase 1 renders the shared-mime-info document into the
+ *    staged tree, and the one pack-time reader asks whether that FILE is in the
+ *    payload (`readPayloadFacts#hasMimeTypes`), which is the same question one
+ *    host later. Carrying the declarations would put the answer in two places.
+ */
+export interface PackSettings {
     /** Package name: the `bin/` entry, the deb `Package:`, the rpm `Name:`. */
     binaryName: string;
+    /** Reverse-DNS application id — the Flatpak manifest's `id` and the exported ref. */
+    appId: string;
     /** Upstream version, normalised for package managers. */
     version: string;
     /** Package revision within one upstream version (deb revision / rpm release). */
@@ -74,25 +210,62 @@ export interface ShipSettings {
     description: string[];
     /** SPDX identifier of the project licence. */
     license: string;
-    /** Absolute path to the licence file, when one was found. */
-    licenseFile?: string;
     homepage?: string;
     /** deb `Section:`. */
     section: string;
     /** rpm `Group:`. */
     group: string;
-    /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
-    kind: 'app' | 'cli';
     /** Extra runtime dependencies per format, appended to the derived set. */
-    extraDepends: {
-        deb: string[];
-        rpm: string[];
-    };
+    extraDepends: Record<DistroFormatId, string[]>;
     /** Project-supplied GI-namespace → package rows, filling gaps in the built-in table. */
-    typelibPackages: Record<string, {
-        deb: string;
-        rpm: string;
-    }>;
+    typelibPackages: Record<string, Record<DistroFormatId, string>>;
+    /** Minimum GJS the emitted dependency asks for. */
+    minGjsVersion: string;
+    /** The Flatpak manifest's non-payload half, fully defaulted at stage time. */
+    flatpak: ShipFlatpakSettings;
+}
+/**
+ * What the generated Flatpak manifest says about everything that is not the payload.
+ *
+ * Resolved — defaults applied — while the project is still in reach, because
+ * the defaults depend on `kind` and on `gjsify.flatpak`/`gjsify.ship.flatpak`,
+ * and the finishing host has neither.
+ *
+ * There is deliberately no `modules` / `extraModules` here. Under `ship` the
+ * module list IS the staged payload (ADR 0024 § 2: "a target that needs an
+ * extra file gets an overlay, never a branch in the staging code"), and an
+ * escape hatch that injects arbitrary build modules would put a second staging
+ * model back in the tree — which is the one thing § 8 gates the whole migration
+ * on. A project that genuinely needs to BUILD something inside the sandbox
+ * still has `gjsify flatpak init` + `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakSettings {
+    /** Runtime id, e.g. `org.gnome.Platform`. */
+    runtime: string;
+    /** Runtime/SDK version, e.g. `50`. */
+    runtimeVersion: string;
+    /** SDK id, e.g. `org.gnome.Sdk`. */
+    sdk: string;
+    /** The branch the app is exported under — the last segment of `app/<id>/<arch>/<branch>`. */
+    branch: string;
+    sdkExtensions: string[];
+    /** Path components prepended to `PATH` inside the build sandbox. */
+    appendPath: string[];
+    /** Capabilities the finished app is granted. */
+    finishArgs: string[];
+    /** Cleanup globs applied to `/app` after the module has run. */
+    cleanup: string[];
+}
+/** The resolved, fully defaulted configuration for one `gjsify ship` run. */
+export interface ShipSettings extends PackSettings {
+    /** Absolute path to the project being shipped. */
+    projectDir: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Absolute path to the licence file, when one was found. */
+    licenseFile?: string;
+    /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
+    kind: 'app' | 'cli';
     /** Absolute path to the built bundle that `bin/<binaryName>` executes. */
     bundlePath: string;
     /** Absolute path of the directory staged wholesale into `lib/<binaryName>/`. */
@@ -101,6 +274,11 @@ export interface ShipSettings {
     iconFiles: string[];
     /** Absolute paths of `*.gschema.xml` files to install. */
     schemaFiles: string[];
+    /**
+     * File types this package defines system-wide (shared-mime-info). Empty for a package that only
+     * HANDLES existing types — that needs no document of its own.
+     */
+    mimeTypes: ShipMimeType[];
     /**
      * Typelibs + shared libraries the package carries itself (`gjsify.ship.bundledTypelibs`).
      *
@@ -128,6 +306,4 @@ export interface ShipSettings {
     outDir: string;
     /** Target architecture in `process.arch` spelling. */
     arch: string;
-    /** Minimum GJS the emitted dependency asks for. */
-    minGjsVersion: string;
 }

package/lib/utils/ship/types.js

@@ -7,4 +7,9 @@
 // (`refs/gtkx`, MPL-2.0, reimplemented not copied) expresses the same
 // distinction as `if (target === 'deb')` inside its stager, and pays for it:
 // adding a fifth target there means editing six files.
+//
+// ADR 0024 § A2 splits the command in two — `--stage` assembles anywhere,
+// `--from-stage` packs on the host that owns the format — and that split shows
+// up here as the {@link PackSettings} / {@link ShipSettings} pair. Read the
+// comment on {@link PackSettings} before adding a field to either.
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.42.0",
+    "version": "0.44.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,21 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.42.0",
-        "@gjsify/create-app": "^0.42.0",
-        "@gjsify/node-globals": "^0.42.0",
-        "@gjsify/node-polyfills": "^0.42.0",
-        "@gjsify/npm-registry": "^0.42.0",
-        "@gjsify/resolve-npm": "^0.42.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.42.0",
-        "@gjsify/vite-plugin-blueprint": "^0.42.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.42.0",
-        "@gjsify/semver": "^0.42.0",
-        "@gjsify/tar": "^0.42.0",
-        "@gjsify/tsc": "^0.42.0",
-        "@gjsify/utils": "^0.42.0",
-        "@gjsify/web-polyfills": "^0.42.0",
-        "@gjsify/workspace": "^0.42.0",
+        "@gjsify/buffer": "^0.44.0",
+        "@gjsify/create-app": "^0.44.0",
+        "@gjsify/node-globals": "^0.44.0",
+        "@gjsify/node-polyfills": "^0.44.0",
+        "@gjsify/npm-registry": "^0.44.0",
+        "@gjsify/resolve-npm": "^0.44.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.44.0",
+        "@gjsify/vite-plugin-blueprint": "^0.44.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.44.0",
+        "@gjsify/semver": "^0.44.0",
+        "@gjsify/tar": "^0.44.0",
+        "@gjsify/tsc": "^0.44.0",
+        "@gjsify/utils": "^0.44.0",
+        "@gjsify/web-polyfills": "^0.44.0",
+        "@gjsify/workspace": "^0.44.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -165,13 +165,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.42.0",
+        "@gjsify/unit": "^0.44.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.42.0",
-        "@gjsify/rolldown-native": "^0.42.0"
+        "@gjsify/oxfmt-native": "^0.44.0",
+        "@gjsify/rolldown-native": "^0.44.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {