Skip to content

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

Rust
7.3 KB
Raw Blame
//! `ai-memory read-page` — display the full body of a wiki page.
//!
//! Two resolution modes:
//! - `--path <path>`: fetch the page at that exact wiki path.
//! - positional `<query>`: FTS5 search scoped to the current project;
//!   fetches the top-ranking hit's full body.
//!
//! The project is auto-detected from the current directory (same heuristic
//! as `search`). Pass `--project` to target a different project explicitly.
//!
//! Thin HTTP client. Never opens the store or wiki directly.

use anyhow::{Result, bail};
use serde::{Deserialize, Serialize};

use crate::cli::ReadPageArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, get_json};

/// Mirrors the `ReadPageResponse` struct on the server side.
#[derive(Debug, Deserialize, Serialize)]
struct PageContent {
    path: String,
    #[serde(default)]
    workspace: String,
    #[serde(default)]
    project: String,
    title: Option<String>,
    body: String,
    frontmatter: serde_json::Value,
    /// Set by the server when the page's `expires_at` TTL has passed: the
    /// exact-path read still answers, while `search` no longer lists the page.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    expired: bool,
}

/// Run the `read-page` subcommand.
///
/// # Errors
/// Returns an error if an explicit scope flag, `--path`, or the query is empty;
/// the server is unreachable; returns non-2xx; or neither `--path` nor a query
/// is supplied.
pub async fn run(config: &Config, args: ReadPageArgs) -> Result<()> {
    super::refuse_empty_explicit(args.workspace.as_deref(), "--workspace")?;
    super::refuse_empty_explicit(args.project.as_deref(), "--project")?;
    let path = match args.path.as_deref() {
        Some(p) if p.trim().is_empty() => {
            bail!("--path was passed empty; specify the wiki page path to read");
        }
        Some(p) => Some(p),
        None => None,
    };
    let query = match args.query.as_deref() {
        Some(q) if q.trim().is_empty() => {
            bail!("search query was passed empty; specify a query or --path <wiki-path>");
        }
        Some(q) => Some(q),
        None => None,
    };
    if path.is_none() && query.is_none() {
        bail!("provide a query (positional) or --path <wiki-path>");
    }

    let (workspace, project) =
        super::resolve_scope(config, args.workspace.as_deref(), args.project.as_deref())?;
    let ep = ServerEndpoint::from_config_resolving_auth(config).await;

    let page: PageContent = if let Some(raw_path) = path {
        get_json(
            &ep,
            "/admin/read-page",
            &[
                ("workspace", workspace.as_str()),
                ("project", project.as_str()),
                ("path", raw_path),
            ],
        )
        .await?
    } else if let Some(q) = query {
        get_json(
            &ep,
            "/admin/read-page",
            &[
                ("workspace", workspace.as_str()),
                ("project", project.as_str()),
                ("q", q),
            ],
        )
        .await?
    } else {
        unreachable!();
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&page)?);
    } else {
        print!("{}", render_text(&page));
    }
    Ok(())
}

fn render_text(page: &PageContent) -> String {
    let mut out = String::new();
    if let Some(title) = &page.title {
        out.push_str(&format!("# {title}\n"));
    }
    out.push_str(&format!("path: {}\n", page.path));
    if page.expired {
        out.push_str("expired: true\n");
    }
    out.push('\n');
    out.push_str(&page.body);
    if !page.body.ends_with('\n') {
        out.push('\n');
    }
    out
}

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

    fn page(expired: bool) -> PageContent {
        PageContent {
            path: "notes/example.md".into(),
            workspace: "default".into(),
            project: "app".into(),
            title: Some("Example".into()),
            body: "body".into(),
            frontmatter: serde_json::json!({}),
            expired,
        }
    }

    #[test]
    fn text_output_marks_only_expired_pages() {
        assert_eq!(
            render_text(&page(false)),
            "# Example\npath: notes/example.md\n\nbody\n"
        );
        assert_eq!(
            render_text(&page(true)),
            "# Example\npath: notes/example.md\nexpired: true\n\nbody\n"
        );
    }

    #[test]
    fn older_server_response_defaults_to_live() {
        let parsed: PageContent = serde_json::from_value(serde_json::json!({
            "path": "notes/example.md",
            "title": null,
            "body": "body\n",
            "frontmatter": {}
        }))
        .unwrap();
        assert!(!parsed.expired);
    }

    fn args(
        path: Option<&str>,
        query: Option<&str>,
        workspace: Option<&str>,
        project: Option<&str>,
    ) -> ReadPageArgs {
        ReadPageArgs {
            query: query.map(Into::into),
            path: path.map(Into::into),
            workspace: workspace.map(Into::into),
            project: project.map(Into::into),
            json: false,
        }
    }

    #[tokio::test]
    async fn an_empty_workspace_is_refused_before_scope_or_network_work() {
        for empty in ["", " \t "] {
            let error = run(
                &Config::default(),
                args(Some("notes/example.md"), None, Some(empty), None),
            )
            .await
            .unwrap_err();
            assert!(
                error.to_string().contains("--workspace was passed empty"),
                "unexpected error: {error}"
            );
        }
    }

    #[tokio::test]
    async fn an_empty_project_is_refused_before_scope_or_network_work() {
        for empty in ["", " \t "] {
            let error = run(
                &Config::default(),
                args(Some("notes/example.md"), None, None, Some(empty)),
            )
            .await
            .unwrap_err();
            assert!(
                error.to_string().contains("--project was passed empty"),
                "unexpected error: {error}"
            );
        }
    }

    #[tokio::test]
    async fn an_empty_path_is_refused_before_scope_or_network_work() {
        for empty in ["", " \t "] {
            let error = run(&Config::default(), args(Some(empty), None, None, None))
                .await
                .unwrap_err();
            assert!(
                error.to_string().contains("--path was passed empty"),
                "unexpected error: {error}"
            );
        }
    }

    #[tokio::test]
    async fn an_empty_query_is_refused_before_scope_or_network_work() {
        for empty in ["", " \t "] {
            let error = run(&Config::default(), args(None, Some(empty), None, None))
                .await
                .unwrap_err();
            assert!(
                error.to_string().contains("search query was passed empty"),
                "unexpected error: {error}"
            );
        }
    }

    #[tokio::test]
    async fn missing_both_path_and_query_is_refused_before_scope_or_network_work() {
        let error = run(&Config::default(), args(None, None, None, None))
            .await
            .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("provide a query (positional) or --path <wiki-path>"),
            "unexpected error: {error}"
        );
    }
}