headlesscode 1.0.2

package/src/deploy/gate-cli.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env tsx
+/**
+ * gate-cli.ts — tiny CLI wrapper around the deploy-gate decision logic
+ * (src/deploy/gate.ts). scripts/deploy-gate.sh calls this to decide approval,
+ * keeping the pure decision logic in TypeScript (unit-tested) and the bash
+ * wrapper thin (UI + path safety + invoking the deploy script).
+ *
+ * Usage:
+ *   node --import tsx src/deploy/gate-cli.ts \
+ *     --repo <path> [--batch <name>] [--notes <file>] [--state <file>] \
+ *     [--token-file <path>] [--approval-file <path>] \
+ *     [--interactive] [--interactive-input <text>]
+ *
+ * Environment:
+ *   DEPLOY_APPROVAL_TOKEN   the token to match against the token file
+ *   DEPLOY_APPROVAL_FILE    fallback for --approval-file
+ *
+ * Output (parsed by the bash wrapper):
+ *   DEPLOY_SUMMARY_BEGIN
+ *   <multi-line deployment summary>
+ *   DEPLOY_SUMMARY_END
+ *   DEPLOY_APPROVED=yes|no
+ *   DEPLOY_REASON=<reason>
+ *
+ * Exit code: 0 when approved, 3 when denied (the gate's "hard stop" code).
+ */
+
+import * as path from "node:path"
+
+import { buildDeploySummary, evaluateApproval } from "./gate.js"
+
+interface CliArgs {
+	repo: string
+	batch?: string
+	notes?: string
+	state?: string
+	tokenFile?: string
+	approvalFile?: string
+	interactive: boolean
+	interactiveInput?: string
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = { repo: "", interactive: false }
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		const next = (): string | undefined => {
+			const v = argv[i + 1]
+			if (v === undefined || v.startsWith("--")) {
+				return undefined
+			}
+			i++
+			return v
+		}
+		switch (arg) {
+			case "--repo":
+			case "--batch":
+			case "--notes":
+			case "--state":
+			case "--token-file":
+			case "--approval-file":
+			case "--interactive-input": {
+				const v = next()
+				if (v === undefined) {
+					throw new Error(`Missing value for ${arg}`)
+				}
+				switch (arg) {
+					case "--repo":
+						args.repo = v
+						break
+					case "--batch":
+						args.batch = v
+						break
+					case "--notes":
+						args.notes = v
+						break
+					case "--state":
+						args.state = v
+						break
+					case "--token-file":
+						args.tokenFile = v
+						break
+					case "--approval-file":
+						args.approvalFile = v
+						break
+					case "--interactive-input":
+						args.interactiveInput = v
+						break
+				}
+				break
+			}
+			case "--interactive":
+				args.interactive = true
+				break
+			case "--help":
+			case "-h":
+				console.error(
+					"gate-cli.ts --repo <path> [--batch <name>] [--notes <file>] [--state <file>] [--token-file <path>] [--approval-file <path>] [--interactive] [--interactive-input <text>]",
+				)
+				process.exit(0)
+				break
+			default:
+				throw new Error(`Unknown argument: ${arg}`)
+		}
+	}
+	return args
+}
+
+function main(): void {
+	const args = parseArgs(process.argv.slice(2))
+	if (!args.repo) {
+		throw new Error("--repo <path> is required")
+	}
+
+	// Default artifact paths inside the target repo (mirror scripts/deploy-gate.sh).
+	const tokenFile = args.tokenFile ?? path.join(args.repo, ".deploy-approval")
+	const batch = args.batch ?? "round"
+	const approvalFile =
+		args.approvalFile ??
+		process.env.DEPLOY_APPROVAL_FILE ??
+		path.join(args.repo, ".worktrees", `.deploy-approved-${batch}`)
+	const statePath = args.state ?? path.join(args.repo, ".worktrees", ".orchestrator-state.json")
+
+	// 1. Deployment summary (what's being deployed).
+	const summary = buildDeploySummary({
+		repo: args.repo,
+		batch,
+		notesPath: args.notes,
+		statePath,
+	})
+	process.stdout.write(`DEPLOY_SUMMARY_BEGIN\n${summary}\nDEPLOY_SUMMARY_END\n`)
+
+	// 2. Approval decision (pure logic; file reads happen in evaluateApproval).
+	const result = evaluateApproval({
+		interactive: args.interactive,
+		interactiveInput: args.interactiveInput,
+		approvalToken: process.env.DEPLOY_APPROVAL_TOKEN,
+		tokenFile,
+		approvalFile,
+	})
+
+	process.stdout.write(`DEPLOY_APPROVED=${result.approved ? "yes" : "no"}\n`)
+	process.stdout.write(`DEPLOY_REASON=${result.reason.replace(/\n/g, " ")}\n`)
+	process.exitCode = result.approved ? 0 : 3
+}
+
+main()

package/src/deploy/gate.ts

@@ -0,0 +1,254 @@
+/**
+ * Human-approval deploy gate — pure decision logic (Phase 4).
+ *
+ * The gate exists because deploy-production.sh pushes to production (GitHub
+ * Actions triggers / direct SSH deploys to Hetzner). That must never happen
+ * without an explicit human decision — NOT an automated "approved because
+ * everything passed" rule. The orchestrator may only run the repo's deploy
+ * script AFTER this gate returns approved.
+ *
+ * Two approval modes (documented in docs/phase4-deploy-gate.md):
+ *
+ *   - INTERACTIVE: a human answers "Approve deploy? [y/N]" on a TTY. Any
+ *     explicit yes (y/yes, case-insensitive) approves; everything else
+ *     (including empty input) denies.
+ *   - NON-INTERACTIVE (token/file): exactly ONE of:
+ *       (a) a one-time approval FILE created by a human, e.g.
+ *           `touch <repo>/.worktrees/.deploy-approved-<batch>` — its mere
+ *           presence is the human's explicit action (it does not exist until
+ *           a human creates it);
+ *       (b) an env token `DEPLOY_APPROVAL_TOKEN` that strictly matches the
+ *           token stored in a file like `<repo>/.deploy-approval`.
+ *     If neither is present, or the token does not match, approval is DENIED.
+ *
+ * Never auto-approve: with no interactive input, no approval file, and no
+ * matching token, the answer is always denied.
+ *
+ * The decision itself lives in `decideApproval` (pure, unit-tested). The
+ * I/O wrapper `evaluateApproval` reads the token/approval files and delegates
+ * to it — this is what the bash wrapper (scripts/deploy-gate.sh) calls via
+ * the tiny CLI (src/deploy/gate-cli.ts), keeping the logic testable without
+ * a network or git.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+/** Everything `decideApproval` needs — resolved values, no file I/O. */
+export interface ApprovalInputs {
+	/** True when the caller wants interactive (TTY) approval. */
+	interactive: boolean
+	/** The line a human typed at the prompt (undefined when not interactive). */
+	interactiveInput?: string
+	/** Value of the DEPLOY_APPROVAL_TOKEN env var (undefined when unset). */
+	approvalToken?: string
+	/** Contents of the token file (e.g. <repo>/.deploy-approval), trimmed. */
+	tokenFileContent?: string
+	/** True when a human-created one-time approval file exists. */
+	approvalFileExists: boolean
+}
+
+export interface ApprovalResult {
+	approved: boolean
+	/** Human-readable reason, safe to print to the operator. */
+	reason: string
+}
+
+/** Interactive input counts as approval only for an explicit yes. */
+function isExplicitYes(input: string): boolean {
+	return /^\s*y(?:es)?\s*$/i.test(input)
+}
+
+/**
+ * PURE decision function — unit-tested without any file system.
+ *
+ * Rules (fail-closed):
+ *   1. Interactive + explicit yes  → approved.
+ *   2. Interactive + anything else → denied (empty, "n", "maybe", …).
+ *   3. Non-interactive + one-time approval FILE present → approved.
+ *   4. Non-interactive + approvalToken AND tokenFileContent set AND they
+ *      match exactly (trimmed) → approved.
+ *   5. Everything else → denied with a reason explaining what was missing.
+ *
+ * Interactive mode takes precedence when both interactive and a token are
+ * configured (the operator is at the keyboard — their answer is what counts).
+ */
+export function decideApproval(inputs: ApprovalInputs): ApprovalResult {
+	if (inputs.interactive) {
+		if (inputs.interactiveInput !== undefined && isExplicitYes(inputs.interactiveInput)) {
+			return { approved: true, reason: "approved interactively (explicit yes at the prompt)" }
+		}
+		return {
+			approved: false,
+			reason:
+				inputs.interactiveInput === undefined
+					? "DENIED: interactive approval requires an explicit yes ('y'/'yes'); no answer was received"
+					: `DENIED: interactive approval requires an explicit yes ('y'/'yes'); got '${inputs.interactiveInput.trim() || "(empty)"}'`,
+		}
+	}
+
+	if (inputs.approvalFileExists) {
+		return { approved: true, reason: "approved by a human-created one-time approval file" }
+	}
+
+	if (inputs.approvalToken !== undefined && inputs.tokenFileContent !== undefined) {
+		if (inputs.approvalToken.trim() !== "" && inputs.approvalToken.trim() === inputs.tokenFileContent.trim()) {
+			return { approved: true, reason: "approved: DEPLOY_APPROVAL_TOKEN matched the token file" }
+		}
+		if (inputs.approvalToken.trim() === "") {
+			return {
+				approved: false,
+				reason: "DENIED: DEPLOY_APPROVAL_TOKEN is set but empty — no token to match",
+			}
+		}
+		return {
+			approved: false,
+			reason: "DENIED: DEPLOY_APPROVAL_TOKEN does not match the token in the approval file",
+		}
+	}
+
+	if (inputs.approvalToken !== undefined && inputs.tokenFileContent === undefined) {
+		return {
+			approved: false,
+			reason: "DENIED: DEPLOY_APPROVAL_TOKEN is set but no token file was found to match against",
+		}
+	}
+	if (inputs.approvalToken === undefined && inputs.tokenFileContent !== undefined) {
+		return {
+			approved: false,
+			reason: "DENIED: a token file exists but DEPLOY_APPROVAL_TOKEN is not set",
+		}
+	}
+	return {
+		approved: false,
+		reason:
+			"DENIED: no interactive input, no one-time approval file, and no matching DEPLOY_APPROVAL_TOKEN — a deploy gate can never auto-approve",
+	}
+}
+
+export interface EvaluateApprovalOptions {
+	interactive: boolean
+	interactiveInput?: string
+	approvalToken?: string
+	/** Path to the token file (e.g. <repo>/.deploy-approval). */
+	tokenFile?: string
+	/** Path to the one-time approval file (e.g. <repo>/.worktrees/.deploy-approved-<batch>). */
+	approvalFile?: string
+}
+
+/** Read token/approval files (if any) and delegate to the pure decision. */
+export function evaluateApproval(options: EvaluateApprovalOptions): ApprovalResult {
+	let tokenFileContent: string | undefined
+	if (options.tokenFile) {
+		try {
+			tokenFileContent = fs.readFileSync(options.tokenFile, "utf-8").trim()
+		} catch {
+			tokenFileContent = undefined // missing file = no token to match
+		}
+	}
+
+	let approvalFileExists = false
+	if (options.approvalFile) {
+		try {
+			approvalFileExists = fs.statSync(options.approvalFile).isFile()
+		} catch {
+			approvalFileExists = false
+		}
+	}
+
+	return decideApproval({
+		interactive: options.interactive,
+		interactiveInput: options.interactiveInput,
+		approvalToken: options.approvalToken,
+		tokenFileContent,
+		approvalFileExists,
+	})
+}
+
+// ─── Deployment summary (what would be deployed) ────────────────────────────
+
+export interface DeploySummaryOptions {
+	/** Target repo root (shown in the summary header). */
+	repo: string
+	/** Batch id (default: derived from the state file or "unnamed"). */
+	batch?: string
+	/** Optional deployment notes file; shown verbatim when present. */
+	notesPath?: string
+	/** Orchestrator state file (`.worktrees/.orchestrator-state.json`). */
+	statePath?: string
+}
+
+/**
+ * Build the human-readable deployment summary printed by the gate BEFORE
+ * asking for approval. Sources, in priority order:
+ *   1. A provided/generated notes file (verbatim).
+ *   2. The orchestrator state file's batch + per-group summary.
+ *   3. A generic line (nothing to summarize).
+ */
+export function buildDeploySummary(options: DeploySummaryOptions): string {
+	const lines: string[] = []
+	lines.push(`Target repo: ${options.repo}`)
+
+	if (options.notesPath) {
+		try {
+			const notes = fs.readFileSync(options.notesPath, "utf-8").trim()
+			if (notes) {
+				lines.push("")
+				lines.push(notes)
+				return lines.join("\n")
+			}
+		} catch {
+			lines.push(`(notes file not readable: ${options.notesPath})`)
+		}
+	}
+
+	if (options.statePath) {
+		try {
+			const raw = fs.readFileSync(options.statePath, "utf-8")
+			const state = JSON.parse(raw) as {
+				batch?: string
+				groups?: Array<{
+					name?: string
+					status?: string
+					issues?: number[]
+					review_verdict?: string
+					qa?: { verdict?: string }
+				}>
+			}
+			const batch = options.batch ?? state.batch ?? "unnamed"
+			lines.push(`Batch: ${batch}`)
+			const groups = Array.isArray(state.groups) ? state.groups : []
+			if (groups.length === 0) {
+				lines.push("(no groups recorded in the orchestrator state file)")
+			} else {
+				lines.push(`Groups (${groups.length}):`)
+				for (const g of groups) {
+					const issues = Array.isArray(g.issues) && g.issues.length > 0 ? ` issues ${g.issues.join(",")}` : ""
+					const review = g.review_verdict ? ` review=${g.review_verdict}` : ""
+					const qa = g.qa?.verdict ? ` qa=${g.qa.verdict}` : ""
+					lines.push(`  - ${g.name ?? "(unnamed)"}: status=${g.status ?? "?"}${issues}${review}${qa}`)
+				}
+			}
+			return lines.join("\n")
+		} catch {
+			// fall through to generic
+		}
+	}
+
+	lines.push(options.batch ? `Batch: ${options.batch}` : "Batch: (not provided)")
+	lines.push("(no deployment notes and no orchestrator state file available — nothing to summarize)")
+	return lines.join("\n")
+}
+
+/**
+ * Default paths for the gate artifacts inside a target repo.
+ *   - token file:  <repo>/.deploy-approval
+ *   - approval:    <repo>/.worktrees/.deploy-approved-<batch>
+ */
+export function defaultTokenFile(repo: string): string {
+	return path.join(repo, ".deploy-approval")
+}
+
+export function defaultApprovalFile(repo: string, batch: string): string {
+	return path.join(repo, ".worktrees", `.deploy-approved-${batch}`)
+}