@basaltkit/ai 0.11.0 → 1.0.0

package/dist/make/fields.d.ts

@@ -0,0 +1,35 @@
+import type { PlanField } from '../plan/types.js';
+export type CanonicalType = 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Json';
+/** Map a loose plan type (`'string'`, `'DateTime'`, `'number'`…) to a canonical type. */
+export declare function canonicalType(raw: string): CanonicalType;
+/** Prisma column type — identical to the canonical name. */
+export 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.
+ */
+export declare function zodValidator(t: CanonicalType, create: boolean): string;
+/** Zod validator for a field, honoring an enum (`z.enum([...])`) over its base type. */
+export declare function zodForField(field: PlanField, create: boolean): string;
+/** The entity's own fields, minus reserved/base columns and duplicates. */
+export 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.
+ */
+export 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`).
+ */
+export declare function injectZodFields(content: string, fields: PlanField[], removeName?: boolean): {
+    content: string;
+    injected: boolean;
+};

package/dist/make/fields.js

@@ -0,0 +1,139 @@
+/** Columns the generator already emits — never re-inject these. */
+const RESERVED = new Set(['id', 'name', 'createdat', 'updatedat', 'deletedat', 'tenantid']);
+/** Map a loose plan type (`'string'`, `'DateTime'`, `'number'`…) to a canonical type. */
+export function canonicalType(raw) {
+    switch (raw.trim().toLowerCase()) {
+        case 'int':
+        case 'integer':
+        case 'number':
+        case 'bigint':
+            return 'Int';
+        case 'float':
+        case 'decimal':
+        case 'double':
+            return 'Float';
+        case 'bool':
+        case 'boolean':
+            return 'Boolean';
+        case 'date':
+        case 'datetime':
+        case 'timestamp':
+            return 'DateTime';
+        case 'json':
+        case 'object':
+            return 'Json';
+        default:
+            return 'String';
+    }
+}
+/** Prisma column type — identical to the canonical name. */
+export function prismaType(t) {
+    return t;
+}
+/**
+ * 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.
+ */
+export function zodValidator(t, create) {
+    switch (t) {
+        case 'Int':
+            return 'z.number().int()';
+        case 'Float':
+            return 'z.number()';
+        case 'Boolean':
+            return 'z.boolean()';
+        case 'DateTime':
+            return create ? 'z.coerce.date()' : 'z.string()';
+        case 'Json':
+            return 'z.unknown()';
+        case 'String':
+            return create ? 'z.string().min(1)' : 'z.string()';
+    }
+}
+function usable(field) {
+    return field.name.trim() !== '' && !RESERVED.has(field.name.toLowerCase());
+}
+/** Zod validator for a field, honoring an enum (`z.enum([...])`) over its base type. */
+export function zodForField(field, create) {
+    if (field.enum && field.enum.length > 0) {
+        return `z.enum([${field.enum.map((v) => `'${v}'`).join(', ')}])`;
+    }
+    return zodValidator(canonicalType(field.type), create);
+}
+/** The entity's own fields, minus reserved/base columns and duplicates. */
+export function domainFields(fields) {
+    const seen = new Set();
+    const out = [];
+    for (const field of fields) {
+        const key = field.name.toLowerCase();
+        if (!usable(field) || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(field);
+    }
+    return out;
+}
+function hasPrismaField(content, name) {
+    return new RegExp(`^[ \\t]*${name}[ \\t]+`, 'm').test(content);
+}
+/**
+ * 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.
+ */
+export function injectPrismaFields(content, fields, tenantScoped, removeName = false) {
+    const nameAnchor = /^([ \t]*)name[ \t]+String.*$/m;
+    if (!nameAnchor.test(content))
+        return { content, injected: false };
+    const extras = [];
+    if (tenantScoped && !hasPrismaField(content, 'tenantId'))
+        extras.push('  tenantId  String');
+    for (const field of domainFields(fields)) {
+        if (hasPrismaField(content, field.name))
+            continue;
+        extras.push(`  ${field.name}  ${prismaType(canonicalType(field.type))}`);
+    }
+    if (extras.length === 0)
+        return { content, injected: false };
+    let out = content.replace(nameAnchor, (line) => `${line}\n${extras.join('\n')}`);
+    if (tenantScoped)
+        out = out.replace(/\n\}\s*$/, `\n\n  @@index([tenantId])\n}\n`);
+    // Drop the generator's base `name` column when the entity supplies its own
+    // fields and none is literally `name` (avoids a spurious empty column).
+    if (removeName)
+        out = out.replace(/^[ \t]*name[ \t]+String\b.*\n/m, '');
+    return { content: out, injected: true };
+}
+/**
+ * Inject domain fields into a generated Zod schema file — into both the entity
+ * schema (`<Name>Schema`) and the create schema (`Create<Name>Schema`).
+ */
+export function injectZodFields(content, fields, removeName = false) {
+    const usableFields = domainFields(fields);
+    if (usableFields.length === 0)
+        return { content, injected: false };
+    let out = content;
+    let injected = false;
+    const entityAnchor = /^([ \t]*)name: z\.string\(\),.*$/m;
+    const entityLines = usableFields.map((f) => `  ${f.name}: ${zodForField(f, false)},`);
+    if (entityAnchor.test(out)) {
+        out = out.replace(entityAnchor, (line) => `${line}\n${entityLines.join('\n')}`);
+        injected = true;
+    }
+    const createAnchor = /^([ \t]*)name: z\.string\(\)\.min\(1\),.*$/m;
+    const createLines = usableFields.map((f) => `  ${f.name}: ${zodForField(f, true)},`);
+    if (createAnchor.test(out)) {
+        out = out.replace(createAnchor, (line) => `${line}\n${createLines.join('\n')}`);
+        injected = true;
+    }
+    // Drop the base `name` from both schemas when the entity has its own fields
+    // and none is literally `name`.
+    if (removeName) {
+        out = out.replace(/^[ \t]*name: z\.string\(\),.*\n/m, '');
+        out = out.replace(/^[ \t]*name: z\.string\(\)\.min\(1\),.*\n/m, '');
+    }
+    return { content: out, injected };
+}

package/dist/make/make.d.ts

@@ -0,0 +1,14 @@
+import type { ProjectContext } from '../context/project.js';
+import type { ArchitecturePlan } from '../plan/types.js';
+import type { MakeOptions, MakeResult } from './types.js';
+/**
+ * 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.
+ */
+export declare function runMake(ctx: ProjectContext, plan: ArchitecturePlan, options?: MakeOptions): Promise<MakeResult>;

package/dist/make/make.js

@@ -0,0 +1,316 @@
+import { FileExistsError, generateResource, names, registerResourceInApp, writeGenerated, } from '@basaltkit/generator';
+import { domainFields, injectPrismaFields, injectZodFields } from './fields.js';
+import { externalRelationTargets, injectPrismaRelations, inverseRelationLines, relationFieldLines, relationForeignKeys, } from './relations.js';
+import { injectOpenApiMeta } from './openapi.js';
+import { renderPermissionsFile } from './permissions.js';
+import { renderPrismaRepository } from './repository.js';
+import { extractModelBlock, mergeModelsIntoSchema, readSchema, runPrismaPush, writeSchema, } from './schema.js';
+import { injectAuditPlugin, injectAuditService, injectPermissionGuards } from './wire.js';
+/**
+ * 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.
+ */
+export async function runMake(ctx, plan, options = {}) {
+    const entities = plan.entities.filter((e) => e.name.trim() !== '');
+    if (entities.length === 0) {
+        throw new Error('ai:make — the plan has no entity to generate.');
+    }
+    const baseDir = options.baseDir ?? process.cwd();
+    const prismaDefault = ctx.stack.orm === 'prisma';
+    const resources = [];
+    for (const entity of entities) {
+        const gen = findGeneratorCommand(plan, entity.name);
+        const prisma = options.prisma ?? gen?.prisma ?? prismaDefault;
+        const softDelete = options.softDelete ?? gen?.softDelete ?? false;
+        const generated = generateResource(entity.name, { prisma, softDelete });
+        const { files, augmented, guarded, audited } = augmentFiles(generated, entity, plan, ctx, { prisma, softDelete });
+        const build = {
+            name: entity.name,
+            prisma,
+            softDelete,
+            files,
+            augmented,
+            guarded,
+            audited,
+            written: [],
+            registered: false,
+        };
+        if (!options.dryRun) {
+            try {
+                build.written = await writeGenerated(files, {
+                    baseDir,
+                    ...(options.force ? { force: true } : {}),
+                });
+                const reg = await registerResourceInApp(entity.name, { baseDir });
+                build.registered = reg.registered;
+                if (!reg.registered && reg.reason && reg.reason !== 'already registered') {
+                    build.note = `not auto-wired: ${reg.reason}`;
+                }
+            }
+            catch (error) {
+                if (error instanceof FileExistsError) {
+                    build.note = error.message.split('\n')[0] ?? error.message;
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        resources.push(build);
+    }
+    // Merge the generated models into prisma/schema.prisma (idempotent), and
+    // optionally run `prisma db push` — removing the biggest manual step.
+    const { schema, migration } = await mergeSchema(resources, baseDir, options);
+    const followUps = buildFollowUps(plan, resources, schema, migration);
+    const review = reviewBuild(ctx, plan, resources, schema, migration);
+    return {
+        request: plan.request,
+        dryRun: options.dryRun === true,
+        resources,
+        ...(schema ? { schema } : {}),
+        ...(migration ? { migration } : {}),
+        followUps,
+        review,
+    };
+}
+async function mergeSchema(resources, baseDir, options) {
+    const prismaResources = resources.filter((r) => r.prisma);
+    if (prismaResources.length === 0)
+        return { schema: undefined, migration: undefined };
+    const schemaPath = options.schemaPath ?? 'prisma/schema.prisma';
+    const blocks = prismaResources
+        .map((r) => r.files.find((f) => f.path.endsWith('.prisma')))
+        .map((f) => (f ? extractModelBlock(f.content) : null))
+        .filter((b) => b !== null);
+    const existing = await readSchema(baseDir, schemaPath);
+    if (existing === null) {
+        return { schema: { path: schemaPath, found: false, merged: [], skipped: [], written: false }, migration: undefined };
+    }
+    const outcome = mergeModelsIntoSchema(existing, blocks);
+    const schema = {
+        path: schemaPath,
+        found: true,
+        merged: outcome.merged,
+        skipped: outcome.skipped,
+        written: false,
+    };
+    if (options.dryRun)
+        return { schema, migration: undefined };
+    if (outcome.merged.length > 0) {
+        await writeSchema(baseDir, schemaPath, outcome.content);
+        schema.written = true;
+    }
+    if (options.migrate && (schema.written || outcome.skipped.length > 0)) {
+        const push = await runPrismaPush(baseDir);
+        return { schema, migration: { ok: push.ok, output: push.output } };
+    }
+    return { schema, migration: undefined };
+}
+/** Find the plan's generator step for an entity and parse its flags — the plan is the source of truth. */
+function findGeneratorCommand(plan, entityName) {
+    for (const step of plan.steps) {
+        if (step.kind !== 'generator' || !step.command)
+            continue;
+        const parsed = parseGeneratorCommand(step.command);
+        if (parsed && parsed.name.toLowerCase() === entityName.toLowerCase())
+            return parsed;
+    }
+    return null;
+}
+function parseGeneratorCommand(command) {
+    const match = /make:resource\s+(\w+)([^\n]*)/.exec(command);
+    if (!match || !match[1])
+        return null;
+    const rest = match[2] ?? '';
+    return { name: match[1], prisma: /--prisma\b/.test(rest), softDelete: /--soft-delete\b/.test(rest) };
+}
+function augmentFiles(files, entity, plan, ctx, opts) {
+    const tenantScoped = ctx.stack.tenancy && entity.tenantScoped;
+    // Domain fields plus the synthetic FK columns from belongs-to relations.
+    const effectiveFields = [...entity.fields, ...relationForeignKeys(entity)];
+    // Drop the generator's base `name` column when the entity has its own fields
+    // and none is literally `name` (else keep it as the label field).
+    const removeName = domainFields(effectiveFields).length > 0 && !effectiveFields.some((f) => f.name.toLowerCase() === 'name');
+    const keepName = !removeName;
+    // Per-entity permission namespace — so each entity in a multi-entity plan is
+    // guarded by its own permission, not a shared one from permissions[0].
+    const guardPrefix = names(entity.name).pluralKebab;
+    const wireGuards = ctx.stack.rbac && plan.permissions.length > 0;
+    const wireAudit = ctx.stack.audit && plan.auditEvents.length > 0;
+    let augmented = false;
+    let guarded = false;
+    let audited = false;
+    const out = files.map((file) => {
+        if (file.path.endsWith('.prisma')) {
+            const withFields = injectPrismaFields(file.content, effectiveFields, tenantScoped, removeName);
+            // Real Prisma relations: FK column (above), @relation field + inverse fields.
+            const withRelations = injectPrismaRelations(withFields.content, relationFieldLines(entity), inverseRelationLines(entity.name, plan.entities));
+            augmented = augmented || withFields.injected || withRelations.injected;
+            return { ...file, content: withRelations.content };
+        }
+        if (file.path.endsWith('.schema.ts')) {
+            const result = injectZodFields(file.content, effectiveFields, removeName);
+            augmented = augmented || result.injected;
+            return { ...file, content: result.content };
+        }
+        if (file.path.endsWith('.repository.ts') && opts.prisma) {
+            // Replace the generator's repository with a complete mapper (all domain
+            // fields + FK columns) + explicit tenant scoping when tenant-scoped.
+            const content = renderPrismaRepository(entity.name, effectiveFields, {
+                softDelete: opts.softDelete,
+                tenantScoped,
+                keepName,
+            });
+            return { ...file, content };
+        }
+        if (file.path.endsWith('.routes.ts')) {
+            let content = file.content;
+            if (wireGuards) {
+                const result = injectPermissionGuards(content, guardPrefix);
+                content = result.content;
+                guarded = guarded || result.injected;
+            }
+            // OpenAPI enrichment: summary + tags on every route (merges with the guard meta).
+            content = injectOpenApiMeta(content, entity.name).content;
+            return { ...file, content };
+        }
+        if (file.path.endsWith('.service.ts') && wireAudit) {
+            const result = injectAuditService(file.content, entity.name, plan.auditEvents);
+            audited = audited || result.injected;
+            return { ...file, content: result.content };
+        }
+        if (file.path.endsWith('.plugin.ts') && wireAudit) {
+            const result = injectAuditPlugin(file.content, entity.name);
+            return { ...file, content: result.content };
+        }
+        return file;
+    });
+    // Declare the resource's permissions + a grant helper (closes the RBAC loop).
+    if (guarded) {
+        const kebab = names(entity.name).kebab;
+        out.push({ path: `src/modules/${kebab}/${kebab}.permissions.ts`, content: renderPermissionsFile(entity.name) });
+    }
+    return { files: out, augmented, guarded, audited };
+}
+function buildFollowUps(plan, resources, schema, migration) {
+    const followUps = [];
+    const prismaResources = resources.filter((r) => r.prisma);
+    if (prismaResources.length > 0) {
+        if (!schema?.found) {
+            const list = prismaResources.map((r) => `src/modules/${kebab(r.name)}/${kebab(r.name)}.prisma`).join(', ');
+            followUps.push(`Add the generated model(s) (${list}) to prisma/schema.prisma, then run \`npx prisma db push\` and restart the server.`);
+        }
+        else if (migration) {
+            followUps.push(migration.ok
+                ? 'Restart the server so it loads the regenerated Prisma client.'
+                : '`prisma db push` failed — check the output, fix it, and re-run `npx prisma db push`.');
+        }
+        else {
+            followUps.push('Run `npx prisma db push` (or re-run `ai:make --migrate`) to create the table(s) + regenerate the client, then restart the server.');
+        }
+    }
+    const external = externalRelationTargets(plan.entities);
+    if (external.length > 0) {
+        followUps.push(`Relations reference model(s) not in this plan (${external.join(', ')}). Add the inverse field ` +
+            '(e.g. `items <This>[]`) to those existing models in schema.prisma so Prisma can validate the relation.');
+    }
+    const guardedResources = resources.filter((r) => r.guarded);
+    const audited = resources.some((r) => r.audited);
+    if (plan.permissions.length > 0 && guardedResources.length === 0) {
+        followUps.push(`Register RBAC permissions (${plan.permissions.join(', ')}) and guard the routes.`);
+    }
+    else if (guardedResources.length > 0) {
+        const helpers = guardedResources.map((r) => `grant${names(r.name).pascal}Permissions(store, 'admin')`).join(', ');
+        followUps.push(`Grant permissions to your roles during seed/setup — call ${helpers} (declared in each module's *.permissions.ts).`);
+    }
+    if (plan.auditEvents.length > 0 && !audited) {
+        followUps.push(`Emit audit events (${plan.auditEvents.join(', ')}) on create/update/delete.`);
+    }
+    return followUps;
+}
+function reviewBuild(ctx, plan, resources, schema, migration) {
+    const items = [];
+    // Tenant isolation — the gate the spec cares most about.
+    if (ctx.stack.tenancy) {
+        const tenantEntities = plan.entities.filter((e) => e.tenantScoped);
+        if (tenantEntities.length === 0) {
+            items.push({ label: 'Tenant isolation', status: 'warn', detail: 'no entity marked tenant-scoped — confirm that is intended' });
+        }
+        else {
+            const missing = resources.filter((r) => plan.entities.find((e) => e.name === r.name)?.tenantScoped && !hasTenantId(r));
+            items.push(missing.length === 0
+                ? { label: 'Tenant isolation', status: 'pass', detail: 'tenantId present on tenant-scoped models' }
+                : { label: 'Tenant isolation', status: 'fail', detail: `missing tenantId: ${missing.map((r) => r.name).join(', ')}` });
+        }
+    }
+    else {
+        items.push({ label: 'Tenant isolation', status: 'pass', detail: 'tenancy is off — not applicable' });
+    }
+    // Validation + routes.
+    const hasRoutes = resources.every((r) => r.files.some((f) => f.path.endsWith('.routes.ts')));
+    const hasSchema = resources.every((r) => r.files.some((f) => f.path.endsWith('.schema.ts')));
+    items.push(hasRoutes && hasSchema
+        ? { label: 'Validation & routes', status: 'pass', detail: 'Zod schema + typed routes generated' }
+        : { label: 'Validation & routes', status: 'fail', detail: 'schema or routes missing' });
+    // Tests.
+    const hasTests = resources.every((r) => r.files.some((f) => f.path.endsWith('.test.ts')));
+    items.push(hasTests
+        ? { label: 'Tests', status: 'pass', detail: 'a test file was generated per resource' }
+        : { label: 'Tests', status: 'fail', detail: 'no test generated' });
+    // Permissions — auto-wired as route meta.can guards when RBAC is enabled.
+    if (plan.permissions.length > 0) {
+        const guarded = resources.some((r) => r.guarded);
+        items.push(guarded
+            ? { label: 'Permissions', status: 'pass', detail: 'routes guarded + permissions declared in *.permissions.ts (grant via the helper)' }
+            : {
+                label: 'Permissions',
+                status: 'warn',
+                detail: ctx.stack.rbac ? 'planned but not auto-wired' : 'RBAC (@basaltkit/permissions) not enabled — wire manually',
+            });
+    }
+    // Audit — auto-wired into the service/plugin when audit is enabled.
+    if (plan.auditEvents.length > 0) {
+        const audited = resources.some((r) => r.audited);
+        items.push(audited
+            ? { label: 'Audit', status: 'pass', detail: 'AUDIT.record() wired into create/update/delete' }
+            : {
+                label: 'Audit',
+                status: 'warn',
+                detail: ctx.stack.audit ? 'planned but not auto-wired' : 'audit (@basaltkit/audit) not enabled — wire manually',
+            });
+    }
+    // Migration — auto-merged into schema.prisma; `--migrate` runs prisma db push.
+    if (resources.some((r) => r.prisma)) {
+        if (migration?.ok) {
+            items.push({ label: 'Migration', status: 'pass', detail: 'model merged into schema.prisma + prisma db push ran' });
+        }
+        else if (migration) {
+            items.push({ label: 'Migration', status: 'fail', detail: 'prisma db push failed — see output' });
+        }
+        else if (schema?.found) {
+            items.push({ label: 'Migration', status: 'warn', detail: 'model merged into schema.prisma — run npx prisma db push' });
+        }
+        else {
+            items.push({ label: 'Migration', status: 'warn', detail: 'add the model to schema.prisma + run npx prisma db push' });
+        }
+    }
+    return { items, ok: !items.some((i) => i.status === 'fail') };
+}
+function hasTenantId(resource) {
+    const model = resource.files.find((f) => f.path.endsWith('.prisma'));
+    if (!model)
+        return false;
+    return /^[ \t]*tenantId[ \t]+/m.test(model.content);
+}
+function kebab(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+}

package/dist/make/openapi.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare function injectOpenApiMeta(content: string, entityName: string): {
+    content: string;
+    injected: boolean;
+};

package/dist/make/openapi.js

@@ -0,0 +1,36 @@
+import { names } from '@basaltkit/generator';
+/** Human summary for a generated CRUD route, from its method + url. */
+function summaryFor(method, url, singular, plural) {
+    switch (method.toUpperCase()) {
+        case 'GET':
+            return url.includes(':id') ? `Get a ${singular}` : `List ${plural}`;
+        case 'POST':
+            return url.endsWith('/restore') ? `Restore a ${singular}` : `Create a ${singular}`;
+        case 'PATCH':
+        case 'PUT':
+            return `Update a ${singular}`;
+        case 'DELETE':
+            return `Delete a ${singular}`;
+        default:
+            return `${singular} operation`;
+    }
+}
+/**
+ * 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.
+ */
+export function injectOpenApiMeta(content, entityName) {
+    const n = names(entityName);
+    const singular = n.kebab.replace(/-/g, ' ');
+    const plural = n.pluralKebab.replace(/-/g, ' ');
+    const tag = n.pascal;
+    let injected = false;
+    const out = content.replace(/route\(\{\s*\n(\s*)method: '(\w+)',\s*\n\s*url: '([^']*)',(?:\s*\n\s*meta: \{([^}]*)\},)?/g, (_match, indent, method, url, metaInner) => {
+        const extra = `summary: '${summaryFor(method, url, singular, plural)}', tags: ['${tag}']`;
+        const meta = metaInner !== undefined ? `{ ${metaInner.trim()}, ${extra} }` : `{ ${extra} }`;
+        injected = true;
+        return `route({\n${indent}method: '${method}',\n${indent}url: '${url}',\n${indent}meta: ${meta},`;
+    });
+    return { content: out, injected };
+}

package/dist/make/permissions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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).
+ */
+export 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).
+ */
+export declare function renderPermissionsFile(name: string): string;

package/dist/make/permissions.js

@@ -0,0 +1,38 @@
+import { names } from '@basaltkit/generator';
+/**
+ * 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).
+ */
+export function permissionList(name) {
+    const prefix = names(name).pluralKebab;
+    return ['view', 'create', 'update', 'delete'].map((action) => `${prefix}.${action}`);
+}
+/**
+ * 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).
+ */
+export function renderPermissionsFile(name) {
+    const n = names(name);
+    const listLines = permissionList(name)
+        .map((p) => `  '${p}',`)
+        .join('\n');
+    return `import { GLOBAL_SCOPE, type AccessStore } from '@basaltkit/permissions'
+
+/** RBAC permissions for the ${n.pascal} resource — the ones its routes guard on. */
+export const ${n.constant}_PERMISSIONS = [
+${listLines}
+] as const
+
+/** Grant every ${n.pascal} permission to a role (default scope: global). */
+export async function grant${n.pascal}Permissions(
+  store: AccessStore,
+  role: string,
+  scope: string = GLOBAL_SCOPE,
+): Promise<void> {
+  await store.grantToRole(role, [...${n.constant}_PERMISSIONS], scope)
+}
+`;
+}

package/dist/make/relations.d.ts

@@ -0,0 +1,23 @@
+import type { PlanEntity, PlanField, PlanRelation } from '../plan/types.js';
+/**
+ * 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`. */
+export declare function foreignKey(relation: PlanRelation): string;
+/** Synthetic FK fields (String) for an entity's relations — feed the Zod schema, mapper and columns. */
+export declare function relationForeignKeys(entity: PlanEntity): PlanField[];
+/** Prisma relation field lines for the entity's belongs-to relations. */
+export declare function relationFieldLines(entity: PlanEntity): string[];
+/** Inverse `hasMany` lines to add to `modelName`, from every other entity that belongs to it. */
+export declare function inverseRelationLines(modelName: string, allEntities: PlanEntity[]): string[];
+/** Insert relation + inverse lines into a generated Prisma model, before its closing brace. */
+export 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). */
+export declare function externalRelationTargets(entities: PlanEntity[]): string[];