trusty-common 0.63.0

//! Native trusty-mpm session-pause snapshot writer (MCP `session_context_pause`
//! tool).
//!
//! Why: `/tm-session-pause` used to shell out to write the snapshot markdown
//! file and append the pause log line by hand. No reusable Rust writer existed
//! — [`crate::catchup::session_finder`] only ever *reads* the format. This
//! module is the write side, built to emit EXACTLY the section shape
//! [`crate::catchup::session_finder::find_paused_sessions`] already parses, so
//! a session this module writes round-trips through the existing reader
//! unchanged.
//! What: [`write_pause_snapshot`] writes `session-YYYYMMDD-HHMMSS.md` under
//! `<project_dir>/.trusty-mpm/sessions/<session-id>/` and appends the matching
//! `pause` line to `sessions-log.jsonl` via
//! [`crate::catchup::session_log::append_entry`], recording the snapshot path
//! relative to the store root so the log stays the attribution index for both
//! the per-session and the pre-#5272 flat layout.
//! Test: `write_pause_snapshot_round_trips_through_reader`,
//! `write_pause_snapshot_omits_empty_sections`,
//! `write_pause_snapshot_appends_log_entry`,
//! `write_pause_snapshot_writes_under_session_dir`,
//! `write_pause_snapshot_falls_back_to_root_for_unsafe_id`.

use std::path::{Path, PathBuf};

use chrono::Utc;

use crate::catchup::git::capture_git_status;
use crate::catchup::session_log::{self, SessionLogEntry};
use crate::catchup::sha_scrub::scrub_sha_like;

/// Input fields for a single pause snapshot.
///
/// Why: groups everything the `session_context_pause` MCP tool receives from
/// its caller so [`write_pause_snapshot`] takes one argument instead of a long
/// parameter list.
/// What: `session_id` keys the append-only log entry; `summary` is required
/// prose; `completed`/`in_progress`/`next_steps` are optional bullet lists;
/// `tmux_window` is the `session_name:window_index:window_id` string (omitted
/// entirely from the file when `None`, matching the reader's back-compat
/// contract for snapshots that predate the field).
/// Test: exercised by every `write_pause_snapshot_*` test.
#[derive(Debug, Clone)]
pub struct PauseSnapshotInput<'a> {
    /// Stable id for the originating session (keys the append-only log).
    pub session_id: &'a str,
    /// The `## Summary` section body (required, non-empty by caller contract).
    pub summary: &'a str,
    /// The `## Completed` section's bullet items.
    pub completed: &'a [String],
    /// The `## In Progress` section's bullet items.
    pub in_progress: &'a [String],
    /// The `## Next Steps` section's bullet items.
    pub next_steps: &'a [String],
    /// The `## Tmux Window` section body, when captured inside tmux.
    pub tmux_window: Option<&'a str>,
}

/// Result of a successful pause-snapshot write.
///
/// Why: the MCP tool returns both the path and the timestamp it used, so the
/// caller (and the PM transcript) can reference the exact snapshot filename.
/// What: `snapshot_path` is the absolute path written; `timestamp` is the UTC
/// instant used to derive the filename and the log entry.
/// Test: exercised by every `write_pause_snapshot_*` test.
#[derive(Debug, Clone)]
pub struct PauseSnapshotOutcome {
    /// Absolute path of the written `session-*.md` file.
    pub snapshot_path: PathBuf,
    /// The UTC instant the filename/log entry were derived from.
    pub timestamp: chrono::DateTime<Utc>,
}

/// Render one `## <Header>` section from a bullet list, or `None` when empty.
///
/// Why: [`session_finder::extract_section`](crate::catchup::session_finder)
/// treats an empty section as absent; mirroring that here keeps back-compat
/// snapshots (predating a given section) indistinguishable from "nothing to
/// report this pause".
/// What: joins `items` as `- <item>` lines under `## <header>`; returns `None`
/// for an empty slice so the caller can skip the section entirely.
/// #9390: each item passes through [`scrub_sha_like`], so a head SHA the PM
/// typed is flagged rather than recorded.
/// Test: `write_pause_snapshot_omits_empty_sections`, `a_snapshot_contains_no_head_sha`.
fn render_bullet_section(header: &str, items: &[String]) -> Option<String> {
    if items.is_empty() {
        return None;
    }
    let mut out = format!("## {header}\n");
    for item in items {
        out.push_str("- ");
        out.push_str(&scrub_sha_like(item));
        out.push('\n');
    }
    Some(out)
}

/// Write a pause snapshot for `project_dir` and append its log entry.
///
/// Why: the single write-side entry point for `session_context_pause` — keeps
/// the markdown shape and the log append atomic-ish (write-then-append, same
/// order the bash skill used) and in one auditable place.
/// What: creates `<project_dir>/.trusty-mpm/sessions/<session-id>/` if needed,
/// captures git status via [`capture_git_status`] for the `## Git Context`
/// section, writes `session-<UTC timestamp>.md` with `## Summary` (always
/// present, even if `input.summary` is empty — the caller contract requires a
/// non-empty summary) followed by `## Completed` / `## In Progress` /
/// `## Next Steps` / `## Git Context` / `## Tmux Window`, each omitted when it
/// would be empty, then appends a `pause` [`SessionLogEntry`] whose `snapshot`
/// is the new file's path RELATIVE to the store root. Returns the resolved
/// absolute path and timestamp.
///
/// #9390: the PM's free text (Summary, Completed, In Progress, Next Steps)
/// passes through [`scrub_sha_like`]; the code-generated `Last commit:` line
/// does not, because #7501 reads it as the supersession baseline.
///
/// #5272: a session id that cannot be a directory name (see
/// [`session_log::session_dir_name`]) writes flat at the store root instead,
/// with a warning — mangling it into a safe name would let two ids share one
/// directory, which is the crosstalk this change exists to remove. Attribution
/// is unaffected either way: the log line, not the location, is what
/// [`session_log::resolve_session_snapshot`] reads.
/// Test: `write_pause_snapshot_round_trips_through_reader`,
/// `write_pause_snapshot_omits_empty_sections`,
/// `write_pause_snapshot_appends_log_entry`,
/// `write_pause_snapshot_writes_under_session_dir`,
/// `write_pause_snapshot_falls_back_to_root_for_unsafe_id`,
/// `a_snapshot_contains_no_head_sha`.
pub fn write_pause_snapshot(
    project_dir: &Path,
    input: &PauseSnapshotInput<'_>,
) -> anyhow::Result<PauseSnapshotOutcome> {
    let sessions_dir = project_dir.join(".trusty-mpm").join("sessions");

    let now = Utc::now();
    let basename = format!("session-{}.md", now.format("%Y%m%d-%H%M%S"));
    // #5272: snapshots live under `sessions/<session-id>/` so the store is
    // partitioned by owner, not just indexed by it.
    let relative = match session_log::session_dir_name(input.session_id) {
        Some(dir) => format!("{dir}/{basename}"),
        None => {
            tracing::warn!(
                session_id = input.session_id,
                "session id is not usable as a directory name; writing the pause \
                 snapshot flat at the store root (attribution still comes from \
                 sessions-log.jsonl)"
            );
            basename
        }
    };
    let snapshot_path = sessions_dir.join(&relative);
    if let Some(parent) = snapshot_path.parent() {
        std::fs::create_dir_all(parent)?;
    }

    let git = capture_git_status(project_dir);
    let mut git_context = String::new();
    if let Some(branch) = &git.branch {
        git_context.push_str(&format!("Branch: {branch}\n"));
    }
    if let Some(commit) = &git.last_commit {
        git_context.push_str(&format!("Last commit: {commit}\n"));
    }
    if let Some(summary) = &git.uncommitted_summary {
        git_context.push_str(&format!("Uncommitted changes: {summary}\n"));
    }

    let mut md = format!(
        "# Session Pause - {}\n\n## Summary\n{}\n\n",
        now.to_rfc3339(),
        scrub_sha_like(input.summary) // #9390: PM text keeps identifiers, not heads.
    );
    if let Some(section) = render_bullet_section("Completed", input.completed) {
        md.push_str(&section);
        md.push('\n');
    }
    if let Some(section) = render_bullet_section("In Progress", input.in_progress) {
        md.push_str(&section);
        md.push('\n');
    }
    if let Some(section) = render_bullet_section("Next Steps", input.next_steps) {
        md.push_str(&section);
        md.push('\n');
    }
    if !git_context.is_empty() {
        md.push_str("## Git Context\n");
        md.push_str(&git_context);
        md.push('\n');
    }
    if let Some(win) = input.tmux_window.filter(|w| !w.is_empty()) {
        md.push_str("## Tmux Window\n");
        md.push_str(win);
        md.push('\n');
    }

    std::fs::write(&snapshot_path, md)?;

    session_log::append_entry(
        &sessions_dir,
        &SessionLogEntry {
            session_id: input.session_id.to_string(),
            event: session_log::EVENT_PAUSE.to_string(),
            snapshot: relative,
            timestamp: now.to_rfc3339(),
        },
    )?;

    Ok(PauseSnapshotOutcome {
        snapshot_path,
        timestamp: now,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::catchup::session_finder::{PausedSession, find_paused_sessions};
    use tempfile::TempDir;

    fn init_git_repo(dir: &Path) {
        let run = |args: &[&str]| {
            std::process::Command::new("git")
                .arg("-C")
                .arg(dir)
                .args(args)
                .output()
                .unwrap();
        };
        run(&["init"]);
        run(&["config", "user.email", "t@t.com"]);
        run(&["config", "user.name", "T"]);
        std::fs::write(dir.join("README.md"), b"hi").unwrap();
        run(&["add", "."]);
        run(&["commit", "-m", "init"]);
    }

    #[test]
    fn write_pause_snapshot_round_trips_through_reader() {
        let tmp = TempDir::new().unwrap();
        init_git_repo(tmp.path());

        let input = PauseSnapshotInput {
            session_id: "s1",
            summary: "Did the thing.",
            completed: &["step 1".to_string()],
            in_progress: &["step 2".to_string()],
            next_steps: &["step 3".to_string()],
            tmux_window: Some("main:2:@7"),
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        assert!(outcome.snapshot_path.exists());

        let sessions = find_paused_sessions(tmp.path()).unwrap();
        assert_eq!(sessions.len(), 1);
        match &sessions[0] {
            PausedSession::TrustyMpm {
                summary,
                in_progress,
                next_steps,
                tmux_window,
                git_context,
                ..
            } => {
                assert_eq!(summary, "Did the thing.");
                assert_eq!(in_progress.as_deref(), Some("- step 2"));
                assert_eq!(next_steps.as_deref(), Some("- step 3"));
                assert_eq!(tmux_window.as_deref(), Some("main:2:@7"));
                assert!(
                    git_context
                        .as_deref()
                        .is_some_and(|g| g.contains("Branch:")),
                    "git context should be present: {git_context:?}"
                );
            }
            other => panic!("expected TrustyMpm variant, got {other:?}"),
        }
    }

    #[test]
    fn write_pause_snapshot_omits_empty_sections() {
        let tmp = TempDir::new().unwrap();
        init_git_repo(tmp.path());

        let input = PauseSnapshotInput {
            session_id: "s1",
            summary: "Just a summary.",
            completed: &[],
            in_progress: &[],
            next_steps: &[],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let content = std::fs::read_to_string(&outcome.snapshot_path).unwrap();
        assert!(!content.contains("## Completed"));
        assert!(!content.contains("## In Progress"));
        assert!(!content.contains("## Next Steps"));
        assert!(!content.contains("## Tmux Window"));
        // Git Context still renders because it's a real repo.
        assert!(content.contains("## Git Context"));
    }

    #[test]
    fn write_pause_snapshot_appends_log_entry() {
        let tmp = TempDir::new().unwrap();
        init_git_repo(tmp.path());

        let input = PauseSnapshotInput {
            session_id: "s-log",
            summary: "Summary.",
            completed: &[],
            in_progress: &[],
            next_steps: &[],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let sessions_dir = tmp.path().join(".trusty-mpm").join("sessions");
        let entries = session_log::read_log(&sessions_dir);
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].session_id, "s-log");
        assert_eq!(entries[0].event, session_log::EVENT_PAUSE);
        // #5272: the log records the path relative to the store root, not a
        // bare basename, so one containment-checked join serves both layouts.
        assert_eq!(
            sessions_dir.join(&entries[0].snapshot),
            outcome.snapshot_path
        );
    }

    /// Why: #5272 — the store is partitioned by owner, and the log entry must
    /// record the path relative to the store root so resolution stays a single
    /// containment-checked join across both layouts.
    /// What: the file lands under `sessions/<session-id>/`, the log entry names
    /// `<session-id>/<basename>`, and the pair round-trips back through
    /// `resolve_session_snapshot` to the same path.
    /// Test: itself.
    #[test]
    fn write_pause_snapshot_writes_under_session_dir() {
        let tmp = TempDir::new().unwrap();
        let id = "7bd5c27a-475b-41df-9e9f-a6f630801717";
        let input = PauseSnapshotInput {
            session_id: id,
            summary: "Summary.",
            completed: &[],
            in_progress: &[],
            next_steps: &[],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let sessions_dir = tmp.path().join(".trusty-mpm").join("sessions");
        assert_eq!(
            outcome.snapshot_path.parent().unwrap(),
            sessions_dir.join(id),
            "snapshot belongs to its session's directory"
        );

        let entries = session_log::read_log(&sessions_dir);
        assert_eq!(entries.len(), 1);
        let basename = outcome.snapshot_path.file_name().unwrap().to_str().unwrap();
        assert_eq!(entries[0].snapshot, format!("{id}/{basename}"));

        assert_eq!(
            session_log::resolve_session_snapshot(&sessions_dir, id, "md").as_ref(),
            Some(&outcome.snapshot_path),
        );
        assert_eq!(
            session_log::resolve_session_snapshot(&sessions_dir, "someone-else", "md"),
            None,
        );
    }

    /// Why: #5272 — an id that cannot be a directory name is never mangled into
    /// one, because two ids collapsing onto one directory is the crosstalk this
    /// change removes. The pause still succeeds and stays attributable.
    /// What: a `/`-bearing id writes flat at the store root and resolves for
    /// itself through the log, and for no one else.
    /// Test: itself.
    #[test]
    fn write_pause_snapshot_falls_back_to_root_for_unsafe_id() {
        let tmp = TempDir::new().unwrap();
        let id = "weird/id";
        let input = PauseSnapshotInput {
            session_id: id,
            summary: "Summary.",
            completed: &[],
            in_progress: &[],
            next_steps: &[],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let sessions_dir = tmp.path().join(".trusty-mpm").join("sessions");
        assert_eq!(outcome.snapshot_path.parent().unwrap(), sessions_dir);
        assert_eq!(
            session_log::resolve_session_snapshot(&sessions_dir, id, "md").as_ref(),
            Some(&outcome.snapshot_path),
        );
        assert_eq!(
            session_log::resolve_session_snapshot(&sessions_dir, "other", "md"),
            None,
        );
    }

    /// Every 7-40 character hex token mixing digits and letters, outside the
    /// code-generated `Last commit:` line. Written independently of the
    /// production rule so a broken scrub cannot also break its own check.
    fn head_sha_tokens(md: &str) -> Vec<String> {
        md.lines()
            .filter(|line| !line.starts_with("Last commit:"))
            .flat_map(|line| line.split(|c: char| !c.is_ascii_alphanumeric()))
            .filter(|w| {
                (7..=40).contains(&w.len())
                    && w.chars().all(|c| c.is_ascii_hexdigit())
                    && w.chars().any(|c| c.is_ascii_digit())
                    && w.chars().any(|c| c.is_ascii_alphabetic())
            })
            .map(str::to_string)
            .collect()
    }

    /// Why (#9390): two of 13 relaunches resumed from snapshots carrying wrong
    /// PR head SHAs the PM had typed into the free-text sections.
    /// What: SHA-like tokens in Summary / Completed / In Progress / Next Steps
    /// are flagged, the code-generated `Last commit:` line keeps its id, and
    /// branch names, issue numbers, dates, times and hex-looking words survive.
    /// Test: itself.
    #[test]
    fn a_snapshot_contains_no_head_sha() {
        let tmp = TempDir::new().unwrap();
        init_git_repo(tmp.path());
        let head = std::process::Command::new("git")
            .arg("-C")
            .arg(tmp.path())
            .args(["log", "-1", "--format=%h"])
            .output()
            .unwrap();
        let head = String::from_utf8_lossy(&head.stdout).trim().to_string();

        let input = PauseSnapshotInput {
            session_id: "s1",
            summary: "On feat/9390-x for #9390, 2026-10-10 21:46: PR #12 head d3963848ab.",
            completed: &["added the facade; deadbeef and xdeadbeef1x are words".to_string()],
            in_progress: &[
                "PR #12 head d3963848ab awaiting CI".to_string(),
                "compare abc1234..def5678".to_string(),
            ],
            next_steps: &["merge `0123456789abcdef0123456789abcdef01234567`".to_string()],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let md = std::fs::read_to_string(&outcome.snapshot_path).unwrap();

        assert_eq!(
            head_sha_tokens(&md),
            Vec::<String>::new(),
            "no head SHA may survive outside `Last commit:`:\n{md}"
        );
        for kept in [
            "feat/9390-x",
            "#9390",
            "2026-10-10",
            "21:46",
            "PR #12",
            "added the facade",
            "deadbeef",
            "xdeadbeef1x",
        ] {
            assert!(md.contains(kept), "{kept:?} must survive:\n{md}");
        }
        assert!(md.contains("<sha?>"), "a stripped id is flagged:\n{md}");
        assert!(
            md.lines()
                .any(|l| l.starts_with(&format!("Last commit: {head} "))),
            "the #7501 baseline keeps its commit id:\n{md}"
        );
    }

    #[test]
    fn write_pause_snapshot_nonrepo_still_writes() {
        // No git init at all — capture_git_status fails-open to all-None, and
        // the snapshot must still write (no Git Context section).
        let tmp = TempDir::new().unwrap();
        let input = PauseSnapshotInput {
            session_id: "s1",
            summary: "Summary.",
            completed: &[],
            in_progress: &[],
            next_steps: &[],
            tmux_window: None,
        };
        let outcome = write_pause_snapshot(tmp.path(), &input).unwrap();
        let content = std::fs::read_to_string(&outcome.snapshot_path).unwrap();
        assert!(!content.contains("## Git Context"));
    }
}