p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/src/runner/dry-run.ts

@@ -0,0 +1,137 @@
+import { MILESTONE } from "../config/defaults.js";
+import { emptyMergeManifestFields } from "../artifacts/manifest-fields.js";
+import { writeManifest } from "../artifacts/manifest.js";
+import { writeRunSummary } from "../artifacts/summary.js";
+import { resolveModelId } from "../agents/index.js";
+import { runPreflight } from "./preflight.js";
+import type { RunManifest } from "../types/run.js";
+
+export interface DryRunOptions {
+  issueKey: string;
+  configPath: string;
+  fixturePath?: string;
+}
+
+export interface DryRunResult {
+  manifest: RunManifest;
+  runDirectory: string;
+  exitCode: number;
+}
+
+export async function executeDryRun(options: DryRunOptions): Promise<DryRunResult> {
+  const preflight = await runPreflight({
+    issueKey: options.issueKey,
+    configPath: options.configPath,
+    fixturePath: options.fixturePath,
+    linearApiKey: process.env.LINEAR_API_KEY,
+  });
+
+  const finishedAt = new Date().toISOString();
+  const model =
+    preflight.success && preflight.context.config
+      ? resolveModelId(preflight.context.config)
+      : !preflight.success && preflight.config
+        ? resolveModelId(preflight.config)
+        : null;
+
+  if (preflight.success) {
+    const manifest: RunManifest = {
+      runId: preflight.context.runId,
+      issueKey: options.issueKey,
+      phase: preflight.context.phase,
+      phaseInferredFromStatus: preflight.context.phaseInferredFromStatus,
+      linearStatusBefore: preflight.context.issue.status,
+      linearStatusAfter: preflight.context.issue.status,
+      targetRepo: preflight.context.resolved.targetRepo,
+      baseBranch: preflight.context.resolved.baseBranch,
+      resolutionSource: preflight.context.resolved.resolutionSource,
+      dryRun: true,
+      finalOutcome: "success",
+      errorClassification: null,
+      startedAt: preflight.context.startedAt.toISOString(),
+      finishedAt,
+      milestone: MILESTONE,
+      promptVersion: null,
+      cursorAgentId: null,
+      cursorRunId: null,
+      branch: null,
+      prUrl: null,
+      previewUrl: null,
+      validationSummary: null,
+      changedFiles: null,
+      checkSummary: null,
+      previousImplementationRunId: null,
+      previousHandoffRunId: null,
+      pmFeedbackCommentId: null,
+      ...emptyMergeManifestFields(),
+      model,
+    };
+    await writeManifest(preflight.context.runDirectory, manifest);
+    await writeRunSummary(
+      preflight.context.runDirectory,
+      manifest,
+      preflight.context.parsed,
+      preflight.context.resolved,
+    );
+    await preflight.context.events.log("run_finished", "info", {
+      finalOutcome: "success",
+    });
+    return {
+      manifest,
+      runDirectory: preflight.context.runDirectory,
+      exitCode: 0,
+    };
+  }
+
+  const manifest: RunManifest = {
+    runId: preflight.runId,
+    issueKey: options.issueKey,
+    phase: preflight.phase,
+    phaseInferredFromStatus: preflight.phaseInferredFromStatus,
+    linearStatusBefore: preflight.issue?.status ?? null,
+    linearStatusAfter: preflight.issue?.status ?? null,
+    targetRepo: preflight.resolved?.targetRepo ?? null,
+    baseBranch: preflight.resolved?.baseBranch ?? null,
+    resolutionSource: preflight.resolved?.resolutionSource ?? null,
+    dryRun: true,
+    finalOutcome: "failed",
+    errorClassification: preflight.errorClassification,
+    startedAt: preflight.startedAt.toISOString(),
+    finishedAt,
+    milestone: MILESTONE,
+    promptVersion: null,
+    cursorAgentId: null,
+    cursorRunId: null,
+    branch: null,
+    prUrl: null,
+    previewUrl: null,
+    validationSummary: null,
+    changedFiles: null,
+    checkSummary: null,
+    previousImplementationRunId: null,
+    previousHandoffRunId: null,
+    pmFeedbackCommentId: null,
+    ...emptyMergeManifestFields(),
+    model,
+  };
+
+  if (preflight.runDirectory) {
+    await writeManifest(preflight.runDirectory, manifest);
+    await writeRunSummary(
+      preflight.runDirectory,
+      manifest,
+      preflight.parsed,
+      preflight.resolved,
+    );
+    await preflight.events?.log("run_finished", "error", {
+      finalOutcome: "failed",
+      errorClassification: preflight.errorClassification,
+    });
+  }
+
+  return {
+    manifest,
+    runDirectory: preflight.runDirectory,
+    exitCode: 2,
+  };
+}

package/workspace-snapshot/files/src/runner/errors.ts

@@ -0,0 +1,70 @@
+import type { CursorCancelOutcome } from "../agents/types.js";
+
+export class PhaseError extends Error {
+  readonly classification: import("../types/run.js").ErrorClassification;
+  readonly cancelOutcome: CursorCancelOutcome | null;
+
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+    cancelOutcome: CursorCancelOutcome | null = null,
+  ) {
+    super(message);
+    this.name = "PhaseError";
+    this.classification = classification;
+    this.cancelOutcome = cancelOutcome;
+  }
+}
+
+export class PlanningError extends PhaseError {
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+    cancelOutcome: CursorCancelOutcome | null = null,
+  ) {
+    super(classification, message, cancelOutcome);
+    this.name = "PlanningError";
+  }
+}
+
+export class ImplementationError extends PhaseError {
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+    cancelOutcome: CursorCancelOutcome | null = null,
+  ) {
+    super(classification, message, cancelOutcome);
+    this.name = "ImplementationError";
+  }
+}
+
+export class HandoffError extends PhaseError {
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+  ) {
+    super(classification, message, null);
+    this.name = "HandoffError";
+  }
+}
+
+export class RevisionError extends PhaseError {
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+    cancelOutcome: CursorCancelOutcome | null = null,
+  ) {
+    super(classification, message, cancelOutcome);
+    this.name = "RevisionError";
+  }
+}
+
+export class MergeError extends PhaseError {
+  constructor(
+    classification: NonNullable<import("../types/run.js").ErrorClassification>,
+    message: string,
+  ) {
+    super(classification, message, null);
+    this.name = "MergeError";
+  }
+}

package/workspace-snapshot/files/src/runner/execution-environment.ts

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+
+export type ExecutionEnvironmentKind =
+  | "github_actions"
+  | "codespaces"
+  | "local_dev";
+
+export interface ExecutionEnvironmentInfo {
+  kind: ExecutionEnvironmentKind;
+  marker: string;
+  hostname?: string;
+  codespaceName?: string;
+  githubRunId?: string;
+  githubWorkflow?: string;
+  gitBranch?: string;
+  gitSha?: string;
+}
+
+export interface ExecutionEnvironmentDetectOptions {
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  hostname?: string;
+  readGitInfo?: (cwd: string) => { branch?: string; sha?: string };
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+  return value?.toLowerCase() === "true";
+}
+
+function readGitInfoFromRepo(cwd: string): { branch?: string; sha?: string } {
+  try {
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return {
+      branch: branch && branch !== "HEAD" ? branch : undefined,
+      sha: sha ? sha.slice(0, 12) : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function resolveGitInfo(
+  env: Record<string, string | undefined>,
+  cwd: string,
+  readGitInfo: (cwd: string) => { branch?: string; sha?: string },
+): { branch?: string; sha?: string } {
+  const fromEnv: { branch?: string; sha?: string } = {};
+  if (env.GITHUB_SHA) {
+    fromEnv.sha = env.GITHUB_SHA.slice(0, 12);
+  }
+  const branchFromEnv =
+    env.GITHUB_REF_NAME?.trim() ||
+    env.GITHUB_HEAD_REF?.trim() ||
+    undefined;
+  if (branchFromEnv) {
+    fromEnv.branch = branchFromEnv;
+  }
+
+  if (fromEnv.branch && fromEnv.sha) {
+    return fromEnv;
+  }
+
+  const fromGit = readGitInfo(cwd);
+  return {
+    branch: fromEnv.branch ?? fromGit.branch,
+    sha: fromEnv.sha ?? fromGit.sha,
+  };
+}
+
+function resolveExecutionEnvironmentKind(
+  env: Record<string, string | undefined>,
+): ExecutionEnvironmentKind {
+  if (isTruthyEnv(env.GITHUB_ACTIONS)) {
+    return "github_actions";
+  }
+  if (isTruthyEnv(env.CODESPACES) || Boolean(env.CODESPACE_NAME?.trim())) {
+    return "codespaces";
+  }
+  return "local_dev";
+}
+
+export function formatExecutionEnvironmentMarker(
+  info: Pick<
+    ExecutionEnvironmentInfo,
+    | "kind"
+    | "hostname"
+    | "codespaceName"
+    | "githubRunId"
+    | "githubWorkflow"
+  >,
+): string {
+  switch (info.kind) {
+    case "github_actions": {
+      const runId = info.githubRunId?.trim() || "unknown run";
+      const workflow = info.githubWorkflow?.trim();
+      return workflow
+        ? `Executed in GitHub Actions: ${runId} / ${workflow}`
+        : `Executed in GitHub Actions: ${runId}`;
+    }
+    case "codespaces":
+      return `Executed in GitHub Codespaces: ${
+        info.codespaceName?.trim() || info.hostname?.trim() || "unknown"
+      }`;
+    case "local_dev":
+      return `Executed in local dev: ${info.hostname?.trim() || "unknown"}`;
+  }
+}
+
+export function detectExecutionEnvironment(
+  options: ExecutionEnvironmentDetectOptions = {},
+): ExecutionEnvironmentInfo {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const hostname = options.hostname ?? os.hostname();
+  const kind = resolveExecutionEnvironmentKind(env);
+  const codespaceName = env.CODESPACE_NAME?.trim() || undefined;
+  const githubRunId = env.GITHUB_RUN_ID?.trim() || undefined;
+  const githubWorkflow = env.GITHUB_WORKFLOW?.trim() || undefined;
+  const git = resolveGitInfo(env, cwd, options.readGitInfo ?? readGitInfoFromRepo);
+
+  const info: ExecutionEnvironmentInfo = {
+    kind,
+    marker: "",
+    hostname,
+    codespaceName,
+    githubRunId,
+    githubWorkflow,
+    gitBranch: git.branch,
+    gitSha: git.sha,
+  };
+  info.marker = formatExecutionEnvironmentMarker(info);
+  return info;
+}
+
+export function appendExecutionEnvironmentMetadataLines(
+  lines: string[],
+  options: ExecutionEnvironmentDetectOptions = {},
+): string[] {
+  const info = detectExecutionEnvironment(options);
+  lines.push(`execution_environment: ${info.kind}`);
+  lines.push(`execution_environment_marker: ${info.marker}`);
+  if (info.hostname) {
+    lines.push(`hostname: ${info.hostname}`);
+  }
+  if (info.codespaceName) {
+    lines.push(`codespace_name: ${info.codespaceName}`);
+  }
+  if (info.githubRunId) {
+    lines.push(`github_run_id: ${info.githubRunId}`);
+  }
+  if (info.githubWorkflow) {
+    lines.push(`github_workflow: ${info.githubWorkflow}`);
+  }
+  if (info.gitBranch) {
+    lines.push(`git_branch: ${info.gitBranch}`);
+  }
+  if (info.gitSha) {
+    lines.push(`git_sha: ${info.gitSha}`);
+  }
+  return lines;
+}
+
+export function logExecutionEnvironmentMarker(
+  options: ExecutionEnvironmentDetectOptions = {},
+): ExecutionEnvironmentInfo {
+  const info = detectExecutionEnvironment(options);
+  console.log(info.marker);
+  return info;
+}

package/workspace-snapshot/files/src/runner/failure-finalization.ts

@@ -0,0 +1,234 @@
+import { loadHarnessConfig } from "../config/load-config.js";
+import { isCloudConfigStaleTemporarilyAllowed } from "../config/runner-upgrade-sync-gate.js";
+import { resolveHarnessWorkspaceRootFromConfigSource } from "../config/workspace-root.js";
+import { getTransitionalStatus } from "../config/status-names.js";
+import {
+  buildFallbackRunManifest,
+  ensureJsonOutManifest,
+  readJsonOutManifest,
+  writeJsonOutManifest,
+} from "../artifacts/write-json-out-manifest.js";
+import { fetchLinearIssue } from "../linear/client.js";
+import { markRunStatusBlocked } from "../linear/run-status-comment.js";
+import {
+  createLinearClient,
+  transitionIssueStatus,
+} from "../linear/writer.js";
+import { resolveRunGeneration } from "./run-generation.js";
+import type { ErrorClassification, RunManifest } from "../types/run.js";
+
+export interface FailureFinalizationInput {
+  issueKey: string;
+  jsonOutPath: string;
+  exitCode: number;
+  configPath: string;
+  linearApiKey?: string;
+  deliveryId?: string | null;
+  generation?: number;
+  message?: string;
+}
+
+export interface FailureFinalizationResult {
+  skipped: boolean;
+  blocked: boolean;
+  reason?: string;
+  manifest: RunManifest;
+  commentAction?: "created" | "updated" | "skipped";
+}
+
+function normalizeStatus(value: string | null | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  return value.trim().toLowerCase();
+}
+
+export function resolveRunOwnedStatuses(
+  manifest: RunManifest,
+  blockedStatus: string,
+  planningInProgressStatus: string,
+): string[] {
+  const owned = new Set<string>();
+  for (const status of manifest.runOwnedStatuses ?? []) {
+    const normalized = normalizeStatus(status);
+    if (normalized) {
+      owned.add(normalized);
+    }
+  }
+
+  const before = normalizeStatus(manifest.linearStatusBefore);
+  if (before) {
+    owned.add(before);
+  }
+
+  const after = normalizeStatus(manifest.linearStatusAfter);
+  if (after) {
+    owned.add(after);
+  }
+
+  owned.add(normalizeStatus(planningInProgressStatus) ?? planningInProgressStatus.toLowerCase());
+  const blocked = normalizeStatus(blockedStatus);
+  if (blocked) {
+    owned.delete(blocked);
+  }
+
+  return [...owned];
+}
+
+export function shouldTransitionIssueToBlocked(input: {
+  currentStatus: string | null | undefined;
+  ownedStatuses: string[];
+  manifest: RunManifest;
+  generation: number;
+}): { shouldTransition: boolean; reason?: string } {
+  if (input.manifest.finalOutcome === "success") {
+    return { shouldTransition: false, reason: "run succeeded" };
+  }
+
+  if (input.manifest.finalOutcome === "duplicate") {
+    return { shouldTransition: false, reason: "duplicate run" };
+  }
+
+  if (
+    input.manifest.runGeneration !== null &&
+    input.manifest.runGeneration !== undefined &&
+    input.manifest.runGeneration > input.generation
+  ) {
+    return { shouldTransition: false, reason: "newer run generation recorded in manifest" };
+  }
+
+  const current = normalizeStatus(input.currentStatus);
+  if (!current) {
+    return { shouldTransition: false, reason: "issue status unavailable" };
+  }
+
+  if (!input.ownedStatuses.some((status) => status === current)) {
+    return { shouldTransition: false, reason: "issue status changed away from run-owned set" };
+  }
+
+  return { shouldTransition: true };
+}
+
+export async function finalizeFailedHarnessRun(
+  input: FailureFinalizationInput,
+): Promise<FailureFinalizationResult> {
+  const generation = input.generation ?? resolveRunGeneration();
+  const deliveryId = input.deliveryId ?? process.env.LINEAR_DELIVERY_ID ?? null;
+
+  let manifest =
+    (await readJsonOutManifest(input.jsonOutPath)) ??
+    buildFallbackRunManifest({
+      issueKey: input.issueKey,
+      errorClassification: "run_crash",
+      message: input.message ?? "Harness run failed before manifest was written",
+      deliveryId,
+      runGeneration: generation,
+    });
+
+  if (input.exitCode === 0) {
+    return {
+      skipped: true,
+      blocked: false,
+      reason: "exit code is zero",
+      manifest,
+    };
+  }
+
+  if (!manifest.runGeneration) {
+    manifest = { ...manifest, runGeneration: generation };
+  }
+  if (!manifest.deliveryId && deliveryId) {
+    manifest = { ...manifest, deliveryId };
+  }
+
+  await writeJsonOutManifest(input.jsonOutPath, manifest);
+
+  const linearApiKey = input.linearApiKey ?? process.env.LINEAR_API_KEY ?? "";
+  if (!linearApiKey) {
+    return {
+      skipped: true,
+      blocked: false,
+      reason: "LINEAR_API_KEY unavailable for failure finalization",
+      manifest,
+    };
+  }
+
+  const { config, source } = await loadHarnessConfig({ configPath: input.configPath });
+  const workspaceRoot = resolveHarnessWorkspaceRootFromConfigSource(source);
+
+  if (
+    manifest.errorClassification === "cloud_config_stale" &&
+    (await isCloudConfigStaleTemporarilyAllowed(workspaceRoot))
+  ) {
+    return {
+      skipped: true,
+      blocked: false,
+      reason: "cloud_config_stale temporarily allowed during runner upgrade sync",
+      manifest,
+    };
+  }
+
+  const issue = await fetchLinearIssue(input.issueKey, linearApiKey);
+  const client = createLinearClient(linearApiKey);
+  const blockedStatus = getTransitionalStatus(config, "blocked");
+  const planningInProgressStatus = getTransitionalStatus(config, "planningInProgress");
+  const ownedStatuses = resolveRunOwnedStatuses(
+    manifest,
+    blockedStatus,
+    planningInProgressStatus,
+  );
+
+  const failureMessage =
+    manifest.validationSummary ??
+    manifest.errorClassification ??
+    "Harness run failed";
+
+  const commentResult = await markRunStatusBlocked(client, issue.id, {
+    message: `Harness run blocked: ${failureMessage}`,
+    phase: manifest.phase === "none" ? "failed" : manifest.phase,
+    runId: manifest.runId,
+    deliveryId: manifest.deliveryId ?? deliveryId,
+    generation,
+  });
+
+  const transitionDecision = shouldTransitionIssueToBlocked({
+    currentStatus: issue.status,
+    ownedStatuses,
+    manifest,
+    generation,
+  });
+
+  if (!transitionDecision.shouldTransition) {
+    return {
+      skipped: true,
+      blocked: false,
+      reason: transitionDecision.reason,
+      manifest,
+      commentAction: commentResult.action,
+    };
+  }
+
+  await transitionIssueStatus(client, issue, blockedStatus);
+  return {
+    skipped: false,
+    blocked: true,
+    manifest,
+    commentAction: commentResult.action,
+  };
+}
+
+export async function ensureHarnessRunJsonOut(
+  input: Omit<FailureFinalizationInput, "exitCode"> & {
+    exitCode?: number;
+    errorClassification?: ErrorClassification;
+  },
+): Promise<RunManifest> {
+  const generation = input.generation ?? resolveRunGeneration();
+  return ensureJsonOutManifest(input.jsonOutPath, {
+    issueKey: input.issueKey,
+    errorClassification: input.errorClassification ?? "run_crash",
+    message: input.message ?? "Harness run failed before manifest was written",
+    deliveryId: input.deliveryId ?? process.env.LINEAR_DELIVERY_ID ?? null,
+    runGeneration: generation,
+  });
+}

package/workspace-snapshot/files/src/runner/fixture.ts

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+import { parseFixtureMarkdown } from "../fixture/frontmatter.js";
+import {
+  teamKeyFromIssueIdentifier,
+  type LinearIssueSnapshot,
+} from "../linear/client.js";
+
+export type { FixtureMetadata } from "../fixture/frontmatter.js";
+
+export async function loadIssueFixture(
+  fixturePath: string,
+  issueKey: string,
+): Promise<LinearIssueSnapshot> {
+  const raw = await readFile(fixturePath, "utf8");
+  const { metadata, body } = parseFixtureMarkdown(raw);
+
+  return {
+    id: `fixture-${issueKey}`,
+    identifier: issueKey,
+    title: metadata.title ?? `Fixture issue ${issueKey}`,
+    description: body,
+    status: metadata.status,
+    projectId: null,
+    projectName: metadata.projectName,
+    teamName: metadata.teamName,
+    teamKey: teamKeyFromIssueIdentifier(issueKey),
+    teamId: null,
+    url: null,
+  };
+}