@gjsify/cli 0.59.0 → 0.60.0

package/lib/commands/install.d.ts

@@ -21,6 +21,16 @@ interface InstallOptions {
     force?: boolean;
 }
 export declare const installCommand: Command<unknown, InstallOptions>;
+/**
+ * Version of the `@gjsify/cli` the workspace at `cwd` pins: the one DECLARED in
+ * its package.json (`^`/`~`/`=` prefix stripped; only a plain version counts).
+ * The installed copy is consulted only when package.json declares no
+ * `@gjsify/cli` at all — `install` replaces a stale `node_modules`, so it must
+ * not override a declared pin (that flagged the very state being repaired).
+ * A declared non-version spec (`workspace:^`, a range, a tag) falls back to the in-repo
+ * source so the check still fires on a fresh checkout of the gjsify monorepo.
+ */
+export declare function readWorkspaceCliVersion(cwd: string): string | null;
 /**
  * Which dependency NAMES are optional across the given manifests.
  *

package/lib/commands/install.js

@@ -350,13 +350,31 @@ function readRunningCliVersion() {
     return null;
 }
 /**
- * Version of the `@gjsify/cli` the workspace at `cwd` pins. Prefers the resolved
- * install, falling back to the in-repo source so the check also fires on a fresh,
- * not-yet-installed checkout of the gjsify monorepo itself.
+ * Version of the `@gjsify/cli` the workspace at `cwd` pins: the one DECLARED in
+ * its package.json (`^`/`~`/`=` prefix stripped; only a plain version counts).
+ * The installed copy is consulted only when package.json declares no
+ * `@gjsify/cli` at all — `install` replaces a stale `node_modules`, so it must
+ * not override a declared pin (that flagged the very state being repaired).
+ * A declared non-version spec (`workspace:^`, a range, a tag) falls back to the in-repo
+ * source so the check still fires on a fresh checkout of the gjsify monorepo.
  */
-function readWorkspaceCliVersion(cwd) {
-    return (readCliVersionFrom(join(cwd, 'node_modules', CLI_PACKAGE_NAME, 'package.json')) ??
-        readCliVersionFrom(join(cwd, 'packages', 'infra', 'cli', 'package.json')));
+export function readWorkspaceCliVersion(cwd) {
+    const pkg = readPackageJson(join(cwd, 'package.json'));
+    let declared = false;
+    for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const spec = pkg?.[kind]?.[CLI_PACKAGE_NAME];
+        if (typeof spec === 'string')
+            declared = true;
+        const m = typeof spec === 'string' ? /^[\^~=v]*(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(spec.trim()) : null;
+        if (m)
+            return m[1];
+    }
+    if (!declared) {
+        const installed = readCliVersionFrom(join(cwd, 'node_modules', CLI_PACKAGE_NAME, 'package.json'));
+        if (installed)
+            return installed;
+    }
+    return readCliVersionFrom(join(cwd, 'packages', 'infra', 'cli', 'package.json'));
 }
 /**
  * Warn (never block) when the running gjsify CLI differs from the `@gjsify/cli`

package/lib/commands/publish.d.ts

@@ -2,6 +2,8 @@ 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 { type HoldReason } from '../utils/publish-hold.js';
+import { type Classification } from '../utils/publish-status.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 interface PublishOptions {
     path?: string;
@@ -12,6 +14,9 @@ interface PublishOptions {
     'tolerate-untrusted-new'?: boolean;
     'verify-timeout'?: number;
     'verify-defer'?: boolean;
+    'hold-timeout'?: number;
+    'report-ledger'?: boolean;
+    ref?: string;
     provenance?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
@@ -60,6 +65,11 @@ export interface PublishWorkspaceInput {
      * success, which is the pre-v0.46.0 behaviour and why this defaults on.
      */
     verifyBudgetMs?: number;
+    /**
+     * How long to wait for an intra-repo pin the registry does not serve before
+     * holding this package. Default {@link DEFAULT_HOLD_WAIT_MS}.
+     */
+    holdWaitMs?: number;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {
@@ -101,6 +111,21 @@ export type PublishOutcome = {
     putUrl: string;
     payloadBytes: number;
     readback: ReadbackResult;
+    /** What the unserved version IS (validating / staged / blocked / …). */
+    classification: Classification;
+}
+/**
+ * The tarball was NOT sent, because an intra-repo pin in it names a version
+ * the registry does not serve — an accepted-but-"validating" upload, say.
+ * `ok` is the tolerance, as for `blocked-missing-dependency`.
+ */
+ | {
+    ok: false;
+    action: 'held-unpublished-dependency';
+    name: string;
+    version: string;
+    registry: string;
+    reasons: HoldReason[];
 } | {
     ok: true;
     action: 'republish-tolerated';

package/lib/commands/publish.js

@@ -50,6 +50,8 @@ import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailabl
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
 import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, probePackageName, verifyPublishedVersion, } from '../utils/publish-readback.js';
 import { collectWorkspacePins, REQUIRED_BLOCK } from '../utils/publish-pins.js';
+import { appendLedger, DEFAULT_HOLD_WAIT_MS, findUnavailablePins, holdsPublish, readLedger, recordUnserved, renderLedgerSummary, summariseReasons, } from '../utils/publish-hold.js';
+import { describeClass, statusTokenFromEnv } from '../utils/publish-status.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -90,6 +92,20 @@ export const publishCommand = {
         description: 'Report an unconfirmed read-back and exit 0 instead of 1. ONLY for a caller that re-checks the same set afterwards — `gjsify run npm:publish` passes it because `scripts/verify-published-closure.mjs` sweeps the whole roster at the end of release.yml. Everywhere else an unconfirmed publish must fail the job that made it.',
         type: 'boolean',
         default: false,
+    })
+        .option('hold-timeout', {
+        description: 'Seconds to wait for an intra-repo dependency pin whose exact version the registry does not serve (yet) before HOLDING this package instead of publishing it. A version npm accepted but never serves (status "validating") would make every dependent uninstallable; the write lag measured on v0.46.0 reaches 252s, hence the default. `0` probes once and holds without waiting. A hold exits 1, or 0 under `--verify-defer`.',
+        type: 'number',
+        default: DEFAULT_HOLD_WAIT_MS / 1000,
+    })
+        .option('report-ledger', {
+        description: 'Print the job-summary markdown for the publish ledger named by $GJSIFY_PUBLISH_LEDGER (versions npm accepted but does not serve, packages held because of them, the recovery command) and exit. Pair with `--ref <tag>`.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('ref', {
+        description: 'With --report-ledger: the git ref to put in the printed recovery command.',
+        type: 'string',
     })
         .option('provenance', {
         description: "Pass-through flag — recorded in the payload but no signing happens (gjsify doesn't ship a sigstore signer yet).",
@@ -142,6 +158,17 @@ export const publishCommand = {
         const checkTrustedOnly = args['check-trusted'] === true;
         const trustedFlag = args.trusted;
         const verbose = Boolean(process.env.GJSIFY_PUBLISH_DEBUG);
+        if (args['report-ledger'] === true) {
+            const summary = renderLedgerSummary(readLedger(process.env.GJSIFY_PUBLISH_LEDGER), args.ref ?? '<tag>');
+            if (summary)
+                process.stdout.write(`${summary}\n`);
+            return;
+        }
+        const holdSeconds = args['hold-timeout'] ?? DEFAULT_HOLD_WAIT_MS / 1000;
+        if (!Number.isFinite(holdSeconds) || holdSeconds < 0) {
+            console.error(`gjsify publish: --hold-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['hold-timeout'])}`);
+            return process.exit(2);
+        }
         if (provenance) {
             console.warn('gjsify publish: --provenance recorded but not signed (no sigstore integration yet).');
         }
@@ -250,6 +277,7 @@ export const publishCommand = {
             otpProvider,
             seedOtpFirst: otp !== undefined,
             verifyBudgetMs,
+            holdWaitMs: Math.round(holdSeconds * 1000),
         });
         reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
@@ -355,6 +383,43 @@ export async function publishWorkspace(input) {
             };
         }
     }
+    // 5b. Do not PUT a tarball whose pin names a VERSION the registry does not
+    //     serve (v0.59.x: adwaita-fonts "Validating" while its dependents shipped).
+    //     Unlike 5 this waits, because a version is late for minutes after its own
+    //     2xx; see publish-hold.ts.
+    const ledgerPath = process.env.GJSIFY_PUBLISH_LEDGER;
+    if (pins.length > 0) {
+        const reasons = await findUnavailablePins({
+            registry: registryClean,
+            pins,
+            ledger: readLedger(ledgerPath),
+            ledgerPath,
+            authorization: headers['authorization'],
+            statusToken: statusTokenFromEnv(process.env),
+            waitBudgetMs: input.holdWaitMs ?? DEFAULT_HOLD_WAIT_MS,
+            log: verbose ? (m) => console.error(m) : undefined,
+        });
+        for (const r of reasons.filter((x) => !holdsPublish(x))) {
+            console.error(`gjsify publish: ${r.block}.${r.name}@${r.version} is not served (${r.detail}) — optional edge, publishing anyway`);
+        }
+        const holding = reasons.filter(holdsPublish);
+        if (holding.length > 0) {
+            appendLedger(ledgerPath, {
+                ev: 'held',
+                name: packed.name,
+                version: packed.version,
+                reasons: holding,
+            });
+            return {
+                ok: false,
+                action: 'held-unpublished-dependency',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                reasons: holding,
+            };
+        }
+    }
     // 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.
@@ -529,6 +594,14 @@ export async function publishWorkspace(input) {
                 putUrl: url,
                 payloadBytes: bodyStr.length,
                 readback,
+                classification: await recordUnserved({
+                    ledgerPath,
+                    registry: registryClean,
+                    name: packed.name,
+                    version: packed.version,
+                    verdict: readback.verdict,
+                    statusToken: statusTokenFromEnv(process.env),
+                }),
             };
         }
         return {
@@ -576,6 +649,14 @@ export async function publishWorkspace(input) {
                 putUrl: url,
                 payloadBytes: bodyStr.length,
                 readback,
+                classification: await recordUnserved({
+                    ledgerPath,
+                    registry: registryClean,
+                    name: packed.name,
+                    version: packed.version,
+                    verdict: readback.verdict,
+                    statusToken: statusTokenFromEnv(process.env),
+                }),
             };
         }
         return {
@@ -701,8 +782,31 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                 warnUnverified(outcome.name, outcome.version, outcome.registry);
             return;
         }
+        case 'held-unpublished-dependency': {
+            const because = summariseReasons(outcome.reasons);
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: false,
+                    action: 'held-unpublished-dependency',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    reasons: outcome.reasons,
+                    deferred: deferUnconfirmed,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`~ ${outcome.name}@${outcome.version} (HELD — not published: ${because})\n`);
+            }
+            if (process.env.GITHUB_ACTIONS) {
+                process.stderr.write(`::warning title=Package held::${outcome.name}@${outcome.version} was NOT published: ${because}\n`);
+            }
+            // The sweep defers like an unconfirmed publish: the closure job goes red
+            // on the missing package, and the job summary carries the recovery.
+            return deferUnconfirmed ? undefined : process.exit(1);
+        }
         case 'publish-unconfirmed': {
-            const message = formatUnconfirmedPublish(outcome);
+            const message = `${formatUnconfirmedPublish(outcome)}\n  state: ${describeClass(outcome.classification.cls)} — ${outcome.classification.detail}`;
             if (asJson) {
                 process.stdout.write(`${JSON.stringify({
                     ok: false,
@@ -720,6 +824,8 @@ function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
                     verdictDetail: outcome.readback.verdictDetail,
                     recordedAt: outcome.readback.recordedAt ?? null,
                     deferred: deferUnconfirmed,
+                    class: outcome.classification.cls,
+                    classDetail: outcome.classification.detail,
                 }, null, 2)}\n`);
             }
             else {
@@ -736,7 +842,7 @@ 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 [${outcome.readback.verdict}] — ` +
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s [${outcome.readback.verdict}; ${describeClass(outcome.classification.cls)}] — ` +
                         'the release-closure job must confirm it\n');
                 }
                 return;

package/lib/utils/discover-showcases.js

@@ -7,6 +7,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 function manifestPath() {
+    // Test seam: e2e points this at a fixture catalog (a gjs-only workspace showcase),
+    // since the curated list no longer holds one.
+    const override = process.env.GJSIFY_SHOWCASES_MANIFEST;
+    if (override)
+        return override;
     const here = dirname(fileURLToPath(import.meta.url));
     // `showcases.json` sits at the CLI package root, but its depth below this
     // module depends on how the CLI was loaded: two levels from

package/lib/utils/gjsify-shim.d.ts

@@ -41,6 +41,24 @@ export declare function needsSelfShim(opts: {
  * reuse it instead of creating their own.
  */
 export declare function ensureGjsifyShimOnPath(): void;
+/**
+ * Write `files` (relative path → content) into a directory NAMED BY THEIR HASH and
+ * return it. Same content, same directory: a run finds what the last one wrote and
+ * writes nothing, so shim dirs no longer pile up one per invocation (5930 in a
+ * `/tmp`, none ever removed).
+ *
+ * A reused dir, rather than one removed on exit, is what lets a child outlive its
+ * parent: a detached grandchild keeps resolving `gjsify` through the inherited PATH
+ * after the CLI that made the shim is gone, and a dir that is deleted at exit
+ * breaks it. Content-addressed means a file in it never changes, so a running
+ * process can never see a different shim than the one it was started with; each
+ * member lands by tmp+`rename`, so a concurrent run sees it whole or not at all.
+ *
+ * Lives under `$XDG_CACHE_HOME/gjsify/shim` — a `/tmp` path is world-writable, and
+ * a PATH entry there lets another local user plant a `gjsify`. A cache dir that
+ * cannot be written (read-only HOME) falls back to a private `mkdtemp` dir.
+ */
+export declare function materializeShimDir(files: Record<string, string>, root?: string): string;
 /**
  * The tree whose `node_modules` holds the running CLI and its prebuilds: the
  * install prefix above the first `node_modules` segment, or the workspace root

package/lib/utils/gjsify-shim.js

@@ -39,13 +39,15 @@
 // came through the workspace's own `node_modules/.bin/gjsify`, that shim IS the CLI
 // the tree wants. Widening this to every Node invocation would silently move in-repo
 // nested builds off the GJS bundle.
-import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, existsSync, readFileSync, renameSync, rmSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, delimiter, relative, isAbsolute, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, shQuoteArg } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
+import { gjsifyCacheRoot } from './install-cache-fs.js';
 import { resolveBinOnPath } from './install-global.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 let _ensured = false;
@@ -128,8 +130,6 @@ export function ensureGjsifyShimOnPath() {
     const workspaceRoot = findWorkspaceRoot(process.cwd()) ?? process.cwd();
     if (!needsSelfShim({ gjs, selfEntry, workspaceRoot }))
         return;
-    const dir = mkdtempSync(join(tmpdir(), 'gjsify-shim-'));
-    const shim = join(dir, 'gjsify');
     // The interpreter is NAMED, not pathed, matching `buildShLauncher` and
     // `buildLauncherShims`, so a missing one fails the same way on every OS. Not
     // `process.execPath`: the batch member cannot quote an interpreter argument
@@ -143,23 +143,78 @@ export function ensureGjsifyShimOnPath() {
     // beifahrer consumer on macOS: `gjsify workspace <pkg> build` died in
     // `get columns` with "Unsupported type void".
     const envPreamble = gjs ? selfShimPreamble(selfEntry) : '';
-    writeFileSync(shim, gjs
-        ? buildShLauncher(selfEntry, { isGjsBundle: true, envPreamble, gjs: interpreter })
-        : `#!/bin/sh\nexec "${interpreter}" "${selfEntry}" "$@"\n`, { mode: 0o755 });
-    chmodSync(shim, 0o755);
+    const files = {
+        gjsify: gjs
+            ? buildShLauncher(selfEntry, { isGjsBundle: true, envPreamble, gjs: interpreter })
+            : `#!/bin/sh\nexec "${interpreter}" "${selfEntry}" "$@"\n`,
+    };
     // cmd.exe and pwsh cannot run the extension-less member: not on PATHEXT, and
     // Windows has no shebang handling. `buildLauncherShims` ports npm's
     // three-sibling answer, including the IF/ELSE ERRORLEVEL handling that
     // `&&`/`||` chaining gets wrong.
     if (!gjs && process.platform === 'win32') {
         const { cmd, ps1 } = buildLauncherShims({ interpreter, interpreterArgs: [], target: selfEntry });
-        writeFileSync(`${shim}.cmd`, cmd);
-        writeFileSync(`${shim}.ps1`, ps1);
+        files['gjsify.cmd'] = cmd;
+        files['gjsify.ps1'] = ps1;
     }
+    const nodeShim = buildNodeShim(gjs, selfEntry, envPreamble);
+    if (nodeShim)
+        files[`${NODE_SHIM_SUBDIR}/node`] = nodeShim;
+    const dir = materializeShimDir(files);
     _selfShimActive = true;
     process.env.GJSIFY_SHIM_DIR = dir;
     process.env.PATH = dir + delimiter + (process.env.PATH ?? '');
-    writeNodeShim(dir, gjs, selfEntry, envPreamble);
+}
+/**
+ * Write `files` (relative path → content) into a directory NAMED BY THEIR HASH and
+ * return it. Same content, same directory: a run finds what the last one wrote and
+ * writes nothing, so shim dirs no longer pile up one per invocation (5930 in a
+ * `/tmp`, none ever removed).
+ *
+ * A reused dir, rather than one removed on exit, is what lets a child outlive its
+ * parent: a detached grandchild keeps resolving `gjsify` through the inherited PATH
+ * after the CLI that made the shim is gone, and a dir that is deleted at exit
+ * breaks it. Content-addressed means a file in it never changes, so a running
+ * process can never see a different shim than the one it was started with; each
+ * member lands by tmp+`rename`, so a concurrent run sees it whole or not at all.
+ *
+ * Lives under `$XDG_CACHE_HOME/gjsify/shim` — a `/tmp` path is world-writable, and
+ * a PATH entry there lets another local user plant a `gjsify`. A cache dir that
+ * cannot be written (read-only HOME) falls back to a private `mkdtemp` dir.
+ */
+export function materializeShimDir(files, root = gjsifyCacheRoot('shim', 'v1')) {
+    const names = Object.keys(files).sort();
+    const hash = createHash('sha256');
+    for (const name of names)
+        hash.update(`${name}\0${files[name]}\0`);
+    const key = hash.digest('hex').slice(0, 16);
+    try {
+        return writeShimDir(join(root, key), files, names);
+    }
+    catch {
+        // Unwritable cache (read-only HOME, full disk): the shim is still needed
+        // for this run, so take the per-run dir this function exists to avoid.
+        return writeShimDir(mkdtempSync(join(tmpdir(), 'gjsify-shim-')), files, names);
+    }
+}
+function writeShimDir(dir, files, names) {
+    for (const name of names) {
+        const path = join(dir, name);
+        if (existsSync(path) && readFileSync(path, 'utf8') === files[name])
+            continue;
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${process.pid}`;
+        try {
+            writeFileSync(tmp, files[name], { mode: 0o755 });
+            chmodSync(tmp, 0o755);
+            renameSync(tmp, path);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
+    }
+    return dir;
 }
 /**
  * The tree whose `node_modules` holds the running CLI and its prebuilds: the
@@ -268,22 +323,17 @@ export function nodeShimDir() {
  * resolves NOWHERE, and it is reachable only from a package script's PATH (see
  * {@link nodeShimDir}).
  */
-function writeNodeShim(dir, gjs, selfEntry, envPreamble) {
+function buildNodeShim(gjs, selfEntry, envPreamble) {
     if (!gjs)
-        return;
-    const sub = join(dir, NODE_SHIM_SUBDIR);
-    if (existsSync(join(sub, 'node')))
-        return; // inherited from a parent gjsify
+        return null;
     if (resolveBinOnPath('node'))
-        return; // a real Node is present — leave it alone
+        return null; // a real Node is present — leave it alone
     const interpreter = process.env.GJS_CONSOLE || 'gjs';
-    mkdirSync(sub, { recursive: true });
-    const shim = join(sub, 'node');
     // A leading FLAG is refused rather than forwarded: `node --test x.mjs` wants
     // Node's own test runner and `node -e '…'` an eval, neither of which
     // `--node-script` can honour, and yargs would take `--test` FOR the script
     // path (`unknown-options-as-args` turns an unknown flag into a positional).
-    writeFileSync(shim, '#!/bin/sh\n' +
+    return ('#!/bin/sh\n' +
         // Same SIP hop as the self-shim — see `buildSelfShimScript`.
         dyldCarryPreamble(process.platform, process.env) +
         'case "$1" in\n' +
@@ -293,6 +343,5 @@ function writeNodeShim(dir, gjs, selfEntry, envPreamble) {
         'esac\n' +
         // The same hop as the `gjsify` shim, so the same preamble.
         envPreamble +
-        `exec "${interpreter}" -m "${selfEntry}" run --node-script "$@"\n`, { mode: 0o755 });
-    chmodSync(shim, 0o755);
+        `exec "${interpreter}" -m "${selfEntry}" run --node-script "$@"\n`);
 }

package/lib/utils/publish-hold.d.ts

@@ -0,0 +1,89 @@
+import { type DependencyBlock, type WorkspacePin } from './publish-pins.js';
+import { classifyUnserved, type Classification, type UnservedClass } from './publish-status.js';
+/** Wait for a pin this long before holding. Covers the measured 252 s write lag (publish-readback.ts). */
+export declare const DEFAULT_HOLD_WAIT_MS = 300000;
+export interface HoldReason {
+    /** The dependency that is not installable. */
+    name: string;
+    version: string;
+    block: DependencyBlock;
+    /** `held` = the dependency was itself held in this run, so nothing of it was published. */
+    cls: UnservedClass | 'held';
+    detail: string;
+}
+export type LedgerEntry = 
+/** This run PUT the version, npm accepted it, and the packument does not serve it. */
+{
+    ev: 'unserved';
+    name: string;
+    version: string;
+    cls: UnservedClass;
+    detail: string;
+}
+/** This run did NOT publish the package, because of the listed dependencies. */
+ | {
+    ev: 'held';
+    name: string;
+    version: string;
+    reasons: HoldReason[];
+}
+/** A later probe found a version an earlier `unserved` entry recorded now served; it supersedes that entry. */
+ | {
+    ev: 'served';
+    name: string;
+    version: string;
+};
+export declare function appendLedger(path: string | undefined, entry: LedgerEntry): void;
+/** Tolerates a missing file (no entries yet) and skips unparseable lines rather than losing the rest. */
+export declare function readLedger(path: string | undefined): LedgerEntry[];
+/**
+ * The version a rewritten pin asks for, when the spec names exactly one:
+ * `0.59.1`, `^0.59.1`, `~0.59.1`. `undefined` for a range, tag or URL — those are
+ * not decidable against one version and the name-level guard covers them.
+ */
+export declare function pinVersion(spec: string): string | undefined;
+export interface FindUnavailablePinsInput {
+    registry: string;
+    pins: readonly WorkspacePin[];
+    ledger: readonly LedgerEntry[];
+    /** Where a re-probe that finds a ledger-`unserved` version served records it, so later dependents skip the probe. */
+    ledgerPath?: string;
+    /** Forwarded to the packument GETs, as the publish's own read-back does. */
+    authorization?: string;
+    statusToken?: string;
+    /** How long to wait for a pin that may merely be late. 0 = one probe, no waiting. */
+    waitBudgetMs: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    log?: (msg: string) => void;
+}
+/**
+ * Every pin whose exact version the registry does not serve (after waiting for
+ * one that may be late), with the reason. Empty = safe to publish.
+ *
+ * Three cheap exits come first, in order: the ledger already knows this version
+ * is unserved or held; one packument probe finds it served (nine in ten); the
+ * status endpoint says it can never be served. Only a pin that is none of those —
+ * possibly just late — pays the wait.
+ */
+export declare function findUnavailablePins(input: FindUnavailablePinsInput): Promise<HoldReason[]>;
+/** Only a `dependencies` edge holds a publish, as in the name-level guard; the rest are reported. */
+export declare const holdsPublish: (reason: HoldReason) => boolean;
+export declare function summariseReasons(reasons: readonly HoldReason[]): string;
+/** Classify a version THIS process PUT and could not read back, and write it to the ledger. */
+export declare function recordUnserved(input: {
+    ledgerPath: string | undefined;
+    registry: string;
+    name: string;
+    version: string;
+    verdict: Parameters<typeof classifyUnserved>[0];
+    statusToken?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<Classification>;
+/**
+ * The job-summary markdown for a ledger: what is unserved and why, what was held
+ * and why, and the exact command that publishes the held set once their
+ * dependencies are installable. `undefined` when nothing needs saying.
+ */
+export declare function renderLedgerSummary(entries: readonly LedgerEntry[], ref: string): string | undefined;