Add CLI application: 6 commands, 3 output formats, 260 tests

[dluc]

This PR introduces a complete command-line interface for Kernel Memory, enabling users to manage content via terminal commands.

Overview

Complete CLI implementation with 6 core commands, multiple output formats, comprehensive test coverage, and a friendly first-run experience.

Stats:

• 106 files changed (+6,473/-202 lines)
• 183 CLI tests + 77 Core tests (260 total)
• Zero warnings, zero errors
• Clean dependency injection architecture

Features

Commands

• km upsert - Create or update content with optional metadata
• km get <id> - Retrieve content by ID
• km delete <id> - Delete content by ID
• km list - List all content with pagination
• km nodes - List configured nodes
• km config - Query configuration settings

Output Formats

• Human - Friendly, colored terminal output (default)
• JSON - Machine-readable JSON
• YAML - Machine-readable YAML

Global Options

• --config <path> - Custom config file path
• --node <name> - Target specific node
• --format <human|json|yaml> - Output format
• --verbosity <normal|quiet|silent> - Control output detail

Examples

# First-run experience
$ km list
Welcome to Kernel Memory! 🚀

No content found yet. This is your first run.

To get started:
  km upsert "Your content here"

# Add content
$ km upsert "Hello, world!" --id greeting
{
  "id": "greeting",
  "status": "success"
}

# Retrieve content
$ km get greeting --format yaml
id: greeting
content: Hello, world!
createdAt: 2025-11-28T10:00:00Z

# List with pagination
$ km list --skip 10 --take 20 --format json
{
  "items": [...],
  "pagination": {
    "totalCount": 45,
    "skip": 10,
    "take": 20,
    "returned": 20
  }
}

# Delete content
$ km delete greeting
{
  "id": "greeting",
  "status": "deleted"
}

Architecture

Config Injection

Configuration is loaded once at startup and injected via dependency injection:

• No hardcoded file paths in commands
• Tests inject mock configs (never touch ~/.km/)
• Clean separation: config loading in Main, business logic in commands

Command Structure

Main → CliApplicationBuilder.Build(args) → Load Config → DI Container →
Commands receive AppConfig via constructor → Business logic executes

Exit Codes

• 0 - Success (includes "no data yet" state)
• 1 - User error (invalid arguments, ID not found)
• 2 - System error (DB corruption, permission denied)

First-Run UX

When the database doesn't exist yet (expected on first run):

• Shows welcoming message with examples (human format)
• Returns valid empty JSON/YAML (machine-readable formats)
• Exit code 0 (not an error)
• Clear distinction between "no data yet" vs actual errors

Components Added

CLI Layer (src/Main/CLI/)

• Commands/ - 6 command implementations (Upsert, Get, Delete, List, Nodes, Config)
• OutputFormatters/ - Human, JSON, YAML formatters
• Infrastructure/ - DI integration (TypeRegistrar, TypeResolver)
• Exceptions/ - DatabaseNotFoundException for first-run state
• Models/ - DTOs for structured output

Services Layer (src/Main/Services/)

• ContentService - Business logic wrapping ContentStorage

Test Suite (tests/Main.Tests/)

• Integration/ - 4 test suites (CLI integration, command execution, readonly commands, user data protection)
• Unit/ - 12 test suites covering commands, formatters, settings, services
• Helpers/ - TestCliApplicationBuilder for test config injection

Infrastructure

• build.sh - Zero-warning build validation
• coverage.sh - Test coverage reporting
• km.sh - CLI wrapper script
• TypeScript-style .editorconfig - Code style enforcement

Quality Metrics

Test Coverage

• ✅ 183 Main.Tests passing
• ✅ 77 Core.Tests passing
• ✅ 260 total tests, zero skipped
• ✅ Coverage meets 80% minimum requirement

Build Quality

• ✅ Zero warnings
• ✅ Zero errors
• ✅ All analyzers enabled (Roslynator, .NET analyzers)
• ✅ Formatted with dotnet format

Design Principles

• ✅ SOLID principles
• ✅ Single Responsibility Principle
• ✅ Dependency injection
• ✅ Clean separation of concerns
• ✅ Comprehensive error handling

Testing Strategy

Integration Tests

• End-to-end command execution
• Multi-command workflows
• Config injection verification
• First-run experience validation

Unit Tests

• Command initialization and validation
• Output formatter behavior
• Settings validation
• Service layer logic
• Error handling

Critical Tests

• UserDataProtectionTests - Ensures tests never touch ~/.km/
• ReadonlyCommandTests - Verifies readonly commands don't create files
• CliIntegrationTests - Validates complete workflows

Breaking Changes

None - this is a new CLI, doesn't affect existing APIs or libraries.

Migration Guide

Not applicable - this is a new feature addition.