@gempack/squad-mcp 0.5.0 → 0.6.1

package/tools/next-task.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Pick the next ready task: candidate status (default pending), all
+// dependencies done, optional agent filter. Tiebreaker priority then id.
+//
+// Usage:
+//   tools/next-task.mjs [--agent senior-dba] [--workspace <path>]
+//                       [--file <relpath>] [--json]
+//
+// Prints a one-line summary by default, or the full task as JSON with --json.
+// If no ready task, prints reason ("no_candidates" / "all_blocked") and the
+// blocked list.
+//
+// Exit codes:
+//   0 ready task surfaced (or json mode, regardless of ready)
+//   1 no ready task (text mode only — for shell pipelines)
+//   2 invalid input
+
+import { readTasksFile, fail } from "./_tasks-io.mjs";
+
+const args = process.argv.slice(2);
+const PROG = "next-task";
+const PRIORITY_RANK = { high: 0, medium: 1, low: 2 };
+
+function parseArgs(argv) {
+  const out = {
+    agent: null,
+    workspace: process.cwd(),
+    file: null,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--agent":
+        out.agent = argv[++i];
+        break;
+      case "--workspace":
+        out.workspace = argv[++i];
+        break;
+      case "--file":
+        out.file = argv[++i];
+        break;
+      case "--json":
+        out.json = true;
+        break;
+      case "--help":
+      case "-h":
+        process.stdout.write(
+          "usage: next-task.mjs [--agent NAME] [--workspace PATH] [--file PATH] [--json]\n",
+        );
+        process.exit(0);
+      default:
+        fail(PROG, 2, `unknown flag: ${a}`);
+    }
+  }
+  return out;
+}
+
+function pickNext(tasks, opts) {
+  const doneIds = new Set(
+    tasks.filter((t) => t.status === "done").map((t) => t.id),
+  );
+  let candidates = tasks.filter((t) => t.status === "pending");
+  if (opts.agent) {
+    candidates = candidates.filter(
+      (t) =>
+        !t.agent_hints ||
+        t.agent_hints.length === 0 ||
+        t.agent_hints.includes(opts.agent),
+    );
+  }
+  if (candidates.length === 0) {
+    return { task: null, reason: "no_candidates", blocked: [] };
+  }
+  const ready = [];
+  const blocked = [];
+  for (const t of candidates) {
+    const missing = (t.dependencies ?? []).filter((d) => !doneIds.has(d));
+    if (missing.length === 0) {
+      ready.push(t);
+    } else {
+      blocked.push({ id: t.id, title: t.title, missing_deps: missing });
+    }
+  }
+  if (ready.length === 0) {
+    return { task: null, reason: "all_blocked", blocked };
+  }
+  ready.sort((a, b) => {
+    const p =
+      PRIORITY_RANK[a.priority ?? "medium"] -
+      PRIORITY_RANK[b.priority ?? "medium"];
+    if (p !== 0) return p;
+    return a.id - b.id;
+  });
+  return { task: ready[0], reason: "ok", blocked };
+}
+
+async function main() {
+  const opts = parseArgs(args);
+  const { data } = await readTasksFile(opts.workspace, opts.file);
+  const result = pickNext(data.tasks, opts);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return;
+  }
+
+  if (result.task) {
+    const t = result.task;
+    process.stdout.write(`#${t.id} [${t.priority ?? "medium"}] ${t.title}\n`);
+    if (t.scope) process.stdout.write(`  scope: ${t.scope}\n`);
+    if (t.agent_hints && t.agent_hints.length > 0) {
+      process.stdout.write(`  agents: ${t.agent_hints.join(", ")}\n`);
+    }
+    return;
+  }
+
+  if (result.reason === "no_candidates") {
+    process.stderr.write("no pending tasks\n");
+  } else {
+    process.stderr.write("all candidates blocked:\n");
+    for (const b of result.blocked) {
+      process.stderr.write(
+        `  #${b.id} ${b.title} (missing deps: ${b.missing_deps.join(", ")})\n`,
+      );
+    }
+  }
+  process.exit(1);
+}
+
+main().catch((err) => fail(PROG, 2, err.message ?? String(err)));

package/tools/post-review.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Post a squad-mcp consolidation result as a `gh pr review` on a GitHub PR.
+//
+// Usage:
+//   echo '{...consolidator JSON...}' | node tools/post-review.mjs --pr 42
+//   echo '{...}' | node tools/post-review.mjs --pr 42 --dry-run
+//   echo '{...}' | node tools/post-review.mjs --pr 42 --request-changes-below 60
+//   echo '{...}' | node tools/post-review.mjs --pr 42 --repo owner/name
+//
+// Flags:
+//   --pr <number>                       PR number on the current repo (required)
+//   --repo <owner/name>                 Override the repo (else gh resolves from cwd)
+//   --request-changes-below <number>    Force `request-changes` if APPROVED w/ score below this
+//   --dry-run                           Print the gh command + body, do NOT execute
+//   --no-footer                         Omit the "generated by squad-mcp" footer line
+//
+// Exit codes:
+//   0 = success (posted, or dry-run produced output)
+//   2 = invalid input / missing args
+//   3 = gh not installed or not authenticated
+//   4 = gh failed (non-zero) — prints stderr from gh
+//
+// This script lives outside the MCP server (tools/, alongside the commit-msg
+// hook) because posting to GitHub is a side-effecting operation with auth.
+// MCP tools are pure primitives. The skill SKILL.md orchestrates: it gets the
+// consolidation JSON from `apply_consolidation_rules`, then invokes this CLI.
+
+import { spawn, spawnSync } from "node:child_process";
+import { formatPrReview } from "../dist/format/pr-review.js";
+
+const args = process.argv.slice(2);
+
+function fail(code, msg) {
+  process.stderr.write(`post-review: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = {
+    pr: null,
+    repo: null,
+    requestChangesBelow: undefined,
+    dryRun: false,
+    noFooter: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--pr":
+        out.pr = argv[++i];
+        break;
+      case "--repo":
+        out.repo = argv[++i];
+        break;
+      case "--request-changes-below":
+        out.requestChangesBelow = Number(argv[++i]);
+        if (!Number.isFinite(out.requestChangesBelow)) {
+          fail(2, `--request-changes-below requires a number`);
+        }
+        break;
+      case "--dry-run":
+        out.dryRun = true;
+        break;
+      case "--no-footer":
+        out.noFooter = true;
+        break;
+      case "--help":
+      case "-h":
+        process.stdout.write(
+          "usage: post-review.mjs --pr <n> [--repo owner/name] [--request-changes-below N] [--dry-run] [--no-footer]\n" +
+            "stdin: JSON output of apply_consolidation_rules\n",
+        );
+        process.exit(0);
+        break;
+      default:
+        fail(2, `unknown flag: ${a}`);
+    }
+  }
+  if (!out.pr) fail(2, "--pr <number> is required");
+  if (!/^\d+$/.test(out.pr))
+    fail(2, `--pr must be a positive integer, got "${out.pr}"`);
+  return out;
+}
+
+async function readStdin() {
+  return await new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+  });
+}
+
+function ensureGh() {
+  // gh --version is read-only and fast. If it's not installed, error early
+  // with a clear message instead of letting the user discover it via spawn ENOENT.
+  const r = spawnSync("gh", ["--version"], { encoding: "utf8" });
+  if (r.error) {
+    if (r.error.code === "ENOENT") {
+      fail(
+        3,
+        "gh CLI not found in PATH. Install: https://cli.github.com/manual/installation",
+      );
+    }
+    fail(3, `gh check failed: ${r.error.message}`);
+  }
+  if (r.status !== 0) {
+    fail(3, `gh --version exited ${r.status}: ${r.stderr || r.stdout}`);
+  }
+}
+
+function runGh(args, body) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("gh", args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => (stdout += d));
+    proc.stderr.on("data", (d) => (stderr += d));
+    proc.on("error", reject);
+    proc.on("close", (code) => resolve({ code, stdout, stderr }));
+    proc.stdin.write(body);
+    proc.stdin.end();
+  });
+}
+
+async function main() {
+  const opts = parseArgs(args);
+
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch (err) {
+    fail(2, `failed to read stdin: ${err.message}`);
+  }
+  if (!raw || raw.trim() === "") {
+    fail(2, "no JSON received on stdin");
+  }
+
+  let consolidation;
+  try {
+    consolidation = JSON.parse(raw);
+  } catch (err) {
+    fail(2, `invalid JSON on stdin: ${err.message}`);
+  }
+  if (
+    !consolidation ||
+    typeof consolidation !== "object" ||
+    !consolidation.verdict
+  ) {
+    fail(
+      2,
+      "stdin JSON missing required `verdict` field — expected output of apply_consolidation_rules",
+    );
+  }
+
+  const formatOptions = {};
+  if (typeof opts.requestChangesBelow === "number") {
+    formatOptions.requestChangesBelowScore = opts.requestChangesBelow;
+  }
+  if (opts.repo) formatOptions.repoLabel = opts.repo;
+
+  const payload = formatPrReview(consolidation, formatOptions);
+  let body = payload.body;
+  if (opts.noFooter) {
+    // Strip the trailing "---\n_Generated by..._\n" footer block. Idempotent.
+    body = body.replace(/\n\n---\n[\s\S]*$/, "\n");
+  }
+
+  const ghArgs = [
+    "pr",
+    "review",
+    opts.pr,
+    `--${payload.action}`,
+    "--body-file",
+    "-",
+  ];
+  if (opts.repo) ghArgs.push("--repo", opts.repo);
+
+  if (opts.dryRun) {
+    process.stdout.write(`# DRY RUN — would execute:\n`);
+    process.stdout.write(
+      `gh ${ghArgs.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")} <<'EOF'\n`,
+    );
+    process.stdout.write(body);
+    process.stdout.write(`EOF\n`);
+    process.stdout.write(
+      `\n# Action: ${payload.action}\n# Summary: ${payload.summary}\n`,
+    );
+    process.exit(0);
+  }
+
+  ensureGh();
+  const r = await runGh(ghArgs, body);
+  if (r.code !== 0) {
+    process.stderr.write(
+      `gh ${payload.action} failed (exit ${r.code}):\n${r.stderr}`,
+    );
+    process.exit(4);
+  }
+  // gh prints the review URL on success; surface it to the caller.
+  if (r.stdout) process.stdout.write(r.stdout);
+  process.stdout.write(
+    `\nposted: ${payload.action} on PR #${opts.pr} | ${payload.summary}\n`,
+  );
+}
+
+main().catch((err) => {
+  fail(4, `unexpected error: ${err && err.stack ? err.stack : err}`);
+});

package/tools/record-learning.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Append a team decision (accept | reject) to `.squad/learnings.jsonl`.
+//
+// Usage:
+//   tools/record-learning.mjs --reject \
+//     --agent senior-dev-security \
+//     --finding "missing CSRF on POST /api/refund" \
+//     --reason "CSRF terminated at API gateway, see infra/edge.tf" \
+//     --pr 42
+//
+//   tools/record-learning.mjs --accept \
+//     --agent senior-architect \
+//     --finding "cross-module coupling Auth -> Billing" \
+//     --reason "refactored to event bus" \
+//     --branch refactor/auth
+//
+// Flags:
+//   --accept | --reject                 (required, mutually exclusive)
+//   --agent <name>                      (required)
+//   --finding "<short title>"           (required)
+//   --reason "<rationale>"              (optional but recommended)
+//   --severity Blocker|Major|Minor|Suggestion  (optional)
+//   --pr <number>                       (optional)
+//   --branch <name>                     (optional)
+//   --scope "<glob>"                    (optional, e.g. "src/auth/**")
+//   --workspace <path>                  (default: cwd)
+//   --file <relpath>                    (override the JSONL location for this run)
+//
+// Exit codes:
+//   0 success
+//   2 invalid input
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+
+function fail(code, msg) {
+  process.stderr.write(`record-learning: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = {
+    decision: null, // 'accept' | 'reject'
+    agent: null,
+    finding: null,
+    reason: null,
+    severity: null,
+    pr: null,
+    branch: null,
+    scope: null,
+    workspace: process.cwd(),
+    file: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--accept":
+        if (out.decision)
+          fail(2, "--accept and --reject are mutually exclusive");
+        out.decision = "accept";
+        break;
+      case "--reject":
+        if (out.decision)
+          fail(2, "--accept and --reject are mutually exclusive");
+        out.decision = "reject";
+        break;
+      case "--agent":
+        out.agent = argv[++i];
+        break;
+      case "--finding":
+        out.finding = argv[++i];
+        break;
+      case "--reason":
+        out.reason = argv[++i];
+        break;
+      case "--severity":
+        out.severity = argv[++i];
+        break;
+      case "--pr":
+        out.pr = Number(argv[++i]);
+        if (!Number.isInteger(out.pr) || out.pr <= 0) {
+          fail(2, "--pr must be a positive integer");
+        }
+        break;
+      case "--branch":
+        out.branch = argv[++i];
+        break;
+      case "--scope":
+        out.scope = argv[++i];
+        break;
+      case "--workspace":
+        out.workspace = argv[++i];
+        break;
+      case "--file":
+        out.file = argv[++i];
+        break;
+      case "--help":
+      case "-h":
+        process.stdout.write(
+          "usage: record-learning.mjs --accept|--reject --agent <name> --finding <title> [options]\n",
+        );
+        process.exit(0);
+      default:
+        fail(2, `unknown flag: ${a}`);
+    }
+  }
+  if (!out.decision) fail(2, "one of --accept or --reject is required");
+  if (!out.agent) fail(2, "--agent <name> is required");
+  if (!out.finding) fail(2, "--finding <title> is required");
+  return out;
+}
+
+async function main() {
+  const opts = parseArgs(args);
+  const ts = new Date().toISOString();
+  const entry = {
+    ts,
+    agent: opts.agent,
+    finding: opts.finding,
+    decision: opts.decision,
+  };
+  if (opts.severity) entry.severity = opts.severity;
+  if (opts.reason) entry.reason = opts.reason;
+  if (opts.pr) entry.pr = opts.pr;
+  if (opts.branch) entry.branch = opts.branch;
+  if (opts.scope) entry.scope = opts.scope;
+
+  const target = path.resolve(
+    opts.workspace,
+    opts.file ?? ".squad/learnings.jsonl",
+  );
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.appendFile(target, JSON.stringify(entry) + "\n", "utf8");
+
+  process.stdout.write(
+    `recorded: ${opts.decision} on ${opts.agent} — "${opts.finding}"\n`,
+  );
+  process.stdout.write(`file:     ${target}\n`);
+}
+
+main().catch((err) => {
+  fail(2, `unexpected error: ${err && err.stack ? err.stack : err}`);
+});

package/tools/record-tasks.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// Bulk-add tasks to `.squad/tasks.json`. Reads a JSON array of task inputs
+// from stdin (or a file via --input) and appends them.
+//
+// Usage:
+//   echo '[{"title":"Add CSRF","scope":"src/api/**"}]' | tools/record-tasks.mjs
+//   tools/record-tasks.mjs --input parsed-prd.json
+//
+// Each task input may include: title (required), description, dependencies,
+// priority, details, test_strategy, scope, agent_hints. id is optional —
+// auto-allocated as max(existing) + 1 in input order.
+//
+// Flags:
+//   --input <path>           Read JSON from this file instead of stdin
+//   --workspace <path>       Default: cwd
+//   --file <relpath>         Override the JSON store location
+//   --dry-run                Validate + print resulting file, do not write
+//
+// Exit codes:
+//   0 success
+//   2 invalid input
+//
+// This CLI is intentionally minimal — no schema validation beyond shape.
+// Production use should go through the MCP `record_tasks` tool which
+// validates the full zod schema.
+
+import { promises as fs } from "node:fs";
+import {
+  readTasksFile,
+  writeTasksFile,
+  VALID_PRIORITIES,
+  fail,
+} from "./_tasks-io.mjs";
+
+const args = process.argv.slice(2);
+const PROG = "record-tasks";
+
+function parseArgs(argv) {
+  const out = {
+    input: null,
+    workspace: process.cwd(),
+    file: null,
+    dryRun: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--input":
+        out.input = argv[++i];
+        break;
+      case "--workspace":
+        out.workspace = argv[++i];
+        break;
+      case "--file":
+        out.file = argv[++i];
+        break;
+      case "--dry-run":
+        out.dryRun = true;
+        break;
+      case "--help":
+      case "-h":
+        process.stdout.write(
+          "usage: record-tasks.mjs [--input PATH | <stdin>] [--workspace PATH] [--file PATH] [--dry-run]\n",
+        );
+        process.exit(0);
+      default:
+        fail(PROG, 2, `unknown flag: ${a}`);
+    }
+  }
+  return out;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function validateInputs(inputs) {
+  if (!Array.isArray(inputs) || inputs.length === 0) {
+    fail(PROG, 2, "input must be a non-empty array of task objects");
+  }
+  for (const [i, t] of inputs.entries()) {
+    if (!t || typeof t !== "object") {
+      fail(PROG, 2, `input[${i}]: not an object`);
+    }
+    if (typeof t.title !== "string" || t.title.length === 0) {
+      fail(PROG, 2, `input[${i}]: title is required and must be a string`);
+    }
+    if (t.priority !== undefined && !VALID_PRIORITIES.includes(t.priority)) {
+      fail(PROG, 2, `input[${i}]: priority must be low|medium|high`);
+    }
+    if (t.dependencies !== undefined && !Array.isArray(t.dependencies)) {
+      fail(PROG, 2, `input[${i}]: dependencies must be an array`);
+    }
+    if (t.id !== undefined && (!Number.isInteger(t.id) || t.id <= 0)) {
+      fail(PROG, 2, `input[${i}]: id must be a positive integer`);
+    }
+  }
+}
+
+async function main() {
+  const opts = parseArgs(args);
+  const raw = opts.input
+    ? await fs.readFile(opts.input, "utf8")
+    : await readStdin();
+
+  let inputs;
+  try {
+    inputs = JSON.parse(raw);
+  } catch (err) {
+    fail(PROG, 2, `invalid JSON on input: ${err.message}`);
+  }
+  validateInputs(inputs);
+
+  const { filePath, data } = await readTasksFile(opts.workspace, opts.file);
+  const existingIds = new Set(data.tasks.map((t) => t.id));
+  let cursor = data.tasks.reduce((m, t) => Math.max(m, t.id), 0);
+  const ts = new Date().toISOString();
+  const newTasks = [];
+  const seen = new Set(existingIds);
+
+  for (const inp of inputs) {
+    let id = inp.id;
+    if (id === undefined) {
+      cursor += 1;
+      id = cursor;
+    } else {
+      if (seen.has(id)) {
+        fail(PROG, 2, `duplicate task id ${id}`);
+      }
+      cursor = Math.max(cursor, id);
+    }
+    seen.add(id);
+    newTasks.push({
+      id,
+      title: inp.title,
+      ...(inp.description !== undefined && { description: inp.description }),
+      status: "pending",
+      dependencies: inp.dependencies ?? [],
+      priority: inp.priority ?? "medium",
+      ...(inp.details !== undefined && { details: inp.details }),
+      ...(inp.test_strategy !== undefined && {
+        test_strategy: inp.test_strategy,
+      }),
+      ...(inp.scope !== undefined && { scope: inp.scope }),
+      ...(inp.agent_hints !== undefined && { agent_hints: inp.agent_hints }),
+      subtasks: [],
+      created_at: ts,
+      updated_at: ts,
+    });
+  }
+
+  // Validate deps after id allocation (forward refs allowed in batch).
+  for (const t of newTasks) {
+    for (const dep of t.dependencies) {
+      if (!seen.has(dep)) {
+        fail(PROG, 2, `task ${t.id} depends on unknown id ${dep}`);
+      }
+      if (dep === t.id) {
+        fail(PROG, 2, `task ${t.id} cannot depend on itself`);
+      }
+    }
+  }
+
+  const next = {
+    version: data.version ?? 1,
+    tasks: [...data.tasks, ...newTasks],
+  };
+
+  if (opts.dryRun) {
+    process.stdout.write(JSON.stringify(next, null, 2) + "\n");
+    process.stderr.write(
+      `would record: ${newTasks.length} task(s), ids ${newTasks.map((t) => t.id).join(", ")}\n`,
+    );
+    return;
+  }
+
+  await writeTasksFile(filePath, next);
+  process.stdout.write(
+    `recorded: ${newTasks.length} task(s), ids ${newTasks.map((t) => t.id).join(", ")}\n`,
+  );
+  process.stdout.write(`file:     ${filePath}\n`);
+}
+
+main().catch((err) => fail(PROG, 2, err.message ?? String(err)));