p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/tests/github/base-branch.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from "vitest";
+import { GitHubApiError } from "../../src/github/client.js";
+import {
+  assertBaseBranchExists,
+  assertHeadBranchWritePermission,
+  assertPrBaseBranchMatches,
+  assertPullRequestMergeable,
+  isIntegrationRepairEligible,
+  parseGitHubRepoUrl,
+} from "../../src/github/base-branch.js";
+
+describe("parseGitHubRepoUrl", () => {
+  it("parses canonical GitHub HTTPS URLs", () => {
+    expect(
+      parseGitHubRepoUrl("https://github.com/owner/example-target-app"),
+    ).toEqual({
+      owner: "owner",
+      repo: "example-target-app",
+    });
+  });
+
+  it("returns null for invalid URLs", () => {
+    expect(parseGitHubRepoUrl("not-a-repo-url")).toBeNull();
+  });
+});
+
+describe("assertBaseBranchExists", () => {
+  it("resolves when branch ref exists", async () => {
+    const client = {
+      getBranchRef: vi.fn().mockResolvedValue({ object: { sha: "abc" } }),
+    };
+
+    await expect(
+      assertBaseBranchExists(
+        client as never,
+        "https://github.com/owner/example-target-app",
+        "dev",
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it("throws base_branch_missing when branch ref is 404", async () => {
+    const client = {
+      getBranchRef: vi
+        .fn()
+        .mockRejectedValue(new GitHubApiError(404, "Not Found")),
+    };
+
+    await expect(
+      assertBaseBranchExists(
+        client as never,
+        "https://github.com/owner/example-target-app",
+        "dev",
+      ),
+    ).rejects.toThrow(/base_branch_missing/);
+  });
+});
+
+describe("assertPullRequestMergeable", () => {
+  it("passes when PR is mergeable", () => {
+    expect(() =>
+      assertPullRequestMergeable({
+        prUrl: "https://github.com/o/r/pull/1",
+        merged: false,
+        mergeable: true,
+        mergeableState: "clean",
+        baseBranch: "dev",
+      }),
+    ).not.toThrow();
+  });
+
+  it("passes when PR is already merged", () => {
+    expect(() =>
+      assertPullRequestMergeable({
+        prUrl: "https://github.com/o/r/pull/1",
+        merged: true,
+        mergeable: false,
+        mergeableState: "dirty",
+        baseBranch: "dev",
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws pr_not_mergeable when PR is dirty", () => {
+    expect(() =>
+      assertPullRequestMergeable({
+        prUrl: "https://github.com/o/r/pull/1",
+        merged: false,
+        mergeable: false,
+        mergeableState: "dirty",
+        baseBranch: "dev",
+      }),
+    ).toThrow(/pr_not_mergeable/);
+  });
+});
+
+describe("isIntegrationRepairEligible", () => {
+  it("allows dirty and behind PRs", () => {
+    expect(
+      isIntegrationRepairEligible({ mergeable: false, mergeableState: "dirty" }),
+    ).toBe(true);
+    expect(
+      isIntegrationRepairEligible({ mergeable: false, mergeableState: "behind" }),
+    ).toBe(true);
+  });
+
+  it("does not repair blocked PRs", () => {
+    expect(
+      isIntegrationRepairEligible({ mergeable: false, mergeableState: "blocked" }),
+    ).toBe(false);
+  });
+});
+
+describe("assertHeadBranchWritePermission", () => {
+  it("passes when repo permissions include push", async () => {
+    const client = {
+      getRepository: vi.fn().mockResolvedValue({ permissions: { push: true } }),
+    };
+
+    await expect(
+      assertHeadBranchWritePermission(client as never, "https://github.com/o/r"),
+    ).resolves.toBeUndefined();
+  });
+
+  it("throws setup guidance when write is missing", async () => {
+    const client = {
+      getRepository: vi.fn().mockResolvedValue({ permissions: { pull: true } }),
+    };
+
+    await expect(
+      assertHeadBranchWritePermission(client as never, "https://github.com/o/r"),
+    ).rejects.toThrow(/repair_head_branch_write_denied/);
+  });
+});
+
+describe("assertPrBaseBranchMatches", () => {
+  it("passes when PR base matches config", () => {
+    expect(() =>
+      assertPrBaseBranchMatches({
+        prUrl: "https://github.com/o/r/pull/1",
+        actualBaseBranch: "dev",
+        expectedBaseBranch: "dev",
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws wrong_pr_base_branch when PR base differs", () => {
+    expect(() =>
+      assertPrBaseBranchMatches({
+        prUrl: "https://github.com/o/r/pull/1",
+        actualBaseBranch: "main",
+        expectedBaseBranch: "dev",
+      }),
+    ).toThrow(/wrong_pr_base_branch/);
+  });
+});

package/workspace-snapshot/files/tests/github/check-policy.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { evaluateChecksForMerge } from "../../src/github/check-policy.js";
+import type { HarnessConfig } from "../../src/config/types.js";
+
+const baseConfig: HarnessConfig = {
+  version: 1,
+  orchestratorMarker: "harness-orchestrator-v1",
+  logDirectory: "runs",
+  repos: [
+    {
+      id: "target-app",
+      targetRepo: "https://github.com/owner/example-target-app",
+      baseBranch: "main",
+    },
+  ],
+  allowedTargetRepos: ["https://github.com/owner/example-target-app"],
+};
+
+describe("evaluateChecksForMerge", () => {
+  it("blocks when no checks and allowUnknownChecks is false", () => {
+    const result = evaluateChecksForMerge([], baseConfig);
+    expect(result.decision).toBe("block");
+    expect(result.classification).toBe("checks_unknown");
+  });
+
+  it("allows success checks", () => {
+    const result = evaluateChecksForMerge(
+      [{ name: "CI", status: "completed", conclusion: "success", detailsUrl: null }],
+      baseConfig,
+    );
+    expect(result.decision).toBe("allow");
+  });
+
+  it("blocks failing checks", () => {
+    const result = evaluateChecksForMerge(
+      [{ name: "CI", status: "completed", conclusion: "failure", detailsUrl: null }],
+      baseConfig,
+    );
+    expect(result.decision).toBe("block");
+    expect(result.classification).toBe("checks_failing");
+  });
+
+  it("blocks pending checks by default", () => {
+    const result = evaluateChecksForMerge(
+      [{ name: "CI", status: "in_progress", conclusion: null, detailsUrl: null }],
+      baseConfig,
+    );
+    expect(result.decision).toBe("block");
+    expect(result.classification).toBe("checks_pending");
+  });
+
+  it("allows pending checks when configured", () => {
+    const result = evaluateChecksForMerge(
+      [{ name: "CI", status: "in_progress", conclusion: null, detailsUrl: null }],
+      { ...baseConfig, merge: { allowPendingChecks: true } },
+    );
+    expect(result.decision).toBe("allow");
+  });
+});

package/workspace-snapshot/files/tests/github/client.test.ts

@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { GitHubClient, GitHubApiError } from "../../src/github/client.js";
+
+const mockFetch = vi.fn();
+const SENTINEL_SECRET = "ghp_sentinelSecretValueForClientTests";
+
+function jsonResponse(status: number, body: unknown) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: async () => JSON.stringify(body),
+  };
+}
+
+function emptyBodyResponse(status: number) {
+  return {
+    ok: true,
+    status,
+    text: async () => "",
+  };
+}
+
+describe("GitHubClient", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("marks draft PR ready via GraphQL mutation", async () => {
+    const pull = {
+      node_id: "PR_kwDOExample",
+      title: "[WES-18] test",
+      html_url: "https://github.com/owner/example-target-app/pull/7",
+      state: "open",
+      merged: false,
+      draft: true,
+      merged_at: null,
+      merge_commit_sha: null,
+      head: { ref: "cursor/wes-18-test", sha: "abc123" },
+      base: { ref: "main" },
+    };
+
+    mockFetch
+      .mockResolvedValueOnce(jsonResponse(200, pull))
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            markPullRequestReadyForReview: {
+              pullRequest: { isDraft: false },
+            },
+          },
+        }),
+      })
+      .mockResolvedValueOnce(jsonResponse(200, { ...pull, draft: false }));
+
+    const client = new GitHubClient({ token: "test-token" });
+    const result = await client.markPullRequestReadyForReview(
+      "weston-uribe",
+      "example-target-app",
+      7,
+    );
+
+    expect(result.draft).toBe(false);
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+    const graphqlCall = mockFetch.mock.calls[1];
+    expect(graphqlCall[0]).toBe("https://api.github.com/graphql");
+    expect(graphqlCall[1]?.method).toBe("POST");
+    const body = JSON.parse(String(graphqlCall[1]?.body));
+    expect(body.variables.pullRequestId).toBe("PR_kwDOExample");
+    expect(body.query).toContain("markPullRequestReadyForReview");
+    const patchCalls = mockFetch.mock.calls.filter(
+      ([url, init]) =>
+        String(url).includes("/pulls/7") && init?.method === "PATCH",
+    );
+    expect(patchCalls).toHaveLength(0);
+  });
+
+  it("throws when GraphQL mutation returns errors", async () => {
+    mockFetch
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          node_id: "PR_kwDOExample",
+          title: "test",
+          html_url: "https://github.com/example/repo/pull/1",
+          state: "open",
+          merged: false,
+          draft: true,
+          merged_at: null,
+          merge_commit_sha: null,
+          head: { ref: "branch", sha: "abc" },
+          base: { ref: "main" },
+        }),
+      )
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          errors: [{ message: "Resource not accessible by integration" }],
+        }),
+      });
+
+    const client = new GitHubClient({ token: "test-token" });
+    await expect(
+      client.markPullRequestReadyForReview("owner", "repo", 1),
+    ).rejects.toBeInstanceOf(GitHubApiError);
+  });
+
+  it("merges a PR with expected head sha", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(200, { sha: "merged-sha", merged: true }),
+    );
+
+    const client = new GitHubClient({ token: "test-token" });
+    const result = await client.mergePullRequest("owner", "repo", 12, {
+      mergeMethod: "squash",
+      commitTitle: "Merge PR",
+      expectedHeadSha: "abc123",
+    });
+
+    expect(result.sha).toBe("merged-sha");
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0]!;
+    expect(url).toBe("https://api.github.com/repos/owner/repo/pulls/12/merge");
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      merge_method: "squash",
+      commit_title: "Merge PR",
+      sha: "abc123",
+    });
+  });
+
+  it("updates a PR branch with expected head sha", async () => {
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(202, { message: "Updating pull request branch." }),
+    );
+
+    const client = new GitHubClient({ token: "test-token" });
+    const result = await client.updatePullRequestBranch("owner", "repo", 12, {
+      expectedHeadSha: "abc123",
+    });
+
+    expect(result.message).toContain("Updating");
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0]!;
+    expect(url).toBe(
+      "https://api.github.com/repos/owner/repo/pulls/12/update-branch",
+    );
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      expected_head_sha: "abc123",
+    });
+  });
+
+  it("upsertActionsSecret resolves for 201 create with empty body", async () => {
+    mockFetch.mockResolvedValueOnce(emptyBodyResponse(201));
+
+    const client = new GitHubClient({ token: "test-token" });
+    await expect(
+      client.upsertActionsSecret(
+        "owner",
+        "repo",
+        "LINEAR_API_KEY",
+        "encrypted:payload",
+        "public-key-id",
+      ),
+    ).resolves.toBeUndefined();
+
+    const [url, init] = mockFetch.mock.calls[0]!;
+    expect(url).toBe(
+      "https://api.github.com/repos/owner/repo/actions/secrets/LINEAR_API_KEY",
+    );
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      encrypted_value: "encrypted:payload",
+      key_id: "public-key-id",
+    });
+  });
+
+  it("upsertActionsSecret resolves for 204 update with empty body", async () => {
+    mockFetch.mockResolvedValueOnce(emptyBodyResponse(204));
+
+    const client = new GitHubClient({ token: "test-token" });
+    await expect(
+      client.upsertActionsSecret(
+        "owner",
+        "repo",
+        "CURSOR_API_KEY",
+        "encrypted:payload",
+        "public-key-id",
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it("upsertActionsSecret throws sanitized GitHubApiError for non-2xx responses", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      text: async () => `token ${SENTINEL_SECRET} is invalid`,
+    });
+
+    const client = new GitHubClient({ token: "test-token" });
+    let caught: GitHubApiError | undefined;
+    try {
+      await client.upsertActionsSecret(
+        "owner",
+        "repo",
+        "HARNESS_GITHUB_TOKEN",
+        "encrypted:payload",
+        "public-key-id",
+      );
+    } catch (error) {
+      caught = error as GitHubApiError;
+    }
+
+    expect(caught).toBeInstanceOf(GitHubApiError);
+    expect(caught?.status).toBe(403);
+    expect(caught?.message).not.toContain(SENTINEL_SECRET);
+    expect(JSON.stringify(caught)).not.toContain(SENTINEL_SECRET);
+  });
+});

package/workspace-snapshot/files/tests/github/commit-reachability.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import type { GitHubCompareResult } from "../../src/github/client.js";
+import {
+  isCommitReachableFromBranch,
+  resolvePromotionProof,
+} from "../../src/github/commit-reachability.js";
+
+class MockGitHubClient {
+  compareResults: GitHubCompareResult[] = [];
+  branchHead = "prod-head-sha";
+  pullMergeCommit = "pr-merge-sha";
+
+  async getBranchRef() {
+    return { ref: "refs/heads/main", object: { sha: this.branchHead, type: "commit", url: "" } };
+  }
+
+  async compareCommits() {
+    return this.compareResults.shift() ?? {
+      status: "diverged",
+      ahead_by: 0,
+      behind_by: 1,
+      commits: [],
+    };
+  }
+
+  async getPullRequest() {
+    return {
+      node_id: "pr-node",
+      title: "Test PR",
+      html_url: "https://github.com/o/r/pull/1",
+      state: "closed",
+      merged: true,
+      merged_at: "2026-07-07T00:00:00.000Z",
+      merge_commit_sha: this.pullMergeCommit,
+      head: { ref: "cursor/wes-1-test", sha: "head-sha" },
+      base: { ref: "dev" },
+    };
+  }
+}
+
+describe("commit reachability", () => {
+  it("treats identical production head as reachable", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [{ status: "identical", ahead_by: 0, behind_by: 0, commits: [] }];
+
+    const result = await isCommitReachableFromBranch(
+      client as never,
+      "o",
+      "r",
+      "merge-sha",
+      "main",
+    );
+
+    expect(result.reachable).toBe(true);
+  });
+
+  it("treats descendant production head as reachable", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [{ status: "ahead", ahead_by: 2, behind_by: 0, commits: [] }];
+
+    const result = await isCommitReachableFromBranch(
+      client as never,
+      "o",
+      "r",
+      "merge-sha",
+      "main",
+    );
+
+    expect(result.reachable).toBe(true);
+  });
+
+  it("treats diverged history as not reachable", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [{ status: "diverged", ahead_by: 1, behind_by: 2, commits: [] }];
+
+    const result = await isCommitReachableFromBranch(
+      client as never,
+      "o",
+      "r",
+      "merge-sha",
+      "main",
+    );
+
+    expect(result.reachable).toBe(false);
+  });
+
+  it("treats production head behind merge commit as not reachable", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [{ status: "behind", ahead_by: 0, behind_by: 3, commits: [] }];
+
+    const result = await isCommitReachableFromBranch(
+      client as never,
+      "o",
+      "r",
+      "merge-sha",
+      "main",
+    );
+
+    expect(result.reachable).toBe(false);
+  });
+});
+
+describe("resolvePromotionProof", () => {
+  it("promotes when stored merge commit is reachable", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [{ status: "ahead", ahead_by: 1, behind_by: 0, commits: [] }];
+
+    const proof = await resolvePromotionProof({
+      client: client as never,
+      targetRepo: "https://github.com/o/r",
+      productionBranch: "main",
+      mergeCommitSha: "merge-sha",
+    });
+
+    expect(proof.proof).toBe(true);
+    if (proof.proof) {
+      expect(proof.method).toBe("merge_commit_sha");
+    }
+  });
+
+  it("does not promote on issue-key diagnostic evidence alone", async () => {
+    const client = new MockGitHubClient();
+    client.compareResults = [
+      { status: "behind", ahead_by: 0, behind_by: 2, commits: [] },
+      {
+        status: "ahead",
+        ahead_by: 1,
+        behind_by: 0,
+        commits: [{ sha: "diag1", commit: { message: "Fix WES-1 footer" } }],
+      },
+    ];
+
+    const proof = await resolvePromotionProof({
+      client: client as never,
+      targetRepo: "https://github.com/o/r",
+      productionBranch: "main",
+      baseBranch: "dev",
+      mergeCommitSha: "missing-on-main",
+      issueKey: "WES-1",
+    });
+
+    expect(proof.proof).toBe(false);
+    if (!proof.proof) {
+      expect(proof.reason).toBe("production_not_promoted");
+      expect(proof.diagnosticIssueKeyCommits).toEqual(["diag1"]);
+    }
+  });
+});

package/workspace-snapshot/files/tests/github/merge-result.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { GitHubApiError } from "../../src/github/client.js";
+import {
+  classifyMergeError,
+  isAlreadyMergedError,
+} from "../../src/github/merge-result.js";
+
+describe("merge-result", () => {
+  it("classifies 405 as merge failure when PR is not mergeable", () => {
+    const error = new GitHubApiError(405, "Pull Request is not mergeable");
+    expect(classifyMergeError(error)).toBe("github_merge_failure");
+    expect(isAlreadyMergedError(error)).toBe(false);
+  });
+
+  it("classifies 409 as already merged", () => {
+    const error = new GitHubApiError(409, "Pull Request already merged");
+    expect(classifyMergeError(error)).toBe("pr_already_merged");
+    expect(isAlreadyMergedError(error)).toBe(true);
+  });
+
+  it("classifies 405 as already merged when message says merged", () => {
+    const error = new GitHubApiError(405, "Pull Request has already been merged");
+    expect(classifyMergeError(error)).toBe("pr_already_merged");
+    expect(isAlreadyMergedError(error)).toBe(true);
+  });
+});

package/workspace-snapshot/files/tests/github/pr-discovery.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildIssueKeyBranchPattern,
+  findImplementationPullRequest,
+  headBranchMatchesIssueKey,
+} from "../../src/github/pr-discovery.js";
+import type { GitHubPullRequestListItem } from "../../src/github/client.js";
+
+class MockGitHubClient {
+  pulls: GitHubPullRequestListItem[] = [];
+
+  async listPullRequests() {
+    return this.pulls;
+  }
+}
+
+describe("pr discovery", () => {
+  it("matches issue key in branch name case-insensitively", () => {
+    expect(headBranchMatchesIssueKey("cursor/wes-13-hello-world", "WES-13")).toBe(true);
+    expect(headBranchMatchesIssueKey("cursor/other-branch", "WES-13")).toBe(false);
+    expect(buildIssueKeyBranchPattern("WES-13").test("cursor/WES-13-test")).toBe(true);
+  });
+
+  it("returns most recent matching open PR on base branch", async () => {
+    const client = new MockGitHubClient();
+    client.pulls = [
+      {
+        number: 4,
+        html_url: "https://github.com/o/r/pull/4",
+        state: "open",
+        created_at: "2026-07-07T02:00:00.000Z",
+        head: { ref: "cursor/wes-13-new", sha: "sha-new" },
+        base: { ref: "dev" },
+      },
+      {
+        number: 3,
+        html_url: "https://github.com/o/r/pull/3",
+        state: "open",
+        created_at: "2026-07-07T01:00:00.000Z",
+        head: { ref: "cursor/wes-13-old", sha: "sha-old" },
+        base: { ref: "dev" },
+      },
+    ];
+
+    const discovered = await findImplementationPullRequest(
+      client as never,
+      "https://github.com/o/r",
+      "dev",
+      "WES-13",
+    );
+
+    expect(discovered?.prNumber).toBe(4);
+    expect(discovered?.branch).toBe("cursor/wes-13-new");
+  });
+});