wasam-kit

Kit replicable para crear varias web apps locales que corren sobre PHP (compilado a WebAssembly vía @php-wasm/node) + SQLite, server-side en Node, cada una en un puerto loopback real.

Permite interop por API (HTTP directo) y por CLI (comando wasam) para que un agente u otra app del sistema interactúe con las apps.

Estructura

wasam-kit/
  package.json            name "wasam-kit"; bin { wasam }
  core/server.cjs         server PHP-WASM genérico (parametrizado por env)
  bin/wasam.cjs           CLI (shebang node)
  registry.json           { "apps": { "notes": { "port": 3001 } } }
  templates/              index.php + app.html base (REST API de notas)
  apps/<app>/public/      scripts .php de cada app (montados en /var/www)
  apps/<app>/store/       app.sqlite persistente + .pid + server.log
  README.md
  .gitignore

Cómo funciona

• PHP corre como binario WebAssembly: no instalas PHP en el sistema.
• SQLite es la DB (extensión pdo_sqlite incluida). La base vive en el FS en-memoria de PHP y se vuelca a apps/<app>/store/app.sqlite tras cada request (persiste entre reinicios y es accesible desde fuera).
• Instancia PHP única reutilizada; requests serializados (sin condiciones de carrera).
• Cada app escucha en su propio puerto 127.0.0.1:<port> → aislamiento multi-app.

El server genérico core/server.cjs lee:

• WASAM_APP (obligatorio) — nombre de la app
• PORT (obligatorio) — puerto loopback
• PHP_VERSION (opcional, default 8.3)

Instalación

cd wasam-kit
npm install

Comandos del CLI

wasam new <app>                         # crea la app desde templates/ y la registra (asigna puerto libre desde 3001)
wasam start <app>                       # lanza el server detached, guarda PID, espera respuesta de /info
wasam stop <app>                        # detiene el server (mata el PID guardado)
wasam list                              # tabla: app | puerto | estado(running/stopped)
wasam call <app> <METHOD> <path> [json] # request HTTP a la app
wasam help                              # ayuda

Puedes invocarlos con node bin/wasam.cjs <cmd> o, tras npm install -g ., directamente con wasam <cmd>.

Nota de shell para wasam call: desde git-bash (MSYS), un argumento que empieza con / (ej. /api/notes) se convierte a una ruta Windows antes de llegar a node. El CLI ahora lo tolera y normaliza la ruta, pero lo más limpio es pasar la ruta sin barra inicial (wasam call notes GET api/notes) o exportar MSYS_NO_PATHCONV=1; en PowerShell/cmd usa la barra inicial normalmente (wasam call notes GET /info).

Ejemplos

node bin/wasam.cjs list
node bin/wasam.cjs start notes
node bin/wasam.cjs call notes GET /info
node bin/wasam.cjs call notes POST /api/notes '{"text":"desde cli"}'
node bin/wasam.cjs call notes GET /api/notes
node bin/wasam.cjs stop notes

HTTP directo (interop API)

Cada app es un servidor HTTP normal en 127.0.0.1:<port>, así que cualquier herramienta puede consumirla sin el CLI:

curl -s localhost:3001/api/notes
curl -s -X POST localhost:3001/api/notes -H 'Content-Type: application/json' -d '{"text":"hola"}'
curl -s localhost:3001/info

Ejemplo de uso por un agente (CLI)

Un agente u otra app puede orquestar apps sin saber de PHP-WASM, solo con el CLI y HTTP:

wasam new notes
wasam start notes
wasam call notes POST api/notes '{"text":"recordar desplegar"}'   # sin leading slash: robusto en bash
wasam call notes GET api/notes          # leer estado
wasam stop notes

O equivalente por HTTP directo contra http://localhost:<port>.