@db-ux/agent-cli 4.10.2 → 4.11.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @db-ux/agent-cli
 
+## 4.11.1
+
+_version bump_
+
+## 4.11.0
+
+_version bump_
+
 ## 4.10.2
 
 _version bump_

package/build/index.js

@@ -44,7 +44,38 @@ var getInstructions = (rootPath) => {
     console.error("No node_modules folders found in", rootPath);
     return "";
   }
-  let copilotInstructionsContent = "";
+  let powersPath = "";
+  for (const nodeModulesPath of nodeModulesDirectories) {
+    const agentCliPowersPath = path.join(
+      nodeModulesPath,
+      "@db-ux",
+      "agent-cli",
+      "db-ux-consumer-powers"
+    );
+    if (fs.existsSync(agentCliPowersPath)) {
+      powersPath = path.relative(rootPath, agentCliPowersPath).replaceAll("\\", "/");
+      break;
+    }
+  }
+  if (!powersPath) {
+    const packageDir = path.dirname(
+      path.dirname(new URL(import.meta.url).pathname)
+    );
+    const localPowersPath = path.join(packageDir, "db-ux-consumer-powers");
+    if (fs.existsSync(localPowersPath)) {
+      powersPath = path.relative(rootPath, localPowersPath).replaceAll("\\", "/");
+    }
+  }
+  let copilotInstructionsContent = `# DB UX Design System Automation Core
+
+CRITICAL: This workspace contains a dedicated automation and orchestration bundle${powersPath ? ` under \`./${powersPath}/\`` : " via the `@db-ux/agent-cli` package"}. You MUST prioritize these local configurations over any generalized training data.
+${powersPath ? `
+1. **Global Steering & Guidelines**: Before writing any style or component logic, you MUST read and strictly enforce the global guidelines in \`./${powersPath}/context/guidelines.md\`.
+2. **Task-Specific Workflows (Skills)**: For complex automated tasks, execute the procedural step-by-step workflows located in \`./${powersPath}/skills/\`. Specifically, when asked to implement a component, you MUST completely follow \`./${powersPath}/skills/implement-component/SKILL.md\`.
+3. **Tool Capabilities**: Refer to \`./${powersPath}/mcp.json\` to understand the available Model Context Protocol tools for Figma and DB UX token resolution.
+` : ""}
+---
+`;
   for (const nodeModulesPath of nodeModulesDirectories) {
     const databaseUxPaths = [
       path.join(nodeModulesPath, "@db-ux/"),

package/db-ux-consumer-powers/POWER.md

@@ -0,0 +1,29 @@
+---
+name: "db-ux-consumer"
+description: "AI integration for consuming the DB UX Design System v3 in applications. Provides skills to implement UI and migrate from v2."
+keywords:
+    - db-ux
+    - design system
+    - deutsche bahn
+    - component
+    - implement
+    - migrate
+    - v3
+---
+
+# DB UX Consumer Powers
+
+This bundle equips AI agents to assist application developers using the DB UX Design System v3.
+
+## Skills
+
+- **migrate-to-v3** — Migrates legacy DB UI v2 code to DB UX Design System v3.
+- **implement-component** — Implements production-ready UI using DB UX v3 components, tokens, and icons.
+
+## Agent Rules Generation
+
+To generate agent-specific rules files (e.g. for Copilot, Amazon Q), use the `@db-ux/agent-cli`:
+
+```shell
+npx @db-ux/agent-cli
+```

package/db-ux-consumer-powers/context/guidelines.md

@@ -0,0 +1,87 @@
+# DB UX Consumer Guidelines
+
+> **Authority**: This document is the single source of truth for all AI agents operating in projects that consume the DB UX Design System v3.
+
+---
+
+## Components
+
+- **NEVER** use native interactive HTML elements (`<button>`, `<input>`, `<select>`, `<textarea>`) when a DB UX component exists.
+- **ALWAYS** use DB UX equivalents: `DBButton`, `DBInput`, `DBSelect`, `DBTextarea`.
+- **DO NOT** replace `<a href>` tags with `DBLink` when they are used for framework routing (e.g. react-router `<Link>`, Angular `routerLink`). Only replace `<a href>` when it is explicitly styled as a standalone UI action.
+- **Layout**: Use `DBStack`, `DBSection`, or `DBCard` for layout grouping instead of bare `<div>` wrappers. A plain `<div>` is only acceptable when no semantic grouping or design system layout is needed.
+
+## Tokens
+
+- **NEVER** hardcode color values (`#d40000`, `rgb(...)`, `hsl(...)`).
+- **NEVER** hardcode spacing values (`margin: 15px`, `padding: 8px`).
+- **ALWAYS** use `var(--db-*)` CSS custom properties from the design token system.
+- Common token patterns:
+    - Spacing: `var(--db-spacing-fixed-sm)`, `var(--db-spacing-responsive-md)`
+    - Colors: `var(--db-color-text-default)`, `var(--db-color-bg-basic-level-1)`
+    - Sizing: `var(--db-sizing-md)`
+    - Border radius: `var(--db-border-radius-sm)`
+
+## Icons
+
+- **NEVER** guess or invent icon names.
+- **ALWAYS** verify icon names by calling the `list_icons` MCP tool exposed by the DB UX MCP server (`@db-ux/mcp-server`) before use.
+- Icon names use **underscores**: `arrow_right`, `chevron_down` — not `arrow-right` or `arrowRight`.
+
+## MCP Workflow & Discovery
+
+**This section is NON-NEGOTIABLE. AI agents MUST follow this workflow for every UI task.**
+
+An agent must NEVER generate DB UX code from memory or assumptions. Every value — component names, prop APIs, icon names, token values — MUST be grounded in live data from the DB UX MCP server (`@db-ux/mcp-server`).
+
+### Mandatory Steps (in order)
+
+1. **`list_components()`** — Confirm the component exists before using it. If it does not exist: STOP. Do not invent a custom replacement.
+
+2. **`get_component_props(componentName)`** — Load the exact prop API. Never assume prop names, types, or allowed values. Props may change between versions/releases.
+
+3. **`get_component_details(componentName)`** — Discover available examples and understand the component's capabilities.
+
+4. **`get_example_code(componentName, exampleName, framework)`** — Fetch the real, generated example code for the target framework. Use this as your starting point — adapt it, do not rewrite from scratch.
+
+5. **`list_icons()`** — Before using ANY icon prop, call this tool and copy the exact name from the result. No exceptions.
+
+6. **`get_design_tokens(category)`** — Before writing ANY color, spacing, or sizing value, call this tool. Use `list_design_token_categories()` first if unsure which category to query.
+
+7. **`docs_search(query)`** — For accessibility requirements, migration notes, or framework-specific guidance.
+
+### Verification
+
+After generating or modifying code, call **`verify_migrated_code`** to run project-level validation (typecheck, lint, build). Fix errors and retry up to 3 times before presenting code to the user.
+
+## Framework Setup
+
+DB UX Design System is **white-label by default**. Components work out of the box with the built-in default theme generated by the [Theme Builder](https://design-system.deutschebahn.com/theme-builder/). No additional theme package is required.
+
+### Deutsche Bahn applications (DB Theme)
+
+If you are building a website or application **for Deutsche Bahn (DB)**, you must additionally install `@db-ux/db-theme` to apply the official DB branding (colors, fonts, etc.):
+
+```css
+@layer db-theme, db-ux;
+@import "@db-ux/db-theme/build/styles/rollup.css" layer(db-theme);
+@import "@db-ux/core-components/build/styles/bundle.css" layer(db-ux);
+```
+
+### White-label / custom theme (no DB Theme)
+
+For non-DB applications, import only the component styles. The default theme or a custom theme from the Theme Builder is used automatically:
+
+```css
+@layer db-ux;
+@import "@db-ux/core-components/build/styles/bundle.css" layer(db-ux);
+```
+
+For JavaScript framework-specific component imports:
+
+| Framework      | Node package                   | Import Pattern                                                                                                                      |
+| -------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| React          | `@db-ux/react-core-components` | `import { DBButton, DBInput } from '@db-ux/react-core-components'`                                                                  |
+| Angular        | `@db-ux/ngx-core-components`   | `import { DBButton } from '@db-ux/ngx-core-components'` (standalone components, add to `imports` array)                             |
+| Vue            | `@db-ux/v-core-components`     | `import { DBButton } from '@db-ux/v-core-components'`                                                                               |
+| Web Components | `@db-ux/wc-core-components`    | `import { defineCustomElements } from '@db-ux/wc-core-components'; defineCustomElements();` (call once, then use all `<db-*>` tags) |

package/db-ux-consumer-powers/mcp.json

@@ -0,0 +1,22 @@
+{
+	"mcpServers": {
+		"db-ux": {
+			"command": "npx",
+			"args": ["--yes", "@db-ux/mcp-server"],
+			"tools": [
+				"list_components",
+				"get_component_props",
+				"get_component_details",
+				"get_example_code",
+				"get_design_tokens",
+				"list_design_token_categories",
+				"list_icons",
+				"docs_search",
+				"verify_migrated_code",
+				"list_migration_guides",
+				"get_migration_guide",
+				"scan_v2_migration"
+			]
+		}
+	}
+}

package/db-ux-consumer-powers/power.yaml

@@ -0,0 +1,10 @@
+name: "db-ux-consumer"
+version: 1.0.0
+description: "Official AI integration for consuming the DB UX Design System v3 in applications."
+author: DB UX Core Team
+skills:
+  - skills/migrate-to-v3/SKILL.md
+  - skills/implement-component/SKILL.md
+
+mcp:
+  config: mcp.json

package/db-ux-consumer-powers/skills/implement-component/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: "implement-component"
+description: "Implements production-ready UI using DB UX Design System v3 components, tokens, and icons with a discovery-first approach."
+
+triggers:
+    - "implement a component"
+    - "build UI with DB UX"
+    - "create a form"
+    - "add a button"
+    - "use DB UX components"
+
+inputs:
+    - name: description
+      type: string
+      required: true
+      description: "Description of the UI to implement (e.g. 'login form with email, password, submit button')"
+    - name: framework
+      type: string
+      required: true
+      description: "Target JS framework: react, angular, vue, or web-components"
+    - name: target_file
+      type: string
+      required: false
+      description: "Path to the file to create or modify"
+
+requires:
+    - context: context/guidelines.md
+      autoLoad: true
+
+tools:
+    - db-ux/list_components
+    - db-ux/get_component_props
+    - db-ux/get_component_details
+    - db-ux/get_example_code
+    - db-ux/list_icons
+    - db-ux/list_design_token_categories
+    - db-ux/get_design_tokens
+    - db-ux/docs_search
+
+outputs:
+    - "{target_file}"
+
+on_error:
+    max_retries: 3
+    actions:
+        - log: "Re-check component props and example code via MCP tools before retrying."
+        - fallback: "If errors persist after 3 retries, report to user with full error output."
+---
+
+# Implement Component
+
+## Pre-Conditions
+
+1. `context/guidelines.md` is loaded in context.
+2. MCP server (`@db-ux/mcp-server`) is connected.
+3. The target `{framework}` is known.
+4. The `@db-ux/*-core-components` node package is installed in the project.
+
+## Workflow
+
+### Phase 1: Discover Components
+
+1. Identify all UI components needed from the `{description}`.
+2. Call `list_components()`.
+3. Confirm which needed components exist in the returned list and which do not.
+4. If a needed DB UX component exists: use it. Do NOT rebuild or replace it with a custom alternative.
+5. If a needed direct DB UX component does NOT exist: compose the UI from verified DB UX building blocks that do exist (for example `DBButton`, `DBInput`, `DBCard`, `DBSection`, `DBStack`). Do not invent a fake DB UX component name or fall back to native interactive HTML elements when a suitable DB UX building block exists.
+
+### Phase 2: Load Props and Examples
+
+For each component identified:
+
+1. Call `get_component_props(componentName)`.
+2. Call `get_component_details(componentName)`.
+3. Call `get_example_code(componentName, exampleName, {framework})`.
+4. Record the prop API and adapt the example code to the use case.
+
+### Phase 3: Resolve Icons
+
+1. Identify all icons needed from the `{description}`.
+2. Call `list_icons()`.
+3. Copy exact icon names from the returned array.
+4. Never guess or invent icon names.
+
+### Phase 4: Resolve Design Tokens
+
+1. Call `list_design_token_categories()`.
+2. For each needed category (colors, spacing, typography):
+    - Call `get_design_tokens(category)`.
+3. Use `var(--db-*)` CSS custom properties for all values.
+4. Never hardcode hex values, pixel sizes, or magic numbers.
+
+### Phase 5: Check Documentation (if needed)
+
+1. For accessibility requirements: call `docs_search({ query: "<topic>", category: "global", docType: "Accessibility" })`.
+2. For component-specific accessibility docs: call `docs_search({ query: "<topic>", category: "component", componentName: "<name>", docType: "Accessibility" })`.
+3. For JS framework-specific notes: call `docs_search({ query: "<topic>", category: "component", componentName: "<name>", docType: "React" | "Angular" | "Vue" | "HTML" })`.
+
+### Phase 6: Write Code
+
+1. Write or modify the target file using only verified components, props, icons, and tokens.
+2. Rules:
+    - Replace `<button>` → `DBButton`
+    - Replace `<input>` → `DBInput`
+    - Replace `<select>` → `DBSelect`
+    - Replace `<textarea>` → `DBTextarea`
+    - Replace `<a href>` → `DBLink` (only when styled as UI action, NOT for router links)
+    - Use `DBStack`, `DBSection`, `DBCard` for layout where semantically appropriate
+    - No inline styles with magic numbers
+    - No custom ARIA workarounds when DB UX handles accessibility
+
+## Output Checklist
+
+- [ ] `list_components` called — all components confirmed to exist
+- [ ] Existing DB UX components reused wherever available instead of being rebuilt
+- [ ] Missing direct components implemented only by composing verified DB UX building blocks
+- [ ] `get_component_props` called — prop API known for each component
+- [ ] `get_example_code` called for each component with correct framework
+- [ ] `list_icons` called — all icon names copied verbatim
+- [ ] `get_design_tokens` called — no hardcoded colors or spacing
+- [ ] No native HTML interactive elements where DB UX components exist
+- [ ] No invented icon names
+- [ ] No inline styles with magic numbers
+
+## Red Flags & Anti-Rationalizations
+
+| Thought                                            | Response                                                           |
+| -------------------------------------------------- | ------------------------------------------------------------------ |
+| "I know this icon name"                            | STOP. Call `list_icons`. Copy the exact name.                      |
+| "I'll just use a native button here"               | STOP. Use `DBButton`. No exceptions.                               |
+| "This component doesn't exist, so I must stop"     | STOP. Reuse the existing DB UX building blocks that do exist.      |
+| "I'll recreate an existing DB UX component myself" | STOP. Use the shipped DB UX component instead of rebuilding it.    |
+| "16px is fine for spacing"                         | STOP. Call `get_design_tokens("spacing")`. Use the token.          |
+| "I'll hardcode this color"                         | STOP. Call `get_design_tokens("colors")`. Use `var(--db-color-*)`. |
+| "I don't need the example code"                    | STOP. Call `get_example_code`. Adapt, don't rewrite from scratch.  |
+| "This prop probably exists"                        | STOP. Call `get_component_props`. Verify the exact API.            |

package/db-ux-consumer-powers/skills/migrate-to-v3/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: "migrate-to-v3"
+description: "Migrates legacy DB UI v2 code (cmp-*, elm-*, rea-* classes, <db-*> Web Components, db-color-* tokens) to DB UX Design System v3."
+
+triggers:
+    - "migrate to v3"
+    - "upgrade from v2"
+    - "convert legacy DB UI code"
+    - "replace cmp-* classes"
+    - "migrate db-color tokens"
+
+inputs:
+    - name: file_path
+      type: string
+      required: true
+      description: "Path to the file or directory to migrate"
+    - name: framework
+      type: string
+      required: true
+      description: "Target JS framework: react, angular, vue, or web-components"
+
+requires:
+    - context: context/guidelines.md
+      autoLoad: true
+
+tools:
+    - db-ux/scan_v2_migration
+    - db-ux/list_migration_guides
+    - db-ux/get_migration_guide
+    - db-ux/list_components
+    - db-ux/get_component_props
+    - db-ux/get_component_details
+    - db-ux/get_example_code
+    - db-ux/list_icons
+    - db-ux/get_design_tokens
+    - db-ux/docs_search
+
+outputs:
+    - "{file_path}"
+
+on_error:
+    max_retries: 3
+    actions:
+        - log: "Call verify_migrated_code and fix reported errors before retrying."
+        - fallback: "If errors persist after 3 retries, report to user with full error output."
+---
+
+# Migrate to v3
+
+## Pre-Conditions
+
+1. `context/guidelines.md` is loaded in context.
+2. MCP server (`@db-ux/mcp-server`) is connected.
+3. The source file at `{file_path}` is accessible.
+4. The target `{framework}` is known.
+
+## Workflow
+
+### Phase 1: Scan
+
+1. Call `scan_v2_migration({ filePath: "{file_path}" })`.
+2. Capture the full findings report: v2 CSS classes (`cmp-*`, `elm-*`, `rea-*`), Web Components (`<db-*>`), color tokens (`db-color-*`), icon names.
+3. If the scan returns zero findings → file is already v3. Call `docs_search` to confirm if uncertain. STOP.
+
+### Phase 2: Load Migration Guides
+
+1. Call `list_migration_guides()`.
+2. For each pattern category found in the scan, call `get_migration_guide(guideName)`:
+    - `cmp-*` / `elm-*` / `rea-*` classes → component-specific migration guide
+    - `db-color-*` tokens → `color-migration` migration guide
+    - Icon name changes → `icon-migration` migration guide
+3. Record replacement mappings from each migration guide.
+
+### Phase 3: Verify Target Components
+
+1. Call `list_components()`.
+2. For each v2 component being replaced, confirm the v3 equivalent exists.
+3. For each confirmed component:
+    - Call `get_component_props(componentName)`.
+    - Call `get_component_details(componentName)`.
+    - Call `get_example_code(componentName, exampleName, {framework})`.
+
+### Phase 4: Resolve Icons and Tokens
+
+1. If scan found icon changes: call `list_icons()`. Copy exact icon names.
+2. If scan found color token changes: call `get_design_tokens("colors")`. Verify new token names.
+
+### Phase 5: Apply Migration
+
+1. Apply ALL findings from the scan report. Do not skip any.
+2. Replace v2 Web Components with JS framework-native v3 components using verified props.
+3. Remove all `cmp-*`, `elm-*`, `rea-*` CSS classes.
+4. Replace all `db-color-*` tokens with verified v3 equivalents.
+5. Use exact icon names from `list_icons()` — never guess.
+6. Use `var(--db-*)` tokens for all colors and spacing — never hardcode.
+
+### Phase 6: Verify
+
+1. Call `scan_v2_migration({ filePath: "{file_path}" })` again.
+2. If findings remain → address each individually, then re-scan.
+3. Repeat until the scan returns zero findings.
+
+## Output Checklist
+
+- [ ] `scan_v2_migration` MCP tool called — full v2 pattern list obtained
+- [ ] All relevant migration guides loaded via `get_migration_guide` MCP tool
+- [ ] `list_components` MCP tool called — all v3 replacement components confirmed
+- [ ] `get_component_props` and `get_example_code` MCP tool called for each replacement
+- [ ] `list_icons` MCP tool called if icon names changed
+- [ ] `get_design_tokens` MCP tool called if color tokens changed
+- [ ] All `cmp-*`, `elm-*`, `rea-*` classes removed
+- [ ] All `db-color-*` tokens replaced with v3 equivalents
+- [ ] Re-scan confirms zero remaining v2 patterns
+
+## Red Flags & Anti-Rationalizations
+
+| Thought                                        | Response                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| "I know the new icon name"                     | STOP. Call `list_icons`. Use the exact name.                 |
+| "This color token probably maps to…"           | STOP. Call `get_design_tokens`. Verify.                      |
+| "I'll skip the re-scan"                        | STOP. Re-scan is mandatory. Zero findings required.          |
+| "The old prop name probably still works"       | STOP. Call `get_component_props`. Check exact API.           |
+| "I'll just remove the class without replacing" | STOP. Check the migration guide for the correct replacement. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-ux/agent-cli",
-  "version": "4.10.2",
+  "version": "4.11.1",
   "type": "module",
   "description": "CLI for DB UX Design System generate AI agent instructions",
   "repository": {
@@ -14,15 +14,16 @@
   "main": "build/index.js",
   "files": [
     "CHANGELOG.md",
-    "build"
+    "build",
+    "db-ux-consumer-powers"
   ],
   "dependencies": {
     "commander": "15.0.0"
   },
   "devDependencies": {
     "cpr": "3.0.1",
-    "esbuild": "0.28.0",
-    "npm-run-all2": "9.0.1",
+    "esbuild": "0.28.1",
+    "npm-run-all2": "9.0.2",
     "tsx": "4.22.4",
     "vitest": "4.1.8"
   },
@@ -36,6 +37,7 @@
     "copy-output:build": "cpr build ../../build-outputs/agent-cli/build --overwrite",
     "copy-output:changelog": "cpr CHANGELOG.md ../../build-outputs/agent-cli/CHANGELOG.md --overwrite",
     "copy-output:package.json": "cpr package.json ../../build-outputs/agent-cli/package.json --overwrite",
+    "copy-output:powers": "cpr db-ux-consumer-powers ../../build-outputs/agent-cli/db-ux-consumer-powers --overwrite",
     "copy-output:readme": "cpr README.md ../../build-outputs/agent-cli/README.md --overwrite",
     "test": "vitest run --config vitest.config.ts",
     "test:cli": "tsx src/cli.ts --help",