@zibby/cli 0.5.8 → 0.6.0

package/templates/.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/.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/.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/{dist/templates/.claude/commands/validate-workflow.md → templates/.claude/commands/zibby-validate-workflow.md}

@@ -3,7 +3,7 @@ description: Statically validate a Zibby workflow + run it locally with sample i
 argument-hint: <workflow-name> [optional input as key=value pairs]
 ---
 
-# /validate-workflow
+# /zibby-validate-workflow
 
 The user wants to verify a workflow works before deploying.
 

package/templates/.cursor/rules/zibby.mdc

@@ -0,0 +1,127 @@
+---
+description: Build, test, deploy, and operate on Zibby — workflows + hosted apps + tests
+globs:
+  - "**/.zibby/workflows/**"
+  - "**/workflows/**"
+  - ".zibby.config.mjs"
+  - "**/workflow.json"
+  - "**/graph.mjs"
+  - "test-specs/**"
+  - ".zibby/memory/**"
+  - "AGENTS.md"
+alwaysApply: false
+---
+
+# Zibby — workflows + apps + tests
+
+This project uses **Zibby**. Two production surfaces share `.zibby.config.mjs`:
+
+1. **Workflows** — graphs of AI-agent steps in a Fargate sandbox.
+2. **Apps** — long-running hosted SaaS instances (n8n, grafana, …).
+
+Plus **Tests** — plain-language `.txt` specs converted to Playwright runs.
+
+See `.claude/CLAUDE.md` for the long-form. `AGENTS.md` has the cross-IDE
+recipes. Canonical docs: https://docs.zibby.app.
+
+## Workflows — common dev loop
+
+```
+zibby workflow new <name>        # scaffold (workflows/<name>/ by default)
+zibby workflow run <name>        # one-shot LOCAL run (preferred for dev loop)
+zibby workflow validate <name>   # static check (graph topology, schemas)
+zibby workflow deploy <name>     # build + push to cloud → UUID
+zibby workflow trigger <uuid>    # remote run
+zibby workflow logs <uuid> -t    # tail live logs (background-run this in chat)
+zibby workflow list              # local + cloud
+zibby workflow delete <uuid>
+```
+
+File layout (workflows/<name>/):
+```
+workflow.json    # name, entryClass, triggers, defaultAgent
+graph.mjs        # class extends WorkflowAgent, buildGraph() returns WorkflowGraph
+nodes/*.mjs      # { name, outputSchema (Zod), prompt|execute }
+state.js         # OPTIONAL — Zod schema for caller-provided inputs (-p)
+package.json     # @zibby/core + zod
+```
+
+Each node's output goes to `state[nodeName]`. Read downstream as
+`state.previousNode.field`. Initial input (`-p key=value`) is top-level
+in state (`state.key`). Loops route back via `addConditionalEdges`;
+counter state lives in the looping node's own outputSchema.
+
+`run` and `trigger` share input flags: `-p key=value` (highest, repeatable),
+`--input '<json>'`, `--input-file path.json` (lowest).
+
+## Apps — common deploy + operate loop
+
+```
+zibby app templates                                 # browse catalog
+zibby app deploy <appType> --project <id>           # catalog deploy (~2-3 min)
+zibby app deploy --goal "<text>" --project <id>     # goal-mode (LLM bootstrap, 5-30 min)
+zibby app list
+zibby app status <instanceId>
+zibby app logs <instanceId> [-t] [--service <name>]
+zibby app upgrade <instanceId> --version vX.Y.Z     # agent-ops base image
+zibby app set-auth <instanceId> --auth-type basic --auth-user admin --auth-password ...
+zibby app set-auth <instanceId> --off               # remove auth sidecar
+zibby app destroy <instanceId> --yes                # PERMANENT — wipes EFS
+```
+
+**Catalog vs goal-mode** — catalog uses a baked task def, goal-mode runs
+an autonomous `agent-ops` install loop. Use catalog when the app is in
+`zibby app templates`; goal-mode for anything else.
+
+Goal-mode flags: `--provider claude|codex`, `--model <id>`,
+`--anthropic-token sk-ant-...` (per-deploy override), `--max-turns N`
+(default 25, bump to 60-100 for heavy installs), `--timeout-min N`
+(default 20, bump to 30-45 for heavy installs).
+
+**Auth** — every app gets a public `*.apps.zibby.app` URL. Set
+`--auth-type basic|token` at deploy time (or via `zibby app set-auth`
+after). `none` is only safe if the app has its own login. Generate
+credentials with `openssl rand -hex 16` (basic password) / `-hex 32`
+(token). Never log credentials.
+
+**Multi-service entries** — `wordpress` (wordpress + mysql), `mattermost`
+(mattermost + postgres), `gas-town` (web + worker + scheduler). Use
+`--service <name>` to tail one service; `app status` lists `services[]`.
+
+## Auth + login
+
+```
+zibby login                  # browser OAuth → ~/.zibby/session.json
+zibby status                 # current auth + workspace + project + agent creds
+```
+
+Headless / CI: `export ZIBBY_API_KEY=zby_xxx` (PAT from https://zibby.dev/settings/api-keys). Env wins over session.
+
+## Agent's job: decide workflow vs app
+
+| User wants… | Use |
+|---|---|
+| Schedule / event-driven LLM automation | **Workflow** |
+| Long-running hosted web service | **App** |
+| Bootstrap an arbitrary OSS thing | **App goal-mode** |
+| Sub-second interactive UI | Neither (Lambda / own backend) |
+
+Always ask before:
+- `zibby workflow deploy` (cloud cost)
+- `zibby app deploy` (per-minute billing starts immediately)
+- `zibby app destroy` (irreversible, EFS wiped)
+- Any `--anthropic-token` paste (credentials in chat history leak)
+
+## How to invoke the CLI
+
+`zibby` on PATH (preferred) or `./.zibby/bin/zibby` as a fallback shim
+that always exists in this project. Don't use `npx @zibby/cli` — not
+always published.
+
+## Canonical docs (always prefer over these notes)
+
+- Workflows: https://docs.zibby.app/workflows
+- Apps: https://docs.zibby.app/apps
+- agent-ops daemon: https://docs.zibby.app/apps/agent-ops
+- CLI: https://docs.zibby.app/cli
+- MCP: https://docs.zibby.app/cli/mcp

package/templates/AGENTS.md

@@ -0,0 +1,248 @@
+<!-- BEGIN ZIBBY — managed by `zibby init`, do not edit between markers -->
+# Zibby integration
+
+This project uses **Zibby** (https://zibby.dev). Zibby is two surfaces
+sharing one account, one CLI, one Studio:
+
+1. **Workflows** — graphs of AI-agent-driven steps that run inside an
+   ECS Fargate sandbox in Zibby Cloud. For event-driven automation
+   that needs an LLM in the loop.
+2. **Apps** — long-running hosted SaaS instances (n8n, Grafana,
+   Outline, …) on Zibby's Fargate fleet, with an `agent-ops` sidecar.
+   Pick from a catalog or describe a goal in natural language.
+
+For deeper detail, see `.claude/CLAUDE.md` in this repo (canonical
+reference) or https://docs.zibby.app.
+
+---
+
+## CLI quick reference
+
+Use `zibby` on PATH (preferred) or `./.zibby/bin/zibby` as a fallback
+shim in this repo. Never fall back to `npx @zibby/cli`.
+
+### Auth + context
+
+```bash
+zibby login                         # browser OAuth → ~/.zibby/session.json
+zibby status                        # current auth + workspace + project + agent creds
+zibby logout                        # clear session
+zibby list                          # list projects in this workspace
+zibby project use <id>              # switch default project
+```
+
+For headless / CI: `export ZIBBY_API_KEY=zby_xxx` (PAT from https://zibby.dev/settings/api-keys). Env var beats session token.
+
+### Workflows
+
+```bash
+zibby workflow new <name>           # scaffold .zibby/workflows/<name>/
+zibby workflow run <name> -p k=v    # one-shot LOCAL run (preferred for dev loop)
+zibby workflow validate <name>      # static check (graph topology, schemas, skills)
+zibby workflow deploy <name>        # build + push to Zibby Cloud → UUID
+zibby workflow trigger <uuid> -p .. # remote run
+zibby workflow logs <uuid> -t       # tail live logs
+zibby workflow schedule <uuid> set "0 9 * * 1-5"   # 5-field Unix cron
+zibby workflow list                 # local + cloud
+zibby workflow delete <uuid>        # remove a deployed workflow
+```
+
+Workflow file layout:
+```
+<paths.workflows or workflows>/<name>/
+├── workflow.json          name, entryClass, triggers, defaultAgent
+├── graph.mjs              class extends WorkflowAgent — buildGraph() returns WorkflowGraph
+├── nodes/*.mjs            one node per file: name, outputSchema (Zod), prompt|execute
+├── state.js               OPTIONAL — Zod schema for caller-provided inputs
+└── package.json           @zibby/core + zod
+```
+
+Node shape:
+```js
+import { z } from 'zod';
+export const planNode = {
+  name: 'plan',
+  agent: 'claude',                    // optional override; defaults to workflow's defaultAgent
+  outputSchema: z.object({ steps: z.array(z.string()) }),
+  prompt: (state) => `Plan: ${state.userRequest}`,
+  // OR for deterministic work:
+  // execute: async (state) => ({ steps: [...] }),
+};
+```
+
+Graph wiring:
+```js
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+export class MyWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.addNode('plan', planNode);
+    graph.addNode('act',  actNode);
+    graph.addEdge('plan', 'act');
+    graph.addEdge('act',  'END');
+    graph.setEntryPoint('plan');
+    return graph;
+  }
+}
+```
+
+**Each node's output goes to `state[nodeName]`.** Read it in downstream
+nodes via `state.plan.steps`. Initial input from `-p key=value` is at
+the TOP of state (`state.key`), not nested under `input`.
+
+Loops: route back to an earlier node via `addConditionalEdges`. Counter
+state lives in the looping node's own outputSchema (`state.check?.attempts`).
+
+### Apps
+
+```bash
+zibby app templates                                 # browse the catalog
+zibby app deploy <appType> --project <id> [--name "..."] [--auth-type basic|token|none ...]
+zibby app deploy --goal "<text>" --project <id>     # goal-mode (LLM bootstrap)
+zibby app list [--project <id>]
+zibby app status <instanceId>
+zibby app logs <instanceId> [-t] [--service <name>]
+zibby app upgrade <instanceId> --version vX.Y.Z     # agent-ops base image bump
+zibby app set-auth <instanceId> --auth-type basic --auth-user admin --auth-password ...
+zibby app set-auth <instanceId> --off               # disable Caddy auth sidecar
+zibby app destroy <instanceId> --yes                # PERMANENT — wipes EFS
+```
+
+Two deploy paths:
+- **Catalog** (`zibby app deploy <appType>`) — deterministic, baked task
+  def, 2-3 min cold start.
+- **Goal-mode** (`zibby app deploy --goal "..."`) — LLM bootstrap via
+  `agent-ops`, 5-30 min cold start.
+
+Goal-mode flags worth knowing: `--provider claude|codex`, `--model <id>`,
+`--anthropic-token sk-ant-oat01-...` (per-deploy Claude credential override),
+`--max-turns N` (default 25, heavy installs need 60-100), `--timeout-min N`
+(default 20, heavy installs need 30-45).
+
+Auth: every app gets a public `https://<id>.apps.zibby.app` URL. Lock it
+down with `--auth-type basic|token`. Generate creds via `openssl rand -hex`.
+Use `--auth-type none` (or omit) only if the app has its own login.
+
+---
+
+## Recipe: "create a workflow that does X"
+
+1. **Sketch the graph.** 2-5 nodes. LLM (judgement) vs custom-code
+   (deterministic shell / HTTP / parse). Linear or conditional?
+2. `zibby workflow new <name>` — scaffold.
+3. Edit `workflow.json`, `nodes/*.mjs`, `graph.mjs`. Every node has a
+   Zod `outputSchema`. Default agent: `claude`.
+4. `zibby workflow validate <name>` — fix reported issues.
+5. `zibby workflow run <name> -p ...` — realistic input. Read the
+   timeline. If a node fails, the `raw` field shows what the model
+   returned vs what the schema expected.
+6. Iterate prompts. The user shouldn't need to.
+7. Ask before `zibby workflow deploy` — cloud costs.
+
+## Recipe: "deploy a hosted X"
+
+1. **Catalog or goal?** Check `zibby app templates`. Catalog if X
+   is listed; else goal-mode.
+2. **Which project?** `zibby status` for current; `zibby list` to
+   pick.
+3. **What auth?** Ask before running. `basic` for browser tools,
+   `token` for APIs, `none` only for apps with their own login.
+   Generate creds with `openssl rand -hex 16` (basic) / `-hex 32`
+   (token).
+4. **Run deploy.** Capture the `instanceId`.
+5. **Tail logs while it boots** (`zibby app logs <id> -t` in background).
+6. **Verify status reaches `running`.** Tell the user URL + creds.
+
+## Recipe: "my workflow / app is broken"
+
+For workflows:
+1. `zibby workflow list` — did the deploy succeed? Is `bundleStatus`
+   ready?
+2. `zibby workflow trigger <uuid>` — did it accept?
+3. `zibby workflow logs <uuid> -t` — did the task start? Did a node
+   fail? Read the `Prompt sent to LLM` + `Response` blocks for agent
+   errors.
+
+For apps:
+1. `zibby app status <id>` — read the status. `failed` → reason field.
+   Stuck `pending` → wait 5 min, then escalate to logs.
+2. `zibby app logs <id> [--service agent-ops]` — supervisor trail +
+   container stderr.
+3. Decide: restart, env-fix, or destroy + redeploy. Never destroy
+   without confirming EFS data loss.
+
+## Recipe: "set an env var for production"
+
+For a workflow:
+```bash
+# next trigger picks it up; existing executions unaffected
+```
+
+For an app:
+```bash
+```
+
+Workflow env wins over project secrets. App env applies at task-start;
+restart to apply changes.
+
+## Recipe: "rotate the auth on a hosted app"
+
+```bash
+zibby app set-auth <instanceId> --auth-type basic \
+  --auth-user admin \
+  --auth-password $(openssl rand -hex 16)
+```
+
+Caddy reloads in ~5s. Old creds stop working immediately. No
+container restart. Tell the user to save the new password before they
+log out.
+
+## Recipe: "wire the Zibby MCP into my IDE"
+
+```bash
+zibby mcp install --ide claude --scope project       # or --ide cursor / codex
+# reload the IDE; agent can now call zibby_workflow_* / zibby_app_* tools directly
+```
+
+For headless / shared configs, pass `--pat zby_xxx` instead of using
+the session token.
+
+---
+
+## Slash commands available in this repo
+
+Every Zibby slash command starts with `/zibby-`:
+
+**Workflows:** `/zibby-new-workflow`, `/zibby-add-node`, `/zibby-add-skill`,
+`/zibby-validate-workflow`, `/zibby-deploy`, `/zibby-trigger`,
+`/zibby-list`, `/zibby-tail`, `/zibby-debug`, `/zibby-delete`,
+`/zibby-static-ip`, `/zibby-workflow-env`
+
+**Apps:** `/zibby-deploy-app`, `/zibby-app-list`, `/zibby-app-status`,
+`/zibby-app-logs`, `/zibby-app-restart`, `/zibby-app-upgrade`,
+`/zibby-app-destroy`, `/zibby-set-auth`, `/zibby-app-env`
+
+**Tests + memory:** `/zibby-test-write`, `/zibby-test-run`,
+`/zibby-test-debug`, `/zibby-test-generate`, `/zibby-memory-stats`,
+`/zibby-memory-cost`, `/zibby-memory-pull`,
+`/zibby-memory-remote-use-hosted`
+
+**Auth + setup:** `/zibby-login`, `/zibby-status`, `/zibby-mcp-install`
+
+Each slash command is a self-contained recipe — invoke it and the
+agent follows the steps inside. Live files: `.claude/commands/zibby-*.md`.
+
+---
+
+## Canonical docs
+
+Single source of truth — when in doubt, fetch:
+
+- Workflows: https://docs.zibby.app/workflows
+- Apps: https://docs.zibby.app/apps
+- agent-ops daemon: https://docs.zibby.app/apps/agent-ops
+- CLI reference: https://docs.zibby.app/cli
+- MCP server: https://docs.zibby.app/cli/mcp
+
+These notes are a snapshot. Docs are kept current.
+<!-- END ZIBBY -->