@aladac/hu 0.1.0-a1

package/plans/serialized-roaming-kernighan.md

@@ -0,0 +1,227 @@
+# Plan: honbu data Subcommand for Claude Code Data Integration
+
+Implements the `honbu data` command hierarchy to access Claude Code's local data stores, enabling hooks to query session transcripts, history, stats, todos, and file history.
+
+## Phase 1: Core Data Access Commands
+
+### Description
+Implement read-only access to the primary data stores: sessions, history, and stats. These form the foundation for all subsequent queries.
+
+### Steps
+
+#### Step 1.1: Create data command module structure
+- **Objective**: Set up the data subcommand with initial scaffolding
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: None
+- **Implementation**:
+  - Create `dataCommand` with subCommands structure
+  - Add placeholder subcommands: session, stats, history
+  - Register in `src/index.ts`
+
+#### Step 1.2: Add data store path utilities
+- **Objective**: Centralize paths to Claude Code data stores
+- **Files**: `src/lib/fs.ts`
+- **Dependencies**: Step 1.1
+- **Implementation**:
+  - Add constants: `PROJECTS_DIR`, `HISTORY_FILE`, `STATS_FILE`, `TODOS_DIR`, `FILE_HISTORY_DIR`, `DEBUG_DIR`
+  - Add `encodeProjectPath(path)` function (mirrors Claude's encoding)
+  - Add `decodeProjectPath(encoded)` function
+
+#### Step 1.3: Implement session list command
+- **Objective**: List sessions with optional project filter
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 1.2
+- **Implementation**:
+  - `honbu data session list [--project <path>] [--limit n] [--json]`
+  - Read projects/ directory structure
+  - Parse JSONL files to extract session metadata
+  - Display: sessionId, timestamp, messageCount, project
+
+#### Step 1.4: Implement session read command
+- **Objective**: Read and format a session transcript
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 1.3
+- **Implementation**:
+  - `honbu data session read <id> [--format json|md]`
+  - Parse JSONL file, reconstruct message thread via parentUuid
+  - JSON: output raw messages
+  - Markdown: format as conversation with tool calls summarized
+
+#### Step 1.5: Implement stats command
+- **Objective**: Display usage statistics
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 1.2
+- **Implementation**:
+  - `honbu data stats [--period <days>] [--json]`
+  - Read and parse stats-cache.json
+  - Display: totalSessions, totalMessages, modelUsage, dailyActivity
+  - Filter by period if specified
+
+#### Step 1.6: Implement history command
+- **Objective**: List and search session history
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 1.2
+- **Implementation**:
+  - `honbu data history [--project <path>] [--limit n] [--json]`
+  - Read history.jsonl
+  - Filter by project if specified
+  - Display: timestamp, display (prompt preview), project
+
+## Phase 2: Extended Data Access
+
+### Description
+Add commands for todos, file history, and the current session context.
+
+### Steps
+
+#### Step 2.1: Implement todos list command
+- **Objective**: List todos across sessions
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Phase 1
+- **Implementation**:
+  - `honbu data todos [--status <status>] [--session <id>] [--json]`
+  - Read todos/*.json files
+  - Filter by status (pending/in_progress/completed)
+  - Display: content, status, session association
+
+#### Step 2.2: Implement todos pending command
+- **Objective**: Show incomplete todos across all sessions
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 2.1
+- **Implementation**:
+  - `honbu data todos pending [--project <path>] [--json]`
+  - Filter for status != "completed"
+  - Group by session or project
+
+#### Step 2.3: Implement file-history list command
+- **Objective**: List files modified in sessions
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Phase 1
+- **Implementation**:
+  - `honbu data files [--session <id>] [--recent <days>] [--json]`
+  - Read file-history/{session}/ directories
+  - Extract file paths from hash-based names (requires reverse lookup)
+  - Display: file path, version count, last modified
+
+#### Step 2.4: Implement session current command
+- **Objective**: Get current session from environment
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Step 1.4
+- **Implementation**:
+  - `honbu data session current`
+  - Read $SESSION_ID environment variable
+  - Output session info or error if not in session context
+
+## Phase 3: Search and Query
+
+### Description
+Add full-text search across sessions and pattern analysis.
+
+### Steps
+
+#### Step 3.1: Implement session search command
+- **Objective**: Search message content across sessions
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Phase 1
+- **Implementation**:
+  - `honbu data search <query> [--limit n] [--json]`
+  - Scan JSONL files for matching content
+  - Return: sessionId, messageId, matched text snippet, timestamp
+
+#### Step 3.2: Implement tools usage command
+- **Objective**: Analyze tool usage patterns
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Phase 1
+- **Implementation**:
+  - `honbu data tools [--tool <name>] [--session <id>] [--json]`
+  - Parse assistant messages for tool_use content blocks
+  - Aggregate: tool name, call count, common inputs
+
+#### Step 3.3: Implement errors command
+- **Objective**: Extract errors from debug logs
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Phase 1
+- **Implementation**:
+  - `honbu data errors [--session <id>] [--recent <days>] [--json]`
+  - Parse debug/*.txt files for error patterns
+  - Display: timestamp, error message, session context
+
+## Phase 4: JSONL Parsing Library
+
+### Description
+Create reusable parsing utilities for JSONL data stores.
+
+### Steps
+
+#### Step 4.1: Create JSONL parser module
+- **Objective**: Efficient JSONL reading with streaming support
+- **Files**: `src/lib/jsonl.ts`
+- **Dependencies**: None
+- **Implementation**:
+  - `parseJsonlFile(path)` - returns array of parsed objects
+  - `streamJsonlFile(path, callback)` - streaming parser for large files
+  - `appendJsonl(path, object)` - append single record
+
+#### Step 4.2: Create session transcript parser
+- **Objective**: Parse and thread session messages
+- **Files**: `src/lib/transcript.ts`
+- **Dependencies**: Step 4.1
+- **Implementation**:
+  - `parseTranscript(path)` - parse JSONL to message array
+  - `threadMessages(messages)` - reconstruct conversation tree
+  - `extractToolCalls(message)` - extract tool usage from content
+  - `summarizeSession(messages)` - generate session summary
+
+#### Step 4.3: Refactor data commands to use parsers
+- **Objective**: Use new parsing utilities in data commands
+- **Files**: `src/commands/data.ts`
+- **Dependencies**: Steps 4.1, 4.2
+- **Implementation**:
+  - Replace inline parsing with library calls
+  - Add error handling for malformed JSONL
+  - Optimize for large session files
+
+## Verification
+
+### Unit Tests
+- Test JSONL parsing with sample data
+- Test project path encoding/decoding
+- Test message threading logic
+
+### Integration Tests
+```bash
+# Phase 1 verification
+honbu data session list
+honbu data session list --project ~/.claude --json
+honbu data session read <session-id>
+honbu data stats
+honbu data stats --period 7
+honbu data history --limit 10
+
+# Phase 2 verification
+honbu data todos
+honbu data todos pending
+honbu data files --recent 1
+
+# Phase 3 verification
+honbu data search "error"
+honbu data tools --tool Bash
+honbu data errors --recent 7
+```
+
+### Hook Integration Test
+```bash
+# Test from a hook context
+export SESSION_ID="test-session-id"
+honbu data session current
+```
+
+## Files Summary
+
+| File | Action |
+|------|--------|
+| `src/commands/data.ts` | Create |
+| `src/lib/fs.ts` | Modify (add paths) |
+| `src/lib/jsonl.ts` | Create |
+| `src/lib/transcript.ts` | Create |
+| `src/index.ts` | Modify (register command) |

package/plans/structured-wondering-wirth.md

@@ -0,0 +1,230 @@
+# Internal AI Utility Interface Design
+
+## Goal
+Design an internal AI utility system leveraging existing Ollama/LM Studio connections for text processing tasks like:
+- Extracting model settings from CivitAI HTML descriptions
+- JSON correction/formatting
+- Text organization utilities
+
+## Current Infrastructure
+
+### Existing Connections (from `src/prompts/extract/client.py`)
+| Host | Backend | Endpoint | Purpose |
+|------|---------|----------|---------|
+| junkpile | Ollama | `192.168.0.26:11434` | Vision models (GGUF) |
+| fuji | LM Studio | `localhost:1234` | Local dev (MLX) |
+
+### Available Text Models
+- `hermes3` - Structured output (Ollama)
+- `huihui_ai/dolphin3-abliterated` - Text synthesis (Ollama)
+- `dolphin-2.9-llama3-8b-mlx` - Text (LM Studio)
+
+### Existing Pattern
+- `VisionClient` class wraps OpenAI SDK
+- Auto-detects backend from port
+- Environment variables: `OPENAPI_HOST`, `OPENAPI_BACKEND`
+
+## Design
+
+### Architecture Overview
+
+Reuse `VisionClient` from `src/prompts/extract/client.py` since it already supports text-only generation via `_generate_text()`. Create a thin wrapper with task-specific processors.
+
+```
+src/prompts/ai/
+├── __init__.py       # Exports AIClient, processors
+├── client.py         # AIClient wrapping VisionClient for text tasks
+├── processors.py     # SettingsExtractor, JSONFixer, TextTransformer
+└── cli.py            # CLI commands: prompts ai extract-settings, fix-json
+```
+
+### Default Model Selection
+
+| Host | Default Model | Reason |
+|------|---------------|--------|
+| junkpile (Ollama) | `hermes3` | Structured output, good at extraction |
+| fuji (LM Studio) | `dolphin-2.9-llama3-8b-mlx` | MLX optimized |
+
+### AIClient Class
+
+```python
+# src/prompts/ai/client.py
+from prompts.extract.client import VisionClient
+
+DEFAULT_MODEL = "hermes3"  # Best for structured extraction
+
+class AIClient:
+    """AI utility client for text processing tasks."""
+
+    def __init__(self, host=None, model=None):
+        self._vision = VisionClient(host=host)
+        self.model = model or DEFAULT_MODEL
+
+    def generate(self, prompt: str, system: str = None) -> str:
+        """Generate text response."""
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+        return self._vision._generate_text(self.model, full_prompt)
+
+    def extract_settings(self, html: str) -> ModelSettings:
+        """Extract SD settings from HTML description."""
+        return SettingsExtractor(self).extract(html)
+
+    def fix_json(self, broken_json: str) -> str:
+        """Fix malformed JSON."""
+        return JSONFixer(self).fix(broken_json)
+```
+
+### Processors
+
+```python
+# src/prompts/ai/processors.py
+from pydantic import BaseModel
+from typing import Optional
+
+class ModelSettings(BaseModel):
+    """Extracted SD model settings."""
+    sampler: Optional[str] = None
+    scheduler: Optional[str] = None
+    steps: Optional[str] = None        # Can be range like "20-35"
+    cfg_scale: Optional[str] = None    # Can be range like "1-2"
+    clip_skip: Optional[int] = None
+    vae: Optional[str] = None
+    notes: Optional[str] = None
+
+SETTINGS_SYSTEM_PROMPT = """Extract Stable Diffusion generation settings from the HTML description.
+Return ONLY valid JSON matching this schema:
+{
+  "sampler": "sampler name or null",
+  "scheduler": "scheduler name or null",
+  "steps": "step count or range like '20-35' or null",
+  "cfg_scale": "CFG value or range like '1-2' or null",
+  "clip_skip": clip skip number or null,
+  "vae": "VAE name or null",
+  "notes": "any other relevant settings notes or null"
+}
+Do not include any other text, only the JSON object."""
+
+class SettingsExtractor:
+    def __init__(self, client):
+        self.client = client
+
+    def extract(self, html: str) -> ModelSettings:
+        response = self.client.generate(
+            prompt=f"Extract settings from:\n\n{html}",
+            system=SETTINGS_SYSTEM_PROMPT
+        )
+        # Parse JSON response into ModelSettings
+        import json
+        data = json.loads(response)
+        return ModelSettings(**data)
+
+JSON_FIX_PROMPT = """Fix the following malformed JSON and return ONLY the corrected JSON.
+Do not explain, just output valid JSON."""
+
+class JSONFixer:
+    def __init__(self, client):
+        self.client = client
+
+    def fix(self, broken: str) -> str:
+        return self.client.generate(
+            prompt=f"Fix this JSON:\n\n{broken}",
+            system=JSON_FIX_PROMPT
+        )
+```
+
+### CLI Commands
+
+```python
+# src/prompts/ai/cli.py
+import click
+from .client import AIClient
+
+@click.group()
+def ai():
+    """AI-powered text utilities."""
+    pass
+
+@ai.command("extract-settings")
+@click.argument("model_id", type=int)
+@click.option("--host", help="AI backend host")
+def extract_settings(model_id: int, host: str):
+    """Extract SD settings from CivitAI model description."""
+    from prompts.civitai.cache import get_cached_model
+
+    cached = get_cached_model(model_id)
+    if not cached:
+        click.echo(f"Model {model_id} not in cache. Run: prompts models info {model_id}")
+        return
+
+    html = cached.get("description", "")
+    client = AIClient(host=host)
+    settings = client.extract_settings(html)
+
+    click.echo(settings.model_dump_json(indent=2))
+
+@ai.command("fix-json")
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--output", "-o", help="Output file (default: stdout)")
+def fix_json(file: str, output: str):
+    """Fix malformed JSON file."""
+    from pathlib import Path
+
+    broken = Path(file).read_text()
+    client = AIClient()
+    fixed = client.fix_json(broken)
+
+    if output:
+        Path(output).write_text(fixed)
+        click.echo(f"Fixed JSON written to {output}")
+    else:
+        click.echo(fixed)
+```
+
+### Integration with Scene Generation
+
+Update `prompts scenes json` to auto-extract settings:
+
+```python
+# In scenes/cli.py
+@scenes.command("json")
+@click.option("--auto-settings", is_flag=True, help="Extract settings from CivitAI")
+def generate_json(..., auto_settings: bool):
+    if auto_settings and model_id:
+        from prompts.ai.client import AIClient
+        client = AIClient()
+        # Get cached model description
+        settings = client.extract_settings(html)
+        # Apply to scene
+```
+
+## Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `src/prompts/ai/__init__.py` | Create |
+| `src/prompts/ai/client.py` | Create |
+| `src/prompts/ai/processors.py` | Create |
+| `src/prompts/ai/cli.py` | Create |
+| `src/prompts/cli.py` | Add `ai` group import |
+
+## Verification
+
+1. **Test extraction**:
+   ```bash
+   # First cache a model
+   uv run prompts models info 1836956
+
+   # Then extract settings
+   uv run prompts ai extract-settings 1836956
+   ```
+
+2. **Test JSON fixing**:
+   ```bash
+   echo '{"broken: json}' > /tmp/broken.json
+   uv run prompts ai fix-json /tmp/broken.json
+   ```
+
+3. **Verify hermes3 is available**:
+   ```bash
+   curl http://192.168.0.26:11434/api/tags | jq '.models[].name'
+   ```

package/plans/vectorized-dreaming-iverson.md

@@ -0,0 +1,191 @@
+# Refactor: Internal Model ID as Primary Key
+
+## Overview
+
+Make the 8-character internal ID the primary key for all model operations. All commands that operate on a single model will use `-m/--model-id` accepting our internal ID format.
+
+## Key Design Decisions
+
+1. **Internal ID is primary** - All lookups start with internal 8-char ID
+2. **CivitAI IDs retained** - Stored as `civitai_id` field, used for API calls
+3. **Unified lookup function** - New `resolve_model()` function handles ID resolution
+4. **Consistent CLI pattern** - All single-model commands use `-m MODEL_ID` or `--model-id MODEL_ID`
+
+## Files to Modify
+
+### 1. `src/prompts/models/cache.py` - Add Unified Lookup
+
+Add a `resolve()` method to `ModelCache` that accepts flexible input:
+
+```python
+def resolve(self, identifier: str) -> Optional[CachedModel]:
+    """Resolve a model by internal ID (primary), name, or CivitAI ID.
+    
+    Lookup order:
+    1. Exact internal ID match (8-char)
+    2. CivitAI ID (if numeric)
+    3. Name partial match (fallback)
+    """
+```
+
+### 2. `src/prompts/models/cli.py` - Standardize Commands
+
+| Command | Current | New |
+|---------|---------|-----|
+| `models info` | `@click.argument("name_or_id")` | `@click.option("-m", "--model-id")` |
+| `models set` | `@click.argument("model_id")` | `@click.option("-m", "--model-id", required=True)` |
+| `models show` | `@click.argument("model_id")` | `@click.option("-m", "--model-id", required=True)` |
+| `models cache clear` | `@click.argument("model_id", type=int)` | `@click.option("-m", "--model-id")` |
+
+### 3. `src/prompts/civitai/cli.py` - Update CivitAI Commands
+
+| Command | Current | New |
+|---------|---------|-----|
+| `civitai prompts` | `@click.argument("model_id", type=int)` | `@click.option("-m", "--model-id", required=True)` |
+| `civitai images` | `@click.argument("model_id", type=int)` | `@click.option("-m", "--model-id", required=True)` |
+
+These commands need to:
+1. Accept internal ID
+2. Resolve to CachedModel
+3. Use `civitai_id` for API calls
+
+### 4. `src/prompts/ai/cli.py` - Update AI Commands
+
+| Command | Current | New |
+|---------|---------|-----|
+| `ai extract-settings` | `@click.argument("model_id", type=int)` | `@click.option("-m", "--model-id", required=True)` |
+
+### 5. `src/prompts/scenes/cli.py` - Update Scene Commands
+
+| Command | Current | New |
+|---------|---------|-----|
+| `scenes json` | `--model-id/-m type=int` | `--model-id/-m` (string, internal ID) |
+| `scenes list` | `--model/-m` | `--model-id/-m` (for consistency) |
+
+## Implementation Steps
+
+### Step 1: Add `resolve()` to ModelCache
+
+Location: `src/prompts/models/cache.py`
+
+```python
+def resolve(self, identifier: str) -> Optional[CachedModel]:
+    """Resolve model by internal ID, CivitAI ID, or name."""
+    # 1. Try exact internal ID (case-insensitive)
+    model = self.get(identifier.upper())
+    if model:
+        return model
+    
+    # 2. Try CivitAI ID if numeric
+    try:
+        civitai_id = int(identifier)
+        model = self.get_by_civitai_id(civitai_id)
+        if model:
+            return model
+    except ValueError:
+        pass
+    
+    # 3. Try name partial match
+    identifier_lower = identifier.lower()
+    for model in self._models.values():
+        if identifier_lower in model.name.lower():
+            return model
+    
+    return None
+```
+
+### Step 2: Update `models` CLI Commands
+
+File: `src/prompts/models/cli.py`
+
+**`models info`** (line 582):
+- Change from `@click.argument("name_or_id")` to `@click.option("-m", "--model-id", required=True)`
+- Use `cache.resolve(model_id)` for lookup
+- If model has `civitai_id`, fetch from CivitAI API
+
+**`models set`** (line 1021):
+- Change from `@click.argument("model_id")` to `@click.option("-m", "--model-id", required=True)`
+- Use `cache.resolve(model_id)`
+
+**`models show`** (line 1091):
+- Change from `@click.argument("model_id")` to `@click.option("-m", "--model-id", required=True)`
+- Use `cache.resolve(model_id)`
+
+**`models cache clear`** (line 964):
+- Change from `@click.argument("model_id", type=int)` to `@click.option("-m", "--model-id")`
+- Resolve internal ID to get `civitai_id` for cache clear
+
+### Step 3: Update `civitai` CLI Commands
+
+File: `src/prompts/civitai/cli.py`
+
+**`civitai prompts`** (line 270):
+```python
+@civitai.command("prompts")
+@click.option("-m", "--model-id", required=True, help="Model ID (internal or CivitAI)")
+def get_prompts(model_id: str, ...):
+    cache = get_cache()
+    model = cache.resolve(model_id)
+    if not model or not model.civitai_id:
+        console.print(f"[red]Model not found or has no CivitAI ID[/red]")
+        return
+    # Use model.civitai_id for API call
+```
+
+**`civitai images`** (line 304):
+- Same pattern as above
+
+### Step 4: Update `ai` CLI Commands
+
+File: `src/prompts/ai/cli.py`
+
+**`ai extract-settings`** (line 20):
+- Change from `@click.argument("model_id", type=int)` to `@click.option("-m", "--model-id", required=True)`
+- Resolve internal ID, use `civitai_id` for cache lookup
+
+### Step 5: Update `scenes` CLI Commands
+
+File: `src/prompts/scenes/cli.py`
+
+**`scenes json`** (line 413):
+- Change `type=int` to string
+- Resolve internal ID to get model file path
+
+**`scenes list`** (line 227):
+- Rename `--model` to `--model-id` for consistency
+- Keep existing filter logic (base model matching)
+
+## Verification
+
+```bash
+# Test internal ID lookup
+uv run prompts models show -m C1GVKMA9
+
+# Test CivitAI ID fallback
+uv run prompts models show -m 827184
+
+# Test name fallback  
+uv run prompts models show -m "WAI"
+
+# Test civitai commands with internal ID
+uv run prompts civitai prompts -m C1GVKMA9
+
+# Test scenes with internal ID
+uv run prompts scenes json wc-r01 -m C1GVKMA9
+
+# Test set command
+uv run prompts models set -m C1GVKMA9 --favorite
+```
+
+## Error Messages
+
+When model not found:
+```
+Model 'XYZ' not found.
+Use 'prompts models list' to see available models and their IDs.
+```
+
+When CivitAI ID required but not available:
+```
+Model 'XYZ' has no CivitAI ID. This command requires a model from CivitAI.
+```