@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/preview/viewers.d.ts

@@ -0,0 +1,113 @@
+import type { UAClass } from "@vincentt-xr/harness/tunnel";
+/** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
+export declare const ROSTER_AT = 4;
+/**
+ * The reconnect advisory's window (Flow L17). It prints only when a connection
+ * attaches within 120s of a disconnect WITH THE SAME UA CLASS. On a first
+ * connection, or at a demo where four fresh phones arrive, the creator never
+ * sees it.
+ */
+export declare const RECONNECT_WINDOW_MS = 120000;
+export interface Viewer {
+    readonly label: string;
+    readonly uaClass: UAClass;
+    readonly connectedAt: number;
+    /** The tester this connection resolved to, once the harness introduced itself. */
+    readonly tester?: string;
+}
+/** One printable line, or a block of them. The runner writes; this decides. */
+export interface ViewerLines {
+    /** `tester-1 connected · iPhone · Safari` */
+    readonly connect?: string;
+    /**
+     * The `!` reconnect advisory, printed BELOW the connect line so the connect
+     * line stays scannable. Held rather than printed immediately — see
+     * `attribute`.
+     */
+    readonly advisory?: string[];
+    /** The one-time roster block, on the fourth tester. */
+    readonly roster?: string[];
+}
+export declare class ViewerRoster {
+    private readonly live;
+    /** Connections seen, ever. Printed once at the end; never a count of people. */
+    private total;
+    private rosterPrinted;
+    /** The most recent disconnect, for the L17 adjacency check. */
+    private lastDeparture;
+    /** Testers ever seen live, so a refresh is recognised as a return. */
+    private readonly testersSeen;
+    /**
+     * A held advisory per connection, keyed by label. The connection arrives before
+     * the harness mounts, so at connect time we do not yet know whether this is a
+     * known tester — and a hedge printed beside a definite `tester-1 refreshed`
+     * teaches the creator to distrust the definite line. So the advisory is
+     * DEFERRED here and dropped if attribution lands. A retracted line in a piped
+     * transcript is worse than a late one.
+     */
+    private readonly heldAdvisory;
+    /** Live CONNECTIONS. The console counts these; the CLI does not display them. */
+    get size(): number;
+    get totalConnections(): number;
+    /** Live TESTERS — distinct, attributed, currently connected. The display count. */
+    get testerCount(): number;
+    /** Live connections with no tester yet: the pre-mount window, or a crashed app. */
+    get unattributedCount(): number;
+    labels(): string[];
+    has(label: string): boolean;
+    get(label: string): Viewer | undefined;
+    /** Distinct live testers, in arrival order. */
+    liveTesters(): string[];
+    /**
+     * connect records a CONNECTION. It prints nothing about a tester yet, because
+     * the tester is not known until the app mounts — see `attribute`, which is
+     * where the line a creator reads comes from.
+     *
+     * Idempotent per label: the tunnel client fires onViewer on EVERY OPEN frame,
+     * not once per connection, so a viewer that requests forty assets would
+     * otherwise announce itself forty times.
+     */
+    connect(label: string, uaClass: UAClass, now: number): ViewerLines;
+    /**
+     * The harness introduced itself: this connection belongs to `tester`. This is
+     * where the creator's line comes from.
+     *
+     * Returns the connect line on a tester's FIRST connection, `refreshed` when a
+     * tester already seen comes back, and nothing for a second concurrent
+     * connection belonging to a tester already live — which is the ordinary case
+     * for one tab, and the reason one scan now reads as one thing.
+     */
+    attribute(label: string, tester: string): ViewerLines;
+    /**
+     * The advisory leads with the RULE and follows with the instance. Leading with
+     * a guess about this specific connection would teach the creator a hedge rather
+     * than a behavior, and one uncertain sentence on a screen where everything
+     * else is fact teaches them to distrust the labels generally — which is the
+     * opposite of what the labels are for.
+     *
+     * It names CONNECTIONS, not devices, and closes on the fact that testers
+     * survive a refresh — so the remedy for the uncertainty is on the same line as
+     * the uncertainty.
+     */
+    private reconnectAdvisory;
+    disconnect(label: string, now: number): ViewerLines;
+    /**
+     * The roster is a ONE-TIME SIGNPOST, not a live-updating footer. A redrawn
+     * status bar fights Ctrl-C, corrupts scrollback, breaks when the output is
+     * piped to a file — which is exactly what an agent does with it — and turns a
+     * plain stream into a TUI, which is a different product.
+     *
+     * It LEADS WITH A COUNT, and the count is exact: distinct attributed testers
+     * currently live. Never the number ever assigned, never a connection count.
+     * The old disclaimer ("this is not a device count") is gone — it existed only
+     * because the number above it was wrong.
+     */
+    rosterBlock(): string[];
+    /**
+     * The `--viewer` miss (Flow L16). An unknown label is a FACT, not an error,
+     * because labels churn — and the remedy is on the same line.
+     */
+    notFollowing(label: string): string;
+    /** The `--tester` miss. Same shape, different coordinate. */
+    notFollowingTester(tester: string): string;
+}

package/dist/preview/viewers.js

@@ -0,0 +1,242 @@
+// The roster: who is connected, what the connect/disconnect lines say, when the
+// roster block prints, and when the reconnect advisory prints.
+//
+// TWO COORDINATES, and the difference is the whole point of this file:
+//
+//   viewer-N  one CONNECTION. Assigned by the edge at the first HTTP byte, so it
+//             exists immediately — and churns, because a browser opens several
+//             per tab under HTTP/1.1 and a reconnect never reuses a label.
+//   tester-N  one BROWSER TAB, across its refreshes. Assigned by the relay when
+//             the app mounts and the harness introduces itself, so it arrives
+//             LATE — and is stable, which is what makes it the display unit.
+//
+// The creator reads testers. `--viewer` still filters connections for
+// connection-level debugging. Neither is derived from the other.
+//
+// It is a pure state machine over (label, uaClass, tester, now), so every rule
+// below is unit-testable without a terminal or a socket. The runner owns the
+// printing.
+import { uaLabel, uaShort } from "./stream.js";
+/** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
+export const ROSTER_AT = 4;
+/**
+ * The reconnect advisory's window (Flow L17). It prints only when a connection
+ * attaches within 120s of a disconnect WITH THE SAME UA CLASS. On a first
+ * connection, or at a demo where four fresh phones arrive, the creator never
+ * sees it.
+ */
+export const RECONNECT_WINDOW_MS = 120_000;
+export class ViewerRoster {
+    live = new Map();
+    /** Connections seen, ever. Printed once at the end; never a count of people. */
+    total = 0;
+    rosterPrinted = false;
+    /** The most recent disconnect, for the L17 adjacency check. */
+    lastDeparture = null;
+    /** Testers ever seen live, so a refresh is recognised as a return. */
+    testersSeen = new Set();
+    /**
+     * A held advisory per connection, keyed by label. The connection arrives before
+     * the harness mounts, so at connect time we do not yet know whether this is a
+     * known tester — and a hedge printed beside a definite `tester-1 refreshed`
+     * teaches the creator to distrust the definite line. So the advisory is
+     * DEFERRED here and dropped if attribution lands. A retracted line in a piped
+     * transcript is worse than a late one.
+     */
+    heldAdvisory = new Map();
+    /** Live CONNECTIONS. The console counts these; the CLI does not display them. */
+    get size() {
+        return this.live.size;
+    }
+    get totalConnections() {
+        return this.total;
+    }
+    /** Live TESTERS — distinct, attributed, currently connected. The display count. */
+    get testerCount() {
+        return this.liveTesters().length;
+    }
+    /** Live connections with no tester yet: the pre-mount window, or a crashed app. */
+    get unattributedCount() {
+        let n = 0;
+        for (const v of this.live.values())
+            if (v.tester === undefined)
+                n++;
+        return n;
+    }
+    labels() {
+        return [...this.live.keys()];
+    }
+    has(label) {
+        return this.live.has(label);
+    }
+    get(label) {
+        return this.live.get(label);
+    }
+    /** Distinct live testers, in arrival order. */
+    liveTesters() {
+        const out = [];
+        for (const v of this.live.values()) {
+            if (v.tester !== undefined && !out.includes(v.tester))
+                out.push(v.tester);
+        }
+        return out;
+    }
+    /**
+     * connect records a CONNECTION. It prints nothing about a tester yet, because
+     * the tester is not known until the app mounts — see `attribute`, which is
+     * where the line a creator reads comes from.
+     *
+     * Idempotent per label: the tunnel client fires onViewer on EVERY OPEN frame,
+     * not once per connection, so a viewer that requests forty assets would
+     * otherwise announce itself forty times.
+     */
+    connect(label, uaClass, now) {
+        if (this.live.has(label))
+            return {};
+        this.live.set(label, { label, uaClass, connectedAt: now });
+        this.total++;
+        const advisory = this.reconnectAdvisory(label, uaClass, now);
+        if (advisory)
+            this.heldAdvisory.set(label, advisory);
+        // NOTHING PRINTS HERE. One tab opens two connections under HTTP/1.1, so a
+        // line per connection is what made one QR scan read as two records. The
+        // creator learns about this connection when it resolves to a tester, or —
+        // if it never does — through the un-attributed line below.
+        return {};
+    }
+    /**
+     * The harness introduced itself: this connection belongs to `tester`. This is
+     * where the creator's line comes from.
+     *
+     * Returns the connect line on a tester's FIRST connection, `refreshed` when a
+     * tester already seen comes back, and nothing for a second concurrent
+     * connection belonging to a tester already live — which is the ordinary case
+     * for one tab, and the reason one scan now reads as one thing.
+     */
+    attribute(label, tester) {
+        const v = this.live.get(label);
+        if (v === undefined || v.tester !== undefined)
+            return {};
+        // A tester already live on ANOTHER connection: this is the tab's second
+        // socket, not an arrival.
+        const alreadyLive = this.liveTesters().includes(tester);
+        this.live.set(label, { ...v, tester });
+        // The advisory is dropped: we have a definite answer now.
+        const held = this.heldAdvisory.get(label);
+        this.heldAdvisory.delete(label);
+        if (alreadyLive)
+            return {};
+        const returning = this.testersSeen.has(tester);
+        this.testersSeen.add(tester);
+        if (returning) {
+            // A refresh, or a socket that dropped and came back. Same tester, same
+            // line, whichever it was — the creator's question is "is this the same
+            // person", and the answer is yes in both cases.
+            return { connect: `${tester} refreshed` };
+        }
+        const descriptor = uaLabel(v.uaClass);
+        const out = {
+            connect: descriptor ? `${tester} connected · ${descriptor}` : `${tester} connected`,
+        };
+        // Only an un-attributed neighbour can still justify the hedge; a known
+        // tester's arrival is certain, so the held advisory dies with it.
+        if (held && this.unattributedCount > 0)
+            out.advisory = held;
+        if (!this.rosterPrinted && this.testerCount >= ROSTER_AT) {
+            this.rosterPrinted = true;
+            out.roster = this.rosterBlock();
+        }
+        return out;
+    }
+    /**
+     * The advisory leads with the RULE and follows with the instance. Leading with
+     * a guess about this specific connection would teach the creator a hedge rather
+     * than a behavior, and one uncertain sentence on a screen where everything
+     * else is fact teaches them to distrust the labels generally — which is the
+     * opposite of what the labels are for.
+     *
+     * It names CONNECTIONS, not devices, and closes on the fact that testers
+     * survive a refresh — so the remedy for the uncertainty is on the same line as
+     * the uncertainty.
+     */
+    reconnectAdvisory(label, uaClass, now) {
+        const gone = this.lastDeparture;
+        if (!gone)
+            return undefined;
+        if (gone.label === label)
+            return undefined;
+        if (gone.uaClass !== uaClass)
+            return undefined;
+        if (now - gone.at > RECONNECT_WINDOW_MS)
+            return undefined;
+        return [
+            `! A connection that reconnects gets a new label. If ${gone.label} came back,`,
+            `  it is ${label} now — labels last one connection. Testers survive a refresh.`,
+        ];
+    }
+    disconnect(label, now) {
+        const v = this.live.get(label);
+        if (!v)
+            return {};
+        this.live.delete(label);
+        this.heldAdvisory.delete(label);
+        this.lastDeparture = { uaClass: v.uaClass, label, at: now };
+        // A tester leaves when its LAST connection does. A tab's two sockets close
+        // moments apart, and announcing a departure on the first would print
+        // `disconnected` for someone still looking at the app.
+        if (v.tester === undefined)
+            return {};
+        if (this.liveTesters().includes(v.tester))
+            return {};
+        return { connect: `${v.tester} disconnected` };
+    }
+    /**
+     * The roster is a ONE-TIME SIGNPOST, not a live-updating footer. A redrawn
+     * status bar fights Ctrl-C, corrupts scrollback, breaks when the output is
+     * piped to a file — which is exactly what an agent does with it — and turns a
+     * plain stream into a TUI, which is a different product.
+     *
+     * It LEADS WITH A COUNT, and the count is exact: distinct attributed testers
+     * currently live. Never the number ever assigned, never a connection count.
+     * The old disclaimer ("this is not a device count") is gone — it existed only
+     * because the number above it was wrong.
+     */
+    rosterBlock() {
+        const rule = "─".repeat(65);
+        const byTester = new Map();
+        for (const v of this.live.values()) {
+            if (v.tester !== undefined && !byTester.has(v.tester)) {
+                byTester.set(v.tester, uaShort(v.uaClass));
+            }
+        }
+        const parts = [...byTester].map(([t, ua]) => `${t} ${ua}`.trim());
+        const n = byTester.size;
+        const lines = [rule, `${n} ${n === 1 ? "tester" : "testers"} · ${parts.join(" · ")}`];
+        // Without this, `4 testers` printed while five connections are live is the
+        // original defect in a new place — and the pre-mount gap makes that state
+        // routine, not rare.
+        const pending = this.unattributedCount;
+        if (pending > 0) {
+            lines.push(`+ ${pending} ${pending === 1 ? "connection" : "connections"} not yet attributed`);
+        }
+        lines.push(rule);
+        return lines;
+    }
+    /**
+     * The `--viewer` miss (Flow L16). An unknown label is a FACT, not an error,
+     * because labels churn — and the remedy is on the same line.
+     */
+    notFollowing(label) {
+        const connected = this.labels();
+        return connected.length === 0
+            ? `! No ${label} on this preview right now. Nothing is connected.`
+            : `! No ${label} on this preview right now. Connected: ${connected.join(", ")}.`;
+    }
+    /** The `--tester` miss. Same shape, different coordinate. */
+    notFollowingTester(tester) {
+        const live = this.liveTesters();
+        return live.length === 0
+            ? `! No ${tester} on this preview right now. No testers are connected.`
+            : `! No ${tester} on this preview right now. Connected: ${live.join(", ")}.`;
+    }
+}

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[]>;