p-dev-harness 0.3.1 → 0.4.0

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

@@ -1,4 +1,7 @@
-import type { ParsedIssue } from "../types/parsed-issue.js";
+import type {
+  ParsedIssue,
+  ProductFoundationFields,
+} from "../types/parsed-issue.js";
 
 const SECTION_HEADERS = [
   "target repo",
@@ -7,6 +10,7 @@ const SECTION_HEADERS = [
   "acceptance criteria",
   "out of scope",
   "validation expectations",
+  "product foundation",
   "context and links",
   "eval hints",
   "definition of ready",
@@ -56,6 +60,58 @@ function extractTargetRepoFromContext(contextSection: string | undefined): strin
   return match?.[1]?.trim();
 }
 
+function parseProductFoundationSection(
+  content: string | undefined,
+): ProductFoundationFields | undefined {
+  if (!content?.trim()) {
+    return undefined;
+  }
+
+  const fields: ProductFoundationFields = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    const bulletMatch = trimmed.match(/^[-*]\s*(.+)$/);
+    const valueSource = bulletMatch?.[1]?.trim() ?? trimmed;
+    const keyValueMatch = valueSource.match(/^([^:]+):\s*(.+)$/);
+    if (!keyValueMatch) {
+      continue;
+    }
+
+    const key = keyValueMatch[1]!.trim().toLowerCase();
+    const value = keyValueMatch[2]!.trim();
+    if (!value) {
+      continue;
+    }
+
+    if (key === "platform runtime" || key === "platform/runtime") {
+      fields.platformRuntime = value;
+    } else if (key === "language framework" || key === "language/framework") {
+      fields.languageFramework = value;
+    } else if (key === "repository structure") {
+      fields.repositoryStructure = value;
+    } else if (key === "testing strategy") {
+      fields.testingStrategy = value;
+    } else if (key === "ci strategy") {
+      fields.ciStrategy = value;
+    }
+  }
+
+  return Object.keys(fields).length > 0 ? fields : undefined;
+}
+
+export function issueHasProductFoundation(
+  productFoundation: ProductFoundationFields | undefined,
+): boolean {
+  return Boolean(
+    productFoundation?.platformRuntime?.trim() &&
+      productFoundation?.languageFramework?.trim(),
+  );
+}
+
 export function parseIssueDescription(description: string): ParsedIssue {
   const sections = parseSections(description);
   const parseErrors: string[] = [];
@@ -85,6 +141,9 @@ export function parseIssueDescription(description: string): ParsedIssue {
     extractTargetRepoFromContext(sections.get("context and links"));
 
   const validationExpectations = sections.get("validation expectations")?.trim();
+  const productFoundation = parseProductFoundationSection(
+    sections.get("product foundation"),
+  );
 
   return {
     targetRepoRaw: targetRepoRaw || undefined,
@@ -92,6 +151,7 @@ export function parseIssueDescription(description: string): ParsedIssue {
     acceptanceCriteria,
     outOfScope,
     validationExpectations: validationExpectations || undefined,
+    productFoundation,
     parseErrors,
   };
 }

package/workspace-snapshot/files/src/linear/project-harness-metadata.ts

@@ -0,0 +1,147 @@
+export type HarnessProductInitializationStatus = "uninitialized" | "initialized";
+
+export interface HarnessProjectMetadata {
+  targetRepo?: string;
+  productInitialization?: HarnessProductInitializationStatus;
+}
+
+const HARNESS_METADATA_HEADER = "Harness metadata:";
+
+function parseMetadataLine(line: string): { key: string; value: string } | null {
+  const match = line.match(/^([A-Za-z][A-Za-z ]*):\s*(.+)$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    key: match[1]!.trim().toLowerCase(),
+    value: match[2]!.trim(),
+  };
+}
+
+export function parseHarnessProjectMetadata(
+  description: string | null | undefined,
+): HarnessProjectMetadata {
+  if (!description?.trim()) {
+    return {};
+  }
+
+  const lines = description.split("\n");
+  const headerIndex = lines.findIndex(
+    (line) => line.trim().toLowerCase() === HARNESS_METADATA_HEADER.toLowerCase(),
+  );
+  if (headerIndex === -1) {
+    return {};
+  }
+
+  const metadata: HarnessProjectMetadata = {};
+  for (let index = headerIndex + 1; index < lines.length; index += 1) {
+    const trimmed = lines[index]!.trim();
+    if (!trimmed) {
+      break;
+    }
+    if (trimmed.startsWith("#")) {
+      break;
+    }
+    if (trimmed.startsWith("##")) {
+      break;
+    }
+
+    const parsed = parseMetadataLine(trimmed);
+    if (!parsed) {
+      continue;
+    }
+
+    if (parsed.key === "target repo") {
+      metadata.targetRepo = parsed.value.replace(/^`|`$/g, "");
+    } else if (parsed.key === "product initialization") {
+      if (parsed.value === "uninitialized" || parsed.value === "initialized") {
+        metadata.productInitialization = parsed.value;
+      }
+    }
+  }
+
+  return metadata;
+}
+
+export function formatHarnessMetadataBlock(
+  metadata: HarnessProjectMetadata,
+): string {
+  const lines = [HARNESS_METADATA_HEADER];
+  if (metadata.targetRepo) {
+    lines.push(`Target repo: ${metadata.targetRepo}`);
+  }
+  if (metadata.productInitialization) {
+    lines.push(`Product initialization: ${metadata.productInitialization}`);
+  }
+  return lines.join("\n");
+}
+
+export function upsertHarnessMetadataInDescription(
+  description: string | null | undefined,
+  patch: Partial<HarnessProjectMetadata>,
+): string {
+  const existing = parseHarnessProjectMetadata(description);
+  const merged: HarnessProjectMetadata = {
+    ...existing,
+    ...patch,
+  };
+  const block = formatHarnessMetadataBlock(merged);
+
+  if (!description?.trim()) {
+    return `${block}\n`;
+  }
+
+  const lines = description.split("\n");
+  const headerIndex = lines.findIndex(
+    (line) => line.trim().toLowerCase() === HARNESS_METADATA_HEADER.toLowerCase(),
+  );
+
+  if (headerIndex === -1) {
+    const suffix = description.endsWith("\n") ? "" : "\n";
+    return `${description}${suffix}\n${block}\n`;
+  }
+
+  let endIndex = headerIndex + 1;
+  while (endIndex < lines.length) {
+    const trimmed = lines[endIndex]!.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      break;
+    }
+    endIndex += 1;
+  }
+
+  const before = lines.slice(0, headerIndex);
+  const after = lines.slice(endIndex);
+  const rebuilt = [...before, block, ...after].join("\n").replace(/\n{3,}/g, "\n\n");
+  return rebuilt.endsWith("\n") ? rebuilt : `${rebuilt}\n`;
+}
+
+export function removeHarnessMetadataFromDescription(
+  description: string | null | undefined,
+): string {
+  if (!description?.trim()) {
+    return "";
+  }
+
+  const lines = description.split("\n");
+  const headerIndex = lines.findIndex(
+    (line) => line.trim().toLowerCase() === HARNESS_METADATA_HEADER.toLowerCase(),
+  );
+  if (headerIndex === -1) {
+    return description.endsWith("\n") ? description : `${description}\n`;
+  }
+
+  let endIndex = headerIndex + 1;
+  while (endIndex < lines.length) {
+    const trimmed = lines[endIndex]!.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      break;
+    }
+    endIndex += 1;
+  }
+
+  const before = lines.slice(0, headerIndex);
+  const after = lines.slice(endIndex);
+  const rebuilt = [...before, ...after].join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  return rebuilt ? `${rebuilt}\n` : "";
+}

package/workspace-snapshot/files/src/linear/project-metadata-sync.ts

@@ -0,0 +1,115 @@
+import type { LinearClient } from "@linear/sdk";
+import {
+  upsertHarnessMetadataInDescription,
+  type HarnessProjectMetadata,
+} from "../linear/project-harness-metadata.js";
+import { readProductMarker } from "../product/read-product-marker.js";
+import {
+  resolveProductInitializationState,
+  type ResolvedProductInitialization,
+} from "../product/initialization-state.js";
+import { parseHarnessMarkers } from "../linear/markers.js";
+import type { GitHubClient } from "../github/client.js";
+
+export const PROJECT_METADATA_SYNC_PHASE = "project_metadata_initialized_sync";
+
+export interface SyncProjectHarnessMetadataInput {
+  linearClient: LinearClient;
+  projectId: string;
+  currentDescription: string | null | undefined;
+  targetRepo: string;
+  developmentBranch: string;
+  github: GitHubClient;
+  orchestratorMarker: string;
+  mergeRunId: string;
+  comments: { body: string }[];
+}
+
+export interface SyncProjectHarnessMetadataResult {
+  updated: boolean;
+  skippedReason?: string;
+  productInitialization?: ResolvedProductInitialization;
+  description?: string;
+}
+
+function hasProjectMetadataSyncMarker(
+  comments: { body: string }[],
+  orchestratorMarker: string,
+  mergeRunId: string,
+): boolean {
+  return comments.some((comment) => {
+    const markers = parseHarnessMarkers(comment.body);
+    return (
+      markers.orchestratorMarker === orchestratorMarker &&
+      markers.phase === PROJECT_METADATA_SYNC_PHASE &&
+      markers.runId === mergeRunId
+    );
+  });
+}
+
+export async function syncProjectHarnessMetadataAfterFoundationMerge(
+  input: SyncProjectHarnessMetadataInput,
+): Promise<SyncProjectHarnessMetadataResult> {
+  const markerRead = await readProductMarker({
+    targetRepo: input.targetRepo,
+    developmentBranch: input.developmentBranch,
+    github: input.github,
+  });
+  const productInitialization = resolveProductInitializationState(markerRead.content);
+  if (productInitialization.state !== "initialized") {
+    return {
+      updated: false,
+      skippedReason: "product_not_initialized",
+      productInitialization,
+    };
+  }
+
+  const current = input.currentDescription ?? "";
+  const nextDescription = upsertHarnessMetadataInDescription(current, {
+    targetRepo: input.targetRepo.replace(/^https:\/\/github\.com\//, ""),
+    productInitialization: "initialized",
+  });
+
+  if (nextDescription === current) {
+    return {
+      updated: false,
+      skippedReason: "metadata_already_initialized",
+      productInitialization,
+      description: current,
+    };
+  }
+
+  if (
+    hasProjectMetadataSyncMarker(
+      input.comments,
+      input.orchestratorMarker,
+      input.mergeRunId,
+    )
+  ) {
+    return {
+      updated: false,
+      skippedReason: "duplicate_sync_marker",
+      productInitialization,
+      description: current,
+    };
+  }
+
+  await input.linearClient.updateProject(input.projectId, {
+    description: nextDescription,
+  });
+
+  return {
+    updated: true,
+    productInitialization,
+    description: nextDescription,
+  };
+}
+
+export function buildHarnessMetadataForNewProduct(input: {
+  targetRepo: string;
+}): HarnessProjectMetadata {
+  return {
+    targetRepo: input.targetRepo.replace(/^https:\/\/github\.com\//, ""),
+    productInitialization: "uninitialized",
+  };
+}

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

@@ -0,0 +1,197 @@
+import type { LinearClient } from "@linear/sdk";
+import { formatGitHubActionsRunLink, getGitHubActionsRunUrl } from "../github/actions-url.js";
+import {
+  listIssueComments,
+  postIssueComment,
+  updateIssueComment,
+  type LinearCommentRecord,
+} from "./writer.js";
+
+export interface RunStatusCommentBodyInput {
+  issueId: string;
+  headline: string;
+  phase: string;
+  githubRunUrl?: string | null;
+  updatedAt?: string;
+  runId?: string | null;
+  deliveryId?: string | null;
+  generation: number;
+}
+
+export interface UpsertRunStatusCommentResult {
+  action: "created" | "updated" | "skipped";
+  commentId?: string;
+  reason?: string;
+}
+
+const GENERATION_METADATA_PATTERN = /^generation:\s*(\d+)\s*$/m;
+const RUN_ID_METADATA_PATTERN = /^run_id:\s*(.+)\s*$/m;
+const DELIVERY_ID_METADATA_PATTERN = /^delivery_id:\s*(.+)\s*$/m;
+
+export function buildRunStatusMarker(issueId: string): string {
+  return `<!-- p-dev-run-status:${issueId} -->`;
+}
+
+export function buildRunStatusCommentBody(input: RunStatusCommentBodyInput): string {
+  const updatedAt = input.updatedAt ?? new Date().toISOString();
+  const githubRunUrl = input.githubRunUrl ?? getGitHubActionsRunUrl();
+  const runLink = githubRunUrl ? formatGitHubActionsRunLink(githubRunUrl) : null;
+
+  const visibleLines = [
+    buildRunStatusMarker(input.issueId),
+    `**${input.headline}**`,
+    `- Phase: \`${input.phase}\``,
+    runLink ? `- Run: ${runLink}` : null,
+    `- Last updated: \`${updatedAt}\``,
+  ].filter(Boolean);
+
+  const hiddenMetadata = [
+    "<!--",
+    `generation: ${input.generation}`,
+    input.runId ? `run_id: ${input.runId}` : null,
+    input.deliveryId ? `delivery_id: ${input.deliveryId}` : null,
+    "-->",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return `${visibleLines.join("\n")}\n\n${hiddenMetadata}`;
+}
+
+export function parseRunStatusGeneration(commentBody: string): number | null {
+  const match = commentBody.match(GENERATION_METADATA_PATTERN);
+  if (!match?.[1]) {
+    return null;
+  }
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function findRunStatusComment(
+  comments: LinearCommentRecord[],
+  issueId: string,
+): LinearCommentRecord | null {
+  const marker = buildRunStatusMarker(issueId);
+  const matches = comments.filter((comment) => comment.body.includes(marker));
+  if (matches.length === 0) {
+    return null;
+  }
+
+  return matches.sort((left, right) => {
+    const leftGeneration = parseRunStatusGeneration(left.body) ?? 0;
+    const rightGeneration = parseRunStatusGeneration(right.body) ?? 0;
+    if (leftGeneration !== rightGeneration) {
+      return rightGeneration - leftGeneration;
+    }
+    return (right.createdAt ?? "").localeCompare(left.createdAt ?? "");
+  })[0] ?? null;
+}
+
+export async function upsertRunStatusComment(
+  client: LinearClient,
+  issueId: string,
+  body: string,
+  options: { generation: number },
+): Promise<UpsertRunStatusCommentResult> {
+  const comments = await listIssueComments(client, issueId);
+  const existing = findRunStatusComment(comments, issueId);
+  if (existing) {
+    const existingGeneration = parseRunStatusGeneration(existing.body);
+    if (existingGeneration !== null && options.generation < existingGeneration) {
+      return {
+        action: "skipped",
+        commentId: existing.id,
+        reason: "incoming generation is older than existing comment",
+      };
+    }
+
+    await updateIssueComment(client, existing.id, body);
+    return { action: "updated", commentId: existing.id };
+  }
+
+  const commentId = await postIssueComment(client, issueId, body);
+  return { action: "created", commentId };
+}
+
+export async function acknowledgeIssueReceived(
+  client: LinearClient,
+  issueId: string,
+  input: {
+    runId?: string | null;
+    deliveryId?: string | null;
+    generation: number;
+  },
+): Promise<UpsertRunStatusCommentResult> {
+  const body = buildRunStatusCommentBody({
+    issueId,
+    headline: "PDev received this issue",
+    phase: "Preparing it for planning",
+    runId: input.runId,
+    deliveryId: input.deliveryId,
+    generation: input.generation,
+  });
+  return upsertRunStatusComment(client, issueId, body, {
+    generation: input.generation,
+  });
+}
+
+export async function updateRunStatusPhase(
+  client: LinearClient,
+  issueId: string,
+  input: {
+    phase: string;
+    headline?: string;
+    runId?: string | null;
+    deliveryId?: string | null;
+    generation: number;
+  },
+): Promise<UpsertRunStatusCommentResult> {
+  const body = buildRunStatusCommentBody({
+    issueId,
+    headline: input.headline ?? `Harness run in progress (${input.phase})`,
+    phase: input.phase,
+    runId: input.runId,
+    deliveryId: input.deliveryId,
+    generation: input.generation,
+  });
+  return upsertRunStatusComment(client, issueId, body, {
+    generation: input.generation,
+  });
+}
+
+export async function markRunStatusBlocked(
+  client: LinearClient,
+  issueId: string,
+  input: {
+    message: string;
+    phase?: string;
+    runId?: string | null;
+    deliveryId?: string | null;
+    generation: number;
+  },
+): Promise<UpsertRunStatusCommentResult> {
+  const body = buildRunStatusCommentBody({
+    issueId,
+    headline: input.message,
+    phase: input.phase ?? "Blocked",
+    runId: input.runId,
+    deliveryId: input.deliveryId,
+    generation: input.generation,
+  });
+  return upsertRunStatusComment(client, issueId, body, {
+    generation: input.generation,
+  });
+}
+
+export function parseRunStatusMetadata(commentBody: string): {
+  generation: number | null;
+  runId: string | null;
+  deliveryId: string | null;
+} {
+  return {
+    generation: parseRunStatusGeneration(commentBody),
+    runId: commentBody.match(RUN_ID_METADATA_PATTERN)?.[1]?.trim() ?? null,
+    deliveryId:
+      commentBody.match(DELIVERY_ID_METADATA_PATTERN)?.[1]?.trim() ?? null,
+  };
+}

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

@@ -79,6 +79,17 @@ export async function postIssueComment(
   return comment?.id ?? "unknown";
 }
 
+export async function updateIssueComment(
+  client: LinearClient,
+  commentId: string,
+  body: string,
+): Promise<void> {
+  const payload = await client.updateComment(commentId, { body });
+  if (!payload.success) {
+    throw new Error("Failed to update Linear comment");
+  }
+}
+
 export async function postPlanningComment(
   client: LinearClient,
   issueId: string,
@@ -142,6 +153,13 @@ export interface PostPhaseStartCommentInput {
   prUrl?: string;
   cursorAgentId?: string;
   cursorRunId?: string;
+  builderAgentId?: string;
+  builderThreadGeneration?: number;
+  builderThreadAction?: string;
+  builderOriginRunId?: string;
+  builderThreadIdempotencyKey?: string;
+  previousBuilderAgentId?: string;
+  builderThreadReplacementReason?: string;
 }
 
 export async function postPhaseStartCommentIfNeeded(
@@ -177,6 +195,13 @@ export async function postPhaseStartCommentIfNeeded(
     runId: input.runId,
     cursorAgentId: input.cursorAgentId,
     cursorRunId: input.cursorRunId,
+    builderAgentId: input.builderAgentId,
+    builderThreadGeneration: input.builderThreadGeneration,
+    builderThreadAction: input.builderThreadAction,
+    builderOriginRunId: input.builderOriginRunId,
+    builderThreadIdempotencyKey: input.builderThreadIdempotencyKey,
+    previousBuilderAgentId: input.previousBuilderAgentId,
+    builderThreadReplacementReason: input.builderThreadReplacementReason,
     model: input.model,
     promptVersion: input.promptVersion,
     targetRepo: input.targetRepo,