@deepseek-harness-tui/dsh-tui 0.9.0 → 0.9.2

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/interaction.js

@@ -0,0 +1,193 @@
+/**
+ * The `AuthInteraction` bridge: pi-ai OAuth flows speak prompts and events;
+ * every interactive surface in this ecosystem speaks `ctx.userQuestions`.
+ *
+ * `prompt()` maps one pi-ai prompt onto one question — `select` prompts carry
+ * their options, text/secret/manual-code prompts expect the custom-answer
+ * input row.
+ *
+ * `notify()` restores the host contract pi-ai's browser flows assume: the
+ * `auth_url` / `device_code` events expect the *host* to open the browser
+ * (their authorize URLs run hundreds of characters — wrapped across panel
+ * lines they are unclickable, and hand-copying picks up wrap artifacts that
+ * corrupt the encoded `redirect_uri`, which the provider then rejects). So
+ * the bridge opens the URL itself, then shows one waiting panel carrying
+ * copy / reopen / cancel actions until the flow settles. The device-code
+ * path gets the same treatment: its short code is the thing to copy, and
+ * the verification page is auto-opened too.
+ *
+ * One `AbortController` owns the whole run: pi-ai reads `interaction.signal`
+ * to abort the flow, every ask request carries it so surfaces close their
+ * panels, and the waiting panel's cancel action fires it.
+ *
+ * Nothing here assumes a browser or GUI *exists* (TUI-RUN-001): when no
+ * opener or clipboard helper is available the panel degrades to showing the
+ * URL / code verbatim with a clear note, and where no question provider is
+ * registered at all, `ask` rejects and the login command turns that into a
+ * clear refusal.
+ *
+ * @module dsh-auth/interaction
+ */
+import { copyToClipboard, openInBrowser } from './opener.js';
+/** Human-readable copy for one notify event. */
+export function describeEvent(event) {
+    switch (event.type) {
+        case 'auth_url':
+            return `Open this URL to authorize (a local callback completes sign-in):\n${event.url}`;
+        case 'device_code':
+            return `Visit ${event.verificationUri} and enter this code:\n  ${event.userCode}`;
+        case 'info':
+        case 'progress':
+            return event.message;
+    }
+}
+const CANCEL = 'Cancel sign-in';
+const OPEN_AGAIN = 'Open browser again';
+const COPY_LINK = 'Copy authorization link';
+const COPY_CODE = 'Copy code';
+/** One answer row, or a thrown error when the surface returned nothing usable. */
+function singleAnswer(answer) {
+    const row = answer.answers[0];
+    if (row === undefined)
+        throw new Error('dsh-auth: the question surface returned no answer');
+    return { selected: row.selected[0], custom: row.custom };
+}
+function authUrlView(url, instructions, opened) {
+    const lead = opened
+        ? 'Authorization page opened in your browser — complete the sign-in there.\n'
+            + 'If it did not open, copy the link below and open it by hand.'
+        : `Open this URL to authorize${instructions === undefined ? '' : ` — ${instructions}`}\n`
+            + 'Copy the link below (it is too long to select reliably once wrapped):';
+    return { body: `${lead}\n${url}`, copyLabel: COPY_LINK, copyText: url, reopenUrl: url };
+}
+function deviceCodeView(userCode, verificationUri, opened) {
+    const lead = opened
+        ? `Enter this code on the page opened in your browser (${verificationUri}):`
+        : `Visit ${verificationUri} and enter this code:`;
+    return { body: `${lead}\n  ${userCode}`, copyLabel: COPY_CODE, copyText: userCode, reopenUrl: verificationUri };
+}
+/**
+ * The bridge for one login run. At most one waiting panel exists at a time;
+ * `settle()` retires it when the flow ends (any outcome), so a completed or
+ * failed login never leaves an interactive dead end on screen.
+ */
+export class QuestionBridge {
+    ask;
+    runAbort;
+    signal;
+    openUrl;
+    copy;
+    waiting;
+    waitingClosed = false;
+    constructor(ask, runAbort, helpers = {}) {
+        this.ask = ask;
+        this.runAbort = runAbort;
+        this.signal = runAbort.signal;
+        this.openUrl = helpers.openUrl ?? openInBrowser;
+        this.copy = helpers.copyText ?? copyToClipboard;
+    }
+    async prompt(prompt) {
+        const secretNote = prompt.type === 'secret' ? ' (input is not masked on this surface — mind your screen)' : '';
+        const question = prompt.type === 'select'
+            ? {
+                id: 'dsh-auth-prompt',
+                header: 'dsh-auth',
+                question: prompt.message,
+                options: prompt.options.map(option => ({
+                    label: option.label,
+                    ...(option.description === undefined ? {} : { description: option.description }),
+                })),
+            }
+            : {
+                id: 'dsh-auth-prompt',
+                header: 'dsh-auth',
+                question: prompt.message,
+                ...(prompt.placeholder === undefined
+                    ? (secretNote === '' ? {} : { detail: secretNote.slice(1) })
+                    : { detail: `${prompt.placeholder}${secretNote}` }),
+            };
+        const answer = singleAnswer(await this.ask({ questions: [question], signal: prompt.signal ?? this.signal }));
+        if (prompt.type === 'select') {
+            const label = answer.selected;
+            const option = label === undefined ? undefined : prompt.options.find(candidate => candidate.label === label);
+            if (option === undefined) {
+                if (answer.custom !== undefined && answer.custom !== '')
+                    return answer.custom;
+                throw new Error('dsh-auth: the selection answer did not match an offered option');
+            }
+            return option.id;
+        }
+        const custom = answer.custom?.trim();
+        if (custom === undefined || custom === '')
+            throw new Error('dsh-auth: the text answer was empty');
+        return custom;
+    }
+    notify(event) {
+        if (event.type === 'auth_url') {
+            if (this.waiting !== undefined)
+                return;
+            const opened = this.openUrl(event.url);
+            void this.runWaitingPanel(authUrlView(event.url, event.instructions, opened));
+            return;
+        }
+        if (event.type === 'device_code') {
+            if (this.waiting !== undefined)
+                return;
+            const opened = this.openUrl(event.verificationUri);
+            void this.runWaitingPanel(deviceCodeView(event.userCode, event.verificationUri, opened));
+        }
+        // info / progress lines are transient; the waiting panel already tells
+        // the user what to do, and the flow's next prompt carries its own copy.
+    }
+    /** Close the waiting panel (if any) and stop answering for this run. */
+    async settle() {
+        this.waitingClosed = true;
+        this.waiting?.controller.abort();
+        await this.waiting?.answer;
+        this.waiting = undefined;
+    }
+    /**
+     * Show the waiting panel until the flow settles or the user cancels,
+     * re-asking after a copy/reopen action with a one-line status prefix.
+     */
+    async runWaitingPanel(view) {
+        let body = view.body;
+        while (!this.waitingClosed) {
+            const controller = new AbortController();
+            const answer = this.ask({
+                questions: [{
+                        id: 'dsh-auth-waiting',
+                        header: 'dsh-auth',
+                        question: 'Waiting for authorization…',
+                        detail: body,
+                        options: [
+                            { label: view.copyLabel },
+                            ...(view.reopenUrl === undefined ? [] : [{ label: OPEN_AGAIN }]),
+                            { label: CANCEL },
+                        ],
+                    }],
+                signal: controller.signal,
+            })
+                .then(response => singleAnswer(response).selected)
+                .catch(() => undefined);
+            this.waiting = { controller, answer };
+            const picked = await answer;
+            this.waiting = undefined;
+            if (picked === undefined || this.waitingClosed)
+                return;
+            if (picked === CANCEL) {
+                this.runAbort.abort('user cancelled sign-in');
+                return;
+            }
+            if (picked === view.copyLabel) {
+                const copied = await this.copy(view.copyText);
+                body = `${copied ? 'Copied — paste it where you need it.' : 'Copy failed — no clipboard helper answered; select the text manually.'}\n${view.body}`;
+                continue;
+            }
+            if (picked === OPEN_AGAIN && view.reopenUrl !== undefined) {
+                this.openUrl(view.reopenUrl);
+                body = `Reopened in your browser.\n${view.body}`;
+            }
+        }
+    }
+}

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/opener.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Best-effort host-side conveniences for OAuth flows: opening the default
+ * browser and copying short text to the clipboard.
+ *
+ * pi-ai's flows emit an `auth_url` event whose instructions assume the host
+ * opens the browser itself ("A browser window should open…"), because the
+ * authorize URL is hundreds of characters — unclickable and practically
+ * uncopyable once a terminal panel wraps it (wrap artifacts inside the
+ * encoded `redirect_uri` are exactly how hand-copied URLs die with
+ * `invalid_authorize_request`). These helpers restore that host contract.
+ * Every path is best-effort and never throws: a missing opener or clipboard
+ * degrades to the URL staying on screen with a copy action.
+ *
+ * @module dsh-auth/opener
+ */
+/** The browser-opening command for this platform, or undefined when unknown. */
+export declare function openerFor(url: string): {
+    command: string;
+    args: readonly string[];
+    verbatim: boolean;
+} | undefined;
+/**
+ * Open `url` in the default browser, detached; the TUI keeps running.
+ * @returns whether the opener process could be spawned at all (not whether
+ *   a browser eventually appeared — that is not observable here).
+ */
+export declare function openInBrowser(url: string): boolean;
+/**
+ * Copy `text` to the system clipboard, trying this platform's helpers in
+ * order. Resolves whether one succeeded; never rejects.
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/opener.js

@@ -0,0 +1,101 @@
+/**
+ * Best-effort host-side conveniences for OAuth flows: opening the default
+ * browser and copying short text to the clipboard.
+ *
+ * pi-ai's flows emit an `auth_url` event whose instructions assume the host
+ * opens the browser itself ("A browser window should open…"), because the
+ * authorize URL is hundreds of characters — unclickable and practically
+ * uncopyable once a terminal panel wraps it (wrap artifacts inside the
+ * encoded `redirect_uri` are exactly how hand-copied URLs die with
+ * `invalid_authorize_request`). These helpers restore that host contract.
+ * Every path is best-effort and never throws: a missing opener or clipboard
+ * degrades to the URL staying on screen with a copy action.
+ *
+ * @module dsh-auth/opener
+ */
+import { spawn } from 'node:child_process';
+/** The browser-opening command for this platform, or undefined when unknown. */
+export function openerFor(url) {
+    if (process.platform === 'win32') {
+        // cmd.exe parses `&` as a command separator, so an unquoted authorize
+        // URL (hundreds of chars of `?a=1&b=2…`) is truncated at the first `&`
+        // and the browser opens a param-less page — OpenAI answers "missing
+        // required parameter". Node only quotes argv containing spaces/quotes,
+        // which a URL has neither of, so the protection must be explicit: the
+        // whole `start` command rides as ONE verbatim argv token, with the URL
+        // double-quoted inside it (`start` treats a leading quoted arg as the
+        // window title, hence the empty "" first).
+        return {
+            command: 'cmd.exe',
+            args: ['/d', '/s', '/c', `start "" "${url}"`],
+            verbatim: true,
+        };
+    }
+    if (process.platform === 'darwin')
+        return { command: 'open', args: [url], verbatim: false };
+    return { command: 'xdg-open', args: [url], verbatim: false };
+}
+/**
+ * Open `url` in the default browser, detached; the TUI keeps running.
+ * @returns whether the opener process could be spawned at all (not whether
+ *   a browser eventually appeared — that is not observable here).
+ */
+export function openInBrowser(url) {
+    const opener = openerFor(url);
+    if (opener === undefined)
+        return false;
+    try {
+        const child = spawn(opener.command, [...opener.args], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+            ...(opener.verbatim ? { windowsVerbatimArguments: true } : {}),
+        });
+        child.on('error', () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Feed `text` to one clipboard helper's stdin; resolves whether it exited 0. */
+function pipeTo(command, args, text) {
+    return new Promise(resolve => {
+        let child;
+        try {
+            child = spawn(command, [...args], { stdio: ['pipe', 'ignore', 'ignore'], windowsHide: true });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        child.on('error', () => resolve(false));
+        child.on('close', code => resolve(code === 0));
+        child.stdin.on('error', () => resolve(false));
+        child.stdin.end(text);
+    });
+}
+/** Clipboard helper candidates per platform, in try order. */
+function clipboardCandidates() {
+    if (process.platform === 'win32')
+        return [{ command: 'clip.exe', args: [] }];
+    if (process.platform === 'darwin')
+        return [{ command: 'pbcopy', args: [] }];
+    return [
+        { command: 'wl-copy', args: [] },
+        { command: 'xclip', args: ['-selection', 'clipboard'] },
+        { command: 'xsel', args: ['--clipboard', '--input'] },
+    ];
+}
+/**
+ * Copy `text` to the system clipboard, trying this platform's helpers in
+ * order. Resolves whether one succeeded; never rejects.
+ */
+export async function copyToClipboard(text) {
+    for (const candidate of clipboardCandidates()) {
+        if (await pipeTo(candidate.command, candidate.args, text))
+            return true;
+    }
+    return false;
+}

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/profiles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Provider routes this plugin owns: the pi-ai catalog providers that ship an
+ * OAuth flow, mounted with their catalog models, wire implementations, and
+ * OAuth flow objects untouched. Credential resolution is not wrapped at all —
+ * the adapter's collection carries this plugin's `CredentialStore`
+ * (`PiAiAuthInjection`), so requests resolve the stored OAuth credential
+ * through the provider's own auth and refresh tokens under the store's lock.
+ *
+ * The hand-built profile mirrors what an empty llm-pi-ai settings profile
+ * resolves to for a catalog route, including the image-request defaults
+ * (llm-pi-ai's own `DEFAULT_*` constants are not exported; the values below
+ * are those constants, and the comment on each says so).
+ *
+ * @module dsh-auth/profiles
+ */
+import type { Provider } from '@earendil-works/pi-ai';
+import type { ResolvedPiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai';
+/** Provider routes this build mounts, in picker order. */
+export declare const OAUTH_PROVIDER_IDS: readonly ["openai-codex", "anthropic", "xai"];
+/** One routable provider id. */
+export type OAuthProviderId = (typeof OAUTH_PROVIDER_IDS)[number];
+/** The OAuth flow object for one mounted route (login/refresh/toAuth live here). */
+export declare function oauthOf(route: Provider): NonNullable<Provider['auth']['oauth']>;
+/**
+ * Build the resolved profile one route registers under. Mirrors the fields
+ * `PiAiAdapter` reads: identity for selectors, the idle timeout, retry
+ * policy, and image budgets it forwards per request, and the catalog provider
+ * with its own models. Everything optional stays absent — the adapter treats
+ * absence as "provider defaults" exactly as an empty llm-pi-ai profile would.
+ */
+export declare function buildOAuthProfile(id: string): ResolvedPiAiProviderProfile;

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/profiles.js

@@ -0,0 +1,68 @@
+/**
+ * Provider routes this plugin owns: the pi-ai catalog providers that ship an
+ * OAuth flow, mounted with their catalog models, wire implementations, and
+ * OAuth flow objects untouched. Credential resolution is not wrapped at all —
+ * the adapter's collection carries this plugin's `CredentialStore`
+ * (`PiAiAuthInjection`), so requests resolve the stored OAuth credential
+ * through the provider's own auth and refresh tokens under the store's lock.
+ *
+ * The hand-built profile mirrors what an empty llm-pi-ai settings profile
+ * resolves to for a catalog route, including the image-request defaults
+ * (llm-pi-ai's own `DEFAULT_*` constants are not exported; the values below
+ * are those constants, and the comment on each says so).
+ *
+ * @module dsh-auth/profiles
+ */
+import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
+import { resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
+/** Provider routes this build mounts, in picker order. */
+export const OAUTH_PROVIDER_IDS = ['openai-codex', 'anthropic', 'xai'];
+/** llm-pi-ai `DEFAULT_MAX_REQUEST_IMAGE_BYTES` (20 MiB, base64 payload bound). */
+const MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+/** llm-pi-ai `DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET` (2048×2048 pixels). */
+const REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048;
+/** llm-pi-ai `DEFAULT_REQUEST_IMAGE_MAX_BYTES` (1 MiB per image). */
+const REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
+/** llm-pi-ai `DEFAULT_STREAM_IDLE_TIMEOUT_MS` (5 minutes). */
+const STREAM_IDLE_TIMEOUT_MS = 300_000;
+/** The installed pi-ai catalog provider for one route, whose OAuth flow we mount. */
+function catalogProviderOf(id) {
+    const found = builtinProviders().find(provider => provider.id === id);
+    if (found === undefined) {
+        throw new Error(`dsh-auth: the installed pi-ai catalog ships no provider "${id}"; `
+            + 'remove it from this plugin\'s providers config or update pi-ai');
+    }
+    return found;
+}
+/** The OAuth flow object for one mounted route (login/refresh/toAuth live here). */
+export function oauthOf(route) {
+    const oauth = route.auth.oauth;
+    if (oauth === undefined) {
+        throw new Error(`dsh-auth: pi-ai provider "${route.id}" ships no OAuth flow`);
+    }
+    return oauth;
+}
+/**
+ * Build the resolved profile one route registers under. Mirrors the fields
+ * `PiAiAdapter` reads: identity for selectors, the idle timeout, retry
+ * policy, and image budgets it forwards per request, and the catalog provider
+ * with its own models. Everything optional stays absent — the adapter treats
+ * absence as "provider defaults" exactly as an empty llm-pi-ai profile would.
+ */
+export function buildOAuthProfile(id) {
+    if (!OAUTH_PROVIDER_IDS.includes(id)) {
+        throw new Error(`dsh-auth: "${id}" is not an OAuth provider this build mounts (${OAUTH_PROVIDER_IDS.join(', ')})`);
+    }
+    const catalog = catalogProviderOf(id);
+    return {
+        provider: id,
+        displayName: catalog.name,
+        streamIdleTimeoutMs: STREAM_IDLE_TIMEOUT_MS,
+        retryPolicy: resolveRetryPolicy(undefined, `dsh-auth: provider "${id}" retryPolicy`),
+        configuredMaxTokens: new Map(),
+        piProvider: catalog,
+        maxRequestImageBytes: MAX_REQUEST_IMAGE_BYTES,
+        requestImagePixelBudget: REQUEST_IMAGE_PIXEL_BUDGET,
+        requestImageMaxBytes: REQUEST_IMAGE_MAX_BYTES,
+    };
+}

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The `ctx.dshAuth` service: the programmatic surface over this plugin's
+ * mounted OAuth routes. UIs (the dsh-tui /provider wizard, a web settings
+ * page) enumerate providers with masked sign-in state and drive login/logout
+ * without touching the credential file or the pi-ai flow objects; the `/auth`
+ * command in `command.ts` is a thin textual veneer over the same api.
+ *
+ * @module dsh-auth/service
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedPiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai';
+import { CredentialFile } from './credentials.js';
+import { type AskFn } from './interaction.js';
+/** One provider's sign-in state; never carries token material. */
+export interface DshAuthSignInStatus {
+    provider: string;
+    /** Route display name (selectors, pickers). */
+    label: string;
+    /** The OAuth flow's own name, e.g. "OpenAI (ChatGPT Plus/Pro)". */
+    oauthLabel: string;
+    /** The flow's login-call-to-action label, when it ships one. */
+    loginLabel: string | undefined;
+    signedIn: boolean;
+    expiresAt: number | undefined;
+    /** Signed in, but the stored access token has expired (refresh may still work). */
+    expired: boolean;
+}
+/** The outcome of a successful login. */
+export interface DshAuthLoginResult {
+    provider: string;
+    oauthLabel: string;
+    expiresAt: number;
+}
+/** The service api consumed by commands and UIs. */
+export interface DshAuthApi {
+    /** Every mounted provider with masked sign-in state. */
+    providers(): Promise<readonly DshAuthSignInStatus[]>;
+    /**
+     * Run one provider's OAuth login. `provider` omitted asks the interactive
+     * surface to choose among providers not currently signed in.
+     * @throws Error when no interactive surface is present, the provider is
+     *   unknown, a login is already running, or the flow itself fails.
+     */
+    login(provider?: string, signal?: AbortSignal): Promise<DshAuthLoginResult>;
+    /** Remove one provider's stored credential; resolves whether one existed. */
+    logout(provider: string): Promise<boolean>;
+}
+/** Cordis service holder; `api` is set by the plugin's apply. */
+export declare class DshAuthService extends Service {
+    api: DshAuthApi | undefined;
+    constructor(ctx: Context);
+}
+/** Everything the api factory needs; all cordis surface is injected, so tests run without a host. */
+export interface DshAuthApiDeps {
+    profiles: ReadonlyMap<string, ResolvedPiAiProviderProfile>;
+    store: CredentialFile;
+    /** The interactive ask surface, resolved per call so mounting order never matters. */
+    resolveAsk: () => AskFn | undefined;
+    logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * The api implementation. One login runs per provider at a time (an in-flight
+ * map, not a global lock: providers sign in independently); a second login
+ * attempt for the same provider fails fast instead of stacking two flows.
+ */
+export declare function createDshAuthApi(deps: DshAuthApiDeps): DshAuthApi;

package/node_modules/@deepseek-harness-tui/dsh-auth/lib/service.js

@@ -0,0 +1,129 @@
+/**
+ * The `ctx.dshAuth` service: the programmatic surface over this plugin's
+ * mounted OAuth routes. UIs (the dsh-tui /provider wizard, a web settings
+ * page) enumerate providers with masked sign-in state and drive login/logout
+ * without touching the credential file or the pi-ai flow objects; the `/auth`
+ * command in `command.ts` is a thin textual veneer over the same api.
+ *
+ * @module dsh-auth/service
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { asStoredCredential } from './credentials.js';
+import { oauthOf } from './profiles.js';
+import { QuestionBridge } from './interaction.js';
+/** Cordis service holder; `api` is set by the plugin's apply. */
+export class DshAuthService extends Service {
+    api;
+    constructor(ctx) {
+        super(ctx, 'dshAuth');
+    }
+}
+/** Select a provider interactively among `candidates`. */
+async function chooseProvider(ask, candidates, signal) {
+    const answer = await ask({
+        questions: [{
+                id: 'dsh-auth-provider',
+                header: 'dsh-auth',
+                question: 'Sign in with which provider?',
+                options: candidates.map(row => ({ label: row.oauthLabel, description: row.provider })),
+            }],
+        signal,
+    });
+    const row = answer.answers[0];
+    const label = row?.selected[0];
+    const chosen = candidates.find(candidate => candidate.oauthLabel === label);
+    if (chosen === undefined)
+        throw new Error('dsh-auth: no provider was chosen');
+    return chosen.provider;
+}
+/**
+ * The api implementation. One login runs per provider at a time (an in-flight
+ * map, not a global lock: providers sign in independently); a second login
+ * attempt for the same provider fails fast instead of stacking two flows.
+ */
+export function createDshAuthApi(deps) {
+    const inflight = new Map();
+    const statusOf = async () => {
+        const described = new Map((await deps.store.describe()).map(row => [row.provider, row]));
+        return [...deps.profiles.entries()].map(([id, profile]) => {
+            const oauth = oauthOf(profile.piProvider);
+            const row = described.get(id);
+            return {
+                provider: id,
+                label: profile.displayName,
+                oauthLabel: oauth.name,
+                loginLabel: oauth.loginLabel,
+                signedIn: row !== undefined && !row.expired,
+                expiresAt: row?.expiresAt,
+                expired: row?.expired ?? false,
+            };
+        });
+    };
+    const loginOne = async (provider, ask, signal) => {
+        const profile = deps.profiles.get(provider);
+        if (profile === undefined) {
+            throw new Error(`dsh-auth: unknown provider "${provider}" (mounted: ${[...deps.profiles.keys()].join(', ')})`);
+        }
+        const oauth = oauthOf(profile.piProvider);
+        const runAbort = new AbortController();
+        if (signal !== undefined) {
+            if (signal.aborted)
+                runAbort.abort(signal.reason);
+            else
+                signal.addEventListener('abort', () => runAbort.abort(signal.reason), { once: true });
+        }
+        const bridge = new QuestionBridge(ask, runAbort);
+        try {
+            const returned = await oauth.login(bridge);
+            const normalized = asStoredCredential(returned);
+            if (normalized === undefined) {
+                throw new Error(`dsh-auth: the ${oauth.name} flow returned an unusable credential; nothing was stored`);
+            }
+            const stored = normalized;
+            await deps.store.modify(provider, async () => stored);
+            return { provider, oauthLabel: oauth.name, expiresAt: stored.expires };
+        }
+        finally {
+            await bridge.settle();
+        }
+    };
+    return {
+        providers: statusOf,
+        login: async (provider, signal) => {
+            const ask = deps.resolveAsk();
+            let target = provider;
+            if (target === undefined) {
+                if (ask === undefined) {
+                    throw new Error('dsh-auth: provider selection needs an interactive surface; name the provider: /auth login <provider>');
+                }
+                const statuses = await statusOf();
+                const candidates = statuses.filter(row => !row.signedIn);
+                if (candidates.length === 0)
+                    throw new Error('dsh-auth: every mounted provider is already signed in');
+                target = await chooseProvider(ask, candidates, signal);
+            }
+            else if (!deps.profiles.has(target)) {
+                throw new Error(`dsh-auth: unknown provider "${target}" (mounted: ${[...deps.profiles.keys()].join(', ')})`);
+            }
+            if (ask === undefined) {
+                throw new Error(`dsh-auth: signing in to "${target}" needs an interactive surface (run inside dsh-tui or the web client); `
+                    + 'this plugin refuses to assume a browser on this machine');
+            }
+            const existing = inflight.get(target);
+            if (existing !== undefined) {
+                throw new Error(`dsh-auth: a login for "${target}" is already running`);
+            }
+            const run = loginOne(target, ask, signal).finally(() => { inflight.delete(target); });
+            inflight.set(target, run);
+            return run;
+        },
+        logout: async (provider) => {
+            if (!deps.profiles.has(provider)) {
+                throw new Error(`dsh-auth: unknown provider "${provider}" (mounted: ${[...deps.profiles.keys()].join(', ')})`);
+            }
+            const existed = (await deps.store.read(provider)) !== undefined;
+            await deps.store.delete(provider);
+            return existed;
+        },
+    };
+}