@nurix/etna 0.18.18 → 0.18.20

package/data/harnesses/code/skills/design/scripts/generate-fixtures.mjs

@@ -0,0 +1,551 @@
+// skills/design/scripts/generate-fixtures.mjs — emits seeded, domain-shaped fixture modules and entity types 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 LIST_BEARING_ARCHETYPES = new Set(["list-detail", "log-stream", "command-center"]);
+
+// Print the refusal (problem + exact fix) to stderr and exit non-zero.
+function refuse(problem, fix) {
+  process.stderr.write(`generate-fixtures.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;
+}
+
+// SNAKE_UPPER a camelCase identifier (supportTickets -> SUPPORT_TICKETS).
+function snakeUpper(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
+}
+
+// Canonical per-entity identifiers shared with scaffold.mjs (module paths and export names must agree).
+function entityNames(name) {
+  const arrayVar = pluralize(toCamel(name));
+  return {
+    iface: toPascal(name),
+    statusType: toPascal(name) + "Status",
+    typeFile: toKebab(name),
+    fixtureFile: pluralize(toKebab(name)),
+    arrayVar,
+    emptyVar: "empty" + cap(arrayVar),
+    degradedVar: "degraded" + cap(arrayVar),
+    seedConst: snakeUpper(arrayVar) + "_SEED",
+  };
+}
+
+// Deterministic FNV-1a hash so a base seed derives a stable, distinct effective seed per entity.
+function hashString(s) {
+  let h = 2166136261 >>> 0;
+  for (let k = 0; k < s.length; k++) {
+    h ^= s.charCodeAt(k);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+// Read, parse, and validate docs/design/structure.md into a normalized model, refusing on malformed input.
+function loadStructure(path) {
+  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 lines = toLines(body);
+  const parsed = parseBlock(lines, 0, lines.length) || {};
+  const entities = Array.isArray(parsed.entities) ? parsed.entities : [];
+  if (entities.length === 0) {
+    refuse(
+      "the structure map declares no entities",
+      "the object pass must populate entities[] before fixtures generate (structure.md); an empty pass fails the structure gate",
+    );
+  }
+  const surfaces = (Array.isArray(parsed.surfaces) ? parsed.surfaces : []).map((s, idx) => {
+    if (s && typeof s.archetype === "string" && !ARCHETYPES.includes(s.archetype.trim())) {
+      refuse(
+        `surface #${idx + 1} ("${s.name || "?"}") has archetype "${s.archetype}", not one of the closed six`,
+        `set archetype to one of: ${ARCHETYPES.join(", ")} (surface-catalog.md; membership is closed)`,
+      );
+    }
+    return { name: s && s.name, archetype: s && s.archetype && String(s.archetype).trim(), entity: s && s.entity && String(s.entity).trim() };
+  });
+  return {
+    unitOfWork: typeof parsed["unit-of-work"] === "string" ? parsed["unit-of-work"].trim() : "",
+    entities: entities.map((e) => ({
+      name: String(e.name).trim(),
+      attributes: Array.isArray(e.attributes) ? e.attributes.map((a) => String(a).trim()) : [],
+      lifecycle: Array.isArray(e.lifecycle) ? e.lifecycle.map((l) => String(l).trim()) : [],
+      relationships: Array.isArray(e.relationships) ? e.relationships : [],
+    })),
+    surfaces,
+  };
+}
+
+// Classify one attribute into a TS type + a runtime generation category.
+function classify(prop, entity, hasLifecycle) {
+  const p = prop.toLowerCase();
+  const t = (tsType, nullable, category) => ({ prop, tsType, nullable, category });
+  if (/(at|date)$/.test(p) || p.includes("date")) return t("string", false, "isoDate");
+  if (hasLifecycle && (p === "status" || p === "state")) return t(entityNames(entity.name).statusType, false, "status");
+  if (/^(is|has)[a-z0-9]/.test(prop) || p === "is" || p === "has") return t("boolean", false, "bool");
+  if (/(count|amount|total|price|qty|quantity|replies|remaining|minutes|seconds|score|size|age|balance|rate|num|weight)$/.test(p) || /^(count|num)/.test(p)) {
+    return t("number", false, "int");
+  }
+  if (p === "email" || /email$/.test(p)) return t("string", false, "email");
+  if (/(assignee|owner|manager|contact)$/.test(p)) return t("string | null", true, "person");
+  if (/(name|requester|customer|author|user|person|agent)$/.test(p)) return t("string", false, "person");
+  if (/(company|org|account|vendor|team|tenant)$/.test(p)) return t("string | null", true, "company");
+  if (/(priority|severity|level|channel|role|type|kind|category|availability|status|state)$/.test(p)) return t("string", false, "token");
+  if (/(subject|title|summary|label|description|body|message|note|text|reason|comment)$/.test(p)) return t("string", false, "sentence");
+  return t("string", false, "phrase");
+}
+
+// Build the ordered field plan for an entity: id, its attributes, and FK columns from many-to-one relationships.
+function fieldPlans(entity, entities) {
+  const plans = [];
+  const seen = new Set();
+  const add = (plan) => {
+    if (seen.has(plan.prop)) return;
+    seen.add(plan.prop);
+    plans.push(plan);
+  };
+  const hasLifecycle = entity.lifecycle.length > 0;
+  add({ prop: "id", tsType: "string", nullable: false, category: "uuid" });
+  for (const attr of entity.attributes) {
+    const prop = toCamel(attr);
+    if (prop === "id" || prop === "") continue;
+    add(classify(prop, entity, hasLifecycle));
+  }
+  for (const rel of entity.relationships) {
+    if (String(rel && rel.cardinality).trim() !== "many-to-one") continue;
+    if (!rel.to || rel.to === entity.name) continue;
+    const related = entities.find((e) => e.name === rel.to);
+    if (!related) continue;
+    const ren = entityNames(rel.to);
+    add({ prop: toCamel(rel.to) + "Id", tsType: "string | null", nullable: true, category: "fk", related: ren });
+  }
+  return plans;
+}
+
+// The name of the token pool a short-enum field draws from.
+function tokenPool(prop) {
+  const p = prop.toLowerCase();
+  if (/priority/.test(p)) return "PRIORITIES";
+  if (/channel/.test(p)) return "CHANNELS";
+  if (/role/.test(p)) return "ROLES";
+  if (/sever/.test(p)) return "SEVERITIES";
+  if (/avail/.test(p)) return "AVAILABILITIES";
+  return "GENERIC_TOKENS";
+}
+
+const POOL_DECLS = {
+  FIRST_NAMES:
+    'const FIRST_NAMES = ["Amara", "Diego", "Priya", "Elias", "Naomi", "Tomas", "Leila", "Marcus", "Yuki", "Ravi", "Sofia", "Idris", "Hana", "Owen", "Chidi", "Wen"];',
+  LAST_NAMES:
+    'const LAST_NAMES = ["Okafor", "Reyes", "Sharma", "Novak", "Bennett", "Costa", "Haddad", "Lindqvist", "Tanaka", "Mehta", "Rossi", "Abara", "Kim", "Fletcher", "Nwosu", "Zhao"];',
+  COMPANIES:
+    'const COMPANIES = ["Northwind Trading", "Blue Harbor Labs", "Meridian Freight", "Cedar and Vale", "Halcyon Systems", "Ironwood Retail", "Sunstone Analytics", "Tidewater Health", "Brightfold Media", "Kestrel Logistics"];',
+  EMAIL_DOMAINS: 'const EMAIL_DOMAINS = ["example.com", "mail.test", "corp.example", "inbox.test"];',
+  SENTENCES:
+    'const SENTENCES = ["Payment retries failing after billing migration", "Export job stuck in queued state", "Login blocked for SSO users", "Webhook deliveries returning 500", "Dashboard widgets render stale totals", "Bulk import drops rows past 10k", "API rate limit hit during nightly sync", "Attachment preview times out on large files"];',
+  PHRASES: 'const PHRASES = ["north region", "priority lane", "overflow shard", "batch window", "cold path", "edge tier"];',
+  PRIORITIES: 'const PRIORITIES = ["low", "medium", "high", "urgent"];',
+  CHANNELS: 'const CHANNELS = ["email", "chat", "phone", "web", "api"];',
+  ROLES: 'const ROLES = ["agent", "admin", "viewer", "lead"];',
+  SEVERITIES: 'const SEVERITIES = ["info", "warning", "error", "critical"];',
+  AVAILABILITIES: 'const AVAILABILITIES = ["online", "away", "busy", "offline"];',
+  GENERIC_TOKENS: 'const GENERIC_TOKENS = ["alpha", "beta", "gamma", "delta"];',
+};
+
+const LONG_TEXT_DECL =
+  'const LONG_TEXT =\n  "Checkout returns 500 on multi-currency carts after the 3.4 billing migration when tax is estimated for split shipments across regions";';
+
+// The runtime helper source snippets emitted into each fixture module.
+const HELPERS = {
+  mulberry32: `// mulberry32: a tiny deterministic PRNG so the same seed yields byte-identical rows.
+function mulberry32(seedValue: number): () => number {
+  let a = seedValue >>> 0;
+  return function next(): number {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}`,
+  randInt: `// A deterministic integer in [min, max] drawn from the seeded stream.
+function randInt(min: number, max: number): number {
+  return min + Math.floor(rand() * (max - min + 1));
+}`,
+  pick: `// A deterministic pick from a fixed pool.
+function pick<T>(items: readonly T[]): T {
+  return items[Math.floor(rand() * items.length)];
+}`,
+  uuid: `// A deterministic UUID-shaped id from the seeded stream.
+function uuid(): string {
+  const hex = "0123456789abcdef";
+  let s = "";
+  for (let k = 0; k < 32; k++) s += hex[Math.floor(rand() * 16)];
+  return s.slice(0, 8) + "-" + s.slice(8, 12) + "-4" + s.slice(13, 16) + "-" + "89ab"[Math.floor(rand() * 4)] + s.slice(17, 20) + "-" + s.slice(20, 32);
+}`,
+  isoOffset: `// A deterministic ISO timestamp offset from a fixed reference instant (never Date.now()).
+function isoOffset(daysBack: number): string {
+  return new Date(BASE_EPOCH - daysBack * 86400000).toISOString();
+}`,
+};
+
+// Produce the runtime value expression for a field, recording the pools/helpers/imports it needs.
+function fieldExpr(plan, use) {
+  const p = plan.prop.toLowerCase();
+  switch (plan.category) {
+    case "uuid":
+      use.helpers.add("uuid");
+      return "uuid()";
+    case "isoDate": {
+      use.helpers.add("isoOffset");
+      use.helpers.add("randInt");
+      if (/updated|modified|last/.test(p)) return "isoOffset(randInt(0, 30))";
+      if (/(due|expire|deadline|sla)/.test(p)) return "i % 7 === 0 ? isoOffset(-randInt(1, 21)) : isoOffset(randInt(0, 14))";
+      return "isoOffset(randInt(1, 400))";
+    }
+    case "status":
+      use.statuses = true;
+      return "STATUSES[i % STATUSES.length]";
+    case "bool":
+      return "rand() > 0.5";
+    case "int":
+      use.helpers.add("randInt");
+      return "i % 13 === 0 ? 0 : i % 7 === 0 ? -randInt(1, 50) : i % 101 === 0 ? 999999 : randInt(1, 480)";
+    case "email":
+      use.helpers.add("pick");
+      use.pools.add("FIRST_NAMES");
+      use.pools.add("LAST_NAMES");
+      use.pools.add("EMAIL_DOMAINS");
+      return 'pick(FIRST_NAMES).toLowerCase() + "." + pick(LAST_NAMES).toLowerCase() + "@" + pick(EMAIL_DOMAINS)';
+    case "person": {
+      use.helpers.add("pick");
+      use.pools.add("FIRST_NAMES");
+      use.pools.add("LAST_NAMES");
+      const base = 'pick(FIRST_NAMES) + " " + pick(LAST_NAMES)';
+      return plan.nullable ? `i % 9 === 0 ? null : ${base}` : base;
+    }
+    case "company":
+      use.helpers.add("pick");
+      use.pools.add("COMPANIES");
+      return plan.nullable ? "i % 11 === 0 ? null : pick(COMPANIES)" : "pick(COMPANIES)";
+    case "token": {
+      use.helpers.add("pick");
+      const pool = tokenPool(plan.prop);
+      use.pools.add(pool);
+      return `pick(${pool})`;
+    }
+    case "sentence":
+      use.helpers.add("pick");
+      use.pools.add("SENTENCES");
+      use.longText = true;
+      return "i % 5 === 0 ? LONG_TEXT : pick(SENTENCES)";
+    case "phrase":
+      use.helpers.add("pick");
+      use.pools.add("PHRASES");
+      return "pick(PHRASES)";
+    case "fk":
+      use.fkImports.set(plan.related.arrayVar, plan.related.fixtureFile);
+      return `${plan.related.arrayVar}[i % ${plan.related.arrayVar}.length].id`;
+    default:
+      use.helpers.add("pick");
+      use.pools.add("PHRASES");
+      return "pick(PHRASES)";
+  }
+}
+
+// Render one entity's type module: the lifecycle enum (when present) and the row interface.
+function typeModule(entity, entities) {
+  const en = entityNames(entity.name);
+  const plans = fieldPlans(entity, entities);
+  let out = `// src/types/${en.typeFile}.ts — ${en.iface} entity type (generated from docs/design/structure.md; do not hand-edit).\n\n`;
+  const usesStatus = plans.some((f) => f.category === "status");
+  if (usesStatus) {
+    out += `export type ${en.statusType} = ${entity.lifecycle.map((s) => `"${s}"`).join(" | ")};\n\n`;
+  }
+  out += `export interface ${en.iface} {\n`;
+  for (const f of plans) out += `  ${f.prop}: ${f.tsType};\n`;
+  out += `}\n`;
+  return { rel: `src/types/${en.typeFile}.ts`, content: out };
+}
+
+// Render one entity's fixture module: seeded PRNG, pools, a row builder, and empty/degraded variants.
+function fixtureModule(entity, entities, baseSeed, listBearing) {
+  const en = entityNames(entity.name);
+  const plans = fieldPlans(entity, entities);
+  const effectiveSeed = (baseSeed + hashString(entity.name)) >>> 0;
+  const volume = listBearing ? 500 : 120;
+  const use = { helpers: new Set(), pools: new Set(), fkImports: new Map(), statuses: false, longText: false };
+
+  const fieldLines = plans.map((f) => `    ${f.prop}: ${fieldExpr(f, use)},`);
+
+  const usesStatus = plans.some((f) => f.category === "status");
+  const typeImports = [en.iface];
+  if (usesStatus) typeImports.push(en.statusType);
+
+  const fkImportLines = [...use.fkImports.entries()]
+    .map(([arrayVar, file]) => `import { ${arrayVar} } from "./${file}";`)
+    .join("\n");
+
+  const helperOrder = ["mulberry32", "randInt", "pick", "uuid", "isoOffset"];
+  const helperBlocks = [];
+  helperBlocks.push(HELPERS.mulberry32);
+  helperBlocks.push(`const rand = mulberry32(${en.seedConst});`);
+  if (use.helpers.has("randInt")) helperBlocks.push(HELPERS.randInt);
+  if (use.helpers.has("pick")) helperBlocks.push(HELPERS.pick);
+  if (use.helpers.has("uuid")) helperBlocks.push(HELPERS.uuid);
+  if (use.helpers.has("isoOffset")) {
+    helperBlocks.push("const BASE_EPOCH = Date.UTC(2026, 0, 1);");
+    helperBlocks.push(HELPERS.isoOffset);
+  }
+  void helperOrder;
+
+  const poolBlocks = [];
+  for (const name of Object.keys(POOL_DECLS)) if (use.pools.has(name)) poolBlocks.push(POOL_DECLS[name]);
+  if (use.longText) poolBlocks.push(LONG_TEXT_DECL);
+  if (use.statuses) poolBlocks.push(`const STATUSES: ${en.statusType}[] = [${entity.lifecycle.map((s) => `"${s}"`).join(", ")}];`);
+
+  const degradedOverrides = plans
+    .filter((f) => f.nullable)
+    .map((f) => `  ${f.prop}: null,`);
+  const firstInt = plans.find((f) => f.category === "int");
+  if (firstInt) degradedOverrides.push(`  ${firstInt.prop}: 0,`);
+
+  const parts = [];
+  parts.push(`// src/fixtures/${en.fixtureFile}.ts — seeded ${en.iface} fixtures (generated; do not hand-edit rows).`);
+  const importGroup = [`import type { ${typeImports.join(", ")} } from "../types/${en.typeFile}";`];
+  if (fkImportLines) importGroup.push(fkImportLines);
+  parts.push(importGroup.join("\n"));
+  parts.push(`export const ${en.seedConst} = ${effectiveSeed};`);
+  parts.push(helperBlocks.join("\n\n"));
+  if (poolBlocks.length) parts.push(poolBlocks.join("\n"));
+  parts.push(
+    `// One ${en.iface} row shaped like production data; unhappy values are seeded in by index.\n` +
+      `function build${en.iface}(i: number): ${en.iface} {\n  return {\n${fieldLines.join("\n")}\n  };\n}`,
+  );
+  parts.push(
+    `// ${volume} rows exercise ${listBearing ? "queue and table density" : "reference-join volume"}; lifecycle states are distributed across the set.\n` +
+      `export const ${en.arrayVar}: ${en.iface}[] = Array.from({ length: ${volume} }, (_row, i) => build${en.iface}(i));`,
+  );
+  parts.push(`// The same surface, empty: a first-run or filtered-to-nothing result.\nexport const ${en.emptyVar}: ${en.iface}[] = [];`);
+  parts.push(
+    `// The same surface, degraded: enrichment failed and joins did not resolve.\n` +
+      `export const ${en.degradedVar}: ${en.iface}[] = ${en.arrayVar}.slice(0, 12).map((row) => ({\n  ...row,\n${degradedOverrides.join("\n")}\n}));`,
+  );
+  return { rel: `src/fixtures/${en.fixtureFile}.ts`, content: parts.join("\n\n") + "\n" };
+}
+
+// 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);
+}
+
+// Entry point: load the map, emit type + fixture modules per entity, 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;
+  const seedRaw = args.seed;
+  if (!structurePath || !out || seedRaw === undefined || seedRaw === true) {
+    refuse("missing arguments", "usage: generate-fixtures.mjs <docs/design/structure.md> --seed <n> --out <project-root-dir>");
+  }
+  const baseSeed = Number.parseInt(String(seedRaw), 10);
+  if (Number.isNaN(baseSeed)) {
+    refuse(`--seed "${seedRaw}" is not an integer`, "pass an integer base seed, e.g. --seed 4173");
+  }
+  const model = loadStructure(structurePath);
+  const listBearingEntities = new Set();
+  if (model.unitOfWork) listBearingEntities.add(model.unitOfWork);
+  for (const s of model.surfaces) if (LIST_BEARING_ARCHETYPES.has(s.archetype)) listBearingEntities.add(s.entity);
+
+  const written = [];
+  for (const entity of model.entities) {
+    const typeMod = typeModule(entity, model.entities);
+    emit(out, typeMod.rel, typeMod.content, written);
+    const fixtureMod = fixtureModule(entity, model.entities, baseSeed, listBearingEntities.has(entity.name));
+    emit(out, fixtureMod.rel, fixtureMod.content, written);
+  }
+  process.stdout.write(`generate-fixtures.mjs: wrote ${written.length} files under ${out} (base seed ${baseSeed})\n`);
+  for (const rel of written) process.stdout.write(`  ${rel}\n`);
+}
+
+main();

package/data/harnesses/code/skills/design/scripts/hook-config.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "PostToolUse hook fragment for the design skill's per-edit detector (D19). This file does NOT self-register — the code plugin merges this matcher-group into plugins/code/hooks at cutover; wiring it into settings is the plugin's job, not this file's. CLAUDE_PLUGIN_ROOT resolves to the installed plugin root at registration. On every Edit/Write/MultiEdit the command reads the hook payload from stdin, runs detector.mjs on the edited file only when it matches \\.(tsx|ts|css|html)$, skips node_modules and the skill's own sources (skills/design/), walks up from the edited file to find the nearest project-root design.md and passes it as --manifest so the cod-02 lever-manifest drift check (D10) fires on the write; when no design.md exists yet (create, before intake) detector.mjs no-ops the drift check. On any violation (detector exit 1) it feeds the fix-or-classify report back to the agent via stderr with exit 2. Timeout is in seconds.",
+  "matcher": "Edit|Write|MultiEdit",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node -e 'let d=\"\";process.stdin.on(\"data\",c=>d+=c).on(\"end\",()=>{try{const p=JSON.parse(d);const f=(p.tool_input&&p.tool_input.file_path)||\"\";if(!f||!/\\.(tsx|ts|css|html)$/.test(f)||f.includes(\"node_modules\")||f.includes(\"/skills/design/\"))return process.exit(0);const path=require(\"node:path\");const fs=require(\"node:fs\");let dir=path.dirname(path.resolve(f)),manifest=null;for(;;){const cand=path.join(dir,\"design.md\");if(fs.existsSync(cand)){manifest=cand;break;}const up=path.dirname(dir);if(up===dir)break;dir=up;}const{spawnSync}=require(\"node:child_process\");const args=[(process.env.CLAUDE_PLUGIN_ROOT||\".\")+\"/skills/design/scripts/detector.mjs\",f];if(manifest)args.push(\"--manifest\",manifest);const r=spawnSync(\"node\",args,{encoding:\"utf8\"});if(r.status===1){process.stderr.write(r.stdout||\"\");return process.exit(2);}process.exit(0);}catch(e){process.exit(0);}});'",
+      "timeout": 30
+    }
+  ]
+}