@basaltkit/ai 0.11.0 → 1.0.1

package/dist/doctor/fixes.d.ts

@@ -0,0 +1,31 @@
+import type { ProjectContext } from '../context/project.js';
+import type { LineWriter } from '../render.js';
+export 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. */
+export 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".
+ */
+export declare const FIXES: Record<string, FixApplier>;
+export type FixStatus = 'ready' | 'noop' | 'unfixable';
+export interface FixOutcome {
+    id: string;
+    status: FixStatus;
+    edits: FileEdit[];
+    message: string;
+}
+/** IDs of rules that have an auto-fixer. */
+export declare function fixableIds(): string[];
+/** Compute (but don't write) the edits for a rule's fix. */
+export declare function planFix(id: string, ctx: ProjectContext, read: (rel: string) => string | null): FixOutcome;
+/** Write a fix's edits to disk. */
+export declare function applyFixEdits(edits: FileEdit[], baseDir: string): Promise<void>;
+/** Render fix outcomes with a line-level diff. */
+export declare function renderFixes(outcomes: FixOutcome[], io: LineWriter): void;

package/dist/doctor/fixes.js

@@ -0,0 +1,82 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * 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".
+ */
+export const FIXES = {
+    'fastify-logger-off': (read, ctx) => {
+        if (!ctx.app)
+            return null;
+        const content = read(ctx.app.path);
+        if (content === null)
+            return null;
+        if (/fastify\s*:\s*\{[^}]*\blogger\b/.test(content))
+            return []; // already configured
+        const after = content.replace(/fastifyPlugin\(\s*\{/, (m) => `${m} fastify: { logger: process.env.NODE_ENV !== 'production' },`);
+        return after === content ? [] : [{ path: ctx.app.path, before: content, after }];
+    },
+    'insecure-app-secret': (read, ctx) => {
+        if (!ctx.env)
+            return null;
+        const value = ctx.env.appSecretDefault;
+        if (!value || !/change|me|example|secret|placeholder|xxx/i.test(value))
+            return [];
+        const content = read(ctx.env.path);
+        if (content === null)
+            return null;
+        const after = content.replace(/^(\s*)APP_SECRET:\s*z\.string\(\)[^\n]*$/m, '$1APP_SECRET: z.string().min(32),');
+        return after === content ? [] : [{ path: ctx.env.path, before: content, after }];
+    },
+};
+/** IDs of rules that have an auto-fixer. */
+export function fixableIds() {
+    return Object.keys(FIXES);
+}
+/** Compute (but don't write) the edits for a rule's fix. */
+export function planFix(id, ctx, read) {
+    const applier = FIXES[id];
+    if (!applier) {
+        return { id, status: 'unfixable', edits: [], message: 'no auto-fix — apply manually (see `basalt ai:doctor`)' };
+    }
+    const edits = applier(read, ctx);
+    if (edits === null)
+        return { id, status: 'unfixable', edits: [], message: 'target file not found' };
+    const changed = edits.filter((e) => e.before !== e.after);
+    if (changed.length === 0)
+        return { id, status: 'noop', edits: [], message: 'nothing to change (already fixed?)' };
+    return { id, status: 'ready', edits: changed, message: `edits ${changed.map((e) => e.path).join(', ')}` };
+}
+/** Write a fix's edits to disk. */
+export async function applyFixEdits(edits, baseDir) {
+    for (const edit of edits)
+        await writeFile(join(baseDir, edit.path), edit.after);
+}
+/** Render fix outcomes with a line-level diff. */
+export function renderFixes(outcomes, io) {
+    const mark = { ready: '✓', noop: '•', unfixable: '⚠' };
+    for (const outcome of outcomes) {
+        io.log(`${mark[outcome.status]} ${outcome.id} — ${outcome.message}`);
+        for (const edit of outcome.edits) {
+            io.log(`  ${edit.path}:`);
+            for (const [removed, added] of lineDiff(edit.before, edit.after)) {
+                if (removed !== undefined)
+                    io.log(`    - ${removed.trim()}`);
+                if (added !== undefined)
+                    io.log(`    + ${added.trim()}`);
+            }
+        }
+    }
+}
+/** Positional line diff — the auto-fixes edit lines in place, keeping the line count. */
+function lineDiff(before, after) {
+    const b = before.split('\n');
+    const a = after.split('\n');
+    const out = [];
+    for (let i = 0; i < Math.max(b.length, a.length); i++) {
+        if (b[i] !== a[i])
+            out.push([b[i], a[i]]);
+    }
+    return out;
+}

package/dist/doctor/rules.d.ts

@@ -0,0 +1,7 @@
+import { type DoctorRule } from './types.js';
+/**
+ * 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}).
+ */
+export declare const DEFAULT_RULES: DoctorRule[];

package/dist/doctor/rules.js

@@ -0,0 +1,230 @@
+import { defineRule } from './types.js';
+/**
+ * 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}).
+ */
+export const DEFAULT_RULES = [
+    // ── observability ─────────────────────────────────────────────────────────
+    defineRule({
+        id: 'prisma-lazy-boot',
+        category: 'observability',
+        check(ctx) {
+            if (!ctx.stack.orm || !ctx.server)
+                return null;
+            if (ctx.server.connectsAtBoot)
+                return null;
+            return {
+                id: 'prisma-lazy-boot',
+                title: 'Database connection is not validated at boot',
+                severity: 'warning',
+                category: 'observability',
+                detected: `${ctx.server.path} never calls prisma.$connect() before listen()`,
+                recommended: "await the Prisma client's $connect() right after boot()",
+                reason: 'Prisma connects lazily on the first query, so an unreachable database ' +
+                    '(wrong host/port/credentials) does NOT crash at startup — it fails ' +
+                    'silently on the first request instead.',
+                fix: [
+                    'const app = await buildApp({ /* … */ }).boot()',
+                    "await app.container.get(PRISMA).$connect()  // fail loudly if the DB is unreachable",
+                ].join('\n'),
+                docs: '/guide/observability',
+            };
+        },
+    }),
+    defineRule({
+        id: 'fastify-logger-off',
+        category: 'observability',
+        check(ctx) {
+            if (ctx.stack.http !== 'fastify' || !ctx.app)
+                return null;
+            if (ctx.app.fastifyLoggerConfigured)
+                return null;
+            return {
+                id: 'fastify-logger-off',
+                title: "Fastify's request logger is disabled",
+                severity: 'warning',
+                category: 'observability',
+                detected: `fastifyPlugin in ${ctx.app.path} has no fastify.logger option`,
+                recommended: "enable Fastify's logger (at least in development)",
+                reason: "Unhandled request errors are logged via request.log.error, but Fastify's " +
+                    'built-in logger defaults to OFF — so 500s are returned to the client while ' +
+                    'the terminal stays silent.',
+                fix: "fastifyPlugin({ routes: [...], fastify: { logger: env.NODE_ENV === 'development' } })",
+                docs: '/guide/observability',
+            };
+        },
+    }),
+    // ── security ──────────────────────────────────────────────────────────────
+    defineRule({
+        id: 'insecure-app-secret',
+        category: 'security',
+        check(ctx) {
+            const value = ctx.env?.appSecretDefault;
+            if (!value)
+                return null;
+            if (!/change|me|example|secret|placeholder|xxx/i.test(value))
+                return null;
+            return {
+                id: 'insecure-app-secret',
+                title: 'APP_SECRET has an insecure default',
+                severity: 'error',
+                category: 'security',
+                detected: `${ctx.env?.path} defaults APP_SECRET to "${value}"`,
+                recommended: 'require APP_SECRET from the environment with no fallback in production',
+                reason: 'A committed default secret lets anyone forge sessions/JWTs if it ever ' +
+                    'reaches a deployed environment. Secrets must come from the environment.',
+                fix: "APP_SECRET: z.string().min(32)  // no .default() — fail fast if unset",
+                docs: '/guide/security',
+            };
+        },
+    }),
+    defineRule({
+        id: 'missing-security-plugin',
+        category: 'security',
+        check(ctx) {
+            if (!ctx.app)
+                return null;
+            if (ctx.app.pluginCalls.includes('securityPlugin'))
+                return null;
+            return {
+                id: 'missing-security-plugin',
+                title: 'No securityPlugin — responses ship without secure headers',
+                severity: 'warning',
+                category: 'security',
+                detected: `${ctx.app.path} registers no securityPlugin()`,
+                recommended: 'add securityPlugin() so secure response headers are set, and enable rate limiting + a CORS allow-list for production',
+                reason: 'Without it the API returns no security headers (HSTS, X-Frame-Options, ' +
+                    'nosniff, …) and applies no rate limiting — a fresh deploy is unprotected ' +
+                    'at the edge. The security primitives exist but are off until wired.',
+                fix: 'securityPlugin({ /* headers on by default */ rateLimit: { limit: 120, windowMs: 60_000 } })',
+                docs: '/guide/security',
+            };
+        },
+    }),
+    // ── tenancy ───────────────────────────────────────────────────────────────
+    defineRule({
+        id: 'missing-tenant-membership',
+        category: 'tenancy',
+        check(ctx) {
+            if (!ctx.app || !ctx.stack.tenancy || !ctx.stack.auth)
+                return null;
+            const teamsAvailable = ctx.app.pluginCalls.includes('teamsPlugin') || ctx.installed.includes('@basaltkit/teams');
+            if (!teamsAvailable)
+                return null;
+            if (ctx.app.pluginCalls.includes('tenantMembershipPlugin'))
+                return null;
+            return {
+                id: 'missing-tenant-membership',
+                title: 'Tenant is resolved from the request but membership is never enforced',
+                severity: 'error',
+                category: 'tenancy',
+                detected: `${ctx.app.path} wires tenancy + auth (+ teams) but no tenantMembershipPlugin`,
+                recommended: 'register tenantMembershipPlugin() so every authenticated, tenant-scoped request verifies the user belongs to the resolved tenant',
+                reason: 'Resolvers take the tenant from client input (x-tenant-id / Host). Without a ' +
+                    'membership check, any authenticated user can act on another tenant just by ' +
+                    'changing that header — a cross-tenant data breach. Tenant resolution is ' +
+                    'identification, never authorization.',
+                fix: "tenantMembershipPlugin()  // central routes opt out with meta: { central: true }",
+                docs: '/guide/security',
+            };
+        },
+    }),
+    defineRule({
+        id: 'tenant-scoping-missing',
+        category: 'tenancy',
+        check(ctx) {
+            if (!ctx.stack.tenancy || !ctx.prisma)
+                return null;
+            const unscoped = ctx.prisma.models.filter((model) => !model.tenantScoped && !GLOBAL_MODELS.has(model.name));
+            if (unscoped.length === 0)
+                return null;
+            const names = unscoped.map((m) => m.name).join(', ');
+            return {
+                id: 'tenant-scoping-missing',
+                title: 'Tenant-scoped app has models without a tenantId',
+                severity: 'warning',
+                category: 'tenancy',
+                detected: `models without a tenantId column: ${names}`,
+                recommended: 'add a tenantId to tenant-owned models so queries can never leak across tenants',
+                reason: 'With tenancy enabled, a model that lacks tenantId cannot be isolated by ' +
+                    'the tenant-scoping layer — a query can return rows from other tenants.',
+                fix: 'tenantId String  // + @@index([tenantId]); scope every query by the current tenant',
+                docs: '/guide/tenancy',
+            };
+        },
+    }),
+    // ── durability ────────────────────────────────────────────────────────────
+    defineRule({
+        id: 'memory-sources-in-use',
+        category: 'durability',
+        check(ctx) {
+            const sources = ctx.app?.memorySources ?? [];
+            if (sources.length === 0)
+                return null;
+            return {
+                id: 'memory-sources-in-use',
+                title: 'Non-durable in-memory sources are wired',
+                severity: 'info',
+                category: 'durability',
+                detected: `${ctx.app?.path} uses ${sources.join(', ')}`,
+                recommended: 'replace in-memory sources with database-backed ones before production',
+                reason: 'In-memory sources reset on every restart and are not shared across ' +
+                    'instances — fine for local dev, data loss in production.',
+                docs: '/guide/tenancy',
+            };
+        },
+    }),
+    defineRule({
+        id: 'redis-localhost-default',
+        category: 'config',
+        check(ctx) {
+            const value = ctx.env?.redisUrlDefault;
+            if (!value || !/localhost|127\.0\.0\.1/.test(value))
+                return null;
+            if (!ctx.stack.queue && !ctx.stack.subscriptions)
+                return null;
+            return {
+                id: 'redis-localhost-default',
+                title: 'Redis URL defaults to localhost',
+                severity: 'info',
+                category: 'config',
+                detected: `${ctx.env?.path} defaults REDIS_URL to "${value}"`,
+                recommended: 'set REDIS_URL from the environment in every non-local deployment',
+                reason: 'A localhost default silently falls back to a dev-only queue/dedupe backend ' +
+                    'in production if the env var is missing.',
+                docs: '/guide/configuration',
+            };
+        },
+    }),
+    defineRule({
+        id: 'in-memory-security-store',
+        category: 'security',
+        check(ctx) {
+            const SECURITY_STORES = {
+                MemoryPasskeyStore: 'WebAuthn passkeys',
+                MemoryWebAuthnChallengeStore: 'WebAuthn challenges',
+                MemoryAccessStore: 'roles & permissions',
+                MemoryDomainStore: 'verified custom domains',
+            };
+            const hit = (ctx.app?.memorySources ?? []).find((source) => source in SECURITY_STORES);
+            if (!hit)
+                return null;
+            return {
+                id: 'in-memory-security-store',
+                title: 'Security state is kept in an in-memory store',
+                severity: 'warning',
+                category: 'security',
+                detected: `${hit} holds ${SECURITY_STORES[hit]} in memory.`,
+                recommended: 'Back it with a durable store (database/Redis) in production.',
+                reason: 'In-memory security stores are wiped on restart and are not shared across ' +
+                    'instances — passkeys/permissions/verified domains would silently reset or ' +
+                    'diverge per replica, which can lock users out or bypass authorization.',
+                fix: `// swap ${hit} for a durable implementation of the same interface`,
+                docs: '/guide/security',
+            };
+        },
+    }),
+];
+/** Models that legitimately have no tenantId (platform-global tables). */
+const GLOBAL_MODELS = new Set(['Tenant', 'User', 'Plan', 'WebhookEvent', 'Migration']);

package/dist/doctor/run.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectContext } from '../context/project.js';
+import type { Diagnostic, DoctorRule } from './types.js';
+/**
+ * Run every rule against the project context and return the diagnostics that
+ * fired, most severe first.
+ */
+export declare function runDoctor(ctx: ProjectContext, rules?: DoctorRule[]): Diagnostic[];
+/** True when any diagnostic is an error — lets CI gate on `ai:doctor`. */
+export declare function hasErrors(diagnostics: Diagnostic[]): boolean;

package/dist/doctor/run.js

@@ -0,0 +1,16 @@
+import { DEFAULT_RULES } from './rules.js';
+const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+/**
+ * Run every rule against the project context and return the diagnostics that
+ * fired, most severe first.
+ */
+export function runDoctor(ctx, rules = DEFAULT_RULES) {
+    return rules
+        .map((rule) => rule.check(ctx))
+        .filter((d) => d !== null)
+        .sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+}
+/** True when any diagnostic is an error — lets CI gate on `ai:doctor`. */
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === 'error');
+}

package/dist/doctor/types.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectContext } from '../context/project.js';
+export type Severity = 'error' | 'warning' | 'info';
+export type DiagnosticCategory = 'security' | 'database' | 'observability' | 'tenancy' | 'performance' | 'durability' | 'config';
+export 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;
+}
+export interface DoctorRule {
+    id: string;
+    category: DiagnosticCategory;
+    /** Returns a diagnostic when the rule fires, else `null`. */
+    check(ctx: ProjectContext): Diagnostic | null;
+}
+export declare function defineRule(rule: DoctorRule): DoctorRule;

package/dist/doctor/types.js

@@ -0,0 +1,3 @@
+export function defineRule(rule) {
+    return rule;
+}