From 8f2d4d12a71c61be6b5f1332ccc11e0fc2a5b77d Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 23:59:56 +0800 Subject: [PATCH 1/6] test(utils): pin what each frontmatter entry point returns today The readers in internal/utils locate the --- delimiters under different rules, so the same SKILL.md can give different answers depending on the entry point. Before they are rebuilt on one locator, these cases record each entry point's current result on the inputs where the rules differ (indented or late delimiters, unclosed and empty blocks, trailing spaces, CRLF, BOM, delimiters in the body) and on a line longer than the bufio.Scanner cap that the path readers silently stop at. Refs #449 --- .../utils/frontmatter_entrypoints_test.go | 260 ++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 internal/utils/frontmatter_entrypoints_test.go diff --git a/internal/utils/frontmatter_entrypoints_test.go b/internal/utils/frontmatter_entrypoints_test.go new file mode 100644 index 000000000..21d0224ed --- /dev/null +++ b/internal/utils/frontmatter_entrypoints_test.go @@ -0,0 +1,260 @@ +package utils + +import ( + "bufio" + "os" + "path/filepath" + "strings" + "testing" +) + +// fmSnapshot is what every frontmatter entry point returns for one SKILL.md. +type fmSnapshot struct { + SkillName string // ParseSkillName + Field string // ParseFrontmatterField(name) + Fields string // ParseFrontmatterFields(name) + List string // ParseFrontmatterList(targets), comma-joined + ListBytes string // ParseFrontmatterListFromBytes(targets), comma-joined + Map string // ParseFrontmatterMap: name, or "error: ..." + Body string // ReadSkillBody + Rewrite string // RewriteFrontmatterList(targets=[x]), which runs splitFrontmatterAndBody +} + +func snapshotFrontmatter(t *testing.T, content string) fmSnapshot { + t.Helper() + dir := t.TempDir() + path := filepath.Join(dir, "SKILL.md") + if err := os.WriteFile(path, []byte(content), 0644); err != nil { + t.Fatal(err) + } + + var s fmSnapshot + name, err := ParseSkillName(dir) + if err != nil { + t.Fatal(err) + } + s.SkillName = name + s.Field = ParseFrontmatterField(path, "name") + s.Fields = ParseFrontmatterFields(path, []string{"name"})["name"] + s.List = strings.Join(ParseFrontmatterList(path, "targets"), ",") + s.ListBytes = strings.Join(ParseFrontmatterListFromBytes([]byte(content), "targets"), ",") + if fm, err := ParseFrontmatterMap([]byte(content)); err != nil { + s.Map = "error: " + err.Error() + } else { + s.Map, _ = fm["name"].(string) + } + s.Body = ReadSkillBody(path) + if out, err := RewriteFrontmatterList([]byte(content), "targets", []string{"x"}); err != nil { + s.Rewrite = "error: " + err.Error() + } else { + s.Rewrite = string(out) + } + return s +} + +// The entry points locate the --- delimiters under different rules (issue #449), so the +// same file can give different answers. These cases pin each entry point's current answer +// on the inputs where the rules differ; they are not a statement of what is right. +func TestFrontmatterEntryPoints_DelimiterRules(t *testing.T) { + tests := []struct { + name string + content string + want fmSnapshot + }{ + { + name: "plain", + content: "---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "a", Body: "body", Rewrite: "---\nname: a\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "no frontmatter", + content: "# Title\n\nbody\n", + want: fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "", Map: "error: no frontmatter at the start", Body: "# Title\n\nbody", Rewrite: "---\ntargets:\n - x\n---\n# Title\n\nbody\n"}, + }, + { + name: "indented opening delimiter", + content: " ---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "body", Rewrite: "---\ntargets:\n - x\n---\n ---\nname: a\ntargets: [t]\n---\nbody\n"}, + }, + { + name: "indented closing delimiter", + content: "---\nname: a\ntargets: [t]\n ---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: unclosed frontmatter: no closing ---", Body: "body", Rewrite: "---\ntargets:\n - x\n---\n---\nname: a\ntargets: [t]\n ---\nbody\n"}, + }, + { + name: "blank line before the opening delimiter", + content: "\n---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "body", Rewrite: "---\nname: a\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "text before the opening delimiter", + content: "# Title\n---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "# Title\n---\nname: a\ntargets: [t]\n---\nbody", Rewrite: "---\ntargets:\n - x\n---\n# Title\n---\nname: a\ntargets: [t]\n---\nbody\n"}, + }, + { + name: "first line only starts with dashes", + content: "--- title\n---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "body", Rewrite: "---\nname: a\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "unclosed block", + content: "---\nname: a\ntargets: [t]\nbody: text\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: unclosed frontmatter: no closing ---", Body: "", Rewrite: "---\ntargets:\n - x\n---\n---\nname: a\ntargets: [t]\nbody: text\n"}, + }, + { + name: "trailing spaces after the delimiters", + content: "--- \nname: a\ntargets: [t]\n---\t \nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "body", Rewrite: "---\nname: a\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "CRLF line endings", + content: "---\r\nname: a\r\ntargets: [t]\r\n---\r\nbody\r\nmore\r\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "a", Body: "body\nmore", Rewrite: "---\ntargets:\n - x\n---\n---\r\nname: a\r\ntargets: [t]\r\n---\r\nbody\r\nmore\r\n"}, + }, + { + name: "BOM", + content: "\xef\xbb\xbf---\nname: a\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "", Map: "a", Body: "\ufeff---\nname: a\ntargets: [t]\n---\nbody", Rewrite: "---\ntargets:\n - x\n---\n\ufeff---\nname: a\ntargets: [t]\n---\nbody\n"}, + }, + { + name: "empty block", + content: "---\n---\nbody\n", + want: fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "", Map: "error: no frontmatter", Body: "body", Rewrite: "---\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "blank block", + content: "---\n\n---\nbody\n", + want: fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "", Map: "error: no frontmatter", Body: "body", Rewrite: "---\ntargets:\n - x\n---\nbody\n"}, + }, + { + name: "delimiters inside the body", + content: "---\nname: a\ntargets: [t]\n---\nbody\n---\nname: b\ntargets: [u]\n---\ntail\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "a", Body: "body\n---\nname: b\ntargets: [u]\n---\ntail", Rewrite: "---\nname: a\ntargets:\n - x\n---\nbody\n---\nname: b\ntargets: [u]\n---\ntail\n"}, + }, + { + name: "indented delimiter inside a block scalar", + content: "---\nname: a\ndescription: |\n ---\ntargets: [t]\n---\nbody\n", + want: fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "", ListBytes: "", Map: "a", Body: "targets: [t]\n---\nbody", Rewrite: "---\ndescription: |\n ---\nname: a\ntargets:\n - x\n---\nbody\n"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := snapshotFrontmatter(t, tt.content) + if got != tt.want { + t.Errorf("entry points changed:\n got %#v\nwant %#v", got, tt.want) + } + }) + } +} + +// The readers that take a path used to read through a bufio.Scanner, which stops without +// an error at the first line of bufio.MaxScanTokenSize bytes or more. The readers that +// take bytes have no such cap. +func TestFrontmatterEntryPoints_OverlongLine(t *testing.T) { + longest := strings.Repeat("x", bufio.MaxScanTokenSize-1) // still read + overlong := longest + "x" // stops the path readers + + t.Run("in the frontmatter", func(t *testing.T) { + fits := snapshotFrontmatter(t, "---\ndescription: "+longest[:len(longest)-len("description: ")]+"\nname: a\ntargets: [t]\n---\nbody\n") + if fits.SkillName != "a" || fits.Field != "a" || fits.Fields != "a" || fits.List != "t" || fits.Body != "body" { + t.Errorf("a line one byte under the cap must be read: %q %q %q %q %q", fits.SkillName, fits.Field, fits.Fields, fits.List, fits.Body) + } + + content := "---\nlicense: MIT\ndescription: " + overlong[:len(overlong)-len("description: ")] + "\nname: a\ntargets: [t]\n---\nbody\n" + path := filepath.Join(t.TempDir(), "SKILL.md") + if err := os.WriteFile(path, []byte(content), 0644); err != nil { + t.Fatal(err) + } + if got := ParseFrontmatterFields(path, []string{"license"})["license"]; got != "MIT" { + t.Errorf("the lines before the overlong one must still be read, got license %q", got) + } + + got := snapshotFrontmatter(t, content) + got.Rewrite = "" // carries the long line; covered by the delimiter cases + want := fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "t", Map: "a", Body: "", Rewrite: ""} + if got != want { + t.Errorf("entry points changed:\n got %#v\nwant %#v", got, want) + } + }) + + t.Run("in the body", func(t *testing.T) { + got := snapshotFrontmatter(t, "---\nname: a\ntargets: [t]\n---\nfirst\n"+overlong+"\nlast\n") + got.Rewrite = "" + want := fmSnapshot{SkillName: "a", Field: "a", Fields: "a", List: "t", ListBytes: "t", Map: "a", Body: "first", Rewrite: ""} + if got != want { + t.Errorf("entry points changed:\n got %#v\nwant %#v", got, want) + } + }) + + t.Run("before any delimiter", func(t *testing.T) { + content := overlong + "\n---\nname: a\ntargets: [t]\n---\nbody\n" + got := snapshotFrontmatter(t, content) + if got.Body != strings.TrimSpace(content) { + t.Errorf("ReadSkillBody must return the whole file, got %d bytes", len(got.Body)) + } + got.Body, got.Rewrite = "", "" + want := fmSnapshot{SkillName: "", Field: "", Fields: "", List: "", ListBytes: "t", Map: "error: no frontmatter at the start", Body: "", Rewrite: ""} + if got != want { + t.Errorf("entry points changed:\n got %#v\nwant %#v", got, want) + } + }) +} + +// A path that opens but cannot be read (a directory) is "no frontmatter", not an error. +func TestFrontmatterEntryPoints_UnreadablePath(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "SKILL.md") + if err := os.Mkdir(path, 0755); err != nil { + t.Fatal(err) + } + + if name, err := ParseSkillName(dir); name != "" || err != nil { + t.Errorf("ParseSkillName = %q, %v; want empty name and no error", name, err) + } + if got := ParseFrontmatterField(path, "name"); got != "" { + t.Errorf("ParseFrontmatterField = %q", got) + } + if got := ParseFrontmatterFields(path, []string{"name"}); len(got) != 0 { + t.Errorf("ParseFrontmatterFields = %v", got) + } + if got := ParseFrontmatterList(path, "targets"); got != nil { + t.Errorf("ParseFrontmatterList = %v", got) + } + if got := ReadSkillBody(path); got != "" { + t.Errorf("ReadSkillBody = %q", got) + } +} + +func TestParseSkillName_MissingFile(t *testing.T) { + if _, err := ParseSkillName(t.TempDir()); !os.IsNotExist(err) { + t.Errorf("err = %v, want not-exist", err) + } +} + +// CRLF inside values: the path readers dropped the \r per line, the bytes reader hands +// it to the YAML decoder. Both must give the same values. +func TestFrontmatterEntryPoints_CRLFValues(t *testing.T) { + content := "---\r\nname: a\r\ndescription: |\r\n one\r\n two\r\nsummary: >-\r\n three\r\n four\r\nquoted: \"five\r\n six\"\r\ntargets:\r\n - t\r\n - u\r\n---\r\nbody\r\n" + path := filepath.Join(t.TempDir(), "SKILL.md") + if err := os.WriteFile(path, []byte(content), 0644); err != nil { + t.Fatal(err) + } + + got := ParseFrontmatterFields(path, []string{"description", "summary", "quoted"}) + want := map[string]string{"description": "one\ntwo\n", "summary": "three four", "quoted": "five six"} + for k, v := range want { + if got[k] != v { + t.Errorf("ParseFrontmatterFields[%s] = %q, want %q", k, got[k], v) + } + } + if got := ParseFrontmatterField(path, "description"); got != "one two" { + t.Errorf("ParseFrontmatterField = %q", got) + } + if got := strings.Join(ParseFrontmatterList(path, "targets"), ","); got != "t,u" { + t.Errorf("ParseFrontmatterList = %q", got) + } + if got := strings.Join(ParseFrontmatterListFromBytes([]byte(content), "targets"), ","); got != "t,u" { + t.Errorf("ParseFrontmatterListFromBytes = %q", got) + } +} From c23daf8cccd31788dffe56f452af5a60ffb3e1a9 Mon Sep 17 00:00:00 2001 From: Willie Date: Wed, 7 Oct 2026 00:03:50 +0800 Subject: [PATCH 2/6] refactor(memory): move guidance plan and apply out of the dashboard handler The guidance rules (status ranking, mixed_modes, multiple_blocks, the plan token, and check -> backup -> recheck -> write) were methods on *Server, so they could only be exercised over HTTP with a configured server, and the recheck after backup depended on callers using the right helper. internal/memory now owns status, plan, and apply behind GuidanceStatus, PlanGuidance, and ApplyGuidance. The server resolves targets, assignments, shared extras, and project reach into a GuidanceInput, syncs shared copies through a callback after each written file, and maps results to JSON. Only ApplyGuidance reaches the write steps, so the recheck cannot be skipped. Note creation and guidance creation shared a copied O_EXCL create with delete-on-failure; both now use createExclusive. Each keeps its own behaviour: notes still chmod to 0644, guidance still creates parents. HTTP routes, shapes, status codes, and error codes are unchanged. The raw write allowances follow the calls to their new functions. Refs #450 --- internal/memory/commit.go | 39 +- internal/memory/guidance_plan.go | 430 +++++++++++++++ internal/memory/guidance_plan_test.go | 300 +++++++++++ internal/server/handler_memory_guidance.go | 489 +++--------------- .../server/handler_memory_guidance_test.go | 85 +-- internal/sourcefs/testdata/raw_writes.tsv | 8 +- wiki/architecture.md | 11 +- 7 files changed, 838 insertions(+), 524 deletions(-) create mode 100644 internal/memory/guidance_plan.go create mode 100644 internal/memory/guidance_plan_test.go diff --git a/internal/memory/commit.go b/internal/memory/commit.go index e631eda59..907f01e6b 100644 --- a/internal/memory/commit.go +++ b/internal/memory/commit.go @@ -30,32 +30,35 @@ func createNote(path, draft string) error { if err != nil { return err } - file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644) + err = createExclusive(path, func(file *os.File) error { + if err := file.Chmod(0644); err != nil { + return err + } + _, err := file.Write(data) + return err + }) if os.IsExist(err) { return ErrConflict } + return err +} + +// createExclusive creates path and fills it with write. It fails with an +// os.IsExist error, leaving the file alone, when path already exists; a file +// it created but could not finish is removed. +func createExclusive(path string, write func(*os.File) error) error { + file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644) if err != nil { return err } - committed := false - defer func() { - if !committed { - os.Remove(path) - } - }() - if err := file.Chmod(0644); err != nil { - file.Close() - return err + err = write(file) + if closeErr := file.Close(); err == nil { + err = closeErr } - if _, err := file.Write(data); err != nil { - file.Close() - return err + if err != nil { + os.Remove(path) } - if err := file.Close(); err != nil { - return err - } - committed = true - return nil + return err } // removeNote commits a deletion after the backup has completed. diff --git a/internal/memory/guidance_plan.go b/internal/memory/guidance_plan.go new file mode 100644 index 000000000..d3c0f5012 --- /dev/null +++ b/internal/memory/guidance_plan.go @@ -0,0 +1,430 @@ +package memory + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "os" + "path/filepath" + "slices" + "sort" + "strconv" + "unicode/utf8" + + "skillshare/internal/instructions" + syncpkg "skillshare/internal/sync" +) + +// Memory guidance is a marked block (see Instructions) added to the +// instruction files targets already read. Connecting never changes the +// config, assignments, or links: the block goes into the file the target +// reads, and everything outside the block is kept. Status only reports what +// the files and links show; it never claims an agent read the notes. + +// ErrGuidanceStale reports that a reviewed plan no longer matches the files +// or the config it was made from. +var ErrGuidanceStale = errors.New("instruction files changed since the preview; review the changes again") + +// GuidanceSource is one file in a target's read chain. +type GuidanceSource struct { + Read string // the path whose content the target gets + Write string // the real file to change for it; empty means Read, or its destination when Read is a link + Shared string // the shared instruction file it is, if any + Live bool // false when the shared file is attached but not synced +} + +// GuidanceReader is one target and the chain of files it reads. +type GuidanceReader struct { + Name string + Sources []GuidanceSource + Dest int // the source that receives a new block + MaxChars int +} + +// GuidanceInput is what the caller resolved from its config: the memory +// folder, the scope, and every target's read chain. +type GuidanceInput struct { + Root string // the memory folder + ProjectRoot string // empty in global scope + Readers []GuidanceReader + Config any // hashed into the plan token, so a config change makes a plan stale +} + +type GuidanceTarget struct { + Name string `json:"name"` + State string `json:"state"` // unconfigured, configured, outdated or broken + File string `json:"file,omitempty"` // where the block is, or would be written + Detail string `json:"detail,omitempty"` // why broken: modified, malformed, mixed_modes, not_synced, unreadable or unsupported + Mode string `json:"mode,omitempty"` // passive or active, when a block is found +} + +type GuidanceChange struct { + Path string `json:"path"` + Before string `json:"before"` + After string `json:"after"` + Targets []string `json:"targets"` + Created bool `json:"created"` + Shared string `json:"-"` // the shared instruction file Path is, if any +} + +type GuidanceSkip struct { + Target string `json:"target"` + Reason string `json:"reason"` +} + +type GuidanceWarning struct { + Code string `json:"code"` // also_read_by or over_limit + Path string `json:"path"` + Targets []string `json:"targets,omitempty"` + Target string `json:"target,omitempty"` + Limit int `json:"limit,omitempty"` + Chars int `json:"chars,omitempty"` +} + +type GuidancePlan struct { + Token string `json:"token"` + Changes []GuidanceChange `json:"changes"` + Skipped []GuidanceSkip `json:"skipped"` + Warnings []GuidanceWarning `json:"warnings"` +} + +// GuidanceFailure is one file that could not be written or synced. Err is +// ErrGuidanceStale when the file no longer matches its reviewed content. +type GuidanceFailure struct { + Path string + Err error +} + +// GuidanceResult lists the files ApplyGuidance wrote and what failed. +type GuidanceResult struct { + Applied []string + Failures []GuidanceFailure +} + +// guidanceSite is a target's chain and where a new block would go. +type guidanceSite struct { + GuidanceTarget + sources []GuidanceSource + dest int // the source that receives a new block + blocks int // live sources holding an intact block + shared string // shared file of File, for syncing copies + maxChars int +} + +func (in GuidanceInput) scope() string { + if in.ProjectRoot != "" { + return ScopeProject + } + return ScopeGlobal +} + +func (in GuidanceInput) instructions(mode string) string { + return Instructions(in.Root, in.ProjectRoot, mode) +} + +// realFile returns the file a write to path changes: a link's destination. +func realFile(path string) (string, error) { + info, err := os.Lstat(path) + if err != nil || info.Mode()&os.ModeSymlink == 0 { + return path, nil + } + return filepath.EvalSymlinks(path) +} + +// GuidanceStatus reports the state of every reader's chain. +func GuidanceStatus(in GuidanceInput) []GuidanceTarget { + sites := guidanceSites(in) + out := make([]GuidanceTarget, 0, len(sites)) + for _, site := range sites { + out = append(out, site.GuidanceTarget) + } + return out +} + +func guidanceSites(in GuidanceInput) []guidanceSite { + out := make([]guidanceSite, 0, len(in.Readers)) + for _, r := range in.Readers { + site := guidanceSite{GuidanceTarget: GuidanceTarget{Name: r.Name}, sources: slices.Clone(r.Sources), dest: r.Dest, maxChars: r.MaxChars} + for i, src := range site.sources { + if src.Write != "" { + continue + } + // The file may itself link elsewhere: change, preview and back up its real file. + write, err := realFile(src.Read) + if err != nil { + site.State, site.Detail, site.File = "broken", "unreadable", src.Read + } + site.sources[i].Write = write + } + out = append(out, resolveSite(site, in)) + } + return out +} + +// resolveSite sets the state from the chain: a current block anywhere the +// target reads wins; then a block it cannot be trusted with; then an +// outdated one. Without a block, site.dest receives it. Each block is checked +// against the text of the mode it records; blocks of different modes in one +// chain contradict each other, and rewriting one file would not fix that. +func resolveSite(site guidanceSite, in GuidanceInput) guidanceSite { + if site.State != "" { + return site + } + rank := map[string]int{StateConfigured: 4, StateModified: 3, StateMalformed: 3, StateOutdated: 2} + best, bestRank := -1, 0 + modes := map[string]bool{} + for i, src := range site.sources { + data, err := os.ReadFile(src.Read) + if err != nil && !os.IsNotExist(err) { + site.State, site.Detail, site.File = "broken", "unreadable", src.Write + return site + } + // JSON previews cannot show other encodings byte for byte, so such a + // file is never inspected or rewritten. + if !utf8.Valid(data) { + site.State, site.Detail, site.File = "broken", "unsupported", src.Write + return site + } + mode := Mode(string(data), in.scope()) + state := Inspect(string(data), in.instructions(mode)) + if !src.Live { + if state != StateUnconfigured { + site.State, site.Detail, site.File, site.shared = "broken", "not_synced", src.Write, src.Shared + return site + } + continue + } + if state != StateUnconfigured && state != StateMalformed { + modes[mode] = true + site.blocks++ + } + if rank[state] > bestRank { + best, bestRank = i, rank[state] + site.Detail, site.Mode = state, mode + } + } + if best >= 0 { + src := site.sources[best] + site.File, site.shared = src.Write, src.Shared + if len(modes) > 1 { + site.State, site.Detail, site.Mode = "broken", "mixed_modes", "" + return site + } + switch site.Detail { + case StateConfigured: + site.State, site.Detail = "configured", "" + case StateOutdated: + site.State, site.Detail = "outdated", "" + default: + site.State = "broken" + } + return site + } + site.State = "unconfigured" + dest := site.sources[site.dest] + if !dest.Live { + site.State, site.Detail = "broken", "not_synced" + } + site.File, site.shared = dest.Write, dest.Shared + return site +} + +// PlanGuidance builds the changes for the named targets, each in the mode +// modes gives it; a target left out keeps its block's mode, or gets passive. +// Targets reading one file share its block, so they must share a mode. The +// token hashes everything the plan depends on, so ApplyGuidance can reject a +// plan whose files or config changed after review. +func PlanGuidance(in GuidanceInput, names []string, modes map[string]string) (GuidancePlan, error) { + sites := guidanceSites(in) + byName := map[string]guidanceSite{} + for _, site := range sites { + byName[site.Name] = site + } + names = slices.Compact(slices.Sorted(slices.Values(names))) + if len(names) == 0 { + return GuidancePlan{}, errors.New("choose at least one target") + } + plan := GuidancePlan{Changes: []GuidanceChange{}, Skipped: []GuidanceSkip{}, Warnings: []GuidanceWarning{}} + index := map[string]int{} + chosen, fileModes := map[string]string{}, map[string]string{} + for _, name := range names { + site, ok := byName[name] + if !ok { + return GuidancePlan{}, errors.New("target has no instruction file: " + name) + } + mode, err := ParseMode(modes[name]) + if err != nil { + return GuidancePlan{}, err + } + if modes[name] == "" && site.Mode != "" { + mode = site.Mode + } + if other, ok := fileModes[site.File]; ok && other != mode && site.File != "" { + return GuidancePlan{}, errors.New("targets reading " + site.File + " share its guidance and must use the same mode") + } + fileModes[site.File], chosen[name] = mode, mode + switch { + case site.State == "configured" && site.Mode == mode: + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, "configured"}) + continue + case site.State == "broken": + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, site.Detail}) + continue + case site.Mode != mode && site.blocks > 1: + // Rewriting only site.File would leave the other blocks in the old mode. + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, "multiple_blocks"}) + continue + } + if i, ok := index[site.File]; ok { + plan.Changes[i].Targets = append(plan.Changes[i].Targets, name) + continue + } + want := in.instructions(mode) + data, readErr := os.ReadFile(site.File) + if readErr != nil && !os.IsNotExist(readErr) { + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, "unreadable"}) + continue + } + if !utf8.Valid(data) { + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, "unsupported"}) + continue + } + after, err := Apply(string(data), want) + if err != nil { + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, Inspect(string(data), want)}) + continue + } + if after == string(data) { + plan.Skipped = append(plan.Skipped, GuidanceSkip{name, "configured"}) + continue + } + index[site.File] = len(plan.Changes) + plan.Changes = append(plan.Changes, GuidanceChange{Path: site.File, Before: string(data), After: after, Targets: []string{name}, Created: os.IsNotExist(readErr), Shared: site.shared}) + } + for _, c := range plan.Changes { + // Every reader of the changed file is affected, selected or not. + var others []string + chars := utf8.RuneCountInString(c.After) + for _, site := range sites { + if !slices.ContainsFunc(site.sources, func(src GuidanceSource) bool { return src.Write == c.Path }) { + continue + } + if !slices.Contains(c.Targets, site.Name) { + others = append(others, site.Name) + } + if site.maxChars > 0 && chars > site.maxChars { + plan.Warnings = append(plan.Warnings, GuidanceWarning{Code: "over_limit", Path: c.Path, Target: site.Name, Limit: site.maxChars, Chars: chars}) + } + } + if len(others) > 0 { + sort.Strings(others) + plan.Warnings = append(plan.Warnings, GuidanceWarning{Code: "also_read_by", Path: c.Path, Targets: others}) + } + } + // Bind the routing too: a mode or assignment change can leave the + // reviewed text equal while changing which files the block reaches. + type route struct { + Name, State, Detail, File, Shared string + Sources [][4]string + } + routes := make([]route, 0, len(sites)) + for _, site := range sites { + r := route{site.Name, site.State, site.Detail, site.File, site.shared, nil} + for _, src := range site.sources { + r.Sources = append(r.Sources, [4]string{src.Read, src.Write, src.Shared, strconv.FormatBool(src.Live)}) + } + routes = append(routes, r) + } + data, err := json.Marshal(struct { + Root string + Names []string + Modes map[string]string + Plan GuidancePlan + Routes []route + Config any + }{in.Root, names, chosen, plan, routes, in.Config}) + if err != nil { + return GuidancePlan{}, err + } + sum := sha256.Sum256(data) + plan.Token = hex.EncodeToString(sum[:]) + return plan, nil +} + +// ApplyGuidance applies a reviewed plan only if recomputing it gives the same +// token; otherwise it returns ErrGuidanceStale and writes nothing. Each +// existing file is backed up before it is changed. written, when set, runs +// after each file is written, so the caller can sync its copies before the +// next file is checked; the failures it returns join the result. +func ApplyGuidance(in GuidanceInput, names []string, modes map[string]string, token string, written func(GuidanceChange) []GuidanceFailure) (GuidanceResult, error) { + plan, err := PlanGuidance(in, names, modes) + if err != nil { + return GuidanceResult{}, err + } + if token == "" || token != plan.Token { + return GuidanceResult{}, ErrGuidanceStale + } + res := GuidanceResult{Applied: []string{}, Failures: []GuidanceFailure{}} + for _, c := range plan.Changes { + if err := writeGuidanceChange(c); err != nil { + res.Failures = append(res.Failures, GuidanceFailure{Path: c.Path, Err: err}) + continue + } + res.Applied = append(res.Applied, c.Path) + if written != nil { + res.Failures = append(res.Failures, written(c)...) + } + } + return res, nil +} + +// backupGuidanceFile is replaced in tests to change a file during its backup. +var backupGuidanceFile = syncpkg.BackupFile + +// writeGuidanceChange rechecks each file as earlier writes and syncs may take +// time, and again after the backup, immediately before the write. +func writeGuidanceChange(c GuidanceChange) error { + if err := checkGuidanceChange(c); err != nil { + return err + } + if !c.Created { + if err := backupGuidanceFile(c.Path, syncpkg.BackupReasonEdit); err != nil { + return err + } + if err := checkGuidanceChange(c); err != nil { + return err + } + } + return commitGuidanceChange(c) +} + +// commitGuidanceChange writes a file after its final review check. A new +// file is created exclusively, so one a competing process made is kept. +func commitGuidanceChange(c GuidanceChange) error { + if !c.Created { + return instructions.WriteFile(c.Path, c.After) + } + if err := os.MkdirAll(filepath.Dir(c.Path), 0755); err != nil { + return err + } + err := createExclusive(c.Path, func(f *os.File) error { + _, err := f.WriteString(c.After) + return err + }) + if os.IsExist(err) { + return ErrGuidanceStale + } + return err +} + +func checkGuidanceChange(c GuidanceChange) error { + data, err := os.ReadFile(c.Path) + if err != nil && !os.IsNotExist(err) { + return err + } + if c.Created != os.IsNotExist(err) || string(data) != c.Before { + return ErrGuidanceStale + } + return nil +} diff --git a/internal/memory/guidance_plan_test.go b/internal/memory/guidance_plan_test.go new file mode 100644 index 000000000..3c44ea04e --- /dev/null +++ b/internal/memory/guidance_plan_test.go @@ -0,0 +1,300 @@ +package memory + +import ( + "errors" + "os" + "path/filepath" + "strings" + "testing" + + syncpkg "skillshare/internal/sync" +) + +func guidanceInput(t *testing.T, readers ...GuidanceReader) GuidanceInput { + t.Helper() + t.Setenv("XDG_STATE_HOME", filepath.Join(t.TempDir(), "state")) + return GuidanceInput{Root: filepath.Join(t.TempDir(), "memory"), Readers: readers} +} + +func guidanceReader(name string, files ...string) GuidanceReader { + r := GuidanceReader{Name: name} + for _, file := range files { + r.Sources = append(r.Sources, GuidanceSource{Read: file, Live: true}) + } + return r +} + +func writeText(t *testing.T, path, content string) string { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0644); err != nil { + t.Fatal(err) + } + return path +} + +func readText(t *testing.T, path string) string { + t.Helper() + data, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return string(data) +} + +func isStale(f GuidanceFailure) bool { return errors.Is(f.Err, ErrGuidanceStale) } + +func TestGuidancePlanAndApply(t *testing.T) { + dir := t.TempDir() + own := writeText(t, filepath.Join(dir, "own.md"), "own\n") + fresh := filepath.Join(dir, "new", "AGENTS.md") + in := guidanceInput(t, guidanceReader("a", own), guidanceReader("b", fresh)) + names := []string{"b", "a"} + + plan, err := PlanGuidance(in, names, nil) + if err != nil || len(plan.Changes) != 2 || plan.Changes[0].Created || !plan.Changes[1].Created || plan.Changes[0].Before != "own\n" { + t.Fatalf("plan = %+v, %v", plan, err) + } + var written []string + res, err := ApplyGuidance(in, names, nil, plan.Token, func(c GuidanceChange) []GuidanceFailure { + written = append(written, c.Path) + return nil + }) + if err != nil || len(res.Failures) != 0 || strings.Join(res.Applied, ",") != own+","+fresh || strings.Join(written, ",") != own+","+fresh { + t.Fatalf("apply = %+v, %v, written %v", res, err, written) + } + if got := readText(t, own); got != plan.Changes[0].After || !strings.HasPrefix(got, "own\n\n