feat(mod_format): Add check-only formatting with interactive diff preview; make formatting default to dry-run and extend formatting API

ts/mod_format/index.ts

@@ -19,7 +19,8 @@ import { CopyFormatter } from './formatters/copy.formatter.js';
 
 export let run = async (
   options: {
-    dryRun?: boolean;
+    write?: boolean;      // Explicitly write changes (default: false, dry-mode)
+    dryRun?: boolean;     // Deprecated, kept for compatibility
     yes?: boolean;
     planOnly?: boolean;
     savePlan?: string;
@@ -35,7 +36,11 @@ export let run = async (
     setVerboseMode(true);
   }
 
-  const project = await Project.fromCwd();
+  // Determine if we should write changes
+  // Default is dry-mode (no writing) unless --write/-w is specified
+  const shouldWrite = options.write ?? (options.dryRun === false);
+
+  const project = await Project.fromCwd({ requireProjectType: false });
   const context = new FormatContext();
   // Cache system removed - no longer needed
   const planner = new FormatPlanner();
@@ -127,9 +132,9 @@ export let run = async (
       return;
     }
 
-    // Dry-run mode
-    if (options.dryRun) {
-      logger.log('info', 'Dry-run mode - no changes will be made');
+    // Dry-run mode (default behavior)
+    if (!shouldWrite) {
+      logger.log('info', 'Dry-run mode - use --write (-w) to apply changes');
       return;
     }
 
@@ -197,14 +202,27 @@ export const handleCleanBackups = async (): Promise<void> => {
   );
 };
 
+// Import the ICheckResult type for external use
+import type { ICheckResult } from './interfaces.format.js';
+export type { ICheckResult };
+
+// Formatters that don't require projectType to be set
+const formattersNotRequiringProjectType = ['npmextra', 'prettier', 'cleanup', 'packagejson'];
+
 /**
  * Run a single formatter by name (for use by other modules)
  */
 export const runFormatter = async (
   formatterName: string,
-  options: { silent?: boolean } = {}
-): Promise<void> => {
-  const project = await Project.fromCwd();
+  options: {
+    silent?: boolean;
+    checkOnly?: boolean;    // Only check for diffs, don't apply
+    showDiff?: boolean;     // Show the diff output
+  } = {}
+): Promise<ICheckResult | void> => {
+  // Determine if this formatter requires projectType
+  const requireProjectType = !formattersNotRequiringProjectType.includes(formatterName);
+  const project = await Project.fromCwd({ requireProjectType });
   const context = new FormatContext();
 
   // Map formatter names to classes
@@ -227,6 +245,17 @@ export const runFormatter = async (
   }
 
   const formatter = new FormatterClass(context, project);
+
+  // Check-only mode: just check for diffs and optionally display them
+  if (options.checkOnly) {
+    const result = await formatter.check();
+    if (result.hasDiff && options.showDiff) {
+      formatter.displayAllDiffs(result);
+    }
+    return result;
+  }
+
+  // Normal mode: analyze and apply changes
   const changes = await formatter.analyze();
 
   for (const change of changes) {