@doist/cli-core 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.9.0](https://github.com/Doist/cli-core/compare/v0.8.0...v0.9.0) (2026-05-09)
+
+### Features
+
+* **auth:** add attachLoginCommand Commander helper ([#13](https://github.com/Doist/cli-core/issues/13)) ([bb921b8](https://github.com/Doist/cli-core/commit/bb921b83cee128c627bf7c318a016ef4a3b85582))
+
+## [0.8.0](https://github.com/Doist/cli-core/compare/v0.7.1...v0.8.0) (2026-05-09)
+
+### Features
+
+* **auth:** extract OAuth login runtime into ./auth subpath ([#12](https://github.com/Doist/cli-core/issues/12)) ([d402f02](https://github.com/Doist/cli-core/commit/d402f02d45237245259df753dbc8a97e0c7791e8))
+
 ## [0.7.1](https://github.com/Doist/cli-core/compare/v0.7.0...v0.7.1) (2026-05-09)
 
 ### Bug Fixes

package/README.md

@@ -12,19 +12,20 @@ npm install @doist/cli-core
 
 ## What's in it
 
-| Module               | Key exports                                                                                                                               | Purpose                                                                                                                                                              |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                    | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep. |
-| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                           | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).             |
-| `empty`              | `printEmpty`                                                                                                                              | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                  |
-| `errors`             | `CliError`                                                                                                                                | Typed CLI error class with `code` and exit-code mapping.                                                                                                             |
-| `global-args`        | `parseGlobalArgs`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled` | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`) and derive predicates from them.    |
-| `json`               | `formatJson`, `formatNdjson`                                                                                                              | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                          |
-| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                            | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                |
-| `options`            | `ViewOptions`                                                                                                                             | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                    |
-| `spinner`            | `createSpinner`                                                                                                                           | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                 |
-| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                        | TTY / CI detection helpers.                                                                                                                                          |
-| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                              | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                        |
+| Module               | Key exports                                                                                                                               | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth` (subpath)     | `attachLoginCommand`, `runOAuthFlow`, `createPkceProvider`, PKCE helpers, `AuthProvider` / `TokenStore` types                             | OAuth runtime plus the `attachLoginCommand` Commander helper for `<cli> [auth] login`. Ships the standard public-client PKCE flow (`createPkceProvider`); `AuthProvider` and `TokenStore` are the escape hatches for DCR, OS-keychain, multi-account, etc. — consumers implement `TokenStore` directly (a single-user config-file version is ~30 LoC). `commander` (when using `attachLoginCommand`) and `open` (browser launch) are optional peer-deps. |
+| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                    | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep.                                                                                                                                                                                                                                                                                     |
+| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                           | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).                                                                                                                                                                                                                                                                                                 |
+| `empty`              | `printEmpty`                                                                                                                              | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                                                                                                                                                                                                                                                                                                      |
+| `errors`             | `CliError`                                                                                                                                | Typed CLI error class with `code` and exit-code mapping.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `global-args`        | `parseGlobalArgs`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled` | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`) and derive predicates from them.                                                                                                                                                                                                                                                                                        |
+| `json`               | `formatJson`, `formatNdjson`                                                                                                              | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                            | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                                                                                                                                                                                                                                                                                                    |
+| `options`            | `ViewOptions`                                                                                                                             | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                        |
+| `spinner`            | `createSpinner`                                                                                                                           | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                     |
+| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                        | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                              | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                            |
 
 ## Usage
 
@@ -121,6 +122,57 @@ registerUpdateCommand(program, {
 
 The semver helpers (`parseVersion`, `compareVersions`, `isNewer`, `getInstallTag`, `fetchLatestVersion`, `getConfiguredUpdateChannel`) are also exported for ad-hoc use outside the registered command.
 
+### Auth (optional subpath)
+
+Wire `<cli> [auth] login` and the supporting OAuth runtime. cli-core ships the standard public-client PKCE flow (`createPkceProvider`) and the `attachLoginCommand` Commander helper that drives `runOAuthFlow` end-to-end. Bespoke flows (Dynamic Client Registration, device code, magic link, username/password) implement the `AuthProvider` interface directly — no cli-core release needed.
+
+Token storage is a `TokenStore` the consumer provides — cli-core does not ship a default. The interface is small enough that a single-user config-file version is ~30 lines inline (use `getConfigPath` + `readConfig` / `writeConfig`). OS-keychain-backed storage, multi-account stores, and the sibling Commander helpers (`logout` / `status` / `token`) are all deferred until concrete consumer migrations prove the shared shape.
+
+Install peer-deps in the consuming CLI:
+
+```bash
+npm install commander open   # `open` is optional
+```
+
+Then:
+
+```ts
+import { createPkceProvider, attachLoginCommand } from '@doist/cli-core/auth'
+import type { TokenStore } from '@doist/cli-core/auth'
+
+type Account = { id: string; label?: string; email: string }
+
+const store: TokenStore<Account> = createMyTokenStore() // consumer-supplied
+
+const provider = createPkceProvider<Account>({
+    authorizeUrl: ({ handshake }) => `${handshake.baseUrl as string}/oauth/authorize`,
+    tokenUrl: ({ handshake }) => `${handshake.baseUrl as string}/oauth/token`,
+    clientId: ({ flags }) => flags.clientId as string,
+    scopes: ['read', 'write'],
+    validate: async ({ token, handshake }) => probeUser(token, handshake.baseUrl as string),
+})
+
+const auth = program.command('auth')
+const login = attachLoginCommand<Account>(auth, {
+    provider,
+    store,
+    preferredPort: 54969,
+    portFallbackCount: 5,
+    resolveScopes: ({ readOnly }) => (readOnly ? ['read'] : ['read', 'write']),
+    renderSuccess: () => `<html>...</html>`,
+    renderError: (message) => `<html>${message}</html>`,
+    onSuccess: ({ account, view, flags }) => {
+        if (view.json) console.log(JSON.stringify({ account, flags }))
+        else console.log(`Signed in as ${account.label ?? account.id}`)
+    },
+})
+login.description('Authenticate via OAuth')
+```
+
+`attachLoginCommand` wires `--read-only`, `--callback-port`, `--json`, `--ndjson` and returns the new `Command` so the consumer can chain `.description(...)` / `.option(...)` / `.addHelpText(...)`. Consumer-attached options land in the `flags` object passed to `resolveScopes` and (post-flow) to `onSuccess`. Under `--json` / `--ndjson` the authorize-URL fallback (printed when `open` is missing or fails to launch) is routed to stderr so the JSON envelope on stdout stays clean; pass `onAuthorizeUrl` to override. The success / error HTML is a render hook — every CLI brings its own template (no shared layout enforced). Errors are `CliError` (`AUTH_OAUTH_FAILED`, `AUTH_CALLBACK_TIMEOUT`, `AUTH_PORT_BIND_FAILED`, `AUTH_TOKEN_EXCHANGE_FAILED`, `AUTH_STORE_WRITE_FAILED`); the consumer's top-level handler formats and exits.
+
+For a lower-level integration that doesn't want the Commander helper, `runOAuthFlow` is exposed directly with the same option set.
+
 ## Development
 
 ```bash

package/dist/auth/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error codes thrown by `@doist/cli-core/auth`. Folded into the `CliErrorCode`
+ * aggregator in `../errors.ts` so consumers don't have to redeclare them in
+ * their own `TCode` union when catching.
+ */
+export type AuthErrorCode = 'AUTH_OAUTH_FAILED' | 'AUTH_CALLBACK_TIMEOUT' | 'AUTH_PORT_BIND_FAILED' | 'AUTH_TOKEN_EXCHANGE_FAILED' | 'AUTH_STORE_WRITE_FAILED';
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACnB,mBAAmB,GACnB,uBAAuB,GACvB,uBAAuB,GACvB,4BAA4B,GAC5B,yBAAyB,CAAA"}

package/dist/auth/errors.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.js.map

package/dist/auth/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":""}

package/dist/auth/flow.d.ts

@@ -0,0 +1,47 @@
+import type { AuthAccount, AuthProvider, TokenStore } from './types.js';
+export type RunOAuthFlowOptions<TAccount extends AuthAccount = AuthAccount> = {
+    provider: AuthProvider<TAccount>;
+    store: TokenStore<TAccount>;
+    /** Resolved scope list to request. */
+    scopes: string[];
+    /** Was `--read-only` set? Threaded through to the provider. */
+    readOnly: boolean;
+    /** Per-CLI flags from the command line (Commander option object). */
+    flags: Record<string, unknown>;
+    /** Preferred local callback port. */
+    preferredPort: number;
+    /** Walk up this many sequential ports if `preferredPort` is busy. Default 5. */
+    portFallbackCount?: number;
+    /** Callback path the OAuth provider redirects to. Default `'/callback'`. */
+    callbackPath?: string;
+    /** Bind address. Default `'127.0.0.1'`. */
+    callbackHost?: string;
+    /** HTML returned to the browser on success. */
+    renderSuccess: () => string;
+    /** HTML returned to the browser on failure. Receives the OAuth error description. */
+    renderError: (message: string) => string;
+    /** Override the browser opener (tests). When omitted, dynamically imports `open`. */
+    openBrowser?: (url: string) => Promise<void>;
+    /** Print the authorize URL to stdout as a fallback when the browser can't open it. */
+    onAuthorizeUrl?: (url: string) => void;
+    /** Callback timeout in ms. Default 3 minutes. */
+    timeoutMs?: number;
+    /** Cancellation signal (Ctrl-C wiring). */
+    signal?: AbortSignal;
+};
+export type RunOAuthFlowResult<TAccount extends AuthAccount = AuthAccount> = {
+    token: string;
+    account: TAccount;
+};
+/**
+ * Drive the OAuth dance end-to-end and persist the resulting token.
+ *
+ * `prepare?` → bind callback server → `authorize` → open browser →
+ * wait for callback → `exchangeCode` → `validateToken` → `store.set`.
+ *
+ * The local HTTP callback server is an internal implementation detail; it
+ * is not a separately reusable module since OAuth login is its only
+ * consumer today.
+ */
+export declare function runOAuthFlow<TAccount extends AuthAccount>(options: RunOAuthFlowOptions<TAccount>): Promise<RunOAuthFlowResult<TAccount>>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/auth/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/auth/flow.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvE,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI;IAC1E,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;IAChC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC3B,sCAAsC;IACtC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAA;IACjB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAA;IAC3B,qFAAqF;IACrF,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC,qFAAqF;IACrF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,sFAAsF;IACtF,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI;IACzE,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,QAAQ,CAAA;CACpB,CAAA;AAOD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,QAAQ,SAAS,WAAW,EAC3D,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACvC,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CA0GvC"}

package/dist/auth/flow.js

@@ -0,0 +1,320 @@
+import { createServer } from 'node:http';
+import { CliError, getErrorMessage } from '../errors.js';
+import { isStdoutTTY } from '../terminal.js';
+import { generateState } from './pkce.js';
+const DEFAULT_PORT_FALLBACK_COUNT = 5;
+const DEFAULT_CALLBACK_TIMEOUT_MS = 3 * 60 * 1000;
+const DEFAULT_CALLBACK_PATH = '/callback';
+const DEFAULT_CALLBACK_HOST = '127.0.0.1';
+/**
+ * Drive the OAuth dance end-to-end and persist the resulting token.
+ *
+ * `prepare?` → bind callback server → `authorize` → open browser →
+ * wait for callback → `exchangeCode` → `validateToken` → `store.set`.
+ *
+ * The local HTTP callback server is an internal implementation detail; it
+ * is not a separately reusable module since OAuth login is its only
+ * consumer today.
+ */
+export async function runOAuthFlow(options) {
+    assertValidPort(options.preferredPort, 'preferredPort');
+    const state = generateState();
+    let prepareHandshake = {};
+    const server = await startCallbackServer({
+        preferredPort: options.preferredPort,
+        portFallbackCount: options.portFallbackCount ?? DEFAULT_PORT_FALLBACK_COUNT,
+        path: options.callbackPath ?? DEFAULT_CALLBACK_PATH,
+        host: options.callbackHost ?? DEFAULT_CALLBACK_HOST,
+        expectedState: state,
+        renderSuccess: options.renderSuccess,
+        renderError: options.renderError,
+    });
+    let abortListener = null;
+    if (options.signal) {
+        abortListener = () => {
+            void server.stop();
+        };
+        options.signal.addEventListener('abort', abortListener);
+    }
+    const checkAborted = () => {
+        if (options.signal?.aborted) {
+            throw new CliError('AUTH_OAUTH_FAILED', 'Authorization aborted.');
+        }
+    };
+    try {
+        checkAborted();
+        if (options.provider.prepare) {
+            const prepared = await options.provider.prepare({
+                redirectUri: server.redirectUri,
+                flags: options.flags,
+            });
+            prepareHandshake = prepared.handshake;
+            checkAborted();
+        }
+        const authorize = await options.provider.authorize({
+            redirectUri: server.redirectUri,
+            state,
+            scopes: options.scopes,
+            readOnly: options.readOnly,
+            flags: options.flags,
+            handshake: prepareHandshake,
+        });
+        checkAborted();
+        await openOrFallback(authorize.authorizeUrl, options);
+        const callback = await server.waitForCallback(options.timeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS);
+        checkAborted();
+        // Merge prepareHandshake into the downstream handshake so prepare-time
+        // state survives even when a custom provider's authorize() forgets to
+        // forward it. Then fold the runtime `flags` and `readOnly` into the
+        // handshake so providers' `exchangeCode` / `validateToken` get the
+        // same view that `authorize` had — the typed input fields don't
+        // carry them, and stuffing them here keeps consumer providers from
+        // having to re-thread them manually.
+        const downstreamHandshake = {
+            ...prepareHandshake,
+            ...authorize.handshake,
+            flags: options.flags,
+            readOnly: options.readOnly,
+        };
+        const exchange = await options.provider.exchangeCode({
+            code: callback.code,
+            state: callback.state,
+            redirectUri: server.redirectUri,
+            handshake: downstreamHandshake,
+        });
+        checkAborted();
+        const account = exchange.account ??
+            (await options.provider.validateToken({
+                token: exchange.accessToken,
+                handshake: downstreamHandshake,
+            }));
+        checkAborted();
+        try {
+            await options.store.set(account, exchange.accessToken);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError('AUTH_STORE_WRITE_FAILED', `Failed to persist token: ${getErrorMessage(error)}`);
+        }
+        return { token: exchange.accessToken, account };
+    }
+    finally {
+        if (options.signal && abortListener) {
+            options.signal.removeEventListener('abort', abortListener);
+        }
+        await server.stop();
+    }
+}
+async function startCallbackServer(options) {
+    let settle = null;
+    const outcomePromise = new Promise((resolve) => {
+        settle = resolve;
+    });
+    const server = createServer((req, res) => {
+        handleRequest(req, res, {
+            path: options.path,
+            expectedState: options.expectedState,
+            renderSuccess: options.renderSuccess,
+            renderError: options.renderError,
+            settle: (outcome) => settle?.(outcome),
+        });
+    });
+    const port = await listenWithFallback(server, options.host, options.preferredPort, options.portFallbackCount);
+    // Advertise as `localhost` when bound to the IPv4 loopback default —
+    // matches the redirect-URI allowlists OAuth apps typically register.
+    // IPv6 literals get bracket-wrapped per RFC 3986. Custom hostnames are
+    // advertised verbatim.
+    const redirectUri = `http://${formatHostForUrl(options.host)}:${port}${options.path}`;
+    let stopped = false;
+    return {
+        redirectUri,
+        async waitForCallback(timeoutMs) {
+            let timer;
+            const timeoutOutcome = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    resolve({
+                        ok: false,
+                        error: new CliError('AUTH_CALLBACK_TIMEOUT', `Authorization timed out after ${Math.round(timeoutMs / 1000)}s.`, {
+                            hints: ['Re-run the login command and complete the browser step.'],
+                        }),
+                    });
+                }, timeoutMs);
+            });
+            try {
+                const outcome = await Promise.race([outcomePromise, timeoutOutcome]);
+                if (!outcome.ok)
+                    throw outcome.error;
+                return outcome.result;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            // Settle the outcome so a still-pending `waitForCallback`
+            // (e.g. one cancelled via AbortSignal) doesn't hang forever.
+            settle?.({
+                ok: false,
+                error: new CliError('AUTH_OAUTH_FAILED', 'Callback server stopped before authorization completed.'),
+            });
+            // Browsers keep the success-page connection alive for several
+            // seconds after the redirect; closeAllConnections lets the CLI
+            // exit promptly instead of waiting for those sockets.
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+function handleRequest(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname !== ctx.path) {
+        res.statusCode = 404;
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.end('Not found');
+        return;
+    }
+    const error = url.searchParams.get('error');
+    if (error) {
+        const description = url.searchParams.get('error_description') ?? error;
+        respondHtml(res, 400, ctx.renderError(description));
+        ctx.settle({
+            ok: false,
+            error: new CliError('AUTH_OAUTH_FAILED', `Authorization failed: ${description}`, {
+                hints: ['Check the browser tab for details and try again.'],
+            }),
+        });
+        return;
+    }
+    // Bad-shape callbacks (missing code/state, state mismatch) render a 400
+    // page but do *not* settle the wait — a browser-extension prefetch or
+    // accidental reload shouldn't kill an in-flight OAuth flow. Only a
+    // provider-driven `?error=` is treated as final. The wait still
+    // settles on timeout / `stop()` if a valid callback never arrives.
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state');
+    if (!code || !state) {
+        respondHtml(res, 400, ctx.renderError('Authorization callback missing code or state.'));
+        return;
+    }
+    if (state !== ctx.expectedState) {
+        respondHtml(res, 400, ctx.renderError('Authorization state did not match. Possible CSRF attempt.'));
+        return;
+    }
+    respondHtml(res, 200, ctx.renderSuccess());
+    ctx.settle({ ok: true, result: { code, state } });
+}
+function respondHtml(res, status, html) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(html);
+}
+async function listenWithFallback(server, host, preferred, fallback) {
+    // Port 0 = OS-assigned ephemeral. The bind always succeeds and there's
+    // nothing meaningful to walk to from there.
+    if (preferred === 0) {
+        try {
+            await tryListen(server, host, 0);
+        }
+        catch (error) {
+            throw wrapBindError(error, host, 0);
+        }
+        const address = server.address();
+        if (!address || typeof address === 'string') {
+            throw new CliError('AUTH_PORT_BIND_FAILED', 'Could not resolve assigned port.');
+        }
+        return address.port;
+    }
+    let lastError = null;
+    for (let i = 0; i <= fallback; i++) {
+        const port = preferred + i;
+        // Stop walking past the valid port range; otherwise `server.listen`
+        // throws a raw `RangeError` outside the `CliError` envelope.
+        if (port > 65535)
+            break;
+        try {
+            await tryListen(server, host, port);
+            return port;
+        }
+        catch (error) {
+            const err = error;
+            // Surface non-EADDRINUSE failures (EACCES on privileged ports,
+            // an unreachable host, …) via the typed error envelope rather
+            // than letting Node's raw error escape.
+            if (err.code !== 'EADDRINUSE')
+                throw wrapBindError(err, host, port);
+            lastError = err;
+        }
+    }
+    throw new CliError('AUTH_PORT_BIND_FAILED', `Could not bind a local port in range ${preferred}..${preferred + fallback}.`, {
+        hints: [
+            'Free a port in that range or pass a different preferred port.',
+            lastError?.message ?? '',
+        ].filter(Boolean),
+    });
+}
+function wrapBindError(error, host, port) {
+    return new CliError('AUTH_PORT_BIND_FAILED', `Could not bind callback server to ${host}:${port}: ${getErrorMessage(error)}`);
+}
+function tryListen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+function formatHostForUrl(host) {
+    if (host === DEFAULT_CALLBACK_HOST)
+        return 'localhost';
+    if (host.includes(':'))
+        return `[${host}]`;
+    return host;
+}
+function assertValidPort(port, label) {
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new CliError('AUTH_PORT_BIND_FAILED', `Invalid ${label} '${String(port)}': expected an integer in [0..65535].`);
+    }
+}
+async function openOrFallback(url, options) {
+    const opener = options.openBrowser ?? (await loadDefaultOpener());
+    if (opener) {
+        try {
+            await opener(url);
+            return;
+        }
+        catch {
+            // Fall through to the URL print below.
+        }
+    }
+    // No opener available, or the opener threw. Surface the URL so the user
+    // can finish the flow manually.
+    if (options.onAuthorizeUrl)
+        options.onAuthorizeUrl(url);
+    else if (isStdoutTTY())
+        console.log(`Open this URL in your browser:\n  ${url}`);
+}
+async function loadDefaultOpener() {
+    try {
+        const mod = (await import('open'));
+        return async (url) => {
+            await mod.default(url);
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=flow.js.map

package/dist/auth/flow.js.map

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

package/dist/auth/index.d.ts

@@ -0,0 +1,11 @@
+export type { AuthErrorCode } from './errors.js';
+export { runOAuthFlow } from './flow.js';
+export type { RunOAuthFlowOptions, RunOAuthFlowResult } from './flow.js';
+export { attachLoginCommand } from './login.js';
+export type { AttachLoginCommandOptions, AttachLoginContext } from './login.js';
+export { DEFAULT_VERIFIER_ALPHABET, deriveChallenge, generateState, generateVerifier, } from './pkce.js';
+export type { GenerateVerifierOptions } from './pkce.js';
+export { createPkceProvider } from './providers/pkce.js';
+export type { PkceLazyString, PkceProviderOptions } from './providers/pkce.js';
+export type { AuthAccount, AuthorizeInput, AuthorizeResult, AuthProvider, ExchangeInput, ExchangeResult, PrepareInput, PrepareResult, TokenStore, ValidateInput, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,YAAY,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EACR,WAAW,EACX,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,GAChB,MAAM,YAAY,CAAA"}

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+export { runOAuthFlow } from './flow.js';
+export { attachLoginCommand } from './login.js';
+export { DEFAULT_VERIFIER_ALPHABET, deriveChallenge, generateState, generateVerifier, } from './pkce.js';
+export { createPkceProvider } from './providers/pkce.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/auth/login.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from 'commander';
+import type { ViewOptions } from '../options.js';
+import type { AuthAccount, AuthProvider, TokenStore } from './types.js';
+export type AttachLoginContext<TAccount extends AuthAccount> = {
+    account: TAccount;
+    /** `--json` / `--ndjson` flag values, both present (defaulted to `false`). */
+    view: Required<ViewOptions>;
+    /**
+     * Stripped per-CLI flags — the parsed options object with the standard
+     * registrar flags (`--read-only`, `--callback-port`, `--json`, `--ndjson`)
+     * removed. Same view `resolveScopes` saw at flow start.
+     */
+    flags: Record<string, unknown>;
+};
+export type AttachLoginCommandOptions<TAccount extends AuthAccount = AuthAccount> = {
+    provider: AuthProvider<TAccount>;
+    store: TokenStore<TAccount>;
+    /** Default local OAuth callback port. Overridable per-invocation via `--callback-port`. */
+    preferredPort: number;
+    /** Walk up this many sequential ports if `preferredPort` is busy. Default: 5. */
+    portFallbackCount?: number;
+    /** Resolve the scope list to request from the runtime flags + read-only state. */
+    resolveScopes(ctx: {
+        readOnly: boolean;
+        flags: Record<string, unknown>;
+    }): string[];
+    renderSuccess(): string;
+    renderError(message: string): string;
+    /** Override the browser opener (tests). When omitted, `runOAuthFlow` imports `open`. */
+    openBrowser?(url: string): Promise<void>;
+    /**
+     * Override the authorize-URL fallback callback that fires when the browser
+     * can't be opened (no `open` peer / opener throws). When omitted, the URL
+     * is written to stderr in machine-output mode (so the JSON / NDJSON
+     * envelope on stdout stays clean) and to stdout via `runOAuthFlow`'s
+     * default in human mode.
+     */
+    onAuthorizeUrl?(url: string): void;
+    /** Called after the token is persisted. */
+    onSuccess(ctx: AttachLoginContext<TAccount>): void | Promise<void>;
+};
+/**
+ * Attach `login` as a subcommand of `parent`. Wires the standard flag set
+ * (`--read-only`, `--callback-port`, `--json`, `--ndjson`) and drives
+ * `runOAuthFlow`. Returns the new `Command` so the consumer can chain
+ * `.description(...)` / `.option(...)` / `.addHelpText(...)` for additional
+ * flags or help text.
+ *
+ * Additional Commander options the consumer attaches to the returned command
+ * land on the same parsed options object Commander hands to the action, so
+ * `resolveScopes` and `onSuccess` see them via `flags`.
+ */
+export declare function attachLoginCommand<TAccount extends AuthAccount>(parent: Command, options: AttachLoginCommandOptions<TAccount>): Command;
+//# sourceMappingURL=login.d.ts.map

package/dist/auth/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/auth/login.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvE,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,WAAW,IAAI;IAC3D,OAAO,EAAE,QAAQ,CAAA;IACjB,8EAA8E;IAC9E,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;IAC3B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAAI;IAChF,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;IAChC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC3B,2FAA2F;IAC3F,aAAa,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kFAAkF;IAClF,aAAa,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM,EAAE,CAAA;IACnF,aAAa,IAAI,MAAM,CAAA;IACvB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACpC,wFAAwF;IACxF,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,2CAA2C;IAC3C,SAAS,CAAC,GAAG,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrE,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,WAAW,EAC3D,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC7C,OAAO,CAwCT"}