@soederpop/luca 0.0.2

package/CLAUDE.md

@@ -0,0 +1,71 @@
+# LUCA
+
+Lightweight Universal Conversational Architecture. Runtime is bun.
+
+The runtime is bun, that means no vitest.
+
+Luca provides a system for building runtime `container` objects which provide server and browser applications with all of the dependencies they need to build complete applications.  A `container` is a per process global singleton, event bus, state machine, and dependency injector.  A `container` is either based on a node or browser runtime, and comes with features optimized for that environment.  You can build your own container on top of it, with your own features, clients, servers.  It is very much inspired by docker layer caching.
+
+A `container` could be used for all "business logic" and state, and be a headless provider for an entire application.  The UI, Scripting output, input, etc, are all just functional interfaces and event bindings to the core container and all of its helpers, and their state.
+
+Dependencies consist of Helpers - Features, Clients, Servers, as well as primitives like event buses, observable state.  The `container` contains registries of all available components: `container.features`, `container.clients`, `container.servers`, `container.commands`, `container.endpoints` as well as factory functions to create instances of them: `container.feature('fileManager')`, `container.server('express')`. 
+
+The `container` and its helpers are perfect for scripts and long running services on the backend, or highly reactive and stateful applications on the frontend.  The components can easily talk to eachother, as the `container` on the server provides servers like `container.server('express')` and `container.server('websocket')` as well as `container.client('rest')` and `container.client('websocket')` and others.  
+
+On the frontend the browser container is perfect for highly reactive, stateful web applications, especially works well with React.
+
+## The `luca` CLI
+
+- in dev, `bun run src/cli/cli.ts` is the same as `luca`
+
+- in prod, or educational material, `luca` refers to the binary build.  In this mode, it can work in any project, and load `commands/` and `endpoints/` through its VM and therefore allows folders of these modules which don't depend on anything from NPM to extend the CLI and be used in commands like `luca serve` to run a local express server
+
+- The `luca` cli is an extremely helpful tool.  
+	- it runs code `luca eval "container.features.available"` 
+	- it generates docs:
+		- `luca describe diskCache`
+		- `luca describe` describe the container itself
+		- `luca describe servers` describe which servers are available
+		- the arguments to describe are pretty forgiving and permissive
+
+**IMPORTANT NOTE** When trying to investigate features, clients, servers, etc, see if these tools can help you first instead of searching for files and reading them that way.  If youw ant to understand what they do, vs how theyre actually implemented
+
+## Coding style and guidelines
+
+- The container is intended to provide a collection of blessed, approved, audited modules that we've built and curated together.  It is intended to be the primary API and interface through the system  
+- The container should provide you with everything you need, and you should not need to be importing dependencies or other modules.  If you find yourself stuck by this constraint, raise this concern, and we can work on finding a way to bring in a feature or client
+- When trying to find paths in the project, use `container.paths.resolve()` or `container.paths.join()` instead of `import { resolve } from 'path'`
+- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies to command handlers, scripts, and any code that has access to a container. The only exception is inside feature implementations themselves (e.g. `proc.ts`, `fs.ts`) where you ARE building the container primitive — those may use Node builtins directly since they can't depend on themselves.
+
+## Container Utilities
+
+The container provides `container.utils` with common utilities. **Use these instead of importing packages directly** — they work in both node and web environments.
+
+- `container.utils.uuid()` — generates a v4 UUID (use instead of importing `node-uuid` or `crypto`)
+- `container.utils.hashObject(obj)` — deterministic hash of any object
+- `container.utils.stringUtils` — `{ kebabCase, camelCase, upperFirst, lowerFirst, pluralize, singularize }`
+- `container.utils.lodash` — `{ uniq, keyBy, uniqBy, groupBy, debounce, throttle, mapValues, mapKeys, pick, get, set, omit }`
+
+Also available on every container:
+- `container.uuid` — the container's own unique ID
+- `container.paths.resolve()` / `container.paths.join()` — path operations
+
+## Type Safety and Introspection
+
+- Zod does a lot of the heavy lifting for us with its type inference
+- For more descriptive things like class descriptions, method descriptions, we rely on jsdoc blocks.  These are parsed and used to generate modules we commit to source.  We shouldn't let these drift, so for this reason we have a pre-commit hook which ensures they're up to date
+- We rely on module augmentation a lot to make sure `container.feature()` can provide type signatures for everything that gets added to it by extension modules down the road.  ( kind of like we did with AGIContainer extending NodeContainer )
+
+## Testing
+
+- Test runner is **bun** (not vitest). Do not import from or add vitest.
+- `bun test` or `bun run test` — runs unit tests only (`test/*.test.ts`)
+- `bun run test:integration` — runs integration tests in `test-integration/` that hit real APIs/CLIs (gated by env vars)
+- Import `mock`, `spyOn` from `bun:test` when needed. If you import anything from `bun:test`, you must also import `describe`, `it`, `expect`, etc. from there (importing disables auto-globals).
+- **ALL tests must pass. Zero tolerance for test failures.** The ESBuild feature's "service is no longer running" error is a known critical bug — if you encounter it, fix it. Do not ignore it, do not skip it, do not leave it broken. This applies to every test: if a test fails, that is a blocker. Fix the root cause.
+
+## API Docs
+
+- See [docs/apis](./docs/apis/) for detailed API descriptions of the public methods and options for creating various helpers
+- See [docs/examples](./docs/examples/) for examples of using each feature.  NOTE: These docs are runnable so you can see the output of the code blocks.  `luca run docs/examples/grep` for example
+- See [docs/tutorials](./docs/tutorials/) for longer form tutorials on various subjects and best practices

package/README.md

@@ -0,0 +1,78 @@
+# Luca: Lightweight Universal Conversational Architecture
+
+`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.
+
+Luca has the concept of a `container` object that is, metaphorically, very similar to a Docker container.  
+
+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.
+
+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` 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.  
+
+## Fully typed at Author-time / Self-Documenting at Runtime
+
+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. 
+
+```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 or json summary of all features
+container.feature.describe('fileManager') // describe an individual feature 
+
+container.introspect() // a json structure that describes the container, its registries, their members
+container.introspectAsText() // a markdown description of the same
+```
+
+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.
+
+And the individual components also respond to the same
+
+```
+const fileManager = container.feature('fileManager')
+
+fileManager.introspect() // json
+fileManager.introspectAsText() // markdown
+fileManager.introspectAsText("usage", "examples") // just summarize it for me my boy
+```
+
+## Self Documentation on steroids actually
+
+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 
+
+```ts
+await container.docs.load()
+const { Tutorial } = container.docs.models
+const tutorials = await container.docs.query(Tutorial).fetchAll()
+```
+
+## A Perfect Companion for AI Coding Assistants and Students alike
+
+The `luca` CLI [Full Docs Here](./docs/CLI.md) has a few interesting commands.
+
+- 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
+
+### Codex MCP note
+
+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.
+
+See [`docs/CLI.md`](./docs/CLI.md) for the exact bridge script and `~/.codex/config.toml` examples.
+
+## Installation
+
+To install the CLI
+
+```sh
+echo 'i will eventually have a url to download the CLI and stuff'
+```
+
+
+