p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/tests/gui/workflow-workspace.test.ts

@@ -0,0 +1,188 @@
+import { readFileSync } from "node:fs";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("server-only", () => ({}));
+
+vi.mock("../../src/workflow-page/linear-status-source.js", () => ({
+  loadLiveLinearStatuses: vi.fn(),
+}));
+
+vi.mock("../../src/workflow-page/model-catalog.js", () => ({
+  fetchLiveCursorModelCatalog: vi.fn(),
+}));
+
+import { loadLiveLinearStatuses } from "../../src/workflow-page/linear-status-source.js";
+import { fetchLiveCursorModelCatalog } from "../../src/workflow-page/model-catalog.js";
+import {
+  normalizeHarnessEnvPaths,
+  resolveHarnessRepoRoot,
+  resolveHarnessWorkspaceDir,
+} from "../../src/gui/repo-root.js";
+import { loadWorkflowBootstrap } from "../../apps/gui/lib/workflow-server.js";
+import { writeControlPlaneSetupState } from "../../src/setup/control-plane-setup-state.js";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+const FAKE_LINEAR_KEY = "fake-linear-secret-value";
+const FAKE_CURSOR_KEY = "fake-cursor-secret-value";
+
+const CONFIG_JSON = JSON.stringify(
+  {
+    version: 1,
+    orchestratorMarker: "harness-orchestrator-v1",
+    logDirectory: "runs",
+    repos: [
+      {
+        id: "my-product",
+        linearProjects: ["My Product"],
+        targetRepo: "https://github.com/acme/my-product",
+        baseBranch: "dev",
+        productionBranch: "main",
+      },
+    ],
+    allowedTargetRepos: ["https://github.com/acme/my-product"],
+    linear: { teamKey: "WES" },
+  },
+  null,
+  2,
+);
+
+describe("workflow operator workspace contract", () => {
+  let sourceRoot = "";
+  let operatorRoot = "";
+  let previousRepoRoot: string | undefined;
+  let previousDevHome: string | undefined;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    previousRepoRoot = process.env.HARNESS_REPO_ROOT;
+    previousDevHome = process.env.P_DEV_HOME;
+
+    sourceRoot = await mkdtemp(path.join(tmpdir(), "harness-source-"));
+    operatorRoot = await mkdtemp(path.join(tmpdir(), "harness-operator-"));
+
+    await writeFile(
+      path.join(sourceRoot, "package.json"),
+      JSON.stringify({ name: "agentic-product-development-harness" }),
+      "utf8",
+    );
+    await mkdir(path.join(sourceRoot, "apps", "gui"), { recursive: true });
+
+    process.env.HARNESS_REPO_ROOT = sourceRoot;
+    process.env.P_DEV_HOME = operatorRoot;
+
+    await mkdir(path.join(operatorRoot, ".harness"), { recursive: true });
+    await writeFile(
+      path.join(operatorRoot, ".env.local"),
+      [
+        "HARNESS_CONFIG_PATH=.harness/config.local.json",
+        `LINEAR_API_KEY=${FAKE_LINEAR_KEY}`,
+        `CURSOR_API_KEY=${FAKE_CURSOR_KEY}`,
+      ].join("\n"),
+      "utf8",
+    );
+    await writeFile(
+      path.join(operatorRoot, ".harness", "config.local.json"),
+      CONFIG_JSON,
+      "utf8",
+    );
+    await writeControlPlaneSetupState(
+      {
+        version: 1,
+        linear: {
+          teamId: "team-123",
+          teamKey: "WES",
+          teamName: "Weston",
+        },
+      },
+      operatorRoot,
+    );
+
+    vi.mocked(loadLiveLinearStatuses).mockResolvedValue({
+      statuses: [{ id: "status-1", name: "Todo", type: "unstarted" }],
+      loadState: "loaded",
+    });
+    vi.mocked(fetchLiveCursorModelCatalog).mockResolvedValue({
+      catalog: [
+        {
+          id: "composer-2.5",
+          availability: "available",
+          supportedParameters: [],
+        },
+      ],
+      loadState: "loaded",
+    });
+  });
+
+  afterEach(async () => {
+    if (previousRepoRoot === undefined) {
+      delete process.env.HARNESS_REPO_ROOT;
+    } else {
+      process.env.HARNESS_REPO_ROOT = previousRepoRoot;
+    }
+    if (previousDevHome === undefined) {
+      delete process.env.P_DEV_HOME;
+    } else {
+      process.env.P_DEV_HOME = previousDevHome;
+    }
+    await rm(sourceRoot, { recursive: true, force: true });
+    await rm(operatorRoot, { recursive: true, force: true });
+  });
+
+  it("uses P_DEV_HOME for workflow bootstrap when source root differs", () => {
+    expect(resolveHarnessWorkspaceDir()).toBe(operatorRoot);
+    expect(resolveHarnessRepoRoot()).toBe(sourceRoot);
+  });
+
+  it("loads Linear from operator workspace credentials, not source-only secrets", async () => {
+    await writeFile(
+      path.join(sourceRoot, ".env.local"),
+      `LINEAR_API_KEY=source-only-linear-key\nCURSOR_API_KEY=source-only-cursor-key\n`,
+      "utf8",
+    );
+    normalizeHarnessEnvPaths(operatorRoot);
+
+    const payload = await loadWorkflowBootstrap({
+      mode: "live",
+      scopeId: "my-product",
+    });
+
+    expect(payload.catalogLoadMetadata.statusCatalog).toBe("loaded");
+    expect(vi.mocked(loadLiveLinearStatuses)).toHaveBeenCalledWith({
+      apiKey: FAKE_LINEAR_KEY,
+      teamId: "team-123",
+    });
+    expect(JSON.stringify(payload)).not.toContain("source-only-linear-key");
+  });
+
+  it("workflow-server reads operator workspace for bootstrap", () => {
+    const source = readFileSync(
+      path.join(repoRoot, "apps/gui/lib/workflow-server.ts"),
+      "utf8",
+    );
+
+    expect(source).toContain("resolveHarnessWorkspaceDir");
+    expect(source).not.toContain("resolveHarnessRepoRoot");
+  });
+
+  it("verify routes read operator workspace for setup verification", () => {
+    const verifyService = readFileSync(
+      path.join(repoRoot, "apps/gui/app/api/setup/verify-service/route.ts"),
+      "utf8",
+    );
+    const verifyTargetRepo = readFileSync(
+      path.join(repoRoot, "apps/gui/app/api/setup/verify-target-repo/route.ts"),
+      "utf8",
+    );
+
+    expect(verifyService).toContain("resolveHarnessWorkspaceDir");
+    expect(verifyTargetRepo).toContain("resolveHarnessWorkspaceDir");
+  });
+});

package/workspace-snapshot/files/tests/linear/markers.test.ts

@@ -94,4 +94,33 @@ target_repo: https://github.com/example/repo
 
   // Linear preserves HTML comments in stored comment bodies (verified via API round-trip).
   // Hidden metadata strategy depends on this behavior.
+
+  it("round-trips Builder thread metadata fields", () => {
+    const footer = formatHarnessCommentFooter({
+      orchestratorMarker: "harness-orchestrator-v1",
+      phase: "revision_start",
+      runId: "rev-run-1",
+      model: "composer-2.5",
+      promptVersion: "revision@1",
+      targetRepo: "https://github.com/owner/example-target-app",
+      builderAgentId: "bc-builder-1",
+      builderThreadGeneration: 2,
+      builderThreadAction: "resumed",
+      builderOriginRunId: "impl-run-1",
+      builderThreadIdempotencyKey: "p-dev:revision:WES-1:comment-1",
+      previousBuilderAgentId: "bc-builder-0",
+      builderThreadReplacementReason: "agent_not_found",
+    });
+
+    const markers = parseHarnessMarkers(`Revision starting.\n\n${footer}`);
+    expect(markers.builderAgentId).toBe("bc-builder-1");
+    expect(markers.builderThreadGeneration).toBe("2");
+    expect(markers.builderThreadAction).toBe("resumed");
+    expect(markers.builderOriginRunId).toBe("impl-run-1");
+    expect(markers.builderThreadIdempotencyKey).toBe(
+      "p-dev:revision:WES-1:comment-1",
+    );
+    expect(markers.previousBuilderAgentId).toBe("bc-builder-0");
+    expect(markers.builderThreadReplacementReason).toBe("agent_not_found");
+  });
 });

package/workspace-snapshot/files/tests/linear/run-status-comment.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  buildRunStatusCommentBody,
+  buildRunStatusMarker,
+  findRunStatusComment,
+  parseRunStatusGeneration,
+  upsertRunStatusComment,
+} from "../../src/linear/run-status-comment.js";
+import * as writer from "../../src/linear/writer.js";
+import type { LinearCommentRecord } from "../../src/linear/writer.js";
+
+const issueUuid = "11111111-2222-3333-4444-555555555555";
+
+describe("run status comment", () => {
+  it("uses issue UUID in marker", () => {
+    expect(buildRunStatusMarker(issueUuid)).toBe(
+      `<!-- p-dev-run-status:${issueUuid} -->`,
+    );
+    const body = buildRunStatusCommentBody({
+      issueId: issueUuid,
+      headline: "PDev received this issue",
+      phase: "Preparing it for planning",
+      generation: 1_700_000_000_000,
+      runId: "run-1",
+      deliveryId: "delivery-1",
+    });
+    expect(body).toContain(buildRunStatusMarker(issueUuid));
+    expect(body).not.toContain("WES-1");
+  });
+
+  it("upserts once and updates the same comment", async () => {
+    const comments: LinearCommentRecord[] = [];
+    const client = {} as never;
+
+    vi.spyOn(writer, "listIssueComments").mockImplementation(async () => comments);
+    vi.spyOn(writer, "postIssueComment").mockImplementation(async (_client, _issueId, body) => {
+      comments.push({
+        id: "comment-1",
+        body,
+        createdAt: "2026-07-17T20:00:00.000Z",
+      });
+      return "comment-1";
+    });
+    vi.spyOn(writer, "updateIssueComment").mockImplementation(async (_client, commentId, body) => {
+      const comment = comments.find((entry) => entry.id === commentId);
+      if (comment) {
+        comment.body = body;
+      }
+    });
+
+    const created = await upsertRunStatusComment(
+      client,
+      issueUuid,
+      buildRunStatusCommentBody({
+        issueId: issueUuid,
+        headline: "Planning in progress",
+        phase: "Planning",
+        generation: 100,
+        runId: "run-1",
+      }),
+      { generation: 100 },
+    );
+    expect(created.action).toBe("created");
+    expect(writer.postIssueComment).toHaveBeenCalledTimes(1);
+
+    const updated = await upsertRunStatusComment(
+      client,
+      issueUuid,
+      buildRunStatusCommentBody({
+        issueId: issueUuid,
+        headline: "Planning finished",
+        phase: "Ready for Build",
+        generation: 200,
+        runId: "run-1",
+      }),
+      { generation: 200 },
+    );
+    expect(updated.action).toBe("updated");
+    expect(writer.postIssueComment).toHaveBeenCalledTimes(1);
+    expect(writer.updateIssueComment).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips update when incoming generation is older", async () => {
+    const comments: LinearCommentRecord[] = [
+      {
+        id: "comment-1",
+        createdAt: "2026-07-17T20:00:00.000Z",
+        body: buildRunStatusCommentBody({
+          issueId: issueUuid,
+          headline: "Current",
+          phase: "Planning",
+          generation: 500,
+        }),
+      },
+    ];
+
+    vi.spyOn(writer, "listIssueComments").mockResolvedValue(comments);
+    vi.spyOn(writer, "updateIssueComment").mockResolvedValue(undefined);
+    vi.spyOn(writer, "postIssueComment").mockResolvedValue("new");
+
+    const result = await upsertRunStatusComment(
+      {} as never,
+      issueUuid,
+      buildRunStatusCommentBody({
+        issueId: issueUuid,
+        headline: "Stale",
+        phase: "Planning",
+        generation: 100,
+      }),
+      { generation: 100 },
+    );
+
+    expect(result.action).toBe("skipped");
+    expect(writer.updateIssueComment).not.toHaveBeenCalled();
+    expect(writer.postIssueComment).not.toHaveBeenCalled();
+  });
+
+  it("finds marker comment by UUID", () => {
+    const match = findRunStatusComment(
+      [
+        {
+          id: "other",
+          body: "<!-- p-dev-run-status:other-id -->",
+          createdAt: "2026-07-17T19:00:00.000Z",
+        },
+        {
+          id: "target",
+          body: buildRunStatusCommentBody({
+            issueId: issueUuid,
+            headline: "Current",
+            phase: "Planning",
+            generation: 200,
+          }),
+          createdAt: "2026-07-17T20:00:00.000Z",
+        },
+      ],
+      issueUuid,
+    );
+
+    expect(match?.id).toBe("target");
+    expect(parseRunStatusGeneration(match?.body ?? "")).toBe(200);
+  });
+});

package/workspace-snapshot/files/tests/observability/analytics-schemas.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { parseClientAnalyticsEventBody } from "../../src/observability/analytics-schemas.js";
+
+describe("client analytics schemas", () => {
+  it("accepts a valid step viewed payload", () => {
+    const parsed = parseClientAnalyticsEventBody({
+      type: "p_dev_configure_step_viewed",
+      stepId: "connect-services",
+      stepNumber: 1,
+      resumed: false,
+      revisited: false,
+    });
+    expect(parsed.type).toBe("p_dev_configure_step_viewed");
+  });
+
+  it("rejects unknown step ids without echoing submitted values", () => {
+    expect(() =>
+      parseClientAnalyticsEventBody({
+        type: "p_dev_configure_step_viewed",
+        stepId: "not-a-real-step",
+        stepNumber: 1,
+        resumed: false,
+        revisited: false,
+      }),
+    ).toThrow("Invalid analytics event payload.");
+  });
+
+  it("rejects mismatched step numbers", () => {
+    expect(() =>
+      parseClientAnalyticsEventBody({
+        type: "p_dev_configure_step_viewed",
+        stepId: "connect-services",
+        stepNumber: 3,
+        resumed: false,
+        revisited: false,
+      }),
+    ).toThrow("Invalid analytics event payload.");
+  });
+
+  it("rejects non-fixed resumed and revisited values", () => {
+    expect(() =>
+      parseClientAnalyticsEventBody({
+        type: "p_dev_configure_step_viewed",
+        stepId: "connect-services",
+        stepNumber: 1,
+        resumed: true,
+        revisited: false,
+      }),
+    ).toThrow("Invalid analytics event payload.");
+  });
+
+  it("rejects extra properties", () => {
+    expect(() =>
+      parseClientAnalyticsEventBody({
+        type: "p_dev_setup_completed",
+        extra: "nope",
+      }),
+    ).toThrow("Invalid analytics event payload.");
+  });
+
+  it("rejects invalid duration buckets", () => {
+    expect(() =>
+      parseClientAnalyticsEventBody({
+        type: "p_dev_configure_step_completed",
+        stepId: "connect-services",
+        stepNumber: 1,
+        resumed: false,
+        revisited: false,
+        durationBucket: "not-real",
+        completionOutcome: "success",
+      }),
+    ).toThrow("Invalid analytics event payload.");
+  });
+});

package/workspace-snapshot/files/tests/observability/context.test.ts

@@ -0,0 +1,132 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { P_DEV_RELEASE_SHA_ENV } from "../../src/observability/constants.js";
+import {
+  buildObservabilityContext,
+  readReleaseShaFromPackageRoot,
+  resolvePackagedReleaseShaFromPackageRoot,
+  resolveReleaseSha,
+  validateReleaseSha,
+} from "../../src/observability/context.js";
+
+const VALID_SHA = "a".repeat(40);
+const OTHER_SHA = "b".repeat(40);
+
+describe("validateReleaseSha", () => {
+  it("accepts lowercase 40-character hex commits", () => {
+    expect(validateReleaseSha(VALID_SHA)).toBe(VALID_SHA);
+    expect(validateReleaseSha(VALID_SHA.toUpperCase())).toBe(VALID_SHA);
+  });
+
+  it("rejects paths, credentials, semver, and arbitrary text", () => {
+    expect(validateReleaseSha("/Users/weston/repo")).toBeNull();
+    expect(validateReleaseSha("ghp_1234567890abcdef")).toBeNull();
+    expect(validateReleaseSha("0.3.1")).toBeNull();
+    expect(validateReleaseSha("not-a-commit")).toBeNull();
+    expect(validateReleaseSha("unknown")).toBeNull();
+    expect(validateReleaseSha(`${VALID_SHA}extra`)).toBeNull();
+  });
+});
+
+describe("resolveReleaseSha", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+    );
+  });
+
+  async function makePackageRoot(sourceCommit: string): Promise<string> {
+    const packageRoot = await mkdtemp(path.join(tmpdir(), "obs-context-package-"));
+    tempDirs.push(packageRoot);
+    await mkdir(path.join(packageRoot, "workspace-snapshot"), { recursive: true });
+    await writeFile(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify({ name: "p-dev-harness", version: "0.4.0" }),
+      "utf8",
+    );
+    await writeFile(
+      path.join(packageRoot, "workspace-snapshot", "manifest.json"),
+      JSON.stringify({ sourceCommit }),
+      "utf8",
+    );
+    return packageRoot;
+  }
+
+  it("prefers validated handoff env over an unresolvable moduleUrl", async () => {
+    const packageRoot = await makePackageRoot(OTHER_SHA);
+    const modulePath = path.join(packageRoot, "gui", "bundled", "route.js");
+
+    expect(
+      resolveReleaseSha({
+        env: { [P_DEV_RELEASE_SHA_ENV]: VALID_SHA },
+        moduleUrl: `file://${modulePath}`,
+      }),
+    ).toBe(VALID_SHA);
+  });
+
+  it("falls back to package manifest when handoff is missing or invalid", async () => {
+    const packageRoot = await makePackageRoot(VALID_SHA);
+    const modulePath = path.join(packageRoot, "dist", "p-dev", "launch.js");
+
+    expect(
+      resolveReleaseSha({
+        env: { [P_DEV_RELEASE_SHA_ENV]: "not-a-commit" },
+        moduleUrl: `file://${modulePath}`,
+      }),
+    ).toBe(VALID_SHA);
+  });
+
+  it("returns unknown when handoff and package-root resolution both fail", () => {
+    expect(
+      resolveReleaseSha({
+        env: {},
+        moduleUrl: "file:///tmp/not-a-package/module.js",
+      }),
+    ).toBe("unknown");
+  });
+});
+
+describe("buildObservabilityContext", () => {
+  it("uses handoff release SHA when bundled moduleUrl cannot resolve package root", () => {
+    const context = buildObservabilityContext({
+      sessionId: "session-1",
+      firstLaunchForPDevHome: true,
+      env: {
+        P_DEV_PACKAGE_VERSION: "0.4.0",
+        [P_DEV_RELEASE_SHA_ENV]: VALID_SHA,
+      },
+      moduleUrl: "file:///tmp/gui/.next/server/chunks/preferences-route.js",
+    });
+
+    expect(context.releaseSha).toBe(VALID_SHA);
+    expect(context.packageVersion).toBe("0.4.0");
+  });
+});
+
+describe("resolvePackagedReleaseShaFromPackageRoot", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+    );
+  });
+
+  it("reads and validates manifest sourceCommit", async () => {
+    const packageRoot = await mkdtemp(path.join(tmpdir(), "obs-context-manifest-"));
+    tempDirs.push(packageRoot);
+    await mkdir(path.join(packageRoot, "workspace-snapshot"), { recursive: true });
+    await writeFile(
+      path.join(packageRoot, "workspace-snapshot", "manifest.json"),
+      JSON.stringify({ sourceCommit: VALID_SHA }),
+      "utf8",
+    );
+
+    expect(resolvePackagedReleaseShaFromPackageRoot(packageRoot)).toBe(VALID_SHA);
+    expect(readReleaseShaFromPackageRoot(packageRoot)).toBe(VALID_SHA);
+  });
+});

package/workspace-snapshot/files/tests/observability/fatal-process.test.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+});
+
+async function writeFatalHarness(
+  dir: string,
+  body: string,
+): Promise<string> {
+  const scriptPath = path.join(dir, "fatal-harness.mjs");
+  await writeFile(scriptPath, body, "utf8");
+  return scriptPath;
+}
+
+function runNodeScript(scriptPath: string, env: NodeJS.ProcessEnv = {}): {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+} {
+  try {
+    const stdout = execFileSync(process.execPath, [scriptPath], {
+      cwd: repoRoot,
+      env: { ...process.env, ...env },
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    return { status: 0, stdout, stderr: "" };
+  } catch (error) {
+    const execError = error as {
+      status?: number | null;
+      stdout?: string;
+      stderr?: string;
+    };
+    return {
+      status: execError.status ?? 1,
+      stdout: execError.stdout ?? "",
+      stderr: execError.stderr ?? "",
+    };
+  }
+}
+
+describe("observability fatal process semantics", () => {
+  it("exits nonzero on uncaught exception with observability enabled", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "fatal-uncaught-"));
+    tempDirs.push(dir);
+    const scriptPath = await writeFatalHarness(
+      dir,
+      `
+import { installObservabilityFatalHandlers } from ${JSON.stringify(path.join(repoRoot, "dist/observability/fatal-handlers.js"))};
+
+installObservabilityFatalHandlers(() => {});
+setTimeout(() => {
+  throw new Error("fatal test");
+}, 10);
+`,
+    );
+    const result = runNodeScript(scriptPath);
+    expect(result.status).not.toBe(0);
+  });
+
+  it("exits nonzero on uncaught exception with observability disabled", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "fatal-uncaught-off-"));
+    tempDirs.push(dir);
+    const scriptPath = await writeFatalHarness(
+      dir,
+      `
+setTimeout(() => {
+  throw new Error("fatal test without observability");
+}, 10);
+`,
+    );
+    const result = runNodeScript(scriptPath);
+    expect(result.status).not.toBe(0);
+  });
+
+  it("exits nonzero on unhandled rejection under strict mode", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "fatal-rejection-"));
+    tempDirs.push(dir);
+    const scriptPath = await writeFatalHarness(
+      dir,
+      `
+Promise.reject(new Error("unhandled rejection"));
+setTimeout(() => {}, 100);
+`,
+    );
+    const result = runNodeScript(scriptPath, {
+      NODE_OPTIONS: "--unhandled-rejections=strict",
+    });
+    expect(result.status).not.toBe(0);
+  });
+});