@vincentt-xr/cli 0.2.0 → 0.4.0

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

package/dist/publish/copy.d.ts

@@ -0,0 +1,180 @@
+import type { FileFindings } from "./classify.js";
+import type { BoundViolation } from "./bounds.js";
+export declare function truncate(value: string, max?: number): string;
+/** Bytes as the creator reads them. Decimal MB, matching what a build tool prints. */
+export declare function formatBytes(bytes: number): string;
+/** The limit, printed as a plain number and never as policy. */
+export declare function formatLimit(bytes: number): string;
+export declare function relativeTime(iso: string, now: number): string;
+/**
+ * Flow L25. Three registers of copy because the platform's confidence genuinely
+ * differs:
+ *   - TEMPLATE-DEFAULT is flat and assertive. The CLI matched a string in a
+ *     corpus it ships; it knows.
+ *   - LIKELY-DEFAULT is hedged. The heuristic will be wrong sometimes, and a
+ *     creator whose experience is genuinely called "AR" must not be told they
+ *     made a mistake.
+ *   - The dead og:image is the only ✗ the checklist ever emits, and it earns it:
+ *     the manifest either contains the path or it does not.
+ *
+ * BOTH default tiers print the offending value. "Still the template default"
+ * without the string is a claim the creator has to go and verify; with it they
+ * either recognise it instantly or spot that we are wrong.
+ *
+ * A FINDING IS NEVER A COUNT. No "2 issues found", no summary line, and no exit
+ * code that varies with findings.
+ */
+export declare function findingLines(byFile: FileFindings[], withSubtitle: boolean): string[];
+/**
+ * Mandatory and always present. A screen with a red ✗ on it reads as a gate
+ * unless it explicitly says otherwise, and a creator who believes the platform
+ * is gating their publish on our opinion of their <meta> tags has learned
+ * something false about who owns the dist.
+ */
+export declare function nothingBlocksYou(): string[];
+export interface ChecklistInput {
+    projectName: string;
+    orgName: string;
+    address: string;
+    fileCount: number;
+    totalBytes: number;
+    nextVersion: number;
+    findings: FileFindings[];
+}
+export declare function readingLine(fileCount: number, totalBytes: number): string;
+export declare function headerLine(projectName: string, orgName: string): string;
+/**
+ * Flow L22 — the single most consequential screen in the product, and its ORDER
+ * is the design.
+ *
+ * The address block is FIRST and it is fenced: a creator who reads nothing else
+ * reads the address and the sentence under it. The findings come AFTER, never
+ * before — the address is the irreversible thing and the metadata is fixable
+ * forever, so putting a red ✗ above the permanence block would make the eye land
+ * on the recoverable problem and skim the unrecoverable one.
+ */
+export declare function firstPublishChecklist(i: ChecklistInput): string[];
+/** The prompt line restates the address AND the version. `[y/N]` — an accidental Enter does nothing. */
+export declare function firstPublishPrompt(address: string, version: number): string;
+/**
+ * Declining. Glyphless, exit 0, zero network calls beyond the project read.
+ * Declining is not a failure and is not an error; it is the prompt working.
+ *
+ * The second line is the one that matters — a creator who backed out because the
+ * address was wrong needs to know the address is still theirs to change.
+ */
+export declare function declined(): string[];
+export interface RepublishInput extends ChecklistInput {
+    liveVersion: number;
+    /** ISO8601 from the SAME project read — no second call to render one parenthetical. */
+    livePublishedAt?: string;
+    now: number;
+}
+/**
+ * Flow L24. No fence, no permanence block, no disclosure: the address is already
+ * permanent and the creator already knows, and presenting a frozen fact as a
+ * choice is worse than not presenting it at all.
+ *
+ * `(v5, published 3 days ago)` is rendered from the project read ALONE —
+ * liveVersion and livePublishedAt both ride GET /projects/{id}.
+ */
+export declare function republishChecklist(i: RepublishInput): string[];
+/** `[Y/n]` — on a republish an accidental Enter does the thing the creator typed the command to do. */
+export declare function republishPrompt(version: number): string;
+/**
+ * A publish onto an offline address brings it online, because publish always
+ * goes live. The creator must be told: they took it offline on purpose and might
+ * not intend to reverse that, so the default reverts to [y/N].
+ */
+export declare function offlineChecklist(i: ChecklistInput): string[];
+export declare function offlinePrompt(version: number): string;
+/**
+ * f1's line verbatim, with f4's reason. Note what is ABSENT, deliberately: f3's
+ * "your local dev loop doesn't need one" paragraph. It is the right copy for
+ * preview and the wrong copy here — a creator trying to publish is not looking
+ * for a smaller room, and offering one at this gate reads as a deflection.
+ */
+export declare function notSignedIn(): string[];
+/**
+ * Loud, local, instant, and it carries the real number. This fires before a
+ * single byte moves and before a single request is made.
+ *
+ * The two numbers are STACKED AND ALIGNED — the judgement the creator must make
+ * is a comparison, and prose defeats it. The three largest files are named
+ * because that is almost always the entire diagnosis: one uncompressed asset is
+ * nearly always the cause.
+ *
+ * The limit is printed as a number, never as policy. No "on your plan", no
+ * "upgrade" — it is a correctness limit and not a quota, and copy implying
+ * otherwise would be the first sentence of a billing model this feature does not
+ * have.
+ */
+export declare function tooLarge(v: BoundViolation): string[];
+/** No dist at all, or no index.html at its root. Zero network calls. */
+export declare function noDist(distDir: string): string[];
+export declare function noIndexHtml(distDir: string): string[];
+/** A local path rule the creator's own build broke. Local, before any request. */
+export declare function badPath(reason: string, offending: string): string[];
+/** The one redrawn line in f4. A bounded progress bar with a known total is not a stream. */
+export declare function progressBar(done: number, total: number, bytesDone: number, bytesTotal: number): string;
+/** The non-TTY degrade: periodic plain lines, at most one per 2s. */
+export declare function progressPlain(done: number, total: number, bytesDone: number): string;
+export declare function uploadStart(fileCount: number): string;
+export declare function uploadDone(fileCount: number, totalBytes: number, ms: number): string;
+/** Covers the commit. The pause between the last byte and the live URL is real. */
+export declare function finishing(): string;
+/**
+ * The payload of the entire command: the live URL, full and clickable, with the
+ * version in parentheses. The caching sentence is one line and ALWAYS present —
+ * a creator refreshing a phone that has the old page in memory will see the old
+ * page, decide publish is broken, and publish again.
+ */
+export declare function liveAt(liveUrl: string, version: number): string[];
+/** Prints only if a retry is needed. It says nothing about a failure, because nothing has failed yet. */
+export declare function takingLonger(): string;
+/**
+ * The cause is NOT named. Every non-healing arm of the commit state machine
+ * returns this identically by design, and the CLI must not invent a distinction
+ * the wire does not carry. "Had to be restarted" is honest about what happened
+ * and is correct for all three arms.
+ */
+export declare function publishExpired(address: string, liveVersion?: number): string[];
+/** All three retries failed. "Nothing was lost" is the true and load-bearing sentence. */
+export declare function flipFailed(address: string, liveVersion?: number): string[];
+/**
+ * Two sentences, no explanation of version allocation. The real case is a
+ * teammate and an agent publishing in the same second, and "someone else
+ * published this project" tells the creator to check with a person before
+ * re-running — the correct next action, and not something a retry loop can do
+ * for them.
+ */
+export declare function publishContended(): string[];
+/**
+ * The commit found fewer objects than the manifest declared. The response
+ * carries COUNTS, never paths, so the CLI diffs against its OWN manifest and
+ * prints its own strings.
+ */
+export declare function publishIncomplete(address: string, counts: {
+    missing?: number;
+    mismatched?: number;
+}, liveVersion?: number): string[];
+/** A file's bytes changed under the CLI between hashing and PUT. Names the file. */
+export declare function badDigest(filePath: string, address: string, liveVersion?: number): string[];
+export declare function tooLargeFromServer(observed: number, limit: number): string[];
+export declare function rateLimited(retryAfterSec: number): string[];
+/**
+ * The same block serves rollback, unpublish, republish, versions, revert and
+ * take-offline. These are the words a creator will actually type, and every one
+ * of them lands on one screen that names the real home. A bare "unknown command"
+ * here would be the product failing to answer a question it knows the answer to.
+ *
+ * The reason is given in one clause and it is the honest one. Not "not
+ * supported", not "coming soon" — neither is true.
+ *
+ * IF THE FOLDER IS NOT LINKED THE LAST TWO LINES ARE DROPPED. The CLI does not
+ * know which project they meant, and guessing a console URL would be worse than
+ * none.
+ */
+export declare function consoleVerb(verb: string, versionsUrl?: string): string[];
+/** The six verbs that land on that block. */
+export declare const CONSOLE_ONLY_VERBS: readonly string[];