@gjsify/cli 0.44.0 → 0.46.0

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

@@ -1,9 +1,40 @@
-import type { FormatDescriptor, FormatId } from './types.js';
+import { type Layout } from './layout.js';
+import type { FormatDescriptor, FormatId, HostOs, PackSettings, RequiredTools } from './types.js';
+/**
+ * The directory `windows-dir` produces, and the top level `windows-dir-zip` puts
+ * its entries under.
+ *
+ * ONE function with TWO readers, deliberately: the zip has to expand to the same
+ * directory the other row writes, and two literals would be two names a user is
+ * asked to believe are one.
+ */
+export declare function windowsProgramDirName(settings: PackSettings): string;
+/**
+ * The tools ONE host needs for a format, whichever shape the row declares.
+ *
+ * The one place the union in {@link RequiredTools} is opened, so a caller cannot
+ * read the map and get `undefined.filter` or read the array on a row that has a
+ * map. An OS the map does not name answers `[]` — not because nothing is needed
+ * there, but because {@link assertHostCanFinish} has already refused that host by
+ * the time this is asked, and inventing a tool list for a host that cannot finish
+ * the format would answer a question nobody may ask.
+ */
+export declare function requiredToolsOn(tools: RequiredTools, host: string): readonly string[];
+/**
+ * Every tool any host could need for a format — the question `installHint`'s
+ * presence is gated on.
+ *
+ * Deliberately NOT what {@link assertToolsInstalled} checks. "Does this row need a
+ * hint at all" is a property of the ROW; "is this tool here" is a question about
+ * one machine, and answering the first with the second would let a row declare a
+ * Windows-only tool and no hint, because the gate happened to run on Linux.
+ */
+export declare function allRequiredTools(tools: RequiredTools): readonly string[];
 export declare const FORMATS: Record<FormatId, FormatDescriptor>;
 export declare const FORMAT_IDS: FormatId[];
 /**
- * What `gjsify ship` builds when nothing said otherwise — every format that
- * needs no tool and no particular host.
+ * What `gjsify ship <os>` builds when nothing said otherwise — every format that
+ * wraps THAT OS's layout and needs no tool and no particular host.
  *
  * A SECOND derivation from the same table, and it has to be one: `FORMAT_IDS`
  * used to be both "every format that exists" and "every format to build by
@@ -14,8 +45,22 @@ export declare const FORMAT_IDS: FormatId[];
  * packs `@gjsify/cli` itself on a bare ubuntu runner. A host-bound format is
  * opt-in through `--target` or `gjsify.ship.targets`; `--help` still lists all
  * of them.
+ *
+ * `layoutOs` is the SECOND criterion, and it is what the layout axis needed: a
+ * `.app` and its zip and a Windows program directory are all `finishOn: 'any'`,
+ * so on the one criterion a bare `gjsify ship` on Linux would start emitting
+ * five artifacts (ADR 0024 issue #1354, open question 3). Answered with § A2's
+ * positional rather than instead of it — the positional picks the layout, this
+ * picks the formats that wrap it, and `gjsify ship` on Linux keeps emitting
+ * exactly `deb` and `rpm`.
+ *
+ * An EMPTY answer is legal and is what darwin and windows give today: their
+ * layouts assemble (`--stage`) and no format wraps them yet. `assemble` refuses
+ * a pack with nothing to pack rather than exiting 0 having produced no artifact.
  */
-export declare const DEFAULT_FORMAT_IDS: FormatId[];
+export declare function defaultFormatIds(layoutOs: HostOs): FormatId[];
+/** Every format that wraps one OS's layout, tool-bound ones included. */
+export declare function formatIdsFor(layoutOs: HostOs): FormatId[];
 /**
  * Refuse a format this host cannot finish, BEFORE anything is built or written.
  *
@@ -35,6 +80,62 @@ export declare function assertHostCanFinish(format: FormatDescriptor, host?: str
  * a build: `gjsify ship` runs the project's `build` script first, and finding
  * out afterwards that `flatpak-builder` is absent costs the whole build.
  */
-export declare function assertToolsInstalled(format: FormatDescriptor, present?: (cmd: string) => boolean): void;
-/** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
-export declare function resolveFormats(raw: readonly string[]): FormatDescriptor[];
+export declare function assertToolsInstalled(format: FormatDescriptor, present?: (cmd: string) => boolean, host?: string): void;
+/**
+ * Parse an explicit `--target deb,rpm` into a sorted, deduplicated descriptor list.
+ *
+ * A format belonging to another layout is an ERROR here, not a filter:
+ * `gjsify ship darwin --target deb` is a mistake worth naming, and dropping it
+ * silently would stage the darwin layout, pack nothing and exit 0 — the shape
+ * the empty-list refusal above already exists to prevent, arriving through a
+ * different door.
+ *
+ * The FLAG is what makes that the right answer, and it is the whole difference
+ * from {@link configuredFormats}: a value typed on this command line is a claim
+ * about THIS run.
+ */
+export declare function resolveFormats(raw: readonly string[], layout: Layout): FormatDescriptor[];
+/**
+ * The same names from `gjsify.ship.targets`, FILTERED to the current layout.
+ *
+ * A configured list is a project-level DEFAULT — "when I ship this, build these"
+ * — written once and read by every run, so it cannot be a claim about a layout
+ * the author had not heard of when they wrote it. Refusing it the way
+ * {@link resolveFormats} refuses a flag makes the new positional unusable in
+ * every project that has the key, and this repository is the proof: with
+ * `targets: ["deb", "rpm"]` in `packages/infra/cli/package.json`,
+ * `gjsify ship darwin --stage` exited 1 telling the author to run
+ * `gjsify ship darwin --stage`. There was no `--target` value that got a darwin
+ * stage out of such a project at all.
+ *
+ * Filtering is safe HERE and only here, because an empty result is not a silent
+ * success: `assemble` refuses a PACK with nothing to pack, and a `--stage` run
+ * legitimately wants exactly this — assemble the layout, wrap nothing.
+ */
+export declare function configuredFormats(raw: readonly string[], layout: Layout): {
+    formats: FormatDescriptor[];
+    dropped: FormatId[];
+};
+/**
+ * Can this format's container hold a notarisation ticket?
+ *
+ * A SWITCH WITH A `never` GUARD and not a field, deliberately — the difference
+ * from `FormatDescriptor.host` is who owns the fact. Where a format can be PACKED
+ * is a property of this project's toolchain and belongs on the descriptor; whether
+ * `stapler` will write a ticket into it is Apple's list, unchanged by anything
+ * here, and six of the nine rows are only "no" because notarisation is a macOS
+ * concept they have nothing to do with. Putting it in a `switch` keeps the answer
+ * beside its citation and still makes a tenth format a compile error.
+ *
+ * `stapler(1)`: *"stapler works only with UDIF disk images, signed \"flat\"
+ * installer packages, and certain code-signed executable bundles such as
+ * \".app\"."* And Apple's notarisation guide for the exception that decides the
+ * zip: *"While you can notarize a ZIP archive, you can't staple to it directly.
+ * Instead, run stapler against each item that you added to the archive. Then
+ * create a new ZIP file containing the stapled items for distribution."*
+ *
+ * `macos-app` is `true` here even though `notarytool` cannot SUBMIT a directory:
+ * the two questions are separate, and a `.app` is precisely the item Apple's
+ * remedy above tells you to staple after submitting the archive around it.
+ */
+export declare function canCarryTicket(id: FormatId): boolean;