p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/setup/vercel-webhook-probe.ts

@@ -0,0 +1,161 @@
+import { computeLinearSignature } from "../webhook/verify.js";
+
+export interface VercelSignedProbeEvidence {
+  passed: boolean;
+  statusCode?: number;
+  result: "accepted_ignored" | "auth_failed" | "unreachable" | "protection_redirect" | "error";
+  reason?: string;
+  probedAt: string;
+  webhookHost?: string;
+  webhookPath?: string;
+}
+
+export interface RunSignedWebhookProbeInput {
+  webhookUrl: string;
+  secret: string;
+  nowMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+function redactWebhookLocation(webhookUrl: string): {
+  webhookHost?: string;
+  webhookPath?: string;
+} {
+  try {
+    const url = new URL(webhookUrl);
+    return {
+      webhookHost: url.host,
+      webhookPath: url.pathname,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function buildIgnoredProbePayload(nowMs: number): string {
+  return JSON.stringify({
+    action: "create",
+    type: "Comment",
+    webhookTimestamp: nowMs,
+    data: {
+      id: "harness-setup-probe",
+    },
+  });
+}
+
+function isVercelProtectionRedirect(response: Response): boolean {
+  if (response.status !== 302 && response.status !== 307 && response.status !== 308) {
+    return false;
+  }
+  const location = response.headers.get("location") ?? "";
+  return /vercel\.com\/sso-api/i.test(location);
+}
+
+export async function runSignedWebhookProbe(
+  input: RunSignedWebhookProbeInput,
+): Promise<VercelSignedProbeEvidence> {
+  const nowMs = input.nowMs ?? Date.now();
+  const location = redactWebhookLocation(input.webhookUrl);
+  const rawBody = buildIgnoredProbePayload(nowMs);
+  const signature = computeLinearSignature(input.secret, rawBody);
+  const fetchImpl = input.fetchImpl ?? fetch;
+
+  try {
+    const response = await fetchImpl(input.webhookUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "linear-signature": signature,
+        "linear-timestamp": String(nowMs),
+        "linear-event": "Comment",
+        "linear-delivery": `harness-setup-probe-${nowMs}`,
+      },
+      body: rawBody,
+      redirect: "manual",
+    });
+
+    if (isVercelProtectionRedirect(response)) {
+      return {
+        passed: false,
+        statusCode: response.status,
+        result: "protection_redirect",
+        reason:
+          "Vercel Deployment Protection redirected the webhook endpoint. Disable protection for /api/linear-webhook or allow public access before verifying the bridge.",
+        probedAt: new Date(nowMs).toISOString(),
+        ...location,
+      };
+    }
+
+    let body: { error?: string; accepted?: boolean; reason?: string } | null = null;
+    try {
+      body = (await response.json()) as {
+        error?: string;
+        accepted?: boolean;
+        reason?: string;
+      };
+    } catch {
+      return {
+        passed: false,
+        statusCode: response.status,
+        result: "error",
+        reason: "Webhook endpoint did not return JSON.",
+        probedAt: new Date(nowMs).toISOString(),
+        ...location,
+      };
+    }
+
+    if (response.status === 401) {
+      return {
+        passed: false,
+        statusCode: response.status,
+        result: "auth_failed",
+        reason: body.error ?? "invalid_signature",
+        probedAt: new Date(nowMs).toISOString(),
+        ...location,
+      };
+    }
+
+    if (response.status === 404) {
+      return {
+        passed: false,
+        statusCode: response.status,
+        result: "unreachable",
+        reason: "Webhook route was not found on the production deployment.",
+        probedAt: new Date(nowMs).toISOString(),
+        ...location,
+      };
+    }
+
+    if (
+      response.status === 200 &&
+      body.accepted === false &&
+      typeof body.reason === "string"
+    ) {
+      return {
+        passed: true,
+        statusCode: response.status,
+        result: "accepted_ignored",
+        reason: body.reason,
+        probedAt: new Date(nowMs).toISOString(),
+        ...location,
+      };
+    }
+
+    return {
+      passed: false,
+      statusCode: response.status,
+      result: "error",
+      reason: "Signed probe was not authentication-accepted and business-ignored.",
+      probedAt: new Date(nowMs).toISOString(),
+      ...location,
+    };
+  } catch {
+    return {
+      passed: false,
+      result: "unreachable",
+      reason: "Webhook endpoint could not be reached for signed probe verification.",
+      probedAt: new Date(nowMs).toISOString(),
+      ...location,
+    };
+  }
+}

package/workspace-snapshot/files/src/setup/workflow-install-merge-errors.ts

@@ -0,0 +1,166 @@
+import { GitHubApiError } from "../github/client.js";
+import { classifyMergeError } from "../github/merge-result.js";
+import type { WorkflowInstallBlockedCategory } from "./target-workflow-finalization-types.js";
+
+export function classifyWorkflowInstallMergeRejection(input: {
+  error: unknown;
+  mergeableState?: string | null;
+  message?: string;
+}): {
+  category: WorkflowInstallBlockedCategory;
+  waiting: boolean;
+  message: string;
+} {
+  const apiMessage = (
+    input.message ??
+    (input.error instanceof Error ? input.error.message : String(input.error))
+  ).toLowerCase();
+
+  if (input.error instanceof GitHubApiError) {
+    if (input.error.status === 401 || input.error.status === 403) {
+      if (
+        apiMessage.includes("review") ||
+        apiMessage.includes("approval") ||
+        apiMessage.includes("required reviewers")
+      ) {
+        return {
+          category: "review-required",
+          waiting: false,
+          message:
+            "GitHub requires human review before this workflow install PR can merge.",
+        };
+      }
+      return {
+        category: "permission-denied",
+        waiting: false,
+        message:
+          "The setup token does not have permission to merge this workflow install PR.",
+      };
+    }
+
+    if (input.error.status === 405) {
+      if (classifyMergeError(input.error) === "pr_already_merged") {
+        return {
+          category: "merge-api-failure",
+          waiting: false,
+          message: "Workflow install PR was already merged.",
+        };
+      }
+    }
+
+    if (input.error.status === 409) {
+      return {
+        category: "merge-conflict",
+        waiting: false,
+        message:
+          "The workflow install PR has merge conflicts that require manual resolution.",
+      };
+    }
+
+    if (input.error.status === 422) {
+      if (
+        apiMessage.includes("merge queue") ||
+        apiMessage.includes("queued for merge")
+      ) {
+        return {
+          category: "merge-queue-required",
+          waiting: false,
+          message:
+            "This repository requires merge queue handling that onboarding does not support automatically.",
+        };
+      }
+      if (
+        apiMessage.includes("head sha") ||
+        apiMessage.includes("expected head")
+      ) {
+        return {
+          category: "mergeability-pending",
+          waiting: true,
+          message:
+            "The workflow install PR head changed during finalization. Revalidating before merge.",
+        };
+      }
+      if (
+        apiMessage.includes("required status") ||
+        apiMessage.includes("not mergeable") ||
+        apiMessage.includes("checks")
+      ) {
+        return {
+          category: "checks-pending",
+          waiting: true,
+          message: "GitHub is still waiting for required checks on the workflow install PR.",
+        };
+      }
+      if (apiMessage.includes("review")) {
+        return {
+          category: "review-required",
+          waiting: false,
+          message:
+            "GitHub requires human review before this workflow install PR can merge.",
+        };
+      }
+    }
+  }
+
+  const state = input.mergeableState?.toLowerCase() ?? "";
+  if (state === "dirty") {
+    return {
+      category: "merge-conflict",
+      waiting: false,
+      message:
+        "The workflow install PR has merge conflicts that require manual resolution.",
+    };
+  }
+  if (state === "behind") {
+    return {
+      category: "branch-behind",
+      waiting: true,
+      message: "The workflow install branch is behind the production branch.",
+    };
+  }
+  if (state === "blocked") {
+    return {
+      category: "review-required",
+      waiting: false,
+      message:
+        "Branch protection or review rules are blocking automatic merge of the workflow install PR.",
+    };
+  }
+
+  return {
+    category: "merge-api-failure",
+    waiting: false,
+    message: "GitHub rejected the workflow install PR merge request.",
+  };
+}
+
+export function blockedCategoryMessage(
+  category: WorkflowInstallBlockedCategory,
+): string {
+  switch (category) {
+    case "checks-pending":
+      return "Waiting for GitHub checks on the workflow install PR.";
+    case "checks-failing":
+      return "Required checks failed on the workflow install PR.";
+    case "mergeability-pending":
+      return "GitHub is still computing mergeability for the workflow install PR.";
+    case "branch-behind":
+      return "Updating the workflow install branch to match production.";
+    case "review-required":
+      return "Human review is required before the workflow install PR can merge.";
+    case "permission-denied":
+      return "The setup token cannot merge the workflow install PR.";
+    case "merge-conflict":
+      return "The workflow install PR has merge conflicts.";
+    case "unexpected-pr-content":
+      return "The workflow install PR contains unexpected changes.";
+    case "merge-queue-required":
+      return "This repository requires merge queue handling.";
+    case "merge-api-failure":
+      return "GitHub rejected the workflow install merge request.";
+    case "verification-failed":
+      return "The workflow was merged but production verification has not succeeded yet.";
+    default:
+      return "Workflow install finalization is blocked.";
+  }
+}

package/workspace-snapshot/files/src/types/parsed-issue.ts

@@ -0,0 +1,8 @@
+export interface ParsedIssue {
+  targetRepoRaw?: string;
+  task: string;
+  acceptanceCriteria: string[];
+  outOfScope: string[];
+  validationExpectations?: string;
+  parseErrors: string[];
+}

package/workspace-snapshot/files/src/types/run.ts

@@ -0,0 +1,157 @@
+export type RunPhase =
+  | "planning"
+  | "implementation"
+  | "handoff"
+  | "revision"
+  | "merge"
+  | "production_sync"
+  | "none";
+
+export type FinalOutcome = "success" | "failed" | "skipped" | "duplicate";
+
+export type ErrorClassification =
+  | "ambiguous_issue"
+  | "missing_target_repo"
+  | "unknown_repo_denied"
+  | "wrong_status"
+  | "duplicate_phase_completed"
+  | "linear_auth_failure"
+  | "cursor_api_failure"
+  | "cursor_run_failed"
+  | "cursor_run_timeout"
+  | "linear_write_failure"
+  | "agent_policy_violation"
+  | "missing_planning_comment"
+  | "validation_failed"
+  | "pr_not_created"
+  | "branch_without_pr"
+  | "wrong_target_repo"
+  | "wrong_pr_target"
+  | "base_branch_missing"
+  | "wrong_pr_base_branch"
+  | "github_auth_failure"
+  | "github_api_failure"
+  | "repair_head_branch_write_denied"
+  | "repair_validation_failed"
+  | "repair_ambiguous"
+  | "repair_scope_violation"
+  | "repair_requires_product_judgment"
+  | "repair_base_branch_violation"
+  | "missing_implementation_marker"
+  | "missing_implementation_pr"
+  | "missing_merge_metadata"
+  | "production_not_promoted"
+  | "missing_pr_url"
+  | "pr_closed"
+  | "preview_not_found"
+  | "checks_failing"
+  | "missing_handoff_marker"
+  | "missing_pm_feedback"
+  | "missing_branch"
+  | "revision_pr_mismatch"
+  | "cursor_branch_attach_failure"
+  | "missing_merge_source_marker"
+  | "pr_already_merged"
+  | "checks_pending"
+  | "checks_unknown"
+  | "github_merge_failure"
+  | "deployment_not_found"
+  | "recovery_handoff"
+  | "implementation_in_progress"
+  | null;
+
+export interface RunManifest {
+  runId: string;
+  issueKey: string;
+  phase: RunPhase;
+  phaseInferredFromStatus: string | null;
+  linearStatusBefore: string | null;
+  linearStatusAfter: string | null;
+  targetRepo: string | null;
+  baseBranch: string | null;
+  resolutionSource: "explicit" | "project" | "team" | null;
+  dryRun: boolean;
+  finalOutcome: FinalOutcome;
+  errorClassification: ErrorClassification;
+  startedAt: string;
+  finishedAt: string;
+  milestone: string;
+  promptVersion: string | null;
+  cursorAgentId: string | null;
+  cursorRunId: string | null;
+  branch: string | null;
+  prUrl: string | null;
+  previewUrl: string | null;
+  validationSummary: string | null;
+  changedFiles: string[] | null;
+  checkSummary: string | null;
+  previousImplementationRunId: string | null;
+  previousHandoffRunId: string | null;
+  pmFeedbackCommentId: string | null;
+  previousRevisionRunId: string | null;
+  mergeCommitSha: string | null;
+  mergeMethod: string | null;
+  mergedAt: string | null;
+  deploymentUrl: string | null;
+  model: string | null;
+}
+
+export type RunEventName =
+  | "run_started"
+  | "config_loaded"
+  | "issue_fetched"
+  | "issue_loaded_from_fixture"
+  | "issue_parsed"
+  | "repo_resolved"
+  | "repo_resolution_failed"
+  | "phase_inferred"
+  | "idempotency_skip"
+  | "planning_comment_loaded"
+  | "implementation_comment_loaded"
+  | "linear_status_changed"
+  | "linear_comment_posted"
+  | "phase_start_comment_posted"
+  | "cursor_agent_created"
+  | "cursor_event"
+  | "cursor_run_poll_fallback"
+  | "cursor_run_finished"
+  | "cursor_run_cancelled"
+  | "cursor_cancel_unavailable"
+  | "cursor_run_cancel_failed"
+  | "git_result_captured"
+  | "pr_captured"
+  | "validation_completed"
+  | "github_pr_inspected"
+  | "preview_poll_started"
+  | "preview_captured"
+  | "preview_not_found"
+  | "handoff_comment_posted"
+  | "handoff_comment_loaded"
+  | "pm_feedback_loaded"
+  | "revision_comment_posted"
+  | "revision_pr_validated"
+  | "merge_source_comment_loaded"
+  | "merge_checks_evaluated"
+  | "repair_started"
+  | "repair_deterministic_update_attempted"
+  | "repair_agent_started"
+  | "repair_completed"
+  | "repair_failed"
+  | "repair_returned_to_merge"
+  | "github_pr_marked_ready"
+  | "github_merge_requested"
+  | "github_merge_completed"
+  | "deployment_poll_started"
+  | "deployment_poll_skipped"
+  | "deployment_captured"
+  | "deployment_not_found"
+  | "merge_comment_posted"
+  | "merge_recovery_written"
+  | "run_finished";
+
+export interface RunEvent {
+  ts: string;
+  level: "info" | "warn" | "error";
+  event: RunEventName;
+  data?: Record<string, unknown>;
+}

package/workspace-snapshot/files/src/validate/constants.ts

@@ -0,0 +1,2 @@
+export const NARROW_TASK_MAX_LENGTH = 240;
+export const NARROW_AC_MAX_COUNT = 7;