indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/types/launch/credentials.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Credential command — `runCredentialCommand`.
+ *
+ * The top-level `signin` / `signout` surface. Sign-in supports two methods: a
+ * browser sign-in (OAuth) for the providers the framework registry exposes, and
+ * an api-key flow for every provider in the directory. When a provider is
+ * sign-in-capable the command prefers the browser flow but still lets the user
+ * pick an api key; for the rest it stores a key directly. The env-var override is
+ * consulted first via the framework {@link getEnvApiKey}, so a user who already
+ * exported (e.g.) `ANTHROPIC_API_KEY` can sign in without re-typing the secret.
+ *
+ * The command owns the first positional token only: it returns `handled: false`
+ * when that token is neither {@link CredentialVerb} so the caller falls through
+ * to a normal launch. Every failure is a typed {@link CredentialFault}; nothing
+ * is signalled by a string sentinel or a bare `process.exit`.
+ *
+ * I/O is injected. The default {@link CredentialIo} wraps `process.stdout` plus a
+ * `node:readline/promises` interface, but tests drive the whole flow over an
+ * in-memory stand-in with no real terminal and an in-memory vault.
+ */
+import { type CredentialCommandOptions, type CredentialFault, type CredentialVerb, type ProviderEntry } from "./contract";
+/**
+ * The console seam the credential command reads and writes through.
+ *
+ * Pinned to the three operations the flow actually needs — emit a line, read a
+ * line of input, and read a secret line — so a test can capture output into an
+ * array and feed scripted answers without a real TTY.
+ */
+export interface CredentialIo {
+    /** Emit one line of human-facing text. */
+    print(line: string): void;
+    /** Prompt for and read one line of visible input. */
+    ask(prompt: string): Promise<string>;
+    /** Prompt for and read one line of secret input (key entry). */
+    askSecret(prompt: string): Promise<string>;
+}
+/**
+ * The default {@link CredentialIo} backed by `process.stdout` and a
+ * `node:readline/promises` interface. Secret entry mutes echo while the line is
+ * typed by suppressing the terminal write of each keystroke.
+ */
+export declare function defaultCredentialIo(): CredentialIo;
+/**
+ * The api-key provider directory: every provider the sign-in surface can store a
+ * key for, with its conventional env var and the page a user obtains a key from.
+ * These are external provider facts; {@link envKey} is the variable
+ * {@link getEnvApiKey} reads for the env-first shortcut.
+ */
+export declare const PROVIDER_DIRECTORY: readonly ProviderEntry[];
+/** Look up a provider entry by id (case-insensitive over the directory). */
+export declare function findProvider(id: string): ProviderEntry | undefined;
+/**
+ * The two ways a provider can be signed in to.
+ *
+ *   - `oauth`   — a browser sign-in driven by the framework registry.
+ *   - `api-key` — paste / store a provider api key.
+ */
+export type SigninMethod = "oauth" | "api-key";
+/** Narrow a `--method` value to a {@link SigninMethod}. */
+export declare function asSigninMethod(value: string | undefined): SigninMethod | undefined;
+/** Whether a provider id can be signed in to through the browser registry. */
+export declare function isOAuthCapable(id: string): boolean;
+/**
+ * Validate an api key against the format rules: non-empty, at least
+ * {@link MIN_KEY_LENGTH} characters, and free of placeholder markers. Returns a
+ * typed {@link CredentialFault} on rejection, or `undefined` when the key passes.
+ */
+export declare function validateApiKey(key: string): CredentialFault | undefined;
+/**
+ * Validate an account name: at most {@link MAX_ACCOUNT_LENGTH} characters and
+ * matching {@link ACCOUNT_PATTERN}. Returns a typed fault on rejection, or
+ * `undefined` when the name is acceptable.
+ */
+export declare function validateAccountName(name: string): CredentialFault | undefined;
+/**
+ * The outcome of {@link runCredentialCommand}.
+ *
+ * {@link handled} reports whether the first positional token was a recognised
+ * {@link CredentialVerb}; when `false`, the caller proceeds to a normal launch
+ * unchanged. {@link fault} carries a typed failure when the command was handled
+ * but did not complete.
+ */
+export interface CredentialResult {
+    /** Whether this invocation was a `signin` / `signout` command. */
+    readonly handled: boolean;
+    /** The verb that ran, when {@link handled} is true. */
+    readonly verb?: CredentialVerb;
+    /** The provider id the verb acted on, when one was resolved. */
+    readonly provider?: string;
+    /** A typed failure, present only when the handled command did not complete. */
+    readonly fault?: CredentialFault;
+}
+/**
+ * Run the api-key sign-in / sign-out command.
+ *
+ * Returns `{ handled: false }` immediately when `argv[0]` is neither verb, so the
+ * orchestrator can call this first and fall through on a miss. Otherwise it
+ * resolves the provider (prompting from the directory when none is named), runs
+ * the verb, and resolves a {@link CredentialResult} — never throwing for an
+ * expected failure, which surfaces as {@link CredentialResult.fault}.
+ *
+ * @param argv the raw token list following the program name
+ * @param opts the injected vault, profile directory, and (optionally) the io seam
+ */
+export declare function runCredentialCommand(argv: readonly string[], opts: CredentialCommandOptions & {
+    io?: CredentialIo;
+}): Promise<CredentialResult>;
+/**
+ * Render a {@link CredentialFault} as the single human-facing message the caller
+ * prints before exiting non-zero. Pure; no I/O.
+ */
+export declare function formatCredentialFault(fault: CredentialFault): string;

package/dist/types/launch/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Launch subsystem — public barrel.
+ *
+ * Re-exports the frozen Phase-10 contract surface: the parsed
+ * {@link Invocation} and its {@link OutputMode} / {@link ThinkingEffort} /
+ * {@link ToolName} vocabularies, the declarative {@link FlagSpec} table types,
+ * the gathered {@link Attachments} shape, the typed {@link CredentialFault}
+ * union and its {@link AuthVault} seam, the model-catalog filter, and the resume
+ * / settings-browser option shapes. Behavior modules (the reader, the usage
+ * renderer, the credential command, the attachment gatherer, the catalog
+ * printer, the resume picker, the settings browser) attach their exports here as
+ * they land, so consumers import the launch surface from `src/launch` rather
+ * than reaching into individual modules.
+ */
+export type { OutputMode, ThinkingEffort, ToolName, FlagKind, FlagDefault, FlagSpec, Invocation, FlagValue, Attachments, AttachmentOptions, CredentialVerb, ProviderEntry, CredentialFaultKind, CredentialFault, AuthVault, CredentialCommandOptions, CatalogFilter, SessionLoader, ResumeFault, SettingsBrowseOptions, ResumeRef, ThinkingLevel, SessionListProgress, ImageContent, KnownProvider, ModelRegistry, OAuthCredentials, Settings, RunnerId, } from "./contract";
+export { THINKING_EFFORTS, TOOL_NAMES, isThinkingEffort, isOutputMode, isToolName, credentialFault, } from "./contract";
+export { FLAG_SPECS, FLAG_GROUPS, readInvocation, readFileReferences, renderUsage, gatherAttachments, AttachmentError, } from "./invocation";
+export type { FlagGroup, GroupedFlagSpec, AttachmentErrorKind, } from "./invocation";
+export { runPackageCommand, defaultPackageIo, PACKAGE_COMMANDS, } from "./packages";
+export type { PackageCommand, PackageIo, PackageCommandOptions, PackageResult, } from "./packages";
+export { runCredentialCommand, defaultCredentialIo, formatCredentialFault, validateApiKey, validateAccountName, findProvider, isOAuthCapable, asSigninMethod, PROVIDER_DIRECTORY, } from "./credentials";
+export type { CredentialIo, CredentialResult, SigninMethod } from "./credentials";
+export { registerBuiltInOAuthProviders, listLoginProviders, startOAuthLogin, openLoginUrl, } from "./oauth";
+export type { AuthKind, LoginProvider, OAuthLoginResult, } from "./oauth";
+export { printModelCatalog, defaultCatalogIo, registrySource } from "./catalog";
+export type { CatalogIo, CatalogModelSource } from "./catalog";
+export { pickResumeTarget, browseSettings, mergeSessions, renderSettingsListing, defaultResumeDeps, defaultSettingsBrowseIo, } from "./pickers";
+export type { ResumeDeps, ResumeOutcome, SettingsBrowseIo, } from "./pickers";

package/dist/types/launch/invocation/attachments.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The attachment gatherer — expands `@file` references into one
+ * {@link Attachments} value.
+ *
+ * Each `@file` token collected by the reader is resolved through the framework
+ * path resolver ({@link resolveReadPath}, which handles `~` expansion and the
+ * cwd), classified by extension, and folded into the result:
+ *
+ *   - **text files** are read as UTF-8 and inlined into {@link Attachments.prose}
+ *     wrapped in a delimited block keyed by the resolved path, so the model sees
+ *     which file each block came from;
+ *   - **image files** are read as bytes, base64-encoded, and collected as
+ *     framework {@link ImageContent} in {@link Attachments.media}.
+ *
+ * Guard rails:
+ *   - an unknown extension, an oversized file, a missing file, or a read error
+ *     raises a typed {@link AttachmentError} (with a {@link AttachmentErrorKind}
+ *     discriminant) rather than a string or a process exit;
+ *   - size caps bound the inlined text and the decoded image before either is
+ *     materialised onto the message;
+ *   - an empty file is skipped silently — it contributes neither prose nor media.
+ *
+ * The `@file` syntax, the extension classification, and base64 image attachment
+ * are kept behaviours; only the typed-error model and the explicit caps are
+ * owned here.
+ */
+import type { Attachments, AttachmentOptions } from "../contract";
+/**
+ * The closed set of attachment failure categories. A consumer switches on
+ * {@link AttachmentError.kind}, never on message text:
+ *
+ *   - `unsupported`  — the file extension is neither text nor image.
+ *   - `too-large`    — the file exceeds its kind's size cap.
+ *   - `not-found`    — the resolved path does not exist.
+ *   - `read-failed`  — the file could not be read or stat-ed.
+ */
+export type AttachmentErrorKind = "unsupported" | "too-large" | "not-found" | "read-failed";
+/**
+ * A typed `@file` expansion failure. Carries the offending reference and the
+ * resolved path for diagnostics; {@link cause} preserves any wrapped error.
+ */
+export declare class AttachmentError extends Error {
+    /** The failure category (the discriminant). */
+    readonly kind: AttachmentErrorKind;
+    /** The raw `@file` reference as supplied on the command line. */
+    readonly reference: string;
+    /** The resolved absolute path, when resolution succeeded. */
+    readonly resolvedPath?: string;
+    /** The wrapped underlying error, if any. */
+    readonly cause?: unknown;
+    constructor(kind: AttachmentErrorKind, message: string, detail: {
+        reference: string;
+        resolvedPath?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Expand the `@file` references into a single {@link Attachments} value.
+ *
+ * Resolves each reference against {@link AttachmentOptions.cwd} via the framework
+ * resolver, classifies it by extension, enforces the per-kind size cap, and
+ * appends either a text block to the prose or an {@link ImageContent} to the
+ * media. References list is taken in order; the prose blocks are joined with a
+ * blank line between them. An empty references list yields an empty
+ * {@link Attachments} (the caller decides whether to attach it at all).
+ *
+ * @param references the raw `@file` paths (without the leading `@`)
+ * @param options    the cwd the references resolve against
+ * @throws AttachmentError on an unsupported extension, an oversized file, a
+ *         missing file, or a read failure
+ */
+export declare function gatherAttachments(references: readonly string[], options: AttachmentOptions): Promise<Attachments>;

package/dist/types/launch/invocation/flags.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The single declarative flag table.
+ *
+ * Every recognised command-line option is described here exactly once, as one
+ * {@link FlagSpec} row. Two consumers walk this same table:
+ *
+ *   - the reader ({@link readInvocation}) indexes it by canonical name and alias
+ *     to bind raw tokens into the parsed {@link Invocation}; and
+ *   - the usage generator ({@link renderUsage}) enumerates it to render the
+ *     option reference — there is no second, hand-maintained help string for it
+ *     to drift against.
+ *
+ * Because both sides read the same rows, the help text and the parser cannot
+ * disagree about which flags exist, what they take, or what they mean. The order
+ * of the rows is the order options appear in the generated usage, grouped by the
+ * {@link FlagGroup} sidecar map below; keeping that order intentional is the only
+ * editorial concern when a row is added.
+ *
+ * Flag names and their semantics are a stable product contract (and largely an
+ * industry convention), so they are kept as-is; only the table that declares
+ * them and the code that reads it are owned here.
+ */
+import type { FlagSpec } from "../contract";
+/**
+ * The heading a flag is filed under in the generated usage. Purely an editorial
+ * grouping for {@link renderUsage}; it has no effect on parsing.
+ */
+export type FlagGroup = "output" | "model" | "context" | "tools" | "meta";
+/**
+ * A {@link FlagSpec} carrying its usage section. The extra {@link group} field is
+ * inert at parse time; the reader ignores it and only the renderer reads it.
+ */
+export interface GroupedFlagSpec extends FlagSpec {
+    /** The usage section this row is rendered under. */
+    readonly group: FlagGroup;
+}
+/**
+ * Human-readable titles for each {@link FlagGroup}, in render order. The usage
+ * generator walks this list, then within each group emits the matching rows from
+ * {@link FLAG_SPECS} in declaration order.
+ */
+export declare const FLAG_GROUPS: readonly {
+    readonly id: FlagGroup;
+    readonly title: string;
+}[];
+/**
+ * The one declarative option table. Every recognised flag is one row; the reader
+ * and the usage generator both index this and nothing else.
+ *
+ * Conventions:
+ *   - {@link FlagSpec.name} is the canonical long spelling (leading dashes
+ *     included) and also the key the parsed value lands under in
+ *     {@link Invocation.flags} (sans the dashes).
+ *   - {@link FlagSpec.aliases} hold short forms and synonyms; every alias hit
+ *     normalises to {@link FlagSpec.name}.
+ *   - {@link FlagSpec.kind} fixes the value vocabulary: `boolean` switches,
+ *     `string` / `number` value flags, and accumulating `list` flags.
+ */
+export declare const FLAG_SPECS: readonly GroupedFlagSpec[];

package/dist/types/launch/invocation/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Invocation subsystem — public barrel.
+ *
+ * Bundles the command-line behavior modules that all read the single
+ * declarative {@link FLAG_SPECS} table:
+ *
+ *   - {@link readInvocation} — the generic, table-driven argv parser that folds
+ *     a sliced argument vector into a typed {@link Invocation};
+ *   - {@link renderUsage} — the `--help` banner generated from that same table,
+ *     so help and parsing share one source of truth;
+ *   - {@link gatherAttachments} — the `@file` expander that resolves references
+ *     through the framework path resolver into inlined prose plus base64 media,
+ *     raising a typed {@link AttachmentError} on failure.
+ *
+ * Consumers import the invocation surface from `src/launch/invocation` rather
+ * than reaching into the individual modules.
+ */
+export { FLAG_SPECS, FLAG_GROUPS } from "./flags";
+export type { FlagGroup, GroupedFlagSpec } from "./flags";
+export { readInvocation, readFileReferences } from "./read";
+export { renderUsage } from "./usage";
+export { gatherAttachments, AttachmentError } from "./attachments";
+export type { AttachmentErrorKind } from "./attachments";

package/dist/types/launch/invocation/read.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The invocation reader — a generic, table-driven argv parser over
+ * {@link FLAG_SPECS}.
+ *
+ * This is the application's full command-line grammar (the boot layer carries
+ * only a thin routing parser). It walks a sliced `argv` once and folds every
+ * token into a fully-typed {@link Invocation}: recognised flags bind through the
+ * declarative {@link FlagSpec} table, `@file` references collect for the
+ * attachment gatherer, and remaining positionals become the prompt and the
+ * positional tail.
+ *
+ * The grammar is deliberately textbook and entirely data-driven — there is no
+ * per-flag branch. One index over {@link FLAG_SPECS} maps every canonical name
+ * and alias to its row; the loop applies whichever row a token resolves to:
+ *
+ *   - **`--name=value`** and **`--name value`** both bind a `string` / `number`
+ *     / `list` flag; an inline `=value` wins, otherwise the following token is
+ *     consumed (unless it is itself a flag, in which case the value is empty).
+ *   - **longest-alias match** resolves the canonical name, so a longer spelling
+ *     is never shadowed by a shorter prefix.
+ *   - **`--`** terminates option parsing; every subsequent token is positional.
+ *   - **clustered short booleans** (`-pi`) expand to each single-letter switch.
+ *   - **`list` flags accumulate** across repetition and split a single
+ *     comma-separated token into elements.
+ *   - **`@file`** tokens are recorded as attachment references rather than
+ *     positionals.
+ *
+ * The parse is total: an unrecognised `--flag` is tolerated as a boolean switch
+ * in the loose {@link Invocation.flags} bag (the extension-flag escape hatch)
+ * rather than rejected, so nothing is silently dropped. Strong typing of the
+ * named fields, and mode derivation, happen in one final fold.
+ */
+import { type Invocation } from "../contract";
+/**
+ * Read a sliced `argv` into the fully-parsed {@link Invocation}.
+ *
+ * Walks the tokens once via the {@link FLAG_SPECS} index, accumulates into a
+ * {@link ParseState}, then folds that into the strongly-typed result: the loose
+ * {@link Invocation.flags} bag is retained for round-tripping and extension
+ * flags, and the named fields are derived from it with per-kind coercion and
+ * validation. The `attachments` field is left unset here — the file references
+ * are surfaced for the attachment gatherer to expand separately.
+ *
+ * @param argv the already-sliced argument vector (no node / executable path)
+ */
+export declare function readInvocation(argv: readonly string[]): Invocation;
+/**
+ * The `@file` references collected from an argv, exposed for the attachment
+ * gatherer. A thin re-walk of the reader so the file references can be obtained
+ * without re-deriving the whole parse where only attachments are needed.
+ */
+export declare function readFileReferences(argv: readonly string[]): string[];

package/dist/types/launch/invocation/usage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The usage renderer — generated entirely from {@link FLAG_SPECS}.
+ *
+ * {@link renderUsage} produces the `--help` banner by walking the same
+ * declarative flag table the reader parses against. There is no second,
+ * hand-maintained help string; every option line is synthesised from its
+ * {@link FlagSpec} (its canonical name, its aliases, its value placeholder, and
+ * its one-line description), grouped by the editorial {@link FLAG_GROUPS}
+ * sections. Adding a flag to the table therefore adds it to the help with no
+ * further edit, and the two can never disagree about what exists.
+ *
+ * The renderer is pure and total: it reads only the table and returns a string.
+ */
+/**
+ * Render the full usage banner.
+ *
+ * Emits a synopsis line, then one section per {@link FLAG_GROUPS} entry that has
+ * any rows, then a short note on the two positional conventions the reader
+ * honours but that are not flags: the `@file` attachment syntax and the `--`
+ * option terminator. Every option line is derived from {@link FLAG_SPECS}; this
+ * function holds no per-flag knowledge of its own.
+ *
+ * @returns the complete multi-line usage string (no trailing newline)
+ */
+export declare function renderUsage(): string;

package/dist/types/launch/launch.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Phase-10 launch subsystem — unit tests.
+ *
+ * No network and no real terminal: every effectful seam is injected. The tests
+ * pin the public launch surface assembled from the contract:
+ *
+ *   1. {@link readInvocation} parses a representative argv into the right
+ *      {@link Invocation} (mode, prompt, model, mcp list, thinking, no-tools).
+ *   2. {@link renderUsage} is generated from {@link FLAG_SPECS} alone — every
+ *      flag description appears, proving the one-source-of-truth invariant.
+ *   3. {@link gatherAttachments} resolves an `@file` in a tmpdir and raises a
+ *      typed {@link AttachmentError} for a missing and an oversized file.
+ *   4. {@link runCredentialCommand} stores an api key through an injected fake
+ *      vault for the api-key path, and drives the framework browser sign-in for
+ *      an OAuth-capable provider (persisting the returned credentials).
+ *   5. {@link printModelCatalog} lists models from an injected source.
+ *   6. {@link registerBuiltInOAuthProviders} primes the framework registry and
+ *      {@link listLoginProviders} surfaces both kinds.
+ */
+export {};

package/dist/types/launch/oauth.d.ts

@@ -0,0 +1,88 @@
+/**
+ * OAuth integration — the browser-sign-in counterpart to the api-key flow.
+ *
+ * The framework ships working sign-in machinery for a handful of providers but
+ * leaves its registry empty by default (api-key-only mode). This module turns
+ * that on: {@link registerBuiltInOAuthProviders} populates the registry with the
+ * three framework providers, and runs once as a side effect of importing the
+ * module so that the moment the launch layer loads, the OAuth-capable providers
+ * are live.
+ *
+ * On top of registration it offers three things the credential command needs:
+ *   - {@link listLoginProviders} — the merged sign-in directory, every entry
+ *     tagged with whether it authenticates by browser sign-in or by api key.
+ *   - {@link startOAuthLogin} — drives a framework provider's login flow and
+ *     persists the resulting credentials through the {@link AuthVault}.
+ *   - {@link openLoginUrl} — a default-browser launcher (per platform) the login
+ *     callback uses to send the user to the provider's consent page.
+ *
+ * No state is held here beyond the framework registry itself; the module is a
+ * thin, testable seam over the framework API plus the app's vault.
+ */
+import { type OAuthLoginCallbacks } from "indusagi/ai";
+import type { AuthVault } from "./contract";
+/**
+ * Register the framework's built-in sign-in providers, idempotently.
+ *
+ * Each provider is registered only when its id is not already present, so
+ * repeated calls (or a re-import) leave the registry unchanged. Returns the ids
+ * that are registered after the call, for callers that want to confirm the set.
+ */
+export declare function registerBuiltInOAuthProviders(): string[];
+/** How a provider authenticates in the merged sign-in directory. */
+export type AuthKind = "oauth" | "apiKey";
+/** One row of the merged sign-in directory. */
+export interface LoginProvider {
+    /** Stable provider id (framework registry id or api-key directory id). */
+    readonly id: string;
+    /** Human-facing label for menus and prompts. */
+    readonly label: string;
+    /** Whether this entry signs in via the browser or stores an api key. */
+    readonly authKind: AuthKind;
+}
+/**
+ * The merged sign-in directory: every registered browser-sign-in provider plus
+ * every api-key provider the app knows, each tagged with its {@link AuthKind}.
+ *
+ * Browser-sign-in providers lead the list (they are the preferred path for the
+ * providers that support them); an api-key provider that shares an id with a
+ * registered sign-in provider is still listed, so a user can choose either path
+ * for the same underlying account.
+ */
+export declare function listLoginProviders(): LoginProvider[];
+/**
+ * Open a sign-in url in the user's default browser.
+ *
+ * Refuses anything that is not an `http`/`https` url and resolves `false`, so a
+ * provider that hands back a non-web redirect never spawns a process. Each
+ * strategy is tried in turn; the first one that spawns without an immediate
+ * error wins. Resolves `true` if a browser was launched, `false` otherwise.
+ */
+export declare function openLoginUrl(url: string): Promise<boolean>;
+/**
+ * The outcome of {@link startOAuthLogin}: the provider and account the
+ * credentials were stored under, and whether this account became the default.
+ */
+export interface OAuthLoginResult {
+    /** The provider id the sign-in completed for. */
+    readonly provider: string;
+    /** The account name the credentials were stored under. */
+    readonly account: string;
+    /** Whether the new account was stored as the provider default. */
+    readonly madeDefault: boolean;
+}
+/**
+ * Drive a framework provider's browser sign-in and persist the result.
+ *
+ * Looks the provider up in the (now populated) framework registry, runs its
+ * login flow with the supplied {@link OAuthLoginCallbacks}, and writes the
+ * returned credentials into the {@link AuthVault} under `account`. The first
+ * account stored for a provider becomes its default. Throws when the provider id
+ * is not registered or the framework login flow rejects.
+ *
+ * @param providerId the registered sign-in provider id (e.g. the framework id)
+ * @param callbacks  the framework login callbacks (url open, prompt, progress)
+ * @param vault      the credential store the result is persisted through
+ * @param account    the account name to store under (defaults to `"default"`)
+ */
+export declare function startOAuthLogin(providerId: string, callbacks: OAuthLoginCallbacks, vault: AuthVault, account?: string): Promise<OAuthLoginResult>;

package/dist/types/launch/packages.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Package command — `runPackageCommand`.
+ *
+ * The top-level `install` / `remove` / `update` / `list` / `config` surface that
+ * manages the extension-package sources the launcher loads. A source is a plain
+ * string the loader understands — an `npm:` spec, a `git:` / `https:` repo, or a
+ * bare local path — and the configured set lives in the user settings under the
+ * `extensionPackages` key, persisted through the {@link PreferenceStore}.
+ *
+ * The command owns the first positional token only: it returns
+ * `{ handled: false }` when that token is not one of the recognised subcommands,
+ * so the orchestrator can call this first and fall through to a normal launch on
+ * a miss. It never throws for an expected failure — a bad argument is reported as
+ * a printed line and a non-zero {@link PackageResult.code}.
+ *
+ * I/O is injected. The default {@link PackageIo} wraps `process.stdout` /
+ * `process.stderr`, but tests drive the whole flow over an in-memory stand-in and
+ * a store pinned to a temp directory, so the real home is never touched.
+ */
+import { PreferenceStore } from "../settings";
+/** The five subcommands the package command recognises as the first token. */
+export type PackageCommand = "install" | "remove" | "update" | "list" | "config";
+/** Every {@link PackageCommand}, as a frozen tuple for membership tests. */
+export declare const PACKAGE_COMMANDS: readonly PackageCommand[];
+/**
+ * The console seam the package command writes through. Pinned to a normal line
+ * and an error line so a test can capture both streams without a real terminal.
+ */
+export interface PackageIo {
+    /** Emit one line of human-facing text to the standard stream. */
+    print(line: string): void;
+    /** Emit one line to the error stream. */
+    printError(line: string): void;
+}
+/** The default {@link PackageIo} backed by `process.stdout` / `process.stderr`. */
+export declare function defaultPackageIo(): PackageIo;
+/**
+ * Options for {@link runPackageCommand}: the injected settings store the sources
+ * persist through and the optional io seam. The store is injected so tests pin it
+ * to a temp directory; boot resolves it from the workspace.
+ */
+export interface PackageCommandOptions {
+    /** The settings store the package sources read from and write to. */
+    readonly store: PreferenceStore;
+    /** The console seam; defaults to {@link defaultPackageIo}. */
+    readonly io?: PackageIo;
+}
+/**
+ * The outcome of {@link runPackageCommand}.
+ *
+ * {@link handled} reports whether the first token was a recognised subcommand;
+ * when `false`, the caller proceeds to a normal launch unchanged. {@link code}
+ * is the process exit code for a handled command — zero on success, non-zero when
+ * a required argument was missing or invalid.
+ */
+export interface PackageResult {
+    /** Whether this invocation was a package subcommand. */
+    readonly handled: boolean;
+    /** The subcommand that ran, when {@link handled} is true. */
+    readonly command?: PackageCommand;
+    /** Process exit code for a handled command (zero on success). */
+    readonly code?: number;
+}
+/**
+ * Run the package command.
+ *
+ * Returns `{ handled: false }` immediately when `argv[0]` is not a recognised
+ * subcommand, so the orchestrator can call this first and fall through on a miss.
+ * Otherwise it performs the subcommand against the injected store and resolves a
+ * {@link PackageResult} — never throwing for an expected failure.
+ *
+ * @param argv the raw token list following the program name
+ * @param opts the injected settings store and (optionally) the io seam
+ */
+export declare function runPackageCommand(argv: readonly string[], opts: PackageCommandOptions): Promise<PackageResult>;

package/dist/types/launch/packages.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package command — unit tests.
+ *
+ * Everything runs against a {@link PreferenceStore} pinned to a temp directory
+ * through {@link PreferenceStore.atPaths}; the real home is never read or
+ * written. The io seam is an in-memory capture, so there is no real terminal. The
+ * tests pin the public behaviour of {@link runPackageCommand}:
+ *
+ *   1. A non-package leading token falls through (`handled: false`).
+ *   2. `install` persists a source, is idempotent under equivalent spellings, and
+ *      `list` reads it back; `remove` clears it again.
+ *   3. A missing source argument is a non-zero, non-throwing failure.
+ *   4. `config` prints the resolved settings paths and contents.
+ */
+export {};