aub-workspace 0.3.0

package/vendor/aub/apps/mcp-server/dist/workspace.js

@@ -0,0 +1,138 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import yaml from 'js-yaml';
+import { parseProjectText } from './aub.js';
+const IGNORED_DIRS = new Set(['node_modules', 'dist', '.git', '.aub', '.pnpm-store']);
+const BLUEPRINT_PATTERN = /\.ui\.(json|ya?ml)$/i;
+export const PROJECT_PATTERN = /\.aub\.project\.(json|ya?ml)$/i;
+export function resolveWorkspacePath(root, filePath) {
+    const absRoot = resolve(root);
+    const absPath = resolve(absRoot, filePath);
+    const rel = relative(absRoot, absPath);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`Path must stay inside the workspace root: ${filePath}`);
+    }
+    return absPath;
+}
+function isYaml(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return ext === '.yaml' || ext === '.yml';
+}
+export function parseBlueprintText(text, filePath) {
+    const document = isYaml(filePath) ? yaml.load(text) : JSON.parse(text);
+    if (!document || typeof document !== 'object') {
+        throw new Error(`File does not contain a Blueprint object: ${filePath}`);
+    }
+    return document;
+}
+export async function readBlueprintFile(absPath) {
+    const text = await readFile(absPath, 'utf8');
+    return parseBlueprintText(text, absPath);
+}
+function toEntry(root, absPath, blueprint) {
+    return {
+        path: relative(root, absPath).split(sep).join('/'),
+        absPath,
+        screenId: blueprint?.screen?.id ?? '',
+        screenName: blueprint?.screen?.name ?? '',
+        version: blueprint?.version ?? '',
+    };
+}
+async function walk(dir, out, pattern) {
+    let dirents;
+    try {
+        dirents = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const dirent of dirents) {
+        const full = join(dir, dirent.name);
+        if (dirent.isDirectory()) {
+            if (IGNORED_DIRS.has(dirent.name) || dirent.name.startsWith('.'))
+                continue;
+            await walk(full, out, pattern);
+        }
+        else if (dirent.isFile() && pattern.test(dirent.name)) {
+            out.push(full);
+        }
+    }
+}
+export async function listBlueprints(root) {
+    const files = [];
+    await walk(root, files, BLUEPRINT_PATTERN);
+    const entries = [];
+    for (const absPath of files.sort()) {
+        try {
+            const blueprint = await readBlueprintFile(absPath);
+            entries.push(toEntry(root, absPath, blueprint));
+        }
+        catch {
+            // Skip files that fail to parse; validate_blueprint surfaces details on demand.
+        }
+    }
+    return entries;
+}
+// Resolve a ref that is either a file path (absolute or relative to root) or a screen id.
+export async function resolveBlueprint(root, ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('A blueprint ref (file path or screen id) is required.');
+    const candidate = isAbsolute(trimmed) ? trimmed : resolve(root, trimmed);
+    if (BLUEPRINT_PATTERN.test(trimmed) || existsSync(candidate)) {
+        if (!existsSync(candidate)) {
+            throw new Error(`Blueprint file not found: ${trimmed}`);
+        }
+        const blueprint = await readBlueprintFile(candidate);
+        return { blueprint, entry: toEntry(root, candidate, blueprint) };
+    }
+    const entries = await listBlueprints(root);
+    const match = entries.find((entry) => entry.screenId === trimmed);
+    if (!match) {
+        throw new Error(`No blueprint found for ref "${ref}" (not a file path and no matching screen id).`);
+    }
+    const blueprint = await readBlueprintFile(match.absPath);
+    return { blueprint, entry: match };
+}
+export async function listProjects(root) {
+    const files = [];
+    await walk(root, files, PROJECT_PATTERN);
+    const entries = [];
+    for (const absPath of files.sort()) {
+        try {
+            const text = await readFile(absPath, 'utf8');
+            const project = parseProjectText(text, absPath);
+            entries.push({
+                path: relative(root, absPath).split(sep).join('/'),
+                absPath,
+                id: project?.id ?? '',
+                name: project?.name ?? '',
+                screenCount: Array.isArray(project?.screens) ? project.screens.length : 0,
+            });
+        }
+        catch {
+            // Skip files that fail to parse; validate_project surfaces details on demand.
+        }
+    }
+    return entries;
+}
+// Resolve a ref that is either a project file path (absolute or relative to root) or a project id.
+export async function resolveProjectRef(root, ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('A project ref (file path or project id) is required.');
+    const candidate = isAbsolute(trimmed) ? trimmed : resolve(root, trimmed);
+    if (PROJECT_PATTERN.test(trimmed) || existsSync(candidate)) {
+        if (!existsSync(candidate)) {
+            throw new Error(`Project file not found: ${trimmed}`);
+        }
+        return { projectPath: candidate };
+    }
+    const entries = await listProjects(root);
+    const match = entries.find((entry) => entry.id === trimmed);
+    if (!match) {
+        throw new Error(`No project found for ref "${ref}" (not a file path and no matching project id).`);
+    }
+    return { projectPath: match.absPath };
+}

package/vendor/aub/docs/agent-handoff.md

@@ -0,0 +1,85 @@
+# AUB Agent Handoff Guide
+
+This guide is for coding agents that receive an AUB UI Blueprint or an `.aub.zip` handoff package.
+
+> 繁體中文版：[`agent-handoff.zh-Hant.md`](./agent-handoff.zh-Hant.md)
+
+## Explain AUB to the user
+
+AUB is a visual UI contract between a person and a coding agent. The user arranges a screen in the AUB editor, then exports structured layout, component semantics, interactions, responsive behavior, screenshots, and verifiable acceptance criteria.
+
+In your first response:
+
+1. Reply in the user's language.
+2. Explain that AUB describes what the interface must do and how it will be verified.
+3. List the AUB files and supporting evidence you found.
+4. State whether you will author, plan, implement, or review.
+5. Identify unresolved product decisions. Ask only when the repository and supplied evidence cannot resolve them.
+
+## Recognize the inputs
+
+An AUB handoff package can contain:
+
+| File | Purpose | Authority |
+|---|---|---|
+| `*.ui.json` | Complete machine-readable UI contract | **Source of truth** |
+| `*.ui.md` | Human- and agent-readable rendering of the Blueprint | Derived reference |
+| `screenshots/*.png` | Visual evidence for each viewport | Supporting reference |
+| `*.agent.md` | Agent-neutral task prompt | Execution instructions |
+| `*.codex.md` | Codex-specific task prompt | Execution instructions |
+| `implementation-report.template.json` | Required node and acceptance report | Completion contract |
+| `implementation-report.schema.json` | Schema for the completed report | Validation contract |
+| `manifest.json` | Package metadata, hashes, and entrypoint | Integrity metadata |
+
+If files conflict, follow this precedence:
+
+1. Valid `*.ui.json`
+2. Explicit repository constraints
+3. Acceptance criteria and responsive rules in the Blueprint
+4. Generated `*.ui.md`
+5. Screenshots
+6. Prose outside the package
+
+Do not silently resolve a conflict. Explain it and propose a concrete resolution.
+
+## Choose the task
+
+- **Author**: Convert product requirements or an existing screen into one schema-valid Blueprint.
+- **Plan**: Map Blueprint nodes and acceptance ids to the target repository without editing files.
+- **Implement**: Change the target repository until the Blueprint and every acceptance item are satisfied.
+- **Review**: Compare an existing implementation with the Blueprint and report mismatches by severity.
+
+## Required workflow
+
+1. Read the target repository's instructions, including applicable `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
+2. Inspect existing routes, components, design tokens, dependencies, tests, and implementation patterns.
+3. Validate the Blueprint before relying on it.
+4. Map every Blueprint node id to an existing or new implementation component.
+   When `aub.registry.json` declares a matching production implementation, reuse its module,
+   export, source, and prop mappings before considering a new component.
+5. Preserve hierarchy, semantic component type, layout mode, viewport geometry, interactions, responsive rules, states, and constraints.
+6. Use repository-native components and tokens when they satisfy the contract.
+7. Run checks that cover every changed surface.
+8. Complete the implementation report with a file mapping and evidence for every acceptance id.
+
+## Non-negotiable rules
+
+- Treat `*.ui.json` as the source of truth. Markdown and screenshots do not override it.
+- Do not redesign the screen, weaken acceptance criteria, or replace declared behavior with a preferred pattern.
+- Do not invent missing product behavior. Record uncertainty and ask the user when it materially affects the result.
+- Do not change `auto` layout to `freeform`, or the reverse, unless the Blueprint or an approved conflict resolution requires it.
+- Preserve accessible names, focus behavior, minimum target sizes, and responsive overflow constraints.
+- Report blockers explicitly. Partial completion must not be presented as complete.
+
+## Completion response
+
+Reply in the user's language and include:
+
+1. What was implemented or reviewed.
+2. Files changed or inspected.
+3. Validation commands and exact results.
+4. Every acceptance id with `pass`, `fail`, or `needs-review` and concrete evidence.
+5. Unresolved decisions, conflicts, or blockers.
+6. The completed `implementation-report.json` when the task is implementation or review.
+
+An implementation is complete only when the report maps every node, every required acceptance item passes with evidence, and no unresolved blocker remains.

package/vendor/aub/docs/agent-handoff.zh-Hant.md

@@ -0,0 +1,85 @@
+# AUB Agent 交付指南
+
+本指南提供給收到 AUB UI Blueprint 或 `.aub.zip` 交付包的編碼 Agent。
+
+> English version: [`agent-handoff.md`](./agent-handoff.md)
+
+## 先向使用者說明 AUB
+
+AUB 是使用者與編碼 Agent 之間的視覺 UI 合約。使用者在 AUB 編輯器中安排畫面，再匯出結構化的版面、元件語意、互動、響應式行為、畫面截圖與可驗證的驗收條件。
+
+第一次回覆時：
+
+1. 使用使用者目前使用的語言。
+2. 說明 AUB 定義了介面應該做什麼，以及最後如何驗收。
+3. 列出找到的 AUB 檔案與輔助證據。
+4. 說明這次要執行生成、規劃、實作或審查。
+5. 指出尚未決定的產品問題。只有 repository 與既有證據都無法回答時才詢問使用者。
+
+## 辨識輸入內容
+
+AUB 交付包可能包含：
+
+| 檔案 | 用途 | 權威性 |
+|---|---|---|
+| `*.ui.json` | 完整且可由機器讀取的 UI 合約 | **唯一真實來源** |
+| `*.ui.md` | Blueprint 的人類與 Agent 可讀版本 | 衍生參考 |
+| `screenshots/*.png` | 各 viewport 的視覺證據 | 輔助參考 |
+| `*.agent.md` | Agent 中立的任務提示 | 執行指示 |
+| `*.codex.md` | Codex 專用任務提示 | 執行指示 |
+| `implementation-report.template.json` | 必填的節點與驗收報告 | 完成契約 |
+| `implementation-report.schema.json` | 完成報告使用的 schema | 驗證契約 |
+| `manifest.json` | 交付包 metadata、雜湊與入口 | 完整性資料 |
+
+若檔案彼此衝突，依以下順序判定：
+
+1. 通過驗證的 `*.ui.json`
+2. Repository 的明確限制
+3. Blueprint 內的驗收條件與響應式規則
+4. 自動產生的 `*.ui.md`
+5. 截圖
+6. 交付包外的文字描述
+
+不得默默自行處理衝突。必須向使用者說明，並提出具體解法。
+
+## 選擇任務
+
+- **生成**：把產品需求或既有畫面轉成一份通過 schema 驗證的 Blueprint。
+- **規劃**：把 Blueprint 節點與 acceptance id 對應到目標 repository，不修改檔案。
+- **實作**：修改目標 repository，直到符合 Blueprint 與所有驗收條件。
+- **審查**：比較既有實作與 Blueprint，依嚴重程度回報不一致之處。
+
+## 必須遵守的流程
+
+1. 讀取目標 repository 的規則，包括適用的 `AGENTS.md`、`CLAUDE.md` 與 `.github/copilot-instructions.md`。
+2. 檢查既有 route、元件、design token、依賴、測試與實作慣例。
+3. 驗證 Blueprint 後才能依賴其內容。
+4. 將每個 Blueprint node id 對應到既有或新建的實作元件。
+   若 `aub.registry.json` 宣告了符合的 production implementation，必須先重用其中的
+   module、export、source 與 prop mapping，再考慮新建元件。
+5. 保留階層、語意元件類型、layout mode、各 viewport 幾何、互動、響應式規則、狀態與限制。
+6. 只要符合合約，應優先使用 repository 既有元件與 token。
+7. 執行涵蓋所有修改面的檢查。
+8. 完成 implementation report，提供每個節點的檔案對應，以及每個 acceptance id 的證據。
+
+## 不可妥協的規則
+
+- `*.ui.json` 是唯一真實來源；Markdown 與截圖不得覆蓋它。
+- 不得自行重新設計、降低驗收條件，或用偏好的模式取代已宣告的行為。
+- 不得猜測缺少的產品行為。應記錄不確定性；若會實質影響結果，再詢問使用者。
+- 除非 Blueprint 或使用者核准的衝突解法要求，不得任意互換 `auto` 與 `freeform` layout。
+- 必須保留 accessible name、focus 行為、最小操作尺寸與響應式 overflow 限制。
+- 必須明確回報阻塞。部分完成不得宣稱為全部完成。
+
+## 完成時的回覆
+
+使用使用者的語言回覆，並包含：
+
+1. 已實作或已審查的內容。
+2. 修改或檢查過的檔案。
+3. 驗證命令與精確結果。
+4. 每個 acceptance id 的 `pass`、`fail` 或 `needs-review`，以及具體證據。
+5. 尚未解決的決策、衝突或阻塞。
+6. 若任務是實作或審查，附上完成的 `implementation-report.json`。
+
+只有在報告已對應所有節點、所有必要驗收條件都有通過證據，且沒有未解決阻塞時，才能視為完成。

package/vendor/aub/docs/template-authoring-agent.md

@@ -0,0 +1,86 @@
+# Template Authoring for Existing Projects
+
+This guide is for coding agents that scan an existing application and produce
+AUB workspace templates.
+
+## Contract
+
+Agents must treat AUB as a semantic contract system, not a screenshot copier.
+When scanning an app:
+
+1. Inspect routes, layouts, reusable components, design tokens, and project
+   conventions before generating a template.
+2. Use core AUB component types when the meaning is clear.
+3. Put project-specific components in `.aub/component-candidates.json`.
+4. Never write a scanned component directly into `aub.registry.json`.
+5. Generate `.aub/templates/<slug>.aub.template.json` with source references,
+   confidence, and `status: "candidate"` unless a human has already approved it.
+
+## Workspace Template Shape
+
+```json
+{
+  "format": "aub-workspace-template",
+  "format_version": "0.1.0",
+  "id": "settings",
+  "name": "Settings",
+  "category": "workspace",
+  "framework": "react",
+  "source": {
+    "kind": "route",
+    "path": "src/pages/settings.tsx",
+    "route": "/settings"
+  },
+  "blueprint": {
+    "version": "0.3.0"
+  },
+  "registryRefs": ["app:settings_panel"],
+  "confidence": 0.72,
+  "status": "candidate"
+}
+```
+
+The embedded `blueprint` must be a complete, schema-valid `.ui.json` document.
+
+## Component Candidates
+
+Scanned custom components belong in `.aub/component-candidates.json`:
+
+```json
+{
+  "format": "aub-component-candidates",
+  "format_version": "0.1.0",
+  "candidates": [{
+    "id": "src-components-insight-card-insight_card",
+    "status": "candidate",
+    "sourcePath": "src/components/InsightCard.tsx",
+    "framework": "react",
+    "componentName": "InsightCard",
+    "suggestedType": "app:insight_card",
+    "suggestedCoreType": "card",
+    "isContainer": true,
+    "props": ["title"],
+    "usageCount": 3,
+    "confidence": 0.72,
+    "reason": "Static scan found a reusable project component."
+  }]
+}
+```
+
+Users review each candidate in the editor:
+
+- **Map core** records that the project component should be represented by an
+  existing AUB core type.
+- **Create extension** writes a namespaced component entry to `aub.registry.json`.
+- **Ignore** leaves the component out of the registry.
+
+## MCP Workflow
+
+1. `scan_project_ui` writes `.aub/component-candidates.json`.
+2. `generate_template_from_source` writes a candidate workspace template.
+3. The user opens the template in the AUB editor and reviews component
+   candidates.
+4. The editor saves the reviewed Blueprint with `write_blueprint` and updates
+   `.aub/session.json` with `update_aub_session`.
+5. The implementation agent reads `get_aub_session`, `get_blueprint`, and
+   `resolve_component` before changing production code.

package/vendor/aub/schema/aub-ci.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://henrylau1103.github.io/AUB/schema/aub-ci.schema.json",
+  "title": "AUB CI Configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": "1.0.0" },
+    "blueprints": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "projects": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "reports": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["blueprint", "report"],
+        "properties": {
+          "blueprint": { "type": "string", "minLength": 1 },
+          "report": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/vendor/aub/schema/aub.registry.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://henrylau1103.github.io/AUB/schema/aub.registry.schema.json",
+  "title": "AUB Extension Component Registry",
+  "description": "Project-level registry of namespaced (team:component) custom component types and their production implementation mappings. Resolved by AUB validation and bundled into agent handoffs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["components"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": {
+      "type": "string",
+      "description": "Optional registry document version (SemVer recommended)."
+    },
+    "description": { "type": "string" },
+    "components": {
+      "type": "array",
+      "description": "Custom component type declarations.",
+      "items": { "$ref": "#/$defs/extensionComponent" }
+    }
+  },
+  "$defs": {
+    "extensionComponent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "isContainer"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*:[a-z][a-z0-9_]*$",
+          "description": "Namespaced type, team:component (e.g. acme:data_card). Must not collide with a core type."
+        },
+        "isContainer": {
+          "type": "boolean",
+          "description": "true if the component may declare children; false for a leaf."
+        },
+        "description": {
+          "type": "string",
+          "description": "What the component is — agents read this to resolve the type without guessing."
+        },
+        "implementations": {
+          "type": "array",
+          "description": "Production component mappings. Agents should reuse these implementations instead of recreating the component.",
+          "items": { "$ref": "#/$defs/componentImplementation" },
+          "minItems": 1
+        }
+      }
+    },
+    "componentImplementation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "framework", "module"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "description": "Stable mapping id, for example react or angular."
+        },
+        "framework": {
+          "enum": ["react", "vue", "angular", "svelte", "web-component", "html", "other"]
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Package or module specifier used by the target repository."
+        },
+        "export": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Exported component symbol. Omit for a default export or custom element."
+        },
+        "importStyle": {
+          "enum": ["named", "default", "namespace", "side-effect", "custom-element"],
+          "default": "named"
+        },
+        "sourcePath": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional repository-relative source file for code navigation."
+        },
+        "storybookUrl": {
+          "type": "string",
+          "format": "uri"
+        },
+        "docsUrl": {
+          "type": "string",
+          "format": "uri"
+        },
+        "props": {
+          "type": "object",
+          "description": "Map production prop names to Blueprint data paths.",
+          "propertyNames": {
+            "pattern": "^[A-Za-z_$][A-Za-z0-9_$.-]*$"
+          },
+          "additionalProperties": { "$ref": "#/$defs/propMapping" }
+        },
+        "notes": {
+          "type": "string",
+          "description": "Implementation constraints that the coding agent must preserve."
+        }
+      }
+    },
+    "propMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Blueprint data path such as content.title, bindings.value, states.loading, or literal:compact."
+        },
+        "required": { "type": "boolean" },
+        "description": { "type": "string" }
+      }
+    }
+  }
+}

package/vendor/aub/schema/design-bridge.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/HenryLau1103/AUB/schema/1.0.0/design-bridge.schema.json",
+  "title": "AUB Design Bridge",
+  "description": "Vendor-neutral envelope for moving an explicitly authored semantic UI Blueprint from Figma or Penpot into AUB without inferring component meaning.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "version", "source", "blueprint", "node_map"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "format": { "const": "aub-design-bridge" },
+    "version": { "const": "1.0.0" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "document_id", "frame_id"],
+      "properties": {
+        "kind": { "type": "string", "enum": ["figma", "penpot"] },
+        "document_id": { "type": "string", "minLength": 1 },
+        "page_id": { "type": "string", "minLength": 1 },
+        "frame_id": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "format": "uri" },
+        "exported_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "blueprint": {
+      "$ref": "https://github.com/HenryLau1103/AUB/schema/0.3.0/ui-blueprint.schema.json"
+    },
+    "node_map": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source_id"],
+        "properties": {
+          "source_id": { "type": "string", "minLength": 1 },
+          "source_name": { "type": "string" },
+          "component_key": { "type": "string" }
+        }
+      }
+    }
+  }
+}