@zibby/skills 0.1.8 → 0.1.9

package/docs/integrations/jira.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+title: Jira Integration
+---
+
+# Jira Integration
+
+Connect your Jira workspace to sync tickets into Zibby for analysis and test generation.
+
+## How It Works
+
+Zibby uses OAuth 2.0 to connect to your Atlassian/Jira account. Once connected, it syncs tickets from your selected Jira project and keeps them up to date.
+
+## Connect Jira
+
+1. Go to your project's **Settings** page in the Zibby dashboard
+2. Under **Integrations**, click **Connect Jira**
+3. You'll be redirected to Atlassian to authorize Zibby
+4. Grant access to your Jira workspace
+5. You'll be redirected back to Zibby
+
+## Select a Jira Space
+
+After connecting:
+
+1. Go to **Settings > Jira Configuration**
+2. Select the Jira project/space to sync (e.g., "SCRUM", "ENG")
+3. Zibby will import all tickets from that space
+
+## Synced Data
+
+For each ticket, Zibby imports:
+
+- **Summary** and **Description** (including Atlassian Document Format)
+- **Issue type** (Story, Bug, Task, etc.)
+- **Priority** (High, Medium, Low)
+- **Labels** and **Components**
+- **Acceptance criteria** (from description)
+
+## Ticket Management
+
+In the **Tickets** page:
+
+- Tickets sync automatically when you visit the page
+- Drag and drop to reorder tickets by priority
+- Click a ticket to view full details and run analysis
+- Ticket order is preserved across sessions
+
+## Reconnecting
+
+Jira tokens expire periodically. If you see a "Please reconnect Jira" message:
+
+1. Go to **Settings > Integrations**
+2. Click **Reconnect** next to Jira
+3. Re-authorize through the Atlassian OAuth flow
+
+Your existing tickets and their order are preserved after reconnecting.
+
+## Troubleshooting
+
+**"Token refresh failed" error**
+
+Your Jira refresh token has expired. Go to Settings and reconnect Jira. This won't affect your existing ticket data or analysis results.
+
+**Tickets not syncing**
+
+Make sure the correct Jira space is selected in Settings. Only tickets from the selected space are displayed.
+
+**Duplicate tickets after reconnecting**
+
+This shouldn't happen — Zibby matches tickets by their Jira key (e.g., SCRUM-123) and updates existing records rather than creating duplicates.

package/docs/intro.md

@@ -0,0 +1,87 @@
+---
+slug: /
+sidebar_position: 1
+title: Introduction
+---
+
+# Zibby
+
+Zibby is an AI-powered test automation platform. Write plain-text test instructions, and Zibby drives a real browser, records video, and generates Playwright scripts — no manual test code required.
+
+## Quick Start
+
+```bash
+npm install -g @zibby/cli
+echo "Go to example.com and verify the page title" > test.txt
+zibby test test.txt --agent cursor
+```
+
+That's it. No `zibby init` required — the CLI uses a built-in workflow by default.
+
+## How It Works
+
+```
+Plain Text Spec → AI Agent → Browser Automation → Video + Playwright Script
+```
+
+1. **Write a test spec** — plain text describing what to test
+2. **Run it** — `zibby test spec.txt` launches an AI agent (Cursor, Claude, or Codex)
+3. **AI drives the browser** — navigates, clicks, fills forms, asserts results
+4. **Get artifacts** — video recording, action timeline, generated Playwright script
+5. **Upload to cloud** (optional) — review results in the [Zibby dashboard](https://zibby.app)
+
+## Architecture
+
+Zibby is a monorepo with five published npm packages, each with a distinct responsibility:
+
+| Package | Version | Description |
+|---|---|---|
+| [`@zibby/cli`](https://www.npmjs.com/package/@zibby/cli) | 0.1.27 | CLI entry point — the `zibby` command. Orchestrates runs, init, login, uploads, and workflow management. |
+| [`@zibby/core`](https://www.npmjs.com/package/@zibby/core) | 0.1.22 | Core engine — workflow graph runtime, agent strategy framework, graph compiler, state management, and template workflows. |
+| [`@zibby/skills`](https://www.npmjs.com/package/@zibby/skills) | 0.1.4 | Skill catalog — built-in skill definitions (Browser, Jira, GitHub, Slack, Memory) plus the `skill()` factory for custom MCP and function skills. |
+| [`@zibby/memory`](https://www.npmjs.com/package/@zibby/memory) | 0.1.4 | Test memory database — version-controlled (Dolt-backed) knowledge base that learns from every run. Stores selectors, page models, navigation patterns, and insights. |
+| [`@zibby/mcp-browser`](https://www.npmjs.com/package/@zibby/mcp-browser) | 0.1.6 | Browser MCP server — wrapper around `@playwright/mcp` with stable ID injection, event recording, and session-aware video capture. |
+
+Users only install `@zibby/cli` — it pulls in the others automatically.
+
+## Two Modes
+
+### Local Mode (no account needed)
+
+Run tests locally, get generated Playwright scripts:
+
+```bash
+zibby test test-specs/login.txt --agent cursor
+```
+
+### Cloud Mode (with Zibby account)
+
+Upload results to the dashboard for video replay, team sharing, and CI integration:
+
+```bash
+zibby test test-specs/login.txt --agent cursor --sync
+```
+
+## Supported AI Agents
+
+Zibby's workflow engine is **agent-agnostic** — the same workflow graph runs identically across all three supported agents:
+
+| Agent | Provider | How It Works | Setup |
+|---|---|---|---|
+| **Cursor** | Cursor IDE | Uses Cursor's built-in agent with MCP tool access | Install [Cursor](https://cursor.com) or set `CURSOR_API_KEY` |
+| **Claude** | Anthropic | Uses Claude Agent SDK with native MCP integration | Set `ANTHROPIC_API_KEY` in `.env` |
+| **Codex** | OpenAI | Uses Codex SDK with full tool/file/bash access | Install `@openai/codex` CLI + set `OPENAI_API_KEY` |
+
+```bash
+# Pick your agent
+zibby test test.txt --agent cursor
+zibby test test.txt --agent claude
+zibby test test.txt --agent codex
+```
+
+## Who Is Zibby For?
+
+- **QA Engineers** who want AI-generated test cases from plain-text specs
+- **Developers** who want Playwright scripts without writing them manually
+- **Teams** adopting test automation without the upfront investment
+- **CI/CD pipelines** that need automated browser testing

package/docs/packages/cli.md

@@ -0,0 +1,238 @@
+---
+sidebar_position: 5
+title: "@zibby/cli"
+---
+
+# @zibby/cli
+
+The user-facing entry point — the `zibby` command.
+
+```bash
+npm install -g @zibby/cli
+```
+
+## What It Does
+
+`@zibby/cli` is the only package most users install. It provides:
+
+- **`zibby run`** — execute test specs with AI agents
+- **`zibby init`** — scaffold a customizable workflow
+- **`zibby login/logout/status`** — authentication
+- **`zibby upload`** — push existing artifacts to Zibby Cloud
+- **`zibby workflow`** — download/upload/list workflow graphs
+- **`zibby setup-playwright`** — configure Playwright MCP
+- **`zibby ci-setup`** — configure for CI/CD pipelines
+- **`zibby memory`** — memory database management
+- **`zibby video`** — organize test video files
+
+## Quick Usage
+
+```bash
+# Zero setup — run immediately
+echo "Go to example.com and verify the page title" > test.txt
+zibby run test.txt --agent cursor
+
+# Or with npx (no install)
+npx @zibby/cli run test.txt --agent cursor
+```
+
+## Commands
+
+### `zibby run [spec-path]`
+
+Run a test specification.
+
+```bash
+# Local test spec
+zibby run test-specs/login.txt --agent cursor
+
+# With cloud sync
+zibby run test-specs/login.txt --sync
+
+# Cloud test cases
+zibby run --sources TC001,TC002 --execution abc123
+
+# Specific workflow
+zibby run test.txt --workflow QuickSmokeWorkflow
+
+# Single node (debugging)
+zibby run test.txt --node execute_live --session last
+
+# Headless (CI/CD)
+zibby run test.txt --headless --auto-approve
+```
+
+| Flag | Description |
+|---|---|
+| `--agent <type>` | `cursor`, `claude`, or `codex` |
+| `--workflow <name>` | Named workflow (e.g., `QuickSmokeWorkflow`, `quick-smoke`) |
+| `--headless` | Headless browser mode |
+| `--node <name>` | Run a single node (`preflight`, `execute_live`, `generate_script`) |
+| `--session <id>` | Reuse session (`last` for most recent) — requires `--node` |
+| `--sources <ids>` | Comma-separated cloud test case IDs |
+| `--execution <id>` | Execution ID (with `--sources`) |
+| `--project <id>` | Project ID |
+| `--collection <name>` | Collection to organize the run |
+| `--folder <path>` | Folder within collection |
+| `--sync` | Upload results to cloud |
+| `--no-sync` | Skip cloud upload |
+| `--config <path>` | Config file path (default: `.zibby.config.js`) |
+| `--auto-approve` | Auto-approve MCP tool calls (CI/CD) |
+| `-o, --open` | Open dashboard after upload |
+| `--verbose` | Info-level logs |
+| `--debug` | Full debug logs |
+
+### `zibby init [project-name]`
+
+Scaffold a Zibby project with config and workflow files.
+
+```bash
+zibby init
+zibby init my-project --agent cursor --cloud-sync
+```
+
+| Flag | Description |
+|---|---|
+| `--agent <type>` | `cursor`, `claude`, or `codex` |
+| `--cloud-sync` | Enable cloud sync |
+| `--headless` / `--headed` | Browser mode |
+| `--skip-install` | Skip `npm install` |
+| `-f, --force` | Overwrite existing config |
+| `--mem` | Initialize memory database |
+
+Creates:
+
+```
+.zibby.config.js
+.zibby/
+├── graph.js
+├── nodes/
+│   ├── preflight.js
+│   ├── execute-live.js
+│   └── generate-script.js
+└── result-handler.js
+```
+
+### `zibby login` / `zibby logout` / `zibby status`
+
+```bash
+zibby login            # OAuth browser flow
+zibby logout           # Clear session
+zibby status           # Show auth status
+zibby status --json    # Machine-readable
+```
+
+### `zibby upload <spec-path>`
+
+Upload existing test artifacts to Zibby Cloud.
+
+```bash
+zibby upload test-specs/login.txt --collection "Auth Tests"
+```
+
+### `zibby workflow`
+
+Manage workflow graphs:
+
+```bash
+zibby workflow list
+zibby workflow download --type run_test
+zibby workflow upload --type analysis --file .zibby/workflow-analysis.json
+```
+
+### `zibby setup-playwright`
+
+Configure the Playwright MCP server:
+
+```bash
+zibby setup-playwright
+zibby setup-playwright --headed --viewport-width 1920 --viewport-height 1080
+```
+
+### `zibby ci-setup`
+
+Configure Cursor Agent for CI/CD:
+
+```bash
+zibby ci-setup
+zibby ci-setup --get-keys
+zibby ci-setup --save
+```
+
+### `zibby video`
+
+Organize test videos — moves videos from `test-results/` to sit next to test files:
+
+```bash
+zibby video
+```
+
+### `zibby list`
+
+List your projects and API tokens:
+
+```bash
+zibby list
+```
+
+## Configuration File
+
+`.zibby.config.js` (or `.zibby.config.mjs`) in your project root:
+
+```javascript
+export default {
+  agent: {
+    cursor: {
+      model: 'auto',
+      // Options: 'auto', 'opus-4.5', 'sonnet-4.5', 'composer-1',
+      //          'gpt-5.2-codex', 'gpt-5.2', 'gpt-5.3', 'gpt-5.4',
+      //          'gemini-3-pro', 'gemini-3-flash'
+    },
+    // claude: { model: 'auto' },
+    // codex: { model: 'gpt-5.2-codex' },
+    strictMode: false,
+  },
+
+  // Per-node model overrides
+  // models: {
+  //   default: 'auto',
+  //   execute_live: 'claude-opus-4',
+  // },
+
+  paths: {
+    specs: 'test-specs',
+    generated: 'tests',
+    output: '.zibby/output',
+  },
+
+  context: {
+    filenames: ['CONTEXT.md', 'AGENTS.md'],
+    discovery: {
+      env: `env-${process.env.ENV || 'local'}.js`,
+    },
+  },
+
+  video: 'on',
+  viewport: { width: 1280, height: 720 },
+  playwrightArtifacts: true,
+  cloudSync: false,
+};
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `CURSOR_API_KEY` | Cursor agent API key (required in CI, optional locally) |
+| `ANTHROPIC_API_KEY` | Claude agent API key |
+| `OPENAI_API_KEY` | Codex agent API key |
+| `ZIBBY_API_KEY` | Project API key for cloud sync |
+| `ZIBBY_USER_TOKEN` | Personal Access Token for CI/CD |
+| `ZIBBY_ENV` | Environment override: `local`, `staging`, `prod` |
+
+## Dependencies
+
+`@zibby/cli` automatically installs:
+- `@zibby/core` — workflow engine
+- `@zibby/skills` — skill catalog
+- `@zibby/memory` — test memory

package/docs/packages/core.md

@@ -0,0 +1,256 @@
+---
+sidebar_position: 1
+title: "@zibby/core"
+---
+
+# @zibby/core
+
+Core test automation engine with multi-agent and multi-MCP support.
+
+```bash
+npm install @zibby/core
+```
+
+> Most users don't install this directly — `@zibby/cli` depends on it automatically.
+
+## What's Inside
+
+`@zibby/core` is the runtime heart of Zibby. It provides:
+
+| Module | Purpose |
+|---|---|
+| **Workflow Framework** | `WorkflowGraph`, `Node`, `WorkflowState`, graph compiler |
+| **Agent Strategies** | `CursorAgentStrategy`, `ClaudeAgentStrategy`, `CodexAgentStrategy` |
+| **Skill Registry** | `registerSkill`, `getSkill`, `listSkillIds` |
+| **Graph Compiler** | `compileGraph`, `validateGraphConfig` — JSON → executable graph |
+| **Tool Resolver** | Maps node skill declarations to concrete MCP tool permissions |
+| **Code Generator** | `generateWorkflowCode` — serializes graphs to code |
+| **Templates** | Built-in workflow templates (browser-test-automation, code-analysis) |
+| **Enrichment Pipeline** | DOM enrichers, accessibility enrichers, page-state enrichers |
+| **Runtime** | Stable-ID runtime, verification strategies, Playwright integration |
+| **Sync** | Cloud upload/download for test results |
+
+## Exports
+
+```javascript
+// Framework
+import {
+  WorkflowGraph,
+  Node,
+  ConditionalNode,
+  WorkflowState,
+  OutputParser,
+  compileGraph,
+  validateGraphConfig,
+  extractSteps,
+} from '@zibby/core';
+
+// Agent strategies
+import {
+  invokeAgent,
+  getAgentStrategy,
+  CursorAgentStrategy,
+  ClaudeAgentStrategy,
+  AgentStrategy,
+} from '@zibby/core';
+
+// Skill registry
+import {
+  registerSkill,
+  getSkill,
+  hasSkill,
+  getAllSkills,
+  listSkillIds,
+} from '@zibby/core';
+
+// Zod (re-exported for convenience)
+import { z } from '@zibby/core';
+
+// Skills enum
+import { SKILLS } from '@zibby/core';
+```
+
+## WorkflowGraph
+
+The central class. Create a graph, add nodes and edges, then run it.
+
+```javascript
+import { WorkflowGraph } from '@zibby/core';
+import { z } from '@zibby/core';
+
+const graph = new WorkflowGraph({
+  stateSchema: z.object({        // Optional: validates initial state
+    testSpec: z.string(),
+    cwd: z.string().optional(),
+  }),
+  middleware: [],                 // Optional: wrap every node execution
+});
+
+graph.addNode('step_a', myNode);
+graph.addEdge('step_a', 'step_b');
+graph.setEntryPoint('step_a');
+
+const result = await graph.run(agent, { testSpec: '...' });
+```
+
+**Key methods:**
+
+| Method | Description |
+|---|---|
+| `addNode(name, config, options?)` | Add an executable node |
+| `addConditionalNode(name, config)` | Add a node that routes based on state |
+| `addEdge(from, to)` | Linear connection between nodes |
+| `addConditionalEdges(from, routeFn)` | Branch based on state — `routeFn(state) => 'next_node'` |
+| `setEntryPoint(name)` | Declare which node runs first |
+| `setStateSchema(zodSchema)` | Validate initial state before execution |
+| `use(middlewareFn)` | Add graph-level middleware |
+| `serialize()` | Export graph as JSON (for dashboard visual editor) |
+| `run(agent, initialState)` | Execute the graph |
+
+## Node Definition
+
+A node is a plain object with `name`, `prompt`, and `outputSchema`:
+
+```javascript
+import { z } from '@zibby/core';
+
+export const myNode = {
+  name: 'my_node',
+
+  // Prompt: function receiving state, returns string
+  prompt: (state) => `Analyze: ${state.testSpec}`,
+
+  // Output schema: Zod object validated at runtime
+  outputSchema: z.object({
+    title: z.string().describe('Short title'),
+    confidence: z.number().min(0).max(1),
+  }),
+
+  // Optional: skills needed (MCP tools)
+  skills: ['browser', 'memory'],
+
+  // Optional: timeout in ms (default 300000)
+  timeout: 600000,
+
+  // Optional: retry count
+  retries: 1,
+
+  // Optional: post-processing hook
+  onComplete: async (state, result) => {
+    // Transform result before it goes into state
+    return { ...result, processedAt: Date.now() };
+  },
+};
+```
+
+For nodes that don't call an LLM (pure data transforms), use a custom `execute` function:
+
+```javascript
+export const transformNode = {
+  name: 'transform',
+  _isCustomCode: true,
+  outputSchema: z.object({ cleaned: z.string() }),
+  execute: async (context) => {
+    const raw = context.state.get('raw_data');
+    return { cleaned: raw.trim().toLowerCase() };
+  },
+};
+```
+
+## Agent Strategy Framework
+
+All agents implement the same `AgentStrategy` base class:
+
+```javascript
+import { AgentStrategy } from '@zibby/core';
+
+class MyCustomAgent extends AgentStrategy {
+  constructor() {
+    super('my-agent', 'My Custom Agent', 50);
+  }
+
+  canHandle(context) {
+    return !!process.env.MY_AGENT_KEY;
+  }
+
+  async invoke(prompt, options) {
+    // options.schema — Zod schema for structured output
+    // options.workspace — working directory
+    // options.skills — skill IDs to resolve
+    // options.model — model name or 'auto'
+    // options.timeout — execution timeout
+    const response = await myApiCall(prompt, options);
+    if (options.schema) {
+      return { raw: response, structured: options.schema.parse(JSON.parse(response)) };
+    }
+    return response;
+  }
+}
+```
+
+Select and invoke an agent:
+
+```javascript
+import { invokeAgent, getAgentStrategy } from '@zibby/core';
+
+// Auto-select based on config
+const result = await invokeAgent(prompt, { state: { agentType: 'cursor' } }, {
+  model: 'auto',
+  workspace: process.cwd(),
+  schema: MyZodSchema,
+  skills: ['browser'],
+});
+```
+
+## Graph Compiler
+
+Compile a JSON graph definition (from the Zibby dashboard visual editor) into an executable `WorkflowGraph`:
+
+```javascript
+import { compileGraph, validateGraphConfig } from '@zibby/core';
+
+const graphJson = {
+  nodes: [
+    { id: 'preflight', type: 'preflight', data: { nodeType: 'preflight' } },
+    { id: 'execute_live', type: 'execute_live', data: { nodeType: 'execute_live' } },
+  ],
+  edges: [
+    { source: 'preflight', target: 'execute_live' },
+    { source: 'execute_live', target: 'END' },
+  ],
+  nodeConfigs: {
+    preflight: { prompt: 'Analyze: {{testSpec}}' },
+  },
+};
+
+// Validate
+const { valid, errors } = validateGraphConfig(graphJson);
+
+// Compile
+const graph = compileGraph(graphJson, { stateSchema: MySchema });
+
+// Run
+await graph.run(agent, initialState);
+```
+
+## Built-in Templates
+
+### Browser Test Automation
+
+```
+preflight → execute_live → generate_script → END
+```
+
+| Node | Skills | Output |
+|---|---|---|
+| `preflight` | — | `{ title, assertions[] }` |
+| `execute_live` | browser, memory | `{ success, steps[], actions[], assertions[] }` |
+| `generate_script` | — | `{ testCode, filename }` |
+
+### Code Analysis
+
+```
+setup → analyze_ticket → generate_code → generate_test_cases → finalize → END
+```
+
+Used by the cloud pipeline for Jira ticket analysis and code generation.