@zibby/cli 0.4.16 → 0.4.17

package/templates/zibby-workflow-claude/claude/commands/zibby-test-run.md

@@ -0,0 +1,49 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-test-run — execute a Zibby test spec
+
+You are helping the user run an existing test spec through Zibby. A spec is a `.txt` file describing what to test in plain language; Zibby's runner turns it into a Playwright execution and produces a video + JSON results.
+
+Canonical docs: **https://docs.zibby.app/tests/running**
+
+## Steps
+
+1. **Identify the spec.** Most projects keep specs under `test-specs/` (configurable in `.zibby.config.mjs` `paths.specs`). If user named one, use it. Otherwise list what's there and ask:
+   ```
+   ls test-specs/
+   ```
+
+2. **Run it.** From the project root:
+   ```
+   Bash(zibby test test-specs/<name>.txt)
+   ```
+   For a quick inline test without writing a spec file:
+   ```
+   Bash(zibby test "go to example.com and check that the title contains Example")
+   ```
+
+3. **Output to expect.** Zibby streams the run live — agent thinking, browser actions, assertion results, final pass/fail. Generated `.spec.js` lands in `tests/<name>.spec.js` (configurable via `paths.generated`). Video + traces under `test-results/`.
+
+4. **If running headless / CI:**
+   ```
+   Bash(zibby test test-specs/<name>.txt --headless)
+   ```
+
+5. **If running a specific node only** (advanced — re-execute one phase of a prior session):
+   ```
+   Bash(zibby test --node execute_live --session last)
+   ```
+
+## Useful flags
+
+- `--agent claude|cursor|codex|gemini` — override the configured agent for this run
+- `--workflow QuickSmokeWorkflow` — use a non-default workflow for the run
+- `--verbose` / `--debug` — escalate log levels
+- `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
+- `--sync` / `--no-sync` — force / skip cloud upload regardless of config
+- `--sources <ids> --execution <id>` — run cloud-stored test cases from a specific execution (comma-separated IDs)
+
+## Common failure modes
+
+- **"No spec found"** — path is relative to project root, not cwd. Check `paths.specs` in `.zibby.config.mjs`.
+- **"Browser crashed"** — usually the playwright browser cache is stale. Drop `--headless` once (default is headed) so you can see what's happening, then re-add `--headless` once it's healthy.
+- **MCP errors during `execute_live`** — the agent's MCP tool config may need refreshing. See `/zibby-test-debug`.

package/templates/zibby-workflow-claude/claude/commands/zibby-test-write.md

@@ -0,0 +1,46 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-test-write — author a new Zibby test spec
+
+You are helping the user write a new test spec. Specs are plain-language `.txt` files in `test-specs/` (configurable via `.zibby.config.mjs` `paths.specs`). Zibby's runner converts them to Playwright at execution time.
+
+Canonical docs: **https://docs.zibby.app/tests/specs**
+
+## Spec format (informal but conventional)
+
+A spec is mostly imperative English with one action per line. Common shape:
+
+```
+Title: <one-line summary>
+
+Setup:
+- Open <url>
+- Log in as <user>
+
+Steps:
+- Click <element>
+- Type <value> into <field>
+- Wait for <state>
+
+Verify:
+- <assertion>
+- <assertion>
+```
+
+Zibby tolerates loose phrasing — what matters is being unambiguous about WHICH element and WHAT value. Use stable selectors (visible text, ARIA labels) over CSS class names.
+
+## Steps for this command
+
+1. **Ask the user what they want to test.** What's the user flow? What are they verifying? What URL?
+2. **Find a similar existing spec to mirror.** `ls test-specs/` and read 1-2 to match the project's conventions.
+3. **Write the spec to `test-specs/<kebab-case-name>.txt`** using `Write` tool.
+4. **Offer to run it immediately** with `/zibby-test-run` (or just `Bash(zibby test test-specs/<name>.txt)`).
+
+## Naming conventions
+
+- kebab-case: `login-with-sso.txt`, `cart-checkout-happy-path.txt`
+- Group by feature: `users-create.txt`, `users-edit.txt`, `users-delete.txt`
+- Avoid ambiguous names like `test1.txt`
+
+## When the spec is complex
+
+For multi-page flows or many assertions, split into multiple specs and run them as a collection. Don't pile everything into one spec — Playwright errors are easier to localize when each spec is one user goal.

package/templates/zibby-workflow-claude/claude/commands/zibby-trigger.md

@@ -0,0 +1,56 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-trigger — run a deployed Zibby workflow
+
+You are helping the user trigger a deployed workflow execution.
+
+A trigger creates a new ECS Fargate task that loads the workflow's bundle, runs the graph, and writes status + logs as it goes.
+
+Canonical docs: **https://docs.zibby.app/cloud/triggering**
+
+## Steps
+
+1. **Get the workflow UUID.** The user should provide it; if not, run `zibby workflow list` to discover it. UUIDs are stable across deploys (the same workflow always has the same UUID; only the bundle version changes).
+
+2. **Construct the input.** Workflows take a JSON input that nodes can read via `ctx.input`. Ask the user what input the workflow expects (or read `workflow.json`'s `inputSchema` if present).
+
+3. **Run the trigger.** Three ways to pass input — they merge with this **precedence (highest → lowest)**:
+   1. `-p key=value` (repeatable) — wins over everything; great for shell-friendly tweaks on top of a base payload
+   2. `--input '<json>'` — full JSON payload as a string
+   3. `--input-file path.json` — full JSON/YAML payload from a file (lowest precedence; `-p` and `--input` override individual keys)
+
+   ```
+   zibby workflow trigger <uuid> --input '{"key":"value"}'
+   zibby workflow trigger <uuid> -p ticket=ENG-1234 -p priority=high
+   zibby workflow trigger <uuid> --input-file payload.json -p priority=urgent   # mix
+   ```
+
+   Same flag surface as `zibby workflow run` (local) — flip the verb and the same call shape goes from local to remote.
+
+4. **Tail the logs immediately:**
+   ```
+   zibby workflow logs <uuid> -t
+   ```
+   This streams live output. The tail auto-attaches to all currently-running executions of the workflow (docker-compose-style), so back-to-back triggers interleave naturally.
+
+5. **Watch for completion.** Workflow runs typically end with one of:
+   - `✓ Workflow completed` — success, status `completed`
+   - `Error: Node 'X' failed` — a node threw; status `failed`
+   - silent timeout — task killed by ECS; status stays `running` then becomes a zombie. Trigger again.
+
+## Idempotency
+
+Use `--idempotency-key <key>` to prevent duplicate runs from a retry-prone caller:
+```
+zibby workflow trigger <uuid> --input '{}' --idempotency-key job-2026-05-04-001
+```
+Same key + same input within ~24h = same execution returned (no new run).
+
+## Multiple inputs / batch
+
+There's no built-in batch trigger — script it from your shell:
+```
+for ticket in ENG-1 ENG-2 ENG-3; do
+  zibby workflow trigger <uuid> -p ticket=$ticket
+done
+zibby workflow logs <uuid> -t   # tail will show all 3 interleaved
+```

package/templates/zibby-workflow-claude/claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(zibby:*)",
+      "Bash(./.zibby/bin/zibby:*)",
+      "Bash(npm install:*)",
+      "Bash(node:*)"
+    ]
+  }
+}

package/templates/zibby-workflow-claude/cursor/rules/zibby-workflows.mdc

@@ -0,0 +1,119 @@
+<!-- zibby-template-version: 4 -->
+---
+description: Help the user build, test, and deploy Zibby agent workflows + browser tests
+globs:
+  - "**/.zibby/workflows/**"
+  - ".zibby.config.mjs"
+  - "**/workflow.json"
+  - "**/graph.mjs"
+  - "test-specs/**"
+  - ".zibby/memory/**"
+alwaysApply: false
+---
+
+# Zibby — workflows + tests
+
+This project uses **Zibby**. Two surfaces share `.zibby.config.mjs` at the project root.
+
+## Workflows
+
+A graph of AI-agent-driven steps that runs inside an ECS Fargate sandbox.
+
+```
+<workflowsBasePath>/<workflow-name>/
+├── workflow.json    # name, entryClass, triggers, schemas (manifest)
+├── graph.mjs        # exports the graph (nodes + edges)
+├── nodes/           # one .mjs file per node, plus index.mjs barrel
+└── package.json     # deps bundled at deploy time
+```
+
+Each node exports `{ id, description, async run(ctx) }`. `ctx` provides `input`, `agent({prompt, schema})`, `shell(cmd)`, `log(...)`.
+
+### Common dev loop
+
+```
+zibby workflow new <name>          # scaffold
+zibby workflow run <name>          # one-shot local run (preferred for the dev loop)
+zibby workflow deploy <name>       # build + push to cloud
+zibby workflow trigger <uuid>      # invoke the cloud workflow
+zibby workflow logs <uuid> -t      # tail live logs (docker-compose-style for concurrent runs)
+zibby workflow list                # local + cloud
+zibby workflow download <uuid>     # pull cloud source back to .zibby/workflows/
+zibby workflow delete <uuid>       # remove a deployed workflow
+```
+
+`run` (one-shot) vs `start` (long-lived dev server, port 3848 — Studio integration). For plain CLI iteration always use `run`.
+
+`run` and `trigger` accept the same input flags: `-p key=value` (highest precedence, repeatable), `--input '<json>'`, `--input-file path.json` (lowest precedence).
+
+### Adding a new node
+
+1. Create `<workflow>/nodes/<name>.mjs` (mirror existing `example.mjs` pattern)
+2. Register in `<workflow>/nodes/index.mjs`
+3. Wire into `<workflow>/graph.mjs` (add to `nodes` array and connect via edges)
+4. `zibby workflow run <name>` to test locally; `zibby workflow deploy` to push
+
+### Per-workflow env vars
+
+Each deployed workflow has its own encrypted env-var bag (KMS-backed); workflow env wins over project secrets on conflict.
+
+```
+zibby workflow env list  <uuid>                          # show key names (values never returned)
+zibby workflow env set   <uuid> ANTHROPIC_API_KEY=sk-…    # add or rotate one
+zibby workflow env unset <uuid> OLD_KEY                   # remove one
+zibby workflow env push  <uuid> --file .env [--file .env.prod]   # bulk replace
+```
+
+Fast path on first deploy: `zibby workflow deploy my-pipeline --env .env` deploys, then auto-pushes the .env into the new UUID.
+
+## Tests (`zibby test`)
+
+Plain-language `.txt` specs at `test-specs/`. The runner drives a real browser via MCP, generates Playwright, produces a video.
+
+```
+zibby test test-specs/<name>.txt        # run a spec
+zibby test "go to example.com and ..."  # inline, no file
+zibby test <spec> --agent claude        # override agent (claude|cursor|codex|gemini)
+zibby test --sources <ids> --execution <id>   # cloud test cases
+```
+
+When debugging, `test-results/<spec>/video.webm` usually tells you what went wrong faster than logs.
+
+### Test memory (`.zibby/memory/.dolt/`)
+
+Local-first Dolt SQL DB that learns selectors, page model, navigation, history from every run. Keyed **per-domain** (cross-spec). Auto-pulls before runs, auto-pushes after passing runs.
+
+When `zibby test` runs and `.dolt/` exists, the agent gets 5 MCP tools auto-exposed:
+- `memory_get_test_history` — recent runs (filter by spec-path substring)
+- `memory_get_selectors` — known selectors per page with stability metrics
+- `memory_get_page_model` — page elements, roles, accessible names
+- `memory_get_navigation` — page-to-page transitions
+- `memory_save_insight` — save observations (`selector_tip | timing | navigation | workaround | flaky | general`)
+
+**After completing a test, the agent MUST call `memory_save_insight` at least once** — record reliable selectors, timing quirks, workarounds.
+
+Local CLI: `zibby memory stats | cost | compact | reset`.
+
+Team sync (BYO or hosted):
+```
+zibby memory remote add aws://my-bucket/team/proj/main   # BYO (S3 / GCS / DoltHub / file:///)
+zibby memory remote use --hosted                         # OR: Zibby-managed S3 (signed-in only)
+```
+Set `memorySync.remote` in `.zibby.config.mjs` (`'hosted'` or `'aws://...'`) so teammates running `zibby init` plug into the same memory automatically.
+
+## Reference
+
+Canonical, evolving docs: **https://docs.zibby.app/workflows**
+
+Topics:
+- Node SDK (ctx.agent / ctx.shell / ctx.log): https://docs.zibby.app/workflows/sdk
+- Deploying & bundling: https://docs.zibby.app/workflows/deploying
+- Triggering & inputs: https://docs.zibby.app/workflows/triggers
+- Per-workflow env vars: https://docs.zibby.app/cloud/env-vars
+- Live log streaming: https://docs.zibby.app/workflows/logs
+- Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
+- Security & secrets: https://docs.zibby.app/workflows/security
+- Test memory: https://docs.zibby.app/tests/memory
+- Tests — running: https://docs.zibby.app/tests/running
+
+Prefer the docs URL for anything you're unsure about — they're updated more frequently than these rules.

package/templates/zibby-workflow-claude/manifest.json

@@ -0,0 +1,47 @@
+{
+  "templateVersion": 4,
+  "description": "Canonical agent helpers for Zibby workflows. Each shipped file carries '<!-- zibby-template-version: N -->' for idempotent upgrades. Bumped on breaking content changes.",
+  "agents": {
+    "claude": {
+      "files": [
+        ".claude/commands/zibby-add-node.md",
+        ".claude/commands/zibby-deploy.md",
+        ".claude/commands/zibby-trigger.md",
+        ".claude/commands/zibby-tail.md",
+        ".claude/commands/zibby-debug.md",
+        ".claude/commands/zibby-delete.md",
+        ".claude/commands/zibby-list.md",
+        ".claude/commands/zibby-static-ip.md",
+        ".claude/commands/zibby-test-run.md",
+        ".claude/commands/zibby-test-write.md",
+        ".claude/commands/zibby-test-generate.md",
+        ".claude/commands/zibby-test-debug.md",
+        ".claude/commands/zibby-memory-stats.md",
+        ".claude/commands/zibby-memory-cost.md",
+        ".claude/commands/zibby-memory-pull.md",
+        ".claude/commands/zibby-memory-remote-use-hosted.md",
+        ".claude/agents/zibby-workflow-builder.md",
+        ".claude/agents/zibby-test-author.md"
+      ],
+      "writeOnceFiles": [
+        ".claude/settings.json"
+      ],
+      "rootBlock": {
+        "target": "CLAUDE.md",
+        "source": "agents-md-block.md"
+      }
+    },
+    "cursor": {
+      "files": [
+        ".cursor/rules/zibby-workflows.mdc"
+      ]
+    },
+    "codex": {
+      "files": [],
+      "rootBlock": {
+        "target": "AGENTS.md",
+        "source": "agents-md-block.md"
+      }
+    }
+  }
+}