@gjsify/cli 0.42.0 → 0.43.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;
@@ -49,17 +64,61 @@ 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.
+ *  - `appId`, `name`, `kind`, `execArgs` — read by the planner and the metadata
+ *    renderers, all of which have run by the time a stage exists.
+ *  - `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;
     /** Upstream version, normalised for package managers. */
@@ -74,15 +133,11 @@ 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[];
@@ -93,6 +148,21 @@ export interface ShipSettings {
         deb: string;
         rpm: string;
     }>;
+    /** Minimum GJS the emitted dependency asks for. */
+    minGjsVersion: 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;
+    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
+    appId: 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 +171,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 +203,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.43.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.43.0",
+        "@gjsify/create-app": "^0.43.0",
+        "@gjsify/node-globals": "^0.43.0",
+        "@gjsify/node-polyfills": "^0.43.0",
+        "@gjsify/npm-registry": "^0.43.0",
+        "@gjsify/resolve-npm": "^0.43.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.43.0",
+        "@gjsify/vite-plugin-blueprint": "^0.43.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.43.0",
+        "@gjsify/semver": "^0.43.0",
+        "@gjsify/tar": "^0.43.0",
+        "@gjsify/tsc": "^0.43.0",
+        "@gjsify/utils": "^0.43.0",
+        "@gjsify/web-polyfills": "^0.43.0",
+        "@gjsify/workspace": "^0.43.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.43.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.43.0",
+        "@gjsify/rolldown-native": "^0.43.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {