diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bc1a5b0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## v0.9.0 + +- `mem-add` refuses (exit 2) an index line that does not link `.md`, + before writing anything. `` may carry `.md`. (#27) +- `mem-add ` alone builds the line from the memory's frontmatter + (`name`, `description`); a missing file or description is refused (exit 2). +- `mem-verify` no longer answers `ok` for text that names a memory without + linking it: reachability is the `orphans` walk. A legacy record whose line has + no link is reported `MISSING` and not re-inserted. (#27) diff --git a/README.md b/README.md index 958cc3f..161cb73 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ happened to message and ask. agentsync tell -- agentsync messages [--max-age 24h] agentsync forget - agentsync mem-add [--section "## Heading"] + agentsync mem-add [--section "## Heading"] [] agentsync mem-verify [--repair=false] agentsync orphans agentsync mem-fold [--section H] [--hub NAME] [--dry-run] @@ -155,8 +155,18 @@ path segment, so `go-tex` does not enclose `go-texinfo`. `mem-add` takes a lease on the index, inserts once, and **reads the file back** to confirm the line survived. Trusting the write would reproduce the bug. +`` is the file beside the index, with or without `.md`. The index +line must link it as `[title](.md)`; a line that does not is refused +with exit 2 before the index is touched (a text-only row points at nothing). +With no ``, mem-add builds `- [name](x.md): description` from the +memory's frontmatter, and refuses (exit 2) naming the missing file or +`description`. + `mem-verify` re-reads every entry this session registered and puts back the ones -that vanished, in the section they came from. +that vanished, in the section they came from. An entry is `ok` only when its line +is in the index AND links a memory that the walk from `MEMORY.md` through hubs +reaches (the rule `orphans` uses); text that merely names a memory is reported +`MISSING`, and is not re-inserted when the recorded line has no link. `orphans` reports the memories that NOTHING points at. It is the half `mem-verify` cannot do: that one repairs what this session wrote, and a memory diff --git a/cmd/agentsync/main.go b/cmd/agentsync/main.go index 2e3ece4..91d28f2 100644 --- a/cmd/agentsync/main.go +++ b/cmd/agentsync/main.go @@ -260,6 +260,40 @@ func withIndexLease(fn func() error) error { return fn() } +// usageError is a refusal for bad arguments; main exits 2 for it, not 1. +type usageError struct{ error } + +func (u usageError) Unwrap() error { return u.error } + +// lineFromFrontmatter builds "- [title](name.md): description" from the +// memory's own frontmatter, and refuses naming what is missing. +func lineFromFrontmatter(path, name string) (string, error) { + b, err := os.ReadFile(path) + if err != nil { + return "", usageError{fmt.Errorf("cannot build an index line: %s.md is not readable (%v); give the line as a second argument", name, err)} + } + fm := map[string]string{} + lines := strings.Split(string(b), "\n") + if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" { + for _, l := range lines[1:] { + if strings.TrimSpace(l) == "---" { + break + } + if k, v, ok := strings.Cut(l, ":"); ok { + fm[strings.TrimSpace(k)] = strings.Trim(strings.TrimSpace(v), `"'`) + } + } + } + if fm["description"] == "" { + return "", usageError{fmt.Errorf("cannot build an index line: %s.md has no frontmatter `description`; add one or give the line as a second argument", name)} + } + title := fm["name"] + if title == "" { + title = name + } + return fmt.Sprintf("- [%s](%s.md): %s", title, name, fm["description"]), nil +} + func memAdd(args []string) error { fs := flag.NewFlagSet("mem-add", flag.ExitOnError) section := fs.String("section", "", "append at the end of this heading's section") @@ -267,10 +301,32 @@ func memAdd(args []string) error { if err := fs.Parse(args); err != nil { return err } - if fs.NArg() != 2 { - return errors.New("usage: agentsync mem-add [--section H] ") + const usage = "usage: agentsync mem-add [--section H] []" + if fs.NArg() != 1 && fs.NArg() != 2 { + return usageError{errors.New(usage)} + } + // ⛔ The name is the file's stem; "x.md" is accepted and means "x". Passing + // the file name verbatim used to be recorded as "x.md" and match nothing. + name := strings.TrimSuffix(fs.Arg(0), ".md") + if name == "" || strings.ContainsAny(name, "/\\()") { + return usageError{fmt.Errorf("%s: %q is not a memory name (the file's name beside the index, without .md)", usage, fs.Arg(0))} + } + var line string + if fs.NArg() == 2 { + line = fs.Arg(1) + } else { + built, err := lineFromFrontmatter(filepath.Join(filepath.Dir(*idx), name+".md"), name) + if err != nil { + return err + } + line = built + } + // ⛔ agentsync#27: an index line that does not link the file is not an + // index line. mem-add reported "indexed" for text alone, and nothing + // pointed at the memory. Refuse BEFORE touching the index. + if !strings.Contains(line, "("+name+".md)") { + return usageError{fmt.Errorf("the index line must link the memory as [title](%s.md); %q does not (nothing would point at the file)", name, line)} } - name, line := fs.Arg(0), fs.Arg(1) err := withIndexLease(func() error { b, err := os.ReadFile(*idx) @@ -382,6 +438,19 @@ func reachedVia(r record, cache map[string]map[string]bool) bool { return got[r.Name+".md"] } +// lineReached reports whether the record's own line links a memory that the +// walk from the index reaches. +func lineReached(r record, cache map[string]map[string]bool) bool { + reachedVia(r, cache) // fills the cache for this index + got := cache[r.Index] + for _, m := range linkRE.FindAllStringSubmatch(r.Line, -1) { + if m[1] != "" && got[m[1]] { + return true + } + } + return false +} + func memVerify(args []string) error { reach := map[string]map[string]bool{} fs := flag.NewFlagSet("mem-verify", flag.ExitOnError) @@ -405,7 +474,13 @@ func memVerify(args []string) error { return err } - if strings.Contains(string(b), r.Line) { + // ⛔ agentsync#27: the recorded text being in the index is NOT + // reachability -- a line with no link names a memory nothing points at, + // and this used to answer "ok" for it. "ok" now needs the line to be + // present AND to link a memory the walk from the index reaches (the one + // definition orphans uses). A walk that could not read says nothing + // either way, so it falls through to the checks below. + if strings.Contains(string(b), r.Line) && lineReached(r, reach) { fmt.Printf("ok %s\n", r.Name) continue } @@ -488,6 +563,12 @@ func memVerify(args []string) error { fmt.Printf("MISSING %s\n", r.Name) continue } + // A record from before mem-add refused linkless lines: re-inserting its + // text would repeat the bug, so say what is needed instead. + if !strings.Contains(r.Line, "("+r.Name+".md)") { + fmt.Printf("MISSING %s (the recorded line has no link; add one with: agentsync mem-add %s)\n", r.Name, r.Name) + continue + } if err := withIndexLease(func() error { b, err := os.ReadFile(r.Index) if err != nil { @@ -875,6 +956,11 @@ func main() { os.Exit(2) } if err := fn(os.Args[2:]); err != nil { + var ue usageError + if errors.As(err, &ue) { + fmt.Fprintln(os.Stderr, "agentsync:", err) + os.Exit(2) + } if errors.Is(err, errUnavailable) { os.Exit(1) // a refusal is a result, not a crash } diff --git a/cmd/agentsync/memadd_test.go b/cmd/agentsync/memadd_test.go new file mode 100644 index 0000000..1dfd40a --- /dev/null +++ b/cmd/agentsync/memadd_test.go @@ -0,0 +1,171 @@ +package main + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" +) + +// agentsync#27: `mem-add file.md ""` printed "indexed" and appended the +// text alone, with no link; mem-verify then called the memory reachable. + +func memEnv(t *testing.T) (dir, index string) { + t.Helper() + dir = t.TempDir() + index = filepath.Join(dir, "MEMORY.md") + t.Setenv("AGENTSYNC_DIR", filepath.Join(t.TempDir(), "state")) + t.Setenv("AGENTSYNC_MEMORY", index) + t.Setenv("AGENTSYNC_OWNER", "test-session") + writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n") + return dir, index +} + +func indexText(t *testing.T, index string) string { + t.Helper() + b, err := os.ReadFile(index) + if err != nil { + t.Fatal(err) + } + return string(b) +} + +func isUsage(err error) bool { + var u usageError + return errors.As(err, &u) +} + +func TestMemAddRefusesALineThatDoesNotLinkTheFile(t *testing.T) { + for _, name := range []string{"a-lesson", "a-lesson.md"} { + t.Run(name, func(t *testing.T) { + dir, index := memEnv(t) + writeMem(t, dir, "a-lesson.md", "---\nname: a-lesson\ndescription: d\n---\nbody\n") + err := memAdd([]string{name, "⛔ plain text, no link"}) + if !isUsage(err) { + t.Fatalf("want a usage refusal (exit 2), got %v", err) + } + if !strings.Contains(err.Error(), "(a-lesson.md)") { + t.Errorf("refusal does not name the missing link: %v", err) + } + if strings.Contains(indexText(t, index), "plain text") { + t.Errorf("wrote a line that links nothing:\n%s", indexText(t, index)) + } + }) + } +} + +func TestMemAddAcceptsALinkedLineWithOrWithoutDotMd(t *testing.T) { + for _, name := range []string{"a-lesson", "a-lesson.md"} { + t.Run(name, func(t *testing.T) { + dir, index := memEnv(t) + writeMem(t, dir, "a-lesson.md", "body\n") + out := capture(t, func() { + if err := memAdd([]string{"--section", "## Lessons", name, "- [a lesson](a-lesson.md): why"}); err != nil { + t.Fatal(err) + } + }) + if !strings.Contains(out, "indexed a-lesson") { + t.Errorf("output %q", out) + } + if !strings.Contains(indexText(t, index), "- [a lesson](a-lesson.md): why") { + t.Errorf("row missing:\n%s", indexText(t, index)) + } + verify := capture(t, func() { _ = memVerify(nil) }) + if !strings.Contains(verify, "ok a-lesson") { + t.Errorf("verify: %s", verify) + } + }) + } +} + +func TestMemAddBuildsTheLinkFromTheFrontmatter(t *testing.T) { + dir, index := memEnv(t) + writeMem(t, dir, "a-lesson.md", "---\nname: A lesson\ndescription: what it taught\n---\nbody\n") + capture(t, func() { + if err := memAdd([]string{"a-lesson.md"}); err != nil { + t.Fatal(err) + } + }) + if !strings.Contains(indexText(t, index), "- [A lesson](a-lesson.md): what it taught") { + t.Errorf("built line wrong:\n%s", indexText(t, index)) + } + if got := capture(t, func() { _ = memVerify(nil) }); !strings.Contains(got, "ok a-lesson") { + t.Errorf("verify: %s", got) + } +} + +func TestMemAddOneArgRefusalsNameWhatIsMissing(t *testing.T) { + t.Run("no file", func(t *testing.T) { + _, index := memEnv(t) + err := memAdd([]string{"ghost"}) + if !isUsage(err) || !strings.Contains(err.Error(), "ghost.md") { + t.Errorf("got %v", err) + } + if strings.Contains(indexText(t, index), "ghost") { + t.Error("wrote something for a missing file") + } + }) + t.Run("no description", func(t *testing.T) { + dir, index := memEnv(t) + writeMem(t, dir, "bare.md", "---\nname: bare\n---\nbody\n") + err := memAdd([]string{"bare"}) + if !isUsage(err) || !strings.Contains(err.Error(), "description") { + t.Errorf("got %v", err) + } + if strings.Contains(indexText(t, index), "bare") { + t.Error("wrote something without a description") + } + }) + t.Run("no arguments and three arguments", func(t *testing.T) { + memEnv(t) + if err := memAdd(nil); !isUsage(err) { + t.Errorf("no args: %v", err) + } + if err := memAdd([]string{"a", "b", "c"}); !isUsage(err) { + t.Errorf("three args: %v", err) + } + }) +} + +// mem-verify must not trust its own record: text in the index that names the +// memory without linking it is not reachability. +func TestMemVerifyDoesNotCallPlainTextReachable(t *testing.T) { + dir, index := memEnv(t) + writeMem(t, dir, "a-lesson.md", "body\n") + capture(t, func() { + if err := memAdd([]string{"a-lesson", "- [a lesson](a-lesson.md): why"}); err != nil { + t.Fatal(err) + } + }) + _ = index + // A neighbour rewrites the row so the link is gone; the recorded line is + // no longer a substring either, but a variant that keeps the TEXT must + // not count: record the text-only form to model the legacy bug. + if err := saveRecords([]record{{Name: "a-lesson", Line: "a-lesson: why", Section: "## Lessons", Index: index}}); err != nil { + t.Fatal(err) + } + writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n- a-lesson: why\n") + out := capture(t, func() { _ = memVerify([]string{"--repair=false"}) }) + if strings.Contains(out, "still reachable") || strings.Contains(out, "ok a-lesson") { + t.Errorf("called an unlinked memory reachable:\n%s", out) + } +} + +// A legacy record whose line has no link is text-only: it must be reported, +// not "ok", even though the text sits in the index. +func TestMemVerifyReportsALegacyLinklessRecord(t *testing.T) { + dir, _ := memEnv(t) + writeMem(t, dir, "a-lesson.md", "body\n") + writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n⛔ plain text only\n") + if err := saveRecords([]record{{Name: "a-lesson", Line: "⛔ plain text only", Section: "## Lessons", Index: filepath.Join(dir, "MEMORY.md")}}); err != nil { + t.Fatal(err) + } + out := capture(t, func() { _ = memVerify([]string{"--repair=false"}) }) + if strings.Contains(out, "still reachable") || strings.Contains(out, "ok a-lesson") { + t.Errorf("text-only line called reachable:\n%s", out) + } + if !strings.Contains(out, "MISSING a-lesson") { + t.Errorf("not reported:\n%s", out) + } +}