@bluewombat/slots 0.1.0

package/gates/parent-clean.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
+
+// Parent working files must not change during the Attempt.
+// --parent DIR (repeatable). Other git worktrees of this Child are included.
+
+const cwd = resolve(process.cwd());
+const tokens = ownArgv(process.argv, GATE_FLAGS);
+const named = [];
+
+for (let i = 0; i < tokens.length; i++) {
+  const token = tokens[i];
+  if (token === "--parent") {
+    const value = tokens[i + 1];
+    if (value === undefined || value.startsWith("-")) {
+      emitVerdict("fail-blocking", "parent-clean needs a directory after --parent.");
+      process.exit(0);
+    }
+    named.push(resolve(cwd, value));
+    i += 1;
+    continue;
+  }
+  emitVerdict("fail-blocking", `parent-clean does not take "${token}". Use --parent <dir>.`);
+  process.exit(0);
+}
+
+const parents = [...named];
+for (const worktree of otherWorktrees(cwd)) {
+  if (!parents.includes(worktree)) {
+    parents.push(worktree);
+  }
+}
+
+if (parents.length === 0) {
+  emitVerdict(
+    "fail-blocking",
+    "parent-clean needs --parent <dir>, or a git worktree Child so it can see the other trees.",
+  );
+  process.exit(0);
+}
+
+const leaked = [];
+for (const parent of parents) {
+  if (parent === cwd) {
+    continue;
+  }
+  if (!existsSync(parent) || !statSync(parent).isDirectory()) {
+    // A directory that was named on the command line and is not there is a
+    // configuration error. A worktree git still lists after its directory went
+    // away is git bookkeeping: it holds no working file, so it can leak none.
+    if (named.includes(parent)) {
+      emitVerdict("fail-blocking", `parent-clean --parent is not a directory: ${parent}`);
+      process.exit(0);
+    }
+    continue;
+  }
+  leaked.push(...leaksIn(parent, cwd));
+}
+
+if (leaked.length > 0) {
+  emitVerdict("fail-blocking", `Parent working files changed:\n${leaked.join("\n")}`);
+  process.exit(0);
+}
+
+emitVerdict("pass");
+
+/** Other worktrees of this repository, minus the ones git has marked prunable. */
+/** @param {string} workspace @returns {string[]} */
+function otherWorktrees(workspace) {
+  const result = git(workspace, ["worktree", "list", "--porcelain"]);
+  if (result.status !== 0) {
+    return [];
+  }
+  const trees = [];
+  for (const record of result.stdout.split("\n\n")) {
+    const lines = record.split("\n");
+    const entry = lines.find((line) => line.startsWith("worktree "));
+    if (entry === undefined || lines.some((line) => line.startsWith("prunable"))) {
+      continue;
+    }
+    const path = resolve(entry.slice("worktree ".length));
+    if (path !== workspace) {
+      trees.push(path);
+    }
+  }
+  return trees;
+}
+
+/**
+ * @param {string} parent
+ * @param {string} workspace
+ * @returns {string[]}
+ */
+function leaksIn(parent, workspace) {
+  if (existsSync(join(parent, ".git"))) {
+    const status = git(parent, ["status", "--porcelain", "-uall"]);
+    if (status.status !== 0) {
+      return [`${parent}: git status failed`];
+    }
+    const lines = status.stdout
+      .split("\n")
+      .map((line) => line.trimEnd())
+      .filter(Boolean);
+    return lines.map((line) => `${relative(workspace, parent) || parent}: ${line}`);
+  }
+  const referenceMs = referenceTime(workspace);
+  /** @type {string[]} */
+  const dirty = [];
+  walkFiles(parent, (file) => {
+    if (statSync(file).mtimeMs > referenceMs) {
+      dirty.push(`${relative(workspace, parent) || parent}: ${relative(parent, file)}`);
+    }
+  });
+  return dirty;
+}
+
+/** @param {string} workspace */
+function referenceTime(workspace) {
+  const gitFile = join(workspace, ".git");
+  if (existsSync(gitFile)) {
+    return statSync(gitFile).mtimeMs;
+  }
+  let oldest = Number.POSITIVE_INFINITY;
+  walkFiles(workspace, (file) => {
+    oldest = Math.min(oldest, statSync(file).mtimeMs);
+  });
+  if (Number.isFinite(oldest)) {
+    return oldest;
+  }
+  return statSync(workspace).mtimeMs;
+}
+
+/**
+ * @param {string} dir
+ * @param {(file: string) => void} visit
+ */
+function walkFiles(dir, visit) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === ".git") {
+      continue;
+    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(full, visit);
+      continue;
+    }
+    if (entry.isFile()) {
+      visit(full);
+    }
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function git(cwd, args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/gates/sensitive-path.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { emitVerdict, GATE_FLAGS, ownArgv, pathMatchesGlob } from "@bluewombat/slot-kit";
+
+// Fail-retryable when the workspace changed a path matching a glob.
+// Remaining argv after Implementer's flags are the globs.
+
+const cwd = process.cwd();
+const globs = ownArgv(process.argv, GATE_FLAGS).filter((token) => token.length > 0);
+
+if (globs.length === 0) {
+  emitVerdict("fail-blocking", "sensitive-path needs at least one glob.");
+  process.exit(0);
+}
+
+if (git(cwd, ["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "sensitive-path needs a git workspace.");
+  process.exit(0);
+}
+
+const hit = new Set();
+
+walkFiles(cwd, (file) => {
+  const posix = relative(cwd, file).replaceAll("\\", "/");
+  if (!matchesAny(posix, globs)) {
+    return;
+  }
+  const onDisk = readFileSync(file);
+  const atHead = blobAtHead(cwd, posix);
+  if (atHead === null || Buffer.compare(onDisk, atHead) !== 0) {
+    hit.add(posix);
+  }
+});
+
+const deleted = git(cwd, ["diff", "--name-only", "--diff-filter=D", "HEAD"]);
+if (deleted.status === 0) {
+  for (const file of deleted.stdout.split("\n").filter(Boolean)) {
+    if (matchesAny(file.replaceAll("\\", "/"), globs)) {
+      hit.add(file);
+    }
+  }
+}
+
+if (hit.size > 0) {
+  emitVerdict("fail-retryable", `Sensitive paths changed:\n${[...hit].sort().join("\n")}`);
+  process.exit(0);
+}
+
+emitVerdict("pass");
+
+/**
+ * @param {string} path
+ * @param {readonly string[]} patterns
+ */
+function matchesAny(path, patterns) {
+  return patterns.some((pattern) => pathMatchesGlob(path, pattern));
+}
+
+/**
+ * @param {string} workspace
+ * @param {string} path
+ */
+function blobAtHead(workspace, path) {
+  const result = spawnSync("git", ["-C", workspace, "show", `HEAD:${path}`]);
+  if (result.status !== 0) {
+    return null;
+  }
+  return result.stdout;
+}
+
+/**
+ * @param {string} dir
+ * @param {(file: string) => void} visit
+ */
+function walkFiles(dir, visit) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === ".git") {
+      continue;
+    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(full, visit);
+      continue;
+    }
+    if (entry.isFile()) {
+      visit(full);
+    }
+  }
+}
+
+/**
+ * @param {string} workspace
+ * @param {string[]} args
+ */
+function git(workspace, args) {
+  return spawnSync("git", ["-C", workspace, ...args], { encoding: "utf8" });
+}

package/gates/workspace-changed.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { emitVerdict, GATE_FLAGS, ownArgv, stageOf } from "@bluewombat/slot-kit";
+
+// An Attempt that changed nothing did not build anything.
+// Work belongs in the working tree: a commit hides it from this Gate and from
+// the Gates that judge the workspace against HEAD. No option.
+//
+// A unit of work only. An assembly is made of work already validated on its own,
+// so there is a real case where the right thing to do is nothing, and refusing
+// it does not send the producer back to work — it sends it back to find
+// something to change. It obliges: the second attempt edits for the sake of
+// editing. A Gate that cannot tell those apart must not be the one to decide.
+
+const cwd = process.cwd();
+const tokens = ownArgv(process.argv, GATE_FLAGS);
+
+if (tokens.length > 0) {
+  emitVerdict("fail-blocking", `workspace-changed takes no option, got "${tokens[0]}".`);
+  process.exit(0);
+}
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "workspace-changed needs a git workspace.");
+  process.exit(0);
+}
+
+if (stageOf(process.argv) === "assembly") {
+  emitVerdict("pass");
+  process.exit(0);
+}
+
+const status = git(["status", "--porcelain", "-uall"]);
+if (status.status !== 0) {
+  emitVerdict("fail-blocking", `workspace-changed cannot read git status: ${status.stderr.trim()}`);
+  process.exit(0);
+}
+
+if (status.stdout.trim().length === 0) {
+  emitVerdict(
+    "fail-retryable",
+    [
+      "Nothing changed in this directory: this run produced nothing.",
+      "Write the work into the working tree here, and do not commit it —",
+      "a commit hides it from the checks that follow.",
+    ].join(" "),
+  );
+  process.exit(0);
+}
+
+emitVerdict("pass");
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/lib/fill.mjs

@@ -0,0 +1,17 @@
+/**
+ * What the shipped templates say, and nothing about how a role runs: the
+ * plumbing — parse, load, fill, spawn — is `@bluewombat/slot-kit`.
+ */
+import { take } from "@bluewombat/slot-kit";
+
+/** @param {string | undefined} raw */
+export function doneWhen(raw) {
+  const done = (raw ?? "").trim();
+  return done.length > 0 ? `Done when:\n${done}` : "";
+}
+
+/** @param {readonly string[]} argv */
+export function attemptOf(argv) {
+  const parsed = Number.parseInt(take(argv, "--attempt") ?? "", 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 1;
+}

package/messages/conventional.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { emitMessage, MESSAGE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
+
+// The feature's commit in the Conventional Commits shape, from the issue's
+// title and body and with no agent: `<type>: <title>`, the body as written.
+//
+// The type is read off the title's first word — a Project that wants a
+// judgement rather than a rule points `authority.describe` at
+// `messages/git-producer.mjs` with an agent after `--`.
+//
+//   --scope NAME    put a scope on the subject: `feat(api): …`
+//   --type NAME     one type for everything, instead of guessing it
+
+const SUBJECT_MAX = 72;
+/** @type {[RegExp, string][]} */
+const TYPES = [
+  [/^(fix|repair|correct|resolve)\b/i, "fix"],
+  [/^(document|describe|write (the )?(readme|docs))\b/i, "docs"],
+  [/^(test|cover)\b/i, "test"],
+  [/^(refactor|rename|move|extract|simplify|clean)\b/i, "refactor"],
+  [/^(bump|upgrade|update (the )?dependenc|configure|set up|setup)\b/i, "chore"],
+];
+
+const own = ownArgv(process.argv, MESSAGE_FLAGS);
+const scope = take(own, "--scope");
+const forcedType = take(own, "--type");
+const title = (take(process.argv, "--title") ?? "").trim();
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (title.length === 0) {
+  process.stderr.write("conventional: no --title.\n");
+  process.exit(1);
+}
+
+const sentence = firstSentence(title);
+const type = forcedType ?? TYPES.find(([pattern]) => pattern.test(sentence))?.[1] ?? "feat";
+const head = `${type}${scope === undefined ? "" : `(${scope})`}: `;
+const subject = `${head}${fit(lowerFirst(sentence), SUBJECT_MAX - head.length)}`;
+if (intention.length === 0) {
+  emitMessage(subject);
+} else {
+  emitMessage(subject, intention);
+}
+
+/** @param {string} text */
+function firstSentence(text) {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  const match = /^(.*?[.!?])(?:\s+(?=[A-Z\p{Lu}])|$)/u.exec(oneLine);
+  return (match?.[1] ?? oneLine).replace(/[.\s]+$/, "");
+}
+
+/** @param {string} text */
+function lowerFirst(text) {
+  // A word that is a name or a symbol keeps its case: `Add \`slugify\``, `README`.
+  return /^[A-Z][a-z]/.test(text) ? `${text.slice(0, 1).toLowerCase()}${text.slice(1)}` : text;
+}
+
+/**
+ * @param {string} text
+ * @param {number} max
+ */
+function fit(text, max) {
+  if (text.length <= max) {
+    return text;
+  }
+  const cut = text.slice(0, max - 1);
+  const atWord = cut.lastIndexOf(" ");
+  return `${(atWord > max / 2 ? cut.slice(0, atWord) : cut).trimEnd()}…`;
+}

package/messages/git-producer.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  emitMessage,
+  fillPrompt,
+  loadPrompt,
+  loadRules,
+  MESSAGE_FLAGS,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+
+// The feature's commit message — and the pull request's description with it
+// — written by an agent that read the diff, under the Project's own rules.
+// Asked once per feature. A role slot like the builders: it fills a template
+// and hands it to the agent after `--`; the agent answers in a file this slot
+// reads back. `--prompt-file` replaces the template, `--rules-file` the rules
+// — that is where a team's commit guideline goes.
+
+const NAME = "message producer";
+
+const DEFAULT_RULES = `- One subject line, imperative mood, at most 72 characters, no trailing period.
+- Say what the change does for the reader of the history, not how it was made.
+- A body only when the subject cannot carry the why; wrap it at 72.
+- Nothing about tools, agents, or this process.`;
+
+const DEFAULT_TEMPLATE = `You are writing the commit message for the change in this directory. It
+is also what the pull request will say, so it is read by people.
+
+Read the change first — \`git log {{target}}..HEAD\` for the commits that make
+it up, \`git diff {{target}}...HEAD\` for what they change. Do not modify
+anything.
+
+What was asked ({{id}}):
+
+{{title}}
+
+{{intention}}
+
+Rules:
+{{rules}}
+
+Write your answer as JSON, and nothing else, to this file:
+
+{{out}}
+
+It looks like this:
+
+{ "subject": "…", "body": "…" }
+
+\`body\` may be omitted.
+`;
+
+const title = (take(process.argv, "--title") ?? "").trim();
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (title.length === 0) {
+  fail("The message producer received no --title.");
+}
+
+const parsed = parseRole(process.argv, MESSAGE_FLAGS, NAME);
+if (!parsed.ok) {
+  fail(parsed.reason);
+}
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  fail(template.reason);
+}
+const rules = loadRules(parsed.options, DEFAULT_RULES);
+if (!rules.ok) {
+  fail(rules.reason);
+}
+
+const scratch = mkdtempSync(join(tmpdir(), "message-"));
+const out = join(scratch, "message.json");
+try {
+  const rendered = fillPrompt(
+    template.value,
+    {
+      title,
+      intention,
+      target: take(process.argv, "--target") ?? "",
+      id: take(process.argv, "--id") ?? "",
+      rules: rules.value.trim(),
+      out,
+    },
+    ["title", "out"],
+    textOption(parsed.options, "promptFile") ?? "built-in template",
+  );
+  if (!rendered.ok) {
+    fail(rendered.reason);
+  }
+  const spawned = await spawnFilled(
+    parsed.runner,
+    rendered.prompt,
+    transcriptArgs(process.argv, { id: `message:${take(process.argv, "--id") ?? ""}` }),
+  );
+  if (!spawned.ok) {
+    fail(spawned.reason);
+  }
+  if (spawned.run.error !== undefined) {
+    fail(`Could not start the agent at ${spawned.about.bin}: ${spawned.run.error.message}`);
+  }
+  const answer = readAnswer(out);
+  if (answer === undefined || typeof answer.subject !== "string" || answer.subject.trim() === "") {
+    fail(`The agent wrote no usable message to ${out}.`);
+  }
+  emitMessage(
+    answer.subject.trim(),
+    typeof answer.body === "string" && answer.body.trim().length > 0
+      ? answer.body.trim()
+      : undefined,
+  );
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}
+
+/** @param {string} path @returns {Record<string, unknown> | undefined} */
+function readAnswer(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  for (const candidate of [fenced?.[1], text]) {
+    if (candidate === undefined) {
+      continue;
+    }
+    try {
+      const value = JSON.parse(candidate);
+      if (value !== null && typeof value === "object") {
+        return value;
+      }
+    } catch {
+      // try the next reading
+    }
+  }
+  return undefined;
+}
+
+/** @param {string} reason @returns {never} */
+function fail(reason) {
+  process.stderr.write(`${reason}\n`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@bluewombat/slots",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
+  "keywords": [
+    "mason",
+    "bluewombat",
+    "gate",
+    "builder",
+    "planner"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/tilap/bluewombat/tree/main/packages/plugins/slots#readme",
+  "bugs": "https://github.com/tilap/bluewombat/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tilap/bluewombat.git",
+    "directory": "packages/plugins/slots"
+  },
+  "exports": {
+    "./planners/*": "./planners/*",
+    "./builders/*": "./builders/*",
+    "./assembly/*": "./assembly/*",
+    "./agents/*": "./agents/*",
+    "./gates/*": "./gates/*",
+    "./publishers/*": "./publishers/*",
+    "./refreshers/*": "./refreshers/*",
+    "./messages/*": "./messages/*"
+  },
+  "files": [
+    "planners",
+    "builders",
+    "assembly",
+    "agents",
+    "lib",
+    "gates",
+    "README.md",
+    "publishers",
+    "refreshers",
+    "messages"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "tsc": "tsc --noEmit",
+    "test": "tsx --test $(find test -name '*.test.ts')"
+  },
+  "dependencies": {
+    "@bluewombat/slot-kit": "^0.1.0"
+  }
+}

package/planners/one-subtask.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap Planner: one Subtask that is the FeatureStandard itself.
+ * FeatureBreakdown appends --intention, --key, --max-units.
+ */
+import { emitPlan, emitRefusal, take } from "@bluewombat/slot-kit";
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitRefusal("The FeatureStandard has no intention to turn into a Subtask.");
+  process.exit(0);
+}
+
+emitPlan([
+  {
+    id: "A",
+    intention,
+    definition_of_done: "The intention is realized in the workspace.",
+    depends_on: [],
+  },
+]);