@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/views/metadata-admin/previews/FlowRunsPanel.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * FlowRunsPanel — run history for a flow, fetched from the automation engine
+ * (`GET /api/v1/automation/{name}/runs`, the observability surface next to
+ * resume/screen). Renders each run's status / start time / duration with an
+ * expandable per-node step log (the `ExecutionLog.steps` ADR-0019/#1479 shape),
+ * so authors can see where a run paused or failed without leaving the Studio.
+ *
+ * Degrades like the palette fetch: offline / plugin-absent / older backend →
+ * a quiet "history unavailable" note, never an error state that blocks the
+ * designer.
+ */
+import * as React from 'react';
+import { AlertCircle, CheckCircle2, ChevronDown, ChevronRight, Clock, Loader2, PauseCircle, RefreshCw, SkipForward } from 'lucide-react';
+import { cn } from '@object-ui/components';
+import { apiBase } from './useFlowNodePalette';
+/** Fetch a flow's run history. Exposed for tests. */
+export async function fetchFlowRuns(flowName, signal) {
+    try {
+        const res = await fetch(`${apiBase()}/automation/${encodeURIComponent(flowName)}/runs?limit=25`, { credentials: 'include', headers: { 'Content-Type': 'application/json' }, signal });
+        if (!res.ok)
+            return null; // 404/501 — plugin absent or older backend
+        const payload = (await res.json());
+        const runs = payload?.data?.runs ?? payload?.runs;
+        return Array.isArray(runs) ? runs : null;
+    }
+    catch {
+        return null; // offline / aborted
+    }
+}
+const STATUS_META = {
+    completed: { icon: CheckCircle2, cls: 'text-emerald-600 dark:text-emerald-400', label: 'Completed' },
+    failed: { icon: AlertCircle, cls: 'text-rose-600 dark:text-rose-400', label: 'Failed' },
+    paused: { icon: PauseCircle, cls: 'text-amber-600 dark:text-amber-400', label: 'Paused' },
+    running: { icon: Loader2, cls: 'text-sky-600 dark:text-sky-400', label: 'Running' },
+    cancelled: { icon: SkipForward, cls: 'text-muted-foreground', label: 'Cancelled' },
+};
+function statusMeta(status) {
+    return STATUS_META[status] ?? { icon: Clock, cls: 'text-muted-foreground', label: status };
+}
+function fmtTime(iso) {
+    if (!iso)
+        return '—';
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
+}
+function fmtDuration(ms) {
+    if (ms == null)
+        return null;
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.round(ms / 60000)}m`;
+}
+function StepRow({ step }) {
+    const cls = step.status === 'success'
+        ? 'text-emerald-600 dark:text-emerald-400'
+        : step.status === 'failure'
+            ? 'text-rose-600 dark:text-rose-400'
+            : 'text-muted-foreground';
+    return (_jsxs("li", { className: "flex items-baseline gap-1.5 py-0.5", children: [_jsx("span", { className: cn('shrink-0 text-[9px] font-semibold uppercase', cls), children: step.status }), _jsx("span", { className: "truncate font-mono text-[10px]", title: step.nodeId, children: step.nodeId }), step.nodeType && _jsx("span", { className: "shrink-0 text-[9px] uppercase text-muted-foreground", children: step.nodeType }), fmtDuration(step.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[9px] text-muted-foreground", children: fmtDuration(step.durationMs) })), step.error?.message && (_jsx("span", { className: "min-w-0 truncate text-[9px] text-rose-600", title: step.error.message, children: step.error.message }))] }));
+}
+function RunRow({ run }) {
+    const [open, setOpen] = React.useState(false);
+    const meta = statusMeta(run.status);
+    const Icon = meta.icon;
+    const steps = Array.isArray(run.steps) ? run.steps : [];
+    return (_jsxs("li", { className: "rounded border bg-background", children: [_jsxs("button", { type: "button", onClick: () => setOpen((v) => !v), className: "flex w-full items-center gap-1.5 p-1.5 text-left", "aria-expanded": open, children: [open ? (_jsx(ChevronDown, { className: "h-3 w-3 shrink-0 text-muted-foreground" })) : (_jsx(ChevronRight, { className: "h-3 w-3 shrink-0 text-muted-foreground" })), _jsx(Icon, { className: cn('h-3.5 w-3.5 shrink-0', meta.cls, run.status === 'running' && 'animate-spin') }), _jsx("span", { className: cn('shrink-0 text-[10px] font-semibold', meta.cls), children: meta.label }), _jsx("span", { className: "min-w-0 truncate text-[10px] text-muted-foreground", title: run.id, children: fmtTime(run.startedAt) }), fmtDuration(run.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground", children: fmtDuration(run.durationMs) }))] }), open && (_jsxs("div", { className: "border-t px-2 py-1.5", children: [_jsxs("div", { className: "pb-1 font-mono text-[9px] text-muted-foreground", title: run.id, children: ["run ", run.id, run.trigger?.type && ` · trigger ${run.trigger.type}`] }), run.error?.message && (_jsx("div", { className: "pb-1 text-[10px] text-rose-600", children: run.error.message })), steps.length === 0 ? (_jsx("div", { className: "text-[10px] italic text-muted-foreground", children: "No step log recorded." })) : (_jsx("ul", { className: "divide-y divide-border/50", children: steps.map((s, i) => (_jsx(StepRow, { step: s }, `${s.nodeId}#${i}`))) }))] }))] }));
+}
+export function FlowRunsPanel({ flowName }) {
+    const [runs, setRuns] = React.useState([]);
+    const [state, setState] = React.useState('loading');
+    const [reloadKey, setReloadKey] = React.useState(0);
+    React.useEffect(() => {
+        const controller = new AbortController();
+        let alive = true;
+        setState('loading');
+        (async () => {
+            const result = await fetchFlowRuns(flowName, controller.signal);
+            if (!alive)
+                return;
+            if (result === null)
+                setState('unavailable');
+            else {
+                setRuns(result);
+                setState('ready');
+            }
+        })();
+        return () => {
+            alive = false;
+            controller.abort();
+        };
+    }, [flowName, reloadKey]);
+    return (_jsxs("div", { className: "flex h-full flex-col p-3 text-xs", children: [_jsxs("div", { className: "flex items-center gap-1.5 pb-2 font-medium text-muted-foreground", children: [_jsx(Clock, { className: "h-3 w-3" }), " Runs", _jsx("button", { type: "button", onClick: () => setReloadKey((k) => k + 1), title: "Refresh run history", "aria-label": "Refresh run history", className: "ml-auto rounded p-0.5 text-muted-foreground transition-colors hover:bg-muted/50 hover:text-foreground", children: _jsx(RefreshCw, { className: cn('h-3 w-3', state === 'loading' && 'animate-spin') }) })] }), state === 'unavailable' ? (_jsx("div", { className: "italic text-muted-foreground", children: "Run history unavailable \u2014 the automation engine is offline or this flow hasn\u2019t been published." })) : state === 'ready' && runs.length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "No runs yet." })) : (_jsx("ul", { className: "min-h-0 flex-1 space-y-1.5 overflow-y-auto", children: runs.map((r) => (_jsx(RunRow, { run: r }, r.id))) }))] }));
+}

package/dist/views/metadata-admin/previews/FlowSimulatorPanel.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FlowSimulatorPanel — the designer-time debug runner UI. Drives a
+ * `FlowSimulator` (pure engine) and lifts its highlight state up so the canvas
+ * can paint the active node / traversed edges. Side effects are mocked; the
+ * panel only collects the flow's input variables as the run seed.
+ */
+import * as React from 'react';
+import type { SimEdge, SimNode } from './simulator/flow-sim-types';
+export interface FlowVariableDecl {
+    name: string;
+    type?: string;
+    defaultValue?: unknown;
+    isInput?: boolean;
+}
+export interface FlowSimulatorPanelProps {
+    nodes: SimNode[];
+    edges: SimEdge[];
+    variables: FlowVariableDecl[];
+    onRunStateChange?: (s: {
+        activeNodeId: string | null;
+        visitedNodeIds: string[];
+        traversedEdgeIds: string[];
+    } | null) => void;
+}
+export declare function FlowSimulatorPanel({ nodes, edges, variables, onRunStateChange }: FlowSimulatorPanelProps): React.JSX.Element;

package/dist/views/metadata-admin/previews/FlowSimulatorPanel.js

@@ -0,0 +1,170 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * FlowSimulatorPanel — the designer-time debug runner UI. Drives a
+ * `FlowSimulator` (pure engine) and lifts its highlight state up so the canvas
+ * can paint the active node / traversed edges. Side effects are mocked; the
+ * panel only collects the flow's input variables as the run seed.
+ */
+import * as React from 'react';
+import { Play, StepForward, RotateCcw, ChevronRight, AlertTriangle, CircleAlert, Plus, Trash2 } from 'lucide-react';
+import { Button, Input, Label, cn } from '@object-ui/components';
+import { FlowSimulator } from './simulator/flow-simulator';
+/** Coerce a free-text seed value: number / boolean / JSON object|array / string. */
+function parseSeed(raw) {
+    const s = raw.trim();
+    if (s === '')
+        return undefined;
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    if ((s.startsWith('{') && s.endsWith('}')) || (s.startsWith('[') && s.endsWith(']'))) {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+}
+/** Node types whose side effects are mocked — authors can pin their output. */
+const MOCKABLE = new Set([
+    'create_record',
+    'update_record',
+    'delete_record',
+    'get_record',
+    'http_request',
+    'connector_action',
+    'script',
+]);
+function mockableNodes(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        if (!MOCKABLE.has(n.type))
+            continue;
+        const cfg = (n.config ?? {});
+        const outputs = [];
+        if (typeof cfg.outputVariable === 'string' && cfg.outputVariable)
+            outputs.push(cfg.outputVariable);
+        if (Array.isArray(cfg.outputVariables)) {
+            for (const o of cfg.outputVariables)
+                if (typeof o === 'string')
+                    outputs.push(o);
+        }
+        out.push({ id: n.id, label: n.label || n.id, type: n.type, outputs });
+    }
+    return out;
+}
+const STATUS_TONE = {
+    ok: 'bg-emerald-100 text-emerald-700',
+    mocked: 'bg-violet-100 text-violet-700',
+    paused: 'bg-amber-100 text-amber-700',
+    skipped: 'bg-zinc-100 text-zinc-600',
+    error: 'bg-rose-100 text-rose-700',
+};
+export function FlowSimulatorPanel({ nodes, edges, variables, onRunStateChange }) {
+    const simRef = React.useRef(null);
+    const [snapshot, setSnapshot] = React.useState(null);
+    const [validation, setValidation] = React.useState(null);
+    const inputs = React.useMemo(() => variables.filter((v) => v.isInput), [variables]);
+    const mockNodes = React.useMemo(() => mockableNodes(nodes), [nodes]);
+    const [seed, setSeed] = React.useState({});
+    /** Free-form variable overrides so any branch can be exercised (e.g. a
+     * decision that reads a computed value no input declares). */
+    const [scratch, setScratch] = React.useState([]);
+    /** Per-node mock outputs, keyed by node id (raw text, parsed on run). */
+    const [mocks, setMocks] = React.useState({});
+    const sync = React.useCallback(() => {
+        const sim = simRef.current;
+        if (!sim)
+            return;
+        const st = sim.state;
+        setSnapshot({
+            ...st,
+            steps: [...st.steps],
+            variables: { ...st.variables },
+            frontier: [...st.frontier],
+            visitedNodeIds: [...st.visitedNodeIds],
+            traversedEdgeIds: [...st.traversedEdgeIds],
+        });
+        onRunStateChange?.({
+            activeNodeId: st.activeNodeId,
+            visitedNodeIds: [...st.visitedNodeIds],
+            traversedEdgeIds: [...st.traversedEdgeIds],
+        });
+    }, [onRunStateChange]);
+    const buildSeed = React.useCallback(() => {
+        const out = {};
+        for (const v of inputs) {
+            const raw = seed[v.name];
+            const parsed = raw != null ? parseSeed(raw) : undefined;
+            out[v.name] = parsed !== undefined ? parsed : v.defaultValue;
+        }
+        // Scratch overrides win — they let an author drive any branch.
+        for (const row of scratch) {
+            const key = row.k.trim();
+            if (key)
+                out[key] = parseSeed(row.v);
+        }
+        return out;
+    }, [inputs, seed, scratch]);
+    const buildMocks = React.useCallback(() => {
+        const out = {};
+        for (const [id, raw] of Object.entries(mocks)) {
+            if (raw != null && raw.trim() !== '')
+                out[id] = parseSeed(raw);
+        }
+        return out;
+    }, [mocks]);
+    const reset = React.useCallback(() => {
+        const sim = new FlowSimulator(nodes, edges);
+        simRef.current = sim;
+        setValidation(sim.reset(buildSeed(), buildMocks()));
+        sync();
+    }, [nodes, edges, buildSeed, buildMocks, sync]);
+    const ensure = React.useCallback(() => {
+        if (!simRef.current)
+            reset();
+        return simRef.current;
+    }, [reset]);
+    const onRun = () => {
+        // A paused run (wait / screen) continues from where it halted. Any other
+        // state — fresh, done, or errored — starts a clean run that re-seeds with
+        // the current Set-variables and Mock-outputs editors, so editing them and
+        // pressing Run again always reflects the new values.
+        let sim = simRef.current;
+        if (sim && sim.state.status === 'paused') {
+            sim.resume();
+        }
+        else {
+            reset();
+            sim = simRef.current;
+        }
+        sim.runToEnd();
+        sync();
+    };
+    const onStep = () => {
+        const sim = ensure();
+        sim.step();
+        sync();
+    };
+    const onResume = () => {
+        const sim = ensure();
+        sim.resume();
+        sim.runToEnd();
+        sync();
+    };
+    const onReset = () => {
+        simRef.current = null;
+        setSnapshot(null);
+        setValidation(null);
+        onRunStateChange?.(null);
+    };
+    const status = snapshot?.status ?? 'idle';
+    const blocked = (validation?.errors.length ?? 0) > 0;
+    return (_jsxs("div", { className: "flex h-full flex-col text-xs", children: [_jsxs("div", { className: "flex items-center gap-1.5 border-b bg-muted/30 px-3 py-2", children: [_jsxs(Button, { size: "sm", className: "h-7 gap-1 px-2", onClick: onRun, disabled: blocked, children: [_jsx(Play, { className: "h-3.5 w-3.5" }), " Run"] }), _jsxs(Button, { size: "sm", variant: "outline", className: "h-7 gap-1 px-2", onClick: onStep, disabled: blocked || status === 'done' || status === 'error', children: [_jsx(StepForward, { className: "h-3.5 w-3.5" }), " Step"] }), status === 'paused' && (_jsxs(Button, { size: "sm", variant: "outline", className: "h-7 gap-1 px-2", onClick: onResume, children: [_jsx(ChevronRight, { className: "h-3.5 w-3.5" }), " Continue"] })), _jsxs(Button, { size: "sm", variant: "ghost", className: "h-7 gap-1 px-2 text-muted-foreground", onClick: onReset, children: [_jsx(RotateCcw, { className: "h-3.5 w-3.5" }), " Reset"] }), _jsx("span", { className: cn('ml-auto rounded px-1.5 py-0.5 text-[10px] font-semibold uppercase', STATUS_TONE[status === 'idle' || status === 'running' ? 'ok' : status] ?? 'bg-muted'), children: status })] }), _jsxs("div", { className: "min-h-0 flex-1 space-y-3 overflow-auto p-3", children: [validation && (validation.errors.length > 0 || validation.warnings.length > 0) && (_jsxs("div", { className: "space-y-1", children: [validation.errors.map((d, i) => (_jsxs("div", { className: "flex items-start gap-1.5 rounded border border-rose-200 bg-rose-50 px-2 py-1 text-rose-700", children: [_jsx(CircleAlert, { className: "mt-0.5 h-3 w-3 shrink-0" }), _jsx("span", { children: d.message })] }, `e${i}`))), validation.warnings.map((d, i) => (_jsxs("div", { className: "flex items-start gap-1.5 rounded border border-amber-200 bg-amber-50 px-2 py-1 text-amber-700", children: [_jsx(AlertTriangle, { className: "mt-0.5 h-3 w-3 shrink-0" }), _jsx("span", { children: d.message })] }, `w${i}`)))] })), inputs.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Inputs" }), inputs.map((v) => (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Label, { className: "w-24 shrink-0 truncate font-mono text-[11px]", title: v.name, children: v.name }), _jsx(Input, { value: seed[v.name] ?? (v.defaultValue != null ? String(v.defaultValue) : ''), onChange: (e) => setSeed((p) => ({ ...p, [v.name]: e.target.value })), placeholder: v.type ?? 'value', className: "h-7 flex-1 text-xs" })] }, v.name)))] })), _jsxs("section", { className: "space-y-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5 font-medium text-muted-foreground", children: [_jsx("span", { children: "Set variables" }), _jsxs("button", { type: "button", className: "ml-auto inline-flex items-center gap-0.5 rounded border px-1.5 py-0.5 text-[10px] hover:bg-muted/50", onClick: () => setScratch((p) => [...p, { k: '', v: '' }]), children: [_jsx(Plus, { className: "h-3 w-3" }), " Add"] })] }), scratch.length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "Override or inject any variable (wins over inputs and mocks at start)." })) : (scratch.map((row, i) => (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(Input, { value: row.k, onChange: (e) => setScratch((p) => p.map((r, j) => (j === i ? { ...r, k: e.target.value } : r))), placeholder: "name", className: "h-7 w-24 shrink-0 font-mono text-[11px]" }), _jsx("span", { className: "text-muted-foreground", children: "=" }), _jsx(Input, { value: row.v, onChange: (e) => setScratch((p) => p.map((r, j) => (j === i ? { ...r, v: e.target.value } : r))), placeholder: "value", className: "h-7 flex-1 text-xs" }), _jsx("button", { type: "button", className: "shrink-0 rounded p-1 text-muted-foreground hover:bg-muted/50 hover:text-rose-600", onClick: () => setScratch((p) => p.filter((_, j) => j !== i)), "aria-label": "Remove variable", children: _jsx(Trash2, { className: "h-3 w-3" }) })] }, i))))] }), mockNodes.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Mock outputs" }), mockNodes.map((m) => (_jsxs("div", { className: "space-y-0.5", children: [_jsxs(Label, { className: "flex items-baseline gap-1.5 text-[11px]", title: m.id, children: [_jsx("span", { className: "truncate font-medium", children: m.label }), _jsx("span", { className: "text-[9px] uppercase text-muted-foreground", children: m.type.replace(/_/g, ' ') }), m.outputs.length > 0 && (_jsxs("span", { className: "truncate font-mono text-[10px] text-violet-600", children: ["\u2192 ", m.outputs.join(', ')] }))] }), _jsx(Input, { value: mocks[m.id] ?? '', onChange: (e) => setMocks((p) => ({ ...p, [m.id]: e.target.value })), placeholder: m.type === 'script' && m.outputs.length ? `{ "${m.outputs[0]}": … }` : 'mocked result (JSON)', className: "h-7 w-full font-mono text-[11px]" })] }, m.id)))] })), snapshot && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Variables" }), Object.keys(snapshot.variables).length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "No variables set." })) : (_jsx("ul", { className: "space-y-1", children: Object.entries(snapshot.variables).map(([k, val]) => (_jsxs("li", { className: "flex items-baseline gap-1.5 rounded border bg-background px-1.5 py-1", children: [_jsx("span", { className: "font-mono text-[11px]", children: k }), _jsxs("span", { className: "truncate font-mono text-[10px] text-muted-foreground", children: ["= ", typeof val === 'object' ? JSON.stringify(val) : String(val)] })] }, k))) }))] })), snapshot && snapshot.steps.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Timeline" }), _jsx("ol", { className: "space-y-1", children: snapshot.steps.map((s) => (_jsxs("li", { className: "rounded border bg-background p-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "font-mono text-[10px] text-muted-foreground", children: s.seq + 1 }), _jsx("span", { className: "truncate font-medium", children: s.label }), _jsx("span", { className: "text-[10px] uppercase text-muted-foreground", children: s.type }), _jsx("span", { className: cn('ml-auto rounded px-1 py-0.5 text-[9px] font-semibold uppercase', STATUS_TONE[s.status]), children: s.status })] }), s.note && _jsx("div", { className: "mt-0.5 text-[10px] text-muted-foreground", children: s.note }), s.error && _jsx("div", { className: "mt-0.5 text-[10px] text-rose-600", children: s.error }), s.wrote && (_jsxs("div", { className: "mt-0.5 truncate font-mono text-[10px] text-violet-600", children: ["\u2192 ", Object.keys(s.wrote).join(', ')] })), s.edges && s.edges.length > 0 && (_jsx("ul", { className: "mt-0.5 space-y-0.5", children: s.edges.map((ed) => (_jsxs("li", { className: "space-y-0.5", children: [_jsxs("div", { className: cn('flex items-center gap-1 font-mono text-[10px]', ed.selected ? 'text-sky-700' : 'text-muted-foreground'), children: [_jsx("span", { children: ed.selected ? '▶' : '·' }), _jsx("span", { className: "truncate", children: ed.isDefault ? 'else' : ed.condition }), _jsx("span", { className: cn('ml-auto', ed.error && 'text-rose-600'), children: ed.error ? 'error' : ed.result ? 'true' : 'false' })] }), ed.error && _jsx("div", { className: "pl-3 text-[10px] text-rose-600", children: ed.error })] }, ed.edgeId))) }))] }, s.seq))) })] })), !snapshot && !blocked && (_jsx("p", { className: "italic text-muted-foreground", children: "Press Run to simulate, or Step to walk node by node. Side effects are mocked \u2014 no backend is called." }))] })] }));
+}

package/dist/views/metadata-admin/previews/JobPreview.d.ts

@@ -0,0 +1,28 @@
+/**
+ * JobPreview — read-only summary of a Background Job draft.
+ *
+ * Canonical shape (see `packages/spec/src/system/job.zod.ts`):
+ *   schedule: { type: 'cron',     expression: string | { dialect:'cron', source:string }, timezone? }
+ *           | { type: 'interval', intervalMs: number }
+ *           | { type: 'once',     at: string (ISO) }
+ *   handler: string         — function key registered in defineStack({ functions })
+ *   retryPolicy?: { maxRetries, backoffMs, backoffMultiplier }
+ *   timeout?: number (ms)
+ *   enabled?: boolean
+ *
+ * Legacy / app-supplied flat shapes are also tolerated:
+ *   • `cron` (string)        — top-level cron expression
+ *   • `every` / `interval`   — interval like "5m" or millis number
+ *   • `at` / `runAs`         — one-shot ISO
+ *   • `timezone` / `tz`
+ *   • `active` / `enabled`
+ *
+ * For cron schedules we compute the **next 5 fire times** locally so
+ * operators can sanity-check the schedule without waiting for the
+ * runtime. The cron parser handles standard 5-field cron with `*`,
+ * `*\/N`, comma lists, and ranges (`a-b`). Special tokens like
+ * `@daily` / `@hourly` are also expanded.
+ */
+import * as React from 'react';
+import type { MetadataPreviewProps } from '../preview-registry';
+export declare function JobPreview({ name, draft }: MetadataPreviewProps): React.JSX.Element;

package/dist/views/metadata-admin/previews/JobPreview.js

@@ -0,0 +1,290 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * JobPreview — read-only summary of a Background Job draft.
+ *
+ * Canonical shape (see `packages/spec/src/system/job.zod.ts`):
+ *   schedule: { type: 'cron',     expression: string | { dialect:'cron', source:string }, timezone? }
+ *           | { type: 'interval', intervalMs: number }
+ *           | { type: 'once',     at: string (ISO) }
+ *   handler: string         — function key registered in defineStack({ functions })
+ *   retryPolicy?: { maxRetries, backoffMs, backoffMultiplier }
+ *   timeout?: number (ms)
+ *   enabled?: boolean
+ *
+ * Legacy / app-supplied flat shapes are also tolerated:
+ *   • `cron` (string)        — top-level cron expression
+ *   • `every` / `interval`   — interval like "5m" or millis number
+ *   • `at` / `runAs`         — one-shot ISO
+ *   • `timezone` / `tz`
+ *   • `active` / `enabled`
+ *
+ * For cron schedules we compute the **next 5 fire times** locally so
+ * operators can sanity-check the schedule without waiting for the
+ * runtime. The cron parser handles standard 5-field cron with `*`,
+ * `*\/N`, comma lists, and ranges (`a-b`). Special tokens like
+ * `@daily` / `@hourly` are also expanded.
+ */
+import * as React from 'react';
+import { AlarmClock, Calendar, Clock, Code2, Globe2, PlayCircle, Power, RotateCcw, Timer, } from 'lucide-react';
+import { PreviewShell, PreviewMessage, PreviewErrorBoundary } from './PreviewShell';
+const CRON_ALIASES = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+};
+function parseCronField(raw, min, max) {
+    const out = { values: new Set(), any: false };
+    if (raw === '*') {
+        for (let i = min; i <= max; i++)
+            out.values.add(i);
+        out.any = true;
+        return out;
+    }
+    for (const part of raw.split(',')) {
+        let stepStr;
+        let body = part;
+        if (part.includes('/')) {
+            const [b, s] = part.split('/');
+            body = b;
+            stepStr = s;
+        }
+        const step = stepStr ? Math.max(1, parseInt(stepStr, 10) || 1) : 1;
+        let lo = min;
+        let hi = max;
+        if (body !== '*') {
+            if (body.includes('-')) {
+                const [a, b] = body.split('-').map((n) => parseInt(n, 10));
+                if (Number.isNaN(a) || Number.isNaN(b))
+                    return null;
+                lo = a;
+                hi = b;
+            }
+            else {
+                const v = parseInt(body, 10);
+                if (Number.isNaN(v))
+                    return null;
+                lo = v;
+                hi = v;
+            }
+        }
+        for (let i = lo; i <= hi; i += step) {
+            if (i >= min && i <= max)
+                out.values.add(i);
+        }
+    }
+    return out;
+}
+function parseCron(expr) {
+    const aliased = CRON_ALIASES[expr.trim()] ?? expr.trim();
+    const parts = aliased.split(/\s+/);
+    if (parts.length !== 5 && parts.length !== 6)
+        return null;
+    // Strip optional 6th seconds field — we ignore second-resolution for preview.
+    const fields = parts.length === 6 ? parts.slice(1) : parts;
+    const [m, h, dom, mon, dow] = fields;
+    const minute = parseCronField(m, 0, 59);
+    const hour = parseCronField(h, 0, 23);
+    const domF = parseCronField(dom, 1, 31);
+    const month = parseCronField(mon, 1, 12);
+    const dowF = parseCronField(dow === '7' ? '0' : dow, 0, 6);
+    if (!minute || !hour || !domF || !month || !dowF)
+        return null;
+    return { minute, hour, dom: domF, month, dow: dowF };
+}
+function nextCronFires(expr, from, count) {
+    const cron = parseCron(expr);
+    if (!cron)
+        return [];
+    const results = [];
+    // Walk minute by minute up to ~366 days; bail early once we hit count.
+    const cursor = new Date(from.getTime());
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1);
+    const limitMs = 366 * 24 * 60 * 60 * 1000;
+    const endAt = from.getTime() + limitMs;
+    while (results.length < count && cursor.getTime() <= endAt) {
+        if (cron.minute.values.has(cursor.getMinutes()) &&
+            cron.hour.values.has(cursor.getHours()) &&
+            cron.month.values.has(cursor.getMonth() + 1) &&
+            // POSIX cron OR semantics: when both DOM and DOW are restricted,
+            // a match in EITHER triggers; when one is `*`, the other governs.
+            (cron.dom.any || cron.dow.any
+                ? cron.dom.values.has(cursor.getDate()) && cron.dow.values.has(cursor.getDay())
+                : cron.dom.values.has(cursor.getDate()) || cron.dow.values.has(cursor.getDay()))) {
+            results.push(new Date(cursor.getTime()));
+        }
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return results;
+}
+function parseInterval(every) {
+    const m = /^(\d+)\s*(ms|s|m|h|d)$/.exec(every.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    switch (m[2]) {
+        case 'ms':
+            return n;
+        case 's':
+            return n * 1000;
+        case 'm':
+            return n * 60000;
+        case 'h':
+            return n * 3600000;
+        case 'd':
+            return n * 86400000;
+        default:
+            return null;
+    }
+}
+function nextIntervalFires(intervalMs, from, count) {
+    const out = [];
+    for (let i = 1; i <= count; i++)
+        out.push(new Date(from.getTime() + i * intervalMs));
+    return out;
+}
+function formatWhen(d) {
+    return d.toLocaleString(undefined, {
+        weekday: 'short',
+        month: 'short',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}
+/**
+ * Normalize the canonical Schedule discriminated-union and legacy flat
+ * shapes into `{ cron?, every?, at?, timezone? }` for rendering.
+ *
+ * Supports:
+ *   • d.schedule = { type:'cron',     expression: string | {source}, timezone? }
+ *   • d.schedule = { type:'interval', intervalMs: number }
+ *   • d.schedule = { type:'once',     at: string }
+ *   • d.schedule = "0 9 * * 1-5"     (legacy: string cron)
+ *   • d.cron / d.every / d.interval / d.at / d.runAt / d.timezone / d.tz
+ */
+function normalizeSchedule(d) {
+    // Canonical discriminated-union schedule object.
+    if (d.schedule && typeof d.schedule === 'object') {
+        const s = d.schedule;
+        const t = String(s.type ?? '');
+        const tz = s.timezone ?? d.timezone ?? d.tz;
+        if (t === 'cron') {
+            const expr = s.expression;
+            const src = typeof expr === 'string'
+                ? expr
+                : expr && typeof expr === 'object' && typeof expr.source === 'string'
+                    ? expr.source
+                    : undefined;
+            return { cron: src, timezone: tz };
+        }
+        if (t === 'interval') {
+            const ms = Number(s.intervalMs);
+            return { every: Number.isFinite(ms) && ms > 0 ? humanizeMs(ms) : undefined, timezone: tz };
+        }
+        if (t === 'once') {
+            return { at: typeof s.at === 'string' ? s.at : undefined, timezone: tz };
+        }
+    }
+    // Flat legacy shapes.
+    const cron = typeof d.cron === 'string'
+        ? d.cron
+        : typeof d.schedule === 'string'
+            ? d.schedule
+            : undefined;
+    const everyRaw = d.every ?? d.interval;
+    const every = typeof everyRaw === 'string'
+        ? everyRaw
+        : typeof everyRaw === 'number'
+            ? humanizeMs(everyRaw)
+            : undefined;
+    const at = typeof d.at === 'string' ? d.at : typeof d.runAt === 'string' ? d.runAt : undefined;
+    const timezone = d.timezone ?? d.tz;
+    return { cron, every, at, timezone };
+}
+function humanizeMs(ms) {
+    if (ms % 86400000 === 0)
+        return `${ms / 86400000}d`;
+    if (ms % 3600000 === 0)
+        return `${ms / 3600000}h`;
+    if (ms % 60000 === 0)
+        return `${ms / 60000}m`;
+    if (ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    return `${ms}ms`;
+}
+export function JobPreview({ name, draft }) {
+    const d = draft;
+    const jobName = String(d.name ?? name ?? '');
+    const label = String(d.label ?? jobName);
+    const description = d.description ?? '';
+    const { cron, every, at, timezone } = normalizeSchedule(d);
+    const handler = d.handler
+        ?? d.target
+        ?? d.function
+        ?? d.functionName;
+    const active = d.active !== false && d.enabled !== false;
+    // Canonical: retryPolicy.{maxRetries,backoffMs,backoffMultiplier}; legacy: flat fields.
+    const retryPolicy = d.retryPolicy;
+    const maxRetries = retryPolicy?.maxRetries
+        ?? d.maxRetries
+        ?? d.retries;
+    const backoffMs = retryPolicy?.backoffMs;
+    const timeoutMs = d.timeout ?? d.timeoutMs;
+    const concurrency = d.concurrency;
+    const intervalMs = every ? parseInterval(every) : null;
+    const { nextFires, deltas } = React.useMemo(() => {
+        const now = new Date();
+        let fires = [];
+        if (cron)
+            fires = nextCronFires(cron, now, 5);
+        else if (intervalMs)
+            fires = nextIntervalFires(intervalMs, now, 5);
+        else if (at) {
+            const t = Date.parse(at);
+            if (!Number.isNaN(t))
+                fires = [new Date(t)];
+        }
+        return {
+            nextFires: fires,
+            deltas: fires.map((f) => humanDelta(f.getTime() - now.getTime())),
+        };
+    }, [cron, intervalMs, at]);
+    const scheduleInvalid = (cron && nextFires.length === 0) || (every && !intervalMs);
+    if (!jobName && !cron && !every && !at && !handler) {
+        return (_jsx(PreviewShell, { hint: "job", children: _jsx(PreviewMessage, { children: "Set a schedule (cron / every / at) and a handler to see the job preview." }) }));
+    }
+    return (_jsx(PreviewShell, { hint: "job", children: _jsx(PreviewErrorBoundary, { children: _jsxs("div", { className: "p-3 space-y-3", children: [_jsx("div", { className: "rounded border bg-muted/30 p-3", children: _jsxs("div", { className: "flex items-start gap-2", children: [_jsx(AlarmClock, { className: "h-4 w-4 mt-0.5 text-muted-foreground shrink-0" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2", children: [_jsx("span", { className: "text-sm font-medium truncate", children: label }), _jsx("span", { className: "font-mono text-[10px] text-muted-foreground", children: jobName })] }), description && _jsx("div", { className: "text-xs text-muted-foreground mt-0.5", children: description }), _jsxs("div", { className: "mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px]", children: [_jsx(Pill, { icon: Power, label: active ? 'Active' : 'Paused', tone: active ? 'green' : 'gray' }), timezone && _jsx(Pill, { icon: Globe2, label: timezone, mono: true }), maxRetries != null && _jsx(Pill, { icon: RotateCcw, label: `retries: ${maxRetries}${backoffMs ? ` (${humanizeMs(backoffMs)} backoff)` : ''}` }), timeoutMs != null && _jsx(Pill, { icon: Timer, label: `timeout: ${humanizeMs(timeoutMs)}` }), concurrency != null && _jsx(Pill, { label: `concurrency: ${concurrency}` })] })] })] }) }), _jsx(Section, { title: "Schedule", icon: Calendar, children: _jsxs("div", { className: "rounded border bg-background p-2.5 text-xs space-y-1", children: [cron && (_jsx(ScheduleLine, { label: "Cron", children: _jsx("code", { className: "font-mono", children: cron }) })), every && (_jsxs(ScheduleLine, { label: "Every", children: [_jsx("code", { className: "font-mono", children: every }), !intervalMs && _jsx("span", { className: "ml-2 text-amber-700", children: "unparseable" })] })), at && (_jsx(ScheduleLine, { label: "At", children: _jsx("code", { className: "font-mono", children: at }) })), !cron && !every && !at && (_jsx("div", { className: "text-muted-foreground italic", children: "No schedule set \u2014 runs only when triggered manually." }))] }) }), (cron || intervalMs || at) && (_jsx(Section, { title: `Next ${Math.max(nextFires.length, 1)} run${nextFires.length === 1 ? '' : 's'}`, icon: Clock, children: nextFires.length === 0 ? (_jsx("div", { className: "text-xs text-amber-700", children: scheduleInvalid
+                                ? 'Could not derive any future fire time. Check the schedule syntax.'
+                                : 'No upcoming runs in the next 366 days.' })) : (_jsx("ul", { className: "rounded border bg-background divide-y text-xs", children: nextFires.map((d, i) => (_jsxs("li", { className: "flex items-center gap-2 px-2.5 py-1.5", children: [_jsx("span", { className: "w-4 text-right text-muted-foreground text-[10px]", children: i + 1 }), _jsx(Clock, { className: "h-3 w-3 text-muted-foreground" }), _jsx("span", { className: "font-mono", children: formatWhen(d) }), _jsxs("span", { className: "ml-auto text-[10px] text-muted-foreground", children: ["in ", deltas[i]] })] }, i))) })) })), _jsx(Section, { title: "Handler", icon: Code2, children: handler ? (_jsxs("div", { className: "rounded border bg-background px-2.5 py-1.5 text-xs flex items-center gap-2", children: [_jsx(PlayCircle, { className: "h-3.5 w-3.5 text-muted-foreground" }), _jsx("code", { className: "font-mono break-all", children: handler })] })) : (_jsx("div", { className: "text-xs text-amber-700", children: "No handler bound \u2014 the job will be a no-op." })) })] }) }) }));
+}
+function humanDelta(ms) {
+    if (ms <= 0)
+        return 'now';
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 48)
+        return `${h}h`;
+    const days = Math.round(h / 24);
+    return `${days}d`;
+}
+function ScheduleLine({ label, children }) {
+    return (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsxs("span", { className: "text-muted-foreground w-12 shrink-0", children: [label, ":"] }), _jsx("span", { className: "break-all", children: children })] }));
+}
+function Section({ title, icon: Icon, children, }) {
+    return (_jsxs("div", { className: "space-y-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5 text-[11px] font-medium text-muted-foreground uppercase tracking-wider", children: [Icon && _jsx(Icon, { className: "h-3 w-3" }), _jsx("span", { children: title })] }), children] }));
+}
+function Pill({ icon: Icon, label, tone = 'gray', mono = false, }) {
+    const cls = tone === 'green' ? 'text-emerald-700' : 'text-foreground';
+    return (_jsxs("span", { className: "inline-flex items-center gap-1", children: [Icon && _jsx(Icon, { className: "h-3 w-3 text-muted-foreground" }), _jsx("span", { className: `${cls} ${mono ? 'font-mono' : ''}`, children: label })] }));
+}

package/dist/views/metadata-admin/previews/ObjectFormCanvas.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ObjectFormCanvas — form-designer-style preview for an Object
+ * metadata draft. Replaces the legacy CRUD grid in DesignerMode.
+ *
+ * Each field renders as the labeled input it will become at runtime
+ * (via {@link FieldStub}). Clicking a row selects it and the host
+ * swaps the inspector to {@link ObjectFieldInspector}. The trailing
+ * "+ Add field" button opens a categorized type picker — picking a
+ * type appends a fresh field and immediately selects it so authors
+ * can fill in name/label in the inspector.
+ *
+ * All edits go through the host's `onPatch` callback. Read-only
+ * surfaces (legacy tier objects, builtin objects) still render the
+ * preview but suppress selection chrome + the add button.
+ */
+import * as React from 'react';
+import type { MetadataSelection } from '../preview-registry';
+import { toFieldName } from './object-fields-io';
+export interface ObjectFormCanvasProps {
+    objectName: string;
+    draft: Record<string, unknown>;
+    /** Last published version, for the review/diff mode. */
+    baseline?: Record<string, unknown>;
+    onPatch?: (patch: Record<string, unknown>) => void;
+    selection?: MetadataSelection | null;
+    onSelectionChange?: (next: MetadataSelection | null) => void;
+    locale?: string;
+}
+export declare function ObjectFormCanvas({ objectName, draft, baseline, onPatch, selection, onSelectionChange, locale, }: ObjectFormCanvasProps): React.JSX.Element;
+export { toFieldName };