Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
41.7 KB
Raw Blame
//! `ai-memory show` project and managed-harness picker.
//!
//! Remote project metadata is joined with a client-local checkout registry.
//! The server never sends host filesystem paths, and each client may map the
//! same remote scope to a different local checkout.

use std::collections::HashMap;
use std::io::{IsTerminal as _, Write as _};
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};

use anyhow::{Context, Result, bail};
use clap::ValueEnum as _;
use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
use crossterm::style::Stylize as _;
use crossterm::{cursor, execute, terminal};
use serde::{Deserialize, Serialize};

use crate::cli::{
    InstallInstructionsArgs, InstallSkillsAgent, RunArgs, RunHarnessChoice, ShowArgs,
};
use crate::commands::{install_instructions, project_registry};
use crate::config::{Config, DEFAULT_WORKSPACE};
use crate::http_client::ServerEndpoint;

const PROJECT_MARKERS: [&str; 12] = [
    ".git",
    ".ai-memory.toml",
    "Cargo.toml",
    "package.json",
    "pyproject.toml",
    "requirements.txt",
    "go.mod",
    "Gemfile",
    "composer.json",
    "pom.xml",
    "docker-compose.yml",
    "compose.yml",
];
const SKIPPED_DIRS: [&str; 8] = [
    "node_modules",
    "target",
    "dist",
    "build",
    "vendor",
    "venv",
    ".venv",
    "__pycache__",
];
const MAX_SCAN_ENTRIES: usize = 4096;
const NEW_PROJECT_LABEL: &str = "+ New project";

#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct ProjectRow {
    /// Workspace id, when the server sent one. `Option` so an older server
    /// that predates these fields still deserializes (they are additive on
    /// the wire). (#1208)
    #[serde(default)]
    pub(crate) workspace_id: Option<String>,
    pub(crate) workspace_name: String,
    /// Project id, the ambiguous-name escape hatch an operator can pass to
    /// `--project-id` on the destructive admin commands. (#1208)
    #[serde(default)]
    pub(crate) project_id: Option<String>,
    pub(crate) project_name: String,
    pub(crate) page_count: u64,
    pub(crate) last_updated: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum CandidateSource {
    Registry,
    Scan,
}

impl CandidateSource {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Registry => "registry",
            Self::Scan => "scan",
        }
    }
}

#[derive(Debug, Clone)]
struct Candidate {
    workspace: String,
    project: String,
    path: PathBuf,
    source: CandidateSource,
    page_count: Option<u64>,
    last_updated: Option<String>,
    activity_us: Option<i64>,
}

impl Candidate {
    fn label(&self) -> String {
        terminal_text(&format!("{}/{}", self.workspace, self.project))
    }

    fn detail(&self) -> String {
        let path = terminal_text(&self.path.to_string_lossy());
        match self.page_count {
            Some(count) => format!(
                "{} | {count} page{} | {path}",
                humanize_age(self.last_updated.as_deref()),
                if count == 1 { "" } else { "s" }
            ),
            None => format!("local only | {path}"),
        }
    }
}

#[derive(Clone)]
pub(super) struct Choice {
    pub(super) label: String,
    pub(super) detail: String,
}

#[derive(Serialize)]
struct JsonProject {
    workspace: String,
    project: String,
    path: String,
    source: &'static str,
    tracked: bool,
    page_count: Option<u64>,
    last_updated: Option<String>,
}

#[derive(Serialize)]
struct JsonOutput {
    server: String,
    projects: Vec<JsonProject>,
    harnesses: Vec<String>,
}

/// Pick a local checkout and harness, then delegate to managed `run`.
pub async fn run(config: &Config, args: ShowArgs) -> Result<i32> {
    if args.json && (args.yolo || args.true_yolo || args.fresh || !args.native_args.is_empty()) {
        bail!("--json only lists launch options; do not combine it with launch arguments");
    }
    let root = std::env::current_dir()
        .context("reading the current directory")?
        .canonicalize()
        .context("canonicalizing the current directory")?;
    let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
    let candidates = collect_candidates(
        config,
        &endpoint,
        &root,
        args.workspace.as_deref(),
        !args.no_scan,
    )
    .await;
    let harnesses = available_harnesses(config);

    if args.json {
        print_json(&endpoint, &candidates, &harnesses)?;
        return Ok(0);
    }
    if !std::io::stdin().is_terminal() || !std::io::stdout().is_terminal() {
        bail!(
            "`ai-memory show` needs a terminal; use `ai-memory show --json` to list choices in scripts"
        );
    }
    if harnesses.is_empty() {
        bail!(
            "no supported managed harness was found in PATH (looked for: {})",
            RunHarnessChoice::value_variants()
                .iter()
                .map(|choice| harness_name(*choice))
                .collect::<Vec<_>>()
                .join(", ")
        );
    }

    let mut project_choices = vec![Choice {
        label: NEW_PROJECT_LABEL.to_owned(),
        detail: "create a directory and install its agent context".to_owned(),
    }];
    project_choices.extend(candidates.iter().map(|candidate| Choice {
        label: candidate.label(),
        detail: candidate.detail(),
    }));
    let Some(project_index) = select("Project", &mut project_choices)? else {
        return Ok(0);
    };
    let new_project = if project_index == 0 {
        let Some(name) = prompt_project_name(&root)? else {
            return Ok(0);
        };
        Some(name)
    } else {
        None
    };

    let mut harness_choices = harnesses
        .iter()
        .map(|choice| Choice {
            label: harness_name(*choice),
            detail: String::new(),
        })
        .collect::<Vec<_>>();
    let project_label = new_project
        .as_deref()
        .map(terminal_text)
        .unwrap_or_else(|| project_choices[project_index].label.clone());
    let Some(harness_index) = select(&format!("Agent | {project_label}"), &mut harness_choices)?
    else {
        return Ok(0);
    };
    let harness = harnesses[harness_index];

    let (target, workspace, project) = if let Some(name) = new_project {
        let workspace = args.workspace.as_deref().unwrap_or(DEFAULT_WORKSPACE);
        let target = create_project(&root, &name, workspace, harness, &config.runtime_env)?;
        (target, workspace.to_owned(), name)
    } else {
        let candidate = &candidates[project_index - 1];
        let target = revalidate_candidate(config, candidate)?;
        (
            target,
            candidate.workspace.clone(),
            candidate.project.clone(),
        )
    };

    crate::commands::run::run_from(
        config,
        RunArgs {
            project_id: None,
            workspace: Some(workspace),
            project: Some(project),
            workstream: None,
            new_workstream: None,
            executable: None,
            yolo: args.yolo,
            true_yolo: args.true_yolo,
            jail: None,
            no_jail: false,
            fresh: args.fresh,
            force_unlock: false,
            no_autowire: false,
            no_exit_prompt: false,
            require_server: false,
            profile: None,
            env: Vec::new(),
            env_file: None,
            harness: Some(harness),
            claude_wrapper: None,
            native_args: args.native_args,
        },
        &target,
    )
    .await
}

async fn collect_candidates(
    config: &Config,
    endpoint: &ServerEndpoint,
    root: &Path,
    workspace_filter: Option<&str>,
    scan: bool,
) -> Vec<Candidate> {
    let rows: Option<Vec<ProjectRow>> = match crate::commands::list_projects::fetch_project_rows(
        endpoint,
        workspace_filter,
    )
    .await
    {
        Ok(rows) => Some(rows),
        Err(error) => {
            eprintln!(
                "ai-memory: server project listing unavailable ({}); using client-local links and scan results",
                terminal_text(&format!("{error:#}"))
            );
            None
        }
    };
    let stats = rows.as_ref().map(|rows| {
        rows.iter()
            .cloned()
            .map(|row| ((row.workspace_name.clone(), row.project_name.clone()), row))
            .collect::<HashMap<_, _>>()
    });

    let links = match project_registry::links_for_server(config, endpoint) {
        Ok(links) => links,
        Err(error) => {
            eprintln!(
                "ai-memory: client project registry unavailable ({}); using scan results",
                terminal_text(&format!("{error:#}"))
            );
            Vec::new()
        }
    };
    let mut candidates = Vec::new();
    let mut stale_warnings = 0usize;
    for link in links {
        if workspace_filter.is_some_and(|filter| filter != link.workspace) {
            continue;
        }
        let key = (link.workspace.clone(), link.project.clone());
        if stats
            .as_ref()
            .is_some_and(|known| !known.contains_key(&key))
        {
            continue;
        }
        let path = match validate_registered_path(&link.path) {
            Ok(path) => path,
            Err(error) => {
                if stale_warnings < 3 {
                    eprintln!(
                        "ai-memory: ignored stale client project link {}/{} ({})",
                        terminal_text(&link.workspace),
                        terminal_text(&link.project),
                        terminal_text(&format!("{error:#}"))
                    );
                }
                stale_warnings += 1;
                continue;
            }
        };
        let row = stats.as_ref().and_then(|known| known.get(&key));
        push_candidate(
            &mut candidates,
            candidate_from(
                path,
                link.workspace,
                link.project,
                CandidateSource::Registry,
                row,
                Some(&link.linked_at),
            ),
        );
    }
    if stale_warnings > 3 {
        eprintln!(
            "ai-memory: ignored {} additional stale client project links",
            stale_warnings - 3
        );
    }

    if scan {
        for path in scan_for_projects(root) {
            let Ok((workspace, project)) = super::resolve_scope_for_path(config, &path) else {
                continue;
            };
            if workspace_filter.is_some_and(|filter| filter != workspace) {
                continue;
            }
            let key = (workspace.clone(), project.clone());
            let row = stats.as_ref().and_then(|known| known.get(&key));
            push_candidate(
                &mut candidates,
                candidate_from(path, workspace, project, CandidateSource::Scan, row, None),
            );
        }
    }
    candidates.sort_by(|left, right| {
        right
            .activity_us
            .cmp(&left.activity_us)
            .then_with(|| left.workspace.cmp(&right.workspace))
            .then_with(|| left.project.cmp(&right.project))
            .then_with(|| left.path.cmp(&right.path))
    });
    candidates
}

fn candidate_from(
    path: PathBuf,
    workspace: String,
    project: String,
    source: CandidateSource,
    row: Option<&ProjectRow>,
    local_activity: Option<&str>,
) -> Candidate {
    Candidate {
        workspace,
        project,
        activity_us: row
            .and_then(|row| timestamp_us(row.last_updated.as_deref()))
            .or_else(|| timestamp_us(local_activity))
            .or_else(|| directory_modified_us(&path)),
        page_count: row.map(|row| row.page_count),
        last_updated: row.and_then(|row| row.last_updated.clone()),
        path,
        source,
    }
}

fn push_candidate(candidates: &mut Vec<Candidate>, candidate: Candidate) {
    if let Some(existing) = candidates
        .iter_mut()
        .find(|existing| existing.path == candidate.path)
    {
        if existing.page_count.is_none() && candidate.page_count.is_some() {
            existing.page_count = candidate.page_count;
            existing.last_updated = candidate.last_updated;
            existing.activity_us = candidate.activity_us;
        }
        return;
    }
    candidates.push(candidate);
}

fn print_json(
    endpoint: &ServerEndpoint,
    candidates: &[Candidate],
    harnesses: &[RunHarnessChoice],
) -> Result<()> {
    let output = JsonOutput {
        server: endpoint.identity(),
        projects: candidates
            .iter()
            .map(|candidate| JsonProject {
                workspace: candidate.workspace.clone(),
                project: candidate.project.clone(),
                path: candidate.path.to_string_lossy().into_owned(),
                source: candidate.source.as_str(),
                tracked: candidate.page_count.is_some(),
                page_count: candidate.page_count,
                last_updated: candidate.last_updated.clone(),
            })
            .collect(),
        harnesses: harnesses
            .iter()
            .map(|choice| harness_name(*choice))
            .collect(),
    };
    let stdout = std::io::stdout();
    let mut out = stdout.lock();
    serde_json::to_writer_pretty(&mut out, &output).context("rendering project list JSON")?;
    writeln!(out)?;
    Ok(())
}

pub(super) fn available_harnesses(config: &Config) -> Vec<RunHarnessChoice> {
    let child_env = crate::commands::run::EffectiveChildEnv::from_runtime(&config.runtime_env);
    let search = child_env.executable_search();
    RunHarnessChoice::value_variants()
        .iter()
        .copied()
        .filter(|choice| crate::commands::run::harness_available(*choice, search))
        .collect()
}

/// Re-check a stored checkout path immediately before it is used.
///
/// The canonical-equality check is the load-bearing one: it rejects a
/// recorded directory that has since been replaced by a symlink pointing
/// somewhere else, before any harness is launched inside it.
pub(super) fn validate_registered_path(path: &Path) -> Result<PathBuf> {
    if !path.is_absolute() {
        bail!("stored checkout path is not absolute");
    }
    let canonical = path
        .canonicalize()
        .with_context(|| format!("checkout {} no longer resolves", path.display()))?;
    if canonical != path {
        bail!("checkout path now resolves somewhere else");
    }
    if !canonical.is_dir() {
        bail!("checkout path is not a directory");
    }
    Ok(canonical)
}

fn revalidate_candidate(config: &Config, candidate: &Candidate) -> Result<PathBuf> {
    let path = validate_registered_path(&candidate.path)?;
    let (workspace, project) = super::resolve_scope_for_path(config, &path)?;
    if workspace != candidate.workspace || project != candidate.project {
        bail!(
            "checkout scope changed after it was listed: expected {}/{}, found {}/{}; rerun `ai-memory show`",
            terminal_text(&candidate.workspace),
            terminal_text(&candidate.project),
            terminal_text(&workspace),
            terminal_text(&project)
        );
    }
    Ok(path)
}

fn scan_for_projects(root: &Path) -> Vec<PathBuf> {
    let mut found = Vec::new();
    if is_project_dir(root) {
        found.push(root.to_path_buf());
    }
    let Ok(entries) = std::fs::read_dir(root) else {
        return found;
    };
    for entry in entries.take(MAX_SCAN_ENTRIES).flatten() {
        let path = entry.path();
        let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
            continue;
        };
        if name.starts_with('.') || SKIPPED_DIRS.contains(&name) {
            continue;
        }
        if entry.file_type().is_ok_and(|kind| kind.is_dir())
            && is_project_dir(&path)
            && let Ok(canonical) = path.canonicalize()
        {
            found.push(canonical);
        }
    }
    found.sort_by(|left, right| {
        directory_modified_us(right)
            .cmp(&directory_modified_us(left))
            .then_with(|| left.cmp(right))
    });
    found
}

fn is_project_dir(path: &Path) -> bool {
    PROJECT_MARKERS
        .iter()
        .any(|marker| path.join(marker).exists())
}

fn directory_modified_us(path: &Path) -> Option<i64> {
    std::fs::metadata(path)
        .and_then(|metadata| metadata.modified())
        .ok()
        .and_then(system_time_us)
}

fn system_time_us(time: SystemTime) -> Option<i64> {
    let micros = time.duration_since(UNIX_EPOCH).ok()?.as_micros();
    i64::try_from(micros).ok()
}

fn timestamp_us(raw: Option<&str>) -> Option<i64> {
    raw?.parse::<jiff::Timestamp>()
        .ok()
        .map(|ts| ts.as_microsecond())
}

fn portable_component(value: &str) -> bool {
    let mut chars = value.chars();
    let Some(first) = chars.next() else {
        return false;
    };
    (first.is_ascii_lowercase() || first.is_ascii_digit())
        && chars.all(|character| {
            character.is_ascii_lowercase()
                || character.is_ascii_digit()
                || matches!(character, '.' | '-' | '_')
        })
}

fn marker_body(workspace: &str, project: &str) -> String {
    let mut document = toml_edit::DocumentMut::new();
    document["workspace"] = toml_edit::value(workspace);
    document["project"] = toml_edit::value(project);
    format!(
        "# Created by `ai-memory show`. Both scope names are pinned so moving\n\
         # into a subdirectory or renaming this checkout does not fork memory.\n\
         {document}"
    )
}

fn create_project(
    parent: &Path,
    name: &str,
    workspace: &str,
    harness: RunHarnessChoice,
    env: &crate::config::RuntimeEnv,
) -> Result<PathBuf> {
    create_project_with_initializer(parent, name, workspace, |staging| {
        install_context_files(harness, staging, env)
    })
}

fn create_project_with_initializer(
    parent: &Path,
    name: &str,
    workspace: &str,
    initialize: impl FnOnce(&Path) -> Result<()>,
) -> Result<PathBuf> {
    if !portable_component(name) {
        bail!(
            "invalid project name {name:?}: use lowercase ASCII letters, digits, dot, dash, or underscore, starting with a letter or digit"
        );
    }
    let target = parent.join(name);
    if target.exists() {
        bail!("project directory already exists: {}", target.display());
    }
    let staging = tempfile::Builder::new()
        .prefix(".ai-memory-project-")
        .tempdir_in(parent)
        .with_context(|| format!("creating a staging directory in {}", parent.display()))?;
    ai_memory_wiki::write_atomic(
        &staging.path().join(".ai-memory.toml"),
        marker_body(workspace, name).as_bytes(),
    )
    .context("writing the staged project marker")?;
    initialize(staging.path())?;
    if target.exists() {
        bail!(
            "project directory appeared while it was being prepared: {}",
            target.display()
        );
    }
    std::fs::rename(staging.path(), &target)
        .with_context(|| format!("publishing new project {}", target.display()))?;
    let target = target
        .canonicalize()
        .with_context(|| format!("canonicalizing new project {}", target.display()))?;
    println!("created {}", target.display());
    Ok(target)
}

fn install_context_files(
    harness: RunHarnessChoice,
    path: &Path,
    env: &crate::config::RuntimeEnv,
) -> Result<()> {
    let (instruction, agent, skill_root) = match harness {
        RunHarnessChoice::Claude => (
            "CLAUDE.md",
            InstallSkillsAgent::ClaudeCode,
            path.join(".claude/skills"),
        ),
        _ => (
            "AGENTS.md",
            InstallSkillsAgent::Agents,
            path.join(".agents/skills"),
        ),
    };
    install_instructions::run_quiet(
        InstallInstructionsArgs {
            target: Some(path.join(instruction)),
            print: false,
            no_skills: false,
            compact: false,
            skills_scope: None,
            skills_agent: Some(agent),
            skills_target_dir: Some(skill_root),
            skills_force: false,
        },
        env,
    )
}

fn humanize_age(timestamp: Option<&str>) -> String {
    let Some(raw) = timestamp else {
        return "no pages yet".to_owned();
    };
    let Ok(then) = raw.parse::<jiff::Timestamp>() else {
        return "unknown activity".to_owned();
    };
    super::humanize_age_secs((jiff::Timestamp::now() - then).get_seconds())
}

pub(super) fn harness_name(harness: RunHarnessChoice) -> String {
    harness
        .to_possible_value()
        .map_or_else(|| "unknown".to_owned(), |value| value.get_name().to_owned())
}

pub(super) fn terminal_text(text: &str) -> String {
    text.chars()
        .map(|character| {
            if character.is_control() {
                '?'
            } else {
                character
            }
        })
        .collect()
}

struct TerminalGuard;

impl Drop for TerminalGuard {
    fn drop(&mut self) {
        let _ = terminal::disable_raw_mode();
        let _ = execute!(std::io::stdout(), cursor::Show);
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum HorizontalDirection {
    Left,
    Right,
}

type HorizontalHandler<'a> = &'a mut dyn FnMut(usize, HorizontalDirection, &mut Choice);

pub(super) fn select(title: &str, choices: &mut [Choice]) -> Result<Option<usize>> {
    select_inner(title, choices, None, None, None)
}

pub(super) fn select_with_horizontal(
    title: &str,
    choices: &mut [Choice],
    horizontal_hint: &str,
    initial_search: Option<&str>,
    on_horizontal: &mut dyn FnMut(usize, HorizontalDirection, &mut Choice),
) -> Result<Option<usize>> {
    select_inner(
        title,
        choices,
        Some(horizontal_hint),
        Some(on_horizontal),
        Some(initial_search.unwrap_or_default()),
    )
}

#[derive(Default)]
struct PickerSearch {
    query: String,
}

impl PickerSearch {
    fn indices(&self, choices: &[Choice]) -> Vec<usize> {
        let query = self.query.to_lowercase();
        choices
            .iter()
            .enumerate()
            .filter_map(|(index, choice)| {
                choice
                    .label
                    .to_lowercase()
                    .contains(&query)
                    .then_some(index)
            })
            .collect()
    }

    fn handle_key(&mut self, code: KeyCode, modifiers: KeyModifiers) -> bool {
        match code {
            KeyCode::Esc if !self.query.is_empty() => self.query.clear(),
            KeyCode::Backspace => {
                self.query.pop();
            }
            KeyCode::Char('u') if modifiers.contains(KeyModifiers::CONTROL) => self.query.clear(),
            KeyCode::Char(character)
                if !character.is_control()
                    && !modifiers.intersects(KeyModifiers::CONTROL | KeyModifiers::ALT) =>
            {
                self.query.push(character)
            }
            _ => return false,
        }
        true
    }
}

fn select_inner(
    title: &str,
    choices: &mut [Choice],
    horizontal_hint: Option<&str>,
    mut on_horizontal: Option<HorizontalHandler<'_>>,
    initial_search: Option<&str>,
) -> Result<Option<usize>> {
    if choices.is_empty() {
        bail!("nothing to choose from");
    }
    terminal::enable_raw_mode().context("entering raw mode")?;
    let _guard = TerminalGuard;
    execute!(std::io::stdout(), cursor::Hide)?;
    while event::poll(std::time::Duration::from_millis(0))? {
        let _ = event::read()?;
    }

    let mut selected = 0usize;
    let mut offset = 0usize;
    let mut drawn = 0u16;
    let mut search = PickerSearch {
        query: initial_search.unwrap_or_default().to_owned(),
    };
    loop {
        let indices = search.indices(choices);
        let visible = if indices.is_empty() {
            vec![Choice {
                label: "No matching workstreams — edit the search or press Esc to clear".into(),
                detail: String::new(),
            }]
        } else {
            indices
                .iter()
                .map(|index| choices[*index].clone())
                .collect::<Vec<_>>()
        };
        selected = selected.min(visible.len() - 1);
        let title = if initial_search.is_some() {
            format!(
                "{title} [{}/{}] | search: {}",
                indices.len(),
                choices.len(),
                search.query
            )
        } else {
            title.to_owned()
        };
        drawn = draw(
            &title,
            &visible,
            selected,
            &mut offset,
            drawn,
            horizontal_hint,
            initial_search.is_some(),
        )?;
        let Event::Key(KeyEvent {
            code,
            modifiers,
            kind: KeyEventKind::Press,
            ..
        }) = event::read()?
        else {
            continue;
        };
        if initial_search.is_some() {
            let previous_query = search.query.clone();
            if search.handle_key(code, modifiers) {
                if search.query != previous_query {
                    selected = 0;
                    offset = 0;
                }
                continue;
            }
        }
        // The resume picker reserves every printable character for search,
        // including the other pickers' j/k/q shortcuts. Ctrl-C still cancels.
        if initial_search.is_some()
            && matches!(code, KeyCode::Char(_))
            && !(code == KeyCode::Char('c') && modifiers.contains(KeyModifiers::CONTROL))
        {
            continue;
        }
        if let Some(direction) = horizontal_direction(&code) {
            if let Some(callback) = on_horizontal.as_mut()
                && let Some(&index) = indices.get(selected)
            {
                callback(index, direction, &mut choices[index]);
            }
            continue;
        }
        match code {
            KeyCode::Up | KeyCode::Char('k') => {
                selected = selected.checked_sub(1).unwrap_or(visible.len() - 1);
            }
            KeyCode::Down | KeyCode::Char('j') => selected = (selected + 1) % visible.len(),
            KeyCode::Home => selected = 0,
            KeyCode::End => selected = visible.len() - 1,
            KeyCode::PageUp => selected = selected.saturating_sub(viewport_rows()),
            KeyCode::PageDown => {
                selected = (selected + viewport_rows()).min(visible.len() - 1);
            }
            KeyCode::Enter => {
                if let Some(&index) = indices.get(selected) {
                    clear(drawn)?;
                    return Ok(Some(index));
                }
            }
            KeyCode::Esc | KeyCode::Char('q') => {
                clear(drawn)?;
                return Ok(None);
            }
            KeyCode::Char('c') if modifiers.contains(KeyModifiers::CONTROL) => {
                clear(drawn)?;
                return Ok(None);
            }
            _ => {}
        }
    }
}

fn horizontal_direction(code: &KeyCode) -> Option<HorizontalDirection> {
    match code {
        KeyCode::Left => Some(HorizontalDirection::Left),
        KeyCode::Right => Some(HorizontalDirection::Right),
        _ => None,
    }
}

fn prompt_project_name(parent: &Path) -> Result<Option<String>> {
    terminal::enable_raw_mode().context("entering raw mode")?;
    let _guard = TerminalGuard;
    execute!(std::io::stdout(), cursor::Hide)?;
    while event::poll(std::time::Duration::from_millis(0))? {
        let _ = event::read()?;
    }

    let mut name = String::new();
    let mut problem = None;
    let mut drawn = 0u16;
    loop {
        drawn = draw_prompt("New project name", &name, problem.as_deref(), drawn)?;
        let Event::Key(KeyEvent {
            code,
            modifiers,
            kind: KeyEventKind::Press,
            ..
        }) = event::read()?
        else {
            continue;
        };
        match code {
            KeyCode::Char('c') if modifiers.contains(KeyModifiers::CONTROL) => {
                clear(drawn)?;
                return Ok(None);
            }
            KeyCode::Esc => {
                clear(drawn)?;
                return Ok(None);
            }
            KeyCode::Backspace => {
                name.pop();
                problem = None;
            }
            KeyCode::Enter => {
                problem = rejection(parent, &name);
                if problem.is_none() {
                    clear(drawn)?;
                    return Ok(Some(name));
                }
            }
            KeyCode::Char(character) if !modifiers.contains(KeyModifiers::CONTROL) => {
                name.push(character);
                problem = None;
            }
            _ => {}
        }
    }
}

fn rejection(parent: &Path, name: &str) -> Option<String> {
    if name.is_empty() {
        return Some("type a name".to_owned());
    }
    if !portable_component(name) {
        return Some("use lowercase letters, digits, dot, dash, or underscore".to_owned());
    }
    if parent.join(name).exists() {
        return Some(format!("{name} already exists here"));
    }
    None
}

fn draw_prompt(title: &str, name: &str, problem: Option<&str>, previous: u16) -> Result<u16> {
    let (columns, _) = terminal::size().unwrap_or((80, 24));
    let width = usize::from(columns.max(20)).saturating_sub(1);
    let mut out = std::io::stdout();
    if previous > 0 {
        execute!(out, cursor::MoveUp(previous))?;
    }
    write!(out, "\r")?;
    execute!(out, terminal::Clear(terminal::ClearType::FromCursorDown))?;
    write!(
        out,
        "  {}\r\n",
        truncate(&terminal_text(title), width).green().bold()
    )?;
    write!(
        out,
        "  > {}{}\r\n",
        truncate(&terminal_text(name), width.saturating_sub(5))
            .as_str()
            .bold(),
        "|".green()
    )?;
    let footer = problem
        .map(|problem| format!("  {}", terminal_text(problem)))
        .unwrap_or_else(|| "  enter create | esc cancel".to_owned());
    let footer = truncate(&footer, width);
    if problem.is_some() {
        write!(out, "{}\r\n", footer.as_str().red())?;
    } else {
        write!(out, "{}\r\n", footer.as_str().dark_grey())?;
    }
    out.flush()?;
    Ok(3)
}

fn viewport_rows() -> usize {
    let (_, rows) = terminal::size().unwrap_or((80, 24));
    usize::from(rows).saturating_sub(3).max(3)
}

fn scroll_offset(selected: usize, total: usize, viewport: usize, current: usize) -> usize {
    let mut offset = current;
    if selected < offset {
        offset = selected;
    } else if selected >= offset + viewport {
        offset = selected + 1 - viewport;
    }
    offset.min(total.saturating_sub(viewport))
}

fn truncate(text: &str, width: usize) -> String {
    if width == 0 {
        return String::new();
    }
    if text.chars().count() <= width {
        return text.to_owned();
    }
    let mut output = text
        .chars()
        .take(width.saturating_sub(1))
        .collect::<String>();
    output.push('…');
    output
}

fn draw(
    title: &str,
    choices: &[Choice],
    selected: usize,
    offset: &mut usize,
    previous: u16,
    horizontal_hint: Option<&str>,
    searchable: bool,
) -> Result<u16> {
    let (columns, _) = terminal::size().unwrap_or((80, 24));
    let width = usize::from(columns.max(20)).saturating_sub(1);
    let viewport = viewport_rows().min(choices.len());
    *offset = scroll_offset(selected, choices.len(), viewport, *offset);

    let mut out = std::io::stdout();
    if previous > 0 {
        execute!(out, cursor::MoveUp(previous))?;
    }
    write!(out, "\r")?;
    execute!(out, terminal::Clear(terminal::ClearType::FromCursorDown))?;
    write!(
        out,
        "  {}\r\n",
        truncate(&terminal_text(title), width).green().bold()
    )?;
    for (index, choice) in choices.iter().enumerate().skip(*offset).take(viewport) {
        let marker = if index == selected { "  > " } else { "    " };
        let label = truncate(
            &terminal_text(&choice.label),
            width.saturating_sub(marker.len()),
        );
        let used = marker.len() + label.chars().count();
        if index == selected {
            write!(
                out,
                "{}{}",
                marker.green().bold(),
                label.as_str().green().bold()
            )?;
        } else {
            write!(out, "{marker}{}", label.as_str().reset())?;
        }
        if !choice.detail.is_empty() && used + 2 < width {
            let detail = truncate(&terminal_text(&choice.detail), width - used - 2);
            write!(out, "  {}", detail.as_str().dark_grey())?;
        }
        write!(out, "\r\n")?;
    }
    let horizontal_hint = horizontal_hint
        .map(|hint| format!(" | {hint}"))
        .unwrap_or_default();
    let hint = if searchable {
        "  type to search | ↑↓ move | ←→ harness | enter select | esc clear/cancel".to_owned()
    } else if choices.len() > viewport {
        format!(
            "  up/down move{horizontal_hint} | pgup/pgdn page | enter select | esc cancel [{}/{}]",
            selected + 1,
            choices.len()
        )
    } else {
        format!("  up/down move{horizontal_hint} | enter select | esc cancel")
    };
    write!(out, "{}\r\n", truncate(&hint, width).dark_grey())?;
    out.flush()?;
    Ok(u16::try_from(viewport)
        .unwrap_or(u16::MAX)
        .saturating_add(2))
}

fn clear(drawn: u16) -> Result<()> {
    let mut out = std::io::stdout();
    if drawn > 0 {
        execute!(out, cursor::MoveUp(drawn))?;
    }
    execute!(out, terminal::Clear(terminal::ClearType::FromCursorDown))?;
    out.flush()?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn search_matches_names_case_insensitively_and_keeps_original_indices() {
        let choices = ["one", "Fix CHECKOUT", "three", "checkout search"].map(|label| Choice {
            label: label.into(),
            detail: "unrelated detail".into(),
        });
        let mut search = PickerSearch {
            query: "checkout".into(),
        };
        assert_eq!(search.indices(&choices), [1, 3]);
        search.query = "missing".into();
        assert!(search.indices(&choices).is_empty());
        search.query.clear();
        assert_eq!(search.indices(&choices), [0, 1, 2, 3]);
    }

    #[test]
    fn typing_searches_immediately_including_navigation_letters() {
        let mut search = PickerSearch::default();
        for character in "qjké".chars() {
            assert!(search.handle_key(KeyCode::Char(character), KeyModifiers::NONE));
        }
        assert_eq!(search.query, "qjké");
        assert!(search.handle_key(KeyCode::Backspace, KeyModifiers::NONE));
        assert_eq!(search.query, "qjk");
        assert!(search.handle_key(KeyCode::Char('u'), KeyModifiers::CONTROL));
        assert!(search.query.is_empty());
        assert!(search.handle_key(KeyCode::Char('q'), KeyModifiers::NONE));
        assert!(!search.handle_key(KeyCode::Enter, KeyModifiers::NONE));
        assert_eq!(search.query, "q");
        assert!(search.handle_key(KeyCode::Esc, KeyModifiers::NONE));
        assert!(search.query.is_empty());
        assert!(!search.handle_key(KeyCode::Esc, KeyModifiers::NONE));
    }

    #[test]
    fn search_does_not_consume_selection_arrows_or_cancel_shortcuts() {
        let mut search = PickerSearch {
            query: "auth".into(),
        };
        for code in [
            KeyCode::Up,
            KeyCode::Down,
            KeyCode::Left,
            KeyCode::Right,
            KeyCode::Home,
            KeyCode::End,
            KeyCode::PageUp,
            KeyCode::PageDown,
            KeyCode::Enter,
        ] {
            assert!(!search.handle_key(code, KeyModifiers::NONE));
        }
        assert!(!search.handle_key(KeyCode::Char('c'), KeyModifiers::CONTROL));
        assert!(!search.handle_key(KeyCode::Char('q'), KeyModifiers::ALT));
        assert_eq!(search.query, "auth");
        assert!(search.handle_key(KeyCode::Char('/'), KeyModifiers::NONE));
        assert_eq!(search.query, "auth/");
    }

    fn config_at(path: &Path) -> Config {
        Config {
            data_dir: path.to_path_buf(),
            ..Config::default()
        }
    }

    fn make_project(root: &Path, name: &str, marker: &str) -> PathBuf {
        let path = root.join(name);
        std::fs::create_dir_all(&path).unwrap();
        std::fs::write(path.join(marker), b"").unwrap();
        path.canonicalize().unwrap()
    }

    #[test]
    fn terminal_text_removes_control_sequences() {
        assert_eq!(terminal_text("safe\n\u{1b}[31mname\r"), "safe??[31mname?");
    }

    #[test]
    fn invalid_server_timestamp_is_not_echoed_to_the_terminal() {
        assert_eq!(humanize_age(Some("\u{1b}[31m")), "unknown activity");
    }

    #[test]
    fn registry_activity_orders_projects_when_server_metadata_is_unavailable() {
        let timestamp = "2026-08-01T12:00:00Z";
        let candidate = candidate_from(
            PathBuf::from("/missing-is-fine-for-this-pure-test"),
            "default".to_owned(),
            "app".to_owned(),
            CandidateSource::Registry,
            None,
            Some(timestamp),
        );

        assert_eq!(candidate.activity_us, timestamp_us(Some(timestamp)));
    }

    #[test]
    fn portable_project_components_reject_injection_and_traversal() {
        for valid in ["ai-memory", "app2", "my_project", "web.api"] {
            assert!(portable_component(valid));
        }
        for invalid in ["", "../other", "Upper", "with space", "x\nproject", "x\""] {
            assert!(!portable_component(invalid));
        }
    }

    #[test]
    fn scan_is_depth_one_and_skips_build_directories() {
        let tmp = tempfile::TempDir::new().unwrap();
        let project = make_project(tmp.path(), "app", "Cargo.toml");
        let nested = tmp.path().join("plain/nested");
        std::fs::create_dir_all(&nested).unwrap();
        std::fs::write(nested.join("go.mod"), b"").unwrap();
        make_project(tmp.path(), "target", "Cargo.toml");

        assert_eq!(scan_for_projects(tmp.path()), vec![project]);
    }

    #[test]
    fn failed_project_initialization_rolls_back_the_staging_directory() {
        let tmp = tempfile::TempDir::new().unwrap();
        let result = create_project_with_initializer(tmp.path(), "app", "default", |_path| {
            bail!("synthetic failure")
        });

        assert!(result.is_err());
        assert!(!tmp.path().join("app").exists());
        assert!(std::fs::read_dir(tmp.path()).unwrap().all(|entry| {
            !entry
                .unwrap()
                .file_name()
                .to_string_lossy()
                .starts_with(".ai-memory-project-")
        }));
    }

    #[test]
    fn created_project_is_published_only_after_initialization() {
        let tmp = tempfile::TempDir::new().unwrap();
        let path = create_project_with_initializer(tmp.path(), "app", "default", |staging| {
            assert!(!tmp.path().join("app").exists());
            std::fs::write(staging.join("AGENTS.md"), b"ready")?;
            Ok(())
        })
        .unwrap();

        assert_eq!(std::fs::read(path.join("AGENTS.md")).unwrap(), b"ready");
        let marker = std::fs::read_to_string(path.join(".ai-memory.toml")).unwrap();
        assert!(marker.contains("workspace = \"default\""));
        assert!(marker.contains("project = \"app\""));
    }

    #[test]
    fn marker_encoding_preserves_an_existing_nonportable_workspace_name() {
        let tmp = tempfile::TempDir::new().unwrap();
        let path =
            create_project_with_initializer(tmp.path(), "app", "Team \"One\"", |_staging| Ok(()))
                .unwrap();

        let marker = std::fs::read_to_string(path.join(".ai-memory.toml")).unwrap();
        let document = marker.parse::<toml_edit::DocumentMut>().unwrap();
        assert_eq!(document["workspace"].as_str(), Some("Team \"One\""));
    }

    #[test]
    fn candidate_is_rejected_when_its_scope_changes_after_listing() {
        let tmp = tempfile::TempDir::new().unwrap();
        let path = make_project(tmp.path(), "app", ".ai-memory.toml");
        std::fs::write(
            path.join(".ai-memory.toml"),
            b"workspace = \"one\"\nproject = \"app\"\n",
        )
        .unwrap();
        let candidate = Candidate {
            workspace: "one".to_owned(),
            project: "app".to_owned(),
            path: path.clone(),
            source: CandidateSource::Scan,
            page_count: None,
            last_updated: None,
            activity_us: None,
        };
        std::fs::write(
            path.join(".ai-memory.toml"),
            b"workspace = \"two\"\nproject = \"app\"\n",
        )
        .unwrap();

        assert!(revalidate_candidate(&config_at(tmp.path()), &candidate).is_err());
    }

    #[cfg(unix)]
    #[test]
    fn registered_path_rejects_a_checkout_replaced_by_a_symlink() {
        use std::os::unix::fs::symlink;

        let tmp = tempfile::TempDir::new().unwrap();
        let checkout = tmp.path().join("checkout");
        let other = tmp.path().join("other");
        std::fs::create_dir(&checkout).unwrap();
        std::fs::create_dir(&other).unwrap();
        let stored = checkout.canonicalize().unwrap();
        std::fs::remove_dir(&checkout).unwrap();
        symlink(&other, &checkout).unwrap();

        assert!(validate_registered_path(&stored).is_err());
    }

    #[test]
    fn scroll_and_truncation_stay_inside_the_viewport() {
        assert_eq!(scroll_offset(5, 24, 5, 0), 1);
        assert_eq!(scroll_offset(23, 24, 5, 22), 19);
        for width in 0..12 {
            assert!(
                truncate("a considerably longer label", width)
                    .chars()
                    .count()
                    <= width
            );
        }
    }

    #[test]
    fn harness_names_cover_every_parser_variant() {
        for harness in RunHarnessChoice::value_variants() {
            assert_ne!(harness_name(*harness), "unknown");
        }
    }

    #[test]
    fn horizontal_arrow_keys_map_to_picker_directions() {
        assert_eq!(
            horizontal_direction(&KeyCode::Left),
            Some(HorizontalDirection::Left)
        );
        assert_eq!(
            horizontal_direction(&KeyCode::Right),
            Some(HorizontalDirection::Right)
        );
        assert_eq!(horizontal_direction(&KeyCode::Up), None);
    }
}