p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/linear/writer.ts

@@ -0,0 +1,216 @@
+import { LinearClient } from "@linear/sdk";
+import type { LinearIssueSnapshot } from "./client.js";
+import { resolveWorkflowStateId } from "./states.js";
+import {
+  formatHarnessCommentFooter,
+  formatHandoffComment,
+  formatPlanningComment,
+  buildErrorCommentBody,
+  type HandoffCommentFooterInput,
+  type RevisionCommentFooterInput,
+  formatRevisionComment,
+  type MergeCommentFooterInput,
+  formatMergeComment,
+  type HarnessCommentFooterInput,
+  type ProductionSyncCommentFooterInput,
+  formatProductionSyncComment,
+  type PhaseStartPhase,
+  type PhaseStartCommentBodyInput,
+  formatPhaseStartComment,
+  findPhaseStartMarker,
+} from "./comments.js";
+import { getGitHubActionsRunUrl } from "../github/actions-url.js";
+
+export interface LinearCommentRecord {
+  id: string;
+  body: string;
+  createdAt?: string;
+}
+
+export async function listIssueComments(
+  client: LinearClient,
+  issueId: string,
+): Promise<LinearCommentRecord[]> {
+  const issue = await client.issue(issueId);
+  if (!issue) {
+    throw new Error(`Linear issue not found: ${issueId}`);
+  }
+  const connection = await issue.comments();
+  return (connection.nodes ?? []).map((comment) => ({
+    id: comment.id,
+    body: comment.body,
+    createdAt: comment.createdAt?.toISOString(),
+  }));
+}
+
+export async function transitionIssueStatus(
+  client: LinearClient,
+  issue: LinearIssueSnapshot,
+  statusName: string,
+): Promise<void> {
+  if (!issue.teamId) {
+    throw new Error(`Issue ${issue.identifier} is missing teamId`);
+  }
+  const stateId = await resolveWorkflowStateId(
+    client,
+    issue.teamId,
+    statusName,
+  );
+  const linearIssue = await client.issue(issue.id);
+  if (!linearIssue) {
+    throw new Error(`Linear issue not found: ${issue.id}`);
+  }
+  const payload = await linearIssue.update({ stateId });
+  if (!payload.success) {
+    throw new Error(`Failed to transition issue to ${statusName}`);
+  }
+}
+
+export async function postIssueComment(
+  client: LinearClient,
+  issueId: string,
+  body: string,
+): Promise<string> {
+  const payload = await client.createComment({ issueId, body });
+  if (!payload.success) {
+    throw new Error("Failed to create Linear comment");
+  }
+  const comment = await payload.comment;
+  return comment?.id ?? "unknown";
+}
+
+export async function postPlanningComment(
+  client: LinearClient,
+  issueId: string,
+  planBody: string,
+  footer: HarnessCommentFooterInput,
+): Promise<string> {
+  const body = formatPlanningComment(planBody, footer);
+  return postIssueComment(client, issueId, body);
+}
+
+export async function postHandoffComment(
+  client: LinearClient,
+  issueId: string,
+  summaryBody: string,
+  footer: HandoffCommentFooterInput,
+): Promise<string> {
+  const body = formatHandoffComment(summaryBody, footer);
+  return postIssueComment(client, issueId, body);
+}
+
+export async function postRevisionComment(
+  client: LinearClient,
+  issueId: string,
+  summaryBody: string,
+  footer: RevisionCommentFooterInput,
+): Promise<string> {
+  const body = formatRevisionComment(summaryBody, footer);
+  return postIssueComment(client, issueId, body);
+}
+
+export async function postMergeCompletionComment(
+  client: LinearClient,
+  issueId: string,
+  summaryBody: string,
+  footer: MergeCommentFooterInput,
+): Promise<string> {
+  const body = formatMergeComment(summaryBody, footer);
+  return postIssueComment(client, issueId, body);
+}
+
+export async function postProductionSyncComment(
+  client: LinearClient,
+  issueId: string,
+  summaryBody: string,
+  footer: ProductionSyncCommentFooterInput,
+): Promise<string> {
+  const body = formatProductionSyncComment(summaryBody, footer);
+  return postIssueComment(client, issueId, body);
+}
+
+export interface PostPhaseStartCommentInput {
+  orchestratorMarker: string;
+  phase: PhaseStartPhase;
+  runId: string;
+  issueKey: string;
+  targetRepo: string;
+  baseBranch?: string;
+  model: string;
+  promptVersion: string;
+  branch?: string;
+  prUrl?: string;
+  cursorAgentId?: string;
+  cursorRunId?: string;
+}
+
+export async function postPhaseStartCommentIfNeeded(
+  client: LinearClient,
+  issueId: string,
+  input: PostPhaseStartCommentInput,
+): Promise<string | null> {
+  const comments = await listIssueComments(client, issueId);
+  if (
+    findPhaseStartMarker(
+      comments,
+      input.orchestratorMarker,
+      input.phase,
+      input.runId,
+    )
+  ) {
+    return null;
+  }
+
+  const githubActionsRunUrl = getGitHubActionsRunUrl();
+  const bodyInput: PhaseStartCommentBodyInput = {
+    issueKey: input.issueKey,
+    targetRepo: input.targetRepo,
+    baseBranch: input.baseBranch,
+    branch: input.branch,
+    prUrl: input.prUrl,
+    githubActionsRunUrl,
+    cursorAgentId: input.cursorAgentId,
+    cursorRunId: input.cursorRunId,
+  };
+  const body = formatPhaseStartComment(input.phase, bodyInput, {
+    orchestratorMarker: input.orchestratorMarker,
+    runId: input.runId,
+    cursorAgentId: input.cursorAgentId,
+    cursorRunId: input.cursorRunId,
+    model: input.model,
+    promptVersion: input.promptVersion,
+    targetRepo: input.targetRepo,
+    baseBranch: input.baseBranch,
+    branch: input.branch,
+    prUrl: input.prUrl,
+    githubActionsRunUrl: githubActionsRunUrl ?? undefined,
+  });
+  return postIssueComment(client, issueId, body);
+}
+
+export async function postErrorComment(
+  client: LinearClient,
+  issueId: string,
+  message: string,
+  footer: MergeCommentFooterInput,
+  phase: "planning" | "implementation" | "handoff" | "revision" | "merge" | "production_sync" = "planning",
+  options?: {
+    errorClassification?: string;
+  },
+): Promise<string> {
+  const body = `${buildErrorCommentBody(phase, message, {
+    githubActionsRunUrl:
+      footer.githubActionsRunUrl ?? getGitHubActionsRunUrl(),
+    errorClassification: options?.errorClassification,
+    targetRepo: footer.targetRepo,
+    branch: footer.branch,
+    prUrl: footer.prUrl,
+    baseBranch: footer.baseBranch,
+    harnessRunId: footer.runId,
+  })}\n\n${formatHarnessCommentFooter(footer)}`;
+  return postIssueComment(client, issueId, body);
+}
+
+export function createLinearClient(apiKey: string): LinearClient {
+  return new LinearClient({ apiKey });
+}

package/workspace-snapshot/files/src/p-dev/browser.ts

@@ -0,0 +1,26 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface BrowserOpener {
+  open(url: string): Promise<void>;
+}
+
+export function createMacOsBrowserOpener(
+  execFileImpl: typeof execFileAsync = execFileAsync,
+): BrowserOpener {
+  return {
+    async open(url: string): Promise<void> {
+      if (process.platform !== "darwin") {
+        throw new Error(
+          "p-dev browser launch is macOS-only in this packaging spike. Re-open the printed Configure URL manually.",
+        );
+      }
+
+      await execFileImpl("open", [url]);
+    },
+  };
+}
+
+export const defaultBrowserOpener = createMacOsBrowserOpener();

package/workspace-snapshot/files/src/p-dev/cli.ts

@@ -0,0 +1,93 @@
+export const DEFAULT_CONFIGURE_ROUTE = "/settings/configure";
+
+export interface PDevCliOptions {
+  host?: string;
+  port?: number;
+  workspace?: string;
+  route: string;
+  openBrowser: boolean;
+}
+
+export function parsePDevCliOptions(argv: string[]): PDevCliOptions {
+  const options: PDevCliOptions = {
+    route: DEFAULT_CONFIGURE_ROUTE,
+    openBrowser: true,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--port") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("--port requires a number");
+      }
+      options.port = Number.parseInt(value, 10);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--port=")) {
+      options.port = Number.parseInt(arg.slice("--port=".length), 10);
+      continue;
+    }
+
+    if (arg === "--host") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("--host requires a value");
+      }
+      options.host = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--host=")) {
+      options.host = arg.slice("--host=".length);
+      continue;
+    }
+
+    if (arg === "--workspace") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("--workspace requires a path");
+      }
+      options.workspace = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--workspace=")) {
+      options.workspace = arg.slice("--workspace=".length);
+      continue;
+    }
+
+    if (arg === "--route") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("--route requires a path");
+      }
+      options.route = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--route=")) {
+      options.route = arg.slice("--route=".length);
+      continue;
+    }
+
+    if (arg === "--no-open") {
+      options.openBrowser = false;
+      continue;
+    }
+  }
+
+  if (options.port !== undefined) {
+    if (!Number.isFinite(options.port) || options.port <= 0 || options.port > 65535) {
+      throw new Error("--port must be a valid TCP port between 1 and 65535");
+    }
+  }
+
+  return options;
+}

package/workspace-snapshot/files/src/p-dev/git-object-plumbing.ts

@@ -0,0 +1,271 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { WorkspaceSnapshotManifestFile } from "./workspace-snapshot-types.js";
+
+export function compareUtf8Paths(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+
+export function computeGitBlobSha1(content: Buffer): string {
+  const result = spawnSync("git", ["hash-object", "--stdin"], {
+    input: content,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `git hash-object failed: ${result.stderr?.toString("utf8") || "unknown error"}`,
+    );
+  }
+  return result.stdout.toString("utf8").trim();
+}
+
+function gitMktreeFromEntries(
+  entries: Array<{ mode: string; type: "blob" | "tree"; sha: string; name: string }>,
+): string {
+  const sorted = [...entries].sort((left, right) =>
+    compareUtf8Paths(left.name, right.name),
+  );
+  const chunks: Buffer[] = [];
+  for (const entry of sorted) {
+    chunks.push(
+      Buffer.from(`${entry.mode} ${entry.type} ${entry.sha}\t${entry.name}\0`, "utf8"),
+    );
+  }
+  const result = spawnSync("git", ["mktree", "-z", "--missing"], {
+    input: Buffer.concat(chunks),
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `git mktree failed: ${result.stderr?.toString("utf8") || result.stdout?.toString("utf8") || "unknown error"}`,
+    );
+  }
+  return result.stdout.toString("utf8").trim();
+}
+
+export function computeSnapshotRootTreeSha1(
+  files: WorkspaceSnapshotManifestFile[],
+): string {
+  const childrenByDir = new Map<
+    string,
+    Array<{ name: string; mode: string; sha1: string }>
+  >();
+
+  for (const file of files) {
+    const segments = file.path.split("/");
+    const name = segments.pop();
+    if (!name) {
+      throw new Error(`Invalid snapshot file path: ${file.path}`);
+    }
+    const dir = segments.join("/");
+    if (!childrenByDir.has(dir)) {
+      childrenByDir.set(dir, []);
+    }
+    childrenByDir.get(dir)!.push({
+      name,
+      mode: file.mode,
+      sha1: file.gitBlobSha1,
+    });
+  }
+
+  const allDirs = new Set<string>(["", ...childrenByDir.keys()]);
+  for (const dir of childrenByDir.keys()) {
+    const parts = dir.split("/").filter(Boolean);
+    for (let index = 0; index < parts.length; index += 1) {
+      allDirs.add(parts.slice(0, index).join("/"));
+    }
+  }
+
+  const treeShaByDir = new Map<string, string>();
+  const sortedDirs = [...allDirs].sort(
+    (left, right) =>
+      right.split("/").filter(Boolean).length -
+      left.split("/").filter(Boolean).length,
+  );
+
+  for (const dir of sortedDirs) {
+    const directChildren = childrenByDir.get(dir) ?? [];
+    const entries: Array<{ mode: string; type: "blob" | "tree"; sha: string; name: string }> =
+      [];
+
+    for (const otherDir of allDirs) {
+      if (otherDir === dir) {
+        continue;
+      }
+      const parent = otherDir.includes("/")
+        ? otherDir.slice(0, otherDir.lastIndexOf("/"))
+        : "";
+      if (parent !== dir) {
+        continue;
+      }
+      const name = dir ? otherDir.slice(dir.length + 1) : otherDir;
+      if (name.includes("/")) {
+        continue;
+      }
+      const subTreeSha = treeShaByDir.get(otherDir);
+      if (!subTreeSha) {
+        throw new Error(`Missing subtree SHA for ${otherDir}`);
+      }
+      entries.push({ mode: "040000", type: "tree", sha: subTreeSha, name });
+    }
+
+    const subdirNames = new Set(entries.map((entry) => entry.name));
+    for (const child of directChildren) {
+      if (!subdirNames.has(child.name)) {
+        entries.push({
+          mode: child.mode,
+          type: "blob",
+          sha: child.sha1,
+          name: child.name,
+        });
+      }
+    }
+
+    treeShaByDir.set(dir, gitMktreeFromEntries(entries));
+  }
+
+  const rootSha = treeShaByDir.get("");
+  if (!rootSha) {
+    throw new Error("Snapshot root tree SHA could not be computed.");
+  }
+  return rootSha;
+}
+
+export interface GitPlumbingWorktree {
+  root: string;
+  env: NodeJS.ProcessEnv;
+}
+
+export async function createGitPlumbingWorktree(): Promise<GitPlumbingWorktree> {
+  const root = await mkdtemp(path.join(tmpdir(), "p-dev-git-plumbing-"));
+  const result = spawnSync("git", ["init"], { cwd: root });
+  if (result.status !== 0) {
+    await rm(root, { recursive: true, force: true });
+    throw new Error(
+      `git init failed: ${result.stderr?.toString("utf8") || "unknown error"}`,
+    );
+  }
+  return {
+    root,
+    env: {
+      ...process.env,
+      GIT_DIR: path.join(root, ".git"),
+      GIT_WORK_TREE: root,
+    },
+  };
+}
+
+export async function destroyGitPlumbingWorktree(
+  worktree: GitPlumbingWorktree,
+): Promise<void> {
+  await rm(worktree.root, { recursive: true, force: true });
+}
+
+export function writeGitBlobToWorktree(
+  worktree: GitPlumbingWorktree,
+  content: Buffer,
+): string {
+  const result = spawnSync("git", ["hash-object", "-w", "--stdin"], {
+    cwd: worktree.root,
+    env: worktree.env,
+    input: content,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `git hash-object -w failed: ${result.stderr?.toString("utf8") || "unknown error"}`,
+    );
+  }
+  return result.stdout.toString("utf8").trim();
+}
+
+export function overlayGitTree(
+  worktree: GitPlumbingWorktree,
+  baseTreeSha: string,
+  overlays: Array<{ path: string; mode: string; sha: string }>,
+): string {
+  const readTree = spawnSync("git", ["read-tree", baseTreeSha], {
+    cwd: worktree.root,
+    env: worktree.env,
+  });
+  if (readTree.status !== 0) {
+    throw new Error(
+      `git read-tree failed: ${readTree.stderr?.toString("utf8") || "unknown error"}`,
+    );
+  }
+
+  for (const overlay of overlays) {
+    const updateIndex = spawnSync(
+      "git",
+      [
+        "update-index",
+        "--add",
+        "--cacheinfo",
+        `${overlay.mode},${overlay.sha},${overlay.path}`,
+      ],
+      { cwd: worktree.root, env: worktree.env },
+    );
+    if (updateIndex.status !== 0) {
+      throw new Error(
+        `git update-index failed for ${overlay.path}: ${updateIndex.stderr?.toString("utf8") || "unknown error"}`,
+      );
+    }
+  }
+
+  const writeTree = spawnSync("git", ["write-tree"], {
+    cwd: worktree.root,
+    env: worktree.env,
+  });
+  if (writeTree.status !== 0) {
+    throw new Error(
+      `git write-tree failed: ${writeTree.stderr?.toString("utf8") || "unknown error"}`,
+    );
+  }
+  return writeTree.stdout.toString("utf8").trim();
+}
+
+export function buildGitTreeFromManifestFiles(
+  worktree: GitPlumbingWorktree,
+  files: WorkspaceSnapshotManifestFile[],
+  blobContentsBySha: Map<string, Buffer>,
+): string {
+  for (const [sha, content] of blobContentsBySha) {
+    writeGitBlobToWorktree(worktree, content);
+    void sha;
+  }
+  return computeSnapshotRootTreeSha1(files);
+}
+
+export function readGitTreeFileContent(
+  worktree: GitPlumbingWorktree,
+  treeSha: string,
+  filePath: string,
+): Buffer | null {
+  const segments = filePath.split("/").filter(Boolean);
+  let currentTree = treeSha;
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    const name = segments[index]!;
+    const lsTree = spawnSync("git", ["ls-tree", `${currentTree}:${name}`], {
+      cwd: worktree.root,
+      env: worktree.env,
+    });
+    if (lsTree.status !== 0) {
+      return null;
+    }
+    const match = /^040000 tree ([0-9a-f]{40})/.exec(lsTree.stdout.toString("utf8").trim());
+    if (!match) {
+      return null;
+    }
+    currentTree = match[1]!;
+  }
+  const leaf = segments[segments.length - 1]!;
+  const catFile = spawnSync("git", ["cat-file", "-p", `${currentTree}:${leaf}`], {
+    cwd: worktree.root,
+    env: worktree.env,
+    encoding: "buffer",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (catFile.status !== 0) {
+    return null;
+  }
+  return catFile.stdout as Buffer;
+}