@plumbus/core 0.1.0

package/instructions/ai.md

@@ -0,0 +1,183 @@
+# AI Runtime
+
+Plumbus provides structured AI interactions through prompts and the `ctx.ai` service.
+
+## Defining a Prompt
+
+```ts
+import { definePrompt } from "@plumbus/core";
+import { z } from "zod";
+
+export const summarizeTicket = definePrompt({
+  name: "summarizeTicket",
+  domain: "support",
+
+  input: z.object({ ticketText: z.string(), customerTier: z.string() }),
+  output: z.object({
+    summary: z.string(),
+    priority: z.enum(["low", "medium", "high"]),
+    sentiment: z.enum(["positive", "neutral", "negative"]),
+  }),
+
+  // provider and model are resolved from config/env at runtime — only set tuning params here
+  model: {
+    temperature: 0.3,
+    maxTokens: 500,
+  },
+});
+```
+
+Prompts should NOT hardcode `provider` or model `name`. These are resolved at runtime through the configuration chain (see below). Only set `temperature` and `maxTokens` in the prompt definition.
+
+## `ctx.ai` Operations
+
+### Generate
+
+Invoke a named prompt with typed input, get validated output:
+
+```ts
+const result = await ctx.ai.generate({
+  prompt: "summarizeTicket",
+  input: { ticketText: input.text, customerTier: "enterprise" },
+});
+// result is typed: { summary: string, priority: "low"|"medium"|"high", sentiment: ... }
+```
+
+### Extract
+
+Extract structured data from text using a Zod schema:
+
+```ts
+const invoice = await ctx.ai.extract({
+  schema: z.object({ invoiceNumber: z.string(), total: z.number(), dueDate: z.string() }),
+  text: input.emailBody,
+});
+```
+
+### Classify
+
+Classify text into provided categories:
+
+```ts
+const labels = await ctx.ai.classify({
+  labels: ["billing", "technical", "general", "urgent"],
+  text: input.ticketText,
+});
+```
+
+### Retrieve (RAG)
+
+Retrieve relevant documents from the vector store:
+
+```ts
+const docs = await ctx.ai.retrieve({ query: "refund policy for enterprise customers" });
+// docs: Array<{ content: string, source: string, score: number, metadata?: Record<string, unknown> }>
+```
+
+## Output Validation
+
+All AI responses are validated against the prompt's output Zod schema. On failure, the framework retries generation (configurable). If retries are exhausted, a structured error is raised.
+
+## Cost Tracking
+
+Every AI invocation records: model used, input/output token counts, latency, and prompt name. Token counts come directly from provider responses and are always accurate.
+
+**Actual costs** are fetched from provider usage APIs — the framework never guesses or hardcodes pricing. Use `createUsageAPIClient()` to configure OpenAI and Anthropic billing API access:
+
+```ts
+import { createUsageAPIClient, createCostTracker } from "@plumbus/core";
+
+const openaiUsage = createUsageAPIClient({
+  provider: "openai",
+  apiKey: process.env.AI_OPENAI_API_KEY,
+});
+
+const anthropicUsage = createUsageAPIClient({
+  provider: "anthropic",
+  apiKey: process.env.AI_ANTHROPIC_API_KEY,
+});
+
+const costTracker = createCostTracker(budgetConfig, [openaiUsage, anthropicUsage]);
+
+// Fetch actual costs from billing APIs
+const result = await costTracker.syncCosts();
+if (!result.synced) {
+  console.warn("Cost sync failed:", result.error);
+}
+```
+
+If the usage API is not configured or unavailable, `cost` on each record is `null` and dollar-based budget limits cannot be enforced. Token-based budget limits always work.
+
+Budget limits (per-request token limit, daily cost limit, per-tenant daily limit) are enforced via `BudgetConfig`.
+
+## Configuration via Environment Variables
+
+Use `loadConfig()` from `@plumbus/core` in your `config/app.config.ts` — it reads AI provider settings from env vars automatically.
+
+### Single Provider
+
+```bash
+AI_PROVIDER=openai
+AI_API_KEY=sk-...
+AI_BASE_URL=https://custom-endpoint.com/v1   # optional, omit for default
+AI_MODEL=gpt-4o-mini
+```
+
+### Multi-Provider
+
+Set `AI_DEFAULT_PROVIDER` to enable multi-provider mode. Providers are discovered from `AI_{NAME}_API_KEY` patterns:
+
+```bash
+AI_DEFAULT_PROVIDER=openai
+
+AI_OPENAI_API_KEY=sk-...
+AI_OPENAI_BASE_URL=https://custom-openai.com/v1   # optional
+AI_OPENAI_MODEL=gpt-4o-mini
+
+AI_ANTHROPIC_API_KEY=sk-ant-...
+AI_ANTHROPIC_BASE_URL=https://custom-anthropic.com  # optional
+AI_ANTHROPIC_MODEL=claude-sonnet-4-20250514
+```
+
+Each prompt's `model.provider` routes to the named provider; prompts without a provider field use `defaultProvider`.
+
+### Default Model
+
+Set a global fallback model that all prompts use unless overridden:
+
+```bash
+AI_DEFAULT_MODEL=gpt-4o
+```
+
+### Per-Prompt Overrides
+
+Override model, provider, temperature, or maxTokens for any specific prompt via env vars:
+
+```bash
+# Format: PROMPT_{NAME}_{FIELD}
+# Name = prompt name with dots → underscores, UPPERCASED
+# Fields: PROVIDER, MODEL, TEMPERATURE, MAX_TOKENS
+
+# Route "writer.write_chapter" to Anthropic:
+PROMPT_WRITER_WRITE_CHAPTER_PROVIDER=anthropic
+PROMPT_WRITER_WRITE_CHAPTER_MODEL=claude-sonnet-4-20250514
+
+# Use a cheaper model for metadata extraction:
+PROMPT_INTERVIEW_EXTRACT_METADATA_MODEL=gpt-4o-mini
+```
+
+### Model Resolution Chain
+
+When a prompt is invoked, the model is resolved in this order:
+
+1. **Per-prompt env override** (`PROMPT_{NAME}_MODEL`) — highest priority
+2. **Prompt definition** (`model.name` in `definePrompt`) — if set
+3. **Default model** (`AI_DEFAULT_MODEL`) — global fallback
+
+Provider resolution follows the same chain: per-prompt override → prompt definition → `AI_DEFAULT_PROVIDER`.
+
+## Security
+
+- Classified fields in prompt inputs are detected and warn/redact based on entity field classifications
+- Tenant isolation is enforced — prompts cannot access cross-tenant data
+- All AI invocations are recorded in the audit trail

package/instructions/capabilities.md

@@ -0,0 +1,171 @@
+# Capabilities
+
+A capability is a discrete unit of business logic. It is the **only** way business logic executes in Plumbus.
+
+## Defining a Capability
+
+```ts
+import { defineCapability } from "@plumbus/core";
+import { z } from "zod";
+
+export const getUser = defineCapability({
+  name: "getUser",
+  kind: "query",
+  domain: "users",
+  description: "Fetches a user by ID",
+
+  input: z.object({ userId: z.string().uuid() }),
+  output: z.object({ id: z.string(), name: z.string(), email: z.string() }),
+
+  access: { roles: ["admin", "user"], tenantScoped: true },
+
+  effects: {
+    data: ["User"],
+    events: [],
+    external: [],
+    ai: false,
+  },
+
+  audit: { event: "user.fetched", includeInput: ["userId"] },
+
+  explanation: { enabled: true, summary: "Fetches user profile data" },
+
+  handler: async (ctx, input) => {
+    const user = await ctx.data.User.findById(input.userId);
+    if (!user) throw ctx.errors.notFound("User not found");
+    return { id: user.id, name: user.name, email: user.email };
+  },
+});
+```
+
+## Capability Kinds
+
+| Kind | HTTP Method | Behavior |
+|------|------------|----------|
+| `query` | GET | Read-only, idempotent, cacheable |
+| `action` | POST | Write operation, side effects expected |
+| `job` | POST (async) | Long-running, returns job handle immediately |
+| `eventHandler` | Internal only | Triggered by event delivery, not exposed via HTTP |
+
+## Handler Pattern
+
+The handler receives two arguments:
+- `ctx` — the execution context (see `framework.md`)
+- `input` — pre-validated input matching the `input` Zod schema
+
+The handler must return a value matching the `output` Zod schema.
+
+### Using `ctx.data`
+
+```ts
+handler: async (ctx, input) => {
+  // Create
+  const order = await ctx.data.Order.create({ customerId: input.customerId, total: input.total });
+  // Read
+  const customer = await ctx.data.Customer.findById(input.customerId);
+  // Update
+  await ctx.data.Order.update(order.id, { status: "confirmed" });
+  // Query
+  const recent = await ctx.data.Order.findMany({ customerId: input.customerId });
+  return { orderId: order.id };
+}
+```
+
+### Using `ctx.events`
+
+```ts
+handler: async (ctx, input) => {
+  const refund = await ctx.data.Refund.create(input);
+  await ctx.events.emit("refund.requested", { refundId: refund.id, amount: refund.amount });
+  return { refundId: refund.id };
+}
+```
+
+### Using `ctx.ai`
+
+```ts
+handler: async (ctx, input) => {
+  const result = await ctx.ai.generate({ prompt: "summarizeTicket", input: { text: input.ticketText } });
+  return { summary: result.summary };
+}
+```
+
+### Using `ctx.flows`
+
+```ts
+handler: async (ctx, input) => {
+  const execution = await ctx.flows.start("approvalWorkflow", { requestId: input.requestId });
+  return { flowExecutionId: execution.id };
+}
+```
+
+## Effects Declaration
+
+Every capability must declare its side effects in the `effects` field:
+
+- `data` — entity names this capability reads from or writes to
+- `events` — event types this capability may emit
+- `external` — external integrations this capability calls (APIs, services)
+- `flows` — flow names this capability may start (optional)
+- `ai` — whether this capability uses AI operations
+
+Effects are used by governance rules to analyze the system.
+
+## Explanation Tracking
+
+Capabilities that use AI (`effects.ai: true`) should enable explanation tracking:
+
+```ts
+explanation: {
+  enabled: true,    // Enable AI explanation tracking
+  summary: "...",   // Human-readable description of AI usage
+},
+```
+
+The governance rule `ruleAIWithoutExplanation` warns when a capability has `effects.ai: true` but doesn't set `explanation.enabled: true`.
+
+## Error Handling
+
+Use `ctx.errors` to throw structured errors:
+
+```ts
+throw ctx.errors.validation("Email is required");
+throw ctx.errors.notFound("Invoice not found");
+throw ctx.errors.forbidden("Cannot access this resource");
+throw ctx.errors.conflict("Email already exists");
+throw ctx.errors.internal("Payment provider unavailable");
+```
+
+These map to HTTP status codes: 400, 404, 403, 409, 500.
+
+These are the **only** structured error types. If you need a custom error, use `ctx.errors.internal()` with a descriptive message.
+
+## Job Capabilities
+
+Capabilities with `kind: "job"` are for long-running operations. They return immediately with a job handle, and the work executes asynchronously.
+
+```ts
+export const generateReport = defineCapability({
+  name: "generateReport",
+  kind: "job",
+  domain: "reports",
+
+  input: z.object({ reportType: z.string(), dateRange: z.object({ from: z.string(), to: z.string() }) }),
+  output: z.object({ reportId: z.string(), estimatedDuration: z.number() }),
+
+  access: { roles: ["admin", "analyst"], tenantScoped: true },
+  effects: { data: ["Report"], events: ["report.generated"], external: [], ai: true },
+
+  handler: async (ctx, input) => {
+    const report = await ctx.data.Report.create({
+      type: input.reportType,
+      status: "queued",
+      dateFrom: input.dateRange.from,
+      dateTo: input.dateRange.to,
+    });
+    return { reportId: report.id, estimatedDuration: 120 };
+  },
+});
+```
+
+Job capabilities are exposed as `POST` endpoints that return `202 Accepted` with the job output. The framework provides job status tracking and progress monitoring automatically.

package/instructions/cli.md

@@ -0,0 +1,113 @@
+# CLI Reference
+
+The Plumbus CLI scaffolds and manages application primitives. **Always run CLI commands from your project root** (the consumer application directory), not from the framework source.
+
+## Project Setup
+
+```bash
+# Create a new Plumbus project
+plumbus create <project-name> [--auth jwt|auth0|clerk] [--ai openai|anthropic] [--compliance GDPR|HIPAA] [--skip-install] [--git]
+
+# Initialize AI agent wiring (copilot, cursor, or agents-md)
+plumbus init --agent copilot
+
+# Check project health
+plumbus doctor
+```
+
+## Scaffolding Primitives
+
+Use these commands to create new entities, capabilities, events, flows, and prompts. The CLI generates correctly structured files with TODOs for you to fill in.
+
+```bash
+# Create an entity
+plumbus entity new <EntityName>
+# → app/entities/<entity-name>.entity.ts
+
+# Create a capability
+plumbus capability new <CapabilityName>
+# → app/capabilities/default/<capability-name>/capability.ts
+
+# Create an event
+plumbus event new <EventName>
+# → app/events/<event-name>.event.ts
+
+# Create a flow
+plumbus flow new <FlowName>
+# → app/flows/default/<flow-name>/flow.ts
+
+# Create a prompt
+plumbus prompt new <PromptName>
+# → app/prompts/<prompt-name>.prompt.ts
+```
+
+Names are PascalCase on the command line and converted to kebab-case for file paths.
+
+## Code Generation & Verification
+
+```bash
+# Generate client code, routes, and types from your contracts
+plumbus generate
+
+# Run governance checks (advisory signals, not hard blocks)
+plumbus verify
+plumbus verify --json
+```
+
+## Database Management
+
+**All database operations must go through the framework. Never use manual SQL DDL queries.**
+
+### Database Lifecycle
+
+```bash
+# Create the application database from config
+plumbus db create
+plumbus db create --test    # Also create <dbname>_test for testing
+
+# Reset (drop + recreate + apply migrations)
+plumbus db reset
+plumbus db reset --test     # Reset the test database
+```
+
+### Migrations
+
+```bash
+# Generate migration SQL from entity definition diffs (programmatic, no drizzle-kit config needed)
+plumbus migrate generate
+
+# Apply pending migration files to the database
+plumbus migrate apply
+plumbus migrate apply --create-db   # Create DB if it doesn't exist, then apply
+
+# Push schema directly to DB (no migration files — ideal for rapid dev iteration)
+plumbus migrate push
+plumbus migrate push --create-db
+
+# Rollback the last applied migration
+plumbus migrate rollback
+```
+
+All migration commands accept `--json` for machine-readable output.
+
+**Workflow:**
+1. Define entities in `app/entities/` using `defineEntity()`
+2. Run `plumbus migrate generate` to produce SQL migration files in `drizzle/`
+3. Run `plumbus migrate apply` to execute pending migrations
+4. For rapid development, use `plumbus migrate push` to sync schema directly (no migration files)
+
+**Never run `drizzle-kit` manually** — the framework wraps it programmatically.
+
+## Development
+
+```bash
+# Start development server with hot reload
+plumbus dev
+```
+
+## Important Notes
+
+- **Run from project root**: All commands must be executed from the consumer project directory where `package.json` lives.
+- **Scaffolded files have TODOs**: After scaffolding, open the generated file and replace `// TODO` sections with your implementation.
+- **`.plumbus/` is generated**: The `.plumbus/` directory contains auto-generated files. Don't edit them manually — they are regenerated by `plumbus generate`.
+- **Use the framework's `define*()` functions**: Never create primitives by hand. Use the CLI to scaffold, then fill in the contracts using `defineEntity()`, `defineCapability()`, `defineFlow()`, `defineEvent()`, `definePrompt()`.

package/instructions/entities.md

@@ -0,0 +1,94 @@
+# Entities
+
+An entity is a data model definition with field classifications, relations, and retention policies.
+
+## Defining an Entity
+
+```ts
+import { defineEntity, field } from "@plumbus/core";
+
+export const User = defineEntity({
+  name: "User",
+  domain: "identity",
+  tenantScoped: true,
+
+  fields: {
+    id: field.id(),
+    email: field.string({ required: true, unique: true, classification: "personal" }),
+    name: field.string({ required: true }),
+    passwordHash: field.string({ required: true, classification: "highly_sensitive", maskedInLogs: true }),
+    role: field.enum(["admin", "user", "viewer"], { required: true, default: "user" }),
+    organizationId: field.relation({ entity: "Organization", type: "many-to-one" }),
+    lastLoginAt: field.timestamp({ nullable: true }),
+    metadata: field.json({ classification: "internal" }),
+    active: field.boolean({ default: true }),
+  },
+
+  indexes: [["email"], ["organizationId", "active"]],
+  retention: { duration: "365d" },
+});
+```
+
+## Field Types
+
+| Constructor | Stored As | Notes |
+|-------------|-----------|-------|
+| `field.id()` | UUID string | Primary key |
+| `field.string(opts)` | Text | General text |
+| `field.number(opts)` | Numeric | Integer or decimal |
+| `field.boolean(opts)` | Boolean | |
+| `field.timestamp(opts)` | Datetime | ISO timestamps |
+| `field.json(opts)` | JSONB | Arbitrary structured data |
+| `field.enum(values, opts)` | Text | Constrained to provided values |
+| `field.relation(config)` | Foreign key | Links to another entity |
+
+## Field Options
+
+All field types accept these options:
+
+| Option | Type | Default | Purpose |
+|--------|------|---------|---------|
+| `required` | boolean | false | Field must have a value |
+| `default` | any | — | Default value if not provided |
+| `unique` | boolean | false | Unique constraint |
+| `nullable` | boolean | false | Allow null |
+| `classification` | FieldClassification | — | Data sensitivity level |
+| `encrypted` | boolean | false | Encrypt at rest |
+| `maskedInLogs` | boolean | false | Mask in audit/log output |
+
+## Classification Levels
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| `public` | No restrictions | Product name |
+| `internal` | Internal use only | Internal notes |
+| `personal` | Personally identifiable | Email, name |
+| `sensitive` | Requires protection | Phone, address |
+| `highly_sensitive` | Maximum protection | SSN, password hash |
+
+Classifications drive: log masking, audit field tracking, governance warnings, and encryption requirements.
+
+## Relations
+
+```ts
+field.relation({ entity: "Organization", type: "many-to-one" })
+```
+
+Relation types: `one-to-one`, `one-to-many`, `many-to-one`, `many-to-many`.
+
+## Repository (generated)
+
+Each entity gets a typed repository on `ctx.data`:
+
+```ts
+const user = await ctx.data.User.findById("usr_123");
+const users = await ctx.data.User.findMany({ active: true });
+const created = await ctx.data.User.create({ email: "a@b.com", name: "Alice" });
+await ctx.data.User.update("usr_123", { active: false });
+await ctx.data.User.delete("usr_123");
+```
+
+Repositories automatically:
+- Inject `tenantId` from `ctx.auth.tenantId` (if `tenantScoped: true`)
+- Record audit events for mutations
+- Mask sensitive fields in logs

package/instructions/events.md

@@ -0,0 +1,93 @@
+# Events
+
+Events represent domain facts that have occurred. They are emitted by capabilities and consumed by event handlers or flow triggers.
+
+## Defining an Event
+
+```ts
+import { defineEvent } from "@plumbus/core";
+import { z } from "zod";
+
+export const orderPlaced = defineEvent({
+  name: "order.placed",
+  domain: "orders",
+  version: "1.0.0",
+
+  payload: z.object({
+    orderId: z.string(),
+    customerId: z.string(),
+    amount: z.number(),
+    items: z.array(z.object({ productId: z.string(), quantity: z.number() })),
+  }),
+});
+```
+
+## Naming Convention
+
+Use `<domain>.<past-tense-verb>` format: `order.placed`, `refund.requested`, `user.updated`, `invoice.paid`.
+
+## Emission
+
+Events are emitted inside capability handlers via `ctx.events.emit`:
+
+```ts
+handler: async (ctx, input) => {
+  const order = await ctx.data.Order.create(input);
+  await ctx.events.emit("order.placed", {
+    orderId: order.id,
+    customerId: input.customerId,
+    amount: input.total,
+    items: input.items,
+  });
+  return { orderId: order.id };
+}
+```
+
+## Outbox Pattern
+
+Events are **not** dispatched immediately. They are written to an outbox table in the **same database transaction** as the capability's data changes. This guarantees at-least-once delivery with no data/event inconsistency.
+
+A background dispatcher polls the outbox and publishes events to the queue system for delivery.
+
+## Event Envelope
+
+When delivered, each event is wrapped in an envelope:
+
+```ts
+{
+  id: "evt_abc123",           // Unique event ID
+  eventType: "order.placed",  // Event name
+  version: "1.0.0",           // Schema version
+  occurredAt: Date,           // When it happened
+  actor: "usr_456",           // Who caused it
+  tenantId: "tnt_789",        // Tenant scope
+  correlationId: "corr_xyz",  // Request correlation
+  causationId: "evt_prev",    // Causing event (if chained)
+  payload: { ... }            // Typed payload
+}
+```
+
+## Consuming Events
+
+Events are consumed by capabilities with `kind: "eventHandler"`:
+
+```ts
+export const onOrderPlaced = defineCapability({
+  name: "onOrderPlaced",
+  kind: "eventHandler",
+  domain: "fulfillment",
+  // ...
+  handler: async (ctx, event) => {
+    // event is the typed payload
+    await ctx.data.Shipment.create({ orderId: event.orderId });
+  },
+});
+```
+
+## Idempotency
+
+Consumers should be idempotent — processing the same event twice must produce the same result. The framework tracks delivered event+consumer pairs to support this.
+
+## Versioning
+
+Include `version` in event definitions. When schemas evolve, bump the version. Consumers can specify version constraints.