@gjsify/cli 0.51.1 → 0.52.0

package/lib/commands/link.js

@@ -0,0 +1,243 @@
+// `gjsify link <checkout>` / `gjsify unlink` — develop a consumer against a local
+// gjsify checkout without waiting for an npm release, and without changing a byte
+// of what the consumer commits.
+//
+// The model, the trap it closes and why `--immutable` refuses it are the header of
+// `utils/dev-link.ts` and ADR 0065. This file is the surface: two commands, the
+// output that makes an active link visible, and the undo.
+//
+// `unlink` REINSTALLS by default. Removing a link leaves a hole where the registry
+// copy used to be, and a command that promises to undo itself must not hand back a
+// tree that no longer resolves; `--no-install` is there for the case where the next
+// step is an install anyway.
+import { existsSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { applyDevLinks, consumerKnownNames, DEV_LINK_FILE, devLinkPath, ensureLocallyIgnored, formatUnbuiltDevLinks, planDevLinks, prepareDevLinks, readDevLinkOverride, removeDevLinkOverride, removeDevLinks, removeLocalIgnore, resolveCheckoutWorkspaces, retireDevLinks, scanDevLinks, unbuiltDevLinks, writeDevLinkOverride, } from '../utils/dev-link.js';
+export const linkCommand = {
+    command: 'link <checkout>',
+    description: 'Link this project against a local gjsify checkout for development: its workspace packages replace the installed registry copies, recorded in a git-ignored .gjsify-link.json that every later `gjsify install` re-applies. Undo with `gjsify unlink`.',
+    builder: (yargs) => yargs
+        .positional('checkout', {
+        description: 'Path to the gjsify checkout to link from (a repo whose package.json declares "workspaces").',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('packages', {
+        description: "Name glob selecting which of the checkout's workspace packages take part (repeatable; default: all of them). Matched against the package NAME with the same single-segment dialect as `gjsify foreach --include`, so a whole scope is `@gjsify/*` — a bare `*` matches no scoped name. Only packages this project actually depends on are ever linked.",
+        type: 'string',
+        array: true,
+    })
+        .option('dry-run', {
+        description: 'Print the links that would be made and write nothing.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: (args) => {
+        const consumerRoot = process.cwd();
+        const dryRun = args['dry-run'] ?? false;
+        const checkout = resolve(consumerRoot, args.checkout);
+        const overridePath = devLinkPath(consumerRoot);
+        // Validated BEFORE anything is written: a `.gjsify-link.json` naming a
+        // directory that is not a gjsify checkout would fail on every later install
+        // instead of on the command that created it.
+        const workspaces = resolveCheckoutWorkspaces(checkout, overridePath);
+        // No `--packages` means every workspace package, spelled as the EMPTY list:
+        // `['*']` would select nothing, because the glob dialect's `*` does not
+        // cross a `/` and every name here is scoped (utils/dev-link.ts).
+        const patterns = args.packages ?? [];
+        const links = planDevLinks({
+            consumerRoot,
+            workspaces,
+            patterns,
+            knownNames: consumerKnownNames(consumerRoot),
+        });
+        if (links.length === 0) {
+            console.error(`gjsify link: nothing to link — ${checkout} has ${workspaces.length} workspace package(s), ` +
+                `none of which ${consumerRoot} depends on${patterns.length === 0 ? '' : ` and matches ${patterns.join(', ')}`}.\n` +
+                `A link that links nothing is a silent no-op, so this is an error. Check the --packages ` +
+                `pattern, or run \`gjsify install\` first so the dependency tree exists.`);
+            return process.exit(1);
+        }
+        const label = `gjsify link${dryRun ? ' (dry-run)' : ''}`;
+        console.log(`${label}  → ${checkout}`);
+        console.log(`${' '.repeat(label.length)}    in ${consumerRoot}`);
+        for (const link of links) {
+            console.log(`  ${link.name}  →  ${relative(checkout, link.target) || '.'}`);
+        }
+        // REFUSES rather than warns, and it refuses before anything is written.
+        // A link to an unbuilt package is not a smaller link, it is a tree whose
+        // first import fails — and the earlier draft's warning was printed once,
+        // at link time, while `gjsify install` re-applied the same link on every
+        // later run in silence (`utils/dev-link.ts`, `assertDevLinksBuilt`).
+        const unbuilt = unbuiltDevLinks(links);
+        if (unbuilt.length > 0) {
+            console.error(`\n${formatUnbuiltDevLinks(unbuilt)}`);
+            return process.exit(1);
+        }
+        // A dry run that hides the REMOVALS is the half-report this feature keeps
+        // being caught by: retiring a link is the destructive half of a re-link,
+        // and it is the half worth seeing before it happens.
+        const sweep = sweepCheckouts(consumerRoot, checkout);
+        const keep = new Set(links.map((l) => l.name));
+        const stale = scanDevLinks(consumerRoot, sweep).filter((link) => !keep.has(link.name));
+        for (const link of stale)
+            console.log(`  retire  ${link.name}  (no longer selected)`);
+        if (dryRun) {
+            console.log(`\n${label}: nothing written. Drop --dry-run to apply.`);
+            return;
+        }
+        // RE-linking is a re-SELECTION, not an addition: whatever the previous
+        // override linked and this one does not is removed here. Without it a
+        // narrower `--packages` left an orphan symlink out of `node_modules` that
+        // no later command would ever name, and every `gjsify install` after it
+        // aborted (utils/dev-link.ts, `scanDevLinks`). Both checkouts are swept,
+        // because the new override may point somewhere else entirely.
+        const retired = retireDevLinks(consumerRoot, sweep, keep);
+        const written = applyDevLinks(links);
+        writeDevLinkOverride(consumerRoot, { version: 1, checkout, packages: patterns });
+        const ignored = ensureLocallyIgnored(consumerRoot);
+        console.log(`\n  ${written.length} link(s) written, ${links.length - written.length} already current.`);
+        // Counted against what was PLANNED, not just reported: `removeDevLinks`
+        // refuses a real directory sitting where a link belongs, and a retire that
+        // silently did less than it announced is the same half-report again.
+        if (stale.length > 0) {
+            console.log(`  ${retired.length} of ${stale.length} retired link(s) removed.`);
+        }
+        console.log(`  override: ${overridePath}`);
+        if (ignored === 'added')
+            console.log(`  git: ${DEV_LINK_FILE} added to .git/info/exclude (local, never committed)`);
+        if (ignored === 'no-git')
+            console.log(`  git: ${consumerRoot} is not a git repository — nothing to ignore`);
+        if (ignored === 'unreadable-git') {
+            console.warn(`  ! git: ${consumerRoot} has a .git POINTER that does not parse, so ${DEV_LINK_FILE} is NOT ignored. ` +
+                `Add it to .gitignore by hand, or the next \`git add -A\` commits your local override.`);
+        }
+        console.log(`\nEvery \`gjsify install\` here now re-applies these links and says so.\n` +
+            `\`gjsify install --immutable\` refuses while the override exists. Undo: \`gjsify unlink\`.`);
+    },
+};
+export const unlinkCommand = {
+    command: 'unlink',
+    description: 'Undo `gjsify link`: remove the development links and the .gjsify-link.json override, then reinstall the registry copies.',
+    builder: (yargs) => yargs
+        .option('dry-run', {
+        description: 'Print what would be removed and change nothing.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('install', {
+        description: 'Reinstall after unlinking, to put the registry copies back where the links were. On by default; --no-install leaves the holes for a later `gjsify install`.',
+        type: 'boolean',
+        default: true,
+    }),
+    handler: async (args) => {
+        const consumerRoot = process.cwd();
+        const dryRun = args['dry-run'] ?? false;
+        const overridePath = devLinkPath(consumerRoot);
+        if (!existsSync(overridePath)) {
+            console.log(`gjsify unlink: no development link in ${consumerRoot} (no ${DEV_LINK_FILE}).`);
+            return;
+        }
+        // TWO readers, because the plan alone is not a census of what is linked
+        // (utils/dev-link.ts, `scanDevLinks`). A checkout that has since been
+        // deleted must still be unlinkable, so the dead-target refusal is caught
+        // here rather than propagated.
+        //
+        // The checkout is read separately from the PLAN, because the plan is the
+        // part that can fail (a checkout that has since been deleted, an unbuilt
+        // one) and the checkout path is what the tree sweep below needs.
+        const checkouts = [];
+        try {
+            const checkout = readDevLinkOverride(consumerRoot)?.checkout;
+            if (checkout)
+                checkouts.push(checkout);
+        }
+        catch {
+            // Unparseable override: the sweep finds nothing, the plan below says
+            // why, and the override is still removed.
+        }
+        let links = [];
+        try {
+            links = prepareDevLinks(consumerRoot)?.links ?? [];
+        }
+        catch (err) {
+            console.warn(`gjsify unlink: ${err instanceof Error ? err.message : String(err)}\n` +
+                `  Removing the override anyway; any dangling links are cleaned by the reinstall.`);
+        }
+        const label = `gjsify unlink${dryRun ? ' (dry-run)' : ''}`;
+        console.log(`${label}  in ${consumerRoot}`);
+        if (dryRun) {
+            const names = new Set(links.map((l) => l.name));
+            for (const link of scanDevLinks(consumerRoot, checkouts))
+                names.add(link.name);
+            for (const name of [...names].sort())
+                console.log(`  would remove link  ${name}`);
+            console.log(`  would remove       ${overridePath}`);
+            console.log(`  would remove       ${DEV_LINK_FILE} entry from .git/info/exclude (if this module wrote it)`);
+            console.log(`\n${label}: nothing changed. Drop --dry-run to apply.`);
+            return;
+        }
+        // ORDER IS THE FIX. The links go first, the override LAST: the override is
+        // the only record of which checkout to sweep, so removing it while a link
+        // is still standing destroys the escape route — measured, that left
+        // `gjsify unlink` reporting success, the reinstall aborting on the orphan,
+        // and no command able to name it again.
+        //
+        // And the sweep is by TREE, not by plan: `removeDevLinks(links)` only ever
+        // visits what the CURRENT override selects, which is exactly how the orphan
+        // survived in the first place.
+        const removed = removeDevLinks(links);
+        const kept = new Set(removed.map((l) => l.name));
+        for (const link of retireDevLinks(consumerRoot, checkouts, new Set())) {
+            if (kept.has(link.name))
+                continue;
+            removed.push(link);
+        }
+        for (const link of removed)
+            console.log(`  unlinked  ${link.name}`);
+        // Nothing may point out of `node_modules` any more, or the reinstall below
+        // dies on it. If something does, the override STAYS: it is what a later
+        // `gjsify unlink` needs, and a half-undone tree with no record of the
+        // checkout is the wedge this whole block exists to prevent.
+        const stragglers = scanDevLinks(consumerRoot, checkouts);
+        if (stragglers.length > 0) {
+            console.error(`gjsify unlink: ${stragglers.length} link(s) still point into a checkout and could not be removed:\n` +
+                stragglers.map((l) => `  ${l.name}  ${l.linkPath} → ${l.target}`).join('\n') +
+                `\n  ${overridePath} is kept so this stays undoable. Remove the paths above and re-run.`);
+            return process.exit(1);
+        }
+        removeDevLinkOverride(consumerRoot);
+        console.log(`  removed   ${overridePath}`);
+        // The `.git/info/exclude` block is part of what `link` wrote, so it is part
+        // of what `unlink` owes back. Leaving it behind made the undo incomplete in
+        // a way nobody notices until they read the file and wonder what wrote it.
+        if (removeLocalIgnore(consumerRoot) === 'removed') {
+            console.log(`  removed   ${DEV_LINK_FILE} entry from .git/info/exclude`);
+        }
+        if (args.install === false) {
+            console.log(`\n  ${removed.length} link(s) removed. Run \`gjsify install\` to restore the registry copies.`);
+            return;
+        }
+        console.log(`\n  ${removed.length} link(s) removed — reinstalling to restore the registry copies.\n`);
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['install']);
+    },
+};
+/**
+ * Which checkouts a re-link has to sweep: the one it is about to record, plus the
+ * one the CURRENT override names when that is a different directory.
+ *
+ * Every failure reading the old override is swallowed. A malformed or dead one
+ * must not stop a fresh `gjsify link` from fixing the situation, which is usually
+ * exactly why it is being run.
+ */
+function sweepCheckouts(consumerRoot, checkout) {
+    let previous = null;
+    try {
+        previous = readDevLinkOverride(consumerRoot)?.checkout ?? null;
+    }
+    catch {
+        previous = null;
+    }
+    return previous && previous !== checkout ? [previous, checkout] : [checkout];
+}

package/lib/commands/onboard.js

@@ -464,6 +464,11 @@ export const onboardCommand = {
         };
         // 4a. Bookkeeping-only rows, and the serial publish path.
         const trustOnly = [];
+        // What THIS sweep has already put on the registry. A name is not served
+        // the instant its PUT is accepted, so the pin guard in `publishWorkspace`
+        // must not ask the registry about a package this loop created moments
+        // ago — target before dependent is the order, and the order is kept here.
+        const publishedHere = new Set();
         for (let i = 0; i < plans.length; i++) {
             const p = plans[i];
             if (p.action === 'skip') {
@@ -494,6 +499,7 @@ export const onboardCommand = {
                 continue;
             }
             const pub = await publishWorkspace({
+                assumePresent: [...publishedHere],
                 wsDir: p.ws.location,
                 tag: 'latest',
                 access: args.access,
@@ -514,7 +520,13 @@ export const onboardCommand = {
                 failed++;
                 continue;
             }
-            log(`  published ${pub.name}@${'version' in pub ? pub.version : ''}`);
+            log(`  published ${pub.name}@${'version' in pub ? pub.version : ''}` +
+                ('readback' in pub && pub.readback?.confirmed
+                    ? ` (verified on ${pub.registry} — ${pub.readback.attempts} probe(s))`
+                    : pub.action === 'skipped-untrusted-new'
+                        ? ''
+                        : ' (UNVERIFIED)'));
+            publishedHere.add(pub.name);
             await configureTrust(p, i, pub.action !== 'skipped-untrusted-new');
         }
         // 4b. The trust-only packages, concurrently.
@@ -670,7 +682,11 @@ function describePublishFailure(pub) {
             return (`npm ${pub.claim === 'already-published' ? 'reported it already published' : 'accepted the upload'} ` +
                 `(HTTP ${pub.putStatus}) but ${pub.name}@${pub.version} did not ` +
                 `resolve on ${pub.registry} after ${pub.readback.attempts} probe(s) over ` +
-                `${(pub.readback.elapsedMs / 1000).toFixed(1)}s`);
+                `${(pub.readback.elapsedMs / 1000).toFixed(1)}s [${pub.readback.verdict}: ${pub.readback.verdictDetail}]`);
+        case 'blocked-missing-dependency':
+            return (`not published — ${pub.missing.length} required pin(s) name a package ${pub.registry} does not ` +
+                `have: ${pub.missing.map((m) => `${m.block}.${m.name}@${m.spec}`).join(', ')}. Bootstrap the ` +
+                `target BEFORE its dependent; that order is a correctness property`);
         case 'error':
             return `HTTP ${pub.status} ${pub.statusText}`;
         default:

package/lib/commands/publish.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from '../types/index.js';
 import { type Diagnose404Result } from '../utils/publish-diagnose.js';
 import { type ReadbackResult } from '../utils/publish-readback.js';
+import { type WorkspacePin } from '../utils/publish-pins.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 interface PublishOptions {
     path?: string;
@@ -29,6 +30,18 @@ export interface PublishWorkspaceInput {
     tolerate: boolean;
     /** Skip an un-bootstrapped new package on the OIDC path. */
     tolerateUntrustedNew: boolean;
+    /**
+     * Names this CALLER has published in this same process, which the pin guard
+     * therefore does not ask the registry about.
+     *
+     * A brand-new name is not served the instant its PUT is accepted — the same
+     * eventual consistency that makes a version gate unsafe — so a sweep that
+     * bootstraps a target and its dependent in one run would otherwise block the
+     * dependent on a name it had just created itself. `gjsify onboard` is that
+     * sweep. The release sweep is `foreach --exec`, one process per package, so
+     * its children pass nothing and every edge is a real registry question.
+     */
+    assumePresent?: readonly string[];
     /** `--trusted` (force OIDC) / `undefined` | `'auto'` (auto-detect). */
     trustedFlag: boolean | 'auto' | undefined;
     /** Registry override. Default: `$npm_config_registry` → scope-aware npmrc → npmjs. */
@@ -94,6 +107,7 @@ export type PublishOutcome = {
     name: string;
     version: string;
     status: number;
+    registry: string;
     /** The read-back that CONFIRMED the conflicting version. */
     readback?: ReadbackResult;
 } | {
@@ -101,6 +115,26 @@ export type PublishOutcome = {
     action: 'skipped-untrusted-new';
     name: string;
     version: string;
+}
+/**
+ * The tarball was NOT sent, because a required intra-repo pin in it names a
+ * package the registry does not have (#1713).
+ *
+ * `ok` is the TOLERANCE, not the health: under `--tolerate-untrusted-new`
+ * this is a skip the sweep continues past, because a fatal child stops
+ * `foreach --exec` mid-roster and leaves a PARTIAL publish. Either way the
+ * broken tarball stays off the registry, which is the difference from the
+ * shape this outcome exists to end — where the dependency was skipped, exit
+ * 0, and its dependent shipped a pin npm could not resolve.
+ */
+ | {
+    ok: boolean;
+    action: 'blocked-missing-dependency';
+    name: string;
+    version: string;
+    registry: string;
+    tolerated: boolean;
+    missing: WorkspacePin[];
 } | {
     ok: false;
     action: 'otp-required';

package/lib/commands/publish.js

@@ -48,7 +48,8 @@ import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers
 import { packWorkspace } from './pack.js';
 import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError } from '../utils/npm-oidc.js';
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
-import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, verifyPublishedVersion, } from '../utils/publish-readback.js';
+import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, probePackageName, verifyPublishedVersion, } from '../utils/publish-readback.js';
+import { collectWorkspacePins, REQUIRED_BLOCK } from '../utils/publish-pins.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -81,7 +82,7 @@ export const publishCommand = {
         default: false,
     })
         .option('verify-timeout', {
-        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path.',
+        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path; the success line then reads `UNVERIFIED` and says so, because a publish nothing checked must never look like one that was checked.',
         type: 'number',
         default: DEFAULT_VERIFY_BUDGET_MS / 1000,
     })
@@ -305,6 +306,55 @@ export async function publishWorkspace(input) {
     // Base headers (npm-command: publish routing header etc.). The OTP is added
     // per-PUT by `doPut` so `withOtpRetry` can retry with different codes.
     const headers = buildPublishHeaders(url, { npmrc });
+    // 5. Do not PUT a tarball whose required intra-repo pins point at a name
+    //    this registry does not have (#1713).
+    //
+    //    The question is PRESENCE OF THE NAME, never a version, and that is what
+    //    makes it safe to gate on: a version is eventually consistent for
+    //    minutes after its own 2xx, so a version gate would manufacture a red on
+    //    a publish that worked. A name does not move once its first version
+    //    lands. `unknown` — a 5xx, a timeout, an auth wall — is not `absent` and
+    //    never blocks.
+    const assumePresent = new Set(input.assumePresent ?? []);
+    const pins = collectWorkspacePins(pkg, rewrittenPkg).filter((pin) => !assumePresent.has(pin.name));
+    if (pins.length > 0) {
+        const probed = await Promise.all(pins.map(async (pin) => ({
+            pin,
+            presence: await probePackageName({
+                registry,
+                name: pin.name,
+                authorization: headers['authorization'],
+            }),
+        })));
+        const missing = [];
+        for (const { pin, presence } of probed) {
+            if (presence.state === 'present')
+                continue;
+            const where = `${pin.block}.${pin.name}@${pin.spec}`;
+            if (presence.state === 'unknown') {
+                console.error(`gjsify publish: could not establish whether ${pin.name} exists (${presence.detail}) — not blocking on ${where}`);
+                continue;
+            }
+            if (pin.block !== REQUIRED_BLOCK) {
+                // npm and pnpm skip an unresolvable optional edge in silence;
+                // Yarn refuses the whole install. Loud, not fatal.
+                console.error(`gjsify publish: ${where} names a package ${registry} does not have — npm installs around it, Yarn (\`YN0035\`) does not`);
+                continue;
+            }
+            missing.push(pin);
+        }
+        if (missing.length > 0) {
+            return {
+                ok: tolerateUntrustedNew,
+                action: 'blocked-missing-dependency',
+                name: packed.name,
+                version: packed.version,
+                registry,
+                tolerated: tolerateUntrustedNew,
+                missing,
+            };
+        }
+    }
     // Trusted Publishing (OIDC) path — `--trusted` forces it, `undefined`
     // auto-detects from the GitHub OIDC env. Unused by `gjsify onboard` (local
     // token auth), preserved verbatim for `gjsify publish` in CI.
@@ -414,7 +464,7 @@ export async function publishWorkspace(input) {
         //
         //   NOT CONFIRMED YET — the other 19. Here the read-back waits out
         //   npm's own write queue, and those residual lags SUM TO 2554 s: a
-        //   sweep that waited them all out with the 300 s default would have
+        //   sweep that waited them all out under the fatal default would have
         //   added ~43 min to that 33 min job. That single number decides the
         //   shape below.
         //
@@ -438,7 +488,7 @@ export async function publishWorkspace(input) {
         //
         // Hence BOTH, split along that cost. The read-back runs per package
         // everywhere and is FATAL by default — that is what turns the
-        // incident's green single-package job red, for up to 300 s of
+        // incident's green single-package job red, for up to 600 s of
         // patience on a job that otherwise ran 59 s. The
         // 199-package sweep passes `--verify-defer --verify-timeout 5`: it
         // still CONFIRMS nine packages in ten and still names the suspect
@@ -458,7 +508,7 @@ export async function publishWorkspace(input) {
             // decoration: it is the only client-side measurement of when a
             // version became RESOLVABLE, as against `time[version]`, which is
             // when the registry recorded the write. The two are assumed equal by
-            // the 4.2-minute figure and the 300 s window, and nothing had ever
+            // the 4.2-minute figure and the default window, and nothing had ever
             // measured the gap. The pre-registered comparison — and what each
             // outcome would change — is in #1509's description; this line, under
             // GJSIFY_PUBLISH_DEBUG (which release.yml sets), is its input. Note
@@ -534,6 +584,7 @@ export async function publishWorkspace(input) {
             name: packed.name,
             version: packed.version,
             status: res.status,
+            registry: registryClean,
             readback,
         };
     }
@@ -568,9 +619,68 @@ export async function publishWorkspace(input) {
  * re-checks the same set afterwards. It is policy, so it lives here and not in
  * {@link publishWorkspace}, which stays a pure fact-finder.
  */
+/**
+ * What the success line SAYS it established — the half of the read-back that
+ * was missing.
+ *
+ * AN INSTRUMENT STATES WHAT IT MEASURED, and `+ name@version` states nothing.
+ * It is the identical string from a CLI that polled the registry and read a
+ * tarball back, from one run with `--verify-timeout 0`, and from any
+ * `@gjsify/cli` older than v0.47.0, which had no read-back at all. That is not a
+ * hypothetical: ts-for-gir's v5.1.0 release (run 34899018849) printed twelve
+ * `+ <name>@5.1.0` lines with `GJSIFY_PUBLISH_DEBUG=1` set and not one
+ * `response:` or read-back line among them, because the job's
+ * `PATH="$WS_PATH/node_modules/.bin:$PATH"` put that workspace's pinned
+ * `@gjsify/cli@^0.44.0` ahead of the 0.51.1 it had just bootstrapped. Three of
+ * the twelve were not on the registry. The marker could not have told anyone,
+ * and nobody could have known to look.
+ *
+ * So every terminal success marker now carries its verification clause, and an
+ * unverified one says UNVERIFIED in a word a log sweep can grep for. A bare
+ * `+ name@version` with no clause is now itself the signature of a CLI too old
+ * to check.
+ */
+function describeVerification(readback, registry) {
+    if (!readback?.confirmed) {
+        return {
+            verified: false,
+            clause: '(UNVERIFIED — read-back disabled by --verify-timeout 0)',
+            json: null,
+        };
+    }
+    const seconds = (readback.elapsedMs / 1000).toFixed(1);
+    return {
+        verified: true,
+        clause: `(verified on ${registry} — ${readback.attempts} probe(s), ${seconds}s)`,
+        json: {
+            registry,
+            verdict: readback.verdict,
+            probes: readback.attempts,
+            elapsedMs: readback.elapsedMs,
+            tarball: readback.last.state === 'present' ? readback.last.tarball : null,
+        },
+    };
+}
+/**
+ * An unverified SUCCESS gets an Actions annotation too.
+ *
+ * `--verify-timeout 0` is a legitimate escape hatch for a registry with no
+ * packument read path, and it restores exactly the behaviour every incident in
+ * this file came out of. A disabled verifier that announces itself is a
+ * decision; one that stays quiet is the original defect wearing a hat — and the
+ * channel is the one `--verify-defer` already uses, beside the job rather than
+ * in a log nobody re-reads. stderr, because `--json` owns stdout.
+ */
+function warnUnverified(name, version, registry) {
+    if (!process.env.GITHUB_ACTIONS)
+        return;
+    process.stderr.write(`::warning title=Publish unverified::${name}@${version} was published with the read-back disabled ` +
+        `(--verify-timeout 0) — nothing confirmed that ${registry} serves it\n`);
+}
 function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
     switch (outcome.action) {
         case 'published': {
+            const verification = describeVerification(outcome.readback, outcome.registry);
             const out = {
                 ok: true,
                 name: outcome.name,
@@ -580,11 +690,15 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                 integrity: outcome.integrity,
                 tag: outcome.tag,
                 registry: outcome.registry,
+                verified: verification.verified,
+                verification: verification.json,
             };
             if (asJson)
                 process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
             else
-                process.stdout.write(`+ ${outcome.name}@${outcome.version}\n`);
+                process.stdout.write(`+ ${outcome.name}@${outcome.version} ${verification.clause}\n`);
+            if (!verification.verified)
+                warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
         case 'publish-unconfirmed': {
@@ -602,6 +716,9 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     elapsedMs: outcome.readback.elapsedMs,
                     readbackUrl: outcome.readback.url,
                     readbackState: outcome.readback.last.state,
+                    verdict: outcome.readback.verdict,
+                    verdictDetail: outcome.readback.verdictDetail,
+                    recordedAt: outcome.readback.recordedAt ?? null,
                     deferred: deferUnconfirmed,
                 }, null, 2)}\n`);
             }
@@ -619,24 +736,31 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     const claimed = outcome.claim === 'already-published' ? 'was reported already published' : 'was accepted';
                     process.stderr.write(`::warning title=Publish unconfirmed::${outcome.name}@${outcome.version} ${claimed} ` +
                         `(HTTP ${outcome.putStatus}) but did not resolve on ${outcome.registry} within ` +
-                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s — the release-closure job must confirm it\n`);
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s [${outcome.readback.verdict}] — ` +
+                        'the release-closure job must confirm it\n');
                 }
                 return;
             }
             return process.exit(1);
         }
         case 'republish-tolerated': {
+            const verification = describeVerification(outcome.readback, outcome.registry);
             const out = {
                 ok: true,
                 action: 'republish-tolerated',
                 name: outcome.name,
                 version: outcome.version,
                 status: outcome.status,
+                registry: outcome.registry,
+                verified: verification.verified,
+                verification: verification.json,
             };
             if (asJson)
                 process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
             else
-                process.stdout.write(`= ${outcome.name}@${outcome.version} (already published, tolerated)\n`);
+                process.stdout.write(`= ${outcome.name}@${outcome.version} (already published, tolerated) ${verification.clause}\n`);
+            if (!verification.verified)
+                warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
         case 'skipped-untrusted-new': {
@@ -654,6 +778,27 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
             }
             return;
         }
+        case 'blocked-missing-dependency': {
+            const edges = outcome.missing.map((m) => `${m.block}.${m.name}@${m.spec}`).join(', ');
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: outcome.ok,
+                    action: 'blocked-missing-dependency',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    tolerated: outcome.tolerated,
+                    missing: outcome.missing,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`~ ${outcome.name}@${outcome.version} (NOT published — ${outcome.missing.length} required pin(s) name a package ${outcome.registry} does not have: ${edges})\n`);
+            }
+            console.error(`gjsify publish: every consumer install of ${outcome.name} would fail with \`npm error 404\`, on every package manager — a required edge is not skippable. Bootstrap the target first (docs/publishing.md § New \`@gjsify/*\` package), then re-run. See #1713.`);
+            if (!outcome.tolerated)
+                return process.exit(1);
+            return;
+        }
         case 'otp-required': {
             console.error(`gjsify publish: npm requires a 2FA one-time code — re-run with \`--otp <code>\``);
             return process.exit(1);

package/lib/commands/ship.js

@@ -35,6 +35,7 @@ import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
+import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
 import { assertHostCanFinish, assertKindCanPack, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
 import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
@@ -433,7 +434,24 @@ async function assemble(args) {
                 workDir: join(outRoot, 'schemas'),
             })),
     ];
-    const staged = placeStage(layout, settings, planned, runtime.files);
+    // THE APPLICATION ICON, rendered once for the sizes this layout's writers
+    // embed — six for the `.exe`'s resource directory, seven for the `.icns` —
+    // and nothing for a CLI or for Linux, where the theme carries the SVG the
+    // project declared. `resolveAppIcon` REFUSES an app that has no source for a
+    // size rather than staging without it: the released artifacts this closes
+    // shipped for a year with the generic icon on two platforms, and the only
+    // reason was that nothing said so (`utils/ship/icons.ts`).
+    const icon = settings.kind === 'app' && layout.icon !== undefined
+        ? await resolveAppIcon({
+            iconFiles: settings.iconFiles,
+            appId: settings.appId,
+            sizes: layout.icon.sizes,
+            target: layout.icon.writes,
+        })
+        : undefined;
+    if (icon !== undefined)
+        console.log(`${LOG} icon: ${iconSizes(icon).join('/')} px, ${icon.source}`);
+    const staged = placeStage(layout, { ...settings, icon }, planned, runtime.files);
     writeStage(stageDir, staged);
     console.log(`${LOG} staged ${staged.length} file(s) for ${layout.name} in ${relative(projectDir, stageDir)}/`);
     if (args.verbose)

package/lib/types/config-data.d.ts

@@ -771,7 +771,7 @@ export interface ConfigDataFlatpak extends AppMetadata {
     command?: string;
     /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
     finishArgs?: string[];
-    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
+    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. a GI library the runtime lacks). */
     extraModules?: unknown[];
     /**
      * Full replacement for the manifest's `modules` array: used verbatim, with