feat(brain): ListPending + PromoteNote — raw→wiki curation primitives (#38)
Closes the human curation loop: list brain/raw/ notes awaiting review (oldest-first, with excerpt) and promote one into brain/wiki/<wing>/<hall>/. PromoteNote rewrites frontmatter (sets wing/hall/promoted_at, preserves created_at + custom fields via the existing frontmatter editor), rebuilds the wing _index, and runs auto-tunnel. Atomic from the caller's view: hall/wing/slug/collision validation happens before any fs change, and the source is deleted only after the destination write succeeds (write-then- delete, never move) — a collision or write failure leaves raw/ intact. Default slug = filename minus the YYYY-MM-DD- prefix. Also exposes GET /pending + POST /promote for shell scripts (bad hall/collision/missing-source → 400, not 500). Scope note: operates on raw/ (the retrospective-skill review queue) per this issue's spec. The knowledge/ legacy pile is #22's bulk-migration concern, not this ongoing queue. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -483,6 +483,40 @@ func (h *Handler) BackfillRefs(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(w, map[string]int{"updated": n})
|
||||
}
|
||||
|
||||
// Pending handles GET /pending — list raw/ notes awaiting promotion.
|
||||
func (h *Handler) Pending(w http.ResponseWriter, _ *http.Request) {
|
||||
pending, err := ListPending(h.brainDir)
|
||||
if err != nil {
|
||||
h.logger.Error("pending failed", "err", err)
|
||||
writeError(w, http.StatusInternalServerError, "pending error")
|
||||
return
|
||||
}
|
||||
writeJSON(w, map[string]any{"pending": pending})
|
||||
}
|
||||
|
||||
type promoteRequest struct {
|
||||
Filename string `json:"filename"`
|
||||
Wing string `json:"wing"`
|
||||
Hall string `json:"hall"`
|
||||
Slug string `json:"slug,omitempty"`
|
||||
}
|
||||
|
||||
// Promote handles POST /promote — move a raw/ note into the wiki. A bad
|
||||
// hall / collision / missing source is a 400 (caller error), not a 500.
|
||||
func (h *Handler) Promote(w http.ResponseWriter, r *http.Request) {
|
||||
var req promoteRequest
|
||||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||||
writeError(w, http.StatusBadRequest, "invalid JSON")
|
||||
return
|
||||
}
|
||||
rel, err := PromoteNote(h.brainDir, PromoteOptions(req))
|
||||
if err != nil {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, map[string]string{"path": rel})
|
||||
}
|
||||
|
||||
func writeJSON(w http.ResponseWriter, v any) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(v) //nolint:errcheck
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
package api
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
|
||||
)
|
||||
|
||||
// PendingNote describes a raw/ note awaiting human promotion to the wiki.
|
||||
type PendingNote struct {
|
||||
Filename string `json:"filename"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
SizeBytes int64 `json:"size_bytes"`
|
||||
Excerpt string `json:"excerpt"`
|
||||
}
|
||||
|
||||
// datePrefix matches a leading YYYY-MM-DD- on a raw filename, stripped when
|
||||
// deriving the default promoted slug.
|
||||
var datePrefix = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}-`)
|
||||
|
||||
// ListPending returns the notes in brain/raw/ awaiting review, oldest-first
|
||||
// (natural review order). An absent raw/ dir yields an empty slice, not an
|
||||
// error. Only .md files are listed; tunnel-candidate files are skipped.
|
||||
func ListPending(brainDir string) ([]PendingNote, error) {
|
||||
dir := filepath.Join(brainDir, "raw")
|
||||
entries, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return []PendingNote{}, nil
|
||||
}
|
||||
return nil, fmt.Errorf("read raw dir: %w", err)
|
||||
}
|
||||
|
||||
out := make([]PendingNote, 0, len(entries))
|
||||
for _, e := range entries {
|
||||
if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") || strings.HasPrefix(e.Name(), "tunnel-candidates-") {
|
||||
continue
|
||||
}
|
||||
info, statErr := e.Info()
|
||||
if statErr != nil {
|
||||
continue
|
||||
}
|
||||
raw, readErr := os.ReadFile(filepath.Join(dir, e.Name()))
|
||||
if readErr != nil {
|
||||
continue
|
||||
}
|
||||
fm, body := parseFrontmatter(string(raw))
|
||||
created := fm.get("created_at")
|
||||
if created == "" {
|
||||
created = info.ModTime().UTC().Format(time.RFC3339)
|
||||
}
|
||||
out = append(out, PendingNote{
|
||||
Filename: e.Name(),
|
||||
CreatedAt: created,
|
||||
SizeBytes: info.Size(),
|
||||
Excerpt: excerpt(body, 200),
|
||||
})
|
||||
}
|
||||
sort.SliceStable(out, func(i, j int) bool { return out[i].CreatedAt < out[j].CreatedAt })
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// PromoteOptions identifies a raw note to promote and its wiki destination.
|
||||
type PromoteOptions struct {
|
||||
Filename string // basename in brain/raw/
|
||||
Wing string
|
||||
Hall string
|
||||
Slug string // optional; defaults to Filename minus date prefix + .md
|
||||
}
|
||||
|
||||
// PromoteNote moves a note from brain/raw/ into the structured wiki: it
|
||||
// rewrites frontmatter (sets wing/hall/promoted_at, preserves created_at and
|
||||
// any custom fields), writes to brain/wiki/<wing>/<hall>/<slug>.md, deletes
|
||||
// the source, then rebuilds the wing index and runs auto-tunnel detection.
|
||||
//
|
||||
// It is atomic from the caller's view: validation (hall, wing, slug,
|
||||
// collision) happens before any filesystem change, and the source is deleted
|
||||
// only after the destination write succeeds (write-then-delete, never move).
|
||||
// Returns the promoted note's path relative to brainDir.
|
||||
func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
|
||||
// Validate filename (basename only — no traversal) before touching fs.
|
||||
base := filepath.Base(opts.Filename)
|
||||
if base != opts.Filename || base == "." || base == ".." || strings.ContainsAny(opts.Filename, `/\`) {
|
||||
return "", fmt.Errorf("invalid filename %q", opts.Filename)
|
||||
}
|
||||
|
||||
slug := opts.Slug
|
||||
if slug == "" {
|
||||
slug = datePrefix.ReplaceAllString(strings.TrimSuffix(base, ".md"), "")
|
||||
}
|
||||
// NotePath validates hall + wing + slug; do this before reading anything.
|
||||
dest, err := brain.NotePath(brainDir, opts.Wing, opts.Hall, slug)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
|
||||
src := filepath.Join(brainDir, "raw", base)
|
||||
raw, err := os.ReadFile(src)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return "", fmt.Errorf("pending note %q does not exist in raw/", base)
|
||||
}
|
||||
return "", fmt.Errorf("read source: %w", err)
|
||||
}
|
||||
|
||||
// Collision: never silently overwrite an existing promoted note.
|
||||
if _, statErr := os.Stat(dest); statErr == nil {
|
||||
rel, _ := filepath.Rel(brainDir, dest)
|
||||
return "", fmt.Errorf("target %s already exists; choose a different slug", filepath.ToSlash(rel))
|
||||
}
|
||||
|
||||
fm, body := parseFrontmatter(string(raw))
|
||||
now := time.Now().UTC().Format(time.RFC3339)
|
||||
fm.set("wing", brain.Sanitise(opts.Wing))
|
||||
fm.set("hall", opts.Hall)
|
||||
if fm.get("created_at") == "" {
|
||||
fm.set("created_at", now)
|
||||
}
|
||||
fm.set("promoted_at", now)
|
||||
|
||||
if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
|
||||
return "", fmt.Errorf("create wing dir: %w", err)
|
||||
}
|
||||
// Write-then-delete: the source survives any write failure.
|
||||
if err := os.WriteFile(dest, []byte(fm.render()+body), 0o644); err != nil {
|
||||
return "", fmt.Errorf("write promoted note: %w", err)
|
||||
}
|
||||
if err := os.Remove(src); err != nil {
|
||||
return "", fmt.Errorf("promoted note written but source removal failed: %w", err)
|
||||
}
|
||||
|
||||
rel, _ := filepath.Rel(brainDir, dest)
|
||||
relSlash := filepath.ToSlash(rel)
|
||||
|
||||
// Best-effort wiki upkeep — the note is already promoted.
|
||||
_ = brain.BuildWingIndex(brainDir, opts.Wing)
|
||||
_ = brain.AutoTunnel(brainDir, relSlash, body)
|
||||
|
||||
return relSlash, nil
|
||||
}
|
||||
|
||||
// excerpt returns the first n runes of s, trimmed, single-spaced.
|
||||
func excerpt(s string, n int) string {
|
||||
s = strings.TrimSpace(s)
|
||||
r := []rune(s)
|
||||
if len(r) > n {
|
||||
r = r[:n]
|
||||
}
|
||||
return strings.TrimSpace(string(r))
|
||||
}
|
||||
@@ -0,0 +1,121 @@
|
||||
package api
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func writeRaw(t *testing.T, brainDir, name, content string) {
|
||||
t.Helper()
|
||||
dir := filepath.Join(brainDir, "raw")
|
||||
require.NoError(t, os.MkdirAll(dir, 0o755))
|
||||
require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
|
||||
}
|
||||
|
||||
func TestListPendingEmptyWhenAbsent(t *testing.T) {
|
||||
got, err := ListPending(t.TempDir())
|
||||
require.NoError(t, err, "absent raw/ is not an error")
|
||||
assert.Empty(t, got)
|
||||
}
|
||||
|
||||
func TestListPendingReturnsOldestFirstWithExcerpt(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeRaw(t, dir, "2026-06-02-newer.md", "---\ncreated_at: 2026-06-02T00:00:00Z\n---\nNewer body here.\n")
|
||||
writeRaw(t, dir, "2026-06-01-older.md", "---\ncreated_at: 2026-06-01T00:00:00Z\n---\nOlder body content.\n")
|
||||
// non-md ignored
|
||||
writeRaw(t, dir, "notes.txt", "ignore me")
|
||||
|
||||
got, err := ListPending(dir)
|
||||
require.NoError(t, err)
|
||||
require.Len(t, got, 2)
|
||||
assert.Equal(t, "2026-06-01-older.md", got[0].Filename, "oldest first")
|
||||
assert.Equal(t, "2026-06-02-newer.md", got[1].Filename)
|
||||
assert.Contains(t, got[0].Excerpt, "Older body content")
|
||||
assert.NotContains(t, got[0].Excerpt, "---", "excerpt is body, not frontmatter")
|
||||
assert.Positive(t, got[0].SizeBytes)
|
||||
}
|
||||
|
||||
func TestPromoteHappyPath(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeRaw(t, dir, "2026-06-01-lejpa-decision.md",
|
||||
"---\ncreated_at: 2026-06-01T09:00:00Z\ncustom_field: keep-me\n---\n# LeJEPA\n\nbody.\n")
|
||||
|
||||
rel, err := PromoteNote(dir, PromoteOptions{
|
||||
Filename: "2026-06-01-lejpa-decision.md", Wing: "jepa-fx", Hall: "decisions",
|
||||
})
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "wiki/jepa-fx/decisions/lejpa-decision.md", rel, "slug defaults to filename minus date prefix")
|
||||
|
||||
// Source deleted.
|
||||
_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-lejpa-decision.md"))
|
||||
assert.True(t, os.IsNotExist(statErr), "source removed after promote")
|
||||
|
||||
got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
|
||||
require.NoError(t, err)
|
||||
s := string(got)
|
||||
assert.Contains(t, s, "wing: jepa-fx")
|
||||
assert.Contains(t, s, "hall: decisions")
|
||||
assert.Contains(t, s, "created_at: 2026-06-01T09:00:00Z", "original created_at preserved")
|
||||
assert.Contains(t, s, "promoted_at:")
|
||||
assert.Contains(t, s, "custom_field: keep-me", "custom frontmatter preserved")
|
||||
assert.Contains(t, s, "# LeJEPA")
|
||||
}
|
||||
|
||||
func TestPromoteExplicitSlug(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeRaw(t, dir, "2026-06-01-x.md", "body\n")
|
||||
rel, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts", Slug: "custom-slug"})
|
||||
require.NoError(t, err)
|
||||
assert.Equal(t, "wiki/a/facts/custom-slug.md", rel)
|
||||
}
|
||||
|
||||
func TestPromoteInvalidHallErrorsBeforeTouchingFS(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeRaw(t, dir, "2026-06-01-x.md", "body\n")
|
||||
_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "garbage"})
|
||||
require.Error(t, err)
|
||||
// Source untouched.
|
||||
_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
|
||||
assert.NoError(t, statErr, "invalid hall must not delete or move the source")
|
||||
}
|
||||
|
||||
func TestPromoteMissingSourceErrors(t *testing.T) {
|
||||
_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "ghost.md", Wing: "a", Hall: "facts"})
|
||||
require.Error(t, err)
|
||||
}
|
||||
|
||||
func TestPromoteSlugCollisionNoOverwrite(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
// Pre-existing target.
|
||||
dest := filepath.Join(dir, "wiki", "a", "facts", "x.md")
|
||||
require.NoError(t, os.MkdirAll(filepath.Dir(dest), 0o755))
|
||||
require.NoError(t, os.WriteFile(dest, []byte("EXISTING\n"), 0o644))
|
||||
writeRaw(t, dir, "2026-06-01-x.md", "NEW\n")
|
||||
|
||||
_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
|
||||
require.Error(t, err, "collision must error, not overwrite")
|
||||
|
||||
got, _ := os.ReadFile(dest)
|
||||
assert.Equal(t, "EXISTING\n", string(got), "target not overwritten")
|
||||
_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
|
||||
assert.NoError(t, statErr, "source preserved on collision (atomic: no delete without write)")
|
||||
}
|
||||
|
||||
func TestPromoteRejectsTraversalFilename(t *testing.T) {
|
||||
_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "../escape.md", Wing: "a", Hall: "facts"})
|
||||
require.Error(t, err)
|
||||
}
|
||||
|
||||
func TestPromoteRebuildsWingIndex(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
writeRaw(t, dir, "2026-06-01-x.md", "---\ntitle: X Note\n---\nbody\n")
|
||||
_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
|
||||
require.NoError(t, err)
|
||||
idx, err := os.ReadFile(filepath.Join(dir, "wiki", "a", "_index.md"))
|
||||
require.NoError(t, err, "wing _index regenerated")
|
||||
assert.Contains(t, string(idx), "x", "promoted note appears in the index")
|
||||
}
|
||||
Reference in New Issue
Block a user