From 891cb6c4ba7568f5110ecac1a9619df28e1a9769 Mon Sep 17 00:00:00 2001 From: Raphael Simon Date: Thu, 19 Nov 2026 12:26:27 -0800 Subject: [PATCH 1/4] Add surla setup -global, the /surla skill and the Herdr companion surla setup -global registers ` stdio` as the surla MCP server in the global JSON or TOML configuration of every coding agent it finds and installs the /surla skill next to each. JSON files keep every other key and exact numbers; config.toml files are edited in place so comments and other servers survive. A second run writes nothing. When Herdr is present, setup copies the companion window's mod.json and main.js into Herdr's mods folder and, on macOS, binds cmd-alt-shift-s when that key is free. The window shows the shown space's project stage, what needs the user and each role's state, focuses a role's pane, and opens the views page by running surla. It reads only `surla status --json`. The command is wired into the CLI with surla stdio and surla up. --- cmd/surla/setup.go | 855 ++++++++++++++++++++++++++++++++ cmd/surla/setup_test.go | 428 ++++++++++++++++ go.mod | 1 + go.sum | 2 + skills/embed.go | 18 + skills/herdr/surla/main.js | 269 ++++++++++ skills/herdr/surla/mod.json | 5 + skills/herdr/surla/test_mod.mjs | 288 +++++++++++ skills/surla/SKILL.md | 58 +++ 9 files changed, 1924 insertions(+) create mode 100644 cmd/surla/setup.go create mode 100644 cmd/surla/setup_test.go create mode 100644 skills/embed.go create mode 100644 skills/herdr/surla/main.js create mode 100644 skills/herdr/surla/mod.json create mode 100644 skills/herdr/surla/test_mod.mjs create mode 100644 skills/surla/SKILL.md diff --git a/cmd/surla/setup.go b/cmd/surla/setup.go new file mode 100644 index 00000000..ea3e8fec --- /dev/null +++ b/cmd/surla/setup.go @@ -0,0 +1,855 @@ +// This file implements "surla setup -global". It registers `surla stdio` as +// the surla MCP server in the global configuration of every coding agent it +// detects and installs the /surla agent skill next to each. When Herdr is +// present it also installs the Surla companion window. "surla up" runs the +// same setup before it starts. +package main + +import ( + "bytes" + "cmp" + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "reflect" + "runtime" + "slices" + "strconv" + "strings" + + "github.com/pelletier/go-toml/v2" + "github.com/pelletier/go-toml/v2/unstable" + + "github.com/goadesign/surla/skills" +) + +type ( + // setupEnvironment holds the machine facts setup reads. runSetup fills it + // from the running process; tests point it at a temporary home so they + // never touch the user's own configuration. + setupEnvironment struct { + // home is the user's home directory. Every default location is under it. + home string + // executable is the absolute path of the surla binary that agents start + // as ` stdio`. + executable string + // getenv reads a variable that moves a client's files, such as + // CLAUDE_CONFIG_DIR or HERDR_APP_HOME. + getenv func(string) string + // onPath reports whether a client's command is installed, so a client + // that has not created its configuration folder yet is still set up. + onPath func(string) bool + // goos selects VS Code's settings folder and the macOS-only Herdr shortcut. + goos string + } + + // mcpJSONTarget is one JSON configuration file and the surla entry its + // client expects. + mcpJSONTarget struct { + // path is the configuration file to create or update. + path string + // serversKey names the top-level object holding server entries: + // "mcpServers" for most clients, "servers" for VS Code. + serversKey string + // entry is the object written at serversKey["surla"]. + entry map[string]any + } + + // codexEntryEdit says where mergeCodexConfig writes mcp_servers.surla in a + // Codex config.toml document. Zero-length ranges mean the key is absent. + codexEntryEdit struct { + // command is the byte range of an existing command string, quotes included. + command unstable.Range + // args is the byte range of an existing args array. + args unstable.Range + // afterHeader is the offset just past the [mcp_servers.surla] header + // line, or 0 when the document has no such table. + afterHeader int + // dotted is true when a dotted key such as surla.command under + // [mcp_servers] defines part of the entry. + dotted bool + } + + // herdrShortcutBinding describes an existing assignment of the companion's + // key. Command arguments stay private to the keyboard file. + herdrShortcutBinding struct { + // section is the keyboard context that already uses the key. + section string + // command names the action without its arguments. + command string + // opensCompanion is true only for a single keypress that opens this mod. + opensCompanion bool + } +) + +const ( + // surlaServerName is the MCP server name and skill folder setup writes. + surlaServerName = "surla" + // herdrModName is the companion's folder under Herdr's mods. + herdrModName = "surla" + // herdrShortcut opens the companion without taking a common terminal key. + herdrShortcut = "cmd-alt-shift-s" + // herdrShortcutAction is Herdr's command shorthand that toggles the companion. + herdrShortcutAction = "mod.open:surla" +) + +// runSetup implements `surla setup -global` for the CLI. It reads the +// process's home, executable and environment, then runs setupGlobal. +// Without -global it explains the flag instead of writing anything. +func runSetup(args []string, stdout io.Writer) error { + var global bool + fs := flag.NewFlagSet("setup", flag.ContinueOnError) + fs.BoolVar(&global, "global", false, "Register Surla with every coding agent on this computer and install the Herdr companion") + if err := fs.Parse(args); err != nil { + return err + } + if fs.NArg() > 0 { + return fmt.Errorf("unexpected arguments %q", fs.Args()) + } + if !global { + return errors.New(`surla setup changes the configuration of every coding agent on this computer; run "surla setup -global" to do that`) + } + env, err := processSetupEnvironment() + if err != nil { + return err + } + return setupGlobal(env, stdout) +} + +// setupGlobal registers ` stdio` as the surla MCP server in each +// detected coding agent's global configuration, installs the /surla skill +// for each, and installs the Herdr companion when Herdr's folder exists. It +// writes one line per change to out. Files that already hold the same entry +// or content are left untouched. A configuration file that is not valid, or +// that defines the surla entry in a form setup cannot edit, stops setup with +// an error naming the file; files written before it keep their changes. +func setupGlobal(env setupEnvironment, out io.Writer) error { + jsonTargets, tomlTargets, skillTargets := setupTargets(env) + if len(jsonTargets) == 0 && len(tomlTargets) == 0 { + fmt.Fprintln(out, "No coding agent was found on this computer; install one, then run surla setup -global again.") + } + for _, target := range jsonTargets { + changed, err := mergeMCPJSONConfig(target) + if err != nil { + return err + } + writeRegistration(out, target.path, changed) + } + for _, path := range tomlTargets { + changed, err := mergeCodexConfig(path, env.executable) + if err != nil { + return err + } + writeRegistration(out, path, changed) + } + for _, path := range skillTargets { + changed, err := writeIntegrationFile(path, skills.SurlaSkillMD) + if err != nil { + return err + } + if changed { + fmt.Fprintf(out, "Installed the /surla skill in %s\n", path) + } + } + modDir, err := setupHerdrMod(env, out) + if err != nil { + return fmt.Errorf("install the Surla companion in Herdr: %w", err) + } + if modDir != "" { + fmt.Fprintf(out, "Surla companion is in %s; open it with herdr-app do mod.open --name %s\n", modDir, herdrModName) + } + return nil +} + +// processSetupEnvironment reads the facts setup needs from this process. The +// executable must be an installed binary: a `go run` build lives in a +// temporary folder that disappears, and agents would fail to start it later. +func processSetupEnvironment() (setupEnvironment, error) { + home, err := os.UserHomeDir() + if err != nil { + return setupEnvironment{}, fmt.Errorf("resolve home directory: %w", err) + } + executable, err := os.Executable() + if err != nil { + return setupEnvironment{}, fmt.Errorf("resolve the surla executable: %w", err) + } + executable, err = filepath.Abs(executable) + if err != nil { + return setupEnvironment{}, fmt.Errorf("resolve the surla executable: %w", err) + } + if rel, err := filepath.Rel(os.TempDir(), executable); err == nil && filepath.IsLocal(rel) { + return setupEnvironment{}, fmt.Errorf("surla is running from the temporary file %s; install it (go install github.com/goadesign/surla/cmd/surla@latest) and run that surla setup -global", executable) + } + return setupEnvironment{ + home: home, + executable: executable, + getenv: os.Getenv, + onPath: func(name string) bool { + _, err := exec.LookPath(name) + return err == nil + }, + goos: runtime.GOOS, + }, nil +} + +// setupTargets lists the configuration and skill files of the coding agents +// installed under env.home: Claude Code, OpenAI Codex, Cursor, Antigravity, +// Gemini CLI, Windsurf, GitHub Copilot CLI and VS Code. The universal +// ~/.agents skill folder is always included. +func setupTargets(env setupEnvironment) ([]mcpJSONTarget, []string, []string) { + var ( + home = env.home + jsonTargets []mcpJSONTarget + tomlTargets []string + skillTargets = []string{skillPath(filepath.Join(home, ".agents"))} + stdioEntry = func() map[string]any { + return map[string]any{"command": env.executable, "args": []any{"stdio"}} + } + isDir = func(path string) bool { + info, err := os.Stat(path) + return err == nil && info.IsDir() + } + exists = func(path string) bool { + _, err := os.Stat(path) + return err == nil + } + ) + + // Claude Code keeps user servers in .claude.json and skills in skills/, + // both under CLAUDE_CONFIG_DIR when it is set. + claudeDir := filepath.Join(home, ".claude") + claudeConfig := filepath.Join(home, ".claude.json") + if dir := env.getenv("CLAUDE_CONFIG_DIR"); dir != "" { + claudeDir = dir + claudeConfig = filepath.Join(dir, ".claude.json") + } + if isDir(claudeDir) || exists(claudeConfig) || env.onPath("claude") { + jsonTargets = append(jsonTargets, mcpJSONTarget{path: claudeConfig, serversKey: "mcpServers", entry: stdioEntry()}) + skillTargets = append(skillTargets, skillPath(claudeDir)) + } + codexDir := cmp.Or(env.getenv("CODEX_HOME"), filepath.Join(home, ".codex")) + if isDir(codexDir) || env.onPath("codex") { + tomlTargets = append(tomlTargets, filepath.Join(codexDir, "config.toml")) + skillTargets = append(skillTargets, skillPath(codexDir)) + } + for _, dir := range []string{ + filepath.Join(home, ".cursor"), + filepath.Join(home, ".gemini", "config"), + filepath.Join(home, ".codeium", "windsurf"), + } { + if !isDir(dir) { + continue + } + config := filepath.Join(dir, "mcp.json") + if filepath.Base(dir) != ".cursor" { + config = filepath.Join(dir, "mcp_config.json") + } + jsonTargets = append(jsonTargets, mcpJSONTarget{path: config, serversKey: "mcpServers", entry: stdioEntry()}) + skillTargets = append(skillTargets, skillPath(dir)) + } + // Gemini CLI shares ~/.gemini with Antigravity's ~/.gemini/config, so it + // counts as installed only through its own settings, skills or command. + geminiDir := filepath.Join(home, ".gemini") + geminiSettings := filepath.Join(geminiDir, "settings.json") + if exists(geminiSettings) || isDir(filepath.Join(geminiDir, "skills")) || env.onPath("gemini") { + jsonTargets = append(jsonTargets, mcpJSONTarget{path: geminiSettings, serversKey: "mcpServers", entry: stdioEntry()}) + skillTargets = append(skillTargets, skillPath(geminiDir)) + } + copilotDir := cmp.Or(env.getenv("COPILOT_HOME"), filepath.Join(home, ".copilot")) + if isDir(copilotDir) || env.onPath("copilot") { + entry := stdioEntry() + entry["type"] = "local" + entry["tools"] = []any{"*"} + jsonTargets = append(jsonTargets, mcpJSONTarget{path: filepath.Join(copilotDir, "mcp-config.json"), serversKey: "mcpServers", entry: entry}) + skillTargets = append(skillTargets, skillPath(copilotDir)) + } + if dir := vscodeUserDir(home, env.goos); dir != "" && isDir(dir) { + entry := stdioEntry() + entry["type"] = "stdio" + jsonTargets = append(jsonTargets, mcpJSONTarget{path: filepath.Join(dir, "mcp.json"), serversKey: "servers", entry: entry}) + } + return jsonTargets, tomlTargets, skillTargets +} + +// skillPath is where a client whose folder is dir reads the /surla skill. +func skillPath(dir string) string { + return filepath.Join(dir, "skills", surlaServerName, "SKILL.md") +} + +// vscodeUserDir returns VS Code's global User settings folder on macOS and +// Linux, or "" on other systems. +func vscodeUserDir(home, goos string) string { + switch goos { + case "darwin": + return filepath.Join(home, "Library", "Application Support", "Code", "User") + case "linux": + return filepath.Join(home, ".config", "Code", "User") + default: + return "" + } +} + +// writeRegistration reports whether setup changed a client's configuration. +func writeRegistration(out io.Writer, path string, changed bool) { + if changed { + fmt.Fprintf(out, "Registered the surla MCP server in %s\n", path) + return + } + fmt.Fprintf(out, "The surla MCP server is already registered in %s\n", path) +} + +// mergeMCPJSONConfig sets target.serversKey["surla"] to target.entry in a JSON +// configuration file, keeping every other key and server. Numbers keep their +// exact text. A missing or empty file starts from an empty object. It writes +// nothing and reports false when the entry is already equal. It returns an +// error, writing nothing, when the file is not one JSON object or its server +// map is not an object, so a broken file is reported instead of replaced. +func mergeMCPJSONConfig(target mcpJSONTarget) (bool, error) { + path := target.path + raw, err := os.ReadFile(path) + if err != nil && !errors.Is(err, os.ErrNotExist) { + return false, fmt.Errorf("read %s: %w", path, err) + } + root := make(map[string]any) + if len(bytes.TrimSpace(raw)) > 0 { + decoder := json.NewDecoder(bytes.NewReader(raw)) + decoder.UseNumber() + if err := decoder.Decode(&root); err != nil { + return false, fmt.Errorf("parse JSON in %s: %w", path, err) + } + if root == nil { + return false, fmt.Errorf("%s must contain a JSON object, not null", path) + } + if _, err := decoder.Token(); !errors.Is(err, io.EOF) { + return false, fmt.Errorf("%s must contain one JSON object", path) + } + } + servers := make(map[string]any) + if existing, present := root[target.serversKey]; present { + var ok bool + if servers, ok = existing.(map[string]any); !ok || servers == nil { + return false, fmt.Errorf("%s: %s must be a JSON object", path, target.serversKey) + } + } + if sameJSON(servers[surlaServerName], target.entry) { + return false, nil + } + servers[surlaServerName] = target.entry + root[target.serversKey] = servers + + var encoded bytes.Buffer + encoder := json.NewEncoder(&encoded) + encoder.SetEscapeHTML(false) + encoder.SetIndent("", " ") + if err := encoder.Encode(root); err != nil { + return false, fmt.Errorf("encode JSON for %s: %w", path, err) + } + if err := replaceConfigFile(path, encoded.Bytes(), 0o644); err != nil { + return false, err + } + return true, nil +} + +// sameJSON reports whether existing, decoded from a file, already equals +// want once both are in JSON's decoded form. +func sameJSON(existing any, want map[string]any) bool { + if existing == nil { + return false + } + encoded, err := json.Marshal(want) + if err != nil { + return false + } + decoder := json.NewDecoder(bytes.NewReader(encoded)) + decoder.UseNumber() + var normalized any + if err := decoder.Decode(&normalized); err != nil { + return false + } + return reflect.DeepEqual(existing, normalized) +} + +// mergeCodexConfig sets mcp_servers.surla to command = executable and +// args = ["stdio"] in an OpenAI Codex config.toml, leaving every other byte +// unchanged so comments, formatting, other servers and other surla keys such +// as env survive. An existing value is replaced in place, a missing key is +// added after the [mcp_servers.surla] header, and a missing entry is appended +// as a new table. It reports false, writing nothing, when the entry already +// matches. It returns an error, writing nothing, when the file is not valid +// TOML or defines the entry in a form it cannot edit in place (an inline +// table, an array of tables, dotted keys missing command or args, a url +// transport, or values of the wrong type); the message names the setting to +// write by hand. +func mergeCodexConfig(path, executable string) (bool, error) { + content, err := os.ReadFile(path) + if err != nil && !errors.Is(err, os.ErrNotExist) { + return false, fmt.Errorf("read %s: %w", path, err) + } + commandValue := strconv.Quote(executable) + const argsValue = `["stdio"]` + byHand := fmt.Sprintf("set [mcp_servers.surla] command = %s and args = %s by hand", commandValue, argsValue) + + // Decoding checks what the position-aware parser does not: duplicate keys, + // redefined tables and type conflicts, which Codex itself refuses. + var decoded map[string]any + if err := toml.Unmarshal(content, &decoded); err != nil { + return false, fmt.Errorf("%s is not valid TOML: %w; %s", path, err, byHand) + } + servers, _ := decoded["mcp_servers"].(map[string]any) + if entry, ok := servers[surlaServerName].(map[string]any); ok { + if _, ok := entry["url"]; ok { + return false, fmt.Errorf("%s: mcp_servers.surla has a url; remove it and %s", path, byHand) + } + if entry["command"] == executable && reflect.DeepEqual(entry["args"], []any{"stdio"}) { + return false, nil + } + } + edit, err := locateCodexSurlaEntry(content) + if err != nil { + return false, fmt.Errorf("%s: %w; %s", path, err, byHand) + } + + var out []byte + switch { + case edit.afterHeader == 0 && !edit.dotted: + out = append(out, bytes.TrimRight(content, " \t\r\n")...) + if len(out) > 0 { + out = append(out, "\n\n"...) + } + out = append(out, "[mcp_servers.surla]\ncommand = "+commandValue+"\nargs = "+argsValue+"\n"...) + case edit.afterHeader == 0 && (edit.command.Length == 0 || edit.args.Length == 0): + return false, fmt.Errorf("%s: mcp_servers.surla is defined with dotted keys missing command or args; %s", path, byHand) + default: + type replacement struct { + at, length int + text string + } + var edits []replacement + var missing string + if edit.command.Length > 0 { + edits = append(edits, replacement{int(edit.command.Offset), int(edit.command.Length), commandValue}) + } else { + missing += "command = " + commandValue + "\n" + } + if edit.args.Length > 0 { + edits = append(edits, replacement{int(edit.args.Offset), int(edit.args.Length), argsValue}) + } else { + missing += "args = " + argsValue + "\n" + } + if missing != "" { + edits = append(edits, replacement{edit.afterHeader, 0, missing}) + } + // Apply from the end so earlier offsets stay valid. + slices.SortFunc(edits, func(a, b replacement) int { return b.at - a.at }) + out = slices.Clone(content) + for _, r := range edits { + text := r.text + if r.length == 0 && r.at > 0 && out[r.at-1] != '\n' { + text = "\n" + text + } + out = slices.Concat(out[:r.at], []byte(text), out[r.at+r.length:]) + } + } + if err := replaceConfigFile(path, out, 0o600); err != nil { + return false, err + } + return true, nil +} + +// locateCodexSurlaEntry parses a Codex config.toml and reports where +// mergeCodexConfig writes mcp_servers.surla. It returns an error for invalid +// TOML and for entries it cannot edit in place. Tables nested under the entry, +// such as [mcp_servers.surla.env], are left as they are. +func locateCodexSurlaEntry(doc []byte) (codexEntryEdit, error) { + var ( + edit codexEntryEdit + table []string + parser unstable.Parser + entry = []string{"mcp_servers", surlaServerName} + command = []string{"mcp_servers", surlaServerName, "command"} + args = []string{"mcp_servers", surlaServerName, "args"} + ) + parser.Reset(doc) + for parser.NextExpression() { + expr := parser.Expression() + switch expr.Kind { + case unstable.Table, unstable.ArrayTable: + var last *unstable.Node + table, last = tomlKeyPath(nil, expr.Key()) + if !slices.Equal(table, entry) { + continue + } + if expr.Kind == unstable.ArrayTable { + return edit, errors.New("mcp_servers.surla is defined as an array of tables") + } + end := int(last.Raw.Offset + last.Raw.Length) + if nl := bytes.IndexByte(doc[end:], '\n'); nl >= 0 { + edit.afterHeader = end + nl + 1 + } else { + edit.afterHeader = len(doc) + } + case unstable.KeyValue: + key, last := tomlKeyPath(slices.Clone(table), expr.Key()) + value := expr.Value() + switch { + case slices.Equal(key, command): + if value.Kind != unstable.String { + return edit, errors.New("mcp_servers.surla.command is not a string") + } + edit.command = tomlValueRange(doc, expr, last) + case slices.Equal(key, args): + if value.Kind != unstable.Array { + return edit, errors.New("mcp_servers.surla.args is not an array") + } + edit.args = tomlValueRange(doc, expr, last) + case slices.Equal(key, entry) || slices.Equal(key, entry[:1]): + return edit, errors.New("mcp_servers or mcp_servers.surla is an inline table") + } + if len(key) > 2 && slices.Equal(key[:2], entry) && len(table) < 2 { + edit.dotted = true + } + } + } + if err := parser.Error(); err != nil { + return edit, fmt.Errorf("not valid TOML: %w", err) + } + return edit, nil +} + +// tomlValueRange returns the bytes of a key/value expression's value: from +// the first non-blank byte after the '=' that follows the key's last segment +// to the end of the expression. The parser records no range for arrays, and +// the expression's own range ends where its value ends, before any comment. +func tomlValueRange(doc []byte, expr *unstable.Node, lastKey *unstable.Node) unstable.Range { + start := int(lastKey.Raw.Offset + lastKey.Raw.Length) + start += bytes.IndexByte(doc[start:], '=') + 1 + for start < len(doc) && (doc[start] == ' ' || doc[start] == '\t') { + start++ + } + end := int(expr.Raw.Offset + expr.Raw.Length) + return unstable.Range{Offset: uint32(start), Length: uint32(end - start)} +} + +// tomlKeyPath appends the decoded segments of a TOML key (bare, quoted or +// dotted) to prefix and returns the path with the last segment's node, whose +// Raw range ends the key in the input. +func tomlKeyPath(prefix []string, it unstable.Iterator) ([]string, *unstable.Node) { + var last *unstable.Node + for it.Next() { + last = it.Node() + prefix = append(prefix, string(last.Data)) + } + return prefix, last +} + +// setupHerdrMod installs the companion's runtime files into Herdr's existing +// home folder (HERDR_APP_HOME, else ~/.config/herdr-app), which Herdr creates +// on its first start. Only mod.json and main.js are written, manifest first; +// identical files are left alone because Herdr reloads a mod whenever its +// files are written. On macOS the shortcut is added when its key is free. It +// returns the mod folder, or "" when Herdr has no home folder. +func setupHerdrMod(env setupEnvironment, out io.Writer) (string, error) { + herdrHome := cmp.Or(env.getenv("HERDR_APP_HOME"), filepath.Join(env.home, ".config", "herdr-app")) + info, err := os.Stat(herdrHome) + if errors.Is(err, os.ErrNotExist) { + return "", nil + } + if err != nil { + return "", fmt.Errorf("inspect Herdr configuration %s: %w", herdrHome, err) + } + if !info.IsDir() { + return "", nil + } + modDir := filepath.Join(herdrHome, "mods", herdrModName) + for _, name := range []string{"mod.json", "main.js"} { + content, err := skills.HerdrMod.ReadFile("herdr/surla/" + name) + if err != nil { + return "", fmt.Errorf("read bundled %s: %w", name, err) + } + if _, err := writeIntegrationFile(filepath.Join(modDir, name), content); err != nil { + return "", err + } + } + if env.goos == "darwin" { + if err := setupHerdrShortcut(herdrHome, out); err != nil { + return "", err + } + } + return modDir, nil +} + +// setupHerdrShortcut adds cmd-alt-shift-s to Herdr's global keyboard section +// when no section binds that key yet. A missing or read-only keyboard file is +// reported and left alone; a malformed one is an error and is not written. +// Editing the file makes Herdr treat it as the user's own on later upgrades. +func setupHerdrShortcut(herdrHome string, out io.Writer) error { + path := filepath.Join(herdrHome, "keys.json") + raw, err := os.ReadFile(path) + if errors.Is(err, os.ErrNotExist) { + fmt.Fprintln(out, "Herdr's keyboard file is missing; open Herdr once and run surla setup -global again to add the shortcut.") + return nil + } + if err != nil { + return fmt.Errorf("read Herdr keyboard settings %s: %w", path, err) + } + info, err := os.Stat(path) + if err != nil { + return fmt.Errorf("inspect Herdr keyboard settings %s: %w", path, err) + } + if info.Mode().Perm()&0o222 == 0 { + fmt.Fprintf(out, "Herdr keyboard settings %s are read-only; kept them unchanged.\n", path) + return nil + } + updated, existing, err := addHerdrShortcut(raw) + if err != nil { + return fmt.Errorf("parse Herdr keyboard settings %s: %w", path, err) + } + if existing != nil { + if existing.opensCompanion { + fmt.Fprintf(out, "Herdr shortcut %s already opens the Surla companion.\n", herdrShortcut) + } else { + fmt.Fprintf(out, "Herdr shortcut %s is taken by %q in %q; kept that binding.\n", herdrShortcut, existing.command, existing.section) + } + return nil + } + if err := replaceConfigFile(path, updated, info.Mode().Perm()); err != nil { + return err + } + fmt.Fprintf(out, "Added Herdr shortcut %s to open the Surla companion. Herdr now treats keys.json as your own.\n", herdrShortcut) + return nil +} + +// addHerdrShortcut validates a whole keyboard document and adds the companion +// binding to its global object, creating that object when absent. Any binding +// of the same first keypress in any section prevents the insertion and is +// returned instead. Bytes outside the insertion stay unchanged. +func addHerdrShortcut(raw []byte) ([]byte, *herdrShortcutBinding, error) { + decoder := json.NewDecoder(bytes.NewReader(raw)) + token, err := decoder.Token() + if err != nil { + if errors.Is(err, io.EOF) { + return nil, nil, errors.New("keyboard settings file is empty") + } + return nil, nil, err + } + if token != json.Delim('{') { + return nil, nil, errors.New("keyboard settings must contain a JSON object") + } + var existing *herdrShortcutBinding + var rootHasMembers, globalHasMembers bool + globalClose := -1 + for decoder.More() { + token, err := decoder.Token() + if err != nil { + return nil, nil, err + } + section := token.(string) + var value json.RawMessage + if err := decoder.Decode(&value); err != nil { + return nil, nil, err + } + rootHasMembers = true + if section != "global" && section != "terminal" && !strings.HasPrefix(section, "layout:") && !strings.HasPrefix(section, "mod:") { + continue + } + var bindings map[string]json.RawMessage + if err := json.Unmarshal(value, &bindings); err != nil || bindings == nil { + return nil, nil, fmt.Errorf("%s must contain a JSON object", section) + } + if section == "global" { + if globalClose >= 0 { + return nil, nil, errors.New("keyboard settings contain more than one global section") + } + globalClose = int(decoder.InputOffset()) - 1 + globalHasMembers = len(bindings) > 0 + } + for chord, action := range bindings { + if !herdrShortcutMatches(chord) { + continue + } + binding := herdrBindingFor(section, chord, action) + // A conflicting binding wins over one that opens the companion, + // because it can intercept the key in its context. + if existing == nil || !binding.opensCompanion { + existing = binding + } + } + } + if _, err := decoder.Token(); err != nil { + return nil, nil, err + } + rootClose := int(decoder.InputOffset()) - 1 + if _, err := decoder.Token(); !errors.Is(err, io.EOF) { + return nil, nil, errors.New("keyboard settings must contain one JSON object") + } + if existing != nil { + return raw, existing, nil + } + member := fmt.Sprintf("%q: %q", herdrShortcut, herdrShortcutAction) + if globalClose >= 0 { + return insertJSONMember(raw, globalClose, globalHasMembers, member), nil, nil + } + member = fmt.Sprintf("%q: {%s}", "global", member) + return insertJSONMember(raw, rootClose, rootHasMembers, member), nil, nil +} + +// herdrBindingFor describes the action bound to chord in section, which is +// either the "command:arg" shorthand or a {command, args} object. +func herdrBindingFor(section, chord string, action json.RawMessage) *herdrShortcutBinding { + var name string + var object struct { + // Command is the app action selected by this binding. + Command string `json:"command"` + // Args holds the action's named arguments without re-encoding them. + Args map[string]json.RawMessage `json:"args"` + } + opens := false + if json.Unmarshal(action, &name) == nil { + opens = name == herdrShortcutAction + name, _, _ = strings.Cut(name, ":") + } else if json.Unmarshal(action, &object) == nil { + name = object.Command + var mod string + opens = object.Command == "mod.open" && len(object.Args) == 1 && json.Unmarshal(object.Args["name"], &mod) == nil && mod == herdrModName + } + return &herdrShortcutBinding{ + section: section, + command: name, + opensCompanion: opens && len(strings.Fields(chord)) == 1, + } +} + +// herdrShortcutMatches reports whether chord starts with cmd-alt-shift-s, +// accepting Herdr's modifier aliases and the implicit shift of an uppercase +// letter. A sequence that starts with this keypress also occupies it. +func herdrShortcutMatches(chord string) bool { + strokes := strings.Fields(chord) + if len(strokes) == 0 { + return false + } + parts := strings.Split(strokes[0], "-") + key := parts[len(parts)-1] + if key != "s" && key != "S" { + return false + } + held := make(map[string]bool) + for _, modifier := range parts[:len(parts)-1] { + modifier = strings.ToLower(modifier) + switch modifier { + case "secondary", "super", "win": + modifier = "cmd" + case "option": + modifier = "alt" + } + held[modifier] = true + } + if key == "S" { + held["shift"] = true + } + return len(held) == 3 && held["cmd"] && held["alt"] && held["shift"] +} + +// insertJSONMember adds member before a validated object's closing brace at +// closeOffset, matching the object's existing indentation and line endings +// and leaving every other byte unchanged. +func insertJSONMember(raw []byte, closeOffset int, hasMembers bool, member string) []byte { + at := closeOffset + for at > 0 && strings.ContainsRune(" \t\r\n", rune(raw[at-1])) { + at-- + } + separator := "" + if hasMembers { + separator = "," + } + var insertion string + if bytes.ContainsRune(raw[at:closeOffset], '\n') { + line := bytes.LastIndexByte(raw[:closeOffset], '\n') + 1 + indent := string(raw[line:closeOffset]) + memberIndent := indent + " " + if hasMembers { + previous := bytes.LastIndexByte(raw[:at], '\n') + 1 + end := previous + for end < at && (raw[end] == ' ' || raw[end] == '\t') { + end++ + } + memberIndent = string(raw[previous:end]) + } + newline := "\n" + if bytes.Contains(raw[at:closeOffset], []byte("\r\n")) { + newline = "\r\n" + } + insertion = separator + newline + memberIndent + member + newline + indent + } else { + insertion = separator + member + string(raw[at:closeOffset]) + } + return slices.Concat(raw[:at], []byte(insertion), raw[closeOffset:]) +} + +// replaceConfigFile atomically replaces the file at path with content, +// following a symlink to its target so dotfile managers keep their link. An +// existing file keeps its permissions; a new one gets perm and any missing +// parent folders. +func replaceConfigFile(path string, content []byte, perm os.FileMode) (err error) { + target := path + if resolved, err := filepath.EvalSymlinks(path); err == nil { + target = resolved + } else if !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("resolve %s: %w", path, err) + } + if info, err := os.Stat(target); err == nil { + perm = info.Mode().Perm() + } else if !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("inspect %s: %w", target, err) + } + if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil { + return fmt.Errorf("create folder for %s: %w", target, err) + } + file, err := os.CreateTemp(filepath.Dir(target), ".surla-setup-*") + if err != nil { + return fmt.Errorf("create update for %s: %w", target, err) + } + defer func() { + if cleanupErr := os.Remove(file.Name()); cleanupErr != nil && !errors.Is(cleanupErr, os.ErrNotExist) { + err = errors.Join(err, fmt.Errorf("remove temporary file for %s: %w", target, cleanupErr)) + } + }() + writeErr := file.Chmod(perm) + if writeErr == nil { + _, writeErr = file.Write(content) + } + if writeErr == nil { + writeErr = file.Sync() + } + if err := errors.Join(writeErr, file.Close()); err != nil { + return fmt.Errorf("write %s: %w", target, err) + } + if err := os.Rename(file.Name(), target); err != nil { + return fmt.Errorf("replace %s: %w", target, err) + } + return nil +} + +// writeIntegrationFile installs bundled skill or mod content at path, +// creating folders as needed, and reports whether it wrote. Identical files +// are left untouched: Herdr reloads a mod whenever its files are written. +func writeIntegrationFile(path string, content []byte) (bool, error) { + installed, err := os.ReadFile(path) + if err != nil && !errors.Is(err, os.ErrNotExist) { + return false, fmt.Errorf("read %s: %w", path, err) + } + if err == nil && bytes.Equal(installed, content) { + return false, nil + } + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return false, fmt.Errorf("create folder for %s: %w", path, err) + } + if err := os.WriteFile(path, content, 0o644); err != nil { + return false, fmt.Errorf("write %s: %w", path, err) + } + return true, nil +} diff --git a/cmd/surla/setup_test.go b/cmd/surla/setup_test.go new file mode 100644 index 00000000..711e6b4b --- /dev/null +++ b/cmd/surla/setup_test.go @@ -0,0 +1,428 @@ +package main + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/goadesign/surla/skills" +) + +// testExecutable is the surla path setup tests register. +const testExecutable = "/opt/surla/bin/surla" + +// testSetupEnvironment points setup at home with no environment overrides and +// no commands on PATH, so tests never read or write the user's configuration. +func testSetupEnvironment(home string) setupEnvironment { + return setupEnvironment{ + home: home, + executable: testExecutable, + getenv: func(string) string { return "" }, + onPath: func(string) bool { return false }, + goos: "darwin", + } +} + +// writeTestFile creates path with content and any missing folders. +func writeTestFile(t *testing.T, path, content string) { + t.Helper() + require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o755)) + require.NoError(t, os.WriteFile(path, []byte(content), 0o644)) +} + +// readTestJSON decodes the JSON object stored at path. +func readTestJSON(t *testing.T, path string) map[string]any { + t.Helper() + raw, err := os.ReadFile(path) + require.NoError(t, err) + var root map[string]any + require.NoError(t, json.Unmarshal(raw, &root)) + return root +} + +func TestSetupRegistersEveryDetectedClientOnce(t *testing.T) { + home := t.TempDir() + for _, dir := range []string{ + ".claude", ".codex", ".cursor", ".gemini/config", ".gemini/skills", ".codeium/windsurf", ".copilot", + "Library/Application Support/Code/User", + } { + require.NoError(t, os.MkdirAll(filepath.Join(home, dir), 0o755)) + } + herdrHome := filepath.Join(home, ".config", "herdr-app") + writeTestFile(t, filepath.Join(herdrHome, "keys.json"), "{\n \"global\": {\n \"cmd-k\": \"app.palette\"\n }\n}\n") + + var out bytes.Buffer + require.NoError(t, setupGlobal(testSetupEnvironment(home), &out)) + + stdio := map[string]any{"command": testExecutable, "args": []any{"stdio"}} + jsonConfigs := []struct { + path, serversKey string + want map[string]any + }{ + {".claude.json", "mcpServers", stdio}, + {".cursor/mcp.json", "mcpServers", stdio}, + {".gemini/config/mcp_config.json", "mcpServers", stdio}, + {".gemini/settings.json", "mcpServers", stdio}, + {".codeium/windsurf/mcp_config.json", "mcpServers", stdio}, + {".copilot/mcp-config.json", "mcpServers", map[string]any{"type": "local", "command": testExecutable, "args": []any{"stdio"}, "tools": []any{"*"}}}, + {"Library/Application Support/Code/User/mcp.json", "servers", map[string]any{"type": "stdio", "command": testExecutable, "args": []any{"stdio"}}}, + } + for _, c := range jsonConfigs { + servers, _ := readTestJSON(t, filepath.Join(home, c.path))[c.serversKey].(map[string]any) + assert.Equal(t, c.want, servers["surla"], c.path) + } + codex, err := os.ReadFile(filepath.Join(home, ".codex", "config.toml")) + require.NoError(t, err) + assert.Equal(t, "[mcp_servers.surla]\ncommand = \"/opt/surla/bin/surla\"\nargs = [\"stdio\"]\n", string(codex)) + for _, dir := range []string{".agents", ".claude", ".codex", ".cursor", ".gemini/config", ".gemini", ".codeium/windsurf", ".copilot"} { + skill, err := os.ReadFile(filepath.Join(home, dir, "skills", "surla", "SKILL.md")) + require.NoError(t, err, dir) + assert.Equal(t, skills.SurlaSkillMD, skill, dir) + } + + modDir := filepath.Join(herdrHome, "mods", "surla") + entries, err := os.ReadDir(modDir) + require.NoError(t, err) + var names []string + for _, entry := range entries { + names = append(names, entry.Name()) + } + assert.Equal(t, []string{"main.js", "mod.json"}, names, "only runtime files are installed") + keys := readTestJSON(t, filepath.Join(herdrHome, "keys.json")) + assert.Equal(t, map[string]any{"cmd-k": "app.palette", "cmd-alt-shift-s": "mod.open:surla"}, keys["global"]) + assert.Contains(t, out.String(), "Added Herdr shortcut cmd-alt-shift-s") + + // A second run finds everything in place and writes nothing. + before := snapshotTree(t, home) + out.Reset() + require.NoError(t, setupGlobal(testSetupEnvironment(home), &out)) + assert.Equal(t, before, snapshotTree(t, home)) + assert.Equal(t, 8, strings.Count(out.String(), "is already registered in"), out.String()) + assert.NotContains(t, out.String(), "Installed") + assert.Contains(t, out.String(), "Herdr shortcut cmd-alt-shift-s already opens the Surla companion.") +} + +// snapshotTree records every file's bytes and modification time under root. +func snapshotTree(t *testing.T, root string) map[string]string { + t.Helper() + files := make(map[string]string) + require.NoError(t, filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error { + if err != nil || entry.IsDir() { + return err + } + info, err := entry.Info() + if err != nil { + return err + } + content, err := os.ReadFile(path) + if err != nil { + return err + } + files[path] = info.ModTime().String() + "\n" + string(content) + return nil + })) + return files +} + +func TestSetupDetectsClientsByEnvironmentAndPath(t *testing.T) { + home := t.TempDir() + claudeDir := filepath.Join(t.TempDir(), "claude") + codexDir := filepath.Join(t.TempDir(), "codex") + env := testSetupEnvironment(home) + env.goos = "linux" + env.getenv = func(name string) string { + return map[string]string{"CLAUDE_CONFIG_DIR": claudeDir, "CODEX_HOME": codexDir}[name] + } + env.onPath = func(name string) bool { return name == "claude" || name == "codex" || name == "gemini" } + + jsonTargets, tomlTargets, skillTargets := setupTargets(env) + var paths []string + for _, target := range jsonTargets { + paths = append(paths, target.path) + } + assert.Equal(t, []string{filepath.Join(claudeDir, ".claude.json"), filepath.Join(home, ".gemini", "settings.json")}, paths) + assert.Equal(t, []string{filepath.Join(codexDir, "config.toml")}, tomlTargets) + assert.Equal(t, []string{ + filepath.Join(home, ".agents", "skills", "surla", "SKILL.md"), + filepath.Join(claudeDir, "skills", "surla", "SKILL.md"), + filepath.Join(codexDir, "skills", "surla", "SKILL.md"), + filepath.Join(home, ".gemini", "skills", "surla", "SKILL.md"), + }, skillTargets) + + // Antigravity's ~/.gemini/config alone does not make Gemini CLI a target. + require.NoError(t, os.MkdirAll(filepath.Join(home, ".gemini", "config"), 0o755)) + jsonTargets, _, _ = setupTargets(testSetupEnvironment(home)) + require.Len(t, jsonTargets, 1) + assert.Equal(t, filepath.Join(home, ".gemini", "config", "mcp_config.json"), jsonTargets[0].path) +} + +func TestSetupWithoutClientsOrHerdrInstallsOnlyTheUniversalSkill(t *testing.T) { + home := t.TempDir() + var out bytes.Buffer + require.NoError(t, setupGlobal(testSetupEnvironment(home), &out)) + assert.Contains(t, out.String(), "No coding agent was found") + assert.NotContains(t, out.String(), "companion") + files := snapshotTree(t, home) + require.Len(t, files, 1) + _, ok := files[filepath.Join(home, ".agents", "skills", "surla", "SKILL.md")] + assert.True(t, ok) +} + +func TestRunSetupRequiresGlobal(t *testing.T) { + err := runSetup(nil, &bytes.Buffer{}) + require.Error(t, err) + assert.Contains(t, err.Error(), `run "surla setup -global"`) + assert.ErrorContains(t, runSetup([]string{"-global", "extra"}, &bytes.Buffer{}), `unexpected arguments ["extra"]`) +} + +func TestSetupJSONConfigMerge(t *testing.T) { + entry := map[string]any{"command": testExecutable, "args": []any{"stdio"}} + cases := []struct { + name, content string + changed bool + wantErr string + check func(t *testing.T, root map[string]any, raw string) + }{ + {name: "missing file", changed: true}, + {name: "empty file", content: " \n", changed: true}, + { + name: "keeps other keys, servers and exact numbers", + content: `{"numStartups": 12345678901234567890, "tip": "&", "mcpServers": {"chorus": {"type": "http", "url": "http://127.0.0.1:9440/mcp"}, "surla": {"type": "http", "url": "http://old"}}}`, + changed: true, + check: func(t *testing.T, root map[string]any, raw string) { + assert.Contains(t, raw, "12345678901234567890") + assert.Contains(t, raw, `"&"`) + servers := root["mcpServers"].(map[string]any) + assert.Equal(t, map[string]any{"type": "http", "url": "http://127.0.0.1:9440/mcp"}, servers["chorus"]) + }, + }, + {name: "already registered", content: `{"mcpServers": {"surla": {"args": ["stdio"], "command": "/opt/surla/bin/surla"}}}`, changed: false}, + {name: "null", content: "null", wantErr: "must contain a JSON object, not null"}, + {name: "array", content: "[]", wantErr: "parse JSON"}, + {name: "invalid", content: "{", wantErr: "parse JSON"}, + {name: "trailing data", content: "{} {}", wantErr: "must contain one JSON object"}, + {name: "servers not an object", content: `{"mcpServers": []}`, wantErr: "mcpServers must be a JSON object"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + path := filepath.Join(t.TempDir(), "config", "mcp.json") + if c.content != "" { + writeTestFile(t, path, c.content) + } + changed, err := mergeMCPJSONConfig(mcpJSONTarget{path: path, serversKey: "mcpServers", entry: entry}) + if c.wantErr != "" { + assert.ErrorContains(t, err, c.wantErr) + raw, readErr := os.ReadFile(path) + require.NoError(t, readErr) + assert.Equal(t, c.content, string(raw), "a refused file is not written") + return + } + require.NoError(t, err) + assert.Equal(t, c.changed, changed) + raw, err := os.ReadFile(path) + require.NoError(t, err) + if !c.changed { + assert.Equal(t, c.content, string(raw)) + } + root := readTestJSON(t, path) + assert.Equal(t, entry, root["mcpServers"].(map[string]any)["surla"]) + if c.check != nil { + c.check(t, root, string(raw)) + } + }) + } +} + +func TestSetupJSONConfigFollowsSymlinkAndKeepsPermissions(t *testing.T) { + dir := t.TempDir() + target := filepath.Join(dir, "dotfiles", "claude.json") + writeTestFile(t, target, `{"theme": "dark"}`) + require.NoError(t, os.Chmod(target, 0o600)) + link := filepath.Join(dir, ".claude.json") + require.NoError(t, os.Symlink(target, link)) + + changed, err := mergeMCPJSONConfig(mcpJSONTarget{path: link, serversKey: "mcpServers", entry: map[string]any{"command": testExecutable}}) + require.NoError(t, err) + assert.True(t, changed) + resolved, err := os.Readlink(link) + require.NoError(t, err) + assert.Equal(t, target, resolved, "the link still points at the dotfile") + info, err := os.Stat(target) + require.NoError(t, err) + assert.Equal(t, os.FileMode(0o600), info.Mode().Perm()) + assert.Equal(t, "dark", readTestJSON(t, target)["theme"]) +} + +func TestSetupCodexConfigMerge(t *testing.T) { + const table = "[mcp_servers.surla]\ncommand = \"/opt/surla/bin/surla\"\nargs = [\"stdio\"]\n" + cases := []struct { + name, content, want string + changed bool + wantErr string + }{ + {name: "missing file", want: table, changed: true}, + { + name: "appends after other settings", + content: "# my settings\nmodel = \"gpt\"\n\n[mcp_servers.chorus]\nurl = \"http://127.0.0.1:9440/mcp\"\n\n", + want: "# my settings\nmodel = \"gpt\"\n\n[mcp_servers.chorus]\nurl = \"http://127.0.0.1:9440/mcp\"\n\n" + table, + changed: true, + }, + { + name: "replaces values in place and keeps other keys", + content: "[mcp_servers.surla]\ncommand = 'old/surla' # pinned\nargs = [\"serve\", \"-x\"]\nstartup_timeout_sec = 30\n\n[mcp_servers.surla.env]\nA = \"1\"\n", + want: "[mcp_servers.surla]\ncommand = \"/opt/surla/bin/surla\" # pinned\nargs = [\"stdio\"]\nstartup_timeout_sec = 30\n\n[mcp_servers.surla.env]\nA = \"1\"\n", + changed: true, + }, + { + name: "adds missing keys after the header", + content: "[mcp_servers.surla]\nstartup_timeout_sec = 30\n", + want: "[mcp_servers.surla]\ncommand = \"/opt/surla/bin/surla\"\nargs = [\"stdio\"]\nstartup_timeout_sec = 30\n", + changed: true, + }, + { + name: "adds a key after a header at the end of the file", + content: "[mcp_servers.surla]", + want: "[mcp_servers.surla]\ncommand = \"/opt/surla/bin/surla\"\nargs = [\"stdio\"]\n", + changed: true, + }, + { + name: "replaces dotted keys", + content: "[mcp_servers]\nsurla.command = \"old\"\nsurla.args = []\n", + want: "[mcp_servers]\nsurla.command = \"/opt/surla/bin/surla\"\nsurla.args = [\"stdio\"]\n", + changed: true, + }, + { + name: "replaces a multiline array with comments", + content: "[mcp_servers.surla]\nargs = [\n \"serve\", # old ]\n \"-x\",\n] # end\ncommand = \"/opt/surla/bin/surla\"\n", + want: "[mcp_servers.surla]\nargs = [\"stdio\"] # end\ncommand = \"/opt/surla/bin/surla\"\n", + changed: true, + }, + {name: "already registered", content: "# keep\n" + table, changed: false}, + {name: "dotted keys missing args", content: "[mcp_servers]\nsurla.command = \"old\"\n", wantErr: "dotted keys missing command or args"}, + {name: "inline table", content: "[mcp_servers]\nsurla = { command = \"old\" }\n", wantErr: "inline table"}, + {name: "array of tables", content: "[[mcp_servers.surla]]\ncommand = \"old\"\n", wantErr: "array of tables"}, + {name: "url transport", content: "[mcp_servers.surla]\nurl = \"http://old\"\n", wantErr: "has a url"}, + {name: "command not a string", content: "[mcp_servers.surla]\ncommand = 3\n", wantErr: "command is not a string"}, + {name: "invalid TOML", content: "[mcp_servers.surla\n", wantErr: "is not valid TOML"}, + {name: "duplicate key", content: "a = 1\na = 2\n", wantErr: "is not valid TOML"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + path := filepath.Join(t.TempDir(), ".codex", "config.toml") + if c.content != "" { + writeTestFile(t, path, c.content) + } + changed, err := mergeCodexConfig(path, testExecutable) + raw, _ := os.ReadFile(path) + if c.wantErr != "" { + assert.ErrorContains(t, err, c.wantErr) + assert.ErrorContains(t, err, `set [mcp_servers.surla] command = "/opt/surla/bin/surla" and args = ["stdio"] by hand`) + assert.Equal(t, c.content, string(raw), "a refused file is not written") + return + } + require.NoError(t, err) + assert.Equal(t, c.changed, changed) + if c.changed { + assert.Equal(t, c.want, string(raw)) + } else { + assert.Equal(t, c.content, string(raw)) + } + }) + } +} + +func TestSetupCodexConfigIsPrivateWhenCreated(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + _, err := mergeCodexConfig(path, testExecutable) + require.NoError(t, err) + info, err := os.Stat(path) + require.NoError(t, err) + assert.Equal(t, os.FileMode(0o600), info.Mode().Perm()) +} + +func TestSetupHerdrShortcut(t *testing.T) { + cases := []struct { + name, keys, want, output string + wantErr string + }{ + { + name: "adds to the global section", + keys: "{\n \"global\": {\n \"cmd-k\": \"app.palette\"\n }\n}\n", + want: "{\n \"global\": {\n \"cmd-k\": \"app.palette\",\n \"cmd-alt-shift-s\": \"mod.open:surla\"\n }\n}\n", + output: "Added Herdr shortcut cmd-alt-shift-s", + }, + { + name: "creates the global section", + keys: "{\"terminal\": {\"ctrl-c\": \"terminal.copy\"}}", + want: "{\"terminal\": {\"ctrl-c\": \"terminal.copy\"},\"global\": {\"cmd-alt-shift-s\": \"mod.open:surla\"}}", + output: "Added Herdr shortcut", + }, + {name: "keeps a conflicting binding", keys: `{"terminal": {"super-option-S": "terminal.split"}}`, output: `is taken by "terminal.split" in "terminal"`}, + {name: "keeps a sequence starting with the key", keys: `{"global": {"cmd-alt-shift-s g": "app.help"}}`, output: `is taken by "app.help"`}, + {name: "already opens the companion", keys: `{"global": {"cmd-alt-shift-s": {"command": "mod.open", "args": {"name": "surla"}}}}`, output: "already opens the Surla companion"}, + {name: "another key is free", keys: `{"global": {"cmd-alt-s": "app.help", "cmd-alt-shift-c": "mod.open:chorus-launcher"}}`, want: `{"global": {"cmd-alt-s": "app.help", "cmd-alt-shift-c": "mod.open:chorus-launcher","cmd-alt-shift-s": "mod.open:surla"}}`, output: "Added"}, + {name: "malformed", keys: `{"global": []}`, wantErr: "global must contain a JSON object"}, + {name: "two documents", keys: `{} {}`, wantErr: "must contain one JSON object"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + herdrHome := t.TempDir() + path := filepath.Join(herdrHome, "keys.json") + writeTestFile(t, path, c.keys) + var out bytes.Buffer + err := setupHerdrShortcut(herdrHome, &out) + raw, readErr := os.ReadFile(path) + require.NoError(t, readErr) + if c.wantErr != "" { + assert.ErrorContains(t, err, c.wantErr) + assert.Equal(t, c.keys, string(raw)) + return + } + require.NoError(t, err) + assert.Contains(t, out.String(), c.output) + want := c.want + if want == "" { + want = c.keys + } + assert.Equal(t, want, string(raw)) + }) + } +} + +func TestSetupHerdrModOutsideMacOSAddsNoShortcut(t *testing.T) { + home := t.TempDir() + herdrHome := filepath.Join(home, "herdr") + writeTestFile(t, filepath.Join(herdrHome, "keys.json"), "{}") + env := testSetupEnvironment(home) + env.goos = "linux" + env.getenv = func(name string) string { + return map[string]string{"HERDR_APP_HOME": herdrHome}[name] + } + var out bytes.Buffer + modDir, err := setupHerdrMod(env, &out) + require.NoError(t, err) + assert.Equal(t, filepath.Join(herdrHome, "mods", "surla"), modDir) + keys, err := os.ReadFile(filepath.Join(herdrHome, "keys.json")) + require.NoError(t, err) + assert.Equal(t, "{}", string(keys)) + manifest, err := os.ReadFile(filepath.Join(modDir, "mod.json")) + require.NoError(t, err) + assert.Contains(t, string(manifest), `"kind": "window"`) +} + +func TestSetupHerdrModReportsMissingKeyboardFile(t *testing.T) { + home := t.TempDir() + require.NoError(t, os.MkdirAll(filepath.Join(home, ".config", "herdr-app"), 0o755)) + var out bytes.Buffer + _, err := setupHerdrMod(testSetupEnvironment(home), &out) + require.NoError(t, err) + assert.Contains(t, out.String(), "Herdr's keyboard file is missing") + _, err = os.Stat(filepath.Join(home, ".config", "herdr-app", "keys.json")) + assert.ErrorIs(t, err, os.ErrNotExist) +} diff --git a/go.mod b/go.mod index 361aa3ff..34a60ddd 100644 --- a/go.mod +++ b/go.mod @@ -7,6 +7,7 @@ require ( github.com/goadesign/surla/story v0.0.0-20261111183703-4568fcf5bb85 github.com/google/uuid v1.6.0 github.com/openai/openai-go/v3 v3.91.0 + github.com/pelletier/go-toml/v2 v2.4.3 github.com/stretchr/testify v1.12.1 github.com/yosida95/uritemplate/v3 v3.0.2 go.opentelemetry.io/otel v1.47.0 diff --git a/go.sum b/go.sum index c3cc1a76..b913e0bb 100644 --- a/go.sum +++ b/go.sum @@ -151,6 +151,8 @@ github.com/pb33f/go-yaml v0.1.1/go.mod h1:QvWdkHP5VjFYAeHMQUkaPQqREaQnBNOXmWzAjN github.com/pb33f/ordered-map/v2 v2.3.2 h1:wDyaZ2Pv9QLh64X4utCeD5Zoi9nIv2aW3lwv172O5PQ= github.com/pb33f/ordered-map/v2 v2.3.2/go.mod h1:1OhFrXu3OYw3kM+FXF+Ug3ugmmZ9LE8z0JfQMLvtV0w= github.com/pborman/getopt v0.0.0-20170112200414-7148bc3a4c30/go.mod h1:85jBQOZwpVEaDAr341tbn15RS4fCAsIst0qp7i8ex1o= +github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY= +github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY= github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo= github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8= github.com/redis/go-redis/v9 v9.23.0 h1:/TTVdJa8BRNsybwwGGnmiYktHNlUXtbOQxlWpHBPL3s= diff --git a/skills/embed.go b/skills/embed.go new file mode 100644 index 00000000..27012525 --- /dev/null +++ b/skills/embed.go @@ -0,0 +1,18 @@ +// Package skills embeds the /surla agent skill and the Surla Herdr companion +// mod, so `surla setup -global` installs them without downloading anything. +package skills + +import "embed" + +// SurlaSkillMD holds skills/surla/SKILL.md, the /surla ($surla) agent skill +// that setup installs next to each detected coding agent. +// +//go:embed surla/SKILL.md +var SurlaSkillMD []byte + +// HerdrMod holds the runtime files of the Surla companion mod that setup +// copies into Herdr's mods folder. Its tests (test_mod.mjs) stay in the +// repository and are not embedded. +// +//go:embed herdr/surla/mod.json herdr/surla/main.js +var HerdrMod embed.FS diff --git a/skills/herdr/surla/main.js b/skills/herdr/surla/main.js new file mode 100644 index 00000000..0f27a26e --- /dev/null +++ b/skills/herdr/surla/main.js @@ -0,0 +1,269 @@ +// Surla companion: a floating window for the Surla project of the shown +// Herdr space. It shows the project's stage and change, what needs the user, +// each role's state with a button that focuses its pane, and a button that +// opens (or starts) the project's views page. It reads only `surla status +// --json` and Herdr's own terminal labels; it holds no Surla credential. + +import { View, div } from "gpui-kit"; +import { h_flex, v_flex } from "gpui-base"; +import { spaces, terminals, panes, focused, theme, exec, run, closeOverlay, props, checking } from "herdr"; + +// POLL_MS is how often the window asks `surla status --json` again. +const POLL_MS = 4000; +// STATUS_TIMEOUT_MS bounds one status read so a stuck command cannot pile up. +const STATUS_TIMEOUT_MS = 10000; +// OPEN_TIMEOUT_MS bounds `surla`, which may start the project's server first. +const OPEN_TIMEOUT_MS = 60000; + +// STAGES names each stage of ProjectStatus.stage for people. +const STAGES = { + describe: "Describe", + agree: "Agree", + build: "Build", + check: "Check", + approve: "Approve", + merged: "Merged", +}; + +// ROLE_TITLES names each registered role for people. +const ROLE_TITLES = { guide: "Guide", builder: "Builder", test_writer: "Test writer" }; + +// ROLE_STATES describes each TeamRoleState.state for people. +const ROLE_STATES = { + not_started: "not started", + ended: "ended", + starting: "starting", + needs_you: "needs you", + working: "working", + waiting: "waiting", + error: "error", + unknown: "unknown", +}; + +// projectFolder returns the folder whose Surla project the window shows for +// space, or null when there is none to ask about. A space on another machine +// has none: `surla` runs on this computer. The first live terminal in the +// space labeled with a Surla project names it; otherwise the focused pane's +// folder when it is in this space, then the first pane's folder, then the +// space's own folder. +export function projectFolder(space, terms, paneList, focus) { + if (!space || space.machine) return null; + for (const term of terms ?? []) { + const labels = term?.labels ?? {}; + if (term?.state === "live" && labels["herdr.space"] === space.id && typeof labels["chorus.project"] === "string" && labels["chorus.project"]) { + return labels["chorus.project"]; + } + } + if (focus?.space === space.id && focus.cwd) return focus.cwd; + const tabs = new Set((space.tabs ?? []).map(tab => tab.id)); + const pane = (paneList ?? []).find(p => tabs.has(p.tab) && p.cwd); + if (pane) return pane.cwd; + return space.folder || null; +} + +// STATUS_FIELDS are the string fields every running `surla status --json` +// answer carries; ROLE_FIELDS are those of each roles[] entry. +const STATUS_FIELDS = ["project_name", "directory", "team", "herdr_mode", "stage", "change_id", "change_title", "attention"]; +const ROLE_FIELDS = ["role", "handle", "state", "attention", "watcher", "assignment"]; + +// parseStatus turns the result of `surla status --json` into what the window +// shows: { kind: "running", status }, { kind: "stopped" } when no server runs +// for the folder, or { kind: "error", message } for a failed command or an +// answer missing a required field. An incomplete answer is reported, never +// filled in. +export function parseStatus(result) { + if (!result || result.code !== 0) { + const message = (result?.stderr || result?.stdout || "").trim(); + return { kind: "error", message: message || "surla status failed." }; + } + let value; + try { + value = JSON.parse(result.stdout); + } catch { + return { kind: "error", message: "surla status printed something other than JSON." }; + } + if (!value || typeof value !== "object" || typeof value.running !== "boolean") { + return { kind: "error", message: "surla status did not say whether a server is running." }; + } + if (!value.running) return { kind: "stopped" }; + const missing = STATUS_FIELDS.find(field => typeof value[field] !== "string"); + if (missing) return { kind: "error", message: `surla status answered without ${missing}.` }; + if (!Array.isArray(value.roles)) return { kind: "error", message: "surla status answered without roles." }; + for (const role of value.roles) { + const field = ROLE_FIELDS.find(name => typeof role?.[name] !== "string"); + if (field) return { kind: "error", message: `surla status answered a role without ${field}.` }; + } + const status = { + projectName: value.project_name, + directory: value.directory, + stage: value.stage, + changeTitle: value.change_title, + attention: value.attention, + roles: value.roles, + }; + return { kind: "running", status }; +} + +// roleTerminal returns the address of the live terminal Herdr labels as +// handle's pane in the project at directory, or null when none is open. +export function roleTerminal(terms, directory, handle) { + if (!directory || !handle) return null; + const term = (terms ?? []).find(t => t?.state === "live" && t.labels?.["chorus.project"] === directory && t.labels?.["chorus.handle"] === handle); + return term?.address ?? null; +} + +// stageLine is the window's one-line summary of the project's stage and change. +export function stageLine(status) { + const stage = STAGES[status.stage] ?? "Unknown stage"; + return status.changeTitle ? `${stage} · ${status.changeTitle}` : stage; +} + +// roleLine says what one role is doing, including why it needs the user. +export function roleLine(role) { + const title = ROLE_TITLES[role.role] ?? role.role; + const state = ROLE_STATES[role.state] ?? "unknown"; + const why = role.state === "needs_you" && role.attention && role.attention !== "none" ? ` (${role.attention})` : ""; + return `${title}: ${state}${why}`; +} + +export default class SurlaCompanion extends View { + init(_props, cx) { + this.result = { kind: "loading" }; + this.folder = null; + this.reading = false; + this.opening = false; + this.openError = ""; + // Herdr loads the mod once for `herdr-app check`; start no commands then. + if (checking()) return; + this.refresh(cx); + cx.timer.every(POLL_MS, cx => this.refresh(cx)); + } + + // shownSpace is the space this window describes: the shown one. + shownSpace() { + return spaces().find(space => space.active) ?? null; + } + + // refresh reads the shown space's project status once; a read still in + // progress makes later ticks wait for it. + refresh(cx) { + if (this.reading) return; + const folder = projectFolder(this.shownSpace(), terminals(), panes(), focused()); + this.folder = folder; + if (!folder) { + this.result = { kind: "none" }; + cx.notify(); + return; + } + this.reading = true; + cx.spawn(async cx => { + try { + const answer = await exec("surla", ["status", "--json"], { cwd: folder, timeout: STATUS_TIMEOUT_MS }); + this.result = parseStatus(answer); + } catch (err) { + this.result = { kind: "error", message: `Could not run surla: ${err?.message ?? err}` }; + } finally { + this.reading = false; + cx.notify(); + } + }); + } + + // openPage runs `surla` in the project folder, which starts the project's + // server when needed and opens its views page in the browser. + openPage(cx) { + if (this.opening || !this.folder) return; + const folder = this.folder; + this.opening = true; + this.openError = ""; + cx.notify(); + cx.spawn(async cx => { + try { + const answer = await exec("surla", [], { cwd: folder, timeout: OPEN_TIMEOUT_MS }); + if (answer.code !== 0) this.openError = (answer.stderr || answer.stdout || "surla failed.").trim(); + } catch (err) { + this.openError = `Could not run surla: ${err?.message ?? err}`; + } finally { + this.opening = false; + cx.notify(); + this.refresh(cx); + } + }); + } + + // button is a control that stops the press from dragging the window. + button(id, label, t, onClick) { + return div() + .id(id) + .px(10) + .py(5) + .rounded(5) + .bg(t.raised) + .text_size(12) + .text_color(t.foreground) + .cursor_pointer() + .hover(s => s.bg(t.hover)) + .on_mouse_down("left", (_event, cx) => cx.stop_propagation()) + .on_click((_event, cx) => onClick(cx)) + .child(label); + } + + render(cx) { + const t = theme(); + const overlay = props()?.overlay; + const header = h_flex() + .items_center() + .gap(8) + .child(div().flex_1().font_semibold().text_size(13).text_color(t.foreground).child(this.title())) + .when(Boolean(overlay), el => el.child(this.button("surla-close", "×", t, () => closeOverlay(overlay)))); + const body = v_flex().gap(6).text_size(12).text_color(t.muted); + const r = this.result; + if (r.kind === "loading") { + body.child("Reading the project…"); + } else if (r.kind === "none") { + body.child("Show a space on this computer to see its Surla project."); + } else if (r.kind === "error") { + body.child(div().text_color(t.blocked).child(r.message)); + } else if (r.kind === "stopped") { + body.child("No Surla server is running for this folder."); + } else { + const s = r.status; + body.child(div().text_color(t.foreground).child(stageLine(s))); + if (s.attention) body.child(div().text_color(t.blocked).child(s.attention)); + const terms = terminals(); + for (const role of s.roles) { + const terminal = roleTerminal(terms, s.directory, role.handle); + body.child( + h_flex() + .items_center() + .gap(8) + .child(div().flex_1().truncate().child(roleLine(role))) + .when(Boolean(terminal), el => el.child(this.button(`surla-show-${role.role}`, "Show", t, () => run("pane.focus", { terminal })))), + ); + } + } + const canOpen = Boolean(this.folder) && r.kind !== "none"; + const footer = h_flex() + .gap(8) + .items_center() + .when(canOpen, el => el.child(this.button("surla-open", this.opening ? "Opening…" : r.kind === "running" ? "Open Page" : "Start Surla", t, cx => this.openPage(cx)))) + .when(Boolean(this.openError), el => el.child(div().flex_1().truncate().text_size(11).text_color(t.blocked).child(this.openError))); + return v_flex() + .id("surla-companion") + .size_full() + .p(14) + .gap(10) + .bg(t.popover) + .rounded(8) + .child(header) + .child(body) + .child(footer); + } + + // title names the project when its status is known. + title() { + const r = this.result; + if (r.kind === "running" && r.status.projectName) return `Surla · ${r.status.projectName}`; + return "Surla"; + } +} diff --git a/skills/herdr/surla/mod.json b/skills/herdr/surla/mod.json new file mode 100644 index 00000000..a76e0d9c --- /dev/null +++ b/skills/herdr/surla/mod.json @@ -0,0 +1,5 @@ +{ + "place": "none", + "title": "Surla", + "overlay": { "kind": "window", "width": 360 } +} diff --git a/skills/herdr/surla/test_mod.mjs b/skills/herdr/surla/test_mod.mjs new file mode 100644 index 00000000..c263fdcc --- /dev/null +++ b/skills/herdr/surla/test_mod.mjs @@ -0,0 +1,288 @@ +// Tests for the Surla companion mod. main.js runs inside Herdr, so these +// tests load it into a Node VM with recording stand-ins for the gpui-kit, +// gpui-base and herdr modules. Run with `node --test` from this folder. +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import test from 'node:test'; +import vm from 'node:vm'; + +const source = (await readFile(new URL('./main.js', import.meta.url), 'utf8')) + .replace(/^import .*;\n/gm, '') + .replace(/^export default class /m, 'class ') + .replace(/^export function /gm, 'function ') + + '\nglobalThis.mod = { projectFolder, parseStatus, roleTerminal, stageLine, roleLine, SurlaCompanion };'; + +// element records one built element: its id, text children, nested elements +// and the handlers main.js attached. +function element() { + const node = { id: null, children: [], handlers: {} }; + const proxy = new Proxy(node, { + get(target, name) { + if (name === 'node') return target; + if (name === 'child') return child => { target.children.push(child); return proxy; }; + if (name === 'id') return id => { target.id = id; return proxy; }; + if (name === 'when') return (cond, build) => (cond ? build(proxy) : proxy); + if (name === 'on_click') return handler => { target.handlers.click = handler; return proxy; }; + if (name === 'on_mouse_down') return (button, handler) => { target.handlers[`down:${button}`] = handler; return proxy; }; + return () => proxy; + }, + }); + return proxy; +} + +// walk lists every element node under root, root included. +function walk(root) { + const node = root.node; + return [node, ...node.children.filter(c => typeof c === 'object' && c?.node).flatMap(walk)]; +} + +// texts lists every string shown under root, in order. +function texts(root) { + return walk(root).flatMap(node => node.children.filter(c => typeof c === 'string')); +} + +// plain copies a value made inside the VM into this realm, so deepEqual +// compares contents rather than the VM's own prototypes. +function plain(value) { + return JSON.parse(JSON.stringify(value)); +} + +// load starts a fresh copy of main.js against a fake Herdr in state, and +// returns the module plus the calls it made. +function load(state) { + const calls = { exec: [], run: [], closed: [] }; + const herdr = { + spaces: () => state.spaces ?? [], + terminals: () => state.terminals ?? [], + panes: () => state.panes ?? [], + focused: () => state.focused ?? null, + theme: () => new Proxy({}, { get: (_t, name) => String(name) }), + props: () => state.props ?? {}, + checking: () => Boolean(state.checking), + exec: async (command, args, options) => { + calls.exec.push(plain({ command, args, options })); + const answer = state.answers?.[args.join(' ')]; + if (answer instanceof Error) throw answer; + return answer ?? { code: 0, stdout: '{"running":false}', stderr: '' }; + }, + run: (name, args) => { calls.run.push(plain({ name, args })); return null; }, + closeOverlay: id => { calls.closed.push(id); return null; }, + }; + const context = vm.createContext({ + ...herdr, + View: class {}, + div: element, + h_flex: element, + v_flex: element, + JSON, + String, + Array, + Set, + Boolean, + }); + vm.runInContext(source, context); + return { mod: context.mod, calls }; +} + +// fakeCx is a GPUI context that runs spawned tasks and records timers. +function fakeCx() { + const cx = { + tasks: [], + timers: [], + notified: 0, + stopped: 0, + notify() { cx.notified++; }, + spawn(body) { const task = Promise.resolve(body(cx)); cx.tasks.push(task); return task; }, + stop_propagation() { cx.stopped++; }, + timer: { every(ms, handler) { cx.timers.push({ ms, handler }); } }, + async settle() { while (cx.tasks.length) await cx.tasks.shift(); }, + }; + return cx; +} + +const space = { id: 'sp1', active: true, machine: null, folder: '/work/space', tabs: [{ id: 'tb1' }] }; + +const running = { + running: true, + project_name: 'homes', + directory: '/work/homes', + team: 'homes-1', + herdr_mode: 'attached', + stage: 'build', + change_id: 'add-listings', + change_title: 'Add listings', + attention: 'The builder needs you.', + roles: [ + { role: 'guide', handle: 'guide-1', state: 'working', attention: 'none', watcher: 'held', assignment: 'no_work' }, + { role: 'builder', handle: 'builder-1', state: 'needs_you', attention: 'permission', watcher: 'held', assignment: 'nothing_owed' }, + { role: 'test_writer', handle: 'tests-1', state: 'not_started', attention: 'none', watcher: 'unknown', assignment: 'unread' }, + ], +}; + +test('projectFolder follows labels, then focus, then panes, then the space folder', () => { + const { mod } = load({}); + const labeled = { state: 'live', labels: { 'herdr.space': 'sp1', 'chorus.project': '/work/homes' } }; + const other = { state: 'live', labels: { 'herdr.space': 'sp2', 'chorus.project': '/work/other' } }; + const ended = { state: 'exited', labels: { 'herdr.space': 'sp1', 'chorus.project': '/work/old' } }; + const panes = [{ tab: 'tb9', cwd: '/elsewhere' }, { tab: 'tb1', cwd: '/work/pane' }]; + const cases = [ + { name: 'no space', space: null, want: null }, + { name: 'remote space', space: { ...space, machine: 'box' }, terms: [labeled], want: null }, + { name: 'labeled terminal', space, terms: [other, ended, labeled], panes, want: '/work/homes' }, + { name: 'focused pane', space, terms: [other], panes, focus: { space: 'sp1', cwd: '/work/focus' }, want: '/work/focus' }, + { name: 'focus in another space', space, panes, focus: { space: 'sp2', cwd: '/work/focus' }, want: '/work/pane' }, + { name: 'first pane of the space', space, panes, want: '/work/pane' }, + { name: 'space folder', space, panes: [{ tab: 'tb9', cwd: '/elsewhere' }], want: '/work/space' }, + { name: 'home space', space: { ...space, folder: '' }, want: null }, + ]; + for (const c of cases) { + assert.equal(mod.projectFolder(c.space, c.terms, c.panes, c.focus), c.want, c.name); + } +}); + +test('parseStatus reads running, stopped and failed answers', () => { + const { mod } = load({}); + const cases = [ + { name: 'stopped', result: { code: 0, stdout: '{"running":false}', stderr: '' }, kind: 'stopped' }, + { name: 'running', result: { code: 0, stdout: JSON.stringify(running), stderr: '' }, kind: 'running' }, + { name: 'failed', result: { code: 1, stdout: '', stderr: 'surla: boom\n' }, kind: 'error', message: 'surla: boom' }, + { name: 'failed silently', result: { code: 2, stdout: '', stderr: '' }, kind: 'error', message: 'surla status failed.' }, + { name: 'not JSON', result: { code: 0, stdout: 'hello', stderr: '' }, kind: 'error' }, + { name: 'no running field', result: { code: 0, stdout: '{}', stderr: '' }, kind: 'error' }, + { name: 'null', result: { code: 0, stdout: 'null', stderr: '' }, kind: 'error' }, + { name: 'missing field', result: { code: 0, stdout: JSON.stringify({ ...running, stage: undefined }), stderr: '' }, kind: 'error', message: 'surla status answered without stage.' }, + { name: 'wrong type', result: { code: 0, stdout: JSON.stringify({ ...running, change_id: null }), stderr: '' }, kind: 'error', message: 'surla status answered without change_id.' }, + { name: 'no roles', result: { code: 0, stdout: JSON.stringify({ ...running, roles: {} }), stderr: '' }, kind: 'error', message: 'surla status answered without roles.' }, + { name: 'incomplete role', result: { code: 0, stdout: JSON.stringify({ ...running, roles: [{ role: 'guide' }] }), stderr: '' }, kind: 'error', message: 'surla status answered a role without handle.' }, + ]; + for (const c of cases) { + const got = mod.parseStatus(c.result); + assert.equal(got.kind, c.kind, c.name); + if (c.message) assert.equal(got.message, c.message, c.name); + } + const got = mod.parseStatus({ code: 0, stdout: JSON.stringify(running), stderr: '' }); + assert.equal(got.status.projectName, 'homes'); + assert.equal(got.status.directory, '/work/homes'); + assert.equal(got.status.roles.length, 3); +}); + +test('roleTerminal finds the live terminal labeled with the project and handle', () => { + const { mod } = load({}); + const terms = [ + { address: 't1', state: 'exited', labels: { 'chorus.project': '/work/homes', 'chorus.handle': 'builder-1' } }, + { address: 't2', state: 'live', labels: { 'chorus.project': '/work/other', 'chorus.handle': 'builder-1' } }, + { address: 't3', state: 'live', labels: { 'chorus.project': '/work/homes', 'chorus.handle': 'builder-1' } }, + ]; + assert.equal(mod.roleTerminal(terms, '/work/homes', 'builder-1'), 't3'); + assert.equal(mod.roleTerminal(terms, '/work/homes', 'tests-1'), null); + assert.equal(mod.roleTerminal(terms, '', 'builder-1'), null); +}); + +test('stageLine and roleLine describe the project for people', () => { + const { mod } = load({}); + assert.equal(mod.stageLine({ stage: 'build', changeTitle: 'Add listings' }), 'Build · Add listings'); + assert.equal(mod.stageLine({ stage: 'describe', changeTitle: '' }), 'Describe'); + assert.equal(mod.stageLine({ stage: 'later', changeTitle: '' }), 'Unknown stage'); + assert.equal(mod.roleLine(running.roles[1]), 'Builder: needs you (permission)'); + assert.equal(mod.roleLine(running.roles[2]), 'Test writer: not started'); +}); + +test('init starts no command while Herdr checks the mod', () => { + const { mod, calls } = load({ checking: true, spaces: [space] }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + assert.equal(calls.exec.length, 0); + assert.equal(cx.timers.length, 0); + assert.deepEqual(texts(view.render(cx)), ['Surla', 'Reading the project…']); +}); + +test('init reads the status in the project folder and polls every four seconds', async () => { + const { mod, calls } = load({ spaces: [space] }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + await cx.settle(); + assert.deepEqual(calls.exec, [{ command: 'surla', args: ['status', '--json'], options: { cwd: '/work/space', timeout: 10000 } }]); + assert.deepEqual(cx.timers.map(t => t.ms), [4000]); + cx.timers[0].handler(cx); + await cx.settle(); + assert.equal(calls.exec.length, 2); + assert.ok(texts(view.render(cx)).includes('No Surla server is running for this folder.')); +}); + +test('a remote space reads nothing and offers nothing', async () => { + const { mod, calls } = load({ spaces: [{ ...space, machine: 'box' }] }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + await cx.settle(); + assert.equal(calls.exec.length, 0); + const root = view.render(cx); + assert.ok(texts(root).includes('Show a space on this computer to see its Surla project.')); + assert.ok(!walk(root).some(node => node.id === 'surla-open')); +}); + +test('a running project shows its stage, roles and pane shortcuts', async () => { + const terminals = [{ address: 't7', state: 'live', labels: { 'herdr.space': 'sp1', 'chorus.project': '/work/homes', 'chorus.handle': 'builder-1' } }]; + const { mod, calls } = load({ + spaces: [space], + terminals, + props: { overlay: 'ov1' }, + answers: { 'status --json': { code: 0, stdout: JSON.stringify(running), stderr: '' } }, + }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + await cx.settle(); + assert.equal(calls.exec[0].options.cwd, '/work/homes'); + const root = view.render(cx); + const shown = texts(root); + for (const text of ['Surla · homes', 'Build · Add listings', 'The builder needs you.', 'Guide: working', 'Builder: needs you (permission)', 'Test writer: not started', 'Open Page']) { + assert.ok(shown.includes(text), text); + } + const ids = walk(root).map(node => node.id).filter(Boolean); + assert.deepEqual(ids.filter(id => id.startsWith('surla-show-')), ['surla-show-builder']); + + // Every button stops the press so it does not drag the window. + const buttons = walk(root).filter(node => node.handlers.click); + assert.deepEqual(buttons.map(node => node.id), ['surla-close', 'surla-show-builder', 'surla-open']); + for (const button of buttons) { + const before = cx.stopped; + button.handlers['down:left']({}, cx); + assert.equal(cx.stopped, before + 1, button.id); + } + + buttons[1].handlers.click({}, cx); + assert.deepEqual(calls.run, [{ name: 'pane.focus', args: { terminal: 't7' } }]); + buttons[0].handlers.click({}, cx); + assert.deepEqual(calls.closed, ['ov1']); +}); + +test('Open Page runs surla in the project folder and reports a failure', async () => { + const { mod, calls } = load({ + spaces: [space], + answers: { '': { code: 1, stdout: '', stderr: 'surla: no project here\n' } }, + }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + await cx.settle(); + let open = walk(view.render(cx)).find(node => node.id === 'surla-open'); + assert.ok(texts({ node: open }).includes('Start Surla')); + open.handlers.click({}, cx); + open.handlers.click({}, cx); + await cx.settle(); + const opens = calls.exec.filter(call => call.args.length === 0); + assert.deepEqual(opens, [{ command: 'surla', args: [], options: { cwd: '/work/space', timeout: 60000 } }]); + assert.ok(texts(view.render(cx)).includes('surla: no project here')); +}); + +test('a command that cannot start is shown, not thrown', async () => { + const { mod } = load({ spaces: [space], answers: { 'status --json': new Error('not installed') } }); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + await cx.settle(); + assert.ok(texts(view.render(cx)).includes('Could not run surla: not installed')); +}); diff --git a/skills/surla/SKILL.md b/skills/surla/SKILL.md new file mode 100644 index 00000000..7c5196db --- /dev/null +++ b/skills/surla/SKILL.md @@ -0,0 +1,58 @@ +--- +name: surla +description: Build or change a Goa or Goa-AI service with Surla from this coding session. Use when the user types /surla or $surla, asks to build a service with Surla, or wants to start, refine, build, verify or approve a Surla change in the current folder. +--- + +# Surla + +Surla turns a feature request into an agreed Change Card, a reviewed +architecture, a build by separate builder and test-writer agents, a +verification run, and an approval that only the user gives. In this session +you are the **guide**: you shape the Story and the Change Card with the user. +Your tools come from the `surla` MCP server that `surla setup -global` +registered. + +## Start + +1. Call a Surla tool from the folder the user is working in. Your first Surla + tool call attaches this session to that folder's project as its guide and + starts the project's server if it is not running. You run no `surla` + command yourself. +2. If the folder holds no project yet and is empty (agent settings folders + such as `.claude` or `.agents` are fine), call `init_project` with + `dir: "."` and the user's module path to create the project in place. If + the folder already holds other files, ask the user where the project + should go instead. +3. Read the `surla://golden-path` resource, then `list_changes` and + `get_change` to see where the project stands. + +## Work on a change with the user + +- Call `update_draft` before each new change and whenever you are told a + design file changed. Work only in the draft folder it returns; never edit + the project folder or copy design files between it and the draft. +- When `update_draft` reports files needing correction, correct them in the + draft (or, when one is in the project folder, tell the user what to fix + there and wait), and call it again until the list is empty. +- Call `refresh_story` and poll `get_story_refresh` until it succeeds or + fails. Use the succeeded refresh in `propose_change` or `revise_change`. +- A revision's `prompt` is the change's complete request as it now stands; + put what changed and why in `revision_note`. +- When the design needs a module, run `GOWORK=off go get` and + `GOWORK=off go mod tidy` in the draft. + +## Show the user the page + +Call `open_views` to open the project's views page in the user's browser. +It returns only whether the page opened. Never ask for, print or pass on a +page link or session token. + +Only the user confirms the Change Card, starts a build, approves a result +and merges it, on the views page. Do not do those steps for them, and do not +run `git merge` on their behalf unless they ask you to after approving. + +## Team + +Building adds a builder and a test writer, which Surla starts in their own +working copies. If the user also uses Chorus, keep its watcher running as the +Chorus skill describes, so Surla and the other roles can reach you. From e2a6c73c914a33548e5a4e01455f8dbb2658413e Mon Sep 17 00:00:00 2001 From: Raphael Simon Date: Thu, 19 Nov 2026 12:42:56 -0800 Subject: [PATCH 2/4] Follow space switches in the companion and tell the guide its Chorus team MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The companion window now shows only the result read for the folder of the space Herdr shows: switching spaces shows "Reading the project…" at once, reads the new folder within half a second, and drops an answer that arrives for a folder no longer shown. An Open Page failure stays with its folder. The /surla skill tells the guide to read its team and handle from `surla status --json` and join `#` on Chorus when available, and names story_refresh_op_id, get_build, list_verifications and get_verification. Setup refuses a config.toml whose mcp_servers is not a table, resolves symlinks when refusing a temporary surla executable (including GOTMPDIR), and writes skill and mod files atomically. --- cmd/surla/setup.go | 55 +++++++++++--- cmd/surla/setup_test.go | 29 +++++++- skills/herdr/surla/main.js | 127 +++++++++++++++++++------------- skills/herdr/surla/test_mod.mjs | 69 ++++++++++++++++- skills/surla/SKILL.md | 30 ++++++-- 5 files changed, 242 insertions(+), 68 deletions(-) diff --git a/cmd/surla/setup.go b/cmd/surla/setup.go index ea3e8fec..2a458d3d 100644 --- a/cmd/surla/setup.go +++ b/cmd/surla/setup.go @@ -182,7 +182,7 @@ func processSetupEnvironment() (setupEnvironment, error) { if err != nil { return setupEnvironment{}, fmt.Errorf("resolve the surla executable: %w", err) } - if rel, err := filepath.Rel(os.TempDir(), executable); err == nil && filepath.IsLocal(rel) { + if temporaryExecutable(executable, os.TempDir(), os.Getenv("GOTMPDIR")) { return setupEnvironment{}, fmt.Errorf("surla is running from the temporary file %s; install it (go install github.com/goadesign/surla/cmd/surla@latest) and run that surla setup -global", executable) } return setupEnvironment{ @@ -197,6 +197,37 @@ func processSetupEnvironment() (setupEnvironment, error) { }, nil } +// temporaryExecutable reports whether executable lies under one of the +// temporary folders, where `go run` builds. Symlinks are resolved on both +// sides, since macOS reaches /var and /tmp through /private. An empty folder +// name is skipped. +func temporaryExecutable(executable string, tempDirs ...string) bool { + exe := resolveExistingPrefix(executable) + for _, dir := range tempDirs { + if dir == "" { + continue + } + if rel, err := filepath.Rel(resolveExistingPrefix(dir), exe); err == nil && filepath.IsLocal(rel) { + return true + } + } + return false +} + +// resolveExistingPrefix resolves symlinks in the longest existing leading +// part of path and appends the rest unchanged. +func resolveExistingPrefix(path string) string { + path = filepath.Clean(path) + if resolved, err := filepath.EvalSymlinks(path); err == nil { + return resolved + } + parent := filepath.Dir(path) + if parent == path { + return path + } + return filepath.Join(resolveExistingPrefix(parent), filepath.Base(path)) +} + // setupTargets lists the configuration and skill files of the coding agents // installed under env.home: Claude Code, OpenAI Codex, Cursor, Antigravity, // Gemini CLI, Windsurf, GitHub Copilot CLI and VS Code. The universal @@ -400,7 +431,13 @@ func mergeCodexConfig(path, executable string) (bool, error) { if err := toml.Unmarshal(content, &decoded); err != nil { return false, fmt.Errorf("%s is not valid TOML: %w; %s", path, err, byHand) } - servers, _ := decoded["mcp_servers"].(map[string]any) + servers := map[string]any{} + if existing, present := decoded["mcp_servers"]; present { + var ok bool + if servers, ok = existing.(map[string]any); !ok { + return false, fmt.Errorf("%s: mcp_servers is not a table; %s", path, byHand) + } + } if entry, ok := servers[surlaServerName].(map[string]any); ok { if _, ok := entry["url"]; ok { return false, fmt.Errorf("%s: mcp_servers.surla has a url; remove it and %s", path, byHand) @@ -525,7 +562,7 @@ func locateCodexSurlaEntry(doc []byte) (codexEntryEdit, error) { // the first non-blank byte after the '=' that follows the key's last segment // to the end of the expression. The parser records no range for arrays, and // the expression's own range ends where its value ends, before any comment. -func tomlValueRange(doc []byte, expr *unstable.Node, lastKey *unstable.Node) unstable.Range { +func tomlValueRange(doc []byte, expr, lastKey *unstable.Node) unstable.Range { start := int(lastKey.Raw.Offset + lastKey.Raw.Length) start += bytes.IndexByte(doc[start:], '=') + 1 for start < len(doc) && (doc[start] == ' ' || doc[start] == '\t') { @@ -835,8 +872,9 @@ func replaceConfigFile(path string, content []byte, perm os.FileMode) (err error } // writeIntegrationFile installs bundled skill or mod content at path, -// creating folders as needed, and reports whether it wrote. Identical files -// are left untouched: Herdr reloads a mod whenever its files are written. +// creating folders as needed, and reports whether it wrote. The file is +// replaced atomically so Herdr, which reloads a mod whenever its files are +// written, never reads a partly written one; identical files are left alone. func writeIntegrationFile(path string, content []byte) (bool, error) { installed, err := os.ReadFile(path) if err != nil && !errors.Is(err, os.ErrNotExist) { @@ -845,11 +883,8 @@ func writeIntegrationFile(path string, content []byte) (bool, error) { if err == nil && bytes.Equal(installed, content) { return false, nil } - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - return false, fmt.Errorf("create folder for %s: %w", path, err) - } - if err := os.WriteFile(path, content, 0o644); err != nil { - return false, fmt.Errorf("write %s: %w", path, err) + if err := replaceConfigFile(path, content, 0o644); err != nil { + return false, err } return true, nil } diff --git a/cmd/surla/setup_test.go b/cmd/surla/setup_test.go index 711e6b4b..08d6e50d 100644 --- a/cmd/surla/setup_test.go +++ b/cmd/surla/setup_test.go @@ -307,6 +307,8 @@ func TestSetupCodexConfigMerge(t *testing.T) { {name: "dotted keys missing args", content: "[mcp_servers]\nsurla.command = \"old\"\n", wantErr: "dotted keys missing command or args"}, {name: "inline table", content: "[mcp_servers]\nsurla = { command = \"old\" }\n", wantErr: "inline table"}, {name: "array of tables", content: "[[mcp_servers.surla]]\ncommand = \"old\"\n", wantErr: "array of tables"}, + {name: "servers as an array of tables", content: "[[mcp_servers]]\nname = \"x\"\n", wantErr: "mcp_servers is not a table"}, + {name: "servers as a string", content: "mcp_servers = \"x\"\n", wantErr: "mcp_servers is not a table"}, {name: "url transport", content: "[mcp_servers.surla]\nurl = \"http://old\"\n", wantErr: "has a url"}, {name: "command not a string", content: "[mcp_servers.surla]\ncommand = 3\n", wantErr: "command is not a string"}, {name: "invalid TOML", content: "[mcp_servers.surla\n", wantErr: "is not valid TOML"}, @@ -319,7 +321,10 @@ func TestSetupCodexConfigMerge(t *testing.T) { writeTestFile(t, path, c.content) } changed, err := mergeCodexConfig(path, testExecutable) - raw, _ := os.ReadFile(path) + raw, readErr := os.ReadFile(path) + if c.content != "" || c.wantErr == "" { + require.NoError(t, readErr) + } if c.wantErr != "" { assert.ErrorContains(t, err, c.wantErr) assert.ErrorContains(t, err, `set [mcp_servers.surla] command = "/opt/surla/bin/surla" and args = ["stdio"] by hand`) @@ -426,3 +431,25 @@ func TestSetupHerdrModReportsMissingKeyboardFile(t *testing.T) { _, err = os.Stat(filepath.Join(home, ".config", "herdr-app", "keys.json")) assert.ErrorIs(t, err, os.ErrNotExist) } + +func TestSetupRefusesTemporaryExecutable(t *testing.T) { + temp := t.TempDir() + link := filepath.Join(t.TempDir(), "tmp-link") + require.NoError(t, os.Symlink(temp, link)) + goTemp := t.TempDir() + installed := t.TempDir() + cases := []struct { + name, executable string + tempDirs []string + want bool + }{ + {name: "under the temporary folder", executable: filepath.Join(temp, "go-build1", "exe", "surla"), tempDirs: []string{temp}, want: true}, + {name: "reached through a symlinked temporary folder", executable: filepath.Join(temp, "exe", "surla"), tempDirs: []string{link}, want: true}, + {name: "under GOTMPDIR", executable: filepath.Join(goTemp, "exe", "surla"), tempDirs: []string{temp, goTemp}, want: true}, + {name: "installed binary", executable: filepath.Join(installed, "bin", "surla"), tempDirs: []string{temp, ""}, want: false}, + {name: "the temporary folder's sibling", executable: temp + "-other/surla", tempDirs: []string{temp}, want: false}, + } + for _, c := range cases { + assert.Equal(t, c.want, temporaryExecutable(c.executable, c.tempDirs...), c.name) + } +} diff --git a/skills/herdr/surla/main.js b/skills/herdr/surla/main.js index 0f27a26e..a106965d 100644 --- a/skills/herdr/surla/main.js +++ b/skills/herdr/surla/main.js @@ -14,6 +14,9 @@ const POLL_MS = 4000; const STATUS_TIMEOUT_MS = 10000; // OPEN_TIMEOUT_MS bounds `surla`, which may start the project's server first. const OPEN_TIMEOUT_MS = 60000; +// FOLLOW_MS is how often the window checks, without running anything, +// whether the shown space now points at another folder. +const FOLLOW_MS = 500; // STAGES names each stage of ProjectStatus.stage for people. const STAGES = { @@ -43,9 +46,10 @@ const ROLE_STATES = { // projectFolder returns the folder whose Surla project the window shows for // space, or null when there is none to ask about. A space on another machine // has none: `surla` runs on this computer. The first live terminal in the -// space labeled with a Surla project names it; otherwise the focused pane's -// folder when it is in this space, then the first pane's folder, then the -// space's own folder. +// space labeled with a Surla project names it; otherwise the focused +// terminal's folder when it is in this space, then the folder of the active +// tab's focused pane, of the active tab's first pane, of the space's first +// pane, and finally the space's own folder. export function projectFolder(space, terms, paneList, focus) { if (!space || space.machine) return null; for (const term of terms ?? []) { @@ -55,8 +59,11 @@ export function projectFolder(space, terms, paneList, focus) { } } if (focus?.space === space.id && focus.cwd) return focus.cwd; - const tabs = new Set((space.tabs ?? []).map(tab => tab.id)); - const pane = (paneList ?? []).find(p => tabs.has(p.tab) && p.cwd); + const tabs = space.tabs ?? []; + const activeTab = tabs.find(tab => tab.active)?.id; + const inSpace = (paneList ?? []).filter(p => p.cwd && tabs.some(tab => tab.id === p.tab)); + const inActiveTab = inSpace.filter(p => p.tab === activeTab); + const pane = inActiveTab.find(p => p.focused) ?? inActiveTab[0] ?? inSpace[0]; if (pane) return pane.cwd; return space.folder || null; } @@ -128,66 +135,80 @@ export function roleLine(role) { export default class SurlaCompanion extends View { init(_props, cx) { - this.result = { kind: "loading" }; - this.folder = null; + // result is the last status read and resultFolder the folder it is for; + // render shows it only while that folder is still the shown one. + this.result = null; + this.resultFolder = null; + // trackedFolder is the shown folder the last read was started for. + this.trackedFolder = null; this.reading = false; - this.opening = false; - this.openError = ""; + // opening and openError belong to the folder named in them. + this.opening = null; + this.openError = null; // Herdr loads the mod once for `herdr-app check`; start no commands then. if (checking()) return; this.refresh(cx); cx.timer.every(POLL_MS, cx => this.refresh(cx)); + // A space switch reads the new folder at once rather than at the next poll. + cx.timer.every(FOLLOW_MS, cx => { + if (this.shownFolder() !== this.trackedFolder) this.refresh(cx); + }); } - // shownSpace is the space this window describes: the shown one. - shownSpace() { - return spaces().find(space => space.active) ?? null; + // shownFolder is the project folder of the space Herdr shows now, or null. + shownFolder() { + const space = spaces().find(space => space.active) ?? null; + return projectFolder(space, terminals(), panes(), focused()); } - // refresh reads the shown space's project status once; a read still in - // progress makes later ticks wait for it. + // refresh reads the shown folder's status once. A read still in progress + // makes this call wait for it; when that read ends, a read starts for the + // folder shown then. An answer for a folder no longer shown is dropped. refresh(cx) { - if (this.reading) return; - const folder = projectFolder(this.shownSpace(), terminals(), panes(), focused()); - this.folder = folder; - if (!folder) { - this.result = { kind: "none" }; + const folder = this.shownFolder(); + this.trackedFolder = folder; + if (!folder || this.reading) { cx.notify(); return; } this.reading = true; cx.spawn(async cx => { + let result; try { - const answer = await exec("surla", ["status", "--json"], { cwd: folder, timeout: STATUS_TIMEOUT_MS }); - this.result = parseStatus(answer); + result = parseStatus(await exec("surla", ["status", "--json"], { cwd: folder, timeout: STATUS_TIMEOUT_MS })); } catch (err) { - this.result = { kind: "error", message: `Could not run surla: ${err?.message ?? err}` }; - } finally { - this.reading = false; + result = { kind: "error", message: `Could not run surla: ${err?.message ?? err}` }; + } + this.reading = false; + if (this.shownFolder() === folder) { + this.result = result; + this.resultFolder = folder; cx.notify(); + } else { + this.refresh(cx); } }); } - // openPage runs `surla` in the project folder, which starts the project's - // server when needed and opens its views page in the browser. - openPage(cx) { - if (this.opening || !this.folder) return; - const folder = this.folder; - this.opening = true; - this.openError = ""; + // openPage runs `surla` in folder, which starts the project's server when + // needed and opens its views page in the browser. + openPage(cx, folder) { + if (this.opening === folder) return; + this.opening = folder; + this.openError = null; cx.notify(); cx.spawn(async cx => { + let message = ""; try { const answer = await exec("surla", [], { cwd: folder, timeout: OPEN_TIMEOUT_MS }); - if (answer.code !== 0) this.openError = (answer.stderr || answer.stdout || "surla failed.").trim(); + if (answer.code !== 0) message = (answer.stderr || answer.stdout || "surla failed.").trim(); } catch (err) { - this.openError = `Could not run surla: ${err?.message ?? err}`; - } finally { - this.opening = false; - cx.notify(); - this.refresh(cx); + message = `Could not run surla: ${err?.message ?? err}`; } + if (this.opening === folder) this.opening = null; + if (message) this.openError = { folder, message }; + cx.notify(); + this.refresh(cx); }); } @@ -195,6 +216,7 @@ export default class SurlaCompanion extends View { button(id, label, t, onClick) { return div() .id(id) + .flex_none() .px(10) .py(5) .rounded(5) @@ -211,13 +233,19 @@ export default class SurlaCompanion extends View { render(cx) { const t = theme(); const overlay = props()?.overlay; + const folder = checking() ? null : this.shownFolder(); + let r; + if (checking()) r = { kind: "loading" }; + else if (!folder) r = { kind: "none" }; + else if (this.resultFolder === folder) r = this.result; + else r = { kind: "loading" }; + const title = r.kind === "running" && r.status.projectName ? `Surla · ${r.status.projectName}` : "Surla"; const header = h_flex() .items_center() .gap(8) - .child(div().flex_1().font_semibold().text_size(13).text_color(t.foreground).child(this.title())) + .child(div().flex_1().min_w(0).truncate().font_semibold().text_size(13).text_color(t.foreground).child(title)) .when(Boolean(overlay), el => el.child(this.button("surla-close", "×", t, () => closeOverlay(overlay)))); const body = v_flex().gap(6).text_size(12).text_color(t.muted); - const r = this.result; if (r.kind === "loading") { body.child("Reading the project…"); } else if (r.kind === "none") { @@ -237,20 +265,24 @@ export default class SurlaCompanion extends View { h_flex() .items_center() .gap(8) - .child(div().flex_1().truncate().child(roleLine(role))) + .child(div().flex_1().min_w(0).truncate().child(roleLine(role))) .when(Boolean(terminal), el => el.child(this.button(`surla-show-${role.role}`, "Show", t, () => run("pane.focus", { terminal })))), ); } } - const canOpen = Boolean(this.folder) && r.kind !== "none"; + // A running project opens from its own folder; otherwise from the shown one. + const target = r.kind === "running" ? r.status.directory : folder; + const canOpen = Boolean(target) && r.kind !== "loading"; + const openError = this.openError?.folder === target ? this.openError.message : ""; + const label = this.opening === target ? "Opening…" : r.kind === "running" ? "Open Page" : "Start Surla"; const footer = h_flex() .gap(8) .items_center() - .when(canOpen, el => el.child(this.button("surla-open", this.opening ? "Opening…" : r.kind === "running" ? "Open Page" : "Start Surla", t, cx => this.openPage(cx)))) - .when(Boolean(this.openError), el => el.child(div().flex_1().truncate().text_size(11).text_color(t.blocked).child(this.openError))); + .when(canOpen, el => el.child(this.button("surla-open", label, t, cx => this.openPage(cx, target)))) + .when(Boolean(openError), el => el.child(div().flex_1().min_w(0).truncate().text_size(11).text_color(t.blocked).child(openError))); return v_flex() .id("surla-companion") - .size_full() + .w_full() .p(14) .gap(10) .bg(t.popover) @@ -259,11 +291,4 @@ export default class SurlaCompanion extends View { .child(body) .child(footer); } - - // title names the project when its status is known. - title() { - const r = this.result; - if (r.kind === "running" && r.status.projectName) return `Surla · ${r.status.projectName}`; - return "Surla"; - } } diff --git a/skills/herdr/surla/test_mod.mjs b/skills/herdr/surla/test_mod.mjs index c263fdcc..1f6d3532 100644 --- a/skills/herdr/surla/test_mod.mjs +++ b/skills/herdr/surla/test_mod.mjs @@ -61,6 +61,7 @@ function load(state) { checking: () => Boolean(state.checking), exec: async (command, args, options) => { calls.exec.push(plain({ command, args, options })); + if (state.deferred) return new Promise((resolve, reject) => state.deferred.push({ resolve, reject })); const answer = state.answers?.[args.join(' ')]; if (answer instanceof Error) throw answer; return answer ?? { code: 0, stdout: '{"running":false}', stderr: '' }; @@ -132,6 +133,12 @@ test('projectFolder follows labels, then focus, then panes, then the space folde { name: 'focused pane', space, terms: [other], panes, focus: { space: 'sp1', cwd: '/work/focus' }, want: '/work/focus' }, { name: 'focus in another space', space, panes, focus: { space: 'sp2', cwd: '/work/focus' }, want: '/work/pane' }, { name: 'first pane of the space', space, panes, want: '/work/pane' }, + { + name: 'focused pane of the active tab', + space: { ...space, tabs: [{ id: 'tb1' }, { id: 'tb2', active: true }] }, + panes: [...panes, { tab: 'tb2', cwd: '/work/second' }, { tab: 'tb2', cwd: '/work/focused', focused: true }], + want: '/work/focused', + }, { name: 'space folder', space, panes: [{ tab: 'tb9', cwd: '/elsewhere' }], want: '/work/space' }, { name: 'home space', space: { ...space, folder: '' }, want: null }, ]; @@ -204,7 +211,7 @@ test('init reads the status in the project folder and polls every four seconds', view.init(undefined, cx); await cx.settle(); assert.deepEqual(calls.exec, [{ command: 'surla', args: ['status', '--json'], options: { cwd: '/work/space', timeout: 10000 } }]); - assert.deepEqual(cx.timers.map(t => t.ms), [4000]); + assert.deepEqual(cx.timers.map(t => t.ms), [4000, 500]); cx.timers[0].handler(cx); await cx.settle(); assert.equal(calls.exec.length, 2); @@ -286,3 +293,63 @@ test('a command that cannot start is shown, not thrown', async () => { await cx.settle(); assert.ok(texts(view.render(cx)).includes('Could not run surla: not installed')); }); + +// tick lets every promise that can settle now do so. +async function tick() { + for (let i = 0; i < 5; i++) await new Promise(resolve => setImmediate(resolve)); +} + +test('a space switch during a status read reads the new folder and drops the old answer', async () => { + const payments = { id: 'sp2', active: false, machine: null, folder: '/work/payments', tabs: [{ id: 'tb2' }] }; + const state = { spaces: [space, payments], deferred: [] }; + const { mod, calls } = load(state); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + assert.deepEqual(calls.exec.map(call => call.options.cwd), ['/work/space']); + + state.spaces = [{ ...space, active: false }, { ...payments, active: true }]; + assert.ok(texts(view.render(cx)).includes('Reading the project…'), 'the old space is not shown'); + assert.ok(!walk(view.render(cx)).some(node => node.id === 'surla-open')); + cx.timers[1].handler(cx); + assert.equal(calls.exec.length, 1, 'one read at a time'); + + state.deferred.shift().resolve({ code: 0, stdout: JSON.stringify(running), stderr: '' }); + await tick(); + assert.deepEqual(calls.exec.map(call => call.options.cwd), ['/work/space', '/work/payments']); + assert.ok(!texts(view.render(cx)).includes('Surla · homes'), 'the old answer is dropped'); + + state.deferred.shift().resolve({ code: 0, stdout: '{"running":false}', stderr: '' }); + await tick(); + assert.ok(texts(view.render(cx)).includes('No Surla server is running for this folder.')); + + state.spaces = [{ ...space, active: false }, { ...payments, active: true, machine: 'box' }]; + const remote = view.render(cx); + assert.ok(texts(remote).includes('Show a space on this computer to see its Surla project.')); + assert.ok(!walk(remote).some(node => node.id === 'surla-open')); + cx.timers[1].handler(cx); + assert.equal(calls.exec.length, 2, 'a remote space runs nothing'); +}); + +test('an Open Page failure stays with the folder it was for', async () => { + const payments = { id: 'sp2', active: false, machine: null, folder: '/work/payments', tabs: [{ id: 'tb2' }] }; + const state = { spaces: [space, payments], deferred: [] }; + const { mod, calls } = load(state); + const view = new mod.SurlaCompanion(); + const cx = fakeCx(); + view.init(undefined, cx); + state.deferred.shift().resolve({ code: 0, stdout: '{"running":false}', stderr: '' }); + await tick(); + + walk(view.render(cx)).find(node => node.id === 'surla-open').handlers.click({}, cx); + assert.deepEqual(calls.exec.at(-1), { command: 'surla', args: [], options: { cwd: '/work/space', timeout: 60000 } }); + state.spaces = [{ ...space, active: false }, { ...payments, active: true }]; + state.deferred.shift().reject(new Error('not installed')); + await tick(); + assert.ok(!texts(view.render(cx)).includes('Could not run surla: not installed')); + + state.spaces = [space, payments]; + while (state.deferred.length) state.deferred.shift().resolve({ code: 0, stdout: '{"running":false}', stderr: '' }); + await tick(); + assert.ok(texts(view.render(cx)).includes('Could not run surla: not installed')); +}); diff --git a/skills/surla/SKILL.md b/skills/surla/SKILL.md index 7c5196db..7457978a 100644 --- a/skills/surla/SKILL.md +++ b/skills/surla/SKILL.md @@ -16,8 +16,10 @@ registered. 1. Call a Surla tool from the folder the user is working in. Your first Surla tool call attaches this session to that folder's project as its guide and - starts the project's server if it is not running. You run no `surla` - command yourself. + starts the project's server if it is not running. You never start, stop, + initialize, verify or approve with the `surla` command, and never ask it + for a page link; the one command you may run is the read-only + `surla status --json` described under Team. 2. If the folder holds no project yet and is empty (agent settings folders such as `.claude` or `.agents` are fine), call `init_project` with `dir: "."` and the user's module path to create the project in place. If @@ -35,12 +37,22 @@ registered. draft (or, when one is in the project folder, tell the user what to fix there and wait), and call it again until the list is empty. - Call `refresh_story` and poll `get_story_refresh` until it succeeds or - fails. Use the succeeded refresh in `propose_change` or `revise_change`. + fails. Pass the succeeded refresh's `op_id` as `story_refresh_op_id` to + `propose_change` or `revise_change`. - A revision's `prompt` is the change's complete request as it now stands; put what changed and why in `revision_note`. - When the design needs a module, run `GOWORK=off go get` and `GOWORK=off go mod tidy` in the draft. +## Follow the build + +- `get_build` reads a change's build: the revision built, whether each role + read its assignment and the test writer's state. When it reports + `drafted_before_drop` after the user dropped a build, call `refresh_story` + and `revise_change` before the next build. +- `list_verifications` and `get_verification` read the verification runs + started for a change and their results. + ## Show the user the page Call `open_views` to open the project's views page in the user's browser. @@ -54,5 +66,13 @@ run `git merge` on their behalf unless they ask you to after approving. ## Team Building adds a builder and a test writer, which Surla starts in their own -working copies. If the user also uses Chorus, keep its watcher running as the -Chorus skill describes, so Surla and the other roles can reach you. +working copies and connects through Chorus. After your first Surla tool call, +run `surla status --json` in the project folder: `team` names the project's +Chorus swarm and channel, and the `roles` entry whose `role` is `guide` +gives your `handle`. + +When Chorus tools are available, join swarm `` on channel `#` as +agent ``, then keep `chorus watch -wait 24h` running in the +background as the Chorus skill describes, restarting it each time it ends. +Surla and the other roles reach you there. When Chorus is not available, +skip this and keep working through the Surla tools. From be1d334a0352fdecfa9426d763efc77a437614d9 Mon Sep 17 00:00:00 2001 From: Raphael Simon Date: Thu, 19 Nov 2026 13:11:31 -0800 Subject: [PATCH 3/4] Add surla stdio and surla up surla stdio is the MCP server every coding agent starts once setup has registered it. The folder decides the role: inside a project's .surla-build it is the builder, inside .surla-tests the test writer, and anywhere else a guide. Until the first tool call or resource read it answers initialize, ping and the tool and resource lists from the generated catalog for that role, creating nothing. The first call binds: a guide starts or attaches to the folder's project server, hands over the shell's model settings and attaches as the project's guide, adopting its Herdr terminal; a worker only reads the credential the running server registered for it and never starts a server or attaches a guide. Later requests are relayed to /mcp with that credential, binding again once if the server refuses it. notifications/cancelled stops a request in flight. surla up runs setup -global unless SURLA_NO_SETUP=1, then chorus up when Chorus is installed, and the CLI now dispatches up, setup and stdio. --- cmd/surla/main.go | 11 + cmd/surla/stdio.go | 794 ++++++++++++++++++++++++++++++++++++++++ cmd/surla/stdio_test.go | 361 ++++++++++++++++++ cmd/surla/up.go | 83 +++++ cmd/surla/up_test.go | 98 +++++ 5 files changed, 1347 insertions(+) create mode 100644 cmd/surla/stdio.go create mode 100644 cmd/surla/stdio_test.go create mode 100644 cmd/surla/up.go create mode 100644 cmd/surla/up_test.go diff --git a/cmd/surla/main.go b/cmd/surla/main.go index b7fff3ce..1090d625 100644 --- a/cmd/surla/main.go +++ b/cmd/surla/main.go @@ -70,6 +70,10 @@ Usage: Commands: + up register Surla with this computer's coding agents (setup -global), + then start Chorus when it is installed + setup -global register surla stdio and the /surla skill with every coding agent + found here, and install the companion window when Herdr is present init create a starter service with an agent and an evaluator suite status read this project's running server, checkpoint and team status stop stop this project's server in order @@ -97,6 +101,7 @@ Other commands: approve check that a saved verification report passed and matches the change being promoted version print the module version this surla binary was built from + stdio the MCP server coding agents start after setup; not run by hand help print this text, or "surla help " for a command's flags ` @@ -153,6 +158,12 @@ func runWithRuntime(args []string, stdout io.Writer, runtime projectRuntime) err // subcommand's flag parsing print its flags and return flag.ErrHelp. func dispatch(sub string, args []string, stdout io.Writer, runtime projectRuntime) error { switch sub { + case "up": + return runUp(args, stdout) + case "setup": + return runSetup(args, stdout) + case "stdio": + return runStdio(args, os.Stdin, stdout, os.Stderr, runtime) case "init": return runtime.init(args, stdout) case "serve": diff --git a/cmd/surla/stdio.go b/cmd/surla/stdio.go new file mode 100644 index 00000000..cd2d2912 --- /dev/null +++ b/cmd/surla/stdio.go @@ -0,0 +1,794 @@ +// This file implements "surla stdio": the MCP server every coding agent on +// this computer starts, registered once by `surla setup -global`. It speaks +// newline-delimited JSON-RPC 2.0 on stdin and stdout. +// +// The folder the agent runs in decides who it is. Inside a project's +// builder working copy (.surla-build) it is that project's builder; inside +// the test writer's (.surla-tests) it is the test writer; anywhere else it +// is a guide. Until the agent calls a tool or reads a resource, stdio +// answers initialize, ping and the tool and resource lists itself from the +// generated MCP catalog, creating no state and starting no process. The +// first tool call binds the session: a guide starts or attaches to the +// folder's project server, hands over this shell's model settings and +// attaches as the project's guide; a worker only reads the credential the +// running server registered for it. Every later request is relayed to the +// server's /mcp with that agent's credential. +package main + +import ( + "bufio" + "bytes" + "context" + "encoding/base64" + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "net/http" + "os" + "os/signal" + "path/filepath" + "slices" + "strings" + "sync" + "syscall" + "time" + + mcpruntime "goa.design/goa-ai/runtime/mcp" + goahttp "goa.design/goa/v3/http" + "goa.design/goa/v3/jsonrpc" + + genmcpserver "github.com/goadesign/surla/gen/jsonrpc/mcp_surla/server" + genmcp "github.com/goadesign/surla/gen/mcp_surla" + genproject "github.com/goadesign/surla/gen/project" + gensurla "github.com/goadesign/surla/gen/surla" + "github.com/goadesign/surla/internal/abspath" + "github.com/goadesign/surla/internal/controlplane" + "github.com/goadesign/surla/internal/modelsettings" + "github.com/goadesign/surla/internal/project" + "github.com/goadesign/surla/internal/testwriter" +) + +type ( + // stdioSession is one coding agent's connection. Its role is fixed when + // stdio starts; its relay is set by the first tool call or resource read + // and replaced when the server stops accepting it. + stdioSession struct { + // role is guide, builder or test_writer, derived from the folder. + role controlplane.CallerKind + // discovery answers initialize, ping and the catalogs for role + // without a server. + discovery http.Handler + // bind returns a relay to the project server for role, given the MCP + // client name the agent reported in initialize ("" when unknown). + bind func(ctx context.Context, client string) (*stdioRelay, error) + // binding serializes binds so concurrent first calls share one start + // and one guide attachment. It is held while the server starts, so + // discovery and relayed requests never wait on it. + binding sync.Mutex + // mu guards client and relay. + mu sync.Mutex + // client is the coding-agent client named by initialize's clientInfo. + client string + // relay is the bound server connection, nil until the first bind. + relay *stdioRelay + } + + // stdioRelay sends JSON-RPC frames to one project server's /mcp as one + // registered agent. + stdioRelay struct { + // endpoint is the server's MCP URL. + endpoint string + // credential is the agent's bearer credential; it never leaves the + // Authorization header. + credential string + // http has no overall timeout: each request carries its own context. + http *http.Client + } + + // stdioFrame carries one raw line or read error from the stdin reader. + stdioFrame struct { + // payload is one trimmed non-empty JSON-RPC line. + payload []byte + // err is a non-EOF read error. + err error + } + + // stdioWriter serializes single-line JSON-RPC responses onto out. + stdioWriter struct { + // mu guards out and err. + mu sync.Mutex + // out receives newline-terminated frames. + out io.Writer + // err is the first write failure; later writes are skipped. + err error + } + + // stdioCancels maps in-flight request IDs to their cancel functions so + // notifications/cancelled can stop them. + stdioCancels struct { + // mu guards next and active. + mu sync.Mutex + // next numbers registrations so release never removes a newer request + // that reused an ID. + next uint64 + // active maps a canonical JSON request ID to its registration. + active map[string]stdioCancelEntry + } + + // stdioCancelEntry is one registered in-flight request. + stdioCancelEntry struct { + // seq is the registration number. + seq uint64 + // cancel stops the request's context. + cancel context.CancelFunc + } + + // memoryResponseWriter captures the in-process discovery handler's reply. + memoryResponseWriter struct { + // header holds the handler's response headers. + header http.Header + // status is the first status written. + status int + // body buffers the response bytes. + body bytes.Buffer + } +) + +const ( + // stdioRequestTimeout bounds one relayed request. Surla tools that wait, + // such as wait_for_changes, return well inside it. + stdioRequestTimeout = 10 * time.Minute + // stdioBindTimeout bounds starting or attaching to the project server. + stdioBindTimeout = 2 * time.Minute +) + +var ( + // errStdioServerStopped is a worker's answer when its project server is + // not running: only the user starts it. + errStdioServerStopped = errors.New("this project's Surla server is not running; ask the user to run surla in the project folder, then call the tool again") + // stdioClientNames maps a word in the MCP clientInfo name to the client + // attach_guide accepts. + stdioClientNames = []string{"claude", "codex", "antigravity", "cursor", "gemini", "opencode"} +) + +// runStdio serves MCP on in and out for the coding agent that started +// `surla stdio` in its working folder, until in ends or the process gets +// SIGINT or SIGTERM. Notices go to diagnostics, never to out. +func runStdio(args []string, in io.Reader, out, diagnostics io.Writer, runtime projectRuntime) error { + fs := flag.NewFlagSet("stdio", flag.ContinueOnError) + if err := fs.Parse(args); err != nil { + return err + } + if fs.NArg() > 0 { + return fmt.Errorf("unexpected arguments %q", fs.Args()) + } + cwd, err := os.Getwd() + if err != nil { + return err + } + session, err := newStdioSession(runtime, cwd, os.Getenv("HC_TERMINAL_ID"), diagnostics) + if err != nil { + return err + } + ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) + defer stop() + return serveStdioLoop(ctx, in, out, session.dispatch) +} + +// newStdioSession derives the agent's role from the physical folder cwd and +// prepares its offline catalog and binding. It reads nothing else and +// creates nothing. +func newStdioSession(runtime projectRuntime, cwd, terminal string, diagnostics io.Writer) (*stdioSession, error) { + physical, err := abspath.Eval(cwd) + if err != nil { + return nil, fmt.Errorf("resolve the working folder: %w", err) + } + role, folder := stdioWorkerRole(physical) + session := &stdioSession{role: role, discovery: newStdioDiscovery(role)} + if role == controlplane.CallerGuide { + session.bind = func(ctx context.Context, client string) (*stdioRelay, error) { + return bindStdioGuide(ctx, runtime, terminal, client, diagnostics) + } + } else { + session.bind = func(ctx context.Context, _ string) (*stdioRelay, error) { + return bindStdioWorker(ctx, runtime, physical, role, folder) + } + } + return session, nil +} + +// stdioWorkerRole reports the worker role whose working copy holds the +// physical folder dir, and that copy's folder name: the innermost +// .surla-build component makes a builder and .surla-tests a test writer. +// Any other folder is a guide's. A worker never becomes a guide, even when +// no project owns its copy. +func stdioWorkerRole(dir string) (controlplane.CallerKind, string) { + parts := strings.Split(filepath.ToSlash(dir), "/") + for i := len(parts) - 1; i >= 0; i-- { + switch parts[i] { + case testwriter.BuilderRole.Folder: + return controlplane.CallerBuilder, parts[i] + case testwriter.TestsRole.Folder: + return controlplane.CallerTestWriter, parts[i] + } + } + return controlplane.CallerGuide, "" +} + +// newStdioDiscovery mounts the generated MCP server over a catalog-only +// adapter, keeping the tools and resources role may call, exactly as the +// project server filters them. Only discovery methods reach it; a tool call +// or resource read is always relayed. +func newStdioDiscovery(role controlplane.CallerKind) http.Handler { + endpoints := genmcp.NewEndpoints(genmcp.NewMCPAdapter(&gensurla.Endpoints{}, nil)) + tools := endpoints.ToolsList + endpoints.ToolsList = func(ctx context.Context, req any) (any, error) { + result, err := tools(ctx, req) + if err != nil { + return nil, err + } + catalog := result.(*genmcp.ToolsListResult) + catalog.Tools = slices.DeleteFunc(catalog.Tools, func(tool *genmcp.ToolInfo) bool { + return !controlplane.OperationAllowed(role, tool.Name) + }) + return catalog, nil + } + resources := endpoints.ResourcesList + endpoints.ResourcesList = func(ctx context.Context, req any) (any, error) { + result, err := resources(ctx, req) + if err != nil { + return nil, err + } + catalog := result.(*genmcp.ResourcesListResult) + catalog.Resources = slices.DeleteFunc(catalog.Resources, func(resource *genmcp.ResourceInfo) bool { + return !controlplane.OperationAllowed(role, resource.Name) + }) + return catalog, nil + } + mux := goahttp.NewMuxer() + genmcpserver.Mount(mux, genmcpserver.New(endpoints, mux, goahttp.RequestDecoder, goahttp.ResponseEncoder, nil)) + return mux +} + +// bindStdioGuide starts or attaches to the working folder's project server, +// hands it this process's model provider settings, attaches the agent as the +// project's guide (adopting its Herdr terminal when one is given) and +// returns a relay with the guide's credential. +func bindStdioGuide( + ctx context.Context, runtime projectRuntime, terminal, client string, diagnostics io.Writer, +) (*stdioRelay, error) { + if err := runtime.preflight(false); err != nil { + return nil, err + } + state, err := runtime.discover() + if err != nil { + return nil, err + } + management, created, err := runtime.attachProject(ctx, state) + if created { + err = errors.Join(err, writeProjectCreatedNotice(diagnostics)) + } + if err != nil { + return nil, err + } + if err := handOverModelSettings(ctx, state, modelsettings.Select(os.Environ()), diagnostics); err != nil { + return nil, err + } + payload := &genproject.AttachGuidePayload{} + if terminal != "" { + payload.HcTerminalID = &terminal + } + if client != "" { + payload.Client = &client + } + attached, err := management.AttachGuide(ctx, payload) + if err != nil { + return nil, fmt.Errorf("attach this agent as the project's guide: %w", err) + } + credential, err := state.AgentCredential(attached.Handle) + if err != nil { + return nil, fmt.Errorf("read the guide's credential: %w", err) + } + return newStdioRelay(state, credential), nil +} + +// bindStdioWorker finds the project whose working copy named folder holds +// dir and returns a relay with the credential of the agent registered for +// role there. It never starts a server, never hands over model settings and +// never attaches a guide: a stopped server or a missing registration is an +// error the agent reports to the user. +func bindStdioWorker( + ctx context.Context, runtime projectRuntime, dir string, role controlplane.CallerKind, folder string, +) (*stdioRelay, error) { + noProject := fmt.Errorf("this %s folder belongs to no Surla project; work only in the folder your assignment names", folder) + root, err := runtime.operatorRootCandidate(dir) + if err != nil { + return nil, err + } + if err := validateOperatorPrivateDir(root); errors.Is(err, os.ErrNotExist) { + return nil, noProject + } else if err != nil { + return nil, fmt.Errorf("read operator storage root %s: %w", root, err) + } + state, err := project.Discover(root, dir) + if err != nil { + return nil, err + } + if state.Record.ID == "" { + return nil, noProject + } + within, err := abspath.Within(filepath.Join(state.Record.Directory, folder), dir) + if errors.Is(err, os.ErrNotExist) || err == nil && !within { + return nil, noProject + } + if err != nil { + return nil, err + } + inUse, err := controlplane.CardStoreInUse(state.CardsDir()) + if err != nil { + return nil, err + } + if !inUse { + return nil, errStdioServerStopped + } + if _, err := confirmProject(ctx, state, projectClient(state)); err != nil { + return nil, fmt.Errorf("%s: %w", projectHolder(state), err) + } + var handles []string + for handle, agent := range state.Record.Agents { + if agent.Role == string(role) { + handles = append(handles, handle) + } + } + if len(handles) != 1 { + return nil, fmt.Errorf("this project has %d registered %s agents, not one; ask the user to start the build's agents from the views page", len(handles), role) + } + credential, err := state.AgentCredential(handles[0]) + if errors.Is(err, os.ErrNotExist) { + return nil, fmt.Errorf("the project's %s has no credential yet; ask the user to start the build's agents from the views page", role) + } + if err != nil { + return nil, fmt.Errorf("read the %s credential: %w", role, err) + } + return newStdioRelay(state, credential), nil +} + +// newStdioRelay connects to state's server as the agent holding credential, +// with the management transport's proxy and redirect refusal but no overall +// timeout: send bounds each request instead. +func newStdioRelay(state *project.State, credential string) *stdioRelay { + client := projectHTTPClient() + client.Timeout = 0 + return &stdioRelay{endpoint: state.Origin() + "/mcp", credential: credential, http: client} +} + +// dispatch answers one JSON-RPC request. A tool call or resource read binds +// the session first; before that, every other request is answered from the +// offline catalog, and after it every request is relayed. A relay the server +// no longer accepts (it restarted or rotated the credential) is bound again +// once. +func (s *stdioSession) dispatch(ctx context.Context, payload []byte, raw *jsonrpc.RawRequest) ([]byte, error) { + method := "" + if raw != nil && !raw.Invalid { + method = raw.Method + } + if method == "initialize" { + s.recordClient(raw.Params) + } + relay := s.currentRelay() + if relay == nil && method != "tools/call" && method != "resources/read" { + return serveStdioDiscovery(ctx, s.discovery, payload, raw) + } + for attempt := 0; ; attempt++ { + if relay == nil { + var err error + if relay, err = s.bindRelay(ctx); err != nil { + return stdioErrorResponse(raw, err), nil + } + } + status, body, err := relay.send(ctx, payload, raw) + if ctx.Err() != nil { + return nil, ctx.Err() + } + if attempt == 0 && (err != nil || status == http.StatusUnauthorized) { + s.dropRelay(relay) + relay = nil + continue + } + if err != nil { + return nil, err + } + return validateStdioHTTPResponse(status, body, relay.endpoint) + } +} + +// recordClient keeps the attach_guide client named by initialize's +// clientInfo, such as "claude" for "claude-code". +func (s *stdioSession) recordClient(params json.RawMessage) { + var initialize struct { + // ClientInfo names the connecting MCP client. + ClientInfo struct { + // Name is the client's self-reported name. + Name string `json:"name"` + } `json:"clientInfo"` + } + if json.Unmarshal(params, &initialize) != nil { + return + } + name := strings.ToLower(initialize.ClientInfo.Name) + for _, client := range stdioClientNames { + if strings.Contains(name, client) { + s.mu.Lock() + s.client = client + s.mu.Unlock() + return + } + } +} + +// currentRelay returns the bound relay, or nil before the first bind. +func (s *stdioSession) currentRelay() *stdioRelay { + s.mu.Lock() + defer s.mu.Unlock() + return s.relay +} + +// bindRelay binds the session once at a time: concurrent first calls share +// one start and one guide attachment. +func (s *stdioSession) bindRelay(ctx context.Context) (*stdioRelay, error) { + s.binding.Lock() + defer s.binding.Unlock() + s.mu.Lock() + relay, client := s.relay, s.client + s.mu.Unlock() + if relay != nil { + return relay, nil + } + bindCtx, cancel := context.WithTimeout(ctx, stdioBindTimeout) + defer cancel() + relay, err := s.bind(bindCtx, client) + if err != nil { + return nil, err + } + s.mu.Lock() + s.relay = relay + s.mu.Unlock() + return relay, nil +} + +// dropRelay forgets relay unless another request already replaced it. +func (s *stdioSession) dropRelay(relay *stdioRelay) { + s.mu.Lock() + defer s.mu.Unlock() + if s.relay == relay { + s.relay = nil + } +} + +// send posts payload to the server as the relay's agent and returns the +// HTTP status and body. +func (r *stdioRelay) send(ctx context.Context, payload []byte, raw *jsonrpc.RawRequest) (status int, body []byte, err error) { + ctx, cancel := context.WithTimeout(ctx, stdioRequestTimeout) + defer cancel() + req, err := newStdioMCPRequest(ctx, r.endpoint, payload, raw) + if err != nil { + return 0, nil, err + } + req.Header.Set("Authorization", "Bearer "+r.credential) + resp, err := r.http.Do(req) + if err != nil { + return 0, nil, err + } + defer func() { err = errors.Join(err, resp.Body.Close()) }() + body, err = io.ReadAll(resp.Body) + return resp.StatusCode, body, err +} + +// serveStdioDiscovery answers one discovery request with the in-process +// catalog handler. +func serveStdioDiscovery(ctx context.Context, handler http.Handler, payload []byte, raw *jsonrpc.RawRequest) ([]byte, error) { + req, err := newStdioMCPRequest(ctx, "http://surla-stdio/mcp", payload, raw) + if err != nil { + return nil, err + } + w := &memoryResponseWriter{header: make(http.Header)} + handler.ServeHTTP(w, req) + return validateStdioHTTPResponse(w.status, w.body.Bytes(), "the offline catalog") +} + +// stdioErrorResponse reports a failed bind to the agent as a JSON-RPC error +// with the request's ID, so the agent can tell the user what to do. +func stdioErrorResponse(raw *jsonrpc.RawRequest, err error) []byte { + var id any + if raw != nil && raw.HasID { + id = raw.ID + } + out, marshalErr := json.Marshal(jsonrpc.MakeErrorResponse(id, jsonrpc.InternalError, "surla: "+err.Error(), nil)) + if marshalErr != nil { + return nil + } + return out +} + +// serveStdioLoop reads frames from in and dispatches each request on its own +// goroutine, so a long tool call does not hold up pings or discovery, until +// in ends or ctx is done. It then waits for the requests in flight. +func serveStdioLoop( + ctx context.Context, + in io.Reader, + out io.Writer, + dispatch func(context.Context, []byte, *jsonrpc.RawRequest) ([]byte, error), +) error { + frames := make(chan stdioFrame) + go readStdioFrames(ctx, in, frames) + writer := &stdioWriter{out: out} + cancels := &stdioCancels{active: make(map[string]stdioCancelEntry)} + var ( + wg sync.WaitGroup + readErr error + ) +loop: + for { + select { + case <-ctx.Done(): + break loop + case frame, ok := <-frames: + if !ok { + break loop + } + if frame.err != nil { + readErr = frame.err + break loop + } + var raw jsonrpc.RawRequest + decoded := raw.UnmarshalJSON(frame.payload) == nil + if decoded && !raw.Invalid && raw.JSONRPC == "2.0" && raw.HasMethod && raw.Method != "" && !raw.HasID { + handleStdioNotification(&raw, cancels) + continue + } + var rawPtr *jsonrpc.RawRequest + if decoded { + rawPtr = &raw + } + reqCtx, cancel := context.WithCancel(ctx) + idKey, seq := "", uint64(0) + if rawPtr != nil && !rawPtr.Invalid && rawPtr.HasID { + // Register before starting the request so a cancellation that + // follows immediately finds it. + if idKey = canonicalStdioIDKey(rawPtr.ID); idKey != "" { + seq = cancels.track(idKey, cancel) + } + } + wg.Add(1) + go func() { + defer wg.Done() + defer cancel() + if idKey != "" { + defer cancels.release(idKey, seq) + } + resp, err := dispatch(reqCtx, frame.payload, rawPtr) + if reqCtx.Err() != nil { + return + } + if err != nil { + resp = stdioErrorResponse(rawPtr, err) + } + if line := compactStdioJSON(resp); len(line) > 0 { + writer.writeLine(line) + } + }() + } + } + wg.Wait() + if readErr != nil { + return fmt.Errorf("read stdio input: %w", readErr) + } + return writer.firstErr() +} + +// readStdioFrames sends each non-empty trimmed line of in to frames until +// EOF, a read error or ctx's end, then closes frames. +func readStdioFrames(ctx context.Context, in io.Reader, frames chan<- stdioFrame) { + defer close(frames) + reader := bufio.NewReader(in) + for { + line, err := reader.ReadBytes('\n') + if trimmed := bytes.TrimSpace(line); len(trimmed) > 0 { + select { + case frames <- stdioFrame{payload: bytes.Clone(trimmed)}: + case <-ctx.Done(): + return + } + } + if err != nil { + if !errors.Is(err, io.EOF) { + select { + case frames <- stdioFrame{err: err}: + case <-ctx.Done(): + } + } + return + } + } +} + +// handleStdioNotification stops the request a notifications/cancelled +// names. Other notifications need no reply and are not forwarded. +func handleStdioNotification(raw *jsonrpc.RawRequest, cancels *stdioCancels) { + if raw.Method != "notifications/cancelled" || len(raw.Params) == 0 { + return + } + var params struct { + // RequestID is the ID of the request to stop. + RequestID json.RawMessage `json:"requestId"` + } + if json.Unmarshal(raw.Params, ¶ms) != nil || len(params.RequestID) == 0 { + return + } + decoder := json.NewDecoder(bytes.NewReader(params.RequestID)) + decoder.UseNumber() + var id any + if decoder.Decode(&id) != nil { + return + } + if key := canonicalStdioIDKey(id); key != "" { + cancels.cancel(key) + } +} + +// validateStdioHTTPResponse requires a JSON body: every dispatched frame is a +// request, so an empty or 202 reply means the server failed it. +func validateStdioHTTPResponse(status int, body []byte, target string) ([]byte, error) { + trimmed := bytes.TrimSpace(body) + if status == http.StatusAccepted || len(trimmed) == 0 { + return nil, fmt.Errorf("unexpected empty HTTP %d response from %s", status, target) + } + if !json.Valid(trimmed) { + return nil, fmt.Errorf("unexpected HTTP %d response from %s that is not JSON", status, target) + } + return trimmed, nil +} + +// newStdioMCPRequest builds the HTTP POST for one frame. A frame whose params +// carry the 2026-07-28 protocol version in _meta gets that version and the +// method and tool-name headers; any other request after initialize gets the +// legacy protocol version, which the generated server serves statelessly. +func newStdioMCPRequest(ctx context.Context, target string, payload []byte, raw *jsonrpc.RawRequest) (*http.Request, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodPost, target, bytes.NewReader(payload)) + if err != nil { + return nil, err + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + if raw != nil && !raw.Invalid { + var params struct { + // Name is a tools/call tool name. + Name json.RawMessage `json:"name"` + // Meta carries the modern protocol version. + Meta map[string]any `json:"_meta"` + } + if len(raw.Params) > 0 && json.Unmarshal(raw.Params, ¶ms) == nil { + if version, ok := params.Meta["io.modelcontextprotocol/protocolVersion"].(string); ok && version != "" { + req.Header.Set("MCP-Protocol-Version", version) + req.Header.Set("Mcp-Method", raw.Method) + var name string + if raw.Method == "tools/call" && json.Unmarshal(params.Name, &name) == nil { + req.Header.Set("Mcp-Name", encodeMCPHeaderValue(name)) + } + return req, nil + } + } + if raw.Method == "initialize" { + return req, nil + } + } + req.Header.Set("MCP-Protocol-Version", mcpruntime.LegacyProtocolVersion) + return req, nil +} + +// encodeMCPHeaderValue wraps a header value in MCP's base64 envelope when it +// has surrounding spaces, bytes outside printable ASCII or the envelope's +// own prefix. +func encodeMCPHeaderValue(value string) string { + unsafe := strings.HasPrefix(value, "=?base64?") || strings.TrimSpace(value) != value + for i := range len(value) { + if value[i] < 0x20 || value[i] > 0x7e { + unsafe = true + break + } + } + if unsafe { + return "=?base64?" + base64.StdEncoding.EncodeToString([]byte(value)) + "?=" + } + return value +} + +// canonicalStdioIDKey encodes a decoded request ID as a map key that keeps +// numbers and strings distinct, or "" for a null ID. +func canonicalStdioIDKey(id any) string { + if id == nil { + return "" + } + encoded, err := json.Marshal(id) + if err != nil || bytes.Equal(encoded, []byte("null")) { + return "" + } + return string(encoded) +} + +// compactStdioJSON removes newlines so each response is one stdout line. +func compactStdioJSON(raw []byte) []byte { + var compact bytes.Buffer + if err := json.Compact(&compact, bytes.TrimSpace(raw)); err != nil { + return nil + } + return compact.Bytes() +} + +// Header returns the buffered response headers. +func (w *memoryResponseWriter) Header() http.Header { return w.header } + +// Write appends response bytes, recording 200 when no status was written. +func (w *memoryResponseWriter) Write(p []byte) (int, error) { + if w.status == 0 { + w.status = http.StatusOK + } + return w.body.Write(p) +} + +// WriteHeader records the first status written. +func (w *memoryResponseWriter) WriteHeader(status int) { + if w.status == 0 { + w.status = status + } +} + +// writeLine writes one newline-terminated frame, keeping the first error. +func (w *stdioWriter) writeLine(line []byte) { + w.mu.Lock() + defer w.mu.Unlock() + if w.err != nil { + return + } + if _, err := w.out.Write(append(line, '\n')); err != nil { + w.err = err + } +} + +// firstErr returns the first write error. +func (w *stdioWriter) firstErr() error { + w.mu.Lock() + defer w.mu.Unlock() + return w.err +} + +// track registers cancel for the request idKey and returns its number. +func (c *stdioCancels) track(idKey string, cancel context.CancelFunc) uint64 { + c.mu.Lock() + defer c.mu.Unlock() + c.next++ + c.active[idKey] = stdioCancelEntry{seq: c.next, cancel: cancel} + return c.next +} + +// cancel stops the request idKey when it is in flight. +func (c *stdioCancels) cancel(idKey string) { + c.mu.Lock() + entry, ok := c.active[idKey] + delete(c.active, idKey) + c.mu.Unlock() + if ok { + entry.cancel() + } +} + +// release removes the registration seq of idKey when it is still current. +func (c *stdioCancels) release(idKey string, seq uint64) { + c.mu.Lock() + defer c.mu.Unlock() + if entry, ok := c.active[idKey]; ok && entry.seq == seq { + delete(c.active, idKey) + } +} diff --git a/cmd/surla/stdio_test.go b/cmd/surla/stdio_test.go new file mode 100644 index 00000000..4dbe7be9 --- /dev/null +++ b/cmd/surla/stdio_test.go @@ -0,0 +1,361 @@ +package main + +import ( + "bytes" + "context" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/goadesign/surla/internal/abspath" + "github.com/goadesign/surla/internal/controlplane" + "github.com/goadesign/surla/internal/project" +) + +// stdioReply is one JSON-RPC response line read back from stdout. +type stdioReply struct { + // ID is the request ID the response answers. + ID json.RawMessage `json:"id"` + // Result is the successful result. + Result json.RawMessage `json:"result"` + // Error is the failure, when there is one. + Error *struct { + // Code is the JSON-RPC error code. + Code int `json:"code"` + // Message explains the failure. + Message string `json:"message"` + } `json:"error"` +} + +// runStdioFrames serves lines through session and returns the replies by +// request ID once input ends and every request has finished. +func runStdioFrames(t *testing.T, session *stdioSession, lines ...string) map[string]stdioReply { + t.Helper() + var out bytes.Buffer + require.NoError(t, serveStdioLoop(context.Background(), strings.NewReader(strings.Join(lines, "\n")+"\n"), &out, session.dispatch)) + replies := make(map[string]stdioReply) + for _, line := range strings.Split(strings.TrimSpace(out.String()), "\n") { + if line == "" { + continue + } + var reply stdioReply + require.NoError(t, json.Unmarshal([]byte(line), &reply), line) + replies[string(reply.ID)] = reply + } + return replies +} + +// toolNames lists the tool names of a tools/list result. +func toolNames(t *testing.T, result json.RawMessage) []string { + t.Helper() + var list struct { + // Tools is the catalog. + Tools []struct { + // Name is the tool's name. + Name string `json:"name"` + } `json:"tools"` + } + require.NoError(t, json.Unmarshal(result, &list)) + var names []string + for _, tool := range list.Tools { + names = append(names, tool.Name) + } + return names +} + +// failingBind fails the test when a session binds: discovery must not. +func failingBind(t *testing.T) func(context.Context, string) (*stdioRelay, error) { + return func(context.Context, string) (*stdioRelay, error) { + t.Error("discovery bound the session") + return nil, io.ErrUnexpectedEOF + } +} + +func TestStdioDiscoveryCreatesNothing(t *testing.T) { + configRoot := t.TempDir() + dir := t.TempDir() + session, err := newStdioSession(testProjectRuntimeAt(configRoot), dir, "t42", io.Discard) + require.NoError(t, err) + assert.Equal(t, controlplane.CallerGuide, session.role) + session.bind = failingBind(t) + + replies := runStdioFrames(t, session, + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"claude-code","version":"2"}}}`, + `{"jsonrpc":"2.0","method":"notifications/initialized"}`, + `{"jsonrpc":"2.0","id":2,"method":"ping"}`, + `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`, + `{"jsonrpc":"2.0","id":4,"method":"resources/list"}`, + ) + require.Len(t, replies, 4) + for id, reply := range replies { + assert.Nil(t, reply.Error, id) + } + var initialize struct { + // ProtocolVersion is the negotiated version. + ProtocolVersion string `json:"protocolVersion"` + // ServerInfo names the server. + ServerInfo struct { + // Name is the server's name. + Name string `json:"name"` + } `json:"serverInfo"` + } + require.NoError(t, json.Unmarshal(replies["1"].Result, &initialize)) + assert.Equal(t, "2025-11-25", initialize.ProtocolVersion) + assert.Equal(t, "surla", initialize.ServerInfo.Name) + tools := toolNames(t, replies["3"].Result) + for _, name := range []string{"propose_change", "revise_change", "init_project", "open_views", "update_draft", "get_build"} { + assert.Contains(t, tools, name) + } + for _, name := range []string{"generate_code", "confirm_intent", "approve_merge", "report_tests_finished"} { + assert.NotContains(t, tools, name) + } + assert.Contains(t, string(replies["4"].Result), "surla://golden-path") + assert.Equal(t, "claude", session.client) + + for _, folder := range []string{configRoot, dir} { + entries, err := os.ReadDir(folder) + require.NoError(t, err) + assert.Empty(t, entries, "discovery wrote into %s", folder) + } +} + +func TestStdioWorkerFoldersBindOnlyTheirRole(t *testing.T) { + project := t.TempDir() + for _, dir := range []string{".surla-build/surla/build-1/sub", ".surla-tests/eval", "nested/.surla-build/x/.surla-tests/y"} { + require.NoError(t, os.MkdirAll(filepath.Join(project, dir), 0o755)) + } + alias := filepath.Join(t.TempDir(), "alias") + require.NoError(t, os.Symlink(filepath.Join(project, ".surla-build", "surla"), alias)) + + cases := []struct { + name, dir string + role controlplane.CallerKind + has, lacks string + }{ + {"project folder", project, controlplane.CallerGuide, "propose_change", "generate_code"}, + {"builder copy with a nested prefix", filepath.Join(project, ".surla-build", "surla", "build-1", "sub"), controlplane.CallerBuilder, "generate_code", "propose_change"}, + {"builder copy through a symlink", filepath.Join(alias, "build-1"), controlplane.CallerBuilder, "generate_code", "init_project"}, + {"test writer's eval module", filepath.Join(project, ".surla-tests", "eval"), controlplane.CallerTestWriter, "report_tests_finished", "propose_change"}, + {"innermost copy decides", filepath.Join(project, "nested", ".surla-build", "x", ".surla-tests", "y"), controlplane.CallerTestWriter, "get_test_writer_assignment", "generate_code"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), c.dir, "", io.Discard) + require.NoError(t, err) + assert.Equal(t, c.role, session.role) + session.bind = failingBind(t) + replies := runStdioFrames(t, session, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`) + tools := toolNames(t, replies["1"].Result) + assert.Contains(t, tools, c.has) + assert.NotContains(t, tools, c.lacks) + }) + } +} + +func TestStdioWorkerWithoutARunningProjectNeverBecomesAGuide(t *testing.T) { + configRoot := t.TempDir() + runtime := testProjectRuntimeAt(configRoot) + workspace, err := abspath.Eval(t.TempDir()) + require.NoError(t, err) + worker := filepath.Join(workspace, ".surla-tests", "eval") + require.NoError(t, os.MkdirAll(worker, 0o755)) + call := `{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"list_test_writer_assignments","arguments":{}}}` + + // No operator storage: the copy belongs to no project. + session, err := newStdioSession(runtime, worker, "t42", io.Discard) + require.NoError(t, err) + reply := runStdioFrames(t, session, call)["7"] + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "belongs to no Surla project") + entries, err := os.ReadDir(configRoot) + require.NoError(t, err) + assert.Empty(t, entries, "a worker bind created operator storage") + + // A project whose server is stopped: the worker is told to ask the user. + root, err := runtime.operatorRoot(workspace) + require.NoError(t, err) + initializeTestProject(t, root, workspace) + session, err = newStdioSession(runtime, worker, "t42", io.Discard) + require.NoError(t, err) + reply = runStdioFrames(t, session, call)["7"] + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, errStdioServerStopped.Error()) +} + +// initializeTestProject saves a project record for workspace under the +// operator root, as the first `surla` start does, without starting a server. +func initializeTestProject(t *testing.T, root, workspace string) { + t.Helper() + state, err := project.Discover(root, workspace) + require.NoError(t, err) + lock, err := state.StartLock(context.Background()) + require.NoError(t, err) + created, err := state.Initialize("uid:test") + require.NoError(t, err) + require.True(t, created) + require.NoError(t, lock.Close()) +} + +func TestStdioRelaysCallsWithTheBoundCredential(t *testing.T) { + var ( + mu sync.Mutex + received []string + ) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var request struct { + // ID is the relayed request's ID. + ID json.RawMessage `json:"id"` + // Method is the relayed method. + Method string `json:"method"` + } + require.NoError(t, json.NewDecoder(r.Body).Decode(&request)) + mu.Lock() + received = append(received, request.Method+" "+r.Header.Get("Authorization")+" "+r.Header.Get("MCP-Protocol-Version")) + mu.Unlock() + if r.Header.Get("Authorization") == "Bearer stale" { + w.WriteHeader(http.StatusUnauthorized) + return + } + w.Header().Set("Content-Type", "application/json") + _, err := io.WriteString(w, `{"jsonrpc":"2.0","id":`+string(request.ID)+`,"result":{"method":"`+request.Method+`"}}`) + assert.NoError(t, err) + })) + defer server.Close() + + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), t.TempDir(), "", io.Discard) + require.NoError(t, err) + var binds []string + credentials := []string{"stale", "fresh"} + session.bind = func(_ context.Context, client string) (*stdioRelay, error) { + binds = append(binds, client) + credential := credentials[len(binds)-1] + return &stdioRelay{endpoint: server.URL + "/mcp", credential: credential, http: server.Client()}, nil + } + + replies := runStdioFrames(t, session, + `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"codex-mcp-client","version":"1"}}}`, + ) + assert.Nil(t, replies["1"].Error) + replies = runStdioFrames(t, session, + `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_changes","arguments":{}}}`, + ) + assert.JSONEq(t, `{"method":"tools/call"}`, string(replies["2"].Result)) + replies = runStdioFrames(t, session, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + assert.JSONEq(t, `{"method":"tools/list"}`, string(replies["3"].Result)) + + assert.Equal(t, []string{"codex", "codex"}, binds, "a refused credential binds once more") + assert.Equal(t, []string{ + "tools/call Bearer stale 2025-11-25", + "tools/call Bearer fresh 2025-11-25", + "tools/list Bearer fresh 2025-11-25", + }, received) +} + +func TestStdioReportsABindFailureToTheAgent(t *testing.T) { + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), t.TempDir(), "", io.Discard) + require.NoError(t, err) + session.bind = func(context.Context, string) (*stdioRelay, error) { + return nil, errStdioServerStopped + } + reply := runStdioFrames(t, session, `{"jsonrpc":"2.0","id":"a","method":"resources/read","params":{"uri":"surla://golden-path"}}`)[`"a"`] + require.NotNil(t, reply.Error) + assert.Equal(t, -32603, reply.Error.Code) + assert.Equal(t, "surla: "+errStdioServerStopped.Error(), reply.Error.Message) + assert.Nil(t, session.currentRelay(), "a failed bind binds nothing") +} + +func TestStdioCancelledRequestGetsNoReply(t *testing.T) { + started := make(chan struct{}) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // The server notices a closed connection only after reading the body. + _, err := io.Copy(io.Discard, r.Body) + assert.NoError(t, err) + close(started) + <-r.Context().Done() + })) + defer server.Close() + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), t.TempDir(), "", io.Discard) + require.NoError(t, err) + session.bind = func(context.Context, string) (*stdioRelay, error) { + return &stdioRelay{endpoint: server.URL + "/mcp", credential: "c", http: server.Client()}, nil + } + + in, input := io.Pipe() + var out bytes.Buffer + done := make(chan error, 1) + go func() { done <- serveStdioLoop(context.Background(), in, &out, session.dispatch) }() + _, err = io.WriteString(input, `{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"wait_for_changes","arguments":{}}}`+"\n") + require.NoError(t, err) + select { + case <-started: + case <-time.After(10 * time.Second): + t.Fatal("the call never reached the server") + } + _, err = io.WriteString(input, `{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":9}}`+"\n") + require.NoError(t, err) + require.NoError(t, input.Close()) + select { + case err := <-done: + require.NoError(t, err) + case <-time.After(10 * time.Second): + t.Fatal("the cancelled call kept the loop running") + } + assert.Empty(t, out.String()) +} + +func TestStdioDiscoveryAnswersWhileTheFirstCallBinds(t *testing.T) { + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), t.TempDir(), "", io.Discard) + require.NoError(t, err) + binding := make(chan struct{}) + release := make(chan struct{}) + session.bind = func(context.Context, string) (*stdioRelay, error) { + close(binding) + <-release + return nil, errStdioServerStopped + } + in, input := io.Pipe() + out := &stdioLockedWriter{w: &bytes.Buffer{}} + done := make(chan error, 1) + go func() { done <- serveStdioLoop(context.Background(), in, out, session.dispatch) }() + _, err = io.WriteString(input, `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_changes","arguments":{}}}`+"\n") + require.NoError(t, err) + <-binding + _, err = io.WriteString(input, `{"jsonrpc":"2.0","id":2,"method":"ping"}`+"\n") + require.NoError(t, err) + assert.Eventually(t, func() bool { return strings.Contains(out.String(), `"id":2`) }, 10*time.Second, 10*time.Millisecond) + close(release) + require.NoError(t, input.Close()) + require.NoError(t, <-done) +} + +// stdioLockedWriter lets a test read output while the loop writes it. +type stdioLockedWriter struct { + // mu guards w. + mu sync.Mutex + // w receives the loop's output. + w *bytes.Buffer +} + +// Write appends p under the lock. +func (l *stdioLockedWriter) Write(p []byte) (int, error) { + l.mu.Lock() + defer l.mu.Unlock() + return l.w.Write(p) +} + +// String returns what was written so far. +func (l *stdioLockedWriter) String() string { + l.mu.Lock() + defer l.mu.Unlock() + return l.w.String() +} diff --git a/cmd/surla/up.go b/cmd/surla/up.go new file mode 100644 index 00000000..5cb5b3e6 --- /dev/null +++ b/cmd/surla/up.go @@ -0,0 +1,83 @@ +// This file implements "surla up": the one command a person runs after +// installing surla. It runs `surla setup -global` and starts Chorus when it +// is installed, so agents of the same project can message each other. +package main + +import ( + "context" + "errors" + "flag" + "fmt" + "io" + "os" + "os/exec" + "time" +) + +// chorusUpTimeout bounds `chorus up`, which returns once its server answers. +const chorusUpTimeout = time.Minute + +// runUp implements `surla up` for the CLI: global setup unless SURLA_NO_SETUP +// is 1, then `chorus up` when chorus is on PATH. +func runUp(args []string, stdout io.Writer) error { + fs := flag.NewFlagSet("up", flag.ContinueOnError) + if err := fs.Parse(args); err != nil { + return err + } + if fs.NArg() > 0 { + return fmt.Errorf("unexpected arguments %q", fs.Args()) + } + var env *setupEnvironment + if os.Getenv("SURLA_NO_SETUP") != "1" { + processEnv, err := processSetupEnvironment() + if err != nil { + return err + } + env = &processEnv + } + chorus, err := exec.LookPath("chorus") + if err != nil { + chorus = "" + } + return upWith(env, chorus, startChorus, stdout) +} + +// upWith runs global setup with env (skipped when env is nil), then starts +// Chorus with start when chorus names its executable. Missing Chorus is +// reported, not an error: Surla works without it, but its agents cannot +// message each other. A failed setup or Chorus start is an error naming how +// to continue. +func upWith( + env *setupEnvironment, chorus string, start func(context.Context, string, io.Writer) error, out io.Writer, +) error { + if env != nil { + if err := setupGlobal(*env, out); err != nil { + return fmt.Errorf("%w (fix that file and run surla up again, or set SURLA_NO_SETUP=1 to skip setup)", err) + } + } + if chorus == "" { + fmt.Fprintln(out, "Chorus is not installed, so Surla's agents will work without messaging each other.") + } else { + ctx, cancel := context.WithTimeout(context.Background(), chorusUpTimeout) + defer cancel() + if err := start(ctx, chorus, out); err != nil { + return fmt.Errorf("start Chorus: %w", err) + } + } + _, err := fmt.Fprintln(out, "Surla is ready: open your coding agent in a project folder and type /surla.") + return err +} + +// startChorus runs `chorus up` with no input and its output on out. Chorus +// starts its server in the background and returns once it answers. +func startChorus(ctx context.Context, chorus string, out io.Writer) error { + command := exec.CommandContext(ctx, chorus, "up") + command.Stdin = nil + command.Stdout = out + command.Stderr = out + err := command.Run() + if errors.Is(ctx.Err(), context.DeadlineExceeded) { + return fmt.Errorf("chorus up did not finish within %s", chorusUpTimeout) + } + return err +} diff --git a/cmd/surla/up_test.go b/cmd/surla/up_test.go new file mode 100644 index 00000000..988f773e --- /dev/null +++ b/cmd/surla/up_test.go @@ -0,0 +1,98 @@ +package main + +import ( + "bytes" + "context" + "errors" + "io" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestUpRunsSetupThenChorus(t *testing.T) { + cases := []struct { + name string + setup bool + chorus string + startErr error + want []string + wantErr string + }{ + { + name: "setup and Chorus", + setup: true, + chorus: "/usr/local/bin/chorus", + want: []string{"Installed the /surla skill", "chorus up ran", "Surla is ready"}, + }, + { + name: "Chorus not installed", + setup: true, + want: []string{"Installed the /surla skill", "Chorus is not installed", "Surla is ready"}, + }, + { + name: "setup skipped", + chorus: "/usr/local/bin/chorus", + want: []string{"chorus up ran", "Surla is ready"}, + }, + { + name: "Chorus fails", + chorus: "/usr/local/bin/chorus", + startErr: errors.New("exit status 1"), + wantErr: "start Chorus: exit status 1", + }, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + home := t.TempDir() + var env *setupEnvironment + if c.setup { + setup := testSetupEnvironment(home) + env = &setup + } + var started []string + start := func(_ context.Context, chorus string, out io.Writer) error { + started = append(started, chorus) + if c.startErr != nil { + return c.startErr + } + _, err := io.WriteString(out, "chorus up ran\n") + return err + } + var out bytes.Buffer + err := upWith(env, c.chorus, start, &out) + if c.chorus != "" { + assert.Equal(t, []string{c.chorus}, started) + } else { + assert.Empty(t, started) + } + if c.wantErr != "" { + assert.EqualError(t, err, c.wantErr) + return + } + require.NoError(t, err) + last := -1 + for _, line := range c.want { + at := bytes.Index(out.Bytes(), []byte(line)) + assert.Greater(t, at, last, "%q in order in %s", line, out.String()) + last = at + } + _, statErr := os.Stat(filepath.Join(home, ".agents", "skills", "surla", "SKILL.md")) + assert.Equal(t, c.setup, statErr == nil, "setup ran only when asked") + }) + } +} + +func TestUpNamesTheSkipWhenSetupFails(t *testing.T) { + home := t.TempDir() + require.NoError(t, os.MkdirAll(filepath.Join(home, ".cursor"), 0o755)) + require.NoError(t, os.WriteFile(filepath.Join(home, ".cursor", "mcp.json"), []byte("{"), 0o644)) + env := testSetupEnvironment(home) + err := upWith(&env, "", nil, io.Discard) + require.Error(t, err) + assert.Contains(t, err.Error(), "parse JSON in "+filepath.Join(home, ".cursor", "mcp.json")) + assert.Contains(t, err.Error(), "set SURLA_NO_SETUP=1 to skip setup") +} From 79d2500e6f71f2853884b7961478f600201aa230 Mon Sep 17 00:00:00 2001 From: Raphael Simon Date: Thu, 19 Nov 2026 13:26:25 -0800 Subject: [PATCH 4/4] Bind stdio workers by registered folder and never replay a tool call A project created in a child folder keeps its builder and test-writer copies there, so a worker now binds to the registered agent whose working folder holds it, falling back to the project folder's own copy only when one agent has the role; the server's build is checked as surla does. The guide binds from the agent's own folder rather than the process's. Relayed requests no longer stop after ten minutes: the server bounds its own operations, some of which run longer, and the agent cancels with notifications/cancelled. A request is sent again only when the server certainly did not run it (a refused credential or a refused connection), so a tool that changes state is never sent twice. surla up starts Chorus without the shell's model provider settings. A new test binds a guide and both kinds of worker copy against the real project server and control plane, including a rotated credential. --- cmd/surla/stdio.go | 105 ++++++++++++++++++---------- cmd/surla/stdio_test.go | 147 ++++++++++++++++++++++++++++++++++++++++ cmd/surla/up.go | 5 +- cmd/surla/up_test.go | 11 +++ 4 files changed, 232 insertions(+), 36 deletions(-) diff --git a/cmd/surla/stdio.go b/cmd/surla/stdio.go index cd2d2912..7eb08045 100644 --- a/cmd/surla/stdio.go +++ b/cmd/surla/stdio.go @@ -136,13 +136,10 @@ type ( } ) -const ( - // stdioRequestTimeout bounds one relayed request. Surla tools that wait, - // such as wait_for_changes, return well inside it. - stdioRequestTimeout = 10 * time.Minute - // stdioBindTimeout bounds starting or attaching to the project server. - stdioBindTimeout = 2 * time.Minute -) +// stdioBindTimeout bounds starting or attaching to the project server. A +// relayed request has no stdio deadline: the server bounds its own operations +// (some run 30 minutes), and the agent stops one with notifications/cancelled. +const stdioBindTimeout = 2 * time.Minute var ( // errStdioServerStopped is a worker's answer when its project server is @@ -189,7 +186,7 @@ func newStdioSession(runtime projectRuntime, cwd, terminal string, diagnostics i session := &stdioSession{role: role, discovery: newStdioDiscovery(role)} if role == controlplane.CallerGuide { session.bind = func(ctx context.Context, client string) (*stdioRelay, error) { - return bindStdioGuide(ctx, runtime, terminal, client, diagnostics) + return bindStdioGuide(ctx, runtime, physical, terminal, client, diagnostics) } } else { session.bind = func(ctx context.Context, _ string) (*stdioRelay, error) { @@ -252,17 +249,22 @@ func newStdioDiscovery(role controlplane.CallerKind) http.Handler { return mux } -// bindStdioGuide starts or attaches to the working folder's project server, +// bindStdioGuide starts or attaches to the project server of the physical +// folder dir (the nearest project at or above it, else a new one for dir), // hands it this process's model provider settings, attaches the agent as the // project's guide (adopting its Herdr terminal when one is given) and // returns a relay with the guide's credential. func bindStdioGuide( - ctx context.Context, runtime projectRuntime, terminal, client string, diagnostics io.Writer, + ctx context.Context, runtime projectRuntime, dir, terminal, client string, diagnostics io.Writer, ) (*stdioRelay, error) { if err := runtime.preflight(false); err != nil { return nil, err } - state, err := runtime.discover() + root, err := runtime.operatorRoot(dir) + if err != nil { + return nil, err + } + state, err := project.Discover(root, dir) if err != nil { return nil, err } @@ -296,9 +298,12 @@ func bindStdioGuide( // bindStdioWorker finds the project whose working copy named folder holds // dir and returns a relay with the credential of the agent registered for -// role there. It never starts a server, never hands over model settings and -// never attaches a guide: a stopped server or a missing registration is an -// error the agent reports to the user. +// role there: the one whose registered working folder holds dir, or, in the +// project folder's own copy, the only agent with role. A project created in +// a child folder keeps its copies there, which only the registration names. +// It never starts a server, never hands over model settings and never +// attaches a guide: a stopped server or a missing registration is an error +// the agent reports to the user. func bindStdioWorker( ctx context.Context, runtime projectRuntime, dir string, role controlplane.CallerKind, folder string, ) (*stdioRelay, error) { @@ -319,13 +324,6 @@ func bindStdioWorker( if state.Record.ID == "" { return nil, noProject } - within, err := abspath.Within(filepath.Join(state.Record.Directory, folder), dir) - if errors.Is(err, os.ErrNotExist) || err == nil && !within { - return nil, noProject - } - if err != nil { - return nil, err - } inUse, err := controlplane.CardStoreInUse(state.CardsDir()) if err != nil { return nil, err @@ -333,19 +331,46 @@ func bindStdioWorker( if !inUse { return nil, errStdioServerStopped } - if _, err := confirmProject(ctx, state, projectClient(state)); err != nil { + identity, err := confirmProject(ctx, state, projectClient(state)) + if err != nil { return nil, fmt.Errorf("%s: %w", projectHolder(state), err) } - var handles []string + if err := confirmBuild(identity); err != nil { + return nil, err + } + var registered, holding []string for handle, agent := range state.Record.Agents { - if agent.Role == string(role) { - handles = append(handles, handle) + if agent.Role != string(role) { + continue + } + registered = append(registered, handle) + within, err := stdioWithin(agent.Folder, dir) + if err != nil { + return nil, err + } + if within { + holding = append(holding, handle) } } - if len(handles) != 1 { - return nil, fmt.Errorf("this project has %d registered %s agents, not one; ask the user to start the build's agents from the views page", len(handles), role) + handle := "" + switch { + case len(holding) == 1: + handle = holding[0] + case len(holding) == 0 && len(registered) == 1: + rootCopy, err := stdioWithin(filepath.Join(state.Record.Directory, folder), dir) + if err != nil { + return nil, err + } + if !rootCopy { + return nil, noProject + } + handle = registered[0] + case len(registered) == 0: + return nil, fmt.Errorf("this project has no registered %s; ask the user to start the build's agents from the views page", role) + default: + return nil, fmt.Errorf("this folder is not the working folder of this project's %s; work only in the folder your assignment names", role) } - credential, err := state.AgentCredential(handles[0]) + credential, err := state.AgentCredential(handle) if errors.Is(err, os.ErrNotExist) { return nil, fmt.Errorf("the project's %s has no credential yet; ask the user to start the build's agents from the views page", role) } @@ -355,9 +380,19 @@ func bindStdioWorker( return newStdioRelay(state, credential), nil } +// stdioWithin reports whether dir is in root's physical subtree; a missing +// root holds nothing. +func stdioWithin(root, dir string) (bool, error) { + within, err := abspath.Within(root, dir) + if errors.Is(err, os.ErrNotExist) { + return false, nil + } + return within, err +} + // newStdioRelay connects to state's server as the agent holding credential, // with the management transport's proxy and redirect refusal but no overall -// timeout: send bounds each request instead. +// timeout: the request's context ends it. func newStdioRelay(state *project.State, credential string) *stdioRelay { client := projectHTTPClient() client.Timeout = 0 @@ -366,9 +401,11 @@ func newStdioRelay(state *project.State, credential string) *stdioRelay { // dispatch answers one JSON-RPC request. A tool call or resource read binds // the session first; before that, every other request is answered from the -// offline catalog, and after it every request is relayed. A relay the server -// no longer accepts (it restarted or rotated the credential) is bound again -// once. +// offline catalog, and after it every request is relayed. When the server +// certainly did not run the request, because it refused the credential or +// no server accepted the connection, the session binds again and sends it +// once more; any other failure is reported, so a tool that changes state is +// never sent twice. func (s *stdioSession) dispatch(ctx context.Context, payload []byte, raw *jsonrpc.RawRequest) ([]byte, error) { method := "" if raw != nil && !raw.Invalid { @@ -392,7 +429,7 @@ func (s *stdioSession) dispatch(ctx context.Context, payload []byte, raw *jsonrp if ctx.Err() != nil { return nil, ctx.Err() } - if attempt == 0 && (err != nil || status == http.StatusUnauthorized) { + if attempt == 0 && (status == http.StatusUnauthorized || errors.Is(err, syscall.ECONNREFUSED)) { s.dropRelay(relay) relay = nil continue @@ -470,8 +507,6 @@ func (s *stdioSession) dropRelay(relay *stdioRelay) { // send posts payload to the server as the relay's agent and returns the // HTTP status and body. func (r *stdioRelay) send(ctx context.Context, payload []byte, raw *jsonrpc.RawRequest) (status int, body []byte, err error) { - ctx, cancel := context.WithTimeout(ctx, stdioRequestTimeout) - defer cancel() req, err := newStdioMCPRequest(ctx, r.endpoint, payload, raw) if err != nil { return 0, nil, err diff --git a/cmd/surla/stdio_test.go b/cmd/surla/stdio_test.go index 4dbe7be9..7d88a370 100644 --- a/cmd/surla/stdio_test.go +++ b/cmd/surla/stdio_test.go @@ -5,10 +5,12 @@ import ( "context" "encoding/json" "io" + "net" "net/http" "net/http/httptest" "os" "path/filepath" + "strconv" "strings" "sync" "testing" @@ -17,6 +19,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + mcpruntime "goa.design/goa-ai/runtime/mcp" + "github.com/goadesign/surla/internal/abspath" "github.com/goadesign/surla/internal/controlplane" "github.com/goadesign/surla/internal/project" @@ -359,3 +363,146 @@ func (l *stdioLockedWriter) String() string { defer l.mu.Unlock() return l.w.String() } + +// startStdioProjectServer serves state's project on its own address with the +// real project server and control plane, as `surla serve` does, and +// publishes its management credential. +func startStdioProjectServer(t *testing.T, state *project.State) *project.Server { + t.Helper() + management, err := project.NewServer(state, func() {}, fixtureTeamDependencies(state)) + require.NoError(t, err) + cp, err := controlplane.New(fixtureProjectOptions(state, management)) + require.NoError(t, err) + t.Cleanup(func() { assert.NoError(t, cp.Close()) }) + api := httptest.NewUnstartedServer(management.Handler(controlplane.NewHTTPHandler(cp, management.Authenticate))) + require.NoError(t, api.Listener.Close()) + api.Listener, err = net.Listen("tcp", state.Address()) + require.NoError(t, err) + api.Start() + t.Cleanup(api.Close) + require.NoError(t, management.PublishRunning(os.Getpid(), "fixture")) + return management +} + +// stdioCall is a tools/call frame for name with the 2026-07-28 protocol +// version in _meta, as current clients send it. +func stdioCall(id int, name string) string { + return `{"jsonrpc":"2.0","id":` + strconv.Itoa(id) + `,"method":"tools/call","params":{"name":"` + name + + `","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"` + mcpruntime.ProtocolVersion + + `","io.modelcontextprotocol/clientCapabilities":{}}}}` +} + +func TestStdioBindsToARealProjectServer(t *testing.T) { + isolateServeWorkspace(t) + workspace, err := abspath.Eval(t.TempDir()) + require.NoError(t, err) + state, err := fixtureProjectState(workspace) + require.NoError(t, err) + management := startStdioProjectServer(t, state) + runtime := testProjectRuntime() + runtime.preflight = func(bool) error { return nil } + + // The guide binds from its own folder, not the process's. + cwd, err := os.Getwd() + require.NoError(t, err) + require.NotEqual(t, workspace, cwd) + guide, err := newStdioSession(runtime, workspace, "", io.Discard) + require.NoError(t, err) + reply := runStdioFrames(t, guide, stdioCall(1, "list_changes"))["1"] + require.Nil(t, reply.Error, string(reply.Result)) + first := guide.currentRelay() + require.NotNil(t, first) + + // A rotated credential is refused once, then the guide binds again. + var guideHandle string + reloaded, err := project.Discover(filepath.Dir(state.Dir), workspace) + require.NoError(t, err) + for handle, agent := range reloaded.Record.Agents { + if agent.Role == "guide" { + guideHandle = handle + } + } + require.NotEmpty(t, guideHandle) + require.NoError(t, os.WriteFile(state.AgentFile(guideHandle), []byte(strings.Repeat("ab", 32)), 0o600)) + reply = runStdioFrames(t, guide, stdioCall(2, "list_changes"))["2"] + require.Nil(t, reply.Error, string(reply.Result)) + assert.Equal(t, strings.Repeat("ab", 32), guide.currentRelay().credential) + + // Workers bind to the registered folder that holds them, in the project + // folder's own copy and in a child project folder's copy. + for _, builder := range []string{ + filepath.Join(workspace, ".surla-build", "app"), + filepath.Join(workspace, "shop", ".surla-build", "app"), + } { + require.NoError(t, os.MkdirAll(filepath.Join(builder, "sub"), 0o755)) + require.NoError(t, management.RegisterBuildRoles(t.Context(), controlplane.BuilderOnly{BuilderFolder: builder})) + worker, err := newStdioSession(runtime, filepath.Join(builder, "sub"), "", io.Discard) + require.NoError(t, err) + require.Equal(t, controlplane.CallerBuilder, worker.role) + reply := runStdioFrames(t, worker, stdioCall(3, "list_builder_assignments"))["3"] + require.Nil(t, reply.Error, string(reply.Result)) + } + + // A test writer's copy left from an earlier build has no registered agent + // on a builder-only build, and never becomes a guide. + leftover := filepath.Join(workspace, "shop", ".surla-tests", "eval") + require.NoError(t, os.MkdirAll(leftover, 0o755)) + worker, err := newStdioSession(runtime, leftover, "", io.Discard) + require.NoError(t, err) + reply = runStdioFrames(t, worker, stdioCall(4, "list_test_writer_assignments"))["4"] + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "this project has no registered test_writer") + assert.Nil(t, worker.currentRelay()) +} + +func TestStdioRetriesOnlyRequestsTheServerNeverRan(t *testing.T) { + var calls int + var mu sync.Mutex + dropped := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + mu.Lock() + calls++ + mu.Unlock() + // The server received the call, then the connection ends without a reply. + conn, _, err := w.(http.Hijacker).Hijack() + if assert.NoError(t, err) { + assert.NoError(t, conn.Close()) + } + })) + defer dropped.Close() + answering := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + _, err := io.WriteString(w, `{"jsonrpc":"2.0","id":1,"result":{}}`) + assert.NoError(t, err) + })) + defer answering.Close() + closed, err := net.Listen("tcp", "127.0.0.1:0") + require.NoError(t, err) + refused := "http://" + closed.Addr().String() + "/mcp" + require.NoError(t, closed.Close()) + + cases := []struct { + name string + endpoints []string + binds int + wantError bool + }{ + {name: "refused connection binds again", endpoints: []string{refused, answering.URL + "/mcp"}, binds: 2}, + {name: "dropped call is not sent again", endpoints: []string{dropped.URL + "/mcp", answering.URL + "/mcp"}, binds: 1, wantError: true}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + session, err := newStdioSession(testProjectRuntimeAt(t.TempDir()), t.TempDir(), "", io.Discard) + require.NoError(t, err) + binds := 0 + session.bind = func(context.Context, string) (*stdioRelay, error) { + binds++ + return &stdioRelay{endpoint: c.endpoints[binds-1], credential: "c", http: &http.Client{}}, nil + } + reply := runStdioFrames(t, session, `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_change","arguments":{}}}`)["1"] + assert.Equal(t, c.binds, binds) + assert.Equal(t, c.wantError, reply.Error != nil) + }) + } + mu.Lock() + defer mu.Unlock() + assert.Equal(t, 1, calls, "the dropped call reached the server once") +} diff --git a/cmd/surla/up.go b/cmd/surla/up.go index 5cb5b3e6..aacb67c3 100644 --- a/cmd/surla/up.go +++ b/cmd/surla/up.go @@ -69,9 +69,12 @@ func upWith( } // startChorus runs `chorus up` with no input and its output on out. Chorus -// starts its server in the background and returns once it answers. +// starts its server in the background and returns once it answers. The +// long-lived Chorus server gets this shell's environment without its model +// provider settings, which only the project server may hold. func startChorus(ctx context.Context, chorus string, out io.Writer) error { command := exec.CommandContext(ctx, chorus, "up") + command.Env = withoutProviderFamilies(os.Environ()) command.Stdin = nil command.Stdout = out command.Stderr = out diff --git a/cmd/surla/up_test.go b/cmd/surla/up_test.go index 988f773e..4aadc2bd 100644 --- a/cmd/surla/up_test.go +++ b/cmd/surla/up_test.go @@ -96,3 +96,14 @@ func TestUpNamesTheSkipWhenSetupFails(t *testing.T) { assert.Contains(t, err.Error(), "parse JSON in "+filepath.Join(home, ".cursor", "mcp.json")) assert.Contains(t, err.Error(), "set SURLA_NO_SETUP=1 to skip setup") } + +func TestUpStartsChorusWithoutProviderSettings(t *testing.T) { + t.Setenv("ANTHROPIC_API_KEY", "provider-sentinel") + t.Setenv("SURLA_UP_TEST_MARK", "kept") + chorus := filepath.Join(t.TempDir(), "chorus") + script := "#!/bin/sh\necho \"args=$* key=${ANTHROPIC_API_KEY:-unset} mark=${SURLA_UP_TEST_MARK:-unset}\"\n" + require.NoError(t, os.WriteFile(chorus, []byte(script), 0o755)) + var out bytes.Buffer + require.NoError(t, startChorus(t.Context(), chorus, &out)) + assert.Equal(t, "args=up key=unset mark=kept\n", out.String()) +}