@skaile/forge-app-actions 0.0.0-stage → 0.2.0

package/src/runtime/composables/usePaletteArgStep.ts

@@ -0,0 +1,110 @@
+/**
+ * The command palette's **argument step**.
+ *
+ * A `PaletteAction` that declares `arg` needs one string before it can run
+ * (`defineForgeAction`'s `arg.toInput` turns that string into the action's
+ * typed input). Selecting such an action does not close the palette: it swaps
+ * the list for the action's candidates and waits for a second Enter.
+ *
+ * This holds the per-component state for that step. It lives here rather than
+ * inline in the components because both UI-kit variants of
+ * `ForgeCommandPalette` run it and are kept in deliberate lock-step — one copy
+ * cannot drift from the other if there is only one copy.
+ *
+ * Not a singleton: `useCommandPalette()` owns the shared registry, this owns
+ * one palette instance's transient step.
+ */
+
+import { type ComputedRef, computed, type Ref, ref, type ShallowRef, shallowRef } from "vue";
+import type { PaletteAction, PaletteArgOption, PaletteArgPrompt } from "../types/command-palette";
+
+export interface UsePaletteArgStepReturn {
+  /** The action awaiting its argument, or `null` when the step is not active. */
+  action: ShallowRef<PaletteAction | null>;
+  /** Candidates for the current query. Empty for a free-text argument. */
+  options: ShallowRef<PaletteArgOption[]>;
+  /** Whether a candidate lookup is in flight. */
+  loading: Ref<boolean>;
+  /** Whether the palette is currently collecting an argument. */
+  active: ComputedRef<boolean>;
+  /** The active action's prompt declaration. */
+  prompt: ComputedRef<PaletteArgPrompt | null>;
+  /**
+   * Enter the argument step for `action`. Returns `false` — and changes
+   * nothing — when the action takes no argument, so a caller can use it as
+   * `if (!begin(a)) { close(); run(a) }`.
+   */
+  begin(action: PaletteAction): boolean;
+  /** Recompute the candidates for `query`. Stale responses are discarded. */
+  query(query: string): Promise<void>;
+  /** Leave the step without running anything. */
+  cancel(): void;
+  /**
+   * The string the action should run with, given what is typed and which row is
+   * highlighted — or `null` when the step cannot complete yet (nothing typed
+   * and nothing highlighted, or a typed value the prompt does not accept).
+   */
+  valueFor(typed: string, index: number): string | null;
+}
+
+export function usePaletteArgStep(): UsePaletteArgStepReturn {
+  const action = shallowRef<PaletteAction | null>(null);
+  const options = shallowRef<PaletteArgOption[]>([]);
+  const loading = ref(false);
+  // Monotonic ticket: an `options()` provider is async and the user keeps
+  // typing, so only the newest lookup may write. Same discipline as
+  // useFileSearch's AbortController, without assuming the provider does I/O.
+  let ticket = 0;
+
+  const active = computed(() => action.value !== null);
+  const prompt = computed(() => action.value?.arg ?? null);
+
+  function begin(next: PaletteAction): boolean {
+    if (!next.arg) return false;
+    action.value = next;
+    options.value = [];
+    void query("");
+    return true;
+  }
+
+  async function query(text: string): Promise<void> {
+    const arg = action.value?.arg;
+    if (!arg?.options) {
+      options.value = [];
+      return;
+    }
+    const mine = ++ticket;
+    loading.value = true;
+    try {
+      const found = await arg.options(text);
+      if (mine !== ticket) return; // superseded by a newer keystroke
+      options.value = found;
+    } catch {
+      // A failing lookup is "no candidates", never a broken palette. The user
+      // can still type a value when the prompt allows it.
+      if (mine === ticket) options.value = [];
+    } finally {
+      if (mine === ticket) loading.value = false;
+    }
+  }
+
+  function cancel(): void {
+    ticket++; // orphan any in-flight lookup
+    action.value = null;
+    options.value = [];
+    loading.value = false;
+  }
+
+  function valueFor(typed: string, index: number): string | null {
+    const arg = action.value?.arg;
+    if (!arg) return null;
+    const picked = options.value[index];
+    if (picked) return picked.value;
+    const allowCustom = arg.allowCustom ?? !arg.options;
+    const trimmed = typed.trim();
+    if (allowCustom && trimmed.length > 0) return trimmed;
+    return null;
+  }
+
+  return { action, options, loading, active, prompt, begin, query, cancel, valueFor };
+}

package/src/runtime/internal/describe-error.ts

@@ -0,0 +1,21 @@
+/**
+ * Turn a thrown value into the single line the agent (or model) will read.
+ *
+ * A zod v4 error carries the useful part in `issues`; `err.message` alone is a
+ * JSON blob. Flatten it to `path: message` pairs so the model can act on it.
+ *
+ * Lives outside `composables/` on purpose: that directory is auto-imported by
+ * the Nuxt module, and this helper is internal.
+ */
+export function describeError(err: unknown): string {
+  if (err && typeof err === "object" && Array.isArray((err as { issues?: unknown }).issues)) {
+    const issues = (err as { issues: Array<{ path?: unknown[]; message?: string }> }).issues;
+    const lines = issues.map((issue) => {
+      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+      return path ? `${path}: ${issue.message}` : String(issue.message);
+    });
+    if (lines.length > 0) return lines.join("; ");
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/runtime/server/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Explicit entry point for the server-side client-capability bridge, via the
+ * `./server` subpath. In a Nuxt consumer the same symbols are auto-imported
+ * (the module's `addServerImportsDir` on `runtime/server/utils`).
+ */
+
+export * from "./utils/capability-registry";
+export * from "./utils/client-capability-bridge";

package/src/runtime/server/utils/capability-registry.ts

@@ -0,0 +1,66 @@
+// server/utils/capability-registry.ts
+import type { AgentEvent, Capability } from "@skaile/workspaces/sdk/types";
+
+/** Event sink handed to a capability handler when it runs. */
+export interface CapabilityHandlerCtx {
+  /** Emit a synthetic AgentEvent into the app's SSE stream. */
+  emitEvent: (event: AgentEvent) => void;
+}
+
+export type CapabilityHandler = (
+  input: Record<string, unknown>,
+  ctx: CapabilityHandlerCtx,
+) => Promise<unknown>;
+
+export interface CapabilityEntry {
+  capability: Capability;
+  handler: CapabilityHandler;
+}
+
+/**
+ * Plain-TS capability registry for the forge app — holds client-side v2
+ * capabilities and routes `capability_invoked` calls to their handlers.
+ */
+export class CapabilityRegistry {
+  private entries = new Map<string, CapabilityEntry>();
+
+  register(entry: CapabilityEntry): void {
+    this.entries.set(entry.capability.name, entry);
+  }
+
+  list(): Capability[] {
+    return [...this.entries.values()].map((e) => e.capability);
+  }
+
+  async dispatch(
+    name: string,
+    input: Record<string, unknown>,
+    ctx: CapabilityHandlerCtx,
+  ): Promise<unknown | { error: string }> {
+    const entry = this.entries.get(name);
+    if (!entry) return { error: `Unknown capability: ${name}` };
+    try {
+      return await entry.handler(input, ctx);
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+/** Dispatch a `capability_invoked` event and send back its `capability_result`. */
+export async function handleCapabilityInvoked(
+  event: { callId: string; name: string; input: unknown },
+  deps: {
+    registry: CapabilityRegistry;
+    ctx: CapabilityHandlerCtx;
+    sendResult: (callId: string, result: unknown) => Promise<void> | void;
+  },
+): Promise<void> {
+  const input =
+    event.input && typeof event.input === "object" ? (event.input as Record<string, unknown>) : {};
+  const result = await deps.registry.dispatch(event.name, input, deps.ctx);
+  await deps.sendResult(event.callId, result);
+}
+
+/** Process-wide singleton — capabilities are registered once at module load. */
+export const capabilityRegistry = new CapabilityRegistry();