Skip to content

Install from URL or Local Path #79

Closed
#86
Closed
Install from URL or Local Path#79
#86
Assignees
rucka
Labels
user storyWork item representing a user story

Description

@rucka
rucka
opened on Nov 8, 2025

Resolution

Delivered by PR #86 (merged). Board: Done.

feat: install KB from URL or local path.

Story Statement

As a developer
I want to install KB content from a URL, local ZIP file, or local directory using pair install --url <source>
So that I can easily access KB packages from remote sources, local archives, or extracted directories

Where: CLI command executed in target project directory

Epic Context

Parent Epic: #65 Enhanced CLI Packaging & Distribution
Status: Refined
Priority: P0 (Must-Have)

Status Workflow

  • Refined: Story is detailed, estimated, and ready for development
  • In Progress: Story is actively being developed
  • Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

  1. Remote URL Installation with Progress
    Given user has internet connectivity and valid KB ZIP URL
    When user runs pair install --url https://example.com/kb.zip
    Then CLI downloads ZIP to repo temp folder with progress bar, verifies checksum if available, extracts to .pair/, backs up existing KB to .pair.backup-{timestamp}/, displays installation summary

  2. Remote URL Installation with Checksum Verification
    Given remote KB ZIP has accompanying .sha256 checksum file
    When user runs pair install --url https://example.com/kb.zip
    Then CLI downloads both ZIP and checksum, validates integrity before extraction, fails installation if checksum mismatch with clear error message

  3. Remote Download Resumption
    Given download interrupted due to network failure
    When user re-runs pair install --url https://example.com/kb.zip
    Then CLI resumes download from last successful byte position, displays resumed progress, completes installation

  4. Local ZIP File Installation (Absolute Path)
    Given valid KB ZIP file at /absolute/path/kb.zip
    When user runs pair install --url /absolute/path/kb.zip
    Then CLI detects local ZIP, extracts to .pair/, backs up existing KB, displays installation summary

  5. Local ZIP File Installation (Relative Path)
    Given valid KB ZIP file at ./downloads/kb.zip
    When user runs pair install --url ./downloads/kb.zip
    Then CLI resolves path from CWD, detects local ZIP, extracts to .pair/, backs up existing KB, displays installation summary

  6. Local Directory Installation (Direct Subfolder)
    Given valid KB directory at ./dataset/ within target repo
    When user runs pair install --url ./dataset/
    Then CLI validates directory structure, installs directly without copy (in-place), backs up existing KB, displays installation summary

  7. Local Directory Installation (External Location)
    Given valid KB directory at /external/path/kb-dataset/ outside target repo
    When user runs pair install --url /external/path/kb-dataset/
    Then CLI validates directory structure, copies to repo temp folder, installs to .pair/, backs up existing KB, displays installation summary

  8. Progress Bar Display
    Given any source type (remote URL, local ZIP, directory)
    When installation progresses through download/copy/extract phases
    Then CLI displays progress bar with percentage, current operation (downloading/extracting/copying), file count or MB transferred

Business Rules

  • Source Detection: Automatic detection via URL protocol (http://, https://) → remote; .zip extension → local ZIP; directory path → local directory
  • Checksum Validation: If .sha256 file exists at {url}.sha256, verify before installation; fail with clear message if mismatch
  • Resume Support: Store partial downloads in repo temp folder with .partial extension; resume on retry; clean up on success
  • Path Resolution: Relative paths (./, ../) resolved from user's CWD
  • Directory Validation: Valid KB structure requires .pair/ directory or AGENTS.md marker file
  • Backup Naming: Format {target}.backup-{timestamp} where timestamp is YYYYMMDD-HHmmss
  • Temp Folder Location: Use {repo_root}/.tmp/pair-install/ for downloads and external directory copies
  • Direct Installation: If directory source is direct or indirect subfolder of target repo, skip temp copy and install directly

Edge Cases and Error Handling

  • Invalid URL Format: Fail fast with "Invalid URL format: {url}" before attempting connection
  • 404/403 Remote URL: Display "Remote KB not found (404)" or "Access denied (403): {url}" with suggestion to check URL
  • Network Timeout: After 30s connection timeout, display "Network timeout. Check connection and retry."
  • Corrupted ZIP: If extraction fails, display "ZIP file corrupted. Checksum: {status}. Re-download or verify source."
  • Invalid Directory Structure: Display "Invalid KB structure: missing .pair/ or AGENTS.md in {path}"
  • Disk Space Insufficient: Before download/copy, check available space; fail with "Insufficient disk space: need {size}MB, available {free}MB"
  • Backup Failure: If backup fails (permissions, space), abort installation with "Cannot backup existing KB: {reason}"
  • Partial Download Cleanup: On failure, clean up .partial files and temp folders
  • Resume Mismatch: If remote file changed (different size/checksum), restart fresh download with warning
  • Permission Denied: Display "Permission denied: {path}. Check file/directory permissions."
  • URL Redirect: Follow up to 5 redirects; fail with "Too many redirects" if exceeded

Technical Analysis

Implementation Approach

...existing technical analysis and requirements...

Task Breakdown

Task List

  • T-79.1: Implement source type detection (URL/ZIP/directory)
  • T-79.2: Implement HTTP client with progress and resume
  • T-79.3: Implement checksum validation for downloads
  • T-79.4: Implement local ZIP file installation
  • T-79.5: Implement local directory installation
  • [SKIPPED] T-79.6: Implement backup manager with timestamped backups
  • T-79.7: Implement temp folder lifecycle management
  • T-79.8: Implement comprehensive error handling
  • T-79.9: Write tests and update documentation

Total Story Points: 5 pts
Estimated Total Effort: ~30 hours (4-6 days)

T-79.1: Implement source type detection (URL/ZIP/directory)

Priority: P0 | Estimated Hours: 2h | Bounded Context: Distribution & CLI Tools

Summary: Detect source type from --url parameter: remote URL, local ZIP, or local directory

Type: Feature Implementation

Description: Implement source detector that analyzes the --url parameter string to determine source type. Check for URL protocols (http://, https://), .zip extension, or directory path. Support both absolute and relative paths with proper resolution from CWD.

Acceptance Criteria:

  • Primary deliverable: Source detector correctly identifies all three source types
  • Quality standard: URL validation (reject unsafe protocols), path resolution accuracy
  • Integration requirement: Provides source type to downstream handlers
  • Verification method: Unit tests cover all detection scenarios

Technical Requirements:

  • Functionality: Protocol detection, file extension check, directory existence validation
  • Performance: Instant detection (< 10ms)
  • Security: Reject file://, ftp:// protocols
  • Compatibility: Cross-platform path handling (Windows/macOS/Linux)

Implementation Approach:

  • Technical Design: Pattern matching on source string, Node.js path module for resolution, fs checks for local paths
  • Bounded Context & Modules: apps/pair-cli source detector module
  • Files to Modify/Create:
    • apps/pair-cli/src/source-detector.ts (new) - Detection logic
    • apps/pair-cli/src/commands/install.ts - Integrate detector
  • Technical Standards: Security Guidelines, Code Design

Dependencies:

  • Technical: Node.js path, fs modules
  • Tasks: None (foundation task)
  • Resources: None

Implementation Steps:

  1. Create source detector module with SourceType enum (REMOTE_URL, LOCAL_ZIP, LOCAL_DIRECTORY)
  2. Implement protocol detection (starts with http:// or https://)
  3. Implement ZIP detection (ends with .zip)
  4. Implement directory detection (exists and is directory)
  5. Add path resolution for relative paths using path.resolve(process.cwd(), source)
  6. Add URL validation (reject unsafe protocols)
  7. Add unit tests for all detection scenarios

Testing Strategy:

Unit Tests: All source type detection scenarios, path resolution, URL validation
Integration Tests: Detection integrated with install command
Manual Testing: Verify detection with real URLs, files, directories

Notes: Detection order: URL protocol → .zip extension → directory check. Relative paths resolved from CWD.

T-79.2: Implement HTTP client with progress and resume

Priority: P0 | Estimated Hours: 6h | Bounded Context: Distribution & CLI Tools

Summary: HTTP client for remote downloads with progress tracking, resume support, and redirect handling

Type: Feature Implementation

Description: Implement HTTP client using Node.js http/https modules for downloading KB ZIPs from remote URLs. Support progress tracking (percentage, MB, speed), resume with HTTP Range requests, redirect following (max 5), timeout handling (30s), and .partial file management.

Acceptance Criteria:

  • Primary deliverable: HTTP client downloads files with progress and resume
  • Quality standard: Progress updates ≤100ms, resume from exact byte position
  • Integration requirement: Works with progress reporter, checksum validator
  • Verification method: Download completes, resume works after interruption

Technical Requirements:

  • Functionality: Streaming download, progress events, Range requests, redirect following
  • Performance: Display MB/s, resume without re-downloading completed data
  • Security: HTTPS support, timeout protection (30s)
  • Compatibility: Works with standard HTTP servers

Implementation Approach:

  • Technical Design: Node.js https.get with streaming, progress tracking via data events, Range header for resume, redirect limit counter
  • Bounded Context & Modules: apps/pair-cli HTTP client and download manager
  • Files to Modify/Create:
    • apps/pair-cli/src/http-client.ts (new) - HTTP download logic
    • apps/pair-cli/src/download-manager.ts (new) - Resume and progress coordination
  • Technical Standards: Code Design, Testing Strategy

Dependencies:

  • Technical: Node.js http/https, fs
  • Tasks: T-79.1 (source detection)
  • Resources: None

Implementation Steps:

  1. Create HTTP client with https.get for remote requests
  2. Implement streaming to file with progress tracking (bytes downloaded)
  3. Add timeout handling (30s connection timeout)
  4. Implement redirect following (max 5, follow Location header)
  5. Add .partial file creation and resume logic with Range header
  6. Calculate and emit progress events (percentage, speed MB/s)
  7. Handle network errors with retry logic (exponential backoff)
  8. Clean up .partial files on success
  9. Add unit tests for download, resume, redirect, timeout scenarios

Testing Strategy:

Unit Tests: Download logic, Range requests, redirect handling, timeout
Integration Tests: Full download with progress, resume after interruption
Manual Testing: Real remote URL download, network interruption simulation

Notes: Resume: check .partial size, send Range: bytes=<size>- header, validate server 206 response

T-79.3: Implement checksum validation for downloads

Priority: P0 | Estimated Hours: 2h | Bounded Context: Distribution & CLI Tools

Summary: Download and validate .sha256 checksum files for integrity verification

Type: Feature Implementation

Description: Implement checksum validator that downloads .sha256 file from {url}.sha256, computes SHA-256 hash of downloaded ZIP, compares hashes. Handle missing checksum (warn but continue), mismatch (fail with error), malformed checksum file.

Acceptance Criteria:

  • Primary deliverable: Checksum validation functional for remote downloads
  • Quality standard: Validation < 2s for typical KB, clear error messages
  • Integration requirement: Validates before extraction, integrates with HTTP client
  • Verification method: Valid checksum passes, invalid fails, missing warns

Technical Requirements:

  • Functionality: Download .sha256, compute SHA-256, compare hashes
  • Performance: Checksum computation < 2s
  • Security: Prevents corrupted/malicious file installation
  • Compatibility: Node.js crypto module (built-in)

Implementation Approach:

  • Technical Design: Download checksum file, use crypto.createHash('sha256') to compute hash, compare strings (case-insensitive)
  • Bounded Context & Modules: apps/pair-cli checksum validator
  • Files to Modify/Create:
    • apps/pair-cli/src/checksum-validator.ts (new) - Validation logic
    • apps/pair-cli/src/http-client.ts - Integrate checksum download
  • Technical Standards: Security Guidelines, Code Design

Dependencies:

  • Technical: Node.js crypto module
  • Tasks: T-79.2 (HTTP client for downloading checksum)
  • Resources: None

Implementation Steps:

  1. Create checksum validator module
  2. Download .sha256 file from {url}.sha256
  3. Parse expected hash from checksum file (first line, trim whitespace)
  4. Compute SHA-256 hash of ZIP file using crypto
  5. Compare computed vs expected (case-insensitive)
  6. Handle missing checksum: warn but continue
  7. Handle mismatch: fail with clear error message
  8. Handle malformed checksum: warn and skip validation
  9. Add unit tests for validation success/failure/missing scenarios

Testing Strategy:

Unit Tests: Hash computation, comparison logic, missing/malformed handling
Integration Tests: Valid checksum passes, invalid fails
Manual Testing: Test with valid/invalid/missing checksums

Notes: Warning for missing: "⚠️ Checksum file not found, skipping verification (HTTPS provides transport security)"

T-79.4: Implement local ZIP file installation

Priority: P0 | Estimated Hours: 3h | Bounded Context: Distribution & CLI Tools

Summary: Install KB from local ZIP files (absolute and relative paths) with extraction and validation

Type: Feature Implementation

Description: Implement local ZIP installation that resolves path (absolute/relative from CWD), validates ZIP file exists and is readable, extracts to temp folder, validates KB structure, and installs to .pair/ with backup. Supports both absolute (/path/kb.zip) and relative (./kb.zip) paths.

Acceptance Criteria:

  • Primary deliverable: Local ZIP installation functional for both path types
  • Quality standard: Extraction < 30s for 50MB ZIP, structure validation
  • Integration requirement: Uses ZIP handler, backup manager, temp folder manager
  • Verification method: ZIP extracts correctly, KB validated, installed to .pair/

Technical Requirements:

  • Functionality: Path resolution, ZIP extraction, structure validation
  • Performance: Extraction < 30s for typical 50MB KB
  • Security: Sanitize extracted paths (no ../ traversal)
  • Compatibility: Cross-platform ZIP handling (adm-zip)

Implementation Approach:

  • Technical Design: Resolve path with path.resolve, use adm-zip for extraction, validate structure (.pair/ or AGENTS.md), install via existing function
  • Bounded Context & Modules: apps/pair-cli ZIP handler and installer
  • Files to Modify/Create:
    • apps/pair-cli/src/zip-handler.ts (new) - ZIP extraction logic
    • apps/pair-cli/src/structure-validator.ts (new) - KB structure validation
    • apps/pair-cli/src/commands/install.ts - Integrate local ZIP path
  • Technical Standards: Code Design, Security Guidelines

Dependencies:

  • Technical: adm-zip (existing dependency)
  • Tasks: T-79.1 (source detection), T-79.6 (backup manager), T-79.7 (temp folder)
  • Resources: None

Implementation Steps:

  1. Create ZIP handler module
  2. Resolve ZIP path (absolute or relative from CWD)
  3. Validate ZIP file exists and is readable
  4. Extract ZIP to temp folder using adm-zip
  5. Sanitize extracted paths (reject ../ traversal)
  6. Validate KB structure (require .pair/ or AGENTS.md)
  7. Backup existing KB if present
  8. Install extracted content to .pair/
  9. Clean up temp folder
  10. Add unit tests for path resolution, extraction, validation

Testing Strategy:

Unit Tests: Path resolution, extraction logic, structure validation
Integration Tests: Full local ZIP install workflow
Manual Testing: Test with absolute/relative paths, valid/invalid ZIPs

Notes: Extract to {repo_root}/.tmp/pair-install/extracted/ before validation and installation

T-79.5: Implement local directory installation

Priority: P0 | Estimated Hours: 4h | Bounded Context: Distribution & CLI Tools

Summary: Install KB from local directories with direct install (repo subfolder) or copy (external)

Type: Feature Implementation

Description: Implement directory installation that detects if directory is within target repo (direct install) or external (copy to temp). Validate directory structure (.pair/ or AGENTS.md), handle both absolute and relative paths, copy external directories to temp folder, install to .pair/ with backup.

Acceptance Criteria:

  • Primary deliverable: Directory installation functional for both subfolder and external locations
  • Quality standard: Direct install optimization for repo subfolders, copy < 10s
  • Integration requirement: Uses directory validator, backup manager, temp folder manager
  • Verification method: Subfolder installs directly, external copies then installs

Technical Requirements:

  • Functionality: Repo detection, directory copy, structure validation
  • Performance: Copy < 10s for typical KB structure
  • Security: Validate directory is within safe boundaries
  • Compatibility: Cross-platform directory operations

Implementation Approach:

  • Technical Design: Detect if directory is subfolder of target repo (path.relative check), validate structure, copy with fs-extra if external, install directly if subfolder
  • Bounded Context & Modules: apps/pair-cli directory handler and installer
  • Files to Modify/Create:
    • apps/pair-cli/src/directory-handler.ts (new) - Directory install logic
    • apps/pair-cli/src/structure-validator.ts - Validate directory structure
    • apps/pair-cli/src/commands/install.ts - Integrate directory install
  • Technical Standards: Code Design, Testing Strategy

Dependencies:

  • Technical: fs-extra for directory copy
  • Tasks: T-79.1 (source detection), T-79.6 (backup manager), T-79.7 (temp folder)
  • Resources: None

Implementation Steps:

  1. Create directory handler module
  2. Resolve directory path (absolute or relative from CWD)
  3. Validate directory exists and is directory
  4. Validate KB structure (.pair/ or AGENTS.md present)
  5. Detect if directory is subfolder of target repo (path.relative)
  6. If subfolder: install directly without copy
  7. If external: copy to temp folder using fs-extra.copy
  8. Backup existing KB if present
  9. Install to .pair/ (from original location or temp)
  10. Clean up temp folder if used
  11. Add unit tests for subfolder detection, copy, validation

Testing Strategy:

Unit Tests: Subfolder detection, directory copy, structure validation
Integration Tests: Direct install from subfolder, copy install from external
Manual Testing: Test with repo subdirectories and external directories

Notes: Subfolder detection: path.relative(repoRoot, dirPath) does not start with ..

T-79.6: Implement backup manager with timestamped backups

SKIPPED: Backup during install is not required because install expects the target directory to be empty. There is no risk of overwriting existing KB data. Backup logic is only needed for update, not install. (See requirements and CLI workflow for rationale.)

Priority: P0 | Estimated Hours: 2h | Bounded Context: Distribution & CLI Tools

Summary: Create timestamped backups of existing KB before installation

Type: Feature Implementation

Description: Implement backup manager that checks for existing .pair/ directory, creates backup with timestamp format {target}.backup-{YYYYMMDD-HHmmss}/, handles backup failures (permissions, disk space), aborts installation if backup fails. Provides rollback capability.

Acceptance Criteria:

  • Primary deliverable: Backup manager creates timestamped backups before install
  • Quality standard: Backup completes quickly (< 5s), error handling for failures
  • Integration requirement: Called before all installation operations
  • Verification method: Existing KB backed up with correct timestamp format

Technical Requirements:

  • Functionality: Timestamp generation, directory copy, error handling
  • Performance: Backup < 5s for typical KB
  • Security: Validate backup location permissions
  • Compatibility: Cross-platform timestamp format

Implementation Approach:

  • Technical Design: Check for .pair/ existence, generate timestamp (ISO format without separators), copy directory with fs-extra.copy, handle errors
  • Bounded Context & Modules: apps/pair-cli backup manager
  • Files to Modify/Create:
    • apps/pair-cli/src/backup-manager.ts (new) - Backup logic
    • apps/pair-cli/src/commands/install.ts - Integrate backup before install
  • Technical Standards: Code Design, Testing Strategy

Dependencies:

  • Technical: fs-extra for directory copy
  • Tasks: None (independent utility)
  • Resources: None

Implementation Steps:

  1. Create backup manager module
  2. Check if .pair/ directory exists
  3. Generate timestamp in format YYYYMMDD-HHmmss (e.g., 20251130-143022)
  4. Create backup target path: .pair.backup-{timestamp}/
  5. Copy .pair/ to backup location using fs-extra.copy
  6. Handle errors: permissions, disk space insufficient
  7. Abort installation and display error if backup fails
  8. Add unit tests for backup creation, timestamp format, error handling

Testing Strategy:

Unit Tests: Timestamp generation, backup creation, error handling
Integration Tests: Backup created before install, installation aborted on backup failure
Manual Testing: Verify backup directory structure and timestamp format

Notes: Abort message on failure: "Cannot backup existing KB: {reason}. Installation aborted."

T-79.7: Implement temp folder lifecycle management

Priority: P0 | Estimated Hours: 2h | Bounded Context: Distribution & CLI Tools

Summary: Manage temp folder {repo_root}/.tmp/pair-install/ lifecycle with cleanup

Type: Feature Implementation

Description: Implement temp folder manager that creates {repo_root}/.tmp/pair-install/ for downloads and external directory copies, manages folder lifecycle (create, use, cleanup), handles cleanup on success and failure, provides fallback to OS temp if repo temp unavailable.

Acceptance Criteria:

  • Primary deliverable: Temp folder created, used, and cleaned up properly
  • Quality standard: Cleanup on both success and failure, clear error messages
  • Integration requirement: Used by all operations requiring staging
  • Verification method: Temp folder created, cleaned up after operations

Technical Requirements:

  • Functionality: Folder creation, cleanup, fallback to OS temp
  • Performance: Cleanup < 2s for typical temp content
  • Security: Validate temp folder permissions
  • Compatibility: Cross-platform temp folder handling

Implementation Approach:

  • Technical Design: Create temp folder at repo root, use for downloads/copies, clean up with fs-extra.remove, fallback to os.tmpdir() if repo temp unavailable
  • Bounded Context & Modules: apps/pair-cli temp folder manager
  • Files to Modify/Create:
    • apps/pair-cli/src/temp-manager.ts (new) - Temp lifecycle management
    • apps/pair-cli/src/commands/install.ts - Integrate temp management
  • Technical Standards: Code Design, Testing Strategy

Dependencies:

  • Technical: fs-extra, os module
  • Tasks: None (foundation utility)
  • Resources: None

Implementation Steps:

  1. Create temp manager module
  2. Implement createTempFolder: create {repo_root}/.tmp/pair-install/
  3. Handle permission errors: fallback to os.tmpdir() + /pair-install/
  4. Implement getTempPath: return temp folder path
  5. Implement cleanup: remove temp folder contents with fs-extra.remove
  6. Handle cleanup errors: log warning but don't fail operation
  7. Add automatic cleanup on process exit (cleanup handler)
  8. Add unit tests for creation, fallback, cleanup

Testing Strategy:

Unit Tests: Temp creation, fallback logic, cleanup
Integration Tests: Temp used in download/copy operations, cleaned up after
Manual Testing: Verify temp folder location, cleanup after success/failure

Notes: Fallback path: os.tmpdir()/pair-install/ if repo .tmp/ unavailable

T-79.8: Implement comprehensive error handling

Priority: P0 | Estimated Hours: 3h | Bounded Context: Distribution & CLI Tools

Summary: Specific error messages for all failure scenarios with actionable guidance

Type: Feature Implementation

Description: Implement comprehensive error handling for all failure scenarios: invalid URL, 404/403, timeout, corrupted ZIP, invalid structure, disk space, permissions, resume mismatch. Each error includes specific problem description and suggested action. Display errors with clear formatting using chalk.

Acceptance Criteria:

  • Primary deliverable: Specific error message for each failure type
  • Quality standard: Actionable guidance, no generic errors
  • Integration requirement: Integrated across all modules (HTTP, ZIP, directory)
  • Verification method: Each error scenario displays correct message

Technical Requirements:

  • Functionality: Error type detection, message mapping, suggestion generation
  • Performance: No performance impact (error path only)
  • Security: No sensitive data in error messages
  • Compatibility: Works across all platforms

Implementation Approach:

  • Technical Design: Create error type enum, map errors to messages with suggestions, use chalk for formatting, include context (URL, path, size)
  • Bounded Context & Modules: apps/pair-cli error handler
  • Files to Modify/Create:
    • apps/pair-cli/src/error-handler.ts (new) - Error mapping and formatting
    • All handler modules - Integrate error handler
  • Technical Standards: Code Design, UX Guidelines

Dependencies:

  • Technical: chalk for formatting
  • Tasks: All previous tasks (error scenarios)
  • Resources: None

Implementation Steps:

  1. Create error handler module with error type enum
  2. Define error messages for each scenario:
    • Invalid URL format
    • 404/403 remote URL
    • Network timeout (30s)
    • Corrupted ZIP (extraction failed)
    • Invalid directory structure
    • Disk space insufficient
    • Permission denied
    • Backup failure
    • Resume mismatch
    • Too many redirects
  3. Implement error formatting with chalk (red for errors, yellow for warnings)
  4. Add context to messages (URL, path, size, checksum status)
  5. Integrate error handler in all modules
  6. Add unit tests for error detection and message generation

Testing Strategy:

Unit Tests: Error type detection, message formatting
Integration Tests: Trigger each error scenario, verify message
Manual Testing: Verify error clarity and actionability

Notes: Example errors:

  • 404: "Remote KB not found (404): {url}. Verify URL or check GitHub releases."
  • Invalid structure: "Invalid KB structure: missing .pair/ or AGENTS.md in {path}"

T-79.9: Write tests and update documentation

Priority: P0 | Estimated Hours: 6h | Bounded Context: Distribution & CLI Tools

Summary: Comprehensive tests (unit/integration) and documentation for all source types

Type: Testing & Documentation

Description: Write unit tests for all modules (source detection, HTTP client, checksum, ZIP, directory, backup, temp, errors). Add integration tests for complete workflows (remote URL, local ZIP, local directory). Update CLI help, README with examples, troubleshooting guide. Achieve ≥80% test coverage.

Acceptance Criteria:

  • Primary deliverable: ≥80% test coverage, docs complete and clear
  • Quality standard: All tests passing, docs reviewed and accurate
  • Integration requirement: Tests cover all acceptance criteria
  • Verification method: Coverage report ≥80%, docs validated

Technical Requirements:

  • Functionality: Unit/integration test suites, CLI help, README examples
  • Performance: Tests complete < 60s total
  • Security: No credentials in test fixtures
  • Compatibility: Tests run on CI and local environments

Implementation Approach:

  • Technical Design: vitest test suites, mock HTTP servers, test fixtures (ZIPs, directories), update CLI help and README
  • Bounded Context & Modules: apps/pair-cli tests and documentation
  • Files to Modify/Create:
    • apps/pair-cli/src/source-detector.test.ts (new) - Source detection tests
    • apps/pair-cli/src/http-client.test.ts (new) - HTTP client tests
    • apps/pair-cli/src/checksum-validator.test.ts (new) - Checksum tests
    • apps/pair-cli/src/zip-handler.test.ts (new) - ZIP handler tests
    • apps/pair-cli/src/directory-handler.test.ts (new) - Directory tests
    • apps/pair-cli/src/backup-manager.test.ts (new) - Backup tests
    • apps/pair-cli/src/temp-manager.test.ts (new) - Temp manager tests
    • apps/pair-cli/src/commands/install.integration.test.ts - Integration tests
    • apps/pair-cli/README.md - Update with --url examples
    • apps/pair-cli/src/cli.ts - Update help text
  • Technical Standards: Testing Strategy, Documentation Guidelines

Dependencies:

  • Technical: vitest, test fixtures (sample ZIPs, directories)
  • Tasks: All previous tasks (tests for their implementations)
  • Resources: None

Implementation Steps:

  1. Create test fixtures: sample KB ZIP, directory structure, checksums
  2. Write unit tests for source detection (all types, path resolution)
  3. Write unit tests for HTTP client (download, resume, redirect, timeout)
  4. Write unit tests for checksum validation (valid, invalid, missing)
  5. Write unit tests for ZIP handler (extraction, validation)
  6. Write unit tests for directory handler (subfolder, external, validation)
  7. Write unit tests for backup manager (creation, timestamp, errors)
  8. Write unit tests for temp manager (creation, fallback, cleanup)
  9. Write unit tests for error handler (all error types)
  10. Write integration tests:
    • Remote URL download and install
    • Local ZIP install (absolute/relative)
    • Local directory install (subfolder/external)
    • Resume interrupted download
    • Checksum validation failure
  11. Update CLI --help with --url option and examples
  12. Update README.md with installation workflows for all source types
  13. Add troubleshooting section for common errors
  14. Run coverage report, ensure ≥80%

Testing Strategy:

Unit Tests: All module functionality individually tested
Integration Tests: Complete workflows for each source type
Manual Testing: Real KB packages (GitHub releases, local files/dirs)

Notes: Coverage target: ≥80% overall, ≥90% for critical modules (HTTP client, checksum validator)

Task Breakdown Completed By: Product Engineer (AI-assisted)
Task Breakdown Date: 2025-11-30
Total Tasks: 9
Story Coverage: 100% of acceptance criteria mapped

Metadata

Metadata

Assignees

Labels

user storyWork item representing a user story

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions