@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/dist/wire.js

@@ -0,0 +1,299 @@
+import * as z from "zod";
+const json = z.json();
+/** Host-owned availability carried by every discovered agent row. */
+export const WhistleAvailabilitySchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        /** The action can currently be invoked. */
+        status: z.literal("available"),
+    })
+        .strict(),
+    z
+        .object({
+        /** The action cannot currently be invoked. */
+        status: z.literal("unavailable"),
+        /** Host-supplied explanation suitable for presentation to a caller. */
+        reason: z.string(),
+    })
+        .strict(),
+]);
+/** The JSON value grammar shared by Whistle transports and App adapters. */
+export const WhistleJsonValueSchema = json;
+/** One JSON object, used for action schemas and custom presentation data. */
+export const WhistleJsonObjectSchema = z.record(z.string(), WhistleJsonValueSchema);
+/** Parse copied JSON data at an untrusted transport boundary. */
+export const parseJsonValue = (value) => WhistleJsonValueSchema.parse(value);
+/** Parse a copied JSON object at an untrusted transport boundary. */
+export const parseJsonObject = (value) => WhistleJsonObjectSchema.parse(value);
+/** General portable failure data for adapters that cross a transport. */
+export const WhistleFailureSchema = z
+    .object({
+    code: z.string().min(1).max(160),
+    message: z.string().min(1).max(512),
+    details: WhistleJsonValueSchema.optional(),
+})
+    .strict();
+/** Parse failure data without carrying an Error or stack across the wire. */
+export const parseFailure = (value) => WhistleFailureSchema.parse(value);
+/** The JSON object shape used by Whistle action schemas. */
+export const WhistleActionSchemaSchema = WhistleJsonObjectSchema;
+const meaningful = z.string().refine((value) => value.trim().length > 0);
+const availabilitySchema = WhistleAvailabilitySchema;
+/** Validate renderer-neutral presentation data attached to an action. */
+export const WhistleActionPresentationSchema = z.union([
+    z.object({ type: z.literal("action") }).strict(),
+    z
+        .object({
+        type: z.literal("custom"),
+        data: WhistleJsonObjectSchema,
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("choice"),
+        options: z.array(z.object({
+            value: WhistleJsonValueSchema,
+            label: meaningful,
+            description: meaningful.optional(),
+        })),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("form"),
+        submitLabel: meaningful.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("confirmation"),
+        message: meaningful,
+        confirmLabel: meaningful.optional(),
+        cancelLabel: meaningful.optional(),
+    })
+        .strict(),
+]);
+/** Validate the serializable action contract carried by a command. */
+export const WhistleActionDataSchema = z
+    .object({
+    inputSchema: WhistleActionSchemaSchema.optional(),
+    outputSchema: WhistleActionSchemaSchema.optional(),
+    presentation: WhistleActionPresentationSchema.optional(),
+})
+    .strict();
+const safeOrder = z
+    .number()
+    .int()
+    .refine((value) => Number.isSafeInteger(value));
+/** Validate aliases and argument mapping metadata for slash commands. */
+export const WhistleSlashArgumentsSchema = z
+    .object({
+    hint: meaningful.pipe(z.string().max(120)),
+    words: z
+        .array(z
+        .object({
+        word: z.string().regex(/^\S{1,64}$/u),
+        description: meaningful.pipe(z.string().max(512)).optional(),
+        arguments: WhistleJsonObjectSchema,
+    })
+        .strict())
+        .max(32)
+        .optional(),
+    text: z
+        .object({
+        field: meaningful.pipe(z.string().max(120)),
+        arguments: WhistleJsonObjectSchema,
+        requestIdField: meaningful.pipe(z.string().max(120)).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .refine((grammar) => grammar.words !== undefined || grammar.text !== undefined, "slash arguments need words or text");
+const orderedProjectionSchema = z
+    .object({ order: safeOrder.optional() })
+    .strict();
+/** Validate explicit membership and ordering across Whistle surfaces. */
+export const WhistleCommandProjectionsSchema = z
+    .object({
+    bindings: z
+        .object({
+        order: safeOrder.optional(),
+        values: z.array(meaningful).max(16),
+    })
+        .strict()
+        .optional(),
+    agent: z
+        .object({
+        keybind: meaningful.optional(),
+        order: safeOrder.optional(),
+    })
+        .strict()
+        .optional(),
+    help: orderedProjectionSchema.optional(),
+    menu: orderedProjectionSchema.optional(),
+    palette: orderedProjectionSchema.optional(),
+    slash: z
+        .object({
+        aliases: z.array(meaningful).max(16),
+        order: safeOrder.optional(),
+        arguments: WhistleSlashArgumentsSchema.optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/** Validate data-only command definitions supplied by an adapter. */
+export const WhistleCommandDefinitionSchema = z
+    .object({
+    id: meaningful.refine((value) => !value.includes(":")),
+    title: meaningful,
+    category: meaningful,
+    description: meaningful.optional(),
+    projections: WhistleCommandProjectionsSchema.optional(),
+    action: WhistleActionDataSchema.optional(),
+    availability: availabilitySchema.optional(),
+})
+    .strict();
+/** Parse action metadata once before an adapter constructs a Whistle command. */
+export const parseAction = (value) => WhistleActionDataSchema.parse(value);
+/** Parse the Whistle-owned projection metadata supplied by an App. */
+export const parseProjections = (value) => WhistleCommandProjectionsSchema.parse(value);
+/** Parse an availability fact while preserving its reason. */
+export const parseAvailability = (value) => availabilitySchema.parse(value);
+/** Parse one data-only command definition before an adapter creates a command. */
+export const parseCommandDefinition = (value) => WhistleCommandDefinitionSchema.parse(value);
+/** Semantic action data; client presentation is intentionally not wire data. */
+const WhistleAgentActionSchema = z
+    .object({
+    inputSchema: WhistleActionSchemaSchema.optional(),
+    outputSchema: WhistleActionSchemaSchema.optional(),
+})
+    .strict();
+/** One neutral agent row emitted by Whistle's `snapshot.agent` projection. */
+export const WhistleAgentProjectionSchema = z
+    .object({
+    commandId: z.string(),
+    sourceId: z.string(),
+    scope: z.string().optional(),
+    title: z.string(),
+    category: z.string(),
+    description: z.string().optional(),
+    order: z.number(),
+    availability: WhistleAvailabilitySchema,
+    action: WhistleAgentActionSchema.optional(),
+    keybind: z.string().optional(),
+})
+    .strict();
+/** A neutral Whistle agent projection collection. */
+export const WhistleAgentProjectionsSchema = z.array(WhistleAgentProjectionSchema);
+/** Decode an untrusted agent projection collection at the wire boundary. */
+export const parse = (value) => WhistleAgentProjectionsSchema.parse(value);
+/** Longest prompt answer or message an interaction carries. */
+export const interactionTextLimit = 8192;
+const shortText = meaningful.pipe(z.string().max(interactionTextLimit));
+const webUrl = z.url({ protocol: /^https?$/u });
+/** Validate renderer-neutral interaction prompts received from a host. */
+export const WhistlePromptSchema = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("choice"),
+        message: shortText,
+        collapsedGroup: shortText.optional(),
+        options: z
+            .array(z
+            .object({
+            value: shortText,
+            label: shortText,
+            description: shortText.optional(),
+            group: shortText.optional(),
+        })
+            .strict())
+            .min(1)
+            .max(256),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("text"),
+        message: shortText,
+        placeholder: shortText.optional(),
+        secret: z.boolean().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("confirmation"),
+        message: shortText,
+        confirmLabel: shortText.optional(),
+        cancelLabel: shortText.optional(),
+    })
+        .strict(),
+]);
+/** Validate interaction notices received from a host. */
+export const WhistleNoticeSchema = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("info"),
+        message: shortText,
+        links: z
+            .array(z.object({ url: webUrl, label: shortText.optional() }).strict())
+            .max(16)
+            .optional(),
+    })
+        .strict(),
+    z.object({ type: z.literal("progress"), message: shortText }).strict(),
+    z
+        .object({
+        type: z.literal("handoff"),
+        url: webUrl,
+        code: shortText.optional(),
+        message: shortText.optional(),
+    })
+        .strict(),
+    z.object({ type: z.literal("success"), message: shortText }).strict(),
+]);
+/** Parse one interaction prompt at the boundary where a client renders it. */
+export const parsePrompt = (value) => WhistlePromptSchema.parse(value);
+/** Parse one interaction notice at the boundary where a client renders it. */
+export const parseNotice = (value) => WhistleNoticeSchema.parse(value);
+const answerSchemas = {
+    confirmation: (prompt) => {
+        WhistlePromptSchema.options[2].parse(prompt);
+        return z.boolean();
+    },
+    text: (prompt) => {
+        WhistlePromptSchema.options[1].parse(prompt);
+        return z.string().max(interactionTextLimit);
+    },
+    choice: (prompt) => {
+        const request = WhistlePromptSchema.options[0].parse(prompt);
+        const answer = z
+            .string()
+            .refine((value) => request.options.some((option) => option.value === value));
+        return answer;
+    },
+};
+/** Capture a prompt's parsed answer contract before handing it to a renderer. */
+export function createPromptAnswerParser(prompt) {
+    const schema = answerSchemas[prompt.type](prompt);
+    return (value) => schema.parse(value);
+}
+/** Parse the answer a human gave to one prompt before the command sees it. */
+export function parsePromptAnswer(prompt, value) {
+    return createPromptAnswerParser(prompt)(value);
+}
+/** Capture a typed answer decoder; invalid input stays an explicit outcome. */
+export function createPromptAnswerDecoder(prompt) {
+    const schema = answerSchemas[prompt.type](prompt);
+    return (value) => {
+        const result = schema.safeParse(value);
+        return result.success
+            ? { kind: "accepted", value: result.data }
+            : { kind: "invalid", cause: result.error };
+    };
+}
+/** Decode a human answer without throwing so renderers can handle invalid input. */
+export function decodePromptAnswer(prompt, value) {
+    return createPromptAnswerDecoder(prompt)(value);
+}

package/docs/api/README.md

@@ -0,0 +1,17 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/whistle**
+
+---
+
+# @fungi.computer/whistle
+
+## Modules
+
+| Module                        | Description |
+| ----------------------------- | ----------- |
+| [catalog](catalog.md)         | -           |
+| [html](html.md)               | -           |
+| [index](index.md)             | -           |
+| [interaction](interaction.md) | -           |
+| [wire](wire.md)               | -           |