wao 0.41.3 → 0.41.5

package/cjs/workspace/.claude/skills/build-module/SKILL.md

@@ -1,281 +0,0 @@
----
-name: build-module
-description: "Build custom WASM64 (Rust) or standalone Lua modules with HyperBEAM integration tests. Iterates until all tests pass 100%. Use when user says 'build the module', 'write the WASM', 'custom Lua module', or 'implement the module'. Not for AOS scripts — use /build-aos."
-argument-hint: "<task-id>"
-disable-model-invocation: true
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-Build custom execution modules (WASM64 Rust or standalone Lua) and HyperBEAM integration tests for a task. Iterates until all tests pass 100%.
-
-## Resolve HyperBEAM path
-
-Read `.env.hyperbeam` and extract the `CWD` value:
-
-```bash
-grep '^CWD=' .env.hyperbeam 2>/dev/null | cut -d= -f2-
-```
-
-If `.env.hyperbeam` doesn't exist or has no `CWD`, **STOP immediately** and tell the user:
-
-> No HyperBEAM configured. Custom module tests require a HyperBEAM installation.
->
-> Set it up by adding a `CWD` entry to `.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).
-
-## Steps
-
-1. Read `tasks.json` and find the task matching `$ARGUMENTS` (task id). Update its status to `"in_progress"`.
-
-2. Read `plan.md` for the module specifications:
-   - Module type: WASM64 (Rust) or standalone Lua
-   - Actions to handle
-   - Response format
-   - State management
-
-3. Read the relevant docs:
-   - Standalone Lua → `docs/aos-lua.md` (custom Lua section) and the tutorial at `docs/docs/pages/tutorials/custom-lua.mdx`
-   - WASM64 Rust → the tutorial at `docs/docs/pages/tutorials/rust-wasm64.mdx`
-   - SDK patterns → `docs/wao-sdk.md` (HB class: `cacheBinary`, `cacheScript`, `spawnAOS`, `scheduleAOS`, `computeAOS`, `scheduleLua`, `computeLua`)
-
-4. **If the module type is `module-lua`** — write a standalone Lua module:
-
-   Write the module in `custom-lua/{name}.lua`:
-
-   ```lua
-   -- {name}.lua - Custom Lua module for lua@5.3a device
-   -- Standalone: no AOS boot code, no Handlers framework.
-
-   local state = {}
-
-   local function intstr(n)
-     if n == math.floor(n) then return string.format("%d", n) end
-     return tostring(n)
-   end
-
-   function compute(base, req, opts)
-     local action = nil
-     if type(req) == "table" then
-       if type(req.body) == "table" then
-         action = req.body.Action or req.body.action
-       end
-       if not action then
-         action = req.Action or req.action
-       end
-     end
-
-     -- Handle actions
-     if action == "MyAction" then
-       -- Implementation here
-     end
-
-     base.results = {
-       outbox = {
-         ["1"] = { data = "result" }
-       },
-       output = ""
-     }
-     return base
-   end
-   ```
-
-   Key patterns:
-   - Entry point is `compute(base, req, opts)` — NOT `Handlers.add`
-   - Action is in `req.body.Action` or `req.body.action` (HTTP lowercases headers)
-   - Response goes in `base.results.outbox` — string-keyed table
-   - Module-level variables persist between compute calls (Lua VM state is saved)
-   - No AOS framework available — no `Handlers`, `ao.send`, `msg.reply`
-
-5. **If the module type is `module-wasm`** — write a Rust WASM64 module:
-
-   Write the module in `custom-wasm/src/lib.rs`:
-
-   ```rust
-   #![no_std]
-   #![no_main]
-
-   use core::panic::PanicInfo;
-
-   #[panic_handler]
-   fn panic(_info: &PanicInfo) -> ! { loop {} }
-
-   static mut BUMP: usize = 4096;
-
-   #[no_mangle]
-   pub extern "C" fn malloc(size: usize) -> usize {
-       unsafe { let ptr = BUMP; BUMP += size; ptr }
-   }
-
-   #[no_mangle]
-   pub extern "C" fn free(_ptr: usize) -> usize { 0 }
-
-   // Manual byte copy (WAMR rejects memory.copy)
-   unsafe fn copy_bytes(dst: *mut u8, src: *const u8, len: usize) {
-       let mut i = 0;
-       while i < len { *dst.add(i) = *src.add(i); i += 1; }
-   }
-
-   #[no_mangle]
-   pub extern "C" fn handle(msg_ptr: usize, _proc_ptr: usize) -> usize {
-       // Parse JSON message, handle actions, return JSON response
-       // Response format: {"ok":true,"response":{"Output":{"data":""},"Messages":[{"Data":"..."}]}}
-       unsafe { /* implementation */ 0 }
-   }
-   ```
-
-   Key constraints:
-   - `#![no_std]` required — WAMR rejects `memory.copy` from std
-   - All pointers are `i64` (memory64 WASM)
-   - Must export `malloc`, `free`, `handle`
-   - Response is JSON with `Messages` array for outbox
-   - Use manual byte loops, not memcpy
-
-   Build with:
-   ```bash
-   cd custom-wasm && cargo +nightly build --target wasm64-unknown-unknown --release -Zbuild-std=core,panic_abort -Zbuild-std-features=panic_immediate_abort
-   ```
-
-6. **If the task type is `module-test`** — write HyperBEAM integration tests:
-
-   **For Lua modules** — write `test/{name}-module.test.js`:
-
-   ```js
-   import { describe, it, before, after } from "node:test"
-   import assert from "node:assert"
-   import { readFileSync } from "node:fs"
-   import { resolve } from "node:path"
-   import { HyperBEAM } from "wao/test"
-   import HB from "wao/hb"
-
-   const luaPath = resolve(import.meta.dirname, "../custom-lua/{name}.lua")
-
-   async function spawnCustomLua(hb, moduleId) {
-     return hb.spawn({
-       "data-protocol": "ao",
-       variant: "ao.TN.1",
-       module: moduleId,
-       "execution-device": "lua@5.3a",
-       "push-device": "push@1.0",
-       "patch-from": "/results/outbox",
-     })
-   }
-
-   describe("{name} custom Lua module", () => {
-     let hbeam, hb, moduleId
-
-     before(async () => {
-       hbeam = await new HyperBEAM({ reset: true }).ready()
-       hb = new HB({ url: hbeam.url })
-       await hb.init(hbeam.jwk)
-       const luaSrc = readFileSync(luaPath, "utf-8")
-       moduleId = await hb.cacheScript(luaSrc, "application/lua")
-     })
-
-     after(async () => { if (hbeam) hbeam.kill() })
-
-     it("should spawn process with module", async () => {
-       const { pid } = await spawnCustomLua(hb, moduleId)
-       assert.ok(pid)
-     })
-
-     // Test all actions, state persistence, error handling
-   })
-   ```
-
-   **For WASM modules** — write `test/{name}-module.test.js`:
-
-   ```js
-   import { describe, it, before, after } from "node:test"
-   import assert from "node:assert"
-   import { readFileSync } from "node:fs"
-   import { resolve } from "node:path"
-   import { HyperBEAM } from "wao/test"
-   import HB from "wao/hb"
-
-   const wasmPath = resolve(import.meta.dirname,
-     "../custom-wasm/target/wasm64-unknown-unknown/release/custom_wasm.wasm")
-
-   describe("{name} custom WASM64 module", () => {
-     let hbeam, hb
-
-     before(async () => {
-       hbeam = await new HyperBEAM({ reset: true }).ready()
-       hb = new HB({ url: hbeam.url })
-       await hb.init(hbeam.jwk)
-     })
-
-     after(async () => { if (hbeam) hbeam.kill() })
-
-     it("should cache and spawn", async () => {
-       const wasm = readFileSync(wasmPath)
-       const imageId = await hb.cacheBinary(wasm, "application/wasm")
-       const { pid } = await hb.spawnAOS({ image: imageId })
-       assert.ok(pid)
-     })
-
-     // Test all actions via scheduleAOS/computeAOS
-   })
-   ```
-
-7. Run the tests:
-
-   ```bash
-   yarn test test/{name}-module.test.js
-   ```
-
-8. If any tests fail:
-   - Read the error output carefully
-   - For WASM: check compilation output, verify no `memory.copy` instructions
-   - For Lua: check `compute` function returns `base` with `results` set
-   - Fix the code and re-run
-   - Repeat until **100% pass**
-
-9. Update the task status to `"done"` in `tasks.json`.
-
-## Iteration Protocol
-
-For each test-fix cycle:
-1. Run tests and capture FULL output
-2. Identify the FIRST failing test (fix failures in order)
-3. Classify: is the bug in module code or test code?
-4. Fix ONE issue per iteration (don't change multiple things at once)
-5. Re-run only the failing test first, then full suite
-6. If the same error persists after 3 different fix attempts, step back:
-   - Re-read the relevant docs (custom module patterns, WASM64/Lua conventions, etc.)
-   - Check if the plan itself has a wrong assumption
-   - Try a completely different approach
-7. Continue iterating until all tests pass — there is no retry limit
-
-Only escalate to the user if:
-- The failure is environmental (cargo missing, WASM build tools, port conflict)
-- The test requires user input (wallet, external service URL)
-- You've tried 10+ iterations with no progress on the same error
-
-## Troubleshooting
-
-### Lua module: "compute not found"
-- Ensure the function is named `compute` (global, not local)
-- Must take exactly 3 arguments: `(base, req, opts)`
-
-### Lua module: action is nil
-- HTTP signatures lowercase headers: check both `req.body.Action` and `req.body.action`
-- Also check `req.Action` as a fallback
-
-### WASM: "memory.copy not supported"
-- Ensure `#![no_std]` is set in lib.rs
-- Use manual byte loops, not any std function that might use memory.copy
-- Verify Cargo.toml has `crate-type = ["cdylib"]`
-
-### WASM: compilation fails with wasm64
-- Install nightly: `rustup toolchain install nightly`
-- Must use `-Zbuild-std=core,panic_abort`
-- Target is `wasm64-unknown-unknown` (not wasm32)
-
-### Tests hang on HyperBEAM spawn
-- Kill stale beam.smp processes: `pkill -f beam.smp`
-- Check `.env.hyperbeam` CWD path is valid
-- Requires Erlang/OTP 27+

package/cjs/workspace/.claude/skills/create-aos/SKILL.md

@@ -1,63 +0,0 @@
----
-name: create-aos
-description: "Scaffold a new AOS Lua script with its test file. Use when user says 'create a handler', 'new AOS script', 'scaffold a script', or 'add a handler'. Not for building full scripts with iteration — use /build-aos."
-argument-hint: "<script-name>"
-disable-model-invocation: true
----
-
-Scaffold a new AOS script with its test file.
-
-The argument `$ARGUMENTS` is the script name (required). It should be lowercase and will be used as the filename.
-
-## Steps
-
-0. Check for conflicts:
-```bash
-test -f "src/$ARGUMENTS.lua" && echo "WARNING: src/$ARGUMENTS.lua already exists" || echo "OK"
-```
-If the file exists, ask the user: overwrite or choose a different name?
-
-1. Create the Lua script file at `src/$ARGUMENTS.lua`:
-
-```lua
-local State = State or {}
-
-Handlers.add("{Name}", "{Name}", function(msg)
-  msg.reply({ Data = "{Name} handled!" })
-end)
-```
-
-Where `{Name}` is the argument with the first letter capitalized (e.g., `greeting` -> `Greeting`).
-
-2. Create the test file at `test/$ARGUMENTS.test.js`:
-
-```js
-import assert from "assert"
-import { describe, it } from "node:test"
-import { readFileSync } from "fs"
-import { resolve } from "path"
-
-import { AO, acc } from "wao/test"
-
-const src_data = readFileSync(
-  resolve(import.meta.dirname, "../src/{name}.lua"),
-  "utf8"
-)
-
-describe("{Name}", function () {
-  it("should handle {Name} action", async () => {
-    const ao = await new AO().init(acc[0])
-    const { p } = await ao.deploy({ src_data })
-    const result = await p.d("{Name}", false)
-    assert.equal(result, "{Name} handled!")
-  })
-})
-```
-
-3. Run the new test:
-
-```bash
-yarn test test/{name}.test.js
-```
-
-4. Report whether the test passes. If it fails, fix and re-run.

package/cjs/workspace/.claude/skills/create-device/SKILL.md

@@ -1,87 +0,0 @@
----
-name: create-device
-description: "Scaffold a new HyperBEAM Erlang device with its test file. Use when user says 'create a device', 'new Erlang device', 'scaffold a device', or 'add a device'. Not for building full devices with iteration — use /build-device."
-argument-hint: "<device-name>"
-disable-model-invocation: true
----
-
-Scaffold a new HyperBEAM Erlang device with its test file.
-
-The argument `$ARGUMENTS` is the device name (required). It should be lowercase and will be used as the module name.
-
-## Steps
-
-1. Read `docs/hyperbeam-dev.md` for the device template and protocol.
-
-2. Create the Erlang device at `HyperBEAM/src/dev_{name}.erl`:
-
-```erlang
--module(dev_{name}).
--export([info/3, init/3, compute/3]).
--include("include/hb.hrl").
-
--define(STATE_KEY, <<"{name}-state">>).
-
-info(_M1, _M2, _Opts) ->
-    {ok, #{
-        <<"name">> => <<"{name}">>,
-        <<"version">> => <<"1.0">>,
-        <<"endpoints">> => [<<"compute">>]
-    }}.
-
-init(M1, _M2, Opts) ->
-    State = #{},
-    {ok, ID} = hb_cache:write(State, Opts),
-    M1Updated = hb_private:set(M1, #{?STATE_KEY => ID}, Opts),
-    {ok, M1Updated}.
-
-compute(M1, M2, Opts) ->
-    Action = hb_maps:get(<<"action">>, M2, <<"default">>, Opts),
-    case Action of
-        <<"get">> -> handle_get(M1, M2, Opts);
-        _ -> {error, #{<<"status">> => 400, <<"error">> => <<"Unknown action">>}}
-    end.
-
-handle_get(M1, _M2, _Opts) ->
-    {ok, maps:merge(M1, #{<<"result">> => <<"ok">>})}.
-```
-
-Where `{name}` is the argument (e.g., `counter`).
-
-3. Create the test at `test/{name}.device.test.js`:
-
-```js
-import assert from "assert"
-import { describe, it, before, after } from "node:test"
-import { HyperBEAM, HB, acc } from "wao/test"
-
-describe("{Name} Device", function () {
-  let hbeam, hb
-
-  before(async () => {
-    hbeam = await new HyperBEAM({ reset: true }).ready()
-    hb = await new HB({ url: hbeam.url }).init(acc[0].jwk)
-  })
-
-  after(async () => hbeam.kill())
-
-  it("should respond to get", async () => {
-    const result = await hb.g("/~{name}@1.0/compute", { action: "get" })
-    assert.ok(result)
-  })
-})
-```
-
-4. Compile HyperBEAM:
-
-```bash
-cd HyperBEAM && rebar3 compile
-```
-
-5. Run the test:
-
-```bash
-yarn test test/{name}.device.test.js
-```
-
-6. Report whether compilation and test pass. If either fails, fix and re-run.

package/cjs/workspace/.claude/skills/create-module/SKILL.md

@@ -1,162 +0,0 @@
----
-name: create-module
-description: "Scaffold a new custom module (WASM64 Rust or standalone Lua) with its test file. Use when user says 'create a module', 'new custom module', 'scaffold a WASM module', or 'scaffold a Lua module'. Not for AOS scripts — use /create-aos."
-argument-hint: "<module-name> [--lua|--wasm]"
-disable-model-invocation: true
-allowed-tools: Read, Write, Bash, Grep, Glob
----
-
-Scaffold a new custom execution module with its HyperBEAM integration test.
-
-The argument `$ARGUMENTS` should include the module name and optionally `--lua` or `--wasm` to specify the type. If no type is given, ask the user.
-
-## Steps
-
-0. Check for conflicts:
-```bash
-test -f "custom-lua/$ARGUMENTS.lua" && echo "WARNING: custom-lua/$ARGUMENTS.lua already exists" || echo "OK"
-test -d "custom-wasm/" && test -f "custom-wasm/src/lib.rs" && echo "WARNING: custom-wasm/src/lib.rs already exists" || echo "OK"
-```
-If the file exists, ask the user: overwrite or choose a different name?
-
-### For Lua modules (`--lua` or default)
-
-1. Create `custom-lua/` directory if it doesn't exist:
-
-```bash
-mkdir -p custom-lua
-```
-
-2. Create `custom-lua/{name}.lua`:
-
-```lua
--- {name}.lua - Custom Lua module for lua@5.3a device
--- Standalone: no AOS boot code, no Handlers framework.
--- Implements a {Name} with basic actions.
-
-local state = {}
-
-local function intstr(n)
-  if n == math.floor(n) then return string.format("%d", n) end
-  return tostring(n)
-end
-
-function compute(base, req, opts)
-  local action = nil
-  if type(req) == "table" then
-    if type(req.body) == "table" then
-      action = req.body.Action or req.body.action
-    end
-    if not action then
-      action = req.Action or req.action
-    end
-  end
-
-  local result = "ok"
-
-  if action == "Get" then
-    -- Return current state
-    result = "state"
-  end
-
-  base.results = {
-    outbox = {
-      ["1"] = { data = result }
-    },
-    output = ""
-  }
-  return base
-end
-```
-
-3. Create `test/{name}-module.test.js`:
-
-```js
-import { describe, it, before, after } from "node:test"
-import assert from "node:assert"
-import { readFileSync } from "node:fs"
-import { resolve } from "node:path"
-import { HyperBEAM } from "wao/test"
-import HB from "wao/hb"
-
-const luaPath = resolve(import.meta.dirname, "../custom-lua/{name}.lua")
-
-async function spawnCustomLua(hb, moduleId) {
-  return hb.spawn({
-    "data-protocol": "ao",
-    variant: "ao.TN.1",
-    module: moduleId,
-    "execution-device": "lua@5.3a",
-    "push-device": "push@1.0",
-    "patch-from": "/results/outbox",
-  })
-}
-
-describe("{Name} Custom Lua Module", function () {
-  let hbeam, hb, moduleId
-
-  before(async () => {
-    hbeam = await new HyperBEAM({ reset: true }).ready()
-    hb = new HB({ url: hbeam.url })
-    await hb.init(hbeam.jwk)
-    const luaSrc = readFileSync(luaPath, "utf-8")
-    moduleId = await hb.cacheScript(luaSrc, "application/lua")
-  })
-
-  after(async () => { if (hbeam) hbeam.kill() })
-
-  it("should spawn and get initial state", async () => {
-    const { pid } = await spawnCustomLua(hb, moduleId)
-    assert.ok(pid, "should get process ID")
-
-    const get = await hb.scheduleLua({ pid, action: "Get" })
-    const result = await hb.computeLua({ pid, slot: get.slot })
-    assert.ok(result)
-  })
-})
-```
-
-### For WASM64 modules (`--wasm`)
-
-1. Create the Rust project if it doesn't exist:
-
-```bash
-test -d custom-wasm || cargo new custom-wasm --lib
-```
-
-2. Write `custom-wasm/Cargo.toml`:
-
-```toml
-[package]
-name = "custom-wasm"
-version = "0.1.0"
-edition = "2021"
-
-[lib]
-crate-type = ["cdylib"]
-
-[profile.release]
-opt-level = "z"
-lto = true
-strip = true
-```
-
-3. Write `custom-wasm/src/lib.rs` with the `#![no_std]` counter template from `docs/docs/pages/tutorials/rust-wasm64.mdx`.
-
-4. Build:
-
-```bash
-cd custom-wasm && cargo +nightly build --target wasm64-unknown-unknown --release -Zbuild-std=core,panic_abort -Zbuild-std-features=panic_immediate_abort
-```
-
-5. Create `test/{name}-module.test.js` using the WASM test template (with `cacheBinary` + `spawnAOS` + `scheduleAOS` + `computeAOS`).
-
-### Final steps
-
-6. Run the test:
-
-```bash
-yarn test test/{name}-module.test.js
-```
-
-7. Report whether the test passes. If it fails, fix and re-run.

package/cjs/workspace/.claude/skills/debug/SKILL.md

@@ -1,57 +0,0 @@
----
-name: debug
-description: "Troubleshoot WAO development issues. Diagnoses port conflicts, stale processes, missing dependencies, and common errors. Use when builds stall, tests hang, ports conflict, or user says 'something is broken', 'tests are stuck', or 'help debug'. Not for test failures — use /test or /test-hb to re-run tests."
-argument-hint: "[issue-type]"
-disable-model-invocation: true
-allowed-tools: Bash, Read, Grep
----
-
-Troubleshoot WAO development issues.
-
-If `$ARGUMENTS` is provided, focus on that specific issue type (`timeout`, `port`, `wasm`, `signature`).
-
-## Steps
-
-1. Read `docs/debug.md` for known issues and their fixes.
-
-2. Check port conflicts:
-
-```bash
-lsof -ti :10000-10010 2>/dev/null
-lsof -ti :6363 2>/dev/null
-```
-
-3. Check for stale beam.smp processes:
-
-```bash
-ps aux | grep beam.smp | grep -v grep
-```
-
-4. Check HyperBEAM directory exists:
-
-```bash
-ls ./HyperBEAM/rebar.config 2>/dev/null && echo "HyperBEAM: OK" || echo "HyperBEAM: NOT FOUND"
-```
-
-5. Verify wallet exists:
-
-```bash
-ls .wallet.json 2>/dev/null && echo "Wallet: OK" || echo "Wallet: NOT FOUND"
-```
-
-6. If argument provided, focus on that specific issue type:
-   - `timeout` — check ports, kill stale processes, verify HyperBEAM
-   - `port` — show all processes on relevant ports
-   - `wasm` — check Node.js flags and WASM modules
-   - `signature` — check for authority field conflicts, linkify_mode
-
-7. If no specific issue, run a minimal connectivity test:
-
-```bash
-pkill -f beam.smp 2>/dev/null || true
-lsof -ti :10000-10010 | xargs -r kill -9 2>/dev/null || true
-```
-
-8. Cross-reference any error messages with the Common Error Messages table in `docs/debug.md`.
-
-9. Report findings with specific fix recommendations.