aub-workspace 0.3.0

package/vendor/aub/apps/mcp-server/dist/tools/import-design-bridge.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { buildKnownTypes, importDesignBridge, validateBlueprintSemantics, } from '../aub.js';
+import { formatAjvErrors } from '../schema.js';
+import { resolveWorkspacePath } from '../workspace.js';
+export const name = 'import_design_bridge';
+const inputSchema = {
+    path: z
+        .string()
+        .optional()
+        .describe('Path inside the workspace to a Figma/Penpot .aub.bridge.json document.'),
+    bridge: z
+        .record(z.any())
+        .optional()
+        .describe('Inline Design Bridge document instead of a workspace file.'),
+    registry: z
+        .string()
+        .optional()
+        .describe('Optional aub.registry.json path for custom component validation.'),
+};
+export const config = {
+    title: 'Import Design Bridge',
+    description: 'Import a vendor-neutral Figma/Penpot Design Bridge into a validated AUB Blueprint. The bridge must explicitly map every semantic node; this tool does not guess component types.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    if (!args.path && !args.bridge)
+        throw new Error('Provide either "path" or inline "bridge".');
+    if (args.path && args.bridge)
+        throw new Error('Provide only one of "path" or "bridge".');
+    const bridgePath = args.path ? resolveWorkspacePath(ctx.root, args.path) : null;
+    const bridge = bridgePath ? JSON.parse(await readFile(bridgePath, 'utf8')) : args.bridge;
+    const bridgeOk = ctx.validators.validateDesignBridge(bridge);
+    if (!bridgeOk) {
+        throw new Error(`Design Bridge validation failed:\n${formatAjvErrors(ctx.validators.validateDesignBridge)
+            .map((item) => `- ${item}`)
+            .join('\n')}`);
+    }
+    const result = importDesignBridge(bridge);
+    const schemaOk = ctx.validators.validateBlueprint(result.blueprint);
+    const schemaErrors = schemaOk ? [] : formatAjvErrors(ctx.validators.validateBlueprint);
+    const knownTypes = await buildKnownTypes({
+        extensionPath: args.registry ? resolveWorkspacePath(ctx.root, args.registry) : null,
+        startDir: bridgePath ? dirname(bridgePath) : ctx.root,
+    });
+    const semanticErrors = schemaOk
+        ? validateBlueprintSemantics(result.blueprint, { knownTypes: knownTypes.knownTypes })
+        : [];
+    if (!schemaOk || semanticErrors.length > 0) {
+        throw new Error(`Imported Blueprint validation failed:\n${[...schemaErrors, ...semanticErrors]
+            .map((item) => `- ${item}`)
+            .join('\n')}`);
+    }
+    return {
+        source: args.path ?? 'inline',
+        designSource: result.source,
+        extensionRegistry: knownTypes.extensionPath,
+        sourceMap: result.sourceMap,
+        blueprint: result.blueprint,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/list-blueprints.js

@@ -0,0 +1,11 @@
+import { listBlueprints } from '../workspace.js';
+export const name = 'list_blueprints';
+export const config = {
+    title: 'List Blueprints',
+    description: 'Scan the AUB workspace root and return every UI Blueprint file (.ui.json / .ui.yaml) with its screen id, name, and version.',
+    inputSchema: {},
+};
+export async function run(ctx) {
+    const blueprints = await listBlueprints(ctx.root);
+    return { root: ctx.root, count: blueprints.length, blueprints };
+}

package/vendor/aub/apps/mcp-server/dist/tools/list-projects.js

@@ -0,0 +1,11 @@
+import { listProjects } from '../workspace.js';
+export const name = 'list_projects';
+export const config = {
+    title: 'List Projects',
+    description: 'Scan the AUB workspace root and return every multi-screen project file (.aub.project.json / .aub.project.yaml) with its id, name, and screen count.',
+    inputSchema: {},
+};
+export async function run(ctx) {
+    const projects = await listProjects(ctx.root);
+    return { root: ctx.root, count: projects.length, projects };
+}

package/vendor/aub/apps/mcp-server/dist/tools/lock-blueprint.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { resolveBlueprint } from '../workspace.js';
+import { createBlueprintLock } from '../aub.js';
+export const name = 'lock_blueprint';
+const inputSchema = {
+    ref: z.string().optional().describe('Blueprint file path or screen id to lock.'),
+    blueprint: z.record(z.any()).optional().describe('Inline Blueprint object to lock.'),
+};
+export const config = {
+    title: 'Lock Blueprint',
+    description: 'Create a deterministic acceptance lock snapshot with structural SHA-256 hashes. Returns the lock object without writing files.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    let blueprint;
+    let source;
+    if (args.blueprint) {
+        blueprint = args.blueprint;
+        source = 'inline';
+    }
+    else if (args.ref) {
+        const resolved = await resolveBlueprint(ctx.root, args.ref);
+        blueprint = resolved.blueprint;
+        source = resolved.entry.path;
+    }
+    else {
+        throw new Error('Provide either "ref" or "blueprint".');
+    }
+    return {
+        source,
+        lock: createBlueprintLock(blueprint, { sourceFile: source }),
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/migrate-blueprint.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { resolveBlueprint } from '../workspace.js';
+import { migrateBlueprint } from '../aub.js';
+export const name = 'migrate_blueprint';
+const inputSchema = {
+    ref: z.string().optional().describe('Blueprint file path or screen id to migrate.'),
+    blueprint: z.record(z.any()).optional().describe('Inline Blueprint object to migrate.'),
+};
+export const config = {
+    title: 'Migrate Blueprint',
+    description: 'Migrate a v0.1 or v0.2 Blueprint to the current schema version. Returns the migrated object without writing files.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    let blueprint;
+    let source;
+    if (args.blueprint) {
+        blueprint = args.blueprint;
+        source = 'inline';
+    }
+    else if (args.ref) {
+        const resolved = await resolveBlueprint(ctx.root, args.ref);
+        blueprint = resolved.blueprint;
+        source = resolved.entry.path;
+    }
+    else {
+        throw new Error('Provide either "ref" or "blueprint".');
+    }
+    const fromVersion = blueprint.version ?? '0.1.0';
+    const migrated = migrateBlueprint(blueprint);
+    return {
+        source,
+        fromVersion,
+        toVersion: migrated.version,
+        changed: fromVersion !== migrated.version,
+        blueprint: migrated,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/resolve-component.js

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { buildKnownTypes } from '../aub.js';
+export const name = 'resolve_component';
+const inputSchema = {
+    type: z
+        .string()
+        .describe('Core or namespaced component type to resolve, for example button or acme:insight_card.'),
+    registry: z
+        .string()
+        .optional()
+        .describe('Optional path to aub.registry.json. Defaults to auto-discovery from the workspace root.'),
+    implementation: z
+        .string()
+        .optional()
+        .describe('Optional implementation id to select, for example react or angular.'),
+};
+export const config = {
+    title: 'Resolve Component',
+    description: 'Resolve a semantic component type to its container behavior, description, and production implementation mappings. Use this before creating a bespoke component.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    if (!args.type?.trim()) {
+        throw new Error('Provide a component "type".');
+    }
+    const resolved = await buildKnownTypes({
+        extensionPath: args.registry ? resolve(ctx.root, args.registry) : null,
+        startDir: ctx.root,
+    });
+    const metadata = resolved.knownTypes.get(args.type);
+    if (!metadata) {
+        throw new Error(`Unknown component type "${args.type}".`);
+    }
+    const implementations = metadata.implementations ?? [];
+    const selected = args.implementation
+        ? implementations.find((item) => item.id === args.implementation)
+        : undefined;
+    if (args.implementation && !selected) {
+        throw new Error(`Component "${args.type}" has no implementation "${args.implementation}". Available: ${implementations.map((item) => item.id).join(', ') || 'none'}.`);
+    }
+    return {
+        type: args.type,
+        source: metadata.source,
+        isContainer: metadata.isContainer,
+        description: metadata.description ?? '',
+        extensionRegistry: resolved.extensionPath,
+        implementations,
+        selectedImplementation: selected ?? null,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/scaffold-blueprint.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { resolveBlueprint } from '../workspace.js';
+import { scaffoldBlueprint, SCAFFOLD_SECTIONS } from '../aub.js';
+export const name = 'scaffold_blueprint';
+const inputSchema = {
+    ref: z
+        .string()
+        .optional()
+        .describe('Blueprint file path or screen id to load and scaffold.'),
+    blueprint: z
+        .record(z.any())
+        .optional()
+        .describe('Inline Blueprint object to scaffold instead of loading from disk.'),
+    sections: z
+        .array(z.enum(['interactions', 'responsive', 'acceptance']))
+        .optional()
+        .describe('Which spec sections to scaffold. Defaults to all three.'),
+    language: z
+        .enum(['en', 'zh-Hant'])
+        .optional()
+        .describe('Language for generated statements. Defaults to en.'),
+};
+export const config = {
+    title: 'Scaffold Blueprint',
+    description: 'Deterministically derive missing interactions, responsive rules, and acceptance criteria from the existing node tree and viewports. Non-destructive: existing entries are preserved and only missing items are appended. Returns the scaffolded blueprint and a summary of what was added.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    let blueprint;
+    let source;
+    if (args.blueprint) {
+        blueprint = args.blueprint;
+        source = 'inline';
+    }
+    else if (args.ref) {
+        const resolved = await resolveBlueprint(ctx.root, args.ref);
+        blueprint = resolved.blueprint;
+        source = resolved.entry.path;
+    }
+    else {
+        throw new Error('Provide either "ref" or "blueprint".');
+    }
+    const sections = (args.sections ?? SCAFFOLD_SECTIONS);
+    const { blueprint: scaffolded, summary } = scaffoldBlueprint(blueprint, {
+        sections,
+        language: args.language ?? 'en',
+    });
+    return {
+        source,
+        summary,
+        blueprint: scaffolded,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/scan-project-ui.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { scanProjectUi } from '../aub.js';
+export const name = 'scan_project_ui';
+const inputSchema = {
+    namespace: z
+        .string()
+        .optional()
+        .describe('Optional namespace for suggested custom types. Defaults to package/app name, or app.'),
+    limit: z.number().int().positive().optional().describe('Maximum files to scan. Defaults to 2000.'),
+};
+export const config = {
+    title: 'Scan Project UI',
+    description: 'Statically scan React/Next, Vue/Nuxt, and Angular project files for routes and reusable UI components. Writes candidates to .aub/component-candidates.json; it never writes aub.registry.json.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    return scanProjectUi(ctx.root, args ?? {});
+}

package/vendor/aub/apps/mcp-server/dist/tools/submit-report.js

@@ -0,0 +1,48 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { z } from 'zod';
+import { resolveBlueprint } from '../workspace.js';
+import { formatAjvErrors } from '../schema.js';
+import { verifyImplementationReport } from '../aub.js';
+export const name = 'submit_report';
+const inputSchema = {
+    ref: z.string().describe('Blueprint file path or screen id the report targets.'),
+    report: z.record(z.any()).describe('Implementation report object to verify against the Blueprint.'),
+    persist: z
+        .boolean()
+        .optional()
+        .describe('Persist an accepted report under <root>/.aub/reports/. Defaults to true.'),
+};
+export const config = {
+    title: 'Submit Implementation Report',
+    description: 'Validate an implementation report against the report schema and the Blueprint (node mappings + acceptance evidence). Accepted reports are persisted under the workspace.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    const { blueprint, entry } = await resolveBlueprint(ctx.root, args.ref);
+    const report = args.report;
+    const schemaOk = ctx.validators.validateReport(report);
+    const schemaErrors = schemaOk ? [] : formatAjvErrors(ctx.validators.validateReport);
+    const verification = schemaOk
+        ? verifyImplementationReport(blueprint, report)
+        : { ready: false, errors: ['Report failed schema validation; skipped semantic verification.'], summary: undefined };
+    const accepted = schemaOk && verification.ready;
+    let savedPath;
+    if (accepted && args.persist !== false) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const screenId = entry.screenId || 'blueprint';
+        const dir = join(ctx.root, '.aub', 'reports');
+        await mkdir(dir, { recursive: true });
+        const absPath = join(dir, `${screenId}-${timestamp}.json`);
+        await writeFile(absPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+        savedPath = relative(ctx.root, absPath).split(sep).join('/');
+    }
+    return {
+        accepted,
+        screenId: entry.screenId,
+        schemaErrors,
+        errors: verification.errors,
+        summary: verification.summary,
+        savedPath,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/update-aub-session.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { updateAubSession } from '../aub.js';
+export const name = 'update_aub_session';
+const inputSchema = {
+    patch: z.record(z.any()).describe('Partial .aub/session.json content to merge into the current workspace session.'),
+};
+export const config = {
+    title: 'Update AUB Session',
+    description: 'Merge workspace session state into .aub/session.json. Use after the editor saves a Blueprint or updates preview route metadata.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    return updateAubSession(ctx.root, args.patch ?? {});
+}

package/vendor/aub/apps/mcp-server/dist/tools/validate-blueprint.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { resolve } from 'node:path';
+import { resolveBlueprint } from '../workspace.js';
+import { formatAjvErrors } from '../schema.js';
+import { validateBlueprintSemantics, buildKnownTypes } from '../aub.js';
+export const name = 'validate_blueprint';
+const inputSchema = {
+    ref: z
+        .string()
+        .optional()
+        .describe('Blueprint file path or screen id to load and validate.'),
+    blueprint: z
+        .record(z.any())
+        .optional()
+        .describe('Inline Blueprint object to validate instead of loading from disk.'),
+    registry: z
+        .string()
+        .optional()
+        .describe('Path to an aub.registry.json declaring namespaced (team:component) extension types. Defaults to auto-discovery from the workspace root.'),
+};
+export const config = {
+    title: 'Validate Blueprint',
+    description: 'Validate a Blueprint against the JSON Schema and the AUB semantic rules. Namespaced extension component types are resolved from a project aub.registry.json (auto-discovered, or pass "registry"). Provide either a ref or an inline blueprint object.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    let blueprint;
+    let source;
+    if (args.blueprint) {
+        blueprint = args.blueprint;
+        source = 'inline';
+    }
+    else if (args.ref) {
+        const resolved = await resolveBlueprint(ctx.root, args.ref);
+        blueprint = resolved.blueprint;
+        source = resolved.entry.path;
+    }
+    else {
+        throw new Error('Provide either "ref" or "blueprint".');
+    }
+    const schemaOk = ctx.validators.validateBlueprint(blueprint);
+    const schemaErrors = schemaOk ? [] : formatAjvErrors(ctx.validators.validateBlueprint);
+    let knownTypes;
+    let extensionRegistry = null;
+    let registryError = null;
+    try {
+        const resolved = await buildKnownTypes({
+            extensionPath: args.registry ? resolve(ctx.root, args.registry) : null,
+            startDir: ctx.root,
+        });
+        knownTypes = resolved.knownTypes;
+        extensionRegistry = resolved.extensionPath;
+    }
+    catch (err) {
+        registryError = err instanceof Error ? err.message : String(err);
+    }
+    const semanticErrors = schemaOk && !registryError ? validateBlueprintSemantics(blueprint, { knownTypes }) : [];
+    if (registryError)
+        semanticErrors.push(`registry: ${registryError}`);
+    return {
+        source,
+        extensionRegistry,
+        valid: schemaOk && !registryError && semanticErrors.length === 0,
+        schemaErrors,
+        semanticErrors,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/validate-project.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { relative, sep } from 'node:path';
+import { resolveProjectRef } from '../workspace.js';
+import { formatAjvErrors } from '../schema.js';
+import { loadProject, validateProjectSemantics, validateBlueprintSemantics, buildKnownTypes } from '../aub.js';
+export const name = 'validate_project';
+const inputSchema = {
+    ref: z.string().describe('Project file path or project id to load and validate.'),
+};
+export const config = {
+    title: 'Validate Project',
+    description: 'Validate a multi-screen project against the JSON Schema and AUB project semantic rules, then validate every member screen Blueprint (schema + semantics). Returns per-screen results and an overall valid flag.',
+    inputSchema,
+};
+export async function run(ctx, args) {
+    if (!args.ref) {
+        throw new Error('Provide a project "ref" (file path or project id).');
+    }
+    const { projectPath } = await resolveProjectRef(ctx.root, args.ref);
+    const loaded = await loadProject(projectPath);
+    const source = relative(ctx.root, loaded.projectPath).split(sep).join('/');
+    const schemaOk = ctx.validators.validateProject(loaded.project);
+    const schemaErrors = schemaOk ? [] : formatAjvErrors(ctx.validators.validateProject);
+    const semanticErrors = validateProjectSemantics(loaded.project, {
+        screensById: loaded.screensById,
+    });
+    let knownTypes;
+    let registryError = null;
+    try {
+        const resolved = await buildKnownTypes({ extensionPath: null, startDir: ctx.root });
+        knownTypes = resolved.knownTypes;
+    }
+    catch (err) {
+        registryError = err instanceof Error ? err.message : String(err);
+    }
+    const screens = loaded.screens.map((screen) => {
+        if (!screen.blueprint) {
+            return {
+                id: screen.ref?.id ?? '',
+                valid: false,
+                schemaErrors: [`Member blueprint failed to load: ${screen.path}`],
+                semanticErrors: [],
+            };
+        }
+        const memberSchemaOk = ctx.validators.validateBlueprint(screen.blueprint);
+        const memberSchemaErrors = memberSchemaOk
+            ? []
+            : formatAjvErrors(ctx.validators.validateBlueprint);
+        const memberSemanticErrors = memberSchemaOk && !registryError
+            ? validateBlueprintSemantics(screen.blueprint, { knownTypes })
+            : [];
+        if (registryError)
+            memberSemanticErrors.push(`registry: ${registryError}`);
+        return {
+            id: screen.ref?.id ?? '',
+            valid: memberSchemaOk && !registryError && memberSemanticErrors.length === 0,
+            schemaErrors: memberSchemaErrors,
+            semanticErrors: memberSemanticErrors,
+        };
+    });
+    const valid = schemaOk &&
+        schemaErrors.length === 0 &&
+        semanticErrors.length === 0 &&
+        loaded.errors.length === 0 &&
+        screens.every((screen) => screen.valid);
+    return {
+        source,
+        valid,
+        schemaErrors,
+        semanticErrors,
+        screens,
+        loadErrors: loaded.errors,
+    };
+}

package/vendor/aub/apps/mcp-server/dist/tools/write-blueprint.js

@@ -0,0 +1,72 @@
+import { access, mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, extname, relative, sep } from 'node:path';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { buildKnownTypes, validateBlueprintSemantics } from '../aub.js';
+import { formatAjvErrors } from '../schema.js';
+import { resolveWorkspacePath } from '../workspace.js';
+export const name = 'write_blueprint';
+const inputSchema = {
+    path: z
+        .string()
+        .describe('Destination path inside the workspace. Must end in .ui.json, .ui.yaml, or .ui.yml.'),
+    blueprint: z.record(z.any()).describe('Complete Blueprint object to validate and write.'),
+    registry: z
+        .string()
+        .optional()
+        .describe('Optional aub.registry.json path for custom component validation.'),
+    overwrite: z.boolean().optional().describe('Replace an existing file. Defaults to false.'),
+};
+export const config = {
+    title: 'Write Blueprint',
+    description: 'Validate and atomically write a Blueprint inside the workspace. Existing files are protected unless overwrite is true.',
+    inputSchema,
+};
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function run(ctx, args) {
+    if (!args.path || !/\.ui\.(json|ya?ml)$/i.test(args.path)) {
+        throw new Error('Provide a destination "path" ending in .ui.json, .ui.yaml, or .ui.yml.');
+    }
+    if (!args.blueprint)
+        throw new Error('Provide a complete "blueprint" object.');
+    const blueprint = args.blueprint;
+    const schemaOk = ctx.validators.validateBlueprint(blueprint);
+    const schemaErrors = schemaOk ? [] : formatAjvErrors(ctx.validators.validateBlueprint);
+    const knownTypes = await buildKnownTypes({
+        extensionPath: args.registry ? resolveWorkspacePath(ctx.root, args.registry) : null,
+        startDir: ctx.root,
+    });
+    const semanticErrors = schemaOk
+        ? validateBlueprintSemantics(blueprint, { knownTypes: knownTypes.knownTypes })
+        : [];
+    if (!schemaOk || semanticErrors.length > 0) {
+        throw new Error(`Blueprint validation failed:\n${[...schemaErrors, ...semanticErrors].map((item) => `- ${item}`).join('\n')}`);
+    }
+    const outputPath = resolveWorkspacePath(ctx.root, args.path);
+    if (!args.overwrite && (await exists(outputPath))) {
+        throw new Error(`Refusing to overwrite existing file: ${args.path}`);
+    }
+    await mkdir(dirname(outputPath), { recursive: true });
+    const ext = extname(outputPath).toLowerCase();
+    const content = ext === '.yaml' || ext === '.yml'
+        ? yaml.dump(blueprint, { noRefs: true, lineWidth: 120 })
+        : `${JSON.stringify(blueprint, null, 2)}\n`;
+    const tempPath = `${outputPath}.${process.pid}.tmp`;
+    await writeFile(tempPath, content, 'utf8');
+    await rename(tempPath, outputPath);
+    return {
+        savedPath: relative(ctx.root, outputPath).split(sep).join('/'),
+        screenId: blueprint.screen.id,
+        format: ext === '.json' ? 'json' : 'yaml',
+        bytes: Buffer.byteLength(content),
+        extensionRegistry: knownTypes.extensionPath,
+    };
+}