@vincentt-xr/cli 0.16.0 → 0.17.0

package/dist/cli/index.js

@@ -38,7 +38,8 @@ import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
 import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
-import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
+import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, } from "../preview/api.js";
+import { previewLimitRefused, resolveCountLimit, } from "../shared/countLimit.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
@@ -584,7 +585,11 @@ async function preview() {
         }
     }
     catch (err) {
-        for (const l of previewFailureLines(err))
+        // The local org is the FALLBACK only. A count refusal names the org that
+        // owns this project, and the wire's name wins over this one wherever both
+        // exist — see resolveCountLimit.
+        const localOrg = await localOrgIdentity();
+        for (const l of previewFailureLines(err, localOrg))
             console.log(l);
         process.exitCode = 1;
         return;
@@ -706,6 +711,18 @@ async function activeOrgName() {
         (await loadMachineConfig()).activeOrg ??
         "");
 }
+/**
+ * The org this machine is pointed at, for a refusal whose body named none.
+ *
+ * `activeOrg` is a SLUG, so it fills the slug slot and not the name slot. The
+ * display name is the API's to give; inventing one from the slug would put a
+ * fabricated workspace name on a refusal.
+ */
+async function localOrgIdentity() {
+    const slug = await activeOrgName();
+    const { consoleUrl } = await resolveAuthUrls();
+    return { slug: slug || undefined, consoleUrl };
+}
 /** The binding's name is a HINT for display only; the API is the authority. */
 async function projectDisplayName(cwd) {
     const located = await locateProjectBinding(cwd);
@@ -744,9 +761,15 @@ async function projectConsoleUrl(cwd, sessionId) {
  * creator never has to read a second, and none of them names the edge, the API
  * or an outage — a creator cannot act on that.
  */
-function previewFailureLines(err) {
+function previewFailureLines(err, local) {
     if (err instanceof PreviewRateLimitedError)
         return mintRateLimited(err.retryAfterSec);
+    // The ceiling is the second 409 on the mint route, and it is a DIFFERENT
+    // creator situation from the conflict below: nothing is running, nothing was
+    // taken down, and the organization is full.
+    if (err instanceof PreviewLimitError) {
+        return previewLimitRefused(resolveCountLimit(err.detail, local));
+    }
     if (err instanceof PreviewConflictError)
         return previewConflict();
     if (err instanceof ProjectUnreachableError) {

package/dist/preview/api.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../shared/config.js";
+import type { CountLimitDetail } from "../shared/countLimit.js";
 import { BackendError } from "../lib/backend.js";
 /** The mint response. Its key set is the cross-repo pin (contract table 2.11). */
 export interface MintedPreview {
@@ -27,6 +28,24 @@ export declare class PreviewRateLimitedError extends BackendError {
 export declare class PreviewConflictError extends BackendError {
     constructor(message: string);
 }
+/**
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
+ *
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export declare class PreviewLimitError extends BackendError {
+    readonly detail: CountLimitDetail;
+    constructor(message: string, detail: CountLimitDetail);
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *

package/dist/preview/api.js

@@ -23,6 +23,28 @@ export class PreviewConflictError extends BackendError {
         this.name = "PreviewConflictError";
     }
 }
+/**
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
+ *
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export class PreviewLimitError extends BackendError {
+    detail;
+    constructor(message, detail) {
+        super(message, 409);
+        this.detail = detail;
+        this.name = "PreviewLimitError";
+    }
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
@@ -104,6 +126,13 @@ export async function mintPreviewSession(cfg, projectId, key, fetchImpl = fetch)
             throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
         }
         if (res.status === 409) {
+            // TWO 409s NOW LAND HERE and the CODE is what separates them. Reading the
+            // status alone would render the ceiling refusal as "a preview is already
+            // running for this folder" — a sentence that is false, that names a
+            // preview the creator does not have, and that sends them to watch it.
+            if (body.code === "preview_limit") {
+                throw new PreviewLimitError(body.message ?? "this organization is at its preview limit", body.detail ?? {});
+            }
             throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
         }
         throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);

package/dist/publish/api.d.ts

@@ -41,7 +41,15 @@ export interface CommitResult {
     releaseNote?: string;
 }
 export interface ApiErrorDetail {
-    limit?: number;
+    /**
+     * ⚠ `limit` CARRIES TWO DIFFERENT TYPES on two different codes, and the api
+     * owns both. On `publish_too_large` and f16's domain ceiling it is a
+     * MAGNITUDE (bytes, a count); on the three count refusals it is the AXIS NAME
+     * ("seats" | "published" | "previews" | "storage"). The two never appear on
+     * the same body, so the union is read at the arm that knows which code it is
+     * handling and never generically.
+     */
+    limit?: number | string;
     observed?: number;
     missing?: number;
     mismatched?: number;
@@ -67,6 +75,14 @@ export interface ApiErrorDetail {
      */
     orgName?: string;
     orgSlug?: string;
+    /**
+     * The count refusals' two figures — the org's current occupancy on the axis,
+     * and the plan's ceiling for it. Both are required for the refusal to
+     * discharge B-F10-2: a refusal naming neither is a refusal with no notice in
+     * it.
+     */
+    count?: number;
+    ceiling?: number;
 }
 export declare class PublishApiError extends Error {
     readonly status: number;

package/dist/publish/command.js

@@ -17,6 +17,7 @@ import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
 import { UploadFailed, uploadAll } from "./upload.js";
 import * as copy from "./copy.js";
+import { publishedLimitRefused, resolveCountLimit, storageCeilingRefused, } from "../shared/countLimit.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
 const COMMIT_RETRIES = 3;
 const COMMIT_RETRY_DELAY_MS = 2000;
@@ -318,8 +319,20 @@ function openErrorLines(err, address, liveVersion, org) {
     if (err.code === "unavailable_plan_limit") {
         return planLimitLines(err, org);
     }
+    // The two count/ceiling refusals of this change. Both land at OPEN — before a
+    // presigned URL is minted and before a byte moves — which is why they are here
+    // and not in commitErrorLines: neither is reachable from commit.
+    if (err.code === "published_limit") {
+        return publishedLimitRefused(resolveCountLimit(err.detail, org));
+    }
+    if (err.code === "storage_ceiling") {
+        // It takes no detail. The body is `{"limit":"storage"}` and names nothing
+        // else by design — the ceiling is an abuse ceiling, not a plan limit.
+        return storageCeilingRefused();
+    }
     if (err.code === "publish_too_large") {
-        return copy.tooLargeFromServer(err.detail.observed ?? 0, err.detail.limit ?? 0);
+        // `limit` is the MAGNITUDE on this code. See ApiErrorDetail.limit.
+        return copy.tooLargeFromServer(err.detail.observed ?? 0, numericLimit(err.detail.limit));
     }
     if (err.code === "rate_limited") {
         return copy.rateLimited(err.retryAfterSec ?? 60);
@@ -339,6 +352,15 @@ function openErrorLines(err, address, liveVersion, org) {
         "",
     ];
 }
+/**
+ * `detail.limit` on a code whose `limit` is a MAGNITUDE. A string there is the
+ * axis-name meaning arriving on a body that should not carry it, and it reads as
+ * 0 rather than as `NaN` — a bound printed as "NaN MB" is worse than one printed
+ * as a figure the copy already handles.
+ */
+function numericLimit(limit) {
+    return typeof limit === "number" ? limit : 0;
+}
 function manifestErrorLines(err, distDir) {
     if (err.reason === "no_dist")
         return copy.noDist(distDir);

package/dist/shared/countLimit.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The detail every count refusal carries. Pinned to the api's `Decision.Err`
+ * renderer: `{limit, count, ceiling, orgName, orgSlug, planName}`.
+ *
+ * On THESE codes `limit` is the AXIS NAME — "seats" | "published" | "previews" |
+ * "storage" — and not a magnitude. It is typed as the transport's union rather
+ * than narrowed to `string`, because the same detail bag carries the byte-valued
+ * `limit` of `publish_too_large`, and a type that disagreed with the transport
+ * would push the mismatch to a cast at the call site.
+ *
+ * NOTHING BELOW READS IT. The axis is already known from the code that selected
+ * the renderer, so reading it back would be the renderer asking the wire to
+ * confirm which function it is. It is declared so the shape is complete and so a
+ * reader can see the field was considered.
+ */
+export interface CountLimitDetail {
+    limit?: number | string;
+    count?: number;
+    ceiling?: number;
+    orgName?: string;
+    orgSlug?: string;
+    planName?: string;
+}
+/**
+ * The org as the CLI can otherwise name it — the machine's configured active
+ * org. It is the FALLBACK and never the authority: see `resolveOrg`.
+ */
+export interface LocalOrgIdentity {
+    name?: string;
+    slug?: string;
+    consoleUrl?: string;
+}
+export interface ResolvedCountLimit {
+    orgName?: string;
+    orgSlug?: string;
+    planName?: string;
+    count: number;
+    ceiling: number;
+    consoleUrl?: string;
+}
+/**
+ * THE WIRE WINS over the machine's configured active org.
+ *
+ * The API names the org that owns the project being acted on; local config names
+ * whichever org the CLI was last pointed at, and on a machine with more than one
+ * workspace they are routinely different. Naming the local one would print the
+ * wrong workspace on the exact screen that is refusing the creator — and the
+ * refusal's figures are about the org the wire named, so a mismatched heading
+ * makes the numbers read as wrong rather than the name.
+ *
+ * The local values remain as a fallback for a body that carried neither, which
+ * is a refusal from an older api rather than a shape this client accepts.
+ */
+export declare function resolveCountLimit(detail: CountLimitDetail, local?: LocalOrgIdentity): ResolvedCountLimit;
+/**
+ * `Acme (acme)` — name and slug when they differ, one of them when they do not,
+ * and an empty string when the wire named neither. Matches f10's shipped
+ * plan-limit heading so the four plan refusals read as one family.
+ */
+export declare function orgLabel(name?: string, slug?: string): string;
+/**
+ * The figures, STACKED AND ALIGNED rather than inline. They are a comparison —
+ * the count against the ceiling — and f2's convention puts two values a creator
+ * must judge on their own aligned lines. Inline they are a sentence to parse;
+ * stacked, an agent and a human read them the same way.
+ */
+export declare function countRows(i: ResolvedCountLimit, axisLabel: string, planSuffix: string): string[];
+/**
+ * f4's rule: where a verb does not exist because the act belongs to another
+ * surface, say where it lives and link to it — and if the link cannot be built,
+ * drop the link and keep the explanation.
+ *
+ * `path` is the org-scoped page that shows the axis being refused.
+ */
+export declare function consoleLines(i: ResolvedCountLimit, path: string): string[];
+/**
+ * The published-project ceiling, refused at open-publish.
+ *
+ * "One published project" means ONE LIVE ADDRESS AT A TIME, and the copy says
+ * so, because the other reading — one project ever published — is what makes a
+ * creator believe they have permanently spent their slot on a mistake. Taking a
+ * project offline frees it, and that is the sentence that distinguishes the two.
+ *
+ * It does NOT say the project being published is excluded from the count, even
+ * though it is: a creator refused here is publishing a SECOND project, so the
+ * exclusion never applies on the screen that would explain it.
+ */
+export declare function publishedLimitRefused(i: ResolvedCountLimit): string[];
+/**
+ * The concurrent-preview ceiling, refused at mint.
+ *
+ * "Still running" is the load-bearing claim and it is stated first among the
+ * facts. A creator whose `vincentt preview` just refused has every reason to
+ * believe it took something down — the command that failed is the command that
+ * starts previews — and B-F10-3's guarantee (a count limit refuses growth and
+ * removes nothing) is invisible unless the refusal says it.
+ */
+export declare function previewLimitRefused(i: ResolvedCountLimit): string[];
+/**
+ * The storage ceiling. It NAMES NO FIGURE, and the asymmetry with the three
+ * count refusals above is deliberate rather than an omission: the ceiling is an
+ * abuse ceiling, not a tier limit. It is flat on every plan, never sold, never
+ * displayed, and its only audience is an operator. A number here would be the
+ * product printing a magnitude a creator cannot act on and was never offered.
+ *
+ * Support is therefore the whole remedy — there is no console page showing this
+ * and no plan that raises it.
+ */
+export declare function storageCeilingRefused(): string[];

package/dist/shared/countLimit.js

@@ -0,0 +1,169 @@
+// The three count-limit refusals — seats, published projects, concurrent live
+// previews — as they reach a creator standing at a ceiling.
+//
+// THE REFUSAL IS THE NOTICE. A count limit is evaluated in the same request as
+// the act it refuses, so no earlier moment exists at which a warning could have
+// been delivered (B-F10-2, as amended). The obligation is discharged by the
+// refusal naming the axis, the current count and the ceiling — which means a
+// refusal rendered without its figures does not discharge it at all. That is the
+// whole reason these arms exist rather than the generic `✗ {message}` default.
+//
+// Two prohibitions govern every string below:
+//   - NO PRICE, and no plan other than the one in force. f16's inherited rule: a
+//     surface tells a creator where they stand, never what to buy.
+//   - NO COMMAND that resolves the refusal. An agent's default response to a
+//     failure is to run the next thing it is handed, and there is no CLI verb
+//     that frees a seat, unpublishes a project or ends someone else's preview.
+//     The copy names the act as a human one, in the console.
+const SUPPORT_EMAIL = "hello@vincentt.studio";
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
+/**
+ * THE WIRE WINS over the machine's configured active org.
+ *
+ * The API names the org that owns the project being acted on; local config names
+ * whichever org the CLI was last pointed at, and on a machine with more than one
+ * workspace they are routinely different. Naming the local one would print the
+ * wrong workspace on the exact screen that is refusing the creator — and the
+ * refusal's figures are about the org the wire named, so a mismatched heading
+ * makes the numbers read as wrong rather than the name.
+ *
+ * The local values remain as a fallback for a body that carried neither, which
+ * is a refusal from an older api rather than a shape this client accepts.
+ */
+export function resolveCountLimit(detail, local) {
+    return {
+        orgName: detail.orgName ?? local?.name,
+        orgSlug: detail.orgSlug ?? local?.slug,
+        planName: detail.planName,
+        count: detail.count ?? 0,
+        ceiling: detail.ceiling ?? 0,
+        consoleUrl: local?.consoleUrl,
+    };
+}
+/**
+ * `Acme (acme)` — name and slug when they differ, one of them when they do not,
+ * and an empty string when the wire named neither. Matches f10's shipped
+ * plan-limit heading so the four plan refusals read as one family.
+ */
+export function orgLabel(name, slug) {
+    if (name && slug && name !== slug)
+        return `${name} (${slug})`;
+    return name || slug || "";
+}
+/**
+ * The figures, STACKED AND ALIGNED rather than inline. They are a comparison —
+ * the count against the ceiling — and f2's convention puts two values a creator
+ * must judge on their own aligned lines. Inline they are a sentence to parse;
+ * stacked, an agent and a human read them the same way.
+ */
+export function countRows(i, axisLabel, planSuffix) {
+    const rows = [];
+    if (i.orgName || i.orgSlug)
+        rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
+    if (i.planName)
+        rows.push(["Plan", `${i.planName} — ${planSuffix}`]);
+    rows.push([axisLabel, `${i.count} of ${i.ceiling} used`]);
+    return alignedRows(rows);
+}
+function alignedRows(rows) {
+    const width = Math.max(...rows.map((r) => r[0].length));
+    return rows.map(([label, value]) => `  ${label.padEnd(width)}   ${value}`);
+}
+/**
+ * f4's rule: where a verb does not exist because the act belongs to another
+ * surface, say where it lives and link to it — and if the link cannot be built,
+ * drop the link and keep the explanation.
+ *
+ * `path` is the org-scoped page that shows the axis being refused.
+ */
+export function consoleLines(i, path) {
+    if (!i.orgSlug)
+        return [`  Email ${SUPPORT_EMAIL}.`, ""];
+    const base = (i.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
+    return [`  See ${base}/orgs/${i.orgSlug}/${path}, or email`, `  ${SUPPORT_EMAIL}.`, ""];
+}
+// THERE IS NO SEAT ARM HERE, AND THE ABSENCE IS THE DESIGN.
+//
+// `seat_limit` is refused on `POST /orgs/{slug}/invites`, which the CLI does not
+// call and has no verb for: inviting a person is an act whose authorized actor
+// is a human, so it lives in the console (f15's convention). The seat refusal's
+// copy — including the two ways to free a seat — is the console's to render.
+//
+// A renderer for it added here would be an export with no caller, which is worse
+// than nothing: it reads as coverage and cannot fail.
+/**
+ * The published-project ceiling, refused at open-publish.
+ *
+ * "One published project" means ONE LIVE ADDRESS AT A TIME, and the copy says
+ * so, because the other reading — one project ever published — is what makes a
+ * creator believe they have permanently spent their slot on a mistake. Taking a
+ * project offline frees it, and that is the sentence that distinguishes the two.
+ *
+ * It does NOT say the project being published is excluded from the count, even
+ * though it is: a creator refused here is publishing a SECOND project, so the
+ * exclusion never applies on the screen that would explain it.
+ */
+export function publishedLimitRefused(i) {
+    return [
+        "",
+        "✗ This organization is already publishing as many projects as its plan allows.",
+        "",
+        ...countRows(i, "Published", "published projects are counted per organization"),
+        "",
+        "  The count is projects with a live address right now, not projects that have",
+        "  ever been published. Taking one offline in the console frees the slot, and",
+        "  everything already published stays exactly as it is.",
+        "",
+        ...consoleLines(i, "projects"),
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/**
+ * The concurrent-preview ceiling, refused at mint.
+ *
+ * "Still running" is the load-bearing claim and it is stated first among the
+ * facts. A creator whose `vincentt preview` just refused has every reason to
+ * believe it took something down — the command that failed is the command that
+ * starts previews — and B-F10-3's guarantee (a count limit refuses growth and
+ * removes nothing) is invisible unless the refusal says it.
+ */
+export function previewLimitRefused(i) {
+    return [
+        "",
+        "✗ This organization has as many previews running as its plan allows.",
+        "",
+        ...countRows(i, "Previews", "previews are counted per organization"),
+        "",
+        "  Every preview that was running is still running — this one did not start.",
+        "  A preview stops when whoever started it stops it, or when it reaches its",
+        "  12-hour limit.",
+        "",
+        ...consoleLines(i, "projects"),
+        "  Nothing was started.",
+        "",
+    ];
+}
+/**
+ * The storage ceiling. It NAMES NO FIGURE, and the asymmetry with the three
+ * count refusals above is deliberate rather than an omission: the ceiling is an
+ * abuse ceiling, not a tier limit. It is flat on every plan, never sold, never
+ * displayed, and its only audience is an operator. A number here would be the
+ * product printing a magnitude a creator cannot act on and was never offered.
+ *
+ * Support is therefore the whole remedy — there is no console page showing this
+ * and no plan that raises it.
+ */
+export function storageCeilingRefused() {
+    return [
+        "",
+        "✗ This organization cannot upload more files right now.",
+        "",
+        "  This is not a plan limit and taking a different plan will not change it.",
+        "",
+        `  Email ${SUPPORT_EMAIL} and it can be looked at.`,
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",