@everystack/cli 0.3.10 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/model-render.ts

@@ -84,6 +84,13 @@ const FIELD_FACTORY: Record<string, string> = {
  * scale-0 numeric renders as the cleaner `field.numeric(p)` (identical to `(p, 0)`).
  */
 export function fieldFactoryCall(type: string): string | null {
+  // An array is its base type + `.array()` — exactly how the compiler emits it
+  // (`format_type` spells arrays `text[]`). An array of an unmapped base stays null.
+  if (type.endsWith('[]')) {
+    const base = fieldFactoryCall(type.slice(0, -2));
+    return base ? `${base}.array()` : null;
+  }
+
   const direct = FIELD_FACTORY[type];
   if (direct) return `field.${direct}()`;
 
@@ -124,9 +131,17 @@ export function modelVarName(table: string): string {
   return singular.split('_').filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
 }
 
-/** `author_id` → `authorId` (a SQL column to its camelCase field key — the inverse of the compiler's snake_case). */
+/**
+ * `author_id` → `authorId` — a SQL column to its field key, LOSSLESSLY: the compiler's
+ * snake_case must reconstruct the exact column (`snake(key) === column`, always). Only a
+ * letter after `_` camelizes, because only a capital letter survives the trip back — an
+ * underscore before a digit is preserved (`yardline_100` stays `yardline_100`,
+ * `top_3_best` → `top_3Best`). Swallowing it (the old `_([a-z0-9])` rule) generated a
+ * phantom rename for every digit-boundary column and COLLIDED distinct columns
+ * (`a_1` and `a1`) onto one key.
+ */
 function toCamelCase(name: string): string {
-  return name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
 
 /** The `.default*()` modifier for a column default, or null when the expression isn't one we map. */

package/src/cli/runbook/model-section.ts

@@ -0,0 +1,112 @@
+/**
+ * renderDataModelSection — the app's Models, rendered for the runbook.
+ *
+ * The one chapter no generic doc can carry: this app's tables, fields,
+ * relations, and declared abilities. Compiled from the same ModelDescriptors
+ * db:generate consumes, so it can never describe a schema the app doesn't
+ * have — and an ability change shows up as runbook drift (`runbook --check`).
+ */
+
+import type { Ability, FieldSpec, ModelDescriptor, Relation } from '@everystack/model';
+
+function typeLabel(spec: FieldSpec): string {
+  let base: string;
+  switch (spec.type) {
+    case 'varchar':
+      base = spec.length != null ? `varchar(${spec.length})` : 'varchar';
+      break;
+    case 'numeric':
+      base =
+        spec.precision != null
+          ? `numeric(${spec.precision}${spec.scale != null ? `, ${spec.scale}` : ''})`
+          : 'numeric';
+      break;
+    case 'enum':
+      base = spec.enumValues ? `enum(${spec.enumValues.join(' | ')})` : 'enum';
+      break;
+    default:
+      base = spec.type;
+  }
+  return spec.isArray ? `${base}[]` : base;
+}
+
+function referenceTarget(spec: FieldSpec): string | null {
+  if (!spec.references) return null;
+  try {
+    const target = spec.references() as { table?: string } | undefined;
+    return target?.table ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function fieldLine(name: string, spec: FieldSpec): string {
+  const parts = [typeLabel(spec)];
+  if (spec.isPrimaryKey) parts.push('pk');
+  if (spec.isNotNull && !spec.isPrimaryKey) parts.push('not null');
+  if (spec.isUnique) parts.push('unique');
+  const target = referenceTarget(spec);
+  if (target) {
+    parts.push(`→ ${target}${spec.onDelete && spec.onDelete !== 'no action' ? ` (${spec.onDelete})` : ''}`);
+  }
+  if (spec.defaultKind === 'now') parts.push('default: now()');
+  else if (spec.defaultKind === 'random') parts.push('default: random');
+  else if (spec.defaultKind === 'value') parts.push(`default: ${JSON.stringify(spec.default)}`);
+  if (spec.isPrivate) parts.push('private (never serialized)');
+  if (spec.isReadonly) parts.push('readonly (never writable via the API)');
+  return `- \`${name}\` — ${parts.join(', ')}`;
+}
+
+function abilityLine(a: Ability): string {
+  const verb = a.action === 'manage' ? 'manage (all actions)' : a.action;
+  const c = a.condition ?? {};
+  const scope: string[] = [];
+  if (c.role) scope.push(`role \`${c.role}\``);
+  if (c.owner) scope.push(`owner (\`${c.owner}\`)`);
+  if (c.via) scope.push(`owner via \`${c.via}\``);
+  if (c.where || c.sql) scope.push('custom predicate');
+  const columns = c.columns ? ` — columns: ${c.columns.map((col) => `\`${col}\``).join(', ')}` : '';
+  return `- ${verb}: ${scope.length ? scope.join(', ') : 'anyone'}${columns}`;
+}
+
+function relationLine(name: string, rel: Relation): string {
+  let target = 'unknown';
+  try {
+    target = rel.target().table;
+  } catch {
+    /* forward reference that can't resolve here — label stays unknown */
+  }
+  const shape = rel.kind === 'belongsTo' ? 'belongs to' : 'has many';
+  return `- \`${name}\` — ${shape} ${target} (via \`${rel.column}\`)`;
+}
+
+export function renderDataModelSection(models: ModelDescriptor[]): string {
+  const lines: string[] = [
+    '## Your data model',
+    '',
+    "Compiled from the app's Models — edit `models/` and regenerate; never edit this section.",
+  ];
+  for (const m of models) {
+    const heading = m.schema && m.schema !== 'public' ? `${m.schema}.${m.table}` : m.table;
+    lines.push('', `### ${heading}`, '');
+    const annotations: string[] = [];
+    if (m.private) annotations.push('not exposed via the generic API');
+    if (m.writtenBy !== 'app') annotations.push(`written by ${m.writtenBy}`);
+    if (annotations.length) lines.push(`_Operational table — ${annotations.join('; ')}._`, '');
+    for (const [name, builder] of Object.entries(m.fields)) {
+      lines.push(fieldLine(name, builder.spec));
+    }
+    const relations = Object.entries(m.relations ?? {});
+    if (relations.length) {
+      lines.push('', 'Relations:', '');
+      for (const [name, rel] of relations) lines.push(relationLine(name, rel));
+    }
+    lines.push('', 'Access:', '');
+    if (m.abilities.length === 0) {
+      lines.push('- no abilities declared — nobody can reach this table through the API');
+    } else {
+      for (const a of m.abilities) lines.push(abilityLine(a));
+    }
+  }
+  return lines.join('\n');
+}