@vincentt-xr/cli 0.1.5 → 0.2.0

package/dist/lib/projects.js

@@ -0,0 +1,217 @@
+// `vincentt create` / `link` / `unlink` — the f2 project verbs, in the CLI voice
+// (→ in progress, ✓ success, ✗ failure, ! advisory; every error ends with the exact
+// next command; a state-changing verb always announces what it wrote to disk).
+//
+// The IO boundary (print, backend, disk, cwd) is injected so every branch is
+// unit-testable without a real API, a real HOME, or a real repository.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { BackendError, SlugTakenError, createProject, getProject, } from "./backend.js";
+import { slugify } from "./slug.js";
+import { clearProjectBinding, loadProjectBinding, locateProjectBinding, writeProjectBinding, } from "../shared/config.js";
+/**
+ * `vincentt create` — register a project and link this folder to it.
+ *
+ * It does NOT scaffold. An unscaffolded folder gets a `!` advisory and the command
+ * PROCEEDS: the server accepts a create from any folder or none, and blocking here
+ * would put the open template behind the auth gate, which is the one thing the
+ * init/create split exists to prevent.
+ */
+export async function createCommand(deps, opts = {}) {
+    const existing = await loadProjectBinding(deps.cwd);
+    if (existing && !opts.force) {
+        deps.print(`✗ This folder is already linked to a project (${existing.slug}).`);
+        deps.print("");
+        deps.print("  Re-link it:   vincentt link <project-id>");
+        deps.print("  Detach it:    vincentt unlink");
+        deps.print("  Replace it:   vincentt create --force");
+        return 1;
+    }
+    if (!(await looksLikeVincenttApp(deps.cwd))) {
+        deps.print("!  This folder doesn't look like a Vincentt app (no package.json with @vincentt-xr/sdk).");
+        deps.print("   `vincentt create` registers a project — it doesn't scaffold one.");
+        deps.print("   To start from the template:  npx @vincentt-xr/cli init");
+        deps.print("");
+    }
+    const name = opts.name ?? path.basename(path.resolve(deps.cwd));
+    const slug = opts.slug ?? slugify(name);
+    if (!slug) {
+        deps.print("✗ Could not derive an address from that name.");
+        deps.print("");
+        deps.print(`  Run \`vincentt create --name "${name}" --slug <address>\` to pick one.`);
+        return 1;
+    }
+    // Printed BEFORE the round trip: the creator sees which address is about to be
+    // claimed on their behalf, not after the fact.
+    deps.print(`→ Checking ${slug}…`);
+    deps.print("");
+    const org = await deps.org();
+    if (!org.ok) {
+        deps.print(org.message);
+        return 1;
+    }
+    const cfg = await deps.config();
+    let created;
+    try {
+        created = await createProject(cfg, org.org.slug, name, slug);
+    }
+    catch (err) {
+        if (err instanceof SlugTakenError) {
+            printSlugTaken(deps.print, err.suggestions, name);
+            return 1;
+        }
+        throw err;
+    }
+    await writeProjectBinding(deps.cwd, {
+        projectId: created.projectId,
+        slug: created.slug,
+    });
+    deps.print(`✓ Created ${created.name} in ${org.org.name}`);
+    deps.print(`  Address reserved:  ${created.liveUrl}`);
+    deps.print(`  Linked this folder: .vincentt/project.json   (added to .gitignore)`);
+    deps.print("");
+    deps.print("  Nothing is served at that address until you publish.");
+    deps.print("  Run `vincentt preview` to try it on your phone.");
+    return 0;
+}
+/**
+ * Four words, byte-identical to the console's — it must read the same whether the
+ * holder is your own org, a stranger, a tombstone, a burn, or a reserved hostname.
+ * Suggestions are LISTED, never applied: the remedy restates the whole command so
+ * it is copy-pasteable, and the closing clause offers the creator's own choice as
+ * an equal option, so an agent reading this cannot conclude auto-picking is sanctioned.
+ */
+function printSlugTaken(print, suggestions, name) {
+    print("✗ That address is taken.");
+    print("");
+    if (suggestions.length > 0) {
+        print("  Available alternatives:");
+        for (const s of suggestions)
+            print(`    ${s}`);
+        print("");
+        print(`  Run \`vincentt create --name "${name}" --slug ${suggestions[0]}\` to use one,`);
+        print("  or pick your own with any --slug.");
+    }
+    else {
+        print(`  Run \`vincentt create --name "${name}" --slug <address>\` with another address.`);
+    }
+}
+// ---- link -------------------------------------------------------------------
+/**
+ * `vincentt link <project-id>` — one verb for four situations (console-first
+ * birth, a fresh clone, a folder that lost its binding, a re-link after
+ * `login --force`). It is a READ plus a local write: the server has no notion of
+ * "which folder", so linking is entirely client-side, gated only by the server's
+ * willingness to return the project at all.
+ */
+export async function linkCommand(deps, projectId) {
+    if (!projectId) {
+        deps.print("✗ Which project? `vincentt link` needs a project id.");
+        deps.print("");
+        deps.print("  vincentt link <project-id>   (copy it from the console)");
+        return 1;
+    }
+    const existing = await loadProjectBinding(deps.cwd);
+    const cfg = await deps.config();
+    let project;
+    try {
+        project = await getProject(cfg, projectId);
+    }
+    catch (err) {
+        if (err instanceof BackendError && err.status === 404) {
+            printUnreachable(deps.print, err.message);
+            return 1;
+        }
+        throw err;
+    }
+    if (existing && existing.projectId !== project.id) {
+        deps.print(`!  This folder is already linked to ${existing.slug}.`);
+        deps.print(`   Re-linking it to ${project.name}.`);
+        deps.print("");
+    }
+    await writeProjectBinding(deps.cwd, { projectId: project.id, slug: project.slug });
+    deps.print(`✓ Linked this folder to ${project.name}`);
+    if (project.liveUrl)
+        deps.print(`  Address: ${project.liveUrl}`);
+    deps.print("  Wrote .vincentt/project.json   (added to .gitignore)");
+    return 0;
+}
+/**
+ * The API's error messages are lowercase and unpunctuated by convention
+ * (`that handle is taken`, `this project is not available to you`), while both
+ * client surfaces present them as sentences. Casing is the ONLY thing either
+ * surface may change — the words are the server's, so a creator moving between
+ * the CLI and the console reads one sentence and support can match a screenshot
+ * to a log line without a translation table.
+ */
+export function asSentence(message) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return trimmed;
+    const cased = trimmed[0].toUpperCase() + trimmed.slice(1);
+    return /[.!?]$/.test(cased) ? cased : `${cased}.`;
+}
+/**
+ * Flow L10. Line 1 is the API's message; the body names both candidate causes and
+ * resolves neither (that is the maximum the anti-oracle contract permits, and it
+ * is accurate for all four real causes). `whoami` is offered first because it is
+ * the one diagnosis that discloses nothing about the project.
+ */
+export function printUnreachable(print, message) {
+    print(`✗ ${asSentence(message)}`);
+    print("");
+    print("  This folder is linked to a project that can't be reached with your current");
+    print("  account. It may have been deleted, or it may belong to an organization you're");
+    print("  not a member of.");
+    print("");
+    print("  Check who you are:   vincentt whoami");
+    print("  Re-link this folder: vincentt link <project-id>   (copy it from the console)");
+}
+// ---- unlink -----------------------------------------------------------------
+/**
+ * `vincentt unlink` — deletes the local binding. NO server call: the binding is a
+ * local pointer and the project is untouched, so there is nothing to tell the
+ * server about.
+ */
+export async function unlinkCommand(deps) {
+    const { hadBinding } = await clearProjectBinding(deps.cwd);
+    if (!hadBinding) {
+        // No glyph: neither success nor failure, just a fact.
+        deps.print("This folder isn't linked to a project.");
+        return 0;
+    }
+    deps.print("✓ Unlinked. Removed .vincentt/project.json");
+    deps.print("");
+    deps.print("  The project itself is untouched — this only disconnects this folder.");
+    deps.print("  Run `vincentt link <project-id>` to link it again.");
+    return 0;
+}
+// ---- shared -----------------------------------------------------------------
+/**
+ * The advisory's trigger: a package.json that depends on @vincentt-xr/sdk. It is a
+ * HINT only — create proceeds either way — so a false negative costs one extra
+ * line of output, never a refused command.
+ */
+export async function looksLikeVincenttApp(cwd) {
+    try {
+        const raw = await fs.readFile(path.join(cwd, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        return Object.keys(deps).some((d) => d.startsWith("@vincentt-xr/"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the bound project for a project-scoped verb, or explain why not. */
+export async function requireBinding(deps) {
+    const located = await locateProjectBinding(deps.cwd);
+    if (!located) {
+        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 undefined;
+    }
+    return { projectId: located.binding.projectId, slug: located.binding.slug };
+}

package/dist/lib/relayInfo.d.ts

@@ -5,9 +5,6 @@ export interface RelayInfo {
     url: string;
     /** The preview process pid, so a stale file can be detected. */
     pid: number;
-    /** The cloudflared child pid, so `preview --stop` can reap an orphaned tunnel
-     *  even after the preview process itself is gone (reparented to init). */
-    tunnelPid?: number;
     /** WS/HTTP path prefix routed to the relay (default /__harness). */
     harnessPath: string;
 }
@@ -15,3 +12,44 @@ export declare function relayInfoPath(cwd: string): string;
 export declare function writeRelayInfo(cwd: string, info: RelayInfo): Promise<string>;
 export declare function readRelayInfo(cwd: string): Promise<RelayInfo | undefined>;
 export declare function clearRelayInfo(cwd: string): Promise<void>;
+/**
+ * isProcessAlive is a NECESSARY but NOT SUFFICIENT check.
+ *
+ * `kill(pid, 0)` proves SOME process holds that pid, never that it is ours: pids
+ * are recycled, and after a reboot the number in a stale marker routinely
+ * belongs to something else entirely. It is kept as the cheap first gate — it
+ * rules out the common case (a killed CLI) with no I/O — and the relay probe
+ * below is what actually proves identity.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * isRelayResponding asks the recorded port whether OUR relay is behind it.
+ *
+ * This is the check that makes a recycled pid harmless: a `/query` that answers
+ * with a RelayResult-shaped body could only have come from a relay this CLI
+ * started. A stranger on that port answers something else, or nothing, and the
+ * marker is correctly judged stale.
+ *
+ * A short timeout, because this runs on the startup path of a command a creator
+ * runs fifty times a day, and the fallback (mint a preview) is what they asked
+ * for anyway.
+ */
+export declare function isRelayResponding(port: number, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<boolean>;
+/**
+ * readLivePreview returns the marker ONLY when it still describes a preview that
+ * is genuinely running, and CLEARS it otherwise.
+ *
+ * The marker is proof that a preview was STARTED, never that one is RUNNING: a
+ * crashed CLI, a `kill -9`, or a reboot all leave it behind. Trusting it
+ * unvalidated let `vincentt preview` short-circuit into "attaching…" followed by
+ * "the preview is no longer running", and exit — no mint, no session, and the
+ * creator's only recourse was deleting a dotfile they do not know exists. A
+ * marker that cannot be validated is not a marker.
+ *
+ * Clearing on the stale path is what stops the dead end from recurring on the
+ * next run.
+ */
+export declare function readLivePreview(cwd: string, deps?: {
+    processAlive?: (pid: number) => boolean;
+    relayResponding?: (port: number) => Promise<boolean>;
+}): Promise<RelayInfo | undefined>;

package/dist/lib/relayInfo.js

@@ -33,3 +33,97 @@ export async function clearRelayInfo(cwd) {
         // Already gone — clearing a non-existent info file is a no-op.
     }
 }
+/**
+ * isProcessAlive is a NECESSARY but NOT SUFFICIENT check.
+ *
+ * `kill(pid, 0)` proves SOME process holds that pid, never that it is ours: pids
+ * are recycled, and after a reboot the number in a stale marker routinely
+ * belongs to something else entirely. It is kept as the cheap first gate — it
+ * rules out the common case (a killed CLI) with no I/O — and the relay probe
+ * below is what actually proves identity.
+ */
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0); // signal 0 = existence check, kills nothing
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * isRelayResponding asks the recorded port whether OUR relay is behind it.
+ *
+ * This is the check that makes a recycled pid harmless: a `/query` that answers
+ * with a RelayResult-shaped body could only have come from a relay this CLI
+ * started. A stranger on that port answers something else, or nothing, and the
+ * marker is correctly judged stale.
+ *
+ * A short timeout, because this runs on the startup path of a command a creator
+ * runs fifty times a day, and the fallback (mint a preview) is what they asked
+ * for anyway.
+ */
+export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return false;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(`http://127.0.0.1:${port}/query`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ kind: "log", limit: 0 }),
+            signal: ac.signal,
+        });
+        if (!res.ok)
+            return false;
+        const body = await res.json();
+        // The SHAPE is the identity proof. Any 200 would do for liveness, but only
+        // a RelayResult says the thing answering is a Vincentt relay.
+        return (typeof body === "object" &&
+            body !== null &&
+            Array.isArray(body.events) &&
+            typeof body.latestSeq === "number");
+    }
+    catch {
+        // Refused, timed out, non-JSON, or something else on the port entirely.
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * readLivePreview returns the marker ONLY when it still describes a preview that
+ * is genuinely running, and CLEARS it otherwise.
+ *
+ * The marker is proof that a preview was STARTED, never that one is RUNNING: a
+ * crashed CLI, a `kill -9`, or a reboot all leave it behind. Trusting it
+ * unvalidated let `vincentt preview` short-circuit into "attaching…" followed by
+ * "the preview is no longer running", and exit — no mint, no session, and the
+ * creator's only recourse was deleting a dotfile they do not know exists. A
+ * marker that cannot be validated is not a marker.
+ *
+ * Clearing on the stale path is what stops the dead end from recurring on the
+ * next run.
+ */
+export async function readLivePreview(cwd, deps = {}) {
+    const info = await readRelayInfo(cwd);
+    if (!info)
+        return undefined;
+    const processAlive = deps.processAlive ?? isProcessAlive;
+    const relayResponding = deps.relayResponding ?? ((p) => isRelayResponding(p));
+    // The cheap gate first: a dead pid needs no network round trip.
+    if (info.pid !== undefined && !processAlive(info.pid)) {
+        await clearRelayInfo(cwd);
+        return undefined;
+    }
+    // The identity gate: alive-but-not-ours (a recycled pid) fails here.
+    if (!(await relayResponding(info.relayPort))) {
+        await clearRelayInfo(cwd);
+        return undefined;
+    }
+    return info;
+}

package/dist/lib/whoami.d.ts

@@ -0,0 +1,11 @@
+import type { Me } from "./backend.js";
+import { type ActiveOrgInput } from "./org.js";
+import type { ResolvedConfig } from "../shared/config.js";
+export interface WhoamiDeps {
+    print: (line: string) => void;
+    /** The machine's API host + PAT. The BINDING's apiUrl is never used here. */
+    config: () => Promise<ResolvedConfig | undefined>;
+    getMe: (cfg: ResolvedConfig) => Promise<Me>;
+    org: ActiveOrgInput;
+}
+export declare function whoamiCommand(deps: WhoamiDeps): Promise<number>;

package/dist/lib/whoami.js

@@ -0,0 +1,38 @@
+// `vincentt whoami` — Flow L10's first offered remedy.
+//
+// Two of the four unreachable-binding causes (`login --force`, a different machine
+// identity) are diagnosable entirely client-side with zero server disclosure, which
+// makes this the one diagnosis the anti-oracle contract cannot object to. That only
+// holds if the command actually answers, so its correctness is load-bearing for
+// f2's hardest copy rather than cosmetic.
+import { resolveActiveOrg } from "./org.js";
+export async function whoamiCommand(deps) {
+    const cfg = await deps.config();
+    if (!cfg) {
+        deps.print("Not signed in. Run `vincentt login`.");
+        return 1;
+    }
+    let me;
+    try {
+        me = await deps.getMe(cfg);
+    }
+    catch (err) {
+        // Reserved for a GENUINE transport failure. The two lines a creator can act on
+        // are named, because "unverified" alone tells someone who does not know who
+        // they are that we do not either.
+        deps.print(`!  Could not reach ${cfg.apiUrl} — your token is present but unverified.`);
+        deps.print("   Check your connection, or `vincentt login` if you believe it expired.");
+        void err;
+        return 1;
+    }
+    const who = me.email ?? me.name ?? me.id ?? "(unknown account)";
+    const org = resolveActiveOrg(me, deps.org);
+    deps.print(`Signed in as ${who}`);
+    // Printed even when there is no active org: an absent line is indistinguishable
+    // from a bug on exactly the path where the creator is already confused.
+    deps.print(org
+        ? `  Active org:  ${org.name} (${org.slug})`
+        : "  Active org:  none — pass --org <slug>");
+    deps.print(`  API:         ${cfg.apiUrl}`);
+    return 0;
+}

package/dist/login/authBackend.d.ts

@@ -0,0 +1,30 @@
+export interface Membership {
+    /** Org display name (e.g. "Acme", or "Personal (alice)" for the personal org). */
+    orgName: string;
+    /** "personal" | "team" — the personal org is the default active org. */
+    orgKind: "personal" | "team";
+    role?: string;
+}
+export interface Identity {
+    email: string;
+    /** All orgs the signed-in user belongs to (switcher source). */
+    memberships: Membership[];
+}
+/**
+ * The auth-flow backend seam. `exchange` redeems the PKCE code for a raw PAT; `me` confirms
+ * identity + orgs with that PAT. Both are injected so a stub backend drives the CLI tests.
+ */
+export interface AuthBackend {
+    /** POST /access-tokens/exchange {code, code_verifier} → the raw PAT ("vct_…"). */
+    exchange(code: string, codeVerifier: string): Promise<string>;
+    /** GET /me with Bearer <pat> → identity + orgs. */
+    me(pat: string): Promise<Identity>;
+}
+/** The real HTTP-backed AuthBackend, pointed at a Vincentt API base URL. */
+export declare function httpAuthBackend(apiBase: string): AuthBackend;
+/**
+ * Map the /me response shape onto our Identity. The backend returns memberships with an org
+ * name + kind; we keep the projection resilient to the exact field names the Go handler emits
+ * (name/orgName, kind/orgKind) so a minor contract wording change doesn't break login.
+ */
+export declare function normalizeMe(raw: unknown): Identity;

package/dist/login/authBackend.js

@@ -0,0 +1,80 @@
+// The two backend calls the CLI makes during `vincentt login`, isolated behind a small
+// interface so the loopback orchestration (pkceLogin.ts) is testable against a stub
+// backend (QA-F1-C2/C4/C5) without real HTTP.
+//
+// Note the CLI does NOT call POST /access-tokens — the browser/console does that (it holds
+// the JWT session; a PAT may not mint a PAT). The CLI only redeems the returned auth_code:
+//   POST /access-tokens/exchange {code, code_verifier} → {token}   (raw PAT, once, in body)
+//   GET  /me            Bearer <PAT>                    → identity + orgs (confirm)
+import { authFailureMessage } from "../shared/authError.js";
+class AuthError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "AuthError";
+    }
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+/** The real HTTP-backed AuthBackend, pointed at a Vincentt API base URL. */
+export function httpAuthBackend(apiBase) {
+    const base = apiBase.replace(/\/$/, "");
+    return {
+        async exchange(code, codeVerifier) {
+            const res = await fetch(`${base}/access-tokens/exchange`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ code, code_verifier: codeVerifier }),
+            });
+            if (!res.ok) {
+                throw new AuthError(`Token exchange failed (${res.status}): ${await safeText(res)}`, res.status);
+            }
+            const body = (await res.json());
+            if (!body.token)
+                throw new AuthError("Token exchange returned no token.");
+            return body.token;
+        },
+        async me(pat) {
+            const res = await fetch(`${base}/me`, {
+                headers: { authorization: `Bearer ${pat}` },
+            });
+            if (!res.ok) {
+                throw new AuthError(authFailureMessage("Identity check failed", res.status, await safeText(res)), res.status);
+            }
+            return normalizeMe(await res.json());
+        },
+    };
+}
+/**
+ * Map the /me response shape onto our Identity. The backend returns memberships with an org
+ * name + kind; we keep the projection resilient to the exact field names the Go handler emits
+ * (name/orgName, kind/orgKind) so a minor contract wording change doesn't break login.
+ */
+export function normalizeMe(raw) {
+    const envelope = (raw ?? {});
+    // GET /me returns { me: {...}, csrfToken }. Unwrap it, but stay resilient to a
+    // bare user object so a contract tweak doesn't break login.
+    const o = (envelope.me && typeof envelope.me === "object" ? envelope.me : envelope);
+    const email = typeof o.email === "string" ? o.email : "";
+    const rawMemberships = Array.isArray(o.memberships) ? o.memberships : [];
+    const memberships = rawMemberships.map((m) => {
+        const r = (m ?? {});
+        const orgName = (typeof r.orgName === "string" && r.orgName) ||
+            (typeof r.name === "string" && r.name) ||
+            "";
+        const kind = r.orgKind ?? r.kind;
+        return {
+            orgName,
+            orgKind: kind === "team" ? "team" : "personal",
+            role: typeof r.role === "string" ? r.role : undefined,
+        };
+    });
+    return { email, memberships };
+}

package/dist/login/guard.d.ts

@@ -0,0 +1,13 @@
+export interface RequireSignedInDeps {
+    /** The token that would authenticate a machine call, if any (env override or config). */
+    currentToken: () => Promise<string | undefined>;
+    /** Emit a line (stderr, so it never pollutes machine-readable stdout). */
+    print: (line: string) => void;
+}
+/**
+ * True when a token is present. When absent, prints the L3 not-signed-in message and returns
+ * false. The exact copy is locked by the f1 design:
+ *   ✗ You're not signed in.
+ *     Run `vincentt login` to connect this machine to your Vincentt account.
+ */
+export declare function requireSignedIn(deps: RequireSignedInDeps): Promise<boolean>;

package/dist/login/guard.js

@@ -0,0 +1,17 @@
+// The not-signed-in voice (Flow L3). f1 defines this voice; any gated command (f2+) uses
+// it via `requireSignedIn`. When no token is present it prints the exact two-line message
+// and reports "not signed in" so the caller can abort with a non-zero exit — no stack trace,
+// no auto-browser-launch (that's `ensureLoggedIn`'s convenience path; the gate is explicit).
+/**
+ * True when a token is present. When absent, prints the L3 not-signed-in message and returns
+ * false. The exact copy is locked by the f1 design:
+ *   ✗ You're not signed in.
+ *     Run `vincentt login` to connect this machine to your Vincentt account.
+ */
+export async function requireSignedIn(deps) {
+    if (await deps.currentToken())
+        return true;
+    deps.print("✗ You're not signed in.");
+    deps.print("  Run `vincentt login` to connect this machine to your Vincentt account.");
+    return false;
+}

package/dist/login/loginCommand.d.ts

@@ -0,0 +1,39 @@
+import type { Identity, Membership } from "./authBackend.js";
+/** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
+export declare function displayConfigPath(absPath: string, home: string): string;
+/** The active org is the personal one (login lands on personal; the CLI never prompts). */
+export declare function activeOrg(memberships: Membership[]): Membership | undefined;
+/**
+ * The success line's org clause: "Active org: <personal>" plus, when the user belongs to
+ * team orgs too, "· also a member of: A, B". A platform-invited creator with only a personal
+ * org gets just the active-org line (no trailing clause).
+ */
+export declare function orgSummaryLine(identity: Identity): string;
+export interface LoginCommandDeps {
+    /** Print a line to the user (stdout for the transcript). */
+    print: (line: string) => void;
+    /** The token currently on this machine, if any (env override or config file). */
+    currentToken: () => Promise<string | undefined>;
+    /** Confirm who a present token belongs to (GET /me). Undefined if it can't be resolved. */
+    whoAmI: () => Promise<Identity | undefined>;
+    /** Run the loopback + PKCE flow; resolves identity + the saved config path. */
+    runLogin: () => Promise<{
+        identity: Identity;
+        configPath: string;
+    }>;
+    /** Forget the existing token before a --force re-login. */
+    clearToken: () => Promise<void>;
+    /** For displaying the config path as ~/…. */
+    home: string;
+    /** Absolute config path (for the L2 already-signed-in line). */
+    configPath: string;
+}
+export interface LoginCommandOptions {
+    force?: boolean;
+}
+/**
+ * Drive `vincentt login`. Returns an exit code (0 ok, 1 failed). Never throws for expected
+ * failure states (timeout, cancel, state-mismatch) — they print a ✗ line ending with the
+ * exact retry command and return 1. No stack trace, no token printed.
+ */
+export declare function loginCommand(deps: LoginCommandDeps, opts?: LoginCommandOptions): Promise<number>;