p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/cli/commands/diagnose-vercel-bridge.ts

@@ -0,0 +1,25 @@
+import { buildVercelBridgeDiagnosticReport } from "../../setup/vercel-bridge-diagnostics.js";
+
+export async function runDiagnoseVercelBridgeCommand(options: {
+  cwd?: string;
+  liveProbe?: boolean;
+}): Promise<number> {
+  try {
+    const report = await buildVercelBridgeDiagnosticReport({
+      cwd: options.cwd,
+      liveProbe: options.liveProbe === true,
+    });
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        error:
+          error instanceof Error
+            ? error.message
+            : "Vercel bridge diagnostics failed.",
+      }),
+    );
+    return 1;
+  }
+}

package/workspace-snapshot/files/src/cli/commands/doctor.ts

@@ -0,0 +1,205 @@
+import { access, constants, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { Cursor } from "@cursor/sdk";
+import { loadHarnessConfig, validateRepoClosure } from "../../config/load-config.js";
+import type { HarnessConfig } from "../../config/types.js";
+import {
+  assertBaseBranchExists,
+  assertHeadBranchWritePermission,
+} from "../../github/base-branch.js";
+import { GitHubClient, pingGitHub } from "../../github/client.js";
+import { pingLinear } from "../../linear/client.js";
+import {
+  doctorChecksFailed,
+  formatDoctorCheckLine,
+  type DoctorCheckResult,
+} from "../../setup/doctor-summary.js";
+import { EXIT_CONFIG, EXIT_SUCCESS } from "../exit-codes.js";
+
+export interface DoctorOptions {
+  configPath: string;
+  profile?: "full" | "merge";
+}
+
+export async function runDoctor(options: DoctorOptions): Promise<number> {
+  const profile = options.profile ?? "full";
+  const checks: DoctorCheckResult[] = [];
+  let config: HarnessConfig | null = null;
+
+  try {
+    const loaded = await loadHarnessConfig({ configPath: options.configPath });
+    config = loaded.config;
+    checks.push({
+      label: "harness config valid",
+      ok: true,
+      detail: loaded.source.label,
+    });
+
+    validateRepoClosure(config);
+    checks.push({
+      label: "allowedTargetRepos covers all repo mappings",
+      ok: true,
+    });
+
+    const runsDir = path.resolve(config.logDirectory);
+    await mkdir(runsDir, { recursive: true });
+    await access(runsDir, constants.W_OK);
+    checks.push({
+      label: "runs/ directory writable",
+      ok: true,
+      detail: runsDir,
+    });
+  } catch (error) {
+    checks.push({
+      label: "harness.config.json valid",
+      ok: false,
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (process.env.LINEAR_API_KEY) {
+    try {
+      const name = await pingLinear(process.env.LINEAR_API_KEY);
+      checks.push({
+        label: "LINEAR_API_KEY set",
+        ok: true,
+        detail: `authenticated as ${name}`,
+      });
+    } catch (error) {
+      checks.push({
+        label: "LINEAR_API_KEY set",
+        ok: false,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+  } else {
+    checks.push({
+      label: "LINEAR_API_KEY set",
+      ok: false,
+      detail: "required for live planning runs",
+    });
+  }
+
+  if (process.env.CURSOR_API_KEY) {
+    checks.push({
+      label: "CURSOR_API_KEY set",
+      ok: true,
+    });
+
+    try {
+      const models = await Cursor.models.list({
+        apiKey: process.env.CURSOR_API_KEY,
+      });
+      const count = models.length;
+      checks.push({
+        label: "Cursor models.list()",
+        ok: true,
+        detail: `${count} model(s) available`,
+      });
+    } catch (error) {
+      checks.push({
+        label: "Cursor models.list()",
+        ok: true,
+        detail: `warn: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+
+    try {
+      const repos = await Cursor.repositories.list({
+        apiKey: process.env.CURSOR_API_KEY,
+      });
+      const count = repos.length;
+      checks.push({
+        label: "Cursor repositories.list()",
+        ok: true,
+        detail: `${count} connected repo(s)`,
+      });
+    } catch (error) {
+      checks.push({
+        label: "Cursor repositories.list()",
+        ok: true,
+        detail: `warn: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  } else if (profile === "merge") {
+    checks.push({
+      label: "CURSOR_API_KEY set",
+      ok: true,
+      skipped: true,
+      detail: "required only when merge integration repair needs a Cursor agent",
+    });
+  } else {
+    checks.push({
+      label: "CURSOR_API_KEY set",
+      ok: false,
+      detail: "required for live planning runs",
+    });
+  }
+
+  if (process.env.GITHUB_TOKEN) {
+    try {
+      const login = await pingGitHub(process.env.GITHUB_TOKEN);
+      checks.push({
+        label: "GITHUB_TOKEN set",
+        ok: true,
+        detail: `authenticated as ${login}`,
+      });
+    } catch (error) {
+      checks.push({
+        label: "GITHUB_TOKEN set",
+        ok: false,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    if (config) {
+      const github = new GitHubClient({ token: process.env.GITHUB_TOKEN });
+      for (const repo of config.repos) {
+        try {
+          await assertBaseBranchExists(github, repo.targetRepo, repo.baseBranch);
+          checks.push({
+            label: `${repo.id} base branch exists`,
+            ok: true,
+            detail: `${repo.targetRepo}#${repo.baseBranch}`,
+          });
+        } catch (error) {
+          checks.push({
+            label: `${repo.id} base branch exists`,
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+          });
+        }
+
+        try {
+          await assertHeadBranchWritePermission(github, repo.targetRepo);
+          checks.push({
+            label: `${repo.id} PR head-branch write`,
+            ok: true,
+            detail: "token can update PR branches",
+          });
+        } catch (error) {
+          checks.push({
+            label: `${repo.id} PR head-branch write`,
+            ok: false,
+            detail:
+              error instanceof Error
+                ? error.message
+                : "Grant classic repo scope, or fine-grained Contents: Read and write plus Pull requests: Read and write on the target repo.",
+          });
+        }
+      }
+    }
+  } else {
+    checks.push({
+      label: "GITHUB_TOKEN set",
+      ok: false,
+      detail: "required for handoff runs (Milestone 4+)",
+    });
+  }
+
+  for (const check of checks) {
+    console.log(formatDoctorCheckLine(check));
+  }
+
+  return doctorChecksFailed(checks) ? EXIT_CONFIG : EXIT_SUCCESS;
+}

package/workspace-snapshot/files/src/cli/commands/inspect.ts

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { readManifest } from "../../artifacts/manifest.js";
+import { getManifestPath, getSummaryPath } from "../../artifacts/paths.js";
+import { EXIT_CONFIG, EXIT_SUCCESS } from "../exit-codes.js";
+
+export interface InspectOptions {
+  runPath: string;
+}
+
+export async function runInspect(options: InspectOptions): Promise<number> {
+  const runDirectory = path.resolve(options.runPath);
+  const manifestPath = getManifestPath(runDirectory);
+
+  try {
+    await access(manifestPath, constants.F_OK);
+  } catch {
+    console.error(`Run directory is missing manifest.json: ${runDirectory}`);
+    return EXIT_CONFIG;
+  }
+
+  const manifest = await readManifest(runDirectory);
+
+  console.log("Harness run inspect");
+  console.log(`- Run ID: ${manifest.runId}`);
+  console.log(`- Issue: ${manifest.issueKey}`);
+  console.log(`- Phase: ${manifest.phase}`);
+  console.log(`- Status: ${manifest.phaseInferredFromStatus ?? "unknown"}`);
+  console.log(`- Target repo: ${manifest.targetRepo ?? "none"}`);
+  console.log(`- Outcome: ${manifest.finalOutcome}`);
+  console.log(`- Error: ${manifest.errorClassification ?? "none"}`);
+  console.log(`- Started: ${manifest.startedAt}`);
+  console.log(`- Finished: ${manifest.finishedAt}`);
+
+  try {
+    const summary = await readFile(getSummaryPath(runDirectory), "utf8");
+    console.log("\n--- run-summary.md ---\n");
+    console.log(summary.trimEnd());
+  } catch {
+    console.log("\n(run-summary.md not found)");
+  }
+
+  return EXIT_SUCCESS;
+}

package/workspace-snapshot/files/src/cli/commands/operator-init.ts

@@ -0,0 +1,39 @@
+import { EXIT_CONFIG, EXIT_SUCCESS } from "../exit-codes.js";
+import { runOperatorScaffold } from "../../setup/setup-actions.js";
+
+function printNextSteps(): void {
+  console.log("");
+  console.log("Next steps:");
+  console.log("  1. Edit .harness/config.local.json with your real target repo mapping");
+  console.log(
+    "  2. Keep HARNESS_CONFIG_PATH=.harness/config.local.json in .env.local",
+  );
+  console.log("  3. Run npm run harness:doctor");
+  console.log(
+    "  4. Base64 encode config.local.json and set HARNESS_CONFIG_JSON_B64 in harness repo GitHub Actions secrets for cloud runs",
+  );
+}
+
+export async function runOperatorInit(options?: {
+  force?: boolean;
+  cwd?: string;
+}): Promise<number> {
+  try {
+    const { logMessages } = await runOperatorScaffold({
+      cwd: options?.cwd,
+      force: options?.force,
+      mode: "apply",
+    });
+
+    for (const message of logMessages) {
+      console.log(message);
+    }
+
+    printNextSteps();
+    return EXIT_SUCCESS;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`operator init failed: ${message}`);
+    return EXIT_CONFIG;
+  }
+}

package/workspace-snapshot/files/src/cli/commands/redact-output.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { redactSecrets, redactSecretsString } from "../../artifacts/redact.js";
+
+export async function runRedactOutputCommand(): Promise<number> {
+  const input = readFileSync(0, "utf8");
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    return 0;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    console.log(JSON.stringify(redactSecrets(parsed), null, 2));
+  } catch {
+    console.log(redactSecretsString(trimmed));
+  }
+
+  return 0;
+}

package/workspace-snapshot/files/src/cli/commands/resolve-route.ts

@@ -0,0 +1,81 @@
+import { EXIT_CONFIG, EXIT_PLANNING_FAILURE, EXIT_RUN_FAILURE } from "../exit-codes.js";
+import { isDispatchPhase } from "../../runner/phase-args.js";
+import { resolveRoute, type ResolveRoutePhaseArg, LinearAuthError } from "../../runner/resolve-route.js";
+import { ResolverError } from "../../resolver/errors.js";
+
+export interface ResolveRouteCommandOptions {
+  issueKey: string;
+  configPath: string;
+  phase?: ResolveRoutePhaseArg;
+  json?: boolean;
+  githubOutput?: boolean;
+}
+
+export async function runResolveRouteCommand(
+  options: ResolveRouteCommandOptions,
+): Promise<number> {
+  if (!options.issueKey) {
+    console.error("--issue <KEY> is required.");
+    return EXIT_CONFIG;
+  }
+
+  const phase = options.phase ?? "auto";
+  if (!isDispatchPhase(phase)) {
+    console.error(`Invalid --phase "${phase}".`);
+    return EXIT_CONFIG;
+  }
+
+  try {
+    const result = await resolveRoute({
+      issueKey: options.issueKey,
+      configPath: options.configPath,
+      phase,
+    });
+
+    if (options.githubOutput) {
+      const outputPath = process.env.GITHUB_OUTPUT;
+      if (outputPath) {
+        const { appendFileSync } = await import("node:fs");
+        const lines = [
+          `issue_key=${result.issueKey}`,
+          `phase=${result.phase}`,
+          `repo_config_id=${result.repoConfigId}`,
+          `base_branch=${result.baseBranch}`,
+          `target_repo=${result.targetRepo}`,
+          `linear_status=${result.linearStatus ?? ""}`,
+          `merge_concurrency_group=${result.mergeConcurrencyGroup}`,
+          `should_run=${result.shouldRun}`,
+        ];
+        appendFileSync(outputPath, `${lines.join("\n")}\n`, "utf8");
+      }
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Issue: ${result.issueKey}`);
+      console.log(`Phase: ${result.phase}`);
+      console.log(`Repo: ${result.repoConfigId}`);
+      console.log(`Base branch: ${result.baseBranch}`);
+      console.log(`Merge concurrency group: ${result.mergeConcurrencyGroup}`);
+      console.log(`Should run: ${result.shouldRun}`);
+    }
+
+    if (!result.shouldRun) {
+      return 0;
+    }
+
+    return 0;
+  } catch (error) {
+    if (error instanceof LinearAuthError) {
+      console.error(error.message);
+      return EXIT_PLANNING_FAILURE;
+    }
+    if (error instanceof ResolverError) {
+      console.error(error.message);
+      return EXIT_RUN_FAILURE;
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    return EXIT_RUN_FAILURE;
+  }
+}

package/workspace-snapshot/files/src/cli/commands/run.ts

@@ -0,0 +1,53 @@
+import { EXIT_CONFIG } from "../exit-codes.js";
+import { runOrchestrator, type RunPhaseArg } from "../../runner/orchestrator.js";
+
+export interface RunCommandOptions {
+  issueKey: string;
+  configPath: string;
+  dryRun?: boolean;
+  fixturePath?: string;
+  json?: boolean;
+  phase?: RunPhaseArg;
+  force?: boolean;
+}
+
+export async function runRunCommand(options: RunCommandOptions): Promise<number> {
+  if (!options.issueKey) {
+    console.error("--issue <KEY> is required.");
+    return EXIT_CONFIG;
+  }
+
+  if (options.fixturePath && !options.dryRun && options.phase !== "dry-run") {
+    console.error("--fixture is only supported with --dry-run");
+    return EXIT_CONFIG;
+  }
+
+  const result = await runOrchestrator({
+    issueKey: options.issueKey,
+    configPath: options.configPath,
+    dryRun: options.dryRun,
+    fixturePath: options.fixturePath,
+    phase: options.dryRun ? "dry-run" : options.phase,
+    force: options.force,
+  });
+
+  if (options.json && result.manifest) {
+    console.log(JSON.stringify(result.manifest, null, 2));
+  } else if (result.manifest && typeof result.manifest === "object") {
+    const manifest = result.manifest as {
+      finalOutcome: string;
+      errorClassification?: string | null;
+      dryRun?: boolean;
+    };
+    const label = manifest.dryRun ? "Dry run" : "Run";
+    console.log(`${label} finished: ${manifest.finalOutcome}`);
+    if (result.runDirectory) {
+      console.log(`Run directory: ${result.runDirectory}`);
+    }
+    if (manifest.errorClassification) {
+      console.log(`Error classification: ${manifest.errorClassification}`);
+    }
+  }
+
+  return result.exitCode;
+}

package/workspace-snapshot/files/src/cli/commands/sync-production.ts

@@ -0,0 +1,207 @@
+import { EXIT_CONFIG } from "../exit-codes.js";
+import { loadHarnessConfig } from "../../config/load-config.js";
+import { createLinearClient } from "../../linear/writer.js";
+import { listIssuesByStatus } from "../../linear/issue-query.js";
+import { executeProductionSyncForIssue } from "../../runner/phases/production-sync.js";
+import { fetchLinearIssue } from "../../linear/client.js";
+import { parseIssueDescription } from "../../linear/parser.js";
+import { resolveTargetRepo } from "../../resolver/target-repo.js";
+import {
+  SyncDispatchError,
+  validateProductionSyncDispatch,
+} from "../../workflow/production-sync-dispatch.js";
+
+export interface SyncProductionCommandOptions {
+  configPath: string;
+  repo?: string;
+  issue?: string;
+  sourceRepo?: string;
+  productionBranch?: string;
+  ref?: string;
+  dryRun?: boolean;
+  force?: boolean;
+  json?: boolean;
+}
+
+export interface SyncProductionSummary {
+  repoId: string;
+  issuesInspected: number;
+  issuesUpdated: number;
+  issuesSkipped: number;
+  results: Array<{
+    issueKey: string;
+    finalOutcome: string;
+    skippedReason?: string;
+    diagnosticIssueKeyCommits?: string[];
+  }>;
+}
+
+export async function runSyncProductionCommand(
+  options: SyncProductionCommandOptions,
+): Promise<number> {
+  if (!options.repo && !options.issue) {
+    console.error("Provide --repo <id> or --issue <KEY>.");
+    return EXIT_CONFIG;
+  }
+
+  let config;
+  try {
+    ({ config } = await loadHarnessConfig({ configPath: options.configPath }));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return EXIT_CONFIG;
+  }
+
+  const linearApiKey = process.env.LINEAR_API_KEY;
+  if (!linearApiKey) {
+    console.error("LINEAR_API_KEY is required.");
+    return EXIT_CONFIG;
+  }
+
+  if (!process.env.GITHUB_TOKEN) {
+    console.error("GITHUB_TOKEN is required.");
+    return EXIT_CONFIG;
+  }
+
+  if (options.repo) {
+    const dispatchContext = {
+      repoId: options.repo,
+      sourceRepo: options.sourceRepo,
+      productionBranch: options.productionBranch,
+      ref: options.ref,
+    };
+
+    try {
+      validateProductionSyncDispatch(dispatchContext, config);
+    } catch (error) {
+      if (error instanceof SyncDispatchError) {
+        console.error(error.message);
+        return EXIT_CONFIG;
+      }
+      throw error;
+    }
+  }
+
+  const issueKeys: string[] = [];
+
+  if (options.issue) {
+    issueKeys.push(options.issue.toUpperCase());
+  } else if (options.repo) {
+    const repoConfig = config.repos.find((repo) => repo.id === options.repo);
+    if (!repoConfig) {
+      console.error(`unknown_repo_id: ${options.repo}`);
+      return EXIT_CONFIG;
+    }
+
+    if (repoConfig.baseBranch === repoConfig.productionBranch) {
+      console.log(
+        `Repo ${options.repo} uses baseBranch === productionBranch; production sync is not applicable.`,
+      );
+      return 0;
+    }
+
+    const teamKey = config.linear?.teamKey;
+    if (!teamKey) {
+      console.error("linear.teamKey is required in harness.config.json");
+      return EXIT_CONFIG;
+    }
+    const client = createLinearClient(linearApiKey);
+    const teams = await client.teams();
+    const team = (teams.nodes ?? []).find((t) => t.key === teamKey);
+    if (!team) {
+      console.error(`Linear team not found for key: ${teamKey}`);
+      return EXIT_CONFIG;
+    }
+
+    const integrationStatus =
+      repoConfig.integrationSuccessStatus ?? "Merged to Dev";
+    const issues = await listIssuesByStatus(
+      client,
+      team.id,
+      integrationStatus,
+      repoConfig.linearProjects,
+    );
+    issueKeys.push(...issues.map((issue) => issue.identifier));
+  }
+
+  const summary: SyncProductionSummary = {
+    repoId: options.repo ?? "single-issue",
+    issuesInspected: issueKeys.length,
+    issuesUpdated: 0,
+    issuesSkipped: 0,
+    results: [],
+  };
+
+  for (const issueKey of issueKeys) {
+    const issue = await fetchLinearIssue(issueKey, linearApiKey);
+    const parsed = parseIssueDescription(issue.description ?? "");
+    const resolved = resolveTargetRepo(
+      parsed,
+      {
+        projectName: issue.projectName ?? undefined,
+        teamName: issue.teamName ?? undefined,
+      },
+      config,
+    );
+
+    if (options.repo && resolved.repoConfigId !== options.repo) {
+      summary.issuesSkipped += 1;
+      summary.results.push({
+        issueKey,
+        finalOutcome: "skipped",
+        skippedReason: "issue_not_in_target_repo",
+      });
+      continue;
+    }
+
+    if (resolved.baseBranch === resolved.productionBranch) {
+      summary.issuesSkipped += 1;
+      summary.results.push({
+        issueKey,
+        finalOutcome: "skipped",
+        skippedReason: "base_branch_equals_production_branch",
+      });
+      continue;
+    }
+
+    const result = await executeProductionSyncForIssue({
+      issueKey,
+      configPath: options.configPath,
+      dryRun: options.dryRun,
+      force: options.force,
+    });
+
+    if (result.manifest.finalOutcome === "success") {
+      summary.issuesUpdated += 1;
+    } else {
+      summary.issuesSkipped += 1;
+    }
+
+    summary.results.push({
+      issueKey,
+      finalOutcome: result.manifest.finalOutcome,
+      skippedReason: result.skippedReason,
+      diagnosticIssueKeyCommits: result.diagnosticIssueKeyCommits,
+    });
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(`Production sync inspected ${summary.issuesInspected} issue(s).`);
+    console.log(`Updated: ${summary.issuesUpdated}`);
+    console.log(`Skipped: ${summary.issuesSkipped}`);
+    for (const item of summary.results) {
+      console.log(
+        `- ${item.issueKey}: ${item.finalOutcome}${item.skippedReason ? ` (${item.skippedReason})` : ""}`,
+      );
+      if (item.diagnosticIssueKeyCommits?.length) {
+        console.log(
+          `  diagnostic issue-key commits: ${item.diagnosticIssueKeyCommits.join(", ")}`,
+        );
+      }
+    }
+  }
+
+  return 0;
+}