# IBR Universal Tool Definitions
# Source of truth for generating platform-specific integrations
#
# Targets:
#   - Claude Code plugin (default, .claude-plugin/)
#   - MCP server (Cursor, Windsurf, Warp, Codex, Continue)
#   - Cody custom commands (.vscode/cody.json)
#   - Aider conventions (CONVENTIONS.md)

meta:
  name: ibr
  version: "1.4.0"
  description: End-to-end design tool for AI coding agents — guided UI builds, iOS/macOS/web design guidance, Calm Precision principles, visual validation, interaction testing, mockup matching (SSIM), test generation, cross-browser (Chrome + Safari), native scanning, and native macOS layout-fill / gap analysis
  repository: https://github.com/tyroneross/interface-built-right

# Tool definitions
tools:
  # ============================================
  # Core Design Validation Tools
  # ============================================

  - id: ibr_start
    name: Capture Baseline
    description: Capture a baseline before making UI changes (for regression verification)
    category: design-validation
    params:
      - name: url
        type: string
        required: true
        description: URL to capture (or auto-detect dev server if omitted)
      - name: name
        type: string
        required: false
        description: Descriptive name for the session
      - name: viewport
        type: string
        required: false
        default: desktop
        enum: [desktop, mobile, tablet, laptop]
        description: Viewport preset to use
    cli: "npx ibr start {url} --name {name} --viewport {viewport}"
    returns:
      - sessionId: string
      - baselinePath: string
    example: |
      npx ibr start http://localhost:3000/dashboard --name "header-redesign"

  - id: ibr_check
    name: Compare Changes
    description: Compare current page state against baseline (regression check)
    category: design-validation
    params:
      - name: sessionId
        type: string
        required: false
        description: Session ID to check (uses most recent if omitted)
    cli: "npx ibr check {sessionId}"
    returns:
      - verdict: string  # MATCH, EXPECTED_CHANGE, UNEXPECTED_CHANGE, LAYOUT_BROKEN
      - diffPercent: number
      - diffPath: string
    example: |
      npx ibr check sess_abc123

  - id: ibr_update
    name: Update Baseline
    description: Accept current state as new baseline
    category: design-validation
    params:
      - name: sessionId
        type: string
        required: false
        description: Session ID to update
    cli: "npx ibr update {sessionId}"
    example: |
      npx ibr update sess_abc123

  # ============================================
  # UI Audit Tools
  # ============================================

  - id: ibr_audit
    name: Audit UI
    description: Audit a page for UI issues (handlers, accessibility, touch targets, orphan APIs)
    category: audit
    params:
      - name: url
        type: string
        required: true
        description: URL to audit
      - name: rules
        type: string
        required: false
        default: minimal
        description: Rule preset to use
      - name: checkApis
        type: string
        required: false
        description: Directory to cross-reference API calls against
    cli: "npx ibr audit {url} --rules {rules} --check-apis {checkApis}"
    returns:
      - elementsScanned: number
      - errors: number
      - warnings: number
      - violations: array
    example: |
      npx ibr audit http://localhost:3000 --rules minimal --check-apis .

  # ============================================
  # Session Management Tools
  # ============================================

  - id: ibr_list
    name: List Sessions
    description: List all design validation sessions
    category: management
    params: []
    cli: "npx ibr list"
    returns:
      - sessions: array

  - id: ibr_status
    name: Show Pending
    description: Show sessions awaiting comparison
    category: management
    params: []
    cli: "npx ibr status"

  - id: ibr_serve
    name: Open Web UI
    description: Start the comparison viewer web UI
    category: management
    params:
      - name: port
        type: number
        required: false
        default: 4200
    cli: "npx ibr serve --port {port}"

  # ============================================
  # Interactive Session Tools
  # ============================================

  - id: ibr_session_start
    name: Start Interactive Session
    description: Start a persistent browser session for multi-step interactions
    category: interactive
    params:
      - name: url
        type: string
        required: true
      - name: name
        type: string
        required: false
      - name: waitFor
        type: string
        required: false
        description: CSS selector to wait for before ready
      - name: lowMemory
        type: boolean
        required: false
        default: false
        description: Enable low-memory mode for weaker machines
    cli: "npx ibr session:start {url} --name {name} --wait-for {waitFor} {lowMemory ? '--low-memory' : ''}"
    returns:
      - sessionId: string
    example: |
      npx ibr session:start http://localhost:3000 --name "search-test"

  - id: ibr_session_click
    name: Click Element
    description: Click an element in an active session
    category: interactive
    params:
      - name: sessionId
        type: string
        required: true
      - name: selector
        type: string
        required: true
    cli: "npx ibr session:click {sessionId} {selector}"

  - id: ibr_session_type
    name: Type Text
    description: Type text into an element
    category: interactive
    params:
      - name: sessionId
        type: string
        required: true
      - name: selector
        type: string
        required: true
      - name: text
        type: string
        required: true
      - name: submit
        type: boolean
        required: false
        default: false
        description: Press Enter after typing
    cli: "npx ibr session:type {sessionId} {selector} {text} {submit ? '--submit' : ''}"

  - id: ibr_session_screenshot
    name: Take Screenshot
    description: Capture screenshot and audit elements in session
    category: interactive
    params:
      - name: sessionId
        type: string
        required: true
      - name: name
        type: string
        required: false
    cli: "npx ibr session:screenshot {sessionId} --name {name}"
    returns:
      - path: string
      - elementsCount: number
      - issuesCount: number

  - id: ibr_session_wait
    name: Wait For
    description: Wait for a selector or duration
    category: interactive
    params:
      - name: sessionId
        type: string
        required: true
      - name: target
        type: string
        required: true
        description: CSS selector or milliseconds
    cli: "npx ibr session:wait {sessionId} {target}"

  - id: ibr_session_close
    name: Close Session
    description: Close a session or stop browser server
    category: interactive
    params:
      - name: sessionId
        type: string
        required: true
        description: Session ID or "all" to stop browser server
    cli: "npx ibr session:close {sessionId}"

  # ============================================
  # Interaction Testing Tools (v0.7.0)
  # ============================================

  - id: ibr_interact
    name: Interaction Assertions
    description: Click, type, or interact with an element, then verify the result (act→verify→screenshot)
    category: interaction-testing
    params:
      - name: url
        type: string
        required: true
      - name: action
        type: string
        required: true
        description: "Action spec: 'click:button:Submit', 'type:textbox:Search:query'"
      - name: expect
        type: string
        required: false
        description: "Assertion: 'visible:Success', 'hidden:Modal', 'text:Saved', 'count:3'"
      - name: expectScreenshot
        type: string
        required: false
        description: Name for screenshot capture after action
    cli: "npx ibr interact {url} --action '{action}' --expect '{expect}' --expect-screenshot {expectScreenshot}"
    example: |
      npx ibr interact http://localhost:3000 --action 'click:button:Submit' --expect 'visible:Success'

  - id: ibr_test_search
    name: Test Search Flow
    description: Test search functionality using the built-in search flow
    category: interaction-testing
    params:
      - name: url
        type: string
        required: false
      - name: query
        type: string
        required: false
        default: test
      - name: expectCount
        type: number
        required: false
    cli: "npx ibr test-search {url} --query '{query}' --expect-count {expectCount}"

  - id: ibr_test_form
    name: Test Form Flow
    description: Test form submission using the built-in form flow
    category: interaction-testing
    params:
      - name: url
        type: string
        required: false
      - name: fill
        type: string
        required: true
        description: JSON object of field name→value pairs
      - name: submitButton
        type: string
        required: false
    cli: "npx ibr test-form {url} --fill '{fill}' --submit-button '{submitButton}'"

  - id: ibr_test_login
    name: Test Login Flow
    description: Test login using the built-in login flow
    category: interaction-testing
    params:
      - name: url
        type: string
        required: false
      - name: email
        type: string
        required: true
      - name: password
        type: string
        required: true
    cli: "npx ibr test-login {url} --email {email} --password {password}"

  # ============================================
  # Mockup Matching Tools (v0.7.0)
  # ============================================

  - id: ibr_match
    name: Mockup Match
    description: Compare a design mockup PNG against a live page using SSIM + pixelmatch
    category: mockup-matching
    params:
      - name: mockup
        type: string
        required: true
        description: Path to mockup PNG file
      - name: url
        type: string
        required: true
      - name: selector
        type: string
        required: false
        description: CSS selector to crop live page to
      - name: maskDynamic
        type: boolean
        required: false
        description: Auto-mask timestamps, ads, dynamic content
      - name: saveDiff
        type: string
        required: false
        description: Path to save the diff image
    cli: "npx ibr match {mockup} {url} --selector '{selector}' {maskDynamic ? '--mask-dynamic' : ''} --save-diff {saveDiff}"
    returns:
      - ssim: number  # 0.0–1.0
      - verdict: string  # pass, review, fail
      - pixelDiff: number
    example: |
      npx ibr match hero-mockup.png http://localhost:3000 --selector '.hero' --mask-dynamic

  # ============================================
  # Design Verification Tools (v0.7.0)
  # ============================================

  - id: ibr_record_change
    name: Record Design Change
    description: Record a design change specification for later verification
    category: design-verification
    params:
      - name: url
        type: string
        required: false
      - name: element
        type: string
        required: true
        description: Accessible name or CSS selector of the element
      - name: description
        type: string
        required: true
      - name: checks
        type: string
        required: true
        description: JSON array of property checks
    cli: "npx ibr record-change {url} --element '{element}' --description '{description}' --checks '{checks}'"

  - id: ibr_verify_changes
    name: Verify Design Changes
    description: Verify all recorded design changes against the live page
    category: design-verification
    params:
      - name: url
        type: string
        required: false
    cli: "npx ibr verify-changes {url}"
    returns:
      - passed: number
      - failed: number
      - ambiguous: number

  # ============================================
  # Test Automation Tools (v0.7.0)
  # ============================================

  - id: ibr_generate_test
    name: Generate Test
    description: Auto-generate a .ibr-test.json test file from page observation
    category: test-automation
    params:
      - name: url
        type: string
        required: true
      - name: scenario
        type: string
        required: false
        description: Natural language scenario description
      - name: testFile
        type: string
        required: false
        default: .ibr-test.json
    cli: "npx ibr generate-test {url} --scenario '{scenario}' --test-file {testFile}"

  - id: ibr_test
    name: Run Tests
    description: Run declarative .ibr-test.json test file
    category: test-automation
    params:
      - name: file
        type: string
        required: false
        default: .ibr-test.json
    cli: "npx ibr test --file {file}"
    returns:
      - total: number
      - passed: number
      - failed: number

  - id: ibr_run_script
    name: Run Python Script
    description: Execute a Python test script with sandboxed resource limits
    category: test-automation
    params:
      - name: script
        type: string
        required: true
      - name: url
        type: string
        required: false
      - name: timeout
        type: number
        required: false
        default: 60000
    cli: "npx ibr run-script {script} --url {url} --timeout {timeout}"

  - id: ibr_iterate
    name: Iterate
    description: Run one iteration of the test-fix loop and report convergence state
    category: test-automation
    params:
      - name: url
        type: string
        required: true
      - name: test
        type: string
        required: false
        default: .ibr-test.json
      - name: maxIterations
        type: number
        required: false
        default: 7
    cli: "npx ibr iterate {url} --test {test} --max-iterations {maxIterations}"
    returns:
      - finalState: string  # resolved, stagnant, oscillating, regressing, in_progress, budget_exceeded
      - issueCount: number

  # ============================================
  # Cross-Browser Tools (v0.7.0)
  # ============================================

  - id: ibr_compare_browsers
    name: Compare Browsers
    description: Scan in Chrome and Safari, diff screenshots and element counts
    category: cross-browser
    params:
      - name: url
        type: string
        required: true
    cli: "npx ibr compare-browsers {url}"
    returns:
      - chromeElements: number
      - safariElements: number
      - pixelDiff: number

# Prompt templates (referenced by commands/skills)
prompts:
  snapshot_before:
    description: Capture baseline BEFORE making UI changes
    template: |
      Capture a baseline screenshot with IBR before making changes.

      ```bash
      npx ibr start {url} --name "{name}"
      ```

      This creates a session that can be compared after changes.

  compare_after:
    description: Compare AFTER making UI changes
    template: |
      Compare current state against the baseline.

      ```bash
      npx ibr check
      ```

      Interpret the verdict:
      - MATCH - No visual changes
      - EXPECTED_CHANGE - Intentional changes detected
      - UNEXPECTED_CHANGE - Review needed
      - LAYOUT_BROKEN - Fix before continuing

  ui_audit:
    description: Full UI/UX workflow audit
    file: prompts/ui-audit.md

# Platform-specific notes
platforms:
  claude-code:
    notes: |
      Primary target. Plugin already exists at plugin/.claude-plugin/
      Commands are markdown files in plugin/commands/
      Agents are markdown files in plugin/agents/

  mcp:
    notes: |
      MCP server covers: Cursor, Windsurf, Warp, Codex, Continue.dev
      Uses stdio transport (local process)
      Config locations vary by IDE:
        - Cursor: VS Code MCP settings
        - Windsurf: ~/.codeium/windsurf/mcp_config.json
        - Codex: ~/.codex/config.toml
        - Continue: config.json mcpServers section

  cody:
    notes: |
      Sourcegraph Cody uses custom commands in JSON format
      Stored in .vscode/cody.json (workspace) or ~/.vscode/code.json (user)
      Supports modes: ask, edit, insert

  aider:
    notes: |
      Aider uses CONVENTIONS.md or .aider.conf.yml
      Read-only context via --read flag
      No native tool API, just prompt context