@gjsify/cli 0.43.0 → 0.45.0

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

@@ -1,5 +1,5 @@
 import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock } from '../../types/config-data.js';
-import type { ShipSettings } from './types.js';
+import type { HostOs, ShipSettings } from './types.js';
 /** The subset of `package.json` the resolver reads. */
 export interface ShipPackageManifest {
     name?: string;
@@ -42,11 +42,29 @@ export interface SettingsInput {
     ship: ConfigDataShip;
     /** Metadata fallback — `gjsify.flatpak` already carries these fields for many projects. */
     flatpak: ConfigDataFlatpak;
+    /**
+     * What the command line decided before any config was read.
+     *
+     * `layoutOs` is REQUIRED, unlike its two neighbours, and the asymmetry is the
+     * point: `outDir` and `arch` have derived defaults that are correct when
+     * nobody says anything, while the layout is chosen by `gjsify ship <os>` (or
+     * by the host) before this function is reached. Making it optional would put
+     * a fourth default for it in here, and a second place that decides the layout
+     * is how the manifest's `target.os` and the staged paths come apart.
+     */
     cli: {
         outDir?: string;
         arch?: string;
+        layoutOs: HostOs;
     };
     discovered: DiscoveredPayload;
+    /**
+     * `gjsify.app` as DECLARED — `undefined` when the project declares nothing.
+     *
+     * Deliberately the raw config value and not `Config.forBuild`'s resolved one:
+     * see where it is defaulted below.
+     */
+    app?: string;
 }
 export interface ResolvedSettings {
     settings: ShipSettings;

package/lib/utils/ship/settings.js

@@ -11,7 +11,8 @@
 // indistinguishable from a value the user typed and would clobber the config.
 import { validateMimeTypes } from './mime.js';
 import { basename } from 'node:path';
-import { DEFAULT_GJS_FLOOR } from './depends.js';
+import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR } from './depends.js';
+import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
 /** Freedesktop main category → deb `Section:` / rpm `Group:`. First match wins. */
 const CATEGORY_SECTIONS = [
@@ -48,6 +49,14 @@ export function resolveShipSettings(input) {
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
     const kind = metadata.kind ?? 'app';
+    // `gjsify.app`, defaulted HERE to `'gjs'` rather than taken from
+    // `Config.forBuild`'s resolution, which falls back to the HOST runtime. That
+    // fallback is right for a build (`gjsify build` under Node should produce a
+    // Node bundle by default) and catastrophic for a package: running this
+    // command under Node would silently turn every undeclared GJS project into
+    // one whose launcher execs `node`. An undeclared target is the common case
+    // for a GJS app, and it means GJS.
+    const app = input.app === 'node' ? 'node' : 'gjs';
     const rawVersion = ship.version ?? pkg.version;
     if (!rawVersion) {
         throw new Error('gjsify ship: no version — set `version` in package.json or `gjsify.ship.version`.');
@@ -71,6 +80,11 @@ export function resolveShipSettings(input) {
         warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores. ` +
             'Point `gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
     }
+    // Resolved here rather than in the packer, because the packer may run on a
+    // host with no `package.json` at all (ADR 0024 § A2) — and because the
+    // finish-args default depends on `kind`, which is a project fact.
+    const flatpakSettings = resolveShipFlatpakSettings({ ship, flatpak, kind });
+    warnings.push(...flatpakSettings.warnings);
     const settings = {
         projectDir: input.projectDir,
         appId,
@@ -100,7 +114,11 @@ export function resolveShipSettings(input) {
         execArgs: ship.execArgs ?? [],
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
+        app,
+        layoutOs: input.cli.layoutOs,
         minGjsVersion: ship.minGjsVersion ?? DEFAULT_GJS_FLOOR,
+        minNodeVersion: ship.minNodeVersion ?? DEFAULT_NODE_FLOOR,
+        flatpak: flatpakSettings.settings,
     };
     return { settings, metadata, warnings };
 }

package/lib/utils/ship/share-dirs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Each entry is a directory the freedesktop/GNOME stack looks in BY NAME. None of
+ * them is ours to choose: `bindtextdomain` reads `share/locale/<lang>/LC_MESSAGES`,
+ * `glib-compile-schemas` compiles `share/glib-2.0/schemas`, and the icon theme
+ * spec fixes `share/icons/hicolor`. That is also why this is a closed set rather
+ * than a convention — a typo in any of them installs a file nothing ever reads.
+ */
+export declare const SHARE: {
+    /** freedesktop desktop entries. */
+    readonly applications: "share/applications";
+    /** The hicolor icon theme, whose cache `gtk-update-icon-cache` builds. */
+    readonly icons: "share/icons/hicolor";
+    /** GSettings schema sources, compiled into `gschemas.compiled` at install. */
+    readonly schemas: "share/glib-2.0/schemas";
+    /** shared-mime-info documents, folded into the mime cache at install. */
+    readonly mime: "share/mime/packages";
+    /** AppStream components. */
+    readonly metainfo: "share/metainfo";
+    /** Compiled gettext catalogues, read directly — no install step. */
+    readonly locale: "share/locale";
+};
+/** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
+export declare function isUnder(path: string, dir: string): boolean;

package/lib/utils/ship/share-dirs.js

@@ -0,0 +1,46 @@
+// The `share/` subdirectories a payload installs into — ONE definition.
+//
+// WHY THIS FILE EXISTS, and it is a repair rather than a tidy-up. Four call
+// sites answer questions about the same directories and every one of them spelled
+// them out again: `plan.ts` stages a file there, `readPayloadFacts` asks whether
+// the payload put anything there, `cacheRefreshCommands` emits the install step
+// that makes it WORK, and `linuxInstallDependent` names the ones a non-Linux
+// layout carries without that step. `share/glib-2.0/schemas` alone existed as
+// five independent string literals across the tree.
+//
+// A comment claiming they "cannot drift" was measured FALSE: pointing one rule in
+// `linuxInstallDependent` at a directory that matches nothing silently dropped a
+// file from the warning `gjsify ship` prints, and the whole suite stayed green at
+// exit 0. The prose was the mechanism, which is to say there was none. Importing
+// one constant makes the compiler the mechanism instead.
+//
+// PREFIX-RELATIVE and POSIX-separated, like every path in the plan. The layout
+// map (`layout.ts`) is what turns these into `Contents/Resources/share/…` or a
+// Windows program directory's `share\`; nothing here knows about that, and
+// nothing here is absolute — `scripts.ts` prepends the format's install prefix,
+// which is `/usr` for a `.deb` and `/app` for a Flatpak.
+/**
+ * Each entry is a directory the freedesktop/GNOME stack looks in BY NAME. None of
+ * them is ours to choose: `bindtextdomain` reads `share/locale/<lang>/LC_MESSAGES`,
+ * `glib-compile-schemas` compiles `share/glib-2.0/schemas`, and the icon theme
+ * spec fixes `share/icons/hicolor`. That is also why this is a closed set rather
+ * than a convention — a typo in any of them installs a file nothing ever reads.
+ */
+export const SHARE = {
+    /** freedesktop desktop entries. */
+    applications: 'share/applications',
+    /** The hicolor icon theme, whose cache `gtk-update-icon-cache` builds. */
+    icons: 'share/icons/hicolor',
+    /** GSettings schema sources, compiled into `gschemas.compiled` at install. */
+    schemas: 'share/glib-2.0/schemas',
+    /** shared-mime-info documents, folded into the mime cache at install. */
+    mime: 'share/mime/packages',
+    /** AppStream components. */
+    metainfo: 'share/metainfo',
+    /** Compiled gettext catalogues, read directly — no install step. */
+    locale: 'share/locale',
+};
+/** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
+export function isUnder(path, dir) {
+    return path.startsWith(`${dir}/`);
+}

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

@@ -0,0 +1,195 @@
+import { type PayloadEntry } from './payload.js';
+import type { HostOs } from './types.js';
+/**
+ * Everything that is per-OS about making a signature, as data.
+ *
+ * The same shape argument `FormatDescriptor` makes one directory over: a second
+ * OS is a row, not a branch. It is a separate table from `FORMATS` on purpose —
+ * § A14 measured that a format declares where it can be PACKED and never what it
+ * can be signed with, and darwin has two format rows that must not be able to
+ * disagree about their signature.
+ */
+export interface SignerDescriptor {
+    /** The layout whose payload this signer signs. */
+    layoutOs: HostOs;
+    /** The command that makes the signature. */
+    tool: string;
+    /** OSes whose tooling can run {@link tool}. */
+    signOn: readonly HostOs[];
+    /** Where {@link tool} comes from, in this signer's own words. */
+    installHint: string;
+    /**
+     * Which payload files carry a signature on this OS.
+     *
+     * `classifyBinary`'s vocabulary, so the predicate is the magic number and
+     * not a filename pattern: a darwin closure names its images `.dylib`,
+     * `.so`, `.node` and nothing at all (the interpreter), and a suffix list
+     * would sign three of those four.
+     */
+    signs: 'macho' | 'pe';
+    /** argv after {@link tool}, for ONE file. */
+    args: (identity: string, file: string) => readonly string[];
+    /** The config key a project spells its default identity under. */
+    configKey: string;
+    /** What a signature from this signer does NOT yet cover — printed once per run. */
+    gap: string;
+}
+/**
+ * The signers, keyed by the LAYOUT they sign — never by the host they run on.
+ *
+ * Linux is deliberately absent rather than present-and-empty. A `.deb` and an
+ * `.rpm` carry no per-file signature: the artifact is signed as a whole, by the
+ * repository that serves it (`debsigs`, `rpmsign`), with a key that belongs to
+ * that repository and not to this build. A row here would make `--sign` on Linux
+ * look like it did something.
+ */
+export declare const SIGNERS: Partial<Record<HostOs, SignerDescriptor>>;
+/** `gjsify.ship.sign` as declared — one entry per {@link HostOs}. */
+export type SignConfig = Partial<Record<HostOs, {
+    identity?: string;
+}>>;
+/**
+ * What this run will do about signatures.
+ *
+ * A union rather than an optional string, because the three states need three
+ * different words and collapsing them is exactly what § A13 warns about: "no
+ * signer for this layout" is silence, "a slot exists and is empty" is a printed
+ * skip, and "here is an identity" is work.
+ */
+export type SignPlan = {
+    kind: 'unsupported';
+} | {
+    kind: 'skip';
+    message: string;
+} | {
+    kind: 'sign';
+    identity: string;
+    signer: SignerDescriptor;
+    source: 'flag' | 'config';
+};
+/**
+ * Resolve the identity for this run, or say why there is none.
+ *
+ * `flag` beats `config` and neither is a yargs `default:` — the uniform
+ * precedence `resolveShipSettings` documents. `config` is `undefined` on the
+ * `--from-stage` path and that is not an omission: § A14 amends § A1 to *a
+ * format declares where it can be packed; the RUN declares what it can sign
+ * with*, and the finishing host has no project to read a default out of.
+ */
+export declare function resolveSignPlan(input: {
+    /** `--sign` as typed. `''` is a value: it is `[ -z "$SIGN" ]` (§ A13). */
+    flag?: string;
+    /** `gjsify.ship.sign`, when a project is in reach. */
+    config?: SignConfig;
+    layoutOs: HostOs;
+}): SignPlan;
+/**
+ * Refuse a signing run this host cannot make, and say which half is missing.
+ *
+ * Two checks and not one, for the same reason `assertCanPack` splits them: the
+ * wrong OS needs another machine, an absent tool needs a package. Both are
+ * knowable before anything is packed.
+ */
+export declare function assertHostCanSign(signer: SignerDescriptor): void;
+export interface SignPayloadInput {
+    /** What `readStage` returned — the PRE-sign tree, already held against the manifest. */
+    payload: readonly PayloadEntry[];
+    identity: string;
+    signer: SignerDescriptor;
+    /** A scratch directory this function owns and WIPES. Never the arriving stage. */
+    workDir: string;
+    /** Print every invocation. */
+    verbose: boolean;
+    log: (line: string) => void;
+}
+/**
+ * Re-sign every signable image in the payload, and hand back the new bytes.
+ *
+ * The signature is made on FILES because that is the only interface `codesign`
+ * and `signtool` have, so the payload is materialised into `workDir`, signed
+ * there, and read back. `workDir` is a scratch directory rather than the stage:
+ * writing into an arriving stage would make the next `--from-stage` run of the
+ * same tree fail `readStage`'s size comparison (measured — see the header), and
+ * `writeStage`'s wipe would delete the payload it was about to pack.
+ *
+ * THE FILE SET MAY NOT CHANGE, and that is asserted rather than assumed. Both
+ * tools rewrite an image in place, so a payload that gained or lost a path here
+ * means something else ran — a bundle seal writing `_CodeSignature/`, say, whose
+ * files would then be dropped on the way back into the payload without anyone
+ * noticing.
+ */
+export declare function signPayload(input: SignPayloadInput): Promise<PayloadEntry[]>;
+/**
+ * What this run will do about notarisation.
+ *
+ * A SECOND credential and an unrelated one (§ A15): `--sign` names an identity
+ * the signing machine holds, `--notarize` names an account credential. They are
+ * two flags because they are two inputs, and the reference keeps them in two
+ * scripts.
+ */
+export interface NotaryDescriptor {
+    layoutOs: HostOs;
+    tool: string;
+    notarizeOn: readonly HostOs[];
+    installHint: string;
+    /**
+     * argv after {@link tool}.
+     *
+     * `credential` is threaded straight into the flag the command consumes, and
+     * that is the whole design of {@link resolveNotaryPlan}'s guard. § A15
+     * measured the trap: `refs/node/tools/osx-notarize.sh` guards on three
+     * environment variables it never uses and then submits with a
+     * `--keychain-profile` nothing checked, so the skip is reachable from an
+     * input the next line does not read. Here the guarded value IS the argument.
+     *
+     * ⚠️ `--keychain-profile` is the ONLY shape § A15 found evidenced, and the
+     * App Store Connect API-key form (`--key`/`--key-id`/`--issuer`) is NOT
+     * implemented because nothing measured it. UNVERIFIED, and marked as such:
+     * no run in this repository has ever invoked `notarytool` — notarisation
+     * needs an Apple account, which ad-hoc signing deliberately does not.
+     */
+    args: (credential: string, artifact: string) => readonly string[];
+}
+export declare const NOTARIES: Partial<Record<HostOs, NotaryDescriptor>>;
+export type NotaryPlan = {
+    kind: 'unsupported';
+} | {
+    kind: 'skip';
+    message: string;
+} | {
+    kind: 'notarize';
+    credential: string;
+    notary: NotaryDescriptor;
+};
+/**
+ * Resolve the notarisation credential, or say why there is none.
+ *
+ * Deliberately NOT defaultable from the project. An identity is a name a machine
+ * may hold for years and is worth writing into a repository; a notarisation
+ * credential is a per-run account credential, and a config key for it is an
+ * invitation to commit one.
+ */
+export declare function resolveNotaryPlan(input: {
+    flag?: string;
+    layoutOs: HostOs;
+    sign: SignPlan;
+}): NotaryPlan;
+/**
+ * Submit one written artifact for notarisation.
+ *
+ * ⚠️ UNVERIFIED END TO END. Everything up to the `spawnToCompletion` is covered
+ * — the argv by `signing.spec.ts`, the guard and both refusals by
+ * `tests/e2e/ship-signing` — and the invocation itself has never run: it needs
+ * an Apple Developer account, and § A17's whole point is that M6's proof does
+ * not. Whoever first runs this on a real credential should record what it did
+ * beside § A15, which is where the question was left open.
+ */
+export declare function notarizeArtifact(input: {
+    plan: Extract<NotaryPlan, {
+        kind: 'notarize';
+    }>;
+    /** The artifact to submit. Must be a FILE — notarytool takes an archive or an installer. */
+    artifact: string;
+    verbose: boolean;
+    log: (line: string) => void;
+}): Promise<void>;