create-safest-tools 0.2.0

package/template/console/command/controller.ts

@@ -0,0 +1,267 @@
+import { requestJson } from "../lib/http";
+import { getOperationsWorkspaceSnapshot, subscribeToOperationsWorkspace } from "../operations/store";
+import { getQueueWorkspaceSnapshot, subscribeToQueueWorkspace } from "../queues/store";
+import type { QueueRecord } from "../queues/types";
+import { getReportWorkspaceSnapshot, subscribeToReportWorkspace } from "../reports/store";
+import { settingsEvents } from "../settings/events";
+import type { SetupStatus } from "../settings/types";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { setCommandSnapshot } from "./store";
+import type { CommandAttentionItem, CommandQueueLoad, CommandRunSummary, CommandSnapshot } from "./types";
+
+interface CommandReport {
+  id: string;
+  reference: string;
+  reasonCode: string;
+  queueId?: string;
+  state: string;
+  priority: number;
+  receivedAt: string;
+  claim?: { reviewerId?: string } | null;
+}
+
+interface WorkflowRun {
+  id: string;
+  reportId?: string;
+  workflowName?: string;
+  workflowKey?: string;
+  version?: string | number;
+  state: string;
+  openTaskCount?: number;
+  startedAt?: string;
+  createdAt: string;
+}
+
+interface ReportsResponse { reports?: CommandReport[] }
+interface QueuesResponse { queues?: QueueRecord[] }
+interface WorkflowRunsResponse { runs?: WorkflowRun[] }
+
+const closedReportStates = new Set(["resolved_by_human", "resolved_by_ai", "closed"]);
+const activeRunStates = new Set(["created", "dispatch_pending", "queued", "running", "waiting", "paused"]);
+
+let actorId = "";
+let reports: CommandReport[] = [];
+let queues: QueueRecord[] = [];
+let runs: WorkflowRun[] = [];
+let setup: SetupStatus | null = null;
+let loading = true;
+let reportSignature = "";
+let queueSignature = "";
+let refreshScheduled = false;
+let started = false;
+
+function reportDataSignature(): string {
+  return reports.map((report) => `${report.id}:${report.state}:${report.priority}:${report.claim?.reviewerId || ""}`).sort().join("|");
+}
+
+function reportStoreSignature(): string {
+  return getReportWorkspaceSnapshot().reports
+    .map((report) => `${report.id}:${report.state}:${report.priority}:${report.owner?.reviewerId || ""}`)
+    .sort()
+    .join("|");
+}
+
+function queueDataSignature(): string {
+  return queues.map((queue) => `${queue.id}:${queue.status}:${queue.activePolicy?.version || 0}`).sort().join("|");
+}
+
+function queueStoreSignature(): string {
+  return getQueueWorkspaceSnapshot().queues
+    .map((queue) => `${queue.id}:${queue.status}:${queue.activePolicy?.version || 0}`)
+    .sort()
+    .join("|");
+}
+
+function readable(value: string): string {
+  const copy = value.replaceAll("_", " ");
+  if (!copy) return "";
+  const sentence = `${copy.charAt(0).toUpperCase()}${copy.slice(1)}`;
+  const acronyms: Record<string, string> = { ai: "AI", api: "API", csv: "CSV", d1: "D1", http: "HTTP", https: "HTTPS", id: "ID", json: "JSON", r2: "R2", sla: "SLA", url: "URL" };
+  return sentence.replace(/\b(ai|api|csv|d1|http|https|id|json|r2|sla|url)\b/giu, (match) => acronyms[match.toLowerCase()] ?? match);
+}
+
+function relativeTime(value: string | undefined): string {
+  const milliseconds = Date.now() - Date.parse(value || "");
+  if (!Number.isFinite(milliseconds)) return "Unknown";
+  const minutes = Math.max(0, Math.floor(milliseconds / 60_000));
+  if (minutes < 1) return "Just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+function reset(): void {
+  reports = [];
+  queues = [];
+  runs = [];
+  setup = null;
+  loading = true;
+  reportSignature = "";
+  queueSignature = "";
+}
+
+function buildSnapshot(): CommandSnapshot {
+  const session = getShellSnapshot().session;
+  const openReports = reports.filter((report) => !closedReportStates.has(report.state));
+  const needsHuman = openReports.filter((report) => !report.claim || ["human_review", "waiting_for_human", "awaiting_reporter"].includes(report.state));
+  const activeRuns = runs.filter((run) => activeRunStates.has(run.state));
+  const operations = getOperationsWorkspaceSnapshot().operations;
+  const incidentCount = Number(operations?.incidents.open || 0) + Number(operations?.incidents.acknowledged || 0);
+  const displayName = session?.displayName || "there";
+
+  const attention: CommandAttentionItem[] = needsHuman.slice(0, 4).map((report) => ({
+    id: `report-${report.id}`,
+    icon: report.priority >= 80 ? "!" : "⌁",
+    title: `${report.reasonCode ? readable(report.reasonCode) : "Report"} needs review`,
+    detail: `${report.reference} · ${queues.find((queue) => queue.id === report.queueId)?.name || "Unrouted"} · ${relativeTime(report.receivedAt)}`,
+    meta: report.claim ? "Claimed" : "Unclaimed",
+    urgent: report.priority >= 80,
+    action: { type: "report", reportId: report.id },
+  }));
+  if (incidentCount > 0) attention.push({
+    id: "operations-incidents",
+    icon: "◇",
+    title: "Operations work needs attention",
+    detail: "An unresolved operational incident needs acknowledgement or recovery.",
+    meta: `${incidentCount} open`,
+    urgent: true,
+    action: { type: "view", view: "operations" },
+  });
+
+  const queueLoads: CommandQueueLoad[] = queues.filter((queue) => queue.status === "active").slice(0, 5).map((queue) => {
+    const queuedReports = openReports.filter((report) => report.queueId === queue.id);
+    const targetMinutes = Number(queue.activePolicy?.responseSlaMinutes || 60);
+    const oldest = queuedReports.reduce((value, report) => Math.min(value, Date.parse(report.receivedAt)), Date.now());
+    const ageMinutes = queuedReports.length ? Math.max(0, (Date.now() - oldest) / 60_000) : 0;
+    return {
+      id: queue.id,
+      name: queue.name,
+      targetMinutes,
+      openCount: queuedReports.length,
+      pressure: Math.min(100, Math.round((ageMinutes / Math.max(1, targetMinutes)) * 100)),
+    };
+  });
+
+  const recentRuns: CommandRunSummary[] = runs.slice(0, 5).map((run) => {
+    const report = reports.find((candidate) => candidate.id === run.reportId);
+    const waitingForHuman = Number(run.openTaskCount || 0) > 0;
+    return {
+      id: run.id,
+      title: run.workflowName || run.workflowKey || `Run ${run.id.slice(0, 8)}`,
+      detail: `${report?.reference || run.reportId || "Report"} · v${run.version || "—"}`,
+      status: waitingForHuman ? "Waiting for human" : readable(run.state),
+      tone: run.state === "failed" || run.state === "repair_required" ? "danger" : waitingForHuman || run.state === "waiting" ? "warning" : "neutral",
+      age: relativeTime(run.startedAt || run.createdAt).replace(" ago", ""),
+      action: run.reportId ? { type: "report", reportId: run.reportId } : { type: "view", view: "operations" },
+    };
+  });
+
+  const optionalSetup = new Set(setup?.optional || []);
+  const incompleteSetupCount = setup?.features.filter((feature) => feature.state !== "ready" && !optionalSetup.has(feature.featureKey)).length || 0;
+  return {
+    loading,
+    generatedAt: new Date().toISOString(),
+    firstName: displayName.split(" ")[0] || "there",
+    metrics: {
+      openReports: openReports.length,
+      needsHuman: needsHuman.length,
+      activeRuns: activeRuns.length,
+      unresolvedIncidents: incidentCount,
+    },
+    attention,
+    queueLoads,
+    recentRuns,
+    incompleteSetupCount,
+    permissions: {
+      useAssistant: session?.permissions.useAssistant === true,
+      manageWorkflows: session?.permissions.manageWorkflows === true,
+      viewAudit: session?.permissions.viewAudit === true,
+      manageInstallation: session?.permissions.manageInstallation === true,
+    },
+  };
+}
+
+function publish(): void {
+  setCommandSnapshot(buildSnapshot());
+}
+
+async function loadCommandData(): Promise<void> {
+  const session = getShellSnapshot().session;
+  if (!session) {
+    reset();
+    publish();
+    return;
+  }
+  loading = true;
+  publish();
+  const tasks: Promise<void>[] = [
+    requestJson<ReportsResponse>("/v1/admin/reports?limit=100")
+      .then((response) => { reports = response.reports || []; })
+      .catch(() => { reports = []; }),
+    requestJson<QueuesResponse>(`/v1/admin/queues${session.permissions.manageConfiguration ? "?include_archived=true" : ""}`)
+      .then((response) => { queues = response.queues || []; })
+      .catch(() => { queues = []; }),
+  ];
+  if (session.permissions.readRuns) {
+    tasks.push(requestJson<WorkflowRunsResponse>("/v1/admin/workflow-runs?limit=50")
+      .then((response) => { runs = response.runs || []; })
+      .catch(() => { runs = []; }));
+  } else {
+    runs = [];
+  }
+  await Promise.all(tasks);
+  reportSignature = reportStoreSignature();
+  queueSignature = queueStoreSignature();
+  loading = false;
+  publish();
+}
+
+function scheduleRefresh(): void {
+  if (loading || refreshScheduled || !getShellSnapshot().session) return;
+  refreshScheduled = true;
+  queueMicrotask(() => {
+    refreshScheduled = false;
+    if (reportDataSignature() === reportStoreSignature() && queueDataSignature() === queueStoreSignature()) return;
+    void loadCommandData();
+  });
+}
+
+export function startCommandController(): void {
+  if (started) return;
+  started = true;
+  subscribeToShell(() => {
+    const session = getShellSnapshot().session;
+    const nextActorId = session?.actor.id || "";
+    if (nextActorId === actorId) {
+      publish();
+      return;
+    }
+    actorId = nextActorId;
+    reset();
+    publish();
+    if (session) void loadCommandData();
+  });
+  subscribeToOperationsWorkspace(publish);
+  subscribeToReportWorkspace(() => {
+    const snapshot = getReportWorkspaceSnapshot();
+    const signature = reportStoreSignature();
+    if (!snapshot.loading && signature !== reportSignature) {
+      reportSignature = signature;
+      scheduleRefresh();
+    }
+  });
+  subscribeToQueueWorkspace(() => {
+    const snapshot = getQueueWorkspaceSnapshot();
+    const signature = queueStoreSignature();
+    if (!snapshot.loading && signature !== queueSignature) {
+      queueSignature = signature;
+      scheduleRefresh();
+    }
+  });
+  window.addEventListener(settingsEvents.setupUpdated, (event) => {
+    if (!(event instanceof CustomEvent) || !event.detail?.setup) return;
+    setup = event.detail.setup as SetupStatus;
+    publish();
+  });
+}

package/template/console/command/events.ts

@@ -0,0 +1,19 @@
+import type { CommandSnapshot } from "./types";
+
+export const commandEvents = {
+  state: "safest:command-centre:state",
+} as const;
+
+export function isCommandSnapshot(value: unknown): value is CommandSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<CommandSnapshot>;
+  return typeof candidate.loading === "boolean"
+    && typeof candidate.generatedAt === "string"
+    && typeof candidate.firstName === "string"
+    && typeof candidate.metrics === "object"
+    && Array.isArray(candidate.attention)
+    && Array.isArray(candidate.queueLoads)
+    && Array.isArray(candidate.recentRuns)
+    && typeof candidate.incompleteSetupCount === "number"
+    && typeof candidate.permissions === "object";
+}

package/template/console/command/store.ts

@@ -0,0 +1,36 @@
+import { commandEvents, isCommandSnapshot } from "./events";
+import type { CommandSnapshot } from "./types";
+
+const subscribers = new Set<() => void>();
+
+let snapshot: CommandSnapshot = {
+  loading: true,
+  generatedAt: new Date().toISOString(),
+  firstName: "there",
+  metrics: { openReports: 0, needsHuman: 0, activeRuns: 0, unresolvedIncidents: 0 },
+  attention: [],
+  queueLoads: [],
+  recentRuns: [],
+  incompleteSetupCount: 0,
+  permissions: { useAssistant: false, manageWorkflows: false, viewAudit: false, manageInstallation: false },
+};
+
+window.addEventListener(commandEvents.state, (event) => {
+  if (!(event instanceof CustomEvent) || !isCommandSnapshot(event.detail)) return;
+  snapshot = event.detail;
+  for (const subscriber of subscribers) subscriber();
+});
+
+export function getCommandSnapshot(): CommandSnapshot {
+  return snapshot;
+}
+
+export function setCommandSnapshot(next: CommandSnapshot | ((current: CommandSnapshot) => CommandSnapshot)): void {
+  snapshot = typeof next === "function" ? next(snapshot) : next;
+  for (const subscriber of subscribers) subscriber();
+}
+
+export function subscribeToCommand(callback: () => void): () => void {
+  subscribers.add(callback);
+  return () => subscribers.delete(callback);
+}

package/template/console/command/types.ts

@@ -0,0 +1,61 @@
+import type { WorkspaceView } from "../shell/types";
+
+export type CommandStatusTone = "neutral" | "warning" | "danger";
+
+export type CommandAction =
+  | { type: "report"; reportId: string }
+  | { type: "view"; view: WorkspaceView };
+
+export interface CommandMetricSnapshot {
+  openReports: number;
+  needsHuman: number;
+  activeRuns: number;
+  unresolvedIncidents: number;
+}
+
+export interface CommandAttentionItem {
+  id: string;
+  icon: string;
+  title: string;
+  detail: string;
+  meta: string;
+  urgent: boolean;
+  action: CommandAction;
+}
+
+export interface CommandQueueLoad {
+  id: string;
+  name: string;
+  targetMinutes: number;
+  openCount: number;
+  pressure: number;
+}
+
+export interface CommandRunSummary {
+  id: string;
+  title: string;
+  detail: string;
+  status: string;
+  tone: CommandStatusTone;
+  age: string;
+  action: CommandAction;
+}
+
+export interface CommandPermissions {
+  useAssistant: boolean;
+  manageWorkflows: boolean;
+  viewAudit: boolean;
+  manageInstallation: boolean;
+}
+
+export interface CommandSnapshot {
+  loading: boolean;
+  generatedAt: string;
+  firstName: string;
+  metrics: CommandMetricSnapshot;
+  attention: CommandAttentionItem[];
+  queueLoads: CommandQueueLoad[];
+  recentRuns: CommandRunSummary[];
+  incompleteSetupCount: number;
+  permissions: CommandPermissions;
+}

package/template/console/components/AnalystIdentity.tsx

@@ -0,0 +1,25 @@
+import type { CSSProperties } from "react";
+
+export interface AnalystIdentityData {
+  displayName: string;
+  avatarUrl?: string | null;
+  avatarColor?: string | null;
+}
+
+export function AnalystAvatar({ analyst, size = "normal" }: { analyst: AnalystIdentityData; size?: "normal" | "small" | "large" }) {
+  const style = { "--avatar-color": analyst.avatarColor || "#315d4d" } as CSSProperties;
+  return (
+    <span className={`analyst-avatar${size === "normal" ? "" : ` ${size}`}`} style={style}>
+      {analyst.avatarUrl ? <img src={analyst.avatarUrl} alt="" referrerPolicy="no-referrer" /> : analyst.displayName.trim().charAt(0).toUpperCase() || "?"}
+    </span>
+  );
+}
+
+export function AnalystIdentity({ analyst, detail }: { analyst: AnalystIdentityData; detail?: string }) {
+  return (
+    <span className="analyst-identity">
+      <AnalystAvatar analyst={analyst} />
+      <span><strong>{analyst.displayName || "Unknown analyst"}</strong>{detail ? <small>{detail}</small> : null}</span>
+    </span>
+  );
+}

package/template/console/components/PageHeader.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+
+export function PageHeader({
+  title,
+  description,
+  titleId,
+  accessory,
+  className = "",
+  children,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  titleId?: string;
+  accessory?: ReactNode;
+  className?: string;
+  children?: ReactNode;
+}) {
+  return (
+    <header className={`page-head console-page-head${className ? ` ${className}` : ""}`}>
+      <div className="page-title-group">
+        <div className="page-title-row"><h1 id={titleId}>{title}</h1>{accessory}</div>
+        {description ? <p>{description}</p> : null}
+      </div>
+      {children}
+    </header>
+  );
+}

package/template/console/configuration/ConfigurationDialog.tsx

@@ -0,0 +1,200 @@
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, type FormEvent } from "react";
+import { ApiRequestError, errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { configurationActionPath, configurationDefault, configurationEndpoint, configurationKeySlug, configurationLabel } from "./api";
+import { announceConfigurationChanged, configurationEvents } from "./events";
+import { editableReportForm, FormBuilder, reportFormContent, type EditableReportForm } from "./FormBuilder";
+import type {
+  ConfigurationDetailResponse,
+  ConfigurationDraft,
+  ConfigurationPublishResponse,
+  ConfigurationSaveResponse,
+  ConfigurationType,
+  ConfigurationValidation,
+  ConfigurationValidationResponse,
+  ConfigurationVersion,
+  JsonObject,
+  QueueListResponse,
+} from "./types";
+
+interface EditorRequest { type: ConfigurationType; key: string; exists: boolean }
+interface CheckedDraft { validation: ConfigurationValidation; saved: ConfigurationSaveResponse }
+
+function jsonObject(value: string): JsonObject {
+  const parsed: unknown = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Configuration JSON must be an object.");
+  return parsed as JsonObject;
+}
+
+function invalidResponse(cause: unknown): ConfigurationValidation | null {
+  if (!(cause instanceof ApiRequestError) || cause.status !== 422 || !cause.body || typeof cause.body !== "object") return null;
+  const response = cause.body as ConfigurationValidationResponse;
+  return response.validation || null;
+}
+
+function ValidationSummary({ validation, message }: { validation: ConfigurationValidation | null; message: string }) {
+  const className = `validation-summary${validation ? validation.valid ? " valid" : " invalid" : ""}`;
+  if (!validation) return <div className={className}>{message || "Not checked in this session."}</div>;
+  const issues = [...(validation.errors || []), ...(validation.warnings || [])];
+  return <div className={className}><strong>{message || (validation.valid ? "Ready to publish" : "Changes needed")}</strong>{issues.length ? <ul>{issues.map((issue, index) => <li key={`${issue.code}-${issue.path || index}`}>{issue.path ? `${issue.path}: ` : ""}{issue.message}</li>)}</ul> : <p>{validation.valid ? `No blocking problems. ${validation.warnings?.length || 0} warnings.` : "Review the configuration and check it again."}</p>}</div>;
+}
+
+export function ConfigurationDialog() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const keyRef = useRef<HTMLInputElement>(null);
+  const [editor, setEditor] = useState<EditorRequest | null>(null);
+  const [key, setKey] = useState("");
+  const [keyEdited, setKeyEdited] = useState(false);
+  const [keyLocked, setKeyLocked] = useState(false);
+  const [draft, setDraft] = useState<ConfigurationDraft | null>(null);
+  const [published, setPublished] = useState<ConfigurationVersion | null>(null);
+  const [form, setForm] = useState<EditableReportForm>(() => editableReportForm(configurationDefault("form")));
+  const [contentJson, setContentJson] = useState("{}");
+  const [baseline, setBaseline] = useState("");
+  const [validation, setValidation] = useState<ConfigurationValidation | null>(null);
+  const [validationMessage, setValidationMessage] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [action, setAction] = useState<"" | "save" | "validate" | "publish">("");
+  const [error, setError] = useState("");
+  const busy = loading || Boolean(action);
+  const type = editor?.type || "form";
+  const visualForm = type === "form";
+  const currentContent = useMemo(() => {
+    try { return visualForm ? reportFormContent(form) as unknown as JsonObject : jsonObject(contentJson); }
+    catch { return null; }
+  }, [contentJson, form, visualForm]);
+  const serialized = currentContent ? JSON.stringify(currentContent) : "";
+  const dirty = Boolean(editor && !loading && (serialized !== baseline || (!keyLocked && key !== editor.key)));
+
+  const clear = (): void => {
+    setEditor(null); setKey(""); setKeyEdited(false); setKeyLocked(false); setDraft(null); setPublished(null);
+    setContentJson("{}"); setBaseline(""); setValidation(null); setValidationMessage(""); setLoading(false); setAction(""); setError("");
+  };
+  const close = (): void => {
+    if (busy) return;
+    if (dirty && !window.confirm("Discard the unsaved configuration changes?")) return;
+    clear();
+  };
+
+  useEffect(() => {
+    const open = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || !["form", "routing_rules", "policy", "template"].includes(String(event.detail?.type))) return;
+      if (shell.session?.permissions.manageConfiguration !== true) return;
+      const nextType = event.detail.type as ConfigurationType;
+      setEditor({ type: nextType, key: typeof event.detail.key === "string" ? event.detail.key : "", exists: event.detail.exists === true });
+    };
+    window.addEventListener(configurationEvents.openEditor, open);
+    return () => window.removeEventListener(configurationEvents.openEditor, open);
+  }, [shell.session?.permissions.manageConfiguration]);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (editor && !dialog.open) { dialog.showModal(); requestAnimationFrame(() => keyRef.current?.focus()); }
+    if (!editor && dialog.open) dialog.close();
+  }, [editor]);
+  useEffect(() => {
+    if (!editor) return;
+    let active = true;
+    const load = async (): Promise<void> => {
+      setLoading(true); setError(""); setDraft(null); setPublished(null); setValidation(null); setValidationMessage(""); setBaseline("");
+      try {
+        const queueResponse = editor.type === "routing_rules" ? await requestJson<QueueListResponse>("/v1/admin/queues").catch(() => ({ queues: [] })) : { queues: [] };
+        const fallback = configurationDefault(editor.type, queueResponse.queues || []);
+        let content = fallback;
+        let nextDraft: ConfigurationDraft | null = null;
+        let nextPublished: ConfigurationVersion | null = null;
+        if (editor.exists) {
+          const result = await requestJson<ConfigurationDetailResponse>(configurationActionPath(editor.type, editor.key || "default", "draft"));
+          nextDraft = result.draft;
+          nextPublished = result.versions?.[0] || null;
+          content = nextDraft?.content || nextPublished?.content || fallback;
+        }
+        if (!active) return;
+        const resolvedKey = editor.type === "routing_rules" ? "default" : editor.key;
+        setKey(resolvedKey); setKeyEdited(Boolean(resolvedKey)); setKeyLocked(editor.type === "routing_rules" || editor.exists);
+        setDraft(nextDraft); setPublished(nextPublished); setContentJson(JSON.stringify(content, null, 2));
+        if (editor.type === "form") setForm(editableReportForm(content));
+        setBaseline(JSON.stringify(content));
+        if (nextDraft) {
+          setValidation(nextDraft.validation);
+          setValidationMessage(nextDraft.validation.valid ? "Stored check passed." : `${nextDraft.validation.errors?.length || 0} stored problems.`);
+        } else if (nextPublished) setValidationMessage(`Based on published version ${nextPublished.version}. Save to create an editable draft.`);
+        else setValidationMessage("Not saved yet.");
+      } catch (cause) { if (active) setError(errorMessage(cause, "The configuration draft could not be opened.")); }
+      finally { if (active) setLoading(false); }
+    };
+    void load();
+    return () => { active = false; };
+  }, [editor]);
+
+  const save = async (): Promise<ConfigurationSaveResponse | null> => {
+    if (!editor || !currentContent) { setError("Configuration JSON must be a valid object."); return null; }
+    const resolvedKey = type === "routing_rules" ? "default" : key.trim();
+    if (!resolvedKey) { setError("An internal name is required."); keyRef.current?.focus(); return null; }
+    if (draft && serialized === baseline) return { draftId: draft.id, revision: draft.revision, validation: draft.validation };
+    setAction("save"); setError("");
+    try {
+      const result = draft ? await requestJson<ConfigurationSaveResponse>(configurationActionPath(type, resolvedKey, "draft"), {
+        method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify({ expected_revision: draft.revision, content: currentContent }),
+      }) : await requestJson<ConfigurationSaveResponse>(`/v1/admin/${configurationEndpoint(type)}`, {
+        method: "POST", headers: mutationHeaders(), body: JSON.stringify({ key: resolvedKey, content: currentContent }),
+      });
+      setKey(resolvedKey); setKeyLocked(true); setBaseline(serialized);
+      setDraft((current) => ({
+        id: result.draftId || current?.id || "draft", configurationKey: resolvedKey, revision: result.revision,
+        validationStatus: result.validation.valid ? "valid" : "invalid", lastPublishedVersionId: current?.lastPublishedVersionId || null,
+        updatedAt: new Date().toISOString(), content: currentContent, validation: result.validation,
+      }));
+      setValidation(result.validation); setValidationMessage(`Draft revision ${result.revision} saved.`); announceConfigurationChanged();
+      return result;
+    } catch (cause) { setError(errorMessage(cause, "The configuration draft could not be saved.")); return null; }
+    finally { setAction(""); }
+  };
+
+  const validate = async (): Promise<CheckedDraft | null> => {
+    const saved = await save();
+    if (!saved || !editor) return null;
+    setAction("validate"); setError("");
+    try {
+      const result = await requestJson<ConfigurationValidationResponse>(configurationActionPath(type, type === "routing_rules" ? "default" : key, "validate"), { method: "POST" });
+      setValidation(result.validation); setValidationMessage(result.validation.valid ? "Ready to publish." : "Changes needed.");
+      setDraft((current) => current ? { ...current, validation: result.validation, validationStatus: result.validation.valid ? "valid" : "invalid" } : current);
+      return { validation: result.validation, saved };
+    } catch (cause) {
+      const invalid = invalidResponse(cause);
+      if (invalid) { setValidation(invalid); setValidationMessage("Changes needed."); return { validation: invalid, saved }; }
+      setError(errorMessage(cause, "The configuration check failed.")); return null;
+    } finally { setAction(""); }
+  };
+
+  const publish = async (): Promise<void> => {
+    const checked = await validate();
+    if (!checked?.validation.valid || !editor) return;
+    if (!window.confirm("Publish this immutable configuration version for future reports and workflow runs?")) return;
+    setAction("publish"); setError("");
+    try {
+      const result = await requestJson<ConfigurationPublishResponse>(configurationActionPath(type, type === "routing_rules" ? "default" : key, "publish"), { method: "POST", headers: mutationHeaders(), body: JSON.stringify({ expected_revision: checked.saved.revision }) });
+      setPublished({ id: result.versionId, version: result.version, content: currentContent || draft?.content || {}, publishedAt: new Date().toISOString() });
+      setValidationMessage(`Published version ${result.version}. Future reports and workflow runs can use it; historical work does not change.`);
+      announceConfigurationChanged();
+    } catch (cause) { setError(errorMessage(cause, "The configuration could not be published.")); }
+    finally { setAction(""); }
+  };
+
+  const updateForm = (next: EditableReportForm): void => {
+    if (!keyLocked && !keyEdited && next.title !== form.title) setKey(configurationKeySlug(next.title, ""));
+    setForm(next); setValidation(null); setValidationMessage("Unsaved changes.");
+  };
+  const title = `${editor?.exists ? "Edit" : "New"} ${configurationLabel(type).toLowerCase()}`;
+  const subtitle = loading ? "Loading configuration…" : `${key || "Unsaved draft"}${draft ? ` · Draft revision ${draft.revision}` : published ? ` · Based on published v${published.version}` : ""}`;
+  return <dialog ref={dialogRef} className="editor-dialog configuration-dialog" aria-labelledby="configuration-dialog-title" onCancel={(event) => { event.preventDefault(); close(); }} data-react-slice="configuration-dialog">
+    <div className="detail-head"><div><h2 id="configuration-dialog-title">{title}</h2><p>{subtitle}</p></div><button className="icon-button" type="button" aria-label="Close" disabled={busy} onClick={close}>×</button></div>
+    {loading ? <div className="configuration-dialog-loading"><div className="skeleton-block" role="status" aria-label="Loading configuration editor" /></div> : <form className="editor-form configuration-form" onSubmit={(event: FormEvent<HTMLFormElement>) => { event.preventDefault(); void save(); }}>
+      <label>Internal name <small>Used to identify this configuration in Safest.</small><input ref={keyRef} pattern="[a-z0-9]+(?:-[a-z0-9]+)*" required readOnly={keyLocked} disabled={busy} value={key} onChange={(event) => { setKeyEdited(true); setKey(event.currentTarget.value); }} /></label>
+      {visualForm ? <FormBuilder value={form} onChange={updateForm} disabled={busy} /> : <label>Configuration JSON<textarea className="code-input configuration-code" spellCheck={false} required disabled={busy} value={contentJson} onChange={(event) => { setContentJson(event.currentTarget.value); setValidation(null); setValidationMessage("Unsaved changes."); }} /></label>}
+      <ValidationSummary validation={validation} message={validationMessage} />
+      <div className="editor-footer"><p className="error" role="alert">{error}</p><div><button className="secondary" type="button" disabled={busy} onClick={close}>Cancel</button><button className="secondary" type="submit" disabled={busy || !dirty}>{action === "save" ? "Saving…" : "Save draft"}</button><button className="secondary" type="button" disabled={busy} onClick={() => void validate()}>{action === "validate" ? "Checking…" : "Check"}</button><button className="primary" type="button" disabled={busy} onClick={() => void publish()}>{action === "publish" ? "Publishing…" : "Publish"}</button></div></div>
+    </form>}
+  </dialog>;
+}