Skip to content

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

Rust
5.9 KB
Raw Blame
//! `ai-memory write-page` — write or update a wiki page via the server.
//!
//! Sends a `POST /admin/write-page` request to the running server.
//! The server handles workspace/project resolution, tier parsing,
//! frontmatter framing, and the atomic wiki write.

use std::io::Read;

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

use crate::cli::WritePageArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, post_json};

#[derive(Serialize)]
struct WritePageBody {
    workspace: String,
    project: String,
    path: String,
    body: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    title: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    kind: Option<String>,
    tier: String,
    tags: Vec<String>,
    pinned: bool,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    applies_to: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    enforced_by: Option<String>,
}

#[derive(Deserialize)]
struct WritePageResponseBody {
    page_id: String,
    path: String,
    #[serde(default)]
    manifest_warning: Option<String>,
}

/// Run the `write-page` subcommand.
///
/// # Errors
/// Returns an error if an explicit scope flag is empty, `--path` is empty,
/// stdin cannot be read (when `body == "-"`), or if the POST to
/// `/admin/write-page` fails.
pub async fn run(config: &Config, args: WritePageArgs) -> Result<()> {
    super::refuse_empty_explicit(args.workspace.as_deref(), "--workspace")?;
    super::refuse_empty_explicit(args.project.as_deref(), "--project")?;
    if args.path.trim().is_empty() {
        bail!("--path was passed empty; specify the wiki page path to write");
    }

    let body_text = if args.body == "-" {
        let mut buf = String::new();
        std::io::stdin()
            .read_to_string(&mut buf)
            .context("reading body from stdin")?;
        buf
    } else {
        args.body
    };

    // Resolve the project the same way read-page/search do: explicit flag wins,
    // otherwise derive the current project from host cwd / repo root. This keeps
    // write + read-back pairs from silently targeting different projects.
    let (workspace, project) =
        super::resolve_scope(config, args.workspace.as_deref(), args.project.as_deref())?;

    let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
    let resp: WritePageResponseBody = post_json(
        &endpoint,
        "/admin/write-page",
        &WritePageBody {
            workspace: workspace.clone(),
            project: project.clone(),
            path: args.path.clone(),
            body: body_text,
            title: args.title,
            kind: args.kind,
            tier: args.tier,
            tags: args.tag,
            pinned: args.pinned,
            applies_to: args.applies_to,
            enforced_by: args.enforced_by,
        },
    )
    .await
    .context("writing page via server")?;

    if let Some(warning) = resp.manifest_warning.as_deref() {
        eprintln!("ai-memory: warning: {warning}");
    }
    println!(
        "✓ wrote {} (page_id={}) under {}/{}",
        resp.path,
        short_page_id(&resp.page_id),
        workspace,
        project
    );
    Ok(())
}

/// The last eight characters of a page id, for display. Page ids are UUIDv7,
/// whose leading characters are a timestamp that pages written close together
/// share.
pub(crate) fn short_page_id(id: &str) -> &str {
    let start = id.char_indices().rev().nth(7).map_or(0, |(i, _)| i);
    &id[start..]
}

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

    #[test]
    fn short_page_id_keeps_the_random_tail() {
        assert_eq!(
            short_page_id("01a16f89-8ca9-7f40-8847-eb44e095e3ea"),
            "e095e3ea"
        );
        assert_eq!(
            short_page_id("01a16f89-eb81-70a2-8ba4-c84c5783b7fb"),
            "5783b7fb"
        );
        assert_eq!(short_page_id("abc"), "abc");
    }

    fn write_args(path: &str, project: Option<&str>) -> WritePageArgs {
        WritePageArgs {
            path: path.into(),
            body: "test body".into(),
            workspace: None,
            project: project.map(str::to_string),
            title: None,
            kind: None,
            tier: "semantic".into(),
            tag: Vec::new(),
            pinned: false,
            applies_to: Vec::new(),
            enforced_by: None,
        }
    }

    #[tokio::test]
    async fn an_empty_project_flag_is_refused_before_any_request() {
        let config = Config::default();
        let a = write_args("notes/example.md", Some("   "));
        let error = run(&config, a).await.unwrap_err();
        assert!(
            error.to_string().contains("--project was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_workspace_flag_is_refused_before_any_request() {
        let config = Config::default();
        let mut a = write_args("notes/example.md", Some("app"));
        a.workspace = Some("".into());
        let error = run(&config, a).await.unwrap_err();
        assert!(
            error.to_string().contains("--workspace was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_path_is_refused_before_any_request() {
        let config = Config::default();
        let a = write_args("   ", Some("app"));
        let error = run(&config, a).await.unwrap_err();
        assert!(
            error.to_string().contains("--path was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_project_flag_is_refused_before_reading_stdin() {
        let config = Config::default();
        let mut a = write_args("notes/example.md", Some(""));
        a.body = "-".into();
        let error = run(&config, a).await.unwrap_err();
        assert!(
            error.to_string().contains("--project was passed empty"),
            "unexpected error: {error}"
        );
    }
}