@gevezex/gdt 0.2.0

package/dist/locale.js

@@ -0,0 +1,44 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+export const SECTION_KEYS = [
+    "plain_language",
+    "goal",
+    "context",
+    "definitions",
+    "acceptance_criteria",
+    "non_functional",
+    "out_of_scope",
+    "assumptions",
+    "open_questions",
+    "changelog",
+    "readiness",
+];
+const text = z.string().trim().min(1);
+export const localeSchema = z.strictObject({
+    /** English name of the language, used in role prompts. */
+    name: text,
+    sections: z.strictObject(Object.fromEntries(SECTION_KEYS.map((key) => [key, text]))),
+    ac_fields: z.strictObject({ given: text, when: text, then: text, example: text }),
+    markers: z.strictObject({ none: text }),
+    vague_phrases: z.array(text),
+});
+const LOCALES_DIR = new URL("../locales/", import.meta.url);
+/** Loads `locales/<language>.toml` shipped with gdt. Throws with a recovery hint when it is missing or invalid. */
+export function loadLocale(language) {
+    const languages = shippedLanguages();
+    if (!languages.includes(language)) {
+        throw new Error(`No locale for language "${language}"; set language in .gdt/config.toml to one of ${languages.join(", ")}`);
+    }
+    const parsed = localeSchema.safeParse(parseToml(readFileSync(new URL(`${language}.toml`, LOCALES_DIR), "utf8")));
+    if (!parsed.success) {
+        throw new Error(`locales/${language}.toml is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+export function shippedLanguages() {
+    return readdirSync(LOCALES_DIR)
+        .filter((name) => name.endsWith(".toml"))
+        .map((name) => name.slice(0, -".toml".length))
+        .sort();
+}

package/dist/notify.js

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+import { which } from "./doctor.js";
+function appleScriptString(text) {
+    return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+const NOTIFIERS = [
+    { name: "terminal-notifier", args: (title, message) => ["-title", title, "-message", message] },
+    {
+        name: "osascript",
+        args: (title, message) => ["-e", `display notification ${appleScriptString(message)} with title ${appleScriptString(title)}`],
+    },
+    { name: "notify-send", args: (title, message) => [title, message] },
+];
+/**
+ * Sends one notification through the first notifier that is on PATH and succeeds; otherwise writes one
+ * line with `log`. Returns the notifier used, or "log".
+ */
+export function notify(title, message, env, log) {
+    for (const notifier of NOTIFIERS) {
+        const bin = which(notifier.name, env);
+        if (bin === null)
+            continue;
+        const result = spawnSync(bin, notifier.args(title, message), { env, stdio: "ignore", timeout: 10_000 });
+        if (result.status === 0)
+            return notifier.name;
+    }
+    log(`notification: ${title}: ${message}`);
+    return "log";
+}

package/dist/prompts.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { loadLocale, SECTION_KEYS } from "./locale.js";
+import { marker, schemas } from "./protocol.js";
+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);
+export function roleFile(name) {
+    return readFileSync(new URL(`${name}.md`, ROLES_DIR), "utf8");
+}
+/**
+ * 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).
+ */
+export function pendingDirectives(records, trustedAuthors, role, afterCommentId) {
+    return records
+        .filter((r) => r.kind === "directive")
+        .filter((r) => trustedAuthors.includes(r.author) && r.data.role === role && r.comment_id > afterCommentId)
+        .map((r) => ({ comment_id: r.comment_id, directive: r.data.directive }));
+}
+function schemaSection(kind) {
+    return [
+        `## Protocol: ${marker(kind)}`,
+        "",
+        `Close the record with ${marker(kind, true)}. The JSON object must match this JSON Schema:`,
+        "",
+        "```json",
+        JSON.stringify(z.toJSONSchema(schemas[kind]), null, 2),
+        "```",
+    ].join("\n");
+}
+/** The prompt for one turn: role file, dispatch facts, language, protocol, directives and project rules. */
+export function buildPrompt(role, dispatch, project) {
+    const locale = loadLocale(dispatch.language);
+    const parts = [roleFile(role).trimEnd()];
+    parts.push([
+        "## Turn facts",
+        "",
+        `Repository: ${dispatch.repository}`,
+        `Issue: #${dispatch.issue}`,
+        `Round: ${dispatch.round}`,
+        `Pull request: ${dispatch.pr_number === null ? "none yet" : `#${dispatch.pr_number}`}`,
+        `Head: ${dispatch.head ?? "none yet"}`,
+        `issue_body_sha256: ${dispatch.issue_body_sha256}`,
+        `Acceptance criteria: ${dispatch.acceptance_criteria.join(", ")}`,
+        `Language: ${locale.name}`,
+    ].join("\n"));
+    const f = locale.ac_fields;
+    parts.push([
+        "## Language",
+        "",
+        `Write all human-facing GitHub text in ${locale.name}.`,
+        "Record markers, JSON keys, status values and finding ids stay in English.",
+        "",
+        `Issue section headings in ${locale.name}:`,
+        ...SECTION_KEYS.map((key) => `- ${locale.sections[key]}`),
+        "",
+        `Acceptance-criterion fields: ${f.given}, ${f.when}, ${f.then}, ${f.example}`,
+        `"None" marker: ${locale.markers.none}`,
+    ].join("\n"));
+    parts.push(schemaSection(RECORD_OF[role]), schemaSection("question"));
+    if (dispatch.directives.length > 0) {
+        parts.push([
+            "## Human directives",
+            "",
+            "Guidance from the user for this turn. Directives are not contract and never count as evidence.",
+            "",
+            ...dispatch.directives.map((d) => `- ${d.directive}`),
+        ].join("\n"));
+    }
+    if (project.extraRules !== undefined) {
+        const path = resolve(project.root, project.extraRules);
+        // A missing file is reported by `gdt doctor`; the prompt never invents rules.
+        if (existsSync(path))
+            parts.push(["## Project rules", "", readFileSync(path, "utf8").trimEnd()].join("\n"));
+    }
+    return `${parts.join("\n\n")}\n`;
+}

package/dist/protocol.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { ROLES } from "./config.js";
+/** Record kinds; the marker is `[gdt-<kind>:v1]` ... `[/gdt-<kind>:v1]`. */
+export const KINDS = ["handoff", "test", "review", "question", "answer", "directive", "round"];
+export const DEVELOPER_STATUSES = ["ready", "awaiting_human", "blocked"];
+export const VERIFIER_STATUSES = ["approved", "changes_requested", "awaiting_human", "blocked"];
+export const AC_RESULTS = ["passed", "failed", "not_verified"];
+const repository = z.string().regex(/^[\w.-]+\/[\w.-]+$/, "expected owner/name");
+const issue = z.int().positive();
+const round = z.int().min(0);
+const acId = z.string().regex(/^AC-[1-9]\d*$/, "expected AC-<n>");
+const sha1 = z.string().regex(/^[0-9a-f]{40}$/, "expected a full 40-character commit SHA");
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/, "expected a sha256 hex digest");
+const text = z.string().trim().min(1);
+const core = {
+    repository,
+    issue,
+    round,
+    pr_number: z.int().positive().nullable(),
+    issue_body_sha256: sha256,
+    acceptance_criteria: z.array(acId),
+};
+const verifier = (role, findingPrefix) => z.strictObject({
+    role: z.literal(role),
+    status: z.enum(VERIFIER_STATUSES),
+    ...core,
+    head: sha1,
+    ac_results: z.array(z.strictObject({ ac: acId, result: z.enum(AC_RESULTS), evidence: text })),
+    findings: z.array(z.strictObject({
+        id: z.string().regex(new RegExp(`^${findingPrefix}-[1-9]\\d*$`), `expected ${findingPrefix}-<n>`),
+        blocking: z.boolean(),
+        summary: text,
+    })),
+});
+export const schemas = {
+    handoff: z.strictObject({
+        role: z.literal("developer"),
+        status: z.enum(DEVELOPER_STATUSES),
+        ...core,
+        ac_traceability: z.array(z.strictObject({ ac: acId, files: z.array(text), tests: z.array(text) })),
+        assumptions: z.array(text),
+        deviations: z.array(text),
+    }),
+    test: verifier("tester", "T"),
+    review: verifier("reviewer", "R"),
+    question: z.strictObject({
+        role: z.enum(ROLES),
+        ...core,
+        question_id: z.string().regex(/^Q[1-9]\d*$/, "expected Q<n>"),
+        resume_role: z.enum(ROLES),
+        question: text,
+    }),
+    answer: z.strictObject({
+        repository,
+        issue,
+        question_id: z.string().regex(/^Q[1-9]\d*$/, "expected Q<n>"),
+        answer: text,
+    }),
+    directive: z.strictObject({ repository, issue, role: z.enum(ROLES), directive: text }),
+    /** Grants the correction round `round` beyond `max_correction_rounds`. */
+    round: z.strictObject({ repository, issue, round: z.int().min(1) }),
+};
+export function marker(kind, closing = false) {
+    return `[${closing ? "/" : ""}gdt-${kind}:v1]`;
+}
+/** The comment body carrying one record: opening marker, JSON object and closing marker. */
+export function formatRecord(kind, data) {
+    return `${marker(kind)}\n${JSON.stringify(data, null, 2)}\n${marker(kind, true)}\n`;
+}
+const BLOCK = new RegExp(`\\[gdt-(${KINDS.join("|")}):v1\\]([\\s\\S]*?)\\[/gdt-\\1:v1\\]`, "g");
+/** Tolerates a Markdown code fence around the JSON object. */
+function unfence(content) {
+    const fenced = /^\s*```[\w-]*\r?\n([\s\S]*?)\r?\n\s*```\s*$/.exec(content);
+    return fenced?.[1] ?? content;
+}
+function schemaReason(error) {
+    return error.issues
+        .flatMap((issue) => issue.code === "unrecognized_keys"
+        ? issue.keys.map((key) => `unrecognized key "${[...issue.path, key].join(".")}"`)
+        : [`${issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue.message}`])
+        .map((reason) => `schema: ${reason}`)
+        .join("; ");
+}
+/** Extracts every record from `comments`. Invalid blocks are excluded and listed in `diagnostics`. */
+export function parseRecords(comments) {
+    const records = [];
+    const diagnostics = [];
+    for (const comment of comments) {
+        for (const match of comment.body.matchAll(BLOCK)) {
+            const kind = match[1];
+            let json;
+            try {
+                json = JSON.parse(unfence(match[2] ?? ""));
+            }
+            catch {
+                diagnostics.push({ comment_id: comment.id, kind, reason: "invalid JSON" });
+                continue;
+            }
+            const parsed = schemas[kind].safeParse(json);
+            if (!parsed.success) {
+                diagnostics.push({ comment_id: comment.id, kind, reason: schemaReason(parsed.error) });
+                continue;
+            }
+            records.push({
+                kind,
+                data: parsed.data,
+                author: comment.author,
+                created_at: comment.created_at,
+                comment_id: comment.id,
+            });
+        }
+    }
+    return { records, diagnostics };
+}

package/dist/state.js

@@ -0,0 +1,113 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const STATUSES = [
+    "starting",
+    "running",
+    "paused",
+    "awaiting_human",
+    "waiting_for_checks",
+    "ready_to_merge",
+    "blocked",
+    "contract_changed",
+    "failed",
+    "stopped",
+];
+/** Statuses that notify the user when the workflow enters them. */
+export const NOTIFY_STATUSES = ["awaiting_human", "blocked", "failed", "ready_to_merge"];
+/** The repository's common Git directory, so worktrees share one state. */
+function gitDir(root, env) {
+    const result = spawnSync("git", ["rev-parse", "--git-common-dir"], { cwd: root, env, encoding: "utf8" });
+    if (result.status === 0 && result.stdout.trim() !== "")
+        return resolve(root, result.stdout.trim());
+    return join(root, ".git");
+}
+export function paths(root, issue, env) {
+    const dir = join(gitDir(root, env), "gdt", `issue-${issue}`);
+    return {
+        root,
+        dir,
+        state: join(dir, "state.json"),
+        lock: join(dir, "supervisor.lock"),
+        pause: join(dir, "paused"),
+        stopping: join(dir, "stopping"),
+        overrides: join(dir, "overrides.json"),
+        logs: join(dir, "logs"),
+        panes: join(dir, "panes.json"),
+        pids: join(dir, "pids"),
+        dispatch: (role) => join(dir, "dispatch", `${role}.json`),
+        started: (key) => join(dir, "runs", `${key}.started`),
+        result: (key) => join(dir, "runs", `${key}.result.json`),
+        prompt: (key) => join(dir, "runs", `${key}.prompt.md`),
+    };
+}
+/** A log line timestamp in local time, `YYYY-MM-DD hh:mm:ss`. */
+export function logTimestamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+        `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`);
+}
+/** Writes via a temporary file and rename, so readers never see a partial file. */
+export function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+export function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function readState(p) {
+    return readJson(p.state);
+}
+/** The per-issue agent/model overrides, empty when none are set. */
+export function readOverrides(p) {
+    return readJson(p.overrides) ?? {};
+}
+export function writeState(p, state, now = new Date()) {
+    state.updated_at = now.toISOString();
+    writeJsonAtomic(p.state, state);
+}
+export function alive(pid) {
+    if (pid === null || pid === undefined || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** The pid in the lock file if that process is alive. */
+export function lockHolder(p) {
+    if (!existsSync(p.lock))
+        return null;
+    const pid = Number(readFileSync(p.lock, "utf8").trim());
+    return Number.isInteger(pid) && alive(pid) ? pid : null;
+}
+/** Takes the per-issue supervisor lock; returns the holder's pid when another live process has it. */
+export function acquireLock(p) {
+    mkdirSync(p.dir, { recursive: true });
+    try {
+        writeFileSync(p.lock, `${process.pid}\n`, { flag: "wx" });
+        return null;
+    }
+    catch {
+        // The lock file exists: honour it only while its process is alive.
+    }
+    const holder = lockHolder(p);
+    if (holder !== null && holder !== process.pid)
+        return holder;
+    const tmp = `${p.lock}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${process.pid}\n`);
+    renameSync(tmp, p.lock);
+    return null;
+}

package/dist/steering.js

@@ -0,0 +1,165 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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 { findRepository, which } from "./doctor.js";
+import { comments, issueSnapshot, postIssueComment, postPullRequestComment, repository } from "./github.js";
+import { formatRecord, parseRecords } from "./protocol.js";
+import { lockHolder, paths, readOverrides, readState, writeJsonAtomic } from "./state.js";
+import { describe, fail, ok } from "./workflow.js";
+function rootOf(cwd) {
+    return findRepository(cwd) ?? cwd;
+}
+function ghFailure(err) {
+    return fail(`${err instanceof Error ? err.message : String(err)}\n`);
+}
+/** The role, or a failure result naming the allowed roles. */
+function checkRole(role) {
+    return ROLES.includes(role) ? role : fail(`Unknown role "${role}"; use developer, tester or reviewer\n`);
+}
+/** `gdt answer <issue> <question-id> <text>`: posts one `human-answer` for an open question. */
+export function answer(issue, questionId, text, cwd, env) {
+    const answerText = text.trim();
+    if (answerText === "")
+        return fail(`The answer for ${questionId} is empty.\n`);
+    const root = rootOf(cwd);
+    try {
+        const repo = repository(root, env);
+        const thread = comments(repo, issue, root, env);
+        for (const pr of issueSnapshot(issue, root, env).pullRequests)
+            thread.push(...comments(repo, pr, root, env));
+        const { records } = parseRecords(thread);
+        const questions = records.filter((r) => r.kind === "question" && r.data.issue === issue && r.data.question_id === questionId);
+        const answers = records.filter((r) => r.kind === "answer" && r.data.issue === issue && r.data.question_id === questionId);
+        const open = questions.filter((q) => !answers.some((a) => Date.parse(a.created_at) >= Date.parse(q.created_at)));
+        if (open.length === 0)
+            return fail(`No open question ${questionId} on #${issue}\n`);
+        postIssueComment(issue, formatRecord("answer", { repository: repo, issue, question_id: questionId, answer: answerText }), root, env);
+    }
+    catch (err) {
+        return ghFailure(err);
+    }
+    return ok(`Answered ${questionId} on #${issue}.\n`);
+}
+/** `gdt steer <issue> --role <role> <text>`: posts one `human-directive` on the workflow channel. */
+export function steer(issue, role, text, cwd, env) {
+    const checked = checkRole(role);
+    if (typeof checked !== "string")
+        return checked;
+    const directive = text.trim();
+    if (directive === "")
+        return fail(`The directive for ${checked} is empty.\n`);
+    const root = rootOf(cwd);
+    try {
+        const repo = repository(root, env);
+        const pullRequests = issueSnapshot(issue, root, env).pullRequests;
+        if (pullRequests.length > 1) {
+            return fail(`more than one open pull request closes #${issue}: ${pullRequests.map((n) => `#${n}`).join(", ")}\n`);
+        }
+        const body = formatRecord("directive", { repository: repo, issue, role: checked, directive });
+        const pr = pullRequests[0];
+        if (pr === undefined)
+            postIssueComment(issue, body, root, env);
+        else
+            postPullRequestComment(pr, body, root, env);
+        return ok(`Posted a directive for ${checked} on ${pr === undefined ? `issue #${issue}` : `pull request #${pr}`}.\n`);
+    }
+    catch (err) {
+        return ghFailure(err);
+    }
+}
+/** `gdt pause <issue>`: no turn is dispatched until `gdt resume`. */
+export function pause(issue, cwd, env) {
+    const p = paths(rootOf(cwd), issue, env);
+    if (readState(p) === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    mkdirSync(dirname(p.pause), { recursive: true });
+    writeFileSync(p.pause, `${new Date().toISOString()}\n`);
+    return ok(`Paused #${issue}. Next: gdt resume ${issue}\n`);
+}
+/** `gdt resume <issue>`: clears the pause; the next decision is dispatched again. */
+export function resume(issue, cwd, env) {
+    const root = rootOf(cwd);
+    const p = paths(root, issue, env);
+    const state = readState(p);
+    if (state === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    rmSync(p.pause, { force: true });
+    // The supervisor corrects the status on its next poll; report the resumed workflow now.
+    const resumed = state.status === "paused" ? { ...state, status: "starting", reason: "" } : state;
+    return ok(`Resumed #${issue}. Next: ${describe(resumed, lockHolder(p) !== null).next}\n`);
+}
+/** `gdt allow-round <issue>`: grants one extra correction round when the budget is exhausted. */
+export function allowRound(issue, cwd, env) {
+    const root = rootOf(cwd);
+    const p = paths(root, issue, env);
+    const state = readState(p);
+    if (state === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    if (state.status !== "blocked" || !state.reason.startsWith("round budget exhausted")) {
+        return fail("allow-round is only valid when the round budget is exhausted\n");
+    }
+    try {
+        const repo = repository(root, env);
+        const round = (state.round ?? 0) + 1;
+        postIssueComment(issue, formatRecord("round", { repository: repo, issue, round }), root, env);
+        return ok(`Granted round ${round} for #${issue}. Next: wait\n`);
+    }
+    catch (err) {
+        return ghFailure(err);
+    }
+}
+/** `gdt set-agent <issue> <role> <agent>/<model>`: overrides the config for that role from its next turn. */
+export function setAgent(issue, role, spec, cwd, env) {
+    const checked = checkRole(role);
+    if (typeof checked !== "string")
+        return checked;
+    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 fail(`Unsupported agent "${agent}"; supported agents: ${supported.join(", ")}\n`);
+    }
+    if (model.trim() === "")
+        return fail(`Missing model in "${spec}"; use <agent>/<model>\n`);
+    const p = paths(rootOf(cwd), issue, 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 } });
+    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. */
+export function installSkill(env) {
+    const source = fileURLToPath(new URL("../skill/SKILL.md", import.meta.url));
+    let text;
+    try {
+        text = readFileSync(source, "utf8");
+    }
+    catch (err) {
+        return fail(`Cannot read ${source}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    const home = env.HOME ?? homedir();
+    const lines = [];
+    for (const agent of supportedAgents()) {
+        const adapter = adapterFor(agent);
+        if (adapter === undefined)
+            continue;
+        if (which(adapter.binary, env) === null) {
+            lines.push(`skipped: ${agent} not found`);
+            continue;
+        }
+        const dir = adapter.skillDir().replace(/^~/, home);
+        const destination = join(dir, "SKILL.md");
+        if (existsSync(destination) && readFileSync(destination, "utf8") === text) {
+            lines.push(`up to date  ${destination}`);
+            continue;
+        }
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(destination, text);
+        lines.push(`installed  ${destination}`);
+    }
+    return ok(`${lines.join("\n")}\n`);
+}