aub-workspace 0.3.0

package/vendor/aub/scripts/diff-blueprint.lib.mjs

@@ -0,0 +1,148 @@
+export function diffBlueprints(before, after) {
+  const screenChanges = changedPaths(before.screen, after.screen);
+  const nodes = diffByKey(before.nodes, after.nodes, (item) => item.id);
+  const interactions = diffByKey(before.interactions, after.interactions, (item) => item.id);
+  const responsive = diffByKey(
+    before.responsive,
+    after.responsive,
+    (item, index) => `${item.viewport}:${item.target_node_id}:${index}`
+  );
+  const acceptance = diffByKey(before.acceptance, after.acceptance, (item) => item.id);
+  const viewports = diffByKey(before.viewports, after.viewports, (item) => item.id);
+  const designSystemChanges = changedPaths(before.design_system ?? {}, after.design_system ?? {});
+
+  return {
+    before: { version: before.version, screen_id: before.screen.id, screen_name: before.screen.name },
+    after: { version: after.version, screen_id: after.screen.id, screen_name: after.screen.name },
+    summary: {
+      screen_fields_changed: screenChanges.length,
+      nodes_added: nodes.added.length,
+      nodes_removed: nodes.removed.length,
+      nodes_changed: nodes.changed.length,
+      interactions_changed: changeCount(interactions),
+      responsive_rules_changed: changeCount(responsive),
+      acceptance_items_changed: changeCount(acceptance),
+      viewports_changed: changeCount(viewports),
+      design_tokens_changed: designSystemChanges.length,
+    },
+    screen_changes: screenChanges,
+    nodes,
+    interactions,
+    responsive,
+    acceptance,
+    viewports,
+    design_system_changes: designSystemChanges,
+  };
+}
+
+export function renderBlueprintDiff(diff) {
+  const lines = [
+    '# UI Blueprint Diff',
+    '',
+    `- Before: **${diff.before.screen_name}** (\`${diff.before.screen_id}\`, v${diff.before.version})`,
+    `- After: **${diff.after.screen_name}** (\`${diff.after.screen_id}\`, v${diff.after.version})`,
+    '',
+    '## Summary',
+    '',
+    '| Area | Added | Removed | Changed |',
+    '|---|---:|---:|---:|',
+    `| Nodes | ${diff.nodes.added.length} | ${diff.nodes.removed.length} | ${diff.nodes.changed.length} |`,
+    `| Interactions | ${diff.interactions.added.length} | ${diff.interactions.removed.length} | ${diff.interactions.changed.length} |`,
+    `| Responsive rules | ${diff.responsive.added.length} | ${diff.responsive.removed.length} | ${diff.responsive.changed.length} |`,
+    `| Acceptance items | ${diff.acceptance.added.length} | ${diff.acceptance.removed.length} | ${diff.acceptance.changed.length} |`,
+    `| Viewports | ${diff.viewports.added.length} | ${diff.viewports.removed.length} | ${diff.viewports.changed.length} |`,
+    '',
+  ];
+
+  renderPathSection(lines, 'Screen metadata', diff.screen_changes);
+  renderEntitySection(lines, 'Nodes', diff.nodes);
+  renderEntitySection(lines, 'Interactions', diff.interactions);
+  renderEntitySection(lines, 'Responsive rules', diff.responsive);
+  renderEntitySection(lines, 'Acceptance items', diff.acceptance);
+  renderEntitySection(lines, 'Viewports', diff.viewports);
+  renderPathSection(lines, 'Design system', diff.design_system_changes);
+
+  return `${lines.join('\n').trim()}\n`;
+}
+
+function diffByKey(beforeItems = [], afterItems = [], keyOf) {
+  const beforeMap = new Map(beforeItems.map((item, index) => [keyOf(item, index), item]));
+  const afterMap = new Map(afterItems.map((item, index) => [keyOf(item, index), item]));
+  const added = [];
+  const removed = [];
+  const changed = [];
+
+  for (const [key, item] of afterMap) {
+    if (!beforeMap.has(key)) added.push({ key, item });
+  }
+  for (const [key, item] of beforeMap) {
+    if (!afterMap.has(key)) removed.push({ key, item });
+  }
+  for (const [key, beforeItem] of beforeMap) {
+    const afterItem = afterMap.get(key);
+    if (!afterItem) continue;
+    const paths = changedPaths(beforeItem, afterItem);
+    if (paths.length > 0) changed.push({ key, paths, before: beforeItem, after: afterItem });
+  }
+
+  return { added, removed, changed };
+}
+
+function changedPaths(before, after, prefix = '') {
+  if (stableValue(before) === stableValue(after)) return [];
+  if (!isPlainObject(before) || !isPlainObject(after)) return [prefix || '(value)'];
+
+  const paths = [];
+  const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+  for (const key of keys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const beforeValue = before[key];
+    const afterValue = after[key];
+    if (stableValue(beforeValue) === stableValue(afterValue)) continue;
+    if (isPlainObject(beforeValue) && isPlainObject(afterValue)) {
+      paths.push(...changedPaths(beforeValue, afterValue, path));
+    } else {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return `[${value.map(stableValue).join(',')}]`;
+  if (isPlainObject(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableValue(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function changeCount(section) {
+  return section.added.length + section.removed.length + section.changed.length;
+}
+
+function renderPathSection(lines, title, paths) {
+  lines.push(`## ${title}`, '');
+  if (paths.length === 0) lines.push('_No changes._', '');
+  else {
+    for (const path of paths) lines.push(`- \`${path}\``);
+    lines.push('');
+  }
+}
+
+function renderEntitySection(lines, title, section) {
+  lines.push(`## ${title}`, '');
+  if (changeCount(section) === 0) {
+    lines.push('_No changes._', '');
+    return;
+  }
+  for (const entry of section.added) lines.push(`- Added \`${entry.key}\``);
+  for (const entry of section.removed) lines.push(`- Removed \`${entry.key}\``);
+  for (const entry of section.changed) {
+    lines.push(`- Changed \`${entry.key}\`: ${entry.paths.map((path) => `\`${path}\``).join(', ')}`);
+  }
+  lines.push('');
+}

package/vendor/aub/scripts/diff-blueprint.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { diffBlueprints, renderBlueprintDiff } from './diff-blueprint.lib.mjs';
+
+const args = process.argv.slice(2);
+const jsonOutput = args.includes('--json');
+const files = args.filter((arg) => arg !== '--json');
+
+if (files.length !== 2) {
+  console.error('Usage: node scripts/diff-blueprint.mjs <before.ui.json|yaml> <after.ui.json|yaml> [--json]');
+  process.exit(2);
+}
+
+const [before, after] = await Promise.all(files.map(readBlueprint));
+const diff = diffBlueprints(before, after);
+process.stdout.write(jsonOutput ? `${JSON.stringify(diff, null, 2)}\n` : renderBlueprintDiff(diff));
+
+async function readBlueprint(path) {
+  const text = await readFile(resolve(path), 'utf8');
+  const extension = extname(path).toLowerCase();
+  return extension === '.yaml' || extension === '.yml' ? yaml.load(text) : JSON.parse(text);
+}

package/vendor/aub/scripts/export-agent-prompt.lib.d.mts

@@ -0,0 +1,10 @@
+export type Blueprint = Record<string, any>;
+
+export interface ExportAgentPromptOptions {
+  adapter?: string;
+  task?: string;
+}
+
+export function exportAgentPrompt(blueprint: Blueprint, options?: ExportAgentPromptOptions): string;
+export function supportedAgentAdapters(): string[];
+export function supportedAgentTasks(): string[];

package/vendor/aub/scripts/export-agent-prompt.lib.mjs

@@ -0,0 +1,160 @@
+import { exportMarkdown } from './export-md.lib.mjs';
+import { createImplementationReportTemplate } from './implementation-report.lib.mjs';
+
+const ADAPTERS = {
+  generic: {
+    label: 'Generic coding agent',
+    repositoryInstructions: [
+      'Inspect the repository instructions and existing implementation patterns before changing files.',
+      'Use the repository-native package manager, components, tokens, and test commands.',
+    ],
+  },
+  codex: {
+    label: 'Codex',
+    repositoryInstructions: [
+      'Read every applicable AGENTS.md before editing files.',
+      'Inspect the existing codebase first and preserve local architecture and design-system conventions.',
+      'Run the repository checks that cover every changed surface and report their exact result.',
+    ],
+  },
+  'claude-code': {
+    label: 'Claude Code',
+    repositoryInstructions: [
+      'Read CLAUDE.md and other repository instructions before editing files.',
+      'Inspect related components and tests before choosing an implementation approach.',
+      'Run the repository checks that cover every changed surface and report their exact result.',
+    ],
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    repositoryInstructions: [
+      'Read .github/copilot-instructions.md and any applicable AGENTS.md before editing files.',
+      'Inspect the existing codebase first and reuse the repository-native components, tokens, and patterns.',
+      'Run the repository checks that cover every changed surface and report their exact result.',
+    ],
+  },
+};
+
+const TASKS = {
+  author: {
+    title: 'Author a UI Blueprint',
+    outcome: 'Produce a schema-valid UI Blueprint JSON document from the supplied product and screen requirements.',
+    steps: [
+      'Inspect the component registry, schema, canonical example, and supplied source material.',
+      'Model one semantic node tree with explicit layout, bindings, interactions, responsive rules, and acceptance criteria.',
+      'Validate the generated JSON and report every unresolved product decision instead of guessing.',
+    ],
+  },
+  implement: {
+    title: 'Implement this UI Blueprint',
+    outcome: 'Modify the target repository so the implementation satisfies the Blueprint and every acceptance criterion.',
+    steps: [
+      'Map every Blueprint node to an existing or new implementation component.',
+      'Implement the declared hierarchy, layout mode, viewport geometry, interactions, and responsive behavior.',
+      'Verify every acceptance item and attach concrete evidence.',
+    ],
+  },
+  plan: {
+    title: 'Plan this UI Blueprint implementation',
+    outcome: 'Produce an implementation plan grounded in the target repository without changing files.',
+    steps: [
+      'Map Blueprint nodes to likely files, routes, and components in the repository.',
+      'Identify reusable components, missing capabilities, dependencies, and risks.',
+      'Return ordered implementation steps tied to node ids and acceptance ids.',
+    ],
+  },
+  review: {
+    title: 'Review an implementation against this UI Blueprint',
+    outcome: 'Inspect the current implementation and report contract mismatches without silently relaxing the Blueprint.',
+    steps: [
+      'Compare the implementation against node hierarchy, layout, geometry, interactions, and responsive rules.',
+      'Evaluate every acceptance item as pass, fail, or needs-review.',
+      'Report mismatches with file references and evidence, ordered by severity.',
+    ],
+  },
+};
+
+export function exportAgentPrompt(blueprint, options = {}) {
+  const adapterId = options.adapter ?? 'generic';
+  const taskId = options.task ?? 'implement';
+  const adapter = ADAPTERS[adapterId];
+  const task = TASKS[taskId];
+  const reportTemplate = createImplementationReportTemplate(blueprint);
+  if (!adapter) throw new Error(`Unknown agent adapter: ${adapterId}`);
+  if (!task) throw new Error(`Unknown agent task: ${taskId}`);
+
+  const lines = [
+    `# ${task.title}`,
+    '',
+    `Adapter: **${adapter.label}**`,
+    `Screen: **${blueprint.screen.name}** (\`${blueprint.screen.id}\`)`,
+    '',
+    '## Required outcome',
+    '',
+    task.outcome,
+    '',
+    '## Repository execution rules',
+    '',
+    ...adapter.repositoryInstructions.map((instruction) => `- ${instruction}`),
+    taskId === 'author'
+      ? '- Treat the supplied requirements as evidence. Use only registered component types and do not invent missing behavior.'
+      : '- Treat the embedded UI Blueprint as the source of truth. Do not redesign, infer missing behavior, or weaken acceptance criteria.',
+    '- If the Blueprint conflicts with repository constraints, stop and report the conflict with a concrete proposed resolution.',
+    '',
+    '## Required workflow',
+    '',
+    '- Start by replying in the user\'s language. Explain what AUB is, list the supplied Blueprint evidence, name the task you will perform, and identify any unresolved product decisions.',
+    ...task.steps.map((step, index) => `${index + 1}. ${step}`),
+    '',
+    '## Final response contract',
+    '',
+    ...(taskId === 'author'
+      ? [
+          '- Return one complete Blueprint JSON object and no prose or Markdown fence.',
+          '- Use children only on registered container types; every leaf must use `children: []`.',
+          '- Use only `px`, `%`, `rem`, or `vw` in size objects; use `grid_columns` for fractional tracks.',
+          '- Validate unique ids, bidirectional parent/children references, interactions, responsive rules, and acceptance coverage.',
+          '- Put unresolved product decisions in `screen.notes` instead of guessing.',
+          '',
+        ]
+      : [
+          '- Summarize changed or inspected files.',
+          '- List validation commands and results.',
+          '- Report each acceptance id as `pass`, `fail`, or `needs-review` with evidence.',
+          '- Call out every unresolved blocker explicitly.',
+          '',
+          '## Machine-readable implementation report',
+          '',
+          'Fill this template and return it with the implementation. Every node must map to a file and every acceptance result must include evidence.',
+          '',
+          '```json',
+          JSON.stringify(reportTemplate, null, 2),
+          '```',
+          '',
+        ]),
+    ...(taskId === 'author'
+      ? [
+          '## Authoring reference',
+          '',
+          'Use the embedded Blueprint as a canonical shape reference. Replace its product-specific content with the requested screen.',
+          '',
+        ]
+      : []),
+    '<aub_blueprint_context>',
+    '',
+    exportMarkdown(blueprint),
+    '',
+    '</aub_blueprint_context>',
+    '',
+  ];
+
+  return lines.join('\n');
+}
+
+export function supportedAgentAdapters() {
+  return Object.keys(ADAPTERS);
+}
+
+export function supportedAgentTasks() {
+  return Object.keys(TASKS);
+}

package/vendor/aub/scripts/export-agent-prompt.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import {
+  exportAgentPrompt,
+  supportedAgentAdapters,
+  supportedAgentTasks,
+} from './export-agent-prompt.lib.mjs';
+
+export { exportAgentPrompt };
+
+export async function runAgentAdapterCli(defaults = {}) {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args, defaults);
+  if (!options.input) {
+    printUsage();
+    process.exitCode = 2;
+    return;
+  }
+
+  const inputText = options.input === '-'
+    ? await readFile(0, 'utf8')
+    : await readFile(resolve(options.input), 'utf8');
+  const extension = options.input === '-' ? '.json' : extname(options.input).toLowerCase();
+  const blueprint = extension === '.yaml' || extension === '.yml'
+    ? yaml.load(inputText)
+    : JSON.parse(inputText);
+  const prompt = exportAgentPrompt(blueprint, {
+    adapter: options.adapter,
+    task: options.task,
+  });
+
+  if (options.output && options.output !== '-') {
+    await writeFile(resolve(options.output), prompt, 'utf8');
+    console.error(`✓ wrote ${options.output} (${prompt.length} bytes)`);
+  } else {
+    process.stdout.write(prompt);
+  }
+}
+
+function parseArgs(args, defaults) {
+  const positionals = [];
+  const options = {
+    adapter: defaults.adapter ?? 'generic',
+    task: defaults.task ?? 'implement',
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === '--adapter') options.adapter = args[++index];
+    else if (value === '--task') options.task = args[++index];
+    else positionals.push(value);
+  }
+  if (!supportedAgentAdapters().includes(options.adapter)) {
+    throw new Error(`Unsupported adapter "${options.adapter}". Use: ${supportedAgentAdapters().join(', ')}`);
+  }
+  if (!supportedAgentTasks().includes(options.task)) {
+    throw new Error(`Unsupported task "${options.task}". Use: ${supportedAgentTasks().join(', ')}`);
+  }
+  return {
+    ...options,
+    input: positionals[0],
+    output: positionals[1],
+  };
+}
+
+function printUsage() {
+  console.error('Usage: node scripts/export-agent-prompt.mjs <input.ui.json|yaml> [output.md]');
+  console.error('       [--adapter generic|codex|claude-code] [--task author|implement|plan|review]');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runAgentAdapterCli().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/vendor/aub/scripts/export-md.lib.d.mts

@@ -0,0 +1,3 @@
+export type Blueprint = Record<string, any>;
+
+export function exportMarkdown(blueprint: Blueprint): string;