makersclaw 0.8.0 → 0.8.1

package/registry/blocks/run-history/run-history.jsx

@@ -0,0 +1,218 @@
+"use client";
+
+// A job's runs, the account of one, and the overview of them all. Props
+// in, callbacks out; the block never reads runs itself and formats no
+// time (each comes in as words). Tokens only. An outcome is a mark AND a
+// word, so it is never told by colour alone. Its own width decides its
+// layout (@container), never the viewport.
+//
+// RunHistory and RunAccount moved from the CRM (makersclaw-store
+// packages/crm 0.7.0) into the template's kit (0.8.1, D15); RunOverview
+// is new.
+
+import { Icon, cx } from "../../ui";
+
+const MARK = {
+  ok: { icon: "circle-check", tone: "text-success", word: "Completed" },
+  done: { icon: "circle-check", tone: "text-success", word: "Completed" },
+  complete: { icon: "circle-check", tone: "text-success", word: "Completed" },
+  failed: { icon: "circle-x", tone: "text-destructive", word: "Failed" },
+  running: { icon: "loader", tone: "text-info", word: "Running" },
+  needs_you: { icon: "circle-help", tone: "text-warning", word: "Needs you" },
+  stopped: { icon: "stop", tone: "text-muted-foreground", word: "Stopped" },
+  skipped: { icon: "minus", tone: "text-muted-foreground", word: "Skipped" },
+};
+const markOf = (s) => MARK[s] ?? MARK.skipped;
+const spin = (s) => (s === "running" ? "animate-spin motion-reduce:animate-none" : null);
+
+/** A count as the overview shows it: words as they come, a number with
+ *  its thousands marked the same way on the server and in the browser. */
+function countOf(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value.toLocaleString("en-US");
+  return value ?? "—";
+}
+
+/**
+ * The runs, newest first.
+ *
+ *   runs       [{ id, status, title, line, cost?, when? }]
+ *              status: ok|done|failed|running|needs_you|stopped|skipped
+ *              title: "Run #7 · Tue 29 Sep, 07:02 · Read now, by Owen"; line: what it did
+ *              when:  the muted words at its end ("yesterday", "2 min")
+ *   selected   the id shown in the account
+ *   onSelect(run)
+ *   empty      what an empty history says
+ */
+export function RunHistory({ runs = [], selected, onSelect, label = "Runs", empty, className }) {
+  if (!runs.length) return <div className={cx("p-4 text-sm text-muted-foreground", className)}>{empty ?? "No runs yet."}</div>;
+  return (
+    <ul aria-label={label} className={cx("m-0 grid min-w-0 list-none p-0", className)}>
+      {runs.map((r) => {
+        const m = markOf(r.status);
+        const on = r.id === selected;
+        const tail = r.cost || r.when;
+        return (
+          <li key={r.id} className="min-w-0">
+            <button
+              type="button"
+              aria-current={on ? "true" : undefined}
+              onClick={() => onSelect?.(r)}
+              className={cx(
+                "grid w-full grid-cols-[16px_minmax(0,1fr)_auto] items-start gap-2.5 border-b border-border px-3.5 py-2.5 text-left text-[13px] outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+                on ? "bg-accent text-accent-foreground" : "hover:bg-muted",
+              )}
+            >
+              <Icon name={m.icon} size={16} className={cx("mt-0.5", m.tone, spin(r.status))} label={m.word} />
+              <span className="grid min-w-0 gap-0.5">
+                <span className={cx("truncate", on && "font-semibold")}>{r.title}</span>
+                {r.line ? (
+                  <span className={cx("truncate text-xs", r.status === "failed" ? "text-destructive" : on ? "" : "text-muted-foreground")}>{r.line}</span>
+                ) : null}
+              </span>
+              {tail ? (
+                <span className={cx("grid justify-items-end gap-0.5 whitespace-nowrap text-xs tabular-nums", on ? "" : "text-muted-foreground")}>
+                  {r.when ? <span>{r.when}</span> : null}
+                  {r.cost ? <span>{r.cost}</span> : null}
+                </span>
+              ) : null}
+            </button>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+function StepsStrip({ steps }) {
+  return (
+    <ol aria-label="Steps" className="m-0 flex list-none flex-wrap items-center gap-y-2 p-0">
+      {steps.map((s, i) => {
+        const m = markOf(s.status);
+        return (
+          <li key={`${s.label}-${i}`} className="flex min-w-0 items-center">
+            {i ? <span aria-hidden="true" className="h-px w-4 shrink-0 bg-border" /> : null}
+            <span className="grid min-w-0 max-w-full gap-0.5 rounded-[var(--radius)] border border-border bg-card px-2.5 py-2 text-card-foreground @xs:min-w-[150px]">
+              <b className="truncate text-xs font-semibold">{s.label}</b>
+              <span className={cx("flex items-center gap-1 text-[11.5px]", m.tone)}>
+                <Icon name={m.icon} size={12} className={spin(s.status)} />
+                {m.word}
+                {s.count ? <span>· {s.count}</span> : null}
+              </span>
+            </span>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}
+
+const BAR = { neutral: "bg-muted-foreground", danger: "bg-destructive", info: "bg-info" };
+
+/**
+ * One run's account.
+ *
+ *   title    "Tue 29 Sep, 07:02"
+ *   sub      the muted line beside it (what it read, the cost, the next run)
+ *   steps    [{ label, status: complete|done|failed|skipped|running, count? }]
+ *   figures  [{ label, value, note?, noteTone?: "success"|"danger", progress?: 0..1, progressTone? }]
+ *   lines    [{ label, text }]: the account, one line a heading
+ *   empty    a node when the run says nothing yet (running)
+ */
+export function RunAccount({ title, sub, steps = [], figures = [], lines = [], empty, className }) {
+  return (
+    <div className={cx("@container flex min-h-0 min-w-0 flex-col", className)}>
+      {steps.length ? (
+        <div className="shrink-0 border-b border-border px-4 py-4 @md:px-[18px]">
+          <StepsStrip steps={steps} />
+        </div>
+      ) : null}
+      <div className="grid content-start gap-3.5 px-4 py-4 @md:px-5">
+        {figures.length ? (
+          <div className="grid grid-cols-1 gap-2.5 @2xs:grid-cols-2 @2xl:grid-cols-4">
+            {figures.map((f) => (
+              <div key={f.label} className="grid min-w-0 gap-0.5 rounded-[var(--radius)] border border-border bg-card px-3 py-2.5 text-card-foreground">
+                <span className="truncate text-xs text-muted-foreground">{f.label}</span>
+                <span className="truncate text-[22px] font-semibold leading-tight tabular-nums">{f.value}</span>
+                {f.progress != null ? (
+                  <span aria-hidden="true" className="mt-1 block h-1 overflow-hidden rounded-sm bg-border">
+                    <span className={cx("block h-full", BAR[f.progressTone] ?? BAR.neutral)} style={{ width: `${Math.max(0, Math.min(1, f.progress)) * 100}%` }} />
+                  </span>
+                ) : null}
+                {f.note ? <span className={cx("text-xs", f.noteTone === "success" ? "text-success" : f.noteTone === "danger" ? "text-destructive" : "text-muted-foreground")}>{f.note}</span> : null}
+              </div>
+            ))}
+          </div>
+        ) : null}
+        <div className="grid gap-0">
+          {title ? (
+            <div className="mb-1 flex flex-wrap items-baseline gap-x-2.5">
+              <b className="text-sm font-semibold">{title}</b>
+              {sub ? <span className="text-[13px] text-muted-foreground">{sub}</span> : null}
+            </div>
+          ) : null}
+          {lines.length ? (
+            <dl className="m-0 grid text-[13px]">
+              {lines.map((l, i) => (
+                <div key={`${l.label}-${i}`} className="grid grid-cols-1 gap-0.5 border-b border-border py-2 last:border-b-0 @sm:grid-cols-[120px_minmax(0,1fr)] @sm:gap-3">
+                  <dt className="text-muted-foreground">{l.label}</dt>
+                  <dd className="m-0 min-w-0">{l.text}</dd>
+                </div>
+              ))}
+            </dl>
+          ) : (
+            empty ?? null
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** One tile of the overview: a mark and a word, never a colour alone. */
+function Tile({ value, word, icon, tone, spinning, className, children }) {
+  return (
+    <div className={cx("grid min-w-0 gap-0.5 rounded-[var(--radius)] border border-border bg-card px-3 py-2.5 text-card-foreground", className)}>
+      <div className="flex min-w-0 items-start gap-2">
+        <span className="min-w-0 flex-1 truncate text-lg font-semibold leading-tight tabular-nums">{value}</span>
+        {icon ? <Icon name={icon} size={14} className={cx("mt-1 shrink-0", tone, spinning && "animate-spin motion-reduce:animate-none")} /> : null}
+      </div>
+      <span className={cx("truncate text-xs", tone ?? "text-muted-foreground")}>{word}</span>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The overview of a job's runs: completed, failed, in progress, the
+ * average run time, and the credits used against the week's cap.
+ *
+ *   completed, failed, running   counts (numbers, or words)
+ *   avg                          the average run time, in words ("2 seconds")
+ *   credits                      { used, of, words: "7 of 37,000 this week" }
+ *   title                        the heading (default "Overview"); null for none
+ */
+export function RunOverview({ completed, failed, running, avg, credits, title = "Overview", className }) {
+  const pct = credits && typeof credits.used === "number" && credits.of > 0 ? Math.max(0, Math.min(1, credits.used / credits.of)) : null;
+  const full = pct != null && pct >= 1;
+  return (
+    <section aria-label={title ?? "Overview"} className={cx("@container grid min-w-0 gap-2", className)}>
+      {title ? <h3 className="m-0 text-xs font-medium text-muted-foreground">{title}</h3> : null}
+      <div className="grid grid-cols-1 gap-2 @2xs:grid-cols-2">
+        <Tile value={countOf(completed ?? 0)} word="Completed" icon="circle-check" tone="text-success" />
+        <Tile value={countOf(failed ?? 0)} word="Failed" icon="circle-x" tone={failed ? "text-destructive" : "text-muted-foreground"} />
+        <Tile value={countOf(running ?? 0)} word="In progress" icon="loader" tone={running ? "text-info" : "text-muted-foreground"} spinning={Boolean(running)} />
+        <Tile value={avg ?? "—"} word="Average run time" icon="clock" />
+        {credits ? (
+          <Tile value={countOf(credits.used)} word="Credits used" icon="zap" tone={full ? "text-destructive" : undefined} className="@2xs:col-span-2">
+            {credits.words ? <span className={cx("text-xs tabular-nums", full ? "text-destructive" : "text-muted-foreground")}>{credits.words}</span> : null}
+            {pct != null ? (
+              <span aria-hidden="true" className="mt-1 block h-1 overflow-hidden rounded-sm bg-border">
+                <span className={cx("block h-full", full ? "bg-destructive" : "bg-muted-foreground")} style={{ width: `${pct * 100}%` }} />
+              </span>
+            ) : null}
+          </Tile>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/registry/blocks/run-view/README.md

@@ -0,0 +1,174 @@
+# RunView
+
+What an automation did, on the same canvas as the builder.
+
+- **Every card wears how it went** — done, running, failed, waiting,
+  skipped, fixed by the agent, or not reached — as a mark and a word, never
+  colour alone. A looped step says how many times; a failed one says why,
+  in plain words.
+- **The path taken is lit** and the paths not taken are dimmed, so a run
+  reads as one route through the flow. A condition shows which way it went
+  (from its own output when the member may read it, else from what ran).
+- **The side panel** gives the run in a few lines: who started it, how
+  long, what it cost of what it may, the version; a note when it waits or
+  stopped and why; a "The agent fixed N steps" list; the report it left.
+  Press a card and it becomes that step's account: how it went, what went
+  in and what came out (for those who may read it), the agent's fix with
+  before and after.
+- **Controls for a run that is not over** (`RunControls`, drawn in the panel
+  when you pass `onControl`). Only what the run's state allows:
+  *running* — Pause, Stop; *paused* — Resume, Stop; *waiting on its
+  owner* — Resume, Stop, and for the step that is stuck: Try this step
+  again, Skip this step, Change its data (for this run only; for those who
+  may read the step); *held at the run's own limit* — Raise its limit (adds
+  credits to this run and goes on; the automation's limit stays). A step
+  cut off in a send is said as unknown: "It did not go: send it again" or "It
+  did go: skip it", never repeated on a guess. A refusal is shown in the
+  platform's words. Stop asks first.
+- **A test run** (`detail.run.dry`: it read real data and changed
+  nothing). A strip over the canvas says how it went in one line (`testWords`:
+  "Test passed: nothing was sent or changed. 3 steps would have run."), then
+  what the steps would have done (the platform's `run.result.dry.would`:
+  "Would send with send_email."), a note for steps that could not be checked
+  (they need what an earlier step would have made) and for loops it only
+  sampled ("Looked at the first 5 of 38"). The chip reads Test passed, Test
+  failed or Test stopped; a step that stood in for itself is a dashed card
+  with a pencil (the state `would`). A real run draws as before.
+- **Retry from this step** (`RetryFromStep`, drawn in a step's panel when
+  you pass `onControl`). A quiet button on a step that ran, in a run that is
+  over (done, failed, stopped) or waiting on its owner; not in one that is
+  going or paused. It runs that step and every step after it again; the
+  steps before keep what they made. A step inside a loop or a branch
+  starts over from the one that holds it, and the panel says so. If a step
+  from there on already sent something, it asks first, in its own words
+  ("It already sent something. Run it again from here?"), and only then
+  sends again. A refusal is shown in the platform's words.
+- **The agent's fix** on a card and in its panel: what changed, what it
+  cost, whether a write can be taken back (a send cannot), and the change
+  the agent drafted for next time, to **keep** (a new version that runs) or
+  **drop**. A person's own edit of a run's data reads "You changed its data"
+  and is not marked as the agent's.
+- **RunsList** — the automation's runs, newest first, with a little
+  overview (done, failed, in progress, spent), a filter, and for each run:
+  what started it, when (in the automation's zone), how it ended, how long
+  and what it cost.
+
+```jsx
+import { RunView, RunsList } from "../components/blocks/run-view";   // a Makersclaw app
+import { RunView, RunsList } from "@/components/makersclaw/blocks/run-view";   // a shadcn project
+```
+
+`makersclaw add run-view` lays `flow-editor`, `step-settings`, `fix-note`
+and `automation-model` with it. Client components. Read-only: nothing here
+changes the flow. Its own width decides its layout: the panel sits beside
+the canvas from about 768 px and under it below.
+
+## Props
+
+### RunView
+
+- `def` — the definition the run used. Pass `useAutomationRun().definition`
+  (the platform pins it) and, when it is null, the live or draft one with a
+  `versionNote` ("This run used version 3. The steps drawn are the current
+  ones.").
+- `detail` — the run's account: `{ run, steps, steps_visible }`
+  (`useAutomationRun().detail`). `run` carries `status`, `version`,
+  `trigger_type`, `is_test`, `credits`, `cap_credits`, `result`, `error`,
+  `wake_at`. A step: `{ path, step_id, attempt, status, credits, error,
+  input?, output?, fix? }`.
+- `runs` — the automation's runs, newest first, for the picker and the
+  run's number. `tz` — the automation's time zone.
+- `apps`, `actions`, `ownedByApp` — as the builder's, for the read-only
+  step panel.
+- `name`, `onBack`, `tabs`, `onPickRun(runId)`.
+- `onRunAgain()`, `runAgainBusy` — Run again (it spends: say so on the
+  control where you can). For a test run the button reads "Test again".
+- `onControl(op, { path?, input?, confirmNotSent?, raiseBy?, confirmResend? })`
+  — `op` is `pause` · `resume` · `stop` · `retry` · `skip` · `edit` ·
+  `retry_from` (the step's panel: `path` is the top-level step to start
+  over from, `confirmResend` says sending again is right); resolves
+  `{ ok }` or `{ ok: false, error, code }` (`useAutomationRun().control`).
+  Without it the panel only says a parked run waits for its owner.
+  `controlBusy` is the op that is out.
+- `onKeepFix(stepId)`, `onDropFix(stepId)` — keep or drop the change the
+  agent drafted for a step it fixed (`useAutomationRun().keepFix` and
+  `dropFix`). A fix with no draft has no button. `onUndoFix(stepId)` takes
+  back a write.
+- `detail.fixes` — the fixer's attempts and the changes it drafted
+  (`useAutomationRun().detail` carries them).
+
+### RunControls
+
+The controls alone: `run`, `steps`, `stepsVisible`, `titleOf(stepId)`,
+`onControl`, `busy`. Draws nothing for a run that is over, or without
+`onControl`.
+
+### RetryFromStep
+
+The button alone: `run`, `steps`, `def`, `stepId`, `onControl`, `busy`.
+Draws nothing for a step that did not run, a run that is going or paused,
+or without `onControl`. The rules are `retryFromOf(run, rows, def, stepId)`
+in automation-model (`{ show, path, inLoop, loopTitle, sent }`).
+
+### RunsList
+
+- `runs`, `tz`, `onOpen(runId)`, `howToTest` (the words under "It has not
+  run yet").
+
+## Hooks (lib/hooks.js)
+
+`useAutomationRun(runId)` → `{ run, steps, stepsVisible, automation,
+definition, fixes, detail, control, keepFix, dropFix, busy, loading, error,
+unavailable, reload }`. Looks every 2.5 s while the run goes; a run that
+has ended is read once. `control(op, opts)` (`opts.confirmResend` is sent as `confirm_resend`) and
+`keepFix(stepId)` resolve
+the platform's answer (a refusal is `{ ok: false, error, code }`, never
+thrown) and read the run again.
+`useAutomation(id).runs` is the list.
+
+## Never
+
+- Never an Approve in a run: an automation has none. A run waiting on its
+  owner says so; the owner answers on the desk. Resume, retry and skip are
+  not approvals: they are the owner's controls on a stuck run.
+- Never a Retry for a send that may have gone, without asking whether it did.
+- Never "Retry from this step" that sends again without asking first.
+- Never a state by colour alone.
+- Never a step's data to someone who may not read it: pass
+  `steps_visible` as the platform sent it.
+
+## Example
+
+```jsx
+"use client";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useAutomation, useAutomationRun } from "../lib/hooks";
+import { RunView } from "../components/blocks/run-view";
+
+export default function RunPage() {
+  const router = useRouter();
+  const q = useSearchParams();
+  const id = q.get("automation");
+  const a = useAutomation(id);
+  const r = useAutomationRun(q.get("run"));
+  if (!a.definition || !r.detail) return <p className="p-4 text-sm text-muted-foreground">Opening the run…</p>;
+  return (
+    <div className="flex h-[640px] flex-col">
+      <RunView
+        def={r.definition ?? a.definition}
+        versionNote={r.definition ? null : `This run used version ${r.run.version}. The steps drawn are the current ones.`}
+        detail={r.detail}
+        runs={a.runs}
+        tz={a.automation.tz}
+        name={a.automation.name}
+        onBack={() => router.push(`?automation=${id}`)}
+        onPickRun={(run) => router.push(`?automation=${id}&run=${run}`)}
+        onControl={r.control}
+        controlBusy={r.busy}
+        onKeepFix={r.keepFix}
+        onDropFix={r.dropFix}
+      />
+    </div>
+  );
+}
+```

package/registry/blocks/run-view/block.json

@@ -0,0 +1,50 @@
+{
+  "name": "run-view",
+  "title": "RunView",
+  "description": "One run of an automation on the same canvas as the builder: every card wears how it went, the path the run took is lit and the paths it did not take are dimmed, a looped step says how many times, a failed step says why, and a step the agent fixed says so on its card and in its panel. A side panel gives the run in a few lines (who started it, how long, what it cost of what it may, the version) and, for a card pressed, how that step went and what went in and out for those who may read it. RunsList is the automation's runs, newest first, with an overview (done, failed, in progress, spent) and a filter. For a run that is not over it offers what the run allows (RunControls): pause, resume, stop; when it is stuck on a step, try it again, skip it, change the data it was given for this run, or raise the run's limit and go on. On a step of a run that is over (done, failed, stopped) or waiting on its owner, a quiet \"Retry from this step\" starts the run over there, asking first when a step from there on already sent something. A step the agent fixed shows what changed, what it cost, whether a write can be taken back, and keeps or drops the change the agent drafted for next time. A test run (a dry run) draws a strip over the canvas, with what each step would have done and what could not be checked, and its steps as dashed pencil cards.",
+  "useWhen": "A member looks at what an automation did: the page behind a run row, and the Runs tab beside the builder. Fed by useAutomationRun and useAutomation (lib/hooks.js). For a job's run drawn top to bottom in the older kit use workflow-view.",
+  "tags": [
+    "automation",
+    "workflow",
+    "run",
+    "history",
+    "runs",
+    "trace",
+    "execution",
+    "steps",
+    "path taken",
+    "failed",
+    "fixed",
+    "retry",
+    "overview",
+    "n8n",
+    "make",
+    "pause",
+    "resume",
+    "stop",
+    "skip",
+    "retry",
+    "control",
+    "retry from this step",
+    "start over",
+    "re-run"
+  ],
+  "exports": [
+    "RunView",
+    "RunsList",
+    "RunControls",
+    "RetryFromStep"
+  ],
+  "files": [
+    "index.js",
+    "run-view.jsx",
+    "runs-list.jsx",
+    "run-controls.jsx"
+  ],
+  "requires": [
+    "automation-model",
+    "flow-editor",
+    "step-settings",
+    "fix-note"
+  ]
+}