@basaltkit/ai 1.5.0 → 1.6.0

package/dist/commands.js

@@ -6,7 +6,7 @@ import { applyFixEdits, fixableIds, planFix, renderFixes } from './doctor/fixes.
 import { createProvider, providerEnvFromProcess } from './provider/factory.js';
 import { createPlan } from './plan/plan.js';
 import { renderPlan } from './plan/render.js';
-import { runMake } from './make/make.js';
+import { packageSteps, runMake } from './make/make.js';
 import { renderMakeResult } from './make/render.js';
 import { runPrismaPush } from './make/schema.js';
 import { verifyProject } from './make/verify.js';
@@ -39,7 +39,7 @@ export function aiCommands(options = {}) {
                 io.log('');
                 if (args.length > 0) {
                     io.log(`You asked: "${args.join(' ')}"`);
-                    io.log('Natural-language planning & scaffolding (ai:plan / ai:make) land in the next phase.');
+                    io.log(`Plan it with: basalt ai:plan "${args.join(' ')}"`);
                     io.log('');
                 }
                 io.log('Available now:');
@@ -182,6 +182,12 @@ export function aiCommands(options = {}) {
                 }
                 renderPlan(plan, io);
                 io.log('');
+                // A plan that only reuses packages has nothing to scaffold — ai:make does
+                // not install dependencies, so the package steps above are the whole job.
+                if (plan.entities.length === 0 && packageSteps(plan).length > 0) {
+                    io.log('Nothing to scaffold — this plan reuses ecosystem packages. Run the package steps above.');
+                    return 0;
+                }
                 // Agent review over the generated code — read-only, uses the same provider.
                 const agentReview = async (result) => {
                     if (flags['review'] !== true)

package/dist/index.d.ts

@@ -15,6 +15,7 @@ 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 { ECOSYSTEM_PACKAGES, renderEcosystemCatalog, type EcosystemPackage } from './plan/packages.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';

package/dist/index.js

@@ -21,6 +21,7 @@ export { analyze } from './analyze/run.js';
 export { createPlan, parsePlan } from './plan/plan.js';
 export { buildPlanContext } from './plan/context.js';
 export { BASALT_KNOWLEDGE } from './plan/knowledge.js';
+export { ECOSYSTEM_PACKAGES, renderEcosystemCatalog } from './plan/packages.js';
 export { renderPlan } from './plan/render.js';
 // Implementation (spec §4 Implement) — execute a plan via the generator + review gate.
 export { runMake } from './make/make.js';

package/dist/make/make.d.ts

@@ -12,3 +12,5 @@ import type { MakeOptions, MakeResult } from './types.js';
  * touches the database, never deletes.
  */
 export declare function runMake(ctx: ProjectContext, plan: ArchitecturePlan, options?: MakeOptions): Promise<MakeResult>;
+/** The plan's `package` steps as instructions — ai:make never installs dependencies itself. */
+export declare function packageSteps(plan: ArchitecturePlan): string[];

package/dist/make/make.js

@@ -28,7 +28,10 @@ export async function runMake(ctx, plan, options = {}) {
     assertSafePlan(plan);
     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 packages = packageSteps(plan);
+        throw new Error(packages.length > 0
+            ? `ai:make — nothing to generate: the plan reuses ecosystem packages. ${packages.join(' ')}`
+            : 'ai:make — the plan has no entity to generate.');
     }
     throwIfAborted(options.signal);
     const baseDir = options.baseDir ?? process.cwd();
@@ -222,7 +225,8 @@ function augmentFiles(files, entity, plan, ctx, opts) {
     return { files: out, augmented, guarded, audited };
 }
 function buildFollowUps(plan, resources, schema, migration) {
-    const followUps = [];
+    // Packages first: the generated code may depend on them being wired.
+    const followUps = packageSteps(plan);
     const prismaResources = resources.filter((r) => r.prisma);
     if (prismaResources.length > 0) {
         if (!schema?.found) {
@@ -257,6 +261,12 @@ function buildFollowUps(plan, resources, schema, migration) {
     }
     return followUps;
 }
+/** The plan's `package` steps as instructions — ai:make never installs dependencies itself. */
+export function packageSteps(plan) {
+    return plan.steps
+        .filter((step) => step.kind === 'package')
+        .map((step) => `${step.title}${step.command ? ` — \`${step.command}\`` : ''}${step.detail ? `: ${step.detail}` : ''}`);
+}
 function reviewBuild(ctx, plan, resources, schema, migration) {
     const items = [];
     // Tenant isolation — the gate the spec cares most about.

package/dist/plan/context.d.ts

@@ -2,7 +2,7 @@ import type { ProjectContext } from '../context/project.js';
 /**
  * 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.
+ * the Architect needs to ground a plan: enabled capabilities, existing models,
+ * the ecosystem packages already installed and the generator's flags.
  */
 export declare function buildPlanContext(ctx: ProjectContext): string;

package/dist/plan/context.js

@@ -1,8 +1,9 @@
+import { ECOSYSTEM_PACKAGES } from './packages.js';
 /**
  * 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.
+ * the Architect needs to ground a plan: enabled capabilities, existing models,
+ * the ecosystem packages already installed and the generator's flags.
  */
 export function buildPlanContext(ctx) {
     const s = ctx.stack;
@@ -25,12 +26,18 @@ export function buildPlanContext(ctx) {
     const models = ctx.prisma && ctx.prisma.models.length > 0
         ? ctx.prisma.models.map((m) => `${m.name}${m.tenantScoped ? ' (tenantId)' : ''}`).join(', ')
         : '(none)';
+    // Catalog packages only: the store/driver packages (-prisma, -s3…) are
+    // implementation detail the planner reaches through the catalog entry.
+    const catalog = new Set(ECOSYSTEM_PACKAGES.map((p) => p.name));
+    const installed = ctx.installed.filter((name) => catalog.has(name));
     const lines = [
         'PROJECT STACK:',
         ...caps.map((c) => `- ${c}`),
         '',
         `EXISTING PRISMA MODELS: ${models}`,
         '',
+        `INSTALLED ECOSYSTEM PACKAGES: ${installed.join(', ') || '(none)'} — use these as they are; any other catalog package needs a "package" install step.`,
+        '',
         'GENERATOR: `basalt make:resource <Name>` — flags: --prisma, --soft-delete, --no-register, --dir, --force.',
     ];
     if (ctx.app)

package/dist/plan/knowledge.d.ts

@@ -6,4 +6,4 @@
  * This is deliberately prescriptive: the plan must reuse the generator and the
  * platform plugins, never hand-roll parallel abstractions.
  */
-export 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.";
+export declare const BASALT_KNOWLEDGE: string;

package/dist/plan/knowledge.js

@@ -1,3 +1,4 @@
+import { renderEcosystemCatalog } from './packages.js';
 /**
  * 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
@@ -10,6 +11,11 @@ export const BASALT_KNOWLEDGE = `You are the Architect agent for Basalt — a ba
 
 ABSOLUTE RULES — always use the framework's official APIs and generators, never invent new ones:
 
+0. ECOSYSTEM FIRST. Before planning any resource, check whether an official package already covers the capability (catalog below). If one does, use it: a "package" step whose "command" installs it (\`pnpm add <package>\`, plus its Prisma store when the app uses Prisma) and whose "detail" says how to wire its plugin/routes in src/app.ts — or, when the project already has it installed, a step that only wires/uses it. NEVER generate a resource, model or module that duplicates a package (no Comment model when @basaltkit/comments exists, no Notification table, no File/Attachment model, no Team/Invitation model, no AuditLog). Do NOT list a package-covered concept in "entities" — entities are only the domain models no package provides. Only generate from scratch what the catalog does not cover, and say so in "warnings" when a package covers it only partly.
+
+ECOSYSTEM CATALOG:
+${renderEcosystemCatalog()}
+
 1. SCAFFOLDING. Create a resource with the generator, not by hand:
    \`basalt make:resource <Name>\` — 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.
    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.
@@ -36,14 +42,14 @@ OUTPUT: Return ONLY a single JSON object (no prose, no markdown fences) matching
       "relations": [{ "name": string, "model": string }] }   // belongs-to: this model gets a <name>Id FK → <model>
   ],
   "steps": [                             // ordered implementation steps
-    { "order": number, "title": string, "kind": "generator"|"schema"|"migration"|"service"|"routes"|"permissions"|"audit"|"test"|"docs"|"other", "detail": string, "command": string, "files": string[] }
+    { "order": number, "title": string, "kind": "package"|"generator"|"schema"|"migration"|"service"|"routes"|"permissions"|"audit"|"test"|"docs"|"other", "detail": string, "command": string, "files": string[] }
   ],
   "permissions": string[],               // e.g. ["patients.view","patients.create",...]
   "auditEvents": string[],               // e.g. ["patient.created",...]
   "tenantScoped": boolean,               // does this feature involve tenant-owned data
   "warnings": string[]                   // risks, decisions to confirm, missing info
 }
-For generator steps, put the exact command in "command" (e.g. "basalt make:resource Patient --prisma --soft-delete"). Omit "command"/"files" when not applicable.
+For generator steps, put the exact command in "command" (e.g. "basalt make:resource Patient --prisma --soft-delete"); for package steps, the install command (e.g. "pnpm add @basaltkit/comments @basaltkit/comments-prisma"), or omit it when the package is already installed. Omit "command"/"files" when not applicable.
 
 ENUMS: a field with a fixed set of values (a status/state) MUST set "enum" to those values — e.g. "estado (pago/pendente)" → { "name": "estado", "type": "String", "enum": ["pago", "pendente"] }. It becomes a validated z.enum([...]) (stored as a String column), never a free z.string().
 

package/dist/plan/packages.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The ecosystem catalog the Architect plans with: each official package, the
+ * capability it covers and the entry points an app wires. Without it the model
+ * only knew the generator and rebuilt features (comments, files, notifications…)
+ * as fresh resources instead of installing the package that already ships them.
+ *
+ * Kept in sync with `packages/*` by `tests/plan-packages.test.ts`.
+ */
+export interface EcosystemPackage {
+    /** npm name, e.g. `@basaltkit/comments`. */
+    name: string;
+    /** What it provides, in the words a request would use. */
+    covers: string;
+    /** The plugin factory wired in src/app.ts. */
+    plugin?: string;
+    /** Ready-made routes the app spreads into its route list. */
+    routes?: string;
+    /** The Prisma-backed store package, when the default store is in-memory. */
+    prisma?: string;
+}
+export declare const ECOSYSTEM_PACKAGES: readonly EcosystemPackage[];
+/** One catalog line per package, for the planner's system prompt. */
+export declare function renderEcosystemCatalog(packages?: readonly EcosystemPackage[]): string;

package/dist/plan/packages.js

@@ -0,0 +1,39 @@
+export const ECOSYSTEM_PACKAGES = [
+    { name: '@basaltkit/auth', covers: 'login, signup, JWT/sessions, password reset, MFA, OAuth, passkeys, API keys', plugin: 'authPlugin', prisma: '@basaltkit/auth-prisma' },
+    { name: '@basaltkit/permissions', covers: 'roles, permissions, policies, route guards (RBAC)', plugin: 'permissionsPlugin', prisma: '@basaltkit/permissions-prisma' },
+    { name: '@basaltkit/tenancy', covers: 'multi-tenancy: tenant resolution and tenant context', plugin: 'tenancyPlugin', prisma: '@basaltkit/tenancy-prisma' },
+    { name: '@basaltkit/teams', covers: 'team members, roles inside a tenant, email invitations', plugin: 'teamsPlugin', routes: 'teamRoutes', prisma: '@basaltkit/teams-prisma' },
+    { name: '@basaltkit/comments', covers: 'comment threads on any resource, @mentions, resolve/reopen', plugin: 'commentsPlugin', routes: 'commentRoutes', prisma: '@basaltkit/comments-prisma' },
+    { name: '@basaltkit/activity', covers: 'user-facing activity feed / history of changes', plugin: 'activityPlugin', prisma: '@basaltkit/activity-prisma' },
+    { name: '@basaltkit/audit', covers: 'append-only audit trail of state changes', plugin: 'auditPlugin', prisma: '@basaltkit/audit-prisma' },
+    { name: '@basaltkit/notifications', covers: 'in-app and email notifications, per-user preferences', plugin: 'notificationsPlugin', routes: 'inAppRoutes', prisma: '@basaltkit/notifications-prisma' },
+    { name: '@basaltkit/files', covers: 'file uploads and attachments, quotas, signed URLs', plugin: 'filesPlugin', routes: 'fileRoutes', prisma: '@basaltkit/files-prisma' },
+    { name: '@basaltkit/files-versions', covers: 'document versions / revisions on top of files', plugin: 'fileVersionsPlugin' },
+    { name: '@basaltkit/storage', covers: 'disk/object storage (local, S3, Azure, GCS)', plugin: 'storagePlugin' },
+    { name: '@basaltkit/drives', covers: 'import from Google Drive, OneDrive/SharePoint, Dropbox', plugin: 'drivesPlugin' },
+    { name: '@basaltkit/subscriptions', covers: 'billing: plans, subscriptions, trials, usage limits, payment gateways', plugin: 'subscriptionsPlugin', prisma: '@basaltkit/subscriptions-prisma' },
+    { name: '@basaltkit/webhooks', covers: 'outbound webhooks with signing and retries', plugin: 'webhooksPlugin', prisma: '@basaltkit/webhooks-prisma' },
+    { name: '@basaltkit/events', covers: 'typed domain events, listeners, transactional outbox', plugin: 'eventsPlugin', prisma: '@basaltkit/events-prisma' },
+    { name: '@basaltkit/queue', covers: 'background jobs (BullMQ, RabbitMQ, SQS, Kafka)', plugin: 'queuePlugin' },
+    { name: '@basaltkit/scheduler', covers: 'scheduled / recurring tasks (cron-like)', plugin: 'schedulerPlugin' },
+    { name: '@basaltkit/mailer', covers: 'sending email (SMTP, Resend, SES, Mailgun)', plugin: 'mailerPlugin' },
+    { name: '@basaltkit/inbound-mail', covers: 'receiving email', routes: 'inboundMailRoutes' },
+    { name: '@basaltkit/realtime', covers: 'live updates over WebSocket/SSE, presence', plugin: 'realtimePlugin' },
+    { name: '@basaltkit/search', covers: 'full-text search (Postgres, Elasticsearch, Meilisearch)', plugin: 'searchPlugin' },
+    { name: '@basaltkit/cache', covers: 'caching with tags and tenant scoping', plugin: 'cachePlugin' },
+    { name: '@basaltkit/flags', covers: 'feature flags and percentage rollouts', plugin: 'flagsPlugin' },
+    { name: '@basaltkit/exports', covers: 'CSV/JSON/XLSX exports and CSV import', plugin: 'exportsPlugin' },
+    { name: '@basaltkit/i18n', covers: 'translations, locale, number/date formatting' },
+    { name: '@basaltkit/backup', covers: 'PostgreSQL backups', plugin: 'backupPlugin' },
+    { name: '@basaltkit/mcp', covers: 'expose routes as MCP tools for AI agents', plugin: 'mcpPlugin' },
+];
+/** One catalog line per package, for the planner's system prompt. */
+export function renderEcosystemCatalog(packages = ECOSYSTEM_PACKAGES) {
+    return packages
+        .map((p) => {
+        const wiring = [p.plugin, p.routes ? `${p.routes}()` : undefined].filter(Boolean).join(' + ');
+        const store = p.prisma ? `; Prisma store: ${p.prisma}` : '';
+        return `- ${p.name} — ${p.covers}${wiring ? ` (wire: ${wiring}${store})` : store ? ` (${store.slice(2)})` : ''}`;
+    })
+        .join('\n');
+}

package/dist/plan/plan.js

@@ -3,6 +3,7 @@ import { runGeneration } from '../generate.js';
 import { buildPlanContext } from './context.js';
 import { BASALT_KNOWLEDGE } from './knowledge.js';
 const STEP_KINDS = [
+    'package',
     'generator',
     'schema',
     'migration',

package/dist/plan/render.js

@@ -51,5 +51,5 @@ export function renderPlan(plan, io) {
     }
     io.log('');
     io.log('This is a plan only — nothing was changed.');
-    io.log('Next: `basalt ai:make` will execute it (arrives in the next phase).');
+    io.log(`Next: basalt ai:make "${plan.request}" implements it.`);
 }

package/dist/plan/types.d.ts

@@ -1,4 +1,6 @@
-export type PlanStepKind = 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
+export type PlanStepKind = 
+/** Install and/or wire an official `@basaltkit/*` package instead of generating code. */
+'package' | 'generator' | 'schema' | 'migration' | 'service' | 'routes' | 'permissions' | 'audit' | 'test' | 'docs' | 'other';
 export interface PlanField {
     name: string;
     type: string;

package/dist/schema/index.d.ts

@@ -230,6 +230,7 @@ export declare const PlanStepKindSchema: z.ZodEnum<{
     generator: "generator";
     migration: "migration";
     other: "other";
+    package: "package";
     permissions: "permissions";
     routes: "routes";
     schema: "schema";
@@ -245,6 +246,7 @@ export declare const PlanStepSchema: z.ZodObject<{
         generator: "generator";
         migration: "migration";
         other: "other";
+        package: "package";
         permissions: "permissions";
         routes: "routes";
         schema: "schema";
@@ -281,6 +283,7 @@ export declare const ArchitecturePlanSchema: z.ZodObject<{
             generator: "generator";
             migration: "migration";
             other: "other";
+            package: "package";
             permissions: "permissions";
             routes: "routes";
             schema: "schema";

package/dist/schema/index.js

@@ -123,6 +123,7 @@ export const PlanEntitySchema = z.object({
     relations: z.array(PlanRelationSchema).optional(),
 });
 export const PlanStepKindSchema = z.enum([
+    'package',
     'generator',
     'schema',
     'migration',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/ai",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -31,7 +31,7 @@
   ],
   "dependencies": {
     "zod": "^4.6.7",
-    "@basaltkit/cli": "^1.7.0",
+    "@basaltkit/cli": "^1.7.1",
     "@basaltkit/generator": "^1.7.0"
   },
   "devDependencies": {