@vincentt-xr/cli 0.17.0 → 0.18.1

package/dist/publish/command.js

@@ -10,25 +10,69 @@
 // branch is assertable without a real API, a real terminal or a real S3.
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { PublishApiError, abandonUpload, commitUpload, openUpload, readProject, } from "./api.js";
+import { MalformedCommitResponse, PublishApiError, abandonUpload, commitUpload, openUpload, readProject, } from "./api.js";
 import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadFailed, uploadAll } from "./upload.js";
+import { UploadExpired, UploadFailed, uploadAll } from "./upload.js";
+/** Re-opens after an expired upload link, per publish, before giving up. */
+export const MAX_REOPENS = 2;
+import { waitUntilServing } from "./visibility.js";
 import * as copy from "./copy.js";
 import { publishedLimitRefused, resolveCountLimit, storageCeilingRefused, } from "../shared/countLimit.js";
+import { AuthExpiredError, authExpiredLines } from "../shared/authError.js";
+import { EXIT } from "../lib/exitCodes.js";
+import { apiFetch, isTransportError } from "../shared/http.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
+import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, } from "../lib/settings.js";
+import { settingsRefusal } from "../lib/settingsCopy.js";
+import { rootAbsoluteFindings } from "./fit.js";
 const COMMIT_RETRIES = 3;
 const COMMIT_RETRY_DELAY_MS = 2000;
 export async function publishCommand(deps, opts = {}) {
+    let committed;
+    const code = await runPublish(deps, opts, (r) => {
+        committed = r;
+    });
+    if (opts.json) {
+        const report = code === 0 && committed ? committed : { state: "failed", exitCode: code };
+        (deps.emit ?? deps.print)(JSON.stringify(report));
+    }
+    return code;
+}
+async function runPublish(deps, opts, onCommitted) {
+    // The binding lookup is local. Its directory is the project root: the settings
+    // file is read there and a relative output or --dist resolves against it,
+    // never against the working directory.
+    const binding = await deps.binding();
+    const root = binding?.dir ?? deps.cwd;
+    // Settings resolve first, before the sign-in gate and before any request.
+    let settings;
+    let hasFile;
+    try {
+        const file = await (deps.readSettings ?? readSettings)(root);
+        hasFile = file !== undefined;
+        settings = resolveSettings({ buildOutput: opts.distDir }, file, TEMPLATE_DEFAULTS, [
+            "build",
+        ]);
+    }
+    catch (err) {
+        if (err instanceof SettingsError) {
+            for (const l of settingsRefusal(err, "publish"))
+                deps.print(l);
+            return 1;
+        }
+        throw err;
+    }
+    // `undefined` → the template's own command; `null` → a file records none.
+    const buildCommand = settings.buildCommand?.value ?? (hasFile ? null : undefined);
     // The gate is LOCAL and NOTHING IS ATTEMPTED — no request, no partial upload.
     if (!(await deps.token())) {
         for (const l of copy.notSignedIn())
             deps.print(l);
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
-    const binding = await deps.binding();
     if (!binding) {
         deps.print("✗ This folder isn't linked to a project.");
         deps.print("");
@@ -36,18 +80,34 @@ export async function publishCommand(deps, opts = {}) {
         deps.print("  vincentt create             Register a new project for this folder");
         return 1;
     }
-    const distDir = path.resolve(deps.cwd, opts.distDir ?? "dist");
+    const distDir = path.resolve(root, settings.buildOutput.value);
+    const output = outputLabelOf(root, distDir, settings.buildOutput.source);
     // Everything below the manifest build happens before a single request. The
     // creator learns about a too-large build in the same second they would
     // otherwise have started a ten-minute upload.
     let manifest;
     try {
-        manifest = await buildManifest(distDir);
+        manifest = await buildManifest(distDir, { repoRoot: root });
     }
     catch (err) {
         if (err instanceof ManifestError) {
-            for (const l of manifestErrorLines(err, distDir))
+            if (err.reason === "secret_path" || err.reason === "lfs_pointer") {
+                deps.print(copy.headerLine(await projectLabel(deps, binding.slug), await orgOf(deps)));
+                deps.print(copy.readingLine(err.stats?.files ?? 0, err.stats?.bytes ?? 0, output));
+                const lines = err.reason === "secret_path"
+                    ? copy.secretFiles(err.paths, output)
+                    : copy.lfsPointers(err.paths, output, buildCommand ?? undefined);
+                for (const l of lines)
+                    deps.print(l);
+                return 1;
+            }
+            const origin = {
+                value: settings.buildOutput.value,
+                source: settings.buildOutput.source,
+            };
+            for (const l of manifestErrorLines(err, distDir, { root, origin, buildCommand })) {
                 deps.print(l);
+            }
             return 1;
         }
         throw err;
@@ -55,13 +115,13 @@ export async function publishCommand(deps, opts = {}) {
     const violation = checkBounds(manifest);
     if (violation) {
         deps.print(copy.headerLine(await projectLabel(deps, binding.slug), await orgOf(deps)));
-        deps.print(copy.readingLine(manifest.files.length, manifest.totalBytes));
+        deps.print(copy.readingLine(manifest.files.length, manifest.totalBytes, output));
         for (const l of copy.tooLarge(violation))
             deps.print(l);
         return 1;
     }
     const cfg = await deps.config();
-    const fetchImpl = deps.fetchImpl ?? fetch;
+    const fetchImpl = deps.fetchImpl ?? apiFetch;
     // ONE call before the checklist. liveVersion and livePublishedAt ride it, so
     // the republish line costs no second round trip.
     let project;
@@ -69,6 +129,8 @@ export async function publishCommand(deps, opts = {}) {
         project = await readProject(cfg, binding.projectId, fetchImpl);
     }
     catch (err) {
+        if (err instanceof AuthExpiredError)
+            return authExpired(deps);
         if (err instanceof PublishApiError && err.status === 404) {
             deps.print(`✗ ${err.message}`);
             deps.print("");
@@ -82,6 +144,20 @@ export async function publishCommand(deps, opts = {}) {
     const isFirstPublish = project.firstPublishedAt === null;
     const nextVersion = (project.highestVersion ?? 0) + 1;
     const orgName = await orgOf(deps);
+    // Refused here, before the prompt and before a byte moves: the api refuses
+    // every publish of a held project, and it used to do so only at commit.
+    if (project.publishState === "held_by_platform") {
+        deps.print("");
+        deps.print(copy.headerLine(project.name, orgName));
+        deps.print(copy.readingLine(manifest.files.length, manifest.totalBytes, output));
+        for (const l of copy.heldByPlatform(address, {
+            orgSlug: (await deps.orgSlug?.()) || undefined,
+            consoleUrl: deps.consoleUrl,
+        })) {
+            deps.print(l);
+        }
+        return 1;
+    }
     // A non-interactive stdin with no --yes must REFUSE rather than assume yes.
     if (!opts.yes && !deps.isTTY) {
         deps.print("");
@@ -93,7 +169,9 @@ export async function publishCommand(deps, opts = {}) {
         deps.print("");
         return 1;
     }
-    const findings = await classifyDist(distDir, new Set(manifest.files.map((f) => f.path)), (abs) => fs.readFile(abs, "utf8"), (dir, rel) => path.join(dir, ...rel.split("/")), { expectedHost: address });
+    const manifestPaths = new Set(manifest.files.map((f) => f.path));
+    const findings = await classifyDist(distDir, manifestPaths, (abs) => fs.readFile(abs, "utf8"), (dir, rel) => path.join(dir, ...rel.split("/")), { expectedHost: address });
+    const rootAbsolute = rootAbsoluteFindings(await readHtmlFiles(distDir, manifest), manifestPaths);
     const checklistInput = {
         projectName: project.name,
         orgName,
@@ -102,6 +180,8 @@ export async function publishCommand(deps, opts = {}) {
         totalBytes: manifest.totalBytes,
         nextVersion,
         findings,
+        output,
+        rootAbsolute,
     };
     let promptLine;
     let defaultYes;
@@ -119,6 +199,16 @@ export async function publishCommand(deps, opts = {}) {
         // accidental Enter must do nothing.
         defaultYes = false;
     }
+    else if (project.publishState !== "live") {
+        // not_serving, or a state newer than this CLI. Only `live` may say "Live at".
+        const known = project.publishState === "not_serving";
+        for (const l of copy.notServingChecklist(checklistInput, known))
+            deps.print(l);
+        promptLine = known
+            ? copy.republishPrompt(nextVersion)
+            : copy.unknownStatePrompt(nextVersion);
+        defaultYes = known;
+    }
     else {
         for (const l of copy.republishChecklist({
             ...checklistInput,
@@ -154,23 +244,35 @@ export async function publishCommand(deps, opts = {}) {
         address,
         liveVersion: project.liveVersion ?? undefined,
         fetchImpl,
+        // The S3 leg sets its own per-file deadline, sized to the file.
+        uploadFetch: deps.fetchImpl ?? ((input, init) => globalThis.fetch(input, init)),
         builtWith,
         org: {
             name: orgName || undefined,
             slug: (await deps.orgSlug?.()) || undefined,
             consoleUrl: deps.consoleUrl,
         },
+        probeFetch: deps.probeFetch ??
+            deps.fetchImpl ??
+            ((input, init) => globalThis.fetch(input, init)),
+        onCommitted,
     });
 }
 async function runUpload(deps, cfg, i) {
+    const open = () => openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
+    const openFailed = (err) => {
+        if (err instanceof AuthExpiredError)
+            return authExpired(deps);
+        for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
+            deps.print(l);
+        return 1;
+    };
     let opened;
     try {
-        opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
+        opened = await open();
     }
     catch (err) {
-        for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
-            deps.print(l);
-        return 1;
+        return openFailed(err);
     }
     deps.print(copy.uploadStart(i.manifest.files.length));
     const progress = createProgress({
@@ -180,30 +282,59 @@ async function runUpload(deps, cfg, i) {
         now: deps.now,
     });
     const startedAt = deps.now();
-    try {
-        await uploadAll({
-            distDir: i.distDir,
-            targets: opened.uploads,
-            manifest: i.manifest.files,
-            onProgress: (p) => progress.update(p),
-            fetchImpl: i.fetchImpl,
-        });
+    let reopens = 0;
+    let uploadErr;
+    for (;;) {
+        try {
+            await uploadAll({
+                distDir: i.distDir,
+                targets: opened.uploads,
+                manifest: i.manifest.files,
+                onProgress: (p) => progress.update(p),
+                fetchImpl: i.uploadFetch,
+                sleep: deps.sleep,
+            });
+            break;
+        }
+        catch (err) {
+            if (!(err instanceof UploadExpired) || reopens >= MAX_REOPENS) {
+                uploadErr = err;
+                break;
+            }
+        }
+        // An expired link: re-open for fresh URLs. An api that resumes returns the
+        // same upload with only the files still missing; one that does not returns
+        // a new upload and every file is sent again.
+        reopens += 1;
+        try {
+            opened = await open();
+        }
+        catch (err) {
+            progress.finish();
+            return openFailed(err);
+        }
     }
-    catch (err) {
+    if (uploadErr !== undefined) {
+        const err = uploadErr;
         progress.finish();
-        await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
+        // A retryable failure (the network, S3 5xx, links that kept expiring) keeps
+        // the upload open so the next `vincentt publish` resumes it and sends only
+        // what is missing. Anything else is abandoned.
+        const resumable = err instanceof UploadExpired || (err instanceof UploadFailed && err.retryable);
+        if (!resumable)
+            await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
         if (err instanceof UploadFailed && err.badDigest) {
             for (const l of copy.badDigest(err.path, i.address, i.liveVersion))
                 deps.print(l);
             return 1;
         }
-        const failedPath = err instanceof UploadFailed ? err.path : "a file";
+        const failedPath = err instanceof UploadFailed || err instanceof UploadExpired ? err.path : "a file";
         deps.print("");
         deps.print(`✗ Uploading ${failedPath} failed.`);
         deps.print("");
         deps.print(i.liveVersion === undefined
-            ? `  Your live address is unchanged — ${i.address}.`
-            : `  Your live address is unchanged — ${i.address} is still serving v${i.liveVersion}.`);
+            ? `  Your live address is unchanged: ${i.address}.`
+            : `  Your live address is unchanged: ${i.address} is still serving v${i.liveVersion}.`);
         deps.print("");
         deps.print("  Publish again:  vincentt publish");
         deps.print("");
@@ -215,30 +346,41 @@ async function runUpload(deps, cfg, i) {
     return commitWithHealing(deps, cfg, i, opened.uploadId);
 }
 /**
- * The commit, with the healing retry. A 502 publish_flip_failed is retried
- * automatically — up to 3 attempts, 2s apart — because commit is idempotent on
- * uploadId and the retry is exactly what the healing path was built for.
- * Surfacing a 502 to a creator whose bytes are all safely stored and whose
- * publish will succeed on the next call would be manufacturing an incident.
+ * The commit, with the healing retry. Commit is idempotent on uploadId, so two
+ * failures are retried automatically, up to 3 attempts with the wait doubling
+ * from 2s: a 502 publish_flip_failed (what the healing path was built for), and
+ * a request whose answer never arrived (a dropped connection, a deadline, a 2xx
+ * body that is not a commit response). Surfacing either to a creator whose bytes
+ * are all safely stored would be manufacturing an incident.
+ *
+ * When the last attempt's answer never arrived, the outcome is unknown and the
+ * copy says so: the version may already be live.
  */
 async function commitWithHealing(deps, cfg, i, uploadId) {
     let announcedSlow = false;
     for (let attempt = 1; attempt <= COMMIT_RETRIES; attempt++) {
         try {
             const result = await commitUpload(cfg, i.projectId, uploadId, i.fetchImpl);
-            for (const l of copy.liveAt(result.liveUrl, result.version))
-                deps.print(l);
+            await reportVisibility(deps, i, result);
             return 0;
         }
         catch (err) {
-            if (!(err instanceof PublishApiError))
-                throw err;
+            // The token can lapse during a long upload. The files are stored and the
+            // live address is unchanged, so signing in and publishing again is safe.
+            if (err instanceof AuthExpiredError)
+                return authExpired(deps);
+            const unanswered = err instanceof MalformedCommitResponse || isTransportError(err);
             // The plan limit is a 409 and falls past this branch deliberately. It is
             // the interlock refusing, not the flip failing, and retrying it three
             // times would be the retry loop the refusal exists to stop.
-            if (err.code === "publish_flip_failed" || err.status === 502) {
+            const flipFailed = err instanceof PublishApiError &&
+                (err.code === "publish_flip_failed" || err.status === 502);
+            if (unanswered || flipFailed) {
                 if (attempt === COMMIT_RETRIES) {
-                    for (const l of copy.flipFailed(i.address, i.liveVersion))
+                    const lines = unanswered
+                        ? copy.commitOutcomeUnknown(i.address, i.liveVersion)
+                        : copy.flipFailed(i.address, i.liveVersion);
+                    for (const l of lines)
                         deps.print(l);
                     return 1;
                 }
@@ -248,9 +390,11 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
                     deps.print(copy.takingLonger());
                     announcedSlow = true;
                 }
-                await deps.sleep(COMMIT_RETRY_DELAY_MS);
+                await deps.sleep(COMMIT_RETRY_DELAY_MS * 2 ** (attempt - 1));
                 continue;
             }
+            if (!(err instanceof PublishApiError))
+                throw err;
             for (const l of commitErrorLines(err, i.address, i.liveVersion, i.org))
                 deps.print(l);
             return 1;
@@ -258,6 +402,32 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
     }
     return 1;
 }
+/**
+ * "Live" is printed only once the public address serves this commit's index.html.
+ * Running out the wait is still exit 0: the commit happened, only the edge lags.
+ */
+async function reportVisibility(deps, i, result) {
+    const index = i.manifest.files.find((f) => f.path === "index.html");
+    const { visible, waitedMs } = index
+        ? await waitUntilServing(result.liveUrl, index.sha256, {
+            fetchImpl: i.probeFetch,
+            now: deps.now,
+            sleep: deps.sleep,
+            onWaiting: () => deps.print(copy.propagating(result.liveUrl, result.version)),
+        })
+        : { visible: true, waitedMs: 0 };
+    const lines = visible
+        ? copy.liveAt(result.liveUrl, result.version)
+        : copy.notYetVisible(result.liveUrl, result.version);
+    for (const l of lines)
+        deps.print(l);
+    i.onCommitted({
+        state: visible ? "live" : "committed_not_visible",
+        version: result.version,
+        liveUrl: result.liveUrl,
+        waitedMs,
+    });
+}
 /**
  * The plan-limit refusal, from the detail the API sends. It is reachable from
  * open AND from commit, because the interlock lives at the port and every flip
@@ -284,6 +454,10 @@ function commitErrorLines(err, address, liveVersion, org) {
     switch (err.code) {
         case "unavailable_plan_limit":
             return planLimitLines(err, org);
+        case "published_limit":
+            // Two opens admitted in the same org race to go live; commit re-checks and
+            // refuses the loser, whose version the api keeps stored.
+            return publishedLimitRefused(resolveCountLimit(err.detail, org), "commit");
         case "publish_expired":
             return copy.publishExpired(address, liveVersion);
         case "publish_contended":
@@ -298,8 +472,8 @@ function commitErrorLines(err, address, liveVersion, org) {
                 `✗ ${err.message}`,
                 "",
                 liveVersion === undefined
-                    ? `  Your live address is unchanged — ${address}.`
-                    : `  Your live address is unchanged — ${address} is still serving v${liveVersion}.`,
+                    ? `  Your live address is unchanged: ${address}.`
+                    : `  Your live address is unchanged: ${address} is still serving v${liveVersion}.`,
                 "",
                 "  Publish again:  vincentt publish",
                 "",
@@ -319,12 +493,10 @@ function openErrorLines(err, address, liveVersion, org) {
     if (err.code === "unavailable_plan_limit") {
         return planLimitLines(err, org);
     }
-    // The two count/ceiling refusals of this change. Both land at OPEN — before a
-    // presigned URL is minted and before a byte moves — which is why they are here
-    // and not in commitErrorLines: neither is reachable from commit.
     if (err.code === "published_limit") {
-        return publishedLimitRefused(resolveCountLimit(err.detail, org));
+        return publishedLimitRefused(resolveCountLimit(err.detail, org), "open");
     }
+    // Refused only at open, before a presigned URL is minted.
     if (err.code === "storage_ceiling") {
         // It takes no detail. The body is `{"limit":"storage"}` and names nothing
         // else by design — the ceiling is an abuse ceiling, not a plan limit.
@@ -345,8 +517,8 @@ function openErrorLines(err, address, liveVersion, org) {
         `✗ ${err.message}`,
         "",
         liveVersion === undefined
-            ? `  Your live address is unchanged — ${address}.`
-            : `  Your live address is unchanged — ${address} is still serving v${liveVersion}.`,
+            ? `  Your live address is unchanged: ${address}.`
+            : `  Your live address is unchanged: ${address} is still serving v${liveVersion}.`,
         "",
         "  Nothing was uploaded.",
         "",
@@ -361,13 +533,46 @@ function openErrorLines(err, address, liveVersion, org) {
 function numericLimit(limit) {
     return typeof limit === "number" ? limit : 0;
 }
-function manifestErrorLines(err, distDir) {
+function manifestErrorLines(err, distDir, ctx) {
     if (err.reason === "no_dist")
-        return copy.noDist(distDir);
+        return copy.noDist(distDir, ctx.buildCommand);
     if (err.reason === "no_index_html")
-        return copy.noIndexHtml(distDir);
+        return copy.noIndexHtml(distDir, ctx.buildCommand);
+    if (err.reason === "output_is_repo_root")
+        return copy.outputIsRoot(ctx.origin);
+    if (err.reason === "output_in_hidden") {
+        return copy.outputInHidden(path.relative(ctx.root, distDir).split(path.sep).join("/"), err.offendingPath);
+    }
+    if (err.reason === "output_outside_repo") {
+        return copy.outputOutside(path.relative(ctx.root, distDir).split(path.sep).join("/"));
+    }
     return copy.badPath(err.reason, err.offendingPath);
 }
+/** `dist/` for the default; the resolved folder and its source otherwise. */
+function outputLabelOf(root, distDir, source) {
+    const rel = path.relative(root, distDir).split(path.sep).join("/");
+    const folder = `${rel || "."}/`;
+    const sourceNote = source === "vincentt.json"
+        ? "(from vincentt.json)"
+        : source === "flag"
+            ? "(from --dist)"
+            : "";
+    return { folder, sourceNote };
+}
+/** Every `.html` in the manifest, for the root-absolute reference check. */
+async function readHtmlFiles(distDir, manifest) {
+    const out = [];
+    for (const f of manifest.files) {
+        if (!f.path.toLowerCase().endsWith(".html"))
+            continue;
+        const html = await fs
+            .readFile(path.join(distDir, ...f.path.split("/")), "utf8")
+            .catch(() => undefined);
+        if (html !== undefined)
+            out.push({ file: f.path, html });
+    }
+    return out;
+}
 /**
  * The address as a creator reads it: the host, never the scheme. `liveUrl` is
  * server-computed (the apex differs per environment), so it is the authority and
@@ -383,6 +588,12 @@ function addressOf(project) {
         return project.liveUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
     }
 }
+/** The api refused the token: the sign-in remedy, and the not-signed-in exit code. */
+function authExpired(deps) {
+    for (const l of authExpiredLines())
+        deps.print(l);
+    return EXIT.NOT_AUTHENTICATED;
+}
 async function orgOf(deps) {
     return (await deps.orgName?.()) ?? "";
 }

package/dist/publish/copy.d.ts

@@ -1,5 +1,7 @@
 import type { FileFindings } from "./classify.js";
 import type { BoundViolation } from "./bounds.js";
+import type { RootAbsoluteFinding } from "./fit.js";
+import type { Offender } from "./manifest.js";
 export declare function truncate(value: string, max?: number): string;
 /** Bytes as the creator reads them. Decimal MB, matching what a build tool prints. */
 export declare function formatBytes(bytes: number): string;
@@ -24,7 +26,7 @@ export declare function relativeTime(iso: string, now: number): string;
  * A FINDING IS NEVER A COUNT. No "2 issues found", no summary line, and no exit
  * code that varies with findings.
  */
-export declare function findingLines(byFile: FileFindings[], withSubtitle: boolean): string[];
+export declare function findingLines(byFile: FileFindings[], withSubtitle: boolean, folder?: string): string[];
 /**
  * Mandatory and always present. A screen with a red ✗ on it reads as a gate
  * unless it explicitly says otherwise, and a creator who believes the platform
@@ -40,8 +42,29 @@ export interface ChecklistInput {
     totalBytes: number;
     nextVersion: number;
     findings: FileFindings[];
+    /** Absent for the template's default `dist/`. */
+    output?: OutputLabel;
+    /** Root-absolute references that do not resolve. The section is absent when empty. */
+    rootAbsolute?: RootAbsoluteFinding[];
 }
-export declare function readingLine(fileCount: number, totalBytes: number): string;
+/**
+ * The `Paths from the root` section: a second section of the checklist, same
+ * geometry as the link preview. Absent when there are no findings, never an
+ * empty heading. One explanation for the whole section.
+ */
+export declare function pathsFromRootLines(findings: RootAbsoluteFinding[] | undefined, folder?: string): string[];
+/**
+ * The output folder as the creator reads it, `dist/` for the template. The
+ * source is appended only when it is not the default, so the template's
+ * transcript is unchanged.
+ */
+export interface OutputLabel {
+    /** Project-relative, with a trailing slash: `dist/`, `build/`. */
+    folder: string;
+    /** `(from vincentt.json)` / `(from --dist)`, or empty for the default. */
+    sourceNote: string;
+}
+export declare function readingLine(fileCount: number, totalBytes: number, output?: OutputLabel): string;
 export declare function headerLine(projectName: string, orgName: string): string;
 /**
  * Flow L22 — the single most consequential screen in the product, and its ORDER
@@ -88,6 +111,28 @@ export declare function republishPrompt(version: number): string;
  */
 export declare function offlineChecklist(i: ChecklistInput): string[];
 export declare function offlinePrompt(version: number): string;
+/**
+ * The address has published before but serves nothing now (`not_serving`), or
+ * the api reports a state this CLI does not know. Neither may say "Live at":
+ * the creator would share an address that answers with nothing.
+ */
+export declare function notServingChecklist(i: ChecklistInput, stateKnown: boolean): string[];
+/** `[y/N]`: the CLI cannot say what this publish changes, so Enter does nothing. */
+export declare function unknownStatePrompt(version: number): string;
+/**
+ * The project is `held_by_platform`: Vincentt took the org's addresses offline
+ * over its traffic allowance, and the api refuses every publish until they are
+ * restored. Refused BEFORE the upload, because uploading a whole build only to
+ * be refused at commit is the retry loop this copy exists to stop.
+ *
+ * The project read carries no figures, so this names none. It shares
+ * planLimitRefused's voice: the platform is the actor, the remedy is outside
+ * the CLI, and nothing was lost.
+ */
+export declare function heldByPlatform(address: string, org?: {
+    orgSlug?: string;
+    consoleUrl?: string;
+}): string[];
 /**
  * f1's line verbatim, with f4's reason. Note what is ABSENT, deliberately: f3's
  * "your local dev loop doesn't need one" paragraph. It is the right copy for
@@ -110,9 +155,24 @@ export declare function notSignedIn(): string[];
  * have.
  */
 export declare function tooLarge(v: BoundViolation): string[];
-/** No dist at all, or no index.html at its root. Zero network calls. */
-export declare function noDist(distDir: string): string[];
-export declare function noIndexHtml(distDir: string): string[];
+export declare function noDist(distDir: string, buildCommand?: string | null): string[];
+export declare function noIndexHtml(distDir: string, buildCommand?: string | null): string[];
+/** How the output was named, for the leak refusals' "why" sentence. */
+export interface OutputOrigin {
+    /** The value as given: `build.output` or `--dist`. */
+    value: string;
+    source: "vincentt.json" | "flag" | "default";
+}
+/** Flow U1 — the output is the project folder itself. */
+export declare function outputIsRoot(o: OutputOrigin): string[];
+/** Flow U1 — the output lies outside the project. `shown` is project-relative. */
+export declare function outputOutside(shown: string): string[];
+/** Flow U1 — the output is, or sits inside, `.git` or `.vincentt`. `shown` is project-relative. */
+export declare function outputInHidden(shown: string, hidden: string): string[];
+/** Flow U1 — hidden names or symlinks that would leak. After the header and reading line. */
+export declare function secretFiles(paths: Offender[], output?: OutputLabel): string[];
+/** Flow U1 — Git LFS pointer files. The recorded build.command, verbatim, when there is one. */
+export declare function lfsPointers(paths: Offender[], output?: OutputLabel, buildCommand?: string): string[];
 /** A local path rule the creator's own build broke. Local, before any request. */
 export declare function badPath(reason: string, offending: string): string[];
 /** The one redrawn line in f4. A bounded progress bar with a known total is not a stream. */
@@ -130,6 +190,13 @@ export declare function finishing(): string;
  * page, decide publish is broken, and publish again.
  */
 export declare function liveAt(liveUrl: string, version: number): string[];
+/** Prints once the commit succeeded and the address is still serving the previous bytes. */
+export declare function propagating(liveUrl: string, version: number): string;
+/**
+ * The wait ran out. The publish DID commit, so this is a success, and it says so
+ * plainly: a creator told "not yet" without that will publish again.
+ */
+export declare function notYetVisible(liveUrl: string, version: number): string[];
 /** Prints only if a retry is needed. It says nothing about a failure, because nothing has failed yet. */
 export declare function takingLonger(): string;
 export interface PlanLimitInput {
@@ -170,6 +237,12 @@ export declare function planLimitRefused(i: PlanLimitInput): string[];
 export declare function publishExpired(address: string, liveVersion?: number): string[];
 /** All three retries failed. "Nothing was lost" is the true and load-bearing sentence. */
 export declare function flipFailed(address: string, liveVersion?: number): string[];
+/**
+ * The commit's answer never arrived (the connection dropped or the api stopped
+ * answering), so whether the address switched is unknown. It says so, rather than
+ * claiming either outcome, and names the one check that settles it.
+ */
+export declare function commitOutcomeUnknown(address: string, liveVersion?: number): string[];
 /**
  * Two sentences, no explanation of version allocation. The real case is a
  * teammate and an agent publishing in the same second, and "someone else