@soederpop/luca 0.0.3 → 0.0.4

package/commands/update-introspection.ts

@@ -1,67 +0,0 @@
-import { z } from 'zod'
-import type { ContainerContext } from '@soederpop/luca'
-import { CommandOptionsSchema } from '@soederpop/luca/schemas'
-import '../src/introspection/scan.js'
-import { NodeContainer } from '../src/node/container.js'
-
-export const argsSchema = CommandOptionsSchema.extend({})
-
-const targets = [
-  {
-    name: 'node',
-    src: ['src/node/features', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
-    outputPath: 'src/introspection/generated.node.ts',
-  },
-  {
-    name: 'web',
-    src: ['src/web/features', 'src/container.ts', 'src/web/container.ts'],
-    outputPath: 'src/introspection/generated.web.ts',
-  },
-  {
-    name: 'agi',
-    src: ['src/node/features', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
-    outputPath: 'src/introspection/generated.agi.ts',
-  },
-]
-
-/**
- * Generates per-container introspection metadata files.
- *
- * Each container type gets its own generated file containing only the
- * metadata relevant to that environment:
- *
- * - generated.node.ts: node features + servers
- * - generated.web.ts: web features
- * - generated.agi.ts: node features + servers + agi features
- */
-async function updateIntrospection(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const container = new NodeContainer()
-
-  for (const target of targets) {
-    console.log(`\n📦 Generating ${target.name} introspection data...`)
-    console.log(`   📁 Sources: ${target.src.join(', ')}`)
-    console.log(`   📄 Output: ${target.outputPath}`)
-
-    const scanner = container.feature('introspectionScanner', {
-      src: target.src,
-      outputPath: target.outputPath,
-    })
-
-    scanner.on('scanCompleted', (data) => {
-      console.log(`   ✅ Found ${data.results} helpers in ${data.files} files (${data.duration}ms)`)
-    })
-
-    await scanner.scan()
-    await scanner.generateRegistryScript()
-
-    console.log(`   📝 Wrote ${target.outputPath}`)
-  }
-
-  console.log('\n✨ All introspection data generated.')
-}
-
-export default {
-  description: 'Generate per-container introspection metadata files from source.',
-  argsSchema,
-  handler: updateIntrospection,
-}

package/docs/ideas/class-registration-refactor-possibilities.md

@@ -1,197 +0,0 @@
----
-tags: [dx, registration, metaprogramming]
-status: spark
----
-
-# Class Registration Refactor Possibilities
-
-Exploring how static initialization blocks and class-level hooks could simplify helper registration, inspired by Ruby's `self.inherited(subclass)` pattern and how ActiveRecord::Base uses it.
-
-## The Ruby Inspiration
-
-In Ruby, when you write `class Post < ActiveRecord::Base`, the `inherited` hook fires automatically:
-
-```ruby
-class ActiveRecord::Base
-  def self.inherited(subclass)
-    subclass.table_name = subclass.name.tableize
-    subclass.establish_connection
-    # The parent configures the child at definition time
-  end
-end
-
-class Post < ActiveRecord::Base
-end
-# That's it. Full ORM-backed model. No registration call needed.
-```
-
-The magic: `inherited` fires at **class definition time**, receives the subclass, and lets the parent **reach into the child and set it up**. The empty class that does everything.
-
-## Current Luca Registration Pattern
-
-Today, every helper requires explicit registration at the bottom of the file:
-
-```typescript
-// src/node/features/fs.ts
-import { features, Feature } from "../feature.js"
-
-export class FS extends Feature {
-  static override shortcut = "features.fs" as const
-  static override stateSchema = FeatureStateSchema
-  static override optionsSchema = FeatureOptionsSchema
-
-  // ... methods ...
-}
-
-export default features.register("fs", FS)
-```
-
-And for extension features (AGI, etc), there's the `attach` pattern:
-
-```typescript
-export class Assistant extends Feature<AssistantState, AssistantOptions> {
-  static attach(container: Container<AvailableFeatures, any>) {
-    features.register('assistant', Assistant)
-    return container
-  }
-}
-
-export default features.register('assistant', Assistant)
-```
-
-The registration is always a separate, imperative call disconnected from the class definition itself. The class doesn't know it's been registered. The registry doesn't know until that line runs.
-
-## The Static Block Approach
-
-ES2022 static initialization blocks let code run at **class definition time**, inside the class body. This is JavaScript's closest equivalent to Ruby's `inherited`:
-
-```typescript
-class Feature {
-  static registry: Registry
-
-  // This is our "inherited" hook
-  static __initSubclass(SubClass: typeof Feature, id: string) {
-    this.registry.register(id, SubClass)
-  }
-}
-```
-
-### What it could look like for authors
-
-```typescript
-// The dream: define, register, and export in one declaration
-export default class FS extends Feature {
-  static {
-    Feature.register(this, "fs")
-  }
-
-  static override shortcut = "features.fs" as const
-  static override stateSchema = FeatureStateSchema
-  static override optionsSchema = FeatureOptionsSchema
-
-  async readFile(path: string) { /* ... */ }
-}
-```
-
-No trailing `features.register()` call. No disconnect between the class and its registration. The class **declares itself** as a registered member of the system.
-
-### The id could be derived from convention
-
-If we adopt a naming convention (like ActiveRecord derives table names from class names), we could eliminate the explicit id entirely:
-
-```typescript
-export default class DiskCache extends Feature {
-  static {
-    Feature.register(this) // id inferred as "diskCache" from class name
-  }
-}
-```
-
-The `register` implementation:
-
-```typescript
-class Feature {
-  static register(SubClass: typeof Feature, id?: string) {
-    // Convention: PascalCase class name -> camelCase registry id
-    const registryId = id ?? SubClass.name[0].toLowerCase() + SubClass.name.slice(1)
-    features.register(registryId, SubClass)
-  }
-}
-```
-
-## Going Further: The Base Class Does All The Work
-
-What if the base classes (`Feature`, `Client`, `Server`) provided a static `register` that also handled module augmentation hints and the `attach` pattern?
-
-```typescript
-// Before: 15+ lines of boilerplate per feature
-import { z } from 'zod'
-import { features, Feature } from '@soederpop/luca/feature'
-import type { AvailableFeatures } from '@soederpop/luca/feature'
-
-declare module '@soederpop/luca/feature' {
-  interface AvailableFeatures {
-    conversation: typeof Conversation
-  }
-}
-
-export class Conversation extends Feature<ConversationState, ConversationOptions> {
-  static override shortcut = 'features.conversation' as const
-  static attach(container: Container<AvailableFeatures, any>) {
-    features.register('conversation', Conversation)
-    return container
-  }
-  // ...
-}
-
-export default features.register('conversation', Conversation)
-```
-
-```typescript
-// After: the class IS the registration
-import { Feature } from '@soederpop/luca/feature'
-
-export default class Conversation extends Feature<ConversationState, ConversationOptions> {
-  static {
-    Feature.register(this, 'conversation')
-  }
-
-  // shortcut derived automatically from registry + id
-  // attach() provided by base class using the registered id
-  // ...
-}
-```
-
-The base `Feature.register()` could:
-1. Call `features.register(id, SubClass)`
-2. Set `SubClass.shortcut` automatically (`features.${id}`)
-3. Generate a default `attach()` that registers and returns the container
-4. Emit a `"subclass:registered"` event on the registry for any other wiring
-
-## Comparison With Other Approaches
-
-| Approach | When it runs | Cooperation needed | Ceremony |
-|----------|-------------|-------------------|----------|
-| Ruby `inherited` | Class definition | None | Zero — just `extends` |
-| Static block + `register` | Class definition | One line in static block | Minimal — inside the class |
-| Trailing `registry.register()` | Module evaluation | Separate call after class | Moderate — disconnected |
-| `defineFeature()` factory | Module evaluation | Wrap entire definition | Different paradigm entirely |
-| Decorators (`@tracked`) | Class definition | One line above class | Minimal — but external |
-
-The static block approach is the sweet spot for Luca: it's **standard JavaScript**, runs at **definition time**, lives **inside the class body**, and keeps the class as the primary authoring unit (unlike `defineFeature()` which replaces the class with a factory call).
-
-## The `defineFeature` Relationship
-
-This is complementary to the [`defineFeature()` idea](./luca-feature-authoring-dx.md), not a replacement. They solve different problems:
-
-- **`defineFeature()`** reduces boilerplate for simple features that are mostly a bag of methods — you skip writing a class entirely
-- **Static block registration** reduces boilerplate for full class-based helpers — you still write the class, but registration is self-contained
-
-For complex features that need class inheritance, lifecycle hooks, and full OOP — the static block pattern is cleaner. For simple features that are essentially a named collection of functions — `defineFeature()` is cleaner.
-
-## Open Questions
-
-- **Registry detection**: Can `Feature.register(this)` figure out which registry to use automatically? The base class (`Feature` vs `Client` vs `Server`) already implies it. A shared `Helper.register(this)` could dispatch to the right registry.
-- **Module augmentation**: The `declare module` blocks for TypeScript are the remaining boilerplate that can't be eliminated by runtime mechanics. Could a codegen step or a TS plugin handle this?
-- **Import side effects**: Today, importing a feature file triggers registration. With static blocks, this is still true — but the registration is more visible and intentional. Is there value in making registration lazy or explicit via `container.use()`?
-- **`attach()` consolidation**: Many `attach()` methods just call `register()` and return the container. If `Feature.register()` generates a default `attach()`, do we still need custom ones? The ones that do more (like wiring up other features) would still override.

package/docs/ideas/container-use-api.md

@@ -1,9 +0,0 @@
-# COntainer `.use()` API
-
-Can we find a way to support using dynamic imports
-
-```ts
-container.use(import("whatever))
-```
-
-these are promises, but the expectation is the default has an attach method.  if not, any function or class they export which has an attach property

package/docs/ideas/feature-stacks.md

@@ -1,22 +0,0 @@
-# Feature Stacks
-
-The number of features in the node container is getting a little absurd.
-
-We have the `container.use` API.  We can bundle / group features like the google related ones into their own folder's and start to build on our plugin / layers concept
-
-The startup time for the luca cli is getting slower and I'm wondering if it is all of these features causing it.
-
-## Group features into folders
-
-- don't autoload all of them, let's make it trivial like to load these features into scripts or commands 
-
-```ts
-import container from '@soederpop/luca/agi'
-import GoogleFeatures from '@soederpop/luca/features/google'
-
-container.use(GoogleFeatures)
-```
-
-## Feature Marketplace ( long term )
-
-Long term as I'm the only one using this shit, but the ability to publish a server that other containers could load features from is cool.  We have all the pieces on the frontend ( asset loader ) to go from a blankpage to a fully functional SPA 

package/docs/ideas/luca-cli-self-sufficiency-demo.md

@@ -1,23 +0,0 @@
-# Luca CLI Self Sufficiency Demo
-
-With the `luca` cli you can have a project folder like:
-
-```
-- public/
-	- index.html
-- commands/
-	- setup-db.ts
-- endpoints/
-	- health.ts
-- docs/
-	- models.ts
-- luca.cli.ts
-```
-
-This should work without there necessarily being a `node_modules` folder here, because each of these things are loaded by luca, transpiled, and run through the VM.
-
-Even the `contentDb` feature which depends on contentbase should work here.
-
-This is what I mean by luca being a dependency injection framework.
-
-The only downside of this is - how do we provide type support without them installing '@soederpop/luca'

package/docs/ideas/mcp-design.md

@@ -1,9 +0,0 @@
-# MCP Design
-
-I have a hunch that the best way to get coding assistants to be aware of our MCP is to have as verbose of tool descriptions as the spec allows, as this seems to be the primary form of guidance.
-
-One neat trick I learned from the excalidraw and other mcps is to have a tool_call called read_me, which we can probably really tune the tool description for, to make sure it gets called as early on as possible by the MCP, and as a way to further refine how it understands to use tool calls.
-
-## Current State
-
-We've got a `luca sandbox-mcp` command in this project which can be used to eval snippets of code inside the luca vm, as well as some other tools.  Claude code consistently fails to use them, however.

package/docs/ideas/web-container-debugging-feature.md

@@ -1,13 +0,0 @@
-# Web Container Debugging Feature
-
-How cool would it be if, from an application that uses WebContainer, we had a client side feature called `serverPlug` 
-
-The `serverPlug` would `connect` to a remote server over an API endpoint, to register itself, with info about the url it is on, its container's uuid.  The server would respond with a websocket url and other necessary info.
-
-On the server side `NodeContainer` there's server side `serverPlug` feature which can act as a host, that accepts registrations.  It spawns its own websocket server to handle communication.
-
-From server side code, I can connect to any individual web container instance, and eval code inside its vm.
-
-We need to think about auth, disconnection events, heartbeats, etc
-
-

package/scripts/animations/chrome-glitch.ts

@@ -1,55 +0,0 @@
-import type { AsciiAnimation } from './types'
-
-const frames = [
-  String.raw`
-      ######   ######  ########
-      ##  ##   ##  ##     ##
-      ######   ##  ##     ##
-      ##  ##   ##  ##     ##
-      ##  ##   ######     ##
-      ##  ##   ######     ##
-
-         [o_o]  channel-open
-          /|\   packet-sync
-          / \   pulse: 71%
-
-      <<..................>>
-`,
-  String.raw`
-      ######   ######  ########
-      ##  ##   ##  ##     ##
-      ######   ##  ##     ##
-      ##  ##   ##  ##     ##
-      ##  ##   ######     ##
-      ##  ##   ######     ##
-
-         [0_0]  channel-open
-          /|\   packet-sync
-          / \   pulse: 84%
-
-      <<##..##..##..##..##..>>
-`,
-  String.raw`
-      ######   ######  ########
-      ##  ##   ##  ##     ##
-      ######   ##  ##     ##
-      ##  ##   ##  ##     ##
-      ##  ##   ######     ##
-      ##  ##   ######     ##
-
-         [O_O]  channel-open
-          /|\   packet-sync
-          / \   pulse: 96%
-
-      <<##################>>
-`,
-]
-
-const chromeGlitch: AsciiAnimation = {
-  id: 'chromeGlitch',
-  name: 'Chrome Glitch Totem',
-  fps: 5,
-  frames,
-}
-
-export default chromeGlitch

package/scripts/animations/index.ts

@@ -1,16 +0,0 @@
-import type { AsciiAnimation } from './types'
-import neonPulse from './neon-pulse'
-import chromeGlitch from './chrome-glitch'
-
-const animations: AsciiAnimation[] = [neonPulse, chromeGlitch]
-
-export function listAnimations(): AsciiAnimation[] {
-  return animations
-}
-
-export function resolveAnimation(id: string): AsciiAnimation {
-  const match = animations.find((animation) => animation.id.toLowerCase() === id.toLowerCase())
-  if (match) return match
-  if (!animations[0]) throw new Error('No animations are registered.')
-  return animations[0]
-}

package/scripts/animations/neon-pulse.ts

@@ -1,64 +0,0 @@
-import type { AsciiAnimation } from './types'
-
-const frames = [
-  String.raw`
-             .-""-.
-           .' .--. '.
-          /  /    \  \
-          | | 0  0 | |
-          | |  __  | |
-          | | /__\ | |
-          | | \__/ | |
-          | |      | |
-         /|  '.__.'  |\
-       .' |   /::\   | '.
-      /   |  |::::|  |   \
-     /____|__|::::|__|____\
-        /_/   |::|   \_\
-             /____\
-     ~ ~ ~  SIGNAL: STABLE  ~ ~ ~
-`,
-  String.raw`
-             .-""-.
-           .' .--. '.
-          /  / /\ \  \
-          | | ^  ^ | |
-          | |  --  | |
-          | | /__\ | |
-          | | \__/ | |
-          | |  /\  | |
-         /|  '.__.'  |\
-       .' |  _/::\_  | '.
-      /   | |::::::| |   \
-     /____|_|::::::|_|____\
-        /_/   |::|   \_\
-             /____\
-     ~ ~ ~  SIGNAL: BREATHING  ~ ~ ~
-`,
-  String.raw`
-             .-""-.
-           .' .--. '.
-          /  / __ \  \
-          | | o  o | |
-          | |  ..  | |
-          | | /__\ | |
-          | | \__/ | |
-          | | .--. | |
-         /|  '.__.'  |\
-       .' |   /::\   | '.
-      /   |  |::::|  |   \
-     /____|__|::::|__|____\
-        /_/   |::|   \_\
-             /____\
-     ~ ~ ~  SIGNAL: SCANNING  ~ ~ ~
-`,
-]
-
-const neonPulse: AsciiAnimation = {
-  id: 'neonPulse',
-  name: 'Neon Pulse Bot',
-  fps: 4,
-  frames,
-}
-
-export default neonPulse

package/scripts/animations/types.ts

@@ -1,6 +0,0 @@
-export interface AsciiAnimation {
-  id: string
-  name: string
-  fps: number
-  frames: string[]
-}