@gevezex/gdt 0.2.0 → 0.4.0

package/dist/init.js

@@ -0,0 +1,307 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { adapterFor, supportedAgents } from "./agents/index.js";
+import { CONFIG_PATH, DEFAULT_LANGUAGE, ROLES, userConfigPath } from "./config.js";
+import { herdrPreflight, which } from "./doctor.js";
+import { detectedChecks } from "./github.js";
+import { ROLE_RULES_DIR, roleRulesPath } from "./prompts.js";
+/** The proposal: one entry per supported agent, the usable terminal, detected checks and language. */
+export function proposal(root, env) {
+    const agents = supportedAgents().flatMap((agent) => {
+        const adapter = adapterFor(agent);
+        if (adapter === undefined)
+            return [];
+        return [
+            {
+                agent,
+                found: which(adapter.binary, env) !== null,
+                model_format: adapter.modelFormat,
+                example: adapter.modelExample,
+            },
+        ];
+    });
+    return {
+        agents,
+        terminal: herdrPreflight(env) === null ? "herdr" : "headless",
+        required_checks: detectedChecks(root, env),
+        language: DEFAULT_LANGUAGE,
+    };
+}
+/** Parses `<agent>/<model>` at the first `/`, the same way `gdt set-agent` does. */
+export function parseRoleSpec(spec) {
+    const slash = spec.indexOf("/");
+    const agent = slash === -1 ? spec : spec.slice(0, slash);
+    const model = slash === -1 ? "" : spec.slice(slash + 1);
+    const supported = supportedAgents();
+    if (!supported.includes(agent)) {
+        return { error: `Unsupported agent "${agent}"; supported agents: ${supported.join(", ")}` };
+    }
+    if (model.trim() === "")
+        return { error: `Missing model in "${spec}"; use <agent>/<model>` };
+    return { agent: agent, model };
+}
+/** The `.gdt/config.toml` text without roles; a key that keeps its schema default is not written. */
+export function serializeConfig(config) {
+    const lines = [];
+    if (config.language !== DEFAULT_LANGUAGE)
+        lines.push(`language = ${JSON.stringify(config.language)}`, "");
+    lines.push("[workflow]", `required_checks = [${config.requiredChecks.map((name) => JSON.stringify(name)).join(", ")}]`);
+    if (config.allowNoRequiredChecks)
+        lines.push("allow_no_required_checks = true");
+    if (config.terminal !== "herdr")
+        lines.push(`terminal = ${JSON.stringify(config.terminal)}`);
+    lines.push("");
+    return lines.join("\n");
+}
+function roleTable(role, spec) {
+    return `[roles.${role}]\nagent = ${JSON.stringify(spec.agent)}\nmodel = ${JSON.stringify(spec.model)}\n`;
+}
+/** The user config text for `roles`, used when the file does not exist yet. */
+export function serializeUserConfig(roles) {
+    return ROLES.map((role) => roleTable(role, roles[role])).join("\n");
+}
+/** Strips the surrounding quotes of one TOML key segment. */
+function unquoteKey(segment) {
+    if (segment.length >= 2 && segment.startsWith('"') && segment.endsWith('"')) {
+        try {
+            const value = JSON.parse(segment);
+            if (typeof value === "string")
+                return value;
+        }
+        catch {
+            // Not JSON-compatible; fall back to a plain strip.
+        }
+        return segment.slice(1, -1);
+    }
+    if (segment.length >= 2 && segment.startsWith("'") && segment.endsWith("'"))
+        return segment.slice(1, -1);
+    return segment;
+}
+/** Splits a TOML dotted key into its segments, honoring quoted segments (e.g. `roles."a.b"`). */
+function keySegments(key) {
+    const segments = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < key.length; i += 1) {
+        const ch = key[i] ?? "";
+        if (quote === '"') {
+            current += ch;
+            if (ch === "\\") {
+                current += key[i + 1] ?? "";
+                i += 1;
+            }
+            else if (ch === '"')
+                quote = null;
+            continue;
+        }
+        if (quote === "'") {
+            current += ch;
+            if (ch === "'")
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ".") {
+            segments.push(unquoteKey(current.trim()));
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    segments.push(unquoteKey(current.trim()));
+    return segments;
+}
+const HEADER_RE = /^\s*\[\[?\s*(.*?)\s*\]\]?\s*(?:#.*)?$/;
+/** The dotted path of a `[table]` / `[[array]]` header, or null when the line is not a header. */
+function headerSegments(line) {
+    const match = HEADER_RE.exec(line);
+    return match === null ? null : keySegments(match[1] ?? "");
+}
+/** Splits `key = value` at the first `=` outside quoted key segments. */
+function splitAssignment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i] ?? "";
+        if (quote === '"') {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === '"')
+                quote = null;
+            continue;
+        }
+        if (quote === "'") {
+            if (ch === "'")
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "=")
+            return { key: line.slice(0, i), value: line.slice(i + 1) };
+    }
+    return null;
+}
+/** Tracks one TOML value across lines so multi-line values stay attached to their assignment. */
+class ValueScan {
+    depth = 0;
+    mode = "normal";
+    /** Feeds one line; returns true once the value is complete at the end of that line. */
+    feed(line) {
+        for (let i = 0; i < line.length; i += 1) {
+            const ch = line[i] ?? "";
+            switch (this.mode) {
+                case "normal":
+                    if (ch === "#")
+                        i = line.length;
+                    else if (ch === '"') {
+                        if (line.startsWith('"""', i)) {
+                            this.mode = "basic-multi";
+                            i += 2;
+                        }
+                        else
+                            this.mode = "basic";
+                    }
+                    else if (ch === "'") {
+                        if (line.startsWith("'''", i)) {
+                            this.mode = "literal-multi";
+                            i += 2;
+                        }
+                        else
+                            this.mode = "literal";
+                    }
+                    else if (ch === "[" || ch === "{")
+                        this.depth += 1;
+                    else if (ch === "]" || ch === "}")
+                        this.depth -= 1;
+                    break;
+                case "basic":
+                    if (ch === "\\")
+                        i += 1;
+                    else if (ch === '"')
+                        this.mode = "normal";
+                    break;
+                case "literal":
+                    if (ch === "'")
+                        this.mode = "normal";
+                    break;
+                case "basic-multi":
+                    if (line.startsWith('"""', i)) {
+                        this.mode = "normal";
+                        i += 2;
+                    }
+                    else if (ch === "\\")
+                        i += 1;
+                    break;
+                case "literal-multi":
+                    if (line.startsWith("'''", i)) {
+                        this.mode = "normal";
+                        i += 2;
+                    }
+                    break;
+            }
+        }
+        return this.mode === "normal" && this.depth === 0;
+    }
+}
+/**
+ * AC-5: replaces the `roles` key of `existing`, keeping every other line (comments, other keys and
+ * tables) byte-for-byte. Roles are removed whatever valid TOML form they were written in — role
+ * tables, a `[roles]` table with inline entries, a top-level inline `roles = { ... }`, or dotted
+ * keys — so a rewrite never leaves a duplicate definition behind. The new tables are appended.
+ */
+export function upsertRoles(existing, roles) {
+    const kept = [];
+    let table = null;
+    let pending = null;
+    for (const line of existing.split("\n")) {
+        if (pending !== null) {
+            const complete = pending.scan.feed(line);
+            if (!pending.drop)
+                kept.push(line);
+            if (complete)
+                pending = null;
+            continue;
+        }
+        const trimmed = line.trim();
+        const inRoleRegion = table !== null && table[0] === "roles";
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            if (!inRoleRegion)
+                kept.push(line);
+            continue;
+        }
+        const header = headerSegments(line);
+        if (header !== null) {
+            table = header;
+            if (header[0] !== "roles")
+                kept.push(line);
+            continue;
+        }
+        const assignment = splitAssignment(line);
+        if (assignment === null) {
+            if (!inRoleRegion)
+                kept.push(line);
+            continue;
+        }
+        const drop = inRoleRegion || (table === null && keySegments(assignment.key)[0] === "roles");
+        if (!drop)
+            kept.push(line);
+        const scan = new ValueScan();
+        if (!scan.feed(assignment.value))
+            pending = { scan, drop };
+    }
+    while (kept.length > 0 && (kept[kept.length - 1] ?? "").trim() === "")
+        kept.pop();
+    const prefix = kept.length > 0 ? `${kept.join("\n")}\n\n` : "";
+    const blocks = ROLES.map((role) => roleTable(role, roles[role]).trimEnd()).join("\n\n");
+    return `${prefix}${blocks}\n`;
+}
+/** Writes the roles to the user config, creating its directory; returns an error message or null. */
+export function writeUserConfig(env, roles) {
+    const path = userConfigPath(env);
+    try {
+        const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, existing === null ? serializeUserConfig(roles) : upsertRoles(existing, roles));
+        return null;
+    }
+    catch (err) {
+        return `Cannot write ${path}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/** Writes the config, creating `.gdt/` when needed; returns an error message, or null on success. */
+export function writeConfig(root, text) {
+    try {
+        const path = join(root, CONFIG_PATH);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+        return null;
+    }
+    catch (err) {
+        return `Cannot write ${CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/**
+ * AC-4: creates each missing `.gdt/roles/<role>.md` as an empty file and returns its
+ * repository-relative path. An existing file is never touched, not even with `--force`.
+ */
+export function createRoleRulesFiles(root) {
+    const created = [];
+    for (const role of ROLES) {
+        const path = roleRulesPath(root, role);
+        mkdirSync(dirname(path), { recursive: true });
+        try {
+            writeFileSync(path, "", { flag: "wx" });
+            created.push(`${ROLE_RULES_DIR}/${role}.md`);
+        }
+        catch (err) {
+            // Exists already: leave it byte-for-byte unchanged.
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+    }
+    return created;
+}

package/dist/prompts.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { z } from "zod";
 import { loadLocale, SECTION_KEYS } from "./locale.js";
 import { marker, schemas } from "./protocol.js";
@@ -7,9 +7,26 @@ export const ROLE_FILES = ["developer", "tester", "reviewer", "issue-writer"];
 /** The record kind each workflow role writes. */
 export const RECORD_OF = { developer: "handoff", tester: "test", reviewer: "review" };
 const ROLES_DIR = new URL("../roles/", import.meta.url);
+/** The directory, relative to a target repository's root, holding the per-role supplementary rules. */
+export const ROLE_RULES_DIR = ".gdt/roles";
 export function roleFile(name) {
     return readFileSync(new URL(`${name}.md`, ROLES_DIR), "utf8");
 }
+/** The absolute path of a workflow role's supplementary rules file in `root`. */
+export function roleRulesPath(root, role) {
+    return join(root, ROLE_RULES_DIR, `${role}.md`);
+}
+/**
+ * The role's supplementary rules, trimmed, or `null` when the file is missing or empty (whitespace
+ * only). Read on every call, so a change reaches the role's next turn without a restart (AC-3).
+ */
+export function roleRules(root, role) {
+    const path = roleRulesPath(root, role);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, "utf8").trimEnd();
+    return text.trim() === "" ? null : text;
+}
 /**
  * Trusted directives for `role` posted after that role's previous dispatch, i.e. with a comment id
  * above `afterCommentId` (the highest comment id seen at that dispatch; 0 before the first one).
@@ -76,5 +93,9 @@ export function buildPrompt(role, dispatch, project) {
         if (existsSync(path))
             parts.push(["## Project rules", "", readFileSync(path, "utf8").trimEnd()].join("\n"));
     }
+    // AC-1/AC-2: a role's own supplementary rules, after the global project rules; empty adds nothing.
+    const rules = roleRules(project.root, role);
+    if (rules !== null)
+        parts.push(["## Role rules", "", rules].join("\n"));
     return `${parts.join("\n\n")}\n`;
 }

package/dist/steering.js

@@ -3,7 +3,8 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { adapterFor, supportedAgents } from "./agents/index.js";
-import { ROLES } from "./config.js";
+import { backendFor } from "./backends/index.js";
+import { loadConfig, ROLES } from "./config.js";
 import { findRepository, which } from "./doctor.js";
 import { comments, issueSnapshot, postIssueComment, postPullRequestComment, repository } from "./github.js";
 import { formatRecord, parseRecords } from "./protocol.js";
@@ -129,6 +130,17 @@ export function setAgent(issue, role, spec, cwd, env) {
     if (readState(p) === null)
         return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
     writeJsonAtomic(p.overrides, { ...readOverrides(p), [checked]: { agent: agent, model } });
+    // AC-1: the agents overview must name the role's new agent. Best effort: the pane may not exist
+    // yet, the terminal may be headless, or herdr may be missing; the override still applies.
+    try {
+        const { report } = loadConfig(p.root, env);
+        if (report.valid && report.workflow.terminal === "herdr") {
+            backendFor(report, p.root, issue, env, p).setDisplayAgent(checked, `${checked} · ${agent}`);
+        }
+    }
+    catch {
+        // The override is written; the label is refreshed on the next `gdt start`.
+    }
     return ok(`${checked} for #${issue} now uses ${agent} with model ${model} from its next turn.\n`);
 }
 /** `gdt install-skill`: copies `skill/SKILL.md` into every detected harness; idempotent. */

package/dist/supervisor.js

@@ -107,6 +107,18 @@ class Supervisor {
         this.backend.setTitle(role, this.roleTitle(role, state));
         this.reportState(role, ROLE_PANE_STATE[state]);
     }
+    /** AC-1: sets the display-only agent label, for example `developer · opencode` or `gdt · supervisor`. */
+    setDisplay(name, label) {
+        try {
+            this.backend.setDisplayAgent(name, label);
+        }
+        catch (err) {
+            if (this.reportWarned)
+                return;
+            this.reportWarned = true;
+            log(`warning: herdr display label failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /** Records a status; notifies once when entering a notifying status. */
     setStatus(status, reason, extra = {}) {
         if (this.state.status !== status || this.state.reason !== reason)
@@ -128,10 +140,13 @@ class Supervisor {
     }
     startWorkers() {
         this.backend.ensureWorkspace();
+        // AC-1: the agents overview shows the role next to the agent name, once per `gdt start`.
+        this.setDisplay("supervisor", "gdt · supervisor");
         this.backend.setTitle("supervisor", "supervisor · starting");
         this.reportState("supervisor", supervisorAgentState(this.state.status));
         for (const role of ROLES) {
             this.setRoleState(role, "WAITING");
+            this.setDisplay(role, `${role} · ${this.agents[role]}`);
             if (this.backend.alive(this.state.pids.workers[role] ?? -1))
                 continue;
             this.state.pids.workers[role] = this.backend.spawnPane(role, [process.execPath, cliPath(), "_worker", String(this.issue), role]);

package/dist/workflow.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { relative } from "node:path";
 import { headless } from "./backends/headless.js";
 import { backendFor } from "./backends/index.js";
-import { loadConfig, ROLES } from "./config.js";
+import { loadConfig, ROLES, userConfigPath } from "./config.js";
 import { validateContract } from "./contract.js";
 import { findRepository, herdrPreflight, unsupportedAgentFindings } from "./doctor.js";
 import { changedFiles } from "./git.js";
@@ -55,10 +55,13 @@ export function start(issue, cwd, env) {
     const root = findRepository(cwd);
     if (root === null)
         return fail(`${cwd} is not inside a Git repository. Run gdt from a checkout of the target repository.\n`);
-    const { report } = loadConfig(root, env);
-    if (!report.valid)
-        return fail('.gdt/config.toml is invalid. Run "gdt doctor" for details.\n');
-    const unsupported = unsupportedAgentFindings(report.roles);
+    const { report, findings } = loadConfig(root, env);
+    if (!report.valid) {
+        // AC-2: `gdt start` refuses with the same config errors as `gdt doctor`.
+        const errors = findings.filter((finding) => finding.level === "error").map((finding) => finding.message);
+        return fail(`${errors.join("\n")}\nRun "gdt doctor" for details.\n`);
+    }
+    const unsupported = unsupportedAgentFindings(report.roles, userConfigPath(env));
     if (unsupported.length > 0)
         return fail(`${unsupported.map((f) => f.message).join("\n")}\n`);
     if (report.workflow.terminal === "herdr") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gevezex/gdt",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.",
   "keywords": [
     "github",

package/skill/SKILL.md

@@ -3,6 +3,20 @@
 You are the operator: the user talks to you in their own language, and you run
 gdt for them. They should never have to memorise a gdt command.
 
+## First-time setup
+
+- With no `.gdt/config.toml`, run `gdt init --json`. It reports the supported
+  agents, which are on PATH, the terminal and the detected CI checks.
+- Present that proposal to the user and ask which agent and model each role
+  (developer, tester, reviewer) uses. Do not pick models for them.
+- Run `gdt init` with their choices, for example
+  `gdt init --developer opencode/deepseek/deepseek-v4-flash --tester claude/claude-sonnet-5 --reviewer codex/gpt-5.6-luna`.
+  It writes the roles to the user config (`~/.config/gdt/config.toml`, or
+  `$XDG_CONFIG_HOME/gdt/config.toml`) and the project settings to
+  `.gdt/config.toml`, then runs `gdt doctor` and installs this skill.
+- When the user config already defines all three roles, `gdt init` without role
+  options reuses them and only writes `.gdt/config.toml`.
+
 ## Start
 
 - `gdt start <issue>` returns immediately; the supervisor keeps running on its own.