Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(cli): add interactive marker initializer
phungmanhquang09c550f08801
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 326a7d0f..c3783b7a 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -918,12 +918,18 @@ pub struct ProjectArgs {/// `project` subcommands.#[derive(Debug, Subcommand)]pub enum ProjectCommand {+ /// Interactively create this checkout's `.ai-memory.toml` marker.+ Init(ProjectInitArgs),/// Set a project `open` or `restricted`.Access(ProjectAccessArgs),/// List who holds a grant on one project.Grants(ProjectGrantsArgs),}+/// Arguments for `project init`.+#[derive(Debug, Args)]+pub struct ProjectInitArgs {}+/// Arguments for `profile`.#[derive(Debug, Args)]pub struct ProfileArgs {@@ -3384,6 +3390,16 @@ mod tests {assert!(Cli::try_parse_from(["ai-memory", "grant", "list"]).is_err());}+ #[test]+ fn project_init_parses_without_server_scope_flags() {+ let parsed =+ Cli::try_parse_from(["ai-memory", "project", "init"]).expect("project init parses");+ let Command::Project(args) = parsed.command else {+ panic!("expected project command");+ };+ assert!(matches!(args.command, ProjectCommand::Init(_)));+ }+#[test]fn serve_parses_insecure_no_auth_override() {let parsed = Cli::try_parse_from([diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex f78711e6..625aa049 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -74,6 +74,7 @@ pub mod path_util;pub mod pending_writes;pub mod profile;pub mod project;+pub mod project_init;pub mod project_registry;pub mod purge_preview;pub mod purge_project;diff --git a/crates/ai-memory-cli/src/commands/project.rs b/crates/ai-memory-cli/src/commands/project.rsindex 05a56771..cefea1e5 100644--- a/crates/ai-memory-cli/src/commands/project.rs+++ b/crates/ai-memory-cli/src/commands/project.rs@@ -1,8 +1,10 @@-//! `ai-memory project` — project settings (#708).+//! `ai-memory project` — local marker setup and server project settings (#708).//!-//! Thin HTTP client over `/admin/projects/*`, root-only like `ai-memory-//! grant`: access is an operator decision, made against the server rather than-//! a database the operator's laptop usually cannot open.+//! `project init` creates a local `.ai-memory.toml` and never contacts the+//! server. The remaining actions are thin HTTP clients over `/admin/projects/*`,+//! root-only like `ai-memory grant`: access is an operator decision, made+//! against the server rather than a database the operator's laptop usually+//! cannot open.use anyhow::{Context, Result};use serde::Deserialize;@@ -14,12 +16,19 @@ use crate::http_client::{ServerEndpoint, post_json};/// Dispatch a `project` subcommand.////// # Errors-/// Transport failures, a non-root token, an unknown project or mode.+/// Local marker initialization failures, or a transport failure, non-root+/// token, unknown project, or invalid mode for a server-side action.pub async fn run(config: &Config, args: ProjectArgs) -> Result<()> {- let ep = ServerEndpoint::from_config_resolving_auth(config).await;match args.command {- ProjectCommand::Access(args) => access(&ep, args).await,- ProjectCommand::Grants(args) => crate::commands::grant::list_for_project(&ep, &args).await,+ ProjectCommand::Init(args) => crate::commands::project_init::run(args),+ ProjectCommand::Access(args) => {+ let ep = ServerEndpoint::from_config_resolving_auth(config).await;+ access(&ep, args).await+ }+ ProjectCommand::Grants(args) => {+ let ep = ServerEndpoint::from_config_resolving_auth(config).await;+ crate::commands::grant::list_for_project(&ep, &args).await+ }}}diff --git a/crates/ai-memory-cli/src/commands/project_init.rs b/crates/ai-memory-cli/src/commands/project_init.rsnew file mode 100644index 00000000..f2e1fe40--- /dev/null+++ b/crates/ai-memory-cli/src/commands/project_init.rs@@ -0,0 +1,393 @@+//! `ai-memory project init` — create a checkout-local scope marker.+//!+//! This command deliberately stays local: it chooses a directory, suggests a+//! scope from the checkout's Git metadata, then creates `.ai-memory.toml`.+//! It does not create a server-side project or contact the configured server.++use std::ffi::OsStr;+use std::fs::OpenOptions;+use std::io::{self, IsTerminal as _, Write as _};+use std::path::Path;++use ai_memory_core::MARKER_FILENAME;+use anyhow::{Context, Result, bail};++use crate::cli::ProjectInitArgs;+use crate::config::DEFAULT_WORKSPACE;++const FALLBACK_PROJECT: &str = "project";++#[derive(Debug, PartialEq, Eq)]+struct Suggestions {+ workspace: String,+ project: String,+}++/// Run the interactive marker initializer.+///+/// # Errors+/// Returns an error outside an interactive terminal, when the current+/// directory or marker cannot be inspected, or when the marker cannot be+/// created without replacing an existing file.+pub fn run(_: ProjectInitArgs) -> Result<()> {+ if !io::stdin().is_terminal() || !io::stdout().is_terminal() {+ bail!("`ai-memory project init` needs an interactive terminal");+ }+ let cwd = std::env::current_dir().context("reading the current directory")?;+ initialize(&cwd, &mut io::stdin().lock(), &mut io::stdout().lock())+}++fn initialize(cwd: &Path, input: &mut impl io::BufRead, output: &mut impl io::Write) -> Result<()> {+ let repo_root = ai_memory_consolidate::discover_repo_root(cwd).ok();+ let directory = repo_root.as_deref().unwrap_or(cwd);+ let marker = directory.join(MARKER_FILENAME);+ if marker+ .try_exists()+ .with_context(|| format!("checking {}", marker.display()))?+ {+ bail!(+ "{} already exists; refusing to overwrite it",+ marker.display()+ );+ }++ let suggestions = suggestions_for(+ directory,+ repo_root.is_some(),+ preferred_remote_identity(cwd).as_deref(),+ );+ let workspace = prompt_scope_value("Workspace", &suggestions.workspace, input, output)?;+ let project = prompt_scope_value("Project", &suggestions.project, input, output)?;+ let body = render_marker(&workspace, &project);+ write_new_marker(&marker, &body)?;+ writeln!(output, "Created {}.", marker.display()).context("reporting created marker")?;+ Ok(())+}++fn preferred_remote_identity(cwd: &Path) -> Option<String> {+ let (upstream, origin) = ai_memory_consolidate::read_identity_remotes(cwd);+ normalized_remote(upstream.as_deref(), origin.as_deref())+}++fn normalized_remote(upstream: Option<&str>, origin: Option<&str>) -> Option<String> {+ [upstream, origin]+ .into_iter()+ .flatten()+ .find_map(ai_memory_core::repository_identity::normalize_remote_url)+}++fn suggestions_for(directory: &Path, is_git_checkout: bool, remote: Option<&str>) -> Suggestions {+ if let Some(remote) = remote+ && let Some(suggestions) = suggestions_from_remote(remote)+ {+ return suggestions;+ }++ Suggestions {+ workspace: if is_git_checkout {+ DEFAULT_WORKSPACE.to_owned()+ } else {+ directory+ .parent()+ .and_then(path_basename)+ .unwrap_or_else(|| DEFAULT_WORKSPACE.to_owned())+ },+ project: path_basename(directory).unwrap_or_else(|| FALLBACK_PROJECT.to_owned()),+ }+}++fn suggestions_from_remote(remote: &str) -> Option<Suggestions> {+ let segments: Vec<&str> = remote+ .split('/')+ .filter(|segment| !segment.is_empty())+ .collect();+ let project = segments.last()?.to_string();+ let workspace = if segments.len() >= 3 {+ segments[segments.len() - 2].to_owned()+ } else {+ DEFAULT_WORKSPACE.to_owned()+ };+ Some(Suggestions { workspace, project })+}++fn path_basename(path: &Path) -> Option<String> {+ path.file_name()+ .and_then(OsStr::to_str)+ .filter(|name| !name.trim().is_empty())+ .map(str::to_owned)+}++fn prompt_scope_value(+ label: &str,+ suggestion: &str,+ input: &mut impl io::BufRead,+ output: &mut impl io::Write,+) -> Result<String> {+ loop {+ write!(output, "{label} [{suggestion}]: ").context("prompting for marker scope")?;+ output.flush().context("flushing marker scope prompt")?;+ let mut line = String::new();+ if input+ .read_line(&mut line)+ .context("reading marker scope input")?+ == 0+ {+ bail!("aborted (no input)");+ }+ let value = if line.trim().is_empty() {+ suggestion+ } else {+ line.trim()+ };+ if valid_scope_value(value) {+ return Ok(value.to_owned());+ }+ writeln!(+ output,+ "Enter a non-empty workspace or project name without '/'."+ )+ .context("reporting invalid marker scope")?;+ }+}++fn valid_scope_value(value: &str) -> bool {+ !value.is_empty() && !value.contains('/')+}++fn render_marker(workspace: &str, project: &str) -> String {+ let mut document = toml_edit::DocumentMut::new();+ document["workspace"] = toml_edit::value(workspace);+ document["project"] = toml_edit::value(project);+ document["recall"] = toml_edit::Item::Table(toml_edit::Table::new());+ document["recall"]["default_global"] = toml_edit::value(false);+ document["profile"] = toml_edit::Item::Table(toml_edit::Table::new());+ document["profile"]["contribute"] = toml_edit::value(false);+ document["profile"]["consume"] = toml_edit::value(false);+ document["briefing"] = toml_edit::Item::Table(toml_edit::Table::new());+ document["briefing"]["inject_on_session_start"] = toml_edit::value(true);+ document["briefing"]["max_chars"] = toml_edit::value(4_000);+ document.to_string()+}++fn write_new_marker(path: &Path, body: &str) -> Result<()> {+ let mut file = OpenOptions::new()+ .write(true)+ .create_new(true)+ .open(path)+ .with_context(|| format!("creating {}", path.display()))?;+ file.write_all(body.as_bytes())+ .with_context(|| format!("writing {}", path.display()))?;+ file.sync_all()+ .with_context(|| format!("syncing {}", path.display()))?;+ Ok(())+}++#[cfg(test)]+mod tests {+ use std::io::Cursor;+ use std::process::Command;++ use super::*;++ #[test]+ fn upstream_wins_over_origin_when_suggesting_scope() {+ let remote = normalized_remote(+ Some("[email protected]:acme/platform/api.git"),+ Some("[email protected]:personal/api.git"),+ )+ .unwrap();+ assert_eq!(remote, "git.example.test/acme/platform/api");+ assert_eq!(+ suggestions_from_remote(&remote),+ Some(Suggestions {+ workspace: "platform".to_owned(),+ project: "api".to_owned(),+ })+ );+ }++ #[test]+ fn origin_is_used_when_upstream_is_not_a_remote_identity() {+ assert_eq!(+ normalized_remote(Some("../parent"), Some("https://github.com/acme/api.git")),+ Some("github.com/acme/api".to_owned())+ );+ }++ #[test]+ fn ownerless_remote_uses_default_workspace() {+ assert_eq!(+ suggestions_from_remote("github.com/api"),+ Some(Suggestions {+ workspace: "default".to_owned(),+ project: "api".to_owned(),+ })+ );+ }++ #[test]+ fn directories_without_git_use_parent_and_current_name() {+ let dir = Path::new("/work/team/service");+ assert_eq!(+ suggestions_for(dir, false, None),+ Suggestions {+ workspace: "team".to_owned(),+ project: "service".to_owned(),+ }+ );+ }++ #[test]+ fn git_checkout_without_remote_uses_default_and_root_name() {+ let dir = Path::new("/work/team/service");+ assert_eq!(+ suggestions_for(dir, true, None),+ Suggestions {+ workspace: "default".to_owned(),+ project: "service".to_owned(),+ }+ );+ }++ #[test]+ fn root_fallbacks_are_stable() {+ assert_eq!(+ suggestions_for(Path::new("/"), false, None),+ Suggestions {+ workspace: "default".to_owned(),+ project: "project".to_owned(),+ }+ );+ }++ #[test]+ fn marker_body_matches_the_interactive_template() {+ assert_eq!(+ render_marker("acme", "api"),+ "workspace = \"acme\"\nproject = \"api\"\n\n[recall]\ndefault_global = false\n\n[profile]\ncontribute = false\nconsume = false\n\n[briefing]\ninject_on_session_start = true\nmax_chars = 4000\n"+ );+ }++ #[test]+ fn initialize_writes_a_new_marker_from_entered_values() {+ let temp = tempfile::tempdir().unwrap();+ let mut input = Cursor::new(b"team\napi\n");+ let mut output = Vec::new();++ initialize(temp.path(), &mut input, &mut output).unwrap();++ assert_eq!(+ std::fs::read_to_string(temp.path().join(MARKER_FILENAME)).unwrap(),+ render_marker("team", "api")+ );+ assert!(String::from_utf8(output).unwrap().contains("Created "));+ }++ #[test]+ fn initialize_accepts_the_suggested_values_on_empty_input() {+ let temp = tempfile::tempdir().unwrap();+ let suggestions = suggestions_for(temp.path(), false, None);+ let mut input = Cursor::new(b"\n\n");+ let mut output = Vec::new();++ initialize(temp.path(), &mut input, &mut output).unwrap();++ assert_eq!(+ std::fs::read_to_string(temp.path().join(MARKER_FILENAME)).unwrap(),+ render_marker(&suggestions.workspace, &suggestions.project)+ );+ }++ #[test]+ fn initialize_from_a_worktree_descendant_writes_at_that_worktree_root() {+ let temp = tempfile::tempdir().unwrap();+ let main = temp.path().join("main");+ std::fs::create_dir(&main).unwrap();+ git(&main, &["init", "-q"]);+ git(&main, &["config", "user.email", "[email protected]"]);+ git(&main, &["config", "user.name", "Fixture"]);+ std::fs::write(main.join("README.md"), "fixture\n").unwrap();+ git(&main, &["add", "README.md"]);+ git(&main, &["commit", "--no-gpg-sign", "-qm", "initial"]);++ let worktree = temp.path().join("linked");+ git(+ &main,+ &["worktree", "add", "-q", worktree.to_str().unwrap(), "HEAD"],+ );+ let nested = worktree.join("nested");+ std::fs::create_dir(&nested).unwrap();+ let mut input = Cursor::new(b"team\napi\n");+ let mut output = Vec::new();++ initialize(&nested, &mut input, &mut output).unwrap();++ assert!(worktree.join(MARKER_FILENAME).is_file());+ assert!(!main.join(MARKER_FILENAME).exists());+ }++ #[test]+ fn initialize_reprompts_for_slash_values() {+ let temp = tempfile::tempdir().unwrap();+ let mut input = Cursor::new(b"team/api\nteam\napi/service\napi\n");+ let mut output = Vec::new();++ initialize(temp.path(), &mut input, &mut output).unwrap();++ assert_eq!(+ std::fs::read_to_string(temp.path().join(MARKER_FILENAME)).unwrap(),+ render_marker("team", "api")+ );+ assert_eq!(+ String::from_utf8(output)+ .unwrap()+ .matches("without '/'.")+ .count(),+ 2+ );+ }++ #[test]+ fn initialize_refuses_to_overwrite_an_existing_marker() {+ let temp = tempfile::tempdir().unwrap();+ let marker = temp.path().join(MARKER_FILENAME);+ std::fs::write(&marker, "workspace = \"original\"\n").unwrap();+ let mut input = Cursor::new(b"team\napi\n");+ let mut output = Vec::new();++ let error = initialize(temp.path(), &mut input, &mut output).unwrap_err();++ assert!(error.to_string().contains("refusing to overwrite"));+ assert_eq!(+ std::fs::read_to_string(marker).unwrap(),+ "workspace = \"original\"\n"+ );+ assert!(output.is_empty());+ }++ #[test]+ fn initialize_aborts_on_end_of_input_without_creating_a_marker() {+ let temp = tempfile::tempdir().unwrap();+ let mut input = Cursor::new(Vec::<u8>::new());+ let mut output = Vec::new();++ let error = initialize(temp.path(), &mut input, &mut output).unwrap_err();++ assert_eq!(error.to_string(), "aborted (no input)");+ assert!(!temp.path().join(MARKER_FILENAME).exists());+ }++ fn git(cwd: &Path, args: &[&str]) {+ let output = Command::new("git")+ .arg("-C")+ .arg(cwd)+ .args(args)+ .output()+ .unwrap_or_else(|error| panic!("running git {args:?}: {error}"));+ assert!(+ output.status.success(),+ "git {args:?} failed: {}",+ String::from_utf8_lossy(&output.stderr)+ );+ }+}diff --git a/docs/marker-file.md b/docs/marker-file.mdindex b771e298..d4a43c9e 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -71,6 +71,40 @@ travel as one percent-encoded JSON-array `aliases` query value on both hook andhandoff requests, and are ignored unless the checkout supplies a normalizedhostful git-remote identity.+## Create a marker interactively++Run this from anywhere inside a checkout to create a marker at the current+worktree root:++```bash+ai-memory project init+```++The command asks for `workspace` and `project`, offering defaults from the+checkout's `upstream` remote, then `origin`. The immediate namespace before the+repository name becomes the workspace (`gitlab.com/acme/group/api` suggests+`group` / `api`). A remote with no namespace suggests `default` for the+workspace. A checkout without a usable remote suggests `default` and its root+directory name.++Outside Git, the marker is written to the current directory; its parent and+current directory names suggest workspace and project. The command requires an+interactive terminal, never overwrites an existing marker, and writes the+following defaults alongside the chosen names:++```toml+[recall]+default_global = false++[profile]+contribute = false+consume = false++[briefing]+inject_on_session_start = true+max_chars = 4000+```+## Schema```toml