wao 0.41.3 → 0.41.5

package/esm/workspace/.claude/rules/testing.md

@@ -1,257 +0,0 @@
----
-paths:
-  - "test/**/*.js"
----
-
-# Testing Rules
-
-For full SDK API reference, read `docs/wao-sdk.md`.
-
-## Framework
-
-Node.js built-in test runner (`node:test`). No external test framework needed.
-
-```js
-import assert from "assert"
-import { describe, it, before, after } from "node:test"
-```
-
-## In-Memory AOS Testing (legacynet units)
-
-Runs AOS WASM directly in Node.js — no server, no Erlang. Instant. Best for unit testing AOS script logic.
-
-```js
-import { AO, acc } from "wao/test"
-import { readFileSync } from "fs"
-import { resolve } from "path"
-
-const src_data = readFileSync(
-  resolve(import.meta.dirname, "../src/file.lua"),
-  "utf8"
-)
-
-describe("My AOS Script", function () {
-  it("should work", async () => {
-    const ao = await new AO().init(acc[0])
-    const { p, pid } = await ao.deploy({ src_data })
-
-    // dry-run (read-only, no state change)
-    const result = await p.d("ActionName", false)
-
-    // message (mutates state)
-    const result2 = await p.m("ActionName", false)
-
-    // message with extra tags
-    const result3 = await p.m("ActionName", { SomeTag: "value" }, false)
-  })
-})
-```
-
-### Process Handle Shorthand
-
-- `p.d("Action", false)` — dry-run, returns Data string
-- `p.m("Action", false)` — send message, returns Data string
-- `p.m("Action", { Tag: "val" }, false)` — send message with tags
-- `p.v("State")` — get Lua variable as JSON
-- `p.v("Table.items[1]")` — nested access
-
-### get/check Patterns
-
-```js
-// get: extract output
-await p.d("Get", false)                           // Data as string
-await p.d("Get", { get: { data: true, json: true } }) // Data as parsed JSON
-await p.msg("Inc", { get: "Status" })              // Specific tag value
-await p.d("Get", { get: { from: "pid", json: true } }) // Filter by sender
-
-// check: validate response
-await p.msg("Inc", { check: { Status: "ok" } })    // Tag value check
-await p.msg("Inc", { check: /Success/ })            // Regex match
-```
-
-## HyperBEAM AOS Testing (integration)
-
-Spawns a real Erlang HyperBEAM node. AOS processes run on the HyperBEAM stack via `genesis-wasm` device. Messages go through HTTP with slot-based scheduling. Best for integration testing the full production stack.
-
-### Raw HyperBEAM API
-
-```js
-import { HyperBEAM } from "wao/test"
-
-describe("HyperBEAM", function () {
-  let hbeam, hb
-
-  before(async () => {
-    hbeam = await new HyperBEAM({ reset: true }).ready()
-    hb = hbeam.hb
-  })
-
-  after(async () => hbeam.kill())
-
-  it("should work", async () => {
-    await hb.post({ path: "/~meta@1.0/info", key: "value" })
-    const { out } = await hb.get({ path: "/~meta@1.0/info" })
-  })
-})
-```
-
-### HyperBEAM Spawn Patterns
-
-```js
-// Basic spawn (default device)
-const { pid } = await hb.spawn({})
-
-// Legacy AOS (genesis-wasm CU)
-const { pid } = await hb.spawnLegacy()
-const { pid } = await hb.spawnAOS()
-
-// Lua VM
-const { pid } = await hb.spawnLua()
-
-// Custom execution device
-const { pid } = await hb.spawn({ "execution-device": "wao@1.0" })
-```
-
-### Device Stack Testing
-
-```js
-const { pid } = await hb.spawn({
-  "execution-device": "stack@1.0",
-  "device-stack": ["wao@1.0", "patch@1.0"],
-  "patch-from": "/results",
-  "patch-to": "/cache",
-})
-const { slot } = await hb.schedule({ pid })
-const result = await hb.compute({ pid, slot, path: "/cache/key" })
-```
-
-### AOS on HyperBEAM (via HB client)
-
-```js
-import { HyperBEAM, HB } from "wao/test"
-
-let hbeam = await new HyperBEAM({ reset: true, genesis_wasm: true }).ready()
-let hb = await new HB({ url: hbeam.url }).init(jwk)
-
-// Spawn AOS process on HyperBEAM
-const { pid } = await hb.spawnLegacy()
-
-// Send message (slot-based scheduling)
-const { slot } = await hb.scheduleLegacy({ pid, action: "Inc", data })
-
-// Get result
-const result = await hb.computeLegacy({ pid, slot })
-
-hbeam.kill()
-```
-
-### AOS class routed through HyperBEAM
-
-```js
-import { AO } from "wao"
-import { HyperBEAM } from "wao/test"
-
-let hbeam = await new HyperBEAM({ reset: true, genesis_wasm: true }).ready()
-let ao = await new AO({ hb: hbeam.url }).init(hbeam.jwk)
-
-const { pid, p } = await ao.deploy({ src_data })
-await p.m("Inc")
-const result = await p.d("Get")
-
-hbeam.kill()
-```
-
-Always call `hbeam.kill()` in `after()` to clean up the HyperBEAM Erlang process.
-
-## Multi-User Testing
-
-Share memory between AO instances to simulate multiple users:
-
-```js
-const ao1 = await new AO().init(acc[0])
-const { p, pid } = await ao1.deploy({ src_data })
-
-// second user shares the same memory
-const ao2 = await new AO({ mem: ao1.mem }).init(acc[1])
-const p2 = ao2.p(pid)
-await p2.m("Transfer", { Recipient: acc[0].addr, Quantity: "100" })
-```
-
-## Payment Testing
-
-### Simple Pay
-
-```js
-const hbeam = await new HyperBEAM({
-  simple_pay: true,
-  simple_pay_price: 2,
-  operator: HyperBEAM.OPERATOR,
-}).ready()
-
-// Topup user
-await operator.hb.p("/~simple-pay@1.0/topup", { amount: 15, recipient: user.addr })
-const bal = await user.hb.p("/~simple-pay@1.0/balance")
-```
-
-### FAFF (Access Control)
-
-```js
-const hbeam = await new HyperBEAM({
-  faff: [HyperBEAM.OPERATOR, allowedAddr],
-}).ready()
-await assert.rejects(disallowed.hb.p(...))  // rejected
-```
-
-### P4 Payment
-
-```js
-const hbeam = await new HyperBEAM({
-  p4_lua: {
-    processor: { body: ledgerScript, name: "ledger.lua" },
-    client: { body: clientScript, name: "client.lua" },
-    admin: addr,
-    balance: { [addr]: 1000 },
-  },
-}).ready()
-```
-
-## Cron Testing
-
-```js
-const { body: taskId } = await hb.post({
-  path: "/~cron@1.0/every",
-  "cron-path": `/~wao@1.0/cron`,
-  interval: "1000-milliseconds",
-  target: pid,
-})
-await wait(3000)
-await hb.post({ path: "/~cron@1.0/stop", task: taskId })
-```
-
-## ANS-104 Format Testing
-
-```js
-const hb = new HB({ url: hbeam.url, format: "ans104" })
-const { pid } = await hb.spawn({
-  "execution-device": "wao@1.0",
-  "Data-Protocol": "ao",
-  Variant: "ao.WDB.1",
-})
-```
-
-## Port Cleanup
-
-Before HyperBEAM tests, kill stale processes:
-
-```bash
-pkill -f beam.smp 2>/dev/null || true
-lsof -ti :10000-10010 | xargs -r kill -9 2>/dev/null || true
-```
-
-## Running Tests
-
-```bash
-yarn test test/aos.test.js         # in-memory AOS (fast unit tests)
-yarn test test/hyperbeam.test.js   # HyperBEAM (integration tests)
-yarn test                          # all test files
-```

package/esm/workspace/.claude/settings.json

@@ -1,109 +0,0 @@
-{
-  "env": {
-    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
-  },
-  "permissions": {
-    "allow": [
-      "Bash(yarn test *)",
-      "Bash(yarn deploy *)",
-      "Bash(node *)",
-      "Bash(pkill -f beam.smp *)",
-      "Bash(lsof *)",
-      "Bash(cd HyperBEAM && rebar3 compile)",
-      "Bash(cd HyperBEAM && rebar3 as genesis_wasm compile)",
-      "Bash(cd HyperBEAM && rebar3 eunit *)",
-      "Bash(cd frontend && npm *)",
-      "Bash(cd frontend && npx playwright *)"
-    ],
-    "deny": [
-      "Bash(rm -rf *)",
-      "Edit(.wallet.json)",
-      "Edit(.env*)"
-    ]
-  },
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty'); if echo \"$CMD\" | grep -qE 'rm\\s+-rf\\s+src/'; then echo 'Blocked: destructive command on src/' >&2; exit 2; fi; exit 0"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // empty'); if echo \"$FILE\" | grep -qE '\\.(lua|js)$'; then echo \"File modified: $FILE — run yarn test to verify\" >&2; fi; exit 0"
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "MSG='WAO context restored after compaction: Send().receive() does NOT work on genesis-wasm — use fire-and-forget + separate AOS scripts. Action tags must be uppercase. Always kill stale beam.smp before HyperBEAM tests. Always call hbeam.kill() in after(). Read docs/ for full API references: wao-sdk.md (JS), aos-lua.md (Lua), hyperbeam-devices.md (devices), hyperbeam-dev.md (Erlang), debug.md (troubleshooting). Dashboard: yarn start (API :3333 + Vite :5174). MCP: get_progress / open_dashboard.'; if [ -f tasks.json ]; then FEATURE=$(cat tasks.json | jq -r '.feature // \"unknown\"'); STEP=$(cat tasks.json | jq -r '.current_step // 0'); PENDING=$(cat tasks.json | jq '[.tasks[] | select(.status != \"done\")] | length'); MSG=\"$MSG BUILD STATE: \\\"$FEATURE\\\" — step $STEP, $PENDING tasks remaining.\"; fi; echo \"$MSG\""
-          }
-        ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "if [ -f tasks.json ] && [ -f plan.md ]; then STEP=$(cat tasks.json | jq -r '.current_step // 0'); PENDING=$(cat tasks.json | jq '[.tasks[] | select(.status != \"done\")] | length'); FEATURE=$(cat tasks.json | jq -r '.feature // \"unknown\"'); echo \"BUILD RESUME: \\\"$FEATURE\\\" has $PENDING remaining tasks (current_step: $STEP). Read tasks.json and resume /build from the first pending task.\"; else echo 'NO ACTIVE BUILD: Run /build <feature> to start a new build workflow.'; fi"
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); TASK=$(echo \"$INPUT\" | jq -r '.task.subject // empty'); if echo \"$TASK\" | grep -qiE '(build|implement|add|create|fix|update)'; then echo '=== Unit tests ===' >&2; cd \"$(pwd)\" && yarn test 2>&1 | tail -5; R1=$?; R2=0; R3=0; if command -v erl >/dev/null 2>&1 && ls test/*.test.js >/dev/null 2>&1; then echo '=== HyperBEAM integration ===' >&2; yarn test 2>&1 | tail -5; R2=$?; fi; if [ -d frontend ]; then echo '=== Frontend tests ===' >&2; cd frontend && npm run test:unit 2>&1 | tail -5; R3=$?; cd ..; fi; if [ $R1 -ne 0 ] || [ $R2 -ne 0 ] || [ $R3 -ne 0 ]; then echo 'BLOCKED: Tests are failing. Fix before marking complete.' >&2; exit 2; fi; fi; exit 0"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); REASON=$(echo \"$INPUT\" | jq -r '.reason // empty'); if [ \"$REASON\" = \"user\" ]; then exit 0; fi; echo 'Check: are all tasks completed and tests passing?' >&2; exit 0"
-          }
-        ]
-      }
-    ],
-    "Notification": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); MSG=$(echo \"$INPUT\" | jq -r '.message // empty'); echo \"$MSG\" >&2; exit 0"
-          }
-        ]
-      }
-    ],
-    "TeammateIdle": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "INPUT=$(cat); echo 'Before going idle: verify all assigned tasks are done, tests pass, and no stale beam.smp processes are running.' >&2; exit 0"
-          }
-        ]
-      }
-    ]
-  },
-  "teammateMode": "in-process",
-  "teammatePermissionMode": "dangerously-skip-permissions"
-}

package/esm/workspace/.claude/skills/build/SKILL.md

@@ -1,214 +0,0 @@
----
-name: build
-description: "Full build workflow — plan, build, test, validate. Manages tasks.json throughout every step. Use when user says 'build this', 'start building', 'implement this feature', or 'make this'. Not for single-file fixes — use /build-aos, /build-device, or /build-module directly."
-argument-hint: "<feature-description>"
-disable-model-invocation: true
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-Full build orchestrator. Sequences through plan → build → test → validate → README, managing `tasks.json` throughout.
-
-## Performance Notes
-- Take your time on each task — quality is more important than speed
-- Read the relevant docs thoroughly before writing code
-- Do not skip validation steps even if they seem redundant
-- When iterating on test failures, identify the root cause before changing code
-
-## Examples
-
-### Start a new build
-```
-/build A counter app that tracks clicks per user, with a leaderboard showing top 10
-```
-
-### Resume an interrupted build
-```
-/build
-```
-(Automatically detects tasks.json and resumes)
-
-## Steps
-
-### 1. Check for existing plan (resume support)
-
-Read `plan.md` and `tasks.json` at the project root. If both exist and tasks.json has `"current_step"`, resume:
-
-1. Find the first task with `"status": "in_progress"` — resume debugging that task immediately.
-2. If no `in_progress` task, find the first task with `"status": "pending"` — start it.
-3. If ALL tasks are `"done"`, **re-verify every test task** by running its tests:
-   - `aos-test` → `yarn test <files>`
-   - `aos-integration` → `yarn test <files>`
-   - `device` → `cd $HB_DIR && rebar3 eunit --module=<module>`
-   - `device-integration` → `yarn test <files>`
-   - `frontend-test` → `cd frontend && npm run test:unit`
-   - `frontend-integration` → `cd frontend && npm run test:e2e`
-   - `validate` → run all validation gates
-
-   If any test task fails, set that task back to `"in_progress"` in tasks.json and resume debugging it. Do NOT skip over failing tests just because the task was previously marked done.
-
-If no plan exists, proceed to step 2.
-
-### 2. Plan
-
-**Enter plan mode using the `EnterPlanMode` tool immediately.** Do not skip this step.
-
-If `$ARGUMENTS` is provided, use it as the feature description. If `$ARGUMENTS` is empty, ask the user what they want to build — but only this one question, then proceed immediately.
-
-While in plan mode, read `.claude/skills/plan/SKILL.md` and execute ALL of its steps:
-1. Ask the user which tracks to build (AOS / Custom Modules / Device / Frontend)
-2. Read the relevant docs for the selected tracks
-3. Design the feature
-4. Write `plan.md` and `tasks.json` at the project root
-
-Once `plan.md` and `tasks.json` are written, **use `ExitPlanMode` to present the plan for user approval.** This exits plan mode and asks the user to approve before building begins.
-
-After the user approves, update `plan.md` status to `APPROVED` and proceed to step 3.
-
-### 3. Clean up sample files
-
-Remove the starter reference files that ship with the template. These exist so users can explore the project before building, but should be cleared before a real build:
-
-```bash
-rm -f src/counter.lua test/aos.test.js test/hyperbeam.test.js
-```
-
-Also remove any other sample files (`src/registry.lua`, `src/token.lua`, `test/registry.test.js`, `test/token.test.js`) if they exist:
-
-```bash
-rm -f src/registry.lua src/token.lua test/registry.test.js test/token.test.js
-```
-
-### 4. Verify prerequisites
-
-Before starting the build loop, check which tracks are selected and verify their prerequisites.
-
-**Device track or integration tests** — require HyperBEAM configured via `.env.hyperbeam`:
-
-```bash
-grep '^CWD=' .env.hyperbeam 2>/dev/null | cut -d= -f2-
-```
-
-If the plan includes `device`, `device-integration`, `aos-integration`, `module-lua`, `module-wasm`, or `module-test` tasks, verify:
-
-1. `.env.hyperbeam` exists and has a `CWD` value
-2. The `CWD` path points to a valid HyperBEAM directory (`$CWD/src` exists)
-3. `rebar3` is available (for device compilation)
-
-If any check fails, **stop and tell the user**:
-
-> Device/integration tasks require HyperBEAM. Configure `.env.hyperbeam`:
-> ```bash
-> echo "CWD=/path/to/your/HyperBEAM" >> .env.hyperbeam
-> ```
->
-> Or re-run `npx wao create` and choose option 1 (clone) or 2 (link).
-
-Only proceed once all prerequisites are met.
-
-### 5. Build loop
-
-For each task in `tasks.json` (in `id` order):
-
-a. Update the task status to `"in_progress"` in `tasks.json` and update `current_step`.
-
-b. Read the skill file for this task's type and follow its instructions. The mapping from task type to skill file:
-
-| Task type | Read and follow |
-|-----------|-----------------|
-| `aos` | `.claude/skills/build-aos/SKILL.md` |
-| `aos-test` | `.claude/skills/build-aos/SKILL.md` |
-| `aos-integration` | `.claude/skills/test-hb/SKILL.md` |
-| `module-lua` | `.claude/skills/build-module/SKILL.md` |
-| `module-wasm` | `.claude/skills/build-module/SKILL.md` |
-| `module-test` | `.claude/skills/build-module/SKILL.md` |
-| `device` | `.claude/skills/build-device/SKILL.md` (eunit tests are inline — same file) |
-| `device-integration` | `.claude/skills/test-device/SKILL.md` |
-| `frontend` | `.claude/skills/build-frontend/SKILL.md` |
-| `frontend-test` | `.claude/skills/build-frontend/SKILL.md` |
-| `frontend-integration` | `.claude/skills/test-e2e/SKILL.md` |
-| `readme` | `.claude/skills/readme/SKILL.md` |
-| `validate` | `.claude/skills/validate/SKILL.md` |
-
-c. Follow the skill's instructions for this task, using the task `id` as context.
-
-d. After completing, verify the task's `done_when` criteria are met:
-   - For test tasks: tests must pass 100%
-   - For build tasks: files must exist and compile/load without errors
-
-e. If the criteria are met, update the task status to `"done"` in `tasks.json`.
-
-f. **If tests fail, keep debugging.** Do not stop. On each iteration:
-   1. Read the full error output — stack traces, assertion messages, log lines
-   2. Identify the root cause (wrong logic, missing handler, bad import, timing issue, etc.)
-   3. Fix the code — not the test, unless the test itself has a bug
-   4. Re-run the failing test file specifically (faster feedback than full suite)
-   5. If the same error persists after 3 different fix attempts, step back:
-      - Re-read the relevant docs (AOS patterns, HyperBEAM device protocol, etc.)
-      - Check if the plan itself has a wrong assumption
-      - Try a completely different approach
-   6. Continue iterating until all tests pass — there is no retry limit
-
-g. Only escalate to the user if:
-   - The failure is environmental (port conflict, missing binary, permissions)
-   - The test requires user input (wallet, external service URL)
-   - You've tried 10+ iterations with no progress on the same error
-
-h. Move to the next task.
-
-### 6. README
-
-After all build and test tasks are done, read `.claude/skills/readme/SKILL.md` and follow its instructions to generate README.md.
-
-### 7. Final validation
-
-Read `.claude/skills/validate/SKILL.md` and follow its instructions to run all validation gates.
-
-### 8. Summary
-
-Report final results:
-
-```
-## Build Complete
-
-Feature: {feature name}
-Tracks: {AOS, Custom Modules, Device, Frontend}
-
-| Task | Status |
-|------|--------|
-| ... | done/skipped/failed |
-
-Overall: PASS / FAIL
-```
-
-## Failure handling
-
-- **Test failures are expected.** The build loop is: write code → run tests → read failures → fix → re-run. This is the core loop — never skip it, never give up early.
-- If a skill exits with test failures, read the full output, diagnose the root cause, fix the code (not the test), and re-run. Keep iterating until 100% pass.
-- If a skill cannot be dispatched (unknown type), skip and warn.
-- If the user interrupts, save current state to tasks.json so the next session can resume.
-
-## Rollback
-
-If a task corrupts working code:
-1. Check git status for what changed
-2. Restore the last working version: `git checkout -- <file>` for specific files
-3. Re-run tests to confirm the rollback worked
-4. Update the task status back to `pending` in tasks.json
-5. Retry with a different approach
-
-Never force a task to `done` status with failing tests. The TaskCompleted hook will block it anyway.
-
-## Troubleshooting
-
-### Build stalls on a single task
-- Check if it's a test failure loop — read the last test output
-- If the same error persists after 3 different fix attempts, step back and reconsider — the plan may have a wrong assumption
-- Run `/debug` to diagnose port/process/WASM issues
-
-### Resume doesn't pick up the right task
-- Read `tasks.json` directly and check `current_step` value
-- Verify task statuses — a task stuck as `in_progress` blocks progression
-
-### Permission denied on yarn test
-- Check `node --version` is 22+ (24+ recommended)
-- On Node 22, set `NODE_OPTIONS=--experimental-wasm-memory64`; on Node 24+ the flag is default-on and is rejected if passed explicitly