Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(wikisync): two-way sync through the MCP write tool (#986 slice 3)
geeksilva9708ddbcfabad2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5d5d23fd..5bc82299 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Added two-way sync to the `ai-memory-wikisync` companion (#986, slice 3):+ `sync` imports repository edits and new pages through the public+ `memory_write_page` MCP tool and exports server edits, comparing each+ page with the last sync. A page changed on both sides is a conflict until+ `--prefer repo` or `--prefer server`; deletes are reported, not synced.+ It is a dry-run without `--apply`, refuses files without frontmatter,+ refuses to overwrite server pages whose metadata a write would clear, and+ re-reads each page right before writing it. (#TBD)++### Changed+- Changed `ai-memory-wikisync` files to carry a small frontmatter (`title`,+ plus `tags`, `pinned` and a non-default `tier` when set) above the body,+ so metadata survives a round trip. The first run after upgrading rewrites+ unedited files of an earlier export in place. (#TBD)+### Fixed- Fixed `ai-memory-wikisync` committing its per-clone export state: the`git add` of the destination that `export --apply` prints also stageddiff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex 17650d20..eee27e40 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -1,11 +1,14 @@# ai-memory-wikisync-Read-only **team-wiki export** companion for-[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986,-slice 1). It pulls explicitly allowlisted page families from a running-ai-memory server through the public, read-only `/api/v1` surface into a-directory inside a project repository, so a team's shared memory can live-as reviewable markdown in git.+**Team-wiki sync** companion for+[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986, slices+1 and 3). It keeps explicitly allowlisted page families of a running+ai-memory server in step with a directory inside a project repository, so a+team's shared memory can live as reviewable markdown in git:++- `export` copies server pages into the repository (one way).+- `sync` also sends repository edits back to the server, through the public+ `memory_write_page` MCP tool.It is a standalone Cargo package (own workspace, own lockfile); the rootai-memory workspace does not build or test it:@@ -28,6 +31,12 @@ ai-memory-wikisync plan \# Same listing, then write — export without --apply is still a dry-run.ai-memory-wikisync export ... --apply++# Two-way: dry-run plan of imports and exports, then apply it.+ai-memory-wikisync sync ...+ai-memory-wikisync sync ... --apply+# A page changed on both sides is a conflict until a side is chosen.+ai-memory-wikisync sync ... --apply --prefer repo # or --prefer server```- `plan` never writes, not even the state file.@@ -43,10 +52,24 @@ ai-memory-wikisync export ... --apply## What it writes-Exactly the server's canonical page projection: `path`, `title`, `body`.-The page body (which carries its own `# H1` title) is transported-verbatim. The tool never forges attribution, generated, or sync-frontmatter into page files.+Each file is a small frontmatter, then the server body verbatim:++```markdown+---+title: "Commit rules"+tags: ["git"]+pinned: true+---+# Commit rules+...+```++Only the fields `memory_write_page` accepts and this tool round-trips appear:+`title`, `tags` (when there are any), `pinned` (when true), and `tier` (when+it is not the default `semantic`). The values are JSON strings and lists,+which are also valid YAML. A sync sends these fields back with every import,+because the tool clears whatever a write omits. Server-generated keys+(`type`, `generated`, `last_modified_by`) never reach the repository.All local bookkeeping lives in **one** state file,`.ai-memory-wikisync/state.json` (mode 0600, atomically replaced after@@ -63,12 +86,15 @@ state; untrack it once with## Safety model+This section describes `plan` and `export`; `sync` adds the rules under+[Two-way sync](#two-way-sync).+- **API-only.** Documented read-only `/api/v1` endpoints (incremental`recent` listing with cursor paging, single-page reads with`ETag`/`If-None-Match` revalidation; the legacy array listing is- accepted as a fallback). No MCP, no admin routes, no writes to the- server. `401`/`403`/`404` become clear errors; page count and body size- are bounded per run.+ accepted as a fallback). No admin routes, and `plan` and `export` never+ write to the server. `401`/`403`/`404` become clear errors; page count+ and body size are bounded per run.- **Path safety.** Every server-reported path is validated into aportable shape (ASCII, no traversal, no dotfiles, no reserved Windowsnames, `.md` leaf, bounded depth/length) before it is joined onto@@ -80,19 +106,57 @@ state; untrack it once withdiverged from both is reported with a diff summary and **refused**; thewhole batch is refused, nothing is written. `--force` overwrites thedivergent files with server content.-- **Never deletes.** Local files — including brand-new local files inside- an allowlisted family — are never deleted. Deletes are slice 4.+- **Never deletes.** Local files and server pages are never deleted,+ including brand-new local files inside an allowlisted family. Deletes+ are slice 4.- **Untrusted content.** Page bodies are data: transported verbatim,never executed, never rendered, never interpreted. Paths that wouldescape `--dest` are refused.-## Roadmap (#986)+## Two-way sync++`sync` classifies every page in the allowlisted families from three+versions: the repository file, the state entry (what the last sync wrote),+and the server page rendered into file bytes.++| Repository | Server | Action |+|---|---|---|+| unchanged | changed | export the server page |+| changed | unchanged | import the file with `memory_write_page` |+| new file | no page | import (create) |+| changed | changed | conflict: nothing is written until `--prefer repo` or `--prefer server` |+| deleted | present | reported; the server page is kept |+| present | deleted | reported; the file is kept |++Safety rules:++- **Writes only through MCP.** No wiki file or SQLite access; the server's+ sanitizer, admission and attribution apply to every import.+- **Dry-run by default.** `--apply` is required, and any refused page+ (a conflict, an invalid file) blocks the whole batch.+- **Frontmatter is required to import.** A file without it would clear the+ page's title, tags and pin on the server, so it is refused.+- **Metadata the write cannot carry is protected.** A server page with any+ frontmatter key other than `title`, `tier`, `pinned`, `tags`, `type`,+ `generated` and `last_modified_by` (a consolidated page's `summary` or+ `sources`, an MCP write's `kind` or `abstract`) is never overwritten by an+ import; the refusal names the keys. Such pages still export.+- **Re-read before each write.** Right before an import the server page is+ read again and must still render to the bytes it was classified against.+ The MCP write has no compare-and-write, so a write that lands between that+ read and the import is the one race left (the case for slice 2).+- **The server's version wins after an import.** If the server stores+ something other than the file (the sanitizer redacting a secret), the file+ is rewritten with the server's rendering.+- **Deletes are not synced yet** (slice 4). Pages gone from both sides drop+ out of the state.-This is slice 1 of the accepted team-wiki sync plan:+## Roadmap (#986)-1. **This release — read-only export** into a project repository.+1. Read-only export into a project repository (`export`).2. Conditional mutation seam (compare-and-write) in core, if independentlyjustified.-3. Bidirectional apply (repo edits flow back through public write tools).+3. **This release — two-way sync** (`sync`): repository edits flow back+ through the public MCP write tool.4. Deletes and conflict reporting.5. Post-merge hook / CI integration.diff --git a/companions/ai-memory-wikisync/src/bidi.rs b/companions/ai-memory-wikisync/src/bidi.rsnew file mode 100644index 00000000..d0462620--- /dev/null+++ b/companions/ai-memory-wikisync/src/bidi.rs@@ -0,0 +1,734 @@+//! Two-way sync (#986, slice 3): repository edits flow back to the server+//! through the public `memory_write_page` tool, server edits flow out as in+//! `export`.+//!+//! Every page in an allowlisted family is classified from three versions:+//! the repository file, the state entry (what the last sync wrote), and the+//! server page rendered into file bytes. A change on one side is applied to+//! the other; a change on both sides is a conflict that only `--prefer`+//! resolves. Deletes on either side are reported and left alone (slice 4).+//!+//! Nothing is written unless `--apply` is passed and nothing in the plan is+//! refused. Before each import the server page is read again and must still+//! render to the bytes it was classified against: the MCP write has no+//! compare-and-write, so that re-read narrows the race to the gap between+//! one read and one write (the case for slice 2).++use std::collections::{BTreeMap, BTreeSet};+use std::fs;+use std::path::Path;++use anyhow::{Context, Result, bail};+use serde_json::Value;++use crate::client::{ApiClient, ApiPage};+use crate::mcp::McpClient;+use crate::page_file::{self, PageMeta};+use crate::state::{self, PageState, SyncState};+use crate::sync::{self, Mode, RunArgs};+use crate::{MAX_BODY_BYTES, MAX_PAGES, paths};++/// Server frontmatter keys a `memory_write_page` import writes back, or+/// the server regenerates on every write. A page carrying any other key+/// (a consolidated page's `summary`, `sources`, `kind`, …) would lose it,+/// because the tool clears what the call omits.+const RECREATED_KEYS: &[&str] = &[+ "title",+ "tier",+ "pinned",+ "tags",+ "type",+ "generated",+ "last_modified_by",+];++/// Which side wins a page changed on both sides.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Prefer {+ Repo,+ Server,+}++/// What the server holds for one path.+#[derive(Debug, Clone, Copy)]+pub enum ServerSide<'a> {+ /// Not in the listing: never created, or deleted.+ Absent,+ /// `304`: unchanged since the ETag recorded with the base.+ NotModified,+ /// The page rendered into file bytes.+ Rendered(&'a [u8]),+}++/// The decision for one page.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Action {+ Unchanged,+ /// Server to repository.+ Export {+ create: bool,+ },+ /// Repository to server.+ Import {+ create: bool,+ },+ /// Changed on both sides, and no `--prefer`.+ Conflict,+ /// The server no longer has a page the last sync saw (slice 4).+ DeletedOnServer,+ /// The repository no longer has a file the last sync wrote (slice 4).+ DeletedInRepo,+ /// Gone from both sides: only the state entry remains, and it is dropped.+ GoneOnBothSides,+}++/// Decide one page from its three versions. Pure, so the matrix is testable+/// without a server.+pub fn decide(+ disk: Option<&[u8]>,+ base: Option<&PageState>,+ server: ServerSide<'_>,+ prefer: Option<Prefer>,+) -> Action {+ let disk_hash = disk.map(state::sha256_hex);+ let disk_is_base = matches!((&disk_hash, base), (Some(disk), Some(base)) if *disk == base.hash);+ match server {+ ServerSide::Absent => match (disk.is_some(), base.is_some()) {+ (true, false) => Action::Import { create: true },+ (true, true) => Action::DeletedOnServer,+ (false, true) => Action::GoneOnBothSides,+ (false, false) => Action::Unchanged,+ },+ ServerSide::NotModified => match (disk.is_some(), base.is_some()) {+ (false, true) => Action::DeletedInRepo,+ (false, false) => Action::Unchanged,+ (true, _) if disk_is_base => Action::Unchanged,+ (true, _) => Action::Import { create: false },+ },+ ServerSide::Rendered(server) => {+ let server_hash = state::sha256_hex(server);+ match disk_hash {+ None if base.is_some() => Action::DeletedInRepo,+ None => Action::Export { create: true },+ Some(disk) if disk == server_hash => Action::Unchanged,+ Some(_) if disk_is_base => Action::Export { create: false },+ Some(_) if base.is_some_and(|base| base.hash == server_hash) => {+ Action::Import { create: false }+ }+ Some(_) => match prefer {+ Some(Prefer::Repo) => Action::Import { create: false },+ Some(Prefer::Server) => Action::Export { create: false },+ None => Action::Conflict,+ },+ }+ }+ }+}++/// Server frontmatter keys an import would clear, sorted.+pub fn keys_an_import_would_clear(frontmatter: &Value) -> Vec<String> {+ let Some(map) = frontmatter.as_object() else {+ return Vec::new();+ };+ let mut keys: Vec<String> = map+ .keys()+ .filter(|key| !RECREATED_KEYS.contains(&key.as_str()))+ .cloned()+ .collect();+ keys.sort();+ keys+}++/// Arguments of `sync`.+#[derive(Debug, Clone)]+pub struct SyncArgs {+ pub run: RunArgs,+ pub prefer: Option<Prefer>,+}++struct Import {+ path: String,+ create: bool,+ meta: PageMeta,+ body: String,+ disk: Vec<u8>,+ /// Hash of the server page's rendering at classification, which must+ /// still hold right before the write; `None` for a create.+ expected_server: Option<String>,+}++struct Export {+ path: String,+ create: bool,+ bytes: String,+ etag: Option<String>,+}++/// A page the plan refuses to touch; any of these blocks `--apply`.+struct Refusal {+ path: String,+ reason: String,+}++#[derive(Default)]+struct Plan {+ imports: Vec<Import>,+ exports: Vec<Export>,+ unchanged: Vec<String>,+ refused: Vec<Refusal>,+ notices: Vec<(String, &'static str)>,+ /// State to keep for pages this run leaves alone or adopts.+ adopted: BTreeMap<String, PageState>,+ forget: Vec<String>,+}++/// Entry point behind `sync`.+pub async fn run(args: &SyncArgs, apply: bool) -> Result<()> {+ let run_args = &args.run;+ let families = sync::validate_allowlist(&run_args.include)?;+ let mode = if apply { Mode::Apply } else { Mode::DryRun };+ let dest_root = sync::resolve_dest(&run_args.dest, mode)?;+ let old_state = state::load(&dest_root)?;+ let api = ApiClient::new(&run_args.server, run_args.token.clone())?;++ let plan = build_plan(&api, args, &families, &dest_root, &old_state).await?;+ print_plan(run_args, &families, &plan, apply);++ if !apply {+ return Ok(());+ }+ if !plan.refused.is_empty() {+ bail!(+ "{} page(s) refused; nothing was written. Resolve them (or pass --prefer for \+ conflicts) and run again",+ plan.refused.len()+ );+ }+ let mcp = McpClient::new(&run_args.server, run_args.token.clone())?;+ let wrote_files = apply_plan(&api, &mcp, run_args, &dest_root, &old_state, plan).await?;+ if wrote_files {+ sync::print_git_hints(run_args);+ }+ Ok(())+}++async fn build_plan(+ api: &ApiClient,+ args: &SyncArgs,+ families: &[String],+ dest_root: &Path,+ old_state: &SyncState,+) -> Result<Plan> {+ let run_args = &args.run;+ let mut plan = Plan::default();+ let listed = api+ .list_pages(&run_args.workspace, &run_args.project)+ .await?;+ let on_server: BTreeSet<String> = sync::select_pages(listed, families)?+ .into_iter()+ .map(|page| page.path)+ .collect();+ let in_repo = local_pages(dest_root, families, &mut plan.refused)?;+ let in_state = old_state+ .pages+ .keys()+ .filter(|path| {+ families+ .iter()+ .any(|family| paths::family_of(path) == family)+ })+ .cloned();+ let all: BTreeSet<String> = on_server+ .iter()+ .cloned()+ .chain(in_repo)+ .chain(in_state)+ .collect();+ if all.len() > MAX_PAGES {+ bail!(+ "{} pages exceed the per-run ceiling of {MAX_PAGES}; narrow --include",+ all.len()+ );+ }+ paths::ensure_no_case_fold_collisions(&all.iter().cloned().collect::<Vec<_>>())?;++ for path in all {+ let disk = sync::read_disk(dest_root, &path)?;+ if disk+ .as_ref()+ .is_some_and(|disk| disk.len() > MAX_BODY_BYTES)+ {+ plan.refused.push(Refusal {+ path,+ reason: format!("file is larger than {MAX_BODY_BYTES} bytes"),+ });+ continue;+ }+ let base = old_state.pages.get(&path);+ let mut current: Option<ApiPage> = None;+ let mut etag = None;+ let mut rendered = None;+ if on_server.contains(&path) {+ let hint = disk+ .as_ref()+ .and(base.and_then(|base| base.etag.as_deref()));+ let read = api+ .read_page(&run_args.workspace, &run_args.project, &path, hint)+ .await?;+ etag = read.etag;+ if let Some(page) = read.page {+ rendered = Some(sync::render_page(&page)?);+ current = Some(page);+ }+ }+ let server = match (&rendered, on_server.contains(&path)) {+ (Some(bytes), _) => ServerSide::Rendered(bytes.as_bytes()),+ (None, true) => ServerSide::NotModified,+ (None, false) => ServerSide::Absent,+ };+ match decide(disk.as_deref(), base, server, args.prefer) {+ Action::Unchanged => {+ if let Some(bytes) = &rendered {+ plan.adopted.insert(+ path.clone(),+ PageState {+ hash: state::sha256_hex(bytes.as_bytes()),+ etag,+ },+ );+ }+ plan.unchanged.push(path);+ }+ Action::Export { create } => {+ let Some(bytes) = rendered else {+ bail!("server returned 304 for {path} with no local file to compare");+ };+ plan.exports.push(Export {+ path,+ create,+ bytes,+ etag,+ });+ }+ Action::Import { create } => {+ let disk = disk.unwrap_or_default();+ if !create && current.is_none() {+ // A 304 proved the server unchanged, but the import+ // still needs the page's metadata keys and rendering.+ let page = api+ .read_page(&run_args.workspace, &run_args.project, &path, None)+ .await?+ .page+ .with_context(|| {+ format!("server returned 304 for {path} without an ETag")+ })?;+ current = Some(page);+ }+ plan_import(&mut plan, path, create, disk, current.as_ref())?;+ }+ Action::Conflict => {+ let summary =+ sync::diff_summary(disk.as_deref(), rendered.as_deref().map(str::as_bytes));+ plan.refused.push(Refusal {+ path,+ reason: format!(+ "changed in the repository and on the server since the last sync \+ ({summary}); pass --prefer repo or --prefer server"+ ),+ });+ }+ Action::DeletedOnServer => plan.notices.push((+ path,+ "deleted on the server; the file is kept (deletes are not synced yet)",+ )),+ Action::DeletedInRepo => plan.notices.push((+ path,+ "deleted in the repository; the server page is kept (deletes are not synced yet)",+ )),+ Action::GoneOnBothSides => plan.forget.push(path),+ }+ }+ Ok(plan)+}++fn plan_import(+ plan: &mut Plan,+ path: String,+ create: bool,+ disk: Vec<u8>,+ current: Option<&ApiPage>,+) -> Result<()> {+ let (meta, body) = match page_file::parse(&disk) {+ Ok(parsed) => parsed,+ Err(error) => {+ plan.refused.push(Refusal {+ path,+ reason: format!("cannot import: {error:#}"),+ });+ return Ok(());+ }+ };+ let expected_server = match current {+ Some(page) => {+ let lost = keys_an_import_would_clear(&page.frontmatter);+ if !lost.is_empty() {+ plan.refused.push(Refusal {+ path,+ reason: format!(+ "cannot import: the server page carries metadata a write would clear \+ ({}); edit it through ai-memory instead",+ lost.join(", ")+ ),+ });+ return Ok(());+ }+ Some(state::sha256_hex(sync::render_page(page)?.as_bytes()))+ }+ None => None,+ };+ plan.imports.push(Import {+ path,+ create,+ meta,+ body,+ disk,+ expected_server,+ });+ Ok(())+}++/// Every `.md` file under the allowlisted families. A symlink or a path the+/// server could not hold is refused, never followed or guessed at.+fn local_pages(+ dest_root: &Path,+ families: &[String],+ refused: &mut Vec<Refusal>,+) -> Result<Vec<String>> {+ let mut found = Vec::new();+ for family in families {+ let mut pending = vec![(dest_root.join(family), family.clone())];+ while let Some((dir, rel)) = pending.pop() {+ let meta = match fs::symlink_metadata(&dir) {+ Ok(meta) => meta,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,+ Err(e) => {+ return Err(anyhow::Error::new(e))+ .context(format!("cannot inspect {}", dir.display()));+ }+ };+ if meta.file_type().is_symlink() {+ refused.push(Refusal {+ path: rel,+ reason: "is a symlink; wikisync never follows one".to_string(),+ });+ continue;+ }+ if !meta.is_dir() {+ continue;+ }+ for entry in+ fs::read_dir(&dir).with_context(|| format!("cannot read {}", dir.display()))?+ {+ let entry = entry?;+ let name = entry.file_name().to_string_lossy().into_owned();+ // Hidden entries include this tool's own tmp files.+ if name.starts_with('.') {+ continue;+ }+ let child_rel = format!("{rel}/{name}");+ let kind = entry.file_type()?;+ if kind.is_symlink() {+ refused.push(Refusal {+ path: child_rel,+ reason: "is a symlink; wikisync never follows one".to_string(),+ });+ } else if kind.is_dir() {+ pending.push((entry.path(), child_rel));+ } else if name.ends_with(".md") {+ match paths::validate_page_path(&child_rel) {+ Ok(()) => found.push(child_rel),+ Err(error) => refused.push(Refusal {+ path: child_rel,+ reason: format!("cannot import: {error:#}"),+ }),+ }+ }+ if found.len() > MAX_PAGES {+ bail!("more than {MAX_PAGES} local pages; narrow --include");+ }+ }+ }+ }+ Ok(found)+}++/// Perform the imports, then the exports, then save the state once. The+/// state is also saved when an import fails partway, so the pages already+/// written are not re-classified as conflicts on the next run.+async fn apply_plan(+ api: &ApiClient,+ mcp: &McpClient,+ args: &RunArgs,+ dest_root: &Path,+ old_state: &SyncState,+ plan: Plan,+) -> Result<bool> {+ let mut new_state = old_state.clone();+ new_state.pages.extend(plan.adopted);+ for path in &plan.forget {+ new_state.pages.remove(path);+ }+ let mut wrote_files = false;+ for import in &plan.imports {+ match import_one(api, mcp, args, dest_root, import).await {+ Ok((entry, normalised)) => {+ wrote_files |= normalised;+ new_state.pages.insert(import.path.clone(), entry);+ }+ Err(error) => {+ state::save(dest_root, &new_state)?;+ return Err(error.context(format!(+ "import of {} failed; the pages imported before it are recorded",+ import.path+ )));+ }+ }+ }+ for export in &plan.exports {+ sync::atomic_write(dest_root, &export.path, export.bytes.as_bytes())?;+ wrote_files = true;+ new_state.pages.insert(+ export.path.clone(),+ PageState {+ hash: state::sha256_hex(export.bytes.as_bytes()),+ etag: export.etag.clone(),+ },+ );+ }+ state::save(dest_root, &new_state)?;+ Ok(wrote_files)+}++/// Re-check, write, read back. Returns the new state entry and whether the+/// file was rewritten because the server stored something other than the+/// file's bytes (the sanitizer redacting a secret, for example).+async fn import_one(+ api: &ApiClient,+ mcp: &McpClient,+ args: &RunArgs,+ dest_root: &Path,+ import: &Import,+) -> Result<(PageState, bool)> {+ let now = api+ .read_page_if_exists(&args.workspace, &args.project, &import.path)+ .await?;+ match (&now, &import.expected_server) {+ (Some(_), None) => bail!("{} was created on the server during this run", import.path),+ (None, Some(_)) => bail!("{} was deleted on the server during this run", import.path),+ (Some(page), Some(expected)) => {+ if state::sha256_hex(sync::render_page(page)?.as_bytes()) != *expected {+ bail!("{} changed on the server during this run", import.path);+ }+ let lost = keys_an_import_would_clear(&page.frontmatter);+ if !lost.is_empty() {+ bail!(+ "{} gained metadata a write would clear during this run ({})",+ import.path,+ lost.join(", ")+ );+ }+ }+ (None, None) => {}+ }+ mcp.write_page(+ &args.workspace,+ &args.project,+ &import.path,+ &import.meta,+ &import.body,+ )+ .await?;+ let read = api+ .read_page(&args.workspace, &args.project, &import.path, None)+ .await?;+ let page = read.page.with_context(|| {+ format!(+ "server returned no body for {} after the write",+ import.path+ )+ })?;+ let rendered = sync::render_page(&page)?;+ let normalised = rendered.as_bytes() != import.disk.as_slice();+ if normalised {+ sync::atomic_write(dest_root, &import.path, rendered.as_bytes())?;+ }+ Ok((+ PageState {+ hash: state::sha256_hex(rendered.as_bytes()),+ etag: read.etag,+ },+ normalised,+ ))+}++fn print_plan(args: &RunArgs, families: &[String], plan: &Plan, apply: bool) {+ println!(+ "ai-memory-wikisync sync: {}/{} <-> {}",+ args.workspace,+ args.project,+ args.dest.display()+ );+ println!(" allowlist: {}", families.join(", "));+ for import in &plan.imports {+ let kind = if import.create { "create" } else { "update" };+ println!(" {:<9} {} (repo -> server, {kind})", "import", import.path);+ }+ for export in &plan.exports {+ let kind = if export.create { "create" } else { "update" };+ println!(" {:<9} {} (server -> repo, {kind})", "export", export.path);+ }+ for path in &plan.unchanged {+ println!(" {:<9} {path}", "unchanged");+ }+ for (path, notice) in &plan.notices {+ println!(" {:<9} {path} — {notice}", "notice");+ }+ for refusal in &plan.refused {+ println!(" {:<9} {} — {}", "REFUSED", refusal.path, refusal.reason);+ }+ println!(+ " sync: {} import, {} export, {} unchanged, {} notice, {} refused",+ plan.imports.len(),+ plan.exports.len(),+ plan.unchanged.len(),+ plan.notices.len(),+ plan.refused.len()+ );+ if !apply {+ println!(" dry run: nothing was written (pass --apply to sync)");+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ fn base(bytes: &[u8]) -> PageState {+ PageState {+ hash: state::sha256_hex(bytes),+ etag: Some("\"e\"".to_string()),+ }+ }++ #[test]+ fn decide_three_way_matrix() {+ let old = b"old".as_slice();+ let repo = b"repo edit".as_slice();+ let server = b"server edit".as_slice();+ let rendered = ServerSide::Rendered;++ // One side changed: the other side follows.+ assert_eq!(+ decide(Some(old), Some(&base(old)), rendered(server), None),+ Action::Export { create: false }+ );+ assert_eq!(+ decide(Some(repo), Some(&base(old)), rendered(old), None),+ Action::Import { create: false }+ );+ assert_eq!(+ decide(Some(repo), Some(&base(old)), ServerSide::NotModified, None),+ Action::Import { create: false }+ );+ assert_eq!(+ decide(Some(old), Some(&base(old)), ServerSide::NotModified, None),+ Action::Unchanged+ );++ // Both changed: a conflict, unless --prefer picks a side.+ assert_eq!(+ decide(Some(repo), Some(&base(old)), rendered(server), None),+ Action::Conflict+ );+ assert_eq!(+ decide(+ Some(repo),+ Some(&base(old)),+ rendered(server),+ Some(Prefer::Repo)+ ),+ Action::Import { create: false }+ );+ assert_eq!(+ decide(+ Some(repo),+ Some(&base(old)),+ rendered(server),+ Some(Prefer::Server)+ ),+ Action::Export { create: false }+ );+ // Both changed to the same bytes: nothing to do.+ assert_eq!(+ decide(Some(server), Some(&base(old)), rendered(server), None),+ Action::Unchanged+ );++ // A file with no base that differs from the server is a conflict+ // too: nothing says which side is newer.+ assert_eq!(+ decide(Some(repo), None, rendered(server), None),+ Action::Conflict+ );+ assert_eq!(+ decide(Some(server), None, rendered(server), None),+ Action::Unchanged+ );++ // Creates come from whichever side has the page.+ assert_eq!(+ decide(None, None, rendered(server), None),+ Action::Export { create: true }+ );+ assert_eq!(+ decide(Some(repo), None, ServerSide::Absent, None),+ Action::Import { create: true }+ );++ // Deletes are reported, never propagated, whatever --prefer says.+ for prefer in [None, Some(Prefer::Repo), Some(Prefer::Server)] {+ assert_eq!(+ decide(Some(old), Some(&base(old)), ServerSide::Absent, prefer),+ Action::DeletedOnServer+ );+ assert_eq!(+ decide(None, Some(&base(old)), rendered(server), prefer),+ Action::DeletedInRepo+ );+ assert_eq!(+ decide(None, Some(&base(old)), ServerSide::NotModified, prefer),+ Action::DeletedInRepo+ );+ assert_eq!(+ decide(None, Some(&base(old)), ServerSide::Absent, prefer),+ Action::GoneOnBothSides+ );+ }+ }++ #[test]+ fn metadata_an_import_would_clear_is_named() {+ let written_by_mcp = json!({+ "title": "T", "tier": "semantic", "pinned": true, "tags": ["a"],+ "type": "Rule", "generated": {"by": "x"}, "last_modified_by": "u"+ });+ assert!(keys_an_import_would_clear(&written_by_mcp).is_empty());+ let consolidated = json!({"title": "T", "summary": "s", "sources": [], "kind": "k"});+ assert_eq!(+ keys_an_import_would_clear(&consolidated),+ vec!["kind", "sources", "summary"]+ );+ assert!(keys_an_import_would_clear(&json!(null)).is_empty());+ }+}diff --git a/companions/ai-memory-wikisync/src/client.rs b/companions/ai-memory-wikisync/src/client.rsindex 5e70d227..4099ed4e 100644--- a/companions/ai-memory-wikisync/src/client.rs+++ b/companions/ai-memory-wikisync/src/client.rs@@ -38,12 +38,23 @@ pub struct PageSummary {}/// The canonical single-page projection. Only the fields this tool-/// transports are decoded; everything else the server returns is ignored-/// rather than stored, and nothing is forged locally.+/// transports, or checks before an import, are decoded; everything else the+/// server returns is ignored rather than stored, and nothing is forged+/// locally.#[derive(Debug, Clone, Deserialize)]pub struct ApiPage {pub path: String,pub body_markdown: String,+ #[serde(default)]+ pub title: String,+ #[serde(default)]+ pub tier: String,+ #[serde(default)]+ pub pinned: bool,+ /// The page's parsed frontmatter: `tags` live here, and so does any+ /// metadata an import would clear.+ #[serde(default)]+ pub frontmatter: serde_json::Value,}/// Result of one page read: the body on `200`, or `None` on `304 Not@@ -145,24 +156,47 @@ impl ApiClient {.send().await.map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;- match response.status() {- StatusCode::OK | StatusCode::NOT_MODIFIED => Ok(response),- StatusCode::UNAUTHORIZED => bail!(- "GET {} returned 401 Unauthorized — the server requires a bearer token \- (pass --token or set AI_MEMORY_AUTH_TOKEN)",- url.as_str()- ),- StatusCode::FORBIDDEN => bail!(- "GET {} returned 403 Forbidden — the token was rejected, the caller lacks \- access to this scope, or the server's host allowlist refused the request",- url.as_str()- ),- StatusCode::NOT_FOUND => bail!(- "GET {} returned 404 Not Found — {not_found_hint}",+ check_status(response, url, not_found_hint)+ }++ /// Read one full page, or `None` when the server has no such page. Used+ /// right before an import, where absence is an answer, not an error.+ pub async fn read_page_if_exists(+ &self,+ workspace: &str,+ project: &str,+ path: &str,+ ) -> Result<Option<ApiPage>> {+ let tail: Vec<&str> = path.split('/').collect();+ let url = self.build_page_url(workspace, project, &tail)?;+ let mut request = self+ .http+ .get(url.clone())+ .header(reqwest::header::ACCEPT, "application/json");+ if let Some(token) = &self.token {+ request = request.bearer_auth(token);+ }+ let response = request+ .send()+ .await+ .map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;+ if response.status() == StatusCode::NOT_FOUND {+ return Ok(None);+ }+ let response = check_status(response, &url, "")?;+ let page: ApiPage = response.json().await.map_err(|e| {+ anyhow!(+ "page read from {} returned malformed JSON: {e}",url.as_str()- ),- status => bail!("GET {} returned unexpected status {status}", url.as_str()),+ )+ })?;+ if page.path != path {+ bail!(+ "server answered a read of {path:?} with page {:?}; refusing the mismatch",+ page.path+ );}+ Ok(Some(page))}/// List the project's latest pages via incremental `recent` paging from@@ -292,6 +326,31 @@ impl ApiClient {}}+fn check_status(+ response: reqwest::Response,+ url: &Url,+ not_found_hint: &str,+) -> Result<reqwest::Response> {+ match response.status() {+ StatusCode::OK | StatusCode::NOT_MODIFIED => Ok(response),+ StatusCode::UNAUTHORIZED => bail!(+ "GET {} returned 401 Unauthorized — the server requires a bearer token \+ (pass --token or set AI_MEMORY_AUTH_TOKEN)",+ url.as_str()+ ),+ StatusCode::FORBIDDEN => bail!(+ "GET {} returned 403 Forbidden — the token was rejected, the caller lacks \+ access to this scope, or the server's host allowlist refused the request",+ url.as_str()+ ),+ StatusCode::NOT_FOUND => bail!(+ "GET {} returned 404 Not Found — {not_found_hint}",+ url.as_str()+ ),+ status => bail!("GET {} returned unexpected status {status}", url.as_str()),+ }+}+/// Small helper so the client builder error reads like the others.trait ContextBuild {fn context_build(self) -> Result<reqwest::Client>;diff --git a/companions/ai-memory-wikisync/src/lib.rs b/companions/ai-memory-wikisync/src/lib.rsindex 27f478d6..edca1785 100644--- a/companions/ai-memory-wikisync/src/lib.rs+++ b/companions/ai-memory-wikisync/src/lib.rs@@ -1,16 +1,20 @@-//! `ai-memory-wikisync`: read-only team-wiki export companion (#986, slice 1).+//! `ai-memory-wikisync`: team-wiki sync companion (#986, slices 1 and 3).//!-//! Pulls explicitly allowlisted page families from a running ai-memory server-//! through the public, read-only `/api/v1` surface into a directory inside a-//! project repository. The tool never mutates the server, never deletes local-//! files (deletes are slice 4), never forges page frontmatter, and never runs-//! git on the operator's behalf.+//! Keeps explicitly allowlisted page families of a running ai-memory server+//! in step with a directory inside a project repository. Reads go through+//! the public, read-only `/api/v1` surface; the only write to the server is+//! the public `memory_write_page` MCP tool, used by `sync`. The tool never+//! opens the wiki directory or SQLite, never deletes (deletes are slice 4),+//! and never runs git on the operator's behalf.//!//! Page bodies are untrusted data: they are transported verbatim into files//! whose validated paths cannot escape the destination directory, and are//! never executed or rendered.+pub mod bidi;pub mod client;+pub mod mcp;+pub mod page_file;pub mod paths;pub mod state;pub mod sync;diff --git a/companions/ai-memory-wikisync/src/main.rs b/companions/ai-memory-wikisync/src/main.rsindex ea6bb2ba..d0ade109 100644--- a/companions/ai-memory-wikisync/src/main.rs+++ b/companions/ai-memory-wikisync/src/main.rs@@ -2,15 +2,16 @@use std::path::PathBuf;+use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};use ai_memory_wikisync::client::DEFAULT_SERVER_URL;use ai_memory_wikisync::sync::{Mode, RunArgs, run};-use clap::{Parser, Subcommand};+use clap::{Parser, Subcommand, ValueEnum};#[derive(Parser, Debug)]#[command(author,version,- about = "Read-only team-wiki export companion for ai-memory (#986, slice 1)"+ about = "Team-wiki sync companion for ai-memory (#986): export and two-way sync")]struct Cli {#[command(subcommand)]@@ -24,6 +25,28 @@ enum Commands {Plan(CommonArgs),/// Export pages into --dest. Dry-run unless --apply is passed.Export(ExportArgs),+ /// Sync both ways: repository edits go to the server through MCP,+ /// server edits come to --dest. Dry-run unless --apply is passed.+ Sync(SyncCliArgs),+}++#[derive(Parser, Debug, Clone)]+struct SyncCliArgs {+ /// Perform the writes. Without it, sync stays a dry-run.+ #[arg(long)]+ apply: bool,+ /// Which side wins a page changed in the repository and on the server.+ /// Without it, such a page is a conflict and nothing is written.+ #[arg(long, value_enum)]+ prefer: Option<PreferArg>,+ #[command(flatten)]+ common: CommonArgs,+}++#[derive(ValueEnum, Debug, Clone, Copy)]+enum PreferArg {+ Repo,+ Server,}#[derive(Parser, Debug, Clone)]@@ -89,6 +112,18 @@ impl From<CommonArgs> for RunArgs {}}+impl From<SyncCliArgs> for SyncArgs {+ fn from(args: SyncCliArgs) -> Self {+ Self {+ run: RunArgs::from(args.common),+ prefer: args.prefer.map(|prefer| match prefer {+ PreferArg::Repo => Prefer::Repo,+ PreferArg::Server => Prefer::Server,+ }),+ }+ }+}+#[tokio::main]async fn main() -> anyhow::Result<()> {let cli = Cli::parse();@@ -102,6 +137,10 @@ async fn main() -> anyhow::Result<()> {};run(&RunArgs::from(args), mode).await}+ Commands::Sync(args) => {+ let apply = args.apply;+ bidi::run(&SyncArgs::from(args), apply).await+ }}}diff --git a/companions/ai-memory-wikisync/src/mcp.rs b/companions/ai-memory-wikisync/src/mcp.rsnew file mode 100644index 00000000..870ef797--- /dev/null+++ b/companions/ai-memory-wikisync/src/mcp.rs@@ -0,0 +1,160 @@+//! The only write seam: the public `memory_write_page` MCP tool.+//!+//! Imports never touch the wiki directory or SQLite. They call the same tool+//! an agent calls, so sanitization, admission, attribution and scope+//! resolution all apply. The request carries `workspace` and `project`+//! explicitly on every call; this companion has no session to route by.++use std::time::Duration;++use anyhow::{Result, anyhow, bail};+use serde_json::{Value, json};+use url::Url;++use crate::page_file::PageMeta;++const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);+/// Bound on a tool error echoed to the terminal.+const ERROR_PREVIEW: usize = 300;++pub struct McpClient {+ http: reqwest::Client,+ url: Url,+ token: Option<String>,+}++impl McpClient {+ /// `server` is the origin `ApiClient::new` already validated.+ pub fn new(server: &str, token: Option<String>) -> Result<Self> {+ let mut url =+ Url::parse(server).map_err(|e| anyhow!("invalid --server {server:?}: {e}"))?;+ url.set_path("/mcp");+ let http = reqwest::Client::builder()+ .timeout(REQUEST_TIMEOUT)+ .build()+ .map_err(|e| anyhow!("cannot build HTTP client: {e}"))?;+ Ok(Self { http, url, token })+ }++ /// Replace (or create) one page with exactly `meta` and `body`. The+ /// tool clears whatever the call omits, which is why every field the+ /// file carries is sent, defaults included.+ pub async fn write_page(+ &self,+ workspace: &str,+ project: &str,+ path: &str,+ meta: &PageMeta,+ body: &str,+ ) -> Result<()> {+ let mut arguments = json!({+ "workspace": workspace,+ "project": project,+ "path": path,+ "body": body,+ "tags": meta.tags,+ "pinned": meta.pinned,+ });+ if let Some(title) = &meta.title {+ arguments["title"] = json!(title);+ }+ if let Some(tier) = &meta.tier {+ arguments["tier"] = json!(tier);+ }+ self.call_tool("memory_write_page", arguments).await+ }++ async fn call_tool(&self, name: &str, arguments: Value) -> Result<()> {+ let request = json!({+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {"name": name, "arguments": arguments},+ });+ let mut builder = self+ .http+ .post(self.url.clone())+ // The streamable HTTP transport refuses a request that does not+ // accept both; it answers plain JSON in its default stateless+ // mode and SSE frames in stateful mode.+ .header(+ reqwest::header::ACCEPT,+ "application/json, text/event-stream",+ )+ .json(&request);+ if let Some(token) = &self.token {+ builder = builder.bearer_auth(token);+ }+ let response = builder+ .send()+ .await+ .map_err(|e| anyhow!("MCP {name} request to {} failed: {e}", self.url))?;+ let status = response.status();+ let text = response+ .text()+ .await+ .map_err(|e| anyhow!("reading the MCP {name} response failed: {e}"))?;+ if !status.is_success() {+ bail!("MCP {name} returned HTTP {status}: {}", preview(&text));+ }+ let message = json_rpc_message(&text)+ .ok_or_else(|| anyhow!("MCP {name} answered with no JSON-RPC message"))?;+ if let Some(error) = message.get("error") {+ bail!("MCP {name} failed: {}", preview(&error.to_string()));+ }+ let result = message+ .get("result")+ .ok_or_else(|| anyhow!("MCP {name} answered with no result"))?;+ if result.get("isError").and_then(Value::as_bool) == Some(true) {+ let detail = result+ .pointer("/content/0/text")+ .and_then(Value::as_str)+ .unwrap_or("no detail");+ bail!("MCP {name} refused the write: {}", preview(detail));+ }+ Ok(())+ }+}++/// The JSON-RPC message in a response body: the body itself, or the last+/// `data:` frame of an SSE stream.+fn json_rpc_message(text: &str) -> Option<Value> {+ if let Ok(value) = serde_json::from_str::<Value>(text) {+ return Some(value);+ }+ text.lines()+ .filter_map(|line| line.strip_prefix("data:"))+ .filter_map(|data| serde_json::from_str::<Value>(data.trim()).ok())+ .next_back()+}++/// Server text is untrusted: bound it and neutralise control characters so+/// it cannot drive the terminal.+fn preview(text: &str) -> String {+ text.chars()+ .take(ERROR_PREVIEW)+ .map(|c| if c.is_control() { '?' } else { c })+ .collect()+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn reads_plain_json_and_sse_frames() {+ let plain = r#"{"jsonrpc":"2.0","id":1,"result":{"isError":false}}"#;+ assert_eq!(json_rpc_message(plain).unwrap()["id"], 1);+ let sse = "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}\n\n";+ assert!(json_rpc_message(sse).unwrap().get("result").is_some());+ assert!(json_rpc_message("event: ping\n\n").is_none());+ }++ #[test]+ fn previews_are_bounded_and_inert() {+ let hostile = format!("\u{1b}[31m{}", "x".repeat(1_000));+ let shown = preview(&hostile);+ assert!(!shown.contains('\u{1b}'));+ assert_eq!(shown.chars().count(), ERROR_PREVIEW);+ }+}diff --git a/companions/ai-memory-wikisync/src/page_file.rs b/companions/ai-memory-wikisync/src/page_file.rsnew file mode 100644index 00000000..863ca536--- /dev/null+++ b/companions/ai-memory-wikisync/src/page_file.rs@@ -0,0 +1,263 @@+//! The on-disk page format: a small, fixed frontmatter plus the verbatim+//! server body.+//!+//! `memory_write_page` replaces a whole page and clears every field the call+//! omits, so a file must carry the metadata an import sends back. Only the+//! fields that write accepts and this tool round-trips appear: `title`,+//! `tags`, `pinned`, and `tier` when it is not the server default. Values+//! are JSON scalars and arrays, which are also valid YAML, so a reviewer+//! reads plain YAML and the parser stays strict and dependency-free.++use anyhow::{Result, bail};+use serde_json::Value;++/// The tier `memory_write_page` assigns when the call omits one.+pub const DEFAULT_TIER: &str = "semantic";+const FENCE: &str = "---";++/// Page metadata a file carries and an import sends back.+#[derive(Debug, Clone, Default, PartialEq, Eq)]+pub struct PageMeta {+ pub title: Option<String>,+ pub tags: Vec<String>,+ pub pinned: bool,+ /// `None` means the server default ([`DEFAULT_TIER`]).+ pub tier: Option<String>,+}++impl PageMeta {+ /// Metadata of a server page, normalised so a default tier and an empty+ /// title are omitted rather than written.+ pub fn from_server(title: &str, tier: &str, pinned: bool, frontmatter: &Value) -> Self {+ let tags = frontmatter+ .get("tags")+ .and_then(Value::as_array)+ .map(|tags| {+ tags.iter()+ .filter_map(Value::as_str)+ .map(str::to_owned)+ .collect()+ })+ .unwrap_or_default();+ Self {+ title: (!title.is_empty()).then(|| title.to_owned()),+ tags,+ pinned,+ tier: (!tier.is_empty() && tier != DEFAULT_TIER).then(|| tier.to_owned()),+ }+ }+}++/// Render the file for a page: frontmatter, then the body byte for byte.+pub fn render(meta: &PageMeta, body: &str) -> String {+ let mut out = String::with_capacity(body.len() + 128);+ out.push_str(FENCE);+ out.push('\n');+ if let Some(title) = &meta.title {+ out.push_str("title: ");+ out.push_str(&json_string(title));+ out.push('\n');+ }+ if !meta.tags.is_empty() {+ let tags: Vec<String> = meta.tags.iter().map(|tag| json_string(tag)).collect();+ out.push_str("tags: [");+ out.push_str(&tags.join(", "));+ out.push_str("]\n");+ }+ if meta.pinned {+ out.push_str("pinned: true\n");+ }+ if let Some(tier) = &meta.tier {+ out.push_str("tier: ");+ out.push_str(&json_string(tier));+ out.push('\n');+ }+ out.push_str(FENCE);+ out.push('\n');+ out.push_str(body);+ out+}++fn json_string(value: &str) -> String {+ Value::String(value.to_owned()).to_string()+}++/// Parse a file this tool wrote, or a reviewer edited, back into metadata+/// and body. Strict on purpose: an import replaces the whole server page,+/// so a key this tool does not understand is refused rather than dropped.+/// Plain (unquoted) scalars are accepted for `title` and `tier`, the shape a+/// person editing YAML by hand most often writes.+pub fn parse(bytes: &[u8]) -> Result<(PageMeta, String)> {+ let Ok(text) = std::str::from_utf8(bytes) else {+ bail!("file is not valid UTF-8");+ };+ let mut lines = text.split_inclusive('\n');+ let opening = lines.next().unwrap_or_default();+ if trim_eol(opening) != FENCE {+ bail!(+ "file has no frontmatter; an import needs it, because the server clears \+ any title, tags or pin the write omits"+ );+ }+ let mut consumed = opening.len();+ let mut meta = PageMeta::default();+ let mut seen: Vec<&str> = Vec::new();+ let mut closed = false;+ for line in lines {+ consumed += line.len();+ let line = trim_eol(line);+ if line == FENCE {+ closed = true;+ break;+ }+ if line.trim().is_empty() {+ continue;+ }+ let Some((key, value)) = line.split_once(':') else {+ bail!("frontmatter line {line:?} is not `key: value`");+ };+ let key = key.trim();+ let value = value.trim();+ if seen.contains(&key) {+ bail!("frontmatter key {key:?} appears twice");+ }+ match key {+ "title" => meta.title = Some(scalar(key, value)?),+ "tier" => meta.tier = Some(scalar(key, value)?).filter(|tier| tier != DEFAULT_TIER),+ "pinned" => {+ meta.pinned = match value {+ "true" => true,+ "false" => false,+ _ => bail!("frontmatter `pinned` must be true or false, not {value:?}"),+ }+ }+ "tags" => meta.tags = tags(value)?,+ _ => bail!(+ "frontmatter key {key:?} is not one wikisync round-trips \+ (title, tags, pinned, tier); remove it before importing"+ ),+ }+ seen.push(key);+ }+ if !closed {+ bail!("frontmatter is not closed by a `---` line");+ }+ Ok((meta, text[consumed..].to_owned()))+}++fn trim_eol(line: &str) -> &str {+ line.strip_suffix('\n')+ .map(|line| line.strip_suffix('\r').unwrap_or(line))+ .unwrap_or(line)+}++fn scalar(key: &str, value: &str) -> Result<String> {+ let parsed = if value.starts_with('"') {+ match serde_json::from_str::<Value>(value) {+ Ok(Value::String(text)) => text,+ _ => bail!("frontmatter `{key}` is not a valid double-quoted string: {value}"),+ }+ } else if value.starts_with(['\'', '[', '{', '|', '>', '&', '*', '!']) {+ bail!("frontmatter `{key}` must be plain text or a double-quoted string");+ } else {+ value.to_owned()+ };+ if parsed.trim().is_empty() || parsed.contains(['\n', '\r']) {+ bail!("frontmatter `{key}` must be one non-empty line");+ }+ Ok(parsed)+}++fn tags(value: &str) -> Result<Vec<String>> {+ let Ok(Value::Array(items)) = serde_json::from_str::<Value>(value) else {+ bail!("frontmatter `tags` must be a list of double-quoted strings, like [\"db\", \"ops\"]");+ };+ items+ .into_iter()+ .map(|item| match item {+ Value::String(tag) if !tag.trim().is_empty() => Ok(tag),+ other => bail!("frontmatter tag {other} is not a non-empty string"),+ })+ .collect()+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;++ fn meta() -> PageMeta {+ PageMeta {+ title: Some("Use \"Postgres\": ação".to_string()),+ tags: vec!["db".to_string(), "ops".to_string()],+ pinned: true,+ tier: Some("episodic".to_string()),+ }+ }++ #[test]+ fn render_then_parse_round_trips_metadata_and_body() {+ let body = "# Use Postgres\n\n---\nA rule line inside the body.\n";+ let rendered = render(&meta(), body);+ assert!(rendered.starts_with("---\ntitle: "), "{rendered}");+ let (parsed, parsed_body) = parse(rendered.as_bytes()).unwrap();+ assert_eq!(parsed, meta());+ assert_eq!(parsed_body, body);+ }++ #[test]+ fn defaults_are_omitted_from_the_file() {+ let plain = PageMeta {+ title: Some("T".to_string()),+ ..PageMeta::default()+ };+ assert_eq!(render(&plain, "# T\n"), "---\ntitle: \"T\"\n---\n# T\n");+ let server = PageMeta::from_server("T", DEFAULT_TIER, false, &json!({"tier": "semantic"}));+ assert_eq!(server, plain);+ let tagged = PageMeta::from_server("T", "episodic", true, &json!({"tags": ["a", 1, "b"]}));+ assert_eq!(tagged.tags, vec!["a".to_string(), "b".to_string()]);+ assert_eq!(tagged.tier.as_deref(), Some("episodic"));+ }++ #[test]+ fn hand_edited_yaml_is_accepted_when_unambiguous() {+ let file = "---\r\ntitle: Plain title\r\n\r\ntier: semantic\r\npinned: false\r\ntags: []\r\n---\r\nbody\r\n";+ let (meta, body) = parse(file.as_bytes()).unwrap();+ assert_eq!(meta.title.as_deref(), Some("Plain title"));+ assert_eq!(meta.tier, None, "the default tier normalises away");+ assert!(meta.tags.is_empty() && !meta.pinned);+ assert_eq!(body, "body\r\n");+ }++ #[test]+ fn anything_an_import_could_lose_is_refused() {+ for (file, needle) in [+ ("# no frontmatter\n", "no frontmatter"),+ (+ "---\ntitle: \"T\"\nbody without a closing fence\n",+ "not `key: value`",+ ),+ ("---\ntitle: \"T\"\n", "not closed"),+ ("---\nsummary: \"x\"\n---\n", "not one wikisync round-trips"),+ ("---\ntitle: \"a\"\ntitle: \"b\"\n---\n", "twice"),+ ("---\npinned: yes\n---\n", "true or false"),+ ("---\ntags: db, ops\n---\n", "list of double-quoted"),+ ("---\ntags: [\"\"]\n---\n", "non-empty string"),+ (+ "---\ntitle: 'single'\n---\n",+ "plain text or a double-quoted",+ ),+ ("---\ntitle: \"\"\n---\n", "non-empty line"),+ ("---\ntitle: \"a\\nb\"\n---\n", "non-empty line"),+ ] {+ let err = parse(file.as_bytes()).unwrap_err().to_string();+ assert!(err.contains(needle), "{file:?}: {err}");+ }+ assert!(+ parse(&[0xff, 0xfe])+ .unwrap_err()+ .to_string()+ .contains("UTF-8")+ );+ }+}diff --git a/companions/ai-memory-wikisync/src/paths.rs b/companions/ai-memory-wikisync/src/paths.rsindex 0f0d0cbf..5bad7db8 100644--- a/companions/ai-memory-wikisync/src/paths.rs+++ b/companions/ai-memory-wikisync/src/paths.rs@@ -1,4 +1,4 @@-//! Destination-path safety for the read-only export.+//! Destination-path safety for export and sync.//!//! Page paths arrive from the server as untrusted data. Every relative wiki//! path is validated into a portable shape before it is ever joined onto thediff --git a/companions/ai-memory-wikisync/src/sync.rs b/companions/ai-memory-wikisync/src/sync.rsindex 5b526744..e0a1b479 100644--- a/companions/ai-memory-wikisync/src/sync.rs+++ b/companions/ai-memory-wikisync/src/sync.rs@@ -14,7 +14,8 @@ use std::path::{Path, PathBuf};use anyhow::{Context, Result, bail};-use crate::client::{ApiClient, PageSummary};+use crate::client::{ApiClient, ApiPage, PageSummary};+use crate::page_file::{self, PageMeta};use crate::paths;use crate::state::{self, PageState, SyncState};use crate::{MAX_BODY_BYTES, MAX_PAGES};@@ -47,8 +48,6 @@ pub enum DivergentReason {LocalEdit,/// Present on disk but never written by this tool.UnknownFile,- /// Begins with a YAML frontmatter delimiter this tool never writes.- LocalFrontmatter,}impl DivergentReason {@@ -56,10 +55,6 @@ impl DivergentReason {match self {Self::LocalEdit => "edited locally since the last export",Self::UnknownFile => "exists on disk but was never written by wikisync",- Self::LocalFrontmatter => {- "edited locally since the last export (file begins with a YAML \- frontmatter delimiter; wikisync never writes frontmatter)"- }}}}@@ -166,14 +161,23 @@ pub fn classify(Some(_) => Classification::Write(WriteKind::Update),},(Some(_), None) => Classification::Divergent(DivergentReason::UnknownFile),- (Some(disk), Some(_)) => {- if disk.starts_with(b"---") {- Classification::Divergent(DivergentReason::LocalFrontmatter)- } else {- Classification::Divergent(DivergentReason::LocalEdit)- }- }+ (Some(_), Some(_)) => Classification::Divergent(DivergentReason::LocalEdit),+ }+}++/// The file bytes for a server page: its round-trippable metadata as+/// frontmatter, then the body verbatim. Export and sync write the same+/// bytes, so the two never disagree about whether a file is current.+pub fn render_page(page: &ApiPage) -> Result<String> {+ if page.body_markdown.len() > MAX_BODY_BYTES {+ bail!(+ "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",+ page.path,+ page.body_markdown.len()+ );}+ let meta = PageMeta::from_server(&page.title, &page.tier, page.pinned, &page.frontmatter);+ Ok(page_file::render(&meta, &page.body_markdown))}/// Bounded, printable diff summary for a divergent file: sizes, line counts@@ -303,7 +307,7 @@ pub fn select_pages(summaries: Vec<PageSummary>, families: &[String]) -> Result<Ok(selected)}-fn read_disk(dest_root: &Path, path: &str) -> Result<Option<Vec<u8>>> {+pub(crate) fn read_disk(dest_root: &Path, path: &str) -> Result<Option<Vec<u8>>> {let target = paths::secure_join(dest_root, path)?;match fs::read(&target) {Ok(bytes) => Ok(Some(bytes)),@@ -346,16 +350,7 @@ async fn run_batch(let read = client.read_page(&args.workspace, &args.project, &page.path, etag_hint).await?;- let mut body = read.page.map(|api_page| api_page.body_markdown);- if let Some(body) = body.as_ref()- && body.len() > MAX_BODY_BYTES- {- bail!(- "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",- page.path,- body.len()- );- }+ let mut body = read.page.as_ref().map(render_page).transpose()?;let mut decision = classify(disk.as_deref(),base,@@ -367,16 +362,7 @@ async fn run_batch(let refetch = client.read_page(&args.workspace, &args.project, &page.path, None).await?;- body = refetch.page.map(|api_page| api_page.body_markdown);- if let Some(body) = body.as_ref()- && body.len() > MAX_BODY_BYTES- {- bail!(- "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",- page.path,- body.len()- );- }+ body = refetch.page.as_ref().map(render_page).transpose()?;decision = classify(disk.as_deref(),base,@@ -545,7 +531,7 @@ fn print_report(args: &RunArgs, report: &Report, mode: Mode, families: &[String]}}-fn print_git_hints(args: &RunArgs) {+pub(crate) fn print_git_hints(args: &RunArgs) {println!("this tool never runs git; to commit the export you may run:\\n git add -- {}\@@ -560,7 +546,7 @@ fn print_git_hints(args: &RunArgs) {/// Validate the destination root. `Apply` creates a missing directory;/// dry-run modes never touch the filesystem, so for them a missing/// destination is simply an empty destination (validated only lexically).-fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {+pub(crate) fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {match mode {Mode::Apply => paths::prepare_dest(dest),Mode::Plan | Mode::DryRun => {@@ -659,13 +645,6 @@ mod tests {classify(Some(edited), None, Some(server)),Classification::Divergent(DivergentReason::UnknownFile));- // Frontmatter this tool never wrote reads as a local edit with a- // specific reason.- let with_fm = b"---\ntitle: forged\n---\n# page\n";- assert_eq!(- classify(Some(with_fm), Some(&base(&disk_hash, None)), Some(server)),- Classification::Divergent(DivergentReason::LocalFrontmatter)- );}#[test]diff --git a/companions/ai-memory-wikisync/tests/api_server.rs b/companions/ai-memory-wikisync/tests/api_server.rsindex fdd06942..9124cf9e 100644--- a/companions/ai-memory-wikisync/tests/api_server.rs+++ b/companions/ai-memory-wikisync/tests/api_server.rs@@ -6,43 +6,89 @@ use std::collections::BTreeMap;use std::fs;use std::net::SocketAddr;use std::path::PathBuf;-use std::sync::Arc;use std::sync::atomic::{AtomicUsize, Ordering};+use std::sync::{Arc, Mutex};+use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};use ai_memory_wikisync::state::{self, SyncState};use ai_memory_wikisync::sync::{Mode, RunArgs, run};use axum::extract::{Path, Query, State};use axum::http::{HeaderMap, StatusCode, header};use axum::response::IntoResponse;-use axum::routing::get;+use axum::routing::{get, post};use axum::{Json, Router};use serde_json::json;use tokio::net::TcpListener;+/// One fixture page: what the real server's page read returns, reduced to+/// the fields wikisync reads.+#[derive(Clone)]+struct FixturePage {+ path: String,+ body: String,+ title: String,+ tier: String,+ pinned: bool,+ frontmatter: serde_json::Value,+}++impl FixturePage {+ fn new(path: &str, body: &str) -> Self {+ Self {+ path: path.to_string(),+ body: body.to_string(),+ title: format!("title {path}"),+ tier: "semantic".to_string(),+ pinned: false,+ frontmatter: json!({}),+ }+ }+}+/// Fixture server state: pages, optional bearer token, call counters.struct Fixture {- /// (path, body) in listing order.- pages: Vec<(String, String)>,+ /// Pages in listing order.+ pages: Mutex<Vec<FixturePage>>,token: Option<&'static str>,project_exists: bool,/// Page advertised by the listing but missing on read, to simulate a/// delete/expiry racing the run.unreachable: Option<&'static str>,+ /// Rewrite this page's body on its Nth read (1-based), to simulate an+ /// edit landing between a sync's classification and its write.+ edit_on_read: Option<(&'static str, usize)>,+ /// Text the fixture's write path redacts, like the server's sanitizer.+ redact: Option<&'static str>,+ reads_by_path: Mutex<BTreeMap<String, usize>>,recent_calls: AtomicUsize,page_reads_200: AtomicUsize,page_reads_304: AtomicUsize,+ mcp_writes: AtomicUsize,}impl Fixture {fn new(pages: Vec<(String, String)>) -> Self {+ Self::with_pages(+ pages+ .iter()+ .map(|(path, body)| FixturePage::new(path, body))+ .collect(),+ )+ }++ fn with_pages(pages: Vec<FixturePage>) -> Self {Self {- pages,+ pages: Mutex::new(pages),token: None,project_exists: true,unreachable: None,+ edit_on_read: None,+ redact: None,+ reads_by_path: Mutex::new(BTreeMap::new()),recent_calls: AtomicUsize::new(0),page_reads_200: AtomicUsize::new(0),page_reads_304: AtomicUsize::new(0),+ mcp_writes: AtomicUsize::new(0),}}@@ -61,11 +107,26 @@ impl Fixture {self}- fn body_of(&self, path: &str) -> Option<&str> {+ fn page(&self, path: &str) -> Option<FixturePage> {self.pages+ .lock()+ .unwrap().iter()- .find(|(candidate, _)| candidate == path)- .map(|(_, body)| body.as_str())+ .find(|page| page.path == path)+ .cloned()+ }++ fn update(&self, path: &str, edit: impl FnOnce(&mut FixturePage)) {+ let mut pages = self.pages.lock().unwrap();+ let page = pages+ .iter_mut()+ .find(|page| page.path == path)+ .expect("fixture page");+ edit(page);+ }++ fn remove(&self, path: &str) {+ self.pages.lock().unwrap().retain(|page| page.path != path);}fn authorize(&self, headers: &HeaderMap) -> Result<(), Box<axum::response::Response>> {@@ -111,21 +172,22 @@ async fn recent_handler(.and_then(|value| value.strip_prefix("idx:")).and_then(|value| value.parse().ok()).unwrap_or(0);- let end = (start + 2).min(fixture.pages.len());- let pages: Vec<serde_json::Value> = fixture.pages[start..end]+ let all = fixture.pages.lock().unwrap().clone();+ let end = (start + 2).min(all.len());+ let pages: Vec<serde_json::Value> = all[start..end].iter().enumerate()- .map(|(offset, (path, _))| {+ .map(|(offset, page)| {json!({- "path": path,- "title": format!("title {path}"),+ "path": page.path,+ "title": page.title,"kind": "note","tier": "semantic","updated_at": format!("2026-10-0{}T00:00:00Z", start + offset + 1),})}).collect();- let next_cursor = if end < fixture.pages.len() {+ let next_cursor = if end < all.len() {json!(format!("idx:{end}"))} else {json!(null)@@ -152,10 +214,45 @@ async fn page_handler(if fixture.unreachable == Some(path.as_str()) {return error_json(StatusCode::NOT_FOUND, "page not found");}- let Some(body) = fixture.body_of(&path) else {+ let read_count = {+ let mut reads = fixture.reads_by_path.lock().unwrap();+ let count = reads.entry(path.clone()).or_insert(0);+ *count += 1;+ *count+ };+ if let Some((target, nth)) = fixture.edit_on_read+ && target == path+ && nth == read_count+ {+ fixture.update(&path, |page| page.body.push_str("edited concurrently\n"));+ }+ let Some(page) = fixture.page(&path) else {return error_json(StatusCode::NOT_FOUND, "page not found");};- let etag = format!("\"{}\"", state::sha256_hex(body.as_bytes()));+ let mut frontmatter = page.frontmatter.clone();+ frontmatter["tier"] = json!(page.tier);+ if page.pinned {+ frontmatter["pinned"] = json!(true);+ }+ let document = json!({+ "project": project,+ "workspace": workspace,+ "path": path,+ "title": page.title,+ "kind": "note",+ "tier": page.tier,+ "pinned": page.pinned,+ "created_at": "2026-10-01T00:00:00Z",+ "updated_at": "2026-10-01T00:00:00Z",+ "supersedes": null,+ "frontmatter": frontmatter,+ "body_markdown": page.body,+ "links": [],+ "backlinks": [],+ });+ // Like the server: the ETag covers the whole projection, so a change to+ // metadata alone also changes it.+ let etag = format!("\"{}\"", state::sha256_hex(document.to_string().as_bytes()));if let Some(if_none_match) = headers.get(header::IF_NONE_MATCH).and_then(|v| v.to_str().ok())@@ -176,26 +273,65 @@ async fn page_handler((header::ETAG, etag),(header::CONTENT_TYPE, "application/json".to_string()),],- Json(json!({- "project": project,- "workspace": workspace,- "path": path,- "title": format!("title {path}"),- "kind": "note",- "tier": "semantic",- "pinned": false,- "created_at": "2026-10-01T00:00:00Z",- "updated_at": "2026-10-01T00:00:00Z",- "supersedes": null,- "frontmatter": {},- "body_markdown": body,- "links": [],- "backlinks": [],- })),+ Json(document),).into_response()}+/// `POST /mcp` `tools/call memory_write_page` with the server's replace+/// semantics: every field the call omits is cleared, and the stored body+/// passes a redaction step like the server's sanitizer.+async fn mcp_handler(+ State(fixture): State<Arc<Fixture>>,+ headers: HeaderMap,+ Json(request): Json<serde_json::Value>,+) -> axum::response::Response {+ if let Err(response) = fixture.authorize(&headers) {+ return *response;+ }+ let accept = headers+ .get(header::ACCEPT)+ .and_then(|value| value.to_str().ok())+ .unwrap_or_default();+ if !(accept.contains("application/json") && accept.contains("text/event-stream")) {+ return StatusCode::NOT_ACCEPTABLE.into_response();+ }+ let args = &request["params"]["arguments"];+ if request["params"]["name"] != "memory_write_page"+ || args["workspace"] != "demo"+ || args["project"] != "app"+ {+ return Json(json!({"jsonrpc": "2.0", "id": request["id"],+ "result": {"isError": true, "content": [{"type": "text", "text": "bad call"}]}}))+ .into_response();+ }+ fixture.mcp_writes.fetch_add(1, Ordering::SeqCst);+ let path = args["path"].as_str().unwrap_or_default().to_string();+ let mut body = args["body"].as_str().unwrap_or_default().to_string();+ if let Some(secret) = fixture.redact {+ body = body.replace(secret, "[REDACTED]");+ }+ let mut written = FixturePage::new(&path, &body);+ if let Some(title) = args["title"].as_str() {+ written.title = title.to_string();+ }+ if let Some(tier) = args["tier"].as_str() {+ written.tier = tier.to_string();+ }+ written.pinned = args["pinned"].as_bool().unwrap_or(false);+ if let Some(tags) = args["tags"].as_array().filter(|tags| !tags.is_empty()) {+ written.frontmatter = json!({ "tags": tags });+ }+ {+ let mut pages = fixture.pages.lock().unwrap();+ pages.retain(|page| page.path != path);+ pages.push(written);+ }+ Json(json!({"jsonrpc": "2.0", "id": request["id"],+ "result": {"isError": false, "content": [{"type": "text", "text": "{}"}]}}))+ .into_response()+}+async fn serve(fixture: Fixture) -> (SocketAddr, Arc<Fixture>) {let shared = Arc::new(fixture);let app = Router::new()@@ -207,6 +343,7 @@ async fn serve(fixture: Fixture) -> (SocketAddr, Arc<Fixture>) {"/api/v1/workspaces/{workspace}/projects/{project}/pages/{*path}",get(page_handler),)+ .route("/mcp", post(mcp_handler)).with_state(shared.clone());let listener = TcpListener::bind("127.0.0.1:0").await@@ -246,6 +383,12 @@ fn fixture_pages() -> Vec<(String, String)> {]}+/// The file export writes for a fixture page: the fixture's title as+/// frontmatter, then the body verbatim.+fn file(path: &str, body: &str) -> Vec<u8> {+ format!("---\ntitle: \"title {path}\"\n---\n{body}").into_bytes()+}+fn temp_dest() -> (tempfile::TempDir, PathBuf) {let tmp = tempfile::tempdir().expect("tempdir");// Canonicalize so the symlink-free destination guard passes on every OS.@@ -272,10 +415,13 @@ async fn export_apply_writes_files_and_state() {.await.expect("first export");- assert_eq!(fs::read(dest.join("notes/a.md")).unwrap(), b"# A\nalpha\n");+ assert_eq!(+ fs::read(dest.join("notes/a.md")).unwrap(),+ file("notes/a.md", "# A\nalpha\n")+ );assert_eq!(fs::read(dest.join("_rules/postgres.md")).unwrap(),- b"# Postgres only\nUse Postgres.\n"+ file("_rules/postgres.md", "# Postgres only\nUse Postgres.\n"));// Only allowlisted families land on disk.assert!(!dest.join("decisions/0001-db.md").exists());@@ -341,7 +487,10 @@ async fn local_edits_are_refused_until_forced() {b"# B\nlocally edited\n","diverged file is untouched");- assert_eq!(fs::read(dest.join("notes/a.md")).unwrap(), b"# A\nalpha\n");+ assert_eq!(+ fs::read(dest.join("notes/a.md")).unwrap(),+ file("notes/a.md", "# A\nalpha\n")+ );assert_eq!(fs::read(dest.join("notes/zz-new.md")).unwrap(),b"# local\n",@@ -353,7 +502,10 @@ async fn local_edits_are_refused_until_forced() {run(&force_args, Mode::Apply).await.expect("--force exports");- assert_eq!(fs::read(dest.join("notes/b.md")).unwrap(), b"# B\nbeta\n");+ assert_eq!(+ fs::read(dest.join("notes/b.md")).unwrap(),+ file("notes/b.md", "# B\nbeta\n")+ );assert_eq!(fs::read(dest.join("notes/zz-new.md")).unwrap(),b"# local\n",@@ -363,7 +515,7 @@ async fn local_edits_are_refused_until_forced() {let state = state::load(&dest).unwrap();assert_eq!(state.pages["notes/b.md"].hash,- state::sha256_hex(b"# B\nbeta\n")+ state::sha256_hex(&file("notes/b.md", "# B\nbeta\n")));}@@ -500,7 +652,316 @@ async fn empty_state_after_user_deletes_local_file_recreates_it() {run(&args(addr, &dest, &["notes"]), Mode::Apply).await.expect("recreate");- assert_eq!(fs::read(dest.join("notes/b.md")).unwrap(), b"# B\nbeta\n");+ assert_eq!(+ fs::read(dest.join("notes/b.md")).unwrap(),+ file("notes/b.md", "# B\nbeta\n")+ );let state: SyncState = state::load(&dest).unwrap();assert!(state.pages.contains_key("notes/b.md"));}++fn sync_args(addr: SocketAddr, dest: &std::path::Path, prefer: Option<Prefer>) -> SyncArgs {+ SyncArgs {+ run: args(addr, dest, &["decisions"]),+ prefer,+ }+}++async fn sync(addr: SocketAddr, dest: &std::path::Path) -> anyhow::Result<()> {+ bidi::run(&sync_args(addr, dest, None), true).await+}++fn decision() -> FixturePage {+ let mut page = FixturePage::new("decisions/db.md", "# DB\nUse Postgres.\n");+ page.title = "DB".to_string();+ page.frontmatter = json!({"tags": ["db"]});+ page.pinned = true;+ page+}++const DECISION_FILE: &str =+ "---\ntitle: \"DB\"\ntags: [\"db\"]\npinned: true\n---\n# DB\nUse Postgres.\n";++#[tokio::test]+async fn sync_exports_metadata_and_round_trips_without_writes() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ DECISION_FILE+ );++ sync(addr, &dest).await.expect("second sync");+ assert_eq!(+ fixture.mcp_writes.load(Ordering::SeqCst),+ 0,+ "nothing to import"+ );+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ DECISION_FILE+ );+}++#[tokio::test]+async fn sync_imports_a_repo_edit_with_its_metadata() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ let edited =+ "---\ntitle: \"DB\"\ntags: [\"db\", \"ops\"]\npinned: true\n---\n# DB\nUse Postgres 17.\n";+ fs::write(dest.join("decisions/db.md"), edited).unwrap();+ // Dry-run first: nothing reaches the server.+ bidi::run(&sync_args(addr, &dest, None), false)+ .await+ .expect("dry run");+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);++ sync(addr, &dest).await.expect("import");+ let page = fixture.page("decisions/db.md").unwrap();+ assert_eq!(page.body, "# DB\nUse Postgres 17.\n");+ assert!(+ page.pinned,+ "the write re-sent pinned, so the replace kept it"+ );+ assert_eq!(page.frontmatter["tags"], json!(["db", "ops"]));+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ edited+ );++ sync(addr, &dest).await.expect("settled");+ assert_eq!(+ fixture.mcp_writes.load(Ordering::SeqCst),+ 1,+ "a settled page is not written again"+ );+}++#[tokio::test]+async fn sync_creates_new_repo_pages_only_with_frontmatter() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ fs::write(dest.join("decisions/cache.md"), "# Cache\nUse Redis.\n").unwrap();+ let err = sync(addr, &dest)+ .await+ .expect_err("a file without frontmatter is refused");+ assert!(err.to_string().contains("refused"), "{err}");+ assert!(fixture.page("decisions/cache.md").is_none());+ assert_eq!(+ fixture.mcp_writes.load(Ordering::SeqCst),+ 0,+ "a refusal blocks the whole batch"+ );++ fs::write(+ dest.join("decisions/cache.md"),+ "---\ntitle: \"Cache\"\n---\n# Cache\nUse Redis.\n",+ )+ .unwrap();+ sync(addr, &dest).await.expect("create");+ let page = fixture+ .page("decisions/cache.md")+ .expect("created on the server");+ assert_eq!(page.title, "Cache");+ assert_eq!(page.body, "# Cache\nUse Redis.\n");+ // Pages outside the allowlist never travel.+ fs::create_dir_all(dest.join("notes")).unwrap();+ fs::write(dest.join("notes/x.md"), "---\ntitle: \"X\"\n---\nx\n").unwrap();+ sync(addr, &dest).await.expect("notes ignored");+ assert!(fixture.page("notes/x.md").is_none());+}++#[tokio::test]+async fn sync_conflicts_until_a_side_is_preferred() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ let repo_edit = DECISION_FILE.replace("Use Postgres.", "Use Postgres in the repo.");+ fs::write(dest.join("decisions/db.md"), &repo_edit).unwrap();+ fixture.update("decisions/db.md", |page| {+ page.body = "# DB\nUse Postgres on the server.\n".into()+ });++ let err = sync(addr, &dest).await.expect_err("conflict");+ assert!(err.to_string().contains("refused"), "{err}");+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ repo_edit+ );+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);++ bidi::run(&sync_args(addr, &dest, Some(Prefer::Server)), true)+ .await+ .expect("prefer server");+ assert!(+ fs::read_to_string(dest.join("decisions/db.md"))+ .unwrap()+ .contains("on the server")+ );++ fs::write(dest.join("decisions/db.md"), &repo_edit).unwrap();+ fixture.update("decisions/db.md", |page| {+ page.body = "# DB\nAgain on the server.\n".into()+ });+ bidi::run(&sync_args(addr, &dest, Some(Prefer::Repo)), true)+ .await+ .expect("prefer repo");+ assert!(+ fixture+ .page("decisions/db.md")+ .unwrap()+ .body+ .contains("in the repo")+ );+}++#[tokio::test]+async fn sync_refuses_to_clear_metadata_it_cannot_round_trip() {+ let mut consolidated = decision();+ consolidated.frontmatter = json!({"tags": ["db"], "summary": "s", "sources": ["x"]});+ let (addr, fixture) = serve(Fixture::with_pages(vec![consolidated])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("export still works");++ let edited = fs::read_to_string(dest.join("decisions/db.md"))+ .unwrap()+ .replace("Use Postgres.", "Edited.");+ fs::write(dest.join("decisions/db.md"), edited).unwrap();+ let err = sync(addr, &dest).await.expect_err("import refused");+ assert!(err.to_string().contains("refused"), "{err}");+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);+ assert_eq!(+ fixture.page("decisions/db.md").unwrap().frontmatter["summary"],+ "s"+ );+}++#[tokio::test]+async fn sync_stops_when_the_server_page_changes_before_the_write() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ fs::write(+ dest.join("decisions/db.md"),+ DECISION_FILE.replace("Use Postgres.", "Repo edit."),+ )+ .unwrap();++ // Reads so far: 1 by the first sync. The second sync classifies with+ // read 2 (a 304) and 3 (the full page for the import); read 4 is the+ // re-check right before the write, and lands after an edit.+ let fixture_with_race = Fixture {+ edit_on_read: Some(("decisions/db.md", 4)),+ ..Fixture::with_pages(vec![fixture.page("decisions/db.md").unwrap()])+ };+ let (race_addr, raced) = serve(fixture_with_race).await;+ // Seed the race server's read counter like the first server's.+ raced+ .reads_by_path+ .lock()+ .unwrap()+ .insert("decisions/db.md".into(), 1);+ let err = sync(race_addr, &dest).await.expect_err("race detected");+ assert!(+ format!("{err:#}").contains("changed on the server during this run"),+ "{err:#}"+ );+ assert_eq!(+ raced.mcp_writes.load(Ordering::SeqCst),+ 0,+ "the write never happened"+ );+}++#[tokio::test]+async fn sync_reports_deletes_and_never_propagates_them() {+ let mut other = decision();+ other.path = "decisions/other.md".to_string();+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ fixture.remove("decisions/db.md");+ fs::remove_file(dest.join("decisions/other.md")).unwrap();+ sync(addr, &dest)+ .await+ .expect("deletes are notices, not refusals");+ assert!(+ dest.join("decisions/db.md").exists(),+ "server delete not propagated"+ );+ assert!(+ fixture.page("decisions/other.md").is_some(),+ "repo delete not propagated"+ );+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);++ fs::remove_file(dest.join("decisions/db.md")).unwrap();+ sync(addr, &dest).await.expect("gone on both sides");+ assert!(+ !state::load(&dest)+ .unwrap()+ .pages+ .contains_key("decisions/db.md")+ );+}++#[tokio::test]+async fn sync_adopts_the_server_rendering_after_an_import() {+ let fixture = Fixture {+ redact: Some("hunter2"),+ ..Fixture::with_pages(vec![decision()])+ };+ let (addr, fixture) = serve(fixture).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ fs::write(+ dest.join("decisions/db.md"),+ DECISION_FILE.replace("Use Postgres.", "password hunter2"),+ )+ .unwrap();+ sync(addr, &dest).await.expect("import");+ let file = fs::read_to_string(dest.join("decisions/db.md")).unwrap();+ assert!(+ file.contains("[REDACTED]") && !file.contains("hunter2"),+ "{file}"+ );++ sync(addr, &dest).await.expect("settled");+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 1);+}++#[tokio::test]+async fn sync_upgrades_a_slice_one_export_without_importing() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ // What slice 1 left behind: the bare body, and its hash as the base.+ fs::create_dir_all(dest.join("decisions")).unwrap();+ fs::write(dest.join("decisions/db.md"), "# DB\nUse Postgres.\n").unwrap();+ let mut old = SyncState::default();+ old.pages.insert(+ "decisions/db.md".into(),+ state::PageState {+ hash: state::sha256_hex(b"# DB\nUse Postgres.\n"),+ etag: None,+ },+ );+ state::save(&dest, &old).unwrap();++ sync(addr, &dest).await.expect("upgrade");+ assert_eq!(+ fixture.mcp_writes.load(Ordering::SeqCst),+ 0,+ "an unedited file is not imported"+ );+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ DECISION_FILE+ );+}diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex a48d1251..9c1c15f6 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -79,8 +79,9 @@ the public MCP write/delete tools. It must never open the wiki directory orSQLite directly. The core read seam is `/api/v1` in API-only mode; the supportedMCP page arguments are documented in [programmatic memory](programmatic-memory.md).-Slice 1 (read-only export) shipped as-[`ai-memory-wikisync`](#ai-memory-wikisync-read-only-team-wiki-export)+Slice 1 (read-only export) and slice 3 (two-way sync through the MCP write+tool) ship as+[`ai-memory-wikisync`](#ai-memory-wikisync-team-wiki-export-and-sync)below; the remaining slices are tracked in #986.## `ai-memory-client`: shared private capture privacy@@ -234,9 +235,9 @@ Re-home by kind:6. Only after repeated usage, consider whether ai-memory core lacks a small,generic API seam; do not start by patching core endpoints.-## `ai-memory-wikisync`: read-only team-wiki export+## `ai-memory-wikisync`: team-wiki export and sync-Slice 1 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)+Slices 1 and 3 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)shape, implemented at [`companions/ai-memory-wikisync`](../companions/ai-memory-wikisync)as a standalone Cargo package with its own `[workspace]` (mirroring theimporter): it is not a member of the root workspace and is not covered by@@ -246,21 +247,26 @@ root `cargo test --workspace`.Mirror a team's shared ai-memory pages into a project repository asreviewable markdown, so the wiki a team actually maintains can travel with-the code it documents — read-only, family-scoped, and dry-run by default.+the code it documents, and let reviewed repository edits flow back —+family-scoped and dry-run by default.### How it talks to ai-memory- `plan` (always dry-run) and `export` (dry-run unless `--apply`) againstthe documented read-only `/api/v1` surface: incremental `recent` listingwith cursor paging (legacy array accepted) plus single-page reads with- `ETag` / `If-None-Match` revalidation. No MCP, no admin routes, no- writes to the server.+ `ETag` / `If-None-Match` revalidation. No admin routes.+- `sync` (dry-run unless `--apply`) also writes to the server, and only+ through the public `memory_write_page` MCP tool with explicit `workspace`+ and `project`, so sanitization, admission and attribution apply. It never+ opens the wiki directory or SQLite.- `--include FAMILY` is an explicit, repeatable allowlist of top-levelwiki directories; at least one is required and a bare `*` is refused.- Auth is a bearer token via `--token` or `AI_MEMORY_AUTH_TOKEN` only;tokens are never logged or persisted.-- Writes exactly the server's canonical projection (path, title, body)- with no forged attribution/generated frontmatter. All local bookkeeping+- Each file is the server body under a fixed frontmatter of the fields a+ write round-trips (`title`, `tags`, `pinned`, and `tier` when not the+ default), never server-generated or attribution keys. All local bookkeepinglives in one state file under the destination(`.ai-memory-wikisync/state.json`, 0600, atomically replaced after eachsuccessful write batch). The directory ignores itself with a `.gitignore`@@ -281,6 +287,15 @@ the code it documents — read-only, family-scoped, and dry-run by default.(tmp + rename + fsync).- Page bodies are untrusted data, transported verbatim and never executedor rendered.+- `sync` changes one side only when the other is unchanged since the last+ sync; a page changed on both sides is refused until `--prefer repo` or+ `--prefer server`. Deletes are reported, never propagated (slice 4).+- An import requires the file's frontmatter (a write clears what it omits),+ and is refused for a server page carrying any metadata the write cannot+ carry (`summary`, `sources`, `kind`, …), naming the keys.+- Right before each import the server page is re-read and must still render+ to the classified bytes. MCP has no compare-and-write, so one read-to-write+ race window remains; that is the documented case for slice 2.### Validation@@ -293,14 +308,18 @@ cargo clippy --manifest-path companions/ai-memory-wikisync/Cargo.toml --all-targUnit tests cover the path-safety matrix, the allowlist rules, statehash/crash behavior and local-edit refusal; integration tests run thefull plan/export flow against a fixture axum server serving `/api/v1`-responses (200/ETag/304/401/404 and cursor pagination).+responses (200/ETag/304/401/404 and cursor pagination), and the sync flow+against the same fixture's `POST /mcp` with the server's replace semantics:+imports with metadata, creates, conflicts and `--prefer`, the+metadata-loss refusal, the pre-write race check, delete notices, sanitizer+rewrites and the upgrade of a slice 1 export.### Roadmap (#986)-1. This slice — read-only export into a project repository.+1. Read-only export into a project repository (shipped).2. Conditional mutation seam (compare-and-write) in core, if independentlyjustified.-3. Bidirectional apply through public write tools.+3. Bidirectional apply through public write tools (shipped as `sync`).4. Deletes and conflict reporting.5. Post-merge hook / CI integration.