@basaltkit/ai 0.11.0 → 1.0.1

package/dist/index.d.ts

@@ -1,791 +1,35 @@
-import { GeneratedFile } from '@basaltkit/generator';
-import { CommandDefinition } from '@basaltkit/cli';
-
-/**
- * Provider-agnostic AI surface.
- *
- * The agent never talks to a vendor SDK directly — every piece of it depends on
- * this interface. Swapping Anthropic ↔ Ollama ↔ an OpenAI-compatible endpoint is
- * therefore an `AI_PROVIDER` config change, not a code change (spec §17).
- */
-interface AIMessage {
-    role: 'system' | 'user' | 'assistant';
-    content: string;
-}
-interface GenerateOptions {
-    messages: AIMessage[];
-    /** Sampling temperature (0 = deterministic). */
-    temperature?: number;
-    /** Hard cap on output tokens. */
-    maxTokens?: number;
-}
-interface AIProvider {
-    /** Stable id, e.g. `'anthropic'`. */
-    readonly name: string;
-    /** Concrete model id in use, e.g. `'claude-sonnet-5'`. */
-    readonly model: string;
-    /** One-shot completion — returns the assistant's full text. */
-    generate(options: GenerateOptions): Promise<string>;
-    /** Streaming completion — yields chunks as they arrive. */
-    stream(options: GenerateOptions): AsyncIterable<string>;
-}
-/**
- * Minimal fetch surface — the global `fetch` (Node 18+) is assignable, and it's
- * injectable so providers can be unit-tested without a network. Mirrors the shape
- * used by `@basaltkit/search-elasticsearch` to avoid a DOM lib dependency.
- */
-type FetchLike = (url: string, init?: {
-    method?: string;
-    headers?: Record<string, string>;
-    body?: string;
-}) => Promise<{
-    ok: boolean;
-    status: number;
-    text(): Promise<string>;
-}>;
-/**
- * Default `stream()` implementation for providers without real token streaming
- * yet: run the one-shot completion and yield it as a single chunk. Real
- * server-sent-event streaming lands in a later phase; this keeps the
- * {@link AIProvider} contract honest today.
- */
-declare function singleChunkStream(run: () => Promise<string>): AsyncIterable<string>;
-
-interface AnthropicProviderOptions {
-    /** API key → `x-api-key` header. Required. */
-    apiKey: string;
-    /** Model id. Defaults to a current Claude model. */
-    model?: string;
-    /** API base URL. Defaults to the public Anthropic API. */
-    baseUrl?: string;
-    /** Injected fetch. Defaults to the global `fetch`. */
-    fetch?: FetchLike;
-}
-/**
- * Anthropic Messages API provider — REST directly, no SDK (same approach as the
- * Elasticsearch driver). System messages are hoisted into the top-level `system`
- * field, as the API requires.
- */
-declare class AnthropicProvider implements AIProvider {
-    readonly name = "anthropic";
-    readonly model: string;
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    constructor(options: AnthropicProviderOptions);
-    generate(options: GenerateOptions): Promise<string>;
-    stream(options: GenerateOptions): AsyncIterable<string>;
-}
-
-interface OllamaProviderOptions {
-    /** Model id, e.g. `'llama3.1'`. */
-    model?: string;
-    /** Ollama base URL. Defaults to the local daemon. */
-    baseUrl?: string;
-    /** Injected fetch. Defaults to the global `fetch`. */
-    fetch?: FetchLike;
-}
-/**
- * Local Ollama provider (`/api/chat`, `stream: false`). Needs no API key, so it's
- * the zero-cost default for offline development and CI.
- */
-declare class OllamaProvider implements AIProvider {
-    readonly name = "ollama";
-    readonly model: string;
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    constructor(options?: OllamaProviderOptions);
-    generate(options: GenerateOptions): Promise<string>;
-    stream(options: GenerateOptions): AsyncIterable<string>;
-}
-
-/**
- * Minimal Server-Sent-Events support for OpenAI-compatible streaming.
- *
- * Some gateways (e.g. go4ai) return a spurious 500 when they buffer a long
- * non-streaming completion, even though the model generated it (and charged for
- * it). Streaming sidesteps that: the response is delivered in chunks, so there's
- * no large buffered body to choke on.
- */
-interface SseResponse {
-    ok: boolean;
-    status: number;
-    /** Full body — used for the error message on a non-2xx. */
-    text(): Promise<string>;
-    /** Decoded text pieces of the streaming body. */
-    chunks: AsyncIterable<string>;
-}
-type SseFetch = (url: string, init: {
-    method?: string;
-    headers?: Record<string, string>;
-    body?: string;
-}) => Promise<SseResponse>;
-/** Default {@link SseFetch} backed by the global `fetch` + its streaming body. */
-declare const globalSseFetch: SseFetch;
-/**
- * Parse an OpenAI-style SSE stream, yielding each `choices[0].delta.content`
- * piece. Tolerant of keep-alive lines, partial frames and the `[DONE]` sentinel.
- */
-declare function parseSseContent(chunks: AsyncIterable<string>): AsyncIterable<string>;
-
-interface OpenAICompatibleProviderOptions {
-    /** API key → `Authorization: Bearer <key>`. Required. */
-    apiKey: string;
-    /** Model id, e.g. `'gpt-4o-mini'` or `'us.anthropic.claude-sonnet-4-5-20250929-v1:0'`. */
-    model?: string;
-    /**
-     * API base URL up to and including `/v1`. `/chat/completions` is appended.
-     * Defaults to the public OpenAI API; point it at any compatible gateway, e.g.
-     * `https://ai.go4ai.io/v1`.
-     */
-    baseUrl?: string;
-    /**
-     * Stream the completion via SSE (default `true`). Streaming avoids the spurious
-     * 500 some gateways return when buffering a long non-streaming response. Set
-     * `false` for a gateway that doesn't support streaming.
-     */
-    stream?: boolean;
-    /** Injected non-streaming fetch. Defaults to the global `fetch`. */
-    fetch?: FetchLike;
-    /** Injected streaming fetch. Defaults to one built on the global `fetch`. */
-    sseFetch?: SseFetch;
-}
-/**
- * Provider for any OpenAI-compatible Chat Completions endpoint (OpenAI itself,
- * Azure-style gateways, LiteLLM, OpenRouter, go4ai, …). Unlike Anthropic's API,
- * system messages stay inline in the `messages` array.
- *
- * Streams by default — the robust path for large generations behind a gateway.
- */
-declare class OpenAICompatibleProvider implements AIProvider {
-    readonly name = "openai";
-    readonly model: string;
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly streaming;
-    private readonly fetchImpl;
-    private readonly sseFetchImpl;
-    constructor(options: OpenAICompatibleProviderOptions);
-    generate(options: GenerateOptions): Promise<string>;
-    stream(options: GenerateOptions): AsyncIterable<string>;
-    private get endpoint();
-    private headers;
-    private requestBody;
-    private viaStream;
-    private viaJson;
-}
-
-interface RetryOptions {
-    /** Extra attempts after the first (so `2` = up to 3 tries). */
-    retries?: number;
-    /** Base backoff in ms; doubles each attempt. */
-    baseDelayMs?: number;
-}
-/**
- * Fetch with retry on transient 5xx/429 responses and network errors, using
- * exponential backoff. Providers hit remote gateways (go4ai, OpenAI, Anthropic)
- * that occasionally return a spurious 500 — one retry usually clears it.
- *
- * Reads the body only on the terminal attempt, so retried responses are simply
- * discarded.
- */
-declare function fetchWithRetry(fetchImpl: FetchLike, url: string, init: {
-    method?: string;
-    headers?: Record<string, string>;
-    body?: string;
-}, options?: RetryOptions): Promise<{
-    ok: boolean;
-    status: number;
-    body: string;
-}>;
-
-/** Providers wired in 0.1. `openai` covers any OpenAI-compatible gateway; `google` is stubbed. */
-type ProviderName = 'anthropic' | 'ollama' | 'openai' | 'openai-compatible' | 'google';
-/** The subset of environment the provider layer reads. */
-interface ProviderEnv {
-    AI_PROVIDER?: string;
-    AI_MODEL?: string;
-    AI_API_KEY?: string;
-    AI_BASE_URL?: string;
-    /** `'false'` disables SSE streaming for the OpenAI-compatible provider. */
-    AI_STREAM?: string;
-}
-interface CreateProviderOptions {
-    /** Override the injected fetch (tests). */
-    fetch?: FetchLike;
-}
-/** Read the provider-relevant vars off `process.env` into a typed {@link ProviderEnv}. */
-declare function providerEnvFromProcess(): ProviderEnv;
-/**
- * Build an {@link AIProvider} from environment. `AI_PROVIDER` selects the vendor
- * (default `anthropic`); `AI_MODEL`, `AI_API_KEY`, `AI_BASE_URL` tune it.
- *
- * The read-only `ai:analyze` / `ai:doctor` commands never call this — their rules
- * are deterministic and run offline. A provider is only needed for the optional
- * `--explain` narrative and, later, for `ai:plan` / `ai:make`.
- */
-declare function createProvider(env?: ProviderEnv, options?: CreateProviderOptions): AIProvider;
-
-/**
- * Reads project files relative to a root. Injectable so the whole detection layer
- * is unit-testable with an in-memory map (no disk).
- */
-interface ProjectReader {
-    read(relPath: string): string | null;
-    exists(relPath: string): boolean;
-}
-/** Default reader backed by the filesystem. */
-declare function nodeReader(root: string): ProjectReader;
-/** In-memory reader for tests: keys are relative paths. */
-declare function memoryReader(files: Record<string, string>): ProjectReader;
-/** Which capabilities the app actually wires (from its plugin list), not just installs. */
-interface DetectedStack {
-    http: 'fastify' | null;
-    orm: 'prisma' | null;
-    database: 'postgresql' | 'mysql' | 'sqlite' | null;
-    tenancy: boolean;
-    auth: boolean;
-    rbac: boolean;
-    subscriptions: boolean;
-    payments: boolean;
-    storage: boolean;
-    queue: boolean;
-    search: boolean;
-    audit: boolean;
-    events: boolean;
-    scheduler: boolean;
-    logger: boolean;
-    ai: boolean;
-}
-interface PrismaModel {
-    name: string;
-    fields: string[];
-    /** True when the model carries a `tenantId` column (tenant-scoped). */
-    tenantScoped: boolean;
-}
-interface PrismaInfo {
-    provider: DetectedStack['database'];
-    models: PrismaModel[];
-}
-interface AppFileInfo {
-    path: string;
-    /** Plugin factories detected in the `plugins:` array, e.g. `'fastifyPlugin'`. */
-    plugins: string[];
-    /** `fastifyPlugin({ fastify: { logger … } })` present. */
-    fastifyLoggerConfigured: boolean;
-    /** In-memory (non-durable) sources still wired, e.g. `MemoryTenantSource`. */
-    memorySources: string[];
-    /** Every `<name>Plugin(` factory call in the app file (unfiltered by capability). */
-    pluginCalls: string[];
-}
-interface ServerFileInfo {
-    path: string;
-    /** Calls `.$connect()` somewhere in bootstrap (fail-loud DB check). */
-    connectsAtBoot: boolean;
-    /** Calls `.listen(` (actually starts a server). */
-    startsServer: boolean;
-}
-interface EnvFileInfo {
-    path: string;
-    /** Default value baked into `APP_SECRET`, if any. */
-    appSecretDefault: string | null;
-    /** Default value baked into `REDIS_URL`, if any. */
-    redisUrlDefault: string | null;
-}
-interface ProjectContext {
-    root: string;
-    /** All `@basaltkit/*` packages found in package.json deps. */
-    installed: string[];
-    stack: DetectedStack;
-    prisma: PrismaInfo | null;
-    app: AppFileInfo | null;
-    server: ServerFileInfo | null;
-    env: EnvFileInfo | null;
-}
-/** Detect the project's stack and key files. Pure over the injected reader. */
-declare function detectProject(root: string, reader?: ProjectReader): ProjectContext;
-
-type Severity = 'error' | 'warning' | 'info';
-type DiagnosticCategory = 'security' | 'database' | 'observability' | 'tenancy' | 'performance' | 'durability' | 'config';
-interface Diagnostic {
-    /** Stable slug — also the (future) `basalt ai:fix <id>` target. */
-    id: string;
-    title: string;
-    severity: Severity;
-    category: DiagnosticCategory;
-    /** What the project currently does. */
-    detected: string;
-    /** What it should do instead. */
-    recommended: string;
-    /** Why it matters. */
-    reason: string;
-    /** Suggested manual fix (code snippet or command). Auto-fix arrives in a later phase. */
-    fix?: string;
-    /** Related docs path. */
-    docs?: string;
-}
-interface DoctorRule {
-    id: string;
-    category: DiagnosticCategory;
-    /** Returns a diagnostic when the rule fires, else `null`. */
-    check(ctx: ProjectContext): Diagnostic | null;
-}
-declare function defineRule(rule: DoctorRule): DoctorRule;
-
-/**
- * Built-in diagnostic rules. Each is pure over a {@link ProjectContext}, so they
- * run offline with no API key. New rules are added here (or supplied to
- * {@link runDoctor}).
- */
-declare const DEFAULT_RULES: DoctorRule[];
-
-/**
- * Run every rule against the project context and return the diagnostics that
- * fired, most severe first.
- */
-declare function runDoctor(ctx: ProjectContext, rules?: DoctorRule[]): Diagnostic[];
-/** True when any diagnostic is an error — lets CI gate on `ai:doctor`. */
-declare function hasErrors(diagnostics: Diagnostic[]): boolean;
-
-interface AnalysisReport {
-    root: string;
-    /** Human-readable capability lines, e.g. `'Fastify detected'`. */
-    capabilities: string[];
-    installed: string[];
-    database: string | null;
-    models: string[];
-    tenantScopedModels: string[];
-    unscopedModels: string[];
-    /** Diagnostics from the doctor rules, summarised into the report. */
-    diagnostics: Diagnostic[];
-}
-/**
- * Static, offline analysis of a project: what's wired, the data model, and the
- * doctor's findings — the data behind the `ai:analyze` report.
- */
-declare function analyze(ctx: ProjectContext): AnalysisReport;
-
-/** The single output method the CLI needs — matches `CommandIo.log`. */
-interface LineWriter {
-    log(message: string): void;
-}
-/** Render the `ai:analyze` report in the spec's `✓ … detected` style. */
-declare function renderAnalysis(report: AnalysisReport, io: LineWriter): void;
-/** Render the `ai:doctor` diagnostics in the spec's `AI DIAGNOSTICS` style. */
-declare function renderDoctor(diagnostics: Diagnostic[], io: LineWriter): void;
-
-interface FileEdit {
-    /** Path relative to the project root. */
-    path: string;
-    before: string;
-    after: string;
-}
-/** Returns the edits a fix would make, `[]` if there's nothing to change, or `null` if it can't apply. */
-type FixApplier = (read: (rel: string) => string | null, ctx: ProjectContext) => FileEdit[] | null;
-/**
- * Auto-fixers for doctor rules — only the ones with a safe, precise edit. Rules
- * that need a judgement call (tenant scoping, choosing a durable store) have no
- * entry and report "no auto-fix — apply manually".
- */
-declare const FIXES: Record<string, FixApplier>;
-type FixStatus = 'ready' | 'noop' | 'unfixable';
-interface FixOutcome {
-    id: string;
-    status: FixStatus;
-    edits: FileEdit[];
-    message: string;
-}
-/** IDs of rules that have an auto-fixer. */
-declare function fixableIds(): string[];
-/** Compute (but don't write) the edits for a rule's fix. */
-declare function planFix(id: string, ctx: ProjectContext, read: (rel: string) => string | null): FixOutcome;
-/** Write a fix's edits to disk. */
-declare function applyFixEdits(edits: FileEdit[], baseDir: string): Promise<void>;
-/** Render fix outcomes with a line-level diff. */
-declare function renderFixes(outcomes: FixOutcome[], io: LineWriter): void;
-
-type PlanStepKind = 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
-interface PlanField {
-    name: string;
-    type: string;
-    /**
-     * Allowed values — makes this a `z.enum([...])` field (validated on input,
-     * stored as a String column). E.g. a status: `['pago', 'pendente']`.
-     */
-    enum?: string[];
-}
-/** A belongs-to relation: this entity holds a `<name>Id` FK referencing `model`. */
-interface PlanRelation {
-    /** Relation field name on this model, e.g. `paciente`. */
-    name: string;
-    /** Related model, e.g. `Paciente`. */
-    model: string;
-}
-interface PlanEntity {
-    name: string;
-    fields: PlanField[];
-    tenantScoped: boolean;
-    relations?: PlanRelation[];
-}
-interface PlanStep {
-    order: number;
-    title: string;
-    kind: PlanStepKind;
-    detail: string;
-    /** Exact CLI command to run (mainly for `kind: 'generator'`). */
-    command?: string;
-    /** Files the step creates or edits. */
-    files?: string[];
-}
-interface ArchitecturePlan {
-    request: string;
-    summary: string;
-    entities: PlanEntity[];
-    steps: PlanStep[];
-    /** RBAC permissions to register, e.g. `patients.create`. */
-    permissions: string[];
-    /** Audit events to emit, e.g. `patient.created`. */
-    auditEvents: string[];
-    tenantScoped: boolean;
-    warnings: string[];
-}
-
-interface CreatePlanOptions {
-    temperature?: number;
-    maxTokens?: number;
-}
-/**
- * Turn a natural-language request into a grounded {@link ArchitecturePlan}. The
- * project context keeps the plan on-convention and collision-free. Read-only —
- * it produces a plan, it changes nothing.
- */
-declare function createPlan(provider: AIProvider, ctx: ProjectContext, request: string, options?: CreatePlanOptions): Promise<ArchitecturePlan>;
-/** Parse + normalize the model's JSON into a validated plan. Tolerant of fences and missing arrays. */
-declare function parsePlan(raw: string, request: string): ArchitecturePlan;
-
-/**
- * Compact, relevant-only project summary for the planner (spec §18 Context
- * Engineering — never ship the whole project to the model). Surfaces exactly what
- * the Architect needs to ground a plan: enabled capabilities, existing models and
- * the generator's flags.
- */
-declare function buildPlanContext(ctx: ProjectContext): string;
-
-/**
- * The Architect agent's system prompt — Basalt's conventions and official APIs,
- * encoded so the model plans *with* the framework instead of inventing its own
- * architecture (spec §8 Framework Knowledge, §22 "prefer official APIs").
- *
- * This is deliberately prescriptive: the plan must reuse the generator and the
- * platform plugins, never hand-roll parallel abstractions.
- */
-declare const BASALT_KNOWLEDGE = "You are the Architect agent for Basalt \u2014 a batteries-included SaaS framework for Node.js/TypeScript (Fastify + Prisma + Zod). You turn a developer's natural-language request into a precise, convention-following implementation PLAN. You PLAN only; you never write code here.\n\nABSOLUTE RULES \u2014 always use the framework's official APIs and generators, never invent new ones:\n\n1. SCAFFOLDING. Create a resource with the generator, not by hand:\n   `basalt make:resource <Name>` \u2014 generates a full vertical: Zod schema, repository, service, DI plugin, typed routes and a test, all on-convention and auto-wired into src/app.ts.\n   Flags: --prisma (Prisma-backed repository + a schema.prisma model with id/createdAt/updatedAt), --soft-delete (adds deletedAt, a restore() method + route), --no-register (skip wiring), --dir=<path>, --force.\n\n2. PERSISTENCE. Prisma via prismaPlugin. Models live in schema.prisma. After editing the schema, run `basalt prisma:sync` to generate the client + migration. Use --prisma so the generator emits the model for you.\n\n3. MULTI-TENANCY. When tenancy is enabled, every tenant-owned model MUST carry a `tenantId` column, and the tenancy layer scopes queries by the current tenant. NEVER plan a query that ignores tenant isolation. Platform-global tables (users, tenants, plans) are the only exceptions.\n\n4. RBAC / PERMISSIONS. For each resource, register `<resource>.view`, `<resource>.create`, `<resource>.update`, `<resource>.delete` and guard the matching routes with the permission check. Use the resource name in plural, lowercase (e.g. `patients.create`).\n\n5. AUDIT. Emit an audit event for each state change: `<resource>.created`, `<resource>.updated`, `<resource>.deleted` (singular resource).\n\n6. VALIDATION + DOCS. Every route carries a Zod schema; OpenAPI is generated from it automatically \u2014 no separate doc wiring.\n\n7. TESTS. Every resource ships a test (the generator creates one; extend it for domain rules).\n\nGROUNDING: Reuse what already exists in the project. Avoid name collisions with existing models. Only add what is missing. Prefer editing the schema + running the generator over hand-writing files.\n\nOUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching exactly:\n{\n  \"summary\": string,                     // 1-2 sentences on the approach\n  \"entities\": [                          // domain entities to create\n    { \"name\": string, \"fields\": [{ \"name\": string, \"type\": string, \"enum\"?: string[] }], \"tenantScoped\": boolean,\n      \"relations\": [{ \"name\": string, \"model\": string }] }   // belongs-to: this model gets a <name>Id FK \u2192 <model>\n  ],\n  \"steps\": [                             // ordered implementation steps\n    { \"order\": number, \"title\": string, \"kind\": \"generator\"|\"schema\"|\"migration\"|\"service\"|\"routes\"|\"permissions\"|\"audit\"|\"test\"|\"docs\"|\"other\", \"detail\": string, \"command\": string, \"files\": string[] }\n  ],\n  \"permissions\": string[],               // e.g. [\"patients.view\",\"patients.create\",...]\n  \"auditEvents\": string[],               // e.g. [\"patient.created\",...]\n  \"tenantScoped\": boolean,               // does this feature involve tenant-owned data\n  \"warnings\": string[]                   // risks, decisions to confirm, missing info\n}\nFor generator steps, put the exact command in \"command\" (e.g. \"basalt make:resource Patient --prisma --soft-delete\"). Omit \"command\"/\"files\" when not applicable.\n\nENUMS: a field with a fixed set of values (a status/state) MUST set \"enum\" to those values \u2014 e.g. \"estado (pago/pendente)\" \u2192 { \"name\": \"estado\", \"type\": \"String\", \"enum\": [\"pago\", \"pendente\"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().\n\nRELATIONS: express a belongs-to as an entry in \"relations\" (e.g. an Appointment belongs to a Patient \u2192 { \"name\": \"patient\", \"model\": \"Patient\" }). Do NOT also add the \"<name>Id\" field to \"fields\" \u2014 the FK column, the @relation and the inverse field are generated. Prefer generating both sides of a relation in the same plan.";
-
-/** Render an {@link ArchitecturePlan} in the spec's `ARCHITECTURE PLAN` style. */
-declare function renderPlan(plan: ArchitecturePlan, io: LineWriter): void;
-
-interface MakeOptions {
-    /** Skip writing to disk — return what would be generated. */
-    dryRun?: boolean;
-    /** Overwrite existing files instead of refusing. */
-    force?: boolean;
-    /** Project root. Defaults to process.cwd(). */
-    baseDir?: string;
-    /** Force a Prisma-backed resource (default: inferred from the stack). */
-    prisma?: boolean;
-    /** Force soft-delete (default: from the plan's generator command). */
-    softDelete?: boolean;
-    /** Path to the Prisma schema to merge models into. Default `prisma/schema.prisma`. */
-    schemaPath?: string;
-    /** After merging models, run `prisma db push` (creates tables + regenerates the client). */
-    migrate?: boolean;
-}
-/** How the generated models were merged into prisma/schema.prisma. */
-interface SchemaMerge {
-    path: string;
-    /** The schema file was found on disk. */
-    found: boolean;
-    /** Models appended. */
-    merged: string[];
-    /** Models already present (left as is). */
-    skipped: string[];
-    /** The schema file was written (false on dry-run). */
-    written: boolean;
-}
-/** Result of an opt-in `prisma db push`. */
-interface Migration {
-    ok: boolean;
-    /** Tail of the command output. */
-    output: string;
-}
-interface ResourceBuild {
-    name: string;
-    prisma: boolean;
-    softDelete: boolean;
-    /** Generated (and domain-augmented) files. */
-    files: GeneratedFile[];
-    /** Domain fields were injected into schema/model. */
-    augmented: boolean;
-    /** Permission `meta.can` guards were injected into the routes. */
-    guarded: boolean;
-    /** Audit recording was injected into the service + plugin. */
-    audited: boolean;
-    /** Files actually written (empty on dry-run or on clash). */
-    written: string[];
-    /** Wired into src/app.ts. */
-    registered: boolean;
-    /** Why a step didn't complete (e.g. a file clash). */
-    note?: string;
-}
-type ReviewStatus = 'pass' | 'warn' | 'fail';
-interface ReviewItem {
-    label: string;
-    status: ReviewStatus;
-    detail: string;
-}
-interface ReviewResult {
-    items: ReviewItem[];
-    /** True when no item failed. */
-    ok: boolean;
-}
-interface MakeResult {
-    request: string;
-    dryRun: boolean;
-    resources: ResourceBuild[];
-    /** How models were merged into the Prisma schema (undefined when no Prisma resource). */
-    schema?: SchemaMerge;
-    /** Result of `--migrate` (undefined when not requested). */
-    migration?: Migration;
-    /** Manual follow-ups the scaffold can't do yet. */
-    followUps: string[];
-    review: ReviewResult;
-}
-
-/**
- * Execute an {@link ArchitecturePlan}: scaffold each entity via the official
- * generator, inject the plan's domain fields, write + auto-wire, then run a
- * deterministic review gate. Read-only when `dryRun` is set.
- *
- * Hybrid by design (the locked decision): the generator produces the
- * on-convention vertical; we only augment it with fields the plan already
- * decided. No destructive operations — never overwrites without `force`, never
- * touches the database, never deletes.
- */
-declare function runMake(ctx: ProjectContext, plan: ArchitecturePlan, options?: MakeOptions): Promise<MakeResult>;
-
-/** Render a {@link MakeResult} — what was generated, the review gate and follow-ups. */
-declare function renderMakeResult(result: MakeResult, io: LineWriter): void;
-
-interface VerifyResult {
-    ok: boolean;
-    /** Command that was run, e.g. `pnpm typecheck`. */
-    command: string;
-    /** Combined stdout/stderr tail on failure. */
-    output: string;
-}
-/**
- * Run the project's typecheck as a review gate (spec §12/§20). Best-effort: if
- * the command is missing or errors, it reports failure rather than throwing.
- */
-declare function verifyProject(baseDir: string, command?: string, args?: string[]): Promise<VerifyResult>;
-
-type CanonicalType = 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Json';
-/** Map a loose plan type (`'string'`, `'DateTime'`, `'number'`…) to a canonical type. */
-declare function canonicalType(raw: string): CanonicalType;
-/** Prisma column type — identical to the canonical name. */
-declare function prismaType(t: CanonicalType): string;
-/**
- * Zod validator for a field. On input (`create`) a `DateTime` coerces from a
- * date/ISO string to a `Date` (so Prisma accepts it — a bare `z.string()` lets a
- * non-ISO value like `"1990-05-01"` through to Prisma and 500). On output it's an
- * ISO string, matching the mapper.
- */
-declare function zodValidator(t: CanonicalType, create: boolean): string;
-/** Zod validator for a field, honoring an enum (`z.enum([...])`) over its base type. */
-declare function zodForField(field: PlanField, create: boolean): string;
-/** The entity's own fields, minus reserved/base columns and duplicates. */
-declare function domainFields(fields: PlanField[]): PlanField[];
-/**
- * Inject domain fields (and `tenantId` + `@@index` when tenant-scoped) into a
- * generated Prisma model snippet, right after its `name` column. Returns
- * `injected: false` if the expected anchor isn't found — the scaffold still lands
- * unchanged and the caller reports it.
- */
-declare function injectPrismaFields(content: string, fields: PlanField[], tenantScoped: boolean, removeName?: boolean): {
-    content: string;
-    injected: boolean;
-};
-/**
- * Inject domain fields into a generated Zod schema file — into both the entity
- * schema (`<Name>Schema`) and the create schema (`Create<Name>Schema`).
- */
-declare function injectZodFields(content: string, fields: PlanField[], removeName?: boolean): {
-    content: string;
-    injected: boolean;
-};
-
-interface RepositoryOptions {
-    softDelete: boolean;
-    /** Scope every query by tenantId from context (portable — no global extension needed). */
-    tenantScoped: boolean;
-    /** Keep the generator's base `name` column. */
-    keepName: boolean;
-}
-/**
- * Render a complete Prisma repository for a resource — replacing the generator's,
- * which (a) only maps id/name/timestamps (dropping domain fields) and (b) relies
- * on the global tenancy extension to stamp tenantId. This one maps every domain
- * field and, when tenant-scoped, scopes tenantId explicitly from the request
- * context, so it works even on a raw client shared with non-tenant models.
- */
-declare function renderPrismaRepository(name: string, fields: PlanField[], options: RepositoryOptions): string;
-
-/**
- * The RBAC permissions for a resource — the exact `<plural>.<action>` strings its
- * route guards check on (F5 derives guards from the entity name, so declaring
- * them here keeps a single source of truth that can't drift from the guards).
- */
-declare function permissionList(name: string): string[];
-/**
- * Generate `<kebab>.permissions.ts`: the permission constants plus a
- * `grant<Name>Permissions(store, role)` helper — so registering RBAC for the
- * resource is one call in the app's seed/setup, closing the loop F4 opened
- * (guards without a way to grant them).
- */
-declare function renderPermissionsFile(name: string): string;
-
-/**
- * OpenAPI enrichment (spec §14): add a `summary` and `tags` to each generated
- * route's `meta`, merging into an existing `meta` (e.g. the `can` guard) or
- * creating one. `@basaltkit/http` renders these into the OpenAPI document.
- */
-declare function injectOpenApiMeta(content: string, entityName: string): {
-    content: string;
-    injected: boolean;
-};
-
-/**
- * Real Prisma relations (Fase 6). A belongs-to relation on an entity generates:
- * a `<name>Id` FK column, a `<name> <Model> @relation(...)` field, and — on the
- * related model — an inverse `<plural> <This>[]` field. Both sides are required
- * for Prisma to validate, so a relation to a model outside the plan is surfaced
- * as a follow-up (the user adds the inverse field to their existing model).
- */
-/** FK column name for a relation, e.g. `paciente` → `pacienteId`. */
-declare function foreignKey(relation: PlanRelation): string;
-/** Synthetic FK fields (String) for an entity's relations — feed the Zod schema, mapper and columns. */
-declare function relationForeignKeys(entity: PlanEntity): PlanField[];
-/** Prisma relation field lines for the entity's belongs-to relations. */
-declare function relationFieldLines(entity: PlanEntity): string[];
-/** Inverse `hasMany` lines to add to `modelName`, from every other entity that belongs to it. */
-declare function inverseRelationLines(modelName: string, allEntities: PlanEntity[]): string[];
-/** Insert relation + inverse lines into a generated Prisma model, before its closing brace. */
-declare function injectPrismaRelations(content: string, relationLines: string[], inverseLines: string[]): {
-    content: string;
-    injected: boolean;
-};
-/** Relation targets that aren't generated in this plan (need a manual inverse field). */
-declare function externalRelationTargets(entities: PlanEntity[]): string[];
-
-/**
- * Inject `meta: { can: '<prefix>.<action>' }` into every generated route, so the
- * permissions guard enforces it. `prefix` is the resource's permission namespace
- * (e.g. `patients`) — derived per entity by the caller, so each entity in a
- * multi-entity plan gets its own correct permission, not a shared one.
- */
-declare function injectPermissionGuards(content: string, prefix: string): {
-    content: string;
-    injected: boolean;
-};
-/**
- * Inject audit recording into the generated service: the constructor receives an
- * `Audit`, and create/update/remove record their event after the repository call.
- */
-declare function injectAuditService(content: string, resourceName: string, events: string[]): {
-    content: string;
-    injected: boolean;
-};
-/** Inject the `AUDIT` dependency into the generated plugin's service construction. */
-declare function injectAuditPlugin(content: string, resourceName: string): {
-    content: string;
-    injected: boolean;
-};
-
-interface ModelBlock {
-    name: string;
-    block: string;
-}
-/** Extract the `model <Name> { … }` block from a generated `.prisma` snippet. */
-declare function extractModelBlock(snippet: string): ModelBlock | null;
-interface MergeOutcome {
-    content: string;
-    merged: string[];
-    skipped: string[];
-}
-/** Append model blocks to a schema, skipping any model already declared (idempotent). */
-declare function mergeModelsIntoSchema(schema: string, blocks: ModelBlock[]): MergeOutcome;
-interface PrismaPushResult {
-    ok: boolean;
-    /** Tail of stdout/stderr. */
-    output: string;
-}
-/** Run `npx prisma db push` — creates the table(s) and regenerates the client. Best-effort. */
-declare function runPrismaPush(baseDir: string): Promise<PrismaPushResult>;
-
-interface ReviewIssue {
-    /** e.g. `tenancy`, `security`, `rbac`, `validation`, `tests`, `fit`. */
-    dimension: string;
-    severity: 'error' | 'warning';
-    message: string;
-}
-interface AgentReview {
-    /** Derived: true only when no issue is error-severity. */
-    approved: boolean;
-    summary: string;
-    issues: ReviewIssue[];
-}
-
-interface ReviewOptions {
-    temperature?: number;
-    maxTokens?: number;
-}
-/**
- * Compact, relevant-only context for the Review agent: the request, the plan, the
- * deterministic review, and the generated code that carries behaviour.
- */
-declare function buildReviewContext(plan: ArchitecturePlan, result: MakeResult): string;
-/** Ask the Review agent to critique the generated code. Read-only — it judges, it doesn't edit. */
-declare function reviewImplementation(provider: AIProvider, plan: ArchitecturePlan, result: MakeResult, options?: ReviewOptions): Promise<AgentReview>;
-/** Parse the verdict. `approved` is derived from the issues, not trusted from the model. */
-declare function parseReview(raw: string): AgentReview;
-
-/**
- * The Review agent's rubric (spec §20). It reviews the *generated code* against
- * Basalt's conventions and the original request, and returns issues by dimension.
- * It does not rewrite code — it judges it.
- */
-declare const REVIEW_KNOWLEDGE = "You are the Review agent for Basalt, a SaaS framework (Fastify + Prisma + Zod). Given a feature request, its plan, the deterministic review results and the generated code, decide whether the implementation is correct and on-convention. You do NOT rewrite code \u2014 you review it, precisely.\n\nSCOPE: `ai:make` generates a BACKEND resource vertical only \u2014 Prisma model, Zod schema, typed routes, service, repository, permissions and a test. It does NOT generate web/UI, React, frontend pages, background jobs, emails or infrastructure; other tools do. Review ONLY the backend vertical, on its own terms. If the request also asks for something outside this scope (a web page, a component, a job\u2026), mention it as a \"warning\" at most \u2014 NEVER an \"error\" \u2014 since `ai:make` is not the tool that produces it.\n\nCheck these dimensions and only raise an issue you can point to in the code:\n\n- tenancy: a tenant-scoped model MUST carry a tenantId column, and every query in its repository MUST be scoped by tenantId (create stamps it; list/find/update/delete filter by it). Raise an ERROR if a tenant-scoped resource can leak or write across tenants.\n- security: no hardcoded secrets; request bodies validated by Zod; no obvious injection.\n- rbac: routes carry `meta: { can: '<resource>.<action>' }` guards, and the permissions are declared. ERROR if a mutating route is unguarded when RBAC is enabled.\n- validation: every route has a Zod schema; the repository maps Prisma rows to the API type (no Date leaking as a Date, no raw row returned).\n- audit: state changes record audit events when audit is enabled (warning if not).\n- tests: a test file exists.\n- fit: the generated backend matches the request's DATA MODEL \u2014 the right entities, fields, relations and tenancy. Do NOT raise an \"error\" for artifacts outside the backend vertical (web UI, frontend, jobs); those are out of scope.\n\nReturn ONLY a single JSON object (no prose, no markdown fences):\n{\n  \"summary\": string,                       // one or two sentences\n  \"issues\": [ { \"dimension\": string, \"severity\": \"error\" | \"warning\", \"message\": string } ]\n}\nRaise \"error\" only for a real, blocking convention violation you can cite; use \"warning\" for improvements. An empty issues array means the implementation is approved.";
-
-/** Render the Review agent's verdict in the spec's `Implementation rejected` style. */
-declare function renderAgentReview(review: AgentReview, io: LineWriter): void;
-
-interface AiCommandsOptions {
-    /** Project root to analyze. Defaults to the current working directory. */
-    cwd?: string;
-}
-/**
- * CLI commands for the AI-native DX (foundation phase):
- *
- * - `basalt ai`          — overview: detected stack + what the agent can do
- * - `basalt ai:analyze`  — static analysis report (read-only, offline)
- * - `basalt ai:doctor`   — diagnostics with fixes (read-only, offline; exits 1 on errors)
- * - `basalt ai:fix`      — apply a doctor fix, or all auto-fixable ones (offline; --dry-run/--yes)
- * - `basalt ai:plan`     — natural language → architecture plan (read-only; needs a provider)
- * - `basalt ai:make`     — plan then implement: scaffold + domain fields, review gate (writes; needs a provider)
- *
- * Wire them in like the generator commands:
- * `commandsPlugin([...generatorCommands(), ...aiCommands()])`.
- */
-declare function aiCommands(options?: AiCommandsOptions): CommandDefinition[];
-
-export { type AIMessage, type AIProvider, type AgentReview, type AiCommandsOptions, type AnalysisReport, AnthropicProvider, type AnthropicProviderOptions, type AppFileInfo, type ArchitecturePlan, BASALT_KNOWLEDGE, type CanonicalType, type CreatePlanOptions, type CreateProviderOptions, DEFAULT_RULES, type DetectedStack, type Diagnostic, type DiagnosticCategory, type DoctorRule, type EnvFileInfo, FIXES, type FetchLike, type FileEdit, type FixApplier, type FixOutcome, type FixStatus, type GenerateOptions, type LineWriter, type MakeOptions, type MakeResult, type Migration, type ModelBlock, OllamaProvider, type OllamaProviderOptions, OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, type PlanEntity, type PlanField, type PlanRelation, type PlanStep, type PlanStepKind, type PrismaInfo, type PrismaModel, type ProjectContext, type ProjectReader, type ProviderEnv, type ProviderName, REVIEW_KNOWLEDGE, type RepositoryOptions, type ResourceBuild, type RetryOptions, type ReviewIssue, type ReviewItem, type ReviewOptions, type ReviewResult, type ReviewStatus, type SchemaMerge, type ServerFileInfo, type Severity, type SseFetch, type SseResponse, type VerifyResult, aiCommands, analyze, applyFixEdits, buildPlanContext, buildReviewContext, canonicalType, createPlan, createProvider, defineRule, detectProject, domainFields, externalRelationTargets, extractModelBlock, fetchWithRetry, fixableIds, foreignKey, globalSseFetch, hasErrors, injectAuditPlugin, injectAuditService, injectOpenApiMeta, injectPermissionGuards, injectPrismaFields, injectPrismaRelations, injectZodFields, inverseRelationLines, memoryReader, mergeModelsIntoSchema, nodeReader, parsePlan, parseReview, parseSseContent, permissionList, planFix, prismaType, providerEnvFromProcess, relationFieldLines, relationForeignKeys, renderAgentReview, renderAnalysis, renderDoctor, renderFixes, renderMakeResult, renderPermissionsFile, renderPlan, renderPrismaRepository, reviewImplementation, runDoctor, runMake, runPrismaPush, singleChunkStream, verifyProject, zodForField, zodValidator };
+export { singleChunkStream, type AIMessage, type AIProvider, type FetchLike, type GenerateOptions, } from './provider/types.js';
+export { AnthropicProvider, type AnthropicProviderOptions } from './provider/anthropic.js';
+export { OllamaProvider, type OllamaProviderOptions } from './provider/ollama.js';
+export { OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, } from './provider/openai.js';
+export { fetchWithRetry, type RetryOptions } from './provider/http.js';
+export { globalSseFetch, parseSseContent, type SseFetch, type SseResponse } from './provider/sse.js';
+export { createProvider, providerEnvFromProcess, type CreateProviderOptions, type ProviderEnv, type ProviderName, } from './provider/factory.js';
+export { detectProject, nodeReader, memoryReader, type AppFileInfo, type DetectedStack, type EnvFileInfo, type PrismaInfo, type PrismaModel, type ProjectContext, type ProjectReader, type ServerFileInfo, } from './context/project.js';
+export { defineRule, type Diagnostic, type DiagnosticCategory, type DoctorRule, type Severity, } from './doctor/types.js';
+export { DEFAULT_RULES } from './doctor/rules.js';
+export { hasErrors, runDoctor } from './doctor/run.js';
+export { applyFixEdits, fixableIds, planFix, renderFixes, FIXES, type FileEdit, type FixApplier, type FixOutcome, type FixStatus, } from './doctor/fixes.js';
+export { analyze, type AnalysisReport } from './analyze/run.js';
+export { createPlan, parsePlan, type CreatePlanOptions } from './plan/plan.js';
+export { buildPlanContext } from './plan/context.js';
+export { BASALT_KNOWLEDGE } from './plan/knowledge.js';
+export { renderPlan } from './plan/render.js';
+export type { ArchitecturePlan, PlanEntity, PlanField, PlanRelation, PlanStep, PlanStepKind, } from './plan/types.js';
+export { runMake } from './make/make.js';
+export { renderMakeResult } from './make/render.js';
+export { verifyProject, type VerifyResult } from './make/verify.js';
+export { canonicalType, domainFields, injectPrismaFields, injectZodFields, prismaType, zodForField, zodValidator, type CanonicalType, } from './make/fields.js';
+export { renderPrismaRepository, type RepositoryOptions } from './make/repository.js';
+export { permissionList, renderPermissionsFile } from './make/permissions.js';
+export { injectOpenApiMeta } from './make/openapi.js';
+export { externalRelationTargets, foreignKey, injectPrismaRelations, inverseRelationLines, relationFieldLines, relationForeignKeys, } from './make/relations.js';
+export { injectAuditPlugin, injectAuditService, injectPermissionGuards } from './make/wire.js';
+export { extractModelBlock, mergeModelsIntoSchema, runPrismaPush, type ModelBlock, } from './make/schema.js';
+export type { MakeOptions, MakeResult, Migration, ResourceBuild, ReviewItem, ReviewResult, ReviewStatus, SchemaMerge, } from './make/types.js';
+export { buildReviewContext, parseReview, reviewImplementation, type ReviewOptions } from './review/review.js';
+export { REVIEW_KNOWLEDGE } from './review/knowledge.js';
+export { renderAgentReview } from './review/render.js';
+export type { AgentReview, ReviewIssue } from './review/types.js';
+export { renderAnalysis, renderDoctor, type LineWriter } from './render.js';
+export { aiCommands, type AiCommandsOptions } from './commands.js';