@reticlehq/server 2.11.0 → 2.13.0

package/dist/cli/cloud-keystore.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Find this repo's key, newest slot generation first.
+ *
+ * A hit in an older slot is not proof the key is ours — only that nothing better was filed. The
+ * caller is expected to establish the tenant before trusting what comes back.
+ */
+export declare const findCredential: (raw: unknown, projectId: string, url: string, orgId: string | undefined) => string | undefined;
+export interface CredentialWrite {
+    projectId: string;
+    url: string;
+    key: string;
+    /** The tenant this key belongs to; undefined against a cloud that cannot name one. */
+    orgId: string | undefined;
+    /** The key this slot held before, if any — used to tell our own stale key from somebody else's. */
+    priorKey: string | undefined;
+    /** Whether that prior key was PROVED to belong to a different organisation. */
+    priorIsForeign: boolean;
+}
+/**
+ * Apply a link's key to the store, in place, and return it.
+ *
+ * The org slot is always ours to write. The two ambiguous slots are a compatibility shim for older
+ * daemons, and a shim must not corrupt what it is shimming:
+ *
+ *   - Overwriting a slot that holds a DIFFERENT live key would hand this key to whichever repo that
+ *     entry belongs to — the same cross-tenant disclosure as reusing theirs, pointing the other way.
+ *   - An EMPTY ambiguous slot is a trap too, because the resolver prefers cloud+project over the
+ *     bare legacy entry: filling a free `<url>::default` while another tenant's key sits in
+ *     `default` silently redirects THEIR repo to our key.
+ *
+ * So once another tenant is known to be on this machine, only the org slot is written. Our own
+ * stale or revoked key is not another tenant and is replaced normally — that is the ordinary
+ * re-link, and refusing it would strand the repo.
+ */
+export declare const applyCredential: (store: Record<string, unknown>, write: CredentialWrite) => Record<string, unknown>;
+/** Where the store lives, given the reticle home directory. */
+export declare const credentialsPath: (homeDir: string, file: string) => string;

package/dist/cli/cloud-keystore.js

@@ -0,0 +1,97 @@
+/**
+ * The machine's credential store: which key belongs to which repo, and who is allowed to write it.
+ *
+ * Split out of `cloud-cli` because both halves — the lookup and the write — encode the same rule
+ * from opposite ends, and reading one without the other is how the rule got broken twice. The store
+ * is `~/.reticle/credentials.json`, a flat map from slot to key.
+ *
+ * There are three generations of slot, and the order matters:
+ *   `<url>::org::<orgId>::<projectId>`  the only unambiguous one
+ *   `<url>::<projectId>`                tells two clouds apart, but not two tenants
+ *   `<projectId>`                       tells nothing apart; the original shape
+ *
+ * Each generation exists because the one before it was found to collide in the field, so the older
+ * two are kept readable (a repo linked by an older CLI must not lose its key) and written only when
+ * doing so cannot mislead somebody else.
+ */
+import { join } from 'node:path';
+import { credentialSlot } from '../cloud/cloud-config.js';
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
+const normalizeUrl = (url) => url.replace(/\/+$/, '');
+/** The key held in a slot, whether it is a bare string or the stamped `{ key, url }` shape. */
+const heldKeyOf = (held) => {
+    if ('string' === typeof held)
+        return held.length > 0 ? held : undefined;
+    if ('object' !== typeof held || null === held)
+        return undefined;
+    const key = held['key'];
+    return 'string' === typeof key && key.length > 0 ? key : undefined;
+};
+/**
+ * Find this repo's key, newest slot generation first.
+ *
+ * A hit in an older slot is not proof the key is ours — only that nothing better was filed. The
+ * caller is expected to establish the tenant before trusting what comes back.
+ */
+export const findCredential = (raw, projectId, url, orgId) => {
+    if ('object' !== typeof raw || null === raw)
+        return undefined;
+    const store = raw;
+    const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
+    if ('string' === typeof orgScoped && orgScoped.length > 0)
+        return orgScoped;
+    const composite = store[credentialSlot(url, projectId)];
+    if ('string' === typeof composite && composite.length > 0)
+        return composite;
+    const found = store[projectId];
+    if ('string' === typeof found)
+        return found.length > 0 ? found : undefined;
+    if ('object' !== typeof found || null === found)
+        return undefined;
+    const record = found;
+    const key = heldKeyOf(record);
+    const forUrl = record['url'];
+    if (key === undefined)
+        return undefined;
+    // A credential stamped with a DIFFERENT cloud is not this project's, however much the ids match.
+    if ('string' === typeof forUrl && normalizeUrl(forUrl) !== normalizeUrl(url))
+        return undefined;
+    return key;
+};
+/**
+ * Apply a link's key to the store, in place, and return it.
+ *
+ * The org slot is always ours to write. The two ambiguous slots are a compatibility shim for older
+ * daemons, and a shim must not corrupt what it is shimming:
+ *
+ *   - Overwriting a slot that holds a DIFFERENT live key would hand this key to whichever repo that
+ *     entry belongs to — the same cross-tenant disclosure as reusing theirs, pointing the other way.
+ *   - An EMPTY ambiguous slot is a trap too, because the resolver prefers cloud+project over the
+ *     bare legacy entry: filling a free `<url>::default` while another tenant's key sits in
+ *     `default` silently redirects THEIR repo to our key.
+ *
+ * So once another tenant is known to be on this machine, only the org slot is written. Our own
+ * stale or revoked key is not another tenant and is replaced normally — that is the ordinary
+ * re-link, and refusing it would strand the repo.
+ */
+export const applyCredential = (store, write) => {
+    const { projectId, url, key, orgId, priorKey, priorIsForeign } = write;
+    if (orgId !== undefined)
+        store[credentialSlot(url, projectId, orgId)] = key;
+    const mayOverwrite = (slot) => {
+        const held = heldKeyOf(store[slot]);
+        if (held === undefined)
+            return true; // free
+        if (held === key)
+            return true; // already ours
+        return held === priorKey && !priorIsForeign; // our own stale key, not somebody else's
+    };
+    const cloudSlot = credentialSlot(url, projectId);
+    if (!priorIsForeign && mayOverwrite(cloudSlot))
+        store[cloudSlot] = key;
+    if (!priorIsForeign && mayOverwrite(projectId))
+        store[projectId] = { key, url };
+    return store;
+};
+/** Where the store lives, given the reticle home directory. */
+export const credentialsPath = (homeDir, file) => join(homeDir, file);

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

@@ -0,0 +1,37 @@
+import { type Session } from './cloud-session.js';
+/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
+export declare const DEFAULT_URL = "https://app.reticle.sh";
+export declare const RETICLE_DIR = ".reticle";
+export declare const SESSION_FILE = "session.json";
+export declare const CREDENTIALS_FILE = "credentials.json";
+/** The user-level reticle directory, `~/.reticle`. Sessions and credentials live here, not in a repo. */
+export declare const home: () => string;
+export declare const err: (msg: string) => void;
+/** A next-step nudge on stderr (humans read it; agents parse stdout JSON and ignore this). */
+export declare const hint: (msg: string) => void;
+export declare const emit: (obj: unknown) => void;
+/** Read + parse a JSON file, or null when missing/malformed (never throws). */
+export declare const readJson: (path: string) => Promise<unknown>;
+/** Parse `--flag value` pairs out of an argv tail. */
+export declare const flags: (argv: readonly string[]) => Record<string, string>;
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export declare const readSession: () => Promise<Session | null>;
+/**
+ * The session for ONE host, or null.
+ *
+ * The whole safety property, holding by construction rather than by a guard somebody has to
+ * remember: a token is looked up BY the host it will be sent to, so no arrangement of environment
+ * variables can fetch one host's credential for a request to another. Falls back to `session.json`
+ * when it names this host, so a machine that logged in before per-host sessions existed is not
+ * silently signed out by an upgrade.
+ */
+export declare const readSessionFor: (url: string) => Promise<Session | null>;
+export declare const baseUrl: (session: {
+    url: string;
+} | null, explicit?: string) => string;
+/** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
+export declare const bearer: (session: {
+    token: string;
+} | null) => string | null;
+/** 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/cli/cloud-kit.js

@@ -0,0 +1,121 @@
+/**
+ * The layer every cloud verb sits on: where files live, how output is written, and how a `/v1` call
+ * is made and authorised.
+ *
+ * Extracted because it was the reason `cloud-cli` could not be split. Each verb is small and mostly
+ * independent, but all of them reach for the same dozen helpers, so any attempt to lift one command
+ * out dragged the plumbing with it or duplicated it. Naming the layer makes the verbs separable —
+ * `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 { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { cloudFetch } from '../cloud/cloud-sync.js';
+import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './cloud-session.js';
+/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
+export const DEFAULT_URL = 'https://app.reticle.sh';
+export const RETICLE_DIR = '.reticle';
+export const SESSION_FILE = 'session.json';
+export const CREDENTIALS_FILE = 'credentials.json';
+/** The user-level reticle directory, `~/.reticle`. Sessions and credentials live here, not in a repo. */
+export const home = () => join(homedir(), RETICLE_DIR);
+export const err = (msg) => {
+    process.stderr.write(`reticle: ${msg}\n`);
+};
+/** A next-step nudge on stderr (humans read it; agents parse stdout JSON and ignore this). */
+export const hint = (msg) => {
+    process.stderr.write(`→ ${msg}\n`);
+};
+export const emit = (obj) => {
+    process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+};
+/** Read + parse a JSON file, or null when missing/malformed (never throws). */
+export const readJson = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+/** Parse `--flag value` pairs out of an argv tail. */
+export const flags = (argv) => {
+    const f = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a !== undefined && a.startsWith('--') && i + 1 < argv.length) {
+            const v = argv[i + 1];
+            if (v !== undefined)
+                f[a.slice(2)] = v;
+            i += 1;
+        }
+    }
+    return f;
+};
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export const readSession = async () => readSessionFrom(readJson(join(home(), SESSION_FILE)));
+/**
+ * The session for ONE host, or null.
+ *
+ * The whole safety property, holding by construction rather than by a guard somebody has to
+ * remember: a token is looked up BY the host it will be sent to, so no arrangement of environment
+ * variables can fetch one host's credential for a request to another. Falls back to `session.json`
+ * when it names this host, so a machine that logged in before per-host sessions existed is not
+ * silently signed out by an upgrade.
+ */
+export const readSessionFor = async (url) => resolveSessionFor(url, await readSessionFrom(readJson(sessionPath(home(), url))), await readSession());
+export const baseUrl = (session, explicit) => {
+    // `--url` wins over the environment: it is typed for THIS command, it is visible in shell history,
+    // and it cannot leak into a sibling process the way an exported variable does.
+    if (explicit !== undefined && explicit.length > 0)
+        return normalizeUrl(explicit);
+    const env = process.env['RETICLE_CLOUD_URL'];
+    if (env !== undefined && env.length > 0)
+        return env.replace(/\/+$/, '');
+    if (null !== session && session.url.length > 0)
+        return session.url;
+    // No hint here any more. This used to warn that it was falling back to localhost, which was worth
+    // saying because that default was wrong for everyone except us. The default is now the hosted
+    // service, so the fallback IS the intended path — and a warning printed on the correct path is
+    // how people learn to ignore stderr, which is where the real problems are written.
+    return DEFAULT_URL;
+};
+/** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
+export const bearer = (session) => {
+    const key = process.env['RETICLE_CLOUD_KEY'];
+    if (key !== undefined && key.length > 0)
+        return key;
+    return session?.token ?? null;
+};
+/** 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 = {};
+    if (token !== null)
+        headers['authorization'] = `Bearer ${token}`;
+    if (body !== undefined)
+        headers['content-type'] = 'application/json';
+    const init = {
+        method,
+        headers,
+    };
+    if (body !== undefined)
+        init.body = JSON.stringify(body);
+    const res = await cloudFetch(url, init);
+    const text = await res.text();
+    let json = null;
+    if (text.length > 0) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`expected JSON from ${method} ${url} but got: ${text.slice(0, 120)}`);
+        }
+    }
+    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}`);
+    }
+    return json;
+};

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

@@ -0,0 +1,17 @@
+/** Run `reticle link` with these arguments. Injected; see the note at the top of this file. */
+export type Linker = (argv: readonly string[]) => Promise<number>;
+/**
+ * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
+ * headless two-step code path for CI/servers where opening a browser makes no sense.
+ */
+export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promise<number>;
+/** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
+/**
+ * `reticle logout` — sign out of ONE host, not of everywhere.
+ *
+ * Which host is the same question every other verb asks: `--url`, else the environment, else the
+ * active session. Signing out of staging must leave production alone — a logout that quietly
+ * cleared every environment would be discovered at the worst possible moment, mid-incident, on the
+ * one you did not mean.
+ */
+export declare const cmdLogout: (argv?: readonly string[]) => Promise<number>;

package/dist/cli/cloud-login.js

@@ -0,0 +1,183 @@
+/**
+ * `reticle login` and `reticle logout` — getting a session onto this machine, and off it.
+ *
+ * Split from `cloud-cli` because this is a coherent story on its own: prove who you are, write the
+ * token where the other verbs will find it, and finish the job by binding the repo you are standing
+ * in. The rest of the CLI reads sessions; only this file creates and destroys them.
+ *
+ * `cmdLink` arrives as a PARAMETER rather than an import. Login ends by linking and link needs a
+ * session, so the two genuinely depend on each other; passing the linker in breaks the cycle at the
+ * one call site instead of merging two commands into one file to satisfy the module graph.
+ */
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { CLOUD_LINK_FILE } from '../cloud/cloud-config.js';
+import { RETICLE_CONFIG_BASENAME } from './cli-port.js';
+import { DevicePollSchema, DeviceStartSchema, openBrowser } from './device-flow.js';
+import { normalizeUrl, sessionPath, SESSIONS_DIR } from './cloud-session.js';
+import { api, baseUrl, emit, err, flags, hint, home, readSession, RETICLE_DIR, SESSION_FILE, } from './cloud-kit.js';
+const LoginSchema = z.object({
+    token: z.string(),
+    org: z.object({ id: z.string().optional(), name: z.string() }),
+});
+/**
+ * `reticle login --email <e> [--org <name>] [--code <123456>]` — sign in, cache the token under
+ * ~/.reticle.
+ *
+ * TWO STEPS, because the cloud proves you own the inbox before it hands out a session: ask for a code,
+ * then exchange it. (It used to take an email alone — which meant anyone who knew your address owned your
+ * org.) `--org` is only consulted when the account is brand new; a returning user never needs it.
+ *
+ * Without `--code` we request one and stop, telling the user to re-run with it. The one exception is a
+ * LOCAL cloud, whose dev mailer cannot actually deliver mail and so echoes the code back in its response
+ * (`devCode`) — there we complete the login in a single command rather than asking a developer to read a
+ * code out of a server log they may not even be tailing.
+ */
+const RequestCodeSchema = z.object({ devCode: z.string().optional() });
+/** Persist a session token under ~/.reticle and print the next step. Shared by both login paths. */
+const writeSession = async (url, token, orgName, orgId, project, link) => {
+    await mkdir(join(home(), SESSIONS_DIR), { recursive: true });
+    const body = `${JSON.stringify({ url: normalizeUrl(url), token, orgName, ...(orgId === undefined ? {} : { orgId }) }, null, 2)}\n`;
+    // Both, on purpose. The per-host file is what lets another environment stay logged in; the active
+    // file is what a bare command with no override resolves through, and keeping it means nothing
+    // about the single-environment workflow changes.
+    await writeFile(sessionPath(home(), url), body);
+    await writeFile(join(home(), SESSION_FILE), body);
+    emit({ loggedIn: orgName, session: join(home(), SESSION_FILE) });
+    await linkAfterLogin(url, project, link);
+};
+/**
+ * Finish the job when the shell is already standing in an unlinked Reticle project.
+ *
+ * `login` used to end by printing "next: `reticle link`", which made getting from local-only to
+ * reporting a TWO command trip whose second half nothing enforces — and the HUD's own invitation
+ * names one command, so the gap was ours to close rather than the reader's to notice. Somebody who
+ * ran `reticle login` inside their instrumented repo wanted their runs on the dashboard; there is no
+ * second thing they could have meant.
+ *
+ * Deliberately narrow, because a login that writes files in a directory the user did not mean is
+ * worse than an extra step:
+ *   - a `.reticle.json` must already exist. That is what `init` writes and what puts a projectId in
+ *     the app's BUNDLE, which is the only thing letting the daemon attribute runs to this repo. A
+ *     bare `.reticle/` directory is NOT the marker: gating on it produced repos that were linked and
+ *     structurally unable to report, whose runs pooled under the daemon's own root instead.
+ *   - an existing `cloud.json` is left completely alone. Re-linking would re-resolve the project and
+ *     is exactly how somebody re-pointing an environment loses a binding they meant to keep.
+ *   - a failure is reported and swallowed. The login SUCCEEDED and its token is already on disk;
+ *     turning that into a non-zero exit would make the recoverable half look like the broken one.
+ */
+const linkAfterLogin = async (url, project, link) => {
+    const fs = createNodeFileSystem();
+    /*
+     * The marker is `.reticle.json`, NOT a `.reticle/` directory.
+     *
+     * `.reticle.json` is what `init` writes and what puts a projectId in the app's bundle, which is
+     * the only thing that lets the daemon attribute a session's runs to this repo. A bare `.reticle/`
+     * proves nothing — it is also created by artifacts and by older builds — and auto-linking on it
+     * produced a repo that was LINKED to a cloud project and yet unable to report to it: runs pooled
+     * into the daemon's own ledger, and `reticle sync` here answered "nothing to send" straight after
+     * 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');
+        return;
+    }
+    /*
+     * An explicit `--project` is an instruction, so it re-binds even a repo that is already linked.
+     * Without a project named, an existing binding is left completely alone — re-resolving it is how
+     * somebody repointing an environment loses a binding they meant to keep.
+     */
+    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');
+        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');
+    }
+};
+/**
+ * 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) => {
+    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);
+    const intervalMs = Math.max(1, started.interval) * 1000;
+    for (;;) {
+        await sleep(intervalMs);
+        const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
+        if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
+            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link);
+            return 0;
+        }
+        if ('pending' === poll.status) {
+            if (Date.now() > started.expiresAt) {
+                err('device login expired — run `reticle login` again');
+                return 1;
+            }
+            continue;
+        }
+        err('denied' === poll.status
+            ? 'device login was denied in the browser'
+            : 'device login expired — run `reticle login` again');
+        return 1;
+    }
+};
+/**
+ * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
+ * headless two-step code path for CI/servers where opening a browser makes no sense.
+ */
+export const cmdLogin = async (argv, link) => {
+    const f = flags(argv);
+    const positional = argv[0] !== undefined && !argv[0].startsWith('--') ? argv[0] : undefined;
+    const email = f['email'] ?? positional;
+    if (email === undefined)
+        return cmdLoginDevice(f['url'], f['project'], link);
+    const org = f['org'];
+    const url = baseUrl(null, f['url']);
+    let code = f['code'];
+    if (code === undefined) {
+        const requested = RequestCodeSchema.parse(await api('POST', `${url}/v1/auth/request-code`, null, {
+            email,
+            ...(org !== undefined ? { orgName: org } : {}),
+        }));
+        // A real cloud mails the code and never echoes it; a local one cannot mail, so it hands it back.
+        if (requested.devCode === undefined) {
+            emit({ codeSent: true, to: email });
+            hint(`check your inbox, then: \`reticle login --email ${email} --code <the 6-digit code>\``);
+            return 0;
+        }
+        code = requested.devCode;
+    }
+    const parsed = LoginSchema.parse(await api('POST', `${url}/v1/auth/login`, null, { email, code }));
+    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link);
+    return 0;
+};
+/** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
+/**
+ * `reticle logout` — sign out of ONE host, not of everywhere.
+ *
+ * Which host is the same question every other verb asks: `--url`, else the environment, else the
+ * active session. Signing out of staging must leave production alone — a logout that quietly
+ * cleared every environment would be discovered at the worst possible moment, mid-incident, on the
+ * one you did not mean.
+ */
+export const cmdLogout = async (argv = []) => {
+    const active = await readSession();
+    const url = baseUrl(active, flags(argv)['url']);
+    await rm(sessionPath(home(), url), { force: true }).catch(() => undefined);
+    // The active pointer only moves if it was pointing at the host just signed out of.
+    if (null !== active && normalizeUrl(active.url) === url)
+        await writeFile(join(home(), SESSION_FILE), '').catch(() => undefined);
+    emit({ loggedOut: true, url });
+    return 0;
+};

package/dist/cli/cloud-session.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The signed-in session on this machine: where it is stored, and how it is read back.
+ *
+ * Split out of `cloud-cli` for the file-size cap, but the unit is real — every rule about WHICH
+ * credential may be sent to WHICH host is decided here, and the safety of that holds by
+ * construction rather than by a guard somebody has to remember at each call site.
+ */
+import { z } from 'zod';
+/** Where per-host sessions live under the reticle home directory. */
+export declare const SESSIONS_DIR = "sessions";
+export declare const SessionSchema: z.ZodObject<{
+    url: z.ZodString;
+    token: z.ZodString;
+    orgName: z.ZodString;
+    /**
+     * WHICH tenant this session signed into. Optional because every session file written before
+     * org-scoped credentials lacks it; the link path treats "unknown" as "cannot prove a stored key
+     * is ours" and mints, which is the safe direction.
+     */
+    orgId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    token: string;
+    orgName: string;
+    orgId?: string | undefined;
+}, {
+    url: string;
+    token: string;
+    orgName: string;
+    orgId?: string | undefined;
+}>;
+export type Session = z.infer<typeof SessionSchema>;
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */
+export declare const normalizeUrl: (url: string) => string;
+export declare const sessionPath: (homeDir: string, url: string) => string;
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export declare const readSessionFrom: (raw: Promise<unknown>) => Promise<Session | null>;
+/**
+ * The session for ONE host, or null.
+ *
+ * This is the whole safety property, and it holds by construction rather than by a guard somebody
+ * has to remember: a token is looked up BY the host it will be sent to, so there is no arrangement
+ * of environment variables that fetches one host's credential for a request to another.
+ *
+ * Falls back to `session.json` when it names this host, so a machine that logged in before per-host
+ * sessions existed keeps working and is not silently signed out by an upgrade.
+ */
+export declare const resolveSessionFor: (url: string, perHost: Session | null, active: Session | null) => Session | null;

package/dist/cli/cloud-session.js

@@ -0,0 +1,53 @@
+/**
+ * The signed-in session on this machine: where it is stored, and how it is read back.
+ *
+ * Split out of `cloud-cli` for the file-size cap, but the unit is real — every rule about WHICH
+ * credential may be sent to WHICH host is decided here, and the safety of that holds by
+ * construction rather than by a guard somebody has to remember at each call site.
+ */
+import { z } from 'zod';
+import { join } from 'node:path';
+/** Where per-host sessions live under the reticle home directory. */
+export const SESSIONS_DIR = 'sessions';
+export const SessionSchema = z.object({
+    url: z.string(),
+    token: z.string(),
+    orgName: z.string(),
+    /**
+     * WHICH tenant this session signed into. Optional because every session file written before
+     * org-scoped credentials lacks it; the link path treats "unknown" as "cannot prove a stored key
+     * is ours" and mints, which is the safe direction.
+     */
+    orgId: z.string().optional(),
+});
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */
+export const normalizeUrl = (url) => url.replace(/\/+$/, '');
+/**
+ * A filesystem-safe name for one host. `https://app.reticle.sh` → `app.reticle.sh`,
+ * `http://localhost:8890` → `localhost_8890`. The scheme is dropped deliberately: nobody runs the
+ * same host over both http and https and means two different accounts by it.
+ */
+const hostSlug = (url) => normalizeUrl(url)
+    .replace(/^[a-z]+:\/\//i, '')
+    .replace(/[^a-zA-Z0-9.-]/g, '_');
+export const sessionPath = (homeDir, url) => join(homeDir, SESSIONS_DIR, `${hostSlug(url)}.json`);
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export const readSessionFrom = async (raw) => {
+    const parsed = SessionSchema.safeParse(await raw);
+    return parsed.success ? parsed.data : null;
+};
+/**
+ * The session for ONE host, or null.
+ *
+ * This is the whole safety property, and it holds by construction rather than by a guard somebody
+ * has to remember: a token is looked up BY the host it will be sent to, so there is no arrangement
+ * of environment variables that fetches one host's credential for a request to another.
+ *
+ * Falls back to `session.json` when it names this host, so a machine that logged in before per-host
+ * sessions existed keeps working and is not silently signed out by an upgrade.
+ */
+export const resolveSessionFor = (url, perHost, active) => {
+    if (perHost !== null)
+        return perHost;
+    return null !== active && normalizeUrl(active.url) === normalizeUrl(url) ? active : null;
+};

package/dist/cli/config-discovery.d.ts

@@ -19,7 +19,7 @@
  * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
  * are handed the list and must name it.
  */
-export interface FoundConfig {
+interface FoundConfig {
     /** Absolute path to the `.reticle.json`. */
     path: string;
     /** The directory it configures — what a reader needs in order to act. */
@@ -33,3 +33,4 @@ export interface ConfigDiscovery {
     searched: string[];
 }
 export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;
+export {};

package/dist/cli/config-discovery.js

@@ -147,6 +147,7 @@ export function discoverProjectConfigs(cwd) {
         catch {
             continue; // A declared workspace directory that does not exist is not an error here.
         }
+        check(base);
         for (const entry of entries) {
             const candidate = join(base, entry);
             try {

package/dist/cli/daemon-start-options.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turn the parsed `_daemon` / `serve` flags into the options `startDaemon` takes.
+ *
+ * Extracted from `handleDaemonInner` to be testable, because the thing it got wrong was invisible
+ * from outside: `headless` used to be spread INSIDE the `driveUrl !== undefined` branch, so
+ * `reticle serve --headed` — no `--drive` — parsed the flag correctly and then dropped it on the
+ * floor. `startDaemon` fell back to `headless ?? true` and the pool launched hidden, which reads to
+ * a user as "--headed does nothing" and cost a real session of being told a run was visible when
+ * four chrome-headless-shell processes said otherwise.
+ *
+ * `headless` and `driveUrl` are independent: the flag governs the shared browser POOL (leases,
+ * replay, the spec runner), which exists whether or not a drive URL was named.
+ */
+import type { StartOptions } from '../index.js';
+export type DaemonFlags = {
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+};
+export declare function daemonStartOptions(parsed: DaemonFlags): StartOptions;
+/**
+ * The argv a parent hands its detached `_daemon` child.
+ *
+ * `serve` and `mcp` each built this list by hand and each made the SAME mistake as the options
+ * builder above — pushing `--headed` only inside the `driveUrl` branch — so the flag survived
+ * parsing, was dropped at the spawn, and the child launched a hidden pool. Three sites, one wrong
+ * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
+ */
+export declare function daemonSpawnArgs(parsed: DaemonFlags): string[];