@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/cli/cloud-kit.d.ts

@@ -31,5 +31,17 @@ export declare const baseUrl: (session: {
 export declare const bearer: (session: {
     token: string;
 } | null) => string | null;
+/**
+ * The platform refused the credential this command sent. Its generic answer ("sign in or API key
+ * required") read as if none had been set; a revoked key, or one whose owner was removed from the
+ * workspace, needs replacing, not adding.
+ */
+export declare class CredentialRefusedError extends Error {
+    readonly status: number;
+    readonly apiKey: boolean;
+    constructor(status: number, apiKey: boolean, 
+    /** The platform's own reason, when it named one (`refusalSaid`). */
+    reason?: string);
+}
 /** One `/v1` call. Throws a friendly Error on a non-2xx so the command surfaces it and exits 1. */
 export declare const api: (method: string, url: string, token: string | null, body?: unknown) => Promise<unknown>;

package/dist/command/cli/cloud-kit.js

@@ -8,6 +8,7 @@
  * `cloud-login` is the first to move — and it is a real seam rather than a file-size dodge: nothing
  * here knows what a project, a credential or a link is.
  */
+import { KEY_REFUSED, refusalSaid } from '../../memory/project/sync-status.js';
 import { DEFAULT_PLATFORM_URL, apiKeyFrom, cloudUrlFrom } from '@reticlehq/core';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -83,6 +84,32 @@ export const baseUrl = (session, explicit) => {
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
 export const bearer = (session) => apiKeyFrom(process.env) ?? session?.token ?? null;
+/** The platform's code for a missing or refused credential, as opposed to a permission. */
+const GENERIC_REFUSAL = 'unauthorized';
+/** A credential the platform answered with: not accepted, rather than not given. */
+const REFUSED_STATUSES = new Set([401, 403]);
+/**
+ * The platform refused the credential this command sent. Its generic answer ("sign in or API key
+ * required") read as if none had been set; a revoked key, or one whose owner was removed from the
+ * workspace, needs replacing, not adding.
+ */
+export class CredentialRefusedError extends Error {
+    status;
+    apiKey;
+    constructor(status, apiKey, 
+    /** The platform's own reason, when it named one (`refusalSaid`). */
+    reason) {
+        super(apiKey
+            ? `the platform refused this API key (${String(status)}): ${reason === undefined || KEY_REFUSED === reason
+                ? 'it was revoked, or its owner no longer has access to the workspace'
+                : reason.replace(/\.$/, '')}. Mint a new key in Settings → API keys and set RETICLE_API_KEY to it.`
+            : `the platform refused your sign-in (${String(status)}): ${reason === undefined || KEY_REFUSED === reason
+                ? 'it expired, was revoked, or you no longer have access to the workspace'
+                : reason.replace(/\.$/, '')}. Run \`reticle login\`.`);
+        this.status = status;
+        this.apiKey = apiKey;
+    }
+}
 /** One `/v1` call. Throws a friendly Error on a non-2xx so the command surfaces it and exits 1. */
 export const api = async (method, url, token, body) => {
     const headers = {};
@@ -108,8 +135,20 @@ export const api = async (method, url, token, body) => {
         }
     }
     if (!res.ok) {
-        const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(json);
-        throw new Error(parsed.success ? parsed.data.error.message : `${res.status} ${res.statusText}`);
+        const parsed = z
+            .object({ error: z.object({ message: z.string(), code: z.string().optional() }) })
+            .safeParse(json);
+        const said = parsed.success ? parsed.data.error.message : `${res.status} ${res.statusText}`;
+        // A 403 the platform explains as something else (a contributor creating a project) is a
+        // permission, not a refused credential: printed as it is worded, never as "sign in again".
+        const permission = 403 === res.status &&
+            parsed.success &&
+            KEY_REFUSED === refusalSaid(text) &&
+            GENERIC_REFUSAL !== parsed.data.error.code;
+        if (token !== null && REFUSED_STATUSES.has(res.status) && !permission) {
+            throw new CredentialRefusedError(res.status, token === apiKeyFrom(process.env), refusalSaid(text));
+        }
+        throw new Error(said);
     }
     return json;
 };

package/dist/command/cli/cloud-link.d.ts

@@ -0,0 +1,57 @@
+import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+import { z } from 'zod';
+/**
+ * What a key is good for, or undefined when the cloud will not accept it.
+ *
+ * Never throws: a revoked key, a rotated one and an unreachable cloud are all "cannot reuse this",
+ * and the caller's answer to every one of them is the same — mint a fresh one.
+ */
+export declare const validateKey: (url: string, key: string) => Promise<z.infer<typeof WhoamiSchema> | undefined>;
+declare const WhoamiSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    projectName: z.ZodString;
+    /**
+     * Which tenant the key belongs to. Optional for the same reason `dashboardUrl` is — an older
+     * cloud does not send it — and when it is missing a stored key cannot be proved to be ours, which
+     * is why the reuse path below mints instead of guessing.
+     */
+    orgId: z.ZodOptional<z.ZodString>;
+    /**
+     * Where this project's dashboard lives. Optional because an older cloud does not send it, and a
+     * CLI that refused to link against one would break the thing it is supposed to connect.
+     */
+    dashboardUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    projectId: string;
+    projectName: string;
+    orgId?: string | undefined;
+    dashboardUrl?: string | undefined;
+}, {
+    projectId: string;
+    projectName: string;
+    orgId?: string | undefined;
+    dashboardUrl?: string | undefined;
+}>;
+export interface PlatformLinked {
+    via: PlatformLinkVia;
+    /** The project this folder was bound to before, if any: a re-run against it is not a new link. */
+    priorProjectId: unknown;
+    projectId: string;
+    /** The workspace's platform id, when the cloud said. */
+    workspaceId: string | undefined;
+}
+/** Hear every link this process makes. One listener: a second replaces the first. */
+export declare function onPlatformLinked(next: (link: PlatformLinked) => void): void;
+export declare function notePlatformLinked(link: PlatformLinked): void;
+/**
+ * `reticle link [--project <id>]` — bind THIS repo to a cloud project. With a login token it MINTS a
+ * project-scoped key (no pasting); with a pre-set RETICLE_API_KEY it resolves the key's project via
+ * whoami. Writes the non-secret binding to <repo>/.reticle/cloud.json and the secret key to
+ * ~/.reticle/credentials.json (keyed by projectId).
+ */
+export declare const cmdLink: (argv: readonly string[], 
+/** The folder to link. The CLI's own; the daemon passes the folder of the tab that asked. */
+cwd?: string, 
+/** What started this link, for `platform_linked`. */
+via?: PlatformLinkVia) => Promise<number>;
+export {};

package/dist/command/cli/cloud-link.js

@@ -0,0 +1,308 @@
+/**
+ * `reticle link` — binding this repo to a cloud project, and the key that binding sends with.
+ *
+ * Split from `cloud-cli` because it is one story with its own rules: which project a bare `link`
+ * targets, when a key already on this machine may be reused and when it provably belongs to another
+ * tenant, and what is written where (`<repo>/.reticle/cloud.json` and `~/.reticle/credentials.json`).
+ * Every other cloud verb only reads what this writes.
+ */
+import { inWorkspace, repoIdentity, resolveProjectId, defaultProjectFor } from './project-name.js';
+import { apiKeyFrom } from '@reticlehq/core';
+import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { z } from 'zod';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { CLOUD_LINK_FILE } from '../../memory/cloud/cloud-config.js';
+import { applyCredential, findCredential } from './auth/cloud-keystore.js';
+import { linkDirectoryFrom } from '../../memory/project/link-directory.js';
+import { RETICLE_CONFIG_BASENAME, readProjectId } from './ports/resolve/cli-port.js';
+import { api, baseUrl, CREDENTIALS_FILE, emit, err, flags, hint, home, readJson, readSession, readSessionFor, RETICLE_DIR, } from './cloud-kit.js';
+/**
+ * How a key is named out loud: enough to match it against the dashboard, never enough to use.
+ *
+ * The same shape the web console shows, so the two name one key identically and somebody can tell
+ * at a glance which row this repo is using.
+ */
+const KEY_HINT_CHARS = 16;
+const keyHint = (key) => key.length <= KEY_HINT_CHARS ? key : `${key.slice(0, KEY_HINT_CHARS)}…`;
+/**
+ * The api key this machine already holds for a project ON THIS CLOUD, if any.
+ *
+ * Two shapes, matching the resolver: `{ key, url }` is what `link` writes now and is only returned
+ * when the URL matches, and a bare string is the legacy shape with no URL to check. Without the URL
+ * check this would happily reuse a production key for a self-hosted link, because `link` names
+ * every project "default" and the two collide in one slot.
+ */
+const storedCredential = async (projectId, url, orgId) => findCredential(await readJson(join(home(), CREDENTIALS_FILE)), projectId, url, orgId);
+/**
+ * What a key is good for, or undefined when the cloud will not accept it.
+ *
+ * Never throws: a revoked key, a rotated one and an unreachable cloud are all "cannot reuse this",
+ * and the caller's answer to every one of them is the same — mint a fresh one.
+ */
+export const validateKey = async (url, key) => {
+    try {
+        return WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, key));
+    }
+    catch {
+        return undefined;
+    }
+};
+const KeySchema = z.object({ projectId: z.string(), projectName: z.string(), key: z.string() });
+const WhoamiSchema = z.object({
+    projectId: z.string(),
+    projectName: z.string(),
+    /**
+     * Which tenant the key belongs to. Optional for the same reason `dashboardUrl` is — an older
+     * cloud does not send it — and when it is missing a stored key cannot be proved to be ours, which
+     * is why the reuse path below mints instead of guessing.
+     */
+    orgId: z.string().optional(),
+    /**
+     * Where this project's dashboard lives. Optional because an older cloud does not send it, and a
+     * CLI that refused to link against one would break the thing it is supposed to connect.
+     */
+    dashboardUrl: z.string().optional(),
+});
+let listener;
+/** Hear every link this process makes. One listener: a second replaces the first. */
+export function onPlatformLinked(next) {
+    listener = next;
+}
+export function notePlatformLinked(link) {
+    try {
+        listener?.(link);
+    }
+    catch {
+        /* a listener never fails a link */
+    }
+}
+/**
+ * `reticle link [--project <id>]` — bind THIS repo to a cloud project. With a login token it MINTS a
+ * project-scoped key (no pasting); with a pre-set RETICLE_API_KEY it resolves the key's project via
+ * whoami. Writes the non-secret binding to <repo>/.reticle/cloud.json and the secret key to
+ * ~/.reticle/credentials.json (keyed by projectId).
+ */
+export const cmdLink = async (argv, 
+/** The folder to link. The CLI's own; the daemon passes the folder of the tab that asked. */
+cwd = process.cwd(), 
+/** What started this link, for `platform_linked`. */
+via = PlatformLinkVia.LINK) => {
+    const f = flags(argv);
+    const url = baseUrl(await readSession(), f['url']);
+    // Same rule as every other authed verb: the token is looked up by the host it will be sent to.
+    const session = await readSessionFor(url);
+    const envKey = apiKeyFrom(process.env);
+    /*
+     * Read the existing binding FIRST, because it decides which project a bare `link` targets.
+     * Re-running `link` is ordinary — rotating a key, repointing an environment — and it must land in
+     * the project this repo already reports to, or its history splits in two without saying so.
+     */
+    // The project's own folder, which is where a session from here writes its runs. A link made before
+    // this, in the folder `link` was run from, is still read as the prior binding.
+    const projectDir = linkDirectoryFrom(cwd);
+    const priorLink = (await readJson(join(projectDir, RETICLE_DIR, CLOUD_LINK_FILE))) ??
+        (await readJson(join(cwd, RETICLE_DIR, CLOUD_LINK_FILE)));
+    const priorProjectId = 'object' === typeof priorLink && priorLink !== null
+        ? priorLink['projectId']
+        : undefined;
+    let projectId;
+    let projectName;
+    let key;
+    /**
+     * The tenant this binding belongs to, recorded so the credential can be filed and found per-org.
+     * Undefined against an older cloud, where the slot stays cloud+project as it always was.
+     */
+    let orgId;
+    let workspace; // the binding's, said when the sign-in names it
+    let repo; // which repository and folder, so a same-named app is not shared
+    /** The key this machine already had for the slot, and whether it provably belongs to another tenant. */
+    let priorKey;
+    let priorIsForeign = false;
+    /*
+     * Where this project's dashboard lives. Asked of the cloud rather than derived from `url`: the API
+     * origin and the console origin are different hosts in every deployment that is not a laptop, so a
+     * link the CLI guessed would be wrong exactly where it matters.
+     */
+    let dashboardUrl;
+    /** Whether the key was already on this machine — so the report can say so instead of "minted". */
+    let reusedKey = false;
+    // Tracked separately from the value: an OLDER cloud answers whoami without a dashboardUrl, and
+    // keying the fallback off the value would ask the same question twice every time.
+    let askedWhoami = false;
+    if (envKey !== undefined && envKey.length > 0) {
+        const who = WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, envKey));
+        projectId = who.projectId;
+        projectName = who.projectName;
+        dashboardUrl = who.dashboardUrl;
+        orgId = who.orgId;
+        askedWhoami = true;
+        key = envKey;
+    }
+    else if (session !== null) {
+        // --project accepts a slug id OR a display name; default when omitted. Resolve to the canonical id.
+        const wanted = f['project'];
+        /*
+         * A repo is named after itself, not "Default".
+         *
+         * When every repo binds to one project called "Default", two unrelated checkouts on one account
+         * merge their runs, issues and impact into a single bucket and the per-project view describes
+         * nothing. It is also what lets two TENANTS collide, since a credential slot built from a
+         * project id is only as distinct as the ids are.
+         */
+        const fallback = defaultProjectFor(basename(projectDir), 'string' === typeof priorProjectId ? priorProjectId : undefined, readProjectId(projectDir));
+        workspace = session.orgName;
+        repo = repoIdentity(projectDir);
+        // Only a default create asks for the folder's own id; a named or already-linked one is kept.
+        const localId = wanted === undefined && 'string' !== typeof priorProjectId
+            ? readProjectId(projectDir)
+            : undefined;
+        const targetId = await resolveProjectId(url, session.token, wanted ?? fallback, workspace, repo, localId);
+        /*
+         * Reuse the key this machine already holds for the project, rather than minting another.
+         *
+         * `link` was idempotent about the BINDING and not about the KEY: two runs against one project
+         * left two live `reticle-cli` keys on the account, each valid, neither identifiable to a repo.
+         * Agents retry — that is what agents do — so it accumulates silently until somebody has a key
+         * list they cannot reason about and revokes the wrong one.
+         *
+         * Validated before trusting, because a stored key can have been revoked or rotated from the
+         * dashboard and a stale credential must not strand the repo. The check is the whoami call the
+         * mint path already makes for `dashboardUrl`, so the common path costs no extra round trip —
+         * and a key that fails it is replaced rather than reported.
+         */
+        const existing = await storedCredential(targetId, url, session.orgId);
+        const validated = existing === undefined ? undefined : await validateKey(url, existing);
+        /*
+         * A valid key is not the same as OUR key.
+         *
+         * `validateKey` only asks whether the cloud still accepts it, and a key belonging to another
+         * organisation on the same cloud passes that question perfectly. With every project named
+         * "default", the slot `<url>::default` was shared across tenants — so a brand-new workspace
+         * signing in on a machine that had linked a different account reused that account's key and
+         * would have pushed its runs into a stranger's dashboard. Measured, not hypothesised.
+         *
+         * So reuse now requires PROOF of a tenant match, and treats anything less as no match: an older
+         * cloud that omits `orgId`, or a session file written before we recorded one, both fall through
+         * to minting. Minting a second key is a tidiness problem; pushing to the wrong tenant is a
+         * disclosure, and only one of those is worth defaulting to.
+         */
+        const sameTenant = validated !== undefined &&
+            session.orgId !== undefined &&
+            validated.orgId !== undefined &&
+            validated.orgId === session.orgId;
+        const reusable = sameTenant ? validated : undefined;
+        priorKey = existing;
+        // Provably somebody else's: it still works on this cloud AND whoami names a different org. A key
+        // that merely FAILED validation is our own revoked one, and overwriting that is the point.
+        priorIsForeign =
+            validated !== undefined &&
+                validated.orgId !== undefined &&
+                session.orgId !== undefined &&
+                validated.orgId !== session.orgId;
+        if (existing !== undefined && reusable !== undefined) {
+            projectId = reusable.projectId;
+            projectName = reusable.projectName;
+            dashboardUrl = reusable.dashboardUrl;
+            orgId = reusable.orgId;
+            askedWhoami = true;
+            key = existing;
+            reusedKey = true;
+        }
+        else {
+            const minted = KeySchema.parse(await api('POST', `${url}/v1/keys`, session.token, {
+                name: 'reticle-cli',
+                projectId: targetId,
+            }));
+            projectId = minted.projectId;
+            projectName = minted.projectName;
+            key = minted.key;
+            // The key was minted WITH this session, so its tenant is this session's by construction.
+            orgId = session.orgId;
+        }
+    }
+    else {
+        err('run `reticle connect` first, or set RETICLE_API_KEY to link with an existing key');
+        return 2;
+    }
+    const reticleDir = join(projectDir, RETICLE_DIR);
+    await mkdir(reticleDir, { recursive: true });
+    const linkPath = join(reticleDir, CLOUD_LINK_FILE);
+    const prev = await readJson(linkPath);
+    const prevObj = 'object' === typeof prev && prev !== null ? prev : {};
+    // The minted-key path has not asked yet. Best-effort: a link that works is worth more than a link
+    // that also has a link in it, and an older cloud simply does not send one.
+    if (!askedWhoami) {
+        try {
+            const who = WhoamiSchema.parse(await api('GET', `${url}/v1/cloud/whoami`, key));
+            dashboardUrl = who.dashboardUrl;
+            // Only FILL IN a tenant we do not have. The session we minted with is the authority on which
+            // org this key belongs to; letting a later lookup overwrite it is how the answer drifts.
+            orgId = orgId ?? who.orgId;
+        }
+        catch {
+            // Older cloud, or a transient failure. The HUD shows its list without a link.
+        }
+    }
+    const cloudJson = {
+        projectId,
+        projectName,
+        // Recorded so the daemon resolves the credential in the ORG slot rather than the ambiguous
+        // cloud+project one, which two tenants on one cloud both answer to.
+        ...(orgId === undefined ? {} : { orgId }),
+        url,
+        ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
+        ...(repo === undefined ? {} : { repo }),
+        // The workspace's name, so `reticle status` can say where this repo sends.
+        ...(workspace === undefined ? {} : { workspace }),
+        sync: prevObj['sync'] ?? { runs: true, memory: true, flows: true },
+        verify: prevObj['verify'] ?? 'local',
+    };
+    await writeFile(linkPath, `${JSON.stringify(cloudJson, null, 2)}\n`);
+    await mkdir(home(), { recursive: true });
+    const credPath = join(home(), CREDENTIALS_FILE);
+    const creds = (await readJson(credPath)) ?? {};
+    const credObj = applyCredential('object' === typeof creds && creds !== null ? creds : {}, { projectId, url, key, orgId, priorKey, priorIsForeign });
+    await writeFile(credPath, `${JSON.stringify(credObj, null, 2)}\n`);
+    emit({ linked: projectName, projectId, cloudJson: linkPath, credentials: credPath });
+    notePlatformLinked({ via, priorProjectId, projectId, workspaceId: orgId });
+    /*
+     * Say what just happened, in the vocabulary of somebody who has used other tools.
+     *
+     * `link` mints the key and stores it for you, which is the product's whole edge — and it is
+     * invisible, which is its whole cost. A real report: somebody pasted a masked placeholder key
+     * into a `.env` because their mental model said "I must make a key and put it somewhere". One had
+     * already been minted and filed outside the repo. They did not need another step; they needed to
+     * be told the step had happened.
+     *
+     * The key is identified the way the dashboard identifies it — a prefix, never the secret — so
+     * this can be read aloud, pasted into an issue, or left in a terminal without leaking anything.
+     */
+    hint(`bound this repo to project "${projectName}"${inWorkspace(workspace)}`);
+    if (projectDir !== resolve(cwd))
+        hint(`linked ${relative(cwd, projectDir)}: that is where this app's runs are written`);
+    hint(reusedKey
+        ? `reusing key ${keyHint(key)} — already stored in ${credPath}, not in your repo`
+        : `minted key ${keyHint(key)} — stored in ${credPath}, not in your repo`);
+    hint('to change it: `reticle connect --project <other>`; to inspect: `reticle status`');
+    hint('linked ✓ runs auto-push on `reticle verify`; `reticle sync` sends existing local runs; `reticle status` shows state');
+    /*
+     * A binding is not a connection.
+     *
+     * Without `.reticle.json` the app's bundle carries no projectId, so the daemon cannot attribute a
+     * session to this repo: its runs pool into whichever root the daemon itself was started in, and
+     * `sync` here reports "nothing to send" however much was actually recorded. Measured on this
+     * repo's bench app — two verdicts driven, then a sync that claimed there was nothing.
+     *
+     * Said AFTER the success line rather than refusing: the binding really was written and really is
+     * correct, and the missing half is one command away. Refusing would strand somebody who links
+     * before they install, which is a legitimate order to work in.
+     */
+    if (!(await createNodeFileSystem().exists(join(projectDir, RETICLE_CONFIG_BASENAME)))) {
+        hint(`no ${RETICLE_CONFIG_BASENAME} here: this app's runs reach this binding only while its dev ` +
+            'server runs with the Reticle build plugin, which announces it. Run `reticle init` in the app ' +
+            'to make the binding hold without it.');
+    }
+    return 0;
+};

package/dist/command/cli/cloud-login.d.ts

@@ -15,4 +15,26 @@ export declare const cmdLogin: (argv: readonly string[], link: Linker, autoLink?
  * one you did not mean.
  */
 export declare const cmdLogout: (argv?: readonly string[]) => Promise<number>;
+/**
+ * The panel's Sign in: the same browser approval `reticle login` opens, started by the daemon, which
+ * owns `~/.reticle`. One flow at a time, and a second press while it is pending reopens its approval
+ * page rather than doing nothing: somebody who closed that tab must be able to get it back.
+ * `onSignedIn` runs when the approval lands so every open panel can repaint. A failure stays in the
+ * daemon log: the panel copied `reticle login` as it was clicked, which is the way through.
+ */
+export declare function hudSignIn(onSignedIn: () => void, start?: (open: (url: string) => void) => Promise<number>, opener?: (url: string) => void, 
+/**
+ * Link the asking tab's project once signed in: "Save for your team" signed in and linked
+ * nothing, so the panel asked for the click just made. The daemon passes `projectLinkOnly`.
+ */
+link?: (root: string) => Promise<number>): (from?: {
+    artifactRoot?: string | undefined;
+}) => void;
+/**
+ * The workspace `connect` links in. A person in several was linked in whichever the saved sign-in
+ * was for, told "Connected", and nothing moved on the dashboard they were looking at. `--workspace
+ * <name|id>` switches the sign-in (and saves it); without it, a person in more than one is told which
+ * one this is and how to choose. Returns non-zero when the named workspace is not theirs.
+ */
+export declare const chooseWorkspace: (url: string, wanted: string | undefined) => Promise<number>;
 export {};

package/dist/command/cli/cloud-login.js

@@ -16,7 +16,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { CLOUD_LINK_FILE } from '../../memory/cloud/cloud-config.js';
 import { RETICLE_CONFIG_BASENAME } from './ports/resolve/cli-port.js';
-import { DevicePollSchema, DeviceStartSchema, openBrowser } from './auth/device-flow.js';
+import { DevicePollSchema, DeviceStartSchema, LoginOrigin, openBrowser, withLoginOrigin, } from './auth/device-flow.js';
 import { normalizeUrl, sessionPath, SESSIONS_DIR } from './auth/cloud-session.js';
 import { api, baseUrl, emit, err, flags, hint, home, readSession, RETICLE_DIR, SESSION_FILE, } from './cloud-kit.js';
 const LoginSchema = z.object({
@@ -101,7 +101,7 @@ const linkAfterLogin = async (url, project, link) => {
      * two verdicts had been recorded. Measured, on this very repo's bench app.
      */
     if (!(await fs.exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
-        hint('next: `reticle init` here first, then `reticle link` — or log in from a project directory');
+        hint('next: `reticle init` here first, then `reticle connect`');
         return;
     }
     /*
@@ -111,25 +111,25 @@ const linkAfterLogin = async (url, project, link) => {
      */
     if (project === undefined &&
         (await fs.exists(join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE)))) {
-        hint('this repo is already linked — `reticle push` to send what it has recorded');
+        hint('this repo is already linked — `reticle sync` to send what it has recorded');
         return;
     }
     try {
         await link(project === undefined ? ['--url', url] : ['--url', url, '--project', project]);
     }
     catch {
-        hint('signed in, but linking this repo failed — run `reticle link` to retry');
+        hint('signed in, but linking this repo failed — run `reticle connect` to retry');
     }
 };
 /**
  * Browser device flow — the DEFAULT `reticle login` (like `gh auth login`): fetch a device + user code,
  * open the browser to approve, then poll until the user confirms. No email to type, no code to copy back.
  */
-const cmdLoginDevice = async (explicitUrl, project, link, autoLink) => {
+const cmdLoginDevice = async (explicitUrl, project, link, autoLink, open = openBrowser, from = LoginOrigin.TERMINAL) => {
     const url = baseUrl(null, explicitUrl);
     const started = DeviceStartSchema.parse(await api('POST', `${url}/v1/auth/device/start`, null, {}));
     hint(`Opening ${started.verificationUri} — confirm this code in the browser: ${started.userCode}`);
-    openBrowser(started.verificationUriComplete);
+    open(withLoginOrigin(started.verificationUriComplete, from));
     const intervalMs = Math.max(1, started.interval) * 1000;
     for (;;) {
         await sleep(intervalMs);
@@ -140,14 +140,14 @@ const cmdLoginDevice = async (explicitUrl, project, link, autoLink) => {
         }
         if ('pending' === poll.status) {
             if (Date.now() > started.expiresAt) {
-                err('device login expired — run `reticle login` again');
+                err('device login expired — run `reticle connect` again');
                 return 1;
             }
             continue;
         }
         err('denied' === poll.status
             ? 'device login was denied in the browser'
-            : 'device login expired — run `reticle login` again');
+            : 'device login expired — run `reticle connect` again');
         return 1;
     }
 };
@@ -200,3 +200,91 @@ export const cmdLogout = async (argv = []) => {
     emit({ loggedOut: true, url });
     return 0;
 };
+/** The daemon signs in for the panel and links nothing: its working directory is not the user's app. */
+const NO_LINK = () => Promise.resolve(0);
+/**
+ * The panel's Sign in: the same browser approval `reticle login` opens, started by the daemon, which
+ * owns `~/.reticle`. One flow at a time, and a second press while it is pending reopens its approval
+ * page rather than doing nothing: somebody who closed that tab must be able to get it back.
+ * `onSignedIn` runs when the approval lands so every open panel can repaint. A failure stays in the
+ * daemon log: the panel copied `reticle login` as it was clicked, which is the way through.
+ */
+export function hudSignIn(onSignedIn, start = (open) => cmdLoginDevice(undefined, undefined, NO_LINK, false, open, LoginOrigin.HUD), opener = openBrowser, 
+/**
+ * Link the asking tab's project once signed in: "Save for your team" signed in and linked
+ * nothing, so the panel asked for the click just made. The daemon passes `projectLinkOnly`.
+ */
+link) {
+    let running = false;
+    let pending;
+    return (from) => {
+        if (running) {
+            if (pending !== undefined)
+                opener(pending);
+            return;
+        }
+        running = true;
+        const root = from?.artifactRoot;
+        void start((url) => {
+            pending = url;
+            opener(url);
+        })
+            .then(async (code) => {
+            if (0 !== code)
+                return;
+            if (link !== undefined && root !== undefined)
+                await link(root).catch(() => 1);
+            onSignedIn();
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            running = false;
+            pending = undefined;
+        });
+    };
+}
+const WorkspacesSchema = z.object({
+    active: z.string().optional(),
+    memberships: z.array(z.object({ orgId: z.string(), name: z.string() })).default([]),
+});
+const ActivatedSchema = z.object({
+    token: z.string(),
+    org: z.object({ id: z.string(), name: z.string() }),
+});
+/**
+ * The workspace `connect` links in. A person in several was linked in whichever the saved sign-in
+ * was for, told "Connected", and nothing moved on the dashboard they were looking at. `--workspace
+ * <name|id>` switches the sign-in (and saves it); without it, a person in more than one is told which
+ * one this is and how to choose. Returns non-zero when the named workspace is not theirs.
+ */
+export const chooseWorkspace = async (url, wanted) => {
+    const session = await readSession();
+    if (null === session)
+        return 0;
+    let listed;
+    try {
+        listed = WorkspacesSchema.parse(await api('GET', `${url}/v1/me/workspaces`, session.token));
+    }
+    catch {
+        return 0; // an older platform: nothing to choose between
+    }
+    const names = listed.memberships.map((m) => `"${m.name}"`).join(', ');
+    if (wanted === undefined) {
+        if (1 < listed.memberships.length)
+            hint(`you belong to ${String(listed.memberships.length)} workspaces (${names}); this links in ` +
+                `"${session.orgName}". Another: reticle connect --workspace <name>`);
+        return 0;
+    }
+    const lc = wanted.toLowerCase();
+    const target = listed.memberships.find((m) => m.orgId === wanted || m.name.toLowerCase() === lc);
+    if (target === undefined) {
+        err(`you are not a member of a workspace "${wanted}": yours are ${names}`);
+        return 2;
+    }
+    if (target.orgId === listed.active)
+        return 0;
+    const activated = ActivatedSchema.parse(await api('POST', `${url}/v1/me/workspaces/${encodeURIComponent(target.orgId)}/activate`, session.token, {}));
+    await writeSession(url, activated.token, activated.org.name, activated.org.id, undefined, () => Promise.resolve(0), session.email, false);
+    hint(`signed in to workspace "${activated.org.name}"`);
+    return 0;
+};

package/dist/command/cli/context-command.d.ts

@@ -0,0 +1 @@
+export declare function handleContext(session: string | undefined): Promise<void>;