@mandujs/core 0.20.10 → 0.22.0

package/src/resource/generator-schema.ts

@@ -0,0 +1,476 @@
+/**
+ * Phase 4c — Schema + migration file orchestration.
+ *
+ * The piece of the generator that runs ONCE per project (not once per
+ * resource): computes the desired `Snapshot` from all persistent
+ * resources, diffs it against `applied.json`, and composes:
+ *
+ *   - Per-resource CREATE TABLE snapshots at
+ *     `.mandu/generated/server/schema/{table}.sql` (derived — docs for humans).
+ *   - An auto-generated migration file at
+ *     `spec/db/migrations/NNNN_auto_<timestamp>.sql` when changes exist.
+ *
+ * # Snapshot state model (pending vs applied)
+ *
+ * There is exactly ONE on-disk snapshot file: `.mandu/schema/applied.json`.
+ * Ownership:
+ *
+ *   - Agent C's migration runner WRITES it after a successful `mandu db apply`.
+ *   - This module (Agent D) only READS it.
+ *
+ * We deliberately do NOT maintain a separate `pending.json`. Rationale:
+ *   1. The "pending" state is ephemeral — it's whatever
+ *      `snapshotFromResources(resources)` returns right now. Persisting
+ *      it would create a third source of truth that could drift from
+ *      both the resource files and the migration file.
+ *   2. The migration file itself is the durable artifact. Its checksum
+ *      (computed by Agent C's runner) is what detects drift between
+ *      "what we planned" and "what was applied".
+ *   3. If the user runs `mandu db plan` twice without applying, we want
+ *      the second run to pick up the FIRST auto-migration that's still
+ *      pending and diff against THAT cumulatively, not re-emit the same
+ *      migration. This module implements that by considering only files
+ *      in the migrations dir that are not yet applied — see
+ *      `readPendingMigrationsCount`.
+ *
+ * # Filename sequencing
+ *
+ * `writeSchemaArtifacts` scans `spec/db/migrations` for the highest
+ * existing NNNN prefix, assigns NNNN+1, and never overwrites any file
+ * already present (respects `MIGRATION_FILE_RE` from the runner). User-
+ * edited migrations are sacred: the generator will only ever ADD new
+ * files at higher sequence numbers.
+ *
+ * # Path traversal defense (Phase 4c.R4 security audit — H-01)
+ *
+ * `tableName` originates from:
+ *   - `persistence.tableName` — validated by `asPersistence` (only
+ *     `[A-Za-z_][A-Za-z0-9_]*` accepted).
+ *   - `options.pluralName` — pre-4c field, NOT format-validated at
+ *     resource-load time.
+ *   - auto-pluralized `resource.name` — resource.name is validated by
+ *     `validateResourceDefinition` (same alphabet).
+ *
+ * To close the remaining gap (pluralName), `writeSchemaArtifacts`
+ * verifies every resolved table name against a conservative identifier
+ * regex AND asserts the `path.join` result stays under
+ * `resourceSchemaOutDir` before touching the filesystem. Same for the
+ * auto-migration file (whose name is NNNN + ISO timestamp, both under
+ * our control, but routed through the same guard for uniformity).
+ *
+ * # References
+ *
+ *   - docs/rfcs/0001-db-resource-layer.md §D3 (resource → DDL auto-derived)
+ *   - docs/rfcs/0001-db-resource-layer.md §D4 (self-rolled migration runner)
+ *   - docs/rfcs/0001-db-resource-layer.md Appendix D (post-4a normative)
+ *   - docs/security/phase-4c-audit.md §H-01 (path traversal remediation)
+ *   - packages/core/src/db/migrations/runner.ts (Agent C — applied.json owner)
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import type { ParsedResource } from "./parser";
+import type { Change, Snapshot, SqlProvider } from "./ddl/types";
+import { diffSnapshots } from "./ddl/diff";
+import { emitChanges, emitCreateTable, emitSchema } from "./ddl/emit";
+import { parseSnapshot, snapshotFromResources } from "./ddl/snapshot";
+import { resolveGeneratedPaths } from "../paths";
+
+// ============================================
+// Public API — types
+// ============================================
+
+/** The combined output of `computeSchemaGeneration`. */
+export interface SchemaGenerationResult {
+  /** The next snapshot that WOULD be applied (for logging / debugging). */
+  nextSnapshot: Snapshot;
+  /** Full desired schema SQL (all CREATE TABLE blocks concatenated). */
+  desiredSchema: string;
+  /** Per-resource CREATE TABLE slices keyed by table name. */
+  desiredSchemaByTable: Record<string, string>;
+  /** Changes vs `applied.json`; empty array if schema unchanged. */
+  changes: Change[];
+  /** Migration SQL body (without BEGIN/COMMIT); empty string if no changes. */
+  migrationSql: string;
+  /**
+   * Suggested migration filename (relative, `NNNN_auto_<ts>.sql`) — `null`
+   * when `changes` is empty. Final NNNN is assigned at write time by
+   * `writeSchemaArtifacts` which scans the migrations directory; this
+   * value is a preview and may differ if another process adds a file
+   * between `computeSchemaGeneration` and `writeSchemaArtifacts`.
+   */
+  migrationFilename: string | null;
+  /** Which provider the nextSnapshot targets. Mirror of `nextSnapshot.provider`. */
+  provider: SqlProvider;
+}
+
+/** The result of the write step. All fields absolute paths or booleans. */
+export interface WriteSchemaArtifactsResult {
+  /** Number of per-resource schema files written. */
+  schemaFilesWritten: number;
+  /** Absolute paths of every schema file written (may include overwrites). */
+  schemaFilePaths: string[];
+  /** Absolute path of the migration file written, or `null` if no changes. */
+  migrationFilePath: string | null;
+  /** The assigned NNNN for the migration (preserves the numeric sequence). */
+  migrationVersion: string | null;
+}
+
+// ============================================
+// Public API — compute
+// ============================================
+
+/**
+ * Compute the diff between the current resource files and the applied
+ * snapshot. Does NOT write anything to disk.
+ *
+ * Steps:
+ *   1. Filter to persistent resources via `snapshotFromResources`
+ *      (non-persistent resources are silently dropped).
+ *   2. Read `.mandu/schema/applied.json`. Missing → `null` → first-run.
+ *   3. Diff via `diffSnapshots`.
+ *   4. Compose SQL outputs.
+ *
+ * Throws if resources declare mixed providers (delegated to
+ * `snapshotFromResources`), or if applied.json exists but is malformed.
+ */
+export async function computeSchemaGeneration(
+  resources: readonly ParsedResource[],
+  rootDir: string,
+  /**
+   * Provider override — useful for CLI flags where the operator wants to
+   * generate DDL for a different target than what's declared in the
+   * resources (e.g. initial setup). When omitted, the provider is
+   * derived from the resources' persistence blocks. When resources
+   * conflict with the override, we THROW so the caller realizes they
+   * need to align the two.
+   */
+  provider?: SqlProvider,
+): Promise<SchemaGenerationResult> {
+  const nextSnapshot = snapshotFromResources(resources);
+  const paths = resolveGeneratedPaths(rootDir);
+
+  if (provider !== undefined && nextSnapshot.resources.length > 0 && nextSnapshot.provider !== provider) {
+    throw new TypeError(
+      `computeSchemaGeneration: provider override "${provider}" conflicts with ` +
+        `resource-declared provider "${nextSnapshot.provider}". Align persistence.provider on ` +
+        `your resources or drop the override.`,
+    );
+  }
+  if (provider !== undefined && nextSnapshot.resources.length === 0) {
+    // Empty resource set — override the fallback so the caller's intent is honored.
+    (nextSnapshot as { provider: SqlProvider }).provider = provider;
+  }
+
+  const applied = await readAppliedSnapshot(paths.schemaStateDir);
+
+  const changes = diffSnapshots(applied, nextSnapshot);
+
+  // Per-resource schema snippets (for the human-readable
+  // `.mandu/generated/server/schema/{table}.sql` files).
+  const desiredSchemaByTable: Record<string, string> = {};
+  for (const resource of nextSnapshot.resources) {
+    desiredSchemaByTable[resource.name] =
+      emitCreateTable(resource, nextSnapshot.provider);
+  }
+
+  const desiredSchema = emitSchema(nextSnapshot.resources, nextSnapshot.provider);
+  const migrationSql = changes.length > 0 ? composeMigrationSql(changes, nextSnapshot.provider) : "";
+
+  return {
+    nextSnapshot,
+    desiredSchema,
+    desiredSchemaByTable,
+    changes,
+    migrationSql,
+    migrationFilename:
+      changes.length > 0 ? previewMigrationFilename() : null,
+    provider: nextSnapshot.provider,
+  };
+}
+
+// ============================================
+// Public API — write
+// ============================================
+
+/**
+ * User-derived segment whitelist. Matches `SAFE_PERSISTENCE_IDENTIFIER_RE`
+ * from `ddl/persistence-types.ts`. Starts with a letter or `_`, then
+ * letters / digits / underscores only. No `.`, `/`, `\`, spaces, shell
+ * metachars, control chars — path traversal impossible.
+ *
+ * Applied to: per-resource `tableName` keys in `desiredSchemaByTable`,
+ * which can originate from `options.pluralName` or `persistence.tableName`.
+ * (Both ultimately flow through `snapshot.ts:resolveTableName`.)
+ */
+const SAFE_TABLE_FILE_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Generator-derived segment whitelist. The auto-migration filename is
+ * `${NNNN}_auto_${ISO_TIMESTAMP_WITH_DASHES}` where the ISO timestamp
+ * has had `:` + `.` replaced with `-`. The character set reduces to
+ * digits, `_`, `-`, `T`, `Z`. This segment is NEVER user-derived but
+ * the path guard is applied for uniformity.
+ */
+const SAFE_MIGRATION_FILE_SEGMENT_RE = /^[A-Za-z0-9_\-]+$/;
+
+/**
+ * Join `dir` + `segment + suffix` and ensure the resolved path stays
+ * strictly under `dir`. Validates `segment` against `allowRe` first
+ * (blocks `..`, `/`, `\`, control chars), then resolves and asserts
+ * containment as defense-in-depth.
+ *
+ * Defense-in-depth rationale (H-01 from Phase 4c audit):
+ *   - `asPersistence` catches malicious `tableName` / `columnName` /
+ *     `indexes[].name` at narrowing time.
+ *   - This check catches anything that slipped through — e.g.
+ *     `options.pluralName` (pre-4c, no runtime format check) — AND
+ *     asserts the resolved path never escapes `dir` even if a future
+ *     refactor loosens the regex.
+ */
+function safeJoinSegment(
+  dir: string,
+  segment: string,
+  suffix: string,
+  allowRe: RegExp,
+): string {
+  if (typeof segment !== "string" || segment.length === 0) {
+    throw new TypeError(`safeJoinSegment: segment must be a non-empty string`);
+  }
+  if (!allowRe.test(segment)) {
+    throw new Error(
+      `[@mandujs/core/resource] refused to write file whose name segment ${JSON.stringify(segment)} ` +
+        `does not match ${allowRe}. This blocks path-traversal via resource-derived names.`,
+    );
+  }
+  const joined = path.join(dir, `${segment}${suffix}`);
+  const resolvedDir = path.resolve(dir);
+  const resolvedJoin = path.resolve(joined);
+  // Must live strictly inside `resolvedDir` — i.e. share the exact
+  // prefix + path separator. The equality check on `path.join` guards
+  // against cross-platform resolution surprises (mixed separators,
+  // UNC paths on Windows).
+  if (
+    resolvedJoin !== path.join(resolvedDir, `${segment}${suffix}`) ||
+    !resolvedJoin.startsWith(resolvedDir + path.sep)
+  ) {
+    throw new Error(
+      `[@mandujs/core/resource] refused to write outside ${resolvedDir}: resolved path ${resolvedJoin}`,
+    );
+  }
+  return joined;
+}
+
+/**
+ * Write per-resource schema snippets and (if changes exist) a new
+ * migration file to disk.
+ *
+ * Guarantees:
+ *   - Never overwrites an existing `NNNN_*.sql` file in the migrations
+ *     directory. The next sequence number is assigned at write time
+ *     based on a fresh scan.
+ *   - `.mandu/schema/applied.json` is NEVER written from this module.
+ *     Agent C's migration runner owns that file and writes it only
+ *     after a successful `mandu db apply`. This keeps drift detection
+ *     meaningful: `applied.json` always reflects what the DB actually
+ *     has, not what we intended to apply.
+ *   - Creates parent directories as needed (`mkdir -p` semantics).
+ *   - Rejects any `tableName` / migration version that would resolve
+ *     outside the target directory (see `safeJoinSegment`).
+ *
+ * Returns the paths of written files so the caller can log / report to
+ * the user.
+ */
+export async function writeSchemaArtifacts(
+  result: SchemaGenerationResult,
+  rootDir: string,
+): Promise<WriteSchemaArtifactsResult> {
+  const paths = resolveGeneratedPaths(rootDir);
+
+  const schemaFilePaths: string[] = [];
+
+  if (Object.keys(result.desiredSchemaByTable).length > 0) {
+    await ensureDir(paths.resourceSchemaOutDir);
+    for (const [tableName, sql] of Object.entries(result.desiredSchemaByTable)) {
+      const filePath = safeJoinSegment(
+        paths.resourceSchemaOutDir,
+        tableName,
+        ".sql",
+        SAFE_TABLE_FILE_SEGMENT_RE,
+      );
+      // Schema files are DERIVED — always regenerate. Format the file
+      // with a header so human readers don't confuse it with a migration.
+      const body = `-- @generated by Mandu — do not edit.
+-- Source: spec/resources (resource definition)
+-- Regenerate with \`mandu generate\` or \`mandu db plan\`.
+--
+-- NOTE: This file is a SNAPSHOT of the current desired schema. It is
+-- NOT applied by the migration runner. For changes to reach your
+-- database, use the NNNN_*.sql files in spec/db/migrations instead.
+
+${sql}
+`;
+      await fs.writeFile(filePath, body, "utf8");
+      schemaFilePaths.push(filePath);
+    }
+  }
+
+  let migrationFilePath: string | null = null;
+  let migrationVersion: string | null = null;
+
+  if (result.migrationSql.length > 0 && result.changes.length > 0) {
+    await ensureDir(paths.migrationsDir);
+    const nextVersion = await findNextMigrationVersion(paths.migrationsDir);
+    // Timestamp chars are a fixed [0-9:T.-Z] subset from
+    // `new Date().toISOString()`; after the `[:.]` → `-` replacement
+    // only `[0-9T-Z]` remain — safe for a file segment. Auto-migration
+    // names are never user-derived but we route through `safeJoinSegment`
+    // for uniformity.
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const filenameSegment = `${nextVersion}_auto_${timestamp}`;
+    migrationFilePath = safeJoinSegment(
+      paths.migrationsDir,
+      filenameSegment,
+      ".sql",
+      SAFE_MIGRATION_FILE_SEGMENT_RE,
+    );
+    migrationVersion = nextVersion;
+
+    const body = `-- @generated by Mandu — human-editable.
+-- Auto-generated on: ${new Date().toISOString()}
+-- Changes detected: ${result.changes.length}
+-- Target provider:  ${result.provider}
+--
+-- This file was composed by \`mandu db plan\`. Review it, edit if
+-- necessary, and apply with \`mandu db apply\`. You own this file after
+-- it's created — the generator will NEVER overwrite it.
+
+${result.migrationSql}`;
+    await fs.writeFile(migrationFilePath, body, "utf8");
+  }
+
+  return {
+    schemaFilesWritten: schemaFilePaths.length,
+    schemaFilePaths,
+    migrationFilePath,
+    migrationVersion,
+  };
+}
+
+// ============================================
+// Internals — migration SQL composition
+// ============================================
+
+/**
+ * Wrap the sequence of `Change` → SQL emission with a transaction
+ * header/footer. SQLite uses `BEGIN` / `COMMIT` (plain) because its
+ * migration runner invokes each file via `db.transaction()` anyway —
+ * but the explicit BEGIN/COMMIT is harmless inside an already-open tx
+ * and makes the file runnable standalone via `sqlite3 foo.db < file.sql`.
+ */
+function composeMigrationSql(changes: readonly Change[], provider: SqlProvider): string {
+  const body = emitChanges(changes, provider);
+  if (body.length === 0) return "";
+  return `BEGIN;
+
+${body}
+
+COMMIT;`;
+}
+
+// ============================================
+// Internals — filesystem I/O
+// ============================================
+
+async function readAppliedSnapshot(schemaStateDir: string): Promise<Snapshot | null> {
+  const appliedPath = path.join(schemaStateDir, "applied.json");
+  let raw: string;
+  try {
+    raw = await fs.readFile(appliedPath, "utf8");
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") {
+      // First run — no applied snapshot yet. Diff engine accepts null
+      // and emits a `create-table` change per resource.
+      return null;
+    }
+    throw err;
+  }
+  try {
+    return parseSnapshot(raw);
+  } catch (err) {
+    // Malformed applied.json is operator-visible; rethrow with a hint.
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `[computeSchemaGeneration] Failed to parse ${appliedPath}: ${msg}. ` +
+        `Either revert the file to its prior state or delete it to force a full re-create.`,
+    );
+  }
+}
+
+/**
+ * Scan `spec/db/migrations/` and return the next zero-padded 4-digit
+ * sequence. First run → "0001". If existing files use wider padding
+ * (e.g. "12345_foo.sql"), the next returned version matches that width.
+ *
+ * Missing directory → "0001". Non-migration files in the directory are
+ * ignored — the regex matches the runner's.
+ */
+async function findNextMigrationVersion(migrationsDir: string): Promise<string> {
+  const re = /^(\d{4,})_[^/\\]+\.sql$/i;
+  let entries: string[];
+  try {
+    entries = await fs.readdir(migrationsDir);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return "0001";
+    throw err;
+  }
+
+  let max = 0;
+  let width = 4;
+  for (const entry of entries) {
+    const match = re.exec(entry);
+    if (!match) continue;
+    const version = match[1]!;
+    const n = Number.parseInt(version, 10);
+    if (Number.isFinite(n) && n > max) max = n;
+    if (version.length > width) width = version.length;
+  }
+
+  const next = (max + 1).toString();
+  // Zero-pad to width; if the new number exceeds the old width (overflow
+  // from e.g. 9999 → 10000), grow the width so padding remains consistent.
+  if (next.length > width) width = next.length;
+  return next.padStart(width, "0");
+}
+
+function previewMigrationFilename(): string {
+  // Preview is deliberately fuzzy: the real NNNN is assigned at write
+  // time in `writeSchemaArtifacts`. Consumers should treat this as
+  // informational only.
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  return `NNNN_auto_${ts}.sql`;
+}
+
+async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+// ============================================
+// Internals — test hooks
+// ============================================
+
+/**
+ * Exposed for unit tests ONLY. Consumers must NOT reach in here — these
+ * helpers are private API.
+ */
+export const _internalForTests = {
+  findNextMigrationVersion,
+  composeMigrationSql,
+  readAppliedSnapshot,
+  safeJoinSegment,
+  SAFE_TABLE_FILE_SEGMENT_RE,
+  SAFE_MIGRATION_FILE_SEGMENT_RE,
+};

package/src/resource/generator.ts

@@ -1,6 +1,13 @@
 /**
  * Resource Generator
  * Main orchestrator for generating resource artifacts
+ *
+ * Phase 4c extension: when a resource declares `options.persistence`, the
+ * orchestrator also emits a typed repo module (`*.repo.ts`) alongside the
+ * existing contract/types/slot/client artifacts. See `generator-repo.ts`
+ * for emission details; schema + migration generation is app-level and
+ * handled by `generateSchemaArtifacts` (separate entry point called by
+ * the CLI's `mandu db plan`).
  */
 
 import type { ParsedResource } from "./parser";
@@ -9,7 +16,15 @@ import { generateResourceContract } from "./generators/contract";
 import { generateResourceTypes } from "./generators/types";
 import { generateResourceSlot } from "./generators/slot";
 import { generateResourceClient } from "./generators/client";
+import { generateRepoSource, shouldEmitRepo } from "./generator-repo";
+import {
+  computeSchemaGeneration,
+  writeSchemaArtifacts,
+  type SchemaGenerationResult,
+  type WriteSchemaArtifactsResult,
+} from "./generator-schema";
 import { resolveGeneratedPaths } from "../paths";
+import type { SqlProvider } from "./ddl/types";
 import path from "path";
 import fs from "fs/promises";
 
@@ -23,7 +38,7 @@ export interface GeneratorOptions {
   /** 기존 슬롯 덮어쓰기 (기본: false) */
   force?: boolean;
   /** 특정 파일만 생성 */
-  only?: ("contract" | "types" | "slot" | "client")[];
+  only?: ("contract" | "types" | "slot" | "client" | "repo")[];
 }
 
 // ============================================
@@ -35,6 +50,12 @@ export interface GeneratorResult {
   created: string[];
   skipped: string[];
   errors: string[];
+  /**
+   * Phase 4c — set when a repo was emitted for this resource. When the
+   * resource has no `options.persistence`, this is `false` and no repo
+   * file is written.
+   */
+  repoEmitted?: boolean;
 }
 
 // ============================================
@@ -114,6 +135,11 @@ export async function generateResourceArtifacts(
     if (!only || only.includes("client")) {
       await generateClient(definition, resourceName, paths.resourceClientDir, result);
     }
+
+    // 5. Phase 4c — Generate Repo (only when persistence is declared, always regenerate)
+    if ((!only || only.includes("repo")) && shouldEmitRepo(parsed)) {
+      await generateRepo(parsed, paths.resourceReposDir, result);
+    }
   } catch (error) {
     result.success = false;
     result.errors.push(
@@ -210,6 +236,34 @@ async function generateClient(
   result.created.push(clientPath);
 }
 
+/**
+ * Phase 4c — Generate repo file.
+ *
+ * Always regenerate (derived). Caller is expected to have already checked
+ * `shouldEmitRepo(parsed)` to avoid emitting repos for non-persistent
+ * resources. We double-check here because `generateRepoSource` throws on
+ * non-persistent resources by default.
+ */
+async function generateRepo(
+  parsed: ParsedResource,
+  reposDir: string,
+  result: GeneratorResult
+): Promise<void> {
+  await ensureDir(reposDir);
+
+  const repoContent = generateRepoSource(parsed, { enable: false });
+  if (repoContent === null) {
+    // Non-persistent resource — caller should have filtered this out but
+    // we handle it gracefully.
+    return;
+  }
+
+  const repoPath = path.join(reposDir, `${parsed.definition.name}.repo.ts`);
+  await Bun.write(repoPath, repoContent);
+  result.created.push(repoPath);
+  result.repoEmitted = true;
+}
+
 // ============================================
 // Batch Generation
 // ============================================
@@ -247,6 +301,68 @@ export async function generateResourcesArtifacts(
   return combinedResult;
 }
 
+// ============================================
+// Phase 4c — App-level schema + migration orchestration
+// ============================================
+
+/**
+ * Options for `generateSchemaArtifacts`. All fields optional.
+ */
+export interface SchemaArtifactsOptions {
+  /**
+   * Project root. Required.
+   */
+  rootDir: string;
+  /**
+   * Provider override. When omitted, the provider is derived from the
+   * resources' persistence blocks. Pass this to generate DDL for a
+   * different target than what's declared in the resources (useful for
+   * CLI flags like `mandu db plan --provider sqlite`).
+   */
+  provider?: SqlProvider;
+  /**
+   * Dry-run mode: compute the diff + SQL but DO NOT write any files.
+   * The caller inspects the returned result and decides whether to persist.
+   */
+  dryRun?: boolean;
+}
+
+/**
+ * The combined result of an app-level schema generation pass.
+ */
+export interface SchemaArtifactsResult {
+  /** The computed diff / desired SQL / preview filename. */
+  generation: SchemaGenerationResult;
+  /** The actual write result, or `null` when `dryRun: true`. */
+  write: WriteSchemaArtifactsResult | null;
+}
+
+/**
+ * Run the schema + migration generation step for an entire project.
+ *
+ * This is distinct from `generateResourceArtifacts` which handles
+ * per-resource contract/slot/types/client/repo emission. Schema + migration
+ * are project-level because a single migration file aggregates changes
+ * across ALL persistent resources.
+ *
+ * Typical caller: `mandu db plan` in the CLI (Agent E).
+ *
+ * @returns The computed generation result and (unless `dryRun: true`)
+ *   the write result describing which files were created on disk.
+ */
+export async function generateSchemaArtifacts(
+  resources: ParsedResource[],
+  options: SchemaArtifactsOptions,
+): Promise<SchemaArtifactsResult> {
+  const { rootDir, provider, dryRun = false } = options;
+  const generation = await computeSchemaGeneration(resources, rootDir, provider);
+  if (dryRun) {
+    return { generation, write: null };
+  }
+  const write = await writeSchemaArtifacts(generation, rootDir);
+  return { generation, write };
+}
+
 // ============================================
 // Summary Logging
 // ============================================

package/src/resource/index.ts

@@ -30,13 +30,29 @@ export type { ParsedResource } from "./parser";
 export {
   generateResourceArtifacts,
   generateResourcesArtifacts,
+  generateSchemaArtifacts,
   logGeneratorResult,
 } from "./generator";
 
-export type { GeneratorOptions, GeneratorResult } from "./generator";
+export type {
+  GeneratorOptions,
+  GeneratorResult,
+  SchemaArtifactsOptions,
+  SchemaArtifactsResult,
+} from "./generator";
 
 // Individual Generators (for advanced use)
 export { generateResourceContract } from "./generators/contract";
 export { generateResourceTypes } from "./generators/types";
 export { generateResourceSlot } from "./generators/slot";
 export { generateResourceClient } from "./generators/client";
+export { generateRepoSource, shouldEmitRepo } from "./generator-repo";
+export type { RepoGenerationOptions } from "./generator-repo";
+export {
+  computeSchemaGeneration,
+  writeSchemaArtifacts,
+} from "./generator-schema";
+export type {
+  SchemaGenerationResult,
+  WriteSchemaArtifactsResult,
+} from "./generator-schema";