@fungi.computer/whistle 0.0.0-stage → 0.0.1

package/dist/index.js

@@ -0,0 +1,694 @@
+/** An owning handler's explicit failure code and optional structured details. */
+export class WhistleActionError extends Error {
+    code;
+    details;
+    constructor(
+    /** Stable failure identity supplied by the handler owner. */
+    code, message, 
+    /** Optional JSON context safe to return to the caller. */
+    details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "WhistleActionError";
+    }
+}
+/** A valid contribution was attempted after the runtime closed. */
+export class WhistleClosedError extends Error {
+    /** Construct the provisional error for a valid post-close contribution. */
+    constructor() {
+        super("Whistle runtime is closed");
+        this.name = "WhistleClosedError";
+    }
+}
+export { createWhistleKeymapAdapter, } from "./keymap.js";
+/**
+ * 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.
+ *
+ * @param snapshot - A complete runtime snapshot.
+ * @param scope - The focused scope, or `null` when nothing scoped is focused.
+ * @returns A frozen snapshot of globals plus the selected scope.
+ */
+export function scopeSnapshot(snapshot, scope) {
+    const active = (rows) => rows.filter((row) => row.scope === undefined || row.scope === scope);
+    const shadowed = (rows, key) => {
+        const focused = new Set(rows.filter((row) => row.scope === scope).map(key));
+        return Object.freeze(active(rows).filter((row) => row.scope !== undefined || !focused.has(key(row))));
+    };
+    return Object.freeze({
+        bindings: shadowed(snapshot.bindings, (row) => row.binding),
+        palette: Object.freeze(active(snapshot.palette)),
+        slash: shadowed(snapshot.slash, (row) => row.alias),
+        help: Object.freeze(active(snapshot.help)),
+        menu: Object.freeze(active(snapshot.menu)),
+        agent: Object.freeze(active(snapshot.agent)),
+    });
+}
+/** Construct the provisional semantic runtime shell. */
+export function createWhistle() {
+    let closed = false;
+    let currentSnapshot = emptySnapshot;
+    let liveContributions = [];
+    let previousAvailability = [];
+    let graphChanged = false;
+    let presenters = [];
+    const listeners = new Set();
+    const publish = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const snapshot = () => {
+        if (closed)
+            return emptySnapshot;
+        const availability = liveContributions.flatMap((live) => live.contribution.commands.map(readAvailability));
+        if (graphChanged ||
+            availability.some((value, index) => !sameAvailability(value, previousAvailability[index]))) {
+            currentSnapshot = snapshotFor(liveContributions, availability);
+            previousAvailability = availability;
+            graphChanged = false;
+        }
+        return currentSnapshot;
+    };
+    return Object.freeze({
+        close: () => {
+            if (closed)
+                return undefined;
+            closed = true;
+            liveContributions = [];
+            presenters = [];
+            previousAvailability = [];
+            currentSnapshot = emptySnapshot;
+            publish();
+            listeners.clear();
+            return undefined;
+        },
+        contribute: (contribution) => {
+            validateContribution(contribution);
+            if (closed)
+                throw new WhistleClosedError();
+            validateConflicts(contribution, liveContributions);
+            validateCapacity(contribution, liveContributions);
+            const generation = Symbol("whistle-contribution");
+            if (!isEmptyContribution(contribution)) {
+                liveContributions = [
+                    ...liveContributions,
+                    { contribution: copyContribution(contribution), generation },
+                ];
+                graphChanged = true;
+                publish();
+            }
+            let active = true;
+            return makeLease((commands) => {
+                if (!active || closed)
+                    return;
+                const replacement = {
+                    ...contribution,
+                    commands,
+                };
+                validateContribution(replacement);
+                const ownIndex = liveContributions.findIndex((candidate) => candidate.generation === generation);
+                const others = liveContributions.filter((candidate) => candidate.generation !== generation);
+                validateConflicts(replacement, others);
+                validateCapacity(replacement, others);
+                const copied = copyContribution(replacement);
+                if (isEmptyContribution(replacement)) {
+                    if (ownIndex < 0)
+                        return;
+                    liveContributions = others;
+                }
+                else if (ownIndex < 0) {
+                    liveContributions = [
+                        ...liveContributions,
+                        { contribution: copied, generation },
+                    ];
+                }
+                else {
+                    liveContributions = liveContributions.map((candidate) => candidate.generation === generation
+                        ? { contribution: copied, generation }
+                        : candidate);
+                }
+                graphChanged = true;
+                publish();
+            }, () => {
+                if (!active)
+                    return;
+                active = false;
+                const live = liveContributions.find((candidate) => candidate.generation === generation);
+                if (live === undefined)
+                    return;
+                liveContributions = liveContributions.filter((candidate) => candidate.generation !== generation);
+                graphChanged = true;
+                publish();
+            });
+        },
+        execute: async function execute(commandId, input) {
+            if (commandId.trim().length === 0)
+                return { status: "invalid" };
+            if (closed)
+                return { status: "closed" };
+            const command = findCommand(commandId, liveContributions);
+            if (command === undefined)
+                return { status: "missing" };
+            let session;
+            try {
+                const availability = readAvailability(command);
+                if (availability.status === "unavailable")
+                    return availability;
+                const presenter = presenters.at(-1)?.presenter;
+                if (input.interaction === undefined &&
+                    presenter !== undefined &&
+                    humanOrigins.has(input.origin))
+                    session = presenter({
+                        commandId,
+                        title: command.title,
+                        retry: () => {
+                            void execute(commandId, input);
+                        },
+                    });
+                const executionInput = {
+                    ...input,
+                    signal: input.signal ?? new AbortController().signal,
+                };
+                if (session !== undefined) {
+                    executionInput.interaction = session.interaction;
+                    executionInput.signal = AbortSignal.any([
+                        executionInput.signal,
+                        session.interaction.signal,
+                    ]);
+                }
+                const result = await command.handler(executionInput);
+                session?.settle({ status: "handled" });
+                return result === undefined
+                    ? { status: "handled" }
+                    : { status: "handled", result };
+            }
+            catch (error) {
+                const failure = failureFor(error instanceof Error
+                    ? error
+                    : new Error("Command handler threw a non-Error value"));
+                session?.settle(session.interaction.signal.aborted
+                    ? { status: "cancelled" }
+                    : { status: "failed", message: failure.message });
+                return { status: "failed", error: failure };
+            }
+        },
+        present: (presenter) => {
+            const entry = { presenter };
+            if (!closed)
+                presenters = [...presenters, entry];
+            return () => {
+                presenters = presenters.filter((candidate) => candidate !== entry);
+            };
+        },
+        snapshot,
+        subscribe: (listener) => {
+            if (closed)
+                return () => undefined;
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    });
+}
+/** Origins where a person is present to answer an interaction. */
+const humanOrigins = new Set([
+    "browser",
+    "keyboard",
+    "menu",
+    "palette",
+    "slash",
+    "terminal",
+]);
+const maximumBindingsOrAliases = 16;
+const maximumSlashWords = 32;
+const maximumLiveContributions = 64;
+const maximumLiveCommands = 256;
+function findCommand(commandId, liveContributions) {
+    for (const live of liveContributions) {
+        for (const command of live.contribution.commands) {
+            if (`${live.contribution.namespace}:${command.id}` === commandId)
+                return command;
+        }
+    }
+    return undefined;
+}
+function isEmptyContribution(contribution) {
+    return contribution.commands.length === 0;
+}
+function validateContribution(contribution) {
+    validateMeaningful(contribution.sourceId, "source ID");
+    validateMeaningful(contribution.namespace, "namespace", true);
+    if (contribution.scope !== undefined)
+        validateMeaningful(contribution.scope, "scope");
+    for (const command of contribution.commands)
+        validateCommand(command);
+}
+function validateConflicts(contribution, liveContributions) {
+    const namespaceOwner = liveContributions.find((live) => live.contribution.namespace === contribution.namespace &&
+        live.contribution.sourceId !== contribution.sourceId);
+    if (namespaceOwner !== undefined)
+        reject("Namespace is already owned by another source");
+    const commandIds = new Set();
+    const slashAliases = new Set();
+    for (const live of liveContributions) {
+        const sameScope = live.contribution.scope === contribution.scope;
+        for (const command of live.contribution.commands) {
+            commandIds.add(`${live.contribution.namespace}:${command.id}`);
+            if (sameScope)
+                for (const alias of command.projections?.slash?.aliases ?? [])
+                    slashAliases.add(alias);
+        }
+    }
+    for (const command of contribution.commands) {
+        const commandId = `${contribution.namespace}:${command.id}`;
+        if (commandIds.has(commandId))
+            reject("Canonical command ID is already registered");
+        commandIds.add(commandId);
+        for (const alias of command.projections?.slash?.aliases ?? []) {
+            if (slashAliases.has(alias))
+                reject("Slash alias is already registered");
+            slashAliases.add(alias);
+        }
+    }
+}
+function validateCapacity(contribution, liveContributions) {
+    if (liveContributions.length >= maximumLiveContributions)
+        reject("Live contribution capacity exceeded");
+    const liveCommandCount = liveContributions.reduce((count, live) => count + live.contribution.commands.length, 0);
+    if (liveCommandCount + contribution.commands.length > maximumLiveCommands)
+        reject("Live command capacity exceeded");
+}
+function copyContribution(contribution) {
+    const copy = {
+        sourceId: contribution.sourceId,
+        namespace: contribution.namespace,
+        commands: contribution.commands.map(copyCommand),
+    };
+    return contribution.scope === undefined
+        ? copy
+        : { ...copy, scope: contribution.scope };
+}
+function copyCommand(command) {
+    const copy = {
+        id: command.id,
+        title: command.title,
+        category: command.category,
+        handler: command.handler,
+    };
+    if (command.description !== undefined)
+        copy.description = command.description;
+    if (command.action !== undefined)
+        copy.action = copyAction(command.action);
+    if (command.availability !== undefined)
+        copy.availability = command.availability;
+    if (command.projections !== undefined)
+        copy.projections = copyProjections(command.projections);
+    return copy;
+}
+function copyAction(action) {
+    const copy = {};
+    if (action.inputSchema !== undefined)
+        copy.inputSchema = copyJsonObject(action.inputSchema);
+    if (action.outputSchema !== undefined)
+        copy.outputSchema = copyJsonObject(action.outputSchema);
+    if (action.presentation !== undefined)
+        copy.presentation = copyPresentation(action.presentation);
+    return Object.freeze(copy);
+}
+function copyJsonObject(value) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+        key,
+        copyJsonValue(nested),
+    ])));
+}
+function copyJsonValue(value) {
+    if (Array.isArray(value))
+        return Object.freeze(value.map(copyJsonValue));
+    if (value !== null && value instanceof Object) {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+            key,
+            copyJsonValue(nested),
+        ])));
+    }
+    return value;
+}
+function copyPresentation(presentation) {
+    switch (presentation.type) {
+        case "action":
+            return Object.freeze({ type: "action" });
+        case "custom":
+            return Object.freeze({
+                type: "custom",
+                data: copyJsonObject(presentation.data),
+            });
+        case "choice":
+            return Object.freeze({
+                type: "choice",
+                options: Object.freeze(presentation.options.map((option) => Object.freeze({
+                    ...option,
+                    value: copyJsonValue(option.value),
+                }))),
+            });
+        case "form":
+            return Object.freeze({ ...presentation });
+        case "confirmation":
+            return Object.freeze({ ...presentation });
+    }
+}
+function copyProjections(projections) {
+    const copy = {};
+    if (projections.bindings !== undefined)
+        copy.bindings = copyBindings(projections.bindings);
+    if (projections.agent !== undefined)
+        copy.agent = copyAgent(projections.agent);
+    if (projections.help !== undefined)
+        copy.help = copyOrdered(projections.help.order);
+    if (projections.menu !== undefined)
+        copy.menu = copyOrdered(projections.menu.order);
+    if (projections.palette !== undefined)
+        copy.palette = copyOrdered(projections.palette.order);
+    if (projections.slash !== undefined)
+        copy.slash = copySlash(projections.slash);
+    return copy;
+}
+function copyBindings(projection) {
+    const copy = {
+        values: [...projection.values],
+    };
+    if (projection.order !== undefined)
+        copy.order = projection.order;
+    return copy;
+}
+function copyAgent(projection) {
+    const copy = {};
+    if (projection.keybind !== undefined)
+        copy.keybind = projection.keybind;
+    if (projection.order !== undefined)
+        copy.order = projection.order;
+    return copy;
+}
+function copyOrdered(order) {
+    const copy = {};
+    if (order !== undefined)
+        copy.order = order;
+    return copy;
+}
+function copySlash(projection) {
+    const copy = {
+        aliases: [...projection.aliases],
+    };
+    if (projection.order !== undefined)
+        copy.order = projection.order;
+    if (projection.arguments !== undefined)
+        copy.arguments = copySlashArguments(projection.arguments);
+    return copy;
+}
+function copySlashArguments(grammar) {
+    const copy = { hint: grammar.hint };
+    if (grammar.words !== undefined)
+        copy.words = Object.freeze(grammar.words.map((word) => Object.freeze({ ...word, arguments: copyJsonObject(word.arguments) })));
+    if (grammar.text !== undefined)
+        copy.text = Object.freeze({
+            ...grammar.text,
+            arguments: copyJsonObject(grammar.text.arguments),
+        });
+    return Object.freeze(copy);
+}
+function validateCommand(command) {
+    validateMeaningful(command.id, "command ID", true);
+    validateMeaningful(command.title, "title");
+    validateMeaningful(command.category, "category");
+    validateAction(command.action);
+    validateProjections(command.projections);
+}
+function validateAction(action) {
+    if (action?.presentation === undefined)
+        return;
+    switch (action.presentation.type) {
+        case "action":
+        case "custom":
+            return;
+        case "choice":
+            for (const option of action.presentation.options) {
+                validateMeaningful(option.label, "choice label");
+                if (option.description !== undefined)
+                    validateMeaningful(option.description, "choice description");
+            }
+            return;
+        case "form":
+            if (action.presentation.submitLabel !== undefined)
+                validateMeaningful(action.presentation.submitLabel, "submit label");
+            return;
+        case "confirmation":
+            validateMeaningful(action.presentation.message, "confirmation message");
+            if (action.presentation.confirmLabel !== undefined)
+                validateMeaningful(action.presentation.confirmLabel, "confirmation label");
+            if (action.presentation.cancelLabel !== undefined)
+                validateMeaningful(action.presentation.cancelLabel, "cancellation label");
+    }
+}
+function validateProjections(projections) {
+    if (projections === undefined)
+        return;
+    for (const projection of [
+        projections.bindings,
+        projections.palette,
+        projections.slash,
+        projections.help,
+        projections.menu,
+        projections.agent,
+    ]) {
+        if (projection !== undefined)
+            validateOrder(projection.order);
+    }
+    if (projections.bindings !== undefined)
+        validateValues(projections.bindings.values, "binding");
+    if (projections.slash !== undefined) {
+        validateValues(projections.slash.aliases, "slash alias");
+        for (const alias of projections.slash.aliases)
+            if (/\s/u.test(alias))
+                reject("slash alias must not contain whitespace");
+        validateSlashArguments(projections.slash.arguments);
+    }
+    if (projections.agent?.keybind !== undefined)
+        validateMeaningful(projections.agent.keybind, "agent keybind");
+}
+function validateSlashArguments(grammar) {
+    if (grammar === undefined)
+        return;
+    validateMeaningful(grammar.hint, "argument hint");
+    if (grammar.words === undefined && grammar.text === undefined)
+        reject("slash arguments need words or text");
+    const words = new Set();
+    for (const word of grammar.words ?? []) {
+        validateMeaningful(word.word, "argument word");
+        if (/\s/u.test(word.word))
+            reject("argument word must not contain whitespace");
+        if (words.has(word.word))
+            reject("argument word is repeated");
+        words.add(word.word);
+        if (word.description !== undefined)
+            validateMeaningful(word.description, "argument word description");
+    }
+    if (words.size > maximumSlashWords)
+        reject("argument word count exceeds 32");
+    if (grammar.text !== undefined) {
+        validateMeaningful(grammar.text.field, "argument text field");
+        if (grammar.text.requestIdField !== undefined)
+            validateMeaningful(grammar.text.requestIdField, "request id field");
+    }
+}
+function validateValues(values, label) {
+    if (values.length > maximumBindingsOrAliases)
+        reject(`${label} count exceeds 16`);
+    for (const value of values)
+        validateMeaningful(value, label);
+}
+function validateMeaningful(value, label, colonFree = false) {
+    if (value.trim().length === 0)
+        reject(`${label} must not be blank`);
+    if (colonFree && value.includes(":"))
+        reject(`${label} must not contain a colon`);
+}
+function validateOrder(value) {
+    if (value !== undefined && !Number.isSafeInteger(value))
+        reject("order must be a safe integer");
+}
+function makeLease(update = () => undefined, dispose = () => undefined) {
+    return Object.freeze({ update, dispose });
+}
+function reject(message) {
+    throw new Error(message);
+}
+const emptySnapshot = Object.freeze({
+    bindings: Object.freeze([]),
+    palette: Object.freeze([]),
+    slash: Object.freeze([]),
+    help: Object.freeze([]),
+    menu: Object.freeze([]),
+    agent: Object.freeze([]),
+});
+const available = Object.freeze({ status: "available" });
+function readAvailability(command) {
+    const value = command.availability?.() ?? available;
+    return value.status === "available"
+        ? available
+        : Object.freeze({ status: "unavailable", reason: value.reason });
+}
+function sameAvailability(left, right) {
+    if (left.status === "available")
+        return right?.status === "available";
+    return right?.status === "unavailable" && left.reason === right.reason;
+}
+function failureFor(error) {
+    if (error instanceof WhistleActionError) {
+        const failure = {
+            code: error.code,
+            message: error.message,
+        };
+        return Object.freeze(error.details === undefined
+            ? failure
+            : { ...failure, details: copyJsonValue(error.details) });
+    }
+    return Object.freeze({
+        code: "command_failed",
+        message: error.message,
+    });
+}
+function snapshotFor(contributions, availability) {
+    const bindings = [];
+    const palette = [];
+    const slash = [];
+    const help = [];
+    const menu = [];
+    const agent = [];
+    let commandIndex = 0;
+    for (const live of contributions) {
+        const contribution = live.contribution;
+        for (const command of contribution.commands) {
+            const projections = command.projections;
+            const commandAvailability = availability[commandIndex++] ?? available;
+            if (projections?.bindings !== undefined) {
+                for (const binding of projections.bindings.values)
+                    bindings.push({
+                        ...projectionRow(contribution, command, projections.bindings.order, commandAvailability),
+                        binding,
+                    });
+            }
+            if (projections?.palette !== undefined)
+                palette.push({
+                    ...projectionRow(contribution, command, projections.palette.order, commandAvailability),
+                });
+            if (projections?.slash !== undefined) {
+                for (const alias of projections.slash.aliases) {
+                    const row = {
+                        ...projectionRow(contribution, command, projections.slash.order, commandAvailability),
+                        alias,
+                    };
+                    slash.push(projections.slash.arguments === undefined
+                        ? row
+                        : { ...row, arguments: projections.slash.arguments });
+                }
+            }
+            if (projections?.help !== undefined)
+                help.push({
+                    ...projectionRow(contribution, command, projections.help.order, commandAvailability),
+                });
+            if (projections?.menu !== undefined)
+                menu.push({
+                    ...projectionRow(contribution, command, projections.menu.order, commandAvailability),
+                });
+            if (projections?.agent !== undefined)
+                agent.push(agentRow(contribution, command, projections.agent, commandAvailability));
+        }
+    }
+    sortBindings(bindings);
+    sortAliases(slash);
+    sortRows(palette);
+    sortRows(help);
+    sortRows(menu);
+    sortRows(agent);
+    return Object.freeze({
+        bindings: freezeRows(bindings),
+        palette: freezeRows(palette),
+        slash: freezeRows(slash),
+        help: freezeRows(help),
+        menu: freezeRows(menu),
+        agent: freezeRows(agent),
+    });
+}
+const utf8Encoder = new TextEncoder();
+function compareUtf8(left, right) {
+    const leftBytes = utf8Encoder.encode(left);
+    const rightBytes = utf8Encoder.encode(right);
+    const length = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftByte = leftBytes[index] ?? 0;
+        const rightByte = rightBytes[index] ?? 0;
+        if (leftByte !== rightByte)
+            return leftByte < rightByte ? -1 : 1;
+    }
+    return leftBytes.length < rightBytes.length
+        ? -1
+        : leftBytes.length > rightBytes.length
+            ? 1
+            : 0;
+}
+function sortRows(rows) {
+    rows.sort((left, right) => left.order - right.order || compareUtf8(left.commandId, right.commandId));
+}
+function sortBindings(rows) {
+    rows.sort((left, right) => left.order - right.order ||
+        compareUtf8(left.commandId, right.commandId) ||
+        compareUtf8(left.binding, right.binding));
+}
+function sortAliases(rows) {
+    rows.sort((left, right) => left.order - right.order ||
+        compareUtf8(left.commandId, right.commandId) ||
+        compareUtf8(left.alias, right.alias));
+}
+function freezeRows(rows) {
+    return Object.freeze(rows.map((row) => Object.freeze(row)));
+}
+function projectionRow(contribution, command, order, availability) {
+    const row = unscopedRow(contribution, command, order, availability);
+    return contribution.scope === undefined
+        ? row
+        : { ...row, scope: contribution.scope };
+}
+function unscopedRow(contribution, command, order, availability) {
+    const row = {
+        commandId: `${contribution.namespace}:${command.id}`,
+        sourceId: contribution.sourceId,
+        title: command.title,
+        category: command.category,
+        order: order ?? 0,
+        availability,
+    };
+    const described = command.description === undefined
+        ? row
+        : { ...row, description: command.description };
+    return command.action === undefined
+        ? described
+        : { ...described, action: command.action };
+}
+function agentRow(contribution, command, projection, availability) {
+    const row = projectionRow(contribution, command, projection.order, availability);
+    const semanticRow = row.action === undefined
+        ? row
+        : { ...row, action: semanticAction(row.action) };
+    return projection.keybind === undefined
+        ? semanticRow
+        : { ...semanticRow, keybind: projection.keybind };
+}
+function semanticAction(action) {
+    const semantic = {};
+    if (action.inputSchema !== undefined)
+        semantic.inputSchema = action.inputSchema;
+    if (action.outputSchema !== undefined)
+        semantic.outputSchema = action.outputSchema;
+    return Object.freeze(semantic);
+}