@gjsify/cli 0.51.1 → 0.53.0

package/lib/commands/install.js

@@ -10,7 +10,7 @@
 // `node_modules/` and symlinks `workspace:` refs to their source. Members with
 // conflicting ranges of the same external still share ONE hoisted copy; the
 // resolver warns naming both ranges, both requesters and the winner (per-member
-// dedup is the open Phase D.8 item in status/open-todos.md).
+// dedup is the open Phase D.8 item in status/open-todos/README.md).
 //
 // Concurrency (ADR 0001): every prefix mutation runs under a per-prefix
 // cross-process lock (utils/install-lock.ts), so installs into different
@@ -35,6 +35,7 @@ import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEn
 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';
+import { applyDevLinks, assertNoDevLinkUnderImmutable, devLinkRoot, prepareDevLinks, } from '../utils/dev-link.js';
 /**
  * Link type for the workspace↔workspace directory links.
  *
@@ -157,6 +158,12 @@ export const installCommand = {
                     '(--immutable forbids rewriting the lockfile). Drop one.');
                 return process.exit(1);
             }
+            // FAIL CLOSED before anything is resolved or written: an active `gjsify
+            // link` override would make a local development tree an input to the one
+            // install shape whose whole promise is "exactly what is committed" — CI,
+            // the Flatpak build, a release. Throws rather than exits so `index.ts`
+            // prints the message that names the override file (utils/dev-link.ts).
+            assertNoDevLinkUnderImmutable(process.cwd());
         }
         if (args.global) {
             if (!args.packages || args.packages.length === 0) {
@@ -426,6 +433,61 @@ function depKindFromArgs(args) {
         return 'optionalDependencies';
     return 'dependencies';
 }
+/**
+ * Wire the `gjsify link` development override for this prefix, and SAY SO.
+ *
+ * Called before the fetch phase for the same reason `wireWorkspaceSymlinks` is:
+ * these links point at local source and depend on no download, so writing them
+ * first means an install that dies mid-way still leaves a resolvable tree. Called
+ * again afterwards as a near no-op safety net.
+ *
+ * The announcement is not decoration. A linked tree changes what a build compiles
+ * without changing any file the consumer commits, so the one place it can be seen
+ * is the output of the command that re-applies it — this is exactly what a bare
+ * `npm link` does not do, and why the next `npm install` silently undoes it.
+ *
+ * Returns `null` when no override is present; throws when one names a checkout
+ * that is gone, is not a gjsify workspace, or is not BUILT (utils/dev-link.ts).
+ *
+ * `devLinkRoot` and not `prefix` verbatim: `assertNoDevLinkUnderImmutable` already
+ * walks up to the workspace root to decide whether an override is in play, and two
+ * answers to "which override governs this install" is one answer too many. Nothing
+ * rescued the difference either — the bare `install` path happens to delegate to
+ * the workspace root before reaching here, `install <pkg>` does not.
+ */
+function activateDevLinks(prefix, announce) {
+    const active = prepareDevLinks(devLinkRoot(prefix));
+    if (!active)
+        return null;
+    const written = applyDevLinks(active.links);
+    if (!announce)
+        return active;
+    console.log(`gjsify install: development link ACTIVE (${active.overridePath}) — ${active.links.length} ` +
+        `package(s) come from ${active.checkout}, linked rather than fetched ` +
+        `(${written.length} (re)written, ${active.links.length - written.length} already current):`);
+    const names = active.links.map((l) => l.name);
+    const shown = names.slice(0, 12);
+    console.log(`  ${shown.join(', ')}${names.length > shown.length ? `, +${names.length - shown.length} more` : ''}`);
+    console.log('  `gjsify unlink` restores the registry copies; `gjsify install --immutable` refuses while it exists.');
+    return active;
+}
+/**
+ * Re-apply the dev links after the install, and SAY SO when it changed anything.
+ *
+ * `applyDevLinks` returns what it had to (re)write, and both post-install call
+ * sites used to throw that away — so an installer that clobbered a link and got it
+ * put back looked exactly like one that never touched it. The safety net is
+ * supposed to be a no-op; the run where it is not is the one worth a line.
+ */
+function reportRewiredDevLinks(active) {
+    if (!active)
+        return;
+    const rewired = applyDevLinks(active.links);
+    if (rewired.length === 0)
+        return;
+    console.log(`gjsify install: re-applied ${rewired.length} development link(s) the install had replaced: ` +
+        `${rewired.map((l) => l.name).join(', ')}`);
+}
 async function projectInstallNative(args, signal) {
     const cwd = process.cwd();
     const pkgPath = join(cwd, 'package.json');
@@ -497,6 +559,7 @@ async function projectInstallNative(args, signal) {
     // re-acquires the same lock re-entrantly.
     const lock = await acquireInstallLock(cwd, { signal });
     try {
+        const devLinks = activateDevLinks(cwd, true);
         // Typed as NativeInstallOptions so the native-backend-only `optionalSpecs`
         // is CHECKED here instead of smuggled past an excess-property check;
         // `installPackages` forwards the object to that backend unchanged.
@@ -518,8 +581,14 @@ async function projectInstallNative(args, signal) {
                 ...optionalDependencyNames(pkg ? [pkg] : []),
                 ...(args['save-optional'] ? (args.packages ?? []).map((s) => parseSpec(s).name) : []),
             ]),
+            linkedNames: devLinks?.names,
         };
         const result = await installPackages(nativeOpts);
+        // The link survives the install — the point of reading the override at all.
+        // The return value is REPORTED, not dropped: a non-empty one means the
+        // install disturbed a link that the pre-fetch pass had already wired, which
+        // is a fact about the installer, not a routine no-op.
+        reportRewiredDevLinks(devLinks);
         // Only the `gjsify install <pkg>...` add-a-dep flow mutates the manifest;
         // the no-args refresh must not.
         if (args.packages && args.packages.length > 0 && pkg) {
@@ -572,7 +641,7 @@ function syncLockfileRequested(cwd, specs) {
  *
  * Hoisting is deliberately minimal — members with conflicting ranges of the same
  * dep share one hoisted copy and the resolver warns. Per-member dedup and nested
- * `node_modules/` are the open Phase D.8 item in status/open-todos.md.
+ * `node_modules/` are the open Phase D.8 item in status/open-todos/README.md.
  */
 async function workspaceInstall(cwd, args, signal) {
     // Held for the WHOLE flow: bin shims, workspace symlinks and the external
@@ -650,6 +719,10 @@ async function workspaceInstallLocked(cwd, args, signal) {
         }
     }
     console.log(`gjsify install: ${workspaces.length} workspace(s), ${externalSpecs.size} external dep spec(s), ${symlinks.length} workspace symlink(s)`);
+    // A `gjsify link` override at the workspace ROOT governs the whole install, and
+    // is wired here for the same reason the shims and workspace symlinks are: before
+    // anything can fail on the network.
+    const devLinks = activateDevLinks(cwd, true);
     // EARLY, before the download/extract phase: the shims derive from workspace
     // manifests alone, while the heavy phase that follows can die mid-way (network,
     // timeout, crash). Writing them up front means a failed install can never leave
@@ -836,6 +909,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             // `types-dev/<lib>` workspace that also exists on npm and is pinned
             // transitively in the lockfile).
             workspaceNames: new Set(byName.keys()),
+            linkedNames: devLinks?.names,
             specOrigins: new Map([...specOrigins].map(([k, v]) => [k, [...v]])),
             // Aggregated over EVERY member, because the specs are: a name any member
             // declares as a plain dependency stays required.
@@ -865,6 +939,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             frozen: args.immutable,
             signal,
             workspaceNames: new Set(byName.keys()),
+            linkedNames: devLinks?.names,
             // Same aggregated answer as the root install: these specs are a SUBSET of
             // the root's, so classifying them differently would make one dep optional
             // at the root and required in a member.
@@ -874,6 +949,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
     }
     // A near no-op safety net in case a later step disturbed a link.
     await wireWorkspaceSymlinks();
+    reportRewiredDevLinks(devLinks);
     // Now that the tree is materialised, refresh the shims' GJS preamble with the
     // native prebuild dirs that only became discoverable after the install (on a
     // fresh checkout `detectNativePackages` finds nothing before extraction).
@@ -1196,7 +1272,7 @@ async function installGlobalAndLink(specs, opts) {
         // A global install of `@gjsify/cli` must also lay down the GJS bundler engine
         // + the sibling format/CSS bridges. They are OPTIONAL PEERS of the CLI (so a
         // plain `npm install @gjsify/cli` on Node does not force a prebuild) and the
-        // native backend does not resolve peerDependencies at all, so without this
+        // native backend, like npm ≥ 7, installs required peers only, so without this
         // they never arrive and `gjsify build` hard-fails under GJS with "no usable
         // bundler engine". Pinned to the CLI's resolved version so they move in
         // lockstep with the bundle; a platform with no published prebuild warns.
@@ -1257,8 +1333,8 @@ function reportLinkedBins(created, binDir) {
  *
  * The engine is an OPTIONAL PEER of `@gjsify/cli` on purpose — a plain
  * `npm install @gjsify/cli` on Node must not fetch prebuilds — but nobody resolves
- * it for a project: npm 7+ skips optional peers and the native backend does not
- * resolve `peerDependencies` at all. Under GJS there is no npm `rolldown`
+ * it for a project: npm 7+ skips optional peers and so does the native backend
+ * (it installs REQUIRED peers only). Under GJS there is no npm `rolldown`
  * fallback, so `gjsify build` had nothing to load.
  *
  * Four conditions, and (b) is the one worth reading:

package/lib/commands/link.d.ts

@@ -0,0 +1,13 @@
+import type { LeafCommand } from '../types/index.js';
+interface LinkOptions {
+    checkout: string;
+    packages?: string[];
+    'dry-run'?: boolean;
+}
+interface UnlinkOptions {
+    'dry-run'?: boolean;
+    install?: boolean;
+}
+export declare const linkCommand: LeafCommand<unknown, LinkOptions>;
+export declare const unlinkCommand: LeafCommand<unknown, UnlinkOptions>;
+export {};

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';