@feigi/fleet-ctl 3.17.0 → 3.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.17.0",
+  "version": "3.17.2",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/tier-roles.mjs

@@ -31,7 +31,10 @@
 //       flagged as a notice — legal, but every `slow-*` cell then measures
 //       the same model as its `task-*` twin;
 //   (f) the agents directory holds at least one `*.agent.md` definition —
-//       with none, (a), (b) and (d) have nothing to check.
+//       with none, (a), (b) and (d) have nothing to check; an agents
+//       directory that cannot be read (missing, not a directory) or a
+//       definition that cannot be read (a directory named `*.agent.md`)
+//       fails too.
 
 import { readFileSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -202,19 +205,35 @@ function kindOf(v) {
 // definitions need. `violations` stop a run (ADR 0014); `notices` never do —
 // they flag a hazard (two roles' cells measuring one model) that is legal
 // configuration, just probably not what the operator meant.
-export function checkRoutes({ agentsDir, modelRoles, overrides, catalog }) {
+export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog }) {
   const violations = [];
   const notices = [];
   const usedBy = {}; // role -> [{ file, level }, ...]
 
-  const files = readdirSync(agentsDir).filter((f) => f.endsWith(".agent.md")).sort();
-  // A directory with no definitions has nothing to route, so every
-  // per-definition check below (the model route, the role's resolution, the
-  // level) would pass over it — a wrong `--agents` path that exists must not
-  // read as a healthy install.
-  if (files.length === 0) violations.push(`no *.agent.md definition found in ${agentsDir}`);
+  // A path `readdirSync`/`readFileSync` cannot read (missing, a regular file,
+  // a directory named `*.agent.md`, no permission) is a wrong agents
+  // directory, not a crash: name the path and where it came from
+  // (`agentsSource` — `--agents <dir>`, or the built-in default).
+  const unreadable = (what, e) => `${agentsSource}: cannot read ${what} (${e.code ?? e.message})`;
+  let files = [];
+  try {
+    files = readdirSync(agentsDir).filter((f) => f.endsWith(".agent.md")).sort();
+    // A directory with no definitions has nothing to route, so every
+    // per-definition check below (the model route, the role's resolution, the
+    // level) would pass over it — a wrong `--agents` path that exists must not
+    // read as a healthy install.
+    if (files.length === 0) violations.push(`no *.agent.md definition found in ${agentsDir}`);
+  } catch (e) {
+    violations.push(unreadable("the agents directory", e));
+  }
   for (const file of files) {
-    const text = readFileSync(join(agentsDir, file), "utf8");
+    let text;
+    try {
+      text = readFileSync(join(agentsDir, file), "utf8");
+    } catch (e) {
+      violations.push(unreadable(file, e));
+      continue;
+    }
     const fm = parseFrontmatter(text);
     if (!fm.role || !fm.level) {
       violations.push(`${file}: model ${JSON.stringify(fm.model)} is not @<role>:<level>`);
@@ -317,13 +336,20 @@ function main() {
   const check = has("check");
   if (!check) die("--check is required (usage: tier-roles.mjs --check [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>])");
 
-  const agentsDir = arg("agents") ?? join(SCRIPT_DIR, "..", "agents");
+  const agentsFlag = arg("agents");
+  const agentsDir = agentsFlag ?? join(SCRIPT_DIR, "..", "agents");
   const config = (key) => [() => readOmpConfigValue(key), `omp config get ${key} --json`];
   const overrides = loadJsonObject(arg("overrides"), ...config("task.agentModelOverrides"), "overrides");
   const modelRoles = loadJsonObject(arg("model-roles"), ...config("modelRoles"), "model-roles");
   const catalog = loadJsonObject(arg("catalog"), readOmpModelCatalog, "omp models --json", "catalog");
 
-  const { violations, notices } = checkRoutes({ agentsDir, modelRoles, overrides, catalog });
+  const { violations, notices } = checkRoutes({
+    agentsDir,
+    agentsSource: agentsFlag === null ? `the default agents directory ${agentsDir}` : undefined,
+    modelRoles,
+    overrides,
+    catalog,
+  });
 
   if (violations.length === 0) {
     console.log("tier-roles: every definition routes to a resolvable model at a level it runs, no shadowing override");

package/scripts/tier-roles.test.mjs

@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { chmodSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { tempDir } from "./temp-dir.mjs";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,6 +12,7 @@ import {
 } from "./tier-roles.mjs";
 
 const SCRIPT = fileURLToPath(new URL("./tier-roles.mjs", import.meta.url));
+const SCRIPTS_DIR = fileURLToPath(new URL(".", import.meta.url));
 const REPO_AGENTS = fileURLToPath(new URL("../agents", import.meta.url));
 
 function dir() {
@@ -211,6 +212,32 @@ test("checkRoutes: an empty agents directory still reports the other violations
   assert.match(violations.join("\n"), /task\.agentModelOverrides\.fleet-a shadows/);
 });
 
+test("checkRoutes: an --agents path that is missing, or a regular file, is a violation naming the flag and path, not a crash", () => {
+  const d = dir();
+  const missing = join(d, "nope");
+  const file = join(d, "plain.txt");
+  writeFileSync(file, "x\n");
+  for (const [path, code] of [[missing, "ENOENT"], [file, "ENOTDIR"]]) {
+    const { violations } = checkRoutes({ agentsDir: path, modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+    assert.deepEqual(violations, [`--agents ${path}: cannot read the agents directory (${code})`]);
+  }
+});
+
+test("checkRoutes: a directory named *.agent.md is a violation naming the entry, and the readable definitions after it are still checked", () => {
+  const agents = agentsDir({ "fleet-a": "@slow:xhigh", "fleet-b": "@smol:max" });
+  mkdirSync(join(agents, "a.agent.md"));
+  const { violations } = checkRoutes({ agentsDir: agents, modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+  assert.equal(violations.length, 2);
+  assert.equal(violations[0], `--agents ${agents}: cannot read a.agent.md (EISDIR)`);
+  assert.match(violations[1], /^fleet-b\.agent\.md: level max is not one modelRoles\.smol's target/);
+});
+
+test("checkRoutes: an unreadable agents directory names the source the caller gives, not --agents", () => {
+  const missing = join(dir(), "nope");
+  const { violations } = checkRoutes({ agentsDir: missing, agentsSource: "the default agents directory X", modelRoles: MODEL_ROLES, overrides: {}, catalog: CATALOG });
+  assert.deepEqual(violations, ["the default agents directory X: cannot read the agents directory (ENOENT)"]);
+});
+
 test("checkRoutes (a): a definition whose model: is not a route is a violation naming the file", () => {
   const { violations } = routes({ "fleet-a": "opus" });
   assert.equal(violations.length, 1);
@@ -358,6 +385,33 @@ test("CLI: --check on an agents directory with no definitions exits 1 naming the
   assert.doesNotMatch(r.stdout, /every definition routes/);
 });
 
+test("CLI: --check on an --agents path that is missing, a regular file, or holds a directory named *.agent.md exits 1 with a refusal naming the cause, no stack trace", () => {
+  const d = dir();
+  const file = join(d, "plain.txt");
+  writeFileSync(file, "x\n");
+  const trap = agentsDir({ "fleet-a": "@slow:xhigh" });
+  mkdirSync(join(trap, "x.agent.md"));
+  for (const [path, code] of [[join(d, "nope"), "ENOENT"], [file, "ENOTDIR"], [trap, "EISDIR"]]) {
+    const r = runCli(["--check", "--agents", path, ...installFlags(d)], d);
+    assert.equal(r.status, 1, path);
+    assert.match(r.stderr, new RegExp(`^tier-roles: --agents ${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}: cannot read .*\\(${code}\\)`), path);
+    assert.doesNotMatch(r.stderr, /\n\s+at /, path);
+    assert.doesNotMatch(r.stdout, /every definition routes/);
+  }
+});
+
+test("CLI: --check with no --agents and an unreadable built-in agents directory refuses without naming a flag it was not given", () => {
+  const d = dir();
+  const scripts = join(d, "scripts");
+  mkdirSync(scripts);
+  for (const f of ["tier-roles.mjs", "arg.mjs", "is-cli.mjs"]) copyFileSync(join(SCRIPTS_DIR, f), join(scripts, f));
+  const r = spawnSync(process.execPath, [join(scripts, "tier-roles.mjs"), "--check", ...installFlags(d)], { cwd: d, encoding: "utf8" });
+  assert.equal(r.status, 1, r.stderr);
+  assert.match(r.stderr, /^tier-roles: the default agents directory .*agents: cannot read the agents directory \(ENOENT\)/);
+  assert.doesNotMatch(r.stderr, /--agents/);
+  assert.doesNotMatch(r.stderr, /\n\s+at /);
+});
+
 test("CLI: --check with a non-route model: exits 1 naming the file", () => {
   const d = dir();
   const agents = agentsDir({ "fleet-a": "opus" });