Run Futon

@rasenganjs/futon is a zero-dependency, WinterCG-compatible HTTP middleware/router library built on Web API primitives (Request/Response/Headers). It has no way to bind a TCP port on its own — that's @rasenganjs/runtime's job (RuntimeAdapters like NodeDevAdapter). This skill covers both: driving the real demo server (apps/playground/rasengan-runtime-node-demo, futon + runtime's NodeDevAdapter) via driver.sh, and exercising futon in-process via direct-invoke.mjs — the path most futon-only changes actually need, since futon is a library first and an HTTP-bound server second.

All paths below are relative to packages/framework/futon/ (the unit root). The driver's own path from there is .claude/skills/run-futon/driver.sh; the in-process script is .claude/skills/run-futon/direct-invoke.mjs.

Prerequisites

Repo already cloned and pnpm install already run at the workspace root (this repo's node_modules/@rasenganjs/futon and the demo app's node_modules/@rasenganjs/{futon,runtime} are workspace symlinks — nothing extra to install for this skill). Node >=22.12 (verified with v22.22.0), pnpm 10.9.0.

node -v   # v22.22.0 (or newer per package.json engines)
pnpm -v   # 10.9.0

Build

Both @rasenganjs/futon and @rasenganjs/runtime ship from dist/, and the demo app (and this skill's direct-invoke.mjs) run against built output — rebuild both before treating a run as proof of anything, since a stale dist/ silently runs old code:

cd <repo-root>
pnpm --filter @rasenganjs/futon build
pnpm --filter @rasenganjs/runtime build

Expect tsup output ending in DTS ⚡️ Build success for each package (ESM + CJS + .d.ts).

Run (agent path)

Two independent checks. Run both — they cover different layers.

1. HTTP demo (futon + runtime, real server, real port)

bash .claude/skills/run-futon/driver.sh

What it does: finds the repo root via git rev-parse --show-toplevel, kills anything already bound to port 5330, starts apps/playground/rasengan-runtime-node-demo (pnpm start, which runs NodeDevAdapter.serve(app) from server/index.mjs) in the background, polls http://localhost:5330/ until it responds, then curls and checks:

Prints PASS/FAIL per check, a final N passed, M failed line, and exits non-zero if anything failed. Server log is written to /tmp/futon-runtime-node-demo.log. The server is killed on exit (success, failure, or Ctrl-C) via a trap that also frees port 5330 directly — pnpm start's $! is the pnpm wrapper, which doesn't forward SIGTERM to the node child it spawns.

Real output from this session:

== futon + runtime demo driver ==
demo: /home/dilane3/Documents/Projects/React-Framework/rasenganjs/apps/playground/rasengan-runtime-node-demo
log:  /tmp/futon-runtime-node-demo.log

-- starting server (pnpm start) in background --
-- waiting for http://localhost:5330/ to respond --
server is up (pid 48626)

-- checks --
  PASS  GET / returns 200 with HTML body
  PASS  GET /hello/World returns 200 with interpolated name
  PASS  POST /echo returns 200 with an echo key
  PASS  GET /does-not-exist returns 404 via custom notFound handler

4 passed, 0 failed

This demo app's app.mjs has no route that throws, so it can't exercise onError — that's covered by the in-process script below instead.

2. Direct invocation (in-process, no port, no runtime adapter)

node .claude/skills/run-futon/direct-invoke.mjs

What it does: imports Futon/json/text straight from dist/index.js (relative import via import.meta.url, not the bare @rasenganjs/futon specifier — works regardless of where/how it's invoked, no dependency on pnpm hoisting), builds a throwaway Futon app with a param route, a route that throws, and a custom notFound, and calls app.fetch(new Request(...)) directly — exactly the pattern src/__tests__/integration/application.test.ts uses. Checks the param route, the onError handler catching the thrown error, and the custom 404.

Real output from this session:

== futon direct-invocation smoke test (in-process, no server) ==

  PASS  GET /hello/:name returns 200 with interpolated param
  PASS  GET /boom is caught by onError and returns 500 with message
  PASS  GET /does-not-exist hits custom notFound handler

3 passed, 0 failed