aub-workspace 0.3.0

package/vendor/aub/scripts/export-md.lib.mjs

@@ -0,0 +1,302 @@
+// Pure-function Markdown exporter for UI Blueprint.
+// Browser-safe: no Node imports, no shebang, no file I/O.
+// The CLI wrapper (export-md.mjs) imports this and handles file operations.
+
+/**
+ * Convert a Blueprint to Markdown suitable as agent prompt context.
+ * Sections:
+ *   1. Title + meta
+ *   2. Screen summary
+ *   3. Component hierarchy (tree)
+ *   4. Layout contract
+ *   5. Interaction rules
+ *   6. Responsive rules
+ *   7. Non-violable conditions
+ *   8. Acceptance checklist
+ *   9. Agent task
+ */
+export function exportMarkdown(blueprint) {
+  const lines = [];
+
+  // 1. Title + meta
+  lines.push(`# ${blueprint.screen.name} — Implementation Brief`);
+  lines.push('');
+  lines.push(`> **Version:** ${blueprint.version}`);
+  lines.push(`> **Source:** this brief was generated by \`scripts/export-md.mjs\` from a UI Blueprint.`);
+  lines.push(`> **Target framework:** any (this brief is framework-agnostic)`);
+  lines.push('');
+  lines.push('This document is the Agent context export of a UI Blueprint. Read it top-to-bottom before implementing. The acceptance checklist at the bottom is the contract — every item must pass before this implementation is considered done.');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 2. Screen summary
+  lines.push('## 1. Screen Summary');
+  lines.push('');
+  lines.push('| Field | Value |');
+  lines.push('|---|---|');
+  lines.push(`| **id** | \`${blueprint.screen.id}\` |`);
+  lines.push(`| **name** | ${blueprint.screen.name} |`);
+  lines.push(`| **type** | \`${blueprint.screen.type}\` |`);
+  lines.push(`| **platform** | \`${blueprint.screen.platform}\` |`);
+  lines.push(`| **primary_user_goal** | ${blueprint.screen.primary_user_goal} |`);
+  if (blueprint.screen.notes) lines.push(`| **notes** | ${blueprint.screen.notes} |`);
+  lines.push('');
+
+  // 3. Component hierarchy
+  lines.push('## 2. Component Hierarchy');
+  lines.push('');
+  lines.push('```');
+  lines.push(renderTree(blueprint));
+  lines.push('```');
+  lines.push('');
+  lines.push('Every node in the tree is a **registered semantic component type** (not a generic rectangle). When you implement, you MUST use components that map to the stated type — not visual stand-ins.');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 4. Layout contract
+  lines.push('## 3. Layout Contract');
+  lines.push('');
+  const layoutNodes = blueprint.nodes.filter((n) => n.layout);
+  if (layoutNodes.length > 0) {
+    for (const n of layoutNodes) {
+      const desc = describeLayout(n);
+      if (desc) lines.push(`- **${n.name}** (\`${n.id}\`): ${desc}`);
+    }
+  } else {
+    lines.push('_No layout rules declared._');
+  }
+  lines.push('');
+  const placementNodes = blueprint.nodes.filter((node) => node.placements && Object.keys(node.placements).length > 0);
+  if (placementNodes.length > 0) {
+    lines.push('### Exact Viewport Geometry');
+    lines.push('');
+    lines.push('For children of a `freeform` container, these pixel values are authoritative at the declared viewport size. Preserve relative composition when interpolating between declared viewports.');
+    lines.push('');
+    lines.push('| Node | Viewport | x | y | width | height | z-index |');
+    lines.push('|---|---:|---:|---:|---:|---:|---:|');
+    for (const node of placementNodes) {
+      for (const viewport of blueprint.viewports) {
+        const placement = resolvePlacement(node, viewport.id);
+        if (!placement) continue;
+        lines.push(`| \`${node.id}\` | \`${viewport.id}\` | ${placement.x} | ${placement.y} | ${placement.width} | ${placement.height} | ${placement.z_index ?? 1} |`);
+      }
+    }
+    lines.push('');
+  }
+  lines.push('Use each container according to its declared mode: `auto` means flex/grid flow is the contract; `freeform` means child `placements` are the contract. Do not replace one mode with the other unless an acceptance item explicitly permits it.');
+  lines.push('');
+  lines.push('### Design System Tokens');
+  lines.push('');
+  renderDesignSystem(lines, blueprint.design_system);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 5. Interaction rules
+  lines.push('## 4. Interaction Rules');
+  lines.push('');
+  if (blueprint.interactions.length > 0) {
+    lines.push('| Source | Trigger | Action | Target | Result |');
+    lines.push('|---|---|---|---|---|');
+    for (const i of blueprint.interactions) {
+      lines.push(`| \`${i.source_node_id}\` | \`${i.trigger}\` | \`${i.action}\` | ${i.target ? `\`${i.target}\`` : '—'} | ${i.result_state} |`);
+    }
+  } else {
+    lines.push('_No interactions declared._');
+  }
+  lines.push('');
+  lines.push('Every interaction declares its **trigger**, **action verb-noun**, and **observable result state**. Do not invent interactions not listed here.');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 6. Responsive rules
+  lines.push('## 5. Responsive Rules');
+  lines.push('');
+  if (blueprint.responsive.length > 0) {
+    lines.push('| Viewport | Target | Rule | Effect |');
+    lines.push('|---|---|---|---|');
+    for (const r of blueprint.responsive) {
+      const changeText = Object.keys(r.changes || {}).length > 0
+        ? Object.entries(r.changes).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')
+        : '_no change_';
+      lines.push(`| \`${r.viewport}\` | \`${r.target_node_id}\` | \`${r.rule}\` | ${changeText} |`);
+    }
+  } else {
+    lines.push('_No responsive rules declared._');
+  }
+  lines.push('');
+  lines.push('Every responsive decision is declared explicitly. The agent MUST NOT collapse the sidebar silently, hide the metric row, or change table to horizontal scroll without a declared rule.');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 7. Non-violable conditions (from acceptance priority=blocker)
+  lines.push('## 6. Non-Violable Conditions');
+  lines.push('');
+  const blockers = blueprint.acceptance.filter((a) => a.priority === 'blocker');
+  if (blockers.length > 0) {
+    blockers.forEach((b, i) => {
+      lines.push(`${i + 1}. **${b.statement}** _(target: \`${b.target}\`)_`);
+    });
+  } else {
+    lines.push('_No blocker-level acceptance items declared._');
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 8. Acceptance checklist
+  lines.push('## 7. Acceptance Checklist');
+  lines.push('');
+  lines.push('This checklist is the contract. Every item must be verifiable. Mark each `[x]` only after manual or automated verification.');
+  lines.push('');
+  if (blueprint.acceptance.length > 0) {
+    const byType = groupBy(blueprint.acceptance, (a) => a.type);
+    let sectionNum = 0;
+    const typeOrder = ['layout', 'interaction', 'responsive', 'a11y', 'content', 'performance'];
+    for (const t of typeOrder) {
+      if (!byType[t] || byType[t].length === 0) continue;
+      sectionNum++;
+      const sectionNames = { layout: 'Layout', interaction: 'Interaction', responsive: 'Responsive', a11y: 'Accessibility', content: 'Content', performance: 'Performance' };
+      lines.push(`### ${sectionNames[t] ?? t} (${byType[t].length})`);
+      lines.push('');
+      for (const a of byType[t]) {
+        lines.push(`- [ ] **${a.id}** (${a.priority}) — ${a.statement} _[verify: \`${a.verification_method}\`]_`);
+      }
+      lines.push('');
+    }
+    lines.push(`**Total: ${blueprint.acceptance.length} verifiable items** (≥5 required by spec).`);
+  } else {
+    lines.push('_No acceptance items declared._');
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // 9. Agent task
+  lines.push('## 8. Agent Task');
+  lines.push('');
+  lines.push(`You are implementing the ${blueprint.screen.name} described above. Your deliverable is:`);
+  lines.push('');
+  lines.push('1. A new file or route matching the component hierarchy in §2.');
+  lines.push('2. Implementation that respects the layout contract in §3.');
+  lines.push('3. Wiring of all interactions in §4.');
+  lines.push('4. Responsive behavior per §5.');
+  lines.push('5. A passing run of the acceptance checklist in §7 — every item verifiable, not vibes.');
+  lines.push('');
+  lines.push('### Implementation order (suggested, not strict)');
+  lines.push('');
+  lines.push('1. App shell + main containers (skeleton, no data)');
+  lines.push('2. Children nodes with hardcoded content');
+  lines.push('3. Wire primary interactions');
+  lines.push('4. Wire secondary interactions and edge cases');
+  lines.push('5. Add responsive rules');
+  lines.push('6. Add empty/loading/error states');
+  lines.push('7. Run accessibility audit, fix any issues');
+  lines.push('8. Run acceptance checklist, mark all items');
+  lines.push('');
+  lines.push('### Stop conditions');
+  lines.push('');
+  lines.push('- **Blocker found:** stop and report. Do not "fix forward" by relaxing the spec.');
+  lines.push('- **Acceptance item impossible as specified:** stop and report. Do not silently weaken the criterion.');
+  lines.push('- **Component type does not exist in your framework:** stop and report. Do not substitute a generic `<div>`.');
+  lines.push('');
+  lines.push('### Output format (when done)');
+  lines.push('');
+  lines.push('Report per acceptance item:');
+  lines.push('');
+  lines.push('```');
+  lines.push('[ ] acc_id — pass | fail | needs-review');
+  lines.push('    evidence: <screenshot path | file:line | dom query | interaction log>');
+  lines.push('    notes: <if any>');
+  lines.push('```');
+  lines.push('');
+  lines.push('If any item is `fail` or `needs-review`, the implementation is not done.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function renderTree(blueprint) {
+  const byId = new Map(blueprint.nodes.map((n) => [n.id, n]));
+  const root = blueprint.nodes.find((n) => n.parent_id === null) || blueprint.nodes[0];
+  if (!root) return '(empty)';
+  const lines = [];
+  walk(root, 0);
+  return lines.join('\n');
+
+  function walk(node, depth) {
+    const indent = '  '.repeat(depth);
+    const label = `${node.id}  (${node.type})`;
+    const childCount = node.children?.length ?? 0;
+    lines.push(`${indent}${label}${childCount > 0 ? '' : '  [leaf]'}`);
+    if (Array.isArray(node.children)) {
+      for (const childId of node.children) {
+        const child = byId.get(childId);
+        if (child) walk(child, depth + 1);
+      }
+    }
+  }
+}
+
+function describeLayout(node) {
+  const l = node.layout;
+  const parts = [];
+  if (l.mode) parts.push(`mode: ${l.mode}`);
+  if (l.display) parts.push(`display: ${l.display}`);
+  if (l.direction) parts.push(`direction: ${l.direction}`);
+  if (l.grid?.columns) parts.push(`grid: ${l.grid.columns} cols${l.grid.template ? ` (${l.grid.template})` : ''}`);
+  if (l.gap) {
+    if (l.gap.x != null && l.gap.y != null) parts.push(`gap: ${l.gap.x}/${l.gap.y}px`);
+    else if (l.gap.x != null) parts.push(`gap-x: ${l.gap.x}px`);
+    else if (l.gap.y != null) parts.push(`gap-y: ${l.gap.y}px`);
+  }
+  if (l.padding) {
+    const p = l.padding;
+    if (p.top != null || p.bottom != null || p.left != null || p.right != null) {
+      parts.push(`padding: ${p.top ?? '-'}/${p.right ?? '-'}/${p.bottom ?? '-'}/${p.left ?? '-'}`);
+    }
+  }
+  if (l.width) parts.push(`width: ${l.width.value}${l.width.unit}`);
+  if (l.height) parts.push(`height: ${l.height.value}${l.height.unit}`);
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
+function resolvePlacement(node, viewportId) {
+  const placements = node.placements;
+  if (!placements) return null;
+  return placements[viewportId]
+    ?? placements.desktop
+    ?? placements.tablet
+    ?? placements.mobile
+    ?? placements.wide
+    ?? null;
+}
+
+function renderDesignSystem(lines, designSystem) {
+  if (!designSystem) {
+    lines.push('_No design system tokens declared._');
+    return;
+  }
+  lines.push(`Token set: **${designSystem.name}**`);
+  lines.push('');
+  lines.push('| Group | Token | Value |');
+  lines.push('|---|---|---|');
+  for (const group of ['colors', 'typography', 'spacing', 'radii', 'shadows']) {
+    for (const [name, value] of Object.entries(designSystem[group] ?? {})) {
+      lines.push(`| ${group} | \`${name}\` | \`${String(value).replaceAll('|', '\\|')}\` |`);
+    }
+  }
+}
+
+function groupBy(arr, keyFn) {
+  const out = {};
+  for (const x of arr) {
+    const k = keyFn(x);
+    (out[k] ??= []).push(x);
+  }
+  return out;
+}

package/vendor/aub/scripts/export-md.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// CLI wrapper around the browser-safe Markdown exporter.
+// Usage: node scripts/export-md.mjs <input.ui.json|input.ui.yaml> [output.ui.md]
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { exportMarkdown } from './export-md.lib.mjs';
+
+export { exportMarkdown };
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.error('Usage: node scripts/export-md.mjs <input.ui.json|input.ui.yaml> [output.ui.md]');
+    console.error('       node scripts/export-md.mjs -  (read JSON from stdin)');
+    process.exit(2);
+  }
+
+  const inputText = args[0] === '-'
+    ? await readFile(0, 'utf8')
+    : await readFile(resolve(args[0]), 'utf8');
+  const ext = args[0] === '-' ? '.json' : extname(args[0]).toLowerCase();
+  const blueprint = ext === '.yaml' || ext === '.yml'
+    ? yaml.load(inputText)
+    : JSON.parse(inputText);
+  const markdown = exportMarkdown(blueprint);
+
+  if (args[1] && args[1] !== '-') {
+    await writeFile(resolve(args[1]), markdown, 'utf8');
+    console.error(`✓ wrote ${args[1]} (${markdown.length} bytes)`);
+  } else {
+    process.stdout.write(markdown);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

package/vendor/aub/scripts/generate-registry-artifacts.lib.mjs

@@ -0,0 +1,118 @@
+// Pure helpers that derive the schema enums and TypeScript unions from the
+// component registry. The registry (schema/registry/components.json) is the
+// single source of truth; this module computes everything else from it.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+export const REGISTRY_PATH = resolve(ROOT, 'schema', 'registry', 'components.json');
+export const SCHEMA_PATH = resolve(ROOT, 'schema', 'ui-blueprint.schema.json');
+export const TYPES_PATH = resolve(ROOT, 'schema', 'types.ts');
+
+export const TYPES_BEGIN = '// <generated:component-types>';
+export const TYPES_END = '// </generated:component-types>';
+
+export async function loadCoreRegistry() {
+  return JSON.parse(await readFile(REGISTRY_PATH, 'utf8'));
+}
+
+/**
+ * Flatten the registry into ordered type lists, preserving category and
+ * in-category order so output is deterministic.
+ */
+export function computeTypeLists(registry) {
+  const all = [];
+  const containers = [];
+  const leaves = [];
+  for (const category of registry.categories ?? []) {
+    for (const type of category.types ?? []) {
+      all.push(type.name);
+      if (type.isContainer) containers.push(type.name);
+      else leaves.push(type.name);
+    }
+  }
+  return { all, containers, leaves };
+}
+
+/** Group type names by registry category for readable, stable rendering. */
+function typesByCategory(registry) {
+  return (registry.categories ?? []).map((category) => ({
+    id: category.id,
+    names: (category.types ?? []).map((t) => t.name),
+  }));
+}
+
+function renderUnionLines(groups, indent = '  ') {
+  return groups
+    .filter((g) => g.names.length > 0)
+    .map((g) => `${indent}| ${g.names.map((n) => `'${n}'`).join(' | ')}`)
+    .join('\n');
+}
+
+/** Produce the generated TypeScript block (between the sentinel markers). */
+export function renderTypesSection(registry) {
+  const groups = typesByCategory(registry);
+  const lists = computeTypeLists(registry);
+  const containerGroups = (registry.categories ?? []).map((category) => ({
+    id: category.id,
+    names: (category.types ?? []).filter((t) => t.isContainer).map((t) => t.name),
+  }));
+
+  const componentUnion = renderUnionLines(groups);
+  const containerUnion = renderUnionLines(containerGroups, '    ');
+
+  return [
+    TYPES_BEGIN,
+    '/** Semantic component type — agents read this to know WHAT a node is. */',
+    'export type ComponentType =',
+    `${componentUnion};`,
+    '',
+    'export type ContainerComponentType = Extract<',
+    '  ComponentType,',
+    `${containerUnion}`,
+    '>;',
+    '',
+    'export type LeafComponentType = Exclude<ComponentType, ContainerComponentType>;',
+    TYPES_END,
+  ].join('\n');
+}
+
+/**
+ * Return a new schema object with the generated core-type enums populated from
+ * the registry. Does not mutate the input.
+ */
+export function applyEnumsToSchema(schema, lists) {
+  const next = structuredClone(schema);
+  const defs = next.$defs ?? {};
+  if (!defs.coreComponentType || !defs.coreContainerComponentType || !defs.coreLeafComponentType) {
+    throw new Error(
+      'schema is missing coreComponentType / coreContainerComponentType / coreLeafComponentType $defs'
+    );
+  }
+  defs.coreComponentType.enum = [...lists.all];
+  defs.coreContainerComponentType.enum = [...lists.containers];
+  defs.coreLeafComponentType.enum = [...lists.leaves];
+  return next;
+}
+
+export function serializeSchema(schema) {
+  return `${JSON.stringify(schema, null, 2)}\n`;
+}
+
+/** Replace the generated block of an existing types.ts source string. */
+export function replaceTypesSection(source, generatedBlock) {
+  const start = source.indexOf(TYPES_BEGIN);
+  const end = source.indexOf(TYPES_END);
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(
+      `types.ts is missing the generated markers ${TYPES_BEGIN} / ${TYPES_END}`
+    );
+  }
+  const before = source.slice(0, start);
+  const after = source.slice(end + TYPES_END.length);
+  return `${before}${generatedBlock}${after}`;
+}

package/vendor/aub/scripts/generate-registry-artifacts.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Regenerate the schema core-type enums and the types.ts component-type block
+// from schema/registry/components.json (the single source of truth).
+//
+// Usage:
+//   node scripts/generate-registry-artifacts.mjs           # write artifacts
+//   node scripts/generate-registry-artifacts.mjs --check   # fail if stale
+
+import { readFile, writeFile } from 'node:fs/promises';
+import {
+  SCHEMA_PATH,
+  TYPES_PATH,
+  loadCoreRegistry,
+  computeTypeLists,
+  renderTypesSection,
+  replaceTypesSection,
+  applyEnumsToSchema,
+  serializeSchema,
+} from './generate-registry-artifacts.lib.mjs';
+
+async function build() {
+  const registry = await loadCoreRegistry();
+  const lists = computeTypeLists(registry);
+
+  const schema = JSON.parse(await readFile(SCHEMA_PATH, 'utf8'));
+  const nextSchema = serializeSchema(applyEnumsToSchema(schema, lists));
+
+  const typesSource = await readFile(TYPES_PATH, 'utf8');
+  const nextTypes = replaceTypesSection(typesSource, renderTypesSection(registry));
+
+  return { nextSchema, nextTypes };
+}
+
+async function main() {
+  const check = process.argv.includes('--check');
+  const { nextSchema, nextTypes } = await build();
+
+  if (check) {
+    const [currentSchema, currentTypes] = await Promise.all([
+      readFile(SCHEMA_PATH, 'utf8'),
+      readFile(TYPES_PATH, 'utf8'),
+    ]);
+    const stale = [];
+    if (currentSchema !== nextSchema) stale.push('schema/ui-blueprint.schema.json');
+    if (currentTypes !== nextTypes) stale.push('schema/types.ts');
+    if (stale.length > 0) {
+      console.error('✗ generated artifacts are stale. Run `pnpm gen`. Out of date:');
+      for (const f of stale) console.error(`  - ${f}`);
+      process.exit(1);
+    }
+    console.log('✓ generated artifacts are up to date');
+    return;
+  }
+
+  await Promise.all([
+    writeFile(SCHEMA_PATH, nextSchema, 'utf8'),
+    writeFile(TYPES_PATH, nextTypes, 'utf8'),
+  ]);
+  console.log('✓ wrote schema enums and types.ts component types from registry');
+}
+
+main().catch((err) => {
+  console.error(err.message ?? err);
+  process.exit(2);
+});