station-kit 1.0.8 → 1.0.9

package/src/app/playground/expression/page.tsx

@@ -0,0 +1,245 @@
+"use client";
+
+import { useState } from "react";
+import { useApi } from "../../hooks/use-api";
+import { useBreadcrumb } from "../../hooks/use-breadcrumb";
+import { ApiPanel } from "../../components/api-panel";
+
+const STARTER_SOURCE = `input.amount > 100 && input.user.tier == "premium"`;
+const STARTER_CONTEXT = JSON.stringify(
+  {
+    input: {
+      amount: 250,
+      user: { tier: "premium" },
+    },
+    upstream: {},
+  },
+  null,
+  2,
+);
+
+export default function ExpressionPlaygroundPage() {
+  const api = useApi();
+  const [source, setSource] = useState(STARTER_SOURCE);
+  const [contextJson, setContextJson] = useState(STARTER_CONTEXT);
+  const [astJson, setAstJson] = useState<string>("");
+  const [parseError, setParseError] = useState<string | null>(null);
+  const [evalResult, setEvalResult] = useState<unknown>(undefined);
+  const [evalError, setEvalError] = useState<string | null>(null);
+  const [parseRunning, setParseRunning] = useState(false);
+  const [evalRunning, setEvalRunning] = useState(false);
+
+  useBreadcrumb(
+    [
+      { label: "Tools" },
+      { label: "Expression playground" },
+    ],
+    "playground",
+  );
+
+  async function handleParse() {
+    setParseError(null);
+    setParseRunning(true);
+    try {
+      const res = await api.parseExpression(source);
+      setAstJson(JSON.stringify(res.data.node, null, 2));
+    } catch (err) {
+      setParseError(err instanceof Error ? err.message : String(err));
+      setAstJson("");
+    } finally {
+      setParseRunning(false);
+    }
+  }
+
+  async function handleEvaluate() {
+    setEvalError(null);
+    setEvalResult(undefined);
+    setEvalRunning(true);
+    try {
+      // First parse if AST is empty
+      let node: unknown;
+      if (astJson.trim()) {
+        node = JSON.parse(astJson);
+      } else {
+        const parsed = await api.parseExpression(source);
+        node = parsed.data.node;
+        setAstJson(JSON.stringify(node, null, 2));
+      }
+      const ctx = JSON.parse(contextJson);
+      const res = await api.evaluateExpression(node, ctx);
+      setEvalResult(res.data.value);
+    } catch (err) {
+      setEvalError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setEvalRunning(false);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="page-title">Expression playground</h1>
+      <p style={{ color: "var(--muted)", marginBottom: "1.5rem", fontSize: "0.875rem" }}>
+        Pure, deterministic expressions used in dynamic broadcast `input` mappings and `when` guards.
+        References resolve against `input.*` (broadcast trigger input) and `upstream.nodeName.*` (upstream outputs).
+      </p>
+
+      <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: "1rem" }}>
+        <section>
+          <Label>Expression source</Label>
+          <textarea
+            className="mono"
+            value={source}
+            onChange={(e) => setSource(e.target.value)}
+            spellCheck={false}
+            rows={4}
+            style={editorStyle}
+          />
+          <div style={{ marginTop: "0.5rem", display: "flex", gap: "0.5rem" }}>
+            <button className="btn" onClick={handleParse} disabled={parseRunning}>
+              {parseRunning ? "Parsing..." : "Parse → AST"}
+            </button>
+            <button className="btn btn--primary" onClick={handleEvaluate} disabled={evalRunning}>
+              {evalRunning ? "Evaluating..." : "Evaluate"}
+            </button>
+          </div>
+          {parseError && (
+            <div style={errorStyle}>
+              {parseError}
+            </div>
+          )}
+        </section>
+
+        <section>
+          <Label>Context (input + upstream)</Label>
+          <textarea
+            className="mono"
+            value={contextJson}
+            onChange={(e) => setContextJson(e.target.value)}
+            spellCheck={false}
+            rows={10}
+            style={{ ...editorStyle, minHeight: "180px" }}
+          />
+        </section>
+      </div>
+
+      <section style={{ marginTop: "1.5rem" }}>
+        <Label>Parsed AST</Label>
+        <textarea
+          className="mono"
+          value={astJson}
+          onChange={(e) => setAstJson(e.target.value)}
+          spellCheck={false}
+          rows={10}
+          placeholder="// Click 'Parse' or paste an ExprNode JSON manually."
+          style={{ ...editorStyle, minHeight: "180px" }}
+        />
+      </section>
+
+      <section style={{ marginTop: "1.5rem" }}>
+        <Label>Result</Label>
+        {evalError ? (
+          <div style={errorStyle}>{evalError}</div>
+        ) : evalResult === undefined ? (
+          <div style={{ ...resultStyle, color: "var(--muted)" }}>—</div>
+        ) : (
+          <pre className="mono" style={resultStyle}>{JSON.stringify(evalResult, null, 2)}</pre>
+        )}
+      </section>
+
+      <section style={{ marginTop: "1.5rem" }}>
+        <Label>Reference</Label>
+        <div style={{ ...resultStyle, color: "var(--muted)" }}>
+          <p style={{ margin: "0 0 0.5rem 0", fontSize: "0.8125rem", lineHeight: 1.6 }}>
+            <strong>Operators:</strong> <span className="mono">==</span>, <span className="mono">!=</span>, <span className="mono">&lt;</span>, <span className="mono">&gt;</span>, <span className="mono">&lt;=</span>, <span className="mono">&gt;=</span>, <span className="mono">&amp;&amp;</span>, <span className="mono">||</span>, <span className="mono">!</span>, <span className="mono">+</span>, <span className="mono">-</span>, <span className="mono">*</span>, <span className="mono">/</span>
+          </p>
+          <p style={{ margin: "0 0 0.5rem 0", fontSize: "0.8125rem", lineHeight: 1.6 }}>
+            <strong>Refs:</strong> <span className="mono">input.x</span>, <span className="mono">upstream.nodeName.x</span>, <span className="mono">nodeName.x</span> (shorthand)
+          </p>
+          <p style={{ margin: "0 0 0.5rem 0", fontSize: "0.8125rem", lineHeight: 1.6 }}>
+            <strong>Literals:</strong> numbers, <span className="mono">&quot;strings&quot;</span>, <span className="mono">true</span> / <span className="mono">false</span> / <span className="mono">null</span>
+          </p>
+          <p style={{ margin: "0.75rem 0 0 0", fontSize: "0.8125rem", lineHeight: 1.6, paddingTop: "0.5rem", borderTop: "1px dashed var(--border)" }}>
+            <strong>Escape hatch:</strong> the language is intentionally minimal — no loops, no user-defined functions, no I/O. If you can&apos;t express something here, write a code-defined signal that does the logic in TypeScript and reference it from the broadcast graph. The signal is the unit of arbitrary code; the expression layer is for connecting them.
+          </p>
+        </div>
+      </section>
+
+      <ApiPanel
+        title="Use these endpoints from your code"
+        snippets={[
+          {
+            label: "Parse string → AST",
+            method: "POST",
+            path: "/api/v1/expressions/parse",
+            body: { source: "input.amount > 100" },
+          },
+          {
+            label: "Evaluate AST against context",
+            method: "POST",
+            path: "/api/v1/expressions/evaluate",
+            body: { node: { kind: "ref", path: ["input", "x"] }, context: { input: { x: 42 } } },
+          },
+          {
+            label: "Validate AST against schemas",
+            method: "POST",
+            path: "/api/v1/expressions/validate",
+            body: {
+              node: { kind: "ref", path: ["input", "x"] },
+              schemaContext: {
+                inputSchema: { type: "object", properties: { x: { type: "number" } } },
+                upstreamSchemas: {},
+                expectedSchema: { type: "number" },
+              },
+            },
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function Label({ children }: { children: React.ReactNode }) {
+  return (
+    <label className="mono" style={{
+      display: "block",
+      fontSize: "0.75rem",
+      color: "var(--muted)",
+      textTransform: "uppercase",
+      letterSpacing: "0.05em",
+      marginBottom: "0.25rem",
+    }}>{children}</label>
+  );
+}
+
+const editorStyle: React.CSSProperties = {
+  width: "100%",
+  padding: "0.625rem 0.75rem",
+  border: "1px solid var(--border)",
+  borderRadius: "4px",
+  background: "var(--surface)",
+  color: "var(--text)",
+  fontSize: "0.8125rem",
+  lineHeight: 1.5,
+  fontFamily: "var(--mono-font, monospace)",
+  resize: "vertical",
+};
+
+const errorStyle: React.CSSProperties = {
+  marginTop: "0.75rem",
+  padding: "0.625rem 0.75rem",
+  background: "var(--error-bg, #fee)",
+  color: "var(--error, #b00)",
+  border: "1px solid var(--error, #b00)",
+  borderRadius: "4px",
+  fontSize: "0.8125rem",
+};
+
+const resultStyle: React.CSSProperties = {
+  padding: "0.625rem 0.75rem",
+  background: "var(--surface)",
+  border: "1px solid var(--border)",
+  borderRadius: "4px",
+  fontSize: "0.8125rem",
+  margin: 0,
+  whiteSpace: "pre-wrap",
+};

package/src/app/schedules/[id]/page.tsx

@@ -0,0 +1,10 @@
+import { ScheduleEditor } from "./schedule-editor";
+
+export default async function ScheduleEditorPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  return <ScheduleEditor id={id} />;
+}

package/src/app/schedules/[id]/schedule-editor.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { useApi, type Schedule } from "../../hooks/use-api";
+import { useBreadcrumb } from "../../hooks/use-breadcrumb";
+import { ScheduleForm, type ScheduleFormValue } from "../components/schedule-form";
+import { ApiPanel } from "../../components/api-panel";
+
+export function ScheduleEditor({ id }: { id: string }) {
+  const api = useApi();
+  const router = useRouter();
+  const [schedule, setSchedule] = useState<Schedule | null>(null);
+  const [value, setValue] = useState<ScheduleFormValue | null>(null);
+  const [previewFires, setPreviewFires] = useState<string[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [savedAt, setSavedAt] = useState<number | null>(null);
+
+  useBreadcrumb(
+    [
+      { label: "Schedules", href: "/schedules" },
+      { label: schedule?.target ?? id },
+    ],
+    "schedules",
+  );
+
+  useEffect(() => {
+    api.getSchedule(id)
+      .then((res) => {
+        setSchedule(res.data);
+        setValue({
+          kind: res.data.kind,
+          target: res.data.target,
+          interval: res.data.interval,
+          input: res.data.input !== undefined ? JSON.stringify(res.data.input, null, 2) : "{}",
+          enabled: res.data.enabled,
+        });
+      })
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)))
+      .finally(() => setLoading(false));
+
+    api.previewSchedule(id, 5).then((res) => setPreviewFires(res.data.fires)).catch(() => {});
+  }, [id]);
+
+  async function handleSave() {
+    if (!value) return;
+    setError(null);
+    let inputParsed: unknown = undefined;
+    if (value.input.trim()) {
+      try {
+        inputParsed = JSON.parse(value.input);
+      } catch (err) {
+        setError(`Input JSON parse error: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+      }
+    }
+    setBusy(true);
+    try {
+      const res = await api.updateSchedule(id, {
+        interval: value.interval,
+        input: inputParsed,
+        enabled: value.enabled,
+      });
+      setSchedule(res.data);
+      setSavedAt(Date.now());
+      const preview = await api.previewSchedule(id, 5);
+      setPreviewFires(preview.data.fires);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function handleDelete() {
+    if (!confirm("Delete this schedule?")) return;
+    try {
+      await api.deleteSchedule(id);
+      router.push("/schedules");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (loading) {
+    return (
+      <div>
+        <h1 className="page-title">Schedule</h1>
+        <div className="loading-bar"><div className="loading-bar-fill" /></div>
+      </div>
+    );
+  }
+
+  if (!schedule || !value) {
+    return (
+      <div>
+        <h1 className="page-title">Schedule</h1>
+        <div className="empty-state">
+          <p className="empty-state-text">{error ?? "Not found."}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: "1rem" }}>
+        <h1 className="page-title" style={{ margin: 0 }}>
+          <span className="mono">{schedule.target}</span>
+        </h1>
+        <button className="btn btn--danger" onClick={handleDelete}>Delete</button>
+      </div>
+
+      <div style={{ display: "grid", gridTemplateColumns: "minmax(0, 2fr) minmax(0, 1fr)", gap: "2rem" }}>
+        <div>
+          <ScheduleForm value={value} onChange={setValue} locked />
+
+          {error && (
+            <div style={{
+              marginTop: "1rem",
+              padding: "0.625rem 0.75rem",
+              background: "var(--error-bg, #fee)",
+              color: "var(--error, #b00)",
+              border: "1px solid var(--error, #b00)",
+              borderRadius: "4px",
+              fontSize: "0.8125rem",
+              maxWidth: "640px",
+            }}>{error}</div>
+          )}
+
+          <div style={{ marginTop: "1.5rem", display: "flex", gap: "0.5rem", alignItems: "center" }}>
+            <button className="btn btn--primary" onClick={handleSave} disabled={busy}>
+              {busy ? "Saving..." : "Save"}
+            </button>
+            {savedAt && Date.now() - savedAt < 3000 && (
+              <span className="mono" style={{ fontSize: "0.75rem", color: "var(--success, #060)" }}>Saved</span>
+            )}
+          </div>
+        </div>
+
+        <aside>
+          <h3 className="mono" style={{ fontSize: "0.75rem", color: "var(--muted)", textTransform: "uppercase", letterSpacing: "0.05em", marginBottom: "0.5rem" }}>
+            Next fire times
+          </h3>
+          <ul style={{ listStyle: "none", padding: 0, margin: 0 }}>
+            {previewFires.map((iso, i) => (
+              <li key={i} className="mono" style={{
+                fontSize: "0.8125rem",
+                padding: "0.375rem 0",
+                borderBottom: "1px dashed var(--border)",
+                color: i === 0 ? "var(--text)" : "var(--muted)",
+              }}>
+                {new Date(iso).toLocaleString()}
+              </li>
+            ))}
+          </ul>
+
+          <h3 className="mono" style={{ fontSize: "0.75rem", color: "var(--muted)", textTransform: "uppercase", letterSpacing: "0.05em", marginTop: "1.5rem", marginBottom: "0.5rem" }}>
+            Last run
+          </h3>
+          <div className="mono" style={{ fontSize: "0.8125rem", color: "var(--muted)" }}>
+            {schedule.lastRunAt ? (
+              <>
+                <div>{new Date(schedule.lastRunAt).toLocaleString()}</div>
+                {schedule.lastRunStatus && <div>status: {schedule.lastRunStatus}</div>}
+                {schedule.lastRunId && <div>id: {schedule.lastRunId}</div>}
+              </>
+            ) : "Never run."}
+          </div>
+        </aside>
+      </div>
+
+      <ApiPanel
+        title="Manage this schedule"
+        snippets={[
+          { label: "Get", method: "GET", path: `/api/v1/schedules/${id}` },
+          {
+            label: "Update",
+            method: "PATCH",
+            path: `/api/v1/schedules/${id}`,
+            body: { interval: value.interval, enabled: value.enabled, input: tryParse(value.input) },
+          },
+          { label: "Preview next 5 fires", method: "POST", path: `/api/v1/schedules/${id}/preview`, body: { count: 5 } },
+          { label: "Delete", method: "DELETE", path: `/api/v1/schedules/${id}` },
+        ]}
+      />
+    </div>
+  );
+}
+
+function tryParse(s: string): unknown {
+  try { return JSON.parse(s); } catch { return s; }
+}

package/src/app/schedules/components/schedule-form.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useApi, type ScheduleKind } from "../../hooks/use-api";
+
+export interface ScheduleFormValue {
+  kind: ScheduleKind;
+  target: string;
+  interval: string;
+  input: string;
+  enabled: boolean;
+}
+
+export interface ScheduleFormProps {
+  value: ScheduleFormValue;
+  onChange: (next: ScheduleFormValue) => void;
+  /** When true, kind/target are locked (edit mode). */
+  locked?: boolean;
+}
+
+export function ScheduleForm({ value, onChange, locked }: ScheduleFormProps) {
+  const api = useApi();
+  const [signalNames, setSignalNames] = useState<string[]>([]);
+  const [staticBroadcastNames, setStaticBroadcastNames] = useState<string[]>([]);
+  const [dynamicBroadcastNames, setDynamicBroadcastNames] = useState<string[]>([]);
+
+  useEffect(() => {
+    Promise.all([
+      api.getSignals().catch(() => ({ data: [] })),
+      api.getBroadcasts().catch(() => ({ data: [] })),
+      api.getBroadcastDefinitions().catch(() => ({ data: [] })),
+    ]).then(([sigs, stat, dyn]) => {
+      setSignalNames(sigs.data.map((s) => s.name));
+      setStaticBroadcastNames(stat.data.map((b) => b.name));
+      setDynamicBroadcastNames(dyn.data.map((d) => d.name));
+    });
+  }, []);
+
+  const targetOptions =
+    value.kind === "signal"
+      ? signalNames
+      : value.kind === "broadcast-static"
+        ? staticBroadcastNames
+        : dynamicBroadcastNames;
+
+  return (
+    <div style={{ display: "grid", gap: "1rem", maxWidth: "640px" }}>
+      <Field label="Kind">
+        <select
+          value={value.kind}
+          disabled={locked}
+          onChange={(e) => onChange({ ...value, kind: e.target.value as ScheduleKind, target: "" })}
+          className="mono"
+          style={selectStyle}
+        >
+          <option value="signal">signal</option>
+          <option value="broadcast-static">broadcast-static</option>
+          <option value="broadcast-dynamic">broadcast-dynamic</option>
+        </select>
+      </Field>
+
+      <Field label="Target" hint={`${targetOptions.length} available`}>
+        {locked ? (
+          <input className="mono" value={value.target} readOnly style={inputStyle} />
+        ) : (
+          <input
+            className="mono"
+            value={value.target}
+            list={`schedule-targets-${value.kind}`}
+            onChange={(e) => onChange({ ...value, target: e.target.value })}
+            placeholder="signal or broadcast name"
+            style={inputStyle}
+          />
+        )}
+        <datalist id={`schedule-targets-${value.kind}`}>
+          {targetOptions.map((name) => (
+            <option key={name} value={name} />
+          ))}
+        </datalist>
+      </Field>
+
+      <Field label="Interval" hint='e.g. "30s", "5m", "1h", "1d"'>
+        <input
+          className="mono"
+          value={value.interval}
+          onChange={(e) => onChange({ ...value, interval: e.target.value })}
+          placeholder="5m"
+          style={inputStyle}
+        />
+      </Field>
+
+      <Field label="Input (JSON)">
+        <textarea
+          className="mono"
+          value={value.input}
+          onChange={(e) => onChange({ ...value, input: e.target.value })}
+          rows={6}
+          spellCheck={false}
+          style={{ ...inputStyle, fontFamily: "var(--mono-font, monospace)", fontSize: "0.8125rem" }}
+        />
+      </Field>
+
+      <label style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}>
+        <input
+          type="checkbox"
+          checked={value.enabled}
+          onChange={(e) => onChange({ ...value, enabled: e.target.checked })}
+        />
+        <span className="mono" style={{ fontSize: "0.875rem" }}>Enabled</span>
+      </label>
+    </div>
+  );
+}
+
+function Field({ label, hint, children }: { label: string; hint?: string; children: React.ReactNode }) {
+  return (
+    <div>
+      <div style={{ display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: "0.25rem" }}>
+        <label className="mono" style={{ fontSize: "0.75rem", color: "var(--muted)" }}>{label}</label>
+        {hint && <span className="mono" style={{ fontSize: "0.6875rem", color: "var(--muted)" }}>{hint}</span>}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+const inputStyle: React.CSSProperties = {
+  width: "100%",
+  padding: "0.5rem 0.625rem",
+  border: "1px solid var(--border)",
+  borderRadius: "4px",
+  background: "var(--surface)",
+  color: "var(--text)",
+  fontSize: "0.875rem",
+};
+
+const selectStyle: React.CSSProperties = {
+  ...inputStyle,
+  appearance: "auto",
+};