@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/docs/api/index.md

@@ -0,0 +1,675 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/whistle**](README.md)
+
+---
+
+[@fungi.computer/whistle](README.md) / index
+
+# index
+
+## Classes
+
+### WhistleActionError
+
+An owning handler's explicit failure code and optional structured details.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new WhistleActionError(
+   code,
+   message,
+   details?
+): WhistleActionError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                           | Description                                            |
+| ---------- | ---------------------------------------------- | ------------------------------------------------------ |
+| `code`     | `string`                                       | Stable failure identity supplied by the handler owner. |
+| `message`  | `string`                                       | -                                                      |
+| `details?` | [`WhistleJsonValue`](wire.md#whistlejsonvalue) | Optional JSON context safe to return to the caller.    |
+
+###### Returns
+
+[`WhistleActionError`](#whistleactionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: string;
+```
+
+Stable failure identity supplied by the handler owner.
+
+##### details?
+
+```ts
+readonly optional details?: WhistleJsonValue;
+```
+
+Optional JSON context safe to return to the caller.
+
+---
+
+### WhistleClosedError
+
+A valid contribution was attempted after the runtime closed.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new WhistleClosedError(): WhistleClosedError;
+```
+
+Construct the provisional error for a valid post-close contribution.
+
+###### Returns
+
+[`WhistleClosedError`](#whistleclosederror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+## Type Aliases
+
+### WhistleExecutionOrigin
+
+```ts
+type WhistleExecutionOrigin =
+  | "agent"
+  | "browser"
+  | "keyboard"
+  | "menu"
+  | "palette"
+  | "programmatic"
+  | "slash"
+  | "terminal";
+```
+
+The trusted host origin entering the single execution door.
+
+---
+
+### WhistleCommandHandler
+
+```ts
+type WhistleCommandHandler<Arguments, Result> = object["bivarianceHack"];
+```
+
+A source-owned command's execution callback, invoked only through the execution
+door.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Arguments`    |
+| `Result`       |
+
+---
+
+### WhistlePromptAnswer
+
+```ts
+type WhistlePromptAnswer<Prompt> = WhistlePromptAnswers[Prompt["type"]];
+```
+
+The answer type for one prompt kind.
+
+#### Type Parameters
+
+| Type Parameter                                              |
+| ----------------------------------------------------------- |
+| `Prompt` _extends_ [`WhistlePrompt`](wire.md#whistleprompt) |
+
+---
+
+### WhistleInteraction
+
+```ts
+type WhistleInteraction = Readonly<{
+  signal: AbortSignal;
+  prompt: <Kind>(prompt, options?) => Promise<WhistlePromptAnswers[Kind]>;
+  notify: (notice) => void;
+}>;
+```
+
+A human conversation attached to one execution. `prompt` rejects when the human
+cancels; `signal` aborts when the whole interaction is dismissed.
+
+---
+
+### WhistleInteractionEnd
+
+```ts
+type WhistleInteractionEnd =
+  | Readonly<{
+      status: "handled";
+    }>
+  | Readonly<{
+      status: "cancelled";
+    }>
+  | Readonly<{
+      status: "failed";
+      message: string;
+    }>;
+```
+
+How an execution with an attached interaction ended.
+
+---
+
+### WhistleInteractionSession
+
+```ts
+type WhistleInteractionSession = Readonly<{
+  interaction: WhistleInteraction;
+  settle: (end) => void;
+}>;
+```
+
+One interaction a presenter opened for one execution.
+
+---
+
+### WhistlePresenter
+
+```ts
+type WhistlePresenter = (request) => WhistleInteractionSession;
+```
+
+A mounted client that can render interactions. Whistle opens one session per
+human execution that has no caller-supplied interaction.
+
+#### Parameters
+
+| Parameter | Type                                                                                 |
+| --------- | ------------------------------------------------------------------------------------ |
+| `request` | `Readonly`\<\{ `commandId`: `string`; `title`: `string`; `retry`: () => `void`; \}\> |
+
+#### Returns
+
+[`WhistleInteractionSession`](#whistleinteractionsession)
+
+---
+
+### WhistleExecutionInput
+
+```ts
+type WhistleExecutionInput<Arguments> = Readonly<{
+  origin: WhistleExecutionOrigin;
+  arguments?: Arguments;
+  signal?: AbortSignal;
+  interaction?: WhistleInteraction;
+}>;
+```
+
+The already-typed input supplied to a command handler.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Arguments`    | `unknown`    |
+
+---
+
+### WhistleExecutionOutcome
+
+```ts
+type WhistleExecutionOutcome<Result> =
+  | Extract<
+      WhistleAvailability,
+      {
+        status: "unavailable";
+      }
+    >
+  | Readonly<{
+      status: "handled";
+      result?: Result;
+    }>
+  | Readonly<{
+      status: "closed";
+    }>
+  | Readonly<{
+      status: "missing";
+    }>
+  | Readonly<{
+      status: "invalid";
+    }>
+  | Readonly<{
+      error: WhistleFailure;
+      status: "failed";
+    }>;
+```
+
+The normalized result of one command execution request.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Result`       | `unknown`    |
+
+---
+
+### WhistleCommand
+
+```ts
+type WhistleCommand<Arguments, Result> = Readonly<{
+  id: string;
+  title: string;
+  category: string;
+  description?: string;
+  projections?: WhistleCommandProjections;
+  action?: WhistleAction;
+  availability?: () => WhistleAvailability;
+  handler: WhistleCommandHandler<Arguments, Result>;
+}>;
+```
+
+One semantic command definition.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Arguments`    | `unknown`    |
+| `Result`       | `unknown`    |
+
+---
+
+### WhistleContribution
+
+```ts
+type WhistleContribution = Readonly<{
+  sourceId: string;
+  namespace: string;
+  scope?: string;
+  commands: readonly WhistleCommand<never>[];
+}>;
+```
+
+One contribution of source-owned commands to a namespace.
+
+---
+
+### WhistleProjectionRow
+
+```ts
+type WhistleProjectionRow = Readonly<{
+  commandId: string;
+  sourceId: string;
+  scope?: string;
+  title: string;
+  category: string;
+  description?: string;
+  order: number;
+  action?: WhistleAction;
+  availability: WhistleAvailability;
+}>;
+```
+
+Shared immutable metadata carried by each projection row.
+
+---
+
+### WhistleAgentProjection
+
+```ts
+type WhistleAgentProjection = Omit<WhistleProjectionRow, "action"> &
+  Readonly<{
+    action?: Pick<WhistleAction, "inputSchema" | "outputSchema">;
+    keybind?: string;
+  }>;
+```
+
+Immutable agent snapshot row composed from the schema-owned action data.
+
+---
+
+### WhistleBindingProjection
+
+```ts
+type WhistleBindingProjection = WhistleProjectionRow &
+  Readonly<{
+    binding: string;
+  }>;
+```
+
+One binding value projected from a command.
+
+---
+
+### WhistlePaletteProjection
+
+```ts
+type WhistlePaletteProjection = WhistleProjectionRow;
+```
+
+One palette value projected from a command.
+
+---
+
+### WhistleSlashProjection
+
+```ts
+type WhistleSlashProjection = WhistleProjectionRow &
+  Readonly<{
+    alias: string;
+    arguments?: WhistleSlashArguments;
+  }>;
+```
+
+One slash alias projected from a command.
+
+---
+
+### WhistleHelpProjection
+
+```ts
+type WhistleHelpProjection = WhistleProjectionRow;
+```
+
+One help value projected from a command.
+
+---
+
+### WhistleMenuProjection
+
+```ts
+type WhistleMenuProjection = WhistleProjectionRow;
+```
+
+One menu value projected from a command.
+
+---
+
+### WhistleSnapshot
+
+```ts
+type WhistleSnapshot = Readonly<{
+  bindings: readonly WhistleBindingProjection[];
+  palette: readonly WhistlePaletteProjection[];
+  slash: readonly WhistleSlashProjection[];
+  help: readonly WhistleHelpProjection[];
+  menu: readonly WhistleMenuProjection[];
+  agent: readonly WhistleAgentProjection[];
+}>;
+```
+
+The six immutable views of one semantic command graph.
+
+---
+
+### WhistleContributionLease
+
+```ts
+type WhistleContributionLease = Readonly<{
+  update: (commands) => void;
+  dispose: () => void;
+}>;
+```
+
+An idempotent lease for one contribution generation.
+
+---
+
+### WhistleRuntime
+
+```ts
+type WhistleRuntime = Readonly<{
+  contribute: (contribution) => WhistleContributionLease;
+  close: () => undefined;
+  execute: (commandId, input) => Promise<WhistleExecutionOutcome>;
+  snapshot: () => WhistleSnapshot;
+  subscribe: (listener) => () => void;
+  present: (presenter) => () => void;
+}>;
+```
+
+The provisional Whistle semantic runtime seam.
+
+---
+
+### WhistleKeymapAdapter
+
+```ts
+type WhistleKeymapAdapter = Readonly<{
+  cleanup: () => void;
+}>;
+```
+
+Lifecycle operations for a projection into a maintained host keymap.
+
+---
+
+### WhistleKeymapBinding
+
+```ts
+type WhistleKeymapBinding = Readonly<{
+  cmd: string;
+  key: string;
+}>;
+```
+
+One physical key string mapped to a Whistle command identifier.
+
+---
+
+### WhistleKeymapCommand
+
+```ts
+type WhistleKeymapCommand = Readonly<{
+  name: string;
+  run: () => Promise<boolean>;
+}>;
+```
+
+Host callback that executes one semantic Whistle command.
+
+---
+
+### WhistleKeymapLayer
+
+```ts
+type WhistleKeymapLayer = Readonly<{
+  bindings: readonly WhistleKeymapBinding[];
+  commands: readonly WhistleKeymapCommand[];
+}>;
+```
+
+Binding and command records accepted by a maintained keymap host.
+
+---
+
+### WhistleKeymapHost
+
+```ts
+type WhistleKeymapHost = Readonly<{
+  registerLayer: (layer) => () => void;
+}>;
+```
+
+Minimal registration surface implemented by a maintained host keymap.
+
+## Functions
+
+### scopeSnapshot()
+
+```ts
+function scopeSnapshot(snapshot, scope): WhistleSnapshot;
+```
+
+The projection for one focused scope: global rows plus the focused scope's rows.
+A focused slash alias or binding shadows the same global one. Agent rows follow
+the same scope filter; the complete runtime remains whole.
+
+#### Parameters
+
+| Parameter  | Type                                  | Description                                                  |
+| ---------- | ------------------------------------- | ------------------------------------------------------------ |
+| `snapshot` | [`WhistleSnapshot`](#whistlesnapshot) | A complete runtime snapshot.                                 |
+| `scope`    | `string` \| `null`                    | The focused scope, or `null` when nothing scoped is focused. |
+
+#### Returns
+
+[`WhistleSnapshot`](#whistlesnapshot)
+
+A frozen snapshot of globals plus the selected scope.
+
+---
+
+### createWhistle()
+
+```ts
+function createWhistle(): WhistleRuntime;
+```
+
+Construct the provisional semantic runtime shell.
+
+#### Returns
+
+[`WhistleRuntime`](#whistleruntime)
+
+---
+
+### createWhistleKeymapAdapter()
+
+```ts
+function createWhistleKeymapAdapter(
+  keymap,
+  whistle,
+  origin,
+): WhistleKeymapAdapter;
+```
+
+Project Whistle bindings into a host-created maintained OpenTUI keymap.
+
+#### Parameters
+
+| Parameter | Type                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------- |
+| `keymap`  | [`WhistleKeymapHost`](#whistlekeymaphost)                                                   |
+| `whistle` | `Pick`\<[`WhistleRuntime`](#whistleruntime), `"snapshot"` \| `"subscribe"` \| `"execute"`\> |
+| `origin`  | [`WhistleExecutionOrigin`](#whistleexecutionorigin)                                         |
+
+#### Returns
+
+[`WhistleKeymapAdapter`](#whistlekeymapadapter)
+
+## References
+
+### WhistleAction
+
+Re-exports [WhistleAction](wire.md#whistleaction)
+
+---
+
+### WhistleActionPresentation
+
+Re-exports [WhistleActionPresentation](wire.md#whistleactionpresentation)
+
+---
+
+### WhistleActionSchema
+
+Re-exports [WhistleActionSchema](wire.md#whistleactionschema)
+
+---
+
+### WhistleAvailability
+
+Re-exports [WhistleAvailability](wire.md#whistleavailability)
+
+---
+
+### WhistleCommandProjections
+
+Re-exports [WhistleCommandProjections](wire.md#whistlecommandprojections)
+
+---
+
+### WhistleCommandDefinition
+
+Re-exports [WhistleCommandDefinition](wire.md#whistlecommanddefinition)
+
+---
+
+### WhistleFailure
+
+Re-exports [WhistleFailure](wire.md#whistlefailure)
+
+---
+
+### WhistleJsonObject
+
+Re-exports [WhistleJsonObject](wire.md#whistlejsonobject)
+
+---
+
+### WhistleJsonValue
+
+Re-exports [WhistleJsonValue](wire.md#whistlejsonvalue)
+
+---
+
+### WhistleNotice
+
+Re-exports [WhistleNotice](wire.md#whistlenotice)
+
+---
+
+### WhistleNoticeLink
+
+Re-exports [WhistleNoticeLink](wire.md#whistlenoticelink)
+
+---
+
+### WhistlePrompt
+
+Re-exports [WhistlePrompt](wire.md#whistleprompt)
+
+---
+
+### WhistlePromptOption
+
+Re-exports [WhistlePromptOption](wire.md#whistlepromptoption)
+
+---
+
+### WhistleSlashArguments
+
+Re-exports [WhistleSlashArguments](wire.md#whistleslasharguments)
+
+---
+
+### WhistleSlashWord
+
+Re-exports [WhistleSlashWord](wire.md#whistleslashword)