@cortexkit/common-auth 0.2.5 → 0.2.6

package/dist/commands/menu.js

@@ -0,0 +1,249 @@
+// One slash command per plugin: the menu a plugin creates once and serves to
+// every invocation. It keeps no per-invocation state; each `open` and `apply`
+// builds its sections afresh from the store and gets its own copy of the
+// caller's context.
+import { createLogger } from '../logger/index.js';
+import { builtinSections, } from './builtins.js';
+import { applyResult, confirmationOf, dialogPayload, } from './seam.js';
+const BUILTIN_IDS = new Set([
+    'accounts',
+    'quota',
+    'routing',
+    'limits',
+    'cache',
+    'diagnostics',
+]);
+/**
+ * A private copy of the caller's context, taken before the first await. Work
+ * an invocation leaves running reports through this copy, so a host that
+ * reuses and rebinds one context object for the next session cannot pull an
+ * earlier invocation's feedback over to it.
+ */
+function ownInvocation(invocation) {
+    const { sessionId } = invocation;
+    const notify = invocation.notify.bind(invocation);
+    return Object.freeze({
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        notify,
+    });
+}
+function coerceOne(knob, raw) {
+    switch (knob.kind) {
+        case 'choice': {
+            const value = raw ?? knob.value;
+            if (typeof value === 'string' &&
+                knob.choices.some((choice) => choice.value === value))
+                return { value };
+            return { problem: `Choose one of the options for ${knob.label}.` };
+        }
+        case 'toggle': {
+            const value = raw ?? knob.value;
+            return typeof value === 'boolean'
+                ? { value }
+                : { problem: `${knob.label} must be on or off.` };
+        }
+        case 'number': {
+            const value = raw === undefined ? (knob.value ?? null) : raw;
+            if (value === null || value === '') {
+                return knob.required
+                    ? { problem: `${knob.label} needs a number.` }
+                    : { value: null };
+            }
+            const number = typeof value === 'number' ? value : Number(value);
+            if (typeof value === 'boolean' || !Number.isFinite(number))
+                return { problem: `${knob.label} needs a number.` };
+            if (knob.min !== undefined && number < knob.min)
+                return { problem: `${knob.label} must be at least ${knob.min}.` };
+            if (knob.max !== undefined && number > knob.max)
+                return { problem: `${knob.label} must be at most ${knob.max}.` };
+            return { value: number };
+        }
+        case 'text': {
+            const value = raw === undefined ? (knob.value ?? null) : raw;
+            if (value === null || value === '')
+                return knob.required
+                    ? { problem: `${knob.label} cannot be empty.` }
+                    : { value: null };
+            return typeof value === 'string'
+                ? { value }
+                : { problem: `${knob.label} must be text.` };
+        }
+    }
+}
+/** The action's inputs, checked against its knobs; unknown names are ignored. */
+function coerceValues(knobs, raw) {
+    const values = {};
+    for (const knob of knobs) {
+        const given = raw && Object.hasOwn(raw, knob.id) ? raw[knob.id] : undefined;
+        const result = coerceOne(knob, given);
+        if ('problem' in result)
+            return result;
+        values[knob.id] = result.value;
+    }
+    return { values };
+}
+function findAction(sections, request) {
+    const section = sections.find((entry) => entry.id === request.sectionId);
+    if (!section)
+        return undefined;
+    const actions = request.itemId === undefined
+        ? section.content.actions
+        : section.content.items?.find((item) => item.id === request.itemId)
+            ?.actions;
+    return actions?.find((action) => action.id === request.actionId);
+}
+export function createCommandMenu(options) {
+    const logger = options.logger ?? createLogger('commands');
+    const now = options.now ?? Date.now;
+    const extras = options.extras ?? [];
+    const seen = new Set();
+    for (const extra of extras) {
+        if (BUILTIN_IDS.has(extra.id) || seen.has(extra.id))
+            throw new Error(`extra section id ${extra.id} is taken`);
+        seen.add(extra.id);
+    }
+    async function plugin(id, slot, section, invocation) {
+        try {
+            return {
+                id,
+                slot,
+                title: section.title,
+                content: await section.build(invocation),
+            };
+        }
+        catch (error) {
+            // One broken plugin section must not take the whole menu down.
+            logger.warn('command menu section failed to build', {
+                command: options.command,
+                section: id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                id,
+                slot,
+                title: section.title,
+                content: { lines: ['This section could not be loaded.'] },
+            };
+        }
+    }
+    /** Every section, in the fixed slot order. */
+    async function sections(invocation) {
+        const out = await builtinSections({
+            store: options.store,
+            now,
+            ...(options.extraLocks ? { extraLocks: options.extraLocks } : {}),
+            ...(options.accounts ? { accounts: options.accounts } : {}),
+            ...(options.quota ? { quota: options.quota } : {}),
+            ...(options.routing ? { routing: options.routing } : {}),
+            ...(options.limits ? { limits: options.limits } : {}),
+        });
+        if (options.cache)
+            out.push(await plugin('cache', 'cache', options.cache, invocation));
+        if (options.diagnostics)
+            out.push(await plugin('diagnostics', 'diagnostics', options.diagnostics, invocation));
+        for (const extra of extras)
+            out.push(await plugin(extra.id, 'extra', extra, invocation));
+        return out;
+    }
+    return {
+        command: options.command,
+        async open(invocation) {
+            const own = ownInvocation(invocation);
+            return dialogPayload(options.command, options.title, await sections(own), logger);
+        },
+        async apply(request, invocation) {
+            const own = ownInvocation(invocation);
+            const finish = async (outcome) => applyResult(options.command, options.title, await sections(own), outcome, logger);
+            const action = request.command === options.command
+                ? findAction(await sections(own), request)
+                : undefined;
+            if (!action)
+                return finish({
+                    ok: false,
+                    text: 'That action is no longer available.',
+                });
+            const confirmation = confirmationOf(action);
+            if (confirmation && request.confirmed !== true)
+                return finish({
+                    ok: false,
+                    text: confirmation.message,
+                    needsConfirmation: true,
+                });
+            const coerced = coerceValues(action.knobs ?? [], request.values);
+            if ('problem' in coerced)
+                return finish({ ok: false, text: coerced.problem });
+            let outcome;
+            try {
+                const result = await action.run({
+                    values: coerced.values,
+                    ...(request.itemId !== undefined ? { itemId: request.itemId } : {}),
+                    invocation: own,
+                });
+                outcome =
+                    typeof result === 'string' ? { ok: true, text: result } : result;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.warn('command menu action failed', {
+                    command: options.command,
+                    section: request.sectionId,
+                    action: request.actionId,
+                    error: message,
+                });
+                outcome = { ok: false, text: message };
+            }
+            return finish(outcome);
+        },
+    };
+}
+function isKnobValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)));
+}
+/**
+ * Checks an apply request that arrived over the loopback RPC; undefined when
+ * it is not one. Only the request's own fields are kept.
+ */
+export function parseApplyRequest(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.command !== 'string' ||
+        typeof raw.sectionId !== 'string' ||
+        typeof raw.actionId !== 'string')
+        return undefined;
+    if (raw.itemId !== undefined && typeof raw.itemId !== 'string')
+        return undefined;
+    if (raw.sessionId !== undefined && typeof raw.sessionId !== 'string')
+        return undefined;
+    if (raw.confirmed !== undefined && typeof raw.confirmed !== 'boolean')
+        return undefined;
+    const values = {};
+    if (raw.values !== undefined) {
+        if (raw.values === null ||
+            typeof raw.values !== 'object' ||
+            Array.isArray(raw.values))
+            return undefined;
+        for (const [name, entry] of Object.entries(raw.values)) {
+            if (!isKnobValue(entry))
+                return undefined;
+            Object.defineProperty(values, name, {
+                value: entry,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    return {
+        command: raw.command,
+        sectionId: raw.sectionId,
+        actionId: raw.actionId,
+        ...(typeof raw.itemId === 'string' ? { itemId: raw.itemId } : {}),
+        ...(raw.values !== undefined ? { values } : {}),
+        ...(raw.confirmed === true ? { confirmed: true } : {}),
+        ...(typeof raw.sessionId === 'string' ? { sessionId: raw.sessionId } : {}),
+    };
+}

package/dist/commands/model.d.ts

@@ -0,0 +1,188 @@
+/** The section slots, in the one order every renderer shows them. */
+export declare const SECTION_SLOTS: readonly ['accounts', 'quota', 'routing', 'limits', 'cache', 'diagnostics', 'extra'];
+export type SectionSlot = (typeof SECTION_SLOTS)[number];
+/** One choice of a `choice` input. */
+export interface MenuChoice {
+    value: string;
+    label: string;
+}
+/**
+ * A typed input an action collects before it runs. `value` is the current
+ * setting, shown as the default. A `number` or `text` input that is not
+ * `required` may be left empty, which the action receives as `null`.
+ */
+export type MenuKnob = {
+    kind: 'choice';
+    id: string;
+    label: string;
+    choices: MenuChoice[];
+    value?: string;
+} | {
+    kind: 'toggle';
+    id: string;
+    label: string;
+    value: boolean;
+} | {
+    kind: 'number';
+    id: string;
+    label: string;
+    value?: number;
+    min?: number;
+    max?: number;
+    required?: boolean;
+} | {
+    kind: 'text';
+    id: string;
+    label: string;
+    value?: string;
+    placeholder?: string;
+    /** Hide what is typed (a pasted secret, for example). */
+    masked?: boolean;
+    required?: boolean;
+};
+export type KnobValue = string | number | boolean | null;
+export type KnobValues = Readonly<Record<string, KnobValue>>;
+export interface MenuConfirmation {
+    message: string;
+    /** Irreversible actions always carry a confirmation. */
+    irreversible: boolean;
+}
+export interface MenuAction {
+    id: string;
+    label: string;
+    description?: string;
+    knobs: MenuKnob[];
+    /** Present when the action must be confirmed before it is applied. */
+    confirm?: MenuConfirmation;
+}
+/**
+ * The account fields a renderer may show, and nothing else: an account is
+ * always projected field by field, never spread, so a credential the store
+ * row carries cannot reach a payload.
+ */
+export interface MenuAccount {
+    id: string;
+    label?: string;
+    enabled: boolean;
+    type: 'oauth' | 'api';
+    /** What the plugin chose to show for the account's identity. */
+    identity?: string;
+}
+export interface MenuItem {
+    id: string;
+    label: string;
+    detail?: string;
+    account?: MenuAccount;
+    /**
+     * Extra name/value pairs a drawer may list under the item. Plugin data
+     * passes through here, so it is scrubbed of credential-shaped names.
+     */
+    facts?: Record<string, unknown>;
+    actions: MenuAction[];
+}
+export interface MenuSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    /** Read-only lines shown above the items. */
+    lines: string[];
+    items: MenuItem[];
+    actions: MenuAction[];
+    facts?: Record<string, unknown>;
+}
+export interface CommandMenuModel {
+    /** The slash command's name, without the slash. */
+    command: string;
+    title: string;
+    sections: MenuSection[];
+}
+/** What a host's TUI receives when the slash command opens the dialog. */
+export interface CommandDialogPayload {
+    command: string;
+    menu: CommandMenuModel;
+}
+/**
+ * One applied action, as a renderer sends it back. `itemId` names the item
+ * the action sits on; absent for a section-level action.
+ */
+export interface CommandApplyRequest {
+    command: string;
+    sectionId: string;
+    itemId?: string;
+    actionId: string;
+    values?: KnobValues;
+    /** True once the user confirmed an action that carries a confirmation. */
+    confirmed?: boolean;
+    sessionId?: string;
+}
+/** The outcome of an apply: a message for the user and the refreshed menu. */
+export interface CommandApplyResult {
+    command: string;
+    ok: boolean;
+    text: string;
+    /** True when the action was refused only for want of a confirmation. */
+    needsConfirmation?: boolean;
+    menu: CommandMenuModel;
+}
+export type NotifyKind = 'info' | 'warning' | 'error';
+/**
+ * The per-invocation context of one slash-command call. The library reads
+ * both fields once, when the call starts, and keeps that copy for any work
+ * the call leaves running (a login completing later, for example), so a host
+ * that reuses one context object across sessions cannot reroute feedback.
+ */
+export interface CommandInvocation {
+    sessionId?: string;
+    notify(message: string, kind?: NotifyKind): void;
+}
+export interface ActionOutcome {
+    ok: boolean;
+    text: string;
+}
+export interface ActionInput {
+    values: KnobValues;
+    /** The item the action sits on; absent for a section-level action. */
+    itemId?: string;
+    invocation: CommandInvocation;
+}
+type ActionBase = {
+    id: string;
+    label: string;
+    description?: string;
+    knobs?: MenuKnob[];
+    run(input: ActionInput): Promise<string | ActionOutcome>;
+};
+/**
+ * An action and its body. An irreversible action must name its
+ * confirmation; a reversible one may.
+ */
+export type ActionDefinition = ActionBase & ({
+    irreversible: true;
+    confirm: string;
+} | {
+    irreversible?: false;
+    confirm?: string;
+});
+export interface ItemDefinition {
+    id: string;
+    label: string;
+    detail?: string;
+    facts?: Record<string, unknown>;
+    actions?: ActionDefinition[];
+}
+export interface SectionContent {
+    lines?: string[];
+    items?: ItemDefinition[];
+    actions?: ActionDefinition[];
+    facts?: Record<string, unknown>;
+}
+/** A section a plugin supplies for one of its slots. */
+export interface PluginSection {
+    title: string;
+    build(invocation: CommandInvocation): SectionContent | Promise<SectionContent>;
+}
+/** A provider extra: a plugin section shown after the fixed slots. */
+export interface PluginExtraSection extends PluginSection {
+    id: string;
+}
+export {};

package/dist/commands/model.js

@@ -0,0 +1,16 @@
+// The command menu: sections of items, each carrying actions with typed
+// inputs. Two kinds of type live here. The `Menu*` types and the request and
+// result types are plain data: they cross the loopback RPC to a host's TUI
+// and are what an in-process renderer walks. The `*Definition` types carry
+// the action bodies a plugin or the library supplies; they never leave the
+// process and are turned into the plain types only by the seam in `seam.ts`.
+/** The section slots, in the one order every renderer shows them. */
+export const SECTION_SLOTS = [
+    'accounts',
+    'quota',
+    'routing',
+    'limits',
+    'cache',
+    'diagnostics',
+    'extra',
+];

package/dist/commands/pi.d.ts

@@ -0,0 +1,22 @@
+import type { CommandMenu } from './menu.js';
+import type { NotifyKind } from './model.js';
+/**
+ * The part of Pi's `ExtensionUIContext` the renderer uses. `select` and
+ * `input` resolve undefined when the user backs out.
+ */
+export interface PiMenuUi {
+    select(title: string, options: string[]): Promise<string | undefined>;
+    confirm(title: string, message: string): Promise<boolean>;
+    input(title: string, placeholder?: string): Promise<string | undefined>;
+    notify(message: string, type?: NotifyKind): void;
+}
+export interface PiMenuOptions {
+    sessionId?: string;
+}
+/**
+ * Runs one invocation of the slash command on Pi: sections, then an item or
+ * a section action, then the action's inputs and confirmation; after each
+ * apply the user is back in the same section with the refreshed menu. Backing
+ * out of the section list ends the invocation.
+ */
+export declare function runPiCommandMenu(menu: CommandMenu, ui: PiMenuUi, options?: PiMenuOptions): Promise<void>;

package/dist/commands/pi.js

@@ -0,0 +1,178 @@
+// The Pi renderer: walks the same menu model the OpenCode dialog draws, with
+// Pi's extension UI (`select`, `confirm`, `input`, `notify`). It sees only the
+// payloads the menu's seam produces, and applies actions through the menu,
+// so the confirmation and input checks are the same as on OpenCode.
+/**
+ * Shows `entries` with `select` and returns the chosen value. Labels are made
+ * unique, since `select` answers with the label.
+ */
+async function pick(ui, title, entries) {
+    const byLabel = new Map();
+    const labels = [];
+    for (const entry of entries) {
+        let label = entry.label;
+        for (let n = 2; byLabel.has(label); n++)
+            label = `${entry.label} (${n})`;
+        byLabel.set(label, entry.value);
+        labels.push(label);
+    }
+    const chosen = await ui.select(title, labels);
+    return chosen === undefined ? undefined : byLabel.get(chosen);
+}
+function withLines(title, lines) {
+    return lines.length > 0 ? `${title}\n${lines.join('\n')}` : title;
+}
+function itemTitle(item) {
+    const lines = item.detail ? [item.detail] : [];
+    for (const [name, value] of Object.entries(item.facts ?? {}))
+        lines.push(`${name}: ${String(value)}`);
+    return withLines(item.label, lines);
+}
+/** One knob's value, or undefined when the user backed out or typed nonsense. */
+async function askKnob(ui, knob) {
+    switch (knob.kind) {
+        case 'choice': {
+            const value = await pick(ui, knob.label, knob.choices.map((choice) => ({
+                label: choice.value === knob.value
+                    ? `${choice.label} (current)`
+                    : choice.label,
+                value: choice.value,
+            })));
+            return value === undefined ? undefined : { value };
+        }
+        case 'toggle': {
+            const value = await pick(ui, knob.label, [
+                { label: knob.value ? 'On (current)' : 'On', value: true },
+                { label: knob.value ? 'Off' : 'Off (current)', value: false },
+            ]);
+            return value === undefined ? undefined : { value };
+        }
+        case 'number': {
+            const range = knob.min !== undefined && knob.max !== undefined
+                ? ` (${knob.min}-${knob.max}${knob.required ? '' : ', empty clears'})`
+                : knob.required
+                    ? ''
+                    : ' (empty clears)';
+            const typed = await ui.input(`${knob.label}${range}`, knob.value !== undefined ? String(knob.value) : undefined);
+            if (typed === undefined)
+                return undefined;
+            const text = typed.trim();
+            if (text === '')
+                return knob.required && knob.value !== undefined
+                    ? { value: knob.value }
+                    : { value: null };
+            const number = Number(text);
+            if (!Number.isFinite(number)) {
+                ui.notify(`${knob.label} needs a number.`, 'error');
+                return undefined;
+            }
+            return { value: number };
+        }
+        case 'text': {
+            const typed = await ui.input(knob.label, knob.value ?? knob.placeholder);
+            if (typed === undefined)
+                return undefined;
+            const text = typed.trim();
+            if (text === '')
+                return knob.required && knob.value !== undefined
+                    ? { value: knob.value }
+                    : { value: null };
+            return { value: text };
+        }
+    }
+}
+async function askValues(ui, action) {
+    const values = {};
+    for (const knob of action.knobs) {
+        const answer = await askKnob(ui, knob);
+        if (!answer)
+            return undefined;
+        values[knob.id] = answer.value;
+    }
+    return values;
+}
+/**
+ * Runs one invocation of the slash command on Pi: sections, then an item or
+ * a section action, then the action's inputs and confirmation; after each
+ * apply the user is back in the same section with the refreshed menu. Backing
+ * out of the section list ends the invocation.
+ */
+export async function runPiCommandMenu(menu, ui, options = {}) {
+    const invocation = {
+        ...(options.sessionId !== undefined
+            ? { sessionId: options.sessionId }
+            : {}),
+        notify: (message, kind) => ui.notify(message, kind),
+    };
+    let model = (await menu.open(invocation)).menu;
+    for (;;) {
+        const chosen = await pick(ui, model.title, model.sections.map((section) => ({
+            label: section.lines[0]
+                ? `${section.title}: ${section.lines[0]}`
+                : section.title,
+            value: section.id,
+        })));
+        if (chosen === undefined)
+            return;
+        for (;;) {
+            const section = model.sections.find((entry) => entry.id === chosen);
+            if (!section)
+                break;
+            const entries = [
+                ...section.items.map((item) => ({
+                    label: item.detail ? `${item.label}: ${item.detail}` : item.label,
+                    value: { kind: 'item', item },
+                })),
+                ...section.actions.map((action) => ({
+                    label: action.label,
+                    value: { kind: 'action', action },
+                })),
+            ];
+            if (entries.length === 0) {
+                ui.notify(section.lines.join('\n') || 'Nothing to do here.');
+                break;
+            }
+            const choice = await pick(ui, withLines(section.title, section.lines), entries);
+            if (!choice)
+                break;
+            let action;
+            let item;
+            if (choice.kind === 'item') {
+                item = choice.item;
+                if (item.actions.length === 0) {
+                    ui.notify(itemTitle(item));
+                    continue;
+                }
+                action = await pick(ui, itemTitle(item), item.actions.map((entry) => ({ label: entry.label, value: entry })));
+                if (!action)
+                    continue;
+            }
+            else {
+                action = choice.action;
+            }
+            const values = await askValues(ui, action);
+            if (!values)
+                continue;
+            if (action.confirm) {
+                const yes = await ui.confirm(action.label, action.confirm.message);
+                if (!yes) {
+                    ui.notify('Cancelled.');
+                    continue;
+                }
+            }
+            const result = await menu.apply({
+                command: model.command,
+                sectionId: section.id,
+                ...(item ? { itemId: item.id } : {}),
+                actionId: action.id,
+                values,
+                ...(action.confirm ? { confirmed: true } : {}),
+                ...(options.sessionId !== undefined
+                    ? { sessionId: options.sessionId }
+                    : {}),
+            }, invocation);
+            ui.notify(result.text, result.ok ? 'info' : 'error');
+            model = result.menu;
+        }
+    }
+}

package/dist/commands/seam.d.ts

@@ -0,0 +1,36 @@
+import type { ActionDefinition, CommandApplyResult, CommandDialogPayload, ItemDefinition, MenuAccount, MenuConfirmation, SectionContent, SectionSlot } from './model.js';
+/** Where a dropped field is reported. Names only, never values. */
+export interface SeamLogger {
+    warn(message: string, data?: unknown): void;
+}
+/** A built-in item may carry the account it shows; plugin items cannot. */
+export interface ResolvedItem extends ItemDefinition {
+    account?: MenuAccount;
+}
+/** A section with its bodies, as the menu holds it between builds. */
+export interface ResolvedSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    content: Omit<SectionContent, 'items'> & {
+        items?: ResolvedItem[];
+    };
+}
+/** The confirmation shown when an irreversible action names none. */
+export declare const DEFAULT_IRREVERSIBLE_CONFIRMATION = "This cannot be undone. Continue?";
+/**
+ * The confirmation an action must pass before it runs, or undefined. An
+ * irreversible action always has one, even when its definition (built
+ * outside the type checker) names none.
+ */
+export declare function confirmationOf(action: ActionDefinition): MenuConfirmation | undefined;
+/** The account fields a renderer may show; see `MenuAccount`. */
+export declare function projectAccount(account: MenuAccount): MenuAccount;
+/** The payload a host's TUI receives when the slash command opens. */
+export declare function dialogPayload(command: string, title: string, sections: readonly ResolvedSection[], logger: SeamLogger): CommandDialogPayload;
+/** An apply's result: the message and the refreshed menu. */
+export declare function applyResult(command: string, title: string, sections: readonly ResolvedSection[], outcome: {
+    ok: boolean;
+    text: string;
+    needsConfirmation?: boolean;
+}, logger: SeamLogger): CommandApplyResult;