@gjsify/cli 0.39.0 → 0.41.0

package/lib/commands/foreach.js

@@ -13,9 +13,15 @@ import { readFileSync, readdirSync } from 'node:fs';
 import { cpus } from 'node:os';
 import { affectedClosure, buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { cliRuntimeClosure } from '../utils/cli-runtime-closure.js';
 import { prefixLines } from '../utils/prefixed-output.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
-import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+// The ONE runner-selection rule, shared rather than re-derived. This file used to
+// carry its own copy; `workspace.ts` grew the bootstrap-CLI branch and the copy
+// here did not, so a `gjsify foreach` reached from a cold-tree bootstrap would
+// have delegated to npm and lost the shim one level down — silently, and only on
+// the OS legs that bootstrap cold. `onboard.ts` already imports it from here.
+import { detectPackageManager } from './workspace.js';
 // Every child spawned by spawnPrefixed registers here so fail-fast can
 // terminate the whole in-flight set instead of waiting on it. On CI a
 // single failed package used to leave foreach awaiting its still-running
@@ -425,20 +431,44 @@ export const foreachCommand = {
                 targets: selected.map((w) => w.name),
             })
             : undefined;
+        // The serial prefix: every child of this command BOOTS the CLI, so a
+        // package the CLI imports must not be written while siblings are starting
+        // (the torn `lib/esm` in `utils/cli-runtime-closure.ts`'s header). Building
+        // that closure first — alone, in the order the caller already sorted — is a
+        // REORDERING, not extra work: the prefix is removed from the parallel set,
+        // so the cost is only the parallelism given up over those few packages.
+        //
+        // Applied to every PARALLEL invocation, not only to `build`. Which scripts
+        // rewrite an output tree is not knowable from a script NAME — `build`,
+        // `build:types`, a package's own `dist` step and `clear` all do — and
+        // gating on the literal string "build" would be the hand-written list this
+        // closure exists to replace. A serial run needs no prefix at all: nothing
+        // else is in flight to read what it writes.
+        const prefixNames = args.parallel === true ? cliRuntimeClosure(allWorkspaces) : new Set();
+        const prefix = prefixNames.size > 0 ? selected.filter((ws) => prefixNames.has(ws.name)) : [];
+        const sweep = prefix.length > 0 ? selected.filter((ws) => !prefixNames.has(ws.name)) : selected;
         try {
+            if (prefix.length > 0) {
+                console.error(`[gjsify foreach] serial prefix: ${prefix.length} package(s) the running CLI imports — ` +
+                    `${prefix.map((ws) => ws.name).join(', ')}`);
+                for (const ws of prefix) {
+                    console.error(`[gjsify foreach] start ${ws.name} (serial prefix)`);
+                    await runOne(ws, finalCmd, cmdArgs, /* prefixOutput */ true, verbose, exec, cache);
+                }
+            }
             if (args.parallel && !args.topological && !args['topological-dev']) {
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runParallel(selected, finalCmd, cmdArgs, jobs, verbose, exec, cache);
+                await runParallel(sweep, finalCmd, cmdArgs, jobs, verbose, exec, cache);
             }
             else if (args.parallel) {
                 // Topological + parallel: each workspace starts as soon as its
                 // deps (in the selected set) have finished. Yarn calls this
                 // "topological order with concurrency"; we cap at --jobs.
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runTopologicalParallel(selected, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec, cache);
+                await runTopologicalParallel(sweep, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec, cache);
             }
             else {
-                await runSequential(selected, finalCmd, cmdArgs, verbose, exec, cache);
+                await runSequential(sweep, finalCmd, cmdArgs, verbose, exec, cache);
             }
         }
         catch (err) {
@@ -703,22 +733,6 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec, cache) {
     if (cache && before)
         cache.storeAfterSuccess(ws, before);
 }
-function detectPackageManager() {
-    // Under GJS there is no Node — neither `npm` nor `yarn` can run scripts, so
-    // the runner is `gjsify` itself via the GJS shim on PATH
-    // (`ensureGjsifyShimOnPath`). Makes node-free `gjsify foreach` work.
-    if (isGjs())
-        return 'gjsify';
-    // `npm_config_user_agent` is set by npm/yarn/pnpm — first token is
-    // `<name>/<version>`. Reuse it so `gjsify foreach build` invoked
-    // through `yarn run` keeps using yarn, etc.
-    const ua = process.env.npm_config_user_agent ?? '';
-    if (ua.startsWith('yarn/'))
-        return 'yarn';
-    if (ua.startsWith('gjsify/'))
-        return 'gjsify';
-    return 'npm';
-}
 async function spawnPrefixed(cmd, args, cwd, prefix) {
     // `completion: 'exit'` — every path out of this command's handler ends in
     // `process.exit(…)` (see the handler's tail), which is what quits the GLib

package/lib/commands/index.d.ts

@@ -12,6 +12,7 @@ export * from './gresource.js';
 export * from './gettext.js';
 export * from './gsettings.js';
 export { flatpakCommand } from './flatpak/index.js';
+export * from './ship.js';
 export * from './dlx.js';
 export * from './install.js';
 export * from './foreach.js';
@@ -25,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';

package/lib/commands/index.js

@@ -12,6 +12,7 @@ export * from './gresource.js';
 export * from './gettext.js';
 export * from './gsettings.js';
 export { flatpakCommand } from './flatpak/index.js';
+export * from './ship.js';
 export * from './dlx.js';
 export * from './install.js';
 export * from './foreach.js';
@@ -25,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';

package/lib/commands/install.d.ts

@@ -7,6 +7,7 @@ interface InstallOptions {
     'save-peer'?: boolean;
     'save-optional'?: boolean;
     immutable?: boolean;
+    prune?: boolean;
     'refresh-lockfile'?: boolean;
     verbose: boolean;
     quiet?: boolean;

package/lib/commands/install.js

@@ -32,6 +32,8 @@ import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { pruneAfterInstall } from '../utils/prune-prefix.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -125,6 +127,11 @@ export const installCommand = {
         description: 'Install a REQUIRED dependency even when its os/cpu/libc excludes the target, instead of failing with EBADPLATFORM (npm config key `force`). Incompatible OPTIONAL dependencies stay skipped — npm ignores --force for those too, and a binary that cannot load is not worth downloading.',
         type: 'boolean',
         default: false,
+    })
+        .option('prune', {
+        description: 'After installing, remove packages an earlier install left behind that this host cannot use (foreign os/cpu/libc). Use --no-prune to disable. Skipped automatically under --immutable, and whenever --os/--cpu/--libc is given: an install must never delete against a target the user typed.',
+        type: 'boolean',
+        default: true,
     }),
     handler: async (args) => {
         // Must run before anything resolves — `--os/--cpu/--libc/--force` are npm
@@ -161,7 +168,7 @@ export const installCommand = {
                     console.warn(`gjsify install --global ignores --${flag}: global installs do not modify a project package.json.`);
                 }
             }
-            await installGlobalAndLink(args.packages, { verbose: args.verbose });
+            await installGlobalAndLink(args.packages, { verbose: args.verbose, prune: args.prune });
             return;
         }
         // Before the heavy install, so the skew is visible even if a later phase
@@ -170,6 +177,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
             return;
         }
@@ -217,6 +225,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
         }
         catch (err) {
@@ -1198,6 +1207,14 @@ async function installGlobalAndLink(specs, opts) {
             const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
             await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
         }
+        // Before the LINK on purpose: `linkGlobalBins`' launchers bake the resolved
+        // prebuild directories into GI_TYPELIB_PATH/LD_LIBRARY_PATH, and must not name
+        // a directory this pass is about to delete.
+        if (opts.prune !== false) {
+            pruneAfterInstall(layout.prefix, resolveHostPlatform({ env: {} }), {
+                hint: 'gjsify prune -g --dry-run',
+            });
+        }
         const created = linkGlobalBins(packageNames, layout);
         reportLinkedBins(created, layout.binDir);
     }
@@ -1205,6 +1222,20 @@ async function installGlobalAndLink(specs, opts) {
         lock.release();
     }
 }
+/**
+ * The automatic pass for a PROJECT prefix.
+ *
+ * Hooked at the command level rather than inside `installPackages`, so `dlx`'s
+ * throwaway cache prefix — created, used once and dropped — pays nothing for it.
+ */
+function pruneProjectPrefix(args) {
+    if (args.prune === false)
+        return;
+    pruneAfterInstall(process.cwd(), resolveHostPlatform({ env: {} }), {
+        immutable: args.immutable === true,
+        hint: 'gjsify prune --dry-run',
+    });
+}
 function reportLinkedBins(created, binDir) {
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');

package/lib/commands/prune.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface PruneOptions {
+    global: boolean;
+    dryRun: boolean;
+    verbose: boolean;
+    os?: string;
+    cpu?: string;
+    libc?: string;
+}
+export declare const pruneCommand: Command<unknown, PruneOptions>;
+export {};

package/lib/commands/prune.js

@@ -0,0 +1,84 @@
+// `gjsify prune` — remove installed packages this target cannot use.
+//
+// The repair half of ADR 0025. `install`/`self-update` prune what they would not
+// have placed, but only going forward: a prefix that accreted foreign-platform
+// packages under an older CLI is only reachable by asking. That is this command,
+// and it is why it exists at all rather than the automatic pass alone.
+//
+// `--os/--cpu/--libc` are accepted here and deliberately NOT honoured by the
+// automatic pass: typed on `prune` they are a request ("show me what a darwin-arm64
+// host could not use"), while inherited by an install they would delete the host's
+// own packages. See `automaticPruneRefusal`.
+import { existsSync } from 'node:fs';
+import { acquireInstallLock } from '../utils/install-lock.js';
+import { defaultGlobalLayout } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { executePrune, formatPruneReport, planPrune } from '../utils/prune-prefix.js';
+export const pruneCommand = {
+    command: 'prune',
+    description: 'Remove installed packages this host cannot use (foreign os/cpu/libc). ' +
+        'Reads each package manifest — a package that declares no platform is never touched.',
+    builder: (yargs) => yargs
+        .option('global', {
+        description: 'Prune the user-global XDG prefix (the `install -g` target) instead of the project.',
+        type: 'boolean',
+        alias: 'g',
+        default: false,
+    })
+        .option('dry-run', {
+        description: 'Report what would be removed without touching the filesystem.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('verbose', {
+        description: 'List every package rather than the first few.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('os', {
+        description: 'Prune AS IF the host were this OS (linux, darwin, win32). Defaults to this host.',
+        type: 'string',
+    })
+        .option('cpu', {
+        description: 'Prune AS IF the host were this architecture (x64, arm64, …). Defaults to this host.',
+        type: 'string',
+    })
+        .option('libc', {
+        description: 'Prune AS IF the host used this libc (glibc, musl). Defaults to this host.',
+        type: 'string',
+    }),
+    handler: async (args) => {
+        const layout = args.global ? defaultGlobalLayout() : null;
+        const prefix = layout ? layout.prefix : process.cwd();
+        if (!existsSync(`${prefix}/node_modules`)) {
+            console.log(`gjsify prune: nothing installed at ${prefix}`);
+            return;
+        }
+        // The flags are read HERE rather than through the npm config keys, so the
+        // automatic pass — which refuses to act on an overridden target — cannot be
+        // reached by way of this command's own options.
+        const target = resolveHostPlatform({
+            env: {
+                ...(args.os ? { npm_config_os: args.os } : {}),
+                ...(args.cpu ? { npm_config_cpu: args.cpu } : {}),
+                ...(args.libc ? { npm_config_libc: args.libc } : {}),
+            },
+        });
+        // A prune racing an install's extract would delete a half-written tree. The
+        // lock is the same one every writer of this prefix takes (ADR 0001).
+        const lock = await acquireInstallLock(prefix, {});
+        let result;
+        try {
+            result = executePrune(planPrune({ prefix, target }), { dryRun: args.dryRun });
+        }
+        finally {
+            lock.release();
+        }
+        console.log(formatPruneReport(result, { dryRun: args.dryRun, verbose: args.verbose }));
+        // Removing nothing is a SUCCESS — idempotent housekeeping, unlike `uninstall`
+        // where naming a package that is not there is a mistake worth reporting. Only
+        // a removal the user asked for and did not get is a failure.
+        if (result.failed.length > 0)
+            return process.exit(1);
+    },
+};

package/lib/commands/self-update.d.ts

@@ -4,6 +4,7 @@ interface SelfUpdateOptions {
     force?: boolean;
     tag: string;
     skipDeps?: boolean;
+    prune?: boolean;
 }
 export declare const selfUpdateCommand: Command<unknown, SelfUpdateOptions>;
 /** Verdict of the post-install "did this change what runs?" check. */

package/lib/commands/self-update.js

@@ -25,7 +25,10 @@ import { dirname, join, posix, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
+import { classifyInstall } from '../utils/install-provenance.js';
 import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { pruneAfterInstall } from '../utils/prune-prefix.js';
 const PACKAGE_NAME = '@gjsify/cli';
 export const selfUpdateCommand = {
     command: 'self-update',
@@ -45,6 +48,11 @@ export const selfUpdateCommand = {
         description: 'npm dist-tag or pinned version to install (e.g. `latest`, `next`, `0.5.0`).',
         type: 'string',
         default: 'latest',
+    })
+        .option('prune', {
+        description: 'After updating, remove packages an earlier install left behind that this host cannot use (foreign os/cpu/libc). Use --no-prune to disable.',
+        type: 'boolean',
+        default: true,
     })
         .option('skip-deps', {
         description: 'Update only the @gjsify/cli bundle itself; do not pull its runtime dependencies ' +
@@ -60,6 +68,24 @@ export const selfUpdateCommand = {
         const currentVersion = readCurrentVersion();
         const installedAtPrefix = existsSync(installedPkgJson);
         console.log(`Current ${PACKAGE_NAME}: v${currentVersion ?? '(unknown)'}`);
+        // REFUSE, do not warn-and-continue, when something else owns this install.
+        //
+        // Everything below writes the user-global XDG prefix. Under a `.deb`,
+        // `.rpm` or Flatpak that produces a SECOND copy which shadows the one the
+        // package manager tracks — so the next `apt upgrade` reverts it, or the two
+        // diverge, and the user's report is "I updated and nothing changed". A
+        // clean refusal naming the right command is strictly more useful than a
+        // successful write to the wrong place; #1064 is the same lesson one layer
+        // down, where the write succeeded and PATH still resolved the old binary.
+        const provenance = classifyInstall({ selfDir: readSelfDir(), xdgPrefix: layout.prefix });
+        if (provenance.managedElsewhere) {
+            console.error(`\ngjsify self-update: this gjsify is managed by something else — ${provenance.evidence}.\n` +
+                `Updating it from here would write ${layout.prefix} and leave you running two installs.\n\n` +
+                `Update with: ${provenance.updateWith}\n`);
+            // `return process.exit()` — a bare `process.exit()` is DEFERRED under
+            // GJS and the handler would run on into the install it just refused.
+            return process.exit(1);
+        }
         if (!installedAtPrefix) {
             console.warn(`\nWarning: no @gjsify/cli install found under ${layout.prefix}.\n` +
                 `self-update only manages installs created by install.mjs or \`gjsify install -g\`.\n` +
@@ -157,6 +183,13 @@ export const selfUpdateCommand = {
         if (pullDeps) {
             await installGjsEnginePackages(layout.prefix, target, { verbose: false });
         }
+        // Same ordering reason as `install -g`: before the LINK, whose launchers bake
+        // the resolved prebuild directories into their env.
+        if (args.prune !== false) {
+            pruneAfterInstall(layout.prefix, resolveHostPlatform({ env: {} }), {
+                hint: 'gjsify prune -g --dry-run',
+            });
+        }
         const linked = linkGlobalBins([PACKAGE_NAME], layout);
         if (linked.length === 0) {
             console.warn('self-update: install completed but no bins were linked — package.json may be missing a `bin` field.');
@@ -246,6 +279,28 @@ export function verifyPathResolution(opts) {
  * `import.meta.url` (the bundle file under GJS, or `lib/index.js` under
  * Node) until it finds a package.json with `name === '@gjsify/cli'`.
  */
+/**
+ * The directory of the running CLI's own package — the input the provenance
+ * question is actually about.
+ *
+ * The same upward walk `readCurrentVersion()` does, and for the same reason: it
+ * works from `lib/index.js` under Node and from the published `dist/cli.gjs.mjs`
+ * bundle under GJS. Honours the same `GJSIFY_CLI_PACKAGE_JSON` escape hatch, so a
+ * test can place a synthetic install anywhere without a real one.
+ */
+function readSelfDir() {
+    const override = process.env.GJSIFY_CLI_PACKAGE_JSON;
+    if (override)
+        return dirname(resolve(override));
+    const here = fileURLToPath(import.meta.url);
+    let dir = dirname(resolve(here));
+    for (let i = 0; i < 8 && dir !== dirname(dir); i++) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        dir = dirname(dir);
+    }
+    return dirname(resolve(here));
+}
 function readCurrentVersion() {
     try {
         // Escape hatch for tests: point GJSIFY_CLI_PACKAGE_JSON at a synthetic

package/lib/commands/ship.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface ShipOptions {
+    target?: string[];
+    out?: string;
+    stage: boolean;
+    'skip-build': boolean;
+    arch?: string;
+    verbose: boolean;
+}
+export declare const shipCommand: Command<unknown, ShipOptions>;
+export {};

package/lib/commands/ship.js

@@ -0,0 +1,217 @@
+// `gjsify ship` — turn a built application into something a stranger can
+// install (ADR 0024).
+//
+// One payload, produced once, then wrapped per format. The command itself is
+// thin on purpose: every decision worth testing lives in `utils/ship/*` as a
+// pure function, and what is left here is filesystem work and printing.
+//
+// Scope today is Linux and `--app gjs`: no runtime is bundled, because GJS and
+// GTK come from the distribution and shipping ~100 MiB of them would be cargo
+// cult (ADR 0024 § 4). macOS and Windows layouts, and Flatpak as a target under
+// this command, are the later stages of the same ADR.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { Config } from '../config.js';
+import { renderDesktopEntry, renderMetainfoApp, renderMetainfoCli, validateAppMetadata, } from '../utils/app-metadata.js';
+import { readPackageJson } from '../utils/pkg-json.js';
+import { describeExit, spawnToCompletion } from '../utils/spawn.js';
+import { buildDeb } from '../utils/ship/deb.js';
+import { deriveDepends, warnAboutGjsFloor } from '../utils/ship/depends.js';
+import { discoverPayload } from '../utils/ship/discover.js';
+import { resolveFormats, FORMAT_IDS } from '../utils/ship/formats.js';
+import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
+import { buildTimestamp, isArchIndependent } from '../utils/ship/payload.js';
+import { planOverlay, planStage } from '../utils/ship/plan.js';
+import { renderLauncher } from '../utils/ship/launcher.js';
+import { buildRpm } from '../utils/ship/rpm.js';
+import { declaredBundlePath, resolveShipSettings } from '../utils/ship/settings.js';
+import { readStage, writeStage } from '../utils/ship/stage-writer.js';
+const LOG = '[gjsify ship]';
+export const shipCommand = {
+    command: 'ship',
+    description: `Build installable artifacts (${FORMAT_IDS.join(', ')}) from the current project.`,
+    builder: (yargs) => yargs
+        .option('target', {
+        type: 'string',
+        array: true,
+        description: `Formats to build, comma-separated or repeated. Default: ${FORMAT_IDS.join(',')}.`,
+    })
+        .option('out', {
+        type: 'string',
+        normalize: true,
+        description: 'Output root, relative to the project. Default: `gjsify.ship.outDir`, else `ship`.',
+    })
+        .option('stage', {
+        type: 'boolean',
+        default: false,
+        description: 'Produce the staged payload and stop, without packing anything.',
+    })
+        .option('skip-build', {
+        type: 'boolean',
+        default: false,
+        description: "Package what is already built instead of running the project's `build` script.",
+    })
+        .option('arch', {
+        type: 'string',
+        description: 'Target architecture in `process.arch` spelling. Default: this host.',
+    })
+        .option('verbose', {
+        type: 'boolean',
+        default: false,
+        description: 'Print each staged file and the GI namespaces the bundle imports.',
+    }),
+    handler: async (args) => {
+        const projectDir = process.cwd();
+        const config = new Config();
+        // No `.catch(() => ({}))` here, unlike the flatpak commands: a config
+        // file that fails to load would silently become "no config", and the
+        // result is a shipped artifact carrying default metadata the author
+        // never chose. An unreadable config is an error worth printing.
+        const configData = await config.forCommand(projectDir);
+        const ship = configData.ship ?? {};
+        const flatpak = configData.flatpak ?? {};
+        assertShippableTarget(configData.app);
+        const pkg = (readPackageJson(join(projectDir, 'package.json')) ?? {});
+        // Resolved before anything is built or written: a typo'd `--target`
+        // should not cost a build and leave a half-written `ship/stage/`.
+        const formats = resolveFormats(args.target ?? ship.targets ?? FORMAT_IDS);
+        if (!args['skip-build'])
+            await runProjectBuild(projectDir);
+        const discovered = discoverPayload({
+            projectDir,
+            pkg,
+            ship,
+            flatpakIcon: flatpak.icon,
+            declaredBundle: declaredBundlePath(pkg, ship),
+        });
+        const { settings, metadata, warnings } = resolveShipSettings({
+            projectDir,
+            pkg,
+            ship,
+            flatpak,
+            cli: { outDir: args.out, arch: args.arch },
+            discovered,
+        });
+        for (const warning of warnings)
+            console.warn(`${LOG} ${warning}`);
+        const mtime = buildTimestamp(settings.bundlePath);
+        const metadataInputs = {
+            appId: settings.appId,
+            name: settings.name,
+            command: settings.binaryName,
+            kind: settings.kind,
+            metadata,
+            configKey: 'gjsify.ship',
+            copyrightYear: new Date(mtime * 1000).getUTCFullYear(),
+        };
+        // Warn rather than fail: an incomplete AppStream component still
+        // installs and still runs. It is app STORES that will reject it, and
+        // that is a different day's problem than getting the package built.
+        for (const missing of validateAppMetadata(metadataInputs)) {
+            console.warn(`${LOG} ${missing.field} is not set — ${missing.hint}`);
+        }
+        const stageInputs = {
+            bundleFiles: discovered.bundleFiles,
+            launcher: renderLauncher(settings, basename(settings.bundlePath)),
+            metainfo: settings.kind === 'app' ? renderMetainfoApp(metadataInputs) : renderMetainfoCli(metadataInputs),
+            desktopEntry: settings.kind === 'app' ? renderDesktopEntry(metadataInputs) : undefined,
+            licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
+        };
+        const outRoot = resolve(projectDir, settings.outDir);
+        const stageDir = join(outRoot, 'stage');
+        const staged = planStage(settings, stageInputs);
+        writeStage(stageDir, staged);
+        console.log(`${LOG} staged ${staged.length} file(s) in ${relative(projectDir, stageDir)}/`);
+        if (args.verbose)
+            for (const file of staged)
+                console.log(`${LOG}   ${file.path}`);
+        if (args.stage)
+            return;
+        const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
+        if (args.verbose)
+            console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
+        const artifacts = [];
+        for (const format of formats) {
+            artifacts.push(await packOne({ format, settings, stageInputs, staged, stageDir, outRoot, namespaces, mtime }));
+        }
+        for (const artifact of artifacts) {
+            console.log(`${LOG} ${artifact.format}: ${relative(projectDir, artifact.path)} (${artifact.size} bytes)`);
+        }
+    },
+};
+async function packOne(input) {
+    const { format, settings, stageDir, outRoot, mtime } = input;
+    const overlay = planOverlay(settings, format, input.stageInputs);
+    const overlayDir = join(outRoot, 'overlay', format.id);
+    writeStage(overlayDir, overlay);
+    const payload = readStage([stageDir, overlayDir], [...input.staged, ...overlay]);
+    const depends = deriveDepends(format.id, {
+        namespaces: input.namespaces,
+        kind: settings.kind,
+        hasSchemas: settings.schemaFiles.length > 0,
+        extra: settings.extraDepends[format.id],
+        typelibPackages: settings.typelibPackages,
+        minGjsVersion: settings.minGjsVersion,
+    });
+    for (const warning of warnAboutGjsFloor(format.id, settings.minGjsVersion))
+        console.warn(`${LOG} ${warning}`);
+    const archLabel = format.archName(settings.arch, isArchIndependent(payload));
+    const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
+    const bytes = format.id === 'deb' ? await buildDeb(common) : await buildRpm(common);
+    const outDir = join(outRoot, 'out');
+    mkdirSync(outDir, { recursive: true });
+    const target = join(outDir, format.fileName(settings, archLabel));
+    writeFileSync(target, bytes);
+    return { format: format.id, path: target, size: bytes.byteLength };
+}
+/**
+ * Refuse a build target this command cannot package correctly.
+ *
+ * The launcher execs `gjs -m <bundle>`, so a `--app node` bundle would produce
+ * a package that installs and then fails at startup — and ADR 0024 § 4 says
+ * that case needs a BUNDLED Node, whose delivery (fetched at ship time versus a
+ * platform package) is still an open decision. Better to say so than to ship
+ * the broken half of it.
+ *
+ * An undeclared target is the common case for a GJS app and is allowed: `app`
+ * otherwise defaults to the HOST runtime, which would refuse a perfectly good
+ * GJS project merely for running this command under Node.
+ */
+function assertShippableTarget(app) {
+    if (app === undefined || app === 'gjs')
+        return;
+    throw new Error(`gjsify ship: this project declares \`gjsify.app: "${app}"\`, and only \`gjs\` can be packaged today. ` +
+        'The launcher execs `gjs -m <bundle>`, so any other target would install and then fail to start. ' +
+        'ADR 0024 § 4 has the runtime-per-OS table and what is still open for the other targets.');
+}
+/**
+ * Run the project's own `build` script, as a CHILD process.
+ *
+ * NOT dispatched in-process, even though `cli-app.ts` exists to allow exactly
+ * that: `gjsify run`'s script path ends in `return process.exit(code)` on every
+ * branch — deliberately, because under GJS a bare `process.exit` falls through
+ * and it needs exactly one exit scheduled. Calling it from here would end the
+ * process after the build and never reach the packing, and neither the types
+ * nor a `--skip-build` test would have caught it.
+ *
+ * `completion: 'return'` because this handler returns afterwards; on GJS that
+ * selects the blocking path rather than arming a main loop only an exit quits.
+ */
+async function runProjectBuild(projectDir) {
+    const pkg = readPackageJson(join(projectDir, 'package.json'));
+    if (typeof pkg?.scripts?.build !== 'string') {
+        throw new Error('gjsify ship: this project has no `build` script to run. Add one, or pass --skip-build to ' +
+            'package what is already built.');
+    }
+    console.log(`${LOG} running the project's build script`);
+    const result = await spawnToCompletion('gjsify', ['run', 'build'], {
+        completion: 'return',
+        cwd: projectDir,
+        stdio: 'inherit',
+        notFound: () => new Error('gjsify ship: `gjsify` is not on PATH, so the project build cannot be run. Build the project ' +
+            'yourself and pass --skip-build.'),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: the project's build script failed${describeExit(result)}.`);
+    }
+}

package/lib/config.d.ts

@@ -24,5 +24,17 @@ export declare class Config {
         globals?: string;
         excludeGlobals?: string[];
     }>;
+    /**
+     * The config for a command that is NOT a build — `gjsify flatpak …`,
+     * `gjsify ship …`.
+     *
+     * They all want exactly what the loader already produces: the merged
+     * `package.json#gjsify` + config-file object, with none of `forBuild`'s
+     * build-specific defaulting. Reaching it through `forBuild({} as never)`
+     * — five copies of that line before this method existed — lies to the type
+     * system and drags a tsconfig read and bundler defaults into a command
+     * that has no bundle.
+     */
+    forCommand(searchFrom?: string): Promise<ConfigData>;
     forBuild(cliArgs: ArgumentsCamelCase<CliBuildOptions>): Promise<ConfigData>;
 }