@codeyam/codeyam-cli 0.1.0-staging.036391e → 0.1.0-staging.039fa00

package/analyzer-template/packages/analyze/src/lib/files/scenarios/mergeInDependentDataStructure.ts

@@ -52,6 +52,7 @@ const PRIMITIVE_TYPES = new Set([
 
 // Check if a type string represents a primitive type
 // Handles union types like "string | undefined" or "number | null"
+// Also handles string literal unions like "'suggestion' | 'warning' | 'tip'"
 function isPrimitiveType(typeStr: string): boolean {
   if (PRIMITIVE_TYPES.has(typeStr)) {
     return true;
@@ -59,9 +60,15 @@ function isPrimitiveType(typeStr: string): boolean {
   // Check union types - if ALL parts of the union are primitives, it's primitive
   // e.g., "string | undefined" -> ["string", "undefined"] -> both are primitive -> true
   // e.g., "object | null" -> ["object", "null"] -> object is not primitive -> false
+  // e.g., "'suggestion' | 'warning'" -> string literal union -> true
   if (typeStr.includes('|')) {
     const parts = typeStr.split('|').map((p) => p.trim());
-    return parts.every((part) => PRIMITIVE_TYPES.has(part));
+    return parts.every(
+      (part) =>
+        PRIMITIVE_TYPES.has(part) ||
+        // String literal values like 'suggestion', 'warning' are primitives
+        (part.startsWith("'") && part.endsWith("'")),
+    );
   }
   return false;
 }
@@ -110,9 +117,21 @@ function pathPartMatches(pathPart: string, schemaPathPart: string): boolean {
 function bestValueFromOptions(options: Array<string | undefined>) {
   options = options.filter(Boolean) as string[];
 
-  const known = options.find((o) => !o.includes('unknown'));
-  if (known) {
-    return known;
+  const known = options.filter((o) => !o.includes('unknown'));
+  if (known.length > 0) {
+    // Among known values, prefer string literal unions over bare primitives.
+    // e.g., "'draft' | 'inProgress' | 'paused' | 'completed'" is more specific than "string".
+    // This handles cases where a dependency schema has a bare type like "string" but the
+    // child entity's analysis has the actual literal union from TypeScript type resolution.
+    if (known.length > 1 && known.some((o) => PRIMITIVE_TYPES.has(o))) {
+      const literalUnion = known.find(
+        (o) => !PRIMITIVE_TYPES.has(o) && o.includes("'"),
+      );
+      if (literalUnion) {
+        return literalUnion;
+      }
+    }
+    return known[0];
   }
 
   const notUnknown = options.find((o) => o !== 'unknown');
@@ -210,6 +229,23 @@ export default function mergeInDependentDataStructure({
     equivalentPostfixes: Record<string, string>;
   }[] = [];
 
+  // O(1) index for findOrCreateEquivalentSchemaPathsEntry.
+  // Maps "(rootPath)::(normalizedFuncName)" → the entry containing that root.
+  // This replaces the O(E) linear search that was causing O(E²) gather performance.
+  const espIndex = new Map<string, (typeof equivalentSchemaPaths)[0]>();
+  const espIndexKey = (path: string, functionName: string | undefined) => {
+    const normalized = cleanFunctionName(functionName);
+    const funcKey =
+      normalized === rootScopeName ? '__self__' : normalized || '__self__';
+    return `${path}::${funcKey}`;
+  };
+  const updateEspIndex = (entry: (typeof equivalentSchemaPaths)[0]) => {
+    for (const root of entry.equivalentRoots) {
+      const funcName = root.function?.name ?? rootScopeName;
+      espIndex.set(espIndexKey(root.schemaRootPath, funcName), entry);
+    }
+  };
+
   // Pre-build a lookup map from cleaned function name to dependency for O(1) lookups.
   // This avoids O(n) linear search in findRelevantDependency which was causing O(n²) performance.
   const dependencyByCleanedName = new Map<
@@ -324,6 +360,54 @@ export default function mergeInDependentDataStructure({
   ) => {
     if (!sourceAndUsageEquivalencies) return;
 
+    // Pre-computed normalized schema index cache.
+    // Avoids repeated splitOutsideParenthesesAndArrays calls and function-name
+    // normalization for the same schema paths across multiple equivalency iterations.
+    // The normalization depends on `functionName` (constant per gatherAllEquivalentSchemaPaths call),
+    // so this cache is scoped to this call.
+    type NormalizedEntry = { path: string; parts: string[] };
+    const normalizedSchemaCache = new Map<
+      object,
+      {
+        byFirstPart: Map<string, NormalizedEntry[]>;
+      }
+    >();
+    const getSchemaIndex = (
+      schema: Record<string, string> | undefined,
+    ): { byFirstPart: Map<string, NormalizedEntry[]> } => {
+      if (!schema) return { byFirstPart: new Map() };
+      const cached = normalizedSchemaCache.get(schema);
+      if (cached) return cached;
+      const byFirstPart = new Map<string, NormalizedEntry[]>();
+      for (const path in schema) {
+        let parts = splitOutsideParenthesesAndArrays(path);
+        if (parts[0].startsWith(functionName)) {
+          const baseName = cleanFunctionName(parts[0]);
+          if (!functionsWithMultipleTypeParams.has(baseName)) {
+            parts =
+              parts[1] === 'functionCallReturnValue'
+                ? ['returnValue', ...parts.slice(2)]
+                : parts.slice(1);
+          }
+        }
+        const entry: NormalizedEntry = { path, parts };
+        // Index by the base of the first part (before any function call args)
+        const firstPart = parts[0] ?? '';
+        const parenIdx = firstPart.indexOf('(');
+        const firstPartBase =
+          parenIdx >= 0 ? firstPart.slice(0, parenIdx) : firstPart;
+        let bucket = byFirstPart.get(firstPartBase);
+        if (!bucket) {
+          bucket = [];
+          byFirstPart.set(firstPartBase, bucket);
+        }
+        bucket.push(entry);
+      }
+      const result = { byFirstPart };
+      normalizedSchemaCache.set(schema, result);
+      return result;
+    };
+
     const findOrCreateEquivalentSchemaPathsEntry = (
       allPaths: { path: string; functionName?: string }[],
     ) => {
@@ -354,62 +438,52 @@ export default function mergeInDependentDataStructure({
         }
       }
 
+      // Use espIndex Map for O(1) lookup instead of O(E) linear search.
+      // Falls back to linear search only when Map hit has a signature index conflict.
       for (const pathInfo of allPaths) {
-        if (!equivalentSchemaPathsEntry) {
-          equivalentSchemaPathsEntry = equivalentSchemaPaths.find((esp) => {
-            // First check: does this entry have a matching root?
-            const hasMatchingRoot = esp.equivalentRoots.some(
-              (er) =>
-                er.schemaRootPath === pathInfo.path &&
-                (er.function?.name ===
-                  cleanFunctionName(pathInfo.functionName) ||
-                  (!er.function &&
-                    cleanFunctionName(pathInfo.functionName) ===
-                      rootScopeName)),
-            );
-            if (!hasMatchingRoot) return false;
-
-            // Second check: would adding our new roots create a signature index conflict?
-            // An entry should NOT contain roots with different signature indices from the same function.
-            if (newRootSignatureIndices.size > 0) {
-              // Get all signature indices in the existing entry (grouped by function)
-              const existingIndicesByFunction = new Map<string, Set<number>>();
-              for (const er of esp.equivalentRoots) {
-                const funcKey = er.function
-                  ? `${er.function.name}::${er.function.filePath}`
-                  : '__self__';
-                const idx = extractSignatureIndex(er.schemaRootPath);
-                if (idx !== undefined) {
-                  if (!existingIndicesByFunction.has(funcKey)) {
-                    existingIndicesByFunction.set(funcKey, new Set());
-                  }
-                  existingIndicesByFunction.get(funcKey)!.add(idx);
-                }
+        if (equivalentSchemaPathsEntry) break;
+        const candidate = espIndex.get(
+          espIndexKey(pathInfo.path, pathInfo.functionName),
+        );
+        if (!candidate) continue;
+
+        // Verify no signature index conflict with the candidate entry
+        if (newRootSignatureIndices.size > 0) {
+          const existingIndicesByFunction = new Map<string, Set<number>>();
+          for (const er of candidate.equivalentRoots) {
+            const funcKey = er.function
+              ? `${er.function.name}::${er.function.filePath}`
+              : '__self__';
+            const idx = extractSignatureIndex(er.schemaRootPath);
+            if (idx !== undefined) {
+              if (!existingIndicesByFunction.has(funcKey)) {
+                existingIndicesByFunction.set(funcKey, new Set());
               }
+              existingIndicesByFunction.get(funcKey)!.add(idx);
+            }
+          }
 
-              // Check if adding our new roots would create a conflict
-              for (const newRoot of equivalentRoots) {
-                const funcKey = newRoot.function
-                  ? `${newRoot.function.name}::${newRoot.function.filePath}`
-                  : '__self__';
-                const newIdx = extractSignatureIndex(newRoot.schemaRootPath);
-                if (newIdx !== undefined) {
-                  const existingIndices =
-                    existingIndicesByFunction.get(funcKey);
-                  if (existingIndices && existingIndices.size > 0) {
-                    // If this function already has signature indices, check for conflict
-                    if (!existingIndices.has(newIdx)) {
-                      // Conflict: entry has indices like [1] but we want to add [2]
-                      return false;
-                    }
-                  }
+          let hasConflict = false;
+          for (const newRoot of equivalentRoots) {
+            const funcKey = newRoot.function
+              ? `${newRoot.function.name}::${newRoot.function.filePath}`
+              : '__self__';
+            const newIdx = extractSignatureIndex(newRoot.schemaRootPath);
+            if (newIdx !== undefined) {
+              const existingIndices = existingIndicesByFunction.get(funcKey);
+              if (existingIndices && existingIndices.size > 0) {
+                if (!existingIndices.has(newIdx)) {
+                  hasConflict = true;
+                  break;
                 }
               }
             }
+          }
 
-            return true;
-          });
+          if (hasConflict) continue;
         }
+
+        equivalentSchemaPathsEntry = candidate;
       }
 
       if (!equivalentSchemaPathsEntry) {
@@ -467,6 +541,9 @@ export default function mergeInDependentDataStructure({
           return true;
         });
 
+      // Keep the espIndex in sync after adding/deduplicating roots
+      updateEspIndex(equivalentSchemaPathsEntry);
+
       return equivalentSchemaPathsEntry;
     };
 
@@ -535,6 +612,8 @@ export default function mergeInDependentDataStructure({
         );
 
         const derivedBasePaths: { path: string; functionName?: string }[] = [];
+        const allPathSet = new Set(allPaths.map((p) => p.path));
+        const derivedBasePathSet = new Set<string>();
 
         // For each child path, find its equivalent parent path and derive bases
         for (const childPathInfo of childPaths) {
@@ -611,26 +690,28 @@ export default function mergeInDependentDataStructure({
                   !childHasArrayIterator &&
                   !childBaseIsGenericSignature
                 ) {
-                  // Add child base if not already present
-                  const childBaseExists =
-                    allPaths.some((p) => p.path === childBase) ||
-                    derivedBasePaths.some((p) => p.path === childBase);
-                  if (!childBaseExists) {
+                  // Add child base if not already present (O(1) Set lookup)
+                  if (
+                    !allPathSet.has(childBase) &&
+                    !derivedBasePathSet.has(childBase)
+                  ) {
                     derivedBasePaths.push({
                       path: childBase,
                       functionName: childPathInfo.functionName,
                     });
+                    derivedBasePathSet.add(childBase);
                   }
 
-                  // Add parent base if not already present
-                  const parentBaseExists =
-                    allPaths.some((p) => p.path === parentBase) ||
-                    derivedBasePaths.some((p) => p.path === parentBase);
-                  if (!parentBaseExists) {
+                  // Add parent base if not already present (O(1) Set lookup)
+                  if (
+                    !allPathSet.has(parentBase) &&
+                    !derivedBasePathSet.has(parentBase)
+                  ) {
                     derivedBasePaths.push({
                       path: parentBase,
                       functionName: parentPathInfo.functionName,
                     });
+                    derivedBasePathSet.add(parentBase);
                   }
                 }
               }
@@ -708,21 +789,20 @@ export default function mergeInDependentDataStructure({
           }
 
           for (const schema of schemas) {
-            for (const schemaPath in schema) {
-              let schemaPathParts =
-                splitOutsideParenthesesAndArrays(schemaPath);
-
-              if (schemaPathParts[0].startsWith(functionName)) {
-                // Only normalize if the function doesn't have multiple different type parameters
-                const baseName = cleanFunctionName(schemaPathParts[0]);
-                if (!functionsWithMultipleTypeParams.has(baseName)) {
-                  schemaPathParts =
-                    schemaPathParts[1] === 'functionCallReturnValue'
-                      ? ['returnValue', ...schemaPathParts.slice(2)]
-                      : schemaPathParts.slice(1);
-                }
-              }
-
+            // Use pre-computed index to only iterate schema entries whose
+            // normalized first part matches pathParts[0], instead of all entries.
+            const schemaIndex = getSchemaIndex(schema);
+            const lookupPart = pathParts[0] ?? '';
+            const lookupParenIdx = lookupPart.indexOf('(');
+            const lookupBase =
+              lookupParenIdx >= 0
+                ? lookupPart.slice(0, lookupParenIdx)
+                : lookupPart;
+            const candidates = schemaIndex.byFirstPart.get(lookupBase) || [];
+            for (const {
+              path: schemaPath,
+              parts: schemaPathParts,
+            } of candidates) {
               if (schemaPathParts.length < pathParts.length) continue;
 
               // Check if all path parts match (allowing function call variants)
@@ -850,10 +930,17 @@ export default function mergeInDependentDataStructure({
         const entry = findOrCreateEquivalentSchemaPathsEntry([
           { path: translatedBasePath, functionName: functionName },
         ]);
-        entry.equivalentRoots.push({
+        const newRoot = {
           schemaRootPath: translatedBasePath,
           function: findRelevantDependency(functionName),
-        });
+        };
+        entry.equivalentRoots.push(newRoot);
+        // Update index for the newly added root
+        const newRootFuncName = newRoot.function?.name ?? rootScopeName;
+        espIndex.set(
+          espIndexKey(newRoot.schemaRootPath, newRootFuncName),
+          entry,
+        );
 
         const basePathParts = splitOutsideParenthesesAndArrays(basePath);
         for (const schemaPath in dataStructure.returnValueSchema) {
@@ -1113,6 +1200,10 @@ export default function mergeInDependentDataStructure({
 
   equivalentSchemaPaths = mergeAllEquivalentSchemaPaths();
 
+  // Collect schemas that need cleaning — batch the calls for the end instead of
+  // calling cleanSchema inside the inner root loop (which was O(roots * schemaSize)).
+  const schemasToClean = new Set<{ [key: string]: string }>();
+
   for (const esp of equivalentSchemaPaths) {
     // Pre-compute which postfixes have children to avoid O(n²) lookups in the inner loop.
     // A postfix "has children" if there are other postfixes that extend it.
@@ -1290,10 +1381,15 @@ export default function mergeInDependentDataStructure({
         schema[newSchemaPath] = postfixValue;
       }
 
-      cleanSchema(schema, { stage: 'afterMergePostfix' });
+      schemasToClean.add(schema);
     }
   }
 
+  // Batch-clean all modified schemas once (instead of once per root per ESP entry)
+  for (const schema of schemasToClean) {
+    cleanSchema(schema, { stage: 'afterMergePostfix' });
+  }
+
   // Propagate equivalency-derived attributes to generic function call variants.
   // When attributes are traced via equivalencies (e.g., fileComparisons from buildDataMap.signature[2]),
   // they get written to non-generic paths (returnValue.data.x or funcName().functionCallReturnValue.data.x).

package/analyzer-template/packages/aws/package.json

@@ -11,15 +11,15 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@aws-sdk/client-codebuild": "^3.948.0",
-    "@aws-sdk/client-cloudwatch-logs": "^3.980.0",
-    "@aws-sdk/client-dynamodb": "^3.956.0",
-    "@aws-sdk/client-ecr": "^3.948.0",
-    "@aws-sdk/client-ecs": "^3.956.0",
-    "@aws-sdk/client-s3": "^3.940.0",
-    "@aws-sdk/client-sqs": "^3.956.0",
-    "@aws-sdk/lib-storage": "^3.975.0",
-    "@aws-sdk/s3-request-presigner": "^3.940.0",
-    "@aws-sdk/util-dynamodb": "^3.971.0"
+    "@aws-sdk/client-codebuild": "^3.1000.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.990.0",
+    "@aws-sdk/client-dynamodb": "^3.990.0",
+    "@aws-sdk/client-ecr": "^3.990.0",
+    "@aws-sdk/client-ecs": "^3.990.0",
+    "@aws-sdk/client-s3": "^3.990.0",
+    "@aws-sdk/client-sqs": "^3.990.0",
+    "@aws-sdk/lib-storage": "^3.990.0",
+    "@aws-sdk/s3-request-presigner": "^3.990.0",
+    "@aws-sdk/util-dynamodb": "^3.990.0"
   }
 }

package/analyzer-template/packages/database/index.ts

@@ -75,6 +75,7 @@ export * from './src/lib/kysely/tables/backgroundJobsTable';
 export * from './src/lib/kysely/tables/branchesTable';
 export * from './src/lib/kysely/tables/commitBranchesTable';
 export * from './src/lib/kysely/tables/commitsTable';
+export * from './src/lib/kysely/tables/editorScenariosTable';
 export * from './src/lib/kysely/tables/entitiesTable';
 export * from './src/lib/kysely/tables/entityBranchesTable';
 export * from './src/lib/kysely/tables/entityStatementsTable';

package/analyzer-template/packages/database/package.json

@@ -13,10 +13,10 @@
   "license": "ISC",
   "dependencies": {
     "@supabase/supabase-js": "2.88.0",
-    "better-sqlite3": "^12.4.1",
+    "better-sqlite3": "^12.6.2",
     "fetch-retry": "^6.0.0",
     "kysely": "^0.28.11",
-    "pg": "^8.16.3"
+    "pg": "^8.19.0"
   },
   "jest": {
     "preset": "ts-jest",
@@ -25,7 +25,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/jest": "^30.0.0",
-    "@types/pg": "^8.15.5",
+    "@types/pg": "^8.18.0",
     "@types/ws": "^8.18.1"
   }
 }

package/analyzer-template/packages/database/src/lib/analysisBranchToDb.ts

@@ -1,6 +1,6 @@
 import { AnalysisBranch } from '~codeyam/types';
 import { DbAnalysisBranch } from './kysely/tableRelations';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 import { AnalysisBranchesTable } from './kysely/tables/analysisBranchesTable';
 import { type Insertable } from 'kysely';
 

package/analyzer-template/packages/database/src/lib/analysisToDb.ts

@@ -1,7 +1,7 @@
 import { Analysis } from '~codeyam/types';
 import { type Insertable } from 'kysely';
 import { AnalysesTable } from './kysely/tables/analysesTable';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 
 export default function analysisToDb(
   analysis: Analysis,

package/analyzer-template/packages/database/src/lib/branchToDb.ts

@@ -1,7 +1,7 @@
 import { Branch } from '~codeyam/types';
 import { type Insertable } from 'kysely';
 import { BranchesTable } from './kysely/tables/branchesTable';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 
 export default function branchToDb(branch: Branch): Insertable<BranchesTable> {
   const { id, projectId, activeAt, contentChangedAt, metadata, ...remaining } =

package/analyzer-template/packages/database/src/lib/commitBranchToDb.ts

@@ -1,6 +1,6 @@
 import { CommitBranch } from '~codeyam/types';
 import { type Insertable } from 'kysely';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 import { CommitBranchesTable } from './kysely/tables/commitBranchesTable';
 
 export default function commitBranchToDb(

package/analyzer-template/packages/database/src/lib/commitToDb.ts

@@ -1,7 +1,7 @@
 import { Commit } from '~codeyam/types';
 import { CommitsTable } from './kysely/tables/commitsTable';
 import { type Insertable } from 'kysely';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 
 export default function commitToDb(
   commit: Commit,

package/analyzer-template/packages/database/src/lib/fileToDb.ts

@@ -1,7 +1,7 @@
 import { File } from '~codeyam/types';
 import { type Insertable } from 'kysely';
 import { FilesTable } from './kysely/tables/filesTable';
-import { randomUUID } from 'crypto';
+const randomUUID = () => crypto.randomUUID();
 
 export default function fileToDb(file: File): Insertable<FilesTable> {
   return {

package/analyzer-template/packages/database/src/lib/kysely/db.ts

@@ -62,6 +62,10 @@ import {
   createScenarioCommentsTable,
   ScenarioCommentsTable,
 } from './tables/scenarioCommentsTable';
+import {
+  createEditorScenariosTable,
+  EditorScenariosTable,
+} from './tables/editorScenariosTable';
 import { createScenariosTable, ScenariosTable } from './tables/scenariosTable';
 import {
   createStatementsTable,
@@ -106,6 +110,7 @@ const databaseSchema = {
   commit_branches: schemaField<CommitBranchesTable>(),
   commits: schemaField<CommitsTable>(),
   debug_reports: schemaField<DebugBundlesTable>(),
+  editor_scenarios: schemaField<EditorScenariosTable>(),
   entities: schemaField<EntitiesTable>(),
   entity_branches: schemaField<EntityBranchesTable>(),
   entity_statements: schemaField<EntityStatementsTable>(),
@@ -210,6 +215,7 @@ export function getSqliteDatabase(sqlitePath?: string) {
     fileMustExist: false,
   });
   sqlite.pragma('journal_mode = WAL');
+  sqlite.pragma('busy_timeout = 5000');
   sqlite.pragma('synchronous = FULL');
 
   // Verify the database has the expected schema
@@ -305,6 +311,7 @@ export async function getDatabaseForTesting(
     // Standard SQLite testing path
     const sqlite = new SQLiteDatabase(dbPath);
     sqlite.pragma('journal_mode = WAL');
+    sqlite.pragma('busy_timeout = 5000');
     sqlite.pragma('synchronous = FULL');
     const kyselyDb = new Kysely<Database>({
       dialect: new SqliteDialect({ database: sqlite }),
@@ -390,6 +397,7 @@ export async function createSqliteSchema(db: Kysely<Database>): Promise<void> {
   await createCommitBranchesTable(db);
   await createCommitsTable(db);
   await createDebugBundlesTable(db);
+  await createEditorScenariosTable(db);
   await createEntitiesTable(db);
   await createEntityBranchesTable(db);
   await createEntityStatementsTable(db);

package/analyzer-template/packages/database/src/lib/kysely/tables/debugReportsTable.ts

@@ -6,7 +6,7 @@ import { schemaField, defaultNow } from '../schemaHelpers';
 /**
  * Metadata for a debug bundle upload.
  * Note: "bundle" refers to the tarball upload (base + delta).
- * The markdown "debug report" from /codeyam:diagnose is stored in feedback.debugReport.
+ * The markdown "debug report" from /codeyam-diagnose is stored in feedback.debugReport.
  */
 interface DebugBundleMetadata {
   timestamp: string;

package/analyzer-template/packages/database/src/lib/kysely/tables/editorScenariosTable.ts

@@ -0,0 +1,62 @@
+import { Kysely, ColumnDefinitionBuilder } from 'kysely';
+import type { Generated } from 'kysely';
+
+import { schemaField, defaultNow } from '../schemaHelpers';
+
+const editorScenariosSchema = {
+  id: schemaField<Generated<string>>(),
+  project_id: schemaField<string>(),
+  name: schemaField<string>(),
+  description: schemaField<string | null>(),
+  component_name: schemaField<string | null>(),
+  component_path: schemaField<string | null>(),
+  screenshot_path: schemaField<string | null>(),
+  created_at: schemaField<Generated<string>>(),
+  updated_at: schemaField<Generated<string>>(),
+} as const;
+
+export type EditorScenariosTable = {
+  [K in keyof typeof editorScenariosSchema]: (typeof editorScenariosSchema)[K];
+};
+
+export const EditorScenariosTableColumns = Object.keys(
+  editorScenariosSchema,
+) as (keyof EditorScenariosTable)[];
+
+export async function createEditorScenariosTable(
+  db: Kysely<any>,
+): Promise<void> {
+  await db.schema
+    .createTable('editor_scenarios')
+    .addColumn('id', 'uuid', (col: ColumnDefinitionBuilder) => col.primaryKey())
+    .addColumn('project_id', 'uuid', (col: ColumnDefinitionBuilder) =>
+      col.notNull(),
+    )
+    .addColumn('name', 'varchar', (col: ColumnDefinitionBuilder) =>
+      col.notNull(),
+    )
+    .addColumn('description', 'text')
+    .addColumn('component_name', 'varchar')
+    .addColumn('component_path', 'varchar')
+    .addColumn('screenshot_path', 'varchar')
+    .addColumn('created_at', 'datetime', defaultNow(true))
+    .addColumn('updated_at', 'datetime', defaultNow(true))
+    .ifNotExists()
+    .execute();
+
+  // Add columns to existing tables (ALTER TABLE has no IF NOT EXISTS in SQLite)
+  for (const col of [
+    'component_name',
+    'component_path',
+    'screenshot_path',
+  ] as const) {
+    try {
+      await db.schema
+        .alterTable('editor_scenarios')
+        .addColumn(col, 'varchar')
+        .execute();
+    } catch {
+      // Column already exists — expected for fresh databases
+    }
+  }
+}