@ai21/gateway 1.2.0 → 1.3.1

package/dist/agents/types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The contract every coding agent implements. The router owns the flow that is the same
+ * for all of them — resolve the key, check it, gate on a subscription, snapshot, write,
+ * verify, undo when there is no subscription, report — and asks the agent for everything
+ * that differs: where its config lives, what goes in it, how to take it out again, how
+ * to tell whether its user is signed in, and how to prove the result works.
+ *
+ * Outcomes are agent-neutral (paths and key names are data), so `report.ts` renders any
+ * agent's result and reads only the agent's `text` for the words that name it.
+ */
+import type { Client, ResolvedUrls, Target } from "../args.js";
+import type { ConfigPaths } from "../fs/safeFile.js";
+import type { PathLookup, RunCommand } from "../process.js";
+/** What every agent's config is rendered from. */
+export interface SnippetInputs {
+    readonly gatewayUrl: string;
+    readonly agentId: string;
+    readonly ai21Key: string;
+    /** Signed-in user id for per-user attribution. Absent on a normal CLI run. */
+    readonly userId?: string | undefined;
+    /**
+     * Marks the traffic as configured by this tool, e.g. `ai21-gateway-cli/0.4.0`.
+     *
+     * Set on what the CLI writes, and deliberately absent from the snippet builders the
+     * contract tests pin against the webapp: a config someone pasted by hand did not
+     * come from here and must not claim to have. Lets the gateway tell the two apart
+     * without the CLI reporting anything itself.
+     */
+    readonly client?: string | undefined;
+}
+/** Stand-in for the AI21 key in a preview, before one has been supplied. */
+export declare const AI21_KEY_PLACEHOLDER = "<your-ai21-api-key>";
+/** Injected rather than read from the process, so tests can use a temp directory. */
+export interface PathContext {
+    readonly cwd: string;
+    readonly home: string;
+}
+/** What an agent may read to locate its config — some honour an env override. */
+export interface AgentEnv extends PathContext {
+    readonly processEnv: Record<string, string | undefined>;
+}
+export interface AgentPaths extends ConfigPaths {
+    /**
+     * Where to run the agent's own CLI so that the file we wrote is the one it reads.
+     * Home for a user-level config, since a project-local one would outrank it.
+     */
+    readonly verifyCwd: string;
+}
+export interface Conflict {
+    readonly key: string;
+    readonly current: string;
+    readonly desired: string;
+}
+export type ConfigOutcome = {
+    readonly kind: "created";
+    readonly path: string;
+} | {
+    readonly kind: "updated";
+    readonly path: string;
+    readonly backup: string;
+    readonly changed: readonly string[];
+} | {
+    readonly kind: "unchanged";
+    readonly path: string;
+} | {
+    readonly kind: "conflict";
+    readonly path: string;
+    readonly conflicts: readonly Conflict[];
+} | {
+    readonly kind: "malformed";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly path: string;
+    readonly reason: string;
+};
+export type RevertOutcome = {
+    readonly kind: "reverted";
+    readonly path: string;
+    /** Keys we added, so reverting means deleting them. */
+    readonly removed: readonly string[];
+    /** Keys that held a value before we wrote, now put back. */
+    readonly restored: readonly string[];
+    /** A `.bak` was there but could not be parsed, so prior values were lost. */
+    readonly backupUnreadable: boolean;
+} | {
+    readonly kind: "restored";
+    readonly path: string;
+    readonly backup: string;
+}
+/** None of the managed keys were there — not ours to revert. */
+ | {
+    readonly kind: "not-configured";
+    readonly path: string;
+} | {
+    readonly kind: "agent-mismatch";
+    readonly path: string;
+    readonly expected: string;
+    readonly actual: string;
+}
+/** `--from-backup` would discard edits made since our write. */
+ | {
+    readonly kind: "drifted";
+    readonly path: string;
+    readonly backup: string;
+} | {
+    readonly kind: "no-backup";
+    readonly path: string;
+    readonly backup: string;
+} | {
+    readonly kind: "malformed";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly path: string;
+    readonly reason: string;
+};
+export interface RevertOptions {
+    /** Restore the `.bak` verbatim instead of removing our keys surgically. */
+    readonly fromBackup: boolean;
+    /** Proceed with a restore that discards drift. */
+    readonly force: boolean;
+    /** When set, the stored `x-agent-id` must equal this or nothing is written. */
+    readonly agentIdGuard?: string | undefined;
+}
+/** Whether the agent's own login can carry requests through the gateway. */
+export type SubscriptionStatus = {
+    readonly kind: "present";
+}
+/** Definitely unusable; `reason` keys into `AgentText.noSubscription`. */
+ | {
+    readonly kind: "missing";
+    readonly reason: string;
+}
+/** Could not tell — never blocks an install. */
+ | {
+    readonly kind: "inconclusive";
+};
+/** Whether the agent can run on this machine at all, before anything else does. */
+export type InstallStatus = {
+    readonly kind: "present";
+} | {
+    readonly kind: "missing";
+};
+/** What `checkInstalled` may consult: an upstream key can stand in for a missing binary. */
+export interface InstallContext {
+    readonly upstreamKey?: string | undefined;
+    readonly processEnv: Record<string, string | undefined>;
+}
+export interface VerifyContext {
+    readonly urls: ResolvedUrls;
+    readonly agentId: string;
+    readonly ai21Key: string;
+    readonly userId?: string | undefined;
+    /** The agent's own upstream credential for a direct check, when it has a flag for one. */
+    readonly upstreamKey?: string | undefined;
+    readonly processEnv: Record<string, string | undefined>;
+    /** `AgentPaths.verifyCwd`. */
+    readonly cwd: string;
+}
+/**
+ * How verification ended. Only `no-subscription` changes the exit code. `via` names the
+ * tier that ran and `reason` the missing credential; both key into the agent's `text`.
+ */
+export type VerifyOutcome = {
+    readonly kind: "disabled";
+} | {
+    readonly kind: "skipped";
+    readonly hint: string;
+} | {
+    readonly kind: "passed";
+    readonly via: string;
+} | {
+    readonly kind: "failed";
+    readonly via: string;
+    readonly reason: string;
+} | {
+    readonly kind: "no-subscription";
+    readonly via: string;
+    readonly reason: string;
+};
+/** Just enough of `fetch` to send one request. `text` is optional; absent means inconclusive. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text?: () => Promise<string>;
+}>;
+/** The outside world an agent touches while checking a login or verifying. */
+export interface AgentDeps {
+    readonly lookup: PathLookup;
+    readonly runCommand: RunCommand;
+    readonly fetchImpl: FetchLike;
+}
+export interface Warning {
+    /** Stable identifier, so `--json` consumers match on this and not on prose. */
+    readonly code: string;
+    readonly message: string;
+}
+/** Flags that feed only a verification tier some agents have. */
+export type VerifyFlag = "anthropic-key";
+/** What the no-subscription refusal says for one `SubscriptionStatus`/`VerifyOutcome` reason. */
+export interface NoSubscriptionText {
+    readonly headline: string;
+    readonly nextStep: string;
+    /** Stable `--json` reason, spelled for a funnel rather than for a person. */
+    readonly jsonReason: string;
+}
+/** What the not-installed refusal says. `jsonOutcome` and `jsonReason` are a contract: never renamed. */
+export interface NotInstalledText {
+    readonly message: string;
+    readonly jsonOutcome: string;
+    readonly jsonReason: string;
+}
+/** Every user-facing phrase that names the agent or its tooling. */
+export interface AgentText {
+    /** The `--json` `outcome` of the no-subscription refusal. A contract: never renamed. */
+    readonly noSubscriptionOutcome: string;
+    readonly noSubscription: Readonly<Record<string, NoSubscriptionText>>;
+    /** How each verification tier reads once it has passed, keyed by `VerifyOutcome.via`. */
+    readonly verifiedVia: Readonly<Record<string, string>>;
+    /** Why verification was skipped, before the agent's manual hint. */
+    readonly skippedBecause: string;
+    readonly notInstalled: NotInstalledText;
+    /** The status line while `checkSubscription` runs: "Checking your Claude login…". */
+    readonly checkingLogin: string;
+    /** The done line once `checkSubscription` found a usable login: "Claude login found". */
+    readonly loginFound: string;
+}
+export interface CodingAgent {
+    readonly id: Client;
+    /** "Claude Code", as a sentence would name it. */
+    readonly displayName: string;
+    /** The config file's name, for help and messages: "settings.json". */
+    readonly configLabel: string;
+    /** Which of `--user` / `--repo` this agent can be configured at. */
+    readonly targets: readonly Target[];
+    readonly verifyFlags: readonly VerifyFlag[];
+    /** Checked first by install, even under --no-verify: `missing` stops it before sign-in or any write. */
+    checkInstalled(ctx: InstallContext, deps: AgentDeps): InstallStatus;
+    resolvePaths(target: Target, env: AgentEnv): AgentPaths;
+    /** What `--print` shows: the file as text, and the fields `--json` adds beside target and urls. */
+    preview(inputs: SnippetInputs): {
+        readonly text: string;
+        readonly json: Readonly<Record<string, unknown>>;
+    };
+    /** Merge our config in. Never throws; nothing is written on `conflict` or `malformed`. */
+    write(paths: AgentPaths, inputs: SnippetInputs, options: {
+        readonly force: boolean;
+    }): ConfigOutcome;
+    revert(paths: AgentPaths, options: RevertOptions): RevertOutcome;
+    /** Blanks the AI21 key in a config value, so conflict output never prints it. */
+    redact(value: string): string;
+    /** Agent-specific things that make a correct config look broken later. */
+    warnings(paths: AgentPaths, processEnv: Record<string, string | undefined>): Warning[];
+    checkSubscription(paths: AgentPaths, deps: AgentDeps): Promise<SubscriptionStatus>;
+    /** Exactly one real request through the gateway, or none. */
+    verify(ctx: VerifyContext, deps: AgentDeps): Promise<VerifyOutcome>;
+    readonly text: AgentText;
+}

package/dist/agents/types.js

@@ -0,0 +1,3 @@
+/** Stand-in for the AI21 key in a preview, before one has been supplied. */
+export const AI21_KEY_PLACEHOLDER = "<your-ai21-api-key>";
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAgCA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC"}

package/dist/cli.js

@@ -7,13 +7,18 @@ import { parseCliArgs } from "./args.js";
 import { EXIT } from "./result.js";
 import { dispatch } from "./router.js";
 import { nodePrecheckDeps } from "./precheck.js";
-import { isExecutableFile, nodeVerifyDeps } from "./verify.js";
+import { nodeAgentDeps } from "./agents/deps.js";
+import { isExecutableFile } from "./process.js";
 import { nodeBrowserDeps, openBrowser } from "./login/browser.js";
 import { selectSecretStore } from "./login/keychain/select.js";
 import { runCredentialCommand } from "./login/keychain/runner.js";
 import { startLoopback } from "./login/loopback.js";
+import { createStatusLine, isInteractive } from "./status.js";
+import { waitForEnter } from "./prompt.js";
 import { FLUSH_CAP_MS, nodeTelemetry } from "./telemetry/telemetry.js";
 export { EXIT } from "./result.js";
+/** 128 + SIGINT: what a shell reports for Ctrl-C, so scripts see the usual code. */
+const EXIT_INTERRUPTED = 130;
 export const USAGE = `ai21-gateway — point a local coding agent at the AI21 Intelligent Gateway
 
 Usage:
@@ -126,21 +131,31 @@ export async function run(argv) {
         case "error":
             return { code: EXIT.USAGE, out: "", err: `${outcome.message}\n\n${USAGE}\n` };
         case "args": {
+            // `--json` keeps stderr to plain lines too: a consumer may be capturing both streams.
+            const status = createStatusLine(process.stderr, !outcome.args.json && isInteractive(process.stderr, process.env));
             // One stream for login's progress and credential-file warnings, so neither is missed.
-            const notify = (message) => void process.stderr.write(`${message}\n`);
+            // Routed through the status line so a message never lands in the middle of the spinner.
+            const notify = (message) => status.log(message);
             // Everything the CLI needs from the outside world is gathered here, at the
             // edge, so every layer below stays pure and testable against a temp
             // directory and a pair of fake streams.
             const telemetry = nodeTelemetry(outcome.args.urls.gateway, versionForTelemetry(), fetch);
+            // Ctrl-C would otherwise leave a half-drawn spinner on the prompt line.
+            const interrupt = () => {
+                status.stop();
+                process.exit(EXIT_INTERRUPTED);
+            };
+            process.once("SIGINT", interrupt);
             const result = await dispatch(outcome.args, {
                 paths: { cwd: process.cwd(), home: homedir() },
                 prompt: { input: process.stdin, output: process.stderr },
                 processEnv: process.env,
-                verify: nodeVerifyDeps(process.env),
+                verify: nodeAgentDeps(process.env),
                 precheck: nodePrecheckDeps(),
                 login: {
                     startListener: startLoopback,
                     openBrowser: (url) => openBrowser(url, nodeBrowserDeps()),
+                    waitForEnter: () => waitForEnter(process.stdin),
                     fetchImpl: fetch,
                     secrets: selectSecretStore({
                         paths: { home: homedir(), warn: notify },
@@ -153,7 +168,12 @@ export async function run(argv) {
                 // stderr, so `--json` on stdout stays a single parseable object even while
                 // login narrates its progress.
                 notify,
+                status,
                 telemetry,
+            }).finally(() => {
+                // Cleared before the caller writes the result, and on a throw, so no frame survives.
+                status.stop();
+                process.off("SIGINT", interrupt);
             });
             // The caller exits right after this returns, which would cut off a send in flight.
             await telemetry.flush(FLUSH_CAP_MS);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AAEnD,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SA0DZ,CAAC;AAEV,+EAA+E;AAC/E,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IACtE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC;IAC7D,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qFAAqF;AACrF,SAAS,mBAAmB;IAC1B,IAAI,CAAC;QACH,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,aAAa;IACpB,IAAI,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,0EAA0E;QAC1E,kCAAkC;QAClC,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,QAAQ;YACnB,GAAG,EAAE,EAAE;YACP,GAAG,EAAE,6GAA6G;SACnH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAuB;IAC/C,wEAAwE;IACxE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;IAE5E,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;QACvD,KAAK,SAAS;YACZ,OAAO,aAAa,EAAE,CAAC;QACzB,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,OAAO,KAAK,IAAI,EAAE,CAAC;QAChF,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,sFAAsF;YACtF,MAAM,MAAM,GAAG,CAAC,OAAe,EAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;YAEpF,2EAA2E;YAC3E,oEAAoE;YACpE,wCAAwC;YACxC,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,KAAK,CAAC,CAAC;YAEzF,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE;gBAC1C,KAAK,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;gBAC9C,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;gBACxD,UAAU,EAAE,OAAO,CAAC,GAAG;gBACvB,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;gBACnC,QAAQ,EAAE,gBAAgB,EAAE;gBAC5B,KAAK,EAAE;oBACL,aAAa,EAAE,aAAa;oBAC5B,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC;oBACzD,SAAS,EAAE,KAAK;oBAChB,OAAO,EAAE,iBAAiB,CAAC;wBACzB,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;wBACxC,GAAG,EAAE,oBAAoB;wBACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ;wBAC1B,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,gBAAgB,EAAE;wBACjF,SAAS,EAAE,aAAa;qBACzB,CAAC;iBACH;gBACD,2EAA2E;gBAC3E,+BAA+B;gBAC/B,MAAM;gBACN,SAAS;aACV,CAAC,CAAC;YAEH,mFAAmF;YACnF,MAAM,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAEpC,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa;IACpB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,4BAA4B,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,MAAM;IACb,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAExC,IAAI,CAAC;QACH,8EAA8E;QAC9E,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,MAAM,EAAE,EAAE,CAAC;IACb,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE1C,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE1C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/fs/safeFile.d.ts

@@ -0,0 +1,19 @@
+/** A config file and the backup kept beside it. */
+export interface ConfigPaths {
+    readonly settings: string;
+    readonly backup: string;
+}
+/** A symlinked config is backed up beside its target, not beside the link. */
+export declare function backupPathFor(paths: ConfigPaths, realPath: string): string;
+/**
+ * Turns an fs error into something safe to print. The code is translated rather
+ * than forwarded so no stack frame, errno struct or internal path escapes.
+ */
+export declare function describeFsError(err: unknown): string;
+/**
+ * Write via a sibling temp file and rename. The rename is atomic within a
+ * filesystem, so a reader either sees the old file or the new one — never a
+ * half-written config. The temp file is removed on any failure so a crashed run
+ * leaves no litter next to the real file.
+ */
+export declare function atomicWrite(target: string, contents: string | Buffer): void;

package/dist/fs/safeFile.js

@@ -0,0 +1,50 @@
+/**
+ * Writing a file someone else owns: atomically, owner-only, with errors that are safe
+ * to print. Shared by every coding agent's config writer, revert and snapshot.
+ */
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+/** A symlinked config is backed up beside its target, not beside the link. */
+export function backupPathFor(paths, realPath) {
+    return realPath === paths.settings ? paths.backup : `${realPath}.bak`;
+}
+/**
+ * Turns an fs error into something safe to print. The code is translated rather
+ * than forwarded so no stack frame, errno struct or internal path escapes.
+ */
+export function describeFsError(err) {
+    const code = err?.code;
+    switch (code) {
+        case "EACCES":
+        case "EPERM":
+            return "permission denied";
+        case "ENOSPC":
+            return "no space left on the device";
+        case "EROFS":
+            return "the filesystem is read-only";
+        case "EISDIR":
+            return "it is a directory, not a file";
+        default:
+            return "the write could not be completed";
+    }
+}
+/**
+ * Write via a sibling temp file and rename. The rename is atomic within a
+ * filesystem, so a reader either sees the old file or the new one — never a
+ * half-written config. The temp file is removed on any failure so a crashed run
+ * leaves no litter next to the real file.
+ */
+export function atomicWrite(target, contents) {
+    // Same directory, so the rename cannot cross a filesystem boundary. The pid
+    // keeps two concurrent runs from fighting over one temp name.
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        // 0600: this file carries an API key.
+        writeFileSync(tmp, contents, { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=safeFile.js.map

package/dist/fs/safeFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeFile.js","sourceRoot":"","sources":["../../src/fs/safeFile.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ5D,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,KAAkB,EAAE,QAAgB;IAChE,OAAO,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,MAAM,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAI,GAAyC,EAAE,IAAI,CAAC;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,mBAAmB,CAAC;QAC7B,KAAK,QAAQ;YACX,OAAO,6BAA6B,CAAC;QACvC,KAAK,OAAO;YACV,OAAO,6BAA6B,CAAC;QACvC,KAAK,QAAQ;YACX,OAAO,+BAA+B,CAAC;QACzC;YACE,OAAO,kCAAkC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAyB;IACnE,4EAA4E;IAC5E,8DAA8D;IAC9D,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,IAAI,CAAC;QACH,sCAAsC;QACtC,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7B,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/{snapshot.d.ts → fs/snapshot.d.ts}

@@ -1,4 +1,4 @@
-import { type ConfigPaths } from "./config.js";
+import { type ConfigPaths } from "./safeFile.js";
 /** One file as it was: its bytes and mode, or the fact that it did not exist. */
 type FileState = {
     readonly path: string;

package/dist/{snapshot.js → fs/snapshot.js}

@@ -6,7 +6,7 @@
  */
 import { chmodSync, existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { atomicWrite, backupPathFor, describeFsError } from "./config.js";
+import { atomicWrite, backupPathFor, describeFsError } from "./safeFile.js";
 function capture(path) {
     if (!existsSync(path))
         return { path, present: false };

package/dist/fs/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/fs/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACvH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAoB,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAe9F,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEvD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;AAClG,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;IAExD,IAAI,SAAS,CAAC,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC;QAC9E,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;AACvG,CAAC;AAED,SAAS,GAAG,CAAC,KAAgB;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,OAAO;IACT,CAAC;IAED,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,wEAAwE;IACxE,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,QAAwB;IACpD,IAAI,CAAC;QACH,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACvB,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9B,CAAC"}

package/dist/login/keychain/linux.d.ts

@@ -9,7 +9,7 @@
  * The secret goes in on stdin and comes out on stdout unchanged, so unlike macOS it needs
  * no encoding.
  */
-import { type PathLookup } from "../../verify.js";
+import { type PathLookup } from "../../process.js";
 import type { SecretStore } from "../secretStore.js";
 import { type CommandRunner } from "./runner.js";
 export declare const SECRET_TOOL = "secret-tool";

package/dist/login/keychain/linux.js

@@ -9,7 +9,7 @@
  * The secret goes in on stdin and comes out on stdout unchanged, so unlike macOS it needs
  * no encoding.
  */
-import { findOnPath } from "../../verify.js";
+import { findOnPath } from "../../process.js";
 import { KEYCHAIN_SERVICE, KEYCHAIN_TIMEOUT_MS, accountFor, failureReason } from "./runner.js";
 export const SECRET_TOOL = "secret-tool";
 /** How the entry is labelled in Seahorse or KWalletManager, for a human deleting it. */

package/dist/login/keychain/linux.js.map

@@ -1 +1 @@
-{"version":3,"file":"linux.js","sourceRoot":"","sources":["../../../src/login/keychain/linux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAmB,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,UAAU,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAEnH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC,wFAAwF;AACxF,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAWjC,gDAAgD;AAChD,MAAM,UAAU,KAAK,CAAC,SAA6B;IACjD,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,IAAuB;IACpD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAElF,OAAO,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAuB,EAAE,UAAkB;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACjD,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,IAAgB,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACrH,MAAM,GAAG,GAAG,CAAC,IAAuB,EAAE,KAAc,EAAE,EAAE,CACtD,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAExE,MAAM,IAAI,GAAG,KAAK,EAAE,OAAe,EAAE,IAAgB,EAA+B,EAAE;QACpF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpE,qFAAqF;QACrF,IAAI,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAEnF,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,SAAS,CAAC;QAElE,uFAAuF;QACvF,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,UAAU;QAEhB,IAAI;QAEJ,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK;YAC9B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAE5F,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9G,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI;YACxB,uFAAuF;YACvF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC3C,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAEnD,OAAO,QAAQ,KAAK,SAAS,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"linux.js","sourceRoot":"","sources":["../../../src/login/keychain/linux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,UAAU,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAEnH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC,wFAAwF;AACxF,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAWjC,gDAAgD;AAChD,MAAM,UAAU,KAAK,CAAC,SAA6B;IACjD,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,IAAuB;IACpD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAElF,OAAO,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAuB,EAAE,UAAkB;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACjD,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,IAAgB,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACrH,MAAM,GAAG,GAAG,CAAC,IAAuB,EAAE,KAAc,EAAE,EAAE,CACtD,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAExE,MAAM,IAAI,GAAG,KAAK,EAAE,OAAe,EAAE,IAAgB,EAA+B,EAAE;QACpF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpE,qFAAqF;QACrF,IAAI,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAEnF,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,SAAS,CAAC;QAElE,uFAAuF;QACvF,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,UAAU;QAEhB,IAAI;QAEJ,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK;YAC9B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAE5F,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9G,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI;YACxB,uFAAuF;YACvF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC3C,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAEnD,OAAO,QAAQ,KAAK,SAAS,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/login/session.d.ts

@@ -6,6 +6,11 @@ import type { SecretStore } from "./secretStore.js";
 export interface LoginDeps {
     readonly startListener: (options: LoopbackOptions) => Promise<Listener>;
     readonly openBrowser: (url: string) => boolean;
+    /**
+     * Holds the flow until the user presses Enter; false if input ended instead. Absent,
+     * the browser opens straight away, which is what tests and non-interactive callers get.
+     */
+    readonly waitForEnter?: () => Promise<boolean>;
     /** For the token exchange and workspace listing; injected so tests make no calls. */
     readonly fetchImpl: FetchLike;
     /** Where the refresh token and the minted key are kept; injected so tests use neither. */
@@ -26,7 +31,14 @@ export type LoginOutcome = {
 export interface LoginProgress {
     /** The caller decides which stream this lands on. */
     readonly notify: (message: string) => void;
+    /** Called once the browser has been sent to the sign-in page and the wait begins. */
+    readonly waiting?: () => void;
 }
+/**
+ * The code framed so the eye lands on it: it is the whole defence against another
+ * process asking to sign in, and in running prose it was easy to skim past.
+ */
+export declare function codeBox(code: string): string;
 /**
  * The consent screen's URL.
  *

package/dist/login/session.js

@@ -6,6 +6,15 @@
 import { randomInt } from "node:crypto";
 import { CLIENT_ID, CLIENT_PARAM, CLI_LOGIN_PATH, CODE_PARAM, EXPIRES_PARAM, REDIRECT_PARAM, STATE_PARAM, verificationCode, } from "./contract.js";
 import { LOGIN_TIMEOUT_MS } from "./loopback.js";
+/**
+ * The code framed so the eye lands on it: it is the whole defence against another
+ * process asking to sign in, and in running prose it was easy to skim past.
+ */
+export function codeBox(code) {
+    const inner = ` verification code: ${code} `;
+    const rule = "─".repeat([...inner].length);
+    return `  ╭${rule}╮\n  │${inner}│\n  ╰${rule}╯`;
+}
 /**
  * The consent screen's URL.
  *
@@ -25,7 +34,18 @@ export function loginUrl(urls, callbackUrl, state, code, expiresAtSeconds) {
 }
 export async function runLogin(urls, deps, io) {
     const code = verificationCode((max) => randomInt(max));
-    // Stamped early, so the page gives up a moment before the listener, not after.
+    /* The code comes first and the browser only on Enter, so it is read before the browser
+     * takes focus. The listener starts after that too: its clock must not run while the
+     * user is still reading. */
+    io.notify(`Sign in to AI21 to continue.\n\n${codeBox(code)}\n\n` +
+        `The sign-in page will show this code. If it shows anything else, choose Deny —\n` +
+        `something other than this terminal is asking to sign in.`);
+    if (deps.waitForEnter !== undefined) {
+        io.notify(`\nPress Enter to open ${new URL(urls.app).host} in your browser…`);
+        if (!(await deps.waitForEnter()))
+            return { kind: "declined", reason: "it was cancelled in the terminal" };
+    }
+    // Stamped here, so the page gives up a moment before the listener, not after.
     const expiresAtSeconds = Math.floor((Date.now() + LOGIN_TIMEOUT_MS) / 1000);
     let listener;
     try {
@@ -40,10 +60,8 @@ export async function runLogin(urls, deps, io) {
     /* Printed as well as opened: `openBrowser` cannot tell us a browser appeared, and over
      * SSH the URL is the only way in. */
     deps.openBrowser(listener.signInUrl);
-    io.notify(`Sign in to continue — your browser should open. If it does not, visit:\n\n  ${listener.signInUrl}\n\n` +
-        `  verification code: ${code}\n\n` +
-        `The page will show this code. If it shows anything else, choose Deny — something\n` +
-        `other than this terminal is asking to sign in.\n\nWaiting…`);
+    io.notify(`\nIf the browser did not open, visit:\n\n  ${listener.signInUrl}`);
+    io.waiting?.();
     return settle(await listener.result);
 }
 function settle(outcome) {

package/dist/login/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/login/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/login/session.ts"],"names":[],"mappings":"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"}

package/dist/process.d.ts

@@ -0,0 +1,26 @@
+export interface CommandResult {
+    /** `null` when the process was killed or could not be started at all. */
+    readonly code: number | null;
+    readonly timedOut: boolean;
+    /** Combined stdout+stderr, used only to explain a failure. */
+    readonly output: string;
+}
+/** Runs one executable with a hard time budget; never rejects. */
+export type RunCommand = (executable: string, args: readonly string[], opts: {
+    readonly cwd: string;
+    readonly timeoutMs: number;
+}) => Promise<CommandResult>;
+export interface PathLookup {
+    readonly platform: string;
+    readonly processEnv: Record<string, string | undefined>;
+    /** Injected so the tier-1 tests never depend on what is installed. */
+    readonly isExecutableFile: (candidate: string) => boolean;
+}
+/**
+ * Hand-rolled rather than shelling out to `which`/`where`, which is slower and
+ * absent from stripped Windows images. `node:path`'s `join` and `delimiter` follow
+ * the *host* platform, so they cannot resolve a Windows PATH under test on macOS.
+ */
+export declare function findOnPath(command: string, lookup: PathLookup): string | undefined;
+export declare const runCommand: RunCommand;
+export declare function isExecutableFile(candidate: string): boolean;