@vincentt-xr/cli 0.2.0 → 0.3.0

package/dist/cli/args.d.ts

@@ -5,6 +5,7 @@
  * usage instead of running the (side-effectful) verb.
  */
 export declare function isHelpInvocation(args: string[]): boolean;
+export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir
  * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is

package/dist/cli/args.js

@@ -18,9 +18,19 @@ const BOOLEAN_FLAGS = new Set([
     "--stop",
     "--no-install",
     "--allow-custom-api",
+    "--yes",
     "--help",
     "-h",
 ]);
+/**
+ * Flags the CLI deliberately does NOT have. The checklist reports and never
+ * writes: a suggested value is one keystroke from a tool that writes it, and
+ * writing to the creator's source is a named boundary.
+ */
+const REFUSED_FLAGS = new Set(["--fix", "--write-meta"]);
+export function refusedFlag(args) {
+    return args.find((a) => REFUSED_FLAGS.has(a.split("=")[0]));
+}
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir
  * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is

package/dist/cli/index.js

@@ -21,7 +21,10 @@ import { getMe, ProjectUnreachableError } from "../lib/backend.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
 import { whoamiCommand } from "../lib/whoami.js";
-import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, projectPublish, } from "../lib/lifecycle.js";
+import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, } from "../lib/lifecycle.js";
+import { publishCommand } from "../publish/command.js";
+import { stdinConfirm } from "../publish/prompt.js";
+import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview } from "../lib/relayInfo.js";
@@ -29,7 +32,7 @@ import { mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../p
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
-import { isHelpInvocation, positionalArgs } from "./args.js";
+import { isHelpInvocation, positionalArgs, refusedFlag } from "./args.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
 // CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
 const DEFAULT_CONSOLE_URL = "https://vincentt.app";
@@ -186,17 +189,54 @@ async function unlink() {
         config: () => resolveConfig(cwd),
     });
 }
+/**
+ * `vincentt publish` — Flows L22-L31.
+ *
+ * The whole gate lives here: the checklist, the permanence disclosure, the
+ * confirmation, the upload and the live URL. There is no browser step in
+ * publishing, not on the first publish, not ever.
+ */
 async function publish() {
-    await requireLogin();
-    const result = await projectPublish(projectDir(), {
-        distDir: flag("--dist"),
-        note: flag("--note"),
-        allowCustomApi: has("--allow-custom-api"),
-        warn: (l) => console.log(l),
-    });
-    console.log(result.message);
-    if (result.notBound)
+    const refused = refusedFlag(argv);
+    if (refused) {
+        console.log(`✗ There's no \`${refused}\` option.`);
+        console.log("");
+        console.log("  The link-preview check reports what it found; it never edits your");
+        console.log("  source. Fix the tags in your own files, rebuild, then publish again.");
         process.exitCode = 1;
+        return;
+    }
+    const cwd = projectDir();
+    process.exitCode = await publishCommand({
+        print: (l) => console.log(l),
+        write: (s) => process.stdout.write(s),
+        confirm: stdinConfirm(),
+        cwd,
+        config: () => resolveConfig(cwd, {
+            allowCustomApi: has("--allow-custom-api"),
+            warn: (l) => console.log(l),
+        }),
+        binding: async () => {
+            const located = await locateProjectBinding(cwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        token: currentToken,
+        isTTY: Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        orgName: activeOrgName,
+    }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes") });
+}
+/** Flow L30 — the six verbs that are console actions, answered rather than rejected. */
+async function consoleOnly(verb) {
+    const cwd = projectDir();
+    process.exitCode = await consoleVerbCommand({
+        print: (l) => console.log(l),
+        projectId: async () => (await locateProjectBinding(cwd))?.binding.projectId,
+        consoleUrl: flag("--console") ?? process.env.VINCENTT_CONSOLE_URL,
+    }, verb);
 }
 /**
  * `vincentt preview` — Flows L13-L21.
@@ -497,6 +537,7 @@ function usage() {
         `  unlink             Disconnect this folder from its project\n\n` +
         `Dev loop\n` +
         `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
+        `                       [--dist <path>] [--note <s>] [--yes]\n` +
         `  preview            Serve the app at an https link a phone can open\n` +
         `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n\n` +
         `Diagnostics (need a running preview)\n` +
@@ -555,6 +596,11 @@ async function main() {
         case "relay":
             return relay();
         default:
+            // Flow L30: rolling back and taking an address offline are console
+            // actions, and a bare "unknown command" here would be the product failing
+            // to answer a question it knows the answer to.
+            if (cmd !== undefined && isConsoleOnlyVerb(cmd))
+                return consoleOnly(cmd);
             console.error(`Unknown command: ${cmd}\n`);
             usage();
             process.exitCode = 1;

package/dist/lib/backend.d.ts

@@ -19,13 +19,6 @@ export interface CreatedProject {
     orgId: string;
     liveUrl: string;
 }
-export interface PublishResult {
-    version: number;
-    /** Immutable versioned URL (<slug>.<apex>/v<n>/). */
-    url: string;
-    /** Stable live alias (<slug>.<apex>/). */
-    liveUrl: string;
-}
 export declare class BackendError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
@@ -70,15 +63,6 @@ export declare function reapTunnel(cfg: ResolvedConfig, projectId: string, ref:
 }): Promise<void>;
 /** Recursively list files under `dir`, returning dir-relative POSIX paths. */
 export declare function walkDir(dir: string, base?: string): Promise<string[]>;
-/**
- * Upload a locally-built dist and make it live. Each file rides as a multipart
- * part whose filename is its dist-relative path (the backend reconstructs the
- * tree). Requires an index.html at the dist root.
- */
-export declare function publishUpload(cfg: ResolvedConfig, projectId: string, distDir: string, opts?: {
-    note?: string;
-    commitSha?: string;
-}): Promise<PublishResult>;
 export interface MeMembership {
     orgId: string;
     orgSlug: string;

package/dist/lib/backend.js

@@ -178,40 +178,6 @@ export async function walkDir(dir, base = dir) {
     }
     return out;
 }
-/**
- * Upload a locally-built dist and make it live. Each file rides as a multipart
- * part whose filename is its dist-relative path (the backend reconstructs the
- * tree). Requires an index.html at the dist root.
- */
-export async function publishUpload(cfg, projectId, distDir, opts = {}) {
-    const files = await walkDir(distDir);
-    if (!files.includes("index.html")) {
-        throw new BackendError(`dist at ${distDir} has no index.html at its root — did the build run?`);
-    }
-    const form = new FormData();
-    // The real dist-relative paths ride as an ordered manifest — a multipart filename
-    // can't carry a directory (FormData strips it to a basename), so the backend maps
-    // paths[i] → files[i] to rebuild the tree.
-    form.append("paths", JSON.stringify(files));
-    for (const rel of files) {
-        const bytes = await fs.readFile(path.join(distDir, rel));
-        // Uint8Array (Buffer) is a valid BlobPart; the filename is cosmetic (the backend
-        // uses the manifest), but pass the basename so server logs read sensibly.
-        form.append("files", new Blob([bytes]), path.basename(rel));
-    }
-    if (opts.note)
-        form.append("note", opts.note);
-    if (opts.commitSha)
-        form.append("commitSha", opts.commitSha);
-    const res = await authFetch(cfg, `/projects/${projectId}/publish/upload`, {
-        method: "POST",
-        body: form,
-    });
-    if (!res.ok) {
-        throw new BackendError(authFailureMessage("publish failed", res.status, await safeText(res)), res.status);
-    }
-    return (await res.json());
-}
 /** Resolve the signed-in identity for `vincentt whoami`. Throws on any non-2xx so
  *  the caller can degrade to "token present, unverified". */
 export async function getMe(cfg) {

package/dist/lib/lifecycle.d.ts

@@ -59,14 +59,22 @@ export interface PublishOptions {
      * has already happened (or thrown).
      */
     warn?: (line: string) => void;
+    /** Skip the confirmation. REFUSED on a first publish; see publishCommand. */
+    yes?: boolean;
 }
 export interface PublishOutcome {
+    /** The full transcript, exactly as the CLI prints it. */
     message: string;
-    notBound: boolean;
-    version?: number;
-    liveUrl?: string;
-    url?: string;
+    exitCode: number;
 }
+/**
+ * The shared `publish` orchestration behind both `vincentt publish` and the MCP
+ * `project_publish` tool, so the two surfaces can never diverge.
+ *
+ * MCP has no terminal, so it is a non-TTY caller: the command refuses without
+ * `--yes` rather than assuming consent, and refuses `--yes` outright on a first
+ * publish. An agent cannot make an address permanent.
+ */
 export declare function projectPublish(projectCwd: string, opts?: PublishOptions): Promise<PublishOutcome>;
 export declare function getActivePreview(): RunningPreview | null;
 export interface PreviewStartResult {

package/dist/lib/lifecycle.js

@@ -3,9 +3,9 @@
 // lower-level pieces (backend calls, scaffold, preview, diagnostics); no CLI or
 // MCP SDK concerns leak in here. Both surfaces render the returned data their
 // own way.
-import path from "node:path";
-import { getMe, gitHeadSha, publishUpload } from "./backend.js";
+import { getMe } from "./backend.js";
 import { createCommand } from "./projects.js";
+import { publishCommand } from "../publish/command.js";
 import { activeOrgSlug, resolveActiveOrg } from "./org.js";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
@@ -68,36 +68,42 @@ export async function resolveOrgForCommand(cfg, input) {
             : "✗ No active organization.\n\n  Run `vincentt whoami` to see which organizations you belong to,\n  then re-run with `--org <slug>`.",
     };
 }
+/**
+ * The shared `publish` orchestration behind both `vincentt publish` and the MCP
+ * `project_publish` tool, so the two surfaces can never diverge.
+ *
+ * MCP has no terminal, so it is a non-TTY caller: the command refuses without
+ * `--yes` rather than assuming consent, and refuses `--yes` outright on a first
+ * publish. An agent cannot make an address permanent.
+ */
 export async function projectPublish(projectCwd, opts = {}) {
-    const cfg = await resolveConfig(projectCwd, {
-        allowCustomApi: opts.allowCustomApi,
-        warn: opts.warn,
-    });
-    const located = await locateProjectBinding(projectCwd);
-    if (!located) {
-        return {
-            message: [
-                "✗ This folder isn't linked to a project.",
-                "",
-                "  vincentt link <project-id>   (copy it from the console)",
-                "  vincentt create             Register a new project for this folder",
-            ].join("\n"),
-            notBound: true,
-        };
-    }
-    const dist = path.resolve(projectCwd, opts.distDir ?? "dist");
-    const commitSha = await gitHeadSha(projectCwd);
-    const result = await publishUpload(cfg, located.binding.projectId, dist, {
-        note: opts.note,
-        commitSha,
-    });
-    return {
-        message: `Published v${result.version}. Live at ${result.liveUrl}`,
-        notBound: false,
-        version: result.version,
-        liveUrl: result.liveUrl,
-        url: result.url,
+    const lines = [];
+    const print = (line) => {
+        lines.push(line);
     };
+    const exitCode = await publishCommand({
+        print,
+        write: () => {
+            // No redraw off a terminal; the degraded path emits whole lines.
+        },
+        confirm: async () => false,
+        cwd: projectCwd,
+        config: () => resolveConfig(projectCwd, {
+            allowCustomApi: opts.allowCustomApi,
+            warn: opts.warn ?? print,
+        }),
+        binding: async () => {
+            const located = await locateProjectBinding(projectCwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        token: async () => process.env.VINCENTT_PAT ?? (await loadMachineConfig()).pat,
+        isTTY: false,
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    }, { distDir: opts.distDir, note: opts.note, yes: opts.yes });
+    return { message: lines.join("\n"), exitCode };
 }
 // ---- preview (one per process) ----------------------------------------------
 let activePreview = null;

package/dist/mcp/server.js

@@ -141,7 +141,7 @@ export function createHarnessMcp(opts = {}) {
         return result.message;
     }));
     server.registerTool("project_publish", {
-        description: "Publish the locally-built dist so this project goes live at <slug>.vincentt.app. Build first (e.g. npm run build), then call this — the dist is uploaded as-is and the server never rebuilds. Requires a prior project_create binding.",
+        description: "Publish the locally-built dist so this project goes live at <slug>.vincentt.app. Build first (e.g. npm run build), then call this — the dist is uploaded as-is and the server never rebuilds. Requires a prior project_create binding. A project's FIRST publish cannot be automated: it makes the address permanent, so the user must run `vincentt publish` in their own terminal once. Every publish after that works from here.",
         inputSchema: {
             distDir: z
                 .string()
@@ -154,10 +154,10 @@ export function createHarnessMcp(opts = {}) {
             ...projectDirInput,
         },
     }, async ({ distDir, note, projectDir }) => guard(async () => {
-        const result = await projectPublish(resolveProjectDir(baseProjectDir, projectDir), {
-            distDir,
-            note,
-        });
+        // `yes` is the only value an MCP caller can pass: there is no terminal to
+        // prompt at. On a FIRST publish the command refuses it outright, which is
+        // what keeps an irreversible act off an agent's tool surface.
+        const result = await projectPublish(resolveProjectDir(baseProjectDir, projectDir), { distDir, note, yes: true });
         return result.message;
     }));
     server.registerTool("preview_start", {

package/dist/publish/api.d.ts

@@ -0,0 +1,67 @@
+import type { ResolvedConfig } from "../shared/config.js";
+import type { ManifestEntry } from "./manifest.js";
+export interface PublishProject {
+    id: string;
+    slug: string;
+    name: string;
+    liveUrl: string;
+    publishState: "never" | "live" | "unpublished" | "not_serving";
+    firstPublishedAt: string | null;
+    liveVersion: number | null;
+    highestVersion: number | null;
+    /** The LIVE version's publishedAt. Ledger-derived; it is why the checklist needs one call. */
+    livePublishedAt: string | null;
+    rolledBackFrom: number | null;
+}
+export interface UploadTarget {
+    path: string;
+    /** The presigned S3 PUT. THE CLI NEVER PARSES IT. */
+    url: string;
+    /**
+     * The map the CLI MUST send verbatim. Content-Type and x-amz-checksum-sha256
+     * are both covered by the signature: dropping either yields
+     * SignatureDoesNotMatch, which reads as an auth bug and gets "fixed" by
+     * deleting the header — §2.7's contract traps 3 and 4.
+     */
+    headers: Record<string, string>;
+}
+export interface OpenedUpload {
+    uploadId: string;
+    uploads: UploadTarget[];
+    expiresAt: string;
+}
+export interface CommitResult {
+    version: number;
+    liveVersion: number;
+    highestVersion: number;
+    liveUrl: string;
+    publishedAt: string;
+    /** Response-side name of the request's `note`. The asymmetry is deliberate. */
+    releaseNote?: string;
+}
+export interface ApiErrorDetail {
+    limit?: number;
+    observed?: number;
+    missing?: number;
+    mismatched?: number;
+    reason?: string;
+    path?: string;
+}
+export declare class PublishApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly detail: ApiErrorDetail;
+    readonly retryAfterSec?: number | undefined;
+    constructor(status: number, code: string, message: string, detail?: ApiErrorDetail, retryAfterSec?: number | undefined);
+}
+/** The ONE call before the checklist. liveVersion + livePublishedAt ride it, by design. */
+export declare function readProject(cfg: ResolvedConfig, projectId: string, fetchImpl?: typeof fetch): Promise<PublishProject>;
+/**
+ * Open an upload. The request body carries `files` (path/size/sha256) and an
+ * optional `note`, AND NOTHING ELSE — there is no field for a MIME type and no
+ * field a parsed title, description or image URL could land in.
+ */
+export declare function openUpload(cfg: ResolvedConfig, projectId: string, files: ManifestEntry[], note: string | undefined, fetchImpl?: typeof fetch): Promise<OpenedUpload>;
+export declare function commitUpload(cfg: ResolvedConfig, projectId: string, uploadId: string, fetchImpl?: typeof fetch): Promise<CommitResult>;
+/** Abandon an open upload. Idempotent server-side; a failure here must never mask the real error. */
+export declare function abandonUpload(cfg: ResolvedConfig, projectId: string, uploadId: string, fetchImpl?: typeof fetch): Promise<void>;

package/dist/publish/api.js

@@ -0,0 +1,96 @@
+// The three-call publish transaction against the Go API, built against
+// implementation.md §2.7's contract table — every wire field named canonically
+// once, and the deliberate asymmetry (request `note`, response `releaseNote`)
+// carried as written.
+//
+// The bytes do NOT transit the API. Open returns one presigned PUT per file,
+// each signed for one exact key; the CLI PUTs direct to S3 and then commits.
+export class PublishApiError extends Error {
+    status;
+    code;
+    detail;
+    retryAfterSec;
+    constructor(status, code, message, detail = {}, retryAfterSec) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+        this.retryAfterSec = retryAfterSec;
+        this.name = "PublishApiError";
+    }
+}
+async function readError(res) {
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+        // A non-JSON error body is still an error; the status carries the meaning.
+    }
+    const retryAfter = res.headers.get("retry-after");
+    return new PublishApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, body.detail ?? {}, retryAfter ? Number(retryAfter) : undefined);
+}
+function authHeaders(cfg) {
+    return { authorization: `Bearer ${cfg.pat}` };
+}
+/** The ONE call before the checklist. liveVersion + livePublishedAt ride it, by design. */
+export async function readProject(cfg, projectId, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}`, {
+        headers: authHeaders(cfg),
+    });
+    if (!res.ok)
+        throw await readError(res);
+    const raw = (await res.json());
+    const num = (k) => typeof raw[k] === "number" ? raw[k] : null;
+    const str = (k) => typeof raw[k] === "string" ? raw[k] : null;
+    return {
+        id: String(raw.id ?? projectId),
+        slug: String(raw.slug ?? ""),
+        name: typeof raw.name === "string" ? raw.name : String(raw.slug ?? ""),
+        liveUrl: str("liveUrl") ?? "",
+        publishState: (str("publishState") ?? "never"),
+        firstPublishedAt: str("firstPublishedAt"),
+        liveVersion: num("liveVersion"),
+        highestVersion: num("highestVersion"),
+        livePublishedAt: str("livePublishedAt"),
+        rolledBackFrom: num("rolledBackFrom"),
+    };
+}
+/**
+ * Open an upload. The request body carries `files` (path/size/sha256) and an
+ * optional `note`, AND NOTHING ELSE — there is no field for a MIME type and no
+ * field a parsed title, description or image URL could land in.
+ */
+export async function openUpload(cfg, projectId, files, note, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg), "content-type": "application/json" },
+        body: JSON.stringify({ files, ...(note ? { note } : {}) }),
+    });
+    if (!res.ok)
+        throw await readError(res);
+    const body = (await res.json());
+    if (!body.uploadId || !Array.isArray(body.uploads)) {
+        throw new PublishApiError(res.status, "malformed_response", "open upload: response missing uploadId/uploads");
+    }
+    return {
+        uploadId: body.uploadId,
+        uploads: body.uploads,
+        expiresAt: body.expiresAt ?? "",
+    };
+}
+export async function commitUpload(cfg, projectId, uploadId, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}/commit`, { method: "POST", headers: authHeaders(cfg) });
+    if (!res.ok)
+        throw await readError(res);
+    return (await res.json());
+}
+/** Abandon an open upload. Idempotent server-side; a failure here must never mask the real error. */
+export async function abandonUpload(cfg, projectId, uploadId, fetchImpl = fetch) {
+    try {
+        await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}`, { method: "DELETE", headers: authHeaders(cfg) });
+    }
+    catch {
+        // Best-effort cleanup: the TTL reaps the row either way.
+    }
+}

package/dist/publish/bounds.d.ts

@@ -0,0 +1,25 @@
+import type { Manifest, ManifestEntry } from "./manifest.js";
+export declare const MAX_TOTAL_BYTES = 524288000;
+export declare const MAX_FILES = 5000;
+export declare const MAX_FILE_BYTES = 104857600;
+export type BoundKind = "total" | "count" | "file";
+export interface BoundViolation {
+    kind: BoundKind;
+    observed: number;
+    limit: number;
+    /** The one offending path, for the per-file case. */
+    path?: string;
+    /** The three largest files by size — the actual diagnosis for the total case. */
+    largest: ManifestEntry[];
+}
+/** The three largest files, descending. Local information about the creator's own disk. */
+export declare function largestFiles(files: ManifestEntry[], n?: number): ManifestEntry[];
+/**
+ * The bounds are INCLUSIVE at the stated number: exactly 500 MiB, exactly 5000
+ * files and exactly 100 MiB all pass.
+ */
+export declare function checkBounds(manifest: Manifest, limits?: {
+    total?: number;
+    count?: number;
+    file?: number;
+}): BoundViolation | undefined;

package/dist/publish/bounds.js

@@ -0,0 +1,53 @@
+// The three bounds, checked LOCALLY before any request (implementation.md §2.5,
+// Flow L28). The manifest is built locally and the limits are known locally, so
+// the creator learns in the same second they would otherwise have started a
+// ten-minute upload.
+//
+// These are the compiled-in defaults the API also carries. A divergence would
+// mean the CLI's printed limit is off by one from the API's, which is why QA
+// drives a manifest exactly AT each bound.
+export const MAX_TOTAL_BYTES = 524_288_000; // 500 MiB
+export const MAX_FILES = 5_000;
+export const MAX_FILE_BYTES = 104_857_600; // 100 MiB
+/** The three largest files, descending. Local information about the creator's own disk. */
+export function largestFiles(files, n = 3) {
+    return [...files].sort((a, b) => b.size - a.size).slice(0, n);
+}
+/**
+ * The bounds are INCLUSIVE at the stated number: exactly 500 MiB, exactly 5000
+ * files and exactly 100 MiB all pass.
+ */
+export function checkBounds(manifest, limits = {}) {
+    const maxTotal = limits.total ?? MAX_TOTAL_BYTES;
+    const maxCount = limits.count ?? MAX_FILES;
+    const maxFile = limits.file ?? MAX_FILE_BYTES;
+    // Per-file first: one pathological object is a more specific diagnosis than
+    // the total it also blows, and naming the file is the whole remedy.
+    const oversize = manifest.files.find((f) => f.size > maxFile);
+    if (oversize) {
+        return {
+            kind: "file",
+            observed: oversize.size,
+            limit: maxFile,
+            path: oversize.path,
+            largest: largestFiles(manifest.files),
+        };
+    }
+    if (manifest.files.length > maxCount) {
+        return {
+            kind: "count",
+            observed: manifest.files.length,
+            limit: maxCount,
+            largest: largestFiles(manifest.files),
+        };
+    }
+    if (manifest.totalBytes > maxTotal) {
+        return {
+            kind: "total",
+            observed: manifest.totalBytes,
+            limit: maxTotal,
+            largest: largestFiles(manifest.files),
+        };
+    }
+    return undefined;
+}

package/dist/publish/classify.d.ts

@@ -0,0 +1,51 @@
+export type Tier = "present" | "missing" | "template-default" | "likely-default" | "dead-image";
+/** The five tags the checklist reads. `twitter:card` is read but reported only through `social`. */
+export type FieldKey = "title" | "description" | "image";
+export interface Finding {
+    field: FieldKey;
+    tier: Tier;
+    /** The value found, if any. Both default tiers PRINT it — evidence is what makes them safe. */
+    value?: string;
+    /** The tag as it appears in the source, e.g. `<meta property="og:image">`. */
+    tag: string;
+}
+export interface FileFindings {
+    /** The dist-relative html path, e.g. `index.html`. */
+    file: string;
+    findings: Finding[];
+}
+export interface ParsedMeta {
+    title?: string;
+    ogTitle?: string;
+    description?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogUrl?: string;
+    twitterCard?: string;
+}
+export declare function parseMeta(html: string): ParsedMeta;
+export interface ClassifyContext {
+    /** Every normalized path in the manifest — what makes the dead-og:image check structural. */
+    manifestPaths: ReadonlySet<string>;
+    /** `<slug>.<apex>`, for the og:url host heuristic. Absent skips that check. */
+    expectedHost?: string;
+}
+/**
+ * CLASSIFY, per 2A:
+ *   absent                              -> MISSING
+ *   value in the bundled corpus         -> TEMPLATE-DEFAULT (high confidence)
+ *   value matches a generic shape       -> LIKELY-DEFAULT (low confidence)
+ *   else                                -> PRESENT
+ *
+ * Plus the one structural certainty: an og:image naming a path that is not in the
+ * manifest is a dead social image, and the manifest either contains it or it does
+ * not.
+ */
+export declare function classify(meta: ParsedMeta, ctx: ClassifyContext): Finding[];
+/**
+ * The manifest path an og:image refers to, or undefined when it is an absolute
+ * URL on some other host — which the CLI cannot check and must not guess about.
+ */
+export declare function localManifestPath(value: string): string | undefined;
+/** Every `.html` in the manifest, classified. Multiple files group under their filename. */
+export declare function classifyDist(distDir: string, manifestPaths: ReadonlySet<string>, readFile: (abs: string) => Promise<string>, join: (dir: string, rel: string) => string, ctx?: Omit<ClassifyContext, "manifestPaths">): Promise<FileFindings[]>;