@zibby/skills 0.1.8 → 0.1.10

package/docs/cli-reference.md

@@ -0,0 +1,338 @@
+---
+sidebar_position: 6
+title: CLI Reference
+---
+
+# CLI Reference
+
+## Installation
+
+```bash
+npm install -g @zibby/cli
+```
+
+---
+
+## Commands
+
+### `zibby test [spec-path]`
+
+Run a test specification.
+
+```bash
+# Run a local test spec
+zibby test test-specs/login.txt --agent cursor
+
+# Run without any project setup
+echo "Go to example.com" > test.txt && zibby test test.txt --agent cursor
+
+# Run with cloud sync
+zibby test test-specs/login.txt --sync
+
+# Run test cases from cloud
+zibby test --sources TC001,TC002 --execution abc123
+```
+
+| Flag | Description |
+|---|---|
+| `--agent <type>` | AI agent: `cursor`, `claude`, or `codex` |
+| `--workflow <name>` | Workflow to use (e.g., `QuickSmokeWorkflow`, `quick-smoke`) |
+| `--headless` | Run browser in headless mode |
+| `--node <name>` | Run only a specific node (`preflight`, `execute_live`, `generate_script`) |
+| `--session <id>` | Reuse an existing session (`last` for most recent) — requires `--node` |
+| `--sources <ids>` | Comma-separated test case IDs to fetch from cloud |
+| `--execution <id>` | Execution ID (required with `--sources`) |
+| `--project <id>` | Project ID or API token (auto-detected from `ZIBBY_API_KEY`) |
+| `--collection <id-or-name>` | Collection to organize the run into (creates if name is new) |
+| `--folder <path>` | Folder within the collection |
+| `--sync` | Force 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 (for CI/CD) |
+| `-o, --open` | Open results in browser after upload |
+| `--verbose` | Show info-level logs |
+| `--debug` | Show debug-level logs |
+
+---
+
+### `zibby init [project-name]`
+
+Initialize a Zibby project with config and workflow files. **Optional** — `zibby test` works without it using the built-in workflow.
+
+```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` | Headless browser mode |
+| `--headed` | Headed browser mode |
+| `--api-key <key>` | Zibby API key |
+| `--skip-install` | Skip `npm install` |
+| `-f, --force` | Overwrite existing config |
+
+---
+
+### `zibby login`
+
+Authenticate with Zibby (opens browser for OAuth).
+
+```bash
+zibby login
+```
+
+---
+
+### `zibby logout`
+
+Clear saved session.
+
+```bash
+zibby logout
+```
+
+---
+
+### `zibby status`
+
+Show current authentication status.
+
+```bash
+zibby status
+zibby status --json
+```
+
+---
+
+### `zibby list`
+
+List your projects and API tokens.
+
+```bash
+zibby list
+```
+
+---
+
+### `zibby upload <spec-path>`
+
+Upload existing test artifacts to Zibby Cloud.
+
+```bash
+zibby upload test-specs/login.txt --collection "Auth Tests"
+```
+
+| Flag | Description |
+|---|---|
+| `--project <id>` | Project ID (required) |
+| `--collection <id-or-name>` | Collection to upload into |
+| `--folder <path>` | Folder within collection |
+
+---
+
+### `zibby video`
+
+Organize test videos — moves videos from `test-results/` to sit next to test files.
+
+```bash
+zibby video
+```
+
+---
+
+### `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 pipelines.
+
+```bash
+zibby ci-setup
+zibby ci-setup --get-keys
+zibby ci-setup --save
+```
+
+---
+
+### `zibby g workflow [name]`
+
+Scaffold a new custom workflow. Auto-generates a name if omitted.
+
+```bash
+zibby g workflow ticket-triage
+zibby g workflow                   # auto-generates name
+```
+
+---
+
+### `zibby start <workflow-name>`
+
+Start a local dev server for testing a custom workflow.
+
+```bash
+zibby start ticket-triage
+zibby start ticket-triage --port 3850
+```
+
+| Flag | Description |
+|---|---|
+| `-p, --port <port>` | Server port (default: 3848) |
+
+---
+
+### `zibby deploy <workflow-name>`
+
+Deploy a custom workflow to Zibby Cloud. Returns the trigger URL and workflow UUID.
+
+```bash
+zibby deploy ticket-triage --project <id>
+```
+
+| Flag | Description |
+|---|---|
+| `--project <id>` | Project ID (or `ZIBBY_PROJECT_ID` env) |
+| `--api-key <key>` | API key (or `ZIBBY_API_KEY` env, or session token) |
+
+---
+
+### `zibby trigger <workflow-uuid>`
+
+Trigger a deployed workflow by its UUID. The CLI automatically discovers the project.
+
+```bash
+# Trigger by UUID (project auto-discovered)
+zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405
+
+# Trigger by UUID with input data
+zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405 \
+  --input '{"ticket":"JIRA-123"}'
+
+# Trigger by name (requires project)
+zibby trigger custom-flow --project <id>
+
+# With idempotency key (prevents duplicate runs)
+zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405 \
+  --idempotency-key "daily-scan-2026-04-27"
+```
+
+| Flag | Description |
+|---|---|
+| `--input <json>` | Input data as JSON string |
+| `--idempotency-key <key>` | Prevent duplicate executions (same key within 24h) |
+| `--project <id>` | Project ID (only needed if triggering by workflow name) |
+
+**After triggering, stream logs:**
+
+```bash
+zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405 -t
+```
+
+---
+
+### `zibby logs <workflow-uuid>`
+
+Fetch and display logs from a workflow's latest execution.
+
+```bash
+# Fetch logs for latest execution (simple, one-time fetch)
+zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405
+
+# Stream logs in real-time (like "heroku logs -t")
+zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405 -t
+
+# Stream logs by workflow name
+zibby logs --workflow custom-flow --project <id> -t
+```
+
+| Flag | Description |
+|---|---|
+| `-t, --follow` | Stream logs in real-time via SSE (Server-Sent Events) |
+| `--project <id>` | Project ID (optional, auto-discovered from workflow UUID) |
+| `--workflow <name>` | Workflow name (fetches latest run) |
+| `--all` | Interleaved logs from all runs (requires `--workflow`) |
+| `--lines <n>` | Max log lines per fetch (default: 1000) |
+
+**How it works:**
+
+- **Without `-t`**: Fetches complete logs from CloudWatch (permanent storage) and exits. Perfect for historical logs and debugging old executions.
+- **With `-t`**: Streams logs in real-time via SSE from DynamoDB hot cache (24h TTL). Only works for active/recent executions. Press Ctrl+C to stop.
+
+**Architecture:**
+
+```
+CloudWatch Logs (permanent) ──────────> CLI (without -t)
+     │
+     └──> Kinesis ──> Lambda ──> DynamoDB (24h TTL) ──> SSE ──> CLI (with -t)
+```
+
+---
+
+### `zibby workflow download`
+
+Download a workflow graph from Zibby Cloud.
+
+```bash
+zibby workflow download --type run_test
+```
+
+### `zibby workflow list`
+
+List all workflows for a project.
+
+```bash
+zibby workflow list
+```
+
+---
+
+## 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 (from dashboard Settings) |
+| `ZIBBY_USER_TOKEN` | Personal Access Token for CI/CD uploads |
+| `ZIBBY_ENV` | Environment override: `local`, `staging`, `prod` |
+
+## Configuration File
+
+`.zibby.config.js` in your project root (ESM):
+
+```javascript
+export default {
+  agent: {
+    cursor: { model: 'auto' },
+    // claude: { model: 'auto' },
+    // codex: { model: 'gpt-5.2-codex' },
+  },
+
+  paths: {
+    specs: 'test-specs',
+    generated: 'tests',
+    output: '.zibby/output',
+  },
+
+  context: {
+    filenames: ['CONTEXT.md', 'AGENTS.md'],
+  },
+
+  video: 'on',
+  viewport: { width: 1280, height: 720 },
+  playwrightArtifacts: true,
+  cloudSync: false,
+};
+```

package/docs/cloning-repositories.md

@@ -0,0 +1,285 @@
+---
+sidebar_position: 8
+title: Cloning Repositories
+---
+
+# Cloning Repositories in Custom Workflows
+
+Custom workflows can clone your project's configured repositories (GitHub/GitLab) using the `cloneRepo()` helper function from `@zibby/core`.
+
+## Overview
+
+When your workflow runs in the cloud, it has access to:
+- All repositories configured in your project settings (GitHub/GitLab)
+- Authenticated tokens for cloning (injected securely by the platform)
+- A clean isolated container environment
+
+The `cloneRepo()` function handles authentication, supports multiple repos, and works with both GitHub.com and self-hosted GitLab instances.
+
+## Basic Usage
+
+### Clone All Repositories
+
+By default, `cloneRepo()` clones all repositories configured for your project:
+
+```javascript
+// nodes/setup.mjs
+import { cloneRepo, z } from '@zibby/core';
+
+const SetupOutputSchema = z.object({
+  repoPaths: z.record(z.string()),
+});
+
+export const setupNode = {
+  name: 'setup',
+  
+  async preProcess(state) {
+    // Clone all repos
+    const repoPaths = await cloneRepo();
+    
+    // repoPaths = {
+    //   'myorg/backend': '/workspace/repos/myorg-backend',
+    //   'myorg/frontend': '/workspace/repos/myorg-frontend'
+    // }
+    
+    return { repoPaths };
+  },
+  
+  prompt: (state) => `Repositories cloned:
+${JSON.stringify(state.setup.repoPaths, null, 2)}
+
+Ready to analyze the codebase.`,
+  
+  outputSchema: SetupOutputSchema,
+};
+```
+
+### Clone Specific Repositories
+
+If you only need certain repositories:
+
+```javascript
+// Clone only backend repo
+const repoPaths = await cloneRepo({
+  repos: ['myorg/backend']
+});
+```
+
+### Using Cloned Repositories
+
+Access the cloned code via the returned paths:
+
+```javascript
+// nodes/analyze.mjs
+import { z } from '@zibby/core';
+
+const AnalyzeOutputSchema = z.object({
+  summary: z.string(),
+  files: z.array(z.string()),
+});
+
+export const analyzeNode = {
+  name: 'analyze',
+  
+  prompt: (state) => `Analyze the codebase.
+
+Repositories are cloned at:
+${JSON.stringify(state.setup.repoPaths, null, 2)}
+
+Use the Shell tool to:
+1. List files in the repos (e.g., ls ${Object.values(state.setup.repoPaths)[0]})
+2. Read important files (e.g., cat ${Object.values(state.setup.repoPaths)[0]}/README.md)
+3. Run analysis commands (e.g., cd ${Object.values(state.setup.repoPaths)[0]} && npm audit)
+
+Return a summary and list of key files.`,
+  
+  outputSchema: AnalyzeOutputSchema,
+};
+```
+
+## Configuration Options
+
+```javascript
+await cloneRepo({
+  // Clone specific repos only (default: all repos)
+  repos: ['myorg/backend', 'myorg/frontend'],
+  
+  // Base directory for cloned repos (default: '/workspace/repos')
+  baseDir: '/workspace/repos',
+  
+  // Clone depth - 1 for shallow clone, 0 for full history (default: 1)
+  depth: 1,
+  
+  // Specific branch to clone (default: repo's default branch)
+  branch: 'develop',
+});
+```
+
+## Return Value
+
+`cloneRepo()` returns an object mapping repository names to their cloned paths:
+
+```javascript
+{
+  'myorg/backend': '/workspace/repos/myorg-backend',
+  'myorg/frontend': '/workspace/repos/myorg-frontend'
+}
+```
+
+If a repository fails to clone, its value will be `null`:
+
+```javascript
+{
+  'myorg/backend': '/workspace/repos/myorg-backend',
+  'myorg/broken-repo': null  // Failed to clone
+}
+```
+
+## Complete Example Workflow
+
+Here's a full workflow that clones repos and runs analysis:
+
+```javascript
+// graph.mjs
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { setupNode, analyzeNode, reportNode } from './nodes/index.mjs';
+
+export class CodeAuditWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+
+    graph.addNode('setup', setupNode);
+    graph.addNode('analyze', analyzeNode);
+    graph.addNode('report', reportNode);
+
+    graph.setEntryPoint('setup');
+    graph.addEdge('setup', 'analyze');
+    graph.addEdge('analyze', 'report');
+    graph.addEdge('report', 'END');
+
+    return graph;
+  }
+}
+```
+
+```javascript
+// nodes/setup.mjs
+import { cloneRepo, z } from '@zibby/core';
+
+export const setupNode = {
+  name: 'setup',
+  
+  async preProcess(state) {
+    console.log('Cloning repositories...');
+    const repoPaths = await cloneRepo();
+    console.log('Cloned:', Object.keys(repoPaths).length, 'repositories');
+    return { repoPaths };
+  },
+  
+  prompt: () => 'Repositories cloned successfully. Ready for analysis.',
+  
+  outputSchema: z.object({
+    ready: z.boolean().default(true),
+  }),
+};
+```
+
+```javascript
+// nodes/analyze.mjs
+import { z } from '@zibby/core';
+
+export const analyzeNode = {
+  name: 'analyze',
+  
+  prompt: (state) => {
+    const repoList = Object.entries(state.setup.repoPaths)
+      .map(([name, path]) => `- ${name}: ${path}`)
+      .join('\\n');
+    
+    return `Analyze all cloned repositories for security issues.
+
+Cloned repositories:
+${repoList}
+
+For each repository, use the Shell tool to:
+1. Check for dependencies with known vulnerabilities (npm audit, pip check, etc.)
+2. Search for common security issues (hardcoded secrets, SQL injection patterns, etc.)
+3. Review package.json/requirements.txt for outdated dependencies
+
+Return a comprehensive security audit report.`;
+  },
+  
+  outputSchema: z.object({
+    findings: z.array(z.object({
+      severity: z.enum(['low', 'medium', 'high', 'critical']),
+      repo: z.string(),
+      description: z.string(),
+      file: z.string().optional(),
+    })),
+    summary: z.string(),
+  }),
+};
+```
+
+## How It Works
+
+1. **Project Configuration**: You configure repositories in your project settings (Web UI)
+2. **Secure Token Injection**: When the workflow runs, Zibby injects:
+   - `REPOS` env var (array of repo metadata with clone URLs)
+   - `GITHUB_TOKEN` and/or `GITLAB_TOKEN` (OAuth tokens for authentication)
+3. **Authenticated Clone**: `cloneRepo()` constructs authenticated URLs and clones via `git clone`
+4. **Isolation**: Each workflow run gets a fresh container with no cached state
+
+## Supported Platforms
+
+- **GitHub** (github.com)
+- **GitLab** (gitlab.com)
+- **Self-hosted GitLab** (custom instance URLs from project settings)
+
+## Error Handling
+
+`cloneRepo()` is resilient to failures:
+
+```javascript
+const repoPaths = await cloneRepo();
+
+// Check for failures
+for (const [repo, path] of Object.entries(repoPaths)) {
+  if (path === null) {
+    console.error(`Failed to clone ${repo}`);
+  }
+}
+
+// Continue with successfully cloned repos
+const successfulRepos = Object.entries(repoPaths)
+  .filter(([_, path]) => path !== null);
+```
+
+Common failure reasons:
+- Missing/expired authentication tokens
+- Repository doesn't exist or access denied
+- Network issues
+- Invalid clone URL
+
+## Performance Tips
+
+1. **Shallow Clones**: Use `depth: 1` (default) for faster cloning
+2. **Specific Repos**: Only clone repos you need via the `repos` option
+3. **Parallel Execution**: `cloneRepo()` clones all repos in parallel automatically
+
+## Local Development
+
+When running workflows locally (`zibby start`), you'll need to:
+1. Set `REPOS` env var manually (JSON array)
+2. Provide `GITHUB_TOKEN` or `GITLAB_TOKEN`
+3. Ensure `git` is installed
+
+Example for local testing:
+
+```bash
+export REPOS='[{"name":"myorg/backend","provider":"github","cloneUrl":"https://github.com/myorg/backend.git"}]'
+export GITHUB_TOKEN="ghp_your_token"
+zibby start my-workflow
+```
+
+In production (cloud), these are injected automatically.