@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/lib/backend.d.ts

@@ -1,26 +1,50 @@
 import type { ResolvedConfig } from "../shared/config.js";
+/**
+ * A project as the Go API returns it. `liveUrl` is SERVER-COMPUTED — the apex
+ * differs per environment, so a client that builds `<slug>.<apex>` itself would
+ * print the wrong address on staging and dev.
+ */
+export interface ProjectView {
+    id: string;
+    slug: string;
+    name: string;
+    orgId: string;
+    liveUrl: string;
+    publishState: string;
+}
 export interface CreatedProject {
     projectId: string;
     slug: string;
     name: string;
-}
-export interface PublishResult {
-    version: number;
-    /** Immutable versioned URL (<slug>.<apex>/v<n>/). */
-    url: string;
-    /** Stable live alias (<slug>.<apex>/). */
+    orgId: string;
     liveUrl: string;
 }
 export declare class BackendError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+/** The address a caller asked for is not available. Carries the server's suggestions. */
+export declare class SlugTakenError extends BackendError {
+    readonly suggestions: string[];
+    constructor(suggestions: string[]);
+}
+/**
+ * The uniform 404 for every unreachable-project cause. The message is the
+ * server's, verbatim: the console shows the same six words, so a creator moving
+ * between surfaces sees one product and support can match a screenshot to a log
+ * line without a translation table.
+ */
+export declare class ProjectUnreachableError extends BackendError {
+    constructor(message: string);
+}
 /**
- * Create a backend project (reuses POST /projects). A `slug` pins the permanent
- * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
- * taken slug comes back 409, surfaced so the caller can re-ask.
+ * Register a project in an org. `slug` is optional and the server NEVER assigns
+ * one on a collision — it returns 409 with suggestions and the caller re-asks, so
+ * a creator's address is always a name they chose.
  */
-export declare function createProject(cfg: ResolvedConfig, name: string, slug?: string): Promise<CreatedProject>;
+export declare function createProject(cfg: ResolvedConfig, orgSlug: string, name: string, slug?: string): Promise<CreatedProject>;
+/** Read a project by id. Backs `link`; the org is derived server-side from the row. */
+export declare function getProject(cfg: ResolvedConfig, projectId: string): Promise<ProjectView>;
 export interface MintedTunnel {
     tunnelId: string;
     /** The public host the phone opens: <slug>-<token>.<previewApex>. */
@@ -39,20 +63,20 @@ export declare function reapTunnel(cfg: ResolvedConfig, projectId: string, ref:
 }): Promise<void>;
 /** Recursively list files under `dir`, returning dir-relative POSIX paths. */
 export declare function walkDir(dir: string, base?: string): Promise<string[]>;
-/**
- * Upload a locally-built dist and make it live. Each file rides as a multipart
- * part whose filename is its dist-relative path (the backend reconstructs the
- * tree). Requires an index.html at the dist root.
- */
-export declare function publishUpload(cfg: ResolvedConfig, projectId: string, distDir: string, opts?: {
-    note?: string;
-    commitSha?: string;
-}): Promise<PublishResult>;
+export interface MeMembership {
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    orgKind: "personal" | "team";
+    role: string;
+    status: string;
+}
 export interface Me {
     id?: string;
     email?: string;
     name?: string;
-    networkId?: string;
+    personalOrgId?: string;
+    memberships?: MeMembership[];
 }
 /** Resolve the signed-in identity for `vincentt whoami`. Throws on any non-2xx so
  *  the caller can degrade to "token present, unverified". */

package/dist/lib/backend.js

@@ -6,6 +6,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { authFailureMessage } from "../shared/authError.js";
 const execFileAsync = promisify(execFile);
 export class BackendError extends Error {
     status;
@@ -29,29 +30,106 @@ async function safeText(res) {
         return "";
     }
 }
+/** The address a caller asked for is not available. Carries the server's suggestions. */
+export class SlugTakenError extends BackendError {
+    suggestions;
+    constructor(suggestions) {
+        super("That address is taken.", 409);
+        this.suggestions = suggestions;
+        this.name = "SlugTakenError";
+    }
+}
+/**
+ * The uniform 404 for every unreachable-project cause. The message is the
+ * server's, verbatim: the console shows the same six words, so a creator moving
+ * between surfaces sees one product and support can match a screenshot to a log
+ * line without a translation table.
+ */
+export class ProjectUnreachableError extends BackendError {
+    constructor(message) {
+        super(message, 404);
+        this.name = "ProjectUnreachableError";
+    }
+}
+async function errorBody(res) {
+    try {
+        const parsed = await res.clone().json();
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
 /**
- * Create a backend project (reuses POST /projects). A `slug` pins the permanent
- * <slug>.vincentt.app host; omit it and the platform assigns a catchy one. A
- * taken slug comes back 409, surfaced so the caller can re-ask.
+ * Register a project in an org. `slug` is optional and the server NEVER assigns
+ * one on a collision — it returns 409 with suggestions and the caller re-asks, so
+ * a creator's address is always a name they chose.
  */
-export async function createProject(cfg, name, slug) {
-    const res = await authFetch(cfg, "/projects", {
+export async function createProject(cfg, orgSlug, name, slug) {
+    const res = await authFetch(cfg, `/orgs/${encodeURIComponent(orgSlug)}/projects`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ name, ...(slug ? { slug } : {}) }),
     });
     if (res.status === 409) {
-        throw new BackendError(`slug "${slug}" is already in use — pick another.`, 409);
+        const body = await errorBody(res);
+        if (body.code === "slug_taken") {
+            throw new SlugTakenError(Array.isArray(body.suggestions) ? body.suggestions : []);
+        }
     }
     if (!res.ok) {
-        throw new BackendError(`create project failed (${res.status}): ${await safeText(res)}`, res.status);
-    }
-    const p = (await res.json());
-    const projectId = p._id ?? p.id;
-    if (!projectId || !p.slug) {
-        throw new BackendError("create project: response missing id/slug");
+        const body = await errorBody(res);
+        // A 401 is the auth cutover, not a project error: authFailureMessage owns
+        // that wording. Every other status prefers the server's own message.
+        throw new BackendError(res.status === 401
+            ? authFailureMessage("create project failed", res.status, await safeText(res))
+            : (body.message ??
+                `create project failed (${res.status}): ${await safeText(res)}`), res.status);
+    }
+    const p = parseProjectView(await res.json(), "create project");
+    return {
+        projectId: p.id,
+        slug: p.slug,
+        name: p.name,
+        orgId: p.orgId,
+        liveUrl: p.liveUrl,
+    };
+}
+/** Read a project by id. Backs `link`; the org is derived server-side from the row. */
+export async function getProject(cfg, projectId) {
+    const res = await authFetch(cfg, `/projects/${encodeURIComponent(projectId)}`);
+    if (!res.ok) {
+        const body = await errorBody(res);
+        if (res.status === 404) {
+            throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
+        }
+        throw new BackendError(res.status === 401
+            ? authFailureMessage("get project failed", res.status, await safeText(res))
+            : (body.message ?? `get project failed (${res.status}): ${await safeText(res)}`), res.status);
     }
-    return { projectId, slug: p.slug, name: p.name ?? name };
+    return parseProjectView(await res.json(), "get project");
+}
+/**
+ * The wire shape is `id`, not `_id`. The legacy tolerance (`p._id ?? p.id`) is
+ * deliberately gone: it would have let an iteration-2-shaped response through
+ * silently, which is exactly how a contract break survives two green suites.
+ */
+function parseProjectView(raw, what) {
+    const p = (raw ?? {});
+    const str = (k) => typeof p[k] === "string" ? p[k] : undefined;
+    const id = str("id");
+    const slug = str("slug");
+    if (!id || !slug) {
+        throw new BackendError(`${what}: response missing id/slug`);
+    }
+    return {
+        id,
+        slug,
+        name: str("name") ?? slug,
+        orgId: str("orgId") ?? "",
+        liveUrl: str("liveUrl") ?? "",
+        publishState: str("publishState") ?? "never",
+    };
 }
 /** Mint a per-session dev tunnel for `localPort` (the backend holds CF creds). */
 export async function mintTunnel(cfg, projectId, localPort) {
@@ -61,7 +139,7 @@ export async function mintTunnel(cfg, projectId, localPort) {
         body: JSON.stringify({ port: localPort }),
     });
     if (!res.ok) {
-        throw new BackendError(`tunnel mint failed (${res.status}): ${await safeText(res)}`, res.status);
+        throw new BackendError(authFailureMessage("tunnel mint failed", res.status, await safeText(res)), res.status);
     }
     return (await res.json());
 }
@@ -100,48 +178,17 @@ export async function walkDir(dir, base = dir) {
     }
     return out;
 }
-/**
- * Upload a locally-built dist and make it live. Each file rides as a multipart
- * part whose filename is its dist-relative path (the backend reconstructs the
- * tree). Requires an index.html at the dist root.
- */
-export async function publishUpload(cfg, projectId, distDir, opts = {}) {
-    const files = await walkDir(distDir);
-    if (!files.includes("index.html")) {
-        throw new BackendError(`dist at ${distDir} has no index.html at its root — did the build run?`);
-    }
-    const form = new FormData();
-    // The real dist-relative paths ride as an ordered manifest — a multipart filename
-    // can't carry a directory (FormData strips it to a basename), so the backend maps
-    // paths[i] → files[i] to rebuild the tree.
-    form.append("paths", JSON.stringify(files));
-    for (const rel of files) {
-        const bytes = await fs.readFile(path.join(distDir, rel));
-        // Uint8Array (Buffer) is a valid BlobPart; the filename is cosmetic (the backend
-        // uses the manifest), but pass the basename so server logs read sensibly.
-        form.append("files", new Blob([bytes]), path.basename(rel));
-    }
-    if (opts.note)
-        form.append("note", opts.note);
-    if (opts.commitSha)
-        form.append("commitSha", opts.commitSha);
-    const res = await authFetch(cfg, `/projects/${projectId}/publish/upload`, {
-        method: "POST",
-        body: form,
-    });
-    if (!res.ok) {
-        throw new BackendError(`publish failed (${res.status}): ${await safeText(res)}`, res.status);
-    }
-    return (await res.json());
-}
 /** Resolve the signed-in identity for `vincentt whoami`. Throws on any non-2xx so
  *  the caller can degrade to "token present, unverified". */
 export async function getMe(cfg) {
-    const res = await authFetch(cfg, "/network/me");
+    const res = await authFetch(cfg, "/me");
     if (!res.ok) {
-        throw new BackendError(`/network/me failed (${res.status}): ${await safeText(res)}`, res.status);
+        throw new BackendError(authFailureMessage("Identity check failed", res.status, await safeText(res)), res.status);
     }
-    return (await res.json());
+    // GET /me returns { me: {...}, csrfToken }; unwrap it, but tolerate a bare user
+    // object so a contract tweak doesn't break whoami.
+    const body = (await res.json());
+    return (body.me ?? body);
 }
 /** The working tree's current commit, for publish provenance. Undefined if not a repo. */
 export async function gitHeadSha(cwd) {

package/dist/lib/diagnostics.d.ts

@@ -7,7 +7,32 @@ export declare function httpRelayClient(baseUrl: string): RelayClient;
 export declare function formatLog(e: LogEvent, now: number): string;
 export declare function formatNetwork(e: NetworkEvent, now: number): string;
 export declare function formatTrace(e: TraceEvent, now: number): string;
-/** Render a RelayResult for one kind into the text block a tool returns. */
+/**
+ * Render a RelayResult for one kind into the text block a tool returns.
+ *
+ * EVERY field is read defensively, because the CLI and the relay are versioned
+ * SEPARATELY on a user's machine even though they ship from one monorepo:
+ * `npx vincentt` fetches whatever the registry has, and points it at whatever
+ * relay `vincentt preview` happens to be running. A field this renderer reads
+ * unguarded is a field whose removal from the relay CRASHES an older CLI.
+ *
+ * That is not hypothetical — it is exactly what removing `sessions` did:
+ * `result.sessions.length` on a response that no longer carried the field took
+ * down the whole command, while `--json` kept working because it never touched
+ * it. A missing optional array must degrade to a missing LINE, never to an
+ * exception that hides the events the creator asked for.
+ */
 export declare function renderResult(result: RelayResult, kind: DiagEvent["kind"], now: number): string;
-/** Only-errors convenience filter applied on top of a log query result. */
+/**
+ * Only-errors convenience filter applied on top of a log query result.
+ *
+ * EVERY index-parallel array is filtered with the SAME predicate rather than
+ * passed through: dropping events without dropping their tags would shift each
+ * remaining tag by one and attribute every error to the wrong tester — which is
+ * worse than no attribution, because it looks right.
+ *
+ * Adding a parallel array to RelayResult means adding it here too. `eventTesters`
+ * arrived with tester attribution and was missed on the first pass, which is
+ * exactly the failure this comment already described.
+ */
 export declare function filterErrors(result: RelayResult): RelayResult;

package/dist/lib/diagnostics.js

@@ -36,26 +36,91 @@ export function formatTrace(e, now) {
     return (`${e.fps.toFixed(0)}fps over ${e.windowMs}ms · longest task ${e.longestTaskMs}ms · ` +
         `${e.longTaskCount} long task(s)${marks}  · ${ago(e.t, now)} #${e.seq}`);
 }
-/** Render a RelayResult for one kind into the text block a tool returns. */
+/**
+ * Render a RelayResult for one kind into the text block a tool returns.
+ *
+ * EVERY field is read defensively, because the CLI and the relay are versioned
+ * SEPARATELY on a user's machine even though they ship from one monorepo:
+ * `npx vincentt` fetches whatever the registry has, and points it at whatever
+ * relay `vincentt preview` happens to be running. A field this renderer reads
+ * unguarded is a field whose removal from the relay CRASHES an older CLI.
+ *
+ * That is not hypothetical — it is exactly what removing `sessions` did:
+ * `result.sessions.length` on a response that no longer carried the field took
+ * down the whole command, while `--json` kept working because it never touched
+ * it. A missing optional array must degrade to a missing LINE, never to an
+ * exception that hides the events the creator asked for.
+ */
 export function renderResult(result, kind, now) {
-    const lines = result.events.map((e) => {
+    const events = result.events ?? [];
+    const latestSeq = typeof result.latestSeq === "number" ? result.latestSeq : -1;
+    const lines = events.map((e) => {
         if (e.kind === "log")
             return formatLog(e, now);
         if (e.kind === "network")
             return formatNetwork(e, now);
         return formatTrace(e, now);
     });
-    const header = result.sessions.length > 1 ? `sessions: ${result.sessions.join(", ")}\n` : "";
-    const cursor = `\n\n(latestSeq ${result.latestSeq} — pass since=${result.latestSeq} to get only newer ${kind} events)`;
+    // Named whenever there is more than one tester, because a merged stream from
+    // four phones is not debuggable and the agent has to be told the filter
+    // exists.
+    //
+    // There is NO `sessions:` line. It printed the raw client-supplied session key
+    // to the terminal and into MCP tool output — a viewer-controlled string with
+    // no validation, on the path the viewer label is carefully guarded on. The
+    // tester id replaces it and is minted here, on this machine.
+    const header = [testersLine(result.testers), viewersLine(result.viewers)]
+        .filter(Boolean)
+        .join("\n");
+    const prefix = header ? `${header}\n` : "";
+    const cursor = `\n\n(latestSeq ${latestSeq} — pass since=${latestSeq} to get only newer ${kind} events)`;
     if (lines.length === 0) {
-        return `${header}No ${kind} events${result.latestSeq >= 0 ? " matched" : " yet — is the preview app open on the device?"}.${result.latestSeq >= 0 ? cursor : ""}`;
+        return `${prefix}No ${kind} events${latestSeq >= 0 ? " matched" : " yet — is the preview app open on the device?"}.${latestSeq >= 0 ? cursor : ""}`;
     }
-    return `${header}${lines.join("\n")}${cursor}`;
+    return `${prefix}${lines.join("\n")}${cursor}`;
 }
-/** Only-errors convenience filter applied on top of a log query result. */
+/**
+ * The tester line leads, because the tester is what an agent should filter on:
+ * it survives the reload a tester does before reporting a bug, so it is the
+ * coordinate that still resolves by the time anyone reads this.
+ */
+function testersLine(testers) {
+    if (!testers || testers.length < 2)
+        return "";
+    return `testers: ${testers.join(", ")} (pass tester to filter to one)`;
+}
+function viewersLine(viewers) {
+    if (!viewers || viewers.length < 2)
+        return "";
+    // "connection", not "device": one tab opens several of these, so calling a
+    // viewer a device is the wrong count in the same words that made "2 viewers"
+    // wrong on the roster.
+    return `viewers: ${viewers.join(", ")} (pass viewer to filter to one connection)`;
+}
+/**
+ * Only-errors convenience filter applied on top of a log query result.
+ *
+ * EVERY index-parallel array is filtered with the SAME predicate rather than
+ * passed through: dropping events without dropping their tags would shift each
+ * remaining tag by one and attribute every error to the wrong tester — which is
+ * worse than no attribution, because it looks right.
+ *
+ * Adding a parallel array to RelayResult means adding it here too. `eventTesters`
+ * arrived with tester attribution and was missed on the first pass, which is
+ * exactly the failure this comment already described.
+ */
 export function filterErrors(result) {
+    const events = result.events ?? [];
+    const keep = events.map((e) => e.kind === "log" && e.level === "error");
+    const parallel = (a) => a === undefined ? undefined : a.filter((_, i) => keep[i]);
     return {
         ...result,
-        events: result.events.filter((e) => e.kind === "log" && e.level === "error"),
+        events: events.filter((_, i) => keep[i]),
+        ...(result.eventViewers === undefined
+            ? {}
+            : { eventViewers: parallel(result.eventViewers) }),
+        ...(result.eventTesters === undefined
+            ? {}
+            : { eventTesters: parallel(result.eventTesters) }),
     };
 }

package/dist/lib/initCommand.d.ts

@@ -0,0 +1,14 @@
+export interface InitDeps {
+    print: (line: string) => void;
+    cwd: string;
+    scaffold?: (targetDir: string) => Promise<void>;
+    install?: (targetDir: string) => Promise<string>;
+    isEmpty?: (targetDir: string) => Promise<boolean>;
+}
+export interface InitOptions {
+    /** Positional target directory; defaults to the cwd. */
+    dir?: string;
+    /** Skip the dependency install (CI, or a creator who wants to pick a manager). */
+    skipInstall?: boolean;
+}
+export declare function initCommand(deps: InitDeps, opts?: InitOptions): Promise<number>;

package/dist/lib/initCommand.js

@@ -0,0 +1,75 @@
+// `vincentt init [dir]` — scaffold a Vincentt XR app. NO account, NO network call
+// to the API, NO binding written.
+//
+// This is the acquisition wedge: local-first is a smaller room, not a wall, so the
+// template must be reachable without ever touching the auth gate. `create` (which
+// does need an account) is offered at the end as the next thing AVAILABLE, never as
+// a requirement.
+import path from "node:path";
+import { detectPackageManager, installDependencies, needsScaffold, scaffoldFromTemplate, } from "../scaffold/index.js";
+export async function initCommand(deps, opts = {}) {
+    const target = path.resolve(deps.cwd, opts.dir ?? ".");
+    const label = opts.dir ? `./${opts.dir}` : ".";
+    const isEmpty = deps.isEmpty ?? needsScaffold;
+    if (!(await isEmpty(target))) {
+        deps.print(`✗ ${label} already contains an app (package.json).`);
+        deps.print("");
+        deps.print("  vincentt init <new-dir>   Scaffold somewhere else");
+        deps.print("  vincentt create           Register THIS folder as a project");
+        return 1;
+    }
+    deps.print(`→ Scaffolding a Vincentt XR app in ${label}…`);
+    deps.print("  · React + react-three-fiber + @vincentt-xr/sdk");
+    const scaffold = deps.scaffold ?? ((dir) => scaffoldFromTemplate(dir));
+    try {
+        await scaffold(target);
+    }
+    catch (err) {
+        deps.print("");
+        deps.print(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        deps.print("");
+        deps.print("  Run `vincentt init` again once that is resolved.");
+        return 1;
+    }
+    let installed = true;
+    if (!opts.skipInstall) {
+        deps.print("  · installing dependencies");
+        const install = deps.install ?? ((dir) => installDependencies(dir));
+        try {
+            await install(target);
+        }
+        catch {
+            installed = false;
+        }
+    }
+    // The template ships a pnpm lockfile and a hoisted node-linker, so telling a
+    // creator to `npm run dev` in it produces a second lockfile and an unproven
+    // node_modules layout. Name the manager the scaffold is actually set up for.
+    const pm = await detectPackageManager(target).catch(() => "npm");
+    deps.print("");
+    deps.print(`✓ Created ${label}`);
+    deps.print("");
+    const steps = [];
+    if (opts.dir)
+        steps.push([`cd ${opts.dir}`, ""]);
+    if (!installed || opts.skipInstall) {
+        steps.push([`${pm} install`, "Install dependencies"]);
+    }
+    steps.push([`${pm} run dev`, "Start the local dev server"]);
+    for (const line of alignedSteps(steps))
+        deps.print(line);
+    deps.print("");
+    deps.print("  No account needed. When you're ready to put it online:");
+    for (const line of alignedSteps([
+        ["vincentt login", "Connect this machine to Vincentt"],
+        ["vincentt create", "Register the project and reserve its address"],
+    ])) {
+        deps.print(line);
+    }
+    return 0;
+}
+/** Two columns, aligned on the widest command, so the block reads as a table. */
+function alignedSteps(steps) {
+    const width = Math.max(...steps.map(([cmd]) => cmd.length));
+    return steps.map(([cmd, note]) => note ? `  ${cmd.padEnd(width)}   ${note}` : `  ${cmd}`);
+}

package/dist/lib/lifecycle.d.ts

@@ -1,33 +1,80 @@
+import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
-import { type RunningPreview } from "../preview/index.js";
+import { type ResolvedConfig } from "../shared/config.js";
+import { type RunningPreview, type StartPreviewOptions } from "../preview/index.js";
 import type { DiagEventKind, RelayResult } from "@vincentt-xr/harness/events";
 export interface CreateOptions {
     name?: string;
     slug?: string;
-    scaffold?: boolean;
-    /** Rebind a directory that already has a binding (drops the old one). */
+    /** Replace a binding this folder already has. */
     force?: boolean;
-    /** Step-level progress for slow phases (scaffold, install). CLI prints; MCP omits. */
-    onProgress?: (message: string) => void;
+    /** --org <slug>; else VINCENTT_ORG; else the machine config's active org. */
+    org?: string;
+    /** Honor a binding's apiUrl override (--allow-custom-api). */
+    allowCustomApi?: boolean;
+    /**
+     * Stream the transcript as it happens. The CLI passes console.log so a slow
+     * create shows progress and the apiUrl advisory lands before the request; MCP
+     * omits it and reads the buffered `message`.
+     */
+    onLine?: (line: string) => void;
 }
 export interface CreateResult {
+    /** The full transcript, exactly as the CLI prints it. */
     message: string;
-    alreadyBound: boolean;
-    slug?: string;
-    projectId?: string;
+    /** Non-zero when nothing was created (already linked, address taken, no org). */
+    exitCode: number;
 }
+/**
+ * The shared `create` orchestration behind both `vincentt create` and the MCP
+ * `project_create` tool, so the two surfaces can never diverge in behavior OR in
+ * what they tell the caller.
+ *
+ * It does NOT scaffold — that is `vincentt init`, which needs no account. See
+ * `initCommand`.
+ */
 export declare function projectCreate(projectCwd: string, opts?: CreateOptions): Promise<CreateResult>;
+/**
+ * Resolve which org a create acts in: the named one if it is an ACTIVE membership,
+ * else the personal org when nothing is named. A named org the caller is not an
+ * active member of resolves to nothing rather than silently falling back — acting
+ * in an org the creator did not ask for is the retargeting the binding rules forbid.
+ */
+export declare function resolveOrgForCommand(cfg: ResolvedConfig, input: {
+    flag?: string;
+}): Promise<{
+    ok: true;
+    org: ResolvedOrg;
+} | {
+    ok: false;
+    message: string;
+}>;
 export interface PublishOptions {
     distDir?: string;
     note?: string;
+    allowCustomApi?: boolean;
+    /**
+     * Where the apiUrl advisory goes. It must reach the creator BEFORE the request,
+     * so it cannot ride the returned message — that is only rendered after the call
+     * has already happened (or thrown).
+     */
+    warn?: (line: string) => void;
+    /** Skip the confirmation. REFUSED on a first publish; see publishCommand. */
+    yes?: boolean;
 }
 export interface PublishOutcome {
+    /** The full transcript, exactly as the CLI prints it. */
     message: string;
-    notBound: boolean;
-    version?: number;
-    liveUrl?: string;
-    url?: string;
+    exitCode: number;
 }
+/**
+ * The shared `publish` orchestration behind both `vincentt publish` and the MCP
+ * `project_publish` tool, so the two surfaces can never diverge.
+ *
+ * MCP has no terminal, so it is a non-TTY caller: the command refuses without
+ * `--yes` rather than assuming consent, and refuses `--yes` outright on a first
+ * publish. An agent cannot make an address permanent.
+ */
 export declare function projectPublish(projectCwd: string, opts?: PublishOptions): Promise<PublishOutcome>;
 export declare function getActivePreview(): RunningPreview | null;
 export interface PreviewStartResult {
@@ -35,7 +82,14 @@ export interface PreviewStartResult {
     /** false when a preview was already running (the existing one is returned). */
     started: boolean;
 }
-export declare function previewStart(projectCwd: string, onLog: (msg: string) => void): Promise<PreviewStartResult>;
+/** Everything the runner needs that this process does not already know. */
+export type PreviewStartOptions = Omit<StartPreviewOptions, "projectCwd" | "config" | "projectId">;
+/**
+ * Resolve the binding and the config, then start. The binding is a HINT and
+ * never an authority (B12): the projectId it carries is presented to the API,
+ * which resolves the org itself and answers 404 for every unreachable cause.
+ */
+export declare function previewStart(projectCwd: string, onLog: (msg: string) => void, extra?: PreviewStartOptions): Promise<PreviewStartResult>;
 export declare function previewStop(): Promise<boolean>;
 export interface PreviewStopOutcome {
     stopped: boolean;
@@ -44,18 +98,30 @@ export interface PreviewStopOutcome {
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt
  * preview` runs in the background and the agent later wants it down). Reads the
- * pidfile and signals the recorded pids rather than the in-process `activePreview`.
- * SIGTERM to the preview process runs its graceful handler (which reaps the tunnel
- * + backend DNS route); if that process is already gone, its cloudflared child may
- * be orphaned to init, so kill the recorded tunnel pid directly. Either way, clear
- * the (now stale) relay info.
+ * pidfile and signals the recorded pid rather than the in-process
+ * `activePreview`.
+ *
+ * There is NO orphaned-tunnel case any more, and that is the point of the edge
+ * repoint: the tunnel is a socket this process owns rather than a child process
+ * that could be reparented to init. When the preview process dies the socket
+ * closes, the edge sees the tunnel go, and the session drains on its own — so
+ * SIGTERM plus clearing the stale relay info is the whole of the cleanup.
  */
 export declare function previewStopSignal(projectCwd: string): Promise<PreviewStopOutcome>;
 export interface DiagQueryOptions {
-    sessionId?: string;
     since?: number;
     limit?: number;
     errorsOnly?: boolean;
+    /**
+     * One tester — one browser tab, across its refreshes. The filter that answers
+     * "it breaks on their phone but not mine". Absent = every tester.
+     */
+    tester?: string;
+    /**
+     * One CONNECTION (2.8), the sub-coordinate below the tester. Absent = every
+     * viewer, which is the default read.
+     */
+    viewer?: string;
 }
 /** Raw diagnostics query against the running relay (used by CLI --json). */
 export declare function diagQuery(projectCwd: string, kind: DiagEventKind, opts?: DiagQueryOptions, relay?: RelayClient): Promise<RelayResult>;