@lark-apaas/fullstack-cli 1.1.19 → 1.1.20

package/dist/gen-dbschema-template/types.ts

@@ -38,6 +38,60 @@ export const fileAttachment = customType<{
   },
 });
 
+/** Escape single quotes in SQL string literals */
+function escapeLiteral(str: string): string {
+  return `'${str.replace(/'/g, "''")}'`;
+}
+
+export const userProfileArray = customType<{
+  data: string[];
+  driverData: string;
+}>({
+  dataType() {
+    return 'user_profile[]';
+  },
+  toDriver(value: string[]) {
+    if (!value || value.length === 0) {
+      return sql`'{}'::user_profile[]`;
+    }
+    const elements = value.map(id => `ROW(${escapeLiteral(id)})::user_profile`).join(',');
+    return sql.raw(`ARRAY[${elements}]::user_profile[]`);
+  },
+  fromDriver(value: string): string[] {
+    if (!value || value === '{}') return [];
+    const inner = value.slice(1, -1);
+    const matches = inner.match(/\([^)]*\)/g) || [];
+    return matches.map(m => m.slice(1, -1).split(',')[0].trim());
+  },
+});
+
+export const fileAttachmentArray = customType<{
+  data: FileAttachment[];
+  driverData: string;
+}>({
+  dataType() {
+    return 'file_attachment[]';
+  },
+  toDriver(value: FileAttachment[]) {
+    if (!value || value.length === 0) {
+      return sql`'{}'::file_attachment[]`;
+    }
+    const elements = value.map(f =>
+      `ROW(${escapeLiteral(f.bucket_id)},${escapeLiteral(f.file_path)})::file_attachment`
+    ).join(',');
+    return sql.raw(`ARRAY[${elements}]::file_attachment[]`);
+  },
+  fromDriver(value: string): FileAttachment[] {
+    if (!value || value === '{}') return [];
+    const inner = value.slice(1, -1);
+    const matches = inner.match(/\([^)]*\)/g) || [];
+    return matches.map(m => {
+      const [bucketId, filePath] = m.slice(1, -1).split(',');
+      return { bucket_id: bucketId.trim(), file_path: filePath.trim() };
+    });
+  },
+});
+
 export const customTimestamptz = customType<{
   data: Date;
   driverData: string;

package/dist/index.js

@@ -472,6 +472,10 @@ var KNOWN_TYPE_FACTORIES = {
   user_profile: "userProfile",
   file_attachment: "fileAttachment"
 };
+var KNOWN_ARRAY_TYPE_FACTORIES = {
+  user_profile: "userProfileArray",
+  file_attachment: "fileAttachmentArray"
+};
 var replaceUnknownTransform = {
   name: "replace-unknown",
   transform(ctx) {
@@ -490,12 +494,17 @@ var replaceUnknownTransform = {
       const lines = textBefore.split("\n");
       let factoryName = "text";
       let foundKnownType = false;
+      let isArrayType = false;
       for (let i = lines.length - 1; i >= Math.max(0, lines.length - 5); i--) {
         const line = lines[i];
         const todoMatch = line.match(/\/\/ TODO: failed to parse database type '(?:\w+\.)?([\w_]+)(\[\])?'/);
         if (todoMatch) {
           const typeName = todoMatch[1];
-          if (KNOWN_TYPE_FACTORIES[typeName]) {
+          isArrayType = todoMatch[2] === "[]";
+          if (isArrayType && KNOWN_ARRAY_TYPE_FACTORIES[typeName]) {
+            factoryName = KNOWN_ARRAY_TYPE_FACTORIES[typeName];
+            foundKnownType = true;
+          } else if (KNOWN_TYPE_FACTORIES[typeName]) {
             factoryName = KNOWN_TYPE_FACTORIES[typeName];
             foundKnownType = true;
           }
@@ -503,6 +512,15 @@ var replaceUnknownTransform = {
         }
       }
       expression.replaceWithText(factoryName);
+      if (isArrayType && foundKnownType) {
+        const parent = node.getParent();
+        if (Node5.isPropertyAccessExpression(parent) && parent.getName() === "array") {
+          const grandParent = parent.getParent();
+          if (Node5.isCallExpression(grandParent)) {
+            grandParent.replaceWithText(node.getText());
+          }
+        }
+      }
       if (foundKnownType) {
         stats.replacedUnknown++;
       } else {
@@ -1005,6 +1023,139 @@ function resolveTemplateTypesPath() {
   return void 0;
 }
 
+// src/commands/db/gen-dbschema/utils/fetch-column-comments.ts
+import postgres from "postgres";
+var DEFAULT_TIMEOUT_MS = 1e4;
+async function fetchColumnComments(connectionString, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const url = new URL(connectionString);
+  const schemaName = url.searchParams.get("schema") ?? "public";
+  const sql = postgres(connectionString, {
+    connect_timeout: Math.ceil(timeoutMs / 1e3),
+    idle_timeout: Math.ceil(timeoutMs / 1e3)
+  });
+  try {
+    const queryPromise = sql`
+      SELECT
+        c.table_name AS "tableName",
+        c.column_name AS "columnName",
+        pgd.description AS "comment"
+      FROM information_schema.columns c
+      JOIN pg_catalog.pg_statio_all_tables st
+        ON c.table_name = st.relname AND c.table_schema = st.schemaname
+      JOIN pg_catalog.pg_description pgd
+        ON pgd.objoid = st.relid AND pgd.objsubid = c.ordinal_position
+      WHERE c.table_schema = ${schemaName}
+        AND pgd.description IS NOT NULL
+        AND pgd.description != ''
+    `;
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+    const result = await Promise.race([queryPromise, timeoutPromise]);
+    const commentMap = /* @__PURE__ */ new Map();
+    for (const row of result) {
+      const key = `${row.tableName}.${row.columnName}`;
+      commentMap.set(key, row.comment);
+    }
+    return commentMap;
+  } finally {
+    await sql.end().catch(() => {
+    });
+  }
+}
+function extractTypeAnnotation(comment) {
+  const typeStart = comment.indexOf("@type");
+  if (typeStart === -1) return null;
+  const afterType = comment.slice(typeStart + 5).trimStart();
+  if (!afterType.startsWith("{")) return null;
+  let depth = 0;
+  let endIndex = 0;
+  for (let i = 0; i < afterType.length; i++) {
+    if (afterType[i] === "{") depth++;
+    if (afterType[i] === "}") depth--;
+    if (depth === 0) {
+      endIndex = i + 1;
+      break;
+    }
+  }
+  if (endIndex === 0) return null;
+  return afterType.slice(0, endIndex);
+}
+function parseColumnComment(comment) {
+  const typeValue = extractTypeAnnotation(comment);
+  if (typeValue) {
+    const descMatch = comment.match(/@description\s+([^@]+)/);
+    return {
+      type: typeValue,
+      description: descMatch?.[1]?.trim()
+    };
+  }
+  return { description: comment.trim() };
+}
+
+// src/commands/db/gen-dbschema/transforms/text/jsonb-comments.ts
+function addJsonbTypeComments(source, columnComments) {
+  if (!columnComments || columnComments.size === 0) {
+    return { text: source, added: 0 };
+  }
+  const lines = source.split("\n");
+  const result = [];
+  let added = 0;
+  let currentTableName = null;
+  const tableDefRegex = /export const\s+\w+\s*=\s*pgTable\(\s*["'`]([^"'`]+)["'`]/;
+  const jsonFieldWithNameRegex = /^\s*(\w+):\s*(?:json|jsonb)\(\s*["'`]([^"'`]+)["'`]\)/;
+  const jsonFieldNoNameRegex = /^\s*(\w+):\s*(?:json|jsonb)\(\s*\)/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const tableMatch = line.match(tableDefRegex);
+    if (tableMatch) {
+      currentTableName = tableMatch[1];
+    }
+    let columnName = null;
+    const jsonMatchWithName = line.match(jsonFieldWithNameRegex);
+    const jsonMatchNoName = line.match(jsonFieldNoNameRegex);
+    if (jsonMatchWithName) {
+      columnName = jsonMatchWithName[2];
+    } else if (jsonMatchNoName) {
+      columnName = jsonMatchNoName[1];
+    }
+    if (columnName && currentTableName) {
+      const commentKey = `${currentTableName}.${columnName}`;
+      const comment = columnComments.get(commentKey);
+      if (comment) {
+        const parsed = parseColumnComment(comment);
+        const indentMatch = line.match(/^\s*/);
+        const indent = indentMatch ? indentMatch[0] : "";
+        const prevLine = result[result.length - 1]?.trim() ?? "";
+        if (!prevLine.startsWith("/**") && !prevLine.startsWith("*") && !prevLine.startsWith("//")) {
+          const commentLines = [];
+          commentLines.push(`${indent}/**`);
+          if (parsed.description) {
+            const safeDesc = parsed.description.replace(/[\r\n]+/g, " ").trim();
+            commentLines.push(`${indent} * ${safeDesc}`);
+          }
+          if (parsed.type) {
+            if (parsed.description) {
+              commentLines.push(`${indent} *`);
+            }
+            const safeType = parsed.type.replace(/[\r\n]+/g, " ").trim();
+            commentLines.push(`${indent} * @type ${safeType}`);
+          }
+          commentLines.push(`${indent} */`);
+          result.push(...commentLines);
+          added++;
+        }
+      }
+    }
+    if (line.match(/^\}\);?\s*$/) || line.match(/^}\s*,\s*\{/)) {
+      currentTableName = null;
+    }
+    result.push(line);
+  }
+  return { text: result.join("\n"), added };
+}
+
 // src/commands/db/gen-dbschema/transforms/text/table-aliases.ts
 var TABLE_ALIAS_MARKER = "// table aliases";
 function generateTableAliases(source) {
@@ -1041,7 +1192,7 @@ function formatSource(source) {
 }
 
 // src/commands/db/gen-dbschema/postprocess.ts
-function postprocessSchema(rawSource) {
+function postprocessSchema(rawSource, options = {}) {
   const patchResult = patchDefects(rawSource);
   let source = patchResult.text;
   const { sourceFile } = parseSource(source);
@@ -1051,12 +1202,15 @@ function postprocessSchema(rawSource) {
   source = ensureHeader(source);
   source = addSystemFieldComments(source);
   source = inlineCustomTypes(source);
+  const jsonbCommentsResult = addJsonbTypeComments(source, options.columnComments);
+  source = jsonbCommentsResult.text;
   source = generateTableAliases(source);
   source = formatSource(source);
   return {
     source,
     astStats,
-    patchedDefects: patchResult.fixed
+    patchedDefects: patchResult.fixed,
+    addedJsonbComments: jsonbCommentsResult.added
   };
 }
 function logStats(result, prefix = "[postprocess]") {
@@ -1103,17 +1257,20 @@ function logStats(result, prefix = "[postprocess]") {
   if (astStats.removedImports.length > 0) {
     console.info(`${prefix} Removed imports: ${astStats.removedImports.join(", ")}`);
   }
+  if (result.addedJsonbComments > 0) {
+    console.info(`${prefix} Added ${result.addedJsonbComments} JSDoc comments for jsonb fields`);
+  }
 }
 
 // src/commands/db/gen-dbschema/index.ts
-function postprocessDrizzleSchema(targetPath) {
+async function postprocessDrizzleSchema(targetPath, options = {}) {
   const resolvedPath = path.resolve(targetPath);
   if (!fs3.existsSync(resolvedPath)) {
     console.warn(`[postprocess-drizzle-schema] File not found: ${resolvedPath}`);
     return void 0;
   }
   const rawSource = fs3.readFileSync(resolvedPath, "utf8");
-  const result = postprocessSchema(rawSource);
+  const result = postprocessSchema(rawSource, { columnComments: options.columnComments });
   fs3.writeFileSync(resolvedPath, result.source, "utf8");
   logStats(result, "[postprocess-drizzle-schema]");
   return {
@@ -1122,7 +1279,8 @@ function postprocessDrizzleSchema(targetPath) {
     unmatchedUnknown: result.astStats.unmatchedUnknown,
     patchedDefects: result.patchedDefects,
     replacedTimestamps: result.astStats.replacedTimestamp,
-    replacedDefaultNow: result.astStats.replacedDefaultNow
+    replacedDefaultNow: result.astStats.replacedDefaultNow,
+    addedJsonbComments: result.addedJsonbComments
   };
 }
 
@@ -1847,6 +2005,16 @@ async function run(options = {}) {
     }
     throw new Error("Unable to locate drizzle-kit package root");
   };
+  let columnComments;
+  try {
+    columnComments = await fetchColumnComments(databaseUrl, { timeoutMs: 1e4 });
+    console.log(`[gen-db-schema] \u2713 Fetched ${columnComments.size} column comments`);
+  } catch (err) {
+    console.warn(
+      "[gen-db-schema] \u26A0 Failed to fetch column comments (skipping):",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
   try {
     const env = {
       ...process.env,
@@ -1870,7 +2038,9 @@ async function run(options = {}) {
       console.error("[gen-db-schema] schema.ts not generated");
       throw new Error("drizzle-kit introspect failed to generate schema.ts");
     }
-    const stats = postprocessDrizzleSchema(generatedSchema);
+    const stats = await postprocessDrizzleSchema(generatedSchema, {
+      columnComments
+    });
     if (stats?.unmatchedUnknown?.length) {
       console.warn("[gen-db-schema] Unmatched custom types detected:", stats.unmatchedUnknown);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",