@vincentt-xr/cli 0.2.0 → 0.3.0

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

package/dist/publish/command.js

@@ -0,0 +1,328 @@
+// `vincentt publish` — Flows L22-L31.
+//
+// The shape: build the manifest LOCALLY, check the bounds LOCALLY, read the
+// project ONCE, show the checklist, ask, then open → PUT direct to S3 → commit.
+// Nothing is sent before the creator answers. `--yes` skips the prompt on every
+// publish including the first; it never skips the checklist, so the permanence
+// disclosure still reaches an unattended operator's transcript.
+//
+// The IO boundary (print, prompt, fetch, disk, clock, TTY) is injected so every
+// 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 { 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 * as copy from "./copy.js";
+const COMMIT_RETRIES = 3;
+const COMMIT_RETRY_DELAY_MS = 2000;
+export async function publishCommand(deps, opts = {}) {
+    // 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;
+    }
+    const binding = await deps.binding();
+    if (!binding) {
+        deps.print("✗ This folder isn't linked to a project.");
+        deps.print("");
+        deps.print("  vincentt link <project-id>   (copy it from the console)");
+        deps.print("  vincentt create             Register a new project for this folder");
+        return 1;
+    }
+    const distDir = path.resolve(deps.cwd, opts.distDir ?? "dist");
+    // 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);
+    }
+    catch (err) {
+        if (err instanceof ManifestError) {
+            for (const l of manifestErrorLines(err, distDir))
+                deps.print(l);
+            return 1;
+        }
+        throw err;
+    }
+    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));
+        for (const l of copy.tooLarge(violation))
+            deps.print(l);
+        return 1;
+    }
+    const cfg = await deps.config();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    // ONE call before the checklist. liveVersion and livePublishedAt ride it, so
+    // the republish line costs no second round trip.
+    let project;
+    try {
+        project = await readProject(cfg, binding.projectId, fetchImpl);
+    }
+    catch (err) {
+        if (err instanceof PublishApiError && err.status === 404) {
+            deps.print(`✗ ${err.message}`);
+            deps.print("");
+            deps.print("  This folder is linked to a project that can't be reached with your current");
+            deps.print("  account. Check who you are:   vincentt whoami");
+            return 1;
+        }
+        throw err;
+    }
+    const address = addressOf(project);
+    const isFirstPublish = project.firstPublishedAt === null;
+    const nextVersion = (project.highestVersion ?? 0) + 1;
+    const orgName = await orgOf(deps);
+    // A non-interactive stdin with no --yes must REFUSE rather than assume yes.
+    if (!opts.yes && !deps.isTTY) {
+        deps.print("");
+        deps.print("✗ Publishing needs a confirmation, and this isn't an interactive terminal.");
+        deps.print("");
+        deps.print("  Re-run it interactively, or pass --yes:  vincentt publish --yes");
+        deps.print("");
+        deps.print("  Nothing was uploaded.");
+        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 checklistInput = {
+        projectName: project.name,
+        orgName,
+        address,
+        fileCount: manifest.files.length,
+        totalBytes: manifest.totalBytes,
+        nextVersion,
+        findings,
+    };
+    let promptLine;
+    let defaultYes;
+    if (isFirstPublish) {
+        for (const l of copy.firstPublishChecklist(checklistInput))
+            deps.print(l);
+        promptLine = copy.firstPublishPrompt(address, nextVersion);
+        defaultYes = false;
+    }
+    else if (project.publishState === "unpublished") {
+        for (const l of copy.offlineChecklist(checklistInput))
+            deps.print(l);
+        promptLine = copy.offlinePrompt(nextVersion);
+        // This publish has a second consequence the creator did not ask for, so an
+        // accidental Enter must do nothing.
+        defaultYes = false;
+    }
+    else {
+        for (const l of copy.republishChecklist({
+            ...checklistInput,
+            liveVersion: project.liveVersion ?? nextVersion - 1,
+            livePublishedAt: project.livePublishedAt ?? undefined,
+            now: deps.now(),
+        })) {
+            deps.print(l);
+        }
+        promptLine = copy.republishPrompt(nextVersion);
+        defaultYes = true;
+    }
+    // --yes suppresses the PROMPT, not the REPORT. The findings block above is
+    // byte-identical on both paths, because stdout is the only channel that
+    // reaches an agent.
+    if (!opts.yes) {
+        const confirmed = await deps.confirm(promptLine, defaultYes);
+        if (!confirmed) {
+            for (const l of copy.declined())
+                deps.print(l);
+            return 0;
+        }
+    }
+    return runUpload(deps, cfg, {
+        projectId: binding.projectId,
+        distDir,
+        manifest,
+        note: opts.note,
+        address,
+        liveVersion: project.liveVersion ?? undefined,
+        fetchImpl,
+    });
+}
+async function runUpload(deps, cfg, i) {
+    let opened;
+    try {
+        opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl);
+    }
+    catch (err) {
+        for (const l of openErrorLines(err, i.address, i.liveVersion))
+            deps.print(l);
+        return 1;
+    }
+    deps.print(copy.uploadStart(i.manifest.files.length));
+    const progress = createProgress({
+        isTTY: deps.isTTY,
+        write: deps.write,
+        print: deps.print,
+        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,
+        });
+    }
+    catch (err) {
+        progress.finish();
+        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";
+        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}.`);
+        deps.print("");
+        deps.print("  Publish again:  vincentt publish");
+        deps.print("");
+        return 1;
+    }
+    progress.finish();
+    deps.print(copy.uploadDone(i.manifest.files.length, i.manifest.totalBytes, deps.now() - startedAt));
+    deps.print(copy.finishing());
+    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.
+ */
+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);
+            return 0;
+        }
+        catch (err) {
+            if (!(err instanceof PublishApiError))
+                throw err;
+            if (err.code === "publish_flip_failed" || err.status === 502) {
+                if (attempt === COMMIT_RETRIES) {
+                    for (const l of copy.flipFailed(i.address, i.liveVersion))
+                        deps.print(l);
+                    return 1;
+                }
+                // The `!` line prints only if a retry happens, and it says nothing about
+                // a failure — from the creator's position nothing has failed yet.
+                if (!announcedSlow) {
+                    deps.print(copy.takingLonger());
+                    announcedSlow = true;
+                }
+                await deps.sleep(COMMIT_RETRY_DELAY_MS);
+                continue;
+            }
+            for (const l of commitErrorLines(err, i.address, i.liveVersion))
+                deps.print(l);
+            return 1;
+        }
+    }
+    return 1;
+}
+function commitErrorLines(err, address, liveVersion) {
+    switch (err.code) {
+        case "publish_expired":
+            return copy.publishExpired(address, liveVersion);
+        case "publish_contended":
+            return copy.publishContended();
+        case "publish_incomplete":
+            // The response carries COUNTS, never paths, so these are the CLI's own
+            // strings about its own manifest.
+            return copy.publishIncomplete(address, { missing: err.detail.missing, mismatched: err.detail.mismatched }, liveVersion);
+        default:
+            return [
+                "",
+                `✗ ${err.message}`,
+                "",
+                liveVersion === undefined
+                    ? `  Your live address is unchanged — ${address}.`
+                    : `  Your live address is unchanged — ${address} is still serving v${liveVersion}.`,
+                "",
+                "  Publish again:  vincentt publish",
+                "",
+            ];
+    }
+}
+function openErrorLines(err, address, liveVersion) {
+    if (!(err instanceof PublishApiError)) {
+        return [
+            "",
+            `✗ ${err instanceof Error ? err.message : String(err)}`,
+            "",
+            "  Nothing was uploaded.",
+            "",
+        ];
+    }
+    if (err.code === "publish_too_large") {
+        return copy.tooLargeFromServer(err.detail.observed ?? 0, err.detail.limit ?? 0);
+    }
+    if (err.code === "rate_limited") {
+        return copy.rateLimited(err.retryAfterSec ?? 60);
+    }
+    if (err.code === "manifest_invalid") {
+        return copy.badPath(err.detail.reason ?? "", err.detail.path ?? "");
+    }
+    return [
+        "",
+        `✗ ${err.message}`,
+        "",
+        liveVersion === undefined
+            ? `  Your live address is unchanged — ${address}.`
+            : `  Your live address is unchanged — ${address} is still serving v${liveVersion}.`,
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+function manifestErrorLines(err, distDir) {
+    if (err.reason === "no_dist")
+        return copy.noDist(distDir);
+    if (err.reason === "no_index_html")
+        return copy.noIndexHtml(distDir);
+    return copy.badPath(err.reason, err.offendingPath);
+}
+/**
+ * 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
+ * the slug is only a fallback.
+ */
+function addressOf(project) {
+    if (!project.liveUrl)
+        return project.slug;
+    try {
+        return new URL(project.liveUrl).host;
+    }
+    catch {
+        return project.liveUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+    }
+}
+async function orgOf(deps) {
+    return (await deps.orgName?.()) ?? "";
+}
+async function projectLabel(deps, slug) {
+    return slug || path.basename(deps.cwd);
+}

package/dist/publish/consoleVerbs.d.ts

@@ -0,0 +1,17 @@
+export declare function isConsoleOnlyVerb(verb: string): boolean;
+export interface ConsoleVerbDeps {
+    print: (line: string) => void;
+    /** The bound project id, or undefined for an unlinked folder. */
+    projectId: () => Promise<string | undefined>;
+    consoleUrl?: string;
+}
+/**
+ * The deep link goes to the exact tab, built from the binding the CLI already
+ * holds — a creator who typed `vincentt rollback` wants to be one click from
+ * rolling back.
+ *
+ * If the folder is NOT linked the last two lines are dropped and the block ends
+ * at the reason: the CLI does not know which project they meant, and guessing a
+ * console URL would be worse than none.
+ */
+export declare function consoleVerbCommand(deps: ConsoleVerbDeps, verb: string): Promise<number>;

package/dist/publish/consoleVerbs.js

@@ -0,0 +1,26 @@
+// Flow L30 — rollback, unpublish, republish, versions, revert and take-offline
+// are NOT CLI verbs, and the CLI says where they are.
+//
+// This is ARGUMENT PARSING. Exit 1, no network call, nothing looked up.
+import { CONSOLE_ONLY_VERBS, consoleVerb } from "./copy.js";
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.app";
+export function isConsoleOnlyVerb(verb) {
+    return CONSOLE_ONLY_VERBS.includes(verb);
+}
+/**
+ * The deep link goes to the exact tab, built from the binding the CLI already
+ * holds — a creator who typed `vincentt rollback` wants to be one click from
+ * rolling back.
+ *
+ * If the folder is NOT linked the last two lines are dropped and the block ends
+ * at the reason: the CLI does not know which project they meant, and guessing a
+ * console URL would be worse than none.
+ */
+export async function consoleVerbCommand(deps, verb) {
+    const projectId = await deps.projectId();
+    const base = (deps.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
+    const url = projectId ? `${base}/projects/${projectId}/versions` : undefined;
+    for (const line of consoleVerb(verb, url))
+        deps.print(line);
+    return 1;
+}