@jskit-ai/crud-server-generator 0.1.39 → 0.1.41

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-server-generator",
-  version: "0.1.39",
+  version: "0.1.41",
   kind: "generator",
   description: "CRUD server generator with routes, actions, and persistence scaffolding.",
   options: {
@@ -15,6 +15,7 @@ export default Object.freeze({
     surface: {
       required: true,
       inputType: "text",
+      validationType: "enabled-surface-id",
       promptLabel: "Target surface",
       promptHint: "Must match an enabled surface id."
     },
@@ -45,6 +46,13 @@ export default Object.freeze({
       defaultValue: "id",
       promptLabel: "Id column",
       promptHint: "Primary key column used by CRUD endpoints (default: id)."
+    },
+    force: {
+      required: false,
+      inputType: "flag",
+      defaultValue: "",
+      promptLabel: "Force overwrite",
+      promptHint: "Overwrite generated scaffold files if the namespace package directory already exists."
     }
   },
   optionPolicies: {
@@ -90,8 +98,14 @@ export default Object.freeze({
           "ownership-filter",
           "table-name",
           "id-column",
-          "directory-prefix"
-        ]
+          "directory-prefix",
+          "force"
+        ],
+        createTarget: {
+          pathTemplate: "packages/${option:namespace|kebab}",
+          label: "package directory",
+          allowExistingEmptyDirectory: false
+        }
       },
       "scaffold-field": {
         entrypoint: "src/server/subcommands/addField.js",
@@ -134,13 +148,13 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/auth-core": "0.1.30",
-        "@jskit-ai/crud-core": "0.1.39",
-        "@jskit-ai/database-runtime": "0.1.31",
-        "@jskit-ai/http-runtime": "0.1.30",
-        "@jskit-ai/kernel": "0.1.31",
-        "@jskit-ai/realtime": "0.1.30",
-        "@jskit-ai/users-core": "0.1.41",
+        "@jskit-ai/auth-core": "0.1.32",
+        "@jskit-ai/crud-core": "0.1.41",
+        "@jskit-ai/database-runtime": "0.1.33",
+        "@jskit-ai/http-runtime": "0.1.32",
+        "@jskit-ai/kernel": "0.1.33",
+        "@jskit-ai/realtime": "0.1.32",
+        "@jskit-ai/users-core": "0.1.43",
         "@local/${option:namespace|kebab}": "file:packages/${option:namespace|kebab}",
         "typebox": "^1.0.81"
       },
@@ -203,6 +217,17 @@ export default Object.freeze({
         category: "crud",
         id: "crud-local-package-server-action-ids-${option:namespace|snake}"
       },
+      {
+        from: "templates/src/local-package/server/listConfig.js",
+        to: "packages/${option:namespace|kebab}/src/server/listConfig.js",
+        reason: "Install app-local CRUD list configuration.",
+        category: "crud",
+        id: "crud-local-package-server-list-config-${option:namespace|snake}",
+        templateContext: {
+          entrypoint: "src/server/buildTemplateContext.js",
+          export: "buildTemplateContext"
+        }
+      },
       {
         from: "templates/src/local-package/server/registerRoutes.js",
         to: "packages/${option:namespace|kebab}/src/server/registerRoutes.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-server-generator",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,11 +13,11 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.2",
-    "@jskit-ai/crud-core": "0.1.39",
-    "@jskit-ai/database-runtime": "0.1.31",
-    "@jskit-ai/http-runtime": "0.1.30",
-    "@jskit-ai/kernel": "0.1.31",
-    "@jskit-ai/users-core": "0.1.41",
+    "@jskit-ai/crud-core": "0.1.41",
+    "@jskit-ai/database-runtime": "0.1.33",
+    "@jskit-ai/http-runtime": "0.1.32",
+    "@jskit-ai/kernel": "0.1.33",
+    "@jskit-ai/users-core": "0.1.43",
     "recast": "^0.23.11",
     "typebox": "^1.0.81"
   }

package/src/server/buildTemplateContext.js

@@ -5,7 +5,7 @@ import { pathToFileURL } from "node:url";
 import {
   normalizeText,
   resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment,
+  resolveKnexConnectionFromEnvironment,
   toKnexClientId
 } from "@jskit-ai/database-runtime/shared";
 import { checkCrudLookupFormControl } from "@jskit-ai/crud-core/shared/crudFieldMetaSupport";
@@ -61,8 +61,8 @@ function normalizeRequestedOwnershipFilter(value, { strict = false } = {}) {
 }
 
 function inferOwnershipFilterFromSnapshot(snapshot) {
-  const hasWorkspace = snapshot?.hasWorkspaceOwnerColumn === true;
-  const hasUser = snapshot?.hasUserOwnerColumn === true;
+  const hasWorkspace = snapshot?.hasWorkspaceIdColumn === true;
+  const hasUser = snapshot?.hasUserIdColumn === true;
   if (hasWorkspace && hasUser) {
     return "workspace_user";
   }
@@ -76,24 +76,24 @@ function inferOwnershipFilterFromSnapshot(snapshot) {
 }
 
 function assertOwnershipColumnsForFilter(snapshot, filter) {
-  const hasWorkspace = snapshot?.hasWorkspaceOwnerColumn === true;
-  const hasUser = snapshot?.hasUserOwnerColumn === true;
+  const hasWorkspace = snapshot?.hasWorkspaceIdColumn === true;
+  const hasUser = snapshot?.hasUserIdColumn === true;
   if (filter === "public") {
     return;
   }
   if (filter === "workspace" && !hasWorkspace) {
     throw new Error(
-      'Ownership filter "workspace" requires column "workspace_owner_id".'
+      'Ownership filter "workspace" requires column "workspace_id".'
     );
   }
   if (filter === "user" && !hasUser) {
     throw new Error(
-      'Ownership filter "user" requires column "user_owner_id".'
+      'Ownership filter "user" requires column "user_id".'
     );
   }
   if (filter === "workspace_user" && (!hasWorkspace || !hasUser)) {
     throw new Error(
-      'Ownership filter "workspace_user" requires both columns "workspace_owner_id" and "user_owner_id".'
+      'Ownership filter "workspace_user" requires both columns "workspace_id" and "user_id".'
     );
   }
 }
@@ -221,7 +221,8 @@ async function resolveMysqlSnapshotFromDatabase({
     );
   }
 
-  const connection = resolveDatabaseConnectionFromEnvironment(env, {
+  const connection = resolveKnexConnectionFromEnvironment(env, {
+    client: dbClient,
     defaultPort: 3306,
     context: "crud table introspection"
   });
@@ -269,16 +270,24 @@ function resolveColumnKey(column, idColumn) {
 function resolveScaffoldColumns(snapshot) {
   const idColumn = String(snapshot.idColumn || DEFAULT_ID_COLUMN);
   const sourceColumns = Array.isArray(snapshot.columns) ? snapshot.columns : [];
+  const foreignKeyColumnNames = new Set(
+    (Array.isArray(snapshot.foreignKeys) ? snapshot.foreignKeys : [])
+      .flatMap((foreignKey) => Array.isArray(foreignKey?.columns) ? foreignKey.columns : [])
+      .map((entry) => String(entry?.name || "").trim())
+      .filter(Boolean)
+  );
   const seenKeys = new Set();
 
   const columns = sourceColumns.map((column) => {
-    const isWorkspaceOwnerColumn = column.name === "workspace_owner_id";
-    const isUserOwnerColumn = column.name === "user_owner_id";
-    const isOwnerColumn = isWorkspaceOwnerColumn || isUserOwnerColumn;
+    const isWorkspaceIdColumn = column.name === "workspace_id";
+    const isUserIdColumn = column.name === "user_id";
+    const isOwnerColumn = isWorkspaceIdColumn || isUserIdColumn;
     const isIdColumn = column.name === idColumn;
+    const isForeignIdColumn = foreignKeyColumnNames.has(column.name) || /_id$/i.test(String(column.name || ""));
     const isCreatedAtColumn = column.name === "created_at";
     const isUpdatedAtColumn = column.name === "updated_at";
     const key = resolveColumnKey(column, idColumn);
+    const isRecordIdColumn = isIdColumn || isOwnerColumn || isForeignIdColumn || /Id$/.test(String(key || ""));
     if (!key) {
       throw new Error(`Could not derive API field key for column "${column.name}".`);
     }
@@ -297,6 +306,8 @@ function resolveScaffoldColumns(snapshot) {
       key,
       isOwnerColumn,
       isIdColumn,
+      isForeignIdColumn,
+      isRecordIdColumn,
       isCreatedAtColumn,
       isUpdatedAtColumn,
       writable: !isOwnerColumn && !isIdColumn && !isCreatedAtColumn && !isUpdatedAtColumn
@@ -327,9 +338,7 @@ function renderPropertyAccess(sourceName, key) {
 
 function renderIntegerSchema(column) {
   const options = [];
-  if (column.isIdColumn === true) {
-    options.push("minimum: 1");
-  } else if (column.unsigned === true) {
+  if (column.unsigned === true) {
     options.push("minimum: 0");
   }
   if (options.length > 0) {
@@ -359,6 +368,11 @@ function renderResourceFieldSchema(column, { forOutput = false } = {}) {
   if (typeKind === "string") {
     schemaExpression = renderStringSchema(column, { forOutput });
   } else if (typeKind === "integer") {
+    if (column?.isRecordIdColumn === true) {
+      return forOutput
+        ? (column.nullable === true ? "nullableRecordIdSchema" : "recordIdSchema")
+        : (column.nullable === true ? "nullableRecordIdInputSchema" : "recordIdInputSchema");
+    }
     schemaExpression = renderIntegerSchema(column);
   } else if (typeKind === "number") {
     schemaExpression = "Type.Number()";
@@ -382,11 +396,14 @@ function renderResourceFieldSchema(column, { forOutput = false } = {}) {
   return schemaExpression;
 }
 
-function renderResourceValidatorsImport({ needsHtmlTimeSchemas = false } = {}) {
+function renderResourceValidatorsImport({ needsHtmlTimeSchemas = false, needsRecordIdSchemas = false } = {}) {
   const imports = [
     "normalizeObjectInput",
     "createCursorListValidator"
   ];
+  if (needsRecordIdSchemas) {
+    imports.push("recordIdSchema", "recordIdInputSchema", "nullableRecordIdSchema", "nullableRecordIdInputSchema");
+  }
   if (needsHtmlTimeSchemas) {
     imports.push("HTML_TIME_STRING_SCHEMA", "NULLABLE_HTML_TIME_STRING_SCHEMA");
   }
@@ -406,6 +423,12 @@ function renderInputNormalizer(column) {
     return "normalizeText";
   }
   if (typeKind === "integer") {
+    if (column?.isRecordIdColumn === true) {
+      if (nullable) {
+        return "(value) => normalizeRecordId(value, { fallback: null })";
+      }
+      return "normalizeRecordId";
+    }
     return "normalizeFiniteInteger";
   }
   if (typeKind === "number") {
@@ -434,10 +457,17 @@ function renderInputNormalizer(column) {
 
 function renderOutputNormalizerExpression(column) {
   const typeKind = String(column.typeKind || "");
+  const nullable = column?.nullable === true;
   if (typeKind === "string" || typeKind === "time") {
     return "normalizeText";
   }
   if (typeKind === "integer") {
+    if (column?.isRecordIdColumn === true) {
+      if (nullable) {
+        return "(value) => normalizeRecordId(value, { fallback: null })";
+      }
+      return "normalizeRecordId";
+    }
     return "normalizeFiniteInteger";
   }
   if (typeKind === "number") {
@@ -522,6 +552,7 @@ function renderResourceNormalizeSupportImport({
   needsNormalizeBoolean = false,
   needsNormalizeFiniteNumber = false,
   needsNormalizeFiniteInteger = false,
+  needsNormalizeRecordId = false,
   needsNormalizeIfInSource = false,
   needsNormalizeIfPresent = false,
   needsNormalizeOrNull = false
@@ -539,6 +570,9 @@ function renderResourceNormalizeSupportImport({
   if (needsNormalizeFiniteInteger) {
     imports.push("normalizeFiniteInteger");
   }
+  if (needsNormalizeRecordId) {
+    imports.push("normalizeRecordId");
+  }
   if (needsNormalizeIfInSource) {
     imports.push("normalizeIfInSource");
   }
@@ -596,15 +630,57 @@ function renderMigrationDefaultClause(column) {
     }
   }
 
+  if (column.typeKind === "string" && normalized.startsWith("'") && normalized.endsWith("'")) {
+    const unquoted = normalized
+      .slice(1, -1)
+      .replace(/\\'/g, "'")
+      .replace(/''/g, "'");
+    return `.defaultTo(${JSON.stringify(unquoted)})`;
+  }
+
   return `.defaultTo(${JSON.stringify(rawDefault)})`;
 }
 
-function renderMigrationColumnLine(column, { idColumn = DEFAULT_ID_COLUMN, primaryKeyColumns = [] } = {}) {
+function renderMigrationSpecificStringType(column, { tableCollation = "" } = {}) {
+  const baseType = normalizeText(column?.columnType);
+  if (!baseType) {
+    return "";
+  }
+
+  const characterSetName = normalizeText(column?.characterSetName);
+  const collationName = normalizeText(column?.collationName);
+  const normalizedTableCollation = normalizeText(tableCollation);
+  if (!collationName || collationName === normalizedTableCollation) {
+    return "";
+  }
+
+  const parts = [baseType];
+  if (characterSetName) {
+    parts.push(`CHARACTER SET ${characterSetName}`);
+  }
+  parts.push(`COLLATE ${collationName}`);
+  return parts.join(" ");
+}
+
+function renderTemporalColumnBuilder(column, methodName) {
+  if (Number.isFinite(column?.datetimePrecision) && column.datetimePrecision > 0) {
+    return `table.${methodName}(${JSON.stringify(column.name)}, { precision: ${column.datetimePrecision} })`;
+  }
+  return `table.${methodName}(${JSON.stringify(column.name)})`;
+}
+
+function renderMigrationColumnLine(column, {
+  idColumn = DEFAULT_ID_COLUMN,
+  primaryKeyColumns = [],
+  foreignKeyColumnNames = new Set(),
+  tableCollation = ""
+} = {}) {
   const isPrimary = Array.isArray(primaryKeyColumns) && primaryKeyColumns.includes(column.name);
   const isIdColumn = column.name === idColumn;
+  const isRecordIdColumn = isIdColumn || column.name === "workspace_id" || column.name === "user_id" || foreignKeyColumnNames.has(column.name) || /_id$/i.test(String(column.name || ""));
 
   if (isIdColumn && column.autoIncrement) {
-    let line = `table.increments(${JSON.stringify(column.name)})`;
+    let line = `table.bigIncrements(${JSON.stringify(column.name)})`;
     if (column.unsigned) {
       line += ".unsigned()";
     }
@@ -615,25 +691,40 @@ function renderMigrationColumnLine(column, { idColumn = DEFAULT_ID_COLUMN, prima
   let line = "";
   const nameLiteral = JSON.stringify(column.name);
   const dataType = String(column.dataType || "").toLowerCase();
+  const specificStringType = renderMigrationSpecificStringType(column, {
+    tableCollation
+  });
 
   if (dataType === "varchar") {
-    const maxLength = Number.isFinite(column.maxLength) ? column.maxLength : 255;
-    line = `table.string(${nameLiteral}, ${maxLength})`;
+    if (specificStringType) {
+      line = `table.specificType(${nameLiteral}, ${JSON.stringify(specificStringType)})`;
+    } else {
+      const maxLength = Number.isFinite(column.maxLength) ? column.maxLength : 255;
+      line = `table.string(${nameLiteral}, ${maxLength})`;
+    }
   } else if (dataType === "char") {
-    line = `table.specificType(${nameLiteral}, ${JSON.stringify(column.columnType || "char(255)")})`;
+    line = `table.specificType(${nameLiteral}, ${JSON.stringify(specificStringType || column.columnType || "char(255)")})`;
   } else if (dataType === "text") {
-    line = `table.text(${nameLiteral})`;
+    if (specificStringType) {
+      line = `table.specificType(${nameLiteral}, ${JSON.stringify(specificStringType)})`;
+    } else {
+      line = `table.text(${nameLiteral})`;
+    }
   } else if (dataType === "tinytext" || dataType === "mediumtext" || dataType === "longtext") {
-    line = `table.text(${nameLiteral}, ${JSON.stringify(dataType)})`;
+    if (specificStringType) {
+      line = `table.specificType(${nameLiteral}, ${JSON.stringify(specificStringType)})`;
+    } else {
+      line = `table.text(${nameLiteral}, ${JSON.stringify(dataType)})`;
+    }
   } else if (dataType === "enum") {
     const enumValues = Array.isArray(column.enumValues) ? column.enumValues : [];
     line = `table.enu(${nameLiteral}, ${JSON.stringify(enumValues)})`;
   } else if (dataType === "set") {
-    line = `table.specificType(${nameLiteral}, ${JSON.stringify(column.columnType || "set")})`;
+    line = `table.specificType(${nameLiteral}, ${JSON.stringify(specificStringType || column.columnType || "set")})`;
   } else if (column.typeKind === "boolean") {
     line = `table.boolean(${nameLiteral})`;
   } else if (dataType === "int" || dataType === "integer") {
-    line = `table.integer(${nameLiteral})`;
+    line = isRecordIdColumn ? `table.bigInteger(${nameLiteral})` : `table.integer(${nameLiteral})`;
   } else if (dataType === "smallint") {
     line = `table.smallint(${nameLiteral})`;
   } else if (dataType === "bigint") {
@@ -657,11 +748,11 @@ function renderMigrationColumnLine(column, { idColumn = DEFAULT_ID_COLUMN, prima
   } else if (dataType === "date") {
     line = `table.date(${nameLiteral})`;
   } else if (dataType === "time") {
-    line = `table.time(${nameLiteral})`;
+    line = renderTemporalColumnBuilder(column, "time");
   } else if (dataType === "datetime") {
-    line = `table.dateTime(${nameLiteral})`;
+    line = renderTemporalColumnBuilder(column, "dateTime");
   } else if (dataType === "timestamp") {
-    line = `table.timestamp(${nameLiteral})`;
+    line = renderTemporalColumnBuilder(column, "timestamp");
   } else {
     throw new Error(
       `Unsupported MySQL type "${dataType}" in migration renderer for column "${column.name}".`
@@ -682,10 +773,18 @@ function renderMigrationColumnLine(column, { idColumn = DEFAULT_ID_COLUMN, prima
 
 function renderMigrationColumnLines(snapshot) {
   const columns = Array.isArray(snapshot.columns) ? snapshot.columns : [];
+  const foreignKeyColumnNames = new Set(
+    (Array.isArray(snapshot.foreignKeys) ? snapshot.foreignKeys : [])
+      .flatMap((foreignKey) => Array.isArray(foreignKey?.columns) ? foreignKey.columns : [])
+      .map((entry) => String(entry?.name || "").trim())
+      .filter(Boolean)
+  );
   const lines = columns.map((column) =>
     `    ${renderMigrationColumnLine(column, {
       idColumn: snapshot.idColumn,
-      primaryKeyColumns: snapshot.primaryKeyColumns
+      primaryKeyColumns: snapshot.primaryKeyColumns,
+      foreignKeyColumnNames,
+      tableCollation: snapshot.tableCollation
     })}`
   );
   return lines.join("\n");
@@ -699,13 +798,23 @@ function renderMigrationIndexLine(index) {
 
   const columnsLiteral = JSON.stringify(columns);
   const indexName = normalizeText(index?.name);
+  const normalizedIndexType = normalizeText(index?.indexType).toUpperCase();
+  const storageEngineIndexType = normalizedIndexType && normalizedIndexType !== "BTREE"
+    ? normalizedIndexType.toLowerCase()
+    : "";
   if (index?.unique === true) {
+    if (indexName && storageEngineIndexType) {
+      return `    table.unique(${columnsLiteral}, { indexName: ${JSON.stringify(indexName)}, storageEngineIndexType: ${JSON.stringify(storageEngineIndexType)} });`;
+    }
     if (indexName) {
       return `    table.unique(${columnsLiteral}, ${JSON.stringify(indexName)});`;
     }
     return `    table.unique(${columnsLiteral});`;
   }
 
+  if (indexName && normalizedIndexType && normalizedIndexType !== "BTREE") {
+    return `    table.index(${columnsLiteral}, ${JSON.stringify(indexName)}, ${JSON.stringify(normalizedIndexType)});`;
+  }
   if (indexName) {
     return `    table.index(${columnsLiteral}, ${JSON.stringify(indexName)});`;
   }
@@ -764,6 +873,28 @@ function renderMigrationForeignKeyLines(snapshot) {
   return lines.join("\n");
 }
 
+function renderMigrationCheckConstraintLines(snapshot) {
+  const tableName = normalizeText(snapshot?.tableName);
+  const checkConstraints = Array.isArray(snapshot?.checkConstraints) ? snapshot.checkConstraints : [];
+  if (!tableName || checkConstraints.length < 1) {
+    return "";
+  }
+
+  return checkConstraints
+    .map((constraint) => {
+      const name = normalizeText(constraint?.name);
+      const clause = normalizeText(constraint?.clause);
+      if (!name || !clause) {
+        return "";
+      }
+
+      const sql = `ALTER TABLE \`${tableName}\` ADD CONSTRAINT \`${name}\` CHECK (${clause})`;
+      return `  await knex.raw(${JSON.stringify(sql)});`;
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
 function mergeFieldMetaEntries(...entryGroups) {
   const mergedByKey = new Map();
   for (const sourceEntries of entryGroups) {
@@ -1116,7 +1247,8 @@ function buildReplacementsFromSnapshot({
     writableColumns,
     snapshot
   });
-  const needsFiniteInteger = resourceColumns.some((column) => column.typeKind === "integer");
+  const needsFiniteInteger = resourceColumns.some((column) => column.typeKind === "integer" && column.isRecordIdColumn !== true);
+  const needsRecordIdSchemas = resourceColumns.some((column) => column.typeKind === "integer" && column.isRecordIdColumn === true);
   const needsFiniteNumber = resourceColumns.some((column) => column.typeKind === "number");
   const needsDateTimeOutput = outputColumns.some((column) => column.typeKind === "datetime");
   const needsDateTimeInput = writableColumns.some((column) => column.typeKind === "datetime");
@@ -1145,7 +1277,8 @@ function buildReplacementsFromSnapshot({
     __JSKIT_CRUD_ID_COLUMN__: JSON.stringify(snapshot.idColumn || DEFAULT_ID_COLUMN),
     __JSKIT_CRUD_RESOLVED_OWNERSHIP_FILTER__: resolvedOwnershipFilter,
     __JSKIT_CRUD_RESOURCE_VALIDATORS_IMPORT__: renderResourceValidatorsImport({
-      needsHtmlTimeSchemas
+      needsHtmlTimeSchemas,
+      needsRecordIdSchemas
     }),
     __JSKIT_CRUD_RESOURCE_DATABASE_RUNTIME_IMPORT__: renderResourceDatabaseRuntimeImport({
       needsToIsoString: needsDateTimeOutput || needsDate,
@@ -1156,6 +1289,7 @@ function buildReplacementsFromSnapshot({
       needsNormalizeBoolean,
       needsNormalizeFiniteNumber: needsFiniteNumber,
       needsNormalizeFiniteInteger: needsFiniteInteger,
+      needsNormalizeRecordId: needsRecordIdSchemas,
       needsNormalizeIfInSource,
       needsNormalizeIfPresent,
       needsNormalizeOrNull
@@ -1176,7 +1310,8 @@ function buildReplacementsFromSnapshot({
     __JSKIT_CRUD_LIST_CONFIG_LINES__: renderRepositoryListConfigLines(snapshot),
     __JSKIT_CRUD_MIGRATION_COLUMN_LINES__: renderMigrationColumnLines(snapshot),
     __JSKIT_CRUD_MIGRATION_INDEX_LINES__: renderMigrationIndexLines(snapshot),
-    __JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__: renderMigrationForeignKeyLines(snapshot)
+    __JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__: renderMigrationForeignKeyLines(snapshot),
+    __JSKIT_CRUD_MIGRATION_CHECK_CONSTRAINT_LINES__: renderMigrationCheckConstraintLines(snapshot)
   });
 
   return replacements;
@@ -1266,6 +1401,7 @@ const __testables = Object.freeze({
   buildReplacementsFromSnapshot,
   parseDotEnvLine,
   renderMigrationColumnLine,
+  renderMigrationCheckConstraintLines,
   renderMigrationForeignKeyLine,
   resolveScaffoldColumns,
   renderPropertyAccess,

package/src/shared/crud/crudResource.js

@@ -5,10 +5,12 @@ import {
 } from "@jskit-ai/database-runtime/shared";
 import {
   normalizeObjectInput,
-  createCursorListValidator
+  createCursorListValidator,
+  recordIdSchema
 } from "@jskit-ai/kernel/shared/validators";
 import {
   normalizeText,
+  normalizeRecordId,
   normalizeFiniteNumber,
   normalizeIfPresent
 } from "@jskit-ai/kernel/shared/support/normalize";
@@ -17,7 +19,7 @@ const RESOURCE_LOOKUP_CONTAINER_KEY = "lookups";
 
 const recordOutputSchema = Type.Object(
   {
-    id: Type.Integer({ minimum: 1 }),
+    id: recordIdSchema,
     textField: Type.String({ minLength: 1, maxLength: 160 }),
     dateField: Type.String({ minLength: 1 }),
     numberField: Type.Number(),
@@ -71,7 +73,7 @@ const recordOutputValidator = Object.freeze({
   normalize(payload = {}) {
     const source = normalizeObjectInput(payload);
     const normalized = {
-      id: Number(source.id),
+      id: normalizeRecordId(source.id, { fallback: "" }),
       textField: normalizeText(source.textField),
       dateField: toIsoString(source.dateField),
       numberField: normalizeFiniteNumber(source.numberField),
@@ -116,7 +118,7 @@ const patchBodyValidator = Object.freeze({
 const deleteOutputValidator = Object.freeze({
   schema: Type.Object(
     {
-      id: Type.Integer({ minimum: 1 }),
+      id: recordIdSchema,
       deleted: Type.Literal(true)
     },
     { additionalProperties: false }
@@ -125,7 +127,7 @@ const deleteOutputValidator = Object.freeze({
     const source = normalizeObjectInput(payload);
 
     return {
-      id: Number(source.id),
+      id: normalizeRecordId(source.id, { fallback: "" }),
       deleted: true
     };
   }

package/templates/migrations/crud_initial.cjs

@@ -11,6 +11,7 @@ __JSKIT_CRUD_MIGRATION_COLUMN_LINES__
 __JSKIT_CRUD_MIGRATION_INDEX_LINES__
 __JSKIT_CRUD_MIGRATION_FOREIGN_KEY_LINES__
   });
+__JSKIT_CRUD_MIGRATION_CHECK_CONSTRAINT_LINES__
 };
 
 exports.down = async function down(knex) {

package/templates/src/local-package/server/repository.js

@@ -7,6 +7,7 @@ import {
   crudRepositoryUpdateById,
   crudRepositoryDeleteById
 } from "@jskit-ai/crud-core/server/repositoryMethods";
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
 import { resource } from "../shared/${option:namespace|singular|camel}Resource.js";
 import { LIST_CONFIG } from "./listConfig.js";
 
@@ -16,6 +17,8 @@ const repositoryRuntime = createCrudRepositoryRuntime(resource, {
 });
 
 function createRepository(knex, options = {}) {
+  const withTransaction = createWithTransaction(knex);
+
   async function list(query = {}, callOptions = {}) {
     return crudRepositoryList(repositoryRuntime, knex, query, options, callOptions);
   }
@@ -41,6 +44,7 @@ function createRepository(knex, options = {}) {
   }
 
   return Object.freeze({
+    withTransaction,
     list,
     findById,
     listByIds,

package/templates/src/local-package/shared/crudResource.js

@@ -65,7 +65,7 @@ const patchBodyValidator = Object.freeze({
 const deleteOutputValidator = Object.freeze({
   schema: Type.Object(
     {
-      id: Type.Integer({ minimum: 1 }),
+      id: recordIdSchema,
       deleted: Type.Literal(true)
     },
     { additionalProperties: false }
@@ -74,7 +74,7 @@ const deleteOutputValidator = Object.freeze({
     const source = normalizeObjectInput(payload);
 
     return {
-      id: Number(source.id),
+      id: normalizeRecordId(source.id, { fallback: "" }),
       deleted: true
     };
   }

package/test/addFieldSubcommand.test.js

@@ -107,8 +107,8 @@ function createSnapshot() {
     idColumn: "id",
     columns: [
       { name: "id", key: "id", typeKind: "integer", nullable: false, unsigned: true },
-      { name: "workspace_owner_id", key: "workspaceOwnerId", typeKind: "integer", nullable: true, unsigned: true },
-      { name: "user_owner_id", key: "userOwnerId", typeKind: "integer", nullable: true, unsigned: true },
+      { name: "workspace_id", key: "workspaceId", typeKind: "integer", nullable: true, unsigned: true },
+      { name: "user_id", key: "userId", typeKind: "integer", nullable: true, unsigned: true },
       { name: "created_at", key: "createdAt", typeKind: "datetime", nullable: false },
       { name: "updated_at", key: "updatedAt", typeKind: "datetime", nullable: false },
       { name: "first_name", key: "firstName", typeKind: "string", nullable: true, maxLength: 160 },
@@ -145,15 +145,21 @@ test("scaffold-field patches CRUD resource file using DB snapshot metadata", asy
     assert.deepEqual(result.touchedFiles, [resourceFile]);
 
     const content = await readFile(path.join(appRoot, resourceFile), "utf8");
-    assert.match(content, /categoryId: Type\.Union\(\[Type\.Integer\(\{ minimum: 0 \}\), Type\.Null\(\)\]\)/);
-    assert.match(content, /normalizeIfInSource\(source, normalized, "categoryId", normalizeFiniteInteger\);/);
-    assert.match(content, /categoryId: normalizeOrNull\(source\.categoryId, normalizeFiniteInteger\)/);
+    assert.match(content, /categoryId: nullableRecordIdSchema/);
+    assert.match(
+      content,
+      /normalizeIfInSource\(source, normalized, "categoryId", \(value\) => normalizeRecordId\(value, \{ fallback: null \}\)\);/
+    );
+    assert.match(
+      content,
+      /categoryId: normalizeOrNull\(source\.categoryId, \(value\) => normalizeRecordId\(value, \{ fallback: null \}\)\)/
+    );
     assert.match(content, /RESOURCE_FIELD_META\.push\(\{/);
     assert.match(content, /key: "categoryId"/);
     assert.match(content, /namespace: "customer-categories"/);
     assert.match(content, /valueKey: "id"/);
     assert.match(content, /formControl: "autocomplete" \/\/ or "select"/);
-    assert.match(content, /normalizeFiniteInteger/);
+    assert.match(content, /normalizeRecordId/);
 
     const secondRun = await runGeneratorSubcommand({
       appRoot,

package/test/buildTemplateContext.test.js

@@ -8,8 +8,8 @@ import { buildTemplateContext, __testables } from "../src/server/buildTemplateCo
 
 function createSnapshot({
   tableName = "contacts",
-  hasWorkspaceOwnerColumn = true,
-  hasUserOwnerColumn = true,
+  hasWorkspaceIdColumn = true,
+  hasUserIdColumn = true,
   hasCreatedAtColumn = true
 } = {}) {
   const createdAtColumn = hasCreatedAtColumn
@@ -29,16 +29,20 @@ function createSnapshot({
           maxLength: null,
           numericPrecision: null,
           numericScale: null,
+          datetimePrecision: null,
+          characterSetName: "",
+          collationName: "",
           enumValues: Object.freeze([])
         })
       ]
     : [];
   return Object.freeze({
     tableName,
+    tableCollation: "utf8mb4_general_ci",
     idColumn: "id",
     primaryKeyColumns: Object.freeze(["id"]),
-    hasWorkspaceOwnerColumn,
-    hasUserOwnerColumn,
+    hasWorkspaceIdColumn,
+    hasUserIdColumn,
     columns: Object.freeze([
       Object.freeze({
         name: "id",
@@ -55,11 +59,14 @@ function createSnapshot({
         maxLength: null,
         numericPrecision: 10,
         numericScale: 0,
+        datetimePrecision: null,
+        characterSetName: "",
+        collationName: "",
         enumValues: Object.freeze([])
       }),
       Object.freeze({
-        name: "workspace_owner_id",
-        key: "workspaceOwnerId",
+        name: "workspace_id",
+        key: "workspaceId",
         dataType: "int",
         columnType: "int unsigned",
         typeKind: "integer",
@@ -72,11 +79,14 @@ function createSnapshot({
         maxLength: null,
         numericPrecision: 10,
         numericScale: 0,
+        datetimePrecision: null,
+        characterSetName: "",
+        collationName: "",
         enumValues: Object.freeze([])
       }),
       Object.freeze({
-        name: "user_owner_id",
-        key: "userOwnerId",
+        name: "user_id",
+        key: "userId",
         dataType: "int",
         columnType: "int unsigned",
         typeKind: "integer",
@@ -89,6 +99,9 @@ function createSnapshot({
         maxLength: null,
         numericPrecision: 10,
         numericScale: 0,
+        datetimePrecision: null,
+        characterSetName: "",
+        collationName: "",
         enumValues: Object.freeze([])
       }),
       Object.freeze({
@@ -106,6 +119,9 @@ function createSnapshot({
         maxLength: 160,
         numericPrecision: null,
         numericScale: null,
+        datetimePrecision: null,
+        characterSetName: "utf8mb4",
+        collationName: "utf8mb4_general_ci",
         enumValues: Object.freeze([])
       }),
       ...createdAtColumn,
@@ -124,30 +140,34 @@ function createSnapshot({
         maxLength: null,
         numericPrecision: null,
         numericScale: null,
+        datetimePrecision: null,
+        characterSetName: "",
+        collationName: "",
         enumValues: Object.freeze([])
       })
     ]),
     indexes: Object.freeze([]),
-    foreignKeys: Object.freeze([])
+    foreignKeys: Object.freeze([]),
+    checkConstraints: Object.freeze([])
   });
 }
 
 test("resolveOwnershipFilterForGeneration infers ownership filter for table introspection mode", () => {
   const snapshotBoth = createSnapshot({
-    hasWorkspaceOwnerColumn: true,
-    hasUserOwnerColumn: true
+    hasWorkspaceIdColumn: true,
+    hasUserIdColumn: true
   });
   const snapshotWorkspaceOnly = createSnapshot({
-    hasWorkspaceOwnerColumn: true,
-    hasUserOwnerColumn: false
+    hasWorkspaceIdColumn: true,
+    hasUserIdColumn: false
   });
   const snapshotUserOnly = createSnapshot({
-    hasWorkspaceOwnerColumn: false,
-    hasUserOwnerColumn: true
+    hasWorkspaceIdColumn: false,
+    hasUserIdColumn: true
   });
   const snapshotPublic = createSnapshot({
-    hasWorkspaceOwnerColumn: false,
-    hasUserOwnerColumn: false
+    hasWorkspaceIdColumn: false,
+    hasUserIdColumn: false
   });
 
   assert.equal(
@@ -178,8 +198,8 @@ test("resolveOwnershipFilterForGeneration infers ownership filter for table intr
 
 test("resolveOwnershipFilterForGeneration rejects explicit ownership filters when required columns are missing", () => {
   const snapshotPublic = createSnapshot({
-    hasWorkspaceOwnerColumn: false,
-    hasUserOwnerColumn: false
+    hasWorkspaceIdColumn: false,
+    hasUserIdColumn: false
   });
 
   assert.throws(
@@ -187,14 +207,14 @@ test("resolveOwnershipFilterForGeneration rejects explicit ownership filters whe
       __testables.resolveOwnershipFilterForGeneration(snapshotPublic, "workspace", {
         enforceTableColumns: true
       }),
-    /requires column "workspace_owner_id"/
+    /requires column "workspace_id"/
   );
   assert.throws(
     () =>
       __testables.resolveOwnershipFilterForGeneration(snapshotPublic, "user", {
         enforceTableColumns: true
       }),
-    /requires column "user_owner_id"/
+    /requires column "user_id"/
   );
 });
 
@@ -221,13 +241,13 @@ test("buildReplacementsFromSnapshot builds deterministic template replacement pa
   assert.equal(replacements.__JSKIT_CRUD_TABLE_NAME__, "\"contacts\"");
   assert.equal(replacements.__JSKIT_CRUD_ID_COLUMN__, "\"id\"");
   assert.equal(replacements.__JSKIT_CRUD_RESOLVED_OWNERSHIP_FILTER__, "workspace_user");
-  assert.match(replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__, /table\.increments\("id"\)/);
+  assert.match(replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__, /table\.bigIncrements\("id"\)/);
   assert.match(replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__, /table\.string\("first_name", 160\)/);
   assert.equal(replacements.__JSKIT_CRUD_RESOURCE_FIELD_META_PUSH_LINES__, "");
   assert.match(replacements.__JSKIT_CRUD_RESOURCE_OUTPUT_SCHEMA_PROPERTIES__, /updatedAt: Type\.String/);
   assert.match(
     replacements.__JSKIT_CRUD_RESOURCE_OUTPUT_SCHEMA_PROPERTIES__,
-    /id: Type\.Integer\(\{ minimum: 1 \}\),/
+    /id: recordIdSchema,/
   );
   assert.match(replacements.__JSKIT_CRUD_RESOURCE_CREATE_SCHEMA_PROPERTIES__, /firstName: Type\.String/);
   assert.match(
@@ -332,8 +352,8 @@ test("buildReplacementsFromSnapshot renders append-only field meta entries from
 
 test("buildReplacementsFromSnapshot renders enum field meta options as select controls", () => {
   const baseSnapshot = createSnapshot({
-    hasWorkspaceOwnerColumn: false,
-    hasUserOwnerColumn: false
+    hasWorkspaceIdColumn: false,
+    hasUserIdColumn: false
   });
   const snapshot = {
     ...baseSnapshot,
@@ -374,7 +394,7 @@ test("buildReplacementsFromSnapshot renders enum field meta options as select co
 test("renderMigrationColumnLine ignores SQL NULL string defaults", () => {
   const line = __testables.renderMigrationColumnLine(
     {
-      name: "workspace_owner_id",
+      name: "workspace_id",
       dataType: "int",
       columnType: "int unsigned",
       typeKind: "integer",
@@ -398,10 +418,144 @@ test("renderMigrationColumnLine ignores SQL NULL string defaults", () => {
   assert.equal(line.includes(".defaultTo("), false);
 });
 
+test("renderMigrationColumnLine unwraps quoted string defaults", () => {
+  const stringLine = __testables.renderMigrationColumnLine({
+    name: "name",
+    dataType: "varchar",
+    columnType: "varchar(255)",
+    typeKind: "string",
+    nullable: false,
+    hasDefault: true,
+    defaultValue: "''",
+    autoIncrement: false,
+    unsigned: false,
+    extra: "",
+    maxLength: 255,
+    numericPrecision: null,
+    numericScale: null,
+    datetimePrecision: null,
+    characterSetName: "utf8mb4",
+    collationName: "utf8mb4_general_ci",
+    enumValues: []
+  });
+  const enumLine = __testables.renderMigrationColumnLine({
+    name: "temperament",
+    dataType: "enum",
+    columnType: "enum('friendly','unknown')",
+    typeKind: "string",
+    nullable: false,
+    hasDefault: true,
+    defaultValue: "'unknown'",
+    autoIncrement: false,
+    unsigned: false,
+    extra: "",
+    maxLength: null,
+    numericPrecision: null,
+    numericScale: null,
+    datetimePrecision: null,
+    characterSetName: "utf8mb4",
+    collationName: "utf8mb4_general_ci",
+    enumValues: ["friendly", "unknown"]
+  });
+
+  assert.match(stringLine, /\.defaultTo\(""\)/);
+  assert.match(enumLine, /\.defaultTo\("unknown"\)/);
+});
+
+test("renderMigrationColumnLine preserves datetime precision", () => {
+  const line = __testables.renderMigrationColumnLine({
+    name: "deleted_at",
+    dataType: "datetime",
+    columnType: "datetime(3)",
+    typeKind: "datetime",
+    nullable: true,
+    hasDefault: false,
+    defaultValue: null,
+    autoIncrement: false,
+    unsigned: false,
+    extra: "",
+    maxLength: null,
+    numericPrecision: null,
+    numericScale: null,
+    datetimePrecision: 3,
+    characterSetName: "",
+    collationName: "",
+    enumValues: []
+  });
+
+  assert.match(line, /table\.dateTime\("deleted_at", \{ precision: 3 \}\)/);
+});
+
+test("buildReplacementsFromSnapshot preserves custom collations, hash unique indexes, and check constraints", () => {
+  const snapshot = createSnapshot({
+    tableName: "services",
+    hasWorkspaceIdColumn: true,
+    hasUserIdColumn: false
+  });
+  const replacements = __testables.buildReplacementsFromSnapshot({
+    snapshot: {
+      ...snapshot,
+      columns: Object.freeze([
+        snapshot.columns[0],
+        snapshot.columns[1],
+        Object.freeze({
+          name: "settings_json",
+          key: "settingsJson",
+          dataType: "longtext",
+          columnType: "longtext",
+          typeKind: "string",
+          nullable: true,
+          hasDefault: false,
+          defaultValue: null,
+          autoIncrement: false,
+          unsigned: false,
+          extra: "",
+          maxLength: null,
+          numericPrecision: null,
+          numericScale: null,
+          datetimePrecision: null,
+          characterSetName: "utf8mb4",
+          collationName: "utf8mb4_bin",
+          enumValues: Object.freeze([])
+        })
+      ]),
+      indexes: Object.freeze([
+        Object.freeze({
+          name: "uq_services_workspace_settings",
+          unique: true,
+          indexType: "HASH",
+          columns: Object.freeze(["workspace_id", "settings_json"])
+        })
+      ]),
+      foreignKeys: Object.freeze([]),
+      checkConstraints: Object.freeze([
+        Object.freeze({
+          name: "settings_json",
+          clause: "json_valid(`settings_json`)"
+        })
+      ])
+    },
+    resolvedOwnershipFilter: "workspace"
+  });
+
+  assert.match(
+    replacements.__JSKIT_CRUD_MIGRATION_COLUMN_LINES__,
+    /table\.specificType\("settings_json", "longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_bin"\)/
+  );
+  assert.match(
+    replacements.__JSKIT_CRUD_MIGRATION_INDEX_LINES__,
+    /storageEngineIndexType: "hash"/
+  );
+  assert.match(
+    replacements.__JSKIT_CRUD_MIGRATION_CHECK_CONSTRAINT_LINES__,
+    /ALTER TABLE `services` ADD CONSTRAINT `settings_json` CHECK \(json_valid\(`settings_json`\)\)/
+  );
+});
+
 test("buildReplacementsFromSnapshot normalizes nullable temporal inputs without invalid date errors", () => {
   const snapshot = createSnapshot({
-    hasWorkspaceOwnerColumn: false,
-    hasUserOwnerColumn: false
+    hasWorkspaceIdColumn: false,
+    hasUserIdColumn: false
   });
   const temporalColumns = [
     ...snapshot.columns.filter((column) => column.key !== "updatedAt"),

package/test/crudResource.test.js

@@ -31,7 +31,7 @@ test("crudResource normalizes list output", () => {
     nextCursor: " 8 "
   });
 
-  assert.equal(normalized.items[0].id, 7);
+  assert.equal(normalized.items[0].id, "7");
   assert.equal(normalized.items[0].textField, "Example text");
   assert.equal(normalized.items[0].dateField, "2026-03-10T00:00:00.000Z");
   assert.equal(normalized.items[0].numberField, 99);

package/test/packageDescriptor.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import descriptor from "../package.descriptor.mjs";
+
+test("crud-server-generator surface option validates against enabled surface ids", () => {
+  assert.equal(descriptor.kind, "generator");
+  assert.equal(descriptor.options?.surface?.validationType, "enabled-surface-id");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("surface"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.optionNames?.includes("force"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.createTarget?.pathTemplate, "packages/${option:namespace|kebab}");
+});
+
+test("crud-server-generator installs listConfig alongside server templates", () => {
+  const files = descriptor.mutations?.files || [];
+  const listConfigTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/listConfig.js");
+
+  assert.ok(listConfigTemplate);
+  assert.equal(
+    listConfigTemplate.to,
+    "packages/${option:namespace|kebab}/src/server/listConfig.js"
+  );
+  assert.deepEqual(listConfigTemplate.templateContext, {
+    entrypoint: "src/server/buildTemplateContext.js",
+    export: "buildTemplateContext"
+  });
+});