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

```json
{
  "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

```bash
# 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