create-safest-tools 0.2.0

package/template/console/main.tsx

@@ -0,0 +1,225 @@
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { AccountJourney } from "./auth/AccountJourney";
+import { AppealDialog, AppealWorkspace } from "./appeals/AppealWorkspace";
+import { startAppealController } from "./appeals/controller";
+import { startCommandController } from "./command/controller";
+import { AnalyticsWorkspace } from "./analytics/AnalyticsWorkspace";
+import { startAnalyticsController } from "./analytics/controller";
+import { AssistantWorkspace } from "./assistant/AssistantWorkspace";
+import { CommandCentre } from "./command/CommandCentre";
+import { ConfigurationDialog } from "./configuration/ConfigurationDialog";
+import { ConfigurationWorkspace } from "./configuration/ConfigurationWorkspace";
+import { QueueEditor } from "./queues/QueueEditor";
+import { QueueWorkspace } from "./queues/QueueWorkspace";
+import { RegistryDialog } from "./registry/RegistryDialog";
+import { RegistryWorkspace } from "./registry/RegistryWorkspace";
+import { QualityDialog, QualityWorkspace } from "./quality/QualityWorkspace";
+import { startQualityController } from "./quality/controller";
+import { startOperationsController } from "./operations/controller";
+import { startQueueController } from "./queues/controller";
+import { startReportController } from "./reports/controller";
+import { OperationsDialog, OperationsWorkspace } from "./operations/OperationsWorkspace";
+import { PeopleWorkspace } from "./people/PeopleWorkspace";
+import { ProfileWorkspace } from "./profile/ProfileWorkspace";
+import { ReportDrawer } from "./reports/ReportDrawer";
+import { ReportWorkspace } from "./reports/ReportWorkspace";
+import { ChannelDialog } from "./settings/ChannelDialog";
+import { SettingsWorkspace } from "./settings/SettingsWorkspace";
+import { WorkspaceShell } from "./shell/WorkspaceShell";
+import { startShellController } from "./shell/controller";
+import { WorkflowDialogs } from "./workflows/WorkflowDialogs";
+import { WorkflowWorkspace } from "./workflows/WorkflowWorkspace";
+
+const mount = document.querySelector<HTMLElement>("#operator-login-root");
+
+if (mount) {
+  const root = createRoot(mount);
+  flushSync(() => root.render(<AccountJourney />));
+  mount.dataset.reactMounted = "true";
+}
+
+const shellMount = document.querySelector<HTMLElement>("#workspace-shell-root");
+const navigationMount = document.querySelector<HTMLElement>("#workspace-navigation-root");
+
+if (shellMount && navigationMount) {
+  const shellRoot = createRoot(shellMount);
+  flushSync(() => shellRoot.render(<WorkspaceShell navigationTarget={navigationMount} />));
+  shellMount.dataset.reactMounted = "true";
+}
+
+const commandMount = document.querySelector<HTMLElement>("#command-centre-root");
+
+if (commandMount) {
+  const commandRoot = createRoot(commandMount);
+  flushSync(() => commandRoot.render(<CommandCentre />));
+  commandMount.dataset.reactMounted = "true";
+}
+
+const reportsMount = document.querySelector<HTMLElement>("#report-workspace-root");
+const reportDrawerMount = document.querySelector<HTMLElement>("#report-drawer-root");
+
+if (reportsMount && reportDrawerMount) {
+  const reportsRoot = createRoot(reportsMount);
+  const reportDrawerRoot = createRoot(reportDrawerMount);
+  flushSync(() => {
+    reportsRoot.render(<ReportWorkspace />);
+    reportDrawerRoot.render(<ReportDrawer />);
+  });
+  reportsMount.dataset.reactMounted = "true";
+  reportDrawerMount.dataset.reactMounted = "true";
+}
+
+const queuesMount = document.querySelector<HTMLElement>("#queue-workspace-root");
+const queueEditorMount = document.querySelector<HTMLElement>("#queue-editor-root");
+
+if (queuesMount && queueEditorMount) {
+  const queuesRoot = createRoot(queuesMount);
+  const queueEditorRoot = createRoot(queueEditorMount);
+  flushSync(() => {
+    queuesRoot.render(<QueueWorkspace />);
+    queueEditorRoot.render(<QueueEditor />);
+  });
+  queuesMount.dataset.reactMounted = "true";
+  queueEditorMount.dataset.reactMounted = "true";
+}
+
+const workflowsMount = document.querySelector<HTMLElement>("#workflow-workspace-root");
+const workflowDialogsMount = document.querySelector<HTMLElement>("#workflow-dialogs-root");
+
+if (workflowsMount && workflowDialogsMount) {
+  const workflowsRoot = createRoot(workflowsMount);
+  const workflowDialogsRoot = createRoot(workflowDialogsMount);
+  flushSync(() => {
+    workflowsRoot.render(<WorkflowWorkspace />);
+    workflowDialogsRoot.render(<WorkflowDialogs />);
+  });
+  workflowsMount.dataset.reactMounted = "true";
+  workflowDialogsMount.dataset.reactMounted = "true";
+}
+
+const registryMount = document.querySelector<HTMLElement>("#registry-workspace-root");
+const registryDialogMount = document.querySelector<HTMLElement>("#registry-dialog-root");
+
+if (registryMount && registryDialogMount) {
+  const registryRoot = createRoot(registryMount);
+  const registryDialogRoot = createRoot(registryDialogMount);
+  flushSync(() => {
+    registryRoot.render(<RegistryWorkspace />);
+    registryDialogRoot.render(<RegistryDialog />);
+  });
+  registryMount.dataset.reactMounted = "true";
+  registryDialogMount.dataset.reactMounted = "true";
+}
+
+const configurationMount = document.querySelector<HTMLElement>("#configuration-workspace-root");
+const configurationDialogMount = document.querySelector<HTMLElement>("#configuration-dialog-root");
+
+if (configurationMount && configurationDialogMount) {
+  const configurationRoot = createRoot(configurationMount);
+  const configurationDialogRoot = createRoot(configurationDialogMount);
+  flushSync(() => {
+    configurationRoot.render(<ConfigurationWorkspace />);
+    configurationDialogRoot.render(<ConfigurationDialog />);
+  });
+  configurationMount.dataset.reactMounted = "true";
+  configurationDialogMount.dataset.reactMounted = "true";
+}
+
+const appealsMount = document.querySelector<HTMLElement>("#appeal-workspace-root");
+const appealDialogMount = document.querySelector<HTMLElement>("#appeal-dialog-root");
+
+if (appealsMount && appealDialogMount) {
+  const appealsRoot = createRoot(appealsMount);
+  const appealDialogRoot = createRoot(appealDialogMount);
+  flushSync(() => {
+    appealsRoot.render(<AppealWorkspace />);
+    appealDialogRoot.render(<AppealDialog />);
+  });
+  appealsMount.dataset.reactMounted = "true";
+  appealDialogMount.dataset.reactMounted = "true";
+}
+
+const qualityMount = document.querySelector<HTMLElement>("#quality-workspace-root");
+const qualityDialogMount = document.querySelector<HTMLElement>("#quality-dialog-root");
+
+if (qualityMount && qualityDialogMount) {
+  const qualityRoot = createRoot(qualityMount);
+  const qualityDialogRoot = createRoot(qualityDialogMount);
+  flushSync(() => {
+    qualityRoot.render(<QualityWorkspace />);
+    qualityDialogRoot.render(<QualityDialog />);
+  });
+  qualityMount.dataset.reactMounted = "true";
+  qualityDialogMount.dataset.reactMounted = "true";
+}
+
+const operationsMount = document.querySelector<HTMLElement>("#operations-workspace-root");
+const operationsDialogMount = document.querySelector<HTMLElement>("#operations-dialog-root");
+
+if (operationsMount && operationsDialogMount) {
+  const operationsRoot = createRoot(operationsMount);
+  const operationsDialogRoot = createRoot(operationsDialogMount);
+  flushSync(() => {
+    operationsRoot.render(<OperationsWorkspace />);
+    operationsDialogRoot.render(<OperationsDialog />);
+  });
+  operationsMount.dataset.reactMounted = "true";
+  operationsDialogMount.dataset.reactMounted = "true";
+}
+
+const analyticsMount = document.querySelector<HTMLElement>("#analytics-workspace-root");
+
+if (analyticsMount) {
+  const analyticsRoot = createRoot(analyticsMount);
+  flushSync(() => analyticsRoot.render(<AnalyticsWorkspace />));
+  analyticsMount.dataset.reactMounted = "true";
+}
+
+const peopleMount = document.querySelector<HTMLElement>("#people-workspace-root");
+
+if (peopleMount) {
+  const peopleRoot = createRoot(peopleMount);
+  flushSync(() => peopleRoot.render(<PeopleWorkspace />));
+  peopleMount.dataset.reactMounted = "true";
+}
+
+const profileMount = document.querySelector<HTMLElement>("#profile-workspace-root");
+
+if (profileMount) {
+  const profileRoot = createRoot(profileMount);
+  flushSync(() => profileRoot.render(<ProfileWorkspace />));
+  profileMount.dataset.reactMounted = "true";
+}
+
+const assistantMount = document.querySelector<HTMLElement>("#assistant-workspace-root");
+
+if (assistantMount) {
+  const assistantRoot = createRoot(assistantMount);
+  flushSync(() => assistantRoot.render(<AssistantWorkspace />));
+  assistantMount.dataset.reactMounted = "true";
+}
+
+startAnalyticsController();
+startAppealController();
+startQualityController();
+startOperationsController();
+startQueueController();
+startReportController();
+startCommandController();
+
+const settingsMount = document.querySelector<HTMLElement>("#settings-workspace-root");
+const channelDialogMount = document.querySelector<HTMLElement>("#channel-dialog-root");
+
+if (settingsMount && channelDialogMount) {
+  const settingsRoot = createRoot(settingsMount);
+  const channelDialogRoot = createRoot(channelDialogMount);
+  flushSync(() => {
+    settingsRoot.render(<SettingsWorkspace />);
+    channelDialogRoot.render(<ChannelDialog />);
+  });
+  settingsMount.dataset.reactMounted = "true";
+  channelDialogMount.dataset.reactMounted = "true";
+}
+
+startShellController();

package/template/console/operations/OperationsWorkspace.tsx

@@ -0,0 +1,126 @@
+import { useEffect, useRef, useState, useSyncExternalStore, type FormEvent, type ReactNode } from "react";
+import { PageHeader } from "../components/PageHeader";
+import { readable, relativeTime } from "../lib/format";
+import {
+  dispatchAcknowledgeOperationsIncident,
+  dispatchCloseOperationsIncident,
+  dispatchOpenOperationsIncident,
+  dispatchOperationsFilters,
+  dispatchOperationsRefresh,
+  dispatchResolveOperationsIncident,
+  dispatchRetryOperationsIncident,
+} from "./events";
+import { getOperationsWorkspaceSnapshot, subscribeToOperationsWorkspace } from "./store";
+import type { OperationsDeadLetter, OperationsDeliveryFailure, OperationsIncidentSummary, OperationsResolutionInput } from "./types";
+
+function amount(value: number | undefined): number { return Number.isFinite(value) ? Number(value) : 0; }
+
+function Metric({ label, value, detail, urgent = false }: { label: string; value: number | string; detail: string; urgent?: boolean }) {
+  return <article className={urgent ? "urgent" : undefined}><span>{label}</span><strong>{value}</strong><small>{detail}</small></article>;
+}
+
+function IncidentRow({ incident }: { incident: OperationsIncidentSummary }) {
+  const urgent = ["high", "critical"].includes(incident.severity) && incident.state !== "resolved";
+  return (
+    <article className="operation-incident-row">
+      <div><strong>{incident.title}</strong><small>{readable(incident.category)} · {incident.occurrenceCount} occurrence{incident.occurrenceCount === 1 ? "" : "s"} · {relativeTime(incident.lastSeenAt)}</small></div>
+      <span className={`badge${urgent ? " urgent" : ""}`}>{readable(incident.severity)}</span>
+      <span className="operation-state">{readable(incident.state)}</span>
+      <button className="secondary" type="button" onClick={() => dispatchOpenOperationsIncident(incident.id)}>Inspect</button>
+    </article>
+  );
+}
+
+function FailureRecord({ item }: { item: OperationsDeadLetter | OperationsDeliveryFailure }) {
+  const deadLetter = "jobType" in item;
+  const title = deadLetter
+    ? `${readable(item.jobType)} · ${item.jobId || item.id}`
+    : `${readable(item.deliveryType)} · ${item.reportReference}`;
+  const summary = deadLetter
+    ? `Dead-lettered ${relativeTime(item.lastSeenAt)} · ${item.occurrenceCount} occurrence${item.occurrenceCount === 1 ? "" : "s"}`
+    : `${item.attemptCount} attempt${item.attemptCount === 1 ? "" : "s"} · ${relativeTime(item.updatedAt)}`;
+  return <article><div><strong>{title}</strong><small>{summary}</small></div><span className="badge urgent">{readable(item.errorCode || "Delivery failed")}</span></article>;
+}
+
+export function OperationsWorkspace() {
+  const snapshot = useSyncExternalStore(subscribeToOperationsWorkspace, getOperationsWorkspaceSnapshot, getOperationsWorkspaceSnapshot);
+  const operations = snapshot.operations;
+  const routingFailures = amount(operations?.routing.failed) + amount(operations?.routing.deadLetter);
+  const actionFailures = amount(operations?.actions.retrying) + amount(operations?.actions.terminalFailed);
+  const noticeFailures = amount(operations?.notifications.retrying) + amount(operations?.notifications.terminalFailed)
+    + amount(operations?.emails.retrying) + amount(operations?.emails.terminalFailed);
+  const openIncidents = amount(operations?.incidents.open) + amount(operations?.incidents.acknowledged);
+  const failureRecords = [...(operations?.deadLetters ?? []), ...(operations?.deliveryFailures ?? [])];
+  const updateFilters = (key: "state" | "severity", value: string): void => {
+    dispatchOperationsFilters({ ...snapshot.filters, [key]: value } as typeof snapshot.filters);
+  };
+
+  return (
+    <div className="page-stack" data-react-slice="operations-workspace">
+      <PageHeader titleId="operations-title" title="Operations" description="Review failed deliveries, exhausted retries, and other incidents.">
+        <div className="surface-buttons"><button className="secondary" type="button" disabled={snapshot.refreshing || !snapshot.canRead} onClick={dispatchOperationsRefresh}>{snapshot.refreshing ? "Refreshing…" : "Refresh"}</button></div>
+      </PageHeader>
+      <section className="surface operations-surface" aria-labelledby="operations-title">
+        <div className="operation-metrics" aria-busy={snapshot.loading || snapshot.refreshing}>
+          <Metric label="Routing failures" value={snapshot.loading ? "—" : routingFailures} detail="Failed or dead-letter jobs" urgent={routingFailures > 0} />
+          <Metric label="Action failures" value={snapshot.loading ? "—" : actionFailures} detail="Retrying or terminal" urgent={actionFailures > 0} />
+          <Metric label="Notice failures" value={snapshot.loading ? "—" : noticeFailures} detail="Email and webhook delivery" urgent={noticeFailures > 0} />
+          <Metric label="Open incidents" value={snapshot.loading ? "—" : openIncidents} detail={`${amount(operations?.incidents.highPriority)} high priority`} urgent={amount(operations?.incidents.highPriority) > 0} />
+        </div>
+        <div className="surface-head operations-section-head"><div><h2>Operational incidents</h2><p>Durable records that can be acknowledged, retried, or resolved.</p></div><div className="filters operations-filters"><label>State<select value={snapshot.filters.state} onChange={(event) => updateFilters("state", event.currentTarget.value)}><option value="">All states</option><option value="open">Open</option><option value="acknowledged">Acknowledged</option><option value="mitigated">Mitigated</option><option value="resolved">Resolved</option></select></label><label>Severity<select value={snapshot.filters.severity} onChange={(event) => updateFilters("severity", event.currentTarget.value)}><option value="">All severities</option><option value="critical">Critical</option><option value="high">High</option><option value="medium">Medium</option><option value="low">Low</option><option value="info">Info</option></select></label></div></div>
+        <div className="operation-incident-list" aria-busy={snapshot.loading || snapshot.refreshing}>
+          {snapshot.loading ? <div className="skeleton-block" role="status" aria-label="Loading operational incidents" /> : snapshot.incidents.length ? snapshot.incidents.map((incident) => <IncidentRow incident={incident} key={incident.id} />) : <div className="empty compact"><span aria-hidden="true">✓</span><h3>No incidents in this view</h3><p>An incident appears here when a failed job needs manual repair.</p></div>}
+        </div>
+        {failureRecords.length ? <><div className="surface-head operations-section-head"><div><h2>Recent failure records</h2><p>Retry and dead-letter evidence retained for investigation.</p></div></div><div className="operation-list">{failureRecords.map((item) => <FailureRecord item={item} key={`${"jobType" in item ? "dead" : "delivery"}-${item.id}`} />)}</div></> : null}
+        <p className="error surface-error" role="alert">{snapshot.error}</p>
+      </section>
+    </div>
+  );
+}
+
+function Fact({ label, children }: { label: string; children: ReactNode }) {
+  return <><dt>{label}</dt><dd>{children || "—"}</dd></>;
+}
+
+export function OperationsDialog() {
+  const snapshot = useSyncExternalStore(subscribeToOperationsWorkspace, getOperationsWorkspaceSnapshot, getOperationsWorkspaceSnapshot);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const [resolutionCode, setResolutionCode] = useState("manual_resolution");
+  const [summary, setSummary] = useState("");
+  const record = snapshot.detail.record;
+  const incident = record?.incident;
+  const resolved = incident?.state === "resolved";
+  const pending = snapshot.detail.pendingAction;
+  const canMutate = snapshot.canOperate && !resolved && !pending;
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (snapshot.detail.incidentId && !dialog.open) dialog.showModal();
+    if (!snapshot.detail.incidentId && dialog.open) dialog.close();
+  }, [snapshot.detail.incidentId]);
+  useEffect(() => { setResolutionCode("manual_resolution"); setSummary(""); }, [snapshot.detail.incidentId]);
+
+  const resolve = (event: FormEvent<HTMLFormElement>): void => {
+    event.preventDefault();
+    const input: OperationsResolutionInput = { resolutionCode, summary };
+    dispatchResolveOperationsIncident(input);
+  };
+
+  return (
+    <dialog ref={dialogRef} className="detail-dialog operations-dialog" aria-labelledby="operations-incident-title" onCancel={(event) => { event.preventDefault(); dispatchCloseOperationsIncident(); }} data-react-slice="operations-dialog">
+      <div className="detail-head"><div><h2 id="operations-incident-title">{incident?.title || "Operational incident"}</h2><p>{incident ? `${readable(incident.severity)} · ${readable(incident.state)}` : snapshot.detail.loading ? "Loading incident…" : "Operations"}</p></div><button className="icon-button" type="button" aria-label="Close operational incident" onClick={dispatchCloseOperationsIncident}>×</button></div>
+      <div className="operations-detail-content">
+        {snapshot.detail.loading && !record ? <div className="skeleton-block" role="status" aria-label="Loading operational incident" /> : record && incident ? <>
+          <p className="operations-summary">{incident.summary}</p>
+          <div className="detail-grid"><section><h3>Incident</h3><dl><Fact label="Category">{readable(incident.category)}</Fact><Fact label="Entity">{incident.entityType ? `${readable(incident.entityType)} · ${incident.entityId || "—"}` : "—"}</Fact><Fact label="Occurrences">{incident.occurrenceCount}</Fact><Fact label="First seen">{new Date(incident.firstSeenAt).toLocaleString()}</Fact><Fact label="Last seen">{new Date(incident.lastSeenAt).toLocaleString()}</Fact></dl></section><section><h3>Ownership and resolution</h3><dl><Fact label="Acknowledged by">{incident.acknowledgedBy || "Not acknowledged"}</Fact><Fact label="Acknowledged at">{incident.acknowledgedAt ? new Date(incident.acknowledgedAt).toLocaleString() : "—"}</Fact><Fact label="Resolved by">{incident.resolvedBy || "Not resolved"}</Fact><Fact label="Resolution">{incident.resolutionSummary || "—"}</Fact></dl></section></div>
+          {incident.metadata && Object.keys(incident.metadata as object).length ? <section><h3>Diagnostic metadata</h3><pre>{JSON.stringify(incident.metadata, null, 2)}</pre></section> : null}
+          <section><h3>Dead-letter records</h3><div className="operation-detail-list">{record.deadLetters.length ? record.deadLetters.map((item) => <article key={item.id}><div><strong>{readable(item.jobType)} · {item.jobId || item.id}</strong><small>{item.occurrenceCount} occurrence{item.occurrenceCount === 1 ? "" : "s"} · {relativeTime(item.lastSeenAt)}</small></div><span className="badge urgent">{readable(item.errorCode || item.state)}</span></article>) : <p>No dead-letter record is attached.</p>}</div></section>
+          {record.repairs.length ? <section><h3>Repair history</h3><div className="operation-detail-list">{record.repairs.map((repair) => <article key={repair.id}><div><strong>{readable(repair.actionType)}</strong><small>{readable(repair.entityType)} · {repair.entityId} · {new Date(repair.plannedAt).toLocaleString()}</small></div><span className="badge">{readable(repair.state)}</span></article>)}</div></section> : null}
+          {!resolved ? <div className="operations-actions"><div><button className="secondary" type="button" disabled={!canMutate || incident.state !== "open"} onClick={dispatchAcknowledgeOperationsIncident}>{pending === "acknowledge" ? "Acknowledging…" : "Acknowledge"}</button><button className="secondary" type="button" disabled={!canMutate || !record.deadLetters.length} onClick={dispatchRetryOperationsIncident}>{pending === "retry" ? "Retrying…" : "Retry safe record"}</button></div><form onSubmit={resolve}><label>Resolution code<input pattern="[a-z][a-z0-9_]{1,63}" maxLength={64} required disabled={!canMutate} value={resolutionCode} onChange={(event) => setResolutionCode(event.currentTarget.value)} /></label><label>Resolution summary<textarea minLength={3} maxLength={2000} required disabled={!canMutate} value={summary} onChange={(event) => setSummary(event.currentTarget.value)} /></label><button className="primary" type="submit" disabled={!canMutate}>{pending === "resolve" ? "Resolving…" : "Resolve incident"}</button></form></div> : null}
+        </> : null}
+        <p className="error" role="alert">{snapshot.detail.error}</p>
+      </div>
+    </dialog>
+  );
+}

package/template/console/operations/controller.ts

@@ -0,0 +1,237 @@
+import { errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { operationsEvents } from "./events";
+import { getOperationsWorkspaceSnapshot, setOperationsWorkspaceSnapshot } from "./store";
+import type {
+  OperationsFilters,
+  OperationsIncidentRecord,
+  OperationsIncidentSummary,
+  OperationsPendingAction,
+  OperationsResolutionInput,
+  OperationsSnapshotCounts,
+  OperationsWorkspaceSnapshot,
+} from "./types";
+
+interface OperationsResponse { operations?: OperationsSnapshotCounts | null }
+interface IncidentListResponse { incidents?: OperationsIncidentSummary[] }
+
+const initialSnapshot = (): OperationsWorkspaceSnapshot => ({
+  loading: true,
+  refreshing: false,
+  error: "",
+  canRead: false,
+  canOperate: false,
+  operations: null,
+  incidents: [],
+  filters: { state: "", severity: "" },
+  detail: { incidentId: null, loading: false, error: "", pendingAction: null, record: null },
+});
+
+let actorId = "";
+let requestVersion = 0;
+let started = false;
+
+function permissions(snapshot: OperationsWorkspaceSnapshot): OperationsWorkspaceSnapshot {
+  const session = getShellSnapshot().session;
+  return {
+    ...snapshot,
+    canRead: session?.permissions.readOperations === true,
+    canOperate: session?.permissions.operateSystem === true,
+  };
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function normalizeIncident(value: unknown): OperationsIncidentSummary {
+  const incident = recordValue(value);
+  return {
+    id: stringValue(incident.id),
+    incidentKey: stringValue(incident.incidentKey ?? incident.incident_key),
+    severity: stringValue(incident.severity),
+    category: stringValue(incident.category),
+    state: stringValue(incident.state),
+    title: stringValue(incident.title),
+    summary: stringValue(incident.summary),
+    entityType: nullableString(incident.entityType ?? incident.entity_type),
+    entityId: nullableString(incident.entityId ?? incident.entity_id),
+    occurrenceCount: Number(incident.occurrenceCount ?? incident.occurrence_count ?? 0),
+    firstSeenAt: stringValue(incident.firstSeenAt ?? incident.first_seen_at),
+    lastSeenAt: stringValue(incident.lastSeenAt ?? incident.last_seen_at),
+    acknowledgedBy: nullableString(incident.acknowledgedBy ?? incident.acknowledged_by),
+    acknowledgedAt: nullableString(incident.acknowledgedAt ?? incident.acknowledged_at),
+    resolvedBy: nullableString(incident.resolvedBy ?? incident.resolved_by),
+    resolvedAt: nullableString(incident.resolvedAt ?? incident.resolved_at),
+    resolutionSummary: nullableString(incident.resolutionSummary ?? incident.resolution_summary),
+    metadata: incident.metadata ?? {},
+  };
+}
+
+function normalizeIncidentRecord(value: unknown): OperationsIncidentRecord {
+  const result = recordValue(value);
+  const deadLetters = Array.isArray(result.deadLetters) ? result.deadLetters : [];
+  const repairs = Array.isArray(result.repairs) ? result.repairs : [];
+  return {
+    incident: normalizeIncident(result.incident),
+    deadLetters: deadLetters.map((entry) => {
+      const item = recordValue(entry);
+      return {
+        id: stringValue(item.id),
+        jobType: stringValue(item.jobType ?? item.job_type),
+        jobId: nullableString(item.jobId ?? item.job_id),
+        state: stringValue(item.state),
+        errorCode: nullableString(item.errorCode ?? item.error_code),
+        occurrenceCount: Number(item.occurrenceCount ?? item.occurrence_count ?? 0),
+        lastSeenAt: stringValue(item.lastSeenAt ?? item.last_seen_at),
+      };
+    }),
+    repairs: repairs.map((entry) => {
+      const item = recordValue(entry);
+      return {
+        id: stringValue(item.id),
+        actionType: stringValue(item.actionType ?? item.action_type),
+        entityType: stringValue(item.entityType ?? item.entity_type),
+        entityId: stringValue(item.entityId ?? item.entity_id),
+        state: stringValue(item.state),
+        plannedBy: nullableString(item.plannedBy ?? item.planned_by),
+        plannedAt: stringValue(item.plannedAt ?? item.planned_at),
+        appliedAt: nullableString(item.appliedAt ?? item.applied_at),
+        errorCode: nullableString(item.errorCode ?? item.error_code),
+      };
+    }),
+  };
+}
+
+async function loadOperations(): Promise<void> {
+  const session = getShellSnapshot().session;
+  if (!session?.permissions.readOperations) {
+    setOperationsWorkspaceSnapshot(permissions({ ...initialSnapshot(), loading: false }));
+    return;
+  }
+  const current = getOperationsWorkspaceSnapshot();
+  setOperationsWorkspaceSnapshot(permissions({ ...current, error: "", refreshing: !current.loading }));
+  const query = new URLSearchParams({ limit: "100" });
+  if (current.filters.state) query.set("state", current.filters.state);
+  if (current.filters.severity) query.set("severity", current.filters.severity);
+  try {
+    const [snapshotResponse, incidentResponse] = await Promise.all([
+      requestJson<OperationsResponse>("/v1/admin/operations"),
+      requestJson<IncidentListResponse>(`/v1/admin/operations/incidents?${query}`),
+    ]);
+    setOperationsWorkspaceSnapshot((snapshot) => permissions({
+      ...snapshot,
+      operations: snapshotResponse.operations ?? null,
+      incidents: (incidentResponse.incidents ?? []).map(normalizeIncident),
+    }));
+  } catch (cause) {
+    setOperationsWorkspaceSnapshot((snapshot) => ({ ...snapshot, error: errorMessage(cause, "Operations could not be loaded.") }));
+  } finally {
+    setOperationsWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, loading: false, refreshing: false }));
+  }
+}
+
+async function openIncident(incidentId: string): Promise<void> {
+  const version = ++requestVersion;
+  setOperationsWorkspaceSnapshot((snapshot) => permissions({
+    ...snapshot,
+    detail: {
+      ...snapshot.detail,
+      incidentId,
+      loading: true,
+      error: "",
+      record: snapshot.detail.record?.incident.id === incidentId ? snapshot.detail.record : null,
+    },
+  }));
+  try {
+    const response = await requestJson<unknown>(`/v1/admin/operations/incidents/${encodeURIComponent(incidentId)}`);
+    if (version !== requestVersion || getOperationsWorkspaceSnapshot().detail.incidentId !== incidentId) return;
+    setOperationsWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, detail: { ...snapshot.detail, record: normalizeIncidentRecord(response) } }));
+  } catch (cause) {
+    if (version !== requestVersion || getOperationsWorkspaceSnapshot().detail.incidentId !== incidentId) return;
+    setOperationsWorkspaceSnapshot((snapshot) => ({ ...snapshot, detail: { ...snapshot.detail, error: errorMessage(cause, "The operational incident could not be opened.") } }));
+  } finally {
+    if (version === requestVersion && getOperationsWorkspaceSnapshot().detail.incidentId === incidentId) {
+      setOperationsWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, detail: { ...snapshot.detail, loading: false } }));
+    }
+  }
+}
+
+function closeIncident(): void {
+  requestVersion += 1;
+  setOperationsWorkspaceSnapshot((snapshot) => permissions({
+    ...snapshot,
+    detail: { incidentId: null, loading: false, error: "", pendingAction: null, record: null },
+  }));
+}
+
+async function mutateIncident(action: Exclude<OperationsPendingAction, null>, input?: OperationsResolutionInput): Promise<void> {
+  const snapshot = getOperationsWorkspaceSnapshot();
+  const incidentId = snapshot.detail.incidentId;
+  if (!incidentId || !snapshot.canOperate || snapshot.detail.pendingAction) return;
+  setOperationsWorkspaceSnapshot({ ...snapshot, detail: { ...snapshot.detail, error: "", pendingAction: action } });
+  try {
+    await requestJson(`/v1/admin/operations/incidents/${encodeURIComponent(incidentId)}/${action}`, {
+      method: "POST",
+      headers: mutationHeaders(action === "resolve"),
+      ...(action === "resolve" && input ? { body: JSON.stringify({ resolution_code: input.resolutionCode, summary: input.summary }) } : {}),
+    });
+    await loadOperations();
+    await openIncident(incidentId);
+  } catch (cause) {
+    const fallback = action === "acknowledge" ? "The incident could not be acknowledged."
+      : action === "retry" ? "The incident could not be retried."
+        : "The incident could not be resolved.";
+    setOperationsWorkspaceSnapshot((current) => ({ ...current, detail: { ...current.detail, error: errorMessage(cause, fallback) } }));
+  } finally {
+    setOperationsWorkspaceSnapshot((current) => permissions({ ...current, detail: { ...current.detail, pendingAction: null } }));
+  }
+}
+
+function validFilters(value: unknown): value is OperationsFilters {
+  if (!value || typeof value !== "object") return false;
+  const filters = value as Partial<OperationsFilters>;
+  return ["", "open", "acknowledged", "mitigated", "resolved"].includes(filters.state ?? "invalid")
+    && ["", "info", "low", "medium", "high", "critical"].includes(filters.severity ?? "invalid");
+}
+
+export function startOperationsController(): void {
+  if (started) return;
+  started = true;
+  subscribeToShell(() => {
+    const session = getShellSnapshot().session;
+    const nextActorId = session?.actor.id || "";
+    if (nextActorId === actorId) {
+      setOperationsWorkspaceSnapshot((snapshot) => permissions(snapshot));
+      return;
+    }
+    actorId = nextActorId;
+    requestVersion += 1;
+    setOperationsWorkspaceSnapshot(initialSnapshot());
+    if (session) void loadOperations();
+  });
+  window.addEventListener(operationsEvents.refresh, () => { void loadOperations(); });
+  window.addEventListener(operationsEvents.filters, (event) => {
+    if (!(event instanceof CustomEvent) || !validFilters(event.detail)) return;
+    setOperationsWorkspaceSnapshot((snapshot) => ({ ...snapshot, filters: event.detail }));
+    void loadOperations();
+  });
+  window.addEventListener(operationsEvents.open, (event) => {
+    if (event instanceof CustomEvent && typeof event.detail?.incidentId === "string") void openIncident(event.detail.incidentId);
+  });
+  window.addEventListener(operationsEvents.close, closeIncident);
+  window.addEventListener(operationsEvents.acknowledge, () => { void mutateIncident("acknowledge"); });
+  window.addEventListener(operationsEvents.retry, () => { void mutateIncident("retry"); });
+  window.addEventListener(operationsEvents.resolve, (event) => {
+    if (!(event instanceof CustomEvent) || typeof event.detail?.resolutionCode !== "string" || typeof event.detail?.summary !== "string") return;
+    void mutateIncident("resolve", event.detail as OperationsResolutionInput);
+  });
+}

package/template/console/operations/events.ts

@@ -0,0 +1,37 @@
+import type { OperationsFilters, OperationsResolutionInput, OperationsWorkspaceSnapshot } from "./types";
+
+export const operationsEvents = {
+  state: "safest:operations:state",
+  refresh: "safest:operations:refresh",
+  filters: "safest:operations:filters",
+  open: "safest:operations:open",
+  close: "safest:operations:close",
+  acknowledge: "safest:operations:acknowledge",
+  retry: "safest:operations:retry",
+  resolve: "safest:operations:resolve",
+} as const;
+
+function dispatch<TDetail>(type: string, detail?: TDetail): void {
+  window.dispatchEvent(detail === undefined ? new Event(type) : new CustomEvent(type, { detail }));
+}
+
+export function dispatchOperationsRefresh(): void { dispatch(operationsEvents.refresh); }
+export function dispatchOperationsFilters(filters: OperationsFilters): void { dispatch(operationsEvents.filters, filters); }
+export function dispatchOpenOperationsIncident(incidentId: string): void { dispatch(operationsEvents.open, { incidentId }); }
+export function dispatchCloseOperationsIncident(): void { dispatch(operationsEvents.close); }
+export function dispatchAcknowledgeOperationsIncident(): void { dispatch(operationsEvents.acknowledge); }
+export function dispatchRetryOperationsIncident(): void { dispatch(operationsEvents.retry); }
+export function dispatchResolveOperationsIncident(input: OperationsResolutionInput): void { dispatch(operationsEvents.resolve, input); }
+
+export function isOperationsWorkspaceSnapshot(value: unknown): value is OperationsWorkspaceSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<OperationsWorkspaceSnapshot>;
+  return typeof candidate.loading === "boolean"
+    && typeof candidate.refreshing === "boolean"
+    && typeof candidate.error === "string"
+    && typeof candidate.canRead === "boolean"
+    && typeof candidate.canOperate === "boolean"
+    && Array.isArray(candidate.incidents)
+    && typeof candidate.filters === "object"
+    && typeof candidate.detail === "object";
+}