@jskit-ai/crud-server-generator 0.1.40 → 0.1.42

package/src/server/buildTemplateContext.js

@@ -5,23 +5,54 @@ import { pathToFileURL } from "node:url";
 import {
   normalizeText,
   resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment,
+  resolveKnexConnectionFromEnvironment,
   toKnexClientId
 } from "@jskit-ai/database-runtime/shared";
+import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
 import { checkCrudLookupFormControl } from "@jskit-ai/crud-core/shared/crudFieldMetaSupport";
+import {
+  importFreshModuleFromAbsolutePath,
+  loadAppConfigFromModuleUrl,
+  resolveRequiredAppRoot
+} from "@jskit-ai/kernel/server/support";
 import { normalizeCrudLookupNamespace } from "@jskit-ai/kernel/shared/support/crudLookup";
 import { toCamelCase, toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
+import descriptor from "../../package.descriptor.mjs";
 
 const DEFAULT_ID_COLUMN = "id";
-const OWNERSHIP_FILTER_AUTO = "auto";
-const OWNERSHIP_FILTER_VALUES = new Set([
-  OWNERSHIP_FILTER_AUTO,
-  "public",
-  "user",
-  "workspace",
-  "workspace_user"
-]);
+const DEFAULT_OWNERSHIP_FILTER_VALUES = Object.freeze(["auto", "public", "user", "workspace", "workspace_user"]);
 const MYSQL_CLIENT_ID = "mysql2";
+const CRUD_PERMISSION_OPERATIONS = Object.freeze(["list", "view", "create", "update", "delete"]);
+
+function resolveAllowedValues(schema = {}, fallbackValues = []) {
+  const resolvedValues = [];
+  const seen = new Set();
+  for (const rawValue of Array.isArray(schema?.allowedValues) ? schema.allowedValues : []) {
+    const value = normalizeText(typeof rawValue === "string" ? rawValue : rawValue?.value).toLowerCase();
+    if (!value || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    resolvedValues.push(value);
+  }
+  if (resolvedValues.length > 0) {
+    return Object.freeze(resolvedValues);
+  }
+  return Object.freeze(
+    (Array.isArray(fallbackValues) ? fallbackValues : [])
+      .map((value) => normalizeText(value).toLowerCase())
+      .filter(Boolean)
+  );
+}
+
+const OWNERSHIP_FILTER_ALLOWED_VALUES = resolveAllowedValues(
+  descriptor?.options?.["ownership-filter"],
+  DEFAULT_OWNERSHIP_FILTER_VALUES
+);
+const OWNERSHIP_FILTER_AUTO = normalizeText(
+  descriptor?.options?.["ownership-filter"]?.defaultValue
+).toLowerCase() || "auto";
+const OWNERSHIP_FILTER_VALUES = new Set(OWNERSHIP_FILTER_ALLOWED_VALUES);
 
 function resolveGlobalScaffoldCache() {
   const globalObject = globalThis;
@@ -54,15 +85,15 @@ function normalizeRequestedOwnershipFilter(value, { strict = false } = {}) {
   }
   if (strict) {
     throw new Error(
-      `Invalid ownership filter "${normalized || String(value || "")}". Use: auto, public, user, workspace, workspace_user.`
+      `Invalid ownership filter "${normalized || String(value || "")}". Use: ${OWNERSHIP_FILTER_ALLOWED_VALUES.join(", ")}.`
     );
   }
   return OWNERSHIP_FILTER_AUTO;
 }
 
 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 +107,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".'
     );
   }
 }
@@ -187,7 +218,7 @@ async function importModuleFromApp(appRequire, moduleId, contextLabel) {
   }
 
   try {
-    return await import(`${pathToFileURL(resolvedPath).href}?t=${Date.now()}_${Math.random()}`);
+    return await importFreshModuleFromAbsolutePath(resolvedPath);
   } catch (error) {
     throw new Error(
       `${contextLabel} failed loading "${moduleId}": ${String(error?.message || error || "unknown error")}`
@@ -195,6 +226,99 @@ async function importModuleFromApp(appRequire, moduleId, contextLabel) {
   }
 }
 
+async function resolveCrudSurfaceRequiresWorkspace({
+  appRoot,
+  options,
+  surface = ""
+} = {}) {
+  const namespace = normalizeText(options?.namespace);
+  const resolvedSurface = normalizeText(surface || options?.surface);
+  if (!namespace) {
+    throw new Error('crud template context requires option "namespace".');
+  }
+  if (!resolvedSurface) {
+    throw new Error('crud template context requires option "surface".');
+  }
+
+  const appConfig = await loadCrudAppConfig(appRoot);
+  const crudPolicy = resolveCrudSurfacePolicyFromAppConfig(
+    {
+      namespace,
+      surface: resolvedSurface,
+      ownershipFilter: options?.["ownership-filter"]
+    },
+    appConfig,
+    {
+      context: "crud template context"
+    }
+  );
+
+  return crudPolicy?.surfaceDefinition?.requiresWorkspace === true;
+}
+
+async function loadCrudAppConfig(appRoot = "") {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context: "crud template context"
+  });
+  return loadAppConfigFromModuleUrl({
+    moduleUrl: pathToFileURL(path.join(resolvedAppRoot, "config", "public.js")).href
+  });
+}
+
+function resolveSurfaceDefinitions(appConfig = {}) {
+  const definitions = asRecord(appConfig?.surfaceDefinitions);
+  const resolved = {};
+  for (const [key, rawValue] of Object.entries(definitions)) {
+    const definition = asRecord(rawValue);
+    const id = normalizeText(definition.id || key).toLowerCase();
+    if (!id) {
+      continue;
+    }
+    resolved[id] = Object.freeze({
+      id,
+      enabled: definition.enabled !== false,
+      requiresWorkspace: definition.requiresWorkspace === true
+    });
+  }
+  return Object.freeze(resolved);
+}
+
+function resolveDefaultCrudSurfaceIdFromAppConfig(appConfig = {}) {
+  const surfaceDefinitions = resolveSurfaceDefinitions(appConfig);
+  const enabledSurfaceDefinitions = Object.values(surfaceDefinitions).filter((entry) => entry.enabled === true);
+  const hasEnabledWorkspaceSurface = enabledSurfaceDefinitions.some((entry) => entry.requiresWorkspace === true);
+  if (hasEnabledWorkspaceSurface) {
+    return "";
+  }
+
+  const homeSurface = surfaceDefinitions.home;
+  if (homeSurface?.enabled === true && homeSurface.requiresWorkspace !== true) {
+    return "home";
+  }
+
+  return "";
+}
+
+async function resolveCrudGenerationSurfaceId({
+  appRoot,
+  options
+} = {}) {
+  const explicitSurface = normalizeText(options?.surface).toLowerCase();
+  if (explicitSurface) {
+    return explicitSurface;
+  }
+
+  const appConfig = await loadCrudAppConfig(appRoot);
+  const defaultSurface = resolveDefaultCrudSurfaceIdFromAppConfig(appConfig);
+  if (defaultSurface) {
+    return defaultSurface;
+  }
+
+  throw new Error(
+    'crud template context requires option "surface" when the app has any enabled workspace surface or no enabled non-workspace "home" surface.'
+  );
+}
+
 function resolveKnexFactory(moduleNamespace) {
   if (typeof moduleNamespace === "function") {
     return moduleNamespace;
@@ -221,7 +345,8 @@ async function resolveMysqlSnapshotFromDatabase({
     );
   }
 
-  const connection = resolveDatabaseConnectionFromEnvironment(env, {
+  const connection = resolveKnexConnectionFromEnvironment(env, {
+    client: dbClient,
     defaultPort: 3306,
     context: "crud table introspection"
   });
@@ -269,16 +394,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 +430,8 @@ function resolveScaffoldColumns(snapshot) {
       key,
       isOwnerColumn,
       isIdColumn,
+      isForeignIdColumn,
+      isRecordIdColumn,
       isCreatedAtColumn,
       isUpdatedAtColumn,
       writable: !isOwnerColumn && !isIdColumn && !isCreatedAtColumn && !isUpdatedAtColumn
@@ -327,9 +462,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 +492,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 +520,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 +547,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 +581,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 +676,7 @@ function renderResourceNormalizeSupportImport({
   needsNormalizeBoolean = false,
   needsNormalizeFiniteNumber = false,
   needsNormalizeFiniteInteger = false,
+  needsNormalizeRecordId = false,
   needsNormalizeIfInSource = false,
   needsNormalizeIfPresent = false,
   needsNormalizeOrNull = false
@@ -539,6 +694,9 @@ function renderResourceNormalizeSupportImport({
   if (needsNormalizeFiniteInteger) {
     imports.push("normalizeFiniteInteger");
   }
+  if (needsNormalizeRecordId) {
+    imports.push("normalizeRecordId");
+  }
   if (needsNormalizeIfInSource) {
     imports.push("normalizeIfInSource");
   }
@@ -596,15 +754,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 +815,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 +872,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 +897,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 +922,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 +997,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) {
@@ -1100,10 +1355,184 @@ function renderRepositoryListConfigLines(snapshot = {}) {
   ].join("\n");
 }
 
+function buildCrudPermissionIds(namespace = "") {
+  const permissionNamespace = toSnakeCase(namespace);
+  if (!permissionNamespace) {
+    return null;
+  }
+
+  return Object.freeze(
+    Object.fromEntries(
+      CRUD_PERMISSION_OPERATIONS.map((operation) => [operation, `crud.${permissionNamespace}.${operation}`])
+    )
+  );
+}
+
+function normalizeCrudOperation(operation = "", context = "CRUD operation") {
+  const normalizedOperation = normalizeText(operation).toLowerCase();
+  if (!CRUD_PERMISSION_OPERATIONS.includes(normalizedOperation)) {
+    throw new Error(`Unknown ${context} "${normalizedOperation || String(operation || "")}".`);
+  }
+  return normalizedOperation;
+}
+
+function renderRoleCatalogPermissionGrants(namespace = "", { requiresNamedPermissions = true } = {}) {
+  const permissionIds = buildCrudPermissionIds(namespace);
+  if (!requiresNamedPermissions || !permissionIds) {
+    return "";
+  }
+
+  return [
+    "roleCatalog.roles.member.permissions.push(",
+    `  ${JSON.stringify(permissionIds.list)},`,
+    `  ${JSON.stringify(permissionIds.view)},`,
+    `  ${JSON.stringify(permissionIds.create)},`,
+    `  ${JSON.stringify(permissionIds.update)},`,
+    `  ${JSON.stringify(permissionIds.delete)}`,
+    ");"
+  ].join("\n");
+}
+
+function renderActionPermissionSupport(namespace = "", { requiresNamedPermissions = true } = {}) {
+  if (!requiresNamedPermissions) {
+    return [
+      "const authenticatedPermission = Object.freeze({",
+      '  require: "authenticated"',
+      "});"
+    ].join("\n");
+  }
+
+  const permissionIds = buildCrudPermissionIds(namespace);
+  if (!permissionIds) {
+    return "";
+  }
+
+  return [
+    "const actionPermissions = Object.freeze({",
+    `  list: ${JSON.stringify(permissionIds.list)},`,
+    `  view: ${JSON.stringify(permissionIds.view)},`,
+    `  create: ${JSON.stringify(permissionIds.create)},`,
+    `  update: ${JSON.stringify(permissionIds.update)},`,
+    `  delete: ${JSON.stringify(permissionIds.delete)}`,
+    "});"
+  ].join("\n");
+}
+
+function renderActionPermissionExpression(operation = "", { requiresNamedPermissions = true } = {}) {
+  const normalizedOperation = normalizeCrudOperation(operation, "CRUD permission operation");
+
+  if (!requiresNamedPermissions) {
+    return "authenticatedPermission";
+  }
+
+  return `{ require: "all", permissions: [actionPermissions.${normalizedOperation}] }`;
+}
+
+function renderRouteWorkspaceSupportImports({ surfaceRequiresWorkspace = true } = {}) {
+  if (!surfaceRequiresWorkspace) {
+    return "";
+  }
+
+  return [
+    'import { routeParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";',
+    'import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/users-core/server/support/workspaceRouteInput";'
+  ].join("\n");
+}
+
+function renderActionWorkspaceValidatorImport({ surfaceRequiresWorkspace = true } = {}) {
+  if (!surfaceRequiresWorkspace) {
+    return "";
+  }
+
+  return 'import { workspaceSlugParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";';
+}
+
+function renderRouteParamsValidatorLine(operation = "", { surfaceRequiresWorkspace = true } = {}) {
+  const normalizedOperation = normalizeCrudOperation(operation, "CRUD route params validator operation");
+  if (normalizedOperation === "list" || normalizedOperation === "create") {
+    if (!surfaceRequiresWorkspace) {
+      return "";
+    }
+    return "      paramsValidator: routeParamsValidator,";
+  }
+
+  if (!surfaceRequiresWorkspace) {
+    return "      paramsValidator: recordIdParamsValidator,";
+  }
+
+  return "      paramsValidator: [routeParamsValidator, recordIdParamsValidator],";
+}
+
+function renderRouteInputLines(operation = "", { surfaceRequiresWorkspace = true } = {}) {
+  const normalizedOperation = normalizeCrudOperation(operation, "CRUD route input operation");
+  const lines = [];
+
+  if (surfaceRequiresWorkspace) {
+    lines.push("          ...buildWorkspaceInputFromRouteParams(request.input.params),");
+  }
+
+  if (normalizedOperation === "list") {
+    lines.push("          ...(request.input.query || {})");
+    return lines.join("\n");
+  }
+
+  if (normalizedOperation === "view") {
+    lines.push("          recordId: request.input.params.recordId,");
+    lines.push("          ...(request.input.query || {})");
+    return lines.join("\n");
+  }
+
+  if (normalizedOperation === "create") {
+    lines.push("          payload: request.input.body");
+    return lines.join("\n");
+  }
+
+  if (normalizedOperation === "update") {
+    lines.push("          recordId: request.input.params.recordId,");
+    lines.push("          patch: request.input.body");
+    return lines.join("\n");
+  }
+
+  lines.push("          recordId: request.input.params.recordId");
+  return lines.join("\n");
+}
+
+function renderActionInputValidatorExpression(operation = "", { surfaceRequiresWorkspace = true } = {}) {
+  const normalizedOperation = normalizeCrudOperation(operation, "CRUD action input validator operation");
+  const validators = [];
+
+  if (surfaceRequiresWorkspace) {
+    validators.push("workspaceSlugParamsValidator");
+  }
+
+  if (normalizedOperation === "list") {
+    validators.push(
+      "listCursorPaginationQueryValidator",
+      "listSearchQueryValidator",
+      "listParentFilterQueryValidator",
+      "lookupIncludeQueryValidator"
+    );
+  } else if (normalizedOperation === "view") {
+    validators.push("recordIdParamsValidator", "lookupIncludeQueryValidator");
+  } else if (normalizedOperation === "create") {
+    validators.push("{ payload: resource.operations.create.bodyValidator }");
+  } else if (normalizedOperation === "update") {
+    validators.push("recordIdParamsValidator", "{ patch: resource.operations.patch.bodyValidator }");
+  } else {
+    validators.push("recordIdParamsValidator");
+  }
+
+  return validators.length === 1 ? validators[0] : `[${validators.join(", ")}]`;
+}
+
 function buildReplacementsFromSnapshot({
+  namespace = "",
   snapshot,
-  resolvedOwnershipFilter
+  resolvedOwnershipFilter,
+  surfaceRequiresWorkspace = true,
+  surfaceId = ""
 }) {
+  const requiresNamedPermissions = surfaceRequiresWorkspace === true;
   const scaffoldColumns = resolveScaffoldColumns(snapshot);
   const outputColumns = scaffoldColumns.filter((column) => !column.isOwnerColumn);
   const writableColumns = scaffoldColumns.filter((column) => column.writable);
@@ -1116,7 +1545,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");
@@ -1143,9 +1573,84 @@ function buildReplacementsFromSnapshot({
   const replacements = Object.freeze({
     __JSKIT_CRUD_TABLE_NAME__: JSON.stringify(snapshot.tableName),
     __JSKIT_CRUD_ID_COLUMN__: JSON.stringify(snapshot.idColumn || DEFAULT_ID_COLUMN),
+    __JSKIT_CRUD_SURFACE_ID__: JSON.stringify(normalizeText(surfaceId).toLowerCase()),
     __JSKIT_CRUD_RESOLVED_OWNERSHIP_FILTER__: resolvedOwnershipFilter,
+    __JSKIT_CRUD_ACTION_PERMISSION_SUPPORT__: renderActionPermissionSupport(namespace, {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_ACTION_WORKSPACE_VALIDATOR_IMPORT__: renderActionWorkspaceValidatorImport({
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_LIST_ACTION_PERMISSION__: renderActionPermissionExpression("list", {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_LIST_ACTION_INPUT_VALIDATOR__: renderActionInputValidatorExpression("list", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_VIEW_ACTION_PERMISSION__: renderActionPermissionExpression("view", {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_VIEW_ACTION_INPUT_VALIDATOR__: renderActionInputValidatorExpression("view", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_CREATE_ACTION_PERMISSION__: renderActionPermissionExpression("create", {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_CREATE_ACTION_INPUT_VALIDATOR__: renderActionInputValidatorExpression("create", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_UPDATE_ACTION_PERMISSION__: renderActionPermissionExpression("update", {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_UPDATE_ACTION_INPUT_VALIDATOR__: renderActionInputValidatorExpression("update", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_DELETE_ACTION_PERMISSION__: renderActionPermissionExpression("delete", {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_DELETE_ACTION_INPUT_VALIDATOR__: renderActionInputValidatorExpression("delete", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_ROLE_CATALOG_PERMISSION_GRANTS__: renderRoleCatalogPermissionGrants(namespace, {
+      requiresNamedPermissions
+    }),
+    __JSKIT_CRUD_ROUTE_SURFACE_REQUIRES_WORKSPACE__: String(surfaceRequiresWorkspace === true),
+    __JSKIT_CRUD_ROUTE_WORKSPACE_SUPPORT_IMPORTS__: renderRouteWorkspaceSupportImports({
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_LIST_ROUTE_PARAMS_VALIDATOR_LINE__: renderRouteParamsValidatorLine("list", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_VIEW_ROUTE_PARAMS_VALIDATOR_LINE__: renderRouteParamsValidatorLine("view", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_CREATE_ROUTE_PARAMS_VALIDATOR_LINE__: renderRouteParamsValidatorLine("create", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_UPDATE_ROUTE_PARAMS_VALIDATOR_LINE__: renderRouteParamsValidatorLine("update", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_DELETE_ROUTE_PARAMS_VALIDATOR_LINE__: renderRouteParamsValidatorLine("delete", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_LIST_ROUTE_INPUT_LINES__: renderRouteInputLines("list", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_VIEW_ROUTE_INPUT_LINES__: renderRouteInputLines("view", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_CREATE_ROUTE_INPUT_LINES__: renderRouteInputLines("create", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_UPDATE_ROUTE_INPUT_LINES__: renderRouteInputLines("update", {
+      surfaceRequiresWorkspace
+    }),
+    __JSKIT_CRUD_DELETE_ROUTE_INPUT_LINES__: renderRouteInputLines("delete", {
+      surfaceRequiresWorkspace
+    }),
     __JSKIT_CRUD_RESOURCE_VALIDATORS_IMPORT__: renderResourceValidatorsImport({
-      needsHtmlTimeSchemas
+      needsHtmlTimeSchemas,
+      needsRecordIdSchemas
     }),
     __JSKIT_CRUD_RESOURCE_DATABASE_RUNTIME_IMPORT__: renderResourceDatabaseRuntimeImport({
       needsToIsoString: needsDateTimeOutput || needsDate,
@@ -1156,6 +1661,7 @@ function buildReplacementsFromSnapshot({
       needsNormalizeBoolean,
       needsNormalizeFiniteNumber: needsFiniteNumber,
       needsNormalizeFiniteInteger: needsFiniteInteger,
+      needsNormalizeRecordId: needsRecordIdSchemas,
       needsNormalizeIfInSource,
       needsNormalizeIfPresent,
       needsNormalizeOrNull
@@ -1176,7 +1682,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;
@@ -1199,11 +1706,16 @@ async function resolveGenerationSnapshot({
   });
 }
 
+function resolveCrudGenerationTableName(options = {}) {
+  return normalizeText(options?.["table-name"] || options?.namespace);
+}
+
 function createCacheKey({ appRoot, options }) {
   const payload = {
     appRoot: path.resolve(String(appRoot || "")),
     options: {
       namespace: normalizeText(options?.namespace),
+      surface: normalizeText(options?.surface),
       ownershipFilter: normalizeText(options?.["ownership-filter"]),
       tableName: normalizeText(options?.["table-name"]),
       idColumn: normalizeText(options?.["id-column"])
@@ -1221,10 +1733,14 @@ async function buildCrudTemplateContext(input = {}) {
   if (!namespace) {
     throw new Error('crud template context requires option "namespace".');
   }
-  const tableName = normalizeText(options["table-name"]);
+  const tableName = resolveCrudGenerationTableName(options);
   if (!tableName) {
     throw new Error('crud template context requires option "table-name".');
   }
+  const resolvedSurface = await resolveCrudGenerationSurfaceId({
+    appRoot,
+    options
+  });
   const snapshot = await resolveGenerationSnapshot({
     appRoot,
     tableName,
@@ -1238,10 +1754,18 @@ async function buildCrudTemplateContext(input = {}) {
       enforceTableColumns: true
     }
   );
+  const surfaceRequiresWorkspace = await resolveCrudSurfaceRequiresWorkspace({
+    appRoot,
+    options,
+    surface: resolvedSurface
+  });
 
   return buildReplacementsFromSnapshot({
+    namespace,
     snapshot,
-    resolvedOwnershipFilter
+    resolvedOwnershipFilter,
+    surfaceRequiresWorkspace,
+    surfaceId: resolvedSurface
   });
 }
 
@@ -1266,14 +1790,26 @@ const __testables = Object.freeze({
   buildReplacementsFromSnapshot,
   parseDotEnvLine,
   renderMigrationColumnLine,
+  renderMigrationCheckConstraintLines,
   renderMigrationForeignKeyLine,
   resolveScaffoldColumns,
   renderPropertyAccess,
   renderResourceFieldSchema,
   renderInputNormalizer,
   renderOutputNormalizerExpression,
+  resolveCrudGenerationTableName,
   resolveGenerationSnapshot,
-  buildFieldMetaEntries
+  buildFieldMetaEntries,
+  resolveDefaultCrudSurfaceIdFromAppConfig,
+  resolveCrudGenerationSurfaceId,
+  resolveCrudSurfaceRequiresWorkspace,
+  buildCrudPermissionIds,
+  renderRoleCatalogPermissionGrants,
+  renderActionPermissionSupport,
+  renderActionPermissionExpression,
+  renderActionInputValidatorExpression,
+  renderRouteParamsValidatorLine,
+  renderRouteInputLines
 });
 
 export {
@@ -1285,5 +1821,6 @@ export {
   renderInputNormalizer,
   renderOutputNormalizerExpression,
   buildFieldMetaEntries,
+  resolveCrudGenerationSurfaceId,
   __testables
 };