@nwire/studio 0.12.1 → 0.13.0

package/src/lib/dispatch-form.ts

@@ -0,0 +1,160 @@
+/**
+ * Dispatch form — pure helpers behind the Operate › Dispatch panel.
+ *
+ * The dispatchable targets come straight from the native manifest's flat
+ * arrays (`actions`, `queries`) — these carry the JSON `inputSchema` that the
+ * deep `model` action node drops (the model keeps only emits/retry). So this
+ * reads the schema-bearing flat arrays rather than the graph nodes.
+ *
+ * Everything here is pure so it unit-tests without a DOM or a live wire.
+ */
+import type { Manifest } from "./manifest";
+
+/** A handler the Dispatch panel can invoke via `POST /_nwire/dispatch`. */
+export interface DispatchTarget {
+  readonly name: string;
+  readonly app: string;
+  readonly kind: "action" | "query";
+  readonly description?: string;
+  /** JSON-schema-shaped input (present for actions; queries usually omit it). */
+  readonly inputSchema?: unknown;
+}
+
+/** A flat, form-renderable view of one top-level schema property. */
+export interface SchemaField {
+  readonly name: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly default?: unknown;
+  readonly enum?: string[];
+}
+
+interface RawEntry {
+  name?: unknown;
+  app?: unknown;
+  description?: unknown;
+  inputSchema?: unknown;
+}
+
+function toTargets(list: unknown, kind: DispatchTarget["kind"]): DispatchTarget[] {
+  if (!Array.isArray(list)) return [];
+  const out: DispatchTarget[] = [];
+  for (const raw of list as RawEntry[]) {
+    if (typeof raw?.name !== "string") continue;
+    out.push({
+      name: raw.name,
+      app: typeof raw.app === "string" ? raw.app : "",
+      kind,
+      description: typeof raw.description === "string" ? raw.description : undefined,
+      inputSchema: raw.inputSchema,
+    });
+  }
+  return out;
+}
+
+/**
+ * Every dispatchable handler in the manifest — actions first (they carry input
+ * schemas and are the common case), then queries. Tolerant of a partial or old
+ * manifest: missing arrays simply contribute nothing.
+ */
+export function dispatchTargets(manifest: Manifest | null | undefined): DispatchTarget[] {
+  if (!manifest) return [];
+  const m = manifest as unknown as { actions?: unknown; queries?: unknown };
+  return [...toTargets(m.actions, "action"), ...toTargets(m.queries, "query")];
+}
+
+/** Free-text filter over name / app / description (case-insensitive). */
+export function filterTargets(targets: readonly DispatchTarget[], query: string): DispatchTarget[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [...targets];
+  return targets.filter(
+    (t) =>
+      t.name.toLowerCase().includes(q) ||
+      t.app.toLowerCase().includes(q) ||
+      (t.description ?? "").toLowerCase().includes(q),
+  );
+}
+
+interface JsonSchemaProp {
+  type?: string | string[];
+  default?: unknown;
+  enum?: unknown[];
+  format?: string;
+}
+
+interface JsonSchema {
+  properties?: Record<string, JsonSchemaProp>;
+  required?: unknown;
+}
+
+function asSchema(schema: unknown): JsonSchema | null {
+  if (!schema || typeof schema !== "object") return null;
+  const s = schema as JsonSchema;
+  return s.properties && typeof s.properties === "object" ? s : null;
+}
+
+/** Flatten a JSON schema's top-level properties into form-field rows. */
+export function schemaFields(schema: unknown): SchemaField[] {
+  const s = asSchema(schema);
+  if (!s) return [];
+  const required = new Set<string>(Array.isArray(s.required) ? (s.required as string[]) : []);
+  const out: SchemaField[] = [];
+  for (const [name, raw] of Object.entries(s.properties ?? {})) {
+    const p = raw ?? {};
+    const t = Array.isArray(p.type) ? p.type.join(" | ") : (p.type ?? "any");
+    out.push({
+      name,
+      type: t,
+      required: required.has(name),
+      default: p.default,
+      enum: Array.isArray(p.enum) ? p.enum.map(String) : undefined,
+    });
+  }
+  return out;
+}
+
+/** Seed a sensible input object from a schema's defaults + types. */
+export function scaffoldInput(schema: unknown): Record<string, unknown> {
+  const s = asSchema(schema);
+  if (!s) return {};
+  const scaffold: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(s.properties ?? {})) {
+    if (prop.default !== undefined) {
+      scaffold[key] = prop.default;
+      continue;
+    }
+    const t = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+    switch (t) {
+      case "string":
+        scaffold[key] = "";
+        break;
+      case "number":
+      case "integer":
+        scaffold[key] = 0;
+        break;
+      case "boolean":
+        scaffold[key] = false;
+        break;
+      case "array":
+        scaffold[key] = [];
+        break;
+      case "object":
+        scaffold[key] = {};
+        break;
+      default:
+        scaffold[key] = null;
+    }
+  }
+  return scaffold;
+}
+
+/** Can this field render as a single inline control (vs. the JSON textarea)? */
+export function isInlineRenderable(field: SchemaField): boolean {
+  const t = field.type.split(" | ")[0];
+  return t === "string" || t === "number" || t === "integer" || t === "boolean";
+}
+
+/** True when every field is a primitive the inline form can render. */
+export function allInlineRenderable(fields: readonly SchemaField[]): boolean {
+  return fields.length > 0 && fields.every(isInlineRenderable);
+}

package/src/lib/error-friendly.ts

@@ -0,0 +1,288 @@
+/**
+ * Friendly errors — turn a raw failure record into something a human reads once
+ * and knows what to do about. The runtime stamps machine-shaped failures
+ * (`action.failed`, `dlq.recorded`, `external.call.failed`, …) carrying a
+ * `SerializedError` + retry counters; this maps the common shapes to a plain
+ * title, a one-sentence summary that names the failing unit, an actionable next
+ * step, and a severity. Pure + data-driven so it unit-tests without a DOM and
+ * the Errors view, the cards, and Storybook all read failures the same way.
+ */
+import type { TelemetryRecord } from "./telemetry";
+
+/** How loud this failure should read. `critical` = the system gave up. */
+export type Severity = "critical" | "high" | "warning" | "info";
+
+/** The failure family we recognised — drives icon + copy. */
+export type ErrorCategory =
+  | "validation"
+  | "declined"
+  | "unauthorized"
+  | "not-found"
+  | "conflict"
+  | "timeout"
+  | "dead-letter"
+  | "exhausted"
+  | "external"
+  | "downstream"
+  | "unknown";
+
+/** The failing unit a record points at (action / projection / call / …). */
+export interface FailureSubject {
+  readonly kind: string;
+  readonly name: string;
+}
+
+/** Normalised retry state across the different failure shapes. */
+export interface AttemptInfo {
+  /** The attempt this record represents, when it carries one. */
+  readonly attempt?: number;
+  /** The ceiling, when declared. */
+  readonly maxAttempts?: number;
+  /** Total attempts made (DLQ / exhausted records report this). */
+  readonly attempts?: number;
+  /** The runtime intends to try again. */
+  readonly willRetry: boolean;
+  /** This failure ended in the dead-letter queue / exhausted retries. */
+  readonly terminal: boolean;
+}
+
+/** The humanised view of one failure record. */
+export interface FriendlyError {
+  readonly title: string;
+  readonly summary: string;
+  readonly suggestion: string;
+  readonly severity: Severity;
+  readonly category: ErrorCategory;
+  readonly subject: FailureSubject;
+  readonly attempt: AttemptInfo;
+  /** The raw error message, kept for the evidence/detail surfaces. */
+  readonly rawMessage?: string;
+}
+
+const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+const num = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+
+/** The unit that failed — read off whichever id field the record carries. */
+export function subjectOf(r: TelemetryRecord): FailureSubject {
+  const action = str(r.action);
+  if (action) return { kind: "action", name: action };
+  const projection = str(r.projection);
+  if (projection) return { kind: "projection", name: projection };
+  const workflow = str(r.workflow);
+  if (workflow) return { kind: "workflow", name: workflow };
+  const call = str(r.call);
+  if (call) return { kind: "external call", name: call };
+  const query = str(r.query);
+  if (query) return { kind: "query", name: query };
+  const listener = str(r.listener);
+  if (listener) return { kind: "listener", name: listener };
+  return { kind: "operation", name: str(r.sourceEvent) ?? "an operation" };
+}
+
+/** Normalise the various retry counters onto one shape. */
+export function attemptOf(r: TelemetryRecord): AttemptInfo {
+  const attempt = num(r.attempt);
+  const attempts = num(r.attempts);
+  const maxAttempts = num(r.maxAttempts);
+  const terminal = r.kind === "dlq.recorded" || r.kind === "reaction.exhausted";
+  // `willRetry` is explicit on the retrying shapes; terminal failures never do.
+  const willRetry = terminal ? false : r.error == null ? false : Boolean(r.willRetry);
+  return { attempt, maxAttempts, attempts, willRetry, terminal };
+}
+
+/** A short, human retry line — `attempt 2 of 3, retrying` / `3 attempts, dead-lettered`. */
+export function retryNarrative(r: TelemetryRecord): string | null {
+  const a = attemptOf(r);
+  if (a.terminal && a.attempts) {
+    return `${a.attempts} ${a.attempts === 1 ? "attempt" : "attempts"} — gave up`;
+  }
+  if (a.attempt && a.maxAttempts) {
+    return `attempt ${a.attempt} of ${a.maxAttempts}${a.willRetry ? ", retrying" : ""}`;
+  }
+  if (a.attempt && a.attempt > 1) return `attempt ${a.attempt}`;
+  return null;
+}
+
+interface ErrorFacts {
+  readonly name?: string;
+  readonly message?: string;
+  readonly code?: string | number;
+}
+
+function errorFacts(r: TelemetryRecord): ErrorFacts {
+  const e = r.error;
+  const code = e && "code" in e ? (e.code as string | number | undefined) : undefined;
+  return { name: e?.name, message: e?.message, code };
+}
+
+const has = (haystack: string | undefined, re: RegExp): boolean => !!haystack && re.test(haystack);
+
+/**
+ * Classify a failure into a known family. Terminal forge outcomes
+ * (dead-letter / exhausted) own their headline regardless of the underlying
+ * cause — "it gave up" is the story, and the cause still shows in the summary +
+ * evidence. Otherwise read the error name/message/code (most specific), then
+ * fall back to the remaining record kinds.
+ */
+export function categorize(r: TelemetryRecord): ErrorCategory {
+  if (r.kind === "dlq.recorded") return "dead-letter";
+  if (r.kind === "reaction.exhausted") return "exhausted";
+
+  const { name, message, code } = errorFacts(r);
+  const n = name ?? "";
+  const m = message ?? "";
+
+  if (
+    has(n, /zod|validation|invalidinput/i) ||
+    has(m, /\b(invalid|required|must be|expected|schema)\b/i)
+  )
+    return "validation";
+  if (code === 401 || code === 403 || has(n, /unauthor|forbidden|denied/i)) return "unauthorized";
+  if (code === 404 || has(n, /notfound/i) || has(m, /not found|does not exist|unknown id/i))
+    return "not-found";
+  if (code === 409 || has(n, /conflict/i) || has(m, /already exists|conflict|duplicate|version/i))
+    return "conflict";
+  if (
+    code === 402 ||
+    has(n, /declin|rejected|paymentfailed/i) ||
+    has(m, /declin|rejected|insufficient/i)
+  )
+    return "declined";
+  if (has(n, /timeout|aborterror/i) || has(m, /timed? ?out|timeout|deadline|aborted/i))
+    return "timeout";
+
+  switch (r.kind) {
+    case "external.call.failed":
+      return "external";
+    case "projection.failed":
+    case "reaction.failed":
+    case "event.listener.failed":
+    case "enqueue.failed":
+      return "downstream";
+    default:
+      return "unknown";
+  }
+}
+
+interface CategoryCopy {
+  readonly title: string;
+  /** `(subject, message) => summary` */
+  readonly summary: (s: FailureSubject, m?: string) => string;
+  readonly suggestion: string;
+}
+
+const COPY: Record<ErrorCategory, CategoryCopy> = {
+  validation: {
+    title: "Invalid input",
+    summary: (s) => `${s.name} rejected its input — the payload didn't match the schema.`,
+    suggestion: "Check the caller's payload against the handler's `input` contract.",
+  },
+  declined: {
+    title: "Declined",
+    summary: (s, m) => `${s.name} was declined${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "A business rule said no. This is expected control flow, not a crash — surface it to the caller.",
+  },
+  unauthorized: {
+    title: "Not allowed",
+    summary: (s) => `${s.name} ran without permission to do what it tried.`,
+    suggestion: "Confirm the caller's auth / tenant scope and the handler's policy.",
+  },
+  "not-found": {
+    title: "Not found",
+    summary: (s, m) => `${s.name} couldn't find something it needed${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "The referenced id may be wrong, deleted, or not yet projected. Check upstream writes.",
+  },
+  conflict: {
+    title: "Conflict",
+    summary: (s, m) => `${s.name} hit a conflicting state${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "Likely a duplicate or a concurrent write. Retry on a fresh read, or make the op idempotent.",
+  },
+  timeout: {
+    title: "Timed out",
+    summary: (s) => `${s.name} didn't finish in time.`,
+    suggestion:
+      "Check the downstream it waits on, or raise the timeout if the work is genuinely slow.",
+  },
+  "dead-letter": {
+    title: "Dead-lettered",
+    summary: (s, m) =>
+      `${s.name} failed every retry and was parked in the dead-letter queue${m ? ` — ${m}` : "."}`,
+    suggestion: "Inspect the payload + root error, fix the cause, then replay from the DLQ.",
+  },
+  exhausted: {
+    title: "Retries exhausted",
+    summary: (s, m) => `${s.name} gave up after exhausting its retries${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "The failure is persistent, not transient. Fix the underlying cause before it retries again.",
+  },
+  external: {
+    title: "External call failed",
+    summary: (s, m) => `The external call ${s.name} failed${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "Check the third-party endpoint's health + credentials. The fault is likely outside the app.",
+  },
+  downstream: {
+    title: "Downstream failed",
+    summary: (s, m) => `${s.name} failed while reacting to an event${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "A projection / reaction couldn't keep up. The read model or saga may now be behind.",
+  },
+  unknown: {
+    title: "Failed",
+    summary: (s, m) => `${s.name} threw an unexpected error${m ? ` — ${m}` : "."}`,
+    suggestion:
+      "Open the evidence tab for the stack + payload, then trace the chain that led here.",
+  },
+};
+
+const KIND_SEVERITY: Record<string, Severity> = {
+  "dlq.recorded": "critical",
+  "reaction.exhausted": "critical",
+  "projection.failed": "high",
+  "event.listener.failed": "high",
+  "enqueue.failed": "high",
+};
+
+/**
+ * Severity for a failure. Terminal shapes are loudest; a failure that will
+ * still retry is only a warning (the system hasn't given up yet); validation /
+ * declined are expected control-flow, also a warning.
+ */
+export function severityOf(r: TelemetryRecord): Severity {
+  const a = attemptOf(r);
+  const fixed = KIND_SEVERITY[r.kind];
+  if (fixed) return fixed;
+  if (a.willRetry) return "warning";
+  const category = categorize(r);
+  if (category === "validation" || category === "declined" || category === "unauthorized")
+    return "warning";
+  return "high";
+}
+
+const SEVERITY_RANK: Record<Severity, number> = { info: 0, warning: 1, high: 2, critical: 3 };
+
+/** Pick the louder of two severities. */
+export function maxSeverity(a: Severity, b: Severity): Severity {
+  return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+
+/** The full humanised view of one failure record. */
+export function explainError(r: TelemetryRecord): FriendlyError {
+  const category = categorize(r);
+  const subject = subjectOf(r);
+  const facts = errorFacts(r);
+  const copy = COPY[category];
+  return {
+    title: copy.title,
+    summary: copy.summary(subject, facts.message),
+    suggestion: copy.suggestion,
+    severity: severityOf(r),
+    category,
+    subject,
+    attempt: attemptOf(r),
+    rawMessage: facts.message,
+  };
+}

package/src/lib/home.ts

@@ -0,0 +1,191 @@
+/**
+ * Pure helpers for the Home dashboard — stat derivation, health classification,
+ * project sorting, and activity formatting. Kept DOM-free so they unit-test in
+ * isolation; `Home.vue` and its composables stay thin orchestration.
+ */
+import type { DiscoveredProject } from "../composables/useDiscovery";
+import type { ManifestView } from "./manifest";
+import type { TelemetryRecord } from "./telemetry";
+import { isFailure } from "./telemetry";
+import { recordColorKey } from "./kind-colors";
+
+/**
+ * A project's reachability, derived from its live status. The server reports
+ * `{ hasManifest, processes }` per cwd (see `/__nwire/projects/status`):
+ *
+ *   - `running`     — at least one live process is registered
+ *   - `on-disk`     — no process, but a `.nwire/manifest.json` exists (browsable)
+ *   - `unreachable` — neither a process nor a manifest (stale catalog entry)
+ */
+export type ProjectHealth = "running" | "on-disk" | "unreachable";
+
+/** Status fields we actually read off the discovery response (shape is server-owned). */
+interface StatusShape {
+  readonly hasManifest?: boolean;
+  readonly processes?: ReadonlyArray<{ readonly port?: number }>;
+  readonly running?: boolean;
+  readonly port?: number;
+}
+
+/** Classify a discovered project's reachability from its live status. */
+export function projectHealth(project: DiscoveredProject): ProjectHealth {
+  const status = project.status as StatusShape | undefined;
+  const procCount = status?.processes?.length ?? 0;
+  if (procCount > 0 || status?.running === true) return "running";
+  if (status?.hasManifest === true) return "on-disk";
+  return "unreachable";
+}
+
+/** Map a health to a `StatusBadge` status token. */
+export function healthBadge(health: ProjectHealth): "live" | "idle" | "error" {
+  switch (health) {
+    case "running":
+      return "live";
+    case "on-disk":
+      return "idle";
+    case "unreachable":
+      return "error";
+  }
+}
+
+/** Human label for a health state. */
+export function healthLabel(health: ProjectHealth): string {
+  switch (health) {
+    case "running":
+      return "Running";
+    case "on-disk":
+      return "On disk";
+    case "unreachable":
+      return "Unreachable";
+  }
+}
+
+/** First live port for a running project, if the status carries one. */
+export function projectPort(project: DiscoveredProject): number | undefined {
+  const status = project.status as StatusShape | undefined;
+  return status?.processes?.find((p) => typeof p.port === "number")?.port ?? status?.port;
+}
+
+const HEALTH_RANK: Record<ProjectHealth, number> = {
+  running: 0,
+  "on-disk": 1,
+  unreachable: 2,
+};
+
+/**
+ * Sort discovered projects for the grid: active first, then by health
+ * (running → on-disk → unreachable), then alphabetically. Pure; returns a new
+ * array.
+ */
+export function sortProjects(projects: readonly DiscoveredProject[]): DiscoveredProject[] {
+  return [...projects].sort((a, b) => {
+    if (a.active !== b.active) return a.active ? -1 : 1;
+    const rank = HEALTH_RANK[projectHealth(a)] - HEALTH_RANK[projectHealth(b)];
+    if (rank !== 0) return rank;
+    return a.snapshot.name.localeCompare(b.snapshot.name);
+  });
+}
+
+/** The quick-stat counts shown on a project card, from its catalog snapshot. */
+export interface ProjectStats {
+  readonly apps: number;
+  readonly plugins: number;
+  readonly actions: number;
+  readonly events: number;
+  readonly resolvers: number;
+  readonly workflows: number;
+}
+
+/**
+ * Composition counts for a project card. Drawn from the catalog snapshot the
+ * project's own Studio last wrote — tolerant of an absent snapshot (a freshly
+ * discovered project that hasn't been opened yet shows zeros, not a crash).
+ */
+export function projectStats(project: DiscoveredProject): ProjectStats {
+  const c = project.snapshot.composition;
+  return {
+    apps: c?.apps ?? 0,
+    plugins: c?.plugins ?? 0,
+    actions: c?.actions ?? 0,
+    events: c?.events ?? 0,
+    resolvers: c?.resolvers ?? 0,
+    workflows: c?.workflows ?? 0,
+  };
+}
+
+/** True when a snapshot carries no composition yet (manifest not generated). */
+export function statsArePending(project: DiscoveredProject): boolean {
+  return project.snapshot.composition == null;
+}
+
+/** One KPI in the active-project quick-stats strip. */
+export interface QuickStat {
+  readonly label: string;
+  readonly value: number;
+  readonly kind: string;
+}
+
+/**
+ * Quick-stats for the active project's KPI strip, derived from the live
+ * manifest view + a telemetry error count. Tolerates a null view (manifest not
+ * loaded / empty) by reporting zeros. Pure.
+ */
+export function quickStats(view: ManifestView | null, errorCount: number): QuickStat[] {
+  const count = (kind: string) => (view ? view.byKind(kind).length : 0);
+  const total = view ? view.model.nodes.length : 0;
+  return [
+    { label: "Nodes", value: total, kind: "app" },
+    { label: "Actions", value: count("action"), kind: "action" },
+    { label: "Events", value: count("event"), kind: "event" },
+    { label: "Projections", value: count("projection"), kind: "projection" },
+    { label: "Errors", value: errorCount, kind: "error" },
+  ];
+}
+
+/** Count failure records in a telemetry buffer (the "errors in window" KPI). */
+export function countErrors(records: readonly TelemetryRecord[]): number {
+  let n = 0;
+  for (const r of records) if (isFailure(r)) n++;
+  return n;
+}
+
+/** A compact activity row for the recent-activity feed. */
+export interface ActivityItem {
+  readonly kind: string;
+  /** Colour key for `kindColor`/`KindBadge` (the dotted kind's family). */
+  readonly colorKey: string;
+  /** Short human label — the handler/event name where present, else the kind. */
+  readonly label: string;
+  readonly ts?: string;
+  readonly correlationId?: string;
+  readonly failed: boolean;
+}
+
+/**
+ * Pull a stable label out of a telemetry record — the named subject
+ * (action/event/handler) when present, falling back to the kind.
+ */
+export function activityLabel(rec: TelemetryRecord): string {
+  const candidates = ["action", "event", "handler", "name", "query", "actor", "projection"];
+  for (const key of candidates) {
+    const v = (rec as Record<string, unknown>)[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return rec.kind;
+}
+
+/**
+ * The latest `limit` telemetry records as compact activity items, newest first.
+ * The buffer is oldest-first; we take the tail and reverse. Pure.
+ */
+export function recentActivity(records: readonly TelemetryRecord[], limit = 8): ActivityItem[] {
+  const tail = records.slice(Math.max(0, records.length - limit));
+  return tail.reverse().map((rec) => ({
+    kind: rec.kind,
+    colorKey: recordColorKey(rec.kind),
+    label: activityLabel(rec),
+    ts: rec.ts,
+    correlationId: rec.envelope?.correlationId,
+    failed: isFailure(rec),
+  }));
+}