aline-ai 0.5.3__py3-none-any.whl → 0.5.5__py3-none-any.whl

realign/commands/add.py

@@ -251,10 +251,233 @@ Use this skill when the user wants to:
 - Send Slack updates about completed work
 """
 
+# Aline Import History Sessions skill definition for Claude Code
+# Installed to ~/.claude/skills/aline-import-history-sessions/SKILL.md
+ALINE_IMPORT_HISTORY_SESSIONS_SKILL_MD = """---
+name: aline-import-history-sessions
+description: Guide users through importing Claude Code session history into Aline database. Use this for first-time setup, onboarding new users, or when users want to selectively import historical sessions. Provides interactive workflow with progress checking.
+---
+
+# Aline Import History Sessions Skill
+
+This skill guides users through the process of importing Claude Code session history into Aline's database. It provides an interactive, step-by-step workflow to help users discover, select, and import their historical sessions.
+
+## Workflow Overview
+
+```
+Analyze Unimported Sessions → Present Summary → User Selection → Import Sessions → Verify Success → Continue or Finish
+```
+
+## Step-by-Step Guide
+
+### Step 1: Analyze Current Status
+
+First, list all sessions to understand what hasn't been imported yet:
+
+```bash
+aline watcher session list --detect-turns
+```
+
+**Internal analysis (do NOT expose status terminology to user):**
+- Count sessions with status `new` → these are "unimported sessions"
+- Count sessions with status `partial` → these have "updates available"
+- Count sessions with status `tracked` → these are "already imported"
+
+Parse the output to extract:
+- Total number of unimported sessions
+- Their session IDs (use these for import, NOT index numbers)
+- Project paths they belong to
+
+### Step 2: Present Summary to User
+
+Present a user-friendly summary WITHOUT mentioning internal status labels:
+
+Example:
+> "I found **47 sessions** in your Claude Code history:
+> - **12 sessions** haven't been imported yet
+> - **3 sessions** have updates since last import
+> - **32 sessions** are already fully imported
+>
+> The unimported sessions span these projects:
+> - `/Users/you/Projects/ProjectA` (5 sessions)
+> - `/Users/you/Projects/ProjectB` (7 sessions)"
+
+### Step 3: Ask User Import Preferences
+
+Use `AskUserQuestion` to understand what the user wants to import:
+
+```json
+{
+  "questions": [{
+    "header": "Import scope",
+    "question": "Which sessions would you like to import?",
+    "options": [
+      {"label": "All unimported (Recommended)", "description": "Import all 12 sessions that haven't been imported yet"},
+      {"label": "Include updates", "description": "Import unimported sessions + update 3 sessions with new content"},
+      {"label": "Select by project", "description": "Choose which project's sessions to import"},
+      {"label": "Select specific", "description": "I'll review and pick individual sessions"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+### Step 4: Handle User Selection
+
+#### If "All unimported":
+Confirm the import with session count:
+```json
+{
+  "questions": [{
+    "header": "Confirm",
+    "question": "Ready to import 12 sessions. Proceed?",
+    "options": [
+      {"label": "Yes, import", "description": "Start importing all unimported sessions"},
+      {"label": "Let me review first", "description": "Show me the session list to review"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+#### If "Select by project":
+List the projects with unimported sessions and ask:
+```json
+{
+  "questions": [{
+    "header": "Project",
+    "question": "Which project's sessions should I import?",
+    "options": [
+      {"label": "ProjectA", "description": "5 unimported sessions"},
+      {"label": "ProjectB", "description": "7 unimported sessions"},
+      {"label": "Current directory", "description": "Import sessions from the current working directory"}
+    ],
+    "multiSelect": true
+  }]
+}
+```
+
+#### If "Select specific":
+Show the session list with details (project path, turn count, last modified) and let user specify which ones. When user provides selection, map their choice back to session IDs.
+
+### Step 5: Execute Import
+
+**IMPORTANT: Always use session_id for imports, NOT index numbers.** Index numbers can change between list operations and cause wrong sessions to be imported.
+
+```bash
+# Import by session ID (PREFERRED - always use this)
+aline watcher session import abc12345-6789-...
+
+# Import multiple by session ID
+aline watcher session import abc12345,def67890,ghi11111
+
+# With force flag (re-import already tracked)
+aline watcher session import abc12345 --force
+
+# With regenerate flag (update summaries)
+aline watcher session import abc12345 --regenerate
+
+# Synchronous import to wait for completion
+aline watcher session import abc12345 --sync
+```
+
+For importing multiple sessions, collect all the session IDs from your analysis and pass them comma-separated.
+
+### Step 6: Verify Import Success
+
+After import, check the status again:
+
+```bash
+aline watcher session list --detect-turns
+```
+
+Verify:
+- Previously unimported sessions should now show as imported
+- Check for any errors in the import output
+- Report success/failure count to user
+
+### Step 7: Ask If User Is Satisfied
+
+```json
+{
+  "questions": [{
+    "header": "Continue?",
+    "question": "Successfully imported X sessions. What would you like to do next?",
+    "options": [
+      {"label": "Import more", "description": "Select additional sessions to import"},
+      {"label": "View imported", "description": "Show details of imported sessions"},
+      {"label": "Done", "description": "Finish the import process"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+If user wants to import more, loop back to Step 1.
+
+### Step 8: Final Summary
+
+When the user is done, provide a summary:
+- Total sessions imported in this session
+- Sessions that were updated
+- Any errors encountered
+- Next steps: suggest `aline search` to explore their imported history
+
+## Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `aline watcher session list` | List all discovered sessions with status |
+| `aline watcher session list --detect-turns` | Include turn counts in listing |
+| `aline watcher session list -p N -n M` | Paginate: page N with M items per page |
+| `aline watcher session import <session_id>` | Import by session ID (recommended) |
+| `aline watcher session import <id1>,<id2>` | Import multiple sessions by ID |
+| `aline watcher session import <id> -f` | Force re-import |
+| `aline watcher session import <id> -r` | Regenerate LLM summaries |
+| `aline watcher session import <id> --sync` | Synchronous import (wait for completion) |
+| `aline watcher session show <session_id>` | View details of a specific session |
+
+## Important: Use Session IDs, Not Index Numbers
+
+**Always use session_id (UUID) for import operations.**
+
+Why:
+- Index numbers are assigned dynamically and can change between list commands
+- Using wrong index could import unintended sessions
+- Session IDs are stable and unique identifiers
+
+Example session ID format: `e58f67bf-ebba-47bd-9371-5ef9e06697d3`
+
+You can use UUID prefix for convenience: `e58f67bf` (first 8 characters)
+
+## Error Handling
+
+- **No sessions found**: Check if Claude Code history exists at `~/.claude/projects/`. Suggest running some Claude Code sessions first.
+- **Import fails**: Check disk space, database permissions at `~/.aline/db/aline.db`
+- **Partial import**: Some sessions may fail due to corrupted JSONL files. Report specific errors and suggest `--force` retry.
+- **Watcher not running**: If async import doesn't complete, suggest `aline watcher start` or use `--sync` flag.
+
+## Tips for Large Imports
+
+- For many sessions (50+), import in batches to track progress
+- Use `--sync` flag to see real-time progress for smaller batches
+- Check `~/.aline/.logs/watcher.log` for detailed import logs
+
+## When to Use This Skill
+
+Use this skill when:
+- User is setting up Aline for the first time
+- User wants to import historical Claude Code sessions
+- User asks "how do I import my history?" or similar
+- User wants to selectively import specific project sessions
+- User needs to re-import or update existing sessions
+"""
+
 # Registry of all skills to install
 SKILLS_REGISTRY: dict[str, str] = {
     "aline": ALINE_SKILL_MD,
     "aline-share": ALINE_SHARE_SKILL_MD,
+    "aline-import-history-sessions": ALINE_IMPORT_HISTORY_SESSIONS_SKILL_MD,
 }
 
 
@@ -293,32 +516,49 @@ def add_tmux_command() -> int:
     _source_aline_tmux_conf(tmux_conf)
 
     console.print(f"[green]✓[/green] tmux installed and config ready: [cyan]{tmux_conf}[/cyan]")
-    console.print("[dim]Tip: in the Aline dashboard tmux session, mouse drag will copy to clipboard.[/dim]")
+    console.print(
+        "[dim]Tip: in the Aline dashboard tmux session, mouse drag will copy to clipboard.[/dim]"
+    )
     return 0
 
 
-def _install_skill_to_path(skill_root: Path, skill_name: str, skill_content: str) -> Path:
-    """Install a skill to the specified root directory.
+def _ensure_symlink(target_link: Path, source_file: Path, force: bool = False) -> bool:
+    """Create a symlink at target_link pointing to source_file.
 
     Args:
-        skill_root: Root directory for skills (e.g., ~/.claude/skills)
-        skill_name: Name of the skill (e.g., "aline")
-        skill_content: Content of the SKILL.md file
+        target_link: The path where the symlink should be created (e.g., ~/.claude/skills/aline/SKILL.md)
+        source_file: The actual file to link to (e.g., ~/.aline/skills/aline/SKILL.md)
+        force: Whether to overwrite existing files/links
 
     Returns:
-        Path to the installed SKILL.md file
+        True if a new link was created or updated, False if skipped (already exists)
     """
-    skill_dir = skill_root / skill_name
-    skill_dir.mkdir(parents=True, exist_ok=True)
-    skill_file = skill_dir / "SKILL.md"
-    skill_file.write_text(skill_content, encoding="utf-8")
-    return skill_file
+    if target_link.exists() or target_link.is_symlink():
+        if not force:
+            # Check if it already points to the right place
+            try:
+                if target_link.is_symlink() and target_link.resolve() == source_file.resolve():
+                    return False  # Already correct
+            except Exception:
+                pass
+            return False  # Exists and not forced
+
+        # Force: remove existing
+        if target_link.is_dir() and not target_link.is_symlink():
+            shutil.rmtree(target_link)
+        else:
+            target_link.unlink()
+
+    target_link.parent.mkdir(parents=True, exist_ok=True)
+    target_link.symlink_to(source_file)
+    return True
 
 
 def add_skills_command(force: bool = False) -> int:
-    """Install Aline skills for Claude Code.
+    """Install Aline skills for Claude Code and Codex.
 
-    Installs all skills from SKILLS_REGISTRY to ~/.claude/skills/
+    1. Writes built-in skills to ~/.aline/skills/
+    2. Creates symlinks in ~/.claude/skills/ and ~/.codex/skills/
 
     Args:
         force: Overwrite existing skills if they exist
@@ -326,42 +566,128 @@ def add_skills_command(force: bool = False) -> int:
     Returns:
         Exit code (0 for success, 1 for failure)
     """
-    claude_skill_root = Path.home() / ".claude" / "skills"
+    aline_skill_root = Path.home() / ".aline" / "skills"
+    targets = [
+        ("Claude", Path.home() / ".claude" / "skills"),
+        ("Codex", Path.home() / ".codex" / "skills"),
+        ("OpenCode", Path.home() / ".config" / "opencode" / "skill"),
+    ]
+
     installed_skills: list[str] = []
     skipped_skills: list[str] = []
     failed_skills: list[tuple[str, str]] = []
 
     for skill_name, skill_content in SKILLS_REGISTRY.items():
-        skill_path = claude_skill_root / skill_name / "SKILL.md"
-
-        # Check if skill already exists
-        if skill_path.exists() and not force:
-            skipped_skills.append(skill_name)
-            continue
-
+        # 1. Update master copy in ~/.aline/skills
+        master_path = aline_skill_root / skill_name / "SKILL.md"
         try:
-            _install_skill_to_path(claude_skill_root, skill_name, skill_content)
-            installed_skills.append(skill_name)
+            master_path.parent.mkdir(parents=True, exist_ok=True)
+            master_path.write_text(skill_content, encoding="utf-8")
         except Exception as e:
-            failed_skills.append((skill_name, str(e)))
+            failed_skills.append((f"{skill_name} (storage)", str(e)))
+            continue
+
+        # 2. Link to targets
+        for tool_name, tool_root in targets:
+            dest_path = tool_root / skill_name / "SKILL.md"
+
+            try:
+                updated = _ensure_symlink(dest_path, master_path, force)
+                if updated:
+                    installed_skills.append(f"{tool_name}/{skill_name}")
+                else:
+                    skipped_skills.append(f"{tool_name}/{skill_name}")
+            except Exception as e:
+                failed_skills.append((f"{tool_name}/{skill_name}", str(e)))
 
     # Report results
-    for skill_name in installed_skills:
-        skill_path = claude_skill_root / skill_name / "SKILL.md"
-        console.print(f"[green]✓[/green] Installed: [cyan]{skill_path}[/cyan]")
+    for item in installed_skills:
+        console.print(f"[green]✓[/green] Installed: [cyan]{item}[/cyan]")
 
-    for skill_name in skipped_skills:
-        skill_path = claude_skill_root / skill_name / "SKILL.md"
-        console.print(f"[yellow]⊘[/yellow] Already exists: [dim]{skill_path}[/dim]")
+    for item in skipped_skills:
+        console.print(f"[yellow]⊘[/yellow] Already exists: [dim]{item}[/dim]")
 
-    for skill_name, error in failed_skills:
-        console.print(f"[red]✗[/red] Failed to install {skill_name}: {error}")
+    for item, error in failed_skills:
+        console.print(f"[red]✗[/red] Failed to install {item}: {error}")
 
     if skipped_skills and not installed_skills:
         console.print("[dim]Use --force to overwrite existing skills[/dim]")
     elif installed_skills:
-        skill_names = ", ".join(f"/{s}" for s in installed_skills)
-        console.print(f"[dim]Restart Claude Code to activate: {skill_names}[/dim]")
+        console.print("[dim]Restart your AI tools to activate new skills[/dim]")
 
     return 1 if failed_skills else 0
 
+
+def add_skills_dev_command(force: bool = False) -> int:
+    """Install developer skills from skill-dev/ directory.
+
+    Symlinks skills from ./skill-dev/ to ~/.claude/skills/ and ~/.codex/skills/
+
+    Args:
+        force: Overwrite existing skills if they exist
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    # Find skill-dev directory relative to this file's package location
+    package_root = Path(__file__).parent.parent.parent.parent
+    skill_dev_dir = package_root / "skill-dev"
+
+    if not skill_dev_dir.exists():
+        console.print(f"[red]skill-dev/ directory not found at:[/red] {skill_dev_dir}")
+        console.print("[dim]This command is for developer use only.[/dim]")
+        return 1
+
+    targets = [
+        ("Claude", Path.home() / ".claude" / "skills"),
+        ("Codex", Path.home() / ".codex" / "skills"),
+        ("OpenCode", Path.home() / ".config" / "opencode" / "skill"),
+    ]
+
+    installed_skills: list[str] = []
+    skipped_skills: list[str] = []
+    failed_skills: list[tuple[str, str]] = []
+
+    # Scan skill-dev for directories containing SKILL.md
+    for skill_dir in skill_dev_dir.iterdir():
+        if not skill_dir.is_dir():
+            continue
+
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.exists():
+            continue
+
+        skill_name = skill_dir.name
+
+        for tool_name, tool_root in targets:
+            dest_path = tool_root / skill_name / "SKILL.md"
+
+            try:
+                updated = _ensure_symlink(dest_path, skill_file, force)
+                if updated:
+                    installed_skills.append(f"{tool_name}/{skill_name}")
+                else:
+                    skipped_skills.append(f"{tool_name}/{skill_name}")
+            except Exception as e:
+                failed_skills.append((f"{tool_name}/{skill_name}", str(e)))
+
+    if not installed_skills and not skipped_skills and not failed_skills:
+        console.print("[yellow]No skills found in skill-dev/[/yellow]")
+        return 0
+
+    # Report results
+    for item in installed_skills:
+        console.print(f"[green]✓[/green] Linked: [cyan]{item}[/cyan]")
+
+    for item in skipped_skills:
+        console.print(f"[yellow]⊘[/yellow] Already exists: [dim]{item}[/dim]")
+
+    for item, error in failed_skills:
+        console.print(f"[red]✗[/red] Failed to install {item}: {error}")
+
+    if skipped_skills and not installed_skills:
+        console.print("[dim]Use --force to overwrite existing skills[/dim]")
+    elif installed_skills:
+        console.print("[dim]Restart your AI tools to activate new skills[/dim]")
+
+    return 1 if failed_skills else 0

realign/commands/config.py

@@ -13,18 +13,9 @@ console = Console()
 
 
 def config_command(
-    action: str = typer.Argument(
-        ...,
-        help="Action to perform: 'get', 'set', or 'init'"
-    ),
-    key: Optional[str] = typer.Argument(
-        None,
-        help="Configuration key (for get/set operations)"
-    ),
-    value: Optional[str] = typer.Argument(
-        None,
-        help="Configuration value (for set operation)"
-    ),
+    action: str = typer.Argument(..., help="Action to perform: 'get', 'set', or 'init'"),
+    key: Optional[str] = typer.Argument(None, help="Configuration key (for get/set operations)"),
+    value: Optional[str] = typer.Argument(None, help="Configuration value (for set operation)"),
 ):
     """
     Manage ReAlign configuration.

realign/commands/context.py

@@ -146,7 +146,9 @@ def context_show_command(
             console.print("[dim]No active context.[/dim]")
             env_val = os.environ.get(CONTEXT_ID_ENV_VAR)
             if env_val:
-                console.print(f"[dim]ALINE_CONTEXT_ID is set to '{env_val}' but no matching context found.[/dim]")
+                console.print(
+                    f"[dim]ALINE_CONTEXT_ID is set to '{env_val}' but no matching context found.[/dim]"
+                )
             console.print("[dim]Searches will include all sessions/events.[/dim]")
             return 0