@xubylele/schema-forge 1.5.2 → 1.6.1

package/README.md

@@ -171,12 +171,25 @@ Creates the necessary directory structure and configuration files.
 Generate SQL migration from schema changes.
 
 ```bash
-schema-forge generate [--name "migration description"]
+schema-forge generate [--name "migration description"] [--safe] [--force]
 ```
 
 **Options:**
 
 - `--name` - Optional name for the migration (default: "migration")
+- `--safe` - Block execution if destructive operations are detected (exits with error)
+- `--force` - Bypass safety checks and proceed with destructive operations (shows warning)
+
+**Safety Behavior:**
+
+When destructive or risky operations are detected (like dropping columns or tables), SchemaForge will:
+
+1. **Without flags** - Display an interactive prompt showing the risky operations and ask for confirmation (yes/no)
+2. **With `--safe`** - Block execution immediately and exit with error code 1, listing all destructive operations
+3. **With `--force`** - Bypass safety checks, show a warning message, and proceed with generating the migration
+4. **In CI environment** (`CI=true`) - Skip the interactive prompt, fail with exit code 3 for destructive operations unless `--force` is used
+
+See [CI Behavior](#ci-behavior) for more details.
 
 Compares your current schema with the tracked state, generates SQL for any changes, and updates the state file.
 
@@ -185,10 +198,15 @@ Compares your current schema with the tracked state, generates SQL for any chang
 Compare your schema with the current state without generating files.
 
 ```bash
-schema-forge diff
+schema-forge diff [--safe] [--force]
 ```
 
-Shows what SQL would be generated if you ran `generate`. Useful for previewing changes.
+**Options:**
+
+- `--safe` - Block execution if destructive operations are detected (exits with error)
+- `--force` - Bypass safety checks and proceed with displaying destructive SQL (shows warning)
+
+Shows what SQL would be generated if you ran `generate`. Useful for previewing changes. Safety behavior is the same as `generate` command. In CI environments, exits with code 3 if destructive operations are detected unless `--force` is used. See [CI Behavior](#ci-behavior) for more details.
 
 ### `schema-forge import`
 
@@ -229,11 +247,82 @@ Use JSON mode for CI and automation:
 schema-forge validate --json
 ```
 
+Exit codes (also see [CI Behavior](#ci-behavior)):
+
+- `3` in CI environment if destructive findings detected
+- `1` if one or more `error` findings are detected
+- `0` if no `error` findings are detected (warnings alone do not fail)
+
 Exit codes:
 
 - `1` when one or more `error` findings are detected
 - `0` when no `error` findings are detected (warnings alone do not fail)
 
+## CI Behavior
+
+SchemaForge ensures deterministic behavior in Continuous Integration (CI) environments to prevent accidental destructive operations.
+
+### Detecting CI Environment
+
+CI mode is automatically activated when either environment variable is set:
+
+- `CI=true`
+- `CONTINUOUS_INTEGRATION=true`
+
+### Exit Codes
+
+SchemaForge uses specific exit codes for different scenarios:
+
+| Exit Code | Meaning |
+| --------- | ------- |
+| `0` | Success - no changes or no destructive operations detected |
+| `1` | General error - validation failed, operation declined, missing files, etc. |
+| `2` | Schema validation error - invalid DSL syntax or structure |
+| `3` | **CI Destructive** - destructive operations detected in CI environment without `--force` |
+
+### Destructive Operations in CI
+
+When running in a CI environment, destructive operations (those flagged as `error` or `warning` level findings) trigger exit code 3:
+
+**Operations classified as destructive:**
+
+- Dropping tables (`DROP_TABLE`)
+- Dropping columns (`DROP_COLUMN`)
+- Changing column types in incompatible ways
+- Making columns NOT NULL when they allow NULL
+
+### Overriding in CI
+
+To proceed with destructive operations in CI, use the `--force` flag:
+
+```bash
+# This will fail with exit code 3 if destructive changes detected
+schema-forge generate
+
+# This will proceed despite destructive changes (requires explicit acknowledgment)
+schema-forge generate --force
+```
+
+### No Interactive Prompts in CI
+
+When `CI=true`, SchemaForge will:
+
+- ✅ Never show interactive prompts, preventing script hangs
+- ✅ Fail deterministically (exit code 3) for destructive operations
+- ✅ Allow explicit override with `--force` flag
+- ❌ Not accept user input for confirmation
+
+### Using `--safe` in CI
+
+The `--safe` flag is compatible with CI and blocks execution of destructive operations:
+
+```bash
+# Blocks execution if destructive operations detected, exits with code 1
+schema-forge generate --safe
+```
+
+This is useful for strict CI pipelines where all destructive changes must be reviewed and merged separately.
+
 ## Constraint Change Detection
 
 SchemaForge detects and generates migrations for:

package/dist/cli.js

@@ -46,11 +46,11 @@ function parseSchema(source) {
     "date"
   ]);
   const validIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
-  function normalizeColumnType3(type) {
+  function normalizeColumnType4(type) {
     return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
   }
   function isValidColumnType2(type) {
-    const normalizedType = normalizeColumnType3(type);
+    const normalizedType = normalizeColumnType4(type);
     if (validBaseColumnTypes.has(normalizedType)) {
       return true;
     }
@@ -174,7 +174,7 @@ function parseSchema(source) {
       throw new Error(`Line ${lineNum}: Invalid column definition. Expected: <name> <type> [modifiers...]`);
     }
     const colName = tokens[0];
-    const colType = normalizeColumnType3(tokens[1]);
+    const colType = normalizeColumnType4(tokens[1]);
     validateIdentifier(colName, lineNum, "column");
     if (!isValidColumnType2(colType)) {
       throw new Error(`Line ${lineNum}: Invalid column type '${tokens[1]}'. Valid types: ${Array.from(validBaseColumnTypes).join(", ")}, varchar(n), numeric(p,s)`);
@@ -777,7 +777,7 @@ var init_validator = __esm({
   }
 });
 
-// node_modules/@xubylele/schema-forge-core/dist/core/validate.js
+// node_modules/@xubylele/schema-forge-core/dist/core/safety/operation-classifier.js
 function normalizeColumnType2(type) {
   return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
 }
@@ -800,119 +800,246 @@ function classifyTypeChange(from, to) {
   const toType = normalizeColumnType2(to);
   const uuidInvolved = fromType === "uuid" || toType === "uuid";
   if (uuidInvolved && fromType !== toType) {
-    return {
-      severity: "error",
-      message: `Type changed from ${fromType} to ${toType} (likely incompatible cast)`
-    };
+    return "DESTRUCTIVE";
   }
   if (fromType === "int" && toType === "bigint") {
-    return {
-      severity: "warning",
-      message: "Type widened from int to bigint"
-    };
+    return "WARNING";
   }
   if (fromType === "bigint" && toType === "int") {
-    return {
-      severity: "error",
-      message: "Type narrowed from bigint to int (likely incompatible cast)"
-    };
+    return "DESTRUCTIVE";
   }
   if (fromType === "text" && parseVarcharLength(toType) !== null) {
-    return {
-      severity: "error",
-      message: `Type changed from text to ${toType} (may truncate existing values)`
-    };
+    return "DESTRUCTIVE";
   }
   if (parseVarcharLength(fromType) !== null && toType === "text") {
-    return {
-      severity: "warning",
-      message: "Type widened from varchar(n) to text"
-    };
+    return "WARNING";
   }
   const fromVarcharLength = parseVarcharLength(fromType);
   const toVarcharLength = parseVarcharLength(toType);
   if (fromVarcharLength !== null && toVarcharLength !== null) {
     if (toVarcharLength >= fromVarcharLength) {
-      return {
-        severity: "warning",
-        message: `Type widened from varchar(${fromVarcharLength}) to varchar(${toVarcharLength})`
-      };
+      return "WARNING";
     }
-    return {
-      severity: "error",
-      message: `Type narrowed from varchar(${fromVarcharLength}) to varchar(${toVarcharLength})`
-    };
+    return "DESTRUCTIVE";
   }
   const fromNumeric = parseNumericType(fromType);
   const toNumeric = parseNumericType(toType);
   if (fromNumeric && toNumeric && fromNumeric.scale === toNumeric.scale) {
     if (toNumeric.precision >= fromNumeric.precision) {
-      return {
-        severity: "warning",
-        message: `Type widened from numeric(${fromNumeric.precision},${fromNumeric.scale}) to numeric(${toNumeric.precision},${toNumeric.scale})`
-      };
+      return "WARNING";
     }
-    return {
-      severity: "error",
-      message: `Type narrowed from numeric(${fromNumeric.precision},${fromNumeric.scale}) to numeric(${toNumeric.precision},${toNumeric.scale})`
-    };
+    return "DESTRUCTIVE";
+  }
+  return "WARNING";
+}
+function classifyOperation(operation) {
+  switch (operation.kind) {
+    case "create_table":
+      return "SAFE";
+    case "add_column":
+      return "SAFE";
+    case "drop_table":
+      return "DESTRUCTIVE";
+    case "drop_column":
+      return "DESTRUCTIVE";
+    case "column_type_changed":
+      return classifyTypeChange(operation.fromType, operation.toType);
+    case "column_nullability_changed":
+      if (operation.from && !operation.to) {
+        return "WARNING";
+      }
+      return "SAFE";
+    case "column_default_changed":
+      return "SAFE";
+    case "column_unique_changed":
+      return "SAFE";
+    case "drop_primary_key_constraint":
+      return "DESTRUCTIVE";
+    case "add_primary_key_constraint":
+      return "SAFE";
+    default:
+      const _exhaustive = operation;
+      return _exhaustive;
+  }
+}
+var init_operation_classifier = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/safety/operation-classifier.js"() {
+    "use strict";
+  }
+});
+
+// node_modules/@xubylele/schema-forge-core/dist/core/safety/safety-checker.js
+function normalizeColumnType3(type) {
+  return type.toLowerCase().trim().replace(/\s+/g, " ").replace(/\s*\(\s*/g, "(").replace(/\s*,\s*/g, ",").replace(/\s*\)\s*/g, ")");
+}
+function parseVarcharLength2(type) {
+  const match = normalizeColumnType3(type).match(/^varchar\((\d+)\)$/);
+  return match ? Number(match[1]) : null;
+}
+function parseNumericType2(type) {
+  const match = normalizeColumnType3(type).match(/^numeric\((\d+),(\d+)\)$/);
+  if (!match) {
+    return null;
   }
   return {
-    severity: "warning",
-    message: `Type changed from ${fromType} to ${toType} (compatibility unknown)`
+    precision: Number(match[1]),
+    scale: Number(match[2])
   };
 }
-function validateSchemaChanges(previousState, currentSchema) {
-  const findings = [];
-  const diff = diffSchemas(previousState, currentSchema);
-  for (const operation of diff.operations) {
-    switch (operation.kind) {
-      case "drop_table":
-        findings.push({
-          severity: "error",
-          code: "DROP_TABLE",
-          table: operation.tableName,
-          message: "Table removed"
-        });
-        break;
-      case "drop_column":
-        findings.push({
-          severity: "error",
-          code: "DROP_COLUMN",
-          table: operation.tableName,
-          column: operation.columnName,
-          message: "Column removed"
-        });
-        break;
-      case "column_type_changed": {
-        const classification = classifyTypeChange(operation.fromType, operation.toType);
-        findings.push({
-          severity: classification.severity,
-          code: "ALTER_COLUMN_TYPE",
+function generateTypeChangeMessage(from, to) {
+  const fromType = normalizeColumnType3(from);
+  const toType = normalizeColumnType3(to);
+  const uuidInvolved = fromType === "uuid" || toType === "uuid";
+  if (uuidInvolved && fromType !== toType) {
+    return `Type changed from ${fromType} to ${toType} (likely incompatible cast)`;
+  }
+  if (fromType === "int" && toType === "bigint") {
+    return "Type widened from int to bigint";
+  }
+  if (fromType === "bigint" && toType === "int") {
+    return "Type narrowed from bigint to int (likely incompatible cast)";
+  }
+  if (fromType === "text" && parseVarcharLength2(toType) !== null) {
+    return `Type changed from text to ${toType} (may truncate existing values)`;
+  }
+  if (parseVarcharLength2(fromType) !== null && toType === "text") {
+    const length = parseVarcharLength2(fromType);
+    return `Type widened from varchar(${length}) to text`;
+  }
+  const fromVarcharLength = parseVarcharLength2(fromType);
+  const toVarcharLength = parseVarcharLength2(toType);
+  if (fromVarcharLength !== null && toVarcharLength !== null) {
+    if (toVarcharLength >= fromVarcharLength) {
+      return `Type widened from varchar(${fromVarcharLength}) to varchar(${toVarcharLength})`;
+    }
+    return `Type narrowed from varchar(${fromVarcharLength}) to varchar(${toVarcharLength})`;
+  }
+  const fromNumeric = parseNumericType2(fromType);
+  const toNumeric = parseNumericType2(toType);
+  if (fromNumeric && toNumeric && fromNumeric.scale === toNumeric.scale) {
+    if (toNumeric.precision >= fromNumeric.precision) {
+      return `Type widened from numeric(${fromNumeric.precision},${fromNumeric.scale}) to numeric(${toNumeric.precision},${toNumeric.scale})`;
+    }
+    return `Type narrowed from numeric(${fromNumeric.precision},${fromNumeric.scale}) to numeric(${toNumeric.precision},${toNumeric.scale})`;
+  }
+  return `Type changed from ${fromType} to ${toType} (compatibility unknown)`;
+}
+function checkOperationSafety(operation) {
+  const safetyLevel = classifyOperation(operation);
+  if (safetyLevel === "SAFE") {
+    return null;
+  }
+  switch (operation.kind) {
+    case "drop_table":
+      return {
+        safetyLevel,
+        code: "DROP_TABLE",
+        table: operation.tableName,
+        message: "Table removed",
+        operationKind: operation.kind
+      };
+    case "drop_column":
+      return {
+        safetyLevel,
+        code: "DROP_COLUMN",
+        table: operation.tableName,
+        column: operation.columnName,
+        message: "Column removed",
+        operationKind: operation.kind
+      };
+    case "column_type_changed":
+      return {
+        safetyLevel,
+        code: "ALTER_COLUMN_TYPE",
+        table: operation.tableName,
+        column: operation.columnName,
+        from: normalizeColumnType3(operation.fromType),
+        to: normalizeColumnType3(operation.toType),
+        message: generateTypeChangeMessage(operation.fromType, operation.toType),
+        operationKind: operation.kind
+      };
+    case "column_nullability_changed":
+      if (operation.from && !operation.to) {
+        return {
+          safetyLevel,
+          code: "SET_NOT_NULL",
           table: operation.tableName,
           column: operation.columnName,
-          from: normalizeColumnType2(operation.fromType),
-          to: normalizeColumnType2(operation.toType),
-          message: classification.message
-        });
-        break;
+          message: "Column changed to NOT NULL (may fail if data contains NULLs)",
+          operationKind: operation.kind
+        };
       }
-      case "column_nullability_changed":
-        if (operation.from && !operation.to) {
-          findings.push({
-            severity: "warning",
-            code: "SET_NOT_NULL",
-            table: operation.tableName,
-            column: operation.columnName,
-            message: "Column changed to NOT NULL (may fail if data contains NULLs)"
-          });
-        }
-        break;
-      default:
-        break;
+      return null;
+    case "drop_primary_key_constraint":
+      return {
+        safetyLevel,
+        code: "DROP_TABLE",
+        // Reuse code for primary key drops
+        table: operation.tableName,
+        message: "Primary key constraint removed",
+        operationKind: operation.kind
+      };
+    default:
+      return null;
+  }
+}
+function checkSchemaSafety(previousState, currentSchema) {
+  const findings = [];
+  const diff = diffSchemas(previousState, currentSchema);
+  for (const operation of diff.operations) {
+    const finding = checkOperationSafety(operation);
+    if (finding) {
+      findings.push(finding);
     }
   }
-  return findings;
+  const hasWarnings = findings.some((f) => f.safetyLevel === "WARNING");
+  const hasDestructiveOps = findings.some((f) => f.safetyLevel === "DESTRUCTIVE");
+  return {
+    findings,
+    hasSafeIssues: false,
+    // All findings are non-safe by definition
+    hasWarnings,
+    hasDestructiveOps
+  };
+}
+var init_safety_checker = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/safety/safety-checker.js"() {
+    "use strict";
+    init_diff();
+    init_operation_classifier();
+  }
+});
+
+// node_modules/@xubylele/schema-forge-core/dist/core/safety/index.js
+var init_safety = __esm({
+  "node_modules/@xubylele/schema-forge-core/dist/core/safety/index.js"() {
+    "use strict";
+    init_operation_classifier();
+    init_safety_checker();
+  }
+});
+
+// node_modules/@xubylele/schema-forge-core/dist/core/validate.js
+function safetyLevelToSeverity(level) {
+  if (level === "DESTRUCTIVE") {
+    return "error";
+  }
+  return "warning";
+}
+function adaptSafetyFinding(finding) {
+  return {
+    severity: safetyLevelToSeverity(finding.safetyLevel),
+    code: finding.code,
+    table: finding.table,
+    column: finding.column,
+    from: finding.from,
+    to: finding.to,
+    message: finding.message
+  };
+}
+function validateSchemaChanges(previousState, currentSchema) {
+  const safetyReport = checkSchemaSafety(previousState, currentSchema);
+  return safetyReport.findings.map(adaptSafetyFinding);
 }
 function toValidationReport(findings) {
   const errors = findings.filter((finding) => finding.severity === "error");
@@ -927,7 +1054,7 @@ function toValidationReport(findings) {
 var init_validate = __esm({
   "node_modules/@xubylele/schema-forge-core/dist/core/validate.js"() {
     "use strict";
-    init_diff();
+    init_safety();
   }
 });
 
@@ -2093,6 +2220,9 @@ var dist_exports = {};
 __export(dist_exports, {
   SchemaValidationError: () => SchemaValidationError,
   applySqlOps: () => applySqlOps,
+  checkOperationSafety: () => checkOperationSafety,
+  checkSchemaSafety: () => checkSchemaSafety,
+  classifyOperation: () => classifyOperation,
   diffSchemas: () => diffSchemas,
   ensureDir: () => ensureDir2,
   fileExists: () => fileExists2,
@@ -2146,6 +2276,7 @@ var init_dist = __esm({
     init_diff();
     init_validator();
     init_validate();
+    init_safety();
     init_state_manager();
     init_sql_generator();
     init_parse_migration();
@@ -2167,7 +2298,7 @@ var import_commander6 = require("commander");
 // package.json
 var package_default = {
   name: "@xubylele/schema-forge",
-  version: "1.5.2",
+  version: "1.6.1",
   description: "Universal migration generator from schema DSL",
   main: "dist/cli.js",
   type: "commonjs",
@@ -2214,7 +2345,7 @@ var package_default = {
   devDependencies: {
     "@changesets/cli": "^2.29.8",
     "@types/node": "^25.2.3",
-    "@xubylele/schema-forge-core": "^1.1.0",
+    "@xubylele/schema-forge-core": "^1.2.0",
     "ts-node": "^10.9.2",
     tsup: "^8.5.1",
     typescript: "^5.9.3",
@@ -2382,6 +2513,18 @@ async function isSchemaValidationError(error2) {
   return error2 instanceof core.SchemaValidationError;
 }
 
+// src/utils/exitCodes.ts
+var EXIT_CODES = {
+  /** Successful operation */
+  SUCCESS: 0,
+  /** Validation error (invalid DSL syntax, config errors, missing files, etc.) */
+  VALIDATION_ERROR: 1,
+  /** Drift detected - Reserved for future use when comparing actual DB state vs schema */
+  DRIFT_DETECTED: 2,
+  /** Destructive operation detected in CI environment without --force */
+  CI_DESTRUCTIVE: 3
+};
+
 // src/utils/output.ts
 var import_boxen = __toESM(require("boxen"));
 var import_chalk = require("chalk");
@@ -2422,13 +2565,96 @@ function warning(message) {
 function error(message) {
   console.error(theme.error(`[ERROR] ${message}`));
 }
+function forceWarning(message) {
+  console.error(theme.warning(`[FORCE] ${message}`));
+}
+
+// src/utils/prompt.ts
+var import_node_readline = __toESM(require("readline"));
+function isCI() {
+  return process.env.CI === "true" || process.env.CONTINUOUS_INTEGRATION === "true";
+}
+function formatFindingsSummary(findings) {
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warning");
+  const lines = [];
+  if (errors.length > 0) {
+    lines.push(theme.error("DESTRUCTIVE OPERATIONS:"));
+    for (const finding of errors) {
+      const columnPart = finding.column ? `.${finding.column}` : "";
+      const fromTo = finding.from && finding.to ? ` (${finding.from} \u2192 ${finding.to})` : "";
+      lines.push(theme.error(`  \u2022 ${finding.code}: ${finding.table}${columnPart}${fromTo}`));
+    }
+  }
+  if (warnings.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(theme.warning("WARNING OPERATIONS:"));
+    for (const finding of warnings) {
+      const columnPart = finding.column ? `.${finding.column}` : "";
+      const fromTo = finding.from && finding.to ? ` (${finding.from} \u2192 ${finding.to})` : "";
+      lines.push(theme.warning(`  \u2022 ${finding.code}: ${finding.table}${columnPart}${fromTo}`));
+    }
+  }
+  return lines.join("\n");
+}
+async function readConfirmation(input = process.stdin, output = process.stdout) {
+  const rl = import_node_readline.default.createInterface({
+    input,
+    output
+  });
+  return new Promise((resolve) => {
+    const askQuestion = () => {
+      rl.question(theme.primary("Proceed with these changes? (yes/no): "), (answer) => {
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === "yes" || normalized === "y") {
+          rl.close();
+          resolve(true);
+        } else if (normalized === "no" || normalized === "n") {
+          rl.close();
+          resolve(false);
+        } else {
+          console.log(theme.warning('Please answer "yes" or "no".'));
+          askQuestion();
+        }
+      });
+    };
+    askQuestion();
+  });
+}
+async function confirmDestructiveOps(findings, input, output) {
+  const riskyFindings = findings.filter(
+    (f) => f.severity === "error" || f.severity === "warning"
+  );
+  if (riskyFindings.length === 0) {
+    return true;
+  }
+  if (isCI()) {
+    error("Cannot run interactive prompts in CI environment. Use --force flag to bypass safety checks.");
+    process.exitCode = EXIT_CODES.CI_DESTRUCTIVE;
+    return false;
+  }
+  console.log("");
+  console.log(formatFindingsSummary(riskyFindings));
+  console.log("");
+  const confirmed = await readConfirmation(input, output);
+  if (!confirmed) {
+    warning("Operation cancelled by user.");
+  }
+  return confirmed;
+}
+function hasDestructiveFindings(findings) {
+  return findings.some((f) => f.severity === "error" || f.severity === "warning");
+}
 
 // src/commands/diff.ts
 var REQUIRED_CONFIG_FIELDS = ["schemaFile", "stateFile"];
 function resolveConfigPath(root, targetPath) {
   return import_path7.default.isAbsolute(targetPath) ? targetPath : import_path7.default.join(root, targetPath);
 }
-async function runDiff() {
+async function runDiff(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)) {
@@ -2456,12 +2682,47 @@ async function runDiff() {
   }
   const previousState = 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 sql = await generateSql2(diff, provider, config.sql);
   console.log(sql);
+  process.exitCode = EXIT_CODES.SUCCESS;
 }
 
 // src/commands/generate.ts
@@ -2488,6 +2749,9 @@ function resolveConfigPath2(root, targetPath) {
   return import_path8.default.isAbsolute(targetPath) ? targetPath : import_path8.default.join(root, targetPath);
 }
 async function runGenerate(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)) {
@@ -2520,8 +2784,42 @@ async function runGenerate(options) {
   }
   const previousState = 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) {
     info("No changes detected");
+    process.exitCode = EXIT_CODES.SUCCESS;
     return;
   }
   const sql = await generateSql2(diff, provider, config.sql);
@@ -2534,6 +2832,7 @@ async function runGenerate(options) {
   const nextState = await schemaToState2(schema);
   await saveState2(statePath, nextState);
   success(`SQL generated successfully: ${migrationPath}`);
+  process.exitCode = EXIT_CODES.SUCCESS;
 }
 
 // src/commands/import.ts
@@ -2585,6 +2884,7 @@ async function runImport(inputPath, options = {}) {
       warning(`...and ${warnings.length - 10} more`);
     }
   }
+  process.exitCode = EXIT_CODES.SUCCESS;
 }
 
 // src/commands/init.ts
@@ -2593,24 +2893,19 @@ async function runInit() {
   const root = getProjectRoot();
   const schemaForgeDir = getSchemaForgeDir(root);
   if (await fileExists(schemaForgeDir)) {
-    error("schemaforge/ directory already exists");
-    error("Please remove it or run init in a different directory");
-    process.exit(1);
+    throw new Error("schemaforge/ directory already exists. Please remove it or run init in a different directory.");
   }
   const schemaFilePath = getSchemaFilePath(root);
   const configPath = getConfigPath(root);
   const statePath = getStatePath(root);
   if (await fileExists(schemaFilePath)) {
-    error(`${schemaFilePath} already exists`);
-    process.exit(1);
+    throw new Error(`${schemaFilePath} already exists`);
   }
   if (await fileExists(configPath)) {
-    error(`${configPath} already exists`);
-    process.exit(1);
+    throw new Error(`${configPath} already exists`);
   }
   if (await fileExists(statePath)) {
-    error(`${statePath} already exists`);
-    process.exit(1);
+    throw new Error(`${statePath} already exists`);
   }
   info("Initializing schema project...");
   await ensureDir(schemaForgeDir);
@@ -2649,6 +2944,7 @@ table users {
   info("Next steps:");
   info("  1. Edit schemaforge/schema.sf to define your schema");
   info("  2. Run: schema-forge generate");
+  process.exitCode = EXIT_CODES.SUCCESS;
 }
 
 // src/commands/validate.ts
@@ -2686,14 +2982,17 @@ async function runValidate(options = {}) {
   const previousState = await loadState2(statePath);
   const findings = await validateSchemaChanges2(previousState, schema);
   const report = await toValidationReport2(findings);
+  if (isCI() && hasDestructiveFindings(findings)) {
+    process.exitCode = EXIT_CODES.CI_DESTRUCTIVE;
+  } else {
+    process.exitCode = report.hasErrors ? EXIT_CODES.VALIDATION_ERROR : EXIT_CODES.SUCCESS;
+  }
   if (options.json) {
     console.log(JSON.stringify(report, null, 2));
-    process.exitCode = report.hasErrors ? 1 : 0;
     return;
   }
   if (findings.length === 0) {
     success("No destructive changes detected");
-    process.exitCode = 0;
     return;
   }
   console.log(
@@ -2710,16 +3009,61 @@ async function runValidate(options = {}) {
       );
     }
   }
-  process.exitCode = report.hasErrors ? 1 : 0;
+}
+
+// src/utils/whatsNew.ts
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+function getCliMetaPath() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".schema-forge", "cli-meta.json");
+}
+function getReleaseUrl(version) {
+  return `https://github.com/xubylele/schema-forge/releases/tag/v${version}`;
+}
+function shouldShowWhatsNew(argv) {
+  if (argv.length === 0) {
+    return false;
+  }
+  if (argv.includes("--help") || argv.includes("-h") || argv.includes("--version") || argv.includes("-V")) {
+    return false;
+  }
+  return true;
+}
+async function showWhatsNewIfUpdated(currentVersion, argv) {
+  if (!shouldShowWhatsNew(argv)) {
+    return;
+  }
+  try {
+    const metaPath = getCliMetaPath();
+    const meta = await readJsonFile(metaPath, {});
+    if (meta.lastSeenVersion === currentVersion) {
+      return;
+    }
+    info(`What's new in schema-forge v${currentVersion}: ${getReleaseUrl(currentVersion)}`);
+    await writeJsonFile(metaPath, { lastSeenVersion: currentVersion });
+  } catch {
+  }
+}
+async function seedLastSeenVersion(version) {
+  const metaPath = getCliMetaPath();
+  const exists = await fileExists(metaPath);
+  if (!exists) {
+    await writeJsonFile(metaPath, { lastSeenVersion: version });
+  }
 }
 
 // src/cli.ts
 var program = new import_commander6.Command();
-program.name("schema-forge").description("CLI tool for schema management and SQL generation").version(package_default.version);
+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) {
+    throw new Error("Cannot use --safe and --force flags together. Choose one:\n  --safe: Block destructive operations\n  --force: Bypass safety checks");
+  }
+}
 async function handleError(error2) {
   if (await isSchemaValidationError(error2) && error2 instanceof Error) {
     error(error2.message);
-    process.exitCode = 2;
+    process.exitCode = EXIT_CODES.VALIDATION_ERROR;
     return;
   }
   if (error2 instanceof Error) {
@@ -2727,7 +3071,7 @@ async function handleError(error2) {
   } else {
     error("Unexpected error");
   }
-  process.exitCode = 1;
+  process.exitCode = EXIT_CODES.VALIDATION_ERROR;
 }
 program.command("init").description("Initialize a new schema project").action(async () => {
   try {
@@ -2736,16 +3080,20 @@ program.command("init").description("Initialize a new schema project").action(as
     await handleError(error2);
   }
 });
-program.command("generate").description("Generate SQL from schema files").option("--name <string>", "Schema name to generate").action(async (options) => {
+program.command("generate").description("Generate SQL from schema files. In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").option("--name <string>", "Schema name to generate").action(async (options) => {
   try {
-    await runGenerate(options);
+    const globalOptions = program.opts();
+    validateFlagExclusivity(globalOptions);
+    await runGenerate({ ...options, ...globalOptions });
   } catch (error2) {
     await handleError(error2);
   }
 });
-program.command("diff").description("Compare two schema versions and generate migration SQL").action(async () => {
+program.command("diff").description("Compare two schema versions and generate migration SQL. In CI environments (CI=true), exits with code 3 if destructive operations are detected unless --force is used.").action(async () => {
   try {
-    await runDiff();
+    const globalOptions = program.opts();
+    validateFlagExclusivity(globalOptions);
+    await runDiff(globalOptions);
   } catch (error2) {
     await handleError(error2);
   }
@@ -2757,14 +3105,20 @@ program.command("import").description("Import schema from SQL migrations").argum
     await handleError(error2);
   }
 });
-program.command("validate").description("Detect destructive or risky schema changes").option("--json", "Output structured JSON").action(async (options) => {
+program.command("validate").description("Detect destructive or risky schema changes. In CI environments (CI=true), exits with code 3 if destructive operations are detected.").option("--json", "Output structured JSON").action(async (options) => {
   try {
     await runValidate(options);
   } catch (error2) {
     await handleError(error2);
   }
 });
-program.parse(process.argv);
-if (!process.argv.slice(2).length) {
-  program.outputHelp();
+async function main() {
+  const argv = process.argv.slice(2);
+  await seedLastSeenVersion(package_default.version);
+  await showWhatsNewIfUpdated(package_default.version, argv);
+  program.parse(process.argv);
+  if (!argv.length) {
+    program.outputHelp();
+  }
 }
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xubylele/schema-forge",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "Universal migration generator from schema DSL",
   "main": "dist/cli.js",
   "type": "commonjs",
@@ -47,10 +47,10 @@
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
     "@types/node": "^25.2.3",
-    "@xubylele/schema-forge-core": "^1.1.0",
+    "@xubylele/schema-forge-core": "^1.2.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
-}
+}