@vincentt-xr/cli 0.2.0 → 0.4.0

package/dist/lib/version.js

@@ -0,0 +1,82 @@
+// `vincentt version` — which CLI is running, and which backend it will actually
+// talk to.
+//
+// The second half is the point. A creator can have the right CLI pointed at the
+// wrong API (a leftover VINCENTT_API_URL, a machine config written months ago,
+// or the localhost default on a fresh install), and every failure that follows
+// reads like a server outage rather than a misconfiguration. So this reports the
+// resolved host AND its provenance, using the same decideApiUrl the real verbs
+// use — a version command that re-derived the URL could disagree with them.
+import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
+/**
+ * Decide what to report. Pure, so the transcript is testable without a home
+ * directory, an env var, or a built package.
+ */
+export function buildVersionReport(env) {
+    const decided = decideApiUrl({
+        bindingApiUrl: env.bindingApiUrl,
+        envApiUrl: env.envApiUrl,
+        machineApiUrl: env.machineApiUrl,
+        allowCustomApi: env.allowCustomApi,
+    });
+    let apiSource;
+    let isDefault = false;
+    if (decided.usedBindingApiUrl) {
+        apiSource = "this folder's binding (--allow-custom-api)";
+    }
+    else if (env.envApiUrl) {
+        apiSource = "VINCENTT_API_URL";
+    }
+    else if (env.machineApiUrl) {
+        apiSource = "~/.vincentt/config.json";
+    }
+    else {
+        apiSource = "built-in default";
+        isDefault = true;
+    }
+    return {
+        cliVersion: env.cliVersion,
+        nodeVersion: env.nodeVersion,
+        apiUrl: decided.apiUrl,
+        apiSource,
+        ignoredBindingApiUrl: decided.ignoredBindingApiUrl,
+        isDefault,
+    };
+}
+/**
+ * The transcript. Two aligned columns so the host and its provenance read as one
+ * fact, not two.
+ */
+export function renderVersion(r) {
+    const out = [
+        "",
+        `vincentt ${r.cliVersion}`,
+        "",
+        `  api     ${r.apiUrl}`,
+        `          from ${r.apiSource}`,
+    ];
+    // A localhost default on a machine that never configured anything is the
+    // single most confusing state to be in: every verb fails with a connection
+    // error that looks like the platform is down.
+    if (r.isDefault && /localhost|127\.0\.0\.1/.test(r.apiUrl)) {
+        out.push("", "  !  Nothing is configured, so this points at a local backend.", "     Set VINCENTT_API_URL, or run `vincentt login` to save one.");
+    }
+    if (r.ignoredBindingApiUrl) {
+        out.push("", `  !  This folder's binding names a different API (${r.ignoredBindingApiUrl})`, "     and was ignored. Re-run with --allow-custom-api to use it.");
+    }
+    out.push("", `  node    ${r.nodeVersion}`, "");
+    return out;
+}
+/** Read the machine's real state and produce the report. */
+export async function versionReport(cwd, opts) {
+    const machine = await loadMachineConfig();
+    const located = await locateProjectBinding(cwd);
+    return buildVersionReport({
+        envApiUrl: process.env.VINCENTT_API_URL,
+        machineApiUrl: machine.apiUrl,
+        bindingApiUrl: located?.binding.apiUrl,
+        allowCustomApi: opts.allowCustomApi,
+        nodeVersion: process.version,
+        cliVersion: opts.cliVersion,
+    });
+}

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

package/dist/publish/classify.js

@@ -0,0 +1,138 @@
+// The link-metadata read: parse every .html in the dist, classify what it finds,
+// and report. Four tiers, three registers of copy (Flow L25).
+//
+// THE RESULT IS NEVER SENT. There is no wire field for a title, a description or
+// an image URL, and that absence is B24's mechanism rather than a promise
+// (D-Metadata-never-crosses-the-wire). This module returns findings to the
+// terminal and to nothing else.
+//
+// The parse is regex-based on purpose: adding an HTML parser to the CLI would be
+// a dependency on hostile-ish input for a report that never blocks, and the tags
+// this reads are emitted by build tools in a shape a regex reads correctly.
+import { FRAMEWORK_NAMES, TEMPLATE_DEFAULT_DESCRIPTIONS, TEMPLATE_DEFAULT_IMAGES, TEMPLATE_DEFAULT_TITLES, inCorpus, } from "./defaults.js";
+const TITLE_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
+/** A `<meta>` whose name/property matches `key`, in either attribute order. */
+function metaContent(html, key) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const forward = new RegExp(`<meta[^>]*\\b(?:name|property)\\s*=\\s*["']${escaped}["'][^>]*>`, "i");
+    const tag = forward.exec(html)?.[0];
+    if (!tag)
+        return undefined;
+    const content = /\bcontent\s*=\s*["']([\s\S]*?)["']/i.exec(tag)?.[1];
+    return content === undefined ? undefined : decodeEntities(content.trim());
+}
+function decodeEntities(s) {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#0?39;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+export function parseMeta(html) {
+    const rawTitle = TITLE_RE.exec(html)?.[1];
+    return {
+        title: rawTitle === undefined ? undefined : decodeEntities(rawTitle.trim()),
+        ogTitle: metaContent(html, "og:title"),
+        description: metaContent(html, "description"),
+        ogDescription: metaContent(html, "og:description"),
+        ogImage: metaContent(html, "og:image"),
+        ogUrl: metaContent(html, "og:url"),
+        twitterCard: metaContent(html, "twitter:card"),
+    };
+}
+/**
+ * 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 function classify(meta, ctx) {
+    return [classifyTitle(meta), classifyDescription(meta), classifyImage(meta, ctx)];
+}
+function classifyTitle(meta) {
+    const value = meta.ogTitle ?? meta.title;
+    const tag = meta.ogTitle !== undefined ? `<meta property="og:title">` : "<title>";
+    if (value === undefined || value === "") {
+        return { field: "title", tier: "missing", tag: "<title>" };
+    }
+    if (inCorpus(value, TEMPLATE_DEFAULT_TITLES)) {
+        return { field: "title", tier: "template-default", value, tag };
+    }
+    // A title under 4 characters, or one that is exactly a framework name.
+    if (value.trim().length < 4 || FRAMEWORK_NAMES.includes(value.trim().toLowerCase())) {
+        return { field: "title", tier: "likely-default", value, tag };
+    }
+    return { field: "title", tier: "present", value, tag };
+}
+function classifyDescription(meta) {
+    const value = meta.description ?? meta.ogDescription;
+    const tag = meta.description !== undefined
+        ? `<meta name="description">`
+        : `<meta property="og:description">`;
+    if (value === undefined || value === "") {
+        return { field: "description", tier: "missing", tag: `<meta name="description">` };
+    }
+    if (inCorpus(value, TEMPLATE_DEFAULT_DESCRIPTIONS)) {
+        return { field: "description", tier: "template-default", value, tag };
+    }
+    if (value.trim().length < 16) {
+        return { field: "description", tier: "likely-default", value, tag };
+    }
+    return { field: "description", tier: "present", value, tag };
+}
+function classifyImage(meta, ctx) {
+    const tag = `<meta property="og:image">`;
+    const value = meta.ogImage;
+    if (value === undefined || value === "") {
+        return { field: "image", tier: "missing", tag };
+    }
+    // The strongest single finding in the checklist, and purely structural: a
+    // social image that 404s, on a project that never touched the template.
+    const local = localManifestPath(value);
+    if (local !== undefined && !ctx.manifestPaths.has(local)) {
+        return { field: "image", tier: "dead-image", value, tag };
+    }
+    if (inCorpus(value, TEMPLATE_DEFAULT_IMAGES) && local !== undefined) {
+        return { field: "image", tier: "template-default", value, tag };
+    }
+    return { field: "image", tier: "present", value, tag };
+}
+/**
+ * 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 function localManifestPath(value) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value) || value.startsWith("//"))
+        return undefined;
+    const withoutQuery = value.split(/[?#]/)[0];
+    const trimmed = withoutQuery.replace(/^\.?\//, "");
+    return trimmed === "" ? undefined : trimmed;
+}
+/** Every `.html` in the manifest, classified. Multiple files group under their filename. */
+export async function classifyDist(distDir, manifestPaths, readFile, join, ctx = {}) {
+    const htmlPaths = [...manifestPaths].filter((p) => /\.html?$/i.test(p)).sort();
+    const out = [];
+    for (const rel of htmlPaths) {
+        let html;
+        try {
+            html = await readFile(join(distDir, rel));
+        }
+        catch {
+            // An unreadable html file is not a finding about the creator's metadata;
+            // the checklist reports what it could read and blocks nothing.
+            continue;
+        }
+        out.push({
+            file: rel,
+            findings: classify(parseMeta(html), { ...ctx, manifestPaths }),
+        });
+    }
+    return out;
+}

package/dist/publish/command.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedConfig } from "../shared/config.js";
+export interface PublishDeps {
+    print: (line: string) => void;
+    /** Raw write, for the redrawn progress line only. */
+    write: (s: string) => void;
+    /** Resolve the confirmation. `defaultYes` decides what a bare Enter means. */
+    confirm: (prompt: string, defaultYes: boolean) => Promise<boolean>;
+    cwd: string;
+    config: () => Promise<ResolvedConfig>;
+    binding: () => Promise<{
+        projectId: string;
+        slug: string;
+    } | undefined>;
+    /** Absent means not signed in — the gate is LOCAL and nothing is attempted. */
+    token: () => Promise<string | undefined>;
+    isTTY: boolean;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    fetchImpl?: typeof fetch;
+    orgName?: () => Promise<string>;
+}
+export interface PublishOptions {
+    distDir?: string;
+    note?: string;
+    yes?: boolean;
+}
+export declare function publishCommand(deps: PublishDeps, opts?: PublishOptions): Promise<number>;