Phase 1: Core Asset Management Module Implementation

Parent Issue: #141 - Asset Management Concepts (Variant B)
Timeline: Week 1-2
Status: 🔄 Ready for Development

Overview

Implement the foundational asset management module following the Content-Addressable Package System with Symlinks approach (Variant B from Issue #141).

Deliverables

1. Module Structure

Create /markitect/assets/ module with:

__init__.py - Module exports and public API
registry.py - AssetRegistry class for JSON-based metadata
deduplicator.py - AssetDeduplicator class with symlink support
packager.py - MarkdownPackager class for .mdpkg operations
manager.py - AssetManager high-level API coordinator
exceptions.py - Asset-specific exception classes
constants.py - Configuration constants and defaults

2. Core Classes Implementation

AssetRegistry

JSON-based asset metadata persistence
SHA-256 content hashing for deduplication
MIME type detection and file size tracking
Thread-safe registry operations

AssetDeduplicator

Content-based asset deduplication
Symlink creation with relative paths
Windows fallback to file copying
Conflict resolution for existing assets

MarkdownPackager

.mdpkg ZIP package creation
Package extraction with symlink restoration
Manifest generation and validation
Asset resolution during packaging

AssetManager

High-level API coordinating all operations
Integration with existing markitect patterns
Error handling and logging
Configuration management integration

3. Unit Test Suite

tests/test_assets/test_registry.py - Registry operations
tests/test_assets/test_deduplicator.py - Deduplication logic
tests/test_assets/test_packager.py - Package operations
tests/test_assets/test_manager.py - High-level API
Test fixtures with sample images and documents
Cross-platform compatibility tests
80%+ code coverage target

4. Basic CLI Integration

markitect/assets/cli.py - Click command group stub
Integration with main CLI in markitect/cli.py
Basic commands: asset add, asset list, package create
Command validation and error handling

Acceptance Criteria

Functional Requirements

Assets can be stored with automatic deduplication
Symlinks work on Unix/Linux, fallback copying on Windows
.mdpkg packages can be created from document directories
Packages can be extracted to workspace with proper asset linking
JSON registry persists asset metadata correctly

Non-Functional Requirements

All operations complete in <100ms for typical files (<10MB)
Memory usage stays under 50MB for asset operations
Cross-platform compatibility (Windows, macOS, Linux)
Thread-safe operations for concurrent access

Estimated Effort: 2 weeks
Priority: High
Complexity: Medium-High

# Phase 1: Core Asset Management Module Implementation **Parent Issue**: #141 - Asset Management Concepts (Variant B) **Timeline**: Week 1-2 **Status**: 🔄 Ready for Development ## Overview Implement the foundational asset management module following the Content-Addressable Package System with Symlinks approach (Variant B from Issue #141). ## Deliverables ### 1. Module Structure Create `/markitect/assets/` module with: - [ ] `__init__.py` - Module exports and public API - [ ] `registry.py` - AssetRegistry class for JSON-based metadata - [ ] `deduplicator.py` - AssetDeduplicator class with symlink support - [ ] `packager.py` - MarkdownPackager class for .mdpkg operations - [ ] `manager.py` - AssetManager high-level API coordinator - [ ] `exceptions.py` - Asset-specific exception classes - [ ] `constants.py` - Configuration constants and defaults ### 2. Core Classes Implementation #### AssetRegistry - [ ] JSON-based asset metadata persistence - [ ] SHA-256 content hashing for deduplication - [ ] MIME type detection and file size tracking - [ ] Thread-safe registry operations #### AssetDeduplicator - [ ] Content-based asset deduplication - [ ] Symlink creation with relative paths - [ ] Windows fallback to file copying - [ ] Conflict resolution for existing assets #### MarkdownPackager - [ ] .mdpkg ZIP package creation - [ ] Package extraction with symlink restoration - [ ] Manifest generation and validation - [ ] Asset resolution during packaging #### AssetManager - [ ] High-level API coordinating all operations - [ ] Integration with existing markitect patterns - [ ] Error handling and logging - [ ] Configuration management integration ### 3. Unit Test Suite - [ ] `tests/test_assets/test_registry.py` - Registry operations - [ ] `tests/test_assets/test_deduplicator.py` - Deduplication logic - [ ] `tests/test_assets/test_packager.py` - Package operations - [ ] `tests/test_assets/test_manager.py` - High-level API - [ ] Test fixtures with sample images and documents - [ ] Cross-platform compatibility tests - [ ] 80%+ code coverage target ### 4. Basic CLI Integration - [ ] `markitect/assets/cli.py` - Click command group stub - [ ] Integration with main CLI in `markitect/cli.py` - [ ] Basic commands: `asset add`, `asset list`, `package create` - [ ] Command validation and error handling ## Acceptance Criteria ### Functional Requirements - [ ] Assets can be stored with automatic deduplication - [ ] Symlinks work on Unix/Linux, fallback copying on Windows - [ ] .mdpkg packages can be created from document directories - [ ] Packages can be extracted to workspace with proper asset linking - [ ] JSON registry persists asset metadata correctly ### Non-Functional Requirements - [ ] All operations complete in <100ms for typical files (<10MB) - [ ] Memory usage stays under 50MB for asset operations - [ ] Cross-platform compatibility (Windows, macOS, Linux) - [ ] Thread-safe operations for concurrent access --- **Estimated Effort**: 2 weeks **Priority**: High **Complexity**: Medium-High