@nurix/etna 0.18.18 → 0.18.20

package/data/harnesses/code/skills/design/scripts/scaffold.mjs

@@ -0,0 +1,552 @@
+// skills/design/scripts/scaffold.mjs — generates the non-creative app substrate (routes, nav, per-surface state shells) from docs/design/structure.md
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const ARCHETYPES = ["list-detail", "dashboard", "entity-detail", "create-edit", "log-stream", "command-center"];
+const LANDING = new Set(["list-detail", "dashboard", "log-stream", "command-center"]);
+
+// Print the refusal (problem + exact fix) to stderr and exit non-zero.
+function refuse(problem, fix) {
+  process.stderr.write(`scaffold.mjs: ${problem}\n`);
+  process.stderr.write(`fix: ${fix}\n`);
+  process.exit(1);
+}
+
+// Parse argv into positionals (_) and --flags (supporting --k v and --k=v).
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        args[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          args[a.slice(2)] = next;
+          i++;
+        } else {
+          args[a.slice(2)] = true;
+        }
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+// Strip a trailing/full-line YAML comment (structure-block values never contain '#').
+function stripComment(line) {
+  const h = line.indexOf("#");
+  if (h === -1) return line;
+  if (h === 0 || /\s/.test(line[h - 1])) return line.slice(0, h).replace(/\s+$/, "");
+  return line;
+}
+
+// Extract the body of the fenced ```yaml structure block by its info-string.
+function extractStructureBlock(text) {
+  const m = text.match(/```yaml structure[^\n]*\n([\s\S]*?)\n```/);
+  return m ? m[1] : null;
+}
+
+// Collapse the block into indent-tagged, comment-free, non-blank lines.
+function toLines(body) {
+  const out = [];
+  for (const raw of body.split(/\r?\n/)) {
+    const noComment = stripComment(raw);
+    if (noComment.trim() === "") continue;
+    out.push({ indent: noComment.length - noComment.trimStart().length, text: noComment.trim() });
+  }
+  return out;
+}
+
+// Parse a scalar, inline flow sequence [a, b], or inline flow mapping {k: v}.
+function parseScalarOrFlow(s) {
+  const t = s.trim();
+  if (t.startsWith("[") && t.endsWith("]")) {
+    const inner = t.slice(1, -1).trim();
+    if (inner === "") return [];
+    return inner.split(",").map((x) => parseScalarOrFlow(x));
+  }
+  if (t.startsWith("{") && t.endsWith("}")) {
+    const inner = t.slice(1, -1).trim();
+    const obj = {};
+    if (inner === "") return obj;
+    for (const pair of inner.split(",")) {
+      const idx = pair.indexOf(":");
+      if (idx === -1) continue;
+      obj[pair.slice(0, idx).trim()] = parseScalarOrFlow(pair.slice(idx + 1));
+    }
+    return obj;
+  }
+  return t;
+}
+
+// Dispatch a contiguous line range [start,end) to a sequence or mapping parse.
+function parseBlock(lines, start, end) {
+  if (start >= end) return null;
+  const base = lines[start].indent;
+  if (lines[start].text.startsWith("- ")) return parseSequence(lines, start, end, base);
+  return parseMapping(lines, start, end, base);
+}
+
+// Parse a YAML sequence: each "- " item, with inline-first-pair mapping items merged with their children.
+function parseSequence(lines, start, end, base) {
+  const items = [];
+  let i = start;
+  while (i < end && lines[i].indent === base && lines[i].text.startsWith("- ")) {
+    const content = lines[i].text.slice(2).trim();
+    let j = i + 1;
+    while (j < end && lines[j].indent > base) j++;
+    if (content.startsWith("{") || content.startsWith("[")) {
+      items.push(parseScalarOrFlow(content));
+    } else if (content.indexOf(":") !== -1) {
+      const map = {};
+      const c = content.indexOf(":");
+      const key = content.slice(0, c).trim();
+      const rest = content.slice(c + 1).trim();
+      map[key] = rest !== "" ? parseScalarOrFlow(rest) : null;
+      if (i + 1 < j) {
+        const child = parseBlock(lines, i + 1, j);
+        if (child && typeof child === "object" && !Array.isArray(child)) Object.assign(map, child);
+      }
+      items.push(map);
+    } else {
+      items.push(parseScalarOrFlow(content));
+    }
+    i = j;
+  }
+  return items;
+}
+
+// Parse a YAML mapping: key/value pairs at one indent, recursing into nested blocks.
+function parseMapping(lines, start, end, base) {
+  const map = {};
+  let i = start;
+  while (i < end && lines[i].indent === base && !lines[i].text.startsWith("- ")) {
+    const line = lines[i].text;
+    const c = line.indexOf(":");
+    if (c === -1) {
+      i++;
+      continue;
+    }
+    const key = line.slice(0, c).trim();
+    const rest = line.slice(c + 1).trim();
+    if (rest !== "") {
+      map[key] = parseScalarOrFlow(rest);
+      i++;
+    } else {
+      let j = i + 1;
+      while (j < end && lines[j].indent > base) j++;
+      map[key] = i + 1 < j ? parseBlock(lines, i + 1, j) : null;
+      i = j;
+    }
+  }
+  return map;
+}
+
+// Split a name into alphanumeric words on any separator.
+function words(s) {
+  return String(s).trim().split(/[^A-Za-z0-9]+/).filter(Boolean);
+}
+
+// PascalCase a name (Support Ticket -> SupportTicket).
+function toPascal(s) {
+  return words(s).map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase()).join("");
+}
+
+// kebab-case a name (Ticket Queue -> ticket-queue).
+function toKebab(s) {
+  return words(s).map((w) => w.toLowerCase()).join("-");
+}
+
+// camelCase a name, preserving already-camel single tokens (created_at -> createdAt, slaMinutes -> slaMinutes).
+function toCamel(s) {
+  const str = String(s).trim();
+  if (/^[A-Za-z0-9]+$/.test(str)) return str[0].toLowerCase() + str.slice(1);
+  const w = words(str);
+  if (!w.length) return "";
+  return w[0].toLowerCase() + w.slice(1).map((x) => x[0].toUpperCase() + x.slice(1).toLowerCase()).join("");
+}
+
+// Naive English pluralization sufficient for entity nouns.
+function pluralize(word) {
+  const w = String(word);
+  if (/[^aeiou]y$/i.test(w)) return w.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(w)) return w + "es";
+  return w + "s";
+}
+
+// Capitalize the first character.
+function cap(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+// Canonical per-entity identifiers shared with generate-fixtures.mjs (module paths and export names must agree).
+function entityNames(name) {
+  const arrayVar = pluralize(toCamel(name));
+  return {
+    iface: toPascal(name),
+    typeFile: toKebab(name),
+    fixtureFile: pluralize(toKebab(name)),
+    arrayVar,
+    emptyVar: "empty" + cap(arrayVar),
+    degradedVar: "degraded" + cap(arrayVar),
+  };
+}
+
+// Normalize a surface's declared states to the canonical loading/empty/error/degraded set.
+function normalizeStates(arr) {
+  const alias = { partial: "degraded", degraded: "degraded", loading: "loading", empty: "empty", error: "error" };
+  const order = ["loading", "empty", "error", "degraded"];
+  const set = new Set();
+  for (const s of arr || []) {
+    const n = alias[String(s).trim().toLowerCase()];
+    if (n) set.add(n);
+  }
+  const picked = order.filter((s) => set.has(s));
+  return picked.length ? picked : order.slice();
+}
+
+// Read, parse, and validate docs/design/structure.md into a normalized model, refusing on malformed input.
+function loadStructure(path, { requireSurfaces }) {
+  if (!existsSync(path)) refuse(`structure map not found at ${path}`, "pass the path to docs/design/structure.md as the first argument");
+  const body = extractStructureBlock(readFileSync(path, "utf8"));
+  if (body === null) {
+    refuse(
+      `no fenced \`\`\`yaml structure block in ${path}`,
+      "docs/design/structure.md must carry a fenced ```yaml structure block (see references/structure.md); run the structure phase to produce it",
+    );
+  }
+  const parsed = parseBlock(toLines(body), 0, toLines(body).length) || {};
+  const rawSurfaces = Array.isArray(parsed.surfaces) ? parsed.surfaces : [];
+  const surfaces = rawSurfaces.map((s, idx) => {
+    for (const key of ["name", "archetype", "route", "entity"]) {
+      if (!s || typeof s[key] !== "string" || s[key].trim() === "") {
+        refuse(
+          `surface #${idx + 1} is missing required field "${key}"`,
+          `every surfaces[] entry needs name, archetype, route, entity (structure.md schema)`,
+        );
+      }
+    }
+    const archetype = String(s.archetype).trim();
+    if (!ARCHETYPES.includes(archetype)) {
+      refuse(
+        `surface "${s.name}" has archetype "${archetype}", not one of the closed six`,
+        `set archetype to one of: ${ARCHETYPES.join(", ")} (surface-catalog.md; membership is closed)`,
+      );
+    }
+    let mod = 0;
+    if (s["density-modifier"] !== undefined && s["density-modifier"] !== null && String(s["density-modifier"]).trim() !== "") {
+      mod = Number.parseInt(String(s["density-modifier"]).trim(), 10);
+      if (Number.isNaN(mod)) {
+        refuse(
+          `surface "${s.name}" has a non-integer density-modifier "${s["density-modifier"]}"`,
+          "density-modifier is a signed integer (+1 denser / 0 / -1 looser) per surface-catalog.md",
+        );
+      }
+    }
+    return {
+      name: String(s.name).trim(),
+      archetype,
+      route: String(s.route).trim(),
+      entity: String(s.entity).trim(),
+      densityModifier: mod,
+      states: normalizeStates(s.states),
+    };
+  });
+  if (requireSurfaces && surfaces.length === 0) {
+    refuse(
+      "the structure map declares no surfaces",
+      "the object pass must assign at least one surface an archetype before scaffold opens (structure.md); an empty pass fails the structure gate",
+    );
+  }
+  return {
+    unitOfWork: typeof parsed["unit-of-work"] === "string" ? parsed["unit-of-work"].trim() : "",
+    coreLoop: typeof parsed["core-loop"] === "string" ? parsed["core-loop"].trim() : "",
+    entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+    temporal: parsed.temporal || {},
+    surfaces,
+  };
+}
+
+// Write a file under the project root, creating parent directories.
+function emit(root, rel, content, written) {
+  const abs = join(root, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content, "utf8");
+  written.push(rel);
+}
+
+// Render index.html carrying placeholder <html data-*> personality attributes (derive-personality --emit resolves them).
+function indexHtml() {
+  return `<!doctype html>
+<!-- Generated by scaffold.mjs. Personality state lives in these <html data-*> attributes (code is the cache).
+     The values below are placeholders; derive-personality.mjs --emit resolves them from the project's design.md. -->
+<html
+  lang="en"
+  data-style="app"
+  data-density="standard"
+  data-verbosity="default"
+  data-feedback="subtle"
+  data-theme="light"
+>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Operator UI</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+}
+
+// Render src/main.tsx: mount the router app and load the emitted global stylesheet.
+function mainTsx() {
+  return `// src/main.tsx — Vite entry: mounts the router app and loads the emitted global stylesheet (generated by scaffold.mjs; do not hand-edit).
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./styles/globals.css";
+
+const rootElement = document.getElementById("root");
+if (!rootElement) {
+  throw new Error("Root element #root not found in index.html");
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+`;
+}
+
+// Render src/App.tsx: one route per surface, wrapped in the persistent operator shell.
+function appTsx(surfaces) {
+  const imports = surfaces
+    .map((s) => `import { ${toPascal(s.name)} } from "./routes/${toKebab(s.name)}/${toPascal(s.name)}";`)
+    .join("\n");
+  const routes = surfaces
+    .map((s) => `          <Route path="${s.route}" element={<${toPascal(s.name)} />} />`)
+    .join("\n");
+  return `// src/App.tsx — application routes and layout wiring (generated from docs/design/structure.md; do not hand-edit).
+import { BrowserRouter, Routes, Route, Outlet } from "react-router-dom";
+import { AppNav } from "./components/nav/AppNav";
+${imports}
+
+// Persistent operator shell: the navigation rail beside the routed surface.
+function AppLayout() {
+  return (
+    <div className="flex min-h-[100dvh] bg-background text-foreground">
+      <AppNav />
+      <main className="flex min-h-0 flex-1 flex-col overflow-auto">
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+
+// Router: one route per surface in the entity/surface map.
+export default function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route element={<AppLayout />}>
+${routes}
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+`;
+}
+
+// Render src/components/nav/AppNav.tsx: top-level entries derived from the object model, secondary surfaces reached by drilling in.
+function navTsx(surfaces) {
+  const navItems = surfaces.filter(
+    (s) => LANDING.has(s.archetype) && !s.route.includes(":") && !/\/new$/.test(s.route),
+  );
+  const items = navItems
+    .map((s) => `  { label: "${s.name}", route: "${s.route}" },`)
+    .join("\n");
+  return `// src/components/nav/AppNav.tsx — top-level navigation derived from the object model (generated; do not hand-edit).
+import { NavLink } from "react-router-dom";
+
+interface NavItem {
+  label: string;
+  route: string;
+}
+
+// Top-level entries are the primary entities' home surfaces; detail and create surfaces are reached by drilling in.
+const NAV_ITEMS: NavItem[] = [
+${items}
+];
+
+// Left navigation rail: one entry per top-level operator surface.
+export function AppNav() {
+  return (
+    <nav
+      aria-label="Primary"
+      className="flex w-56 shrink-0 flex-col gap-1 border-r border-sidebar-border bg-sidebar p-3 text-sidebar-foreground"
+    >
+      {NAV_ITEMS.map((item) => (
+        <NavLink
+          key={item.route}
+          to={item.route}
+          end
+          className={({ isActive }) =>
+            [
+              "rounded-md px-3 py-2 text-sm font-medium transition-colors",
+              isActive
+                ? "bg-sidebar-accent text-sidebar-accent-foreground"
+                : "text-sidebar-foreground hover:bg-sidebar-accent/60",
+            ].join(" ")
+          }
+        >
+          {item.label}
+        </NavLink>
+      ))}
+    </nav>
+  );
+}
+`;
+}
+
+// Render one surface shell: typed props, fixture wiring, pre-created lifecycle state shells, and the density-step root.
+function surfaceShell(surface) {
+  const comp = toPascal(surface.name);
+  const slug = toKebab(surface.name);
+  const en = entityNames(surface.entity);
+  const states = surface.states;
+  const hasEmpty = states.includes("empty");
+  const hasDegraded = states.includes("degraded");
+  const union = [...states, "ready"].map((s) => `"${s}"`).join(" | ");
+  const densityAttr =
+    surface.densityModifier > 0 ? ' data-density-step="tighter"' : surface.densityModifier < 0 ? ' data-density-step="looser"' : "";
+
+  const named = [en.arrayVar];
+  if (hasEmpty) named.push(en.emptyVar);
+  if (hasDegraded) named.push(en.degradedVar);
+
+  const branches = [];
+  if (states.includes("loading")) {
+    branches.push(`      {state === "loading" && (
+        <div className="flex flex-1 items-center justify-center py-12" aria-busy="true">
+          <p className="text-sm text-muted-foreground">Loading ${surface.name}</p>
+        </div>
+      )}`);
+  }
+  if (hasEmpty) {
+    branches.push(`      {state === "empty" && (
+        <div className="flex flex-1 flex-col items-center justify-center gap-1 py-12 text-center">
+          <p className="text-sm font-medium text-foreground">Nothing here yet</p>
+          <p className="max-w-sm text-sm text-muted-foreground">
+            ${surface.name} has no records yet. New records appear here as the operator creates them.
+          </p>
+        </div>
+      )}`);
+  }
+  if (states.includes("error")) {
+    branches.push(`      {state === "error" && (
+        <div role="alert" className="flex flex-1 flex-col items-center justify-center gap-1 py-12 text-center">
+          <p className="text-sm font-medium text-destructive">Could not load ${surface.name}</p>
+          <p className="max-w-sm text-sm text-muted-foreground">The request failed. Retry to reload this surface.</p>
+        </div>
+      )}`);
+  }
+  if (hasDegraded) {
+    branches.push(`      {state === "degraded" && (
+        <div className="flex flex-1 flex-col gap-2">
+          <p className="text-sm text-warning">Showing partial data. Some records are stale or failed to enrich.</p>
+          <${comp}Composition rows={rows} degraded />
+        </div>
+      )}`);
+  }
+  branches.push(`      {state === "ready" && <${comp}Composition rows={rows} />}`);
+
+  const pickBody = [];
+  if (hasDegraded) pickBody.push(`  if (state === "degraded") return ${en.degradedVar};`);
+  if (hasEmpty) pickBody.push(`  if (state === "empty") return ${en.emptyVar};`);
+  pickBody.push(`  return ${en.arrayVar};`);
+
+  const content = `// src/routes/${slug}/${comp}.tsx — ${surface.name} surface shell (${surface.archetype}; generated by scaffold.mjs; do not hand-edit).
+import type { ${en.iface} } from "../../types/${en.typeFile}";
+import { ${named.join(", ")} } from "../../fixtures/${en.fixtureFile}";
+
+type SurfaceState = ${union};
+
+interface ${comp}Props {
+  state?: SurfaceState;
+}
+
+// ${surface.name}: the ${surface.archetype} surface; scaffold pre-creates every lifecycle shell for the surfaces phase to fill.
+export function ${comp}({ state = "ready" }: ${comp}Props) {
+  const rows: ${en.iface}[] = pickRows(state);
+  return (
+    <section${densityAttr} aria-label="${surface.name}" className="flex h-full min-h-0 flex-col gap-4 p-6">
+      <header className="flex items-center justify-between border-b border-border pb-3">
+        <div className="flex flex-col gap-1">
+          <h1 className="text-base font-semibold tracking-tight text-foreground">${surface.name}</h1>
+          <p className="text-xs text-muted-foreground">${surface.archetype} - ${surface.entity}</p>
+        </div>
+        <span className="text-xs text-muted-foreground tabular-nums">{rows.length} records</span>
+      </header>
+${branches.join("\n")}
+    </section>
+  );
+}
+
+// Composition region: the surfaces phase composes the ${surface.archetype} archetype here, following its exemplar and the emitted tokens.
+function ${comp}Composition({ rows, degraded = false }: { rows: ${en.iface}[]; degraded?: boolean }) {
+  return (
+    <div className="flex flex-1 flex-col rounded-lg border border-border bg-card text-card-foreground">
+      <div className="flex items-center justify-between border-b border-border px-4 py-3">
+        <p className="text-sm font-medium text-foreground">${surface.name}</p>
+        <p className="text-xs text-muted-foreground tabular-nums">
+          {rows.length} records{degraded ? " (partial)" : ""}
+        </p>
+      </div>
+      <p className="px-4 py-6 text-sm text-muted-foreground">
+        Compose the ${surface.archetype} surface for ${surface.entity} here.
+      </p>
+    </div>
+  );
+}
+
+// Select the fixture set backing the requested lifecycle state.
+function pickRows(state: SurfaceState): ${en.iface}[] {
+${pickBody.join("\n")}
+}
+`;
+  return { rel: `src/routes/${slug}/${comp}.tsx`, content };
+}
+
+// Entry point: load the map, emit the substrate, and report what was written.
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const structurePath = args._[0];
+  const out = typeof args.out === "string" ? args.out : null;
+  if (!structurePath || !out) {
+    refuse("missing arguments", "usage: scaffold.mjs <docs/design/structure.md> --out <project-root-dir>");
+  }
+  const model = loadStructure(structurePath, { requireSurfaces: true });
+  const written = [];
+  emit(out, "index.html", indexHtml(), written);
+  emit(out, "src/main.tsx", mainTsx(), written);
+  emit(out, "src/App.tsx", appTsx(model.surfaces), written);
+  emit(out, "src/components/nav/AppNav.tsx", navTsx(model.surfaces), written);
+  for (const surface of model.surfaces) {
+    const shell = surfaceShell(surface);
+    emit(out, shell.rel, shell.content, written);
+  }
+  process.stdout.write(`scaffold.mjs: wrote ${written.length} files under ${out}\n`);
+  for (const rel of written) process.stdout.write(`  ${rel}\n`);
+}
+
+main();