@cortexkit/antigravity-auth-core 2.2.1 → 3.0.1

package/dist/common-auth-embedded/commands/menu.js

@@ -0,0 +1,300 @@
+// 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, createTextRedactor, dialogPayload, projectFailure, } from './seam.js';
+const BUILTIN_IDS = new Set([
+    'accounts',
+    'quota',
+    'routing',
+    'limits',
+    'cache',
+    'diagnostics',
+]);
+const STORE_SLOTS = [
+    'accounts',
+    'quota',
+    'routing',
+    'limits',
+];
+/**
+ * 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, redact) {
+    const { sessionId } = invocation;
+    const notify = invocation.notify.bind(invocation);
+    // A notification leaves the process just as a payload does, so its text
+    // goes through the same redactor.
+    return Object.freeze({
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        notify: (message, kind) => kind === undefined
+            ? notify(redact(String(message)))
+            : notify(redact(String(message)), kind),
+    });
+}
+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 redact = createTextRedactor(options.redaction);
+    const seam = { logger, redact };
+    const now = options.now ?? Date.now;
+    const extras = options.extras ?? [];
+    const replaced = options.replace ?? {};
+    const builtSlots = STORE_SLOTS.filter((slot) => !replaced[slot]);
+    for (const slot of STORE_SLOTS) {
+        if (replaced[slot] && options[slot] !== undefined)
+            throw new Error(`the ${slot} section is replaced; its built-in options cannot also be given`);
+    }
+    const store = options.store;
+    if (builtSlots.length > 0 && !store)
+        throw new Error(`a store is required for the built-in ${builtSlots.join(', ')} section${builtSlots.length > 1 ? 's' : ''}`);
+    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: redact(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) {
+        // Built-in sections read the store once; a fully replaced menu never
+        // touches it.
+        const built = store && builtSlots.length > 0
+            ? await builtinSections({
+                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 } : {}),
+            })
+            : [];
+        const out = [];
+        for (const slot of STORE_SLOTS) {
+            const replacement = replaced[slot];
+            if (replacement)
+                out.push(await plugin(slot, slot, replacement, invocation));
+            else {
+                const section = built.find((entry) => entry.slot === slot);
+                if (section)
+                    out.push(section);
+            }
+        }
+        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, redact);
+            return dialogPayload(options.command, options.title, await sections(own), seam);
+        },
+        async apply(request, invocation) {
+            const own = ownInvocation(invocation, redact);
+            const finish = async (outcome) => applyResult(options.command, options.title, await sections(own), outcome, seam);
+            const action = request.command === options.command
+                ? findAction(await sections(own), request)
+                : undefined;
+            if (!action)
+                return finish({
+                    ok: false,
+                    code: 'unavailable',
+                    text: 'That action is no longer available.',
+                });
+            const confirmation = confirmationOf(action);
+            if (confirmation && request.confirmed !== true)
+                return finish({
+                    ok: false,
+                    code: 'needs-confirmation',
+                    text: confirmation.message,
+                    needsConfirmation: true,
+                });
+            const coerced = coerceValues(action.knobs ?? [], request.values);
+            if ('problem' in coerced)
+                return finish({
+                    ok: false,
+                    code: 'invalid-input',
+                    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 }
+                        : {
+                            ok: result.ok,
+                            text: result.text,
+                            ...(result.ok ? {} : { code: result.code ?? 'refused' }),
+                        };
+            }
+            catch (error) {
+                // The raw text goes only to the log (redacted); the user sees the
+                // projected code and message, never the exception's own words.
+                const failure = projectFailure(error);
+                logger.warn('command menu action failed', {
+                    command: options.command,
+                    section: request.sectionId,
+                    action: request.actionId,
+                    code: failure.code,
+                    error: redact(error instanceof Error ? error.message : String(error)),
+                });
+                outcome = { ok: false, ...failure };
+            }
+            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/common-auth-embedded/commands/model.d.ts

@@ -0,0 +1,238 @@
+/** 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;
+    /**
+     * The header a section-level action is listed under (`Actions`). See
+     * `MenuSection` for how renderers draw groups.
+     */
+    group?: 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;
+    /** The header the item is listed under (`Accounts`); see `MenuSection`. */
+    group?: string;
+    /**
+     * A short value shown right-aligned beside the label (`enabled`,
+     * `5h 58% left`): an OpenCode dialog option's `footer`.
+     */
+    status?: 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[];
+}
+/**
+ * One section of the menu. How every renderer draws it:
+ *
+ * - Every option a renderer shows can be selected and does something: it is
+ *   an item with at least one action, or a section-level action. Text that
+ *   does nothing is never an option; it is a group header or a line.
+ * - `lines` are read-only text. On OpenCode they are drawn as header text
+ *   (a `category`) above the first group; on Pi they are part of the select
+ *   title.
+ * - The options are the items, then the section-level actions, in that
+ *   order. When an option's `group` differs from the previous one's, a
+ *   header naming the group is drawn first. A header is never selectable
+ *   (on OpenCode it is the option's `category`).
+ * - An item's `status` is drawn right-aligned beside its label (on
+ *   OpenCode, `footer`); its `detail` and an action's `description` are
+ *   the secondary text (`description`).
+ *
+ * The built-in sections never emit an item without actions, and a plugin
+ * section should not either. A renderer that meets one must not offer it as
+ * an option: on OpenCode a `disabled` option is hidden altogether, so the
+ * item is written as header text instead, and Pi writes it into the title.
+ */
+export interface MenuSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    /** Read-only text shown above the rows; never a selectable option. */
+    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;
+    /**
+     * A stable code naming why the apply failed; present on every failure.
+     * The library's own codes are `unavailable`, `needs-confirmation`,
+     * `invalid-input`, `refused`, `action-failed` and `pool-<store failure
+     * kind>`; a plugin's `CommandError` or `ActionOutcome` names its own.
+     */
+    code?: 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;
+    /** The failure's stable code; a failure without one is `refused`. */
+    code?: 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;
+    /** The header a section-level action is listed under; see `MenuSection`. */
+    group?: 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;
+    /** The header the item is listed under; see `MenuSection`. */
+    group?: string;
+    /** A short value shown right-aligned beside the label. */
+    status?: string;
+    facts?: Record<string, unknown>;
+    actions?: ActionDefinition[];
+}
+export interface SectionContent {
+    /** Read-only text; renderers never make a line selectable. */
+    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/common-auth-embedded/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/common-auth-embedded/commands/pi.d.ts

@@ -0,0 +1,23 @@
+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. Each
+ * section's list ends with Back, which returns to the section list; backing
+ * out of the section list ends the invocation.
+ */
+export declare function runPiCommandMenu(menu: CommandMenu, ui: PiMenuUi, options?: PiMenuOptions): Promise<void>;