@zibby/cli 0.3.0 → 0.4.0

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-static-ip.md

@@ -1,10 +1,12 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-static-ip — set up dedicated outbound static IP for a workflow
 
 You are helping the user route a workflow's outbound traffic through a static IP address — needed when the workflow calls APIs that require IP allowlisting (corporate GitLab/GitHub Enterprise, internal SaaS, firewalls).
 
 Canonical docs: **https://docs.zibby.app/workflows/egress**
 
+> Note: the `--dedicated-ip` flag lives on the legacy alias `zibby deploy <name>`, NOT on `zibby workflow deploy <name>`. The two share a handler, but only `zibby deploy` exposes this flag in `--help`.
+
 ## What "static IP" means here
 
 By default, workflow tasks run on Fargate and their outbound traffic exits via AWS-managed IPs that rotate. With the **dedicated egress** addon enabled, the workflow's outbound traffic is routed through a Zibby-managed proxy whose IP is pinned and customer-allowlistable.
@@ -23,19 +25,19 @@ Two pieces:
 
 2. **Check current state:**
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip status)
+   Bash(zibby deploy <name> --dedicated-ip status)
    ```
    Output tells you: addon active or inactive, this workflow currently using it or not, and the assigned IPs to publish to customers.
 
 3. **If addon is inactive — enable it** (only after explicit user confirmation):
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip enable)
+   Bash(zibby deploy <name> --dedicated-ip enable)
    ```
    This is one-time per account. After this, the addon is active for ALL workflows in the account that opt in.
 
 4. **Opt this workflow in:**
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip use)
+   Bash(zibby deploy <name> --dedicated-ip use)
    ```
    From now on, every deploy of this workflow + every triggered execution routes outbound through the static IP.
 
@@ -52,8 +54,8 @@ Two pieces:
 
 ## Reverting
 
-- `Bash(zibby workflow deploy <name> --dedicated-ip unuse)` — stop routing this workflow's egress through the static IP. Other opted-in workflows are unaffected.
-- `Bash(zibby workflow deploy <name> --dedicated-ip disable)` — disable the addon entirely (also stops billing).
+- `Bash(zibby deploy <name> --dedicated-ip unuse)` — stop routing this workflow's egress through the static IP. Other opted-in workflows are unaffected.
+- `Bash(zibby deploy <name> --dedicated-ip disable)` — disable the addon entirely (also stops billing).
 
 ## Tell the user the IPs
 

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-tail.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-tail — stream live logs from a Zibby workflow
 
 You are helping the user tail logs from a workflow execution.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-debug.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-debug — diagnose a failing Zibby test
 
 You are helping the user figure out why a test failed.
@@ -34,7 +34,7 @@ Spec ambiguity is the most common cause. If the spec says "click the button" and
 ```
 Bash(zibby test test-specs/<name>.txt --verbose)        # info-level logs
 Bash(zibby test test-specs/<name>.txt --debug)          # all logs, lots
-Bash(zibby test test-specs/<name>.txt --headed)         # see the browser
+Bash(zibby test test-specs/<name>.txt)                  # default is headed — drop --headless to watch the browser
 ```
 
 ### 5. Re-execute one node from a prior session

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-generate.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-generate — generate test specs from a Jira ticket / requirements
 
 You are helping the user auto-generate test specs from a ticket description (Jira) or a free-text requirements doc. Zibby's `generate` command runs the configured AI agent against the codebase + ticket and produces `.txt` specs in `test-specs/`.

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

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- 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.
@@ -40,9 +40,10 @@ Canonical docs: **https://docs.zibby.app/tests/running**
 - `--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. Re-run with `--headed` once to refresh, then `--headless`.
+- **"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/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-write.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- 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.

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

@@ -1,11 +1,11 @@
-<!-- zibby-template-version: 1 -->
+<!-- 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/workflows/triggering**
+Canonical docs: **https://docs.zibby.app/cloud/triggering**
 
 ## Steps
 
@@ -13,15 +13,19 @@ Canonical docs: **https://docs.zibby.app/workflows/triggering**
 
 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:**
+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"}'
-   ```
-   Or use `-p key=value` for individual params (more shell-friendly than embedded JSON):
-   ```
    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

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

@@ -1,46 +1,106 @@
-<!-- zibby-template-version: 2 -->
+<!-- zibby-template-version: 4 -->
 ---
-description: Help the user build, test, and deploy Zibby agent workflows
+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 agent workflows
+# Zibby — workflows + tests
 
-This project contains one or more **Zibby workflows** — graphs of AI-agent-driven steps that run inside an ECS Fargate sandbox in Zibby Cloud.
+This project uses **Zibby**. Two surfaces share `.zibby.config.mjs` at the project root.
 
-## Anatomy
+## Workflows
+
+A graph of AI-agent-driven steps that runs inside an ECS Fargate sandbox.
 
 ```
 <workflowsBasePath>/<workflow-name>/
-├── workflow.json    # name, entryClass, triggers, schemas
+├── workflow.json    # name, entryClass, triggers, schemas (manifest)
 ├── graph.mjs        # exports the graph (nodes + edges)
-├── nodes/           # one .mjs file per node
+├── 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
+### Common dev loop
 
 ```
-zibby workflow run <name>       # one-shot local run (mirrors trigger flags)
-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 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
 ```
 
-## Adding a new node
+`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**
@@ -49,8 +109,11 @@ 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/dist/templates/zibby-workflow-claude/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": 3,
+  "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": {
@@ -16,6 +16,10 @@
         ".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"
       ],

package/dist/utils/apply-memory-sync-config.js

@@ -0,0 +1 @@
+var m=[null,void 0,"","none","off",!1],f="hosted",d=["aws://","gs://","https://","http://","file://"];function y(r){if(!r||typeof r!="object")return{ok:!0,kind:"noop"};let e=r.remote;return m.includes(e)?{ok:!0,kind:"noop"}:typeof e!="string"?{ok:!1,error:`memorySync.remote must be null or a string, got ${typeof e}`}:e===f?{ok:!0,kind:"hosted"}:d.some(n=>e.startsWith(n))?{ok:!0,kind:"byo",remote:e}:{ok:!1,error:`memorySync.remote = ${JSON.stringify(e)} is not recognized. Use null, 'hosted', or a URL beginning with one of: ${d.join(" / ")}.`}}async function c({cwd:r,projectId:e,block:n,memoryApi:t,hostedSetup:i,getSessionToken:s,logger:u=console}){let o=y(n);if(!o.ok)return u.warn?.(`[memory-sync] config invalid: ${o.error}`),{action:"error",reason:o.error};if(o.kind==="noop")return{action:"skipped",reason:"memorySync.remote not set"};if(o.kind==="byo")return t?.memoryRemoteAdd?t.memoryRemoteAdd(r,o.remote)?{action:"byo",remote:o.remote}:{action:"error",reason:"memoryRemoteAdd returned false (memory DB not initialized?)"}:{action:"error",reason:"@zibby/ui-memory not loaded"};if(o.kind==="hosted"){if(typeof s=="function"&&!s())return{action:"pending-login",reason:'memorySync.remote = "hosted" but the user is not logged in. Run `zibby login` then `zibby memory remote use --hosted`.'};if(typeof i!="function")return{action:"error",reason:"hostedSetup function not provided"};try{return await i({cwd:r,projectId:e}),{action:"hosted"}}catch(a){return{action:"error",reason:`hosted setup failed: ${a.message}`}}}return{action:"error",reason:`unhandled kind: ${o.kind}`}}export{c as applyMemorySyncConfig,y as validateMemorySyncConfig};

package/dist/utils/hosted-memory-sync.js

@@ -0,0 +1 @@
+import{readFileSync as y,writeFileSync as f,existsSync as d,mkdirSync as S,chmodSync as w}from"fs";import{join as u}from"path";var x="memory-sync.json",C="memory-sync-creds.json",h=120*1e3;function c(r){let e=u(r,".zibby");return{dir:e,config:u(e,x),creds:u(e,C)}}function p(r){let{config:e}=c(r);if(!d(e))return null;try{let t=JSON.parse(y(e,"utf-8"));return t.mode!=="hosted"?null:t}catch{return null}}function K(r){return!!p(r)}function T(r,e){let{dir:t,config:n}=c(r);S(t,{recursive:!0}),f(n,JSON.stringify({mode:"hosted",projectId:e.projectId,bucket:e.bucket,prefix:e.prefix,doltUrl:e.doltUrl,configuredAt:new Date().toISOString()},null,2),"utf-8")}function b(r){let{config:e,creds:t}=c(r);for(let n of[e,t])if(d(n))try{f(n,"")}catch{}}function l(r){let{creds:e}=c(r);if(!d(e))return null;try{let t=JSON.parse(y(e,"utf-8"));return!t?.accessKeyId||!t?.secretAccessKey||!t?.sessionToken?null:t}catch{return null}}function m(r,e){let{dir:t,creds:n}=c(r);S(t,{recursive:!0}),f(n,JSON.stringify(e,null,2),"utf-8");try{w(n,384)}catch{}}function E(r){return r?.expiration?new Date(r.expiration).getTime()-Date.now()<h:!0}async function I({cwd:r,projectId:e,apiUrl:t,sessionToken:n,fetch:s=globalThis.fetch}){if(!e)throw new Error("refreshCredentials: projectId required");if(!t)throw new Error("refreshCredentials: apiUrl required");if(!n)throw new Error("refreshCredentials: sessionToken required (run `zibby login`)");let i=`${String(t).replace(/\/+$/,"")}/memory/sync-credentials`,a=await s(i,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${n}`},body:JSON.stringify({projectId:e})});if(!a.ok){let g=await a.text().catch(()=>"");throw new Error(`memory-sync credentials request failed (${a.status}): ${g||"no body"}`)}let o=await a.json();if(!o?.accessKeyId||!o?.secretAccessKey||!o?.sessionToken)throw new Error("memory-sync credentials response missing required fields");return m(r,{accessKeyId:o.accessKeyId,secretAccessKey:o.secretAccessKey,sessionToken:o.sessionToken,expiration:o.expiration||null,refreshedAt:new Date().toISOString()}),l(r)}async function A({cwd:r,apiUrl:e,sessionToken:t,fetch:n}){let s=p(r);if(!s)return null;let i=l(r);return(!i||E(i))&&(i=await I({cwd:r,projectId:s.projectId,apiUrl:e,sessionToken:t,fetch:n})),i}async function N({cwd:r,apiUrl:e,sessionToken:t,fetch:n}){let s=await A({cwd:r,apiUrl:e,sessionToken:t,fetch:n});return s?{AWS_ACCESS_KEY_ID:s.accessKeyId,AWS_SECRET_ACCESS_KEY:s.secretAccessKey,AWS_SESSION_TOKEN:s.sessionToken,AWS_REGION:process.env.AWS_REGION||"ap-southeast-2"}:null}var j={paths:c,readCreds:l,writeCreds:m,isExpiringSoon:E,REFRESH_HEADROOM_MS:h};export{j as __testing,N as buildDoltEnv,b as clearConfig,A as getActiveCredentials,K as isHosted,p as readConfig,I as refreshCredentials,T as writeConfig};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Zibby CLI - Test automation generator and runner",
   "type": "module",
   "bin": {