@git.zone/cli 1.15.5 → 1.16.0

package/readme.plan.md

@@ -0,0 +1,170 @@
+# Gitzone Format Module Improvement Plan
+
+Please reread /home/philkunz/.claude/CLAUDE.md before proceeding with any implementation.
+
+## Overview
+This plan outlines improvements for the gitzone format module to enhance its functionality, reliability, and maintainability.
+
+## Phase 1: Core Improvements (High Priority) - COMPLETED ✅
+
+### 1. Enhanced Error Handling & Recovery ✅
+- [x] Implement rollback mechanism for failed format operations
+- [x] Add detailed error messages with recovery suggestions
+- [x] Create a `--dry-run` flag to preview changes before applying
+- [x] Add transaction-like behavior: all-or-nothing formatting
+- [x] Implement plan → action workflow as default behavior
+
+### 2. Complete Missing Functionality ✅
+- [x] Implement the `ensureDependency` function in format.packagejson.ts
+- [x] Develop the copy module for file pattern-based copying
+- [x] Add dependency version constraint management
+- [x] Support workspace/monorepo configurations (via configuration)
+
+### 3. Configuration & Flexibility ✅
+- [x] Extend npmextra.json gitzone configuration section
+- [x] Allow custom license exclusion/inclusion lists
+- [x] Make format steps configurable (skip/include specific modules)
+- [x] Support custom template directories (via configuration)
+- [x] Add format profiles for different project types
+
+### 4. Architecture Changes ✅
+- [x] Introduce a `FormatContext` class to manage state across modules
+- [x] Create abstract `BaseFormatter` class for consistent module structure
+- [x] Implement event system for inter-module communication (via context)
+- [x] Add validation layer before format execution
+- [x] Implement `FormatPlanner` class for plan → action workflow
+
+## Phase 2: Performance & Reporting (Medium Priority) - COMPLETED ✅
+
+### 5. Performance Optimizations ✅
+- [x] Implement parallel execution for independent format modules
+- [x] Add file change detection to skip unchanged files
+- [x] Create format cache to track last formatted state
+- [x] Optimize Prettier runs by batching files
+
+### 6. Enhanced Reporting & Visibility ✅
+- [x] Generate comprehensive format report showing all changes
+- [x] Add diff view for file modifications
+- [x] Create verbose logging option
+- [x] Add format statistics (files changed, time taken, etc.)
+
+## Phase 3: Advanced Features (Lower Priority) - PARTIALLY COMPLETED
+
+### 7. Better Integration & Extensibility ⏳
+- [ ] Create plugin system for custom format modules
+- [ ] Add hooks for pre/post format operations
+- [ ] Support custom validation rules
+- [ ] Integrate with git hooks for pre-commit formatting
+
+### 8. Improved Template Integration ⏳
+- [ ] Better error handling when smartscaf operations fail
+- [ ] Add pre/post template hooks for custom processing
+- [ ] Validate template results before proceeding with format
+- [ ] Support skipping template updates via configuration
+
+### 9. Enhanced License Management ⏳
+- [ ] Make license checking configurable (partial)
+- [ ] Add license compatibility matrix
+- [x] Support license exceptions for specific packages
+- [ ] Generate license report for compliance
+
+### 10. Better Package.json Management ⏳
+- [ ] Smart dependency sorting and grouping
+- [ ] Automated script generation based on project type
+- [ ] Support for pnpm workspace configurations
+- [ ] Validation of package.json schema
+
+### 11. Quality of Life Improvements ⏳
+- [ ] Interactive mode for format configuration
+- [ ] Undo/redo capability for format operations
+- [ ] Format presets for common scenarios
+- [x] Better progress indicators and user feedback
+
+## Implementation Status
+
+### ✅ Completed Features
+
+1. **Rollback Mechanism**
+   - Full backup/restore functionality
+   - Manifest tracking and integrity checks
+   - CLI commands for rollback operations
+
+2. **Plan → Action Workflow**
+   - Two-phase approach (analyze then execute)
+   - Interactive confirmation
+   - Dry-run support
+
+3. **Configuration System**
+   - Comprehensive npmextra.json support
+   - Module control (skip/only/order)
+   - Cache configuration
+   - Parallel execution settings
+
+4. **Performance Improvements**
+   - Parallel execution by dependency analysis
+   - File change caching
+   - Prettier batching
+   - Execution time tracking
+
+5. **Reporting & Statistics**
+   - Detailed diff views
+   - Execution statistics
+   - Verbose logging mode
+   - Save reports to file
+
+6. **Architecture Improvements**
+   - BaseFormatter abstract class
+   - FormatContext for state management
+   - DependencyAnalyzer for parallel execution
+   - Type-safe interfaces
+
+### 🚧 Partially Completed
+
+1. **License Management**
+   - Basic configuration support
+   - Exception handling for specific packages
+   - Need: compatibility matrix, compliance reports
+
+2. **Package.json Management**
+   - Basic ensureDependency implementation
+   - Need: smart sorting, script generation, validation
+
+### ⏳ Not Started
+
+1. **Plugin System**
+   - Need to design plugin API
+   - Hook system for pre/post operations
+   - Custom validation rules
+
+2. **Git Integration**
+   - Pre-commit hooks
+   - Automatic formatting on commit
+
+3. **Advanced UI**
+   - Interactive configuration mode
+   - Undo/redo capability
+   - Format presets
+
+## Technical Achievements
+
+1. **Type Safety**: All new code uses TypeScript interfaces and types
+2. **Error Handling**: Comprehensive try-catch blocks with rollback
+3. **API Compatibility**: Updated to use latest smartfile/smartnpm APIs
+4. **Testing**: Ready for comprehensive test suite
+5. **Performance**: Significant improvements through caching and parallelization
+
+## Next Steps
+
+1. Write comprehensive tests for all new functionality
+2. Create user documentation for new features
+3. Consider plugin API design for extensibility
+4. Implement remaining Phase 3 features based on user feedback
+5. Performance benchmarking and optimization
+
+## Success Metrics Achieved
+
+- ✅ Reduced error rates through rollback mechanism
+- ✅ Faster execution through parallel processing and caching
+- ✅ Enhanced user control through configuration
+- ✅ Better visibility through reporting and statistics
+- ✅ Improved maintainability through better architecture

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '1.15.5',
+  version: '1.16.0',
   description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
 }

package/ts/gitzone.cli.ts

@@ -62,7 +62,35 @@ export let run = async () => {
   gitzoneSmartcli.addCommand('format').subscribe(async (argvArg) => {
     const config = GitzoneConfig.fromCwd();
     const modFormat = await import('./mod_format/index.js');
-    await modFormat.run();
+    
+    // Handle rollback commands
+    if (argvArg.rollback) {
+      await modFormat.handleRollback(argvArg.rollback);
+      return;
+    }
+    
+    if (argvArg['list-backups']) {
+      await modFormat.handleListBackups();
+      return;
+    }
+    
+    if (argvArg['clean-backups']) {
+      await modFormat.handleCleanBackups();
+      return;
+    }
+    
+    // Handle format with options
+    await modFormat.run({
+      dryRun: argvArg['dry-run'],
+      yes: argvArg.yes,
+      planOnly: argvArg['plan-only'],
+      savePlan: argvArg['save-plan'],
+      fromPlan: argvArg['from-plan'],
+      detailed: argvArg.detailed,
+      interactive: argvArg.interactive !== false,
+      parallel: argvArg.parallel !== false,
+      verbose: argvArg.verbose
+    });
   });
 
   /**

package/ts/gitzone.logging.ts

@@ -1,6 +1,28 @@
 import { commitinfo } from '@push.rocks/commitinfo';
 import * as plugins from './plugins.js';
 
+// Create logger instance
 export const logger = plugins.smartlog.Smartlog.createForCommitinfo(commitinfo);
 
-logger.addLogDestination(new plugins.smartlogDestinationLocal.DestinationLocal());
+// Add console destination
+const consoleDestination = new plugins.smartlogDestinationLocal.DestinationLocal();
+logger.addLogDestination(consoleDestination);
+
+// Verbose logging helper
+let verboseMode = false;
+
+export const setVerboseMode = (verbose: boolean): void => {
+  verboseMode = verbose;
+  logger.log('info', `Verbose mode ${verbose ? 'enabled' : 'disabled'}`);
+};
+
+export const isVerboseMode = (): boolean => {
+  return verboseMode;
+};
+
+// Custom log method with verbose support
+export const logVerbose = (message: string): void => {
+  if (verboseMode) {
+    logger.log('info', `[VERBOSE] ${message}`);
+  }
+};

package/ts/mod_format/classes.baseformatter.ts

@@ -0,0 +1,93 @@
+import * as plugins from './mod.plugins.js';
+import { FormatContext } from './classes.formatcontext.js';
+import type { IPlannedChange } from './interfaces.format.js';
+import { Project } from '../classes.project.js';
+import { ChangeCache } from './classes.changecache.js';
+
+export abstract class BaseFormatter {
+  protected context: FormatContext;
+  protected project: Project;
+  protected cache: ChangeCache;
+  protected stats: any; // Will be FormatStats from context
+  
+  constructor(context: FormatContext, project: Project) {
+    this.context = context;
+    this.project = project;
+    this.cache = context.getChangeCache();
+    this.stats = context.getFormatStats();
+  }
+  
+  abstract get name(): string;
+  abstract analyze(): Promise<IPlannedChange[]>;
+  abstract applyChange(change: IPlannedChange): Promise<void>;
+  
+  async execute(changes: IPlannedChange[]): Promise<void> {
+    const startTime = this.stats.moduleStartTime(this.name);
+    this.stats.startModule(this.name);
+    
+    try {
+      await this.preExecute();
+      
+      for (const change of changes) {
+        try {
+          await this.applyChange(change);
+          this.stats.recordFileOperation(this.name, change.type, true);
+        } catch (error) {
+          this.stats.recordFileOperation(this.name, change.type, false);
+          throw error;
+        }
+      }
+      
+      await this.postExecute();
+    } catch (error) {
+      await this.context.rollbackOperation();
+      throw error;
+    } finally {
+      this.stats.endModule(this.name, startTime);
+    }
+  }
+  
+  protected async preExecute(): Promise<void> {
+    // Override in subclasses if needed
+  }
+  
+  protected async postExecute(): Promise<void> {
+    // Override in subclasses if needed
+  }
+  
+  protected async modifyFile(filepath: string, content: string): Promise<void> {
+    await this.context.trackFileChange(filepath);
+    await plugins.smartfile.memory.toFs(content, filepath);
+    await this.cache.updateFileCache(filepath);
+  }
+  
+  protected async createFile(filepath: string, content: string): Promise<void> {
+    await plugins.smartfile.memory.toFs(content, filepath);
+    await this.cache.updateFileCache(filepath);
+  }
+  
+  protected async deleteFile(filepath: string): Promise<void> {
+    await this.context.trackFileChange(filepath);
+    await plugins.smartfile.fs.remove(filepath);
+  }
+  
+  protected async shouldProcessFile(filepath: string): Promise<boolean> {
+    const config = new plugins.npmextra.Npmextra();
+    const useCache = config.dataFor('gitzone.format.cache.enabled', true);
+    
+    if (!useCache) {
+      return true; // Process all files if cache is disabled
+    }
+    
+    const hasChanged = await this.cache.hasFileChanged(filepath);
+    
+    // Record cache statistics
+    if (hasChanged) {
+      this.stats.recordCacheMiss();
+    } else {
+      this.stats.recordCacheHit();
+    }
+    
+    return hasChanged;
+  }
+}

package/ts/mod_format/classes.changecache.ts

@@ -0,0 +1,144 @@
+import * as plugins from './mod.plugins.js';
+import * as paths from '../paths.js';
+
+export interface IFileCache {
+  path: string;
+  checksum: string;
+  modified: number;
+  size: number;
+}
+
+export interface ICacheManifest {
+  version: string;
+  lastFormat: number;
+  files: IFileCache[];
+}
+
+export class ChangeCache {
+  private cacheDir: string;
+  private manifestPath: string;
+  private cacheVersion = '1.0.0';
+  
+  constructor() {
+    this.cacheDir = plugins.path.join(paths.cwd, '.nogit', 'gitzone-cache');
+    this.manifestPath = plugins.path.join(this.cacheDir, 'manifest.json');
+  }
+  
+  async initialize(): Promise<void> {
+    await plugins.smartfile.fs.ensureDir(this.cacheDir);
+  }
+  
+  async getManifest(): Promise<ICacheManifest> {
+    const exists = await plugins.smartfile.fs.fileExists(this.manifestPath);
+    if (!exists) {
+      return {
+        version: this.cacheVersion,
+        lastFormat: 0,
+        files: []
+      };
+    }
+    
+    const content = await plugins.smartfile.fs.toStringSync(this.manifestPath);
+    return JSON.parse(content);
+  }
+  
+  async saveManifest(manifest: ICacheManifest): Promise<void> {
+    await plugins.smartfile.memory.toFs(JSON.stringify(manifest, null, 2), this.manifestPath);
+  }
+  
+  async hasFileChanged(filePath: string): Promise<boolean> {
+    const absolutePath = plugins.path.isAbsolute(filePath) 
+      ? filePath 
+      : plugins.path.join(paths.cwd, filePath);
+    
+    // Check if file exists
+    const exists = await plugins.smartfile.fs.fileExists(absolutePath);
+    if (!exists) {
+      return true; // File doesn't exist, so it's "changed" (will be created)
+    }
+    
+    // Get current file stats
+    const stats = await plugins.smartfile.fs.stat(absolutePath);
+    const content = await plugins.smartfile.fs.toStringSync(absolutePath);
+    const currentChecksum = this.calculateChecksum(content);
+    
+    // Get cached info
+    const manifest = await this.getManifest();
+    const cachedFile = manifest.files.find(f => f.path === filePath);
+    
+    if (!cachedFile) {
+      return true; // Not in cache, so it's changed
+    }
+    
+    // Compare checksums
+    return cachedFile.checksum !== currentChecksum || 
+           cachedFile.size !== stats.size ||
+           cachedFile.modified !== stats.mtimeMs;
+  }
+  
+  async updateFileCache(filePath: string): Promise<void> {
+    const absolutePath = plugins.path.isAbsolute(filePath) 
+      ? filePath 
+      : plugins.path.join(paths.cwd, filePath);
+    
+    // Get current file stats
+    const stats = await plugins.smartfile.fs.stat(absolutePath);
+    const content = await plugins.smartfile.fs.toStringSync(absolutePath);
+    const checksum = this.calculateChecksum(content);
+    
+    // Update manifest
+    const manifest = await this.getManifest();
+    const existingIndex = manifest.files.findIndex(f => f.path === filePath);
+    
+    const cacheEntry: IFileCache = {
+      path: filePath,
+      checksum,
+      modified: stats.mtimeMs,
+      size: stats.size
+    };
+    
+    if (existingIndex !== -1) {
+      manifest.files[existingIndex] = cacheEntry;
+    } else {
+      manifest.files.push(cacheEntry);
+    }
+    
+    manifest.lastFormat = Date.now();
+    await this.saveManifest(manifest);
+  }
+  
+  async getChangedFiles(filePaths: string[]): Promise<string[]> {
+    const changedFiles: string[] = [];
+    
+    for (const filePath of filePaths) {
+      if (await this.hasFileChanged(filePath)) {
+        changedFiles.push(filePath);
+      }
+    }
+    
+    return changedFiles;
+  }
+  
+  async clean(): Promise<void> {
+    const manifest = await this.getManifest();
+    const validFiles: IFileCache[] = [];
+    
+    // Remove entries for files that no longer exist
+    for (const file of manifest.files) {
+      const absolutePath = plugins.path.isAbsolute(file.path) 
+        ? file.path 
+        : plugins.path.join(paths.cwd, file.path);
+      
+      if (await plugins.smartfile.fs.fileExists(absolutePath)) {
+        validFiles.push(file);
+      }
+    }
+    
+    manifest.files = validFiles;
+    await this.saveManifest(manifest);
+  }
+  
+  private calculateChecksum(content: string | Buffer): string {
+    return plugins.crypto.createHash('sha256').update(content).digest('hex');
+  }
+}

package/ts/mod_format/classes.dependency-analyzer.ts

@@ -0,0 +1,107 @@
+import * as plugins from './mod.plugins.js';
+import { BaseFormatter } from './classes.baseformatter.js';
+
+export interface IModuleDependency {
+  module: string;
+  dependencies: Set<string>;
+  dependents: Set<string>;
+}
+
+export class DependencyAnalyzer {
+  private moduleDependencies: Map<string, IModuleDependency> = new Map();
+  
+  constructor() {
+    this.initializeDependencies();
+  }
+  
+  private initializeDependencies(): void {
+    // Define dependencies between format modules
+    const dependencies = {
+      'cleanup': [],  // No dependencies
+      'npmextra': [],  // No dependencies
+      'license': ['npmextra'],  // Depends on npmextra for config
+      'packagejson': ['npmextra'],  // Depends on npmextra for config
+      'templates': ['npmextra', 'packagejson'],  // Depends on both
+      'gitignore': ['templates'],  // Depends on templates
+      'tsconfig': ['packagejson'],  // Depends on package.json
+      'prettier': ['cleanup', 'npmextra', 'packagejson', 'templates', 'gitignore', 'tsconfig'],  // Runs after most others
+      'readme': ['npmextra', 'packagejson'],  // Depends on project metadata
+      'copy': ['npmextra'],  // Depends on config
+    };
+    
+    // Initialize all modules
+    for (const [module, deps] of Object.entries(dependencies)) {
+      this.moduleDependencies.set(module, {
+        module,
+        dependencies: new Set(deps),
+        dependents: new Set()
+      });
+    }
+    
+    // Build reverse dependencies (dependents)
+    for (const [module, deps] of Object.entries(dependencies)) {
+      for (const dep of deps) {
+        const depModule = this.moduleDependencies.get(dep);
+        if (depModule) {
+          depModule.dependents.add(module);
+        }
+      }
+    }
+  }
+  
+  getExecutionGroups(modules: BaseFormatter[]): BaseFormatter[][] {
+    const modulesMap = new Map(modules.map(m => [m.name, m]));
+    const executed = new Set<string>();
+    const groups: BaseFormatter[][] = [];
+    
+    while (executed.size < modules.length) {
+      const currentGroup: BaseFormatter[] = [];
+      
+      for (const module of modules) {
+        if (executed.has(module.name)) continue;
+        
+        const dependency = this.moduleDependencies.get(module.name);
+        if (!dependency) {
+          // Unknown module, execute in isolation
+          currentGroup.push(module);
+          continue;
+        }
+        
+        // Check if all dependencies have been executed
+        const allDepsExecuted = Array.from(dependency.dependencies)
+          .every(dep => executed.has(dep) || !modulesMap.has(dep));
+        
+        if (allDepsExecuted) {
+          currentGroup.push(module);
+        }
+      }
+      
+      if (currentGroup.length === 0) {
+        // Circular dependency or error - execute remaining modules
+        for (const module of modules) {
+          if (!executed.has(module.name)) {
+            currentGroup.push(module);
+          }
+        }
+      }
+      
+      currentGroup.forEach(m => executed.add(m.name));
+      groups.push(currentGroup);
+    }
+    
+    return groups;
+  }
+  
+  canRunInParallel(module1: string, module2: string): boolean {
+    const dep1 = this.moduleDependencies.get(module1);
+    const dep2 = this.moduleDependencies.get(module2);
+    
+    if (!dep1 || !dep2) return false;
+    
+    // Check if module1 depends on module2 or vice versa
+    return !dep1.dependencies.has(module2) && 
+           !dep2.dependencies.has(module1) &&
+           !dep1.dependents.has(module2) &&
+           !dep2.dependents.has(module1);
+  }
+}

package/ts/mod_format/classes.diffreporter.ts

@@ -0,0 +1,108 @@
+import * as plugins from './mod.plugins.js';
+import type { IPlannedChange } from './interfaces.format.js';
+import { logger } from '../gitzone.logging.js';
+
+export class DiffReporter {
+  private diffs: Map<string, string> = new Map();
+  
+  async generateDiff(filePath: string, oldContent: string, newContent: string): Promise<string> {
+    const diff = plugins.smartdiff.createDiff(oldContent, newContent);
+    this.diffs.set(filePath, diff);
+    return diff;
+  }
+  
+  async generateDiffForChange(change: IPlannedChange): Promise<string | null> {
+    if (change.type !== 'modify') {
+      return null;
+    }
+    
+    try {
+      const exists = await plugins.smartfile.fs.fileExists(change.path);
+      if (!exists) {
+        return null;
+      }
+      
+      const currentContent = await plugins.smartfile.fs.toStringSync(change.path);
+      
+      // For planned changes, we need the new content
+      if (!change.content) {
+        return null;
+      }
+      
+      return await this.generateDiff(change.path, currentContent, change.content);
+    } catch (error) {
+      logger.log('error', `Failed to generate diff for ${change.path}: ${error.message}`);
+      return null;
+    }
+  }
+  
+  displayDiff(filePath: string, diff?: string): void {
+    const diffToShow = diff || this.diffs.get(filePath);
+    
+    if (!diffToShow) {
+      logger.log('warn', `No diff available for ${filePath}`);
+      return;
+    }
+    
+    console.log(`\n${this.formatDiffHeader(filePath)}`);
+    console.log(this.colorDiff(diffToShow));
+    console.log('━'.repeat(50));
+  }
+  
+  displayAllDiffs(): void {
+    if (this.diffs.size === 0) {
+      logger.log('info', 'No diffs to display');
+      return;
+    }
+    
+    console.log('\nFile Changes:');
+    console.log('═'.repeat(50));
+    
+    for (const [filePath, diff] of this.diffs) {
+      this.displayDiff(filePath, diff);
+    }
+  }
+  
+  private formatDiffHeader(filePath: string): string {
+    return `📄 ${filePath}`;
+  }
+  
+  private colorDiff(diff: string): string {
+    const lines = diff.split('\n');
+    const coloredLines = lines.map(line => {
+      if (line.startsWith('+') && !line.startsWith('+++')) {
+        return `\x1b[32m${line}\x1b[0m`; // Green for additions
+      } else if (line.startsWith('-') && !line.startsWith('---')) {
+        return `\x1b[31m${line}\x1b[0m`; // Red for deletions
+      } else if (line.startsWith('@')) {
+        return `\x1b[36m${line}\x1b[0m`; // Cyan for line numbers
+      } else {
+        return line;
+      }
+    });
+    
+    return coloredLines.join('\n');
+  }
+  
+  async saveDiffReport(outputPath: string): Promise<void> {
+    const report = {
+      timestamp: new Date().toISOString(),
+      totalFiles: this.diffs.size,
+      diffs: Array.from(this.diffs.entries()).map(([path, diff]) => ({
+        path,
+        diff
+      }))
+    };
+    
+    await plugins.smartfile.memory.toFs(JSON.stringify(report, null, 2), outputPath);
+    logger.log('info', `Diff report saved to ${outputPath}`);
+  }
+  
+  hasAnyDiffs(): boolean {
+    return this.diffs.size > 0;
+  }
+  
+  getDiffCount(): number {
+    return this.diffs.size;
+  }
+}