p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/tests/setup/harness-snapshot-structured-errors.test.ts

@@ -0,0 +1,137 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MockGitHubHarnessProvisioningProvider } from "../../src/setup/github-remote-provider.js";
+import {
+  applyHarnessRepoProvisioning,
+  previewHarnessRepoProvisioning,
+} from "../../src/setup/harness-repo-provisioning.js";
+import { createTestWorkspaceSnapshotRoot } from "./test-workspace-snapshot-fixture.js";
+import { SnapshotProvisioningError } from "../../src/setup/harness-snapshot-provisioning-helpers.js";
+import * as snapshotProvisioning from "../../src/setup/harness-snapshot-provisioning.js";
+
+const snapshotFixture = vi.hoisted(() => ({
+  snapshotRoot: "",
+  packageRoot: "",
+  manifest: null as Awaited<
+    ReturnType<typeof createTestWorkspaceSnapshotRoot>
+  >["manifest"] | null,
+  fingerprint: "",
+}));
+
+vi.mock("../../src/setup/harness-workspace-snapshot-loader.js", () => ({
+  loadEmbeddedWorkspaceSnapshot: vi.fn(async () => {
+    if (!snapshotFixture.manifest) {
+      return {
+        ok: false as const,
+        state: "snapshot-unavailable" as const,
+        message: "Test snapshot fixture is not initialized.",
+      };
+    }
+    return {
+      ok: true as const,
+      packageRoot: snapshotFixture.packageRoot,
+      snapshotRoot: snapshotFixture.snapshotRoot,
+      packageVersion: "0.3.0",
+      manifest: snapshotFixture.manifest,
+      fingerprint: snapshotFixture.fingerprint,
+    };
+  }),
+}));
+
+describe("structured provisioning recovery states", () => {
+  let workspaceDir = "";
+
+  beforeEach(async () => {
+    process.env.P_DEV_RUNTIME_MODE = "packaged";
+    process.env.P_DEV_PACKAGE_VERSION = "0.3.0";
+    const fixture = await createTestWorkspaceSnapshotRoot("0.3.0");
+    snapshotFixture.snapshotRoot = fixture.snapshotRoot;
+    snapshotFixture.packageRoot = fixture.packageRoot;
+    snapshotFixture.manifest = fixture.manifest;
+    snapshotFixture.fingerprint = fixture.fingerprint;
+    workspaceDir = await mkdtemp(path.join(tmpdir(), "p-dev-structured-err-"));
+    await mkdir(path.join(workspaceDir, ".harness"), { recursive: true });
+    await writeFile(
+      path.join(workspaceDir, ".env.local"),
+      ["GITHUB_TOKEN=ghp_test_token", "HARNESS_CONFIG_PATH=.harness/config.local.json"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+  });
+
+  beforeEach(() => {
+    process.env.P_DEV_RUNTIME_MODE = "packaged";
+  });
+
+  afterEach(async () => {
+    delete process.env.P_DEV_RUNTIME_MODE;
+    delete process.env.P_DEV_PACKAGE_VERSION;
+    vi.restoreAllMocks();
+    if (workspaceDir) {
+      await rm(workspaceDir, { recursive: true, force: true });
+    }
+    if (snapshotFixture.packageRoot) {
+      await rm(snapshotFixture.packageRoot, { recursive: true, force: true });
+    }
+    snapshotFixture.manifest = null;
+  });
+
+  it("maps marker-commit-failed code to marker-write-pending regardless of message wording", async () => {
+    const provider = new MockGitHubHarnessProvisioningProvider({
+      authenticatedUser: { id: 1, login: "test-user" },
+    });
+    vi.spyOn(snapshotProvisioning, "provisionHarnessWorkspaceFromSnapshot").mockResolvedValue({
+      ok: false,
+      message: "totally unrelated human text without marker keyword",
+      recoverable: true,
+      code: "marker-commit-failed",
+    });
+
+    const preview = await previewHarnessRepoProvisioning({
+      cwd: workspaceDir,
+      provider,
+      operationId: "op-structured",
+    });
+    const apply = await applyHarnessRepoProvisioning({
+      cwd: workspaceDir,
+      provider,
+      confirmed: true,
+      fingerprint: preview.fingerprint,
+      operationId: preview.operationId,
+    });
+    expect(apply.state).toBe("marker-write-pending");
+  });
+
+  it("maps description-finalization-failed code to marker-write-pending", async () => {
+    const provider = new MockGitHubHarnessProvisioningProvider({
+      authenticatedUser: { id: 1, login: "test-user" },
+    });
+    vi.spyOn(snapshotProvisioning, "provisionHarnessWorkspaceFromSnapshot").mockResolvedValue({
+      ok: false,
+      message: new SnapshotProvisioningError(
+        "description-finalization-failed",
+        "custom operator-facing copy",
+        true,
+      ).message,
+      recoverable: true,
+      code: "description-finalization-failed",
+    });
+
+    const preview = await previewHarnessRepoProvisioning({
+      cwd: workspaceDir,
+      provider,
+      operationId: "op-desc-code",
+    });
+    const apply = await applyHarnessRepoProvisioning({
+      cwd: workspaceDir,
+      provider,
+      confirmed: true,
+      fingerprint: preview.fingerprint,
+      operationId: preview.operationId,
+    });
+    expect(apply.state).toBe("marker-write-pending");
+  });
+});

package/workspace-snapshot/files/tests/setup/harness-snapshot-upload-rate-limit.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { GitHubApiError } from "../../src/github/client.js";
+import { GitHubUploadRateLimitGate } from "../../src/setup/github-upload-rate-limit-gate.js";
+import {
+  createProvisioningRetryContext,
+  getDefaultSnapshotUploadConcurrency,
+  isRetryableGitHubError,
+  resolveSnapshotUploadConcurrency,
+} from "../../src/setup/harness-snapshot-provisioning.js";
+import { preserveGitHubSetupError } from "../../src/setup/github-remote-setup-live.js";
+
+describe("resolveSnapshotUploadConcurrency", () => {
+  const original = process.env.HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY;
+
+  afterEach(() => {
+    if (original === undefined) {
+      delete process.env.HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY;
+    } else {
+      process.env.HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY = original;
+    }
+  });
+
+  it("defaults to 2 when unset", () => {
+    delete process.env.HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY;
+    expect(resolveSnapshotUploadConcurrency()).toBe(2);
+    expect(getDefaultSnapshotUploadConcurrency()).toBe(2);
+  });
+
+  it("rejects invalid overrides", () => {
+    expect(() => resolveSnapshotUploadConcurrency("abc")).toThrow(
+      /Invalid HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY/,
+    );
+    expect(() => resolveSnapshotUploadConcurrency("0")).toThrow(
+      /between 1 and 4/,
+    );
+    expect(() => resolveSnapshotUploadConcurrency("5")).toThrow(
+      /between 1 and 4/,
+    );
+  });
+
+  it("accepts integer overrides within bounds", () => {
+    expect(resolveSnapshotUploadConcurrency("3")).toBe(3);
+  });
+});
+
+describe("GitHubUploadRateLimitGate", () => {
+  it("coordinates concurrent workers on the same pause deadline", async () => {
+    let now = 0;
+    const sleeps: number[] = [];
+    const gate = new GitHubUploadRateLimitGate({
+      now: () => now,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+        now += ms;
+      },
+    });
+
+    gate.recordRateLimitFailure(new GitHubApiError(403, "secondary rate limit"));
+    await gate.waitBeforeMutation();
+    await gate.waitBeforeMutation();
+
+    expect(sleeps).toEqual([60_000]);
+    expect(now).toBe(60_000);
+  });
+});
+
+describe("isRetryableGitHubError", () => {
+  it("does not retry non-rate-limit 403", () => {
+    const error = preserveGitHubSetupError(
+      new GitHubApiError(403, "Resource not accessible by integration"),
+    );
+    expect(isRetryableGitHubError(error)).toBe(false);
+  });
+
+  it("retries preserved 429 errors", () => {
+    const error = preserveGitHubSetupError(
+      new GitHubApiError(429, "secondary rate limit"),
+    );
+    expect(isRetryableGitHubError(error)).toBe(true);
+  });
+});
+
+describe("createProvisioningRetryContext", () => {
+  it("emits rate-limit pause callbacks without waiting real time", async () => {
+    let now = 0;
+    const pauses: number[] = [];
+    const context = createProvisioningRetryContext({
+      onRateLimitPause: (seconds) => {
+        pauses.push(seconds);
+      },
+    });
+    context.gate = new GitHubUploadRateLimitGate({
+      now: () => now,
+      sleep: async (ms) => {
+        now += ms;
+      },
+    });
+
+    const error = new GitHubApiError(403, "secondary rate limit");
+    const delayMs = context.gate.recordRateLimitFailure(error);
+    context.onRateLimitPause?.(Math.ceil(delayMs / 1_000), "snapshot-objects-uploading");
+
+    expect(pauses).toEqual([60]);
+  });
+});

package/workspace-snapshot/files/tests/setup/linear-setup-apply.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from "vitest";
+import { ensureWorkflowStatesForTeam } from "../../src/setup/linear-setup-apply.js";
+import type { LinearClient } from "@linear/sdk";
+
+function createMockClient(input?: {
+  initialStates?: Array<{ id: string; name: string; type: string }>;
+  duplicateOnCreate?: string;
+}) {
+  let workflowStates = [
+    ...(input?.initialStates ?? [
+      { id: "s-backlog", name: "Backlog", type: "backlog" },
+      { id: "s-canceled", name: "Canceled", type: "canceled" },
+    ]),
+  ];
+
+  const client = {
+    workflowStates: vi.fn(async () => ({
+      nodes: workflowStates,
+      pageInfo: { hasNextPage: false },
+      fetchNext: vi.fn(),
+    })),
+    createWorkflowState: vi.fn(async (args: { name: string }) => {
+      if (input?.duplicateOnCreate === args.name) {
+        workflowStates = [
+          ...workflowStates,
+          {
+            id: "existing-after-race",
+            name: args.name,
+            type: "unstarted",
+          },
+        ];
+        throw new Error(
+          "Failed, cannot create a duplicate workflow state. A workflow state with this name and type already exists for this team.",
+        );
+      }
+      workflowStates = [
+        ...workflowStates,
+        {
+          id: `created-${args.name}`,
+          name: args.name,
+          type: "started",
+        },
+      ];
+      return {
+        workflowState: Promise.resolve({
+          id: `created-${args.name}`,
+          name: args.name,
+          type: "started",
+        }),
+      };
+    }),
+  } as unknown as LinearClient;
+
+  return client;
+}
+
+describe("linear-setup-apply", () => {
+  it("re-lists default seeded states before creating missing workflow states", async () => {
+    const client = createMockClient();
+    const created: string[] = [];
+    const skipped: string[] = [];
+
+    const complete = await ensureWorkflowStatesForTeam({
+      client,
+      teamId: "team-1",
+      created,
+      skipped,
+    });
+
+    expect(skipped).toContain("status:Backlog");
+    expect(skipped).toContain("status:Canceled");
+    expect(created.some((entry) => entry.startsWith("status:"))).toBe(true);
+    expect(complete).toBe(true);
+  });
+
+  it("reuses an existing workflow state when Linear reports a duplicate conflict", async () => {
+    const client = createMockClient({
+      duplicateOnCreate: "Ready for Planning",
+    });
+    const created: string[] = [];
+    const skipped: string[] = [];
+
+    await ensureWorkflowStatesForTeam({
+      client,
+      teamId: "team-1",
+      created,
+      skipped,
+    });
+
+    expect(skipped).toContain("status:Ready for Planning");
+    expect(
+      created.filter((entry) => entry === "status:Ready for Planning"),
+    ).toHaveLength(0);
+  });
+
+  it("computes post-apply coverage from the final team workflow state list", async () => {
+    const client = createMockClient({
+      initialStates: [
+        { id: "s1", name: "Backlog", type: "backlog" },
+        { id: "s2", name: "Canceled", type: "canceled" },
+        { id: "s3", name: "Ready for Planning", type: "unstarted" },
+        { id: "s4", name: "Planning", type: "started" },
+        { id: "s5", name: "Ready for Build", type: "unstarted" },
+        { id: "s6", name: "Building", type: "started" },
+        { id: "s7", name: "PR Open", type: "started" },
+        { id: "s8", name: "PM Review", type: "started" },
+        { id: "s9", name: "Engineering Review", type: "started" },
+        { id: "s10", name: "Needs Revision", type: "unstarted" },
+        { id: "s11", name: "Revising", type: "started" },
+        { id: "s12", name: "Ready to Merge", type: "started" },
+        { id: "s13", name: "Merging", type: "started" },
+        { id: "s14", name: "Merged to Dev", type: "completed" },
+        { id: "s15", name: "Merged / Deployed", type: "completed" },
+        { id: "s16", name: "Blocked", type: "started" },
+      ],
+    });
+    const created: string[] = [];
+    const skipped: string[] = [];
+
+    const complete = await ensureWorkflowStatesForTeam({
+      client,
+      teamId: "team-1",
+      created,
+      skipped,
+    });
+
+    expect(complete).toBe(true);
+    expect(created).toHaveLength(0);
+    expect(skipped.length).toBeGreaterThan(0);
+  });
+});

package/workspace-snapshot/files/tests/setup/linear-setup-plan.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import {
+  findExistingProjectForCreateInput,
+  findExistingTeamForCreateInput,
+  isWorkflowStatusCoverageComplete,
+  matchWorkflowStates,
+  normalizeLinearName,
+} from "../../src/setup/linear-setup-plan.js";
+
+describe("linear-setup-plan", () => {
+  it("reuses existing workflow states by normalized name", () => {
+    const plan = matchWorkflowStates([
+      { id: "1", name: "  backlog ", type: "backlog" },
+      { id: "2", name: "Ready for Planning", type: "unstarted" },
+    ]);
+
+    const backlog = plan.find((entry) => entry.name === "Backlog");
+    const ready = plan.find((entry) => entry.name === "Ready for Planning");
+    const building = plan.find((entry) => entry.name === "Building");
+
+    expect(backlog?.present).toBe(true);
+    expect(backlog?.action).toBe("skip");
+    expect(ready?.present).toBe(true);
+    expect(building?.present).toBe(false);
+    expect(building?.action).toBe("create");
+  });
+
+  it("normalizes names for team and project matching", () => {
+    expect(normalizeLinearName("  Harness Test ")).toBe("harness test");
+  });
+
+  it("reuses an existing team by key or normalized name during create preview", () => {
+    const teams = [
+      { id: "team-1", key: "H62", name: "Harness Configure M6.2 Test" },
+    ];
+
+    expect(
+      findExistingTeamForCreateInput(teams, {
+        teamKey: "h62",
+        teamName: "Harness Configure M6.2 Test",
+      })?.id,
+    ).toBe("team-1");
+
+    expect(
+      findExistingTeamForCreateInput(teams, {
+        teamKey: "NEW",
+        teamName: "Harness Configure M6.2 Test",
+      })?.id,
+    ).toBe("team-1");
+  });
+
+  it("reuses an existing project by normalized name and team association", () => {
+    const projects = [
+      {
+        id: "project-1",
+        name: "Harness Configure M6.2 Project",
+        teamIds: ["team-1"],
+      },
+      {
+        id: "project-2",
+        name: "Harness Configure M6.2 Project",
+        teamIds: ["team-2"],
+      },
+    ];
+
+    expect(
+      findExistingProjectForCreateInput(projects, {
+        projectName: "  harness configure m6.2 project ",
+        teamId: "team-1",
+      })?.id,
+    ).toBe("project-1");
+  });
+
+  it("reports workflow coverage complete only when creatable statuses are present", () => {
+    const incomplete = matchWorkflowStates([
+      { id: "1", name: "Backlog", type: "backlog" },
+    ]);
+    expect(isWorkflowStatusCoverageComplete(incomplete)).toBe(false);
+
+    const complete = matchWorkflowStates(
+      [
+        "Backlog",
+        "Ready for Planning",
+        "Planning",
+        "Ready for Build",
+        "Building",
+        "PR Open",
+        "PM Review",
+        "Engineering Review",
+        "Needs Revision",
+        "Revising",
+        "Ready to Merge",
+        "Merging",
+        "Merged to Dev",
+        "Merged / Deployed",
+        "Blocked",
+        "Canceled",
+      ].map((name, index) => ({
+        id: String(index),
+        name,
+        type: "started",
+      })),
+    );
+    expect(isWorkflowStatusCoverageComplete(complete)).toBe(true);
+  });
+});

package/workspace-snapshot/files/tests/setup/linear-webhook-env-local.test.ts

@@ -0,0 +1,95 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  persistGeneratedLinearWebhookSecret,
+  readLinearWebhookSecretFromEnvLocal,
+  upsertLinearWebhookSecretInEnvContent,
+} from "../../src/setup/linear-webhook-env-local.js";
+import { parseEnvFileContent } from "../../src/setup/env-merge.js";
+import { resolveLocalFilePaths } from "../../src/setup/setup-state.js";
+
+const GENERATED_SECRET = "a".repeat(64);
+const EXISTING_OPERATOR_SECRET = "operator-webhook-secret-value";
+const EXISTING_LINEAR_API_KEY = "lin_api_existing";
+
+describe("linear-webhook-env-local", () => {
+  let tempRoot = "";
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(path.join(tmpdir(), "linear-webhook-env-local-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  it("writes generated LINEAR_WEBHOOK_SECRET to a new .env.local file", async () => {
+    const wrote = await persistGeneratedLinearWebhookSecret({
+      cwd: tempRoot,
+      secret: GENERATED_SECRET,
+    });
+
+    expect(wrote).toBe(true);
+    const content = await readFile(
+      resolveLocalFilePaths(tempRoot).envLocal,
+      "utf8",
+    );
+    expect(content).toContain(`LINEAR_WEBHOOK_SECRET=${GENERATED_SECRET}`);
+  });
+
+  it("preserves existing tokens and config when upserting webhook secret", async () => {
+    const paths = resolveLocalFilePaths(tempRoot);
+    await writeFile(
+      paths.envLocal,
+      [
+        "# local notes",
+        "MY_CUSTOM_TOOL=keep-me",
+        `LINEAR_API_KEY=${EXISTING_LINEAR_API_KEY}`,
+      ].join("\n"),
+      "utf8",
+    );
+
+    await persistGeneratedLinearWebhookSecret({
+      cwd: tempRoot,
+      secret: GENERATED_SECRET,
+    });
+
+    const content = await readFile(paths.envLocal, "utf8");
+    const parsed = parseEnvFileContent(content);
+    expect(content).toContain("# local notes");
+    expect(content).toContain("MY_CUSTOM_TOOL=keep-me");
+    expect(parsed.values.LINEAR_API_KEY).toBe(EXISTING_LINEAR_API_KEY);
+    expect(parsed.values.LINEAR_WEBHOOK_SECRET).toBe(GENERATED_SECRET);
+  });
+
+  it("does not overwrite an explicit existing LINEAR_WEBHOOK_SECRET by default", async () => {
+    const paths = resolveLocalFilePaths(tempRoot);
+    await writeFile(
+      paths.envLocal,
+      `LINEAR_WEBHOOK_SECRET=${EXISTING_OPERATOR_SECRET}\n`,
+      "utf8",
+    );
+
+    const wrote = await persistGeneratedLinearWebhookSecret({
+      cwd: tempRoot,
+      secret: GENERATED_SECRET,
+    });
+
+    expect(wrote).toBe(false);
+    const saved = await readLinearWebhookSecretFromEnvLocal({ cwd: tempRoot });
+    expect(saved).toBe(EXISTING_OPERATOR_SECRET);
+  });
+
+  it("upsertLinearWebhookSecretInEnvContent replaces an existing key in place", () => {
+    const content = upsertLinearWebhookSecretInEnvContent(
+      `LINEAR_WEBHOOK_SECRET=old-secret\nLINEAR_API_KEY=keep\n`,
+      GENERATED_SECRET,
+    );
+
+    expect(content).toContain(`LINEAR_WEBHOOK_SECRET=${GENERATED_SECRET}`);
+    expect(content).toContain("LINEAR_API_KEY=keep");
+    expect(content).not.toContain("old-secret");
+  });
+});