@xubylele/schema-forge 1.12.1 → 1.13.0

package/dist/cli.js

@@ -30,11 +30,190 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// node_modules/@xubylele/schema-forge-core/dist/core/normalize.js
+function normalizeIdent(input) {
+  return input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+}
+function pkName(table) {
+  return `pk_${normalizeIdent(table)}`;
+}
+function uqName(table, column) {
+  return `uq_${normalizeIdent(table)}_${normalizeIdent(column)}`;
+}
+function legacyPkName(table) {
+  return `${normalizeIdent(table)}_pkey`;
+}
+function legacyUqName(table, column) {
+  return `${normalizeIdent(table)}_${normalizeIdent(column)}_key`;
+}
+function simpleHash(input) {
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index++) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+function hashSqlContent(value) {
+  return simpleHash(value);
+}
+function normalizeSqlExpression(value) {
+  if (!value) {
+    return "";
+  }
+  return normalizeSpacesOutsideQuotes(value);
+}
+function deterministicIndexName(params) {
+  const tableName = normalizeIdent(params.table) || "table";
+  const columnList = params.columns ?? [];
+  if (columnList.length > 0) {
+    const columnToken = columnList.map((column) => normalizeIdent(column) || "col").join("_").slice(0, 40);
+    return `idx_${tableName}_${columnToken}`;
+  }
+  const normalizedExpression = normalizeSqlExpression(params.expression);
+  const identExpr = normalizeIdent(normalizedExpression).slice(0, 24) || "expr";
+  const hash = simpleHash(normalizedExpression || params.expression || "").slice(0, 8);
+  return `idx_${tableName}_${identExpr}_${hash}`;
+}
+function normalizeSpacesOutsideQuotes(value) {
+  let result = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let pendingSpace = false;
+  for (const char of value) {
+    if (char === "'" && !inDoubleQuote) {
+      if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
+        result += " ";
+      }
+      pendingSpace = false;
+      inSingleQuote = !inSingleQuote;
+      result += char;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
+        result += " ";
+      }
+      pendingSpace = false;
+      inDoubleQuote = !inDoubleQuote;
+      result += char;
+      continue;
+    }
+    if (!inSingleQuote && !inDoubleQuote && /\s/.test(char)) {
+      pendingSpace = true;
+      continue;
+    }
+    if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
+      result += " ";
+    }
+    pendingSpace = false;
+    result += char;
+  }
+  return result.trim();
+}
+function normalizeKnownFunctionsOutsideQuotes(value) {
+  let result = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let buffer = "";
+  function flushBuffer() {
+    if (!buffer) {
+      return;
+    }
+    result += buffer.replace(/\bnow\s*\(\s*\)/gi, "now()").replace(/\bgen_random_uuid\s*\(\s*\)/gi, "gen_random_uuid()");
+    buffer = "";
+  }
+  for (const char of value) {
+    if (char === "'" && !inDoubleQuote) {
+      flushBuffer();
+      inSingleQuote = !inSingleQuote;
+      result += char;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      flushBuffer();
+      inDoubleQuote = !inDoubleQuote;
+      result += char;
+      continue;
+    }
+    if (inSingleQuote || inDoubleQuote) {
+      result += char;
+      continue;
+    }
+    buffer += char;
+  }
+  flushBuffer();
+  return result;
+}
+function normalizePunctuationOutsideQuotes(value) {
+  let result = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      result += char;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      result += char;
+      continue;
+    }
+    if (!inSingleQuote && !inDoubleQuote && (char === "(" || char === ")")) {
+      while (result.endsWith(" ")) {
+        result = result.slice(0, -1);
+      }
+      result += char;
+      let lookahead = index + 1;
+      while (lookahead < value.length && value[lookahead] === " ") {
+        lookahead++;
+      }
+      index = lookahead - 1;
+      continue;
+    }
+    if (!inSingleQuote && !inDoubleQuote && char === ",") {
+      while (result.endsWith(" ")) {
+        result = result.slice(0, -1);
+      }
+      result += ", ";
+      let lookahead = index + 1;
+      while (lookahead < value.length && value[lookahead] === " ") {
+        lookahead++;
+      }
+      index = lookahead - 1;
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}
+function normalizeDefault(expr) {
+  if (expr === void 0 || expr === null) {
+    return null;
+  }
+  const trimmed = expr.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const normalizedSpacing = normalizeSpacesOutsideQuotes(trimmed);
+  const normalizedPunctuation = normalizePunctuationOutsideQuotes(normalizedSpacing);
+  return normalizeKnownFunctionsOutsideQuotes(normalizedPunctuation);
+}
+var init_normalize = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/normalize.js"() {
+    "use strict";
+  }
+});
+
 // node_modules/@xubylele/schema-forge-core/dist/core/parser.js
 function parseSchema(source) {
   const lines = source.split("\n");
   const tables = {};
   const policyList = [];
+  const indexList = [];
+  const viewList = [];
   let currentLine = 0;
   const validBaseColumnTypes = /* @__PURE__ */ new Set([
     "uuid",
@@ -338,6 +517,48 @@ function parseSchema(source) {
     };
     return { policy, nextLineIndex: lineIdx };
   }
+  const policyDeclRegex = /^policy\s+"([^"]*)"\s+on\s+\w+/;
+  function parseViewDeclaration(startLine, options) {
+    const firstLine = cleanLine(lines[startLine]);
+    const declMatch = firstLine.match(/^view\s+(\w+)\s+as(?:\s+([\s\S]+))?$/);
+    if (!declMatch) {
+      throw new Error(`Line ${startLine + 1}: Invalid view declaration. Expected: view <name> as <sql>`);
+    }
+    const viewName = declMatch[1];
+    validateIdentifier(viewName, startLine + 1, "view");
+    const queryLines = [];
+    const inlineQuery = declMatch[2]?.trim();
+    if (inlineQuery) {
+      queryLines.push(inlineQuery);
+    }
+    let lineIdx = startLine + 1;
+    while (lineIdx < lines.length) {
+      const rawLine = lines[lineIdx];
+      const cleaned = cleanLine(rawLine);
+      if (!cleaned) {
+        if (queryLines.length > 0) {
+          queryLines.push("");
+        }
+        lineIdx++;
+        continue;
+      }
+      if (cleaned.startsWith("table ") || policyDeclRegex.test(cleaned) || cleaned.startsWith("index ") || cleaned.startsWith("view ") || options?.stopAtTableClose === true && cleaned === "}") {
+        break;
+      }
+      queryLines.push(rawLine.trim());
+      lineIdx++;
+    }
+    const query = queryLines.join("\n").trim();
+    if (!query) {
+      throw new Error(`Line ${startLine + 1}: View '${viewName}' is missing SQL query body`);
+    }
+    const view = {
+      name: viewName,
+      query,
+      hash: hashSqlContent(query)
+    };
+    return { view, nextLineIndex: lineIdx };
+  }
   function parseTableBlock(startLine) {
     const firstLine = cleanLine(lines[startLine]);
     const match = firstLine.match(/^table\s+(\w+)\s*\{\s*$/);
@@ -362,6 +583,12 @@ function parseSchema(source) {
         foundClosingBrace = true;
         break;
       }
+      if (cleaned.startsWith("view ")) {
+        const { view, nextLineIndex } = parseViewDeclaration(lineIdx, { stopAtTableClose: true });
+        viewList.push({ view, startLine: lineIdx + 1 });
+        lineIdx = nextLineIndex;
+        continue;
+      }
       try {
         const column = parseColumn(cleaned, lineIdx + 1);
         columns.push(column);
@@ -381,7 +608,129 @@ function parseSchema(source) {
     };
     return lineIdx;
   }
-  const policyDeclRegex = /^policy\s+"([^"]*)"\s+on\s+\w+/;
+  function parseIndexColumns(columnsRaw, lineNum) {
+    const parsed = columnsRaw.split(",").map((column) => column.trim()).filter(Boolean);
+    if (parsed.length === 0) {
+      throw new Error(`Line ${lineNum}: Index columns clause requires at least one column`);
+    }
+    for (const column of parsed) {
+      validateIdentifier(column, lineNum, "column");
+    }
+    return parsed;
+  }
+  function parseIndexDeclaration(startLine) {
+    const firstLine = cleanLine(lines[startLine]);
+    const inlineExprMatch = firstLine.match(/^index(?:\s+(\w+))?\s+on\s+(\w+)\s*\((.+)\)\s*$/);
+    if (inlineExprMatch) {
+      const name = inlineExprMatch[1];
+      const table2 = inlineExprMatch[2];
+      const expressionRaw = inlineExprMatch[3].trim();
+      if (name) {
+        validateIdentifier(name, startLine + 1, "column");
+      }
+      validateIdentifier(table2, startLine + 1, "table");
+      if (!expressionRaw) {
+        throw new Error(`Line ${startLine + 1}: Expression index requires a non-empty expression`);
+      }
+      const normalizedExpression = normalizeSqlExpression(expressionRaw);
+      const resolvedName2 = name ?? deterministicIndexName({ table: table2, expression: normalizedExpression });
+      return {
+        index: {
+          name: resolvedName2,
+          table: table2,
+          columns: [],
+          unique: false,
+          expression: normalizedExpression
+        },
+        nextLineIndex: startLine + 1
+      };
+    }
+    const blockMatch = firstLine.match(/^index(?:\s+(\w+))?\s+on\s+(\w+)\s*$/);
+    if (!blockMatch) {
+      throw new Error(`Line ${startLine + 1}: Invalid index declaration. Expected: index [name] on <table> or index [name] on <table>(<expression>)`);
+    }
+    const declaredName = blockMatch[1];
+    const table = blockMatch[2];
+    if (declaredName) {
+      validateIdentifier(declaredName, startLine + 1, "column");
+    }
+    validateIdentifier(table, startLine + 1, "table");
+    let lineIdx = startLine + 1;
+    let columns;
+    let unique = false;
+    let where;
+    let expression;
+    const seenClauses = /* @__PURE__ */ new Set();
+    while (lineIdx < lines.length) {
+      const cleaned = cleanLine(lines[lineIdx]);
+      if (!cleaned) {
+        lineIdx++;
+        continue;
+      }
+      if (cleaned.startsWith("table ") || cleaned.startsWith("policy ") || cleaned.startsWith("index ")) {
+        break;
+      }
+      if (cleaned === "unique") {
+        if (seenClauses.has("unique")) {
+          throw new Error(`Line ${lineIdx + 1}: Duplicate 'unique' in index declaration`);
+        }
+        seenClauses.add("unique");
+        unique = true;
+        lineIdx++;
+        continue;
+      }
+      if (cleaned.startsWith("columns ")) {
+        if (seenClauses.has("columns")) {
+          throw new Error(`Line ${lineIdx + 1}: Duplicate 'columns' in index declaration`);
+        }
+        seenClauses.add("columns");
+        columns = parseIndexColumns(cleaned.slice("columns ".length), lineIdx + 1);
+        lineIdx++;
+        continue;
+      }
+      if (cleaned.startsWith("where ")) {
+        if (seenClauses.has("where")) {
+          throw new Error(`Line ${lineIdx + 1}: Duplicate 'where' in index declaration`);
+        }
+        seenClauses.add("where");
+        where = normalizeSqlExpression(cleaned.slice("where ".length));
+        lineIdx++;
+        continue;
+      }
+      if (cleaned.startsWith("expression ")) {
+        if (seenClauses.has("expression")) {
+          throw new Error(`Line ${lineIdx + 1}: Duplicate 'expression' in index declaration`);
+        }
+        seenClauses.add("expression");
+        expression = normalizeSqlExpression(cleaned.slice("expression ".length));
+        lineIdx++;
+        continue;
+      }
+      throw new Error(`Line ${lineIdx + 1}: Unexpected index clause '${cleaned}'`);
+    }
+    if (columns && expression || !columns && !expression) {
+      throw new Error(`Line ${startLine + 1}: Index must define exactly one target kind: either 'columns' or 'expression'`);
+    }
+    if (expression !== void 0 && expression.trim().length === 0) {
+      throw new Error(`Line ${startLine + 1}: Expression index requires a non-empty expression`);
+    }
+    const resolvedName = declaredName ?? deterministicIndexName({
+      table,
+      columns,
+      expression
+    });
+    return {
+      index: {
+        name: resolvedName,
+        table,
+        columns: columns ?? [],
+        unique,
+        ...where !== void 0 && { where },
+        ...expression !== void 0 && { expression }
+      },
+      nextLineIndex: lineIdx
+    };
+  }
   while (currentLine < lines.length) {
     const cleaned = cleanLine(lines[currentLine]);
     if (!cleaned) {
@@ -395,10 +744,27 @@ function parseSchema(source) {
       const { policy, nextLineIndex } = parsePolicyBlock(currentLine);
       policyList.push({ policy, startLine: currentLine + 1 });
       currentLine = nextLineIndex;
+    } else if (cleaned.startsWith("index ")) {
+      const { index, nextLineIndex } = parseIndexDeclaration(currentLine);
+      indexList.push({ index, startLine: currentLine + 1 });
+      currentLine = nextLineIndex;
+    } else if (cleaned.startsWith("view ")) {
+      const { view, nextLineIndex } = parseViewDeclaration(currentLine);
+      viewList.push({ view, startLine: currentLine + 1 });
+      currentLine = nextLineIndex;
     } else {
-      throw new Error(`Line ${currentLine + 1}: Unexpected content '${cleaned}'. Expected table or policy definition.`);
+      throw new Error(`Line ${currentLine + 1}: Unexpected content '${cleaned}'. Expected table, index, view, or policy definition.`);
     }
   }
+  for (const { index, startLine } of indexList) {
+    if (!tables[index.table]) {
+      throw new Error(`Line ${startLine}: Index "${index.name}" references undefined table "${index.table}"`);
+    }
+    if (!tables[index.table].indexes) {
+      tables[index.table].indexes = [];
+    }
+    tables[index.table].indexes.push(index);
+  }
   for (const { policy, startLine } of policyList) {
     if (!tables[policy.table]) {
       throw new Error(`Line ${startLine}: Policy "${policy.name}" references undefined table "${policy.table}"`);
@@ -408,164 +774,27 @@ function parseSchema(source) {
     }
     tables[policy.table].policies.push(policy);
   }
-  return { tables };
+  const views = {};
+  for (const { view, startLine } of viewList) {
+    if (views[view.name]) {
+      throw new Error(`Line ${startLine}: Duplicate view definition '${view.name}'`);
+    }
+    views[view.name] = view;
+  }
+  return {
+    tables,
+    ...Object.keys(views).length > 0 && { views }
+  };
 }
 var POLICY_COMMANDS;
 var init_parser = __esm({
   "node_modules/@xubylele/schema-forge-core/dist/core/parser.js"() {
     "use strict";
+    init_normalize();
     POLICY_COMMANDS = ["select", "insert", "update", "delete", "all"];
   }
 });
 
-// node_modules/@xubylele/schema-forge-core/dist/core/normalize.js
-function normalizeIdent(input) {
-  return input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
-}
-function pkName(table) {
-  return `pk_${normalizeIdent(table)}`;
-}
-function uqName(table, column) {
-  return `uq_${normalizeIdent(table)}_${normalizeIdent(column)}`;
-}
-function legacyPkName(table) {
-  return `${normalizeIdent(table)}_pkey`;
-}
-function legacyUqName(table, column) {
-  return `${normalizeIdent(table)}_${normalizeIdent(column)}_key`;
-}
-function normalizeSpacesOutsideQuotes(value) {
-  let result = "";
-  let inSingleQuote = false;
-  let inDoubleQuote = false;
-  let pendingSpace = false;
-  for (const char of value) {
-    if (char === "'" && !inDoubleQuote) {
-      if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
-        result += " ";
-      }
-      pendingSpace = false;
-      inSingleQuote = !inSingleQuote;
-      result += char;
-      continue;
-    }
-    if (char === '"' && !inSingleQuote) {
-      if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
-        result += " ";
-      }
-      pendingSpace = false;
-      inDoubleQuote = !inDoubleQuote;
-      result += char;
-      continue;
-    }
-    if (!inSingleQuote && !inDoubleQuote && /\s/.test(char)) {
-      pendingSpace = true;
-      continue;
-    }
-    if (pendingSpace && result.length > 0 && result[result.length - 1] !== " ") {
-      result += " ";
-    }
-    pendingSpace = false;
-    result += char;
-  }
-  return result.trim();
-}
-function normalizeKnownFunctionsOutsideQuotes(value) {
-  let result = "";
-  let inSingleQuote = false;
-  let inDoubleQuote = false;
-  let buffer = "";
-  function flushBuffer() {
-    if (!buffer) {
-      return;
-    }
-    result += buffer.replace(/\bnow\s*\(\s*\)/gi, "now()").replace(/\bgen_random_uuid\s*\(\s*\)/gi, "gen_random_uuid()");
-    buffer = "";
-  }
-  for (const char of value) {
-    if (char === "'" && !inDoubleQuote) {
-      flushBuffer();
-      inSingleQuote = !inSingleQuote;
-      result += char;
-      continue;
-    }
-    if (char === '"' && !inSingleQuote) {
-      flushBuffer();
-      inDoubleQuote = !inDoubleQuote;
-      result += char;
-      continue;
-    }
-    if (inSingleQuote || inDoubleQuote) {
-      result += char;
-      continue;
-    }
-    buffer += char;
-  }
-  flushBuffer();
-  return result;
-}
-function normalizePunctuationOutsideQuotes(value) {
-  let result = "";
-  let inSingleQuote = false;
-  let inDoubleQuote = false;
-  for (let index = 0; index < value.length; index++) {
-    const char = value[index];
-    if (char === "'" && !inDoubleQuote) {
-      inSingleQuote = !inSingleQuote;
-      result += char;
-      continue;
-    }
-    if (char === '"' && !inSingleQuote) {
-      inDoubleQuote = !inDoubleQuote;
-      result += char;
-      continue;
-    }
-    if (!inSingleQuote && !inDoubleQuote && (char === "(" || char === ")")) {
-      while (result.endsWith(" ")) {
-        result = result.slice(0, -1);
-      }
-      result += char;
-      let lookahead = index + 1;
-      while (lookahead < value.length && value[lookahead] === " ") {
-        lookahead++;
-      }
-      index = lookahead - 1;
-      continue;
-    }
-    if (!inSingleQuote && !inDoubleQuote && char === ",") {
-      while (result.endsWith(" ")) {
-        result = result.slice(0, -1);
-      }
-      result += ", ";
-      let lookahead = index + 1;
-      while (lookahead < value.length && value[lookahead] === " ") {
-        lookahead++;
-      }
-      index = lookahead - 1;
-      continue;
-    }
-    result += char;
-  }
-  return result;
-}
-function normalizeDefault(expr) {
-  if (expr === void 0 || expr === null) {
-    return null;
-  }
-  const trimmed = expr.trim();
-  if (trimmed.length === 0) {
-    return null;
-  }
-  const normalizedSpacing = normalizeSpacesOutsideQuotes(trimmed);
-  const normalizedPunctuation = normalizePunctuationOutsideQuotes(normalizedSpacing);
-  return normalizeKnownFunctionsOutsideQuotes(normalizedPunctuation);
-}
-var init_normalize = __esm({
-  "node_modules/@xubylele/schema-forge-core/dist/core/normalize.js"() {
-    "use strict";
-  }
-});
-
 // node_modules/@xubylele/schema-forge-core/dist/core/diff.js
 function getTableNamesFromState(state) {
   return new Set(Object.keys(state.tables));
@@ -610,6 +839,62 @@ function policyEquals(oldP, newP) {
     return false;
   return true;
 }
+function resolveSchemaIndexName(index) {
+  if (index.name && index.name.trim().length > 0) {
+    return index.name.trim();
+  }
+  return deterministicIndexName({
+    table: index.table,
+    columns: index.columns,
+    expression: index.expression
+  });
+}
+function resolveStateIndexName(index) {
+  if (index.name && index.name.trim().length > 0) {
+    return index.name.trim();
+  }
+  return deterministicIndexName({
+    table: index.table,
+    columns: index.columns,
+    expression: index.expression
+  });
+}
+function normalizeIndexWhere(value) {
+  return normalizeSqlExpression(value);
+}
+function normalizeIndexExpression(value) {
+  return normalizeSqlExpression(value);
+}
+function indexesEqual(previous, current) {
+  if (previous.table !== current.table)
+    return false;
+  if ((previous.unique ?? false) !== (current.unique ?? false))
+    return false;
+  if (previous.columns.length !== current.columns.length)
+    return false;
+  for (let index = 0; index < previous.columns.length; index++) {
+    if (previous.columns[index] !== current.columns[index]) {
+      return false;
+    }
+  }
+  if (normalizeIndexWhere(previous.where) !== normalizeIndexWhere(current.where))
+    return false;
+  if (normalizeIndexExpression(previous.expression) !== normalizeIndexExpression(current.expression))
+    return false;
+  return true;
+}
+function resolveStateViewHash(view) {
+  if (view.hash && view.hash.trim().length > 0) {
+    return view.hash;
+  }
+  return hashSqlContent(view.query);
+}
+function resolveSchemaViewHash(view) {
+  if (view.hash && view.hash.trim().length > 0) {
+    return view.hash;
+  }
+  return hashSqlContent(view.query);
+}
 function diffSchemas(oldState, newSchema) {
   const operations = [];
   const oldTableNames = getTableNamesFromState(oldState);
@@ -622,6 +907,15 @@ function diffSchemas(oldState, newSchema) {
         kind: "create_table",
         table: newSchema.tables[tableName]
       });
+      const createdTable = newSchema.tables[tableName];
+      const createdIndexes = (createdTable.indexes ?? []).map((index) => ({ ...index, name: resolveSchemaIndexName(index) })).sort((left, right) => left.name.localeCompare(right.name));
+      for (const index of createdIndexes) {
+        operations.push({
+          kind: "create_index",
+          tableName,
+          index
+        });
+      }
     }
   }
   const commonTableNames = sortedNewTableNames.filter((tableName) => oldTableNames.has(tableName));
@@ -765,7 +1059,66 @@ function diffSchemas(oldState, newSchema) {
       operations.push({
         kind: "add_primary_key_constraint",
         tableName,
-        columnName: currentPrimaryKey
+        columnName: currentPrimaryKey
+      });
+    }
+  }
+  for (const tableName of commonTableNames) {
+    const newTable = newSchema.tables[tableName];
+    const oldTable = oldState.tables[tableName];
+    if (!newTable || !oldTable) {
+      continue;
+    }
+    const oldIndexes = oldTable.indexes ?? {};
+    const newIndexesByName = /* @__PURE__ */ new Map();
+    for (const index of newTable.indexes ?? []) {
+      const resolved = { ...index, name: resolveSchemaIndexName(index) };
+      newIndexesByName.set(resolved.name, resolved);
+    }
+    const oldIndexesByName = /* @__PURE__ */ new Map();
+    for (const oldIndex of Object.values(oldIndexes)) {
+      oldIndexesByName.set(resolveStateIndexName(oldIndex), oldIndex);
+    }
+    const oldIndexNames = Array.from(oldIndexesByName.keys()).sort((a, b) => a.localeCompare(b));
+    const newIndexNames = Array.from(newIndexesByName.keys()).sort((a, b) => a.localeCompare(b));
+    const indexDrops = [];
+    const indexCreates = [];
+    for (const oldIndexName of oldIndexNames) {
+      const oldIndex = oldIndexesByName.get(oldIndexName);
+      if (!oldIndex) {
+        continue;
+      }
+      const nextIndex = newIndexesByName.get(oldIndexName);
+      if (!nextIndex) {
+        indexDrops.push({ ...oldIndex, name: oldIndexName });
+        continue;
+      }
+      if (!indexesEqual(oldIndex, nextIndex)) {
+        indexDrops.push({ ...oldIndex, name: oldIndexName });
+      }
+    }
+    for (const newIndexName of newIndexNames) {
+      const newIndex = newIndexesByName.get(newIndexName);
+      if (!newIndex) {
+        continue;
+      }
+      const oldIndex = oldIndexesByName.get(newIndexName);
+      if (!oldIndex || !indexesEqual(oldIndex, newIndex)) {
+        indexCreates.push(newIndex);
+      }
+    }
+    for (const index of indexDrops) {
+      operations.push({
+        kind: "drop_index",
+        tableName,
+        index
+      });
+    }
+    for (const index of indexCreates) {
+      operations.push({
+        kind: "create_index",
+        tableName,
+        index
       });
     }
   }
@@ -817,6 +1170,36 @@ function diffSchemas(oldState, newSchema) {
       }
     }
   }
+  const oldViews = oldState.views ?? {};
+  const newViews = newSchema.views ?? {};
+  const oldViewNames = Object.keys(oldViews).sort((a, b) => a.localeCompare(b));
+  const newViewNames = Object.keys(newViews).sort((a, b) => a.localeCompare(b));
+  const oldViewNameSet = new Set(oldViewNames);
+  const newViewNameSet = new Set(newViewNames);
+  for (const viewName of newViewNames) {
+    const nextView = newViews[viewName];
+    if (!nextView) {
+      continue;
+    }
+    if (!oldViewNameSet.has(viewName)) {
+      operations.push({ kind: "create_view", view: nextView });
+      continue;
+    }
+    const prevView = oldViews[viewName];
+    if (!prevView) {
+      continue;
+    }
+    const oldHash = resolveStateViewHash(prevView);
+    const newHash = resolveSchemaViewHash(nextView);
+    if (oldHash !== newHash) {
+      operations.push({ kind: "replace_view", view: nextView });
+    }
+  }
+  for (const viewName of oldViewNames) {
+    if (!newViewNameSet.has(viewName)) {
+      operations.push({ kind: "drop_view", viewName });
+    }
+  }
   for (const tableName of sortedOldTableNames) {
     if (!newTableNames.has(tableName)) {
       operations.push({
@@ -916,9 +1299,52 @@ function validateSchema(schema) {
   for (const tableName in schema.tables) {
     const table = schema.tables[tableName];
     validateTableColumns(tableName, table, schema.tables);
+    validateTableIndexes(tableName, table, schema.tables);
   }
   validatePolicies(schema);
 }
+function validateTableIndexes(tableName, table, allTables) {
+  if (!table.indexes?.length) {
+    return;
+  }
+  const normalizedNames = /* @__PURE__ */ new Set();
+  for (const index of table.indexes) {
+    validateSingleIndex(tableName, table, index, allTables);
+    const effectiveName = index.name?.trim() || deterministicIndexName({
+      table: index.table,
+      columns: index.columns,
+      expression: index.expression
+    });
+    if (normalizedNames.has(effectiveName)) {
+      throw new Error(`Table '${tableName}': duplicate index name '${effectiveName}'`);
+    }
+    normalizedNames.add(effectiveName);
+  }
+}
+function validateSingleIndex(tableName, table, index, allTables) {
+  if (!allTables[index.table]) {
+    throw new Error(`Table '${tableName}': index '${index.name}' references table '${index.table}' which does not exist`);
+  }
+  if (index.table !== tableName) {
+    throw new Error(`Table '${tableName}': index '${index.name}' must target table '${tableName}'`);
+  }
+  const hasColumns = index.columns.length > 0;
+  const hasExpression = index.expression !== void 0;
+  if (hasColumns && hasExpression || !hasColumns && !hasExpression) {
+    throw new Error(`Table '${tableName}': index '${index.name}' must define exactly one of columns or expression`);
+  }
+  if (hasExpression && index.expression.trim().length === 0) {
+    throw new Error(`Table '${tableName}': index '${index.name}' expression cannot be empty`);
+  }
+  if (hasColumns) {
+    const tableColumns = new Set(table.columns.map((column) => column.name));
+    for (const columnName of index.columns) {
+      if (!tableColumns.has(columnName)) {
+        throw new Error(`Table '${tableName}': index '${index.name}' references unknown column '${columnName}'`);
+      }
+    }
+  }
+}
 function validateDuplicateTables(schema) {
   const tableNames = Object.keys(schema.tables);
   const seen = /* @__PURE__ */ new Set();
@@ -997,6 +1423,7 @@ var VALID_POLICY_COMMANDS, VALID_BASE_COLUMN_TYPES;
 var init_validator = __esm({
   "node_modules/@xubylele/schema-forge-core/dist/core/validator.js"() {
     "use strict";
+    init_normalize();
     VALID_POLICY_COMMANDS = [
       "select",
       "insert",
@@ -1097,12 +1524,22 @@ function classifyOperation(operation) {
       return "DESTRUCTIVE";
     case "add_primary_key_constraint":
       return "SAFE";
+    case "create_index":
+      return "SAFE";
+    case "drop_index":
+      return "WARNING";
     case "create_policy":
       return "SAFE";
     case "drop_policy":
       return "DESTRUCTIVE";
     case "modify_policy":
       return "WARNING";
+    case "create_view":
+      return "SAFE";
+    case "drop_view":
+      return "DESTRUCTIVE";
+    case "replace_view":
+      return "WARNING";
     default:
       const _exhaustive = operation;
       return _exhaustive;
@@ -1225,6 +1662,14 @@ function checkOperationSafety(operation) {
         message: "Primary key constraint removed",
         operationKind: operation.kind
       };
+    case "drop_index":
+      return {
+        safetyLevel,
+        code: "DROP_INDEX",
+        table: operation.tableName,
+        message: `Index '${operation.index.name}' removed`,
+        operationKind: operation.kind
+      };
     case "drop_policy":
       return {
         safetyLevel,
@@ -1241,6 +1686,22 @@ function checkOperationSafety(operation) {
         message: "Policy expression changed",
         operationKind: operation.kind
       };
+    case "drop_view":
+      return {
+        safetyLevel,
+        code: "DROP_VIEW",
+        table: operation.viewName,
+        message: "View removed",
+        operationKind: operation.kind
+      };
+    case "replace_view":
+      return {
+        safetyLevel,
+        code: "REPLACE_VIEW",
+        table: operation.view.name,
+        message: "View definition changed",
+        operationKind: operation.kind
+      };
     default:
       return null;
   }
@@ -1402,6 +1863,7 @@ var init_fs = __esm({
 // node_modules/@xubylele/schema-forge-core/dist/core/state-transform.js
 async function schemaToState(schema) {
   const tables = {};
+  let views;
   for (const [tableName, table] of Object.entries(schema.tables)) {
     const columns = {};
     const primaryKeyColumn = table.primaryKey ?? table.columns.find((column) => column.primaryKey)?.name ?? null;
@@ -1426,15 +1888,40 @@ async function schemaToState(schema) {
         };
       }
     }
+    let indexes;
+    if (table.indexes?.length) {
+      indexes = {};
+      for (const index of table.indexes) {
+        indexes[index.name] = {
+          name: index.name,
+          table: index.table,
+          columns: [...index.columns],
+          unique: index.unique,
+          ...index.where !== void 0 && { where: index.where },
+          ...index.expression !== void 0 && { expression: index.expression }
+        };
+      }
+    }
     tables[tableName] = {
       columns,
       ...primaryKeyColumn !== null && { primaryKey: primaryKeyColumn },
+      ...indexes !== void 0 && { indexes },
       ...policies !== void 0 && { policies }
     };
   }
+  if (schema.views && Object.keys(schema.views).length > 0) {
+    views = {};
+    for (const [viewName, view] of Object.entries(schema.views)) {
+      views[viewName] = {
+        query: view.query,
+        hash: view.hash
+      };
+    }
+  }
   return {
     version: 1,
-    tables
+    tables,
+    ...views !== void 0 && { views }
   };
 }
 var init_state_transform = __esm({
@@ -1463,6 +1950,242 @@ var init_state_manager = __esm({
   }
 });
 
+// node_modules/@xubylele/schema-forge-core/dist/core/plan-builder.js
+function toAction(operation) {
+  switch (operation.kind) {
+    case "create_table":
+    case "add_column":
+    case "add_primary_key_constraint":
+    case "create_index":
+    case "create_policy":
+    case "create_view":
+      return "create";
+    case "drop_table":
+    case "drop_column":
+    case "drop_primary_key_constraint":
+    case "drop_index":
+    case "drop_policy":
+    case "drop_view":
+      return "delete";
+    case "column_type_changed":
+    case "column_nullability_changed":
+    case "column_default_changed":
+    case "column_unique_changed":
+    case "modify_policy":
+    case "replace_view":
+      return "modify";
+    default: {
+      const exhaustiveCheck = operation;
+      return exhaustiveCheck;
+    }
+  }
+}
+function actionToSymbol(action) {
+  if (action === "create") {
+    return "+";
+  }
+  if (action === "modify") {
+    return "~";
+  }
+  return "-";
+}
+function formatNullable(value) {
+  return value ? "nullable" : "not null";
+}
+function formatUnique(value) {
+  return value ? "unique" : "not unique";
+}
+function formatDefault(value) {
+  if (value === null) {
+    return "null";
+  }
+  return value;
+}
+function toEntry(operation) {
+  const action = toAction(operation);
+  const symbol = actionToSymbol(action);
+  switch (operation.kind) {
+    case "create_table":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `create table ${operation.table.name}`,
+        tableName: operation.table.name
+      };
+    case "drop_table":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop table ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "add_column":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `add column ${operation.column.name} to ${operation.tableName}`,
+        tableName: operation.tableName,
+        columnName: operation.column.name
+      };
+    case "drop_column":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop column ${operation.columnName} from ${operation.tableName}`,
+        tableName: operation.tableName,
+        columnName: operation.columnName
+      };
+    case "column_type_changed":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `modify column ${operation.columnName} type on ${operation.tableName} (${operation.fromType} -> ${operation.toType})`,
+        tableName: operation.tableName,
+        columnName: operation.columnName,
+        from: operation.fromType,
+        to: operation.toType
+      };
+    case "column_nullability_changed":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `modify column ${operation.columnName} nullability on ${operation.tableName} (${formatNullable(operation.from)} -> ${formatNullable(operation.to)})`,
+        tableName: operation.tableName,
+        columnName: operation.columnName,
+        from: operation.from,
+        to: operation.to
+      };
+    case "column_default_changed":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `modify column ${operation.columnName} default on ${operation.tableName} (${formatDefault(operation.fromDefault)} -> ${formatDefault(operation.toDefault)})`,
+        tableName: operation.tableName,
+        columnName: operation.columnName,
+        from: operation.fromDefault,
+        to: operation.toDefault
+      };
+    case "column_unique_changed":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `modify column ${operation.columnName} unique constraint on ${operation.tableName} (${formatUnique(operation.from)} -> ${formatUnique(operation.to)})`,
+        tableName: operation.tableName,
+        columnName: operation.columnName,
+        from: operation.from,
+        to: operation.to
+      };
+    case "drop_primary_key_constraint":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop primary key constraint on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "add_primary_key_constraint":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `add primary key constraint on ${operation.tableName} (${operation.columnName})`,
+        tableName: operation.tableName,
+        columnName: operation.columnName
+      };
+    case "create_index":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `create index ${operation.index.name} on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "drop_index":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop index ${operation.index.name} on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "create_policy":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `create policy ${operation.policy.name} on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "drop_policy":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop policy ${operation.policyName} on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "modify_policy":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `modify policy ${operation.policyName} on ${operation.tableName}`,
+        tableName: operation.tableName
+      };
+    case "create_view":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `create view ${operation.view.name}`
+      };
+    case "drop_view":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `drop view ${operation.viewName}`
+      };
+    case "replace_view":
+      return {
+        action,
+        symbol,
+        operationKind: operation.kind,
+        summary: `replace view ${operation.view.name}`
+      };
+    default: {
+      const exhaustiveCheck = operation;
+      return exhaustiveCheck;
+    }
+  }
+}
+function formatMigrationPlanLine(entry) {
+  return `${entry.symbol} ${entry.summary}`;
+}
+function formatMigrationPlanLines(entries) {
+  return entries.map(formatMigrationPlanLine);
+}
+function buildMigrationPlan(diff) {
+  const entries = diff.operations.map(toEntry);
+  return {
+    entries,
+    lines: formatMigrationPlanLines(entries)
+  };
+}
+var init_plan_builder = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/plan-builder.js"() {
+    "use strict";
+  }
+});
+
 // node_modules/@xubylele/schema-forge-core/dist/generator/sql-generator.js
 function generateEnableRls(tableName) {
   return `ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;`;
@@ -1507,14 +2230,46 @@ function generateOperation(operation, provider, sqlConfig) {
       return generateDropPrimaryKeyConstraint(operation.tableName);
     case "add_primary_key_constraint":
       return generateAddPrimaryKeyConstraint(operation.tableName, operation.columnName);
+    case "create_index":
+      return generateCreateIndex(operation.tableName, operation.index);
+    case "drop_index":
+      return generateDropIndex(operation.tableName, operation.index);
     case "create_policy":
       return generateCreatePolicy(operation.tableName, operation.policy);
     case "drop_policy":
       return generateDropPolicy(operation.tableName, operation.policyName);
+    case "create_view":
+      return generateCreateOrReplaceView(operation.view);
+    case "drop_view":
+      return generateDropView(operation.viewName);
+    case "replace_view":
+      return generateCreateOrReplaceView(operation.view);
     case "modify_policy":
       return generateModifyPolicy(operation.tableName, operation.policyName, operation.policy);
   }
 }
+function generateCreateOrReplaceView(view) {
+  return `CREATE OR REPLACE VIEW ${view.name} AS
+${view.query};`;
+}
+function generateDropView(viewName) {
+  return `DROP VIEW IF EXISTS ${viewName};`;
+}
+function generateCreateIndex(tableName, index) {
+  const uniqueToken = index.unique ? "UNIQUE " : "";
+  const payload = index.expression ? `(${index.expression})` : `(${index.columns.join(", ")})`;
+  const whereClause = index.where ? ` WHERE ${index.where}` : "";
+  return `CREATE ${uniqueToken}INDEX ${index.name} ON ${tableName} ${payload}${whereClause};`;
+}
+function generateDropIndex(tableName, index) {
+  const fallbackName = deterministicIndexName({
+    table: tableName,
+    columns: index.columns,
+    expression: index.expression
+  });
+  const indexNames = Array.from(/* @__PURE__ */ new Set([index.name, fallbackName]));
+  return indexNames.map((indexName) => `DROP INDEX IF EXISTS ${indexName};`).join("\n");
+}
 function generateCreateTable(table, provider, sqlConfig) {
   const columnDefs = table.columns.map((col) => generateColumnDefinition(col, provider, sqlConfig));
   const lines = ["CREATE TABLE " + table.name + " ("];
@@ -2558,6 +3313,26 @@ function renderPolicy(policy) {
   }
   return lines.join("\n");
 }
+function renderIndex(index) {
+  const resolvedName = index.name || deterministicIndexName({
+    table: index.table,
+    columns: index.columns,
+    expression: index.expression
+  });
+  const lines = [`index ${resolvedName} on ${index.table}`];
+  if (index.expression) {
+    lines.push(`expression ${index.expression}`);
+  } else {
+    lines.push(`columns ${index.columns.join(", ")}`);
+  }
+  if (index.unique) {
+    lines.push("unique");
+  }
+  if (index.where) {
+    lines.push(`where ${index.where}`);
+  }
+  return lines.join("\n");
+}
 function schemaToDsl(schema) {
   const tableNames = Object.keys(schema.tables).sort((left, right) => left.localeCompare(right));
   const blocks = [];
@@ -2569,6 +3344,17 @@ function schemaToDsl(schema) {
     }
     tableLines.push("}");
     blocks.push(tableLines.join("\n"));
+    const sortedIndexes = (table.indexes ?? []).map((index) => ({
+      ...index,
+      name: index.name || deterministicIndexName({
+        table: index.table,
+        columns: index.columns,
+        expression: index.expression
+      })
+    })).sort((left, right) => left.name.localeCompare(right.name));
+    for (const index of sortedIndexes) {
+      blocks.push(renderIndex(index));
+    }
     if (table.policies?.length) {
       for (const policy of table.policies) {
         blocks.push(renderPolicy(policy));
@@ -2586,6 +3372,7 @@ ${blocks.join("\n\n")}
 var init_schema_to_dsl = __esm({
   "node_modules/@xubylele/schema-forge-core/dist/core/sql/schema-to-dsl.js"() {
     "use strict";
+    init_normalize();
   }
 });
 
@@ -3039,13 +3826,17 @@ __export(dist_exports, {
   SchemaValidationError: () => SchemaValidationError,
   analyzeSchemaDrift: () => analyzeSchemaDrift,
   applySqlOps: () => applySqlOps,
+  buildMigrationPlan: () => buildMigrationPlan,
   checkOperationSafety: () => checkOperationSafety,
   checkSchemaSafety: () => checkSchemaSafety,
   classifyOperation: () => classifyOperation,
+  deterministicIndexName: () => deterministicIndexName,
   diffSchemas: () => diffSchemas,
   ensureDir: () => ensureDir2,
   fileExists: () => fileExists2,
   findFiles: () => findFiles,
+  formatMigrationPlanLine: () => formatMigrationPlanLine,
+  formatMigrationPlanLines: () => formatMigrationPlanLines,
   generateSql: () => generateSql,
   getColumnNamesFromSchema: () => getColumnNamesFromSchema,
   getColumnNamesFromState: () => getColumnNamesFromState,
@@ -3056,6 +3847,7 @@ __export(dist_exports, {
   getStatePath: () => getStatePath2,
   getTableNamesFromSchema: () => getTableNamesFromSchema,
   getTableNamesFromState: () => getTableNamesFromState,
+  hashSqlContent: () => hashSqlContent,
   introspectPostgresSchema: () => introspectPostgresSchema,
   legacyPkName: () => legacyPkName,
   legacyUqName: () => legacyUqName,
@@ -3063,6 +3855,7 @@ __export(dist_exports, {
   loadState: () => loadState,
   normalizeDefault: () => normalizeDefault,
   normalizeIdent: () => normalizeIdent,
+  normalizeSqlExpression: () => normalizeSqlExpression,
   nowTimestamp: () => nowTimestamp,
   parseAddDropConstraint: () => parseAddDropConstraint,
   parseAlterColumnType: () => parseAlterColumnType,
@@ -3101,6 +3894,7 @@ var init_dist = __esm({
     init_validate();
     init_safety();
     init_state_manager();
+    init_plan_builder();
     init_sql_generator();
     init_parse_migration();
     init_apply_ops();
@@ -3117,12 +3911,12 @@ var init_dist = __esm({
 });
 
 // src/cli.ts
-var import_commander8 = require("commander");
+var import_commander10 = require("commander");
 
 // package.json
 var package_default = {
   name: "@xubylele/schema-forge",
-  version: "1.12.1",
+  version: "1.13.0",
   description: "Universal migration generator from schema DSL",
   main: "dist/cli.js",
   type: "commonjs",
@@ -3131,12 +3925,12 @@ var package_default = {
   },
   exports: {
     ".": {
-      require: "dist/cli.js",
-      types: "dist/cli.d.ts"
+      require: "./dist/cli.js",
+      types: "./dist/cli.d.ts"
     },
     "./api": {
-      require: "dist/api.js",
-      types: "dist/api.d.ts"
+      require: "./dist/api.js",
+      types: "./dist/api.d.ts"
     }
   },
   scripts: {
@@ -3176,19 +3970,19 @@ var package_default = {
     boxen: "^8.0.1",
     chalk: "^5.6.2",
     commander: "^14.0.3",
-    pg: "^8.19.0",
+    pg: "^8.20.0",
     "update-notifier": "^7.3.1"
   },
   devDependencies: {
     "@changesets/cli": "^2.30.0",
-    "@types/node": "^25.2.3",
-    "@types/pg": "^8.18.0",
-    "@xubylele/schema-forge-core": "^1.5.0",
-    testcontainers: "^11.8.1",
+    "@types/node": "^25.5.2",
+    "@types/pg": "^8.20.0",
+    "@xubylele/schema-forge-core": "^1.6.0",
+    testcontainers: "^11.13.0",
     "ts-node": "^10.9.2",
     tsup: "^8.5.1",
-    typescript: "^5.9.3",
-    vitest: "^4.0.18"
+    typescript: "^6.0.2",
+    vitest: "^4.1.2"
   }
 };
 
@@ -3388,6 +4182,10 @@ async function generateSql2(diff, provider, config) {
   const core = await loadCore();
   return core.generateSql(diff, provider, config);
 }
+async function buildMigrationPlan2(diff) {
+  const core = await loadCore();
+  return core.buildMigrationPlan(diff);
+}
 async function schemaToState2(schema) {
   const core = await loadCore();
   return core.schemaToState(schema);
@@ -4009,12 +4807,109 @@ async function runIntrospect(options = {}) {
   }
 }
 
-// src/commands/validate.ts
+// src/commands/plan.ts
 var import_commander7 = require("commander");
 var import_path13 = __toESM(require("path"));
 function resolveConfigPath5(root, targetPath) {
   return import_path13.default.isAbsolute(targetPath) ? targetPath : import_path13.default.join(root, targetPath);
 }
+async function runPlan(options = {}) {
+  if (options.safe && options.force) {
+    throw new Error("Cannot use --safe and --force flags together. Choose one:\n  --safe: Block destructive operations\n  --force: Bypass safety checks");
+  }
+  const root = getProjectRoot();
+  const configPath = getConfigPath(root);
+  if (!await fileExists(configPath)) {
+    throw new Error('SchemaForge project not initialized. Run "schema-forge init" first.');
+  }
+  const config = await readJsonFile(configPath, {});
+  const useLiveDatabase = Boolean(options.url || process.env.DATABASE_URL);
+  const requiredFields = useLiveDatabase ? ["schemaFile"] : ["schemaFile", "stateFile"];
+  for (const field of requiredFields) {
+    const value = config[field];
+    if (!value || typeof value !== "string") {
+      throw new Error(`Invalid config: '${field}' is required`);
+    }
+  }
+  const schemaPath = resolveConfigPath5(root, config.schemaFile);
+  const statePath = config.stateFile ? resolveConfigPath5(root, config.stateFile) : null;
+  const schemaSource = await readTextFile(schemaPath);
+  const schema = await parseSchema2(schemaSource);
+  try {
+    await validateSchema2(schema);
+  } catch (error2) {
+    if (error2 instanceof Error) {
+      throw await createSchemaValidationError(error2.message);
+    }
+    throw error2;
+  }
+  const previousState = useLiveDatabase ? await withPostgresQueryExecutor(
+    resolvePostgresConnectionString({ url: options.url }),
+    async (query) => {
+      const schemaFilters = parseSchemaList(options.schema);
+      const liveSchema = await introspectPostgresSchema2({
+        query,
+        ...schemaFilters ? { schemas: schemaFilters } : {}
+      });
+      return schemaToState2(liveSchema);
+    }
+  ) : await loadState2(statePath ?? "");
+  const diff = await diffSchemas2(previousState, schema);
+  if (options.force) {
+    forceWarning("Are you sure to use --force? This option will bypass safety checks for destructive operations.");
+  }
+  if (options.safe && !options.force && diff.operations.length > 0) {
+    const findings = await validateSchemaChanges2(previousState, schema);
+    const destructiveFindings = findings.filter((f) => f.severity === "error");
+    if (destructiveFindings.length > 0) {
+      const errorMessages = destructiveFindings.map((f) => {
+        const target = f.column ? `${f.table}.${f.column}` : f.table;
+        const typeRange = f.from && f.to ? ` (${f.from} -> ${f.to})` : "";
+        return `  - ${f.code}: ${target}${typeRange}`;
+      }).join("\n");
+      throw await createSchemaValidationError(
+        `Cannot proceed with --safe flag: Found ${destructiveFindings.length} destructive operation(s):
+${errorMessages}
+
+Remove --safe flag or modify schema to avoid destructive changes.`
+      );
+    }
+  }
+  if (!options.safe && !options.force && diff.operations.length > 0) {
+    const findings = await validateSchemaChanges2(previousState, schema);
+    const riskyFindings = findings.filter((f) => f.severity === "error" || f.severity === "warning");
+    if (riskyFindings.length > 0) {
+      const confirmed = await confirmDestructiveOps(findings);
+      if (!confirmed) {
+        if (process.exitCode !== EXIT_CODES.CI_DESTRUCTIVE) {
+          process.exitCode = EXIT_CODES.VALIDATION_ERROR;
+        }
+        return;
+      }
+    }
+  }
+  if (diff.operations.length === 0) {
+    success("No changes detected");
+    process.exitCode = EXIT_CODES.SUCCESS;
+    return;
+  }
+  const plan = await buildMigrationPlan2(diff);
+  console.log(plan.lines.join("\n"));
+  process.exitCode = EXIT_CODES.SUCCESS;
+}
+
+// src/commands/preview.ts
+var import_commander8 = require("commander");
+async function runPreview(options = {}) {
+  await runPlan(options);
+}
+
+// src/commands/validate.ts
+var import_commander9 = require("commander");
+var import_path14 = __toESM(require("path"));
+function resolveConfigPath6(root, targetPath) {
+  return import_path14.default.isAbsolute(targetPath) ? targetPath : import_path14.default.join(root, targetPath);
+}
 async function runValidate(options = {}) {
   const root = getProjectRoot();
   const configPath = getConfigPath(root);
@@ -4030,11 +4925,11 @@ async function runValidate(options = {}) {
       throw new Error(`Invalid config: '${field}' is required`);
     }
   }
-  const schemaPath = resolveConfigPath5(root, config.schemaFile);
+  const schemaPath = resolveConfigPath6(root, config.schemaFile);
   if (!config.stateFile) {
     throw new Error("Invalid config: 'stateFile' is required");
   }
-  const statePath = resolveConfigPath5(root, config.stateFile);
+  const statePath = resolveConfigPath6(root, config.stateFile);
   const schemaSource = await readTextFile(schemaPath);
   const schema = await parseSchema2(schemaSource);
   try {
@@ -4194,7 +5089,7 @@ async function seedLastSeenVersion(version) {
 }
 
 // src/cli.ts
-var program = new import_commander8.Command();
+var program = new import_commander10.Command();
 program.name("schema-forge").description("CLI tool for schema management and SQL generation").version(package_default.version).option("--safe", "Prevent execution of destructive operations").option("--force", "Force execution by bypassing safety checks and CI detection");
 function validateFlagExclusivity(options) {
   if (options.safe && options.force) {
@@ -4242,6 +5137,24 @@ program.command("diff").description("Compare two schema versions and generate mi
     await handleError(error2);
   }
 });
+program.command("plan").description("Preview migration operations as a human-readable plan. In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").option("--url <string>", "PostgreSQL connection URL for live plan (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
+  try {
+    const globalOptions = program.opts();
+    validateFlagExclusivity(globalOptions);
+    await runPlan({ ...options, ...globalOptions });
+  } catch (error2) {
+    await handleError(error2);
+  }
+});
+program.command("preview").description("Preview migration operations (alias of plan). In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").option("--url <string>", "PostgreSQL connection URL for live preview (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
+  try {
+    const globalOptions = program.opts();
+    validateFlagExclusivity(globalOptions);
+    await runPreview({ ...options, ...globalOptions });
+  } catch (error2) {
+    await handleError(error2);
+  }
+});
 program.command("doctor").description("Check live database drift against state. Exits with code 2 when drift is detected.").option("--json", "Output structured JSON").option("--url <string>", "PostgreSQL connection URL (defaults to DATABASE_URL)").option("--schema <list>", "Comma-separated schema names to introspect (default: public)").action(async (options) => {
   try {
     await runDoctor(options);