aub-workspace 0.3.0

package/vendor/aub/scripts/check-editor-bundle-budget.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+const repoRoot = resolve(import.meta.dirname, '..');
+const assetsDir = resolve(repoRoot, 'apps/editor/dist/assets');
+const maxChunkBytes = Number(process.env.AUB_EDITOR_MAX_CHUNK_BYTES ?? 500 * 1024);
+
+const entries = await readdir(assetsDir, { withFileTypes: true });
+const jsChunks = [];
+
+for (const entry of entries) {
+  if (!entry.isFile() || !entry.name.endsWith('.js')) continue;
+  const path = join(assetsDir, entry.name);
+  const info = await stat(path);
+  jsChunks.push({ path, bytes: info.size });
+}
+
+const offenders = jsChunks
+  .filter((chunk) => chunk.bytes > maxChunkBytes)
+  .sort((a, b) => b.bytes - a.bytes);
+
+if (offenders.length > 0) {
+  const limit = formatBytes(maxChunkBytes);
+  const details = offenders
+    .map((chunk) => `- ${relative(repoRoot, chunk.path)}: ${formatBytes(chunk.bytes)} > ${limit}`)
+    .join('\n');
+  throw new Error(`Editor bundle budget exceeded:\n${details}`);
+}
+
+console.log(`Editor bundle budget ok: ${jsChunks.length} JS chunks, max ${formatBytes(maxChunkBytes)}.`);
+
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
+  return `${(bytes / 1024).toFixed(1)} KiB`;
+}

package/vendor/aub/scripts/ci-verify.lib.mjs

@@ -0,0 +1,256 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import yaml from 'js-yaml';
+import { buildKnownTypes } from './registry.lib.mjs';
+import { validateBlueprintSemantics } from './validate-blueprint.lib.mjs';
+import { loadProject, validateProjectSemantics } from './project.lib.mjs';
+import { verifyImplementationReport } from './implementation-report.lib.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export async function verifyWorkspace({
+  workspace = process.cwd(),
+  configPath = '.aub/ci.json',
+  requireReports = false,
+} = {}) {
+  const root = resolve(workspace);
+  const absoluteConfig = resolve(root, configPath);
+  const validators = await loadValidators();
+  const failures = [];
+  const checks = [];
+  let config;
+
+  if (existsSync(absoluteConfig)) {
+    config = JSON.parse(await readFile(absoluteConfig, 'utf8'));
+    if (!validators.validateConfig(config)) {
+      for (const error of formatAjvErrors(validators.validateConfig)) {
+        failures.push({ path: relativePath(root, absoluteConfig), message: `CI config: ${error}` });
+      }
+      return summarize({ root, configPath, checks, failures });
+    }
+  } else {
+    const discovered = await discoverAubFiles(root);
+    config = {
+      version: '1.0.0',
+      blueprints: discovered.blueprints,
+      projects: discovered.projects,
+      reports: [],
+    };
+  }
+
+  const blueprintRefs = config.blueprints ?? [];
+  const projectRefs = config.projects ?? [];
+  const reportRefs = config.reports ?? [];
+  const reportTargets = new Set(reportRefs.map((entry) => normalizeRef(entry.blueprint)));
+
+  if (blueprintRefs.length === 0 && projectRefs.length === 0) {
+    failures.push({ path: configPath, message: 'No Blueprint or project files were configured or discovered.' });
+  }
+
+  for (const ref of blueprintRefs) {
+    const result = await verifyBlueprintFile(root, ref, validators);
+    checks.push(result);
+    failures.push(...result.failures);
+    if (requireReports && !reportTargets.has(normalizeRef(ref))) {
+      failures.push({ path: ref, message: 'No implementation report is configured for this Blueprint.' });
+    }
+  }
+
+  for (const ref of projectRefs) {
+    const result = await verifyProjectFile(root, ref, validators);
+    checks.push(result);
+    failures.push(...result.failures);
+  }
+
+  for (const entry of reportRefs) {
+    const result = await verifyReportFile(root, entry, validators);
+    checks.push(result);
+    failures.push(...result.failures);
+  }
+
+  return summarize({ root, configPath: existsSync(absoluteConfig) ? configPath : null, checks, failures });
+}
+
+async function loadValidators() {
+  const [blueprint, project, report, config] = await Promise.all([
+    readJson(join(ROOT, 'schema', 'ui-blueprint.schema.json')),
+    readJson(join(ROOT, 'schema', 'ui-project.schema.json')),
+    readJson(join(ROOT, 'schema', 'implementation-report.schema.json')),
+    readJson(join(ROOT, 'schema', 'aub-ci.schema.json')),
+  ]);
+  const ajv = new Ajv2020({ allErrors: true, strict: true });
+  addFormats(ajv);
+  return {
+    validateBlueprint: ajv.compile(blueprint),
+    validateProject: ajv.compile(project),
+    validateReport: ajv.compile(report),
+    validateConfig: ajv.compile(config),
+  };
+}
+
+async function verifyBlueprintFile(root, ref, validators) {
+  const path = resolveRef(root, ref);
+  const failures = [];
+  try {
+    const blueprint = await readDocument(path);
+    const schemaOk = validators.validateBlueprint(blueprint);
+    if (!schemaOk) {
+      for (const error of formatAjvErrors(validators.validateBlueprint)) {
+        failures.push({ path: ref, message: `Blueprint schema: ${error}` });
+      }
+    } else {
+      try {
+        const { knownTypes } = await buildKnownTypes({ startDir: dirname(path) });
+        for (const error of validateBlueprintSemantics(blueprint, { knownTypes })) {
+          failures.push({ path: ref, message: `Blueprint semantics: ${error}` });
+        }
+      } catch (error) {
+        failures.push({ path: ref, message: `Component registry: ${error.message}` });
+      }
+    }
+  } catch (error) {
+    failures.push({ path: ref, message: error.message });
+  }
+  return { kind: 'blueprint', path: ref, passed: failures.length === 0, failures };
+}
+
+async function verifyProjectFile(root, ref, validators) {
+  const path = resolveRef(root, ref);
+  const failures = [];
+  try {
+    const loaded = await loadProject(path);
+    if (!validators.validateProject(loaded.project)) {
+      for (const error of formatAjvErrors(validators.validateProject)) {
+        failures.push({ path: ref, message: `Project schema: ${error}` });
+      }
+    }
+    for (const error of validateProjectSemantics(loaded.project, { screensById: loaded.screensById })) {
+      failures.push({ path: ref, message: `Project semantics: ${error}` });
+    }
+    for (const error of loaded.errors) failures.push({ path: ref, message: error });
+    for (const screen of loaded.screens) {
+      if (!screen.blueprint) continue;
+      const screenRef = relativePath(root, screen.path);
+      if (!validators.validateBlueprint(screen.blueprint)) {
+        for (const error of formatAjvErrors(validators.validateBlueprint)) {
+          failures.push({ path: screenRef, message: `Blueprint schema: ${error}` });
+        }
+        continue;
+      }
+      try {
+        const { knownTypes } = await buildKnownTypes({ startDir: dirname(screen.path) });
+        for (const error of validateBlueprintSemantics(screen.blueprint, { knownTypes })) {
+          failures.push({ path: screenRef, message: `Blueprint semantics: ${error}` });
+        }
+      } catch (error) {
+        failures.push({ path: screenRef, message: `Component registry: ${error.message}` });
+      }
+    }
+  } catch (error) {
+    failures.push({ path: ref, message: error.message });
+  }
+  return { kind: 'project', path: ref, passed: failures.length === 0, failures };
+}
+
+async function verifyReportFile(root, entry, validators) {
+  const failures = [];
+  try {
+    const [blueprint, report] = await Promise.all([
+      readDocument(resolveRef(root, entry.blueprint)),
+      readJson(resolveRef(root, entry.report)),
+    ]);
+    if (!validators.validateReport(report)) {
+      for (const error of formatAjvErrors(validators.validateReport)) {
+        failures.push({ path: entry.report, message: `Report schema: ${error}` });
+      }
+    } else {
+      const result = verifyImplementationReport(blueprint, report);
+      for (const error of result.errors) {
+        failures.push({ path: entry.report, message: `Implementation report: ${error}` });
+      }
+    }
+  } catch (error) {
+    failures.push({ path: entry.report, message: error.message });
+  }
+  return {
+    kind: 'report',
+    path: entry.report,
+    blueprint: entry.blueprint,
+    passed: failures.length === 0,
+    failures,
+  };
+}
+
+async function discoverAubFiles(root) {
+  const blueprints = [];
+  const projects = [];
+  await walk(root, async (path) => {
+    const rel = relativePath(root, path);
+    if (/\.aub\.project\.(json|ya?ml)$/i.test(path)) projects.push(rel);
+    else if (/\.ui\.(json|ya?ml)$/i.test(path)) blueprints.push(rel);
+  });
+  return { blueprints: blueprints.sort(), projects: projects.sort() };
+}
+
+async function walk(dir, visit) {
+  const { readdir } = await import('node:fs/promises');
+  const ignored = new Set(['node_modules', 'dist', '.git', '.pnpm-store', '_site']);
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') && entry.name !== '.aub') continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignored.has(entry.name)) await walk(path, visit);
+    } else if (entry.isFile()) {
+      await visit(path);
+    }
+  }
+}
+
+function summarize({ root, configPath, checks, failures }) {
+  return {
+    valid: failures.length === 0,
+    workspace: root,
+    configPath,
+    summary: {
+      checks: checks.length,
+      passed: checks.filter((check) => check.passed).length,
+      failed: checks.filter((check) => !check.passed).length,
+      failures: failures.length,
+    },
+    checks,
+    failures,
+  };
+}
+
+function resolveRef(root, ref) {
+  return isAbsolute(ref) ? ref : resolve(root, ref);
+}
+
+function normalizeRef(ref) {
+  return ref.replaceAll('\\', '/').replace(/^\.\//, '');
+}
+
+function relativePath(root, path) {
+  return relative(root, path).split(sep).join('/');
+}
+
+function formatAjvErrors(validate) {
+  return (validate.errors ?? []).map((error) => {
+    const path = error.instancePath || '(root)';
+    return `${path} ${error.message ?? 'invalid'}`;
+  });
+}
+
+async function readDocument(path) {
+  const text = await readFile(path, 'utf8');
+  const extension = extname(path).toLowerCase();
+  return extension === '.yaml' || extension === '.yml' ? yaml.load(text) : JSON.parse(text);
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}

package/vendor/aub/scripts/ci-verify.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { appendFile } from 'node:fs/promises';
+import { verifyWorkspace } from './ci-verify.lib.mjs';
+
+const args = process.argv.slice(2);
+const workspace = valueAfter(args, '--workspace') ?? process.cwd();
+const configPath = valueAfter(args, '--config') ?? '.aub/ci.json';
+const requireReports = args.includes('--require-reports');
+
+const result = await verifyWorkspace({ workspace, configPath, requireReports });
+
+for (const check of result.checks) {
+  console.log(`${check.passed ? '✓' : '✗'} ${check.kind}: ${check.path}`);
+}
+for (const failure of result.failures) {
+  console.error(`  ${failure.path}: ${failure.message}`);
+  if (process.env.GITHUB_ACTIONS === 'true') {
+    console.error(`::error file=${failure.path}::${escapeAnnotation(failure.message)}`);
+  }
+}
+console.log(
+  `AUB CI: ${result.summary.passed}/${result.summary.checks} checks passed, ${result.summary.failures} failure(s).`
+);
+
+if (process.env.GITHUB_STEP_SUMMARY) {
+  const rows = result.checks
+    .map((check) => `| ${check.passed ? 'Pass' : 'Fail'} | ${check.kind} | \`${check.path}\` |`)
+    .join('\n');
+  await appendFile(
+    process.env.GITHUB_STEP_SUMMARY,
+    `## AUB contract verification\n\n| Status | Check | File |\n|---|---|---|\n${rows || '| Fail | configuration | No checks found |'}\n\n**${result.summary.failures} failure(s)**\n`
+  );
+}
+
+process.exit(result.valid ? 0 : 1);
+
+function valueAfter(argv, flag) {
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+function escapeAnnotation(value) {
+  return value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+}

package/vendor/aub/scripts/create-authoring-kit.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import JSZip from 'jszip';
+import { migrateBlueprint } from './migrate-blueprint.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const outputPath = resolve(process.argv[2] || 'aub-authoring-kit.zip');
+const schema = JSON.parse(await readFile(resolve(root, 'schema/ui-blueprint.schema.json'), 'utf8'));
+const registry = JSON.parse(await readFile(resolve(root, 'schema/registry/components.json'), 'utf8'));
+const example = migrateBlueprint(JSON.parse(await readFile(resolve(root, 'examples/dashboard.ui.json'), 'utf8')));
+const files = {
+  'AUTHORING.md': authoringGuide(),
+  'ui-blueprint.schema.json': `${JSON.stringify(schema, null, 2)}\n`,
+  'components.json': `${JSON.stringify(registry, null, 2)}\n`,
+  'examples/canonical.ui.json': `${JSON.stringify(example, null, 2)}\n`,
+  'prompts/author.md': authorPrompt(),
+  'VALIDATE.md': validationGuide(),
+};
+const zip = new JSZip();
+const manifestFiles = {};
+for (const [path, content] of Object.entries(files)) {
+  const bytes = Buffer.from(content);
+  manifestFiles[path] = { sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.byteLength };
+  zip.file(path, content);
+}
+zip.file('manifest.json', `${JSON.stringify({
+  format: 'aub-authoring-kit',
+  format_version: '1.0.0',
+  blueprint_version: schema.properties.version.enum.at(-1),
+  files: manifestFiles,
+}, null, 2)}\n`);
+await writeFile(outputPath, await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }));
+console.error(`✓ wrote ${outputPath}`);
+
+export function authoringGuide() {
+  return `# AUB Blueprint Authoring
+
+Produce a single JSON document that validates against \`ui-blueprint.schema.json\`.
+
+## Rules
+
+1. Use only component types declared in \`components.json\`.
+2. Create exactly one root node with \`parent_id: null\`.
+3. Keep every \`parent_id\` and \`children\` relationship bidirectionally consistent.
+4. Read \`isContainer\` from \`components.json\`. Types with \`isContainer: false\` are leaves and MUST use \`children: []\`; represent labels and icons through \`content\`, not child nodes.
+5. Use \`layout.mode: auto\` for flex/grid flow and \`freeform\` only when exact placements are known.
+6. Size units are limited to \`px\`, \`%\`, \`rem\`, and \`vw\`. Never use \`fr\` in a size object; use \`grid_columns\` for fractional tracks.
+7. Declare interactions, responsive behavior, and at least five acceptance criteria.
+8. Include layout, interaction, responsive, and accessibility acceptance categories.
+9. Never invent uncertain product behavior. Put unresolved decisions in \`screen.notes\`.
+10. Before returning, verify leaf children, allowed units, unique ids, references, and acceptance coverage.
+11. Return JSON only when the caller requests a machine-readable Blueprint.
+`;
+}
+
+export function authorPrompt() {
+  return `Create an AUB UI Blueprint from the supplied UI requirements.
+
+Read AUTHORING.md, components.json, the JSON Schema, and the canonical example first.
+Return a complete JSON object. Do not use unregistered component types.
+Do not omit parent/children links, responsive rules, interactions, or acceptance criteria.
+Use children only on registry types where isContainer is true. Every leaf must have children: [].
+Use only px, %, rem, or vw size units; express fractional grids with grid_columns.
+When source material is ambiguous, preserve the ambiguity in screen.notes instead of guessing.
+Perform a final schema checklist before returning, then validate with the documented command.
+`;
+}
+
+export function validationGuide() {
+  return `# Validation
+
+From the AUB repository:
+
+\`\`\`bash
+pnpm validate path/to/screen.ui.json
+\`\`\`
+
+The command must exit with status 0. Fix schema and semantic errors before handoff.
+`;
+}

package/vendor/aub/scripts/create-implementation-report.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { createImplementationReportTemplate } from './implementation-report.lib.mjs';
+
+const [inputPath, outputPath] = process.argv.slice(2);
+if (!inputPath) {
+  console.error('Usage: node scripts/create-implementation-report.mjs <blueprint.ui.json|yaml> [report.json]');
+  process.exit(2);
+}
+
+const text = await readFile(resolve(inputPath), 'utf8');
+const extension = extname(inputPath).toLowerCase();
+const blueprint = extension === '.yaml' || extension === '.yml' ? yaml.load(text) : JSON.parse(text);
+const output = `${JSON.stringify(createImplementationReportTemplate(blueprint), null, 2)}\n`;
+
+if (outputPath && outputPath !== '-') {
+  await writeFile(resolve(outputPath), output, 'utf8');
+  console.error(`✓ wrote ${outputPath}`);
+} else {
+  process.stdout.write(output);
+}

package/vendor/aub/scripts/design-bridge.lib.d.mts

@@ -0,0 +1,32 @@
+import type { Blueprint } from '../schema/types.js';
+
+export interface DesignBridgeSource {
+  kind: 'figma' | 'penpot';
+  document_id: string;
+  page_id?: string;
+  frame_id: string;
+  url?: string;
+  exported_at?: string;
+}
+
+export interface DesignBridgeDocument {
+  format: 'aub-design-bridge';
+  version: '1.0.0';
+  source: DesignBridgeSource;
+  blueprint: Blueprint;
+  node_map: Record<
+    string,
+    {
+      source_id: string;
+      source_name?: string;
+      component_key?: string;
+    }
+  >;
+}
+
+export const DESIGN_BRIDGE_VERSION: '1.0.0';
+export function importDesignBridge(input: DesignBridgeDocument): {
+  blueprint: Blueprint;
+  source: DesignBridgeSource;
+  sourceMap: DesignBridgeDocument['node_map'];
+};

package/vendor/aub/scripts/design-bridge.lib.mjs

@@ -0,0 +1,69 @@
+export const DESIGN_BRIDGE_VERSION = '1.0.0';
+
+export function importDesignBridge(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Design Bridge input must be an object.');
+  }
+  if (input.format !== 'aub-design-bridge' || input.version !== DESIGN_BRIDGE_VERSION) {
+    throw new Error(`Design Bridge must declare format "aub-design-bridge" and version "${DESIGN_BRIDGE_VERSION}".`);
+  }
+  if (!['figma', 'penpot'].includes(input.source?.kind)) {
+    throw new Error('Design Bridge source.kind must be "figma" or "penpot".');
+  }
+  if (!input.blueprint || typeof input.blueprint !== 'object' || Array.isArray(input.blueprint)) {
+    throw new Error('Design Bridge must contain a complete blueprint object.');
+  }
+  if (!input.node_map || typeof input.node_map !== 'object' || Array.isArray(input.node_map)) {
+    throw new Error('Design Bridge must contain a node_map object.');
+  }
+
+  const blueprint = structuredClone(input.blueprint);
+  const nodes = Array.isArray(blueprint.nodes) ? blueprint.nodes : [];
+  const nodeIds = new Set(nodes.map((node) => node?.id).filter(Boolean));
+  const mappedIds = new Set(Object.keys(input.node_map));
+  const missing = [...nodeIds].filter((id) => !mappedIds.has(id));
+  const unknown = [...mappedIds].filter((id) => !nodeIds.has(id));
+  if (missing.length > 0 || unknown.length > 0) {
+    const details = [
+      missing.length > 0 ? `missing node mappings: ${missing.join(', ')}` : '',
+      unknown.length > 0 ? `unknown mapped nodes: ${unknown.join(', ')}` : '',
+    ].filter(Boolean);
+    throw new Error(`Design Bridge node_map must exactly cover blueprint nodes (${details.join('; ')}).`);
+  }
+
+  const sourceFile =
+    input.source.url ??
+    `${input.source.kind}://${input.source.document_id}/${input.source.page_id ?? 'page'}/${input.source.frame_id}`;
+  const sourceMap = {};
+  blueprint.nodes = nodes.map((node) => {
+    const mapping = input.node_map[node.id];
+    if (!mapping?.source_id) {
+      throw new Error(`Design Bridge node_map.${node.id}.source_id is required.`);
+    }
+    sourceMap[node.id] = {
+      source_id: mapping.source_id,
+      ...(mapping.source_name ? { source_name: mapping.source_name } : {}),
+      ...(mapping.component_key ? { component_key: mapping.component_key } : {}),
+    };
+    return {
+      ...node,
+      source: {
+        file: sourceFile,
+        selector: mapping.source_id,
+      },
+    };
+  });
+  blueprint.provenance = {
+    source_kind: input.source.kind,
+    framework: input.source.kind === 'figma' ? 'Figma' : 'Penpot',
+    importer_version: DESIGN_BRIDGE_VERSION,
+    entry_file: input.source.frame_id,
+    source_files: [sourceFile],
+  };
+
+  return {
+    blueprint,
+    source: structuredClone(input.source),
+    sourceMap,
+  };
+}

package/vendor/aub/scripts/diff-blueprint.lib.d.mts

@@ -0,0 +1,18 @@
+export interface BlueprintDiff {
+  before: { version: string; screen_id: string; screen_name: string };
+  after: { version: string; screen_id: string; screen_name: string };
+  summary: Record<string, number>;
+  screen_changes: string[];
+  nodes: Record<string, any[]>;
+  interactions: Record<string, any[]>;
+  responsive: Record<string, any[]>;
+  acceptance: Record<string, any[]>;
+  viewports: Record<string, any[]>;
+  design_system_changes: string[];
+}
+
+export function diffBlueprints(
+  before: Record<string, any>,
+  after: Record<string, any>
+): BlueprintDiff;
+export function renderBlueprintDiff(diff: BlueprintDiff): string;