Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ You do not have to write the list of your projects by hand:

```sh
relai index build --scan ~/projects # every git repo of the folder (symlinks included); says which need `relai init`
relai index build --scan ~/work --scan ~/oss # --scan is repeatable and adds up (also with a list file and --depth); a repo reached by several --scan folders is indexed once
relai discover --links ~/projects # the mentions between them: who points at whom, and how strongly
relai discover --links ~/projects --depth 2 # also look one folder deeper (nested repos are named by path)
relai discover --links ~/projects --prompt # instructions for your agent to check each mention with you
Expand Down
10 changes: 10 additions & 0 deletions cmd/relai/args.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,13 @@ func containsDashDash(args []string) bool {
}
return false
}

// stringList is a flag that can be given several times; every value is kept, in order.
type stringList []string

func (l *stringList) String() string { return strings.Join(*l, ",") }

func (l *stringList) Set(v string) error {
*l = append(*l, v)
return nil
}
29 changes: 10 additions & 19 deletions cmd/relai/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ Usage:
relai handoff [dir] print the current state of the work (≤ 2,000 tokens by default)
relai discover [dir] list what the project already gives agents (skills, hooks, specs, docs…);
--prompt prints instructions for your agent to draft .relai/notes.md
relai index build [-o <path>] [--scan <folder>] [<list-file>]
read each repo path/URL in <list-file> (and/or every git repo in --scan <folder>)
relai index build [-o <path>] [--scan <folder>]... [--depth N] [<list-file>]
read each repo path/URL in <list-file> (and/or every git repo in each --scan <folder>;
repeat --scan to cover several folders, a repo reached by several of them is indexed once)
and collect their relai.yaml into an index (default: .relai/index.json)
relai discover --links <folder> [--depth N] [--propose [--min-weak N] | --prompt] [--json]
mentions between the git repos of <folder> (strong: remote URL or relative path;
Expand Down Expand Up @@ -154,11 +155,12 @@ func main() {
}
fs := flag.NewFlagSet("index build", flag.ExitOnError)
out := fs.String("o", defaultIndexPath, "write the index to this file")
scanDir := fs.String("scan", "", "find the git repositories in this folder instead of (or in addition to) a list file")
var scanDirs stringList
fs.Var(&scanDirs, "scan", "find the git repositories in this folder instead of (or in addition to) a list file; repeatable")
scanDepth := fs.Int("depth", 1, "with --scan: how many folder levels to look down for repositories")
_ = fs.Parse(reorderArgs(fs, os.Args[3:]))
if fs.NArg() < 1 && *scanDir == "" {
fmt.Fprintln(os.Stderr, "usage: relai index build [-o <path>] [--scan <folder>] [<list-file>]")
if fs.NArg() < 1 && len(scanDirs) == 0 {
fmt.Fprintln(os.Stderr, "usage: relai index build [-o <path>] [--scan <folder>]... [<list-file>]")
os.Exit(2)
}
var sources []string
Expand All @@ -167,21 +169,10 @@ func main() {
sources, err = index.ReadList(fs.Arg(0))
exitOn(err)
}
if *scanDir != "" {
repos, err := scan.FindDepth(*scanDir, *scanDepth)
if len(scanDirs) > 0 {
scanned, err := scanSources(scanDirs, *scanDepth, os.Stdout)
exitOn(err)
var without []string
for _, r := range repos {
sources = append(sources, r.Path)
if !r.Relai {
without = append(without, r.Name)
}
}
fmt.Printf("scan: %d repositories in %s, %d with a relai.yaml", len(repos), *scanDir, len(repos)-len(without))
if len(without) > 0 {
fmt.Printf("; without one (skipped, run `relai init` there to include them): %s", strings.Join(without, ", "))
}
fmt.Println()
sources = append(sources, scanned...)
}
entries, skipped := index.Build(sources)
for _, sk := range skipped {
Expand Down
51 changes: 51 additions & 0 deletions cmd/relai/scan.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
package main

import (
"fmt"
"io"
"strings"

"github.com/ECG-Rudy-Glt/RELAI/internal/scan"
)

// scanSources finds the git repositories of every folder in dirs (depth levels down) and returns their
// paths, in the order found. A repository reached more than once, through two folders that overlap or
// through a symbolic link, is returned once, by the first folder that found it. One "scan:" line per
// folder is written to w; with several folders, the count is of the repositories that folder added.
func scanSources(dirs []string, depth int, w io.Writer) ([]string, error) {
var sources []string
seen := map[string]bool{}
for _, dir := range dirs {
repos, err := scan.FindDepth(dir, depth)
if err != nil {
return nil, err
}
var kept []scan.Repo
already := 0
for _, r := range repos {
key := scan.Identity(r.Path) // a symbolic link or a worktree of a repository already found is that repository
if seen[key] {
already++
continue
}
seen[key] = true
kept = append(kept, r)
}
var without []string
for _, r := range kept {
sources = append(sources, r.Path)
if !r.Relai {
without = append(without, r.Name)
}
}
fmt.Fprintf(w, "scan: %d repositories in %s, %d with a relai.yaml", len(kept), dir, len(kept)-len(without))
if already > 0 {
fmt.Fprintf(w, "; %d already counted from a previous folder", already)
}
if len(without) > 0 {
fmt.Fprintf(w, "; without one (skipped, run `relai init` there to include them): %s", strings.Join(without, ", "))
}
fmt.Fprintln(w)
}
return sources, nil
}
232 changes: 232 additions & 0 deletions cmd/relai/scan_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,232 @@
package main

import (
"bytes"
"encoding/json"
"os"
"os/exec"
"path/filepath"
"strings"
"sync"
"testing"
)

// mkRepo creates a real git repository at dir/name with a relai.yaml (id = name), and returns its path.
func mkRepo(t *testing.T, dir, name string) string {
t.Helper()
p := filepath.Join(dir, name)
if err := os.MkdirAll(p, 0o755); err != nil {
t.Fatal(err)
}
if out, err := exec.Command("git", "-C", p, "init", "-q").CombinedOutput(); err != nil {
t.Skipf("git init: %v: %s", err, out)
}
yaml := "id: " + name + "\nsummary: test repo\n"
if err := os.WriteFile(filepath.Join(p, "relai.yaml"), []byte(yaml), 0o644); err != nil {
t.Fatal(err)
}
return p
}

func TestScanSourcesAccumulates(t *testing.T) {
root := t.TempDir()
a, b := filepath.Join(root, "a"), filepath.Join(root, "b")
ra := mkRepo(t, a, "one")
rb := mkRepo(t, b, "two")
var out bytes.Buffer
got, err := scanSources([]string{a, b}, 1, &out)
if err != nil {
t.Fatal(err)
}
if len(got) != 2 || got[0] != ra || got[1] != rb {
t.Fatalf("want [%s %s], got %v", ra, rb, got)
}
if n := strings.Count(out.String(), "scan: "); n != 2 {
t.Errorf("want one scan line per folder, got:\n%s", out.String())
}
}

func TestScanSourcesOverlapNoDuplicate(t *testing.T) {
root := t.TempDir()
r := mkRepo(t, root, "one")
mkRepo(t, root, "two")
link := filepath.Join(t.TempDir(), "link")
if err := os.Symlink(root, link); err != nil {
t.Skip("no symlinks:", err)
}
// the same folder twice, a symlink to it, and a folder that is itself the repository
got, err := scanSources([]string{root, root, link, r}, 1, &bytes.Buffer{})
if err != nil {
t.Fatal(err)
}
if len(got) != 2 {
t.Fatalf("want 2 repositories once each, got %v", got)
}
}

func TestScanSourcesSingleKeepsOutput(t *testing.T) {
root := t.TempDir()
mkRepo(t, root, "one")
p := filepath.Join(root, "bare")
if err := os.MkdirAll(p, 0o755); err != nil {
t.Fatal(err)
}
_ = exec.Command("git", "-C", p, "init", "-q").Run()
var out bytes.Buffer
if _, err := scanSources([]string{root}, 1, &out); err != nil {
t.Fatal(err)
}
want := "scan: 2 repositories in " + root + ", 1 with a relai.yaml; without one (skipped, run `relai init` there to include them): bare\n"
if out.String() != want {
t.Errorf("got %q\nwant %q", out.String(), want)
}
}

func TestScanSourcesMissingFolder(t *testing.T) {
if _, err := scanSources([]string{filepath.Join(t.TempDir(), "nope")}, 1, &bytes.Buffer{}); err == nil {
t.Error("a missing folder must be an error")
}
}

var (
binOnce sync.Once
binPath string
binErr string
)

// builtBinary builds the real binary once for all the end-to-end tests of the package.
func builtBinary(t *testing.T) string {
t.Helper()
binOnce.Do(func() {
dir, err := os.MkdirTemp("", "relai-bin")
if err != nil {
binErr = err.Error()
return
}
binPath = filepath.Join(dir, "relai")
if out, err := exec.Command("go", "build", "-o", binPath, ".").CombinedOutput(); err != nil {
binErr = err.Error() + "\n" + string(out)
}
})
if binErr != "" {
t.Fatalf("build: %s", binErr)
}
return binPath
}

// runIndexBuild builds the real binary once per test and runs `relai index build` with args.
func runIndexBuild(t *testing.T, args ...string) (string, []string) {
t.Helper()
bin := builtBinary(t)
idx := filepath.Join(t.TempDir(), "index.json")
cmd := exec.Command(bin, append([]string{"index", "build", "-o", idx}, args...)...)
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("index build: %v\n%s", err, out)
}
b, err := os.ReadFile(idx)
if err != nil {
t.Fatal(err)
}
var entries []struct {
Source string
}
if err := json.Unmarshal(b, &entries); err != nil {
t.Fatal(err)
}
var sources []string
for _, e := range entries {
sources = append(sources, e.Source)
}
return string(out), sources
}

func TestIndexBuildRepeatedScan(t *testing.T) {
root := t.TempDir()
a, b := filepath.Join(root, "a"), filepath.Join(root, "b")
mkRepo(t, a, "one")
mkRepo(t, b, "two")
_, sources := runIndexBuild(t, "--scan", a, "--scan", b)
if len(sources) != 2 {
t.Fatalf("both folders must be indexed, got %v", sources)
}
// overlapping folders (root holds a and b at depth 2) must not duplicate
_, sources = runIndexBuild(t, "--scan", a, "--scan", root, "--depth", "2")
if len(sources) != 2 {
t.Fatalf("overlap must not duplicate, got %v", sources)
}
}

func TestIndexBuildSingleScanUnchanged(t *testing.T) {
root := t.TempDir()
mkRepo(t, root, "one")
out, sources := runIndexBuild(t, "--scan", root)
if len(sources) != 1 {
t.Fatalf("got %v", sources)
}
if !strings.Contains(out, "scan: 1 repositories in "+root+", 1 with a relai.yaml\n") {
t.Errorf("scan line changed:\n%s", out)
}
}

func TestIndexBuildScansWithListFile(t *testing.T) {
root := t.TempDir()
a, b := filepath.Join(root, "a"), filepath.Join(root, "b")
mkRepo(t, a, "one")
mkRepo(t, b, "two")
listed := mkRepo(t, filepath.Join(root, "c"), "three")
list := filepath.Join(root, "list.txt")
if err := os.WriteFile(list, []byte(listed+"\n"), 0o644); err != nil {
t.Fatal(err)
}
_, sources := runIndexBuild(t, "--scan", a, "--scan", b, list)
if len(sources) != 3 {
t.Fatalf("list file and both scans must add up, got %v", sources)
}
}

func TestIndexBuildListAndScanNameTheSameRepoOnce(t *testing.T) {
root := t.TempDir()
one := mkRepo(t, root, "one")
list := filepath.Join(t.TempDir(), "list.txt")
if err := os.WriteFile(list, []byte(one+"\n"), 0o644); err != nil {
t.Fatal(err)
}
out, sources := runIndexBuild(t, "--scan", root, list)
if len(sources) != 1 {
t.Fatalf("a repository named by the list and by a scan must be indexed once, got %v", sources)
}
if !strings.Contains(out, "same repository as") {
t.Errorf("the second name should be reported:\n%s", out)
}
}

func TestScanSourcesWorktreeInAnotherFolderIsTheSameRepo(t *testing.T) {
root := t.TempDir()
a, b := filepath.Join(root, "a"), filepath.Join(root, "b")
main := mkRepo(t, a, "app")
if err := os.MkdirAll(b, 0o755); err != nil {
t.Fatal(err)
}
git := func(args ...string) {
t.Helper()
c := exec.Command("git", append([]string{"-C", main, "-c", "user.name=t", "-c", "user.email=t@t"}, args...)...)
if out, err := c.CombinedOutput(); err != nil {
t.Fatalf("git %v: %v %s", args, err, out)
}
}
git("add", ".")
git("commit", "-q", "-m", "x")
git("worktree", "add", "-q", filepath.Join(b, "app-feature"), "-b", "feature")
var out bytes.Buffer
got, err := scanSources([]string{a, b}, 1, &out)
if err != nil {
t.Fatal(err)
}
if len(got) != 1 || got[0] != main {
t.Fatalf("the worktree in folder b is the repository of folder a: want [%s], got %v", main, got)
}
if !strings.Contains(out.String(), "1 already counted") {
t.Errorf("the overlap should be said:\n%s", out.String())
}
}
4 changes: 2 additions & 2 deletions docs/HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ no central service, no Backstage, no federation or SSO.

| Area | State |
|---|---|
| Release | **v0.2.0** is published (6 platform archives + `checksums.txt`); `scripts/install.sh` verifies the SHA-256 before installing and never runs `sudo` on its own. `main` is ahead of it by the fixes below once they merge |
| CLI | Go, stdlib only, `cmd/relai`: `init` (AGENTS.md, relai.yaml, `.relai/notes.md`, and for Claude Code a `CLAUDE.md` plus a SessionStart hook; never overwrites; `--no-claude`), `handoff`, `discover`, `index build` / `find`, `index build --scan <folder>` and `discover --links <folder>` (find the repos of a folder and the mentions between them: evidence, never verdicts), `tidy` (close the tasks merged commits say they close, refresh the export, delete merged branches; run by the post-merge hook), `workspace` (one budgeted overview of all indexed projects, files only), `new <template> <dir>`, `version`. Flags may come before or after the arguments. `init --hooks` adds a git pre-commit hook that keeps `.beads/issues.jsonl` current |
| Release | Releases are automatic: every merge to `main` with a `feat:`/`fix:`/`perf:` commit is tagged and published by `.github/workflows/release.yml` (6 platform archives + `checksums.txt`; see the releases page for the latest); `scripts/install.sh` verifies the SHA-256 before installing and never runs `sudo` on its own. |
| CLI | Go, stdlib only, `cmd/relai`: `init` (AGENTS.md, relai.yaml, `.relai/notes.md`, and for Claude Code a `CLAUDE.md` plus a SessionStart hook; never overwrites; `--no-claude`), `handoff`, `discover`, `index build` / `find`, `index build --scan <folder>` (repeatable) and `discover --links <folder>` (find the repos of a folder and the mentions between them: evidence, never verdicts), `tidy` (close the tasks merged commits say they close, refresh the export, delete merged branches; run by the post-merge hook), `workspace` (one budgeted overview of all indexed projects, files only), `new <template> <dir>`, `version`. Flags may come before or after the arguments. `init --hooks` adds a git pre-commit hook that keeps `.beads/issues.jsonl` current |
| Handoff | Format **v0.5** (see `spec/handoff.md`, changelog at the end). Deterministic, about 2,000 tokens at most, degraded mode for repos with no harness, honest messages when `bd` or `openspec` cannot be read |
| Tests | `go test ./...`: handoff (budget, degraded mode, hygiene, large inputs), initrepo, discover, index (every `provides` list shape), scaffold (symlinks, binary files, token substitution), CLI args. CI runs gofmt, vet, test |
| Experiment E2 | `eval/README.md`. The gain is mostly in turns (1 instead of 4-30); in tokens it is 1.2x-3.4x in dollars, more in raw tokens, and nothing on repos with no tracker or notes. Do not quote the 56x figure (it is a size estimate, not an agent measurement) |
Expand Down
10 changes: 10 additions & 0 deletions internal/index/index.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ package index
import (
"bytes"
"fmt"
"github.com/ECG-Rudy-Glt/RELAI/internal/scan"
"os"
"os/exec"
"path/filepath"
Expand Down Expand Up @@ -122,7 +123,16 @@ func ReadList(path string) ([]string, error) {
// returns the entries it could read plus the sources it had to skip, with a reason for each.
// It never fails outright: a bad source is reported as a skip, not an error.
func Build(sources []string) (entries []Entry, skipped []Skip) {
first := map[string]string{} // identity of a repository -> the source that named it first
for _, src := range sources {
// The same repository named twice (a list file and a scanned folder, a symbolic link, a worktree) is
// indexed once, and the second name is reported.
id := scan.Identity(src)
if prev, dup := first[id]; dup {
skipped = append(skipped, Skip{Source: src, Reason: "same repository as " + prev})
continue
}
first[id] = src
m, warn, err := readOne(src)
if err != nil {
skipped = append(skipped, Skip{Source: src, Reason: err.Error()})
Expand Down
Loading
Loading