@skaile/forge-app-actions 0.2.1 → 0.4.0

package/src/runtime/server/utils/server-actions.ts

@@ -0,0 +1,198 @@
+// server/utils/server-actions.ts
+//
+// NOTE: this file must live *directly* in `runtime/server/utils/`. The Nuxt
+// module auto-imports that directory NON-recursively (see
+// `client-capability-bridge.ts`), so a subdirectory would silently never reach
+// consumers.
+//
+// Server actions are headless: they run in Nitro, have no palette row and no
+// browser round-trip. They are the unit the `./mcp` projection exposes as MCP
+// tools. Browser actions (`defineForgeAction`) are unaffected.
+
+import * as z from "zod";
+
+/** Who may be offered an action: people/CLIs (`user`) and/or models (`llm`). Exposure control, not authorization. */
+export type ServerActionAudience = "user" | "llm";
+
+const AUDIENCES: readonly ServerActionAudience[] = ["user", "llm"];
+
+/**
+ * What an action sees. The core fixes no principal shape: `P` is whatever the
+ * app's transport hook resolved, `D` whatever dependencies it injects.
+ */
+export interface ServerActionContext<P = unknown, D = unknown> {
+  /** Canonical capability name `app.<id>`, derived by `run`; never taken from the caller. */
+  name: string;
+  /** What the transport's authorize hook set as `principal` (MCP: `forge-app-actions:mcp:authorize`). */
+  principal: P;
+  /** Host event (under Nitro an `H3Event`); apps pass it on to their server utils. */
+  event: unknown;
+  /** What the transport's authorize hook set as `deps`, e.g. injected service clients. */
+  deps: D;
+}
+
+/**
+ * The caller-supplied part of a context. `run` derives `name` itself and
+ * ignores one passed here.
+ */
+export type ServerActionScope<P = unknown, D = unknown> = Omit<ServerActionContext<P, D>, "name">;
+
+export interface DefineServerActionArgs<
+  Id extends string,
+  T extends z.ZodType,
+  P = unknown,
+  D = unknown,
+  R = unknown,
+> {
+  /** Without the `app.` prefix, e.g. `trainings.create`; the name becomes `app.<id>`. An id starting with `app.` throws. */
+  id: Id;
+  /** Description the model reads. Required; empty throws. */
+  description: string;
+  /** Zod schema of the input. Defaults to `z.object({})`. */
+  input?: T;
+  /** Documentation only, as with `defineForgeAction`. Defaults to `"effect"`. */
+  kind?: "effect" | "query";
+  /** Who is offered the action. Defaults to both; an empty array throws. */
+  audience?: readonly ServerActionAudience[];
+  /**
+   * Runs after the input parsed and before the handler, with the canonical
+   * context. Throw to deny (an error with a numeric `statusCode` keeps it);
+   * the handler then does not run. Read the current authority here, not from a
+   * value captured earlier.
+   */
+  authorize?: (input: z.infer<T>, ctx: ServerActionContext<P, D>) => void | Promise<void>;
+  run: (input: z.infer<T>, ctx: ServerActionContext<P, D>) => R;
+}
+
+export interface ServerAction<Id extends string = string, I = unknown, O = unknown> {
+  id: Id;
+  name: string;
+  description: string;
+  kind: "effect" | "query";
+  readonly audience: readonly ServerActionAudience[];
+  readonly inputZod: z.ZodType;
+  /** `z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })` without `$schema`. */
+  inputSchema: Record<string, unknown>;
+  /** Type-level only: never set at runtime. Read it through `ActionInput` / `ActionOutput`. */
+  readonly types?: { input: I; output: O };
+  /**
+   * Parses `input` through `inputZod` once (a `ZodError` propagates), awaits
+   * `authorize` (a rejection propagates and nothing ran), then calls the handler.
+   * The context's `name` is always `app.<id>`; a `name` in `ctx` is ignored.
+   */
+  run(input: unknown, ctx: ServerActionScope & { name?: string }): Promise<unknown>;
+}
+
+/** The input type an action accepts (`z.input` of its schema). */
+export type ActionInput<A> = A extends ServerAction<string, infer I, unknown> ? I : never;
+
+/** The output type an action resolves to. */
+export type ActionOutput<A> = A extends ServerAction<string, unknown, infer O> ? O : never;
+
+/** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
+function withoutSchemaKey(schema: Record<string, unknown>): Record<string, unknown> {
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+}
+
+export function defineServerAction<
+  const Id extends string,
+  T extends z.ZodType = z.ZodObject<Record<string, never>>,
+  P = unknown,
+  D = unknown,
+  R = unknown,
+>(args: DefineServerActionArgs<Id, T, P, D, R>): ServerAction<Id, z.input<T>, Awaited<R>> {
+  const { id } = args;
+  if (!id || id.trim().length === 0) {
+    throw new Error("defineServerAction: an action needs a non-empty id.");
+  }
+  if (id.startsWith("app.")) {
+    throw new Error(
+      `defineServerAction("${id}"): the id must not carry the \`app.\` prefix — it is added ` +
+        `automatically to derive the action name. Use "${id.slice(4)}".`,
+    );
+  }
+  if (!args.description || args.description.trim().length === 0) {
+    throw new Error(
+      `defineServerAction("${id}"): a server action must declare a description — the model reads it.`,
+    );
+  }
+  const requested = args.audience ?? AUDIENCES;
+  if (requested.length === 0 || requested.some((entry) => !AUDIENCES.includes(entry))) {
+    throw new Error(
+      `defineServerAction("${id}"): audience must be a non-empty subset of ${JSON.stringify(AUDIENCES)}.`,
+    );
+  }
+  const audience = Object.freeze([...new Set(requested)]);
+
+  const inputZod: z.ZodType = args.input ?? z.object({});
+  const inputSchema = withoutSchemaKey(
+    z.toJSONSchema(inputZod, { target: "draft-07", io: "input" }) as Record<string, unknown>,
+  );
+  const name = `app.${id}`;
+
+  return {
+    id,
+    name,
+    description: args.description,
+    kind: args.kind ?? "effect",
+    audience,
+    inputZod,
+    inputSchema,
+    async run(input, ctx) {
+      const parsed = inputZod.parse(input) as z.infer<T>;
+      const context = { ...ctx, name } as ServerActionContext<P, D>;
+      await args.authorize?.(parsed, context);
+      return await args.run(parsed, context);
+    },
+  };
+}
+
+/**
+ * `defineServerAction` with the app's principal and deps types bound once, so
+ * handlers and `authorize` callbacks are typed without annotating every definition.
+ */
+export function createServerActionDefiner<P = unknown, D = unknown>() {
+  return <
+    const Id extends string,
+    T extends z.ZodType = z.ZodObject<Record<string, never>>,
+    R = unknown,
+  >(
+    args: DefineServerActionArgs<Id, T, P, D, R>,
+  ): ServerAction<Id, z.input<T>, Awaited<R>> => defineServerAction<Id, T, P, D, R>(args);
+}
+
+/** The actions offered to `audience`, in order. Element types are kept, so a typed catalogue stays typed. */
+export function forAudience<A extends ServerAction>(
+  actions: readonly A[],
+  audience: ServerActionAudience,
+): A[] {
+  return actions.filter((action) => action.audience.includes(audience));
+}
+
+export class ServerActionRegistry {
+  private readonly actions = new Map<string, ServerAction>();
+
+  register(action: ServerAction): void {
+    if (this.actions.has(action.name)) {
+      throw new Error(`Server action already registered: ${action.name}`);
+    }
+    this.actions.set(action.name, action);
+  }
+
+  registerAll(actions: readonly ServerAction[]): void {
+    for (const action of actions) this.register(action);
+  }
+
+  /** In registration order. */
+  list(): ServerAction[] {
+    return [...this.actions.values()];
+  }
+
+  get(name: string): ServerAction | undefined {
+    return this.actions.get(name);
+  }
+}
+
+/** Process-wide singleton, like `capabilityRegistry`. */
+export const serverActionRegistry = new ServerActionRegistry();