@nathapp/nax 0.73.4 → 0.74.0

package/flows/nax-finish/steps/index.ts

@@ -0,0 +1,8 @@
+export * from "./context";
+export * from "./acceptance";
+export * from "./quality";
+export * from "./escalate";
+export * from "./forge";
+export * from "./git";
+export * from "./pr";
+export * from "./result";

package/flows/nax-finish/steps/pr.ts

@@ -0,0 +1,71 @@
+import { FinishError } from "../errors";
+import { runArgv } from "../exec";
+import type { RunFn } from "../types";
+import { type Forge, detectForge, extractUrl, viewArgv } from "./forge";
+
+export const _prDeps: { run: RunFn } = { run: runArgv };
+
+/**
+ * Parse `gh pr view --json isDraft,url` / `glab mr view --output json` stdout.
+ *
+ * GitHub's schema is well-defined: `{ isDraft, url }`. GitLab's `glab mr view --output json`
+ * schema is not guaranteed to expose an equivalent boolean under a stable name across
+ * versions, so this is best-effort: it checks a few plausible field names for draft status
+ * and falls back to treating any successfully-parsed MR as ready (not draft) when none are
+ * found — per the task brief, "treat any successful view as already-ready unless you find
+ * clear evidence otherwise."
+ */
+function parseView(stdout: string, forge: Forge): { isDraft: boolean; url?: string } {
+  try {
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+    if (forge === "github") {
+      return { isDraft: parsed.isDraft === true, url: typeof parsed.url === "string" ? parsed.url : undefined };
+    }
+    const isDraft = parsed.isDraft === true || parsed.draft === true || parsed.work_in_progress === true;
+    return { isDraft, url: extractUrl(stdout) };
+  } catch {
+    return { isDraft: false, url: extractUrl(stdout) };
+  }
+}
+
+export async function openOrPromotePr(
+  repoRoot: string,
+  branch: string,
+  title: string,
+  body: string,
+): Promise<{ status: "opened" | "promoted" | "already-ready"; url?: string }> {
+  const forge = await detectForge(_prDeps.run, repoRoot, "finish-pr");
+  const view = await _prDeps.run(viewArgv(forge, branch, "isDraft,url"), { cwd: repoRoot });
+
+  if (view.exitCode !== 0) {
+    const createCmd =
+      forge === "github"
+        ? ["gh", "pr", "create", "--title", title, "--body", body, "--head", branch]
+        : ["glab", "mr", "create", "--title", title, "--description", body, "--source-branch", branch];
+    const create = await _prDeps.run(createCmd, { cwd: repoRoot });
+    if (create.exitCode !== 0) {
+      throw new FinishError(
+        `Failed to create PR/MR for "${branch}": ${create.stderr.trim() || `exit ${create.exitCode}`}`,
+        "FINISH_PR_CREATE_FAILED",
+        { stage: "finish-pr", branch },
+      );
+    }
+    return { status: "opened", url: extractUrl(create.stdout) };
+  }
+
+  const { isDraft, url } = parseView(view.stdout, forge);
+  if (isDraft) {
+    const readyCmd = forge === "github" ? ["gh", "pr", "ready", branch] : ["glab", "mr", "update", branch, "--ready"];
+    const ready = await _prDeps.run(readyCmd, { cwd: repoRoot });
+    if (ready.exitCode !== 0) {
+      throw new FinishError(
+        `Failed to promote PR/MR "${branch}" to ready: ${ready.stderr.trim() || `exit ${ready.exitCode}`}`,
+        "FINISH_PR_PROMOTE_FAILED",
+        { stage: "finish-pr", branch },
+      );
+    }
+    return { status: "promoted", url };
+  }
+
+  return { status: "already-ready", url };
+}

package/flows/nax-finish/steps/quality.ts

@@ -0,0 +1,93 @@
+import { FinishError } from "../errors";
+import { DEFAULT_GATE_TIMEOUT_MS, runShell } from "../exec";
+import type { ShellRunFn } from "../types";
+
+export interface QualityCommands {
+  build?: string;
+  typecheck?: string;
+  lint?: string;
+  test?: string;
+  format?: string;
+}
+
+export const _qualityDeps: { runShell: ShellRunFn; readText: (path: string) => Promise<string | null> } = {
+  runShell,
+  readText: async (path) => {
+    const file = Bun.file(path);
+    return (await file.exists()) ? await file.text() : null;
+  },
+};
+
+const GATE_ORDER: (keyof QualityCommands)[] = ["build", "typecheck", "lint", "test", "format"];
+
+export interface QualityGateOutcome {
+  passed: boolean;
+  /** Gate names that actually ran — empty means nothing was configured. */
+  ran: string[];
+  failing: string[];
+  output: string;
+}
+
+/**
+ * Run the repo's configured quality commands in order, each through
+ * `/bin/sh -c` (matching `src/quality/runner.ts`) so `&&`, quoting and globs
+ * survive, and each under a wall-clock cap so a hung gate can't stall the flow.
+ *
+ * `passed` is only true when at least one gate ran. A repo with no configured
+ * commands must not report a green gate — that previously let the flow open a
+ * "ready" PR having verified nothing.
+ */
+export async function runQualityGates(
+  repoRoot: string,
+  commands: QualityCommands,
+  opts: { timeoutMs?: number } = {},
+): Promise<QualityGateOutcome> {
+  const failing: string[] = [];
+  const ran: string[] = [];
+  const chunks: string[] = [];
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS;
+  for (const gate of GATE_ORDER) {
+    const command = commands[gate];
+    if (!command) continue;
+    ran.push(gate);
+    const res = await _qualityDeps.runShell(command, { cwd: repoRoot, timeoutMs });
+    chunks.push(`[${gate}] exit=${res.exitCode}\n${res.stdout}\n${res.stderr}`);
+    if (res.exitCode !== 0) failing.push(gate);
+  }
+  if (ran.length === 0) {
+    return {
+      passed: false,
+      ran,
+      failing: [],
+      output: "[quality] no quality.commands configured in .nax/config.json — nothing was verified",
+    };
+  }
+  return { passed: failing.length === 0, ran, failing, output: chunks.join("\n\n") };
+}
+
+/**
+ * Read `quality.commands` from the repo-root `.nax/config.json` only.
+ *
+ * Deliberately root-scoped: per-package `.nax/mono/<pkg>/config.json` overrides
+ * are unreliable as a repo-root gate (a package's own `test` command does not
+ * verify the repo), and this gate runs once at the root by design.
+ */
+export async function loadQualityCommands(workdir: string): Promise<QualityCommands> {
+  const text = await _qualityDeps.readText(`${workdir}/.nax/config.json`);
+  if (!text) return {};
+  let cfg: { quality?: { commands?: QualityCommands } };
+  try {
+    cfg = JSON.parse(text);
+  } catch (cause) {
+    throw new FinishError(
+      "Failed to parse .nax/config.json while loading quality commands",
+      "FINISH_CONFIG_UNPARSEABLE",
+      {
+        stage: "finish-quality",
+        path: `${workdir}/.nax/config.json`,
+        cause,
+      },
+    );
+  }
+  return cfg.quality?.commands ?? {};
+}

package/flows/nax-finish/steps/result.ts

@@ -0,0 +1,15 @@
+import type { FinishResult } from "../types";
+
+export function resultPath(repoRoot: string): string {
+  return `${repoRoot}/.nax/nax-finish-result.json`;
+}
+
+export const _resultDeps: { writeText: (p: string, s: string) => Promise<void> } = {
+  writeText: async (p, s) => {
+    await Bun.write(p, s);
+  },
+};
+
+export async function writeResult(repoRoot: string, result: FinishResult): Promise<void> {
+  await _resultDeps.writeText(resultPath(repoRoot), `${JSON.stringify(result, null, 2)}\n`);
+}

package/flows/nax-finish/types.ts

@@ -0,0 +1,59 @@
+/** One acceptance-test group as reported by `nax features resolve --json`. */
+export interface AcceptanceGroup {
+  packageDir: string;
+  testPath: string;
+  exists: boolean;
+  command?: string;
+  language: string;
+}
+
+export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export interface Finding {
+  severity: Severity;
+  title: string;
+  problem: string;
+  fix: string;
+}
+export interface ReviewVerdict {
+  /**
+   * `clean` is not a model-produced route — the review nodes' `parse` rewrites
+   * `proceed` with zero findings to `clean` so the graph can skip the fix node
+   * entirely instead of prompting an agent to "apply fixes" for nothing.
+   */
+  route: "proceed" | "escalate" | "clean";
+  findings: Finding[];
+  escalationReason?: string;
+}
+/** Wall-clock budgets, forwarded from `finish.autoFlow.timeouts` by the plugin. */
+export interface FinishTimeouts {
+  acceptanceMs?: number;
+  gateMs?: number;
+}
+export interface FinishInput {
+  feature: string;
+  workdir: string;
+  branch: string;
+  prdPath: string;
+  /**
+   * True only when Telegram escalation is both enabled *and* credentialed, as
+   * determined by the plugin. When true the flow skips the PR/MR comment
+   * fallback (and does not open a draft to hold one) — the plugin sends the
+   * Telegram message from the result file instead.
+   */
+  escalateTelegram: boolean;
+  timeouts?: FinishTimeouts;
+}
+export interface FinishResult {
+  feature: string;
+  status: "opened" | "promoted" | "already-ready" | "escalated" | "nothing-to-finish";
+  url?: string;
+  escalationReason?: string;
+}
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut?: boolean;
+}
+export type RunFn = (cmd: string[], opts: { cwd: string; timeoutMs?: number }) => Promise<RunResult>;
+export type ShellRunFn = (command: string, opts: { cwd: string; timeoutMs?: number }) => Promise<RunResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.73.4",
+  "version": "0.74.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
@@ -11,9 +11,9 @@
     "dev": "bun run bin/nax.ts",
     "build": "bun build bin/nax.ts --outdir dist --target bun --define \"GIT_COMMIT=\\\"$(git rev-parse --short HEAD)\\\"\"",
     "typecheck": "bun x tsc --noEmit && bun x tsc --noEmit -p tsconfig.contracts.json",
-    "lint": "bun x biome check src/ bin/ && bun run check:no-real-global-nax && bun run check:alias-internals && bun run check:deep-relatives && bun run check:nax-error && bun run check:logger-storyid && bun run check:log-format-layering && bun run check:file-sizes",
-    "lint:json": "bun x biome check src/ bin/ --reporter json && bun run check:nax-error 1>&2 && bun run check:logger-storyid 1>&2",
-    "lint:fix": "bun x biome check --write src/ bin/",
+    "lint": "bun x biome check src/ bin/ flows/ && bun run check:no-real-global-nax && bun run check:alias-internals && bun run check:deep-relatives && bun run check:nax-error && bun run check:logger-storyid && bun run check:log-format-layering && bun run check:file-sizes",
+    "lint:json": "bun x biome check src/ bin/ flows/ --reporter json && bun run check:nax-error 1>&2 && bun run check:logger-storyid 1>&2",
+    "lint:fix": "bun x biome check --write src/ bin/ flows/",
     "check:no-real-global-nax": "bun run scripts/check-no-real-global-nax.ts",
     "check:alias-internals": "bun run scripts/check-alias-internals.ts",
     "check:deep-relatives": "bun run scripts/check-deep-relatives.ts",
@@ -50,6 +50,7 @@
   },
   "dependencies": {
     "@types/react": "^19.2.14",
+    "acpx": "^0.12.1",
     "chalk": "^5.6.2",
     "commander": "^13.1.0",
     "ink": "^6.7.0",
@@ -75,6 +76,7 @@
   ],
   "files": [
     "dist/",
+    "flows/",
     "README.md",
     "CHANGELOG.md"
   ],