indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/types/console/overlays/pickers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Picker overlays — the selection dialogs raised over the transcript.
+ *
+ * This group owns the four modal kinds that present a list to pick from: the
+ * single-model picker (`models`), the per-scope model picker (`scopedModels`),
+ * the colour-scheme picker (`theme`), and the settings list (`settings`). It is
+ * mounted unconditionally by {@link import("./host").OverlayHost}; the host
+ * routes by {@link ModalState.kind}, so this component only renders a dialog
+ * body for one of its own kinds and is otherwise inert.
+ */
+import type { ConsoleDispatch, InkThemeAdapter, ModalState, OverlayServices } from "../contract";
+/**
+ * The props every overlay group receives, forwarded verbatim from
+ * {@link import("./host").OverlayHost}.
+ */
+export interface OverlayGroupProps {
+    /** The active modal overlay (kind + opaque payload). */
+    readonly modal: ModalState;
+    /** The runtime handles overlays drive; absent on headless mount paths. */
+    readonly services?: OverlayServices;
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** Dispatch a reducer event to mutate console state. */
+    readonly dispatch: ConsoleDispatch;
+    /** Drop the active overlay back to the composer. */
+    readonly closeModal: () => void;
+}
+/**
+ * The picker overlay group: models, scoped models, theme, and settings.
+ *
+ * Renders the framework dialog matching the active modal kind, and nothing for
+ * any kind owned by another group. With no runtime services attached (headless
+ * and test mounts) every kind renders nothing.
+ *
+ * @param props the forwarded overlay props
+ */
+export declare function PickerOverlays(props: OverlayGroupProps): JSX.Element | null;

package/dist/types/console/overlays/sessions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Session overlays — the transcript navigation dialogs.
+ *
+ * This group owns the three modal kinds that browse persisted or in-flight
+ * transcript state: the session resume/list picker (`sessions`), the
+ * transcript-tree navigator (`tree`), and the prior-user-turn picker
+ * (`userTurns`) used when branching or forking. It is mounted unconditionally
+ * by {@link import("./host").OverlayHost}, which routes by
+ * {@link ModalState.kind}; this component renders a dialog body only for one of
+ * its own kinds and is otherwise inert.
+ *
+ * Each body maps the app's session vocabulary onto the framework dialog prop
+ * shapes: a {@link import("../../sessions").SavedSession} becomes a
+ * `SessionInfo`, a {@link import("../../sessions").BranchNode} becomes a
+ * `SessionTreeOption`, and a {@link import("../../sessions").PriorTurn} becomes
+ * a `UserMessageOption`. Async catalog/tree/turn loads run in `useEffect`; every
+ * confirm drives the matching service then closes the modal. When the runtime
+ * {@link OverlayServices} bundle is absent, the group renders nothing.
+ */
+import type { OverlayGroupProps } from "./pickers";
+/**
+ * The session overlay group: sessions, tree, and prior-turn pickers.
+ *
+ * Renders the dialog body matching the active modal kind, or nothing for a kind
+ * this group does not own (or when no runtime services are wired in).
+ *
+ * @param props the forwarded overlay props (modal, services, theme, dispatch, closer)
+ */
+export declare function SessionOverlays(props: OverlayGroupProps): JSX.Element | null;

package/dist/types/console/reducer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Console reducer — the single pure fold over {@link ConsoleState}.
+ *
+ * The whole terminal surface is reduced from one immutable {@link ConsoleState}
+ * value, mutated only by dispatching a {@link ConsoleEvent} into
+ * {@link consoleReducer}. This module is the one place those transitions live:
+ * it is a pure function (no React, no I/O, no timers) that, given a prior state
+ * and an event, returns a *fresh* state — it never mutates its input. That makes
+ * every transition unit-testable in isolation and keeps the surface component a
+ * thin shell that only wires events in and renders the result out.
+ *
+ * The transitions fall into a few families, mirroring the {@link ConsoleEvent}
+ * grouping:
+ *
+ *   - **Composer edits** (`buffer:*`, `caret:*`) splice and navigate the live
+ *     input buffer, keeping the caret clamped into `[0, buffer.length]`.
+ *   - **History recall** (`history:*`) walks the submitted-input ring, stashing
+ *     the live buffer on the way in and restoring it on the way out.
+ *   - **Transcript view** (`rows:*`, `block:append`) appends and patches the
+ *     rendered rows projected from the conductor's {@link SessionSignal} stream
+ *     (the surface translates each signal into a row event).
+ *   - **Overlays / status / theme / toggles / busy** flip the small UI-local
+ *     flags the surface reads to decide what chrome to render.
+ *
+ * Live session data (messages, usage, model) is *not* stored here — it is read
+ * straight from the conductor snapshot — so this state stays purely UI-local and
+ * the reducer never needs to know about the agent loop.
+ */
+import { type ConsoleEvent, type ConsoleState } from "./contract";
+/**
+ * Fold a {@link ConsoleEvent} into a {@link ConsoleState}, returning a fresh
+ * state.
+ *
+ * Pure and total: every event has a defined transition, and the input state is
+ * never mutated. The `switch` is exhaustive over the event union, so adding an
+ * event without handling it is a compile error.
+ *
+ * @param state the prior console state
+ * @param event the action to apply
+ */
+export declare function consoleReducer(state: ConsoleState, event: ConsoleEvent): ConsoleState;
+/**
+ * Build the initial {@link ConsoleState} a console mounts with.
+ *
+ * Starts from the frozen {@link EMPTY_CONSOLE_STATE} seed and overlays any
+ * caller-supplied UI preferences (scheme, the display toggles). Pure and
+ * deterministic — no runtime is consulted — so the first render is stable.
+ *
+ * @param overrides optional UI-local preferences to seed
+ */
+export declare function initConsoleState(overrides?: Partial<ConsoleState>): ConsoleState;

package/dist/types/console/slash/builtins.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The built-in slash catalog — the single ordered source of truth.
+ *
+ * The catalog is assembled from three static topic groups, each its own module
+ * under `./commands/`: transcript/session control, the workbench pickers
+ * (model/models-for/theme/settings/help/keys/whats-new/debug), and the
+ * integration bridges (login/logout/mcp/memory/composio/copy/export/share). On
+ * top of those it splices in the *dynamic* rows — one `/skill:<name>` per
+ * discovered Agent-Skills capability card and one `/<template-name>` per
+ * discovered prompt-template macro — produced by {@link buildDynamicCommands}.
+ *
+ * There is no command `if`-ladder anywhere: adding a static command is appending
+ * a row to one of the groups, and the dynamic rows are discovered at module load
+ * from the standard skill/macro roots (returning nothing, never an error, when
+ * those roots are absent). The registry index, the completion matcher, and the
+ * family grouping are all *derived* from {@link SLASH_COMMANDS} (see
+ * `registry.ts`).
+ *
+ * Listing order is intentional: transcript controls first (the verbs a new user
+ * meets), then the workbench pickers, then the integration bridges, and finally
+ * the discovered skills and templates.
+ */
+import type { SlashCommand } from "../contract";
+/** The family labels the catalog groups commands under (for `/help`). */
+export { FAMILY } from "./commands/shared";
+/**
+ * The built-in catalog — every command row in listing order.
+ *
+ * Consumers fold this into a {@link SlashRegistry} via `buildRegistry`; the index
+ * by name/alias, the family grouping, and the completion matcher are all derived
+ * from this one array.
+ */
+export declare const SLASH_COMMANDS: readonly SlashCommand[];

package/dist/types/console/slash/commands/dynamic.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Dynamic slash commands — capability cards and prompt templates as registry rows.
+ *
+ * The static catalog (`./builtins`) is hand-maintained, but two command families
+ * are *discovered* at startup rather than written by hand: the Agent-Skills
+ * capability cards ({@link SkillCard}s loaded from `SKILL.md` files) and the
+ * user/project prompt templates ({@link Macro}s loaded from `*.md` macro files).
+ * This module turns whatever was discovered into ordinary {@link SlashCommand}
+ * rows so they sit in the same registry as the built-ins, complete the same way,
+ * and resolve through the same dispatcher.
+ *
+ * Two row shapes are produced:
+ *
+ *   - `/skill:<name>` — invoking it submits an Agent-Skills *invocation block*
+ *     (`<skill name="…" location="…">body</skill>`) as a normal turn, which is
+ *     exactly what the agent loop recognises to load and run that skill. The
+ *     trailing argument string becomes the skill body, so `/skill:commit tidy the
+ *     diff` runs the `commit` card against "tidy the diff".
+ *   - `/<template-name>` — invoking it expands the macro body against the
+ *     trailing arguments (the single-pass `$arg` model from the briefing layer)
+ *     and submits the result as a normal turn.
+ *
+ * Both return a `{ kind: "prompt" }` outcome so the dispatcher hands the produced
+ * text to the conductor as a turn; neither reaches into a backend the console
+ * does not own. When nothing was discovered, {@link buildDynamicCommands} returns
+ * an empty array, so splicing it into the catalog is always safe.
+ */
+import type { Macro, SkillCard } from "../../../briefing";
+import type { SlashCommand } from "../../contract";
+/**
+ * The discovered material a dynamic catalog is built from.
+ *
+ * Both fields are optional and default to empty: a caller that only loaded
+ * skills passes `{ skills }`, one that only loaded templates passes `{ templates }`,
+ * and a caller with neither passes `{}` (or nothing) and gets back `[]`.
+ */
+export interface DynamicCommandSources {
+    /** Capability cards discovered from `SKILL.md` files. */
+    readonly skills?: readonly SkillCard[];
+    /** Prompt templates discovered from `*.md` macro files. */
+    readonly templates?: readonly Macro[];
+}
+/**
+ * Project discovered skills and templates into {@link SlashCommand} rows.
+ *
+ * Skill rows are listed first (namespaced under `skill:`), then the template
+ * rows. A name claimed by an earlier row — including any of the static built-ins
+ * a caller will concatenate these ahead of — is the registry's problem to reject
+ * at assembly time; this function only suppresses *self*-collisions so a template
+ * whose name duplicates a skill's `skill:`-prefixed token (impossible) or another
+ * template (first wins) cannot crash the build. When no sources are supplied the
+ * result is an empty array, never an error.
+ *
+ * @param sources the discovered skills and templates
+ * @returns the dynamic command rows, skills first then templates
+ */
+export declare function buildDynamicCommands(sources?: DynamicCommandSources): SlashCommand[];

package/dist/types/console/slash/commands/dynamic.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamic command group — focused tests.
+ *
+ * The builder turns discovered capability cards and prompt-template macros into
+ * {@link SlashCommand} rows. Each row's `run` is driven against a scripted
+ * {@link SlashContext} so its produced outcome (a `prompt` carrying the skill
+ * invocation block or the expanded template) is asserted directly.
+ */
+export {};

package/dist/types/console/slash/commands/integrations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Integration slash commands — auth launchers, the external bridges, and the
+ * clipboard / export / share I/O verbs.
+ *
+ * This group is the console's seam onto everything that lives *outside* a single
+ * turn: signing in and out of a provider, wiring the MCP and memory surfaces,
+ * connecting an external SaaS bridge, and moving the transcript out of the
+ * terminal (clipboard, HTML export, a share link). The handlers do real work
+ * where a backing capability exists — they render the live transcript to HTML
+ * through the {@link publishTranscript} publisher, drive an {@link MCPClientPool}
+ * over the workspace MCP config, reflect the working-memory card from the
+ * capability deck, and reach the Composio catalog through the SaaS gateway — and
+ * fall back to an *informative* status (never a dead placeholder) when a backend
+ * is unreachable in the current environment.
+ *
+ * The two family commands (`/memory`, `/composio`) are built from
+ * {@link SubCommand} tables via {@link familyRunner}, so their verb dispatch is a
+ * lookup, not an `if`-ladder. Overlay surfaces (`mcp`, `memory`, `composio`)
+ * carry the *gathered* text into the plugin modal payload, so the dialog renders
+ * the real state the command collected rather than a fixed line.
+ */
+import type { SlashCommand } from "../../contract";
+/**
+ * The integration command group: auth launchers, the MCP/memory/composio
+ * bridges, and the clipboard / export / share I/O verbs. Appended to the slash
+ * registry by the integrator alongside the other groups.
+ */
+export declare const integrationCommands: SlashCommand[];

package/dist/types/console/slash/commands/integrations.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Integration slash commands — focused behavioral tests.
+ *
+ * Each handler is exercised through a scripted fake {@link SlashContext} that
+ * records the overlay requests (`openModal`) and status toasts (`setStatus`) the
+ * handlers raise. The coverage walks every command and family verb:
+ *   1. The auth/bridge launchers (`/login`, `/logout`, `/mcp`) open the right
+ *      modal kind, and a named `/login` threads the provider into the payload.
+ *   2. `/memory` reflects the real working-memory card (status / tools / on /
+ *      off) and carries the gathered text into the plugin overlay.
+ *   3. `/composio` reports the missing-key state specifically when no
+ *      `COMPOSIO_API_KEY` is configured, and warns on a missing connect target.
+ *   4. `/copy` extracts the newest assistant prose and writes it through the
+ *      injected clipboard, warning when there is nothing to copy.
+ *   5. `/export` renders the live transcript to an HTML file (and warns on an
+ *      empty transcript); `/share` reuses that path and degrades informatively.
+ */
+export {};

package/dist/types/console/slash/commands/shared.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared slash-command helpers — the small, pure toolkit every command group is
+ * written against.
+ *
+ * The console's slash catalog is split into topic groups (transcript control,
+ * the workbench pickers, the integration bridges). Each group is its own module
+ * exporting a `SlashCommand[]`; this file holds the handful of helpers they all
+ * lean on so the groups stay free of duplicated wiring and the family
+ * sub-command dispatch lives in exactly one place.
+ *
+ * Two stances every group keeps:
+ *   1. **Handlers are thin.** A `run(ctx)` never reaches into React, the
+ *      filesystem, or a provider SDK; every effect goes through the injected
+ *      {@link SlashContext}. The handler decides *which* effect to raise.
+ *   2. **Families are tables, not ladders.** A command with sub-verbs (e.g.
+ *      `/memory note|show|forget`) is built from a {@link SubCommand} table via
+ *      {@link familyRunner}, never a hand-written `if`-chain.
+ */
+import type { SlashContext, SlashOutcome, StatusMessage } from "../../contract";
+/**
+ * The family labels the catalog groups commands under for `/help` and
+ * completion. Named constants (not bare strings scattered across rows) so the
+ * grouping a command declares and the grouping the help view renders cannot
+ * drift apart.
+ */
+export declare const FAMILY: {
+    readonly composio: "composio";
+    readonly memory: "memory";
+    readonly scopedModels: "models-for";
+    readonly theme: "theme";
+};
+/** The settled "command ran, nothing more to do" outcome. */
+export declare const HANDLED: SlashOutcome;
+/** Mint an info-tone status toast. */
+export declare function info(text: string): StatusMessage;
+/** Mint a warning-tone status toast (used for usage hints on bad args). */
+export declare function warn(text: string): StatusMessage;
+/**
+ * Split a family command's argument string into a leading sub-command verb and
+ * the remainder, both trimmed. An empty argument string yields an empty verb so
+ * a family command can show its own usage when invoked bare.
+ *
+ * @param args the raw trailing argument string from {@link SlashContext.args}
+ */
+export declare function splitVerb(args: string): {
+    verb: string;
+    rest: string;
+};
+/**
+ * One sub-command of a command family — its verb, a one-line description for the
+ * usage list, and the thin action it runs through the {@link SlashContext}.
+ */
+export interface SubCommand {
+    /** The sub-command verb, lower-cased (e.g. `add`, `list`, `clear`). */
+    readonly verb: string;
+    /** One-line description rendered in the family's usage toast. */
+    readonly describe: string;
+    /** Run the sub-command; `rest` is the argument tail after the verb. */
+    run(ctx: SlashContext, rest: string): SlashOutcome;
+}
+/**
+ * Build a family command's `run` from a sub-command table.
+ *
+ * The family handler is a single thin function whose branch structure is
+ * *generated* from the table: it splits the verb, looks it up, and runs the
+ * matching action — falling back to a usage toast (assembled from the table's
+ * descriptions) when the verb is missing or unknown.
+ *
+ * @param family the family label, used in the usage header
+ * @param subs   the sub-command table for this family
+ */
+export declare function familyRunner(family: string, subs: readonly SubCommand[]): (ctx: SlashContext) => SlashOutcome;

package/dist/types/console/slash/commands/transcript.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Transcript & session-control slash commands.
+ *
+ * The first topic group of the console's slash catalog: the verbs that reset,
+ * rename, branch, inspect, or leave the live session view. Every row is a thin
+ * {@link SlashCommand} whose `run` drives the injected {@link SlashContext} — a
+ * reducer event, a conductor call, a modal, or an exit request — and settles to
+ * {@link HANDLED}. Nothing here reaches into React, the filesystem, or a
+ * provider SDK directly; backend work flows through the {@link SessionConductor}.
+ *
+ * The rename, stats, condense, and reload verbs are backed by real conductor
+ * surface ({@link SessionConductor.setSessionName}, {@link SessionConductor.stats},
+ * {@link SessionConductor.condense}). Where the conductor cannot accept a richer
+ * input (the condense path is parameterless on this build), the closest real
+ * action is taken and the status line explains precisely what was applied.
+ */
+import type { SlashCommand } from "../../contract";
+/**
+ * The transcript / session-control group, in listing order.
+ *
+ * Appended into the slash registry by the catalog integrator; this module owns
+ * only the rows, never the wiring.
+ */
+export declare const transcriptCommands: SlashCommand[];

package/dist/types/console/slash/commands/transcript.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Focused tests for the transcript / session-control slash group.
+ *
+ * Each command is exercised against a scripted {@link SlashContext} fake that
+ * records every effect it raises (reducer events, status toasts, modal opens,
+ * conductor calls, exit requests). The assertions check that each verb raises
+ * exactly the effect its contract promises and settles to `handled` without
+ * throwing.
+ */
+export {};

package/dist/types/console/slash/commands/workbench.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workbench slash commands — the pickers, display blocks, and help surfaces.
+ *
+ * This group covers the overlays a user reaches for to inspect or retune the
+ * session: the model pickers, the per-scope routing editor, the colour-scheme
+ * switch, the settings list, the command palette (`/help`), the keyboard map
+ * (`/keys`), the project changelog (`/whats-new`), and a diagnostics dump
+ * (`/debug`). The picker handlers stay thin — they raise an overlay through
+ * {@link SlashContext.openModal} or flip a reducer flag — while the help,
+ * keys, whats-new, and debug handlers do real work: they read the live slash
+ * catalog, the grounded keymap, a `CHANGELOG.md` on disk, and the conductor's
+ * session statistics, then surface the result as a display block or a written
+ * file rather than a dead placeholder.
+ */
+import type { SlashCommand } from "../../contract";
+/**
+ * The workbench command rows, in listing order. Pickers and help surfaces open
+ * an overlay; the changelog drops a display block; debug flips a toggle and
+ * reports it.
+ */
+export declare const workbenchCommands: SlashCommand[];

package/dist/types/console/slash/commands/workbench.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Workbench command group — focused handler tests.
+ *
+ * Each command is driven against a scripted {@link SlashContext} fake that
+ * records every injected action, so a handler's effect is asserted by
+ * inspecting the recorded overlays / dispatches / statuses / blocks rather than
+ * a rendered surface. The group stays thin: every handler resolves to a settled
+ * outcome and raises exactly the effects its row promises.
+ */
+export {};

package/dist/types/console/slash/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Slash subsystem — public barrel.
+ *
+ * The console's data-driven slash layer, in three pure pieces:
+ *
+ *   - **The catalog** — {@link SLASH_COMMANDS}, the single ordered list of
+ *     {@link SlashCommand} rows (core commands plus the `composio` / `memory` /
+ *     `scoped-models` / `theme` families). There is no command `if`-ladder; a new
+ *     command is a new row.
+ *   - **The registry** — {@link buildRegistry} folds the catalog into the frozen
+ *     {@link SlashRegistry} shape (commands + a name/alias index), and the derived
+ *     lookups ({@link matchPrefix}, {@link findCommand}, {@link commandsInFamily},
+ *     {@link listFamilies}) power resolution, completion, and grouped listing.
+ *   - **Resolution** — {@link resolveSlash} parses a typed composer line and
+ *     resolves it against a registry to a discriminated {@link SlashResolution}.
+ *
+ * {@link DEFAULT_SLASH_REGISTRY} is the catalog pre-folded into a registry, the
+ * value the console mounts with. The effectful dispatcher (which calls a matched
+ * command's `run`) lives outside this barrel; everything exported here is pure.
+ */
+export { SLASH_COMMANDS, FAMILY } from "./builtins";
+export { buildRegistry, tokensOf, findCommand, matchPrefix, listFamilies, commandsInFamily, } from "./registry";
+export { SLASH_PREFIX, looksLikeSlash, parseSlash, resolveSlash, type SlashLine, type SlashResolution, } from "./resolve";
+import type { SlashRegistry } from "../contract";
+/**
+ * The built-in catalog pre-folded into a resolved {@link SlashRegistry}.
+ *
+ * The default the console mounts with: the catalog indexed by every canonical
+ * name and alias, ready for {@link resolveSlash} and the completion matcher. A
+ * caller that needs to splice in prompt templates, plugin commands, or
+ * `/skill:*` entries builds its own registry from a concatenated list via
+ * {@link buildRegistry} rather than mutating this one.
+ */
+export declare const DEFAULT_SLASH_REGISTRY: SlashRegistry;

package/dist/types/console/slash/registry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Slash registry assembly — fold a command list into the resolved registry.
+ *
+ * The slash subsystem keeps exactly one hand-maintained list of commands (the
+ * {@link SLASH_COMMANDS} array in `builtins.ts`); everything a consumer needs to
+ * resolve, complete, or list a command is *derived* from that array here. This
+ * module is the bridge between the flat data and the {@link SlashRegistry} shape
+ * the contract froze:
+ *
+ *   - {@link buildRegistry} indexes the list by canonical name *and* by every
+ *     alias, so {@link import("./resolve").resolveSlash} is an O(1) map lookup
+ *     rather than a scan. It also guards the one invariant a flat array cannot:
+ *     two rows must not claim the same token (a duplicate name or alias is a
+ *     programming error, surfaced loudly at assembly time, not silently shadowed).
+ *   - {@link matchPrefix} powers the completion window: given the partial token
+ *     the user has typed, it returns the rows whose name or alias starts with it,
+ *     in registry order.
+ *   - {@link commandsInFamily} / {@link listFamilies} project the `family` field
+ *     for grouped listing (the `/help` overlay, the completion grouping).
+ *
+ * No effects, no React, no conductor — the registry is a value, and these are
+ * pure derivations over it. The dispatcher consumes the registry; it is not
+ * built here.
+ */
+import type { SlashCommand, SlashRegistry } from "../contract";
+/**
+ * Every token a command answers to: its canonical name plus any aliases.
+ *
+ * The single place name/alias enumeration happens, so the index builder and the
+ * prefix matcher agree on what counts as "a token for this command".
+ *
+ * @param command the command to enumerate tokens for
+ */
+export declare function tokensOf(command: SlashCommand): string[];
+/**
+ * Fold an ordered command list into a resolved {@link SlashRegistry}.
+ *
+ * Preserves the input order in {@link SlashRegistry.commands} (it is the listing
+ * order the completion window and `/help` render in) and derives the
+ * {@link SlashRegistry.index} by mapping every token — canonical and alias — to
+ * its owning command. Tokens are lower-cased on the way in so resolution can be
+ * case-insensitive without the resolver re-normalising.
+ *
+ * Throws when two rows claim the same token: a flat array cannot express
+ * "these names are disjoint", so the invariant is enforced here, at the one
+ * point the table is assembled, instead of letting a later row silently shadow
+ * an earlier one.
+ *
+ * @param commands the ordered command list (the single source of truth)
+ */
+export declare function buildRegistry(commands: readonly SlashCommand[]): SlashRegistry;
+/**
+ * Resolve a single token (canonical or alias) to its command, or `undefined`.
+ *
+ * A thin, case-insensitive read of {@link SlashRegistry.index} so call sites do
+ * not re-implement the lower-casing the registry index expects.
+ *
+ * @param registry the registry to read
+ * @param token    a canonical name or alias, with or without a leading slash
+ */
+export declare function findCommand(registry: SlashRegistry, token: string): SlashCommand | undefined;
+/**
+ * The commands whose name or alias begins with a partial token, in registry
+ * order — the candidate set the completion window renders.
+ *
+ * Matching is case-insensitive and prefix-based against *every* token a command
+ * answers to, but each command appears at most once even when several of its
+ * tokens match. An empty partial returns the whole list (the bare-`/` case where
+ * the user has opened the completion window but typed nothing yet).
+ *
+ * @param registry the registry to search
+ * @param partial  the partial command token (without a leading slash)
+ */
+export declare function matchPrefix(registry: SlashRegistry, partial: string): SlashCommand[];
+/**
+ * The distinct family labels present in the registry, in first-seen order.
+ *
+ * Commands without a `family` are omitted; the result drives the grouped
+ * headings in `/help` and the completion window.
+ *
+ * @param registry the registry to scan
+ */
+export declare function listFamilies(registry: SlashRegistry): string[];
+/**
+ * The commands belonging to a family, in registry order.
+ *
+ * @param registry the registry to filter
+ * @param family   the family label to select
+ */
+export declare function commandsInFamily(registry: SlashRegistry, family: string): SlashCommand[];

package/dist/types/console/slash/resolve.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Slash line resolution — parse a typed line, then match it against the registry.
+ *
+ * This module is the pure front half of the slash subsystem: it takes the raw
+ * string a user typed into the composer and decides three things, in order:
+ *
+ *   1. **Is this a slash line at all?** A line is a slash invocation only when its
+ *      first non-blank character is `/` and what follows is a command-shaped
+ *      token (so a bare `/` or a `/path/to/file` literal is *not* hijacked as a
+ *      command). {@link parseSlash} reports this without consulting the registry.
+ *   2. **Which command does the token resolve to?** {@link resolveSlash} folds a
+ *      {@link SlashRegistry} in: it splits the line into a name and a trailing
+ *      argument string, then resolves the name (and its aliases) through the
+ *      registry's index. Resolution is case-insensitive on the command token.
+ *   3. **What should the dispatcher do?** The result is a discriminated
+ *      {@link SlashResolution}: `not-slash` (treat as a normal prompt / bash
+ *      escape), `match` (run this command with these args), or `miss` (it looked
+ *      like a command but no row owns the token — fall through to templates,
+ *      plugin commands, or a literal prompt).
+ *
+ * Nothing here touches React, the conductor, or I/O — the whole module is a pair
+ * of pure functions over a string and a registry, which is exactly why the slash
+ * parsing/matching logic lives here rather than inside a `useInput` handler. The
+ * effectful half (actually calling a command's `run`) is the dispatcher's job.
+ */
+import type { SlashCommand, SlashRegistry } from "../contract";
+/**
+ * The leading character that marks a line as a slash invocation.
+ *
+ * A single constant so the prefix is defined in exactly one place and the tests
+ * assert against the same literal the parser reads.
+ */
+export declare const SLASH_PREFIX: "/";
+/**
+ * The lexical split of a slash line into its command token and argument tail.
+ *
+ * Produced by {@link parseSlash} before the registry is consulted, so the two
+ * concerns — "did the user type a command-shaped line" and "does a command own
+ * that token" — stay separable. `name` is the bare token with no leading slash
+ * and folded to lower case for case-insensitive matching; `args` is everything
+ * after the first run of whitespace, with the single separating space removed
+ * but interior spacing preserved.
+ */
+export interface SlashLine {
+    /** The command token, lower-cased, without the leading slash. */
+    readonly name: string;
+    /** The trailing argument string (may be empty), interior spacing preserved. */
+    readonly args: string;
+}
+/**
+ * Whether a typed line is shaped like a slash command at all.
+ *
+ * A line qualifies only when, after trimming leading blanks, it begins with the
+ * {@link SLASH_PREFIX} *and* what follows up to the first whitespace is a clean
+ * {@link COMMAND_TOKEN}. This deliberately rejects a lone `/`, a `//comment`, and
+ * a `/usr/local/bin` style path (whose embedded slash breaks the token shape) so
+ * those reach the prompt untouched.
+ *
+ * @param input the raw composer line
+ */
+export declare function looksLikeSlash(input: string): boolean;
+/**
+ * Split a slash line into its {@link SlashLine} token/argument pair, or
+ * `undefined` when the line is not shaped like a command.
+ *
+ * The token runs from just after the slash up to the first whitespace (or
+ * end-of-line); the argument tail is whatever follows that whitespace, trimmed
+ * only at its outer edges. The token is lower-cased so resolution can be
+ * case-insensitive without the caller pre-normalising.
+ *
+ * @param input the raw composer line
+ */
+export declare function parseSlash(input: string): SlashLine | undefined;
+/**
+ * The outcome of resolving a typed line against a {@link SlashRegistry}.
+ *
+ *   - `not-slash` — the line is not a command invocation; the dispatcher should
+ *     hand it on as a normal prompt (or a `!`/`!!` bash escape).
+ *   - `match`     — the token resolved to `command`; run it with `args` (the raw
+ *     trailing string) via a {@link import("../contract").SlashContext}.
+ *   - `miss`      — the line *was* command-shaped but no row owns the token; the
+ *     dispatcher falls through to templates / plugin commands / a literal prompt.
+ *     The offending `name` is reported so a caller can surface "unknown command".
+ */
+export type SlashResolution = {
+    readonly kind: "not-slash";
+} | {
+    readonly kind: "match";
+    readonly command: SlashCommand;
+    readonly args: string;
+} | {
+    readonly kind: "miss";
+    readonly name: string;
+};
+/**
+ * Resolve a raw composer line against the registry to a {@link SlashResolution}.
+ *
+ * Parses the line ({@link parseSlash}); a non-command line resolves to
+ * `not-slash`. A command-shaped line's token is looked up in the registry index
+ * (which already carries both canonical names and aliases), yielding `match`
+ * with the owning command and the raw argument string, or `miss` when no row
+ * claims the token.
+ *
+ * This is the single entry point a dispatcher calls; it performs no effects.
+ *
+ * @param input    the raw composer line
+ * @param registry the registry to resolve against
+ */
+export declare function resolveSlash(input: string, registry: SlashRegistry): SlashResolution;