@everystack/cli 0.3.12 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "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/runbook/detect.ts

@@ -12,6 +12,14 @@ import path from 'node:path';
 
 export type Tier = 'V1' | 'V2' | 'V3';
 
+/**
+ * How this app's migrations actually happen — detection, not aspiration.
+ * The discriminator for 'everystack' is the db:generate artifact
+ * (db/schema.generated.ts), not the presence of drizzle.config.ts: the
+ * reference app keeps legacy drizzle-kit tooling alongside the generated flow.
+ */
+export type MigrationMode = 'everystack' | 'transitional' | 'hand-authored';
+
 export interface ProjectReality {
   root: string;
   /** package.json name. */
@@ -36,6 +44,10 @@ export interface ProjectReality {
   hasExpoApp: boolean;
   /** Relative migrations dir ('drizzle' or 'db/migrations') or null. */
   migrationsDir: string | null;
+  /** The detected migration story, or null when the app has none yet. */
+  migrationMode: MigrationMode | null;
+  /** package.json scripts, in declaration order. */
+  scripts: Record<string, string>;
 }
 
 const V2_PACKAGES = new Set(['api', 'auth', 'admin', 'logging', 'security', 'query']);
@@ -111,6 +123,24 @@ export function detectProjectReality(root: string): ProjectReality {
       ? 'db/migrations'
       : null;
 
+  const hasModels = models.files.length > 0 || models.hasIndex;
+  const hasGeneratedSchema = isFile(path.join(abs, 'db', 'schema.generated.ts'));
+  const hasHandTooling = isFile(path.join(abs, 'drizzle.config.ts'));
+  const migrationMode: MigrationMode | null = hasModels
+    ? hasGeneratedSchema || (!migrationsDir && !hasHandTooling)
+      ? 'everystack'
+      : 'transitional'
+    : migrationsDir || hasHandTooling
+      ? 'hand-authored'
+      : null;
+
+  const scripts: Record<string, string> = {};
+  if (pkg.scripts && typeof pkg.scripts === 'object') {
+    for (const [name, cmd] of Object.entries(pkg.scripts)) {
+      if (typeof cmd === 'string') scripts[name] = cmd;
+    }
+  }
+
   return {
     root: abs,
     name: typeof pkg.name === 'string' && pkg.name ? pkg.name : path.basename(abs),
@@ -123,5 +153,7 @@ export function detectProjectReality(root: string): ProjectReality {
     hasSstConfig: isFile(path.join(abs, 'sst.config.ts')),
     hasExpoApp: isDir(path.join(abs, 'app')),
     migrationsDir,
+    migrationMode,
+    scripts,
   };
 }

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

@@ -80,7 +80,73 @@ function relationLine(name: string, rel: Relation): string {
   return `- \`${name}\` — ${shape} ${target} (via \`${rel.column}\`)`;
 }
 
-export function renderDataModelSection(models: ModelDescriptor[]): string {
+export interface DataModelOptions {
+  /** Above this many models the section renders as a summary. Default 16. */
+  threshold?: number;
+}
+
+const DEFAULT_THRESHOLD = 16;
+
+function nameList(tables: string[], cap = 15): string {
+  const shown = tables.slice(0, cap).map((t) => `\`${t}\``);
+  const rest = tables.length - cap;
+  return rest > 0 ? `${shown.join(', ')} (+${rest} more)` : shown.join(', ');
+}
+
+/**
+ * At scale (a 199-model brownfield pull) the full per-field render is reference
+ * material, not operations — ~5k lines nobody reads. Above the threshold we
+ * summarize per schema and keep the security-relevant signals (owner scoping,
+ * tables nobody can reach, operational tables), pointing at the real reference.
+ */
+function renderSummary(models: ModelDescriptor[]): string {
+  const bySchema = new Map<string, ModelDescriptor[]>();
+  for (const m of models) {
+    const schema = m.schema || 'public';
+    if (!bySchema.has(schema)) bySchema.set(schema, []);
+    bySchema.get(schema)!.push(m);
+  }
+  const lines: string[] = [
+    '## Your data model',
+    '',
+    `${models.length} models across ${bySchema.size} schema(s) — summarized; the full reference is`,
+    'the `models/` directory and `everystack db:authz:report`. Compiled from the Models — edit',
+    'them and regenerate; never edit this section.',
+  ];
+  for (const schema of [...bySchema.keys()].sort()) {
+    const group = bySchema.get(schema)!;
+    lines.push('', `### ${schema} — ${group.length} table(s)`, '');
+    const ownerScoped = group.filter((m) => m.abilities.some((a) => a.condition?.owner || a.condition?.via));
+    const anonReadable = group.filter((m) =>
+      m.abilities.some(
+        (a) =>
+          (a.action === 'read' || a.action === 'manage') &&
+          !a.condition?.role && !a.condition?.owner && !a.condition?.via &&
+          !a.condition?.where && !a.condition?.sql,
+      ),
+    );
+    const roleGated = group.filter((m) => m.abilities.some((a) => a.condition?.role));
+    const noAbilities = group.filter((m) => m.abilities.length === 0);
+    const operational = group.filter((m) => m.private || m.writtenBy !== 'app');
+    lines.push(
+      `- owner-scoped: ${ownerScoped.length} · anon-readable: ${anonReadable.length} · role-gated: ${roleGated.length}`,
+    );
+    if (noAbilities.length) {
+      lines.push(
+        `- no abilities declared (unreachable through the API): ${nameList(noAbilities.map((m) => m.table))}`,
+      );
+    }
+    if (operational.length) {
+      lines.push(
+        `- operational (private / non-app writers): ${nameList(operational.map((m) => m.table))}`,
+      );
+    }
+  }
+  return lines.join('\n');
+}
+
+export function renderDataModelSection(models: ModelDescriptor[], opts: DataModelOptions = {}): string {
+  if (models.length > (opts.threshold ?? DEFAULT_THRESHOLD)) return renderSummary(models);
   const lines: string[] = [
     '## Your data model',
     '',

package/src/cli/runbook/sections.ts

@@ -71,8 +71,24 @@ function projectMap(r: ProjectReality): Block {
       `- \`${r.models.dir}/\` — \`defineModel\` tables (${r.models.files.length} model(s); the source of truth for schema + authz)`,
     );
   }
-  if (r.hasDatabase) lines.push('- `db/` — generated Drizzle schema (never edit by hand)');
-  if (r.migrationsDir) lines.push(`- \`${r.migrationsDir}/\` — generated migrations`);
+  if (r.hasDatabase) {
+    lines.push(
+      r.migrationMode === 'everystack'
+        ? '- `db/` — generated Drizzle schema (never edit by hand)'
+        : r.migrationMode === 'transitional'
+          ? '- `db/` — Drizzle schema (migrating to Models; parts are still hand-maintained)'
+          : '- `db/` — Drizzle schema (hand-maintained)',
+    );
+  }
+  if (r.migrationsDir) {
+    lines.push(
+      r.migrationMode === 'everystack'
+        ? `- \`${r.migrationsDir}/\` — generated migrations`
+        : r.migrationMode === 'transitional'
+          ? `- \`${r.migrationsDir}/\` — migrations (hand-authored journal, moving to \`db:generate\`)`
+          : `- \`${r.migrationsDir}/\` — migrations (hand-authored via drizzle-kit)`,
+    );
+  }
   if (r.handlers.api || r.handlers.worker || r.handlers.image || r.crons.length) {
     const parts = [
       r.handlers.api ? 'api.ts' : null,
@@ -87,14 +103,24 @@ function projectMap(r: ProjectReality): Block {
   return gen('project-map', lines);
 }
 
-function dailyWorkflow(): Block {
-  return gen('daily-workflow', [
-    '## Daily workflow',
-    '',
-    '- `pnpm dev` — start the Expo dev server',
-    '- `pnpm test` — run the tests; every feature starts with a failing test',
-    '- Conventional commits (`feat:`, `fix:`, `chore:`, `docs:`); tests pass before commit',
-  ]);
+const SCRIPTS_MAX = 12;
+const SCRIPT_CMD_MAX = 64;
+
+function dailyWorkflow(r: ProjectReality): Block {
+  const lines = ['## Daily workflow', ''];
+  const entries = Object.entries(r.scripts);
+  for (const [name, cmd] of entries.slice(0, SCRIPTS_MAX)) {
+    const shown = cmd.length > SCRIPT_CMD_MAX ? `${cmd.slice(0, SCRIPT_CMD_MAX)}…` : cmd;
+    lines.push(`- \`pnpm ${name}\` — \`${shown}\``);
+  }
+  if (entries.length > SCRIPTS_MAX) {
+    lines.push(`- …and ${entries.length - SCRIPTS_MAX} more in \`package.json\``);
+  }
+  if (entries.length === 0) {
+    lines.push('- No scripts declared in `package.json` yet.');
+  }
+  lines.push('- Every feature starts with a failing test; conventional commits; tests pass before commit.');
+  return gen('daily-workflow', lines);
 }
 
 function deploy(r: ProjectReality): Block {
@@ -127,6 +153,13 @@ function extend(r: ProjectReality): Block {
       '- **Add a table or field:** edit the Model in `models/`, run `everystack db:generate`,',
       '  review the emitted migration, then `everystack db:migrate`. Never hand-write a SQL',
       '  migration, never edit `db/schema.ts` — after any change `db:generate` must be a clean no-op.',
+    );
+    if (r.migrationMode === 'transitional') {
+      lines.push(
+        '  _(Target flow — this app is migrating to Models and the hand-authored journal is being retired.)_',
+      );
+    }
+    lines.push(
       '- **Change who can read/write:** declare `can()` abilities on the Model — they compile',
       '  to RLS + grants. Never hand-write `CREATE POLICY` or `GRANT`.',
     );
@@ -158,10 +191,24 @@ function extend(r: ProjectReality): Block {
 }
 
 function database(r: ProjectReality): Block {
+  const flow =
+    r.migrationMode === 'everystack'
+      ? ['- `everystack db:generate` — compile Models → next migration (schema + RLS + grants)']
+      : r.migrationMode === 'transitional'
+        ? [
+            '- **Mid-migration to Models:** the journal is still hand-authored. Target flow is',
+            '  `everystack db:generate`; it must produce a clean, empty data diff before the',
+            '  generated flow takes over. Until then, review hand-written SQL like the liability it is.',
+          ]
+        : [
+            '- Migrations are hand-authored (drizzle-kit). The Models on-ramp: `everystack db:pull`',
+            '  writes `models/` from the live database; from there `everystack db:generate` compiles',
+            '  migrations (schema + RLS + grants) and hand-written SQL retires.',
+          ];
   return gen('database', [
     '## Database operations',
     '',
-    '- `everystack db:generate` — compile Models → next migration (schema + RLS + grants)',
+    ...flow,
     '- `everystack db:migrate --stage <name>` — apply migrations on the deployed Lambda',
     '- `everystack db:seed --stage dev` — seed the database (dev only)',
     '- `everystack db:psql --stage dev` — psql into the stage database (credentials never exposed)',
@@ -273,7 +320,7 @@ export function buildStructure(reality: ProjectReality, ctx: RunbookContext): Bl
     ),
     prerequisites(reality),
     projectMap(reality),
-    dailyWorkflow(),
+    dailyWorkflow(reality),
     deploy(reality),
     slot(
       'stage-notes',