@a2f0/agent-tool 0.1.1

package/src/config.ts

@@ -0,0 +1,101 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export interface RequiredCheck {
+  name: string;
+  workflow?: string;
+}
+
+export interface AgentToolConfig {
+  schemaVersion: 1;
+  subject: { conventional: boolean; maxLength: number; types: string[] };
+  merge: { requireChecks: boolean; requiredChecks: RequiredCheck[]; requireStrictBaseFreshness: boolean };
+  review: { claudeModel: string | null; codexModel: string | null; opencodeModel: string; opencodeVariants: Record<string, string>; timeoutMs: number };
+  versions: { packages: string[] | null; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
+  pr: { rejectClaudeBranding: boolean };
+}
+
+export const DEFAULT_CONFIG: AgentToolConfig = {
+  schemaVersion: 1,
+  subject: {
+    conventional: true,
+    maxLength: 72,
+    types: ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
+  },
+  merge: { requireChecks: true, requiredChecks: [], requireStrictBaseFreshness: false },
+  review: { claudeModel: null, codexModel: null, opencodeModel: "deepseek/deepseek-v4-pro", opencodeVariants: { low: "low", medium: "medium", high: "high", xhigh: "max", max: "max" }, timeoutMs: 600_000 },
+  versions: { packages: null, lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
+  pr: { rejectClaudeBranding: false },
+};
+
+function object(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${name} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function keys(value: Record<string, unknown>, allowed: string[], name: string): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new Error(`Unknown ${name} setting '${key}'.`);
+  }
+}
+
+function strings(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
+}
+
+/** Data-only policy: never import repository JavaScript or commitlint code. */
+export function parseConfig(source: string): AgentToolConfig {
+  const input = object(JSON.parse(source), "config");
+  keys(input, Object.keys(DEFAULT_CONFIG), "config");
+  if (input.schemaVersion !== 1) throw new Error("Unsupported config schemaVersion; expected 1.");
+  const result = structuredClone(DEFAULT_CONFIG);
+  for (const section of ["subject", "merge", "review", "versions", "pr"] as const) {
+    if (input[section] === undefined) continue;
+    const settings = object(input[section], section);
+    keys(settings, Object.keys(result[section]), section);
+    Object.assign(result[section], settings);
+  }
+  const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };
+  if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");
+  if (!Number.isSafeInteger(result.subject.maxLength) || result.subject.maxLength < 1) invalid("subject.maxLength");
+  if (!strings(result.subject.types) || result.subject.types.length === 0 || result.subject.types.some(type => !/^[a-z]+$/.test(type))) invalid("subject.types");
+  if (typeof result.merge.requireChecks !== "boolean") invalid("merge.requireChecks");
+  if (!Array.isArray(result.merge.requiredChecks)) invalid("merge.requiredChecks");
+  if (typeof result.merge.requireStrictBaseFreshness !== "boolean") invalid("merge.requireStrictBaseFreshness");
+  for (const check of result.merge.requiredChecks) {
+    const entry = object(check, "merge.requiredChecks entry");
+    keys(entry, ["name", "workflow"], "merge.requiredChecks entry");
+    if (typeof check.name !== "string" || !check.name.trim() || (check.workflow !== undefined && (typeof check.workflow !== "string" || !check.workflow.trim()))) invalid("merge.requiredChecks");
+  }
+  for (const key of ["claudeModel", "codexModel"] as const) {
+    if (result.review[key] !== null && (typeof result.review[key] !== "string" || !/^[^\s]+$/.test(result.review[key]!))) invalid(`review.${key}`);
+  }
+  const variants = object(result.review.opencodeVariants, "review.opencodeVariants");
+  keys(variants, ["low", "medium", "high", "xhigh", "max"], "review.opencodeVariants");
+  for (const value of Object.values(variants)) if (typeof value !== "string" || !/^[^\s]+$/.test(value)) invalid("review.opencodeVariants");
+  if (typeof result.review.opencodeModel !== "string" || !/^[^\s/]+\/[^\s]+$/.test(result.review.opencodeModel)) invalid("review.opencodeModel");
+  if (!Number.isSafeInteger(result.review.timeoutMs) || result.review.timeoutMs < 1000 || result.review.timeoutMs > 3_600_000) invalid("review.timeoutMs");
+  if (result.versions.packages !== null) {
+    if (!strings(result.versions.packages) || result.versions.packages.some(dir => dir !== "." && (path.isAbsolute(dir) || dir.includes("\\") || dir.split("/").some(part => !part || part === "." || part === "..")))) invalid("versions.packages");
+  }
+  if (result.versions.lockfile !== null && result.versions.lockfile !== "bun.lock") invalid("versions.lockfile");
+  // Commands are argv arrays resolved on PATH outside the repository; no shell.
+  if (!Array.isArray(result.versions.validate) || result.versions.validate.some(command => !strings(command) || command.length === 0 || !/^[\w.+-]+$/.test(command[0]!))) invalid("versions.validate");
+  if (typeof result.versions.commitMessage !== "string" || !result.versions.commitMessage.trim() || /[\r\n]/.test(result.versions.commitMessage)) invalid("versions.commitMessage");
+  if (typeof result.pr.rejectClaudeBranding !== "boolean") invalid("pr.rejectClaudeBranding");
+  return result;
+}
+
+/** Explicit file wins; project policy is opt-in through agent-tool.json. */
+export function loadConfig(rootDir: string = process.cwd()): AgentToolConfig {
+  const explicit = process.env.AGENT_TOOL_CONFIG;
+  const file = explicit ? path.resolve(explicit) : path.join(rootDir, "agent-tool.json");
+  if (!existsSync(file)) {
+    if (explicit) throw new Error(`Config file does not exist: ${file}`);
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  if (!lstatSync(file).isFile()) throw new Error(`Config must be a regular file: ${file}`);
+  return parseConfig(readFileSync(file, "utf8"));
+}

package/src/doctor.ts

@@ -0,0 +1,23 @@
+import { spawnSync } from "node:child_process";
+import { loadConfig } from "./config";
+
+const specifications = [
+  { name: "git", help: [] as string[], flags: [] as string[] },
+  { name: "gh", help: [] as string[], flags: [] as string[] },
+  { name: "claude", help: ["--help"], flags: ["--safe-mode", "--permission-mode", "--effort"] },
+  { name: "codex", help: ["exec", "--help"], flags: ["--ignore-user-config", "--ignore-rules", "--strict-config", "--ephemeral", "--output-last-message"] },
+  { name: "opencode", help: ["run", "--help"], flags: ["--pure", "--variant", "--agent"] },
+];
+
+/** Probe only local versions and flags; never launch a model or print credentials. */
+export function doctor(rootDir: string): { schemaVersion: 1; config: ReturnType<typeof loadConfig>; tools: { name: string; version: string; compatible: boolean; missingFlags: string[] }[] } {
+  const config = loadConfig(rootDir);
+  const tools = specifications.map(spec => {
+    const version = spawnSync(spec.name, ["--version"], { encoding: "utf8", timeout: 3000, maxBuffer: 256 * 1024 });
+    const help = spec.flags.length ? spawnSync(spec.name, spec.help, { encoding: "utf8", timeout: 3000, maxBuffer: 256 * 1024 }) : undefined;
+    const helpText = `${help?.stdout ?? ""}\n${help?.stderr ?? ""}`;
+    const missingFlags = spec.flags.filter(flag => !helpText.includes(flag));
+    return { name: spec.name, version: version.stdout?.trim() || "unavailable", compatible: version.status === 0 && (!help || help.status === 0) && missingFlags.length === 0, missingFlags };
+  });
+  return { schemaVersion: 1, config, tools };
+}

package/src/git/currentBranchPr.ts

@@ -0,0 +1,114 @@
+import { spawnSync } from "node:child_process";
+
+interface CurrentBranchPr {
+  readonly baseRefName: string;
+  readonly branch: string;
+  readonly prNumber: string;
+  readonly repo: string;
+  readonly title: string;
+}
+
+interface CommandResult {
+  readonly error?: Error;
+  readonly signal: string | null;
+  readonly status: number | null;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+
+type CommandRunner = (command: string, args: string[]) => CommandResult;
+
+function runWithResult(command: string, args: string[]): CommandResult {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const output = {
+    status: result.status,
+    signal: result.signal,
+    stderr: result.stderr,
+    stdout: result.stdout,
+  };
+  return result.error ? { ...output, error: result.error } : output;
+}
+
+function field(source: string, key: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(source);
+    return typeof parsed === "object" && parsed !== null
+      ? Reflect.get(parsed, key)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringField(source: string, key: string): string {
+  const value = field(source, key);
+  return typeof value === "string" ? value : "";
+}
+
+function numberField(source: string, key: string): string {
+  const value = field(source, key);
+  return typeof value === "number" ? String(value) : "";
+}
+
+export function repoFromPrUrl(prUrl: string): string {
+  try {
+    const segments = new URL(prUrl).pathname.split("/").filter(Boolean);
+    if (segments.length >= 4 && segments[2] === "pull") {
+      return `${segments[0]}/${segments[1]}`;
+    }
+  } catch {
+    // Fall through to the actionable error below.
+  }
+  throw new Error(`Could not resolve the base repository from '${prUrl}'.`);
+}
+
+/** Resolve the current branch's open PR, including one from an upstream fork. */
+export function viewCurrentBranchPr(
+  branch: string,
+  execute: CommandRunner = runWithResult,
+): CurrentBranchPr | undefined {
+  const result = execute("gh", [
+    "pr",
+    "view",
+    "--json",
+    "number,state,title,url,baseRefName",
+  ]);
+  if (result.error) {
+    throw new Error(`Could not run gh pr view: ${result.error.message}`);
+  }
+  if (result.signal !== null) {
+    throw new Error(`gh pr view terminated by signal ${result.signal}.`);
+  }
+  if (result.status !== 0) {
+    const failure = result.stderr.trim();
+    if (failure === `no pull requests found for branch "${branch}"`) {
+      return undefined;
+    }
+    throw new Error(
+      `Could not resolve the current branch's PR: ${failure || "gh pr view failed"}`,
+    );
+  }
+  const state = stringField(result.stdout, "state");
+  if (state === "CLOSED" || state === "MERGED") {
+    return undefined;
+  }
+  if (state !== "OPEN") {
+    throw new Error(`Current branch PR has invalid state '${state}'.`);
+  }
+
+  const prNumber = numberField(result.stdout, "number");
+  const prUrl = stringField(result.stdout, "url");
+  if (prNumber.length === 0 || prUrl.length === 0) {
+    throw new Error("Could not determine the current branch's PR identity.");
+  }
+  return {
+    branch,
+    repo: repoFromPrUrl(prUrl),
+    prNumber,
+    title: stringField(result.stdout, "title"),
+    baseRefName: stringField(result.stdout, "baseRefName"),
+  };
+}

package/src/git/environment.ts

@@ -0,0 +1,10 @@
+/** Disable object substitution and hooks, retaining existing Git config overrides. */
+export function gitEnvironment(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env, GIT_NO_REPLACE_OBJECTS: "1" };
+  const count = Number(env.GIT_CONFIG_COUNT ?? "0");
+  if (!Number.isSafeInteger(count) || count < 0 || count > 1000) throw new Error("Invalid GIT_CONFIG_COUNT.");
+  env.GIT_CONFIG_COUNT = String(count + 1);
+  env[`GIT_CONFIG_KEY_${count}`] = "core.hooksPath";
+  env[`GIT_CONFIG_VALUE_${count}`] = "/dev/null";
+  return env;
+}