Feat/schema pipeline/plan d2b metadata row sql

packages/nextly/src/cli/commands/migrate-create.ts

@@ -62,6 +62,11 @@ import { PromptCancelledError } from "../../domains/schema/migrate-create/prompt
 import type { SupportedDialect } from "../../domains/schema/services/schema-generator";
 import { loadUiSchema } from "../../domains/schema/ui-schema/loader";
 import { mergeUiEntities } from "../../domains/schema/ui-schema/merge";
+import {
+  buildCollectionMetadataUpsert,
+  buildComponentMetadataUpsert,
+  buildSingleMetadataUpsert,
+} from "../../domains/schema/ui-schema/metadata-sql";
 import { createContext, type CommandContext } from "../program";
 import { getDialectDisplayName, validateDatabaseEnv } from "../utils/adapter";
 import { loadConfig, type LoadConfigResult } from "../utils/config-loader";
@@ -247,6 +252,34 @@ export async function runMigrateCreate(
   }
   const { collections, singles, components } = merged;
 
+  // §4.12.7: per-dialect metadata-row upserts for UI-built entities that
+  // survived the merge (code-first wins → shadowed UI slugs are skipped).
+  const dropped = new Set(merged.droppedUiSlugs);
+  const tn = (slug: string, prefix: "dc_" | "single_" | "comp_") =>
+    `${prefix}${slug.replace(/-/g, "_")}`;
+  const metadataUpserts: { tableName: string; sql: string }[] = [];
+  for (const c of manifest.collections) {
+    if (dropped.has(c.slug)) continue;
+    metadataUpserts.push({
+      tableName: tn(c.slug, "dc_"),
+      sql: buildCollectionMetadataUpsert(c, dialect),
+    });
+  }
+  for (const s of manifest.singles) {
+    if (dropped.has(s.slug)) continue;
+    metadataUpserts.push({
+      tableName: tn(s.slug, "single_"),
+      sql: buildSingleMetadataUpsert(s, dialect),
+    });
+  }
+  for (const cp of manifest.components) {
+    if (dropped.has(cp.slug)) continue;
+    metadataUpserts.push({
+      tableName: tn(cp.slug, "comp_"),
+      sql: buildComponentMetadataUpsert(cp, dialect),
+    });
+  }
+
   if (
     collections.length === 0 &&
     singles.length === 0 &&
@@ -269,6 +302,7 @@ export async function runMigrateCreate(
       collections,
       singles,
       components,
+      metadataUpserts,
       nonInteractive,
       autoAcceptRenames: options.acceptRenames === true,
     });

packages/nextly/src/domains/schema/migrate-create/__tests__/generate.test.ts

@@ -74,6 +74,39 @@ describe("generateMigration", () => {
     expect(sql).toContain("-- Generated at: 2026-04-29T15:45:00.123Z");
   });
 
+  it("appends a metadata upsert only when its table is touched (§4.12.7)", async () => {
+    const result = await generateMigration({
+      name: "create_posts",
+      dialect: "postgresql",
+      migrationsDir,
+      collections: [POSTS_V1],
+      singles: [],
+      components: [],
+      nonInteractive: true,
+      now: NOW,
+      metadataUpserts: [
+        {
+          tableName: "dc_posts",
+          sql: 'INSERT INTO "dynamic_collections" /*posts*/',
+        },
+        {
+          tableName: "dc_unrelated",
+          sql: 'INSERT INTO "dynamic_collections" /*nope*/',
+        },
+      ],
+    });
+    expect(result).not.toBeNull();
+    const sql = await readFile(result!.sqlPath, "utf-8");
+    // dc_posts is created → its upsert is appended.
+    expect(sql).toContain("/*posts*/");
+    // dc_unrelated has no operation → its upsert is omitted.
+    expect(sql).not.toContain("/*nope*/");
+    // The upsert follows the CREATE TABLE DDL.
+    expect(sql.indexOf("/*posts*/")).toBeGreaterThan(
+      sql.indexOf('CREATE TABLE "dc_posts"')
+    );
+  });
+
   it("returns null when config matches latest snapshot (no changes)", async () => {
     // Seed a snapshot matching POSTS_V1.
     const desired = buildDesiredSnapshotFromConfigForTest(

packages/nextly/src/domains/schema/migrate-create/generate.ts

@@ -37,11 +37,7 @@ import type { RenameCandidate } from "../pipeline/pushschema-pipeline-interfaces
 import { RegexRenameDetector } from "../pipeline/rename-detector";
 import { generateSQL } from "../pipeline/sql-templates/index";
 
-import {
-  formatMigrationFile,
-  formatTimestamp,
-  slugify,
-} from "./format-file";
+import { formatMigrationFile, formatTimestamp, slugify } from "./format-file";
 import { promptRenames, type RenameDecision } from "./prompt-renames";
 import {
   EMPTY_SNAPSHOT,
@@ -90,6 +86,11 @@ export interface GenerateArgs {
   collections: MinimalConfigEntity[];
   singles: MinimalConfigEntity[];
   components: MinimalConfigEntity[];
+  /**
+   * UI-built metadata-row upserts (spec §4.12.7), keyed by data-table name.
+   * Each is appended to the generated SQL when an operation touches its table.
+   */
+  metadataUpserts?: { tableName: string; sql: string }[];
   /** Skip interactive prompts (non-TTY / CI). */
   nonInteractive?: boolean;
   /** Only meaningful with nonInteractive=true. Default = decline. */
@@ -110,6 +111,18 @@ export interface GenerateResult {
   renamesAccepted: number;
 }
 
+/** The table an operation acts on (for correlating metadata upserts). */
+function operationTableName(op: Operation): string {
+  switch (op.type) {
+    case "add_table":
+      return op.table.name;
+    case "rename_table":
+      return op.toName;
+    default:
+      return op.tableName;
+  }
+}
+
 /**
  * Run the migrate:create orchestration. Returns null if no operations
  * remain (config matches latest snapshot — exit code 2 in the CLI).
@@ -156,6 +169,14 @@ export async function generateMigration(
   // 7. Generate SQL per op.
   const sqlStatements = operations.map(op => generateSQL(op, args.dialect));
 
+  // 7b. Append UI metadata-row upserts for any touched UI-built table (§4.12.7).
+  if (args.metadataUpserts && args.metadataUpserts.length > 0) {
+    const touched = new Set(operations.map(operationTableName));
+    for (const m of args.metadataUpserts) {
+      if (touched.has(m.tableName)) sqlStatements.push(m.sql);
+    }
+  }
+
   // 8. Compose file content + write both files.
   const collectionSlugs = args.collections.map(c => c.slug).sort();
   const singleSlugs = args.singles.map(c => c.slug).sort();

packages/nextly/src/domains/schema/ui-schema/metadata-sql.test.ts

@@ -0,0 +1,112 @@
+/**
+ * @module domains/schema/ui-schema/metadata-sql.test
+ * @since v0.0.3-alpha (Plan D2b)
+ */
+import { describe, expect, it } from "vitest";
+
+import { uiSchemaManifest } from "../../../schemas/_zod/ui-schema";
+import { calculateSchemaHash } from "../services/schema-hash";
+
+import {
+  buildCollectionMetadataUpsert,
+  buildComponentMetadataUpsert,
+  buildSingleMetadataUpsert,
+} from "./metadata-sql";
+
+const manifest = uiSchemaManifest.parse({
+  collections: [
+    {
+      slug: "events",
+      labels: { singular: "Event", plural: "Events" },
+      admin: { useAsTitle: "title" },
+      fields: [
+        { name: "title", type: "text", required: true },
+        { name: "note", type: "text" },
+      ],
+    },
+    { slug: "no-labels", fields: [{ name: "x", type: "text" }] },
+  ],
+  singles: [{ slug: "home", fields: [{ name: "hero", type: "text" }] }],
+  components: [{ slug: "seo", fields: [{ name: "meta_title", type: "text" }] }],
+});
+
+const events = manifest.collections[0];
+const noLabels = manifest.collections[1];
+const home = manifest.singles[0];
+const seo = manifest.components[0];
+
+describe("buildCollectionMetadataUpsert", () => {
+  it("postgres: INSERT … ON CONFLICT (slug) DO UPDATE with ::jsonb casts", () => {
+    const sql = buildCollectionMetadataUpsert(events, "postgresql");
+    expect(sql).toContain('INSERT INTO "dynamic_collections"');
+    expect(sql).toContain('ON CONFLICT ("slug") DO UPDATE SET');
+    expect(sql).toContain("::jsonb");
+    expect(sql).toContain("'dc_events'");
+    expect(sql).toContain("'ui'");
+  });
+
+  it("mysql: INSERT … ON DUPLICATE KEY UPDATE with backtick idents", () => {
+    const sql = buildCollectionMetadataUpsert(events, "mysql");
+    expect(sql).toContain("INSERT INTO `dynamic_collections`");
+    expect(sql).toContain("ON DUPLICATE KEY UPDATE");
+    expect(sql).toContain("VALUES(`fields`)");
+  });
+
+  it("sqlite: ON CONFLICT(slug) and integer booleans", () => {
+    const sql = buildCollectionMetadataUpsert(events, "sqlite");
+    expect(sql).toContain('ON CONFLICT ("slug") DO UPDATE SET');
+    expect(sql).toMatch(/"status"/);
+  });
+
+  it("embeds the runtime schema hash for the fields", () => {
+    const sql = buildCollectionMetadataUpsert(events, "postgresql");
+    const hash = calculateSchemaHash(
+      events.fields as unknown as Parameters<typeof calculateSchemaHash>[0]
+    );
+    expect(sql).toContain(hash);
+  });
+
+  it("derives labels from the slug when omitted", () => {
+    const sql = buildCollectionMetadataUpsert(noLabels, "postgresql");
+    expect(sql).toContain('"labels"');
+    expect(sql).toContain("'dc_no_labels'");
+  });
+
+  it("is deterministic (same input → identical SQL)", () => {
+    expect(buildCollectionMetadataUpsert(events, "postgresql")).toBe(
+      buildCollectionMetadataUpsert(events, "postgresql")
+    );
+  });
+
+  it("escapes single quotes in values", () => {
+    const tricky = uiSchemaManifest.parse({
+      collections: [
+        {
+          slug: "quotes",
+          labels: { singular: "It's", plural: "It's" },
+          fields: [{ name: "x", type: "text" }],
+        },
+      ],
+    }).collections[0];
+    const sql = buildCollectionMetadataUpsert(tricky, "postgresql");
+    expect(sql).toContain("It''s");
+  });
+});
+
+describe("buildSingleMetadataUpsert", () => {
+  it("targets dynamic_singles with a singular label column", () => {
+    const sql = buildSingleMetadataUpsert(home, "postgresql");
+    expect(sql).toContain('INSERT INTO "dynamic_singles"');
+    expect(sql).toContain('"label"');
+    expect(sql).toContain("'single_home'");
+  });
+});
+
+describe("buildComponentMetadataUpsert", () => {
+  it("targets dynamic_components and omits status", () => {
+    const sql = buildComponentMetadataUpsert(seo, "postgresql");
+    expect(sql).toContain('INSERT INTO "dynamic_components"');
+    expect(sql).toContain("'comp_seo'");
+    expect(sql).not.toContain('"status"');
+  });
+});