cli/readme.hints.md

Gitzone CLI - Development Hints

• the cli of the git.zone project.

Project Overview

Gitzone CLI (@git.zone/cli) is a comprehensive toolbelt for streamlining local development cycles. It provides utilities for:

• Project initialization and templating (via smartscaf)
• Code formatting and standardization
• Version control and commit management
• Docker and CI/CD integration
• Meta project management

Architecture

Core Structure

• Main CLI entry: cli.ts / cli.child.ts
• Modular architecture with separate modules in ts/mod_* directories
• Each module handles specific functionality (format, commit, docker, etc.)
• Extensive use of plugins pattern via plugins.ts files

Configuration Management

• Uses npmextra.json for all tool configuration
• Configuration stored under gitzone key in npmextra
• No separate .gitzonerc file - everything in npmextra.json
• Project type and module metadata also stored in npmextra

Format Module (mod_format) - SIGNIFICANTLY ENHANCED

The format module is responsible for project standardization:

Current Modules:

1. cleanup - Removes obsolete files (yarn.lock, tslint.json, etc.)
2. copy - File copying with glob patterns (fully implemented)
3. gitignore - Creates/updates .gitignore from templates
4. license - Checks dependency licenses for compatibility
5. npmextra - Manages project metadata and configuration
6. packagejson - Formats and updates package.json
7. prettier - Applies code formatting with batching
8. readme - Ensures readme files exist
9. templates - Updates project templates based on type
10. tsconfig - Formats TypeScript configuration

Execution Order (Dependency-Based):

• Modules are now executed in parallel groups based on dependencies
• Independent modules run concurrently for better performance
• Dependency analyzer ensures correct execution order

New Architecture Features

1. BaseFormatter Pattern: All formatters extend abstract BaseFormatter class
2. FormatContext: Central state management across all modules
3. FormatPlanner: Implements plan → action workflow
4. RollbackManager: Full backup/restore capabilities
5. ChangeCache: Tracks file changes to optimize performance
6. DependencyAnalyzer: Manages module execution order
7. DiffReporter: Generates diff views for changes
8. FormatStats: Comprehensive execution statistics

Key Patterns

1. Plugin Architecture: All dependencies imported through plugins.ts files
2. Streaming: Uses smartstream for file processing
3. Interactive Prompts: smartinteract for user input
4. Enhanced Error Handling: Comprehensive try-catch with automatic rollback
5. Template System: Templates handled by smartscaf, not directly by gitzone
6. Type Safety: Full TypeScript with interfaces and type definitions

Important Notes

• .nogit/ directory used for temporary/untracked files, backups, and cache
• .nogit/gitzone-backups/ stores format operation backups
• .nogit/gitzone-cache/ stores file change cache
• Templates are managed by smartscaf - improvements should be made there
• License checking configurable with exceptions support
• All features implemented: ensureDependency, copy module, etc.

Recent Improvements (Completed)

1. Plan → Action Workflow: Shows changes before applying them
2. Rollback Mechanism: Full backup and restore on failures
3. Enhanced Configuration: Granular control via npmextra.json
4. Better Error Handling: Detailed errors with recovery options
5. Performance Optimizations: Parallel execution and caching
6. Reporting: Diff views, statistics, verbose logging
7. Architecture: Clean separation of concerns with new classes

Development Tips

• Always check readme.plan.md for ongoing improvement plans
• Use npmextra.json for any new configuration options
• Keep modules focused and single-purpose
• Maintain the existing plugin pattern for dependencies
• Test format operations on sample projects before deploying
• Consider backward compatibility when changing configuration structure
• Use BaseFormatter pattern for new format modules
• Leverage FormatContext for cross-module state sharing

Configuration Examples

{
  "gitzone": {
    "format": {
      "interactive": true,
      "parallel": true,
      "showStats": true,
      "cache": {
        "enabled": true,
        "clean": true
      },
      "rollback": {
        "enabled": true,
        "autoRollbackOnError": true,
        "backupRetentionDays": 7
      },
      "modules": {
        "skip": ["prettier"],
        "only": [],
        "order": []
      },
      "licenses": {
        "allowed": ["MIT", "Apache-2.0"],
        "exceptions": {
          "some-package": "GPL-3.0"
        }
      }
    }
  }
}

CLI Usage

# Basic format
gitzone format

# Dry run to preview changes
gitzone format --dry-run

# Non-interactive mode
gitzone format --yes

# Plan only (no execution)
gitzone format --plan-only

# Save plan for later
gitzone format --save-plan format.json

# Execute saved plan
gitzone format --from-plan format.json

# Verbose mode
gitzone format --verbose

# Detailed diff views
gitzone format --detailed

# Rollback operations
gitzone format --rollback
gitzone format --rollback <operation-id>
gitzone format --list-backups
gitzone format --clean-backups

Common Issues (Now Resolved)

1. ✅ Format operations are now reversible with rollback
2. ✅ Enhanced error messages with recovery suggestions
3. ✅ All modules fully implemented (including copy)
4. ✅ Dry-run capability available
5. ✅ Extensive configuration options available

Future Considerations

• Plugin system for custom formatters
• Git hooks integration for pre-commit formatting
• Advanced UI with interactive configuration
• Format presets for common scenarios
• Performance benchmarking tools

API Changes

• smartfile API updated to use fs.* and memory.* namespaces
• smartnpm requires instance creation: new NpmRegistry()
• All file operations now use updated APIs
• Type imports use import type for proper verbatim module syntax