@spunto/design-system 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/workers/types.ts

@@ -26,8 +26,23 @@ export interface WorkerCardWorker {
   name?: string | null
   /** Fallback identity when `name` is empty — renders as "Workspace #3". */
   index?: number | null
-  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `error`. */
+  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `exited` | `unknown` | `error`. */
   state?: string | null
+  /**
+   * Why the worker is in that state, when there is a why: an exit code, a reason, and the status
+   * it came from. Read laxly on purpose — every field optional, an unrecognised `reason` yields no
+   * detail instead of an invented one. The strict version of this shape lives in
+   * `@spunto/build` (`WorkerStatusMeta`), which is where a control plane *writing* it should look.
+   */
+  statusMeta?: {
+    reason?: string | null
+    message?: string | null
+    exitCode?: number | null
+    oomKilled?: boolean | null
+    /** What the worker was before it became `unknown` — the buttons to offer depend on it. */
+    previousStatus?: string | null
+    at?: string | null
+  } | null
   /** Docker-level state: `running` | `stopped` | `exited` | `created` | `not_found` | `error`. */
   dockerState?: string | null
   createdAt?: string | null

package/src/components/workers/worker-status.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest"
+import { resolveWorkerStatus, workerStatusConfig } from "./worker-status"
+
+describe("resolveWorkerStatus — le node injoignable", () => {
+  it("ne prétend rien, et ne prétend surtout pas qu'un setup est en cours", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "unknown" })
+    expect(status.key).toBe("unknown")
+    expect(status.label).toBe("Unknown")
+    expect(status.settingUp).toBe(false)
+    expect(status.running).toBe(false)
+  })
+
+  it("prime sur un dockerState périmé", () => {
+    // Le cas réel : le dernier `inspect` réussi disait « running », puis le node est parti. La
+    // pastille doit dire qu'on ne sait pas, pas répéter une observation qu'on ne peut plus refaire.
+    const status = resolveWorkerStatus({ id: "w", state: "unknown", dockerState: "running" })
+    expect(status.key).toBe("unknown")
+  })
+
+  it("dit pourquoi, quand le plan de contrôle l'a dit", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "unknown",
+      statusMeta: { reason: "node-disconnected", previousStatus: "ready" },
+    })
+    expect(status.detail).toBe("The node is unreachable")
+  })
+})
+
+describe("resolveWorkerStatus — le conteneur mort tout seul", () => {
+  it("se résout sans dockerState, pour un produit qui n'a qu'un champ", () => {
+    // Spunto Lite n'a pas de second axe : avant, `exited` n'était atteignable que par la branche
+    // docker et un worker mort retombait sur le repli `pending`.
+    const status = resolveWorkerStatus({ id: "w", state: "exited" })
+    expect(status.key).toBe("exited")
+    expect(status.label).toBe("Exited")
+    expect(status.running).toBe(false)
+  })
+
+  it("porte le code de sortie quand il y en a un", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", exitCode: 137 },
+    })
+    expect(status.detail).toBe("Ran out of memory (exit 137)")
+  })
+
+  it("garde un code de sortie nul, qui est une valeur et pas une absence", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "completed", exitCode: 0 },
+    })
+    expect(status.detail).toBe("The container finished and exited cleanly (exit 0)")
+  })
+
+  it("préfère toujours le message du plan de contrôle à sa propre formulation", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", message: "Killed while compiling the kernel" },
+    })
+    expect(status.detail).toBe("Killed while compiling the kernel")
+  })
+})
+
+describe("resolveWorkerStatus — la tolérance qui fait vivre la table", () => {
+  it("n'invente pas de détail pour une raison qu'elle ne connaît pas", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "ready", statusMeta: { reason: "sonar-storm" } })
+    expect(status.detail).toBeUndefined()
+    expect(status.key).toBe("running")
+  })
+
+  it("laisse les statuts connus intacts", () => {
+    expect(resolveWorkerStatus({ id: "w", state: "building" }).settingUp).toBe(true)
+    expect(resolveWorkerStatus({ id: "w", state: "ready", dockerState: "running" }).key).toBe("running")
+    expect(resolveWorkerStatus({ id: "w", state: "wat" }).key).toBe("pending")
+  })
+
+  it("donne une pastille à chaque clé, sans exception", () => {
+    for (const [key, config] of Object.entries(workerStatusConfig)) {
+      expect(config.label, `"${key}" has no label`).toBeTruthy()
+      expect(config.dotClass, `"${key}" has no dot`).toBeTruthy()
+    }
+  })
+})

package/src/components/workers/worker-status.tsx

@@ -6,13 +6,18 @@
 // This module is the union of both, plus the transient states (`pulling`,
 // `stopping`, `deleting`) that only ever existed as ad-hoc `if`s above the table.
 //
-// `building` is the odd one out: it is the state a *control plane* reports, and
-// the only one here that Spunto Lite names and the dashboard does not. Both wait
-// for a project image before a container exists — Cloud does it inside
-// `provisioning` and rebuilds the fact client-side by joining the project's image
-// builds, Lite says it in the field. It is deliberately not folded into
-// `pulling`: building an image and pulling one are different waits, and only one
-// of them has a log worth opening.
+// Three keys here are *control plane* states rather than docker ones, and they
+// are the reason this table is not just a mapping of `docker inspect`:
+//
+// - `building` — waiting for the project image, before any container exists. Not
+//   folded into `pulling`: building an image and pulling one are different waits,
+//   and only one of them has a log worth opening.
+// - `exited` — the container died without being asked to. It already existed as a
+//   *docker* state; it is now also a lifecycle one, so a product with a single
+//   `state` field resolves it without falling through to the fallback.
+// - `unknown` — the node is unreachable, so we do not know. It claims nothing on
+//   purpose: showing the last known status as though it were current is the lie
+//   this key exists to avoid. `statusMeta.previousStatus` keeps what it was.
 //
 // No "use client": pure functions and hookless components, so a React Server
 // Component can call them.
@@ -30,6 +35,7 @@ export type WorkerStatusKey =
   | "pending"
   | "setup"
   | "building"
+  | "unknown"
   | "pulling"
   | "stopping"
   | "deleting"
@@ -89,6 +95,9 @@ export const workerStatusConfig: Record<WorkerStatusKey, WorkerStatusConfig> = {
   pending: BUSY,
   setup: { ...BUSY, label: "Setting up…" },
   building: { ...BUSY, label: "Building image…" },
+  // Volontairement neutre : ni jaune (rien n'est en cours, on ne sait pas), ni rouge
+  // (rien n'a échoué). C'est l'absence d'information, et elle a le droit de se voir.
+  unknown: { ...IDLE, label: "Unknown" },
   pulling: { ...BUSY, label: "Pulling image…" },
   stopping: { ...BUSY, label: "Stopping…" },
   deleting: { ...BUSY, label: "Deleting…" },
@@ -100,16 +109,51 @@ export interface WorkerStatus extends WorkerStatusConfig {
   settingUp: boolean
   /** Container up and past its setup — stats, git chips and the pulsing dot apply. */
   running: boolean
+  /**
+   * One sentence for what `statusMeta` carries — "Container ran out of memory", "was ready" —
+   * or `undefined` when there is nothing to add. The pill says *what*; this says *why*, and a
+   * consumer renders it beside the pill or not at all.
+   */
+  detail?: string
 }
 
 /** Lifecycle states that mean "not usable yet, a setup is in flight". */
 const SETUP_STATES = new Set(["provisioning", "starting", "setup"])
 
+/**
+ * Fallback phrasing per reason, used only when the control plane sent no `message`.
+ *
+ * Deliberately short and deliberately incomplete: a reason this table has never heard of yields
+ * no detail rather than an invented one — same rule as the status table itself.
+ */
+const REASON_PHRASES: Record<string, string> = {
+  "oom-killed": "Ran out of memory",
+  exited: "The container exited on its own",
+  completed: "The container finished and exited cleanly",
+  "removed-externally": "The container is gone from the node",
+  "setup-failed": "Setup failed inside the container",
+  "build-failed": "The project image could not be built",
+  "spawn-orphaned": "Startup was interrupted and cannot resume",
+  "node-lost": "The node disconnected before the container existed",
+  "node-disconnected": "The node is unreachable",
+}
+
+/** What `statusMeta` has to say, if anything: the message it carried, else its reason. */
+function detailOf(meta: WorkerCardWorker["statusMeta"]): string | undefined {
+  if (!meta) return undefined
+  if (meta.message) return meta.message
+  const phrase = meta.reason ? REASON_PHRASES[meta.reason] : undefined
+  if (!phrase) return undefined
+  // `exitCode` is worth showing when it is there — `0` included, which is why this is not `||`.
+  return meta.exitCode != null ? `${phrase} (exit ${meta.exitCode})` : phrase
+}
+
 /**
  * Worker snapshot → one status, tolerant of shapes it has never seen.
  *
  * Order matters: the *lifecycle* state wins whenever it describes an action in
- * flight (deleting, stopping, building, pulling, setting up), because docker still reports
+ * flight or already settled (deleting, stopping, unknown, exited, building, pulling, setting up),
+ * because docker still reports
  * the container as `running` throughout — showing "Running" while a worker is
  * being deleted is the bug this ordering exists to prevent. Past that, the
  * docker state is the truth. Apps with a single `state` field (Spunto Lite) fall
@@ -120,16 +164,24 @@ export function resolveWorkerStatus(worker: WorkerCardWorker): WorkerStatus {
   const state = worker.state ?? null
   const docker = worker.dockerState ?? null
 
+  const detail = detailOf(worker.statusMeta)
   const of = (key: WorkerStatusKey, flags?: Partial<Pick<WorkerStatus, "settingUp" | "running">>): WorkerStatus => ({
     key,
     ...workerStatusConfig[key],
     settingUp: false,
     running: key === "running",
+    ...(detail ? { detail } : {}),
     ...flags,
   })
 
   if (state === "deleting") return of("deleting")
   if (state === "stopping") return of("stopping")
+  // Le node est injoignable : on ne sait pas. Surtout pas `settingUp` — annoncer une progression
+  // pour une machine qu'on ne voit plus est exactement ce que ce statut existe pour éviter.
+  if (state === "unknown") return of("unknown")
+  // Mort tout seul. Le statut de cycle de vie prime sur `dockerState`, qui dirait la même chose
+  // quand il est là — et ne dirait rien du tout chez un produit qui n'a qu'un champ.
+  if (state === "exited") return of("exited")
   if (state === "building") return of("building", { settingUp: true })
   if (state === "pulling") return of("pulling", { settingUp: true })
   if (state && SETUP_STATES.has(state)) return of("setup", { settingUp: true })