@stacksjs/database 0.70.88 → 0.70.91

package/dist/query-logger.js

@@ -0,0 +1,213 @@
+import { memoryUsage } from "node:process";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { parseQuery } from "./query-parser";
+import { db } from "./utils";
+let trackQuery = () => {};
+export function setQueryTracker(fn) {
+  trackQuery = fn;
+}
+let isLogging = !1;
+export async function logQuery(event) {
+  if (isLogging)
+    return;
+  try {
+    const { query, durationMs, error, bindings } = extractQueryInfo(event);
+    try {
+      trackQuery(query, durationMs, config.database?.default || "unknown");
+    } catch {}
+    if (!config.database?.queryLogging?.enabled)
+      return;
+    const status = determineQueryStatus(durationMs, error), logRecord = await createQueryLogRecord(query, durationMs, status, error, bindings);
+    if (config.database?.queryLogging?.analysis?.enabled && (status === "slow" || config.database.queryLogging.analysis.analyzeAll))
+      await enhanceWithQueryAnalysis(logRecord);
+    isLogging = !0;
+    try {
+      await storeQueryLog(logRecord);
+    } finally {
+      isLogging = !1;
+    }
+    if (status !== "completed")
+      log[status === "failed" ? "error" : "warn"](`Query ${status}:`, {
+        query: logRecord.query,
+        duration: logRecord.duration,
+        connection: logRecord.connection,
+        ...error && { error }
+      });
+  } catch (err) {
+    log.error("Failed to log query:", err);
+  }
+}
+function extractQueryInfo(event) {
+  const query = event.query?.sql || "", durationMs = event.queryDurationMillis || 0, error = event.error;
+  let bindings;
+  if (event.query?.parameters)
+    try {
+      bindings = JSON.stringify(event.query.parameters);
+    } catch {
+      bindings = "[]";
+    }
+  return { query, durationMs, error, bindings };
+}
+function determineQueryStatus(durationMs, error) {
+  const slowThreshold = config.database?.queryLogging?.slowThreshold || 100;
+  if (error)
+    return "failed";
+  if (durationMs > slowThreshold)
+    return "slow";
+  return "completed";
+}
+async function createQueryLogRecord(query, durationMs, status, error, bindings) {
+  const connection = config.database.default || "unknown", normalizedQuery = parseQuery(query).normalized || query, { trace, caller } = extractTraceInfo();
+  return {
+    query,
+    normalized_query: normalizedQuery,
+    duration: durationMs,
+    connection,
+    status,
+    error: error ? String(error) : void 0,
+    executed_at: new Date().toISOString(),
+    bindings,
+    trace,
+    ...caller,
+    memory_usage: memoryUsage().heapUsed / 1024 / 1024
+  };
+}
+const SECRET_PATTERNS = [
+  /\b(?:sk|pk|rk|api|secret|token|bearer|password|pwd|key)[_-]?[A-Za-z0-9]{12,}/gi,
+  /\bsk_(?:live|test)_[A-Za-z0-9]{20,}/g,
+  /\bAKIA[0-9A-Z]{16}/g,
+  /\b[A-Za-z0-9_-]{40,}\b(?=\s|$|['"])/g
+];
+function sanitizeStackTrace(stack) {
+  let out = stack;
+  for (const pattern of SECRET_PATTERNS)
+    out = out.replace(pattern, "<redacted>");
+  return out;
+}
+function extractTraceInfo() {
+  try {
+    const stack = Error("Stack trace capture").stack || "", callerLine = stack.split(`
+`).slice(1).find((line) => !line.includes("query-logger.ts"));
+    let caller = {};
+    if (callerLine) {
+      const methodMatch = callerLine.match(/at (.+?) \(/), fileMatch = callerLine.match(/\((.+?):(\d+):(\d+)\)/);
+      if (methodMatch && methodMatch[1]) {
+        const methodParts = methodMatch[1].split(".");
+        caller = {
+          model: methodParts.length > 1 ? methodParts[0] : void 0,
+          method: methodParts.length > 1 ? methodParts[1] : methodParts[0]
+        };
+      }
+      if (fileMatch && fileMatch[1] && fileMatch[2])
+        caller = {
+          ...caller,
+          file: fileMatch[1],
+          line: Number.parseInt(fileMatch[2], 10)
+        };
+    }
+    return {
+      trace: sanitizeStackTrace(stack),
+      caller
+    };
+  } catch {
+    return { trace: "", caller: {} };
+  }
+}
+async function enhanceWithQueryAnalysis(logRecord) {
+  try {
+    const { tables, type } = parseQuery(logRecord.query);
+    logRecord.affected_tables = JSON.stringify(tables || []);
+    if (type === "SELECT" && config.database?.queryLogging?.analysis?.explainPlan) {
+      const explainResult = await getExplainPlan(logRecord.query);
+      if (explainResult) {
+        logRecord.explain_plan = explainResult.plan;
+        logRecord.indexes_used = JSON.stringify(explainResult.indexesUsed || []);
+        logRecord.missing_indexes = JSON.stringify(explainResult.missingIndexes || []);
+        if (config.database?.queryLogging?.analysis?.suggestions)
+          logRecord.optimization_suggestions = JSON.stringify(generateOptimizationSuggestions(explainResult, logRecord));
+      }
+    }
+    const tags = [type];
+    if (tables && tables.length > 0)
+      tags.push(...tables.map((table) => `table:${table}`));
+    logRecord.tags = JSON.stringify(tags);
+  } catch (error) {
+    log.debug("Error during query analysis:", error);
+  }
+}
+const EXPLAIN_DIALECTS = new Set(["sqlite", "mysql", "postgres"]);
+async function getExplainPlan(query) {
+  try {
+    const rawDriver = (await import("@stacksjs/config")).config?.database?.default, driver = typeof rawDriver === "string" ? rawDriver : "sqlite";
+    if (!EXPLAIN_DIALECTS.has(driver))
+      return null;
+    let sqlText;
+    if (driver === "mysql")
+      sqlText = `EXPLAIN FORMAT=JSON ${query}`;
+    else if (driver === "postgres")
+      sqlText = `EXPLAIN (FORMAT JSON) ${query}`;
+    else
+      sqlText = `EXPLAIN QUERY PLAN ${query}`;
+    const result = await db.unsafe?.(sqlText);
+    if (!result)
+      return null;
+    const rows = Array.isArray(result) ? result : result.rows ?? [], planText = JSON.stringify(rows), indexesUsed = [], missingIndexes = [];
+    if (driver === "sqlite")
+      for (const row of rows) {
+        const detail = row?.detail || "", idxMatch = detail.match(/USING (?:COVERING )?INDEX (\w+)/i);
+        if (idxMatch && idxMatch[1])
+          indexesUsed.push(idxMatch[1]);
+        else {
+          const scanMatch = detail.match(/^SCAN\s+(\w+)/i);
+          if (scanMatch && scanMatch[1])
+            missingIndexes.push(scanMatch[1]);
+        }
+      }
+    else if (driver === "mysql") {
+      const text = planText;
+      for (const m of text.matchAll(/"key"\s*:\s*"([^"]+)"/g))
+        if (m[1])
+          indexesUsed.push(m[1]);
+      for (const m of text.matchAll(/"table_name"\s*:\s*"([^"]+)"[^}]*"access_type"\s*:\s*"ALL"/g))
+        if (m[1])
+          missingIndexes.push(m[1]);
+    } else if (driver === "postgres") {
+      const text = planText;
+      for (const m of text.matchAll(/"Index Name"\s*:\s*"([^"]+)"/g))
+        if (m[1])
+          indexesUsed.push(m[1]);
+      for (const m of text.matchAll(/"Node Type"\s*:\s*"Seq Scan"[^}]*"Relation Name"\s*:\s*"([^"]+)"/g))
+        if (m[1])
+          missingIndexes.push(m[1]);
+    }
+    return {
+      plan: planText.length > 4000 ? `${planText.slice(0, 4000)}\u2026` : planText,
+      indexesUsed: Array.from(new Set(indexesUsed)),
+      missingIndexes: Array.from(new Set(missingIndexes))
+    };
+  } catch (err) {
+    log.debug("[query-logger] EXPLAIN failed (non-fatal):", err);
+    return null;
+  }
+}
+function generateOptimizationSuggestions(explainResult, logRecord) {
+  const suggestions = [];
+  if (explainResult.missingIndexes && explainResult.missingIndexes.length > 0)
+    suggestions.push(`Consider adding index on ${explainResult.missingIndexes.join(", ")}`);
+  if (logRecord.status === "slow") {
+    suggestions.push("Consider optimizing this query to reduce execution time");
+    if (logRecord.query.toLowerCase().includes("select *"))
+      suggestions.push("Specify only needed columns instead of using SELECT *");
+    if (!logRecord.query.toLowerCase().includes("limit"))
+      suggestions.push("Consider adding LIMIT clause to reduce result set size");
+  }
+  return suggestions;
+}
+async function storeQueryLog(logRecord) {
+  try {
+    await db.insertInto("query_logs").values(logRecord).execute();
+  } catch (error) {
+    log.error("Failed to store query log:", error);
+  }
+}

package/dist/query-parser.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Parse and normalize a SQL query
+ */
+export declare function parseQuery(sql: string): { normalized: string, type: string, tables: string[] };

package/dist/query-parser.js

@@ -0,0 +1,93 @@
+export function parseQuery(sql) {
+  const result = {
+    normalized: "",
+    type: "OTHER",
+    tables: []
+  };
+  if (!sql)
+    return result;
+  try {
+    const upperQuery = sql.trim().toUpperCase();
+    if (upperQuery.startsWith("SELECT"))
+      result.type = "SELECT";
+    else if (upperQuery.startsWith("INSERT"))
+      result.type = "INSERT";
+    else if (upperQuery.startsWith("UPDATE"))
+      result.type = "UPDATE";
+    else if (upperQuery.startsWith("DELETE"))
+      result.type = "DELETE";
+    result.tables = extractTables(sql, result.type);
+    result.normalized = normalizeQuery(sql);
+    return result;
+  } catch {
+    return {
+      normalized: sql,
+      type: "OTHER",
+      tables: []
+    };
+  }
+}
+function buildIdentifierRegex(keyword, flags = "i") {
+  return new RegExp(`${keyword}\\s+(?:"([^"]+)"|\`([^\`]+)\`|\\[([^\\]]+)\\]|([\\w.]+))`, flags);
+}
+function pickMatchedIdentifier(match) {
+  if (!match)
+    return null;
+  const ident = match[1] ?? match[2] ?? match[3] ?? match[4];
+  if (!ident)
+    return null;
+  return ident.split(".").pop() ?? null;
+}
+function extractTables(sql, type) {
+  const tables = [];
+  try {
+    switch (type) {
+      case "SELECT": {
+        const fromMatch = sql.match(buildIdentifierRegex("from")), fromTable = pickMatchedIdentifier(fromMatch);
+        if (fromTable)
+          tables.push(fromTable);
+        const joinRegex = buildIdentifierRegex("join", "gi");
+        for (const m of sql.matchAll(joinRegex)) {
+          const joinTable = pickMatchedIdentifier(m);
+          if (joinTable)
+            tables.push(joinTable);
+        }
+        break;
+      }
+      case "INSERT": {
+        const intoMatch = sql.match(buildIdentifierRegex("into")), intoTable = pickMatchedIdentifier(intoMatch);
+        if (intoTable)
+          tables.push(intoTable);
+        break;
+      }
+      case "UPDATE": {
+        const updateMatch = sql.match(buildIdentifierRegex("update")), updateTable = pickMatchedIdentifier(updateMatch);
+        if (updateTable)
+          tables.push(updateTable);
+        break;
+      }
+      case "DELETE": {
+        const deleteFromMatch = sql.match(buildIdentifierRegex("from")), deleteTable = pickMatchedIdentifier(deleteFromMatch);
+        if (deleteTable)
+          tables.push(deleteTable);
+        break;
+      }
+    }
+  } catch {}
+  return [...new Set(tables)].filter(Boolean);
+}
+function normalizeQuery(sql) {
+  try {
+    let normalizedSql = sql;
+    normalizedSql = normalizedSql.replace(/(?<![a-zA-Z_])\b\d+\b(?![a-zA-Z_])/g, "?");
+    normalizedSql = normalizedSql.replace(/'([^']|'')*'/g, "?");
+    normalizedSql = normalizedSql.replace(/"([^"]|"")*"/g, "?");
+    normalizedSql = normalizedSql.replace(/\btrue\b/gi, "?");
+    normalizedSql = normalizedSql.replace(/\bfalse\b/gi, "?");
+    normalizedSql = normalizedSql.replace(/\bnull\b/gi, "?");
+    normalizedSql = normalizedSql.replace(/\s+/g, " ").trim();
+    return normalizedSql;
+  } catch {
+    return sql;
+  }
+}

package/dist/rbac-tables.d.ts

@@ -0,0 +1,17 @@
+import { sqlHelpers } from './sql-helpers';
+/** `roles` table — id + name + guard + timestamps with UNIQUE(name, guard_name). */
+export declare function rolesTableSql(sql: SqlHelpers): string;
+/** `permissions` table — same shape as `roles`. */
+export declare function permissionsTableSql(sql: SqlHelpers): string;
+/** `user_roles` pivot — composite PK makes double-assign a unique violation. */
+export declare function userRolesTableSql(): string;
+/** `user_permissions` pivot. */
+export declare function userPermissionsTableSql(): string;
+/** `role_permissions` pivot. */
+export declare function rolePermissionsTableSql(): string;
+/**
+ * Create the 5 RBAC tables. Idempotent (`IF NOT EXISTS`), so it's
+ * safe to run on every `buddy migrate`.
+ */
+export declare function migrateRbacTables(options?: { verbose?: boolean }): Promise<{ success: boolean, error?: string }>;
+declare type SqlHelpers = ReturnType<typeof sqlHelpers>;

package/dist/rbac-tables.js

@@ -0,0 +1,84 @@
+import { log } from "@stacksjs/logging";
+import { env as envVars } from "@stacksjs/env";
+import { db } from "./utils";
+import { sqlHelpers } from "./sql-helpers";
+function getDbDriver() {
+  return envVars.DB_CONNECTION || "sqlite";
+}
+export function rolesTableSql(sql) {
+  const { pkColumn, nullableTimestamp } = sql;
+  return `CREATE TABLE IF NOT EXISTS roles (
+    ${pkColumn},
+    name VARCHAR(255) NOT NULL,
+    guard_name VARCHAR(255) NOT NULL DEFAULT 'web',
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at ${nullableTimestamp},
+    UNIQUE (name, guard_name)
+  )`;
+}
+export function permissionsTableSql(sql) {
+  const { pkColumn, nullableTimestamp } = sql;
+  return `CREATE TABLE IF NOT EXISTS permissions (
+    ${pkColumn},
+    name VARCHAR(255) NOT NULL,
+    guard_name VARCHAR(255) NOT NULL DEFAULT 'web',
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at ${nullableTimestamp},
+    UNIQUE (name, guard_name)
+  )`;
+}
+export function userRolesTableSql() {
+  return `CREATE TABLE IF NOT EXISTS user_roles (
+    user_id INTEGER NOT NULL,
+    role_id INTEGER NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (user_id, role_id)
+  )`;
+}
+export function userPermissionsTableSql() {
+  return `CREATE TABLE IF NOT EXISTS user_permissions (
+    user_id INTEGER NOT NULL,
+    permission_id INTEGER NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (user_id, permission_id)
+  )`;
+}
+export function rolePermissionsTableSql() {
+  return `CREATE TABLE IF NOT EXISTS role_permissions (
+    role_id INTEGER NOT NULL,
+    permission_id INTEGER NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (role_id, permission_id)
+  )`;
+}
+export async function migrateRbacTables(options = {}) {
+  const dbDriver = getDbDriver(), sql = sqlHelpers(dbDriver);
+  if (options.verbose)
+    log.info(`Creating RBAC tables for ${dbDriver}...`);
+  try {
+    if (options.verbose)
+      log.info("Creating roles table...");
+    await db.unsafe(rolesTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating permissions table...");
+    await db.unsafe(permissionsTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating user_roles pivot...");
+    await db.unsafe(userRolesTableSql()).execute();
+    if (options.verbose)
+      log.info("Creating user_permissions pivot...");
+    await db.unsafe(userPermissionsTableSql()).execute();
+    if (options.verbose)
+      log.info("Creating role_permissions pivot...");
+    await db.unsafe(rolePermissionsTableSql()).execute();
+    if (options.verbose)
+      log.success("RBAC tables created");
+    return { success: !0 };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(`Failed to create RBAC tables: ${message}`);
+    return { success: !1, error: message };
+  }
+}

package/dist/safe-migrations.d.ts

@@ -0,0 +1,72 @@
+import { db } from './utils';
+/**
+ * Add a column to `tableName` without taking a table-level lock long
+ * enough to disrupt traffic. The column is created nullable, backfilled
+ * in batches, and (if `notNull: true`) the constraint is added at the
+ * end.
+ *
+ * Pre-conditions:
+ *   - `tableName` exists
+ *   - `columnName` does NOT already exist (this helper doesn't gracefully
+ *     handle the rerun case — wrap in `if (!columnExists)` if you need that)
+ *
+ * Caveats:
+ *   - SQLite doesn't support adding NOT NULL columns to existing tables
+ *     without a default; we work around it by always supplying one
+ *   - Postgres < 11 rewrites the entire table when a default is added;
+ *     this helper assumes ≥ 11
+ *
+ * @example
+ * ```ts
+ * await addColumnSafely(db, 'users', 'email_verified', {
+ *   type: 'boolean',
+ *   defaultValue: false,
+ *   notNull: true,
+ * })
+ * ```
+ */
+export declare function addColumnSafely(db: Database, tableName: string, columnName: string, options: AddColumnSafelyOptions): Promise<void>;
+/**
+ * Back-fill `columnName` with `value` for any row where it's currently
+ * NULL. Runs in batches so the UPDATE doesn't lock the entire table.
+ *
+ * Useful as a standalone helper when you want to backfill an *existing*
+ * column (e.g. populating a denormalized count) — `addColumnSafely`
+ * uses it internally.
+ */
+export declare function backfillInBatches(db: Database, tableName: string, columnName: string, value: string | number | boolean | null, batchSize?: number): Promise<void>;
+/**
+ * Rename a column safely on a table that's actively serving traffic.
+ *
+ * Most database engines DO support `RENAME COLUMN` as a metadata-only
+ * operation (no rewrite, no long lock), which means the headline
+ * concern is *application-side*: app code reads the old column name,
+ * the migration renames it, and the next request 500s.
+ *
+ * This helper wraps the rename in a multi-step sequence the framework
+ * docs can teach as the canonical pattern:
+ *
+ *   1. Add the new column
+ *   2. Backfill from old → new
+ *   3. Update writes to dual-write old AND new (app-level, deploy step)
+ *   4. Update reads to read from new (app-level, deploy step)
+ *   5. Drop the old column (separate migration)
+ *
+ * For the rare case where the rename *can* happen atomically (small
+ * table, no live traffic), pass `{ atomic: true }` and we'll just emit
+ * the RENAME COLUMN.
+ *
+ * @example
+ * ```ts
+ * // Step 1 of the rename sequence — the rest is app-side coordination.
+ * await renameColumnSafely(db, 'users', 'name', 'full_name', { type: 'varchar(255)' })
+ * ```
+ */
+export declare function renameColumnSafely(db: Database, tableName: string, oldName: string, newName: string, options: { type: string, atomic?: boolean }): Promise<void>;
+declare interface AddColumnSafelyOptions {
+  type: string
+  defaultValue?: string | number | boolean | null
+  notNull?: boolean
+  batchSize?: number
+}
+declare type Database = typeof db;

package/dist/safe-migrations.js

@@ -0,0 +1,59 @@
+import { db } from "./utils";
+import { sql } from "./types";
+export async function addColumnSafely(db, tableName, columnName, options) {
+  const { type, defaultValue, notNull = !1, batchSize = 1000 } = options, dbAny = db, defaultSql = defaultValue === void 0 ? "" : ` DEFAULT ${formatDefault(defaultValue)}`;
+  await execRaw(dbAny, `ALTER TABLE ${quote(tableName)} ADD COLUMN ${quote(columnName)} ${type}${defaultSql}`);
+  if (defaultValue !== void 0)
+    await backfillInBatches(db, tableName, columnName, defaultValue, batchSize);
+  if (notNull)
+    await execRaw(dbAny, `ALTER TABLE ${quote(tableName)} ALTER COLUMN ${quote(columnName)} SET NOT NULL`);
+}
+async function execRaw(dbAny, statement) {
+  if (typeof dbAny.unsafe === "function")
+    return await dbAny.unsafe(statement) ?? {};
+  await sql`${sql.raw(statement)}`.execute(dbAny);
+  return {};
+}
+export async function backfillInBatches(db, tableName, columnName, value, batchSize = 1000) {
+  const dbAny = db;
+  let updated = 0, total = 0;
+  do {
+    const batchSql = `
+      UPDATE ${quote(tableName)} SET ${quote(columnName)} = ${formatDefault(value)}
+      WHERE ${quote(columnName)} IS NULL
+        AND ${rowIdColumnFor(dbAny)} IN (
+          SELECT ${rowIdColumnFor(dbAny)} FROM ${quote(tableName)}
+          WHERE ${quote(columnName)} IS NULL
+          LIMIT ${batchSize}
+        )
+    `, result = await execRaw(dbAny, batchSql);
+    updated = result.numAffectedRows != null ? Number(result.numAffectedRows) : 0;
+    total += updated;
+  } while (updated > 0);
+}
+export async function renameColumnSafely(db, tableName, oldName, newName, options) {
+  const dbAny = db;
+  if (options.atomic) {
+    await execRaw(dbAny, `ALTER TABLE ${quote(tableName)} RENAME COLUMN ${quote(oldName)} TO ${quote(newName)}`);
+    return;
+  }
+  await execRaw(dbAny, `ALTER TABLE ${quote(tableName)} ADD COLUMN ${quote(newName)} ${options.type}`);
+  await execRaw(dbAny, `UPDATE ${quote(tableName)} SET ${quote(newName)} = ${quote(oldName)}`);
+}
+function quote(name) {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(name))
+    throw Error(`Refusing to quote unsafe identifier: ${JSON.stringify(name)}`);
+  return `"${name}"`;
+}
+function formatDefault(value) {
+  if (value === null)
+    return "NULL";
+  if (typeof value === "number")
+    return String(value);
+  if (typeof value === "boolean")
+    return value ? "TRUE" : "FALSE";
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+function rowIdColumnFor(_db) {
+  return "id";
+}

package/dist/schema.d.ts

@@ -0,0 +1,4 @@
+/** @defaultValue `{ createTable: () => Promise<unknown> }` */
+export declare const Schema: {
+  createTable: (tableName: string, callback: (table: Table) => void) => Promise<void>
+};

package/dist/schema.js

@@ -0,0 +1,10 @@
+import { log } from "@stacksjs/logging";
+import { Table } from "./table";
+export const Schema = {
+  async createTable(tableName, callback) {
+    const table = new Table;
+    callback(table);
+    table.execute();
+    log.success(`Table "${tableName}" created.`);
+  }
+};

package/dist/seed-scaffold.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Remove a single `useSeeder` / `seedable` object-property from model
+ * source text (stacksjs/stacks#1929). Brace-aware (balances nested
+ * `{}` and skips string literals) and conservative: only strips the
+ * documented value shapes (`true`, `false`, or a `{ … }` object). For
+ * anything else (an identifier, a function call, a spread) it returns
+ * `changed: false` so the caller can flag it for manual cleanup
+ * instead of risking a mangled file.
+ *
+ * Exported for unit tests.
+ */
+export declare function stripUseSeederTrait(source: string): { source: string, changed: boolean, skipped: boolean };
+/**
+ * Walk the configured models directory, find every model whose
+ * `traits.useSeeder` is truthy, and write a class-seeder file for it.
+ * Returns a structured report so the CLI command can render a summary
+ * without re-parsing log lines.
+ */
+export declare function scaffoldClassSeedersFromModels(options?: ScaffoldOptions): Promise<ScaffoldResult>;
+/** Pure renderer — exported for unit tests. */
+export declare function renderSeederFile(modelName: string, modelImportPath: string, count: number): string;
+export declare interface ScaffoldOptions {
+  modelsDir?: string
+  seedersDir?: string
+  force?: boolean
+  dryRun?: boolean
+}
+export declare interface ScaffoldResult {
+  generated: Array<{ model: string, file: string }>
+  skipped: Array<{ model: string, file: string, reason: 'already-exists' | 'no-useseeder' }>
+  errors: Array<{ model: string, error: string }>
+  strippedTrait: Array<{ model: string, file: string }>
+  traitStripSkipped: Array<{ model: string, file: string }>
+}