raise-cli 2.2.1__py3-none-any.whl

raise_cli/session/close.py

@@ -0,0 +1,268 @@
+"""Session close orchestrator.
+
+Processes structured session output and performs all writes atomically:
+1. Record session in personal/sessions/index.jsonl (developer-specific)
+2. Append patterns to memory/patterns.jsonl (project knowledge)
+3. Update coaching corrections in developer.yaml
+4. Update coaching observations in developer.yaml
+5. Clear current_session in developer.yaml
+6. Write session-state.yaml (project-level working state)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+from raise_cli.memory.writer import (
+    PatternInput,
+    PatternSubType,
+    SessionInput,
+    WriteResult,
+    append_pattern,
+    append_session,
+)
+from raise_cli.onboarding.profile import (
+    DeveloperProfile,
+    add_correction,
+    end_session,
+    save_developer_profile,
+    update_coaching,
+)
+from raise_cli.schemas.session_state import (
+    CurrentWork,
+    EpicProgress,
+    LastSession,
+    PendingItems,
+    SessionState,
+)
+from raise_cli.session.state import save_session_state
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CloseInput:
+    """Structured input for session close.
+
+    Can be populated from CLI flags or from a state file.
+    """
+
+    session_id: str = ""
+    summary: str = ""
+    session_type: str = "feature"
+    outcomes: list[str] = field(default_factory=lambda: list[str]())
+    patterns: list[dict[str, str]] = field(
+        default_factory=lambda: list[dict[str, str]]()
+    )
+    corrections: list[dict[str, str]] = field(
+        default_factory=lambda: list[dict[str, str]]()
+    )
+    current_work: dict[str, str] | None = None
+    pending: dict[str, list[str]] | None = None
+    progress: dict[str, int | str] | None = None
+    completed_epics: list[str] = field(default_factory=lambda: list[str]())
+    coaching: dict[str, object] | None = None
+    notes: str = ""
+    narrative: str = ""
+    next_session_prompt: str = ""
+
+
+@dataclass
+class CloseResult:
+    """Result of session close operation."""
+
+    success: bool
+    session_id: str = ""
+    patterns_added: int = 0
+    corrections_added: int = 0
+    messages: list[str] = field(default_factory=lambda: list[str]())
+
+
+def load_state_file(path: Path) -> CloseInput:
+    """Load close input from a YAML state file.
+
+    Args:
+        path: Path to the state file written by the AI skill.
+
+    Returns:
+        CloseInput populated from the file.
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist.
+        yaml.YAMLError: If the file is not valid YAML.
+    """
+    content = path.read_text(encoding="utf-8")
+    data = yaml.safe_load(content)
+    if not isinstance(data, dict):
+        msg = f"State file must be a YAML mapping, got {type(data).__name__}"
+        raise ValueError(msg)
+
+    d = cast(dict[str, object], data)
+
+    return CloseInput(
+        session_id=str(d.get("session_id", "")),
+        summary=str(d.get("summary", "")),
+        session_type=str(d.get("type", "feature")),
+        outcomes=list(d.get("outcomes", []) or []),  # type: ignore[arg-type]
+        patterns=list(d.get("patterns", []) or []),  # type: ignore[arg-type]
+        corrections=list(d.get("corrections", []) or []),  # type: ignore[arg-type]
+        current_work=d.get("current_work"),  # type: ignore[arg-type]
+        pending=d.get("pending"),  # type: ignore[arg-type]
+        progress=d.get("progress"),  # type: ignore[arg-type]
+        completed_epics=list(d.get("completed_epics", []) or []),  # type: ignore[arg-type]
+        coaching=d.get("coaching"),  # type: ignore[arg-type]
+        notes=str(d.get("notes", "")),
+        narrative=str(d.get("narrative", "")),
+        next_session_prompt=str(d.get("next_session_prompt", "")),
+    )
+
+
+def process_session_close(
+    close_input: CloseInput,
+    profile: DeveloperProfile,
+    project_path: Path,
+    session_id: str | None = None,
+) -> CloseResult:
+    """Process session close — perform all writes.
+
+    Args:
+        close_input: Structured session close data.
+        profile: Current developer profile.
+        project_path: Absolute path to the project root.
+
+    Returns:
+        CloseResult with operation summary.
+    """
+    result = CloseResult(success=True)
+    memory_dir = project_path / ".raise" / "rai" / "memory"
+    personal_dir = project_path / ".raise" / "rai" / "personal"
+
+    # 1. Record session in personal/sessions/index.jsonl
+    session_input = SessionInput(
+        topic=close_input.summary,
+        session_type=close_input.session_type,
+        outcomes=close_input.outcomes,
+    )
+    session_result = append_session(personal_dir, session_input)
+    result.session_id = session_result.id
+    result.messages.append(f"Session {session_result.id} recorded")
+
+    # 2. Append patterns
+    for pat_data in close_input.patterns:
+        description = pat_data.get("description", "")
+        if not description:
+            continue
+        context = pat_data.get("context", "")
+        context_list = [c.strip() for c in context.split(",")]
+        pat_type = pat_data.get("type", "process")
+        try:
+            sub_type = PatternSubType(pat_type)
+        except ValueError:
+            sub_type = PatternSubType.PROCESS
+
+        pat_input = PatternInput(
+            content=description,
+            sub_type=sub_type,
+            context=context_list,
+            learned_from=result.session_id,
+        )
+        pat_result: WriteResult = append_pattern(
+            memory_dir, pat_input, developer_prefix=profile.get_pattern_prefix()
+        )
+        result.patterns_added += 1
+        result.messages.append(f"Pattern {pat_result.id} added")
+
+    # 3. Update coaching corrections
+    updated_profile = profile
+    for corr_data in close_input.corrections:
+        what = corr_data.get("what", "")
+        lesson = corr_data.get("lesson", "")
+        if what and lesson:
+            updated_profile = add_correction(
+                updated_profile, result.session_id, what, lesson
+            )
+            result.corrections_added += 1
+
+    # 4. Update coaching observations
+    if close_input.coaching:
+        c = close_input.coaching
+        updated_profile = update_coaching(
+            updated_profile,
+            strengths=c.get("strengths"),  # type: ignore[arg-type]
+            growth_edge=c.get("growth_edge"),  # type: ignore[arg-type]
+            trust_level=c.get("trust_level"),  # type: ignore[arg-type]
+            autonomy=c.get("autonomy"),  # type: ignore[arg-type]
+            relationship=c.get("relationship"),  # type: ignore[arg-type]
+            communication_notes=c.get("communication_notes"),  # type: ignore[arg-type]
+        )
+        result.messages.append("Coaching updated")
+
+    # 5. Remove session from active_sessions and save profile
+    updated_profile = end_session(updated_profile, session_id=session_id or result.session_id)
+    save_developer_profile(updated_profile)
+    result.messages.append("Profile updated")
+
+    # 5. Write session-state.yaml
+    if close_input.current_work:
+        cw = close_input.current_work
+        current_work = CurrentWork(
+            release=cw.get("release", ""),
+            epic=cw.get("epic", ""),
+            story=cw.get("story", ""),
+            phase=cw.get("phase", ""),
+            branch=cw.get("branch", ""),
+        )
+    else:
+        current_work = CurrentWork(release="", epic="", story="", phase="", branch="")
+
+    pending = PendingItems()
+    if close_input.pending:
+        pending = PendingItems(
+            decisions=close_input.pending.get("decisions", []),
+            blockers=close_input.pending.get("blockers", []),
+            next_actions=close_input.pending.get("next_actions", []),
+        )
+
+    # Build progress if provided
+    progress: EpicProgress | None = None
+    if close_input.progress:
+        p = close_input.progress
+        progress = EpicProgress(
+            epic=str(p.get("epic", "")),
+            stories_done=int(p.get("stories_done", 0)),
+            stories_total=int(p.get("stories_total", 0)),
+            sp_done=int(p.get("sp_done", 0)),
+            sp_total=int(p.get("sp_total", 0)),
+        )
+
+    session_state = SessionState(
+        current_work=current_work,
+        last_session=LastSession(
+            id=result.session_id,
+            date=date.today(),
+            developer=profile.name,
+            summary=close_input.summary,
+            patterns_captured=[f"PAT-{result.session_id}" for _ in close_input.patterns]
+            if close_input.patterns
+            else [],
+        ),
+        pending=pending,
+        notes=close_input.notes,
+        narrative=close_input.narrative,
+        next_session_prompt=close_input.next_session_prompt,
+        progress=progress,
+        completed_epics=close_input.completed_epics,
+    )
+    # Write to flat file (not per-session dir) — flat file serves as
+    # cross-session continuity buffer. Next session start will migrate
+    # it to the new per-session directory.
+    save_session_state(project_path, session_state)
+    result.messages.append("Session state saved")
+
+    return result

raise_cli/session/journal.py

@@ -0,0 +1,119 @@
+"""Session journal — incremental memory persistence.
+
+Append-only journal for preserving decisions, insights, and task completions
+across context compaction events. Each entry is a JSONL line in
+.raise/rai/personal/sessions/{session_id}/journal.jsonl.
+
+Two consumers:
+- Agent: calls `rai session journal add` to record decisions/insights
+- Hooks: call `rai session journal show --compact` to inject context post-compaction
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from raise_cli.memory.writer import WriteResult, get_next_id
+from raise_cli.schemas.journal import JournalEntry, JournalEntryType
+
+JOURNAL_FILE = "journal.jsonl"
+
+
+def append_journal_entry(
+    session_dir: Path,
+    entry_type: JournalEntryType,
+    content: str,
+    tags: list[str] | None = None,
+    timestamp: datetime | None = None,
+) -> WriteResult:
+    """Append a journal entry to the session journal.
+
+    Args:
+        session_dir: Path to per-session directory.
+        entry_type: Category of entry.
+        content: The content to preserve.
+        tags: Optional context tags.
+        timestamp: When the entry was created. Defaults to now.
+
+    Returns:
+        WriteResult with generated ID.
+    """
+    file_path = session_dir / JOURNAL_FILE
+    entry_id = get_next_id(file_path, "JRN")
+    ts = timestamp or datetime.now()
+
+    data: dict[str, Any] = {
+        "id": entry_id,
+        "timestamp": ts.isoformat(),
+        "entry_type": entry_type.value,
+        "content": content,
+        "tags": tags or [],
+    }
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    with file_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(data) + "\n")
+
+    return WriteResult(
+        success=True,
+        id=entry_id,
+        file_path=str(file_path),
+        message=f"Journal {entry_id} appended ({entry_type.value})",
+    )
+
+
+def read_journal(
+    session_dir: Path,
+    last_n: int | None = None,
+) -> list[JournalEntry]:
+    """Read journal entries from a session.
+
+    Args:
+        session_dir: Path to per-session directory.
+        last_n: If set, return only the last N entries.
+
+    Returns:
+        List of JournalEntry objects, oldest first.
+    """
+    file_path = session_dir / JOURNAL_FILE
+    if not file_path.exists():
+        return []
+
+    entries: list[JournalEntry] = []
+    for line in file_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        data = json.loads(line)
+        entries.append(JournalEntry(**data))
+
+    if last_n is not None:
+        entries = entries[-last_n:]
+
+    return entries
+
+
+def format_journal_compact(entries: list[JournalEntry]) -> str:
+    """Format journal entries for compact context injection.
+
+    Produces a token-efficient summary suitable for post-compaction
+    context injection via hook stdout.
+
+    Args:
+        entries: Journal entries to format.
+
+    Returns:
+        Compact multi-line string.
+    """
+    if not entries:
+        return "No journal entries."
+
+    lines: list[str] = ["# Session Journal"]
+    for entry in entries:
+        tag_suffix = f" [{', '.join(entry.tags)}]" if entry.tags else ""
+        lines.append(f"- {entry.entry_type.value.upper()}: {entry.content}{tag_suffix}")
+
+    return "\n".join(lines)

raise_cli/session/resolver.py

@@ -0,0 +1,126 @@
+"""Session ID resolution logic.
+
+Resolves session ID from --session flag or RAI_SESSION_ID env var
+following priority order: flag > env var > error (or None for optional).
+"""
+
+from __future__ import annotations
+
+from raise_cli.exceptions import RaiSessionNotFoundError
+
+
+def _normalize_session_id(session_id: str) -> str:
+    """Normalize session ID to standard format.
+
+    Accepts:
+    - "SES-177" (already normalized)
+    - "ses-177" (lowercase prefix)
+    - "177" (numeric only)
+
+    Rejects values containing path traversal components (CWE-23) since
+    session IDs are used to construct file paths.
+
+    Returns:
+        Normalized session ID in format "SES-NNN".
+
+    Raises:
+        ValueError: If session_id contains '..' or path separator characters.
+    """
+    session_id = session_id.strip()
+
+    if not session_id:
+        return session_id  # Empty string, caller will handle
+
+    # CWE-23: Reject path traversal components before any path construction.
+    # Session IDs flow from env vars (RAI_SESSION_ID) into get_session_dir().
+    if ".." in session_id or "/" in session_id or "\\" in session_id:
+        raise ValueError(
+            f"Invalid session ID — path traversal characters detected: {session_id!r}"
+        )
+
+    # Already normalized (case-insensitive check)
+    if session_id.upper().startswith("SES-"):
+        return session_id.upper()
+
+    # Numeric only — add prefix
+    if session_id.isdigit():
+        return f"SES-{session_id}"
+
+    # Unknown format — return as-is (let caller handle invalid formats)
+    return session_id
+
+
+def resolve_session_id(
+    session_flag: str | None,
+    env_var: str | None,
+) -> str:
+    """Resolve session ID from flag or environment variable.
+
+    Resolution priority:
+    1. --session flag (explicit, per-command)
+    2. RAI_SESSION_ID env var (per-terminal/process)
+    3. RaiSessionNotFoundError (no session context)
+
+    Normalization:
+    - "177" → "SES-177"
+    - "ses-177" → "SES-177"
+    - "SES-177" → "SES-177" (no change)
+
+    Args:
+        session_flag: Value from --session CLI flag.
+        env_var: Value from RAI_SESSION_ID environment variable.
+
+    Returns:
+        Normalized session ID (e.g., "SES-177").
+
+    Raises:
+        RaiSessionNotFoundError: When neither flag nor env var is provided.
+
+    Example:
+        >>> resolve_session_id(session_flag="177", env_var=None)
+        'SES-177'
+        >>> resolve_session_id(session_flag=None, env_var="SES-178")
+        'SES-178'
+    """
+    # Priority 1: --session flag
+    if session_flag and session_flag.strip():
+        return _normalize_session_id(session_flag)
+
+    # Priority 2: RAI_SESSION_ID env var
+    if env_var and env_var.strip():
+        return _normalize_session_id(env_var)
+
+    # Priority 3: Error
+    raise RaiSessionNotFoundError(
+        "No session ID provided",
+        hint="Pass --session SES-NNN or set RAI_SESSION_ID environment variable",
+    )
+
+
+def resolve_session_id_optional(
+    session_flag: str | None,
+    env_var: str | None,
+) -> str | None:
+    """Resolve session ID, returning None when neither source is provided.
+
+    Same resolution priority as resolve_session_id but returns None instead
+    of raising when no session context exists. Use for commands where
+    --session is optional (e.g., telemetry emit commands).
+
+    Args:
+        session_flag: Value from --session CLI flag.
+        env_var: Value from RAI_SESSION_ID environment variable.
+
+    Returns:
+        Normalized session ID, or None if neither source provided.
+    """
+    # Priority 1: --session flag
+    if session_flag and session_flag.strip():
+        return _normalize_session_id(session_flag)
+
+    # Priority 2: RAI_SESSION_ID env var
+    if env_var and env_var.strip():
+        return _normalize_session_id(env_var)
+
+    # Priority 3: None (no session context — that's OK)
+    return None

raise_cli/session/state.py

@@ -0,0 +1,187 @@
+"""Session state persistence.
+
+Reads and writes .raise/rai/personal/session-state.yaml — per-developer working
+state that is overwritten each session-close and read by session-start.
+
+Migration: if the old path (.raise/rai/session-state.yaml) exists and the new
+personal/ path does not, the file is moved automatically.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from raise_cli.config.paths import get_session_dir
+from raise_cli.schemas.session_state import SessionState
+
+logger = logging.getLogger(__name__)
+
+# New path: personal directory (gitignored, per-developer)
+SESSION_STATE_REL_PATH = Path(".raise") / "rai" / "personal" / "session-state.yaml"
+
+# Legacy path for migration
+_LEGACY_SESSION_STATE_REL_PATH = Path(".raise") / "rai" / "session-state.yaml"
+
+
+def get_session_state_path(project_path: Path, session_id: str | None = None) -> Path:
+    """Get the absolute path to session state file.
+
+    When session_id is provided, returns per-session path:
+        .raise/rai/personal/sessions/{session_id}/state.yaml
+
+    When session_id is None, returns legacy flat path:
+        .raise/rai/personal/session-state.yaml
+
+    Args:
+        project_path: Absolute path to the project root.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        Path to the session state file.
+    """
+    if session_id is not None:
+        return get_session_dir(session_id, project_path) / "state.yaml"
+    return project_path / SESSION_STATE_REL_PATH
+
+
+def _migrate_session_state(project_path: Path) -> None:
+    """Migrate session-state.yaml from old shared path to personal/.
+
+    Moves .raise/rai/session-state.yaml → .raise/rai/personal/session-state.yaml
+    if old exists and new does not.
+    """
+    old_path = project_path / _LEGACY_SESSION_STATE_REL_PATH
+    new_path = get_session_state_path(project_path)
+
+    if old_path.exists() and not new_path.exists():
+        new_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(old_path), str(new_path))
+        logger.info("Migrated session state: %s → %s", old_path, new_path)
+
+
+def migrate_flat_to_session(project_path: Path, session_id: str) -> bool:
+    """One-time migration from flat layout to per-session directory.
+
+    Moves:
+    - personal/session-state.yaml → personal/sessions/{session_id}/state.yaml
+    - personal/telemetry/signals.jsonl → personal/sessions/{session_id}/signals.jsonl
+
+    Args:
+        project_path: Absolute path to the project root.
+        session_id: Session ID for the target per-session directory.
+
+    Returns:
+        True if migration occurred, False if nothing to migrate.
+    """
+    personal_dir = project_path / ".raise" / "rai" / "personal"
+    flat_state = personal_dir / "session-state.yaml"
+    flat_signals = personal_dir / "telemetry" / "signals.jsonl"
+
+    # Nothing to migrate
+    if not flat_state.exists() and not flat_signals.exists():
+        return False
+
+    # Don't migrate if session dir already exists
+    session_dir = get_session_dir(session_id, project_path)
+    if session_dir.exists():
+        return False
+
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    if flat_state.exists():
+        shutil.move(str(flat_state), str(session_dir / "state.yaml"))
+        logger.info("Migrated state: %s → %s/state.yaml", flat_state, session_dir)
+
+    if flat_signals.exists():
+        shutil.move(str(flat_signals), str(session_dir / "signals.jsonl"))
+        logger.info(
+            "Migrated signals: %s → %s/signals.jsonl", flat_signals, session_dir
+        )
+
+    return True
+
+
+def cleanup_session_dir(project_path: Path, session_id: str) -> None:
+    """Remove per-session directory after session close.
+
+    Only removes the specific session directory. Does NOT remove
+    shared files (index.jsonl, memory/).
+
+    Args:
+        project_path: Absolute path to the project root.
+        session_id: Session ID whose directory to remove.
+    """
+    session_dir = get_session_dir(session_id, project_path)
+    if session_dir.exists():
+        shutil.rmtree(session_dir)
+        logger.info("Cleaned up session dir: %s", session_dir)
+
+
+def load_session_state(
+    project_path: Path, session_id: str | None = None
+) -> SessionState | None:
+    """Load session state from per-session directory or flat file.
+
+    When session_id is provided, loads from per-session directory.
+    When session_id is None, loads from legacy flat file (with migration).
+
+    Args:
+        project_path: Absolute path to the project root.
+        session_id: Optional session ID for per-session isolation.
+
+    Returns:
+        SessionState if file exists and is valid, None otherwise.
+    """
+    if session_id is None:
+        _migrate_session_state(project_path)
+    state_path = get_session_state_path(project_path, session_id)
+
+    if not state_path.exists():
+        logger.debug("Session state not found: %s", state_path)
+        return None
+
+    try:
+        content = state_path.read_text(encoding="utf-8")
+        data = yaml.safe_load(content)
+        if data is None:
+            logger.warning("Empty session state: %s", state_path)
+            return None
+        return SessionState.model_validate(data)
+    except yaml.YAMLError as e:
+        logger.warning("Invalid YAML in session state: %s", e)
+        return None
+    except ValidationError as e:
+        logger.warning("Invalid session state schema: %s", e)
+        return None
+
+
+def save_session_state(
+    project_path: Path, state: SessionState, session_id: str | None = None
+) -> None:
+    """Save session state to per-session directory or flat file.
+
+    When session_id is provided, writes to per-session directory.
+    When session_id is None, writes to legacy flat file.
+
+    Creates parent directories if they don't exist.
+    Overwrites any existing file.
+
+    Args:
+        project_path: Absolute path to the project root.
+        state: The session state to save.
+        session_id: Optional session ID for per-session isolation.
+    """
+    state_path = get_session_state_path(project_path, session_id)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = state.model_dump(mode="json")
+    content = yaml.dump(
+        data, default_flow_style=False, allow_unicode=True, sort_keys=False
+    )
+    state_path.write_text(content, encoding="utf-8")
+    logger.debug("Saved session state: %s", state_path)