@soederpop/luca 0.0.31 → 0.0.34

package/README.md

@@ -1,48 +1,171 @@
-# Luca: Lightweight Universal Conversational Architecture
+# Luca
 
-`luca` is a CLI you can download that comes with 40+ self-documenting feature, client, and server modules and types that you can use to build full featured, secure applications, without any complication, or without any `npm install` step.
+**Lightweight Universal Conversational Architecture**
 
-Luca has the concept of a `container` object that is, metaphorically, very similar to a Docker container.  
+A single binary CLI that ships 40+ self-documenting features, clients, and servers. No `npm install`, no setup — download it and start building.
 
-Like Docker containers, you can build layers on top of the base luca `NodeContainer` or `WebContainer` and `use()` your own `Feature`, `Client`, `Command`, `Endpoint` and `Server` patterns.  Bundle that up into your own single file executable, or browser bundle, and provide a standard foundation for all of your custom applications to build on top of.
+Luca gives you a `container` object — think of it like a Docker container for your application runtime. It's a per-process singleton, event bus, state machine, and dependency injector all in one. Layer your own features, clients, servers, commands, and endpoints on top of the base `NodeContainer` (server) or `WebContainer` (browser), then bundle it into your own single-file executable or browser build.
 
-This library provides a `NodeContainer` for server side applications, `WebContainer` for the browser, and an `AGIContainer` that demonstrates another layer on top of the standard node server / script stack.
+The `AGIContainer` extends the node stack with features, clients, and servers for building AI assistants — wrappers around major coding models, tool orchestration, and UIs to visualize them working.
 
-The `AGIContainer` provides features, clients, and servers suitable for building a whole manner of AI Assistants, and comes with its own Assistants to write framework code for you or architect and design applications.  It provides wrappers around all of the major coding assistants, so you can build cool UI applications to visualize them working.  
+## Installation
+
+### Download the binary
+
+Grab the latest release for your platform from [GitHub Releases](https://github.com/soederpop/luca/releases/latest):
+
+| Platform | Binary |
+|----------|--------|
+| macOS (Apple Silicon) | `luca-darwin-arm64` |
+| macOS (Intel) | `luca-darwin-x64` |
+| Linux x64 | `luca-linux-x64` |
+| Linux ARM64 | `luca-linux-arm64` |
+| Windows x64 | `luca-windows-x64.exe` |
+
+**Quick install (macOS/Linux):**
+
+```sh
+# Download (replace PLATFORM with your arch, e.g. darwin-arm64)
+curl -L -o luca https://github.com/soederpop/luca/releases/latest/download/luca-PLATFORM
+chmod +x luca
+sudo mv luca /usr/local/bin/
+```
+
+### macOS Gatekeeper warning
+
+The binary is not yet code-signed (code signing is in progress). On first run macOS will block it with *"luca can't be opened because Apple cannot check it for malicious software."*
+
+To allow it:
+
+1. **System Settings** > **Privacy & Security** > scroll down to the Security section
+2. You'll see a message about `luca` being blocked — click **Allow Anyway**
+3. Run `luca` again and click **Open** in the confirmation dialog
+
+Or from the terminal:
+
+```sh
+xattr -d com.apple.quarantine /usr/local/bin/luca
+```
+
+After that it runs without interruption.
+
+### Verify
+
+```sh
+luca --version
+# luca v0.0.34 (main@325a0ee) built 2026-03-25T06:10:28Z
+```
+
+## Quick Start
+
+### Bootstrap a new project
+
+```sh
+luca bootstrap my-app
+cd my-app
+```
+
+Or just run `luca bootstrap` and it'll ask you for a project name. This scaffolds a project with `commands/`, `endpoints/`, `features/`, `docs/`, and AI assistant configuration — everything wired up and ready to extend.
+
+### Explore
+
+```sh
+luca                              # list all commands
+luca describe features            # index of 40+ features
+luca describe fs                  # full docs for any feature
+luca describe fs.readFile         # drill into a specific method
+luca eval "container.features.available"  # run code with the container in scope
+luca console                      # full REPL
+```
+
+### Run scripts and markdown
+
+`luca run` executes TypeScript, JavaScript, and markdown files. Markdown files have their code blocks executed in order, with `container` already in scope — no imports needed:
+
+````md
+# my-script.md
+
+Grab some data and print it:
+
+```ts
+const fs = container.feature('fs')
+const files = await fs.readdir('.')
+console.log(`Found ${files.length} files`)
+```
+
+Then do something with it:
+
+```ts
+const yaml = container.feature('yaml')
+console.log(yaml.stringify({ files }))
+```
+````
+
+```sh
+luca run my-script.md
+```
+
+Each block shares state with the previous ones, so variables defined in one block are available in the next. Use `--safe` to require approval before each block, or `--console` to drop into a REPL afterward with all the accumulated context.  **Note:** if your block uses top-level awaits, we can't preserve context.  You can use `container.addContext({ yourVariable })` and it will be available as a global variable in future blocks.
+
+### Serve
+
+```sh
+luca serve   # serves endpoints/ folder as HTTP routes
+```
 
-## Fully typed at Author-time / Self-Documenting at Runtime
+See [`docs/CLI.md`](./docs/CLI.md) for the full CLI reference.
 
-Besides being fully typed, The `container`'s JavaScript API is self documenting at runtime.  All of the constructor options, the shape of observable state, events emitted, environment variables used, method descriptions, are documented and fully typed.  This helps while debugging, working in the chrome console or a CLI REPL, allows for insane metaprogramming and is a great way to learn about the framework and its components. 
+## Importing the container into your own scripts / modules
 
 ```ts
 import container from '@soederpop/luca'
+```
+
+That's it — you get one object with everything on it. No factory function, no setup. It's a singleton.
+
+We do export the framework classes (`WebContainer`, `Feature`, `Client`, `Server`, etc.) if you want to extend them, but for using the system you only ever need the default export.
+
+### In the browser via esm.sh
 
-container.features.available // ['fs','git','proc','vault',...]
-container.clients.available // ['rest','websocket']
-container.servers.available // ['express','websocket','ipc','mcp']
+**Static import:**
 
-container.features.describe() // markdown or json summary of all features
-container.feature.describe('fileManager') // describe an individual feature 
+```js
+import container from 'https://esm.sh/@soederpop/luca/web'
 
-container.introspect() // a json structure that describes the container, its registries, their members
-container.introspectAsText() // a markdown description of the same
+container.features.available  // ['fetch', 'state', 'ui', ...]
 ```
 
-You can pass args to these things to only get a small slice of information, e.g. just usage examples, or a list of events it emits, or documentation for a single method.
+**Dynamic import:**
 
-And the individual components also respond to the same
+```js
+const { default: container } = await import('https://esm.sh/@soederpop/luca/web')
 
+container.features.available  // same singleton
 ```
-const fileManager = container.feature('fileManager')
 
-fileManager.introspect() // json
-fileManager.introspectAsText() // markdown
-fileManager.introspectAsText("usage", "examples") // just summarize it for me my boy
+With dynamic import you have to pick it off `default` yourself — there's no top-level default binding like the static form gives you. Either way, it's the same singleton container, and `window.luca` is set automatically so you can poke at it from the console.
+
+## How It Works
+
+### Self-documenting at runtime
+
+Every helper (feature, client, server) carries its own introspection metadata — constructor options, observable state shape, events emitted, environment variables used, method signatures. This powers `luca describe`, works in the REPL, and enables metaprogramming.
+
+```ts
+import container from '@soederpop/luca'
+
+container.features.available   // ['fs','git','proc','vault',...]
+container.clients.available    // ['rest','websocket']
+container.servers.available    // ['express','websocket','ipc','mcp']
+
+container.features.describe()  // markdown summary of all features
+container.feature('fs').introspect()          // json
+container.feature('fs').introspectAsText()    // markdown
 ```
 
-## Self Documentation on steroids actually
+### Content-aware documentation
 
-The node container has a `container.docs` feature that uses [Contentbase](https://contentbase.soederpop.com) to be able to understand and interact with the local project markdown documentation 
+The node container includes `container.docs` powered by [Contentbase](https://github.com/soederpop/contentbase) — query your project's markdown documentation like a database:
 
 ```ts
 await container.docs.load()
@@ -50,29 +173,111 @@ const { Tutorial } = container.docs.models
 const tutorials = await container.docs.query(Tutorial).fetchAll()
 ```
 
-## A Perfect Companion for AI Coding Assistants and Students alike
+### Project extensions
+
+Drop files into convention-based folders and they're auto-discovered:
 
-The `luca` CLI [Full Docs Here](./docs/CLI.md) has a few interesting commands.
+- `commands/` — custom CLI commands, run via `luca <name>`
+- `endpoints/` — file-based HTTP routes, served via `luca serve`
+- `features/` — custom container features
 
-- The `luca eval` command lets you run snippets of code to see what they produce.  The `container` is already defined for you
-- The `luca describe` command lets you view docs, or just parts of docs, of any group of features, clients, etc, as a single markdown doc
-- The `luca console` command will bring you into a full blown REPL
-- The `luca chat` command will put you in touch with a tutor
-- The `luca sandbox-mcp` provides a REPL for your coding assistant and a documentation browser
+Generate boilerplate with `luca scaffold`:
 
-### Codex MCP note
+```sh
+luca scaffold command myTask --description "Automate something"
+luca scaffold feature myCache --description "Custom caching layer"
+luca scaffold endpoint users --description "User management API"
+```
 
-If OpenAI Codex CLI reports `MCP client ... timed out after 10 seconds` for Luca or Contentbase stdio servers, use a Node stdio bridge to launch Bun. This avoids an intermittent Codex<->Bun stdio startup issue where the server appears to start but handshake still times out.
+### Building an assistant
 
-See [`docs/CLI.md`](./docs/CLI.md) for the exact bridge script and `~/.codex/config.toml` examples.
+Features can inject their own tools into an assistant via `assistant.use()`. Here's an assistant that can browse the web:
 
-## Installation
+```ts
+import container from '@soederpop/luca'
+
+const browser = container.feature('browserUse', { headed: true })
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a web research assistant. Use your browser tools to find information.',
+  model: 'gpt-4.1-mini',
+})
+
+// browserUse injects its tools — open, click, type, screenshot, extract, etc.
+assistant.use(browser)
+await assistant.start()
+
+await assistant.ask('Go to hacker news and tell me what the top 3 stories are about')
+```
 
-To install the CLI
+### AI coding assistant integration
+
+The CLI works great alongside Claude Code, Codex, and other coding assistants:
+
+- `luca describe` gives assistants full API docs for any helper
+- `luca eval` lets them test container expressions before committing code
+- `luca sandbox-mcp` provides a REPL and doc browser as an MCP server
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (runtime and test runner)
+
+### Setup
+
+```sh
+git clone https://github.com/soederpop/luca.git
+cd luca
+bun install
+```
+
+### Running in dev
+
+```sh
+# Run the CLI from source (equivalent to the luca binary)
+bun run src/cli/cli.ts
+
+# Examples
+bun run src/cli/cli.ts describe features
+bun run src/cli/cli.ts eval "container.features.available"
+```
+
+### Testing
+
+```sh
+# Unit tests
+bun test
+
+# Integration tests (may require API keys / env vars)
+bun run test:integration
+```
+
+### Building the binary
 
 ```sh
-echo 'i will eventually have a url to download the CLI and stuff'
+bun run compile
 ```
 
+This runs the full pipeline: introspection generation, scaffold templates, bootstrap code, python bridge, build stamp, then compiles to `dist/luca` via Bun's native compiler.
+
+### Project structure
+
+```
+src/
+  cli/          CLI entry point and commands
+  node/         NodeContainer and server-side features
+  web/          WebContainer and browser features
+  agi/          AGIContainer — AI assistant layer
+  schemas/      Shared Zod schemas
+  react/        React bindings
+test/           Unit tests
+test-integration/  Integration tests
+docs/
+  apis/         Generated API docs
+  examples/     Runnable examples (luca run docs/examples/grep)
+  tutorials/    Longer-form guides
+```
 
+## License
 
+MIT

package/bun.lock

@@ -18,7 +18,7 @@
         "chokidar": "^3.5.3",
         "cli-markdown": "^3.5.0",
         "compromise": "^14.14.5",
-        "contentbase": "^0.0.5",
+        "contentbase": "^0.1.7",
         "cors": "^2.8.5",
         "detect-port": "^1.5.1",
         "dotenv": "^17.2.4",
@@ -33,6 +33,7 @@
         "inflect": "^0.5.0",
         "ink": "^6.7.0",
         "inquirer": "^9.1.5",
+        "ioredis": "^5.10.1",
         "isomorphic-vm": "^0.0.1",
         "isomorphic-ws": "^5.0.0",
         "js-tiktoken": "^1.0.21",
@@ -192,6 +193,8 @@
 
     "@inquirer/figures": ["@inquirer/figures@1.0.12", "", {}, "sha512-MJttijd8rMFcKJC8NYmprWr6hD3r9Gd9qUC0XwPNwoEPWSMVJwA2MlXxF+nhZZNMY+HXsWa+o7KY2emWYIn0jQ=="],
 
+    "@ioredis/commands": ["@ioredis/commands@1.5.1", "", {}, "sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw=="],
+
     "@isaacs/cliui": ["@isaacs/cliui@8.0.2", "", { "dependencies": { "string-width": "^5.1.2", "string-width-cjs": "npm:string-width@^4.2.0", "strip-ansi": "^7.0.1", "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", "wrap-ansi": "^8.1.0", "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" } }, "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA=="],
 
     "@isaacs/fs-minipass": ["@isaacs/fs-minipass@4.0.1", "", { "dependencies": { "minipass": "^7.0.4" } }, "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w=="],
@@ -334,7 +337,7 @@
 
     "@sindresorhus/is": ["@sindresorhus/is@4.6.0", "", {}, "sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw=="],
 
-    "@soederpop/luca": ["@soederpop/luca@0.0.2", "", { "dependencies": { "@modelcontextprotocol/sdk": "^1.12.1", "@ngrok/ngrok": "^1.5.1", "@openai/codex": "^0.99.0", "@resvg/resvg-js": "^2.6.2", "@supabase/supabase-js": "^2.95.3", "@types/marked": "^6.0.0", "@types/marked-terminal": "^6.1.1", "axios": "^1.3.5", "cacache": "^17.0.7", "chalk": "^5.2.0", "child-process-promise": "^2.2.1", "chokidar": "^3.5.3", "cli-markdown": "^3.5.0", "compromise": "^14.14.5", "contentbase": "", "cors": "^2.8.5", "cross-fetch": "^4.1.0", "detect-port": "^1.5.1", "dotenv": "^17.2.4", "endent": "^2.1.0", "esbuild-wasm": "0.17.18", "excalidraw-to-svg": "^3.1.0", "express": "^4.18.2", "figlet": "^1.6.0", "glob": "^11.0.2", "googleapis": "^171.4.0", "grammy": "^1.40.0", "inflect": "^0.5.0", "ink": "^6.7.0", "inquirer": "^9.1.5", "isomorphic-vm": "^0.0.1", "isomorphic-ws": "^5.0.0", "js-tiktoken": "^1.0.21", "js-yaml": "^4.1.0", "lodash-es": "^4.17.21", "marked": "^15.0.12", "marked-terminal": "^7.3.0", "mdast-util-to-markdown": "^1.5.0", "mdast-util-to-string": "^3.2.0", "micromatch": "^4.0.5", "minimist": "^1.2.8", "node-uuid": "^1.4.8", "object-hash": "^3.0.0", "openai": "^5.1.1", "opener": "^1.5.2", "react": "^19.2.4", "react-devtools-core": "^7.0.1", "react-dom": "^19.2.4", "react-reconciler": "^0.33.0", "remark-gfm": "^3.0.1", "rimraf": "^5.0.0", "typescript": "^5.9.3", "unist-util-find-after": "^4.0.1", "unist-util-find-all-after": "^4.0.1", "unist-util-find-all-before": "^4.0.1", "unist-util-find-before": "^3.0.1", "unist-util-select": "^4.0.3", "unist-util-visit": "^4.1.2", "wink-eng-lite-web-model": "^1.8.1", "wink-nlp": "^2.4.0", "ws": "^8.13.0", "zod": "^4.0.0" }, "optionalDependencies": { "node-llama-cpp": "^3.17.1" }, "bin": { "luca": "src/cli/cli.ts" } }, "sha512-oxHCwZYjnGFWvr9TdkYcbBy6txwFORibumQeXF1UWBQsVTJECot5GlQ+dyVlmMLvEcde7N0JOryJZVWeWQRkQg=="],
+    "@soederpop/luca": ["@soederpop/luca@0.0.32", "", { "dependencies": { "@modelcontextprotocol/sdk": "^1.12.1", "@ngrok/ngrok": "^1.5.1", "@openai/codex": "^0.99.0", "@resvg/resvg-js": "^2.6.2", "@supabase/supabase-js": "^2.95.3", "@types/marked": "^6.0.0", "@types/marked-terminal": "^6.1.1", "axios": "^1.3.5", "cacache": "^17.0.7", "chalk": "^5.2.0", "child-process-promise": "^2.2.1", "chokidar": "^3.5.3", "cli-markdown": "^3.5.0", "compromise": "^14.14.5", "contentbase": "^0.1.7", "cors": "^2.8.5", "detect-port": "^1.5.1", "dotenv": "^17.2.4", "endent": "^2.1.0", "esbuild-wasm": "0.17.18", "excalidraw-to-svg": "^3.1.0", "express": "^4.18.2", "figlet": "^1.6.0", "glob": "^11.0.2", "googleapis": "^171.4.0", "grammy": "^1.40.0", "inflect": "^0.5.0", "ink": "^6.7.0", "inquirer": "^9.1.5", "isomorphic-vm": "^0.0.1", "isomorphic-ws": "^5.0.0", "js-tiktoken": "^1.0.21", "js-yaml": "^4.1.0", "lodash-es": "^4.17.21", "marked": "^15.0.12", "marked-terminal": "^7.3.0", "mdast-util-to-markdown": "^1.5.0", "mdast-util-to-string": "^3.2.0", "micromatch": "^4.0.5", "minimist": "^1.2.8", "node-uuid": "^1.4.8", "object-hash": "^3.0.0", "openai": "^5.1.1", "opener": "^1.5.2", "react": "^19.2.4", "react-devtools-core": "^7.0.1", "react-dom": "^19.2.4", "react-reconciler": "^0.33.0", "remark-gfm": "^3.0.1", "rimraf": "^5.0.0", "typescript": "^5.9.3", "unist-util-find-after": "^4.0.1", "unist-util-find-all-after": "^4.0.1", "unist-util-find-all-before": "^4.0.1", "unist-util-find-before": "^3.0.1", "unist-util-select": "^4.0.3", "unist-util-visit": "^4.1.2", "wink-eng-lite-web-model": "^1.8.1", "wink-nlp": "^2.4.0", "ws": "^8.13.0", "zod": "^4.0.0" }, "optionalDependencies": { "node-llama-cpp": "^3.17.1" }, "bin": { "luca": "src/cli/cli.ts" } }, "sha512-JlIz18N0/J/dDfaFluJdwIvY1P6LkuV/gDBbrj3XGKAN1YaumMLThTcoQARE8CgEyfKVfM8bM9T9nNmygs1lCQ=="],
 
     "@supabase/auth-js": ["@supabase/auth-js@2.95.3", "", { "dependencies": { "tslib": "2.8.1" } }, "sha512-vD2YoS8E2iKIX0F7EwXTmqhUpaNsmbU6X2R0/NdFcs02oEfnHyNP/3M716f3wVJ2E5XHGiTFXki6lRckhJ0Thg=="],
 
@@ -638,6 +641,8 @@
 
     "clone": ["clone@1.0.4", "", {}, "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg=="],
 
+    "cluster-key-slot": ["cluster-key-slot@1.1.2", "", {}, "sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA=="],
+
     "cmake-js": ["cmake-js@8.0.0", "", { "dependencies": { "debug": "^4.4.3", "fs-extra": "^11.3.3", "node-api-headers": "^1.8.0", "rc": "1.2.8", "semver": "^7.7.3", "tar": "^7.5.6", "url-join": "^4.0.1", "which": "^6.0.0", "yargs": "^17.7.2" }, "bin": { "cmake-js": "bin/cmake-js" } }, "sha512-YbUP88RDwCvoQkZhRtGURYm9RIpWdtvZuhT87fKNoLjk8kIFIFeARpKfuZQGdwfH99GZpUmqSfcDrK62X7lTgg=="],
 
     "code-excerpt": ["code-excerpt@4.0.0", "", { "dependencies": { "convert-to-spaces": "^2.0.1" } }, "sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA=="],
@@ -674,7 +679,7 @@
 
     "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
 
-    "contentbase": ["contentbase@0.0.5", "", { "dependencies": { "@soederpop/luca": "^0.0.2", "gray-matter": "^4.0.3", "js-yaml": "^4.1.0", "mdast-util-mdxjs-esm": "^2.0.1", "mdast-util-to-markdown": "^2.1.2", "mdast-util-to-string": "^4.0.0", "picomatch": "^4.0.3", "rehype-stringify": "^10.0.1", "remark-gfm": "^4.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.1.2", "remark-stringify": "^11.0.0", "unified": "^11.0.5", "unist-util-find-after": "^5.0.0", "unist-util-find-all-after": "^5.0.0", "unist-util-find-all-before": "^5.0.0", "unist-util-find-before": "^4.0.0", "unist-util-select": "^5.1.0", "unist-util-visit": "^5.0.0", "zod": "^4.3.6" }, "bin": { "cnotes": "src/cli/index.ts", "contentbase": "src/cli/index.ts" } }, "sha512-TmF9K30CgHnljfJMbd7q3eTMR6fwZltp/WJpLWch9pA79hFMT5tg+r1piEOHS5UIFOYQKmEB79Rm6gugDgCOSw=="],
+    "contentbase": ["contentbase@0.1.8", "", { "dependencies": { "@soederpop/luca": ">=0.0.16", "gray-matter": "^4.0.3", "js-yaml": "^4.1.0", "mdast-util-mdxjs-esm": "^2.0.1", "mdast-util-to-markdown": "^2.1.2", "mdast-util-to-string": "^4.0.0", "picomatch": "^4.0.3", "rehype-stringify": "^10.0.1", "remark-gfm": "^4.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.1.2", "remark-stringify": "^11.0.0", "unified": "^11.0.5", "unist-util-find-after": "^5.0.0", "unist-util-find-all-after": "^5.0.0", "unist-util-find-all-before": "^5.0.0", "unist-util-find-before": "^4.0.0", "unist-util-select": "^5.1.0", "unist-util-visit": "^5.0.0", "zod": "^4.3.6" }, "bin": { "cnotes": "src/cli/index.ts", "contentbase": "src/cli/index.ts" } }, "sha512-FcivPrOkmowDea2FobSCHPmNdudQz90ZF5xwp2aDF5ajRXu1lujvzOXEvmwAZ9AcJC37BQHVNR0Ifa1guZaODw=="],
 
     "convert-to-spaces": ["convert-to-spaces@2.0.1", "", {}, "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ=="],
 
@@ -684,8 +689,6 @@
 
     "cors": ["cors@2.8.5", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g=="],
 
-    "cross-fetch": ["cross-fetch@4.1.0", "", { "dependencies": { "node-fetch": "^2.7.0" } }, "sha512-uKm5PU+MHTootlWEY+mZ4vvXoCn4fLQxT9dSc1sXVMSFkINTJVN8cAQROpwcKm8bJ/c7rgZVIBWzH5T78sNZZw=="],
-
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
 
     "css-declaration-sorter": ["css-declaration-sorter@7.2.0", "", { "peerDependencies": { "postcss": "^8.0.9" } }, "sha512-h70rUM+3PNFuaBDTLe8wF/cdWu+dOZmb7pJt8Z2sedYbAcQVQV/tEchueg3GWxwqS0cxtbxmaHEdkNACqcvsow=="],
@@ -738,6 +741,8 @@
 
     "delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
 
+    "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
+
     "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
 
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
@@ -1032,6 +1037,8 @@
 
     "inquirer": ["inquirer@9.3.7", "", { "dependencies": { "@inquirer/figures": "^1.0.3", "ansi-escapes": "^4.3.2", "cli-width": "^4.1.0", "external-editor": "^3.1.0", "mute-stream": "1.0.0", "ora": "^5.4.1", "run-async": "^3.0.0", "rxjs": "^7.8.1", "string-width": "^4.2.3", "strip-ansi": "^6.0.1", "wrap-ansi": "^6.2.0", "yoctocolors-cjs": "^2.1.2" } }, "sha512-LJKFHCSeIRq9hanN14IlOtPSTe3lNES7TYDTE2xxdAy1LS5rYphajK1qtwvj3YmQXvvk0U2Vbmcni8P9EIQW9w=="],
 
+    "ioredis": ["ioredis@5.10.1", "", { "dependencies": { "@ioredis/commands": "1.5.1", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-HuEDBTI70aYdx1v6U97SbNx9F1+svQKBDo30o0b9fw055LMepzpOOd0Ccg9Q6tbqmBSJaMuY0fB7yw9/vjBYCA=="],
+
     "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
 
     "ipull": ["ipull@3.9.5", "", { "dependencies": { "@tinyhttp/content-disposition": "^2.2.0", "async-retry": "^1.3.3", "chalk": "^5.3.0", "ci-info": "^4.0.0", "cli-spinners": "^2.9.2", "commander": "^10.0.0", "eventemitter3": "^5.0.1", "filenamify": "^6.0.0", "fs-extra": "^11.1.1", "is-unicode-supported": "^2.0.0", "lifecycle-utils": "^2.0.1", "lodash.debounce": "^4.0.8", "lowdb": "^7.0.1", "pretty-bytes": "^6.1.0", "pretty-ms": "^8.0.0", "sleep-promise": "^9.1.0", "slice-ansi": "^7.1.0", "stdout-update": "^4.0.1", "strip-ansi": "^7.1.0" }, "optionalDependencies": { "@reflink/reflink": "^0.1.16" }, "bin": { "ipull": "dist/cli/cli.js" } }, "sha512-5w/yZB5lXmTfsvNawmvkCjYo4SJNuKQz/av8TC1UiOyfOHyaM+DReqbpU2XpWYfmY+NIUbRRH8PUAWsxaS+IfA=="],
@@ -1122,6 +1129,10 @@
 
     "lodash.debounce": ["lodash.debounce@4.0.8", "", {}, "sha512-FT1yDzDYEoYWhnSGnpE/4Kj1fLZkDFyqRb7fNt6FdYOSxlUWAtp42Eh6Wb0rGIv/m9Bgo7x4GhQbm5Ys4SG5ow=="],
 
+    "lodash.defaults": ["lodash.defaults@4.2.0", "", {}, "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ=="],
+
+    "lodash.isarguments": ["lodash.isarguments@3.1.0", "", {}, "sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg=="],
+
     "lodash.memoize": ["lodash.memoize@4.1.2", "", {}, "sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag=="],
 
     "lodash.merge": ["lodash.merge@4.6.2", "", {}, "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ=="],
@@ -1536,6 +1547,10 @@
 
     "readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
 
+    "redis-errors": ["redis-errors@1.2.0", "", {}, "sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w=="],
+
+    "redis-parser": ["redis-parser@3.0.0", "", { "dependencies": { "redis-errors": "^1.0.0" } }, "sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A=="],
+
     "rehype-stringify": ["rehype-stringify@10.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "hast-util-to-html": "^9.0.0", "unified": "^11.0.0" } }, "sha512-k9ecfXHmIPuFVI61B9DeLPN0qFHfawM6RsuX48hoqlaKSF61RskNjSm1lI8PhBEM0MRdLxVVm4WmTqJQccH9mA=="],
 
     "remark-gfm": ["remark-gfm@3.0.1", "", { "dependencies": { "@types/mdast": "^3.0.0", "mdast-util-gfm": "^2.0.0", "micromark-extension-gfm": "^2.0.0", "unified": "^10.0.0" } }, "sha512-lEFDoi2PICJyNrACFOfDD3JlLkuSbOa5Wd8EPt06HUdptv8Gn0bxYTdbU/XXQ3swAPkEaGxxPN9cbnMHvVu1Ig=="],
@@ -1634,6 +1649,8 @@
 
     "stack-utils": ["stack-utils@2.0.6", "", { "dependencies": { "escape-string-regexp": "^2.0.0" } }, "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ=="],
 
+    "standard-as-callback": ["standard-as-callback@2.1.0", "", {}, "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A=="],
+
     "statuses": ["statuses@2.0.1", "", {}, "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ=="],
 
     "stdin-discarder": ["stdin-discarder@0.3.1", "", {}, "sha512-reExS1kSGoElkextOcPkel4NE99S0BWxjUHQeDFnR8S993JxpPX7KU4MNmO19NXhlJp+8dmdCbKQVNgLJh2teA=="],
@@ -2030,6 +2047,8 @@
 
     "inquirer/wrap-ansi": ["wrap-ansi@6.2.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA=="],
 
+    "ioredis/debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
     "ipull/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
 
     "ipull/lifecycle-utils": ["lifecycle-utils@2.1.0", "", {}, "sha512-AnrXnE2/OF9PHCyFg0RSqsnQTzV991XaZA/buhFDoc58xU7rhSCDgCz/09Lqpsn4MpoPHt7TRAXV1kWZypFVsA=="],

package/commands/build-python-bridge.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+async function buildPythonBridge(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fs = container.feature('fs')
+
+	const sourcePath = 'src/python/bridge.py'
+	const outputPath = 'src/python/generated.ts'
+
+	if (!fs.exists(sourcePath)) {
+		console.error(`   ❌ ${sourcePath} not found`)
+		process.exit(1)
+	}
+
+	const content = fs.readFile(sourcePath)
+	console.log(`   📄 bridge.py: ${content.length} chars`)
+
+	const escapeForTemplate = (s: string) =>
+		s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+	const output = `// Auto-generated Python bridge script
+// Generated at: ${new Date().toISOString()}
+// Source: src/python/bridge.py
+//
+// Do not edit manually. Run: luca build-python-bridge
+
+export const bridgeScript = \`${escapeForTemplate(content)}\`
+`
+
+	fs.ensureFolder('src/python')
+	await fs.writeFileAsync(outputPath, output)
+	console.log(`\n✨ Generated ${outputPath}`)
+}
+
+export default {
+	description: 'Bundle the Python bridge script into src/python/generated.ts',
+	argsSchema,
+	handler: buildPythonBridge,
+}

package/docs/apis/clients/rest.md

@@ -24,13 +24,13 @@ container.client('rest', {
 
 ### beforeRequest
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 
 
 ### patch
 
-Send a PATCH request.
+Send a PATCH request. Returns the parsed response body directly (not an axios Response wrapper). On HTTP errors, returns the error as JSON instead of throwing.
 
 **Parameters:**
 
@@ -46,7 +46,7 @@ Send a PATCH request.
 
 ### put
 
-Send a PUT request.
+Send a PUT request. Returns the parsed response body directly (not an axios Response wrapper). On HTTP errors, returns the error as JSON instead of throwing.
 
 **Parameters:**
 
@@ -62,7 +62,7 @@ Send a PUT request.
 
 ### post
 
-Send a POST request.
+Send a POST request. Returns the parsed response body directly (not an axios Response wrapper). On HTTP errors, returns the error as JSON instead of throwing.
 
 **Parameters:**
 
@@ -78,7 +78,7 @@ Send a POST request.
 
 ### delete
 
-Send a DELETE request.
+Send a DELETE request. Returns the parsed response body directly (not an axios Response wrapper). On HTTP errors, returns the error as JSON instead of throwing.
 
 **Parameters:**
 
@@ -94,7 +94,7 @@ Send a DELETE request.
 
 ### get
 
-Send a GET request.
+Send a GET request. Returns the parsed response body directly (not an axios Response wrapper). On HTTP errors, returns the error as JSON instead of throwing.
 
 **Parameters:**
 
@@ -118,7 +118,7 @@ Handle an axios error by emitting 'failure' and returning the error as JSON.
 |------|------|----------|-------------|
 | `error` | `AxiosError` | ✓ | Parameter error |
 
-**Returns:** `void`
+**Returns:** `Promise<object>`
 
 
 

package/docs/apis/clients/websocket.md

@@ -1,6 +1,6 @@
 # WebSocketClient (clients.websocket)
 
-WebSocket client that bridges raw WebSocket events to Luca's Helper event bus, providing a clean interface for sending/receiving messages, tracking connection state, and optional auto-reconnection with exponential backoff. Events emitted: - `open` — connection established - `message` — message received (JSON-parsed when possible) - `close` — connection closed (with code and reason) - `error` — connection error - `reconnecting` — attempting reconnection (with attempt number)
+WebSocketClient helper
 
 ## Usage
 
@@ -53,6 +53,26 @@ Send data over the WebSocket connection. Automatically JSON-serializes the paylo
 
 
 
+### ask
+
+Send a request and wait for a correlated response. The message is sent with a unique `requestId`; the remote side is expected to reply with a message containing `replyTo` set to that same ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `string` | ✓ | A string identifying the request type |
+| `data` | `any` |  | Optional payload to include with the request |
+| `timeout` | `any` |  | How long to wait for a response (default 10 000 ms) |
+
+**Returns:** `Promise<R>`
+
+```ts
+const result = await ws.ask('getUser', { id: 42 })
+```
+
+
+
 ### disconnect
 
 Gracefully close the WebSocket connection. Suppresses auto-reconnect and updates connection state to disconnected.
@@ -146,16 +166,9 @@ Emitted when a request fails
 
 ## Examples
 
-**clients.websocket**
+**ask**
 
 ```ts
-const ws = container.client('websocket', {
- baseURL: 'ws://localhost:8080',
- reconnect: true,
- maxReconnectAttempts: 5
-})
-ws.on('message', (data) => console.log('Received:', data))
-await ws.connect()
-await ws.send({ type: 'hello' })
+const result = await ws.ask('getUser', { id: 42 })
 ```