@soederpop/luca 0.0.2

package/src/clients/supabase/index.ts

@@ -0,0 +1,366 @@
+import {
+  Client,
+  type ClientOptions,
+  type ClientsInterface,
+  clients,
+} from "@soederpop/luca/client";
+import type { Container, ContainerContext } from "@soederpop/luca/container";
+import { z } from "zod";
+import {
+  ClientStateSchema,
+  ClientOptionsSchema,
+  ClientEventsSchema,
+} from "@soederpop/luca/schemas/base.js";
+import {
+  createClient,
+  type SupabaseClient as SupabaseSDKClient,
+  type SupabaseClientOptions as SupabaseSDKOptions,
+  type RealtimeChannel,
+} from "@supabase/supabase-js";
+
+declare module "@soederpop/luca/client" {
+  interface AvailableClients {
+    supabase: typeof SupabaseClient;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export const SupabaseClientOptionsSchema = ClientOptionsSchema.extend({
+  supabaseUrl: z
+    .string()
+    .describe("The Supabase project URL (e.g. https://xyz.supabase.co)"),
+  supabaseKey: z
+    .string()
+    .describe("The Supabase anon or service-role key"),
+  clientOptions: z
+    .record(z.string(), z.any())
+    .optional()
+    .describe(
+      "Pass-through options forwarded directly to the Supabase SDK createClient()"
+    ),
+}).describe("Options for creating a Supabase client");
+
+export const SupabaseClientStateSchema = ClientStateSchema.extend({
+  authenticated: z
+    .boolean()
+    .default(false)
+    .describe("Whether a user session is currently active"),
+  userId: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The authenticated user's ID, if any"),
+  userEmail: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The authenticated user's email, if any"),
+  realtimeChannels: z
+    .array(z.string())
+    .default([])
+    .describe("Names of currently subscribed realtime channels"),
+  lastError: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The most recent error message, if any"),
+}).describe("Supabase client state");
+
+export const SupabaseClientEventsSchema = ClientEventsSchema.extend({
+  authStateChange: z
+    .tuple([
+      z.string().describe("The auth event name (e.g. SIGNED_IN, SIGNED_OUT)"),
+      z.any().describe("The session object"),
+    ])
+    .describe("Emitted when the auth state changes"),
+  realtimeMessage: z
+    .tuple([
+      z.string().describe("The channel name"),
+      z.any().describe("The payload"),
+    ])
+    .describe("Emitted when a realtime message is received"),
+  realtimeStatus: z
+    .tuple([
+      z.string().describe("The channel name"),
+      z.string().describe("The status (e.g. SUBSCRIBED, CLOSED)"),
+    ])
+    .describe("Emitted when a realtime channel status changes"),
+  error: z
+    .tuple([z.any().describe("The error object")])
+    .describe("Emitted on any Supabase error"),
+}).describe("Supabase client events");
+
+export type SupabaseClientOptions = z.infer<typeof SupabaseClientOptionsSchema>;
+export type SupabaseClientState = z.infer<typeof SupabaseClientStateSchema>;
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+/**
+ * Supabase client for the Luca container system.
+ *
+ * Wraps the official `@supabase/supabase-js` SDK and exposes it through Luca's
+ * typed state, events, and introspection system. The SDK is isomorphic so this
+ * single implementation works in both Node and browser containers.
+ *
+ * Use `client.sdk` for full SDK access, or use the convenience wrappers for
+ * common operations (auth, database queries, storage, edge functions, realtime).
+ *
+ * @example
+ * ```typescript
+ * const supabase = container.client('supabase', {
+ *   supabaseUrl: 'https://xyz.supabase.co',
+ *   supabaseKey: 'your-anon-key',
+ * })
+ *
+ * // Query data
+ * const { data } = await supabase.from('users').select('*')
+ *
+ * // Auth
+ * await supabase.signInWithPassword('user@example.com', 'password')
+ *
+ * // Realtime
+ * supabase.subscribe('changes', 'users', (payload) => {
+ *   console.log('Change:', payload)
+ * })
+ * ```
+ */
+export class SupabaseClient extends Client<
+  SupabaseClientState,
+  SupabaseClientOptions
+> {
+  static override shortcut = "clients.supabase" as const;
+  static override description =
+    "Supabase client wrapping the official SDK with typed state, events, and realtime channel management";
+
+  static override stateSchema = SupabaseClientStateSchema;
+  static override optionsSchema = SupabaseClientOptionsSchema;
+  static override eventsSchema = SupabaseClientEventsSchema;
+
+  private _sdk!: SupabaseSDKClient<any, any>;
+  private _channels = new Map<string, RealtimeChannel>();
+
+  // @ts-ignore - required options (supabaseUrl, supabaseKey) widen beyond base ClientOptions
+  static attach(container: Container & ClientsInterface, options?: any) {
+    // @ts-ignore
+    container.clients.register("supabase", SupabaseClient);
+    return container;
+  }
+
+  constructor(options: SupabaseClientOptions, context: ContainerContext) {
+    super(options, context);
+
+    const sdkOptions = (options.clientOptions ?? {}) as SupabaseSDKOptions<string>;
+    this._sdk = createClient(options.supabaseUrl, options.supabaseKey, sdkOptions);
+
+    this._sdk.auth.onAuthStateChange((event, session) => {
+      const user = session?.user;
+      this.state.set("authenticated", !!session);
+      this.state.set("userId", user?.id ?? null);
+      this.state.set("userEmail", user?.email ?? null);
+      this.emit("authStateChange" as any, event, session);
+    });
+
+    this.state.set("connected", true);
+  }
+
+  // ---------------------------------------------------------------------------
+  // SDK access
+  // ---------------------------------------------------------------------------
+
+  /** Returns the raw Supabase SDK client for full access to all SDK methods. */
+  get sdk(): SupabaseSDKClient<any, any> {
+    return this._sdk;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Database
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Start a query on a Postgres table or view.
+   * @param table - The table or view name to query
+   */
+  from(table: string) {
+    return this._sdk.from(table);
+  }
+
+  /**
+   * Call a Postgres function (RPC).
+   * @param fn - The function name
+   * @param params - Arguments to pass to the function
+   * @param options - Optional settings (head, get, count)
+   */
+  rpc(fn: string, params?: Record<string, unknown>, options?: { head?: boolean; get?: boolean; count?: "exact" | "planned" | "estimated" }) {
+    return this._sdk.rpc(fn, params, options);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Auth
+  // ---------------------------------------------------------------------------
+
+  /** Sign in with email and password. */
+  async signInWithPassword(email: string, password: string) {
+    const result = await this._sdk.auth.signInWithPassword({ email, password });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Create a new user account with email and password. */
+  async signUp(email: string, password: string) {
+    const result = await this._sdk.auth.signUp({ email, password });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Sign the current user out. */
+  async signOut() {
+    const result = await this._sdk.auth.signOut();
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Get the current session, if any. */
+  async getSession() {
+    return this._sdk.auth.getSession();
+  }
+
+  /** Get the current user, if any. */
+  async getUser() {
+    return this._sdk.auth.getUser();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Storage
+  // ---------------------------------------------------------------------------
+
+  /** Returns the Supabase Storage client for managing buckets and files. */
+  get storage() {
+    return this._sdk.storage;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Edge Functions
+  // ---------------------------------------------------------------------------
+
+  /** Returns the Supabase Functions client. */
+  get functions() {
+    return this._sdk.functions;
+  }
+
+  /** Invoke a Supabase Edge Function by name. */
+  async invoke(name: string, body?: any) {
+    const result = await this._sdk.functions.invoke(name, { body });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Realtime
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Subscribe to realtime changes on a Postgres table.
+   * @param channelName - A name for this subscription channel
+   * @param table - The table to listen to
+   * @param callback - Called with the payload on each change
+   * @param event - The event type to listen for (default: all changes)
+   */
+  subscribe(
+    channelName: string,
+    table: string,
+    callback: (payload: any) => void,
+    event: "INSERT" | "UPDATE" | "DELETE" | "*" = "*"
+  ): RealtimeChannel {
+    const channel = this._sdk
+      .channel(channelName)
+      .on(
+        "postgres_changes" as any,
+        { event, schema: "public", table },
+        (payload: any) => {
+          this.emit("realtimeMessage" as any, channelName, payload);
+          callback(payload);
+        }
+      )
+      .subscribe((status: string) => {
+        this.emit("realtimeStatus" as any, channelName, status);
+      });
+
+    this._channels.set(channelName, channel);
+    this._syncChannelState();
+    return channel;
+  }
+
+  /**
+   * Unsubscribe and remove a realtime channel by name.
+   * @param channelName - The channel name to remove
+   */
+  async unsubscribe(channelName: string) {
+    const channel = this._channels.get(channelName);
+    if (channel) {
+      await this._sdk.removeChannel(channel);
+      this._channels.delete(channelName);
+      this._syncChannelState();
+    }
+  }
+
+  /** Unsubscribe and remove all realtime channels. */
+  async unsubscribeAll() {
+    await this._sdk.removeAllChannels();
+    this._channels.clear();
+    this._syncChannelState();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Connect is a no-op since the Supabase SDK initializes on construction.
+   * The client is ready to use immediately after creation.
+   */
+  override async connect() {
+    this.state.set("connected", true);
+    return this;
+  }
+
+  /**
+   * Disconnect by signing out and removing all realtime channels.
+   */
+  async disconnect() {
+    await this.unsubscribeAll();
+    await this._sdk.auth.signOut();
+    this.state.set("connected", false);
+    this.state.set("authenticated", false);
+    this.state.set("userId", null);
+    this.state.set("userEmail", null);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private _syncChannelState() {
+    this.state.set("realtimeChannels", Array.from(this._channels.keys()));
+  }
+
+  private _setError(message: string) {
+    this.state.set("lastError", message);
+    this.emit("error" as any, new Error(message));
+  }
+}
+
+// @ts-ignore
+clients.register("supabase", SupabaseClient);

package/src/command.ts

@@ -0,0 +1,164 @@
+import { Helper } from './helper.js'
+import type { Container, ContainerContext } from './container.js'
+import { Registry } from './registry.js'
+import { CommandStateSchema, CommandOptionsSchema, CommandEventsSchema } from './schemas/base.js'
+import { z } from 'zod'
+import { join } from 'path'
+
+export type CommandState = z.infer<typeof CommandStateSchema>
+export type CommandOptions = z.infer<typeof CommandOptionsSchema>
+
+export interface AvailableCommands {}
+
+export type CommandFactory = <T extends keyof AvailableCommands>(
+	key: T,
+	options?: ConstructorParameters<AvailableCommands[T]>[0]
+) => NonNullable<InstanceType<AvailableCommands[T]>>
+
+export interface CommandsInterface {
+	commands: CommandsRegistry
+	command: CommandFactory
+}
+
+export type CommandHandler<T = any> = (options: T, context: ContainerContext) => Promise<void>
+
+export class Command<
+	T extends CommandState = CommandState,
+	K extends CommandOptions = CommandOptions
+> extends Helper<T, K> {
+	static override shortcut = 'commands.base'
+	static override description = 'Base command'
+	static override stateSchema = CommandStateSchema
+	static override optionsSchema = CommandOptionsSchema
+	static override eventsSchema = CommandEventsSchema
+
+	static commandDescription: string = ''
+	static argsSchema: z.ZodType = CommandOptionsSchema
+
+	override get initialState(): T {
+		return ({ running: false } as unknown) as T
+	}
+
+	parseArgs(): any {
+		const schema = (this.constructor as typeof Command).argsSchema
+		return schema.parse(this.container.options)
+	}
+
+	async execute(): Promise<void> {
+		// override in subclass
+	}
+
+	async run(): Promise<void> {
+		// Intercept --help before the command executes
+		if (this.container.argv.help) {
+			const { formatCommandHelp } = await import('./commands/help.js')
+			const ui = (this.container as any).feature('ui')
+			const name = (this.constructor as typeof Command).shortcut?.replace('commands.', '') || 'unknown'
+			console.log(formatCommandHelp(name, this.constructor, ui.colors))
+			return
+		}
+
+		this.state.set('running', true)
+		this.emit('started')
+
+		try {
+			await this.execute()
+			this.state.set('running', false)
+			this.state.set('exitCode', 0)
+			this.emit('completed', 0)
+		} catch (err: any) {
+			this.state.set('running', false)
+			this.state.set('exitCode', 1)
+			this.emit('failed', err)
+			throw err
+		}
+	}
+
+	static attach(container: Container<any> & CommandsInterface) {
+		container.commands = commands
+
+		Object.assign(container, {
+			command<T extends keyof AvailableCommands>(
+				id: T,
+				options?: ConstructorParameters<AvailableCommands[T]>[0]
+			): NonNullable<InstanceType<AvailableCommands[T]>> {
+				const BaseClass = commands.lookup(id as string) as any
+
+				return container.createHelperInstance({
+					cache: helperCache,
+					type: 'command',
+					id: String(id),
+					BaseClass,
+					options,
+					fallbackName: String(id),
+				}) as NonNullable<InstanceType<AvailableCommands[T]>>
+			},
+		})
+
+		container.registerHelperType('commands', 'command')
+		return container
+	}
+}
+
+export class CommandsRegistry extends Registry<Command<any>> {
+	override scope = 'commands'
+	override baseClass = Command as any
+
+	registerHandler<T = any>(
+		name: string,
+		opts: {
+			description?: string
+			argsSchema?: z.ZodType
+			handler: CommandHandler<T>
+		},
+	) {
+		const handler = opts.handler
+		const argsSchema = opts.argsSchema || CommandOptionsSchema
+		const desc = opts.description || ''
+
+		const CommandClass = class extends Command {
+			static override shortcut = `commands.${name}` as const
+			static override description = desc
+			static override commandDescription = desc
+			static override optionsSchema = argsSchema as any
+			static override argsSchema = argsSchema
+
+			override async execute() {
+				await handler(this.parseArgs(), this.context)
+			}
+		}
+
+		Object.defineProperty(CommandClass, 'name', { value: `${name}Command` })
+
+		return this.register(name, CommandClass as any)
+	}
+
+	async discover(options: { directory: string }) {
+		const { Glob } = globalThis.Bun || (await import('bun'))
+		const glob = new Glob('*.ts')
+
+		for await (const file of glob.scan({ cwd: options.directory })) {
+			if (file === 'index.ts') continue
+
+			const mod = await import(join(options.directory, file))
+			const commandModule = mod.default || mod
+
+			// Support export-based command files (like endpoints).
+			// If the module exports a handler function, register it
+			// using the filename as the command name.
+			if (typeof commandModule.handler === 'function' && !this.has(file.replace(/\.ts$/, ''))) {
+				const name = file.replace(/\.ts$/, '')
+				this.registerHandler(name, {
+					description: commandModule.description || '',
+					argsSchema: commandModule.argsSchema,
+					handler: commandModule.handler,
+				})
+			}
+		}
+	}
+}
+
+export const commands = new CommandsRegistry()
+export const helperCache = new Map()
+
+export default Command

package/src/commands/chat.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod'
+import * as readline from 'readline'
+import { commands } from '../command'
+import { CommandOptionsSchema } from '../schemas/base'
+import type { ContainerContext } from '../container'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		chat: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	model: z.string().optional().describe('Override the LLM model for the assistant'),
+	folder: z.string().default('assistants').describe('Directory containing assistant definitions'),
+	resume: z.string().optional().describe('Thread ID or conversation ID to resume'),
+	list: z.boolean().optional().describe('List recent conversations and exit'),
+	historyMode: z.enum(['lifecycle', 'daily', 'persistent', 'session']).optional().describe('Override history persistence mode'),
+	offRecord: z.boolean().optional().describe('Alias for --history-mode lifecycle (ephemeral, no persistence)'),
+})
+
+export default async function chat(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const ui = container.feature('ui')
+
+	const manager = container.feature('assistantsManager', { folder: options.folder })
+	manager.discover()
+
+	const entries = manager.list()
+
+	if (entries.length === 0) {
+		console.error(ui.colors.red('No assistants found.'))
+		console.error(ui.colors.dim(`  Create an assistant directory in "${options.folder}/" with a CORE.md file.`))
+		process.exit(1)
+	}
+
+	const requestedName = container.argv._[1] as string | undefined
+	let name: string
+
+	if (requestedName) {
+		const entry = manager.get(requestedName)
+		if (!entry) {
+			const available = entries.map((e: any) => e.name).join(', ')
+			console.error(ui.colors.red(`Assistant "${requestedName}" not found.`))
+			console.error(ui.colors.dim(`  Available: ${available}`))
+			process.exit(1)
+		}
+		name = requestedName
+	} else if (entries.length === 1) {
+		name = entries[0].name
+	} else {
+		const answers = await ui.wizard([
+			{
+				type: 'list',
+				name: 'assistant',
+				message: 'Choose an assistant',
+				choices: entries.map((e: any) => ({ name: e.name, value: e.name })),
+			},
+		])
+		name = answers.assistant
+	}
+
+	// Resolve history mode: --off-record overrides everything to lifecycle
+	// CLI defaults to 'daily' for interactive persistence
+	const historyMode = options.offRecord
+		? 'lifecycle'
+		: (options.historyMode || 'daily')
+
+	const createOptions: Record<string, any> = { historyMode }
+	if (options.model) createOptions.model = options.model
+
+	const assistant = manager.create(name, createOptions)
+
+	// --list: show recent conversations and exit
+	if (options.list) {
+		const history = await assistant.listHistory({ limit: 20 })
+		if (history.length === 0) {
+			console.log(ui.colors.dim('  No saved conversations.'))
+		} else {
+			console.log()
+			console.log(ui.colors.dim('  Recent conversations:'))
+			console.log()
+			for (const meta of history) {
+				const date = new Date(meta.updatedAt).toLocaleString()
+				const msgs = ui.colors.dim(`(${meta.messageCount} messages)`)
+				console.log(`  ${ui.colors.cyan(meta.thread)} ${msgs}`)
+				console.log(`    ${ui.colors.dim(date)} - ${meta.title}`)
+			}
+			console.log()
+			console.log(ui.colors.dim(`  Resume with: luca chat ${name} --resume <thread-id>`))
+		}
+		return
+	}
+
+	// --resume: set thread override before start
+	if (options.resume) {
+		assistant.resumeThread(options.resume)
+	}
+
+	let isFirstChunk = true
+
+	assistant.on('chunk', (text: string) => {
+		if (isFirstChunk) {
+			process.stdout.write('\n')
+			isFirstChunk = false
+		}
+		process.stdout.write(text)
+	})
+
+	assistant.on('toolCall', (toolName: string, args: any) => {
+		const argsStr = JSON.stringify(args).slice(0, 120)
+		process.stdout.write(ui.colors.dim(`\n  ⟳ ${toolName}`) + ui.colors.dim(`(${argsStr})\n`))
+	})
+
+	assistant.on('toolResult', (toolName: string, result: any) => {
+		const preview = typeof result === 'string' ? result.slice(0, 100) : JSON.stringify(result).slice(0, 100)
+		process.stdout.write(ui.colors.green(`  ✓ ${toolName}`) + ui.colors.dim(` → ${preview}${preview.length >= 100 ? '…' : ''}\n`))
+	})
+
+	assistant.on('toolError', (toolName: string, error: any) => {
+		const msg = error?.message || String(error)
+		process.stdout.write(ui.colors.red(`  ✗ ${toolName}: ${msg}\n`))
+	})
+
+	assistant.on('response', () => {
+		process.stdout.write('\n')
+		isFirstChunk = true
+	})
+
+	// Start the assistant (loads history if applicable)
+	await assistant.start()
+
+	const messageCount = assistant.messages?.length || 0
+	const isResuming = historyMode !== 'lifecycle' && messageCount > 1
+
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	})
+
+	function prompt(): Promise<string> {
+		return new Promise((resolve) => {
+			rl.question(ui.colors.dim(`\n${name} > `), (answer: string) => resolve(answer.trim()))
+		})
+	}
+
+	console.log()
+	if (isResuming) {
+		console.log(ui.colors.dim(`  Resuming conversation with ${ui.colors.cyan(name)} (${messageCount} messages). Type .exit to quit.`))
+	} else {
+		console.log(ui.colors.dim(`  Chatting with ${ui.colors.cyan(name)}. Type .exit to quit.`))
+	}
+	if (historyMode !== 'lifecycle') {
+		console.log(ui.colors.dim(`  Mode: ${historyMode}`))
+	}
+	console.log()
+
+	while (true) {
+		const question = await prompt()
+
+		if (!question) continue
+		if (question === '.exit') break
+
+		await assistant.ask(question)
+	}
+
+	rl.close()
+
+	// Show resume instruction for non-lifecycle modes
+	if (historyMode !== 'lifecycle' && assistant.currentThreadId) {
+		console.log()
+		console.log(ui.colors.dim(`  Session saved. To resume this conversation:`))
+		console.log(ui.colors.dim(`    luca chat ${name} --resume ${assistant.currentThreadId}`))
+		console.log()
+	}
+}
+
+commands.registerHandler('chat', {
+	description: 'Start an interactive chat session with a local assistant',
+	argsSchema,
+	handler: chat,
+})