@cruxy/cli 1.8.0 → 1.9.0

package/dist/onboarding/flow.js

@@ -1,8 +1,8 @@
-import { AuthError, NetworkError, createProvider } from "@cruxy/sdk";
+import { AuthError, DeviceLoginClient, NetworkError, createProvider, } from "@cruxy/sdk";
 import { themeForColor } from "../theme/index.js";
-import { resolveApiKey, writeCredential } from "../config/index.js";
+import { apiKeyEnvVar, readCredential, resolveApiKey, writeCredential, writeCredentialWithMeta, } from "../config/index.js";
 import { newOnboardingState, readOnboardingState, writeOnboardingState, } from "./detect.js";
-import { acquireKeyStep, firstWinStep, scaffoldStep } from "./steps.js";
+import { acquireKeyStep, deviceLoginStep, firstWinStep, scaffoldStep, } from "./steps.js";
 /**
  * Orchestrate the onboarding steps (U.6) — resumable and idempotent. The key
  * step is skipped when a key already resolves; the completion marker is written
@@ -17,14 +17,27 @@ export async function runOnboarding(opts) {
     let apiKey = deps.resolveApiKey(provider);
     // ── key (mandatory; skipped if already resolvable unless forceKey) ─────────
     if (!apiKey || opts.forceKey) {
-        const result = await acquireKeyStep(io, deps, provider);
+        warnAboutOverwrite(io, deps);
+        // Device login is the default; paste stays reachable behind `--paste`, and
+        // is the only path when there is no device flow to run (a non-cruxy
+        // provider, whose keys these gateway routes know nothing about).
+        const useDevice = !opts.preferPaste && deps.deviceLogin !== undefined;
+        const result = useDevice
+            ? await deviceLoginStep(io, deps, provider)
+            : await acquireKeyStep(io, deps, provider);
         if (result.status === "aborted") {
             return { completed: false, aborted: true };
         }
         if (result.status !== "ok") {
-            // Failed (unreachable / rejected) — surface guidance, no marker.
+            // Failed (unreachable / rejected / declined) — surface guidance, no marker.
             if (result.message)
                 io.write(`${t.muted(result.message)}\n`);
+            if (useDevice) {
+                // The paste path exists for exactly the cases the device flow cannot
+                // serve, and someone who has just watched it fail is precisely who needs
+                // to know it is there.
+                io.write(t.muted("if you can't approve in a browser, `cruxy login --paste` takes a key directly.\n"));
+            }
             return { completed: false, aborted: false };
         }
         apiKey = result.apiKey;
@@ -46,14 +59,53 @@ export async function runOnboarding(opts) {
     io.write(`${t.success(t.strong(`${t.glyph.success} all set`))} — happy hacking.\n`);
     return { completed: true, aborted: false, apiKey };
 }
+/**
+ * Say, BEFORE anything is overwritten, the two things a login silently does.
+ *
+ * Both are facts a user cannot see and would otherwise discover the hard way:
+ * that this replaces a saved credential with no undo, and that an exported key
+ * will go on winning over whatever is saved here, so a perfectly successful
+ * login can change nothing at all about the next request.
+ */
+function warnAboutOverwrite(io, deps) {
+    const t = themeForColor(io.color);
+    const status = deps.credentialStatus?.();
+    if (!status)
+        return;
+    if (status.storedKey) {
+        io.write(t.muted("\nthis replaces the credential currently saved in ~/.cruxy — there is no undo.\n"));
+    }
+    if (status.shadowingEnvVar) {
+        io.write(t.warning(`\n${status.shadowingEnvVar} is set in your environment, and the environment always wins over the saved credential.\n`) +
+            t.muted(`whatever you sign in with will be saved, but your requests will keep using ${status.shadowingEnvVar} until you unset it.\n`));
+    }
+}
 /**
  * Build the production {@link OnboardingDeps}: live gateway validation, the
  * credentials store, real state persistence, and a wall-clock timestamp.
  */
 export function createDefaultDeps(opts) {
+    const provider = opts.config.model.provider;
+    // ONLY ON THE CRUXY PROVIDER, on the same reasoning `run.ts` uses to gate the
+    // limits probe: `/device/*` are cruxy gateway routes, and a
+    // bring-your-own-provider setup has no notion of them. Pointing them at
+    // someone else's base URL would be a request to a stranger — so there is no
+    // device flow to offer, and the key step falls through to the paste prompt.
+    const deviceLogin = provider === "cruxy"
+        ? (io) => runDeviceLogin(opts.config, io)
+        : undefined;
     return {
-        validateKey: (provider, apiKey) => validateKeyLive(provider, apiKey, opts.config),
+        validateKey: (p, apiKey) => validateKeyLive(p, apiKey, opts.config),
         writeCredential,
+        writeCredentialWithMeta,
+        ...(deviceLogin ? { deviceLogin } : {}),
+        credentialStatus: () => {
+            const envVar = apiKeyEnvVar(provider);
+            return {
+                storedKey: readCredential(provider) !== undefined,
+                ...(process.env[envVar] ? { shadowingEnvVar: envVar } : {}),
+            };
+        },
         resolveApiKey,
         readState: () => readOnboardingState(),
         writeState: (state) => writeOnboardingState(state),
@@ -62,6 +114,69 @@ export function createDefaultDeps(opts) {
         now: () => new Date().toISOString(),
     };
 }
+/**
+ * Drive one real device login against the gateway.
+ *
+ * Everything that can go wrong on the wire collapses to `unreachable` here,
+ * because from the user's seat there is one answer to all of it — try again —
+ * and the flow's own outcomes (denied, expired, invalid) are the states that
+ * genuinely differ. The credential is returned, never written: persisting is the
+ * step's job, so there is exactly one place that decides what lands in the store.
+ */
+async function runDeviceLogin(config, io) {
+    const client = new DeviceLoginClient({ gatewayUrl: config.cruxy.gatewayUrl });
+    let session;
+    try {
+        session = await client.start();
+    }
+    catch (err) {
+        return { status: "unreachable", message: unreachableMessage(err) };
+    }
+    io.prompt({
+        userCode: session.userCode,
+        verificationUri: session.verificationUri,
+        ...(session.verificationUriComplete !== undefined
+            ? { verificationUriComplete: session.verificationUriComplete }
+            : {}),
+        expiresInMs: session.expiresInMs,
+    });
+    let outcome;
+    try {
+        outcome = await client.poll(session, {
+            onProgress: (p) => io.waiting({
+                remainingMs: p.remainingMs,
+                ...(p.throttled !== undefined ? { throttled: p.throttled } : {}),
+            }),
+        });
+    }
+    catch (err) {
+        return { status: "unreachable", message: unreachableMessage(err) };
+    }
+    switch (outcome.status) {
+        case "approved":
+            return {
+                status: "ok",
+                apiKey: outcome.credential.accessToken,
+                ...(outcome.credential.expiresAt !== undefined
+                    ? { expiresAt: outcome.credential.expiresAt }
+                    : {}),
+                ...(outcome.credential.keyId !== undefined
+                    ? { keyId: outcome.credential.keyId }
+                    : {}),
+            };
+        case "denied":
+            return { status: "denied" };
+        case "expired":
+            return { status: "expired" };
+        case "invalid":
+            return { status: "invalid" };
+    }
+}
+function unreachableMessage(err) {
+    return err instanceof NetworkError
+        ? "couldn't reach the gateway — check your connection and run `cruxy login` again"
+        : "the gateway answered unexpectedly — run `cruxy login` to try again";
+}
 /**
  * Validate a key with one cheap live call: start a 1-token stream and look at the
  * first event. `AuthError` ⇒ invalid (bad key), `NetworkError` ⇒ unreachable;

package/dist/onboarding/steps.js

@@ -8,6 +8,118 @@ import { loadProjectInstructions, scaffoldProjectInstructions, } from "../config
  */
 const MAX_KEY_ATTEMPTS = 3;
 const c = (io) => themeForColor(io.color);
+/**
+ * Sign in by approving in a browser — the default path.
+ *
+ * WHY IT IS THE DEFAULT, and why it is not merely a nicer prompt: a pasted key
+ * is minted through the admin issue-key route, which cannot produce a
+ * subscription credential — asking for one there is explicitly refused. So every
+ * pasted CLI key lands in the metered `apikey` bucket with no token pool, while
+ * the same human's web chat and desktop draw on their plan. One human, two
+ * budgets. The device flow mints through the login issuer, which is the only
+ * path to the subscription bucket, so the credential it produces draws on the
+ * pool the user already has.
+ *
+ * THE KEY IS NOT RE-VALIDATED. The gateway minted it seconds ago and returned it
+ * over the same connection; a `validateKey` call here would spend a real,
+ * billable request to re-prove a fact we were just told — against the very pool
+ * this step exists to establish. The paste path validates because there a key is
+ * an unverified claim by the user; here it is the gateway's own answer.
+ *
+ * Every outcome is reported, never thrown: a denial and an expiry are the flow
+ * working correctly, and both leave the existing credential untouched.
+ */
+export async function deviceLoginStep(io, deps, provider) {
+    const col = c(io);
+    if (!deps.deviceLogin)
+        return { status: "skipped" };
+    const outcome = await deps.deviceLogin(deviceIO(io));
+    switch (outcome.status) {
+        case "ok": {
+            deps.writeCredentialWithMeta(provider, outcome.apiKey, {
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+                source: "device",
+            });
+            io.write(`${col.success(col.glyph.success)} signed in — credential saved to ~/.cruxy\n`);
+            if (outcome.expiresAt) {
+                io.write(col.muted(`  it expires on ${formatExpiry(outcome.expiresAt)}; run \`cruxy login\` again before then.\n`));
+            }
+            return {
+                status: "ok",
+                apiKey: outcome.apiKey,
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+            };
+        }
+        case "denied":
+            io.write(`${col.danger(col.glyph.failure)} the sign-in was declined in the browser.\n`);
+            return { status: "failed", message: "sign-in declined" };
+        case "expired":
+            io.write(`${col.danger(col.glyph.failure)} the code expired before it was approved.\n`);
+            return {
+                status: "failed",
+                message: "the code expired — run `cruxy login` to get a new one",
+            };
+        case "invalid":
+            // The gateway collapses four causes into one code on purpose and tells us
+            // nothing about which; all four are answered by starting over.
+            io.write(`${col.danger(col.glyph.failure)} that sign-in could not be completed.\n`);
+            return {
+                status: "failed",
+                message: "sign-in could not be completed — run `cruxy login` to retry",
+            };
+        case "unreachable":
+            io.write(`${col.danger(col.glyph.failure)} couldn't reach the gateway to sign in.\n`);
+            return { status: "failed", message: outcome.message };
+    }
+}
+/** Render the device flow's two messages onto the onboarding IO. */
+function deviceIO(io) {
+    const col = c(io);
+    let lastNote = "";
+    return {
+        prompt: (session) => {
+            const link = session.verificationUriComplete ?? session.verificationUri;
+            io.write(`\nTo sign in, open ${col.accent(link)}\n` +
+                `and enter the code ${col.strong(session.userCode)}\n\n` +
+                col.muted(`waiting for approval (expires in ${humanDuration(session.expiresInMs)})…\n`));
+        },
+        waiting: (info) => {
+            // Only the throttle is worth saying out loud, and only once: a line per
+            // poll would scroll a quiet wait off the screen, and "still waiting" adds
+            // nothing to the "waiting for approval" already on it.
+            if (!info.throttled || lastNote === "throttled")
+                return;
+            lastNote = "throttled";
+            io.write(col.muted("  the gateway asked us to slow down; still waiting…\n"));
+        },
+    };
+}
+/** "2 days", "9 minutes" — coarse on purpose; this is a reassurance, not a timer. */
+function humanDuration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return "less than a minute";
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"}`;
+}
+/** The date part of an RFC 3339 expiry, or the raw string if it will not parse. */
+function formatExpiry(expiresAt) {
+    const at = Date.parse(expiresAt);
+    if (Number.isNaN(at))
+        return expiresAt;
+    return new Date(at).toISOString().slice(0, 10);
+}
 /**
  * Acquire and persist a provider key: print the create-key URL, read it masked,
  * validate it live, and **only then** write it to the credentials store. Loops on

package/dist/session/index.js

@@ -16,6 +16,6 @@ export { SessionLog } from "./log.js";
 export { defaultExportName, exportMarkdown, } from "./export.js";
 export { foldEvents, readEvents, readMeta, replaySession } from "./replay.js";
 export { redactMessages } from "./redact.js";
-export { findSession, isAmbiguous, listSessions, summarizeSession, } from "./list.js";
-export { cwdMismatchWarning, describeSession, loadResume, relativeAge, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
-export { SESSION_FILE_VERSION, SessionEventSchema, SessionMetaSchema, } from "./types.js";
+export { findSession, isAmbiguous, listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
+export { cwdMismatchWarning, describeSession, loadResume, priorDirectoriesWarning, relativeAge, resolveSessionId, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
+export { KNOWN_EVENT_KINDS, SESSION_FILE_VERSION, ResumedEventSchema, SessionEventSchema, SessionMetaSchema, } from "./types.js";

package/dist/session/list.js

@@ -1,6 +1,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { projectDir, SESSION_FILE_EXT } from "./paths.js";
+import { readMeta } from "./replay.js";
 import { MessageSchema, SessionEventSchema, SessionMetaSchema, } from "./types.js";
 /**
  * Listing sessions for the resume picker and the TUI sidebar (P2). Both read
@@ -22,10 +23,18 @@ function toTitle(text) {
  * Summarize one session file: its meta, its first user prompt (the title) and
  * how many user turns it holds.
  *
- * This reads the whole file, which is the honest cost of counting turns. It is
- * bounded in practice — the picker asks for ten — and a session file is text
- * measured in tens of kilobytes. If it ever stops being cheap the fix is a
- * sidecar index, not a partial read that reports a wrong count.
+ * This reads the whole file, which is the honest cost of counting turns — a
+ * partial read cannot produce a correct count, and reporting a wrong one is
+ * worse than paying for a right one.
+ *
+ * What changed: this used to claim the cost was "bounded in practice — the
+ * picker asks for ten". It was not. {@link listSessions} summarized EVERY file
+ * and sliced afterwards, so the limit bounded the rows and not the work; a
+ * project of 200 sessions paid 200 full parses to show 10. The limit now bounds
+ * the work (see {@link sessionRefsByRecency}), which is what finally makes that
+ * sentence true. A sidecar index is still the answer if per-file cost ever
+ * stops being acceptable — but the ordering fix had to come first, because an
+ * index would have made the same mistake faster.
  */
 export function summarizeSession(file) {
     let raw;
@@ -89,10 +98,18 @@ export function summarizeSession(file) {
     return { ...meta, title: title ?? UNTITLED, turns };
 }
 /**
- * Every session recorded for `cwd`'s project, most-recently-updated first.
- * Missing directory → empty list (not an error: no sessions yet is normal).
+ * Session files in `cwd`'s project, most-recently-modified first.
+ *
+ * `readdir` plus one `stat` each — NO file is opened. This is the ordering step
+ * that lets every caller below bound its own work: recency is knowable from the
+ * directory alone, so the expensive per-file read only ever has to happen for
+ * the files a caller is actually going to show.
+ *
+ * Missing directory → empty list (not an error: no sessions yet is normal). A
+ * file that vanishes between the `readdir` and the `stat` is skipped rather
+ * than throwing — listing races an active session by definition.
  */
-export function listSessions(cwd, limit = Infinity) {
+function sessionRefsByRecency(cwd) {
     const dir = projectDir(cwd);
     let names;
     try {
@@ -101,37 +118,106 @@ export function listSessions(cwd, limit = Infinity) {
     catch {
         return [];
     }
-    const summaries = [];
+    const files = [];
     for (const name of names) {
         if (!name.endsWith(SESSION_FILE_EXT))
             continue;
-        const summary = summarizeSession(path.join(dir, name));
+        const file = path.join(dir, name);
+        try {
+            files.push({ file, mtimeMs: statSync(file).mtimeMs });
+        }
+        catch {
+            continue; // deleted mid-listing
+        }
+    }
+    // Newest first, with the path as a tiebreak so two files written in the same
+    // millisecond list in a stable order rather than whatever `readdir` returned.
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs || a.file.localeCompare(b.file));
+    return files;
+}
+/**
+ * Every session recorded for `cwd`'s project, most-recently-updated first,
+ * capped at `limit`.
+ *
+ * `limit` bounds the WORK, not just the rows. Files are ordered by mtime first
+ * (cheap — see {@link sessionRefsByRecency}) and summarized one at a time until
+ * `limit` valid summaries exist, so the picker asking for ten reads ten files
+ * and not two hundred.
+ *
+ * OVER-FETCH AND REFILL is why this is a loop and not a `slice`. A file with no
+ * readable meta summarizes to `null` and is skipped — that tolerance is the
+ * point of the format and `tree.test.ts` pins it. Taking the ten most recent
+ * files and summarizing those would let one junk file among them silently
+ * return nine rows; walking until ten SUMMARIES exist costs one wasted parse
+ * per junk file and always returns ten when ten are there.
+ */
+export function listSessions(cwd, limit = Infinity) {
+    const summaries = [];
+    for (const { file } of sessionRefsByRecency(cwd)) {
+        if (summaries.length >= limit)
+            break;
+        const summary = summarizeSession(file);
         if (summary)
             summaries.push(summary);
     }
-    summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-    return Number.isFinite(limit) ? summaries.slice(0, limit) : summaries;
+    return summaries;
+}
+/**
+ * Every session's IDENTITY for `cwd`'s project, most-recently-updated first.
+ *
+ * One meta line per file, via {@link readMeta} — no turn counting, no title.
+ * This is the index `--resume <id>` resolves against, and it exists because
+ * resolution never needed the expensive half: on a 200-session project it costs
+ * ~10ms against ~120ms for the equivalent {@link listSessions}, and the resume
+ * path used to build the expensive one two or three times over.
+ *
+ * `meta` stays authoritative for the id, deliberately — the FILENAME also
+ * carries it, and matching on that would be cheaper still, but it would make a
+ * file with no readable meta resolvable and then unloadable. A session that
+ * cannot be summarized must not be offerable either.
+ */
+export function listSessionRefs(cwd) {
+    const refs = [];
+    for (const { file, mtimeMs } of sessionRefsByRecency(cwd)) {
+        const meta = readMeta(file);
+        if (meta)
+            refs.push({ sessionId: meta.sessionId, file, mtimeMs });
+    }
+    return refs;
+}
+/**
+ * Match an id (or id prefix) against an already-built index.
+ *
+ * Pure, and separate from the reading, so ONE index can answer both "is this
+ * ambiguous?" and "which one is it?" — the two questions the resume path asks
+ * back to back, and used to rebuild the whole listing to answer separately.
+ *
+ * An exact id always wins outright: `abc` names the session called `abc` even
+ * when `abcdef` also exists, so a full id is never ambiguous against something
+ * that merely starts the same way.
+ */
+export function matchSessionRefs(refs, id) {
+    const exact = refs.find((r) => r.sessionId === id);
+    if (exact)
+        return [exact];
+    return refs.filter((r) => r.sessionId.startsWith(id));
 }
 /**
  * Find one session by id (or unambiguous id prefix) within `cwd`'s project.
- * Returns null when nothing matches; throws nothing — the caller decides how
- * loudly to fail.
+ * Returns null when nothing matches or the prefix is ambiguous; throws nothing
+ * — the caller decides how loudly to fail.
  *
  * Prefix matching exists because the ids are UUIDs and nobody is going to type
  * one; the picker and the sidebar both show a short form.
+ *
+ * Builds its own index. `resolveSessionId` in `resume.ts` is the path that
+ * builds ONE and asks both questions of it; prefer that when you need both.
  */
 export function findSession(cwd, id) {
-    const all = listSessions(cwd);
-    const exact = all.find((s) => s.sessionId === id);
-    if (exact)
-        return exact;
-    const matches = all.filter((s) => s.sessionId.startsWith(id));
-    return matches.length === 1 ? matches[0] : null;
+    const matches = matchSessionRefs(listSessionRefs(cwd), id);
+    return matches.length === 1 ? summarizeSession(matches[0].file) : null;
 }
 /** Whether an id prefix matches more than one session (an ambiguous resume). */
 export function isAmbiguous(cwd, id) {
-    const all = listSessions(cwd);
-    if (all.some((s) => s.sessionId === id))
-        return false;
-    return all.filter((s) => s.sessionId.startsWith(id)).length > 1;
+    return matchSessionRefs(listSessionRefs(cwd), id).length > 1;
 }

package/dist/session/log.js

@@ -15,23 +15,42 @@ export class SessionLog {
         this.currentRunId = opts.currentRunId;
     }
     /**
-     * Open (or create) a session log. A NEW file gets its `meta` line; reopening
-     * an existing one (a `--resume`) does not — `meta` describes where and when
-     * the conversation began, and a second copy written from wherever it was
-     * resumed would make "the session's directory" ambiguous. Replay already
-     * takes the first `meta`, so a duplicate could only ever mislead a later
-     * reader, never help one.
+     * Open (or create) a session log.
+     *
+     * A NEW file gets its `meta` line. Reopening an existing one (a `--resume`)
+     * still does NOT get a second `meta` — that ruling is unchanged and is the
+     * reason this method has always branched: `meta` describes where and when the
+     * conversation began, and a second copy written from wherever it was resumed
+     * would make "the session's directory" ambiguous. Replay takes the first
+     * `meta`, so a duplicate could only ever mislead a later reader.
+     *
+     * What a reopen gets instead is a `resumed` event (#172 item 2). It carries
+     * the directory this run is in, which is the fact that used to vanish: a
+     * session begun in one directory and continued in another recorded nothing
+     * about the second, so `cwdMismatchWarning` told the user at the time and the
+     * file forgot immediately. `meta` stays singular and authoritative; the
+     * reopen is a separate kind, and no reader can confuse the two.
      *
      * Returns `null` when a new log cannot be created at all — the caller then
      * runs without persistence rather than failing, exactly as a corrupt usage
-     * store is survivable. A reopen never returns null: a write problem on an
-     * existing file surfaces on the first append, which warns and goes inert.
+     * store is survivable. A reopen still never returns null: the `resumed` write
+     * is now the first append, and a write problem there warns and goes inert
+     * exactly as any other failed append does. A session that cannot record its
+     * own reopen is not a session worth refusing to continue.
      */
     static open(opts) {
         const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
         const log = new SessionLog(file, opts);
-        if (hasContent(file))
+        if (hasContent(file)) {
+            log.write({
+                kind: "resumed",
+                at: new Date().toISOString(),
+                cwd: opts.cwd,
+                roots: opts.roots ?? [],
+                cliVersion: APP_VERSION,
+            });
             return log;
+        }
         const ok = log.write({
             kind: "meta",
             version: SESSION_FILE_VERSION,