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/setup.go b/cmd/surla/setup.go new file mode 100644 index 00000000..2a458d3d --- /dev/null +++ b/cmd/surla/setup.go @@ -0,0 +1,890 @@ +// 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 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{ + home: home, + executable: executable, + getenv: os.Getenv, + onPath: func(name string) bool { + _, err := exec.LookPath(name) + return err == nil + }, + goos: runtime.GOOS, + }, 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 +// ~/.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 := 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) + } + 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, 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. 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) { + return false, fmt.Errorf("read %s: %w", path, err) + } + if err == nil && bytes.Equal(installed, content) { + return false, nil + } + 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 new file mode 100644 index 00000000..08d6e50d --- /dev/null +++ b/cmd/surla/setup_test.go @@ -0,0 +1,455 @@ +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: "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"}, + {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, 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`) + 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) +} + +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/cmd/surla/stdio.go b/cmd/surla/stdio.go new file mode 100644 index 00000000..7eb08045 --- /dev/null +++ b/cmd/surla/stdio.go @@ -0,0 +1,829 @@ +// 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 + } +) + +// 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 + // 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, physical, 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 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, dir, terminal, client string, diagnostics io.Writer, +) (*stdioRelay, error) { + if err := runtime.preflight(false); err != nil { + return nil, err + } + root, err := runtime.operatorRoot(dir) + if err != nil { + return nil, err + } + state, err := project.Discover(root, dir) + 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: 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) { + 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 + } + inUse, err := controlplane.CardStoreInUse(state.CardsDir()) + if err != nil { + return nil, err + } + if !inUse { + return nil, errStdioServerStopped + } + identity, err := confirmProject(ctx, state, projectClient(state)) + if err != nil { + return nil, fmt.Errorf("%s: %w", projectHolder(state), err) + } + 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) { + continue + } + registered = append(registered, handle) + within, err := stdioWithin(agent.Folder, dir) + if err != nil { + return nil, err + } + if within { + holding = append(holding, handle) + } + } + 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(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) + } + if err != nil { + return nil, fmt.Errorf("read the %s credential: %w", role, err) + } + 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: the request's context ends it. +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. 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 { + 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 && (status == http.StatusUnauthorized || errors.Is(err, syscall.ECONNREFUSED)) { + 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) { + 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..7d88a370 --- /dev/null +++ b/cmd/surla/stdio_test.go @@ -0,0 +1,508 @@ +package main + +import ( + "bytes" + "context" + "encoding/json" + "io" + "net" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strconv" + "strings" + "sync" + "testing" + "time" + + "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" +) + +// 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() +} + +// 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 new file mode 100644 index 00000000..aacb67c3 --- /dev/null +++ b/cmd/surla/up.go @@ -0,0 +1,86 @@ +// 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. 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 + 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..4aadc2bd --- /dev/null +++ b/cmd/surla/up_test.go @@ -0,0 +1,109 @@ +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") +} + +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()) +} 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..a106965d --- /dev/null +++ b/skills/herdr/surla/main.js @@ -0,0 +1,294 @@ +// 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; +// 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 = { + 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 +// 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 ?? []) { + 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 = 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; +} + +// 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) { + // 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; + // 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); + }); + } + + // 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 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) { + const folder = this.shownFolder(); + this.trackedFolder = folder; + if (!folder || this.reading) { + cx.notify(); + return; + } + this.reading = true; + cx.spawn(async cx => { + let result; + try { + result = parseStatus(await exec("surla", ["status", "--json"], { cwd: folder, timeout: STATUS_TIMEOUT_MS })); + } catch (err) { + 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 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) message = (answer.stderr || answer.stdout || "surla failed.").trim(); + } catch (err) { + 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); + }); + } + + // button is a control that stops the press from dragging the window. + button(id, label, t, onClick) { + return div() + .id(id) + .flex_none() + .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 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().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); + 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().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 })))), + ); + } + } + // 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", 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") + .w_full() + .p(14) + .gap(10) + .bg(t.popover) + .rounded(8) + .child(header) + .child(body) + .child(footer); + } +} 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..1f6d3532 --- /dev/null +++ b/skills/herdr/surla/test_mod.mjs @@ -0,0 +1,355 @@ +// 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 })); + 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: '' }; + }, + 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: '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 }, + ]; + 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, 500]); + 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')); +}); + +// 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 new file mode 100644 index 00000000..7457978a --- /dev/null +++ b/skills/surla/SKILL.md @@ -0,0 +1,78 @@ +--- +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 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 + 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. 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. +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 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.