Merge branch 'main' into runkids/arch-444-check-resolution

This commit is contained in:
Willie
2026-10-07 00:56:06 +08:00
committed by GitHub
11 changed files with 1483 additions and 831 deletions
+21 -18
View File
@@ -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.
+433
View File
@@ -0,0 +1,433 @@
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. Sources holds
// at least one file, and Dest indexes one of them.
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 as JSON 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
}
// Scope is ScopeProject when the input has a project root.
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. Invalid
// input returns PlanGuidance's error. Each existing file is backed up before
// it is changed. written, when set, runs after each file is written, shared or
// not, 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
}
+300
View File
@@ -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<!-- skillshare:memory scope=global") {
t.Errorf("own = %q", got)
}
if got := readText(t, fresh); got != plan.Changes[1].After {
t.Errorf("new file = %q", got)
}
if backups, err := syncpkg.FileBackupVersions(own); err != nil || len(backups) == 0 {
t.Errorf("backups of the changed file = %v, %v", backups, err)
}
for _, target := range GuidanceStatus(in) {
if target.State != "configured" || target.Mode != ModePassive {
t.Errorf("status = %+v", target)
}
}
if again, err := PlanGuidance(in, names, nil); err != nil || len(again.Changes) != 0 || len(again.Skipped) != 2 || again.Skipped[0].Reason != "configured" {
t.Errorf("second plan = %+v, %v", again, err)
}
}
func TestApplyGuidanceRejectsPlanStaleSinceReview(t *testing.T) {
own := writeText(t, filepath.Join(t.TempDir(), "own.md"), "own\n")
in := guidanceInput(t, guidanceReader("a", own))
names := []string{"a"}
plan, _ := PlanGuidance(in, names, nil)
writeText(t, own, "edited elsewhere\n")
if _, err := ApplyGuidance(in, names, nil, plan.Token, nil); !errors.Is(err, ErrGuidanceStale) {
t.Fatalf("file change: %v", err)
}
plan, _ = PlanGuidance(in, names, nil)
in.Config = "changed"
if _, err := ApplyGuidance(in, names, nil, plan.Token, nil); !errors.Is(err, ErrGuidanceStale) {
t.Fatalf("config change: %v", err)
}
if _, err := ApplyGuidance(in, names, nil, "", nil); !errors.Is(err, ErrGuidanceStale) {
t.Fatalf("empty token: %v", err)
}
if got := readText(t, own); got != "edited elsewhere\n" {
t.Errorf("own = %q", got)
}
}
func TestApplyGuidanceRechecksAfterBackup(t *testing.T) {
own := writeText(t, filepath.Join(t.TempDir(), "own.md"), "own\n")
in := guidanceInput(t, guidanceReader("a", own))
plan, _ := PlanGuidance(in, []string{"a"}, nil)
// An external editor changes the file while it is backed up.
backupGuidanceFile = func(path, reason string) error {
err := syncpkg.BackupFile(path, reason)
writeText(t, path, "external edit after backup\n")
return err
}
t.Cleanup(func() { backupGuidanceFile = syncpkg.BackupFile })
res, err := ApplyGuidance(in, []string{"a"}, nil, plan.Token, nil)
if err != nil || len(res.Applied) != 0 || len(res.Failures) != 1 || res.Failures[0].Path != own || !isStale(res.Failures[0]) {
t.Fatalf("apply = %+v, %v", res, err)
}
if got := readText(t, own); got != "external edit after backup\n" {
t.Errorf("external edit lost: %q", got)
}
}
func TestApplyGuidanceRechecksEachReviewedFile(t *testing.T) {
for _, change := range []string{"edited", "deleted", "created"} {
t.Run(change, func(t *testing.T) {
dir := t.TempDir()
first := writeText(t, filepath.Join(dir, "first.md"), "first\n")
second := filepath.Join(dir, "second.md")
if change != "created" {
writeText(t, second, "second\n")
}
in := guidanceInput(t, guidanceReader("a", first), guidanceReader("b", second))
names := []string{"a", "b"}
plan, _ := PlanGuidance(in, names, nil)
if len(plan.Changes) != 2 {
t.Fatalf("plan = %+v", plan)
}
want := map[string]string{"edited": "external edit\n", "created": ""}[change]
// An external editor changes the later file while the earlier file is applied.
res, err := ApplyGuidance(in, names, nil, plan.Token, func(GuidanceChange) []GuidanceFailure {
if change == "deleted" {
if err := os.Remove(second); err != nil {
t.Fatal(err)
}
} else {
writeText(t, second, want)
}
return nil
})
if err != nil || len(res.Applied) != 1 || res.Applied[0] != first || len(res.Failures) != 1 || res.Failures[0].Path != second || !isStale(res.Failures[0]) {
t.Fatalf("apply = %+v, %v", res, err)
}
if change == "deleted" {
if _, err := os.Stat(second); !os.IsNotExist(err) {
t.Fatal("deleted instructions recreated")
}
} else if got := readText(t, second); got != want {
t.Fatalf("external edit lost: %q", got)
}
})
}
}
func TestApplyGuidanceCompetingCreates(t *testing.T) {
path := filepath.Join(t.TempDir(), "AGENTS.md")
in := guidanceInput(t, guidanceReader("a", path))
plan, _ := PlanGuidance(in, []string{"a"}, nil)
if len(plan.Changes) != 1 || !plan.Changes[0].Created {
t.Fatalf("plan = %+v", plan)
}
type result struct {
res GuidanceResult
err error
}
const writers = 8
results := make(chan result, writers)
start := make(chan struct{})
for range writers {
go func() {
<-start
res, err := ApplyGuidance(in, []string{"a"}, nil, plan.Token, nil)
results <- result{res, err}
}()
}
close(start)
wins, stale := 0, 0
for range writers {
r := <-results
switch {
case r.err == nil && len(r.res.Applied) == 1 && len(r.res.Failures) == 0:
wins++
case errors.Is(r.err, ErrGuidanceStale), r.err == nil && len(r.res.Applied) == 0 && len(r.res.Failures) == 1 && isStale(r.res.Failures[0]):
stale++
default:
t.Fatalf("apply = %+v, %v", r.res, r.err)
}
}
if wins != 1 || stale != writers-1 {
t.Fatalf("wins = %d, stale = %d", wins, stale)
}
if got := readText(t, path); got != plan.Changes[0].After {
t.Errorf("winner overwritten: %q", got)
}
}
// The concurrent test cannot choose which check a loser fails; this one
// creates the file after the final review check, where only O_EXCL protects it.
func TestGuidanceCreateIsExclusive(t *testing.T) {
path := filepath.Join(t.TempDir(), "AGENTS.md")
change := GuidanceChange{Path: path, Created: true, After: "reviewed guidance"}
if err := checkGuidanceChange(change); err != nil {
t.Fatal(err)
}
writeText(t, path, "external instructions")
if err := commitGuidanceChange(change); !errors.Is(err, ErrGuidanceStale) {
t.Fatalf("expected stale plan, got %v", err)
}
if got := readText(t, path); got != "external instructions" {
t.Fatalf("external instructions lost: %q", got)
}
}
func TestCreateExclusiveRemovesUnfinishedFile(t *testing.T) {
path := filepath.Join(t.TempDir(), "note.md")
failed := errors.New("write failed")
if err := createExclusive(path, func(*os.File) error { return failed }); err != failed {
t.Fatalf("err = %v", err)
}
if _, err := os.Stat(path); !os.IsNotExist(err) {
t.Errorf("unfinished file kept: %v", err)
}
}
func TestGuidanceFlagsBlocksOfDifferentModes(t *testing.T) {
dir := t.TempDir()
a, b := filepath.Join(dir, "a.md"), filepath.Join(dir, "b.md")
in := guidanceInput(t, guidanceReader("claude", a, b))
writeText(t, a, in.instructions(ModePassive))
writeText(t, b, in.instructions(ModeActive))
if got := GuidanceStatus(in)[0]; got.State != "broken" || got.Detail != "mixed_modes" || got.Mode != "" {
t.Fatalf("status = %+v", got)
}
plan, err := PlanGuidance(in, []string{"claude"}, map[string]string{"claude": ModeActive})
if err != nil || len(plan.Changes) != 0 || len(plan.Skipped) != 1 || plan.Skipped[0].Reason != "mixed_modes" {
t.Fatalf("plan = %+v, %v", plan, err)
}
}
func TestGuidanceRefusesModeSwitchAcrossSeveralBlocks(t *testing.T) {
dir := t.TempDir()
a, b := filepath.Join(dir, "a.md"), filepath.Join(dir, "b.md")
in := guidanceInput(t, guidanceReader("claude", a, b))
writeText(t, a, in.instructions(ModePassive))
writeText(t, b, in.instructions(ModePassive))
if got := GuidanceStatus(in)[0]; got.State != "configured" || got.Mode != ModePassive {
t.Fatalf("status = %+v", got)
}
plan, err := PlanGuidance(in, []string{"claude"}, map[string]string{"claude": ModeActive})
if err != nil || len(plan.Changes) != 0 || len(plan.Skipped) != 1 || plan.Skipped[0].Reason != "multiple_blocks" {
t.Fatalf("plan = %+v, %v", plan, err)
}
}
func TestGuidanceLeavesUnsafeFilesUntouched(t *testing.T) {
block := Instructions("/notes", "", ModePassive)
cases := map[string]struct{ content, detail string }{
"non-UTF-8": {"caf\xe9 rules\n", "unsupported"},
"modified": {"own\n" + strings.Replace(block, "Open only", "Always open", 1), "modified"},
"malformed": {"own\n" + strings.TrimSuffix(block, blockEnd+"\n"), "malformed"},
}
for name, tc := range cases {
t.Run(name, func(t *testing.T) {
own := writeText(t, filepath.Join(t.TempDir(), "own.md"), tc.content)
in := guidanceInput(t, guidanceReader("a", own))
in.Root = "/notes"
if got := GuidanceStatus(in)[0]; got.State != "broken" || got.Detail != tc.detail || got.File != own {
t.Fatalf("status = %+v", got)
}
plan, err := PlanGuidance(in, []string{"a"}, nil)
if err != nil || len(plan.Changes) != 0 || len(plan.Skipped) != 1 || plan.Skipped[0].Reason != tc.detail {
t.Fatalf("plan = %+v, %v", plan, err)
}
if res, err := ApplyGuidance(in, []string{"a"}, nil, plan.Token, nil); err != nil || len(res.Applied) != 0 || len(res.Failures) != 0 {
t.Fatalf("apply = %+v, %v", res, err)
}
if got := readText(t, own); got != tc.content {
t.Errorf("bytes changed: %q", got)
}
})
}
}
+65 -424
View File
@@ -1,398 +1,91 @@
package server
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"net/http"
"os"
"path/filepath"
"slices"
"sort"
"strconv"
"time"
"unicode/utf8"
"skillshare/internal/config"
"skillshare/internal/instructions"
"skillshare/internal/memory"
syncpkg "skillshare/internal/sync"
)
// Memory guidance is a marked block (see memory.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.
// The guidance rules live in internal/memory. This file resolves what only the
// server knows (targets, instruction assignments, shared extras, project
// reach) into memory.GuidanceInput and converts the results to JSON.
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
}
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"`
}
// 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
shared string // the shared instruction file it is, if any
live bool // false when the shared file is attached but not synced
}
// 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
}
// memoryInstructions returns the guidance block of the current scope in the
// given update mode. Callers hold s.mu.
func (s *Server) memoryInstructions(root, mode string) string {
if s.IsProjectMode() {
return memory.Instructions(root, s.projectRoot, mode)
}
return memory.Instructions(root, "", mode)
}
// memoryInstructionsByMode returns the block of every update mode, for copying.
// memoryInstructionsByMode returns the guidance block of the current scope in
// every update mode, for copying. Callers hold s.mu.
func (s *Server) memoryInstructionsByMode(root string) map[string]string {
return map[string]string{memory.ModePassive: s.memoryInstructions(root, memory.ModePassive), memory.ModeActive: s.memoryInstructions(root, memory.ModeActive)}
return map[string]string{memory.ModePassive: memory.Instructions(root, s.projectRoot, memory.ModePassive), memory.ModeActive: memory.Instructions(root, s.projectRoot, memory.ModeActive)}
}
// 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
// guidanceInput resolves every target's read chain. Callers hold s.mu.
func (s *Server) guidanceInput() (memory.GuidanceInput, error) {
root, err := s.memoryRoot()
if err != nil {
return memory.GuidanceInput{}, err
}
return filepath.EvalSymlinks(path)
}
// guidanceSites resolves every target's read chain. Callers hold s.mu.
func (s *Server) guidanceSites(root string) []guidanceSite {
out := []guidanceSite{}
in := memory.GuidanceInput{Root: root, ProjectRoot: s.projectRoot, Config: []any{s.extrasConfig(), s.cfg.Targets}}
if s.IsProjectMode() {
agents := filepath.Join(s.projectRoot, instructions.AgentsFile)
for _, reach := range s.projectReaches() {
it, _ := config.TargetInstructions(reach.Target, s.cfg.Targets[reach.Target], true)
own := filepath.Join(s.projectRoot, it.Path)
site := guidanceSite{guidanceTarget: guidanceTarget{Name: reach.Target}, maxChars: it.MaxChars}
reader := memory.GuidanceReader{Name: reach.Target, MaxChars: it.MaxChars}
if reach.Reads {
// AGENTS.md may itself link elsewhere: change, preview and back up its real file.
if write, err := realFile(agents); err == nil {
site.sources = append(site.sources, guidanceSource{read: agents, write: write, live: true})
} else {
site.State, site.Detail, site.File = "broken", "unreadable", agents
}
reader.Sources = append(reader.Sources, memory.GuidanceSource{Read: agents, Live: true})
}
if reach.How != instructions.ReachDirect && reach.How != instructions.ReachLink {
if write, err := realFile(own); err == nil {
site.sources = append(site.sources, guidanceSource{read: own, write: write, live: true})
} else {
site.State, site.Detail, site.File = "broken", "unreadable", own
}
reader.Sources = append(reader.Sources, memory.GuidanceSource{Read: filepath.Join(s.projectRoot, it.Path), Live: true})
}
out = append(out, s.resolveSite(site, root))
in.Readers = append(in.Readers, reader)
}
return out
return in, nil
}
for _, t := range s.instructionTargets() {
site := guidanceSite{guidanceTarget: guidanceTarget{Name: t.Name}, maxChars: t.MaxChars}
own := guidanceSource{read: t.Path, live: true}
reader := memory.GuidanceReader{Name: t.Name, MaxChars: t.MaxChars}
own := memory.GuidanceSource{Read: t.Path, Live: true}
for _, a := range t.Assigned {
extra, ok := s.sharedExtra(a.Name)
if !ok {
continue
}
src := guidanceSource{read: filepath.Join(s.extrasSourceDir(extra), extra.File), shared: a.Name, live: a.Status == "synced"}
src.write = src.read
src := memory.GuidanceSource{Read: filepath.Join(s.extrasSourceDir(extra), extra.File), Shared: a.Name, Live: a.Status == "synced"}
src.Write = src.Read
if a.Mode != "import" {
// A link or copy is the target's own file; edit the source.
own.write, own.shared, own.live = src.write, a.Name, src.live
if !src.live {
own.Write, own.Shared, own.Live = src.Write, a.Name, src.Live
if !src.Live {
own = src
}
continue
}
site.sources = append(site.sources, src)
reader.Sources = append(reader.Sources, src)
}
if own.write == "" {
write, err := realFile(t.Path)
if err != nil {
site.State, site.Detail, site.File = "broken", "unreadable", t.Path
}
own.write = write
}
site.sources = append([]guidanceSource{own}, site.sources...)
reader.Sources = append([]memory.GuidanceSource{own}, reader.Sources...)
// A tool that imports shared files gets the block in the first synced one.
for i, src := range site.sources[1:] {
if src.live {
site.dest = i + 1
for i, src := range reader.Sources[1:] {
if src.Live {
reader.Dest = i + 1
break
}
}
out = append(out, s.resolveSite(site, root))
in.Readers = append(in.Readers, reader)
}
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 (s *Server) resolveSite(site guidanceSite, root string) guidanceSite {
if site.State != "" {
return site
}
rank := map[string]int{memory.StateConfigured: 4, memory.StateModified: 3, memory.StateMalformed: 3, memory.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 := memory.Mode(string(data), guidanceScope(s))
state := memory.Inspect(string(data), s.memoryInstructions(root, mode))
if !src.live {
if state != memory.StateUnconfigured {
site.State, site.Detail, site.File, site.shared = "broken", "not_synced", src.write, src.shared
return site
}
continue
}
if state != memory.StateUnconfigured && state != memory.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 memory.StateConfigured:
site.State, site.Detail = "configured", ""
case memory.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 apply can reject a plan
// whose files or config changed after review. Callers hold s.mu.
func (s *Server) planGuidance(names []string, modes map[string]string) (guidancePlan, error) {
root, err := s.memoryRoot()
if err != nil {
return guidancePlan{}, err
}
sites := s.guidanceSites(root)
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 := memory.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 := s.memoryInstructions(root, 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 := memory.Apply(string(data), want)
if err != nil {
plan.Skipped = append(plan.Skipped, guidanceSkip{name, memory.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
Extras []config.ExtraConfig
Targets any
}{root, names, chosen, plan, routes, s.extrasConfig(), s.cfg.Targets})
if err != nil {
return guidancePlan{}, err
}
sum := sha256.Sum256(data)
plan.Token = hex.EncodeToString(sum[:])
return plan, nil
return in, nil
}
// handleMemoryGuidance — GET /api/extras/memory/guidance
func (s *Server) handleMemoryGuidance(w http.ResponseWriter, r *http.Request) {
s.mu.RLock()
defer s.mu.RUnlock()
root, err := s.memoryRoot()
in, err := s.guidanceInput()
if err != nil {
writeMemoryError(w, err)
return
}
writeJSON(w, map[string]any{"scope": guidanceScope(s), "instructions": s.memoryInstructionsByMode(root), "targets": guidanceTargets(s.guidanceSites(root))})
}
func guidanceScope(s *Server) string {
if s.IsProjectMode() {
return memory.ScopeProject
}
return memory.ScopeGlobal
}
func guidanceTargets(sites []guidanceSite) []guidanceTarget {
out := make([]guidanceTarget, 0, len(sites))
for _, site := range sites {
out = append(out, site.guidanceTarget)
}
return out
writeJSON(w, map[string]any{"scope": in.Scope(), "instructions": s.memoryInstructionsByMode(in.Root), "targets": memory.GuidanceStatus(in)})
}
type guidanceRequest struct {
@@ -420,7 +113,12 @@ func (s *Server) handleMemoryGuidancePlan(w http.ResponseWriter, r *http.Request
}
s.mu.RLock()
defer s.mu.RUnlock()
plan, err := s.planGuidance(body.Targets, body.Modes)
in, err := s.guidanceInput()
if err != nil {
writeCodedError(w, http.StatusBadRequest, "memory_guidance_invalid", err.Error(), map[string]string{})
return
}
plan, err := memory.PlanGuidance(in, body.Targets, body.Modes)
if err != nil {
writeCodedError(w, http.StatusBadRequest, "memory_guidance_invalid", err.Error(), map[string]string{})
return
@@ -440,13 +138,28 @@ func (s *Server) handleMemoryGuidanceApply(w http.ResponseWriter, r *http.Reques
}
s.mu.Lock()
defer s.mu.Unlock()
plan, err := s.planGuidance(body.Targets, body.Modes)
in, err := s.guidanceInput()
if err != nil {
writeCodedError(w, http.StatusBadRequest, "memory_guidance_invalid", err.Error(), map[string]string{})
return
}
if body.Token == "" || body.Token != plan.Token {
writeCodedError(w, http.StatusConflict, "memory_guidance_stale", errGuidanceStale.Error(), map[string]string{})
res, err := memory.ApplyGuidance(in, body.Targets, body.Modes, body.Token, func(c memory.GuidanceChange) []memory.GuidanceFailure {
var out []memory.GuidanceFailure
if extra, ok := s.sharedExtra(c.Shared); ok && c.Shared != "" {
for _, result := range s.syncSharedCopies(extra) {
if result.Error != "" {
out = append(out, memory.GuidanceFailure{Path: result.Target, Err: errors.New(result.Error)})
}
}
}
return out
})
if errors.Is(err, memory.ErrGuidanceStale) {
writeCodedError(w, http.StatusConflict, "memory_guidance_stale", err.Error(), map[string]string{})
return
}
if err != nil {
writeCodedError(w, http.StatusBadRequest, "memory_guidance_invalid", err.Error(), map[string]string{})
return
}
type failure struct {
@@ -454,92 +167,20 @@ func (s *Server) handleMemoryGuidanceApply(w http.ResponseWriter, r *http.Reques
Error string `json:"error"`
Code string `json:"code,omitempty"`
}
applied, failures := []string{}, []failure{}
for _, c := range plan.Changes {
if err := writeGuidanceChange(c); err != nil {
code := ""
if errors.Is(err, errGuidanceStale) {
code = "memory_guidance_stale"
}
failures = append(failures, failure{Path: c.Path, Error: err.Error(), Code: code})
continue
}
applied = append(applied, c.Path)
if extra, ok := s.sharedExtra(c.shared); ok && c.shared != "" {
for _, result := range s.syncSharedCopies(extra) {
if result.Error != "" {
failures = append(failures, failure{Path: result.Target, Error: result.Error})
}
}
applied, failures := res.Applied, []failure{}
for _, f := range res.Failures {
code := ""
if errors.Is(f.Err, memory.ErrGuidanceStale) {
code = "memory_guidance_stale"
}
failures = append(failures, failure{Path: f.Path, Error: f.Err.Error(), Code: code})
}
status, msg := "ok", ""
if len(failures) > 0 {
status, msg = "partial", failures[0].Path+": "+failures[0].Error
}
s.writeOpsLog("memory-guidance", status, start, map[string]any{"targets": body.Targets, "modes": body.Modes, "files": applied, "scope": "ui"}, msg)
root, _ := s.memoryRoot()
writeJSON(w, map[string]any{"success": len(failures) == 0, "applied": applied, "errors": failures, "targets": guidanceTargets(s.guidanceSites(root))})
}
var errGuidanceStale = errors.New("instruction files changed since the preview; review the changes again")
// writeGuidanceChange rechecks each file as earlier writes and syncs may take time.
func writeGuidanceChange(c guidanceChange) error {
if err := checkGuidanceChange(c); err != nil {
return err
}
if !c.Created {
if err := syncpkg.BackupFile(c.Path, syncpkg.BackupReasonEdit); err != nil {
return err
}
}
if err := checkGuidanceChange(c); err != nil {
return err
}
return commitGuidanceChange(c)
}
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
}
// commitGuidanceChange writes a file after its final review check.
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
}
f, err := os.OpenFile(c.Path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
if os.IsExist(err) {
return errGuidanceStale
}
if err != nil {
return err
}
committed := false
defer func() {
if !committed {
os.Remove(c.Path)
}
}()
_, writeErr := f.WriteString(c.After)
closeErr := f.Close()
if writeErr != nil {
return writeErr
}
if closeErr != nil {
return closeErr
}
committed = true
return nil
// Syncing copies changes what the chains show, so resolve them again.
in, _ = s.guidanceInput()
writeJSON(w, map[string]any{"success": len(failures) == 0, "applied": applied, "errors": failures, "targets": memory.GuidanceStatus(in)})
}
@@ -1,7 +1,6 @@
package server
import (
"errors"
"net/http"
"os"
"path/filepath"
@@ -13,30 +12,30 @@ import (
)
type guidanceStatus struct {
Instructions map[string]string `json:"instructions"`
Targets []guidanceTarget `json:"targets"`
Instructions map[string]string `json:"instructions"`
Targets []memory.GuidanceTarget `json:"targets"`
}
func guidanceState(t *testing.T, s *Server) map[string]guidanceTarget {
func guidanceState(t *testing.T, s *Server) map[string]memory.GuidanceTarget {
t.Helper()
rr := instructionsRequest(t, s, http.MethodGet, "/api/extras/memory/guidance", "")
if rr.Code != http.StatusOK {
t.Fatalf("guidance: %d %s", rr.Code, rr.Body)
}
out := map[string]guidanceTarget{}
out := map[string]memory.GuidanceTarget{}
for _, target := range decodeBody[guidanceStatus](t, rr).Targets {
out[target.Name] = target
}
return out
}
func planGuidanceFor(t *testing.T, s *Server, targets string) guidancePlan {
func planGuidanceFor(t *testing.T, s *Server, targets string) memory.GuidancePlan {
t.Helper()
rr := instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/plan", `{"targets":`+targets+`}`)
if rr.Code != http.StatusOK {
t.Fatalf("plan: %d %s", rr.Code, rr.Body)
}
return decodeBody[guidancePlan](t, rr)
return decodeBody[memory.GuidancePlan](t, rr)
}
func applyGuidance(t *testing.T, s *Server, targets, token string) map[string]any {
@@ -398,72 +397,6 @@ func TestMemoryGuidance_SkipsNonUTF8Files(t *testing.T) {
}
}
func TestMemoryGuidance_RechecksEachReviewedFile(t *testing.T) {
for _, change := range []string{"edited", "deleted", "created"} {
t.Run(change, func(t *testing.T) {
s, home := newInstructionsServer(t, "claude", "codex")
writeHome(t, home, ".claude/CLAUDE.md", "claude own\n")
codex := filepath.Join(home, ".codex/AGENTS.md")
if change != "created" {
writeHome(t, home, ".codex/AGENTS.md", "codex own\n")
}
plan := planGuidanceFor(t, s, `["claude","codex"]`)
if len(plan.Changes) != 2 {
t.Fatalf("plan = %+v", plan)
}
if err := writeGuidanceChange(plan.Changes[0]); err != nil {
t.Fatal(err)
}
// An external editor changes the later file while the earlier file is applied.
if change == "deleted" {
if err := os.Remove(codex); err != nil {
t.Fatal(err)
}
} else {
content := "external edit\n"
if change == "created" {
content = ""
}
writeHome(t, home, ".codex/AGENTS.md", content)
}
if err := writeGuidanceChange(plan.Changes[1]); !errors.Is(err, errGuidanceStale) {
t.Fatalf("expected stale conflict, got %v", err)
}
if change == "deleted" {
if _, err := os.Stat(codex); !os.IsNotExist(err) {
t.Fatal("deleted instructions recreated")
}
} else {
want := "external edit\n"
if change == "created" {
want = ""
}
if got := readFile(t, codex); got != want {
t.Fatalf("external edit lost: %q", got)
}
}
})
}
}
func TestMemoryGuidance_CreateIsExclusive(t *testing.T) {
path := filepath.Join(t.TempDir(), "AGENTS.md")
change := guidanceChange{Path: path, Created: true, After: "reviewed guidance"}
if err := checkGuidanceChange(change); err != nil {
t.Fatal(err)
}
// A different process creates the file after the final review check.
if err := os.WriteFile(path, []byte("external instructions"), 0644); err != nil {
t.Fatal(err)
}
if err := commitGuidanceChange(change); !errors.Is(err, errGuidanceStale) {
t.Fatalf("expected stale plan, got %v", err)
}
if got := readFile(t, path); got != "external instructions" {
t.Fatalf("external instructions lost: %q", got)
}
}
func TestMemoryGuidance_SwitchesModeForEveryReaderOfTheFile(t *testing.T) {
s, home := newInstructionsServer(t, "claude", "codex")
writeHome(t, home, ".claude/CLAUDE.md", "# Me\n")
@@ -477,7 +410,7 @@ func TestMemoryGuidance_SwitchesModeForEveryReaderOfTheFile(t *testing.T) {
body := `{"targets":["codex"],"modes":{"codex":"active"}`
rr := instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/plan", body+`}`)
plan = decodeBody[guidancePlan](t, rr)
plan = decodeBody[memory.GuidancePlan](t, rr)
if rr.Code != http.StatusOK || len(plan.Changes) != 1 || !strings.Contains(plan.Changes[0].After, "mode=active") {
t.Fatalf("plan: %d %+v", rr.Code, plan)
}
@@ -511,7 +444,7 @@ func TestMemoryGuidance_FlagsTargetReadingBlocksOfDifferentModes(t *testing.T) {
plan := planGuidanceFor(t, s, `["claude"]`)
applyGuidance(t, s, `["claude"]`, plan.Token)
body := `{"targets":["codex"],"modes":{"codex":"active"}`
plan = decodeBody[guidancePlan](t, instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/plan", body+`}`))
plan = decodeBody[memory.GuidancePlan](t, instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/plan", body+`}`))
if rr := instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/apply", body+`,"token":"`+plan.Token+`"}`); rr.Code != http.StatusOK {
t.Fatalf("apply: %d %s", rr.Code, rr.Body)
}
@@ -532,7 +465,7 @@ func TestMemoryGuidance_RefusesModeSwitchForTargetReadingSeveralBlocks(t *testin
applyGuidance(t, s, `["codex"]`, plan.Token)
rr := instructionsRequest(t, s, http.MethodPost, "/api/extras/memory/guidance/plan", `{"targets":["claude"],"modes":{"claude":"active"}}`)
plan = decodeBody[guidancePlan](t, rr)
plan = decodeBody[memory.GuidancePlan](t, rr)
if rr.Code != http.StatusOK || len(plan.Changes) != 0 || len(plan.Skipped) != 1 || plan.Skipped[0].Reason != "multiple_blocks" {
t.Errorf("plan: %d %+v", rr.Code, plan)
}
+3 -5
View File
@@ -215,9 +215,10 @@ internal/mcp/write.go atomicWrite os.MkdirAll filepath.Dir(path) plugin
internal/mcp/write.go atomicWrite os.Remove file.Name() plugin
internal/mcp/write.go atomicWrite os.Rename file.Name(), path plugin
internal/memory/commit.go commitNote os.Rename draft, path extras
internal/memory/commit.go createNote os.OpenFile path extras
internal/memory/commit.go createNote os.Remove path extras
internal/memory/commit.go createExclusive os.OpenFile path extras
internal/memory/commit.go createExclusive os.Remove path extras
internal/memory/commit.go removeNote os.Remove path extras
internal/memory/guidance_plan.go commitGuidanceChange os.MkdirAll filepath.Dir(c.Path) plugin
internal/memory/move.go Move os.MkdirAll filepath.Dir(destination) extras
internal/memory/move.go Move os.OpenFile destination extras
internal/memory/move.go Move os.Remove destination extras
@@ -307,9 +308,6 @@ internal/server/handler_create_skill.go (*Server).handleCreateSkill os.WriteFile
internal/server/handler_extensions.go (*Server).handleExtensionsOpen os.MkdirAll dir plugin
internal/server/handler_extensions.go (*Server).handleExtensionsRemove os.RemoveAll path plugin
internal/server/handler_extras.go (*Server).handleExtrasCreate os.MkdirAll sourceDir extras
internal/server/handler_memory_guidance.go commitGuidanceChange os.MkdirAll filepath.Dir(c.Path) plugin
internal/server/handler_memory_guidance.go commitGuidanceChange os.OpenFile c.Path plugin
internal/server/handler_memory_guidance.go commitGuidanceChange os.Remove c.Path plugin
internal/server/handler_skill_content.go writeFileAtomic os.CreateTemp dir agents
internal/server/handler_skill_content.go writeFileAtomic os.Remove tmpPath agents
internal/server/handler_skill_content.go writeFileAtomic os.Rename tmpPath, path agents
Can't render this file because it contains an unexpected character in line 23 and column 89.
+74 -259
View File
@@ -1,7 +1,6 @@
package utils
import (
"bufio"
"bytes"
"encoding/json"
"fmt"
@@ -14,43 +13,20 @@ import (
// ParseSkillName reads the SKILL.md and extracts the "name" from frontmatter.
func ParseSkillName(skillPath string) (string, error) {
skillFile := filepath.Join(skillPath, "SKILL.md")
file, err := os.Open(skillFile)
name := ""
err := scanLenientBlock(filepath.Join(skillPath, "SKILL.md"), func(raw []byte) bool {
line := strings.TrimSpace(string(raw))
if !strings.HasPrefix(line, "name:") {
return true
}
// Extract value: "name: my-skill" -> "my-skill", without quotes
name = strings.Trim(strings.TrimSpace(strings.SplitN(line, ":", 2)[1]), `"'`)
return false
})
if err != nil {
return "", err
}
defer file.Close()
scanner := bufio.NewScanner(file)
inFrontmatter := false
for scanner.Scan() {
line := strings.TrimSpace(scanner.Text())
// Detect frontmatter delimiters
if line == "---" {
if inFrontmatter {
break // End of frontmatter
}
inFrontmatter = true
continue
}
if inFrontmatter {
if strings.HasPrefix(line, "name:") {
// Extract value: "name: my-skill" -> "my-skill"
parts := strings.SplitN(line, ":", 2)
if len(parts) == 2 {
name := strings.TrimSpace(parts[1])
// Remove quotes if present
name = strings.Trim(name, `"'`)
return name, nil
}
}
}
}
return "", nil // Name not found
return name, nil
}
// isYAMLBlockIndicator returns true for YAML block scalar indicators (>, >-, >+, |, |-, |+).
@@ -84,168 +60,57 @@ func resolveField(fm map[string]any, field string) any {
// Supports both inline [a, b] and block (- a\n- b) formats.
// Returns nil when the field is absent or the file cannot be read.
func ParseFrontmatterList(filePath, field string) []string {
raw := extractFrontmatterRaw(filePath)
if raw == "" {
return nil
}
var fm map[string]any
if err := yaml.Unmarshal([]byte(raw), &fm); err != nil {
return nil
}
val := resolveField(fm, field)
if val == nil {
return nil
}
switch v := val.(type) {
case []any:
result := make([]string, 0, len(v))
for _, item := range v {
if s, ok := item.(string); ok {
result = append(result, s)
}
}
if len(result) == 0 {
return nil
}
return result
default:
raw, err := readLenientBlock(filePath)
if err != nil {
return nil
}
return stringList(decodeFrontmatter(raw), field)
}
// ParseFrontmatterListFromBytes parses a YAML list field from pre-read content.
// Same as ParseFrontmatterList but avoids re-reading the file.
func ParseFrontmatterListFromBytes(content []byte, field string) []string {
raw := extractFrontmatterRawFromBytes(content)
if raw == "" {
return nil
}
raw := locateFrontmatter(content, lenientBlock).withoutLastNewline()
return stringList(decodeFrontmatter(raw), field)
}
// stringList returns the string items of a list field, resolved by resolveField.
func stringList(fm map[string]any, field string) []string {
list, _ := resolveField(fm, field).([]any)
var result []string
for _, item := range list {
if s, ok := item.(string); ok {
result = append(result, s)
}
}
return result
}
// decodeFrontmatter decodes the block a lenient reader found. It is nil when the block
// is empty or not a YAML mapping.
func decodeFrontmatter(raw []byte) map[string]any {
var fm map[string]any
if err := yaml.Unmarshal([]byte(raw), &fm); err != nil {
if err := yaml.Unmarshal(raw, &fm); err != nil {
return nil
}
val := resolveField(fm, field)
if val == nil {
return nil
}
switch v := val.(type) {
case []any:
result := make([]string, 0, len(v))
for _, item := range v {
if s, ok := item.(string); ok {
result = append(result, s)
}
}
if len(result) == 0 {
return nil
}
return result
default:
return nil
}
}
// extractFrontmatterRawFromBytes extracts raw frontmatter YAML from pre-read content.
func extractFrontmatterRawFromBytes(content []byte) string {
s := string(content)
lines := strings.Split(s, "\n")
inFrontmatter := false
var fmLines []string
for _, line := range lines {
trimmed := strings.TrimSpace(line)
if trimmed == "---" {
if inFrontmatter {
break
}
inFrontmatter = true
continue
}
if inFrontmatter {
fmLines = append(fmLines, line)
}
}
if len(fmLines) == 0 {
return ""
}
return strings.Join(fmLines, "\n")
}
// extractFrontmatterRaw reads the raw frontmatter text between --- delimiters.
func extractFrontmatterRaw(filePath string) string {
file, err := os.Open(filePath)
if err != nil {
return ""
}
defer file.Close()
scanner := bufio.NewScanner(file)
inFrontmatter := false
var lines []string
for scanner.Scan() {
line := scanner.Text()
trimmed := strings.TrimSpace(line)
if trimmed == "---" {
if inFrontmatter {
break
}
inFrontmatter = true
continue
}
if inFrontmatter {
lines = append(lines, line)
}
}
if len(lines) == 0 {
return ""
}
return strings.Join(lines, "\n")
return fm
}
// ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content.
// The Agent Skills format requires the file to begin with it, closed by a second ---.
func ParseFrontmatterMap(content []byte) (map[string]any, error) {
content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))
// Scan line by line up to the closing ---, keeping only offsets, so memory does
// not grow with the line count of a large body.
start, end := -1, -1
pos := 0
for line := range bytes.Lines(content) {
if start < 0 {
// Exactly ---: an indented delimiter does not open frontmatter. CRLF is fine.
if string(bytes.TrimRight(line, "\r\n")) != "---" {
return nil, fmt.Errorf("no frontmatter at the start")
}
start = len(line)
} else if string(bytes.TrimRight(line, "\r\n")) == "---" { // also exactly ---
end = pos
break
}
pos += len(line)
}
if start < 0 {
block := locateFrontmatter(content, strictBlock)
if !block.open {
return nil, fmt.Errorf("no frontmatter at the start")
}
if end < 0 {
if !block.closed {
return nil, fmt.Errorf("unclosed frontmatter: no closing ---")
}
raw := string(content[start:end])
if strings.TrimSpace(raw) == "" {
if len(bytes.TrimSpace(block.raw)) == 0 {
return nil, fmt.Errorf("no frontmatter")
}
var fm map[string]any
if err := yaml.Unmarshal([]byte(raw), &fm); err != nil {
if err := yaml.Unmarshal(block.raw, &fm); err != nil {
return nil, fmt.Errorf("invalid frontmatter: %w", err)
}
// A non-string key decodes to map[any]any, which JSON cannot carry.
@@ -265,15 +130,11 @@ func ParseFrontmatterFields(filePath string, fields []string) map[string]string
return result
}
raw := extractFrontmatterRaw(filePath)
if raw == "" {
return result
}
var fm map[string]any
if err := yaml.Unmarshal([]byte(raw), &fm); err != nil {
raw, err := readLenientBlock(filePath)
if err != nil {
return result
}
fm := decodeFrontmatter(raw)
for _, field := range fields {
val, ok := fm[field]
@@ -304,93 +165,47 @@ func ReadSkillBody(filePath string) string {
return ""
}
content := string(data)
// Check for frontmatter opening delimiter
if !strings.HasPrefix(strings.TrimSpace(content), "---") {
return strings.TrimSpace(content)
block := locateFrontmatter(scanLines(data), bodyBlock)
if !block.open {
return strings.TrimSpace(string(data))
}
// Skip leading whitespace + first "---" line
scanner := bufio.NewScanner(strings.NewReader(content))
foundOpen := false
for scanner.Scan() {
if strings.TrimSpace(scanner.Text()) == "---" {
foundOpen = true
break
}
if !block.closed {
return ""
}
if !foundOpen {
return strings.TrimSpace(content)
}
// Skip until closing "---"
for scanner.Scan() {
if strings.TrimSpace(scanner.Text()) == "---" {
// Collect remaining lines
var lines []string
for scanner.Scan() {
lines = append(lines, scanner.Text())
}
result := strings.Join(lines, "\n")
return strings.TrimSpace(result)
}
}
// No closing delimiter found — return everything after opening "---"
return ""
return strings.TrimSpace(string(block.body))
}
// ParseFrontmatterField reads a SKILL.md file and extracts the value of a given frontmatter field.
// It supports both inline values and YAML block scalars (>, >-, |, |-).
func ParseFrontmatterField(filePath, field string) string {
file, err := os.Open(filePath)
prefix := field + ":"
val := ""
var blockParts []string // set once val is a block scalar indicator
err := scanLenientBlock(filePath, func(raw []byte) bool {
if blockParts != nil {
// The block scalar continues while lines are indented
if len(raw) > 0 && (raw[0] == ' ' || raw[0] == '\t') {
blockParts = append(blockParts, strings.TrimSpace(string(raw)))
return true
}
return false
}
line := strings.TrimSpace(string(raw))
if !strings.HasPrefix(line, prefix) {
return true
}
val = strings.TrimSpace(strings.SplitN(line, ":", 2)[1])
if isYAMLBlockIndicator(val) {
blockParts = []string{}
return true
}
return false
})
if err != nil {
return ""
}
defer file.Close()
scanner := bufio.NewScanner(file)
inFrontmatter := false
prefix := field + ":"
for scanner.Scan() {
line := strings.TrimSpace(scanner.Text())
if line == "---" {
if inFrontmatter {
break
}
inFrontmatter = true
continue
}
if inFrontmatter && strings.HasPrefix(line, prefix) {
parts := strings.SplitN(line, ":", 2)
if len(parts) == 2 {
val := strings.TrimSpace(parts[1])
// Handle YAML block scalar indicators — read indented continuation lines
if isYAMLBlockIndicator(val) {
var blockParts []string
for scanner.Scan() {
next := scanner.Text()
trimmed := strings.TrimSpace(next)
if trimmed == "---" {
break
}
// Block continues while lines are indented
if len(next) > 0 && (next[0] == ' ' || next[0] == '\t') {
blockParts = append(blockParts, trimmed)
} else {
break
}
}
return strings.Join(blockParts, " ")
}
val = strings.Trim(val, `"'`)
return val
}
}
if blockParts != nil {
return strings.Join(blockParts, " ")
}
return ""
return strings.Trim(val, `"'`)
}
@@ -0,0 +1,367 @@
package utils
import (
"bufio"
"bytes"
"os"
"path/filepath"
"runtime"
"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
}
// writeSkill writes content as SKILL.md in a new directory.
func writeSkill(t *testing.T, content []byte) (dir, path string) {
t.Helper()
dir = t.TempDir()
path = filepath.Join(dir, "SKILL.md")
if err := os.WriteFile(path, content, 0644); err != nil {
t.Fatal(err)
}
return dir, path
}
func snapshotFrontmatter(t *testing.T, content string) fmSnapshot {
t.Helper()
dir, path := writeSkill(t, []byte(content))
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 := writeSkill(t, []byte(content))
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 := writeSkill(t, []byte(content))
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)
}
}
// A block scalar on the last frontmatter line: the readers that rebuilt the block from
// lines dropped its final newline, ParseFrontmatterMap decodes the block as written.
func TestFrontmatterEntryPoints_BlockScalarOnLastLine(t *testing.T) {
content := "---\nname: a\ndescription: |\n text\n---\nbody\n"
_, path := writeSkill(t, []byte(content))
if got := ParseFrontmatterFields(path, []string{"description"})["description"]; got != "text" {
t.Errorf("ParseFrontmatterFields = %q, want %q", got, "text")
}
fm, err := ParseFrontmatterMap([]byte(content))
if err != nil {
t.Fatal(err)
}
if got := fm["description"]; got != "text\n" {
t.Errorf("ParseFrontmatterMap = %q, want %q", got, "text\n")
}
}
// The path readers drop one \r per line before decoding, so \r\r\n is a single line break
// for them and two for the bytes reader.
func TestFrontmatterEntryPoints_DoubleCarriageReturn(t *testing.T) {
content := "---\r\r\ntargets:\r\r\n - |\r\r\n t\r\r\n u\r\r\n---\r\r\nbody\r\r\n"
_, path := writeSkill(t, []byte(content))
if got := ParseFrontmatterList(path, "targets"); len(got) != 1 || got[0] != "t\nu\n" {
t.Errorf("ParseFrontmatterList = %q", got)
}
if got := ParseFrontmatterListFromBytes([]byte(content), "targets"); len(got) != 1 || got[0] != "\nt\n\nu\n" {
t.Errorf("ParseFrontmatterListFromBytes = %q", got)
}
if got := ReadSkillBody(path); got != "body" {
t.Errorf("ReadSkillBody = %q", got)
}
}
// The readers that take a path keep only the frontmatter block: neither the body after
// it nor the text of a file without one costs them memory.
func TestFrontmatterEntryPoints_PathReadersKeepOnlyTheBlock(t *testing.T) {
filler := bytes.Repeat([]byte("body\n"), 1<<19)
tests := []struct {
name string
content []byte
want string
}{
{"large body after the block", append([]byte("---\nname: a\ntargets: [a]\n---\n"), filler...), "a"},
{"large file without frontmatter", filler, ""},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir, path := writeSkill(t, tt.content)
var before, after runtime.MemStats
runtime.GC()
runtime.ReadMemStats(&before)
name, err := ParseSkillName(dir)
field := ParseFrontmatterField(path, "name")
fields := ParseFrontmatterFields(path, []string{"name"})["name"]
list := strings.Join(ParseFrontmatterList(path, "targets"), ",")
runtime.ReadMemStats(&after)
if err != nil || name != tt.want || field != tt.want || fields != tt.want || list != tt.want {
t.Fatalf("got %q, %v, %q, %q, %q; want %q from each", name, err, field, fields, list, tt.want)
}
if got := after.TotalAlloc - before.TotalAlloc; got > 1<<20 {
t.Errorf("the readers allocated %d bytes, want under 1 MiB", got)
}
})
}
}
// ParseSkillName and ParseFrontmatterField stop at the line they look for, so a large
// frontmatter block after it, closed or not, costs them no memory.
func TestFrontmatterEntryPoints_KeyReadersStopAtTheKey(t *testing.T) {
filler := bytes.Repeat([]byte("k: v\n"), 1<<19)
tests := []struct {
name string
content []byte
}{
{"closed block", append(append([]byte("---\nname: a\n"), filler...), "---\nbody\n"...)},
{"unclosed block", append([]byte("---\nname: a\n"), filler...)},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir, path := writeSkill(t, tt.content)
var before, after runtime.MemStats
runtime.GC()
runtime.ReadMemStats(&before)
name, err := ParseSkillName(dir)
field := ParseFrontmatterField(path, "name")
runtime.ReadMemStats(&after)
if err != nil || name != "a" || field != "a" {
t.Fatalf("got %q, %v, %q; want %q from each", name, err, field, "a")
}
if got := after.TotalAlloc - before.TotalAlloc; got > 1<<20 {
t.Errorf("the readers allocated %d bytes, want under 1 MiB", got)
}
})
}
}
+190
View File
@@ -0,0 +1,190 @@
package utils
import (
"bufio"
"bytes"
"os"
)
// frontmatterPolicy is the rule one reader uses to find the --- delimiters. The readers
// do not agree on it (issue #449), so each difference is a field here and each reader
// names its policy below.
type frontmatterPolicy struct {
// skipBOM ignores a UTF-8 byte order mark before the opening delimiter.
skipBOM bool
// dashGuard gives up unless the content, after leading whitespace, starts with ---.
// The delimiter itself may still be a later line.
dashGuard bool
// firstLine requires the opening delimiter to be the first line. Otherwise the first
// delimiter line anywhere in the content opens the block.
firstLine bool
// delim reports whether a line, without its "\n", is a delimiter.
delim func(line []byte) bool
}
var (
// strictBlock is the Agent Skills format: the file begins with exactly ---, and the
// block ends at the next line that is exactly ---. CRLF is fine. ParseFrontmatterMap.
strictBlock = frontmatterPolicy{skipBOM: true, firstLine: true, delim: delimExact}
// lenientBlock takes the first two lines that are --- after trimming all whitespace,
// wherever they are. ParseSkillName, ParseFrontmatterList, ParseFrontmatterListFromBytes,
// ParseFrontmatterFields, ParseFrontmatterField.
lenientBlock = frontmatterPolicy{delim: delimTrimmed}
// bodyBlock is lenientBlock for content that starts with ---. ReadSkillBody.
bodyBlock = frontmatterPolicy{dashGuard: true, delim: delimTrimmed}
// rewriteBlock allows trailing spaces and tabs but no indent and no "\r", so that an
// indented --- inside a YAML block scalar stays content. splitFrontmatterAndBody.
rewriteBlock = frontmatterPolicy{dashGuard: true, delim: delimColumn0}
)
func delimExact(line []byte) bool { return string(bytes.TrimRight(line, "\r")) == "---" }
func delimTrimmed(line []byte) bool { return string(bytes.TrimSpace(line)) == "---" }
func delimColumn0(line []byte) bool { return string(bytes.TrimRight(line, " \t")) == "---" }
// frontmatterBlock is where the frontmatter sits in the content. raw and body point into
// the content; nothing is copied.
type frontmatterBlock struct {
open bool // an opening delimiter was found
closed bool // and a closing one
raw []byte // the lines between the delimiters; up to the end of the content when unclosed
body []byte // everything after the closing delimiter line; nil when unclosed
}
// withoutLastNewline returns raw without the newline before the closing delimiter, which
// is what the readers that used to split the content into lines decode. A block scalar
// on the last line loses its final newline that way; ParseFrontmatterMap decodes raw and
// keeps it.
func (b frontmatterBlock) withoutLastNewline() []byte {
if b.closed {
return bytes.TrimSuffix(b.raw, []byte("\n"))
}
return b.raw
}
// lineKind is where one line sits relative to the frontmatter block.
type lineKind int
const (
lineBefore lineKind = iota // before the opening delimiter
lineNoBlock // the policy rules out a block: stop
lineOpen // the opening delimiter
lineInside // a line of the block
lineClose // the closing delimiter
)
// blockWalk applies a policy's line rule to one line after another. It is the single
// place that decides which line opens and which closes the block.
type blockWalk struct {
p frontmatterPolicy
open bool
}
// next classifies line, given without its "\n".
func (w *blockWalk) next(line []byte) lineKind {
isDelim := w.p.delim(line)
switch {
case w.open && isDelim:
return lineClose
case w.open:
return lineInside
case isDelim:
w.open = true
return lineOpen
case w.p.firstLine:
return lineNoBlock
}
return lineBefore
}
// locateFrontmatter finds the frontmatter block under the given policy. It walks the
// lines only as far as the closing delimiter and allocates nothing, so a large body
// costs no memory. Whether an unclosed block counts is the caller's decision.
func locateFrontmatter(content []byte, p frontmatterPolicy) frontmatterBlock {
if p.skipBOM {
content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))
}
if p.dashGuard && !bytes.HasPrefix(bytes.TrimSpace(content), []byte("---")) {
return frontmatterBlock{}
}
w := blockWalk{p: p}
start, pos := -1, 0
for line := range bytes.Lines(content) {
next := pos + len(line)
switch w.next(bytes.TrimSuffix(line, []byte("\n"))) {
case lineClose:
return frontmatterBlock{open: true, closed: true, raw: content[start:pos], body: content[next:]}
case lineOpen:
start = next
case lineNoBlock:
return frontmatterBlock{}
}
pos = next
}
if start < 0 {
return frontmatterBlock{}
}
return frontmatterBlock{open: true, raw: content[start:]}
}
// scanLenientBlock calls fn with each line of a file's lenientBlock, without the
// delimiters, until the block ends or fn returns false. It is how the readers that take a
// path read: line by line through a default bufio.Scanner (see scanLines), keeping
// nothing, so they can stop at the key they want. A failed read ends the lines early;
// only a failed open is an error. The line passed to fn is only valid during the call.
func scanLenientBlock(path string, fn func(line []byte) bool) error {
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
w := blockWalk{p: lenientBlock}
scanner := bufio.NewScanner(f)
for scanner.Scan() {
switch w.next(scanner.Bytes()) {
case lineClose, lineNoBlock:
return nil
case lineInside:
if !fn(scanner.Bytes()) {
return nil
}
}
}
return nil
}
// readLenientBlock returns the lines of a file's lenientBlock joined with "\n", which is
// the YAML the list and fields readers have always decoded.
func readLenientBlock(path string) ([]byte, error) {
var raw bytes.Buffer
n := 0
err := scanLenientBlock(path, func(line []byte) bool {
if n++; n > 1 {
raw.WriteByte('\n')
}
raw.Write(line)
return true
})
return raw.Bytes(), err
}
// scanLines returns data as a default bufio.Scanner delivers it: the lines joined with
// "\n", one trailing "\r" dropped per line, ending without an error before the first line
// of bufio.MaxScanTokenSize bytes or more. The readers that take a path have always read
// this way; the ones that take bytes see the content as it is.
func scanLines(data []byte) []byte {
var out bytes.Buffer
out.Grow(len(data))
scanner := bufio.NewScanner(bytes.NewReader(data))
for n := 0; scanner.Scan(); n++ {
if n > 0 {
out.WriteByte('\n')
}
out.Write(scanner.Bytes())
}
return out.Bytes()
}
+10 -43
View File
@@ -28,12 +28,11 @@ func SetFrontmatterList(filePath string, field string, values []string) error {
// RewriteFrontmatterList returns updated frontmatter while preserving the body.
// It has the same field and removal semantics as SetFrontmatterList.
func RewriteFrontmatterList(data []byte, field string, values []string) ([]byte, error) {
content := string(data)
fmRaw, body := splitFrontmatterAndBody(content)
fmRaw, body := splitFrontmatterAndBody(data)
var fm map[string]any
if fmRaw != "" {
if err := yaml.Unmarshal([]byte(fmRaw), &fm); err != nil {
if len(fmRaw) > 0 {
if err := yaml.Unmarshal(fmRaw, &fm); err != nil {
return nil, err
}
}
@@ -90,51 +89,19 @@ func RewriteFrontmatterList(data []byte, field string, values []string) ([]byte,
sb.WriteString("---\n")
sb.Write(fmBytes)
sb.WriteString("---\n")
if body != "" {
sb.WriteString(body)
}
sb.Write(body)
return []byte(sb.String()), nil
}
// splitFrontmatterAndBody splits SKILL.md content into raw frontmatter YAML
// and the remaining body. Returns ("", fullContent) if no frontmatter found.
func splitFrontmatterAndBody(content string) (string, string) {
if !strings.HasPrefix(strings.TrimSpace(content), "---") {
return "", content
// and the remaining body. Returns (nil, content) if no frontmatter found.
func splitFrontmatterAndBody(content []byte) (fmRaw, body []byte) {
block := locateFrontmatter(content, rewriteBlock)
if !block.closed {
return nil, content
}
lines := strings.Split(content, "\n")
inFrontmatter := false
fmStart := -1
fmEnd := -1
for i, line := range lines {
// Only match "---" at column 0 (with optional trailing whitespace).
// TrimRight preserves leading whitespace so indented "---" inside
// a YAML block scalar is not mistaken for the frontmatter delimiter.
if strings.TrimRight(line, " \t") == "---" {
if !inFrontmatter {
inFrontmatter = true
fmStart = i + 1
} else {
fmEnd = i
break
}
}
}
if fmEnd < 0 {
return "", content
}
fmRaw := strings.Join(lines[fmStart:fmEnd], "\n")
body := ""
if fmEnd+1 < len(lines) {
body = strings.Join(lines[fmEnd+1:], "\n")
}
return fmRaw, body
return block.withoutLastNewline(), block.body
}
// ToggleFrontmatterFlag flips a top-level boolean frontmatter key and reports the new state.
+11 -6
View File
@@ -55,12 +55,17 @@ note. Broken links are reported without rewriting user-owned index sections.
Prepared writes and deletions recheck the version after backup immediately before
replacement/removal; new notes use exclusive creation to reject concurrent creates.
`handler_memory_guidance.go` resolves existing target read chains and instruction
assignments. Plan returns per-file before/after content, skips, reader/size
warnings, and a token; apply recomputes it before backed-up writes and syncing
shared copies. Each file is checked against its reviewed content and existence
before writing, including after backup. A later conflict preserves that file and
reports `memory_guidance_stale` in the partial result alongside applied paths.
`handler_memory_guidance.go` only resolves existing target read chains and
instruction assignments into `memory.GuidanceInput` (including which file
receives a new block) and converts results to JSON;
`internal/memory/guidance_plan.go` owns status, plan, and apply
(`GuidanceStatus`, `PlanGuidance`, `ApplyGuidance`), tested against a temp
directory. Plan returns per-file before/after content, skips, reader/size
warnings, and a token; apply recomputes it before backed-up writes, and a
callback lets the server sync shared copies after each written file. Each file
is checked against its reviewed content and existence before writing, including
after backup. A later conflict preserves that file and reports
`memory_guidance_stale` in the partial result alongside applied paths.
New guidance files use exclusive creation; a competing creator also produces
`memory_guidance_stale` without overwriting its file.
It preserves other content, assignments, and connection modes.