@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/docs/api/catalog.md

@@ -0,0 +1,498 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/whistle**](README.md)
+
+---
+
+[@fungi.computer/whistle](README.md) / catalog
+
+# catalog
+
+## Type Aliases
+
+### WhistleCatalogInvoke
+
+```ts
+type WhistleCatalogInvoke = (
+  commandId,
+  args,
+  signal,
+) => Promise<WhistleJsonValue>;
+```
+
+Call one advertised command at its backend; resolves to a raw step.
+
+#### Parameters
+
+| Parameter   | Type                                             |
+| ----------- | ------------------------------------------------ |
+| `commandId` | `string`                                         |
+| `args`      | [`WhistleJsonObject`](wire.md#whistlejsonobject) |
+| `signal`    | `AbortSignal`                                    |
+
+#### Returns
+
+`Promise`\<[`WhistleJsonValue`](wire.md#whistlejsonvalue)\>
+
+---
+
+### WhistleCatalogV1
+
+```ts
+type WhistleCatalogV1 = ReadonlySchemaValue<
+  z.output<typeof WhistleCatalogSchema>
+>;
+```
+
+An advertised command catalog decoded by the maintained catalog schema.
+
+---
+
+### WhistleCatalogStepV1
+
+```ts
+type WhistleCatalogStepV1 = ReadonlySchemaValue<
+  z.output<typeof WhistleCatalogStepSchema>
+>;
+```
+
+A decoded catalog response step derived from its maintained schema.
+
+## Variables
+
+### whistleCatalogProtocol
+
+```ts
+const whistleCatalogProtocol: "whistle.catalog/v1" = "whistle.catalog/v1";
+```
+
+The one catalog protocol this Whistle understands.
+
+---
+
+### WhistleCatalogSchema
+
+```ts
+const WhistleCatalogSchema: ZodPipe<ZodObject<{
+  protocol: ZodLiteral<"whistle.catalog/v1">;
+  commands: ZodArray<ZodObject<{
+     id: ZodString;
+     title: ZodString;
+     category: ZodString;
+     description: ZodOptional<ZodString>;
+     projections: ZodOptional<ZodObject<{
+        bindings: ZodOptional<ZodObject<..., ...>>;
+        agent: ZodOptional<ZodObject<..., ...>>;
+        help: ZodOptional<ZodObject<..., ...>>;
+        menu: ZodOptional<ZodObject<..., ...>>;
+        palette: ZodOptional<ZodObject<..., ...>>;
+        slash: ZodOptional<ZodObject<..., ...>>;
+     }, $strict>>;
+     action: ZodOptional<ZodObject<{
+        inputSchema: ZodOptional<ZodRecord<..., ...>>;
+        outputSchema: ZodOptional<ZodRecord<..., ...>>;
+        presentation: ZodOptional<ZodUnion<...>>;
+     }, $strict>>;
+     availability: ZodOptional<ZodDiscriminatedUnion<[ZodObject<{
+        status: ...;
+      }, $strict>, ZodObject<{
+        status: ...;
+        reason: ...;
+     }, $strict>], "status">>;
+  }, $strict>>;
+}, $strict>, ZodTransform<Readonly<{
+  protocol: "whistle.catalog/v1";
+  commands: readonly object[];
+}>, {
+  protocol: "whistle.catalog/v1";
+  commands: object[];
+}>>;
+```
+
+Validate one complete Whistle catalog and its unique command ids.
+
+---
+
+### parseCatalog
+
+```ts
+const parseCatalog: typeof WhistleCatalogSchema.parse;
+```
+
+Parse an advertised catalog at the client boundary.
+
+---
+
+### WhistleCatalogStepSchema
+
+```ts
+const WhistleCatalogStepSchema: ZodPipe<ZodDiscriminatedUnion<[ZodObject<{
+  type: ZodLiteral<"done">;
+  notice: ZodOptional<ZodDiscriminatedUnion<[ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+     links: ZodOptional<...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     url: ZodURL;
+     code: ZodOptional<...>;
+     message: ZodOptional<...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+  }, $strict>], "type">>;
+  result: ZodOptional<ZodJSONSchema>;
+}, $strict>, ZodObject<{
+  type: ZodLiteral<"prompt">;
+  prompt: ZodDiscriminatedUnion<[ZodObject<{
+     type: ZodLiteral<"choice">;
+     message: ZodPipe<ZodString, ZodString>;
+     collapsedGroup: ZodOptional<ZodPipe<..., ...>>;
+     options: ZodArray<ZodObject<..., ...>>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<"text">;
+     message: ZodPipe<ZodString, ZodString>;
+     placeholder: ZodOptional<ZodPipe<..., ...>>;
+     secret: ZodOptional<ZodBoolean>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<"confirmation">;
+     message: ZodPipe<ZodString, ZodString>;
+     confirmLabel: ZodOptional<ZodPipe<..., ...>>;
+     cancelLabel: ZodOptional<ZodPipe<..., ...>>;
+  }, $strict>], "type">;
+  notice: ZodOptional<ZodDiscriminatedUnion<[ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+     links: ZodOptional<...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     url: ZodURL;
+     code: ZodOptional<...>;
+     message: ZodOptional<...>;
+   }, $strict>, ZodObject<{
+     type: ZodLiteral<...>;
+     message: ZodPipe<..., ...>;
+  }, $strict>], "type">>;
+  next: ZodObject<{
+     arguments: ZodRecord<ZodString, ZodJSONSchema>;
+     answer: ZodString;
+  }, $strict>;
+}, $strict>], "type">, ZodTransform<
+  | Readonly<{
+  type: "done";
+  notice?:   | {
+     type: "info";
+     message: string;
+     links?: object[];
+   }
+     | {
+     type: "progress";
+     message: string;
+   }
+     | {
+     type: "handoff";
+     url: string;
+     code?: string;
+     message?: string;
+   }
+     | {
+     type: "success";
+     message: string;
+   };
+  result?: JSONType;
+}>
+  | Readonly<{
+  type: "prompt";
+  prompt:   | {
+     type: "choice";
+     message: string;
+     collapsedGroup?: string;
+     options: object[];
+   }
+     | {
+     type: "text";
+     message: string;
+     placeholder?: string;
+     secret?: boolean;
+   }
+     | {
+     type: "confirmation";
+     message: string;
+     confirmLabel?: string;
+     cancelLabel?: string;
+   };
+  notice?:   | {
+     type: "info";
+     message: string;
+     links?: object[];
+   }
+     | {
+     type: "progress";
+     message: string;
+   }
+     | {
+     type: "handoff";
+     url: string;
+     code?: string;
+     message?: string;
+   }
+     | {
+     type: "success";
+     message: string;
+   };
+  next: {
+     arguments: Record<string, JSONType>;
+     answer: string;
+  };
+}>,
+  | {
+  type: "done";
+  notice?:   | {
+     type: "info";
+     message: string;
+     links?: object[];
+   }
+     | {
+     type: "progress";
+     message: string;
+   }
+     | {
+     type: "handoff";
+     url: string;
+     code?: string;
+     message?: string;
+   }
+     | {
+     type: "success";
+     message: string;
+   };
+  result?: JSONType;
+}
+  | {
+  type: "prompt";
+  prompt:   | {
+     type: "choice";
+     message: string;
+     collapsedGroup?: string;
+     options: object[];
+   }
+     | {
+     type: "text";
+     message: string;
+     placeholder?: string;
+     secret?: boolean;
+   }
+     | {
+     type: "confirmation";
+     message: string;
+     confirmLabel?: string;
+     cancelLabel?: string;
+   };
+  notice?:   | {
+     type: "info";
+     message: string;
+     links?: object[];
+   }
+     | {
+     type: "progress";
+     message: string;
+   }
+     | {
+     type: "handoff";
+     url: string;
+     code?: string;
+     message?: string;
+   }
+     | {
+     type: "success";
+     message: string;
+   };
+  next: {
+     arguments: Record<string, JSONType>;
+     answer: string;
+  };
+}>>;
+```
+
+Validate one response step before it reaches an interaction renderer.
+
+---
+
+### parseCatalogStep
+
+```ts
+const parseCatalogStep: typeof WhistleCatalogStepSchema.parse;
+```
+
+Parse one backend reply before any of it reaches a renderer.
+
+## Functions
+
+### catalogCommands()
+
+```ts
+function catalogCommands(catalog, invoke): readonly Readonly<{
+  id: string;
+  title: string;
+  category: string;
+  description?: string;
+  projections?: {
+     bindings?: {
+        order?: number;
+        values: readonly string[];
+     };
+     agent?: {
+        keybind?: string;
+        order?: number;
+     };
+     help?: {
+        order?: number;
+     };
+     menu?: {
+        order?: number;
+     };
+     palette?: {
+        order?: number;
+     };
+     slash?: {
+        aliases: readonly string[];
+        order?: number;
+        arguments?: {
+           hint: string;
+           words?: readonly ...[];
+           text?: {
+              field: ...;
+              arguments: ...;
+              requestIdField?: ...;
+           };
+        };
+     };
+  };
+  action?: {
+     inputSchema?: {
+      [key: string]:
+        | string
+        | number
+        | boolean
+        | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+        | {
+      [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+      }
+        | null;
+     };
+     outputSchema?: {
+      [key: string]:
+        | string
+        | number
+        | boolean
+        | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+        | {
+      [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+      }
+        | null;
+     };
+     presentation?:   | {
+        type: "action";
+      }
+        | {
+        type: "custom";
+        data: {
+         [key: string]:
+           | string
+           | number
+           | boolean
+           | readonly string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...[]
+           | {
+         [key: string]: string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | number | boolean | readonly (string | ... 4 more ... | null)[] | { ...; } | null)[] | { ...; } | null)[] | { ...; } | ...;
+         }
+           | null;
+        };
+      }
+        | {
+        type: "choice";
+        options: readonly object[];
+      }
+        | {
+        type: "form";
+        submitLabel?: string;
+      }
+        | {
+        type: "confirmation";
+        message: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+      };
+  };
+  availability?: () => WhistleAvailability;
+  handler: (input) => unknown;
+}>[];
+```
+
+Turn an advertised catalog into Whistle commands. Each handler runs the
+backend's step conversation through the caller's interaction; an Agent, which
+has no interaction, can run only commands that finish in one step.
+
+#### Parameters
+
+| Parameter          | Type                                                                       |
+| ------------------ | -------------------------------------------------------------------------- |
+| `catalog`          | \{ `protocol`: `"whistle.catalog/v1"`; `commands`: readonly `object`[]; \} |
+| `catalog.protocol` | `"whistle.catalog/v1"`                                                     |
+| `catalog.commands` | readonly `object`[]                                                        |
+| `invoke`           | [`WhistleCatalogInvoke`](#whistlecataloginvoke)                            |
+
+#### Returns
+
+readonly `Readonly`\<\{ `id`: `string`; `title`: `string`; `category`: `string`;
+`description?`: `string`; `projections?`: \{ `bindings?`: \{ `order?`: `number`;
+`values`: readonly `string`[]; \}; `agent?`: \{ `keybind?`: `string`; `order?`:
+`number`; \}; `help?`: \{ `order?`: `number`; \}; `menu?`: \{ `order?`:
+`number`; \}; `palette?`: \{ `order?`: `number`; \}; `slash?`: \{ `aliases`:
+readonly `string`[]; `order?`: `number`; `arguments?`: \{ `hint`: `string`;
+`words?`: readonly ...[]; `text?`: \{ `field`: ...; `arguments`: ...;
+`requestIdField?`: ...; \}; \}; \}; \}; `action?`: \{ `inputSchema?`: \{
+\[`key`: `string`\]: \| `string` \| `number` \| `boolean` \| readonly string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| number \| boolean \| readonly
+(string \| number \| boolean \| readonly (string \| number \| boolean \|
+readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`: `string`\]: string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| number \| boolean \| readonly
+(string \| number \| boolean \| readonly (string \| number \| boolean \|
+readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; `outputSchema?`: \{
+\[`key`: `string`\]: \| `string` \| `number` \| `boolean` \| readonly string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| number \| boolean \| readonly
+(string \| number \| boolean \| readonly (string \| number \| boolean \|
+readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`: `string`\]: string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| number \| boolean \| readonly (string \| number \| boolean \| readonly
+(string \| number \| boolean \| readonly (string \| number \| boolean \|
+readonly (string \| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{
+...; \} \| null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; `presentation?`: \|
+\{ `type`: `"action"`; \} \| \{ `type`: `"custom"`; `data`: \{ \[`key`:
+`string`\]: \| `string` \| `number` \| `boolean` \| readonly string \| number \|
+boolean \| readonly (string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \|
+null)\[\] \| \{ ...; \} \| ...[] \| \{ \[`key`: `string`\]: string \| number \|
+boolean \| readonly (string \| number \| boolean \| readonly (string \| number
+\| boolean \| readonly (string \| number \| boolean \| readonly (string \|
+number \| boolean \| readonly (string \| number \| boolean \| readonly (string
+\| ... 4 more ... \| null)\[\] \| \{ ...; \} \| null)\[\] \| \{ ...; \} \|
+null)\[\] \| \{ ...; \} \| ...; \} \| `null`; \}; \} \| \{ `type`: `"choice"`;
+`options`: readonly `object`[]; \} \| \{ `type`: `"form"`; `submitLabel?`:
+`string`; \} \| \{ `type`: `"confirmation"`; `message`: `string`;
+`confirmLabel?`: `string`; `cancelLabel?`: `string`; \}; \}; `availability?`: ()
+=> [`WhistleAvailability`](wire.md#whistleavailability); `handler`: (`input`) =>
+`unknown`; \}\>[]

package/docs/api/html.md

@@ -0,0 +1,45 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/whistle**](README.md)
+
+---
+
+[@fungi.computer/whistle](README.md) / html
+
+# html
+
+## Type Aliases
+
+### HtmlWhistleBinding
+
+```ts
+type HtmlWhistleBinding = Readonly<{
+  keymap: ReturnType<typeof createDefaultHtmlKeymap>;
+  dispose: () => void;
+}>;
+```
+
+Maintained document keymap plus disposable Whistle command projection.
+
+## Functions
+
+### bindHtmlKeymap()
+
+```ts
+function bindHtmlKeymap(root, whistle, origin): HtmlWhistleBinding;
+```
+
+Bind Whistle commands to the maintained OpenTUI HTML keymap. The root owns the
+host's document lifetime; dispose removes the command projection only.
+
+#### Parameters
+
+| Parameter | Type                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| `root`    | `HTMLElement`                                                                                       |
+| `whistle` | `Pick`\<[`WhistleRuntime`](index.md#whistleruntime), `"snapshot"` \| `"subscribe"` \| `"execute"`\> |
+| `origin`  | [`WhistleExecutionOrigin`](index.md#whistleexecutionorigin)                                         |
+
+#### Returns
+
+[`HtmlWhistleBinding`](#htmlwhistlebinding)