@theagilemonkeys/facility 0.11.3 → 0.12.0

package/src/doctor.mjs

@@ -1,582 +1,77 @@
-// `facility doctor` — check the install and tell the truth about what's left.
-// Static checks run locally; the GitHub-side items it can't verify are
-// printed as the explicit manual checklist instead of being assumed.
-import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getProfile, loadConfig } from "./platform-config.mjs";
-import { banner, bold, dim, fail, green, heading, item, ok, red, warn, yellow } from "./ui.mjs";
-
-const REQUIRED = [
-  ".github/workflows/facility-crew.yml",
-  ".github/workflows/facility-codex.yml",
-  ".github/workflows/facility-review.yml",
-  ".github/workflows/facility-address-review.yml",
-  ".github/workflows/facility-doctor.yml",
-  ".github/workflows/facility-security-sweep.yml",
-  ".github/workflows/facility-watchtower.yml",
-  ".github/workflows/facility-canary.yml",
-  ".github/facility/architect.md",
-  ".github/facility/builder.md",
-  ".github/facility/doctor.md",
-  ".github/facility/sweep.md",
-  ".github/facility/doctor/resolve.mjs",
-  ".github/facility/delivery/verify.mjs",
-  ".github/facility/receipts/collect.mjs",
-  ".github/facility/review/finalize.mjs",
-  ".github/facility/security/sync-findings.mjs",
-  ".github/facility/watchtower/outcomes.mjs",
-  ".github/facility/watchtower/health.mjs",
-  ".github/facility/watchtower/canary.mjs",
-  ".github/facility/watchtower/budgets.json",
-  "STANDARD.md",
-  "AGENTS.md",
-  ".claude/hooks/protect-branch.mjs",
-  ".claude/hooks/protect-files.mjs",
-  ".claude/skills/working-to-standard/SKILL.md",
-  ".claude/skills/reviewing-to-standard/SKILL.md",
-  ".claude/skills/maintainable-software/SKILL.md",
-  ".claude/commands/verify.md",
-  "guards/run.mjs",
+import { banner, heading, item, ok, warn } from "./ui.mjs";
+
+const AGENTS = [
+  "architect",
+  "builder",
+  "pr-reviewer",
+  "address-review",
+  "ci-doctor",
+  "security-audit",
 ];
 
-export async function doctor(flags, version, options = {}) {
-  const platform = platformTarget(flags, options);
-  if (!flags.local && platform) return platformDoctor(flags, version, platform, options);
-  if ((flags.platform || flags.url || flags.key || flags.profile) && !platform) {
-    const message = "facility doctor needs both --url and --key, or a saved login profile.";
-    if (flags.json) {
-      (options.stdout || process.stdout).write(
-        `${JSON.stringify({
-          mode: "platform",
-          target: null,
-          ok: false,
-          checks: [],
-          error: { code: "doctor_target_required", message },
-        })}\n`,
-      );
-    }
-    else console.log(message);
-    return 2;
-  }
-
+export async function doctor(flags, version) {
   const dir = flags.dir || process.cwd();
-  const report = inspectLocalInstall(dir, {
-    runGuards: flags["run-guards"] === true,
-    github: flags.github === true,
-  });
+  const checks = [checkProjectManifest(dir), ...AGENTS.map((name) => checkAgent(dir, name))];
+  const problems = checks.filter((check) => !check.ok).length;
+  const result = { mode: "local", ok: problems === 0, problems, checks };
+
   if (flags.json) {
-    (options.stdout || process.stdout).write(`${JSON.stringify(report)}\n`);
-    return report.ok ? 0 : 1;
+    console.log(JSON.stringify(result));
+    return result.ok ? 0 : 1;
   }
 
   banner(version);
-  renderLocalReport(report);
-  console.log("");
-  if (report.ok) item(`${dim("Everything checkable checks out.")}`);
-  else item(`${dim(`${report.problems} problem${report.problems === 1 ? "" : "s"} found.`)}`);
-  console.log("");
-  return report.ok ? 0 : 1;
-}
-
-function inspectLocalInstall(dir, options = {}) {
-  const checks = [];
-  let manifest = {};
-  for (const file of REQUIRED) {
-    checks.push(
-      existsSync(join(dir, file))
-        ? localCheck("Files", file, "pass", "Present")
-        : localCheck("Files", file, "fail", "missing", "Run `npx @theagilemonkeys/facility init`."),
-    );
-  }
-
-  const manifestPath = join(dir, ".facility.json");
-  if (!existsSync(manifestPath)) {
-    checks.push(localCheck("Manifest", ".facility.json", "fail", "missing"));
-  } else {
-    try {
-      manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-      const models = manifest.models;
-      checks.push(
-        models?.build &&
-          models?.review &&
-          models?.plan &&
-          models?.codexBuild &&
-          models?.codexPlan
-          ? localCheck(
-              "Manifest",
-              ".facility.json",
-              "pass",
-              `engines ${(manifest.engines || [manifest.engine || "claude-code"]).join(",")}, models build=${models.build}, review=${models.review}, plan=${models.plan}, codexBuild=${models.codexBuild}, codexPlan=${models.codexPlan}`,
-            )
-          : localCheck(
-              "Manifest",
-              "models",
-              "fail",
-              "Claude and Codex build/plan models must all be configured.",
-              "Rerun init with explicit Claude and Codex model flags.",
-            ),
-      );
-      const mode = detectAnthropicAuthMode(manifest, dir);
-      checks.push(
-        mode
-          ? localCheck("Manifest", "auth", "pass", `Anthropic auth: ${mode}`)
-          : localCheck(
-              "Manifest",
-              "auth",
-              "fail",
-              "Anthropic auth mode is missing or unsupported.",
-              "Rerun init with --auth=<api-key|oauth|wif|bedrock|vertex>.",
-            ),
-      );
-      checks.push(
-        manifest.provision
-          ? localCheck("Manifest", "provision", "pass", String(manifest.provision))
-          : localCheck(
-              "Manifest",
-              "provision",
-              "fail",
-              "No provision command configured; the crew will under-verify.",
-              "Set manifest.provision.",
-            ),
-      );
-      checks.push(
-        manifest.checks?.length
-          ? localCheck("Manifest", "checks", "pass", manifest.checks.join(", "))
-          : localCheck(
-              "Manifest",
-              "checks",
-              "fail",
-              "No check commands configured; verify-before-done has nothing to run.",
-              "Set manifest.checks.",
-            ),
-      );
-      if (manifest.preview?.enabled) {
-        const previewValid =
-          typeof manifest.preview.image === "string" &&
-          Number.isInteger(manifest.preview.port) &&
-          (!manifest.preview.readinessPath ||
-            String(manifest.preview.readinessPath).startsWith("/"));
-        checks.push(
-          previewValid
-            ? localCheck(
-                "Manifest",
-                "protected preview",
-                "pass",
-                `${manifest.preview.image}:${manifest.preview.port}${manifest.preview.readinessPath ?? ""}`,
-              )
-            : localCheck(
-                "Manifest",
-                "protected preview",
-                "fail",
-                "Preview image, port, or readiness path is invalid.",
-                "Rerun init with --preview-image, --preview-port, and an optional /readiness path.",
-              ),
-        );
-      }
-    } catch (error) {
-      checks.push(
-        localCheck(
-          "Manifest",
-          ".facility.json",
-          "fail",
-          `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-          "Repair the manifest or rerun `npx @theagilemonkeys/facility init --force`.",
-        ),
-      );
-    }
-  }
-
-  if (existsSync(join(dir, "guards/run.mjs")) && options.runGuards) {
-    const result = spawnSync(process.execPath, ["guards/run.mjs"], { cwd: dir, encoding: "utf8" });
-    checks.push(
-      result.status === 0
-        ? localCheck("Guards", "guards/run.mjs", "pass", "Guards pass")
-        : localCheck(
-            "Guards",
-            "guards/run.mjs",
-            "fail",
-            "Guards failed",
-            "Run `node guards/run.mjs` and fix every reported violation.",
-            `${result.stdout}${result.stderr}`.trim(),
-          ),
-      );
-  } else if (existsSync(join(dir, "guards/run.mjs"))) {
-    checks.push(
-      localCheck(
-        "Guards",
-        "guards/run.mjs",
-        "warn",
-        "Not executed by the static doctor.",
-        "Pass --run-guards only for a trusted checkout, or run `node guards/run.mjs` directly.",
-      ),
-    );
-  }
-
-  const requirements = authRequirements(detectAnthropicAuthMode(manifest, dir));
-  const ghSecrets = options.github
-    ? spawnSync("gh", ["secret", "list"], {
-        cwd: dir,
-        encoding: "utf8",
-        timeout: 10_000,
-      })
-    : undefined;
-  const ghVariables = options.github
-    ? spawnSync("gh", ["variable", "list"], {
-        cwd: dir,
-        encoding: "utf8",
-        timeout: 10_000,
-      })
-    : undefined;
-  const environmentSecrets = new Set();
-  if (options.github) {
-    for (const environment of ["facility-crew", "facility-codex"]) {
-      const result = spawnSync("gh", ["secret", "list", "--env", environment], {
-        cwd: dir,
-        encoding: "utf8",
-        timeout: 10_000,
-      });
-      if (result.status === 0) {
-        for (const name of namesFromGhList(result.stdout)) environmentSecrets.add(name);
-      }
-    }
+  heading("Workspace contract");
+  for (const check of checks) {
+    if (check.ok) ok(`${check.label}: ${check.detail}`);
+    else warn(`${check.label}: ${check.detail}`);
   }
-  const requiredSecrets = new Set(requirements.secrets);
-  if (manifest.engines?.includes("codex")) requiredSecrets.add("OPENAI_API_KEY");
-  if (manifest.preview?.enabled) {
-    for (const name of ["FACILITY_API_URL", "FACILITY_PROJECT_ID", "FACILITY_PREVIEW_KEY"]) {
-      requiredSecrets.add(name);
-    }
-  }
-  if (ghSecrets?.status === 0 && ghVariables?.status === 0) {
-    const secrets = namesFromGhList(ghSecrets.stdout);
-    for (const name of environmentSecrets) secrets.add(name);
-    const variables = namesFromGhList(ghVariables.stdout);
-    for (const name of requiredSecrets) {
-      checks.push(
-        secrets.has(name)
-          ? localCheck("GitHub", name, "pass", "Secret exists")
-          : localCheck("GitHub", name, "fail", "Secret not found", credentialRemediation(name, requirements.remediation)),
-      );
-    }
-    for (const name of requirements.variables) {
-      checks.push(
-        variables.has(name)
-          ? localCheck("GitHub", name, "pass", "Variable exists")
-          : localCheck("GitHub", name, "fail", "Variable not found", requirements.remediation),
-      );
-    }
-    checks.push(githubBranchProtectionCheck(dir, manifest));
-  } else if (options.github) {
-    checks.push(
-      localCheck(
-        "GitHub",
-        "automation credentials",
-        "warn",
-        "Could not query secrets and variables because gh is unavailable or unauthenticated.",
-        "Verify the required repo/org credentials manually.",
-      ),
-    );
-  } else {
-    for (const name of requiredSecrets) {
-      checks.push(
-        localCheck(
-          "GitHub",
-          name,
-          "warn",
-          "Secret not queried by the offline doctor.",
-          "Pass --github to query with gh, or verify it manually.",
-        ),
-      );
-    }
-    for (const name of requirements.variables) {
-      checks.push(
-        localCheck(
-          "GitHub",
-          name,
-          "warn",
-          "Variable not queried by the offline doctor.",
-          "Pass --github to query with gh, or verify it manually.",
-        ),
-      );
-    }
-  }
-  const manual = [
-    "Claude GitHub App installed on the repo",
-    ...(options.github ? [] : ["default branch protected: PR + 1 human review required"]),
-    "provider TEST keys (if any) live in the facility-crew Environment",
-  ];
-  const problems = checks.filter((check) => check.status === "fail").length;
-  return { ok: problems === 0, mode: "local", directory: dir, problems, checks, manual };
+  item(result.ok ? "Facility can create a story workspace from this repository." : `${problems} problem${problems === 1 ? "" : "s"} found.`);
+  return result.ok ? 0 : 1;
 }
 
-function credentialRemediation(name, authRemediation) {
-  if (name === "OPENAI_API_KEY") {
-    return "store a dedicated, spend-capped key in the facility-codex environment";
-  }
-  if (name.startsWith("FACILITY_")) {
-    return "configure the Facility API URL, project id, and project-scoped preview key together";
+function checkProjectManifest(dir) {
+  const path = join(dir, ".facility.yml");
+  if (!existsSync(path)) return failed("start command", ".facility.yml is missing");
+  const source = readFileSync(path, "utf8");
+  if (!/^version:\s*1\s*$/m.test(source)) return failed("start command", "version must be 1");
+  if (!/^\s{2}primary:\s*["']?github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+["']?\s*$/m.test(source)) {
+    return failed("start command", "repositories.primary must be github.com/owner/repository");
   }
-  return authRemediation;
-}
-
-function githubBranchProtectionCheck(dir, manifest) {
-  const repo = spawnSync("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], {
-    cwd: dir,
-    encoding: "utf8",
-    timeout: 10_000,
-  });
-  const nameWithOwner = repo.stdout.trim();
-  if (repo.status !== 0 || !nameWithOwner) {
-    return localCheck(
-      "GitHub",
-      "branch protection",
-      "warn",
-      "Could not resolve the GitHub repository.",
-      "Run gh auth login and verify branch protection manually.",
-    );
+  if (!/^\s{2}start:\s*["']?.+$/m.test(source)) return failed("start command", "environment.start is missing");
+  const servicePort = /^\s{6}port:\s*([1-9]\d{0,4})\s*$/m.exec(source);
+  if (!servicePort || Number(servicePort[1]) > 65_535) {
+    return failed("start command", "a service port between 1 and 65535 is required");
   }
-  const branch = String(manifest.defaultBranch || "main");
-  const protection = spawnSync(
-    "gh",
-    ["api", `repos/${nameWithOwner}/branches/${encodeURIComponent(branch)}/protection`],
-    { cwd: dir, encoding: "utf8", timeout: 10_000 },
-  );
-  return protection.status === 0
-    ? localCheck("GitHub", `${branch} branch protection`, "pass", "Protection is enabled")
-    : localCheck(
-        "GitHub",
-        `${branch} branch protection`,
-        "fail",
-        "Protection could not be verified.",
-        "Require pull requests and at least one human approval on the default branch.",
-      );
-}
-
-function localCheck(section, label, status, message, remediation, detail) {
-  return {
-    section,
-    label,
-    status,
-    message,
-    ...(remediation ? { remediation } : {}),
-    ...(detail ? { detail } : {}),
-  };
+  return passed("start command", ".facility.yml declares the repository and development environment");
 }
 
-function renderLocalReport(report) {
-  for (const section of ["Files", "Manifest", "Guards", "GitHub"]) {
-    heading(section === "GitHub" ? "GitHub side (verify by hand or with gh)" : section);
-    for (const check of report.checks.filter((candidate) => candidate.section === section)) {
-      const message = `${check.label}${check.message && check.message !== "Present" ? ` — ${check.message}` : ""}${
-        check.remediation ? ` — ${check.remediation}` : ""
-      }`;
-      if (check.status === "pass") ok(message);
-      else if (check.status === "warn") warn(message);
-      else fail(message);
-      if (check.detail) {
-        console.log(
-          check.detail
-            .split("\n")
-            .map((line) => `      ${line}`)
-            .join("\n"),
-        );
-      }
-    }
-  }
-  for (const line of report.manual) item(dim(`  · ${line}`));
+function checkAgent(dir, name) {
+  const relative = `.agents/${name}.md`;
+  const path = join(dir, relative);
+  if (!existsSync(path)) return failed(relative, "missing");
+  const source = readFileSync(path, "utf8").replace(/\r\n?/g, "\n");
+  if (!source.startsWith("---\n") || !/\n---\n[\s\S]*\S/.test(source)) return failed(relative, "invalid frontmatter or empty prompt");
+  if (!new RegExp(`^name:\\s*${escapeRegExp(name)}\\s*$`, "m").test(source)) return failed(relative, `name must be ${name}`);
+  if (!/^engine:\s*(?:claude_code|codex)\s*$/m.test(source)) return failed(relative, "engine must be claude_code or codex");
+  if (!/^model:\s*\S+\s*$/m.test(source)) return failed(relative, "model is missing");
+  if (!/^triggers:\s*$/m.test(source) || !/^\s{2}- type:\s*(?:manual|schedule|github)\s*$/m.test(source)) {
+    return failed(relative, "at least one supported trigger is required");
+  }
+  if (/^(?:permissions|sandbox|tools):/m.test(source)) return failed(relative, "per-agent access controls are not supported");
+  return passed(relative, "valid agent manifest");
 }
 
-function detectAnthropicAuthMode(manifest, dir) {
-  const configured = manifest.auth?.provider === "anthropic" ? manifest.auth.mode : undefined;
-  if (["api-key", "oauth", "wif", "bedrock", "vertex"].includes(configured)) return configured;
-
-  const workflowPath = join(dir, ".github/workflows/facility-crew.yml");
-  if (!existsSync(workflowPath)) return undefined;
-  const workflow = readFileSync(workflowPath, "utf8");
-  if (workflow.includes("anthropic_federation_rule_id:")) return "wif";
-  if (workflow.includes("use_bedrock:")) return "bedrock";
-  if (workflow.includes("use_vertex:")) return "vertex";
-  if (workflow.includes("anthropic_api_key:")) return "api-key";
-  if (workflow.includes("claude_code_oauth_token:")) return "oauth";
-  return undefined;
+function passed(label, detail) {
+  return { label, ok: true, detail };
 }
 
-function authRequirements(mode) {
-  if (mode === "api-key") {
-    return {
-      secrets: ["ANTHROPIC_API_KEY"],
-      variables: [],
-      remediation: "store a dedicated, spend-capped test key",
-    };
-  }
-  if (mode === "oauth") {
-    return {
-      secrets: ["CLAUDE_CODE_OAUTH_TOKEN"],
-      variables: [],
-      remediation: "run `claude setup-token`, then store the token",
-    };
-  }
-  if (mode === "wif") {
-    return {
-      secrets: [],
-      variables: ["ANTHROPIC_FEDERATION_RULE_ID", "ANTHROPIC_ORGANIZATION_ID"],
-      remediation: "configure Anthropic Workload Identity Federation",
-    };
-  }
-  if (mode === "bedrock") {
-    return {
-      secrets: ["AWS_ROLE_TO_ASSUME"],
-      variables: ["AWS_REGION"],
-      remediation: "configure the AWS GitHub OIDC role and Bedrock region",
-    };
-  }
-  if (mode === "vertex") {
-    return {
-      secrets: [],
-      variables: ["GCP_WORKLOAD_IDENTITY_PROVIDER", "GCP_SERVICE_ACCOUNT"],
-      remediation: "configure Google Workload Identity Federation for Vertex AI",
-    };
-  }
-  return { secrets: [], variables: [], remediation: "select a supported auth mode" };
-}
-
-function namesFromGhList(output) {
-  return new Set(
-    output
-      .split("\n")
-      .map((line) => line.trim().split(/\s+/)[0])
-      .filter(Boolean),
-  );
-}
-
-function platformTarget(flags, options) {
-  if (!flags.platform && !flags.profile && !flags.url && !flags.key) return null;
-  if (flags.url || flags.key) {
-    if (!flags.url || !flags.key) return null;
-    return { url: stripSlash(flags.url), key: flags.key, profileName: flags.profile || "adhoc" };
-  }
-  const configPath = options.configPath || options.env?.FACILITY_CONFIG || process.env.FACILITY_CONFIG;
-  const config = options.config || loadConfig(configPath);
-  const { name, value } = getProfile(config, flags.profile);
-  if (!value?.url || !value?.key) return null;
-  return {
-    url: stripSlash(value.url),
-    key: value.key,
-    profileName: name,
-    allowInsecure: value.allowInsecure === true,
-  };
-}
-
-async function platformDoctor(flags, version, target, options) {
-  const stdout = options.stdout || process.stdout;
-  const fetchImpl = options.fetch || fetch;
-  const write = (line = "") => stdout.write(`${line}\n`);
-  if (!flags.json) {
-    write("");
-    write(`  ${bold("facility")} ${dim(`v${version}`)} ${dim("— deployment readiness doctor")}`);
-    write("");
-    write(`  ${bold("Profile")}  ${target.profileName}`);
-    write(`  ${bold("API")}      ${target.url}`);
-    write("");
-  }
-  try {
-    assertSafePlatformUrl(target.url, flags, target.allowInsecure);
-    const payload = await requestDoctor(fetchImpl, target, doctorTimeoutMs(flags.timeout));
-    if (flags.json) {
-      write(
-        JSON.stringify({
-          mode: "platform",
-          target: { profile: target.profileName, url: target.url },
-          ...payload,
-        }),
-      );
-      return payload.ok ? 0 : 1;
-    }
-    write(bold("Readiness"));
-    for (const check of payload.checks || []) {
-      const marker =
-        check.status === "pass" ? green("✓") : check.status === "warn" ? yellow("!") : red("✗");
-      write(`  ${marker} ${check.label}`);
-      write(`    ${dim(check.message)}`);
-      if (check.remediation) write(`    ${bold("Fix:")} ${check.remediation}`);
-    }
-    write("");
-    write(payload.ok ? "Ready for production traffic." : "Not ready for production traffic.");
-    write("");
-    return payload.ok ? 0 : 1;
-  } catch (error) {
-    if (flags.json) {
-      write(JSON.stringify({
-        mode: "platform",
-        target: { profile: target.profileName, url: target.url },
-        ok: false,
-        checks: [],
-        error: {
-          code: error.status === 401 ? "unauthorized" : error.code || "doctor_failed",
-          message: error.message || "facility doctor failed",
-          ...(error.status ? { status: error.status } : {}),
-        },
-      }));
-    } else write(error.message || "facility doctor failed");
-    return error.status === 401 ? 2 : 1;
-  }
-}
-
-function assertSafePlatformUrl(value, flags, profileAllowsInsecure = false) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    throw new Error("Facility API URL must be a valid absolute URL");
-  }
-  const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(parsed.hostname);
-  if (
-    parsed.protocol !== "https:" &&
-    !local &&
-    !flags["allow-insecure"] &&
-    !profileAllowsInsecure
-  ) {
-    const error = new Error(
-      "Refusing to send an API key over plain HTTP. Use HTTPS or pass --allow-insecure for a trusted development endpoint.",
-    );
-    error.code = "insecure_api_url";
-    throw error;
-  }
-}
-
-async function requestDoctor(fetchImpl, target, timeoutMs) {
-  const response = await fetchImpl(new URL(`${target.url}/v1/admin/doctor`), {
-    method: "GET",
-    headers: { authorization: `Bearer ${target.key}` },
-    signal: AbortSignal.timeout(timeoutMs),
-  });
-  const payload = await response.json().catch(() => undefined);
-  if (!payload || typeof payload !== "object") {
-    throw new Error("Facility API returned an invalid JSON response");
-  }
-  if (!response.ok) {
-    const error = new Error(payload?.error?.message || `Facility API returned ${response.status}`);
-    error.status = response.status;
-    throw error;
-  }
-  if (typeof payload.ok !== "boolean" || !Array.isArray(payload.checks)) {
-    throw new Error("Facility API returned an invalid doctor response");
-  }
-  return payload;
-}
-
-function doctorTimeoutMs(value) {
-  if (value === undefined) return 30_000;
-  const seconds = Number(value);
-  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 300) {
-    const error = new Error("--timeout must be greater than 0 and at most 300 seconds");
-    error.code = "invalid_flag";
-    throw error;
-  }
-  return Math.round(seconds * 1_000);
+function failed(label, detail) {
+  return { label, ok: false, detail };
 }
 
-function stripSlash(value) {
-  return String(value).replace(/\/$/, "");
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }