coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity

Issue #143: Phase 2 - CLI Integration and User Experience (Week 3) #143

New Issue
Closed
opened 2025-10-08 07:50:21 +00:00 by tegwick · 0 comments
tegwick commented 2025-10-08 07:50:21 +00:00
Owner
Copy Link

Phase 2: CLI Integration and User Experience

Parent Issue: #141 - Asset Management Concepts (Variant B)
Dependencies: Issue #142 (Phase 1 Core Module)
Timeline: Week 3
Status: 🔄 Ready for Development

Overview

Complete the CLI integration and user experience for the asset management system, building on the core module from Phase 1. Focus on creating a polished command-line interface that integrates seamlessly with existing markitect workflows.

Deliverables

1. Complete CLI Command Suite

Asset Management Commands

  • markitect asset add <file> <document> [--name NAME] - Add asset with deduplication
  • markitect asset list [--document DOC] [--unused] [--format FORMAT] - List assets
  • markitect asset dedupe [--dry-run] [--force] - Deduplicate assets
  • markitect asset stats - Show asset library statistics
  • markitect asset cleanup [--orphaned] [--dry-run] - Clean unused assets

Package Management Commands

  • markitect package create <document-dir> <package-name> - Create .mdpkg
  • markitect package extract <package-file> [--name NAME] - Extract package
  • markitect package list [--format FORMAT] - List packages
  • markitect package validate <package-file> - Validate package integrity

Workspace Management Commands

  • markitect workspace init [--template TEMPLATE] - Initialize workspace
  • markitect workspace status - Show workspace status
  • markitect workspace sync [--document DOC] - Sync workspace assets

2. CLI Integration and User Experience

Command Registration

  • Integrate asset commands with main markitect/cli.py
  • Follow existing Click command group patterns
  • Consistent help text and error messages
  • Tab completion support for commands and paths

Output Formatting

  • Table format for asset and package listings (default)
  • JSON format for programmatic consumption
  • Progress bars for long-running operations
  • Color-coded status indicators
  • Consistent formatting with existing markitect commands

Error Handling

  • Informative error messages with suggested fixes
  • Graceful handling of permission errors
  • Validation of file paths and arguments
  • Confirmation prompts for destructive operations

3. Configuration Management Integration

Configuration Schema Extension

# markitect.yaml
asset_management:
  enabled: true
  workspace_path: "./markitect_workspace"
  shared_assets_path: "./markitect_workspace/shared_assets"  
  packages_path: "./markitect_workspace/packages"
  
  # Deduplication settings
  auto_dedupe: true
  symlink_preferred: true
  fallback_to_copy: true  # Windows compatibility
  
  # Package settings
  compression_level: 6
  include_manifest: true
  validate_on_create: true
  
  # Performance settings
  cache_enabled: true
  batch_size: 100
  max_file_size_mb: 50

Configuration Integration

  • Extend ConfigurationManager with asset settings
  • Validate configuration on startup
  • Provide sensible defaults for all settings
  • Support per-project configuration overrides

4. User Documentation

Command Documentation

  • Comprehensive help text for all commands
  • Usage examples for common workflows
  • Option descriptions and default values
  • Integration with existing markitect help system

User Guide Section

  • Getting started with asset management
  • Asset deduplication workflow
  • Package creation and sharing
  • Workspace management best practices
  • Troubleshooting common issues

Acceptance Criteria

Functional Requirements

  • All CLI commands work correctly with proper error handling
  • Commands integrate seamlessly with existing markitect workflows
  • Configuration management works with existing config system
  • Help text is comprehensive and accurate
  • Output formatting is consistent and user-friendly

User Experience Requirements

  • Commands follow markitect CLI conventions and patterns
  • Error messages are clear and actionable
  • Progress feedback for operations taking >2 seconds
  • Tab completion works for commands and file paths
  • Destructive operations require confirmation

Performance Requirements

  • Command startup time <500ms
  • List operations complete in <1s for typical workspaces
  • Large file operations show progress indicators
  • Memory usage stays reasonable during batch operations

Testing Strategy

CLI Testing

  • Command argument parsing and validation
  • Output formatting for different scenarios
  • Error handling for invalid inputs
  • Integration with existing markitect CLI tests

User Experience Testing

  • End-to-end workflow testing
  • Error recovery scenarios
  • Configuration validation
  • Cross-platform behavior

Documentation Testing

  • All examples in documentation work correctly
  • Help text matches actual command behavior
  • Configuration examples are valid

Command Specifications

Asset Add Command

markitect asset add logo.png ./project_a --name company_logo.png

Options:
  --name NAME           Virtual name in document (default: original filename)
  --document PATH       Target document directory (required)
  --force              Overwrite existing virtual name  
  --no-symlink         Force file copy instead of symlink
  --help               Show command help

Asset List Command

markitect asset list --document ./project_a --format table

Options:
  --document PATH       Filter by document directory
  --unused             Show only unused assets
  --format FORMAT      Output format: table, json (default: table)
  --sort FIELD         Sort by: name, size, date (default: name)
  --help               Show command help

Package Create Command

markitect package create ./project_a project_a_v1

Options:
  --output PATH         Output directory (default: workspace/packages)
  --compression LEVEL   ZIP compression level 0-9 (default: 6)
  --exclude PATTERN     Exclude files matching pattern
  --include-sources     Include source markdown files
  --validate           Validate package after creation
  --help               Show command help

Dependencies

Internal Dependencies

  • Issue #142: Core asset management module must be complete
  • markitect.cli: Main CLI framework and patterns
  • markitect.config_manager: Configuration management
  • markitect.database: Database integration

External Dependencies

  • Click: CLI framework (existing)
  • Rich: Enhanced terminal output (optional)
  • Colorama: Cross-platform color support (optional)

Risks and Mitigations

Risk: CLI commands become too complex for users
Mitigation: Progressive disclosure, good defaults, comprehensive help

Risk: Performance issues with large workspaces
Mitigation: Pagination, lazy loading, progress indicators

Risk: Configuration conflicts with existing settings
Mitigation: Careful schema design, validation, backward compatibility

Definition of Done

  • All CLI commands implemented and tested
  • Integration with main markitect CLI complete
  • Configuration management extended and working
  • User documentation written and tested
  • All acceptance criteria met
  • Code review completed and approved
  • No regressions in existing markitect functionality

Estimated Effort: 1 week
Priority: High
Complexity: Medium

# Phase 2: CLI Integration and User Experience **Parent Issue**: #141 - Asset Management Concepts (Variant B) **Dependencies**: Issue #142 (Phase 1 Core Module) **Timeline**: Week 3 **Status**: 🔄 Ready for Development ## Overview Complete the CLI integration and user experience for the asset management system, building on the core module from Phase 1. Focus on creating a polished command-line interface that integrates seamlessly with existing markitect workflows. ## Deliverables ### 1. Complete CLI Command Suite #### Asset Management Commands - [ ] `markitect asset add <file> <document> [--name NAME]` - Add asset with deduplication - [ ] `markitect asset list [--document DOC] [--unused] [--format FORMAT]` - List assets - [ ] `markitect asset dedupe [--dry-run] [--force]` - Deduplicate assets - [ ] `markitect asset stats` - Show asset library statistics - [ ] `markitect asset cleanup [--orphaned] [--dry-run]` - Clean unused assets #### Package Management Commands - [ ] `markitect package create <document-dir> <package-name>` - Create .mdpkg - [ ] `markitect package extract <package-file> [--name NAME]` - Extract package - [ ] `markitect package list [--format FORMAT]` - List packages - [ ] `markitect package validate <package-file>` - Validate package integrity #### Workspace Management Commands - [ ] `markitect workspace init [--template TEMPLATE]` - Initialize workspace - [ ] `markitect workspace status` - Show workspace status - [ ] `markitect workspace sync [--document DOC]` - Sync workspace assets ### 2. CLI Integration and User Experience #### Command Registration - [ ] Integrate asset commands with main `markitect/cli.py` - [ ] Follow existing Click command group patterns - [ ] Consistent help text and error messages - [ ] Tab completion support for commands and paths #### Output Formatting - [ ] Table format for asset and package listings (default) - [ ] JSON format for programmatic consumption - [ ] Progress bars for long-running operations - [ ] Color-coded status indicators - [ ] Consistent formatting with existing markitect commands #### Error Handling - [ ] Informative error messages with suggested fixes - [ ] Graceful handling of permission errors - [ ] Validation of file paths and arguments - [ ] Confirmation prompts for destructive operations ### 3. Configuration Management Integration #### Configuration Schema Extension ```yaml # markitect.yaml asset_management: enabled: true workspace_path: "./markitect_workspace" shared_assets_path: "./markitect_workspace/shared_assets" packages_path: "./markitect_workspace/packages" # Deduplication settings auto_dedupe: true symlink_preferred: true fallback_to_copy: true # Windows compatibility # Package settings compression_level: 6 include_manifest: true validate_on_create: true # Performance settings cache_enabled: true batch_size: 100 max_file_size_mb: 50 ``` #### Configuration Integration - [ ] Extend `ConfigurationManager` with asset settings - [ ] Validate configuration on startup - [ ] Provide sensible defaults for all settings - [ ] Support per-project configuration overrides ### 4. User Documentation #### Command Documentation - [ ] Comprehensive help text for all commands - [ ] Usage examples for common workflows - [ ] Option descriptions and default values - [ ] Integration with existing markitect help system #### User Guide Section - [ ] Getting started with asset management - [ ] Asset deduplication workflow - [ ] Package creation and sharing - [ ] Workspace management best practices - [ ] Troubleshooting common issues ## Acceptance Criteria ### Functional Requirements - [ ] All CLI commands work correctly with proper error handling - [ ] Commands integrate seamlessly with existing markitect workflows - [ ] Configuration management works with existing config system - [ ] Help text is comprehensive and accurate - [ ] Output formatting is consistent and user-friendly ### User Experience Requirements - [ ] Commands follow markitect CLI conventions and patterns - [ ] Error messages are clear and actionable - [ ] Progress feedback for operations taking >2 seconds - [ ] Tab completion works for commands and file paths - [ ] Destructive operations require confirmation ### Performance Requirements - [ ] Command startup time <500ms - [ ] List operations complete in <1s for typical workspaces - [ ] Large file operations show progress indicators - [ ] Memory usage stays reasonable during batch operations ## Testing Strategy ### CLI Testing - [ ] Command argument parsing and validation - [ ] Output formatting for different scenarios - [ ] Error handling for invalid inputs - [ ] Integration with existing markitect CLI tests ### User Experience Testing - [ ] End-to-end workflow testing - [ ] Error recovery scenarios - [ ] Configuration validation - [ ] Cross-platform behavior ### Documentation Testing - [ ] All examples in documentation work correctly - [ ] Help text matches actual command behavior - [ ] Configuration examples are valid ## Command Specifications ### Asset Add Command ```bash markitect asset add logo.png ./project_a --name company_logo.png Options: --name NAME Virtual name in document (default: original filename) --document PATH Target document directory (required) --force Overwrite existing virtual name --no-symlink Force file copy instead of symlink --help Show command help ``` ### Asset List Command ```bash markitect asset list --document ./project_a --format table Options: --document PATH Filter by document directory --unused Show only unused assets --format FORMAT Output format: table, json (default: table) --sort FIELD Sort by: name, size, date (default: name) --help Show command help ``` ### Package Create Command ```bash markitect package create ./project_a project_a_v1 Options: --output PATH Output directory (default: workspace/packages) --compression LEVEL ZIP compression level 0-9 (default: 6) --exclude PATTERN Exclude files matching pattern --include-sources Include source markdown files --validate Validate package after creation --help Show command help ``` ## Dependencies ### Internal Dependencies - **Issue #142**: Core asset management module must be complete - **markitect.cli**: Main CLI framework and patterns - **markitect.config_manager**: Configuration management - **markitect.database**: Database integration ### External Dependencies - **Click**: CLI framework (existing) - **Rich**: Enhanced terminal output (optional) - **Colorama**: Cross-platform color support (optional) ## Risks and Mitigations **Risk**: CLI commands become too complex for users **Mitigation**: Progressive disclosure, good defaults, comprehensive help **Risk**: Performance issues with large workspaces **Mitigation**: Pagination, lazy loading, progress indicators **Risk**: Configuration conflicts with existing settings **Mitigation**: Careful schema design, validation, backward compatibility ## Definition of Done - [ ] All CLI commands implemented and tested - [ ] Integration with main markitect CLI complete - [ ] Configuration management extended and working - [ ] User documentation written and tested - [ ] All acceptance criteria met - [ ] Code review completed and approved - [ ] No regressions in existing markitect functionality --- **Estimated Effort**: 1 week **Priority**: High **Complexity**: Medium
tegwick added this to the Images And File Attachments project 2025-10-08 08:17:57 +00:00
tegwick moved this to Active in Images And File Attachments on 2025-10-14 09:44:47 +00:00
tegwick moved this to Done in Images And File Attachments on 2025-10-14 13:44:14 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
priority:critical
Critical priority issue
 priority:high
High priority issue
 priority:low
Low priority issue
 priority:medium
Medium priority issue
 status:active
Issues currently being worked on
 status:blocked
Issues blocked by dependencies
 status:done
Completed issues
 status:review
Issues under review
 status:todo
Issues ready to be worked on
 type:bug
Bug report
 type:documentation
Documentation update
 type:enhancement
Enhancement to existing feature
 type:feature
New feature request
 wish
Feature wishlist item - idea to be discussed and refined
 wish/archived
Archived or rejected wishlist item
 wish/discussion
Wishlist item currently being discussed and refined
 wish/draft
Wishlist item with initial draft specification
 wish/ready
Wishlist item ready to become a regular issue
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project Images And File Attachments
Assignees
Clear assignees
bubble-reader tegwick
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: coulomb/markitect-main#143
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?