feat(plugins): add plugins migrate command for schema updates

When a plugin releases a new version with schema changes, developers
can now run `codapult plugins migrate [name]` to diff the installed
schema block against the latest plugin source, patch schema.ts, and
generate a proper Drizzle migration. Supports --push flag for dev mode.

- Add 'update' action to patchSchemaTables (diff-aware replace)
- Register codapult_plugins_migrate MCP tool (19 tools total)
- Add 3 unit tests for update/unchanged/not-installed cases

Author: vladzdev

README.md

@@ -27,6 +27,7 @@ npx @codapult/cli <command>
 
 - `codapult plugins add <name>` — install a plugin from a local directory
 - `codapult plugins remove <name>` — uninstall a plugin
+- `codapult plugins migrate [name]` — update plugin schema and generate DB migration (`--push` for dev mode)
 - `codapult plugins list` — list installed plugins
 
 ### Code Generation
@@ -61,7 +62,7 @@ npx @codapult/cli <command>
 
 ## MCP Server
 
-The CLI includes an MCP (Model Context Protocol) server with 18 tools, 6 resources, and 2 prompt templates for AI-assisted development. See the [MCP documentation](https://codapult.dev/docs/developer-tools/mcp) for details.
+The CLI includes an MCP (Model Context Protocol) server with 19 tools, 6 resources, and 2 prompt templates for AI-assisted development. See the [MCP documentation](https://codapult.dev/docs/developer-tools/mcp) for details.
 
 ## License
 

src/commands/plugins.ts

@@ -263,6 +263,119 @@ export async function pluginsRemoveCommand(name: string): Promise<void> {
   console.log();
 }
 
+// ---------------------------------------------------------------------------
+// codapult plugins migrate [name]
+// ---------------------------------------------------------------------------
+
+function getInstalledPluginNames(root: string): string[] {
+  const pluginsDir = resolve(root, 'src/plugins');
+  if (!existsSync(pluginsDir)) return [];
+  return readdirSync(pluginsDir)
+    .filter((f) => f.endsWith('.ts') && f !== 'index.ts')
+    .map((f) => f.replace('.ts', ''));
+}
+
+export async function pluginsMigrateCommand(
+  name: string | undefined,
+  options: { push?: boolean },
+): Promise<void> {
+  const root = findProjectRoot();
+  if (!root) {
+    fail('Not inside a Codapult project.');
+    process.exit(1);
+  }
+
+  const pluginNames = name ? [name] : getInstalledPluginNames(root);
+
+  if (pluginNames.length === 0) {
+    info('No installed plugins found.');
+    dim('Use: codapult plugins add <name>');
+    return;
+  }
+
+  heading(name ? `Migrating plugin: ${name}` : 'Migrating all installed plugins');
+
+  let schemaUpdated = false;
+
+  for (const pName of pluginNames) {
+    const result = resolveManifest(root, pName);
+    if (!result) {
+      warn(`Plugin "${pName}" — manifest not found, skipping.`);
+      continue;
+    }
+
+    const { manifest, pluginDir } = result;
+
+    if (!manifest.install.schemaTables) {
+      dim(`${manifest.name}: no schema tables — skipping.`);
+      continue;
+    }
+
+    const updated = patchSchemaTables(
+      root,
+      manifest.name,
+      pluginDir,
+      manifest.install.schemaTables,
+      'update',
+    );
+
+    if (updated) {
+      success(`${manifest.name}: schema updated in schema.ts`);
+      schemaUpdated = true;
+    } else {
+      dim(`${manifest.name}: schema is already up to date.`);
+    }
+
+    // Also refresh imports in case the plugin added new drizzle column types
+    if (manifest.install.schemaImports && manifest.install.schemaImports.length > 0) {
+      patchSchemaImports(root, manifest.name, manifest.install.schemaImports, 'add');
+    }
+  }
+
+  if (!schemaUpdated) {
+    console.log();
+    info('All plugin schemas are up to date — no migration needed.');
+    return;
+  }
+
+  console.log();
+
+  if (options.push) {
+    info('Applying schema changes (db:push)...');
+    if (!execQuiet('pnpm db:push', root)) {
+      fail('db:push failed — run manually: pnpm db:push');
+      process.exit(1);
+    }
+    success('Database schema applied');
+  } else {
+    info('Generating migration...');
+    try {
+      execSync('pnpm db:generate', { cwd: root, stdio: 'inherit' });
+      success('Migration generated');
+    } catch {
+      fail('db:generate failed — run manually: pnpm db:generate');
+      process.exit(1);
+    }
+
+    console.log();
+    const apply = await confirm('Apply the migration now (pnpm db:migrate)?');
+    if (apply) {
+      try {
+        execSync('pnpm db:migrate', { cwd: root, stdio: 'inherit' });
+        success('Migration applied');
+      } catch {
+        fail('db:migrate failed — run manually: pnpm db:migrate');
+        process.exit(1);
+      }
+    } else {
+      info('Skipped. Apply later with: pnpm db:migrate');
+    }
+  }
+
+  heading('Done!');
+  console.log();
+}
+
 // ---------------------------------------------------------------------------
 // codapult plugins list
 // ---------------------------------------------------------------------------

src/index.ts

@@ -6,7 +6,12 @@ import { setupCommand } from './commands/setup.js';
 import { updateCommand } from './commands/update.js';
 import { doctorCommand } from './commands/doctor.js';
 import { configShowCommand } from './commands/config-show.js';
-import { pluginsAddCommand, pluginsRemoveCommand, pluginsListCommand } from './commands/plugins.js';
+import {
+  pluginsAddCommand,
+  pluginsRemoveCommand,
+  pluginsListCommand,
+  pluginsMigrateCommand,
+} from './commands/plugins.js';
 import {
   generatePageCommand,
   generateApiCommand,
@@ -73,6 +78,12 @@ plugins
 
 plugins.command('remove <name>').description('uninstall a plugin').action(pluginsRemoveCommand);
 
+plugins
+  .command('migrate [name]')
+  .description('update plugin schema and generate DB migration')
+  .option('--push', 'use db:push instead of db:generate + db:migrate (dev mode)')
+  .action(pluginsMigrateCommand);
+
 plugins.command('list').description('list installed plugins').action(pluginsListCommand);
 
 const generate = program

src/mcp/tools/plugins.ts

@@ -193,4 +193,84 @@ export function registerPluginTools(server: McpServer): void {
       };
     },
   );
+
+  server.registerTool(
+    'codapult_plugins_migrate',
+    {
+      title: 'Migrate Plugin Schema',
+      description:
+        "Update an installed plugin's schema in schema.ts to match the latest version. " +
+        'Returns whether the schema changed. After this, run db:generate + db:migrate (production) ' +
+        'or db:push (development) to apply changes to the database.',
+      inputSchema: {
+        name: z
+          .string()
+          .optional()
+          .describe('Plugin name (e.g. "crm"). Omit to migrate all installed plugins.'),
+      },
+    },
+    ({ name }) => {
+      const root = getRoot();
+
+      const pluginsDir = resolve(root, 'src/plugins');
+      const pluginNames: string[] = name
+        ? [name]
+        : existsSync(pluginsDir)
+          ? readdirSync(pluginsDir)
+              .filter((f) => f.endsWith('.ts') && f !== 'index.ts')
+              .map((f) => f.replace('.ts', ''))
+          : [];
+
+      if (pluginNames.length === 0) {
+        return { content: [{ type: 'text' as const, text: 'No installed plugins found.' }] };
+      }
+
+      const results: { plugin: string; updated: boolean; error?: string }[] = [];
+
+      for (const pName of pluginNames) {
+        const res = resolveManifest(root, pName);
+        if (!res) {
+          results.push({ plugin: pName, updated: false, error: 'manifest not found' });
+          continue;
+        }
+
+        const { manifest, pluginDir } = res;
+
+        if (!manifest.install.schemaTables) {
+          results.push({ plugin: pName, updated: false });
+          continue;
+        }
+
+        const updated = patchSchemaTables(
+          root,
+          manifest.name,
+          pluginDir,
+          manifest.install.schemaTables,
+          'update',
+        );
+
+        const imports = manifest.install.schemaImports;
+        if (updated && imports && imports.length > 0) {
+          patchSchemaImports(root, manifest.name, imports, 'add');
+        }
+
+        results.push({ plugin: pName, updated });
+      }
+
+      const anyUpdated = results.some((r) => r.updated);
+      const output = {
+        results,
+        schemaChanged: anyUpdated,
+        nextSteps: anyUpdated
+          ? [
+              'Run: pnpm db:generate (create migration file)',
+              'Run: pnpm db:migrate (apply migration)',
+              'Or for development: pnpm db:push',
+            ]
+          : [],
+      };
+
+      return { content: [{ type: 'text' as const, text: JSON.stringify(output, null, 2) }] };
+    },
+  );
 }

src/utils/patchers.test.ts

@@ -160,6 +160,55 @@ describe('patchSchemaTables', () => {
     expect(written).not.toContain('widget');
     expect(written).toContain('user');
   });
+
+  it('replaces marked block with new content on update', () => {
+    const schema = `export const user = sqliteTable('user', {});\n\n// --- plugin:test-plugin:start ---\nexport const widget = sqliteTable('widget', {\n  id: text('id'),\n});\n// --- plugin:test-plugin:end ---\n`;
+    const newTables = `export const widget = sqliteTable('widget', {\n  id: text('id'),\n  name: text('name'),\n});\n`;
+
+    mockedExists.mockReturnValue(true);
+    mockedRead.mockImplementation((p) => {
+      const path = p as string;
+      if (path.includes('schema.ts')) return schema;
+      return newTables;
+    });
+
+    const result = patchSchemaTables(ROOT, 'test-plugin', '/plugins/test', 'tables.ts', 'update');
+
+    expect(result).toBe(true);
+    const written = mockedWrite.mock.calls[0][1] as string;
+    expect(written).toContain("name: text('name')");
+    expect(written).toContain('// --- plugin:test-plugin:start ---');
+    expect(written).toContain('// --- plugin:test-plugin:end ---');
+  });
+
+  it('returns false on update when schema is unchanged', () => {
+    const tables = `export const widget = sqliteTable('widget', {});`;
+    const schema = `export const user = sqliteTable('user', {});\n\n// --- plugin:test-plugin:start ---\n${tables}\n// --- plugin:test-plugin:end ---\n`;
+
+    mockedExists.mockReturnValue(true);
+    mockedRead.mockImplementation((p) => {
+      const path = p as string;
+      if (path.includes('schema.ts')) return schema;
+      return tables + '\n';
+    });
+
+    const result = patchSchemaTables(ROOT, 'test-plugin', '/plugins/test', 'tables.ts', 'update');
+
+    expect(result).toBe(false);
+    expect(mockedWrite).not.toHaveBeenCalled();
+  });
+
+  it('returns false on update when plugin is not installed', () => {
+    const schema = `export const user = sqliteTable('user', {});`;
+
+    mockedExists.mockReturnValue(true);
+    mockedRead.mockReturnValue(schema);
+
+    const result = patchSchemaTables(ROOT, 'test-plugin', '/plugins/test', 'tables.ts', 'update');
+
+    expect(result).toBe(false);
+    expect(mockedWrite).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------

src/utils/patchers.ts

@@ -78,39 +78,61 @@ export function patchSchemaImports(
   writeFileSync(schemaPath, content, 'utf-8');
 }
 
+function extractMarkedBlock(content: string, name: string): string | null {
+  const start = MARKER_START(name);
+  const end = MARKER_END(name);
+  const startIdx = content.indexOf(start);
+  const endIdx = content.indexOf(end);
+  if (startIdx === -1 || endIdx === -1) return null;
+  return content.slice(startIdx + start.length, endIdx);
+}
+
+function readPluginTables(pluginDir: string, tablesFile: string): string | null {
+  const tablesPath = resolve(pluginDir, tablesFile);
+  if (!existsSync(tablesPath)) return null;
+
+  let tables = readFileSync(tablesPath, 'utf-8');
+  // Strip import lines — host schema already has them
+  tables = tables.replace(/^import\s+.*;\s*\n/gm, '');
+  // Strip type/interface declarations
+  tables = tables.replace(/^export\s+type\s+.*;\s*\n/gm, '');
+  tables = tables.replace(/^(?:export\s+)?interface\s+\w+\s*\{[\s\S]*?\}\s*\n/gm, '');
+  return tables.trim();
+}
+
 export function patchSchemaTables(
   projectRoot: string,
   pluginName: string,
   pluginDir: string,
   tablesFile: string,
-  action: 'add' | 'remove',
-): void {
+  action: 'add' | 'remove' | 'update',
+): boolean {
   const schemaPath = resolve(projectRoot, 'src/lib/db/schema.ts');
-  if (!existsSync(schemaPath)) return;
+  if (!existsSync(schemaPath)) return false;
   let content = readFileSync(schemaPath, 'utf-8');
 
   if (action === 'remove') {
     content = removeMarkedBlock(content, pluginName);
     writeFileSync(schemaPath, content, 'utf-8');
-    return;
+    return true;
   }
 
-  if (hasMarker(content, pluginName)) return;
+  if (action === 'add' && hasMarker(content, pluginName)) return false;
 
-  const tablesPath = resolve(pluginDir, tablesFile);
-  if (!existsSync(tablesPath)) return;
+  const tables = readPluginTables(pluginDir, tablesFile);
+  if (!tables) return false;
 
-  let tables = readFileSync(tablesPath, 'utf-8');
-
-  // Strip import lines — host schema already has them
-  tables = tables.replace(/^import\s+.*;\s*\n/gm, '');
-  // Strip type exports
-  tables = tables.replace(/^export\s+type\s+.*;\s*\n/gm, '');
-  tables = tables.trim();
+  if (action === 'update') {
+    if (!hasMarker(content, pluginName)) return false;
+    const oldBlock = extractMarkedBlock(content, pluginName);
+    if (oldBlock !== null && oldBlock.trim() === tables) return false;
+    content = removeMarkedBlock(content, pluginName);
+  }
 
   const block = `\n${MARKER_START(pluginName)}\n${tables}\n${MARKER_END(pluginName)}\n`;
   content = content.trimEnd() + '\n' + block;
   writeFileSync(schemaPath, content, 'utf-8');
+  return true;
 }
 
 // ---------------------------------------------------------------------------