@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/blocks/actions/requests.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The actions block's wire shapes + the host service it calls (mos-p9auh;
+ * jatui-n5z1x). MOS made two session fetches to /api/v1/artifacts/[id]/
+ * actions; in jatui those are the HOST's, reached through
+ * `HostAdapter.services.actions` (an `ActionsService`). A host without one
+ * renders the actions as a quiet, labelled list — never live-looking
+ * buttons that send nowhere. Link actions (`href`) need no service.
+ */
+import type { BlockServices } from "../../types.js";
+import type { AckStatus, ActionInputs } from "./schema.js";
+/** One action request as a viewer sees it (no raw user ids). */
+export interface ActionRequestView {
+    id: string;
+    actionId: string;
+    status: AckStatus;
+    /** The agent's answer, shown under the button. */
+    note: string | null;
+    ackedBy: string | null;
+    ackedAt: string | null;
+    createdAt: string;
+    /** Who pressed it (name/email), for the "by … · time" line. */
+    viewerLabel: string | null;
+    /** True when the session viewer pressed it. */
+    mine: boolean;
+    inputs: ActionInputs;
+}
+export interface ActionsReadResponse {
+    requests: ActionRequestView[];
+    /** actionId → may THIS viewer press it (role gate). */
+    allowed: Record<string, boolean>;
+}
+/** The newest request per action id (requests arrive oldest first). */
+export declare function latestByAction(requests: ActionRequestView[]): Map<string, ActionRequestView>;
+export declare class ActionRequestError extends Error {
+    readonly status: number;
+    readonly request: ActionRequestView | null;
+    constructor(message: string, status: number, request?: ActionRequestView | null);
+}
+/**
+ * The host's leg for action requests (`HostAdapter.services.actions`).
+ * Both calls may throw any Error with a human message — the block shows
+ * it. A `send` that finds the action already open throws an error carrying
+ * that open `request` (`ActionRequestError` is one), so the block shows the
+ * existing one instead of queueing a second.
+ */
+export interface ActionsService {
+    /** This block's requests (oldest first) + which actions THIS viewer may press. */
+    load(args: {
+        artifactId: string;
+        blockId: string;
+    }): Promise<ActionsReadResponse>;
+    /** Record one request; resolves with it as the viewer sees it. */
+    send(args: {
+        artifactId: string;
+        blockId: string;
+        actionId: string;
+        inputs: ActionInputs;
+        reason?: string | null;
+    }): Promise<ActionRequestView>;
+}
+/** The actions service the host provided, or null (read-only list). */
+export declare function actionsServiceOf(services: BlockServices | undefined): ActionsService | null;

package/dist/artifact-blocks/blocks/actions/requests.js

@@ -0,0 +1,26 @@
+/** The newest request per action id (requests arrive oldest first). */
+export function latestByAction(requests) {
+    const out = new Map();
+    for (const r of requests) {
+        const prev = out.get(r.actionId);
+        if (!prev || prev.createdAt <= r.createdAt)
+            out.set(r.actionId, r);
+    }
+    return out;
+}
+export class ActionRequestError extends Error {
+    status;
+    request;
+    constructor(message, status, request = null) {
+        super(message);
+        this.status = status;
+        this.request = request;
+    }
+}
+/** The actions service the host provided, or null (read-only list). */
+export function actionsServiceOf(services) {
+    const s = services?.actions;
+    return s && typeof s.load === "function" && typeof s.send === "function"
+        ? s
+        : null;
+}

package/dist/artifact-blocks/blocks/actions/schema.d.ts

@@ -0,0 +1,168 @@
+/**
+ * actions block — params schema + the request rules both sides share
+ * (mos-p9auh, living artifacts phase 4).
+ *
+ * Pure TS, no Svelte: the session route (/api/v1/artifacts/[id]/actions)
+ * imports `validateActionRequest` from here so the server checks a click
+ * against the SAME declared fields the component rendered — the client's
+ * word about an input is never trusted on its own.
+ *
+ * An action is a REQUEST to the owning agent. MOS records it (one
+ * artifact_events row, kind 'action') and the agent answers with
+ * `mos-artifact ack`; nothing here executes anything.
+ */
+import { z } from "zod";
+/**
+ * Team roles an action may be limited to. Mirrors ROLES in MOS
+ * src/lib/teams.ts (the role names a host's team model must map onto; the
+ * host enforces them server-side, jatui only carries the declaration).
+ */
+export declare const ACTION_ROLES: readonly ["viewer", "member", "office", "provider", "admin", "owner"];
+type ActionRole = (typeof ACTION_ROLES)[number];
+/** Who may press an action when it names no `roles`: every member-rank role. */
+export declare const DEFAULT_ACTION_ROLES: readonly ActionRole[];
+export declare const actionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    intent: z.ZodOptional<z.ZodString>;
+    variant: z.ZodDefault<z.ZodEnum<{
+        primary: "primary";
+        default: "default";
+        danger: "danger";
+    }>>;
+    confirm: z.ZodOptional<z.ZodString>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"text">;
+        label: z.ZodString;
+        placeholder: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        multiline: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"number">;
+        label: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"select">;
+        label: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+    roles: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+        viewer: "viewer";
+        office: "office";
+        provider: "provider";
+    }>>>;
+    owner: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const actionsSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    owner: z.ZodOptional<z.ZodString>;
+    actions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        intent: z.ZodOptional<z.ZodString>;
+        variant: z.ZodDefault<z.ZodEnum<{
+            primary: "primary";
+            default: "default";
+            danger: "danger";
+        }>>;
+        confirm: z.ZodOptional<z.ZodString>;
+        fields: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"text">;
+            label: z.ZodString;
+            placeholder: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            multiline: z.ZodDefault<z.ZodBoolean>;
+            maxLength: z.ZodDefault<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"number">;
+            label: z.ZodString;
+            required: z.ZodDefault<z.ZodBoolean>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            step: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"select">;
+            label: z.ZodString;
+            required: z.ZodDefault<z.ZodBoolean>;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strip>>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>>;
+        roles: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+            viewer: "viewer";
+            office: "office";
+            provider: "provider";
+        }>>>;
+        owner: z.ZodOptional<z.ZodString>;
+        href: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ActionsParams = z.infer<typeof actionsSchema>;
+export type ActionDef = z.infer<typeof actionSchema>;
+export type ActionInputValue = string | number;
+export type ActionInputs = Record<string, ActionInputValue>;
+/** The ack lifecycle (mirrors the artifact_events.ack_status CHECK). */
+export declare const ACK_STATUSES: readonly ["queued", "running", "done", "failed"];
+export type AckStatus = (typeof ACK_STATUSES)[number];
+/** A link action (PARAMS-SPEC §2): navigates, never sends a request. */
+export declare function isLinkAction(action: ActionDef): action is ActionDef & {
+    href: string;
+};
+/** Does a link leave this origin (→ new tab)? Root-relative and `#` stay. */
+export declare function isOffOrigin(href: string, origin?: string): boolean;
+export declare function isTerminal(status: AckStatus): boolean;
+/** The intent the agent switches on: explicit intent, else the action id. */
+export declare function intentOf(action: ActionDef): string;
+/** May a viewer with this team role press this action? */
+export declare function roleMayAct(action: ActionDef, role: string | null): boolean;
+export type ActionRequestCheck = {
+    ok: true;
+    inputs: ActionInputs;
+    reason: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Check ONE request against the action it names: every declared field is
+ * coerced and range/option-checked, undeclared inputs are dropped (never
+ * forwarded to the agent), and a danger action demands a typed reason.
+ * The server's authority; the component runs it too so the viewer sees the
+ * same message before a round-trip (`fieldsOnly` = check the form before
+ * the danger confirm opens, when no reason has been typed yet).
+ */
+export declare function validateActionRequest(action: ActionDef, rawInputs: unknown, rawReason: unknown, opts?: {
+    fieldsOnly?: boolean;
+}): ActionRequestCheck;
+export {};

package/dist/artifact-blocks/blocks/actions/schema.js

@@ -0,0 +1,253 @@
+/**
+ * actions block — params schema + the request rules both sides share
+ * (mos-p9auh, living artifacts phase 4).
+ *
+ * Pure TS, no Svelte: the session route (/api/v1/artifacts/[id]/actions)
+ * imports `validateActionRequest` from here so the server checks a click
+ * against the SAME declared fields the component rendered — the client's
+ * word about an input is never trusted on its own.
+ *
+ * An action is a REQUEST to the owning agent. MOS records it (one
+ * artifact_events row, kind 'action') and the agent answers with
+ * `mos-artifact ack`; nothing here executes anything.
+ */
+import { z } from "zod";
+import { linkUrlSchema, shortTextSchema } from "../../params.js";
+/** Ids are stable across republishes: request history keys on them. */
+const idSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "must be lowercase a-z0-9_- (max 64), starting with a letter or digit");
+/**
+ * Team roles an action may be limited to. Mirrors ROLES in MOS
+ * src/lib/teams.ts (the role names a host's team model must map onto; the
+ * host enforces them server-side, jatui only carries the declaration).
+ */
+export const ACTION_ROLES = [
+    "viewer",
+    "member",
+    "office",
+    "provider",
+    "admin",
+    "owner",
+];
+/** Who may press an action when it names no `roles`: every member-rank role. */
+export const DEFAULT_ACTION_ROLES = [
+    "member",
+    "office",
+    "provider",
+    "admin",
+    "owner",
+];
+/** Hard cap on one text input's value. */
+const MAX_TEXT_INPUT = 2000;
+/** A danger action's typed reason: at least this many characters. */
+const MIN_DANGER_REASON = 4;
+const MAX_DANGER_REASON = 500;
+const textField = z.object({
+    id: idSchema,
+    type: z.literal("text"),
+    label: shortTextSchema.min(1),
+    placeholder: shortTextSchema.optional(),
+    required: z.boolean().default(false),
+    /** Renders a textarea instead of a single-line input. */
+    multiline: z.boolean().default(false),
+    maxLength: z.number().int().min(1).max(MAX_TEXT_INPUT).default(500),
+    default: z.string().max(MAX_TEXT_INPUT).optional(),
+});
+const numberField = z
+    .object({
+    id: idSchema,
+    type: z.literal("number"),
+    label: shortTextSchema.min(1),
+    required: z.boolean().default(false),
+    min: z.number().finite().optional(),
+    max: z.number().finite().optional(),
+    step: z.number().positive().finite().optional(),
+    default: z.number().finite().optional(),
+})
+    .refine((f) => f.min === undefined || f.max === undefined || f.min <= f.max, {
+    message: "min must be <= max",
+    path: ["min"],
+});
+const selectField = z
+    .object({
+    id: idSchema,
+    type: z.literal("select"),
+    label: shortTextSchema.min(1),
+    required: z.boolean().default(false),
+    options: z
+        .array(z.object({
+        value: z.string().min(1).max(120),
+        label: shortTextSchema.min(1),
+    }))
+        .min(1)
+        .max(30),
+    default: z.string().max(120).optional(),
+})
+    .refine((f) => new Set(f.options.map((o) => o.value)).size === f.options.length, { message: "option values must be unique", path: ["options"] })
+    .refine((f) => f.default === undefined || f.options.some((o) => o.value === f.default), { message: "default must be one of the option values", path: ["default"] });
+const actionFieldSchema = z.discriminatedUnion("type", [
+    textField,
+    numberField,
+    selectField,
+]);
+export const actionSchema = z
+    .object({
+    id: idSchema,
+    /** The button text. */
+    label: z.string().trim().min(1).max(80),
+    /** One line under the button: what pressing it asks the agent to do. */
+    description: z.string().max(500).optional(),
+    /**
+     * The machine-readable intent the agent switches on, e.g.
+     * "rerun-scenario:ruby_office_switch". Defaults to the action id.
+     */
+    intent: z.string().trim().min(1).max(200).optional(),
+    /** primary = the obvious next step; danger = confirm + typed reason. */
+    variant: z.enum(["default", "primary", "danger"]).default("default"),
+    /** Extra confirm copy shown before a danger request is sent. */
+    confirm: z.string().max(500).optional(),
+    /** Small form the viewer fills before sending (max 8 fields). */
+    fields: z.array(actionFieldSchema).max(8).default([]),
+    /**
+     * Team roles allowed to press it (exact list). Omitted = every
+     * member-rank role; a viewer-role seat can never act unless listed.
+     */
+    roles: z.array(z.enum(ACTION_ROLES)).min(1).max(6).optional(),
+    /** Route this action's requests to a different agent than the block's. */
+    owner: z.string().trim().min(1).max(80).optional(),
+    /**
+     * PARAMS-SPEC §2 (jat-j49id): set → the action is a LINK, not a
+     * request. It renders as an `<a>` to this url (http(s) or
+     * root-relative; off-origin opens in a new tab), fires no event, and
+     * ignores intent / fields / confirm / roles / owner — no team role is
+     * needed to follow a link. It works on read-only surfaces too.
+     */
+    href: linkUrlSchema.optional(),
+})
+    .refine((a) => new Set(a.fields.map((f) => f.id)).size === a.fields.length, {
+    message: "field ids must be unique within an action",
+    path: ["fields"],
+});
+export const actionsSchema = z
+    .object({
+    title: shortTextSchema.optional(),
+    description: z.string().max(1000).optional(),
+    /**
+     * The agent that hears these requests (falls back to the block-level
+     * owner, then the artifact publisher). Read SERVER-SIDE only.
+     */
+    owner: z.string().trim().min(1).max(80).optional(),
+    actions: z.array(actionSchema).min(1).max(12),
+})
+    .refine((p) => new Set(p.actions.map((a) => a.id)).size === p.actions.length, { message: "action ids must be unique", path: ["actions"] });
+/** The ack lifecycle (mirrors the artifact_events.ack_status CHECK). */
+export const ACK_STATUSES = ["queued", "running", "done", "failed"];
+/** A link action (PARAMS-SPEC §2): navigates, never sends a request. */
+export function isLinkAction(action) {
+    return typeof action.href === "string" && action.href.length > 0;
+}
+/** Does a link leave this origin (→ new tab)? Root-relative and `#` stay. */
+export function isOffOrigin(href, origin) {
+    if (!/^https?:\/\//i.test(href))
+        return false;
+    if (!origin)
+        return true;
+    try {
+        return new URL(href).origin !== origin;
+    }
+    catch {
+        return true;
+    }
+}
+const TERMINAL_ACK = ["done", "failed"];
+export function isTerminal(status) {
+    return TERMINAL_ACK.includes(status);
+}
+/** The intent the agent switches on: explicit intent, else the action id. */
+export function intentOf(action) {
+    return action.intent ?? action.id;
+}
+/** May a viewer with this team role press this action? */
+export function roleMayAct(action, role) {
+    if (!role)
+        return false;
+    const allowed = action.roles ?? DEFAULT_ACTION_ROLES;
+    return allowed.includes(role);
+}
+/**
+ * Check ONE request against the action it names: every declared field is
+ * coerced and range/option-checked, undeclared inputs are dropped (never
+ * forwarded to the agent), and a danger action demands a typed reason.
+ * The server's authority; the component runs it too so the viewer sees the
+ * same message before a round-trip (`fieldsOnly` = check the form before
+ * the danger confirm opens, when no reason has been typed yet).
+ */
+export function validateActionRequest(action, rawInputs, rawReason, opts = {}) {
+    const given = typeof rawInputs === "object" &&
+        rawInputs !== null &&
+        !Array.isArray(rawInputs)
+        ? rawInputs
+        : {};
+    const inputs = {};
+    for (const field of action.fields) {
+        const raw = given[field.id];
+        const empty = raw === undefined ||
+            raw === null ||
+            (typeof raw === "string" && raw.trim() === "");
+        if (empty) {
+            if (field.required)
+                return { ok: false, error: `${field.label} is required` };
+            continue;
+        }
+        if (field.type === "text") {
+            if (typeof raw !== "string")
+                return { ok: false, error: `${field.label} must be text` };
+            const v = raw.trim();
+            if (v.length > field.maxLength)
+                return {
+                    ok: false,
+                    error: `${field.label} is longer than ${field.maxLength} characters`,
+                };
+            inputs[field.id] = v;
+        }
+        else if (field.type === "number") {
+            const n = typeof raw === "number" ? raw : Number(String(raw).trim());
+            if (!Number.isFinite(n))
+                return { ok: false, error: `${field.label} must be a number` };
+            if (field.min !== undefined && n < field.min)
+                return {
+                    ok: false,
+                    error: `${field.label} must be at least ${field.min}`,
+                };
+            if (field.max !== undefined && n > field.max)
+                return {
+                    ok: false,
+                    error: `${field.label} must be at most ${field.max}`,
+                };
+            inputs[field.id] = n;
+        }
+        else {
+            if (typeof raw !== "string" ||
+                !field.options.some((o) => o.value === raw))
+                return { ok: false, error: `${field.label}: pick one of the options` };
+            inputs[field.id] = raw;
+        }
+    }
+    let reason = null;
+    if (action.variant === "danger" && !opts.fieldsOnly) {
+        const r = typeof rawReason === "string" ? rawReason.trim() : "";
+        if (r.length < MIN_DANGER_REASON)
+            return {
+                ok: false,
+                error: "This action needs a reason (a few words on why) before it is sent",
+            };
+        if (r.length > MAX_DANGER_REASON)
+            return {
+                ok: false,
+                error: `The reason is longer than ${MAX_DANGER_REASON} characters`,
+            };
+        reason = r;
+    }
+    return { ok: true, inputs, reason };
+}