p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/webhook/handle-linear-webhook.ts

@@ -0,0 +1,201 @@
+import {
+  dispatchRepositoryEvent,
+  getDispatchEventType,
+  getDispatchRepository,
+} from "./dispatch-github.js";
+import { shouldDispatchLinearIssueEvent } from "./filter.js";
+import {
+  parseLinearIssueEvent,
+  readWebhookHeaders,
+} from "./parse-linear-issue-event.js";
+import { logWebhookEvent } from "./redact-log.js";
+import type {
+  RepositoryDispatchPayload,
+  WebhookAcceptedResponse,
+  WebhookErrorResponse,
+  WebhookIgnoredResponse,
+} from "./types.js";
+import {
+  parseTimestampMs,
+  verifyLinearSignature,
+  verifyWebhookTimestamp,
+} from "./verify.js";
+
+export interface HandleLinearWebhookOptions {
+  method: string;
+  rawBody: string;
+  headerGetter: (name: string) => string | null;
+  webhookSecret?: string;
+  dispatchToken?: string;
+  teamKey?: string | null;
+  toleranceMs?: number;
+  nowMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+type WebhookResponseBody =
+  | WebhookAcceptedResponse
+  | WebhookIgnoredResponse
+  | WebhookErrorResponse;
+
+export interface HandleLinearWebhookResult {
+  status: number;
+  body: WebhookResponseBody;
+}
+
+function jsonResponse(
+  status: number,
+  body: WebhookResponseBody,
+): HandleLinearWebhookResult {
+  return { status, body };
+}
+
+export async function handleLinearWebhook(
+  options: HandleLinearWebhookOptions,
+): Promise<HandleLinearWebhookResult> {
+  if (options.method !== "POST") {
+    return jsonResponse(405, { error: "method_not_allowed" });
+  }
+
+  const webhookSecret = options.webhookSecret ?? process.env.LINEAR_WEBHOOK_SECRET;
+  if (!webhookSecret) {
+    return jsonResponse(500, { error: "dispatch_failed" });
+  }
+
+  const headers = readWebhookHeaders(options.headerGetter);
+  const signatureOk = verifyLinearSignature({
+    secret: webhookSecret,
+    rawBody: options.rawBody,
+    signatureHeader: headers.signature,
+  });
+
+  if (!signatureOk) {
+    logWebhookEvent({ accepted: false, error: "invalid_signature" });
+    return jsonResponse(401, { error: "invalid_signature" });
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(options.rawBody) as unknown;
+  } catch {
+    logWebhookEvent({ accepted: false, error: "invalid_signature" });
+    return jsonResponse(401, { error: "invalid_signature" });
+  }
+
+  const payloadRecord = payload as { webhookTimestamp?: unknown };
+  const toleranceMs =
+    options.toleranceMs ??
+    Number(process.env.LINEAR_WEBHOOK_TIMESTAMP_TOLERANCE_MS ?? 60_000);
+
+  const timestampOk = verifyWebhookTimestamp({
+    webhookTimestampMs: parseTimestampMs(payloadRecord.webhookTimestamp),
+    headerTimestampMs: parseTimestampMs(headers.timestamp),
+    toleranceMs,
+    nowMs: options.nowMs,
+  });
+
+  if (!timestampOk) {
+    logWebhookEvent({ accepted: false, error: "timestamp_out_of_tolerance" });
+    return jsonResponse(401, { error: "timestamp_out_of_tolerance" });
+  }
+
+  const teamKey =
+    options.teamKey ?? process.env.HARNESS_TEAM_KEY ?? null;
+  const parsed = parseLinearIssueEvent(payload, headers, teamKey);
+
+  if (!parsed) {
+    logWebhookEvent({ accepted: false, reason: "ignored_event" });
+    return jsonResponse(200, { accepted: false, reason: "ignored_event" });
+  }
+
+  const filterResult = shouldDispatchLinearIssueEvent(parsed);
+  if (!filterResult.dispatch) {
+    logWebhookEvent({
+      linearDeliveryId: parsed.linearDeliveryId,
+      linearWebhookId: parsed.linearWebhookId,
+      issueKey: parsed.issueKey,
+      action: parsed.action,
+      statusName: parsed.statusName,
+      previousStatusName: parsed.previousStatusName,
+      accepted: false,
+      reason: filterResult.reason,
+    });
+    return jsonResponse(200, {
+      accepted: false,
+      reason: filterResult.reason,
+    });
+  }
+
+  if (!parsed.issueKey) {
+    logWebhookEvent({
+      linearDeliveryId: parsed.linearDeliveryId,
+      linearWebhookId: parsed.linearWebhookId,
+      action: parsed.action,
+      statusName: parsed.statusName,
+      accepted: false,
+      reason: "missing_issue_key",
+    });
+    return jsonResponse(200, {
+      accepted: false,
+      reason: "missing_issue_key",
+    });
+  }
+
+  const dispatchToken =
+    options.dispatchToken ?? process.env.GITHUB_DISPATCH_TOKEN;
+  if (!dispatchToken) {
+    logWebhookEvent({
+      issueKey: parsed.issueKey,
+      accepted: false,
+      error: "dispatch_failed",
+    });
+    return jsonResponse(500, { error: "dispatch_failed" });
+  }
+
+  const clientPayload: RepositoryDispatchPayload = {
+    issueKey: parsed.issueKey,
+    issueId: parsed.issueId,
+    issueUrl: parsed.issueUrl,
+    action: parsed.action,
+    statusName: parsed.statusName,
+    previousStatusName: parsed.previousStatusName,
+    linearDeliveryId: parsed.linearDeliveryId,
+    linearWebhookId: parsed.linearWebhookId,
+    receivedAt: new Date(options.nowMs ?? Date.now()).toISOString(),
+  };
+
+  try {
+    await dispatchRepositoryEvent({
+      token: dispatchToken,
+      repository: getDispatchRepository(),
+      eventType: getDispatchEventType(),
+      clientPayload,
+      fetchImpl: options.fetchImpl,
+    });
+  } catch (error) {
+    logWebhookEvent({
+      issueKey: parsed.issueKey,
+      accepted: false,
+      error: "dispatch_failed",
+      reason: error instanceof Error ? error.message : String(error),
+    });
+    return jsonResponse(500, { error: "dispatch_failed" });
+  }
+
+  logWebhookEvent({
+    linearDeliveryId: parsed.linearDeliveryId,
+    linearWebhookId: parsed.linearWebhookId,
+    issueKey: parsed.issueKey,
+    action: parsed.action,
+    statusName: parsed.statusName,
+    previousStatusName: parsed.previousStatusName,
+    accepted: true,
+    dispatched: true,
+  });
+
+  return jsonResponse(200, {
+    accepted: true,
+    dispatched: true,
+    issueKey: parsed.issueKey,
+  });
+}

package/workspace-snapshot/files/src/webhook/parse-linear-issue-event.ts

@@ -0,0 +1,105 @@
+import { extractIssueKey } from "./extract-issue-key.js";
+import type { LinearWebhookHeaders, ParsedLinearIssueWebhook } from "./types.js";
+
+interface LinearStateLike {
+  name?: string | null;
+}
+
+interface LinearIssueData {
+  id?: string;
+  identifier?: string;
+  url?: string;
+  state?: LinearStateLike | null;
+}
+
+interface LinearWebhookPayload {
+  action?: string;
+  type?: string;
+  url?: string;
+  webhookId?: string;
+  webhookTimestamp?: number;
+  actor?: {
+    name?: string;
+    type?: string;
+  };
+  data?: LinearIssueData;
+  updatedFrom?: {
+    stateId?: string | null;
+    state?: LinearStateLike | null;
+  };
+}
+
+function readStateName(state: LinearStateLike | null | undefined): string | null {
+  if (!state || typeof state.name !== "string") {
+    return null;
+  }
+  const trimmed = state.name.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+export function hasStatusChange(payload: LinearWebhookPayload): boolean {
+  const updatedFrom = payload.updatedFrom;
+  if (!updatedFrom) {
+    return false;
+  }
+  if (updatedFrom.stateId != null) {
+    return true;
+  }
+  return updatedFrom.state != null;
+}
+
+export function parseLinearIssueEvent(
+  payload: unknown,
+  headers: LinearWebhookHeaders,
+  teamKey?: string | null,
+): ParsedLinearIssueWebhook | null {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+
+  const body = payload as LinearWebhookPayload;
+  const eventType = headers.eventType ?? body.type ?? "";
+  const data = body.data ?? {};
+  const statusName = readStateName(data.state);
+  const previousStatusName = readStateName(body.updatedFrom?.state);
+  const issueUrl = body.url ?? data.url ?? null;
+
+  const issueKey = extractIssueKey({
+    identifier: data.identifier ?? null,
+    issueUrl: data.url ?? null,
+    payloadUrl: issueUrl,
+    teamKey,
+  });
+
+  const actorName =
+    typeof body.actor?.name === "string" ? body.actor.name.trim() : null;
+  const actorType =
+    typeof body.actor?.type === "string" ? body.actor.type.trim() : null;
+  const actorSummary = actorName ?? actorType;
+
+  return {
+    issueKey,
+    issueId: typeof data.id === "string" ? data.id : null,
+    issueUrl,
+    action: typeof body.action === "string" ? body.action : "",
+    statusName,
+    previousStatusName,
+    statusChanged: hasStatusChange(body),
+    linearDeliveryId: headers.deliveryId,
+    linearWebhookId:
+      typeof body.webhookId === "string" ? body.webhookId : null,
+    actorSummary,
+    eventType,
+  };
+}
+
+export function readWebhookHeaders(
+  headerGetter: (name: string) => string | null,
+): LinearWebhookHeaders {
+  return {
+    signature: headerGetter("linear-signature"),
+    deliveryId: headerGetter("linear-delivery"),
+    eventType: headerGetter("linear-event"),
+    timestamp: headerGetter("linear-timestamp"),
+  };
+}

package/workspace-snapshot/files/src/webhook/redact-log.ts

@@ -0,0 +1,26 @@
+export interface WebhookLogFields {
+  linearDeliveryId?: string | null;
+  linearWebhookId?: string | null;
+  issueKey?: string | null;
+  action?: string | null;
+  statusName?: string | null;
+  previousStatusName?: string | null;
+  accepted?: boolean;
+  dispatched?: boolean;
+  reason?: string | null;
+  error?: string | null;
+}
+
+export function logWebhookEvent(fields: WebhookLogFields): void {
+  console.log(JSON.stringify({ event: "linear_webhook", ...fields }));
+}
+
+export function redactToken(value: string | null | undefined): string {
+  if (!value) {
+    return "[missing]";
+  }
+  if (value.length <= 8) {
+    return "[redacted]";
+  }
+  return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}

package/workspace-snapshot/files/src/webhook/types.ts

@@ -0,0 +1,75 @@
+export interface LinearWebhookHeaders {
+  signature: string | null;
+  deliveryId: string | null;
+  eventType: string | null;
+  timestamp: string | null;
+}
+
+export interface ParsedLinearIssueWebhook {
+  issueKey: string | null;
+  issueId: string | null;
+  issueUrl: string | null;
+  action: string;
+  statusName: string | null;
+  previousStatusName: string | null;
+  statusChanged: boolean;
+  linearDeliveryId: string | null;
+  linearWebhookId: string | null;
+  actorSummary: string | null;
+  eventType: string;
+}
+
+export type WebhookIgnoreReason =
+  | "ignored_event"
+  | "ignored_status"
+  | "missing_issue_key";
+
+export interface WebhookAcceptedResponse {
+  accepted: true;
+  dispatched: true;
+  issueKey: string;
+}
+
+export interface WebhookIgnoredResponse {
+  accepted: false;
+  reason: WebhookIgnoreReason;
+}
+
+export interface WebhookErrorResponse {
+  error:
+    | "method_not_allowed"
+    | "invalid_signature"
+    | "timestamp_out_of_tolerance"
+    | "dispatch_failed";
+}
+
+export interface RepositoryDispatchPayload {
+  issueKey: string;
+  issueId: string | null;
+  issueUrl: string | null;
+  action: string;
+  statusName: string | null;
+  previousStatusName: string | null;
+  linearDeliveryId: string | null;
+  linearWebhookId: string | null;
+  receivedAt: string;
+}
+
+export interface ProductionPromotedDispatchPayload {
+  repo: string;
+  productionBranch: string;
+  sourceRepo: string;
+  after: string;
+  ref: string;
+  receivedAt: string;
+  githubRunId?: string;
+  githubDeliveryId?: string;
+}
+
+export interface DispatchGitHubOptions {
+  token: string;
+  repository: string;
+  eventType: string;
+  clientPayload: RepositoryDispatchPayload | ProductionPromotedDispatchPayload;
+  fetchImpl?: typeof fetch;
+}

package/workspace-snapshot/files/src/webhook/verify.ts

@@ -0,0 +1,68 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export interface VerifySignatureOptions {
+  secret: string;
+  rawBody: string;
+  signatureHeader: string | null;
+}
+
+export interface VerifyTimestampOptions {
+  webhookTimestampMs: number | null;
+  headerTimestampMs: number | null;
+  nowMs?: number;
+  toleranceMs?: number;
+}
+
+export function computeLinearSignature(
+  secret: string,
+  rawBody: string,
+): string {
+  return createHmac("sha256", secret).update(rawBody).digest("hex");
+}
+
+export function verifyLinearSignature(
+  options: VerifySignatureOptions,
+): boolean {
+  const { secret, rawBody, signatureHeader } = options;
+  if (!signatureHeader || !/^[0-9a-f]+$/i.test(signatureHeader)) {
+    return false;
+  }
+
+  const computed = Buffer.from(computeLinearSignature(secret, rawBody), "hex");
+  const provided = Buffer.from(signatureHeader, "hex");
+
+  if (computed.length !== provided.length) {
+    return false;
+  }
+
+  return timingSafeEqual(computed, provided);
+}
+
+export function parseTimestampMs(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+export function verifyWebhookTimestamp(
+  options: VerifyTimestampOptions,
+): boolean {
+  const toleranceMs = options.toleranceMs ?? 60_000;
+  const nowMs = options.nowMs ?? Date.now();
+  const candidates = [options.webhookTimestampMs, options.headerTimestampMs].filter(
+    (value): value is number => value !== null,
+  );
+
+  if (candidates.length === 0) {
+    return false;
+  }
+
+  return candidates.some(
+    (timestampMs) => Math.abs(nowMs - timestampMs) <= toleranceMs,
+  );
+}

package/workspace-snapshot/files/src/webhook/workflow-command.ts

@@ -0,0 +1,10 @@
+export function buildHarnessRunCommand(issueKey: string, phase = "auto"): string {
+  return `npm run harness:run -- --issue ${issueKey} --phase ${phase} --json`;
+}
+
+export function buildHarnessRunArgs(
+  issueKey: string,
+  phase = "auto",
+): string[] {
+  return ["run", "--issue", issueKey, "--phase", phase, "--json"];
+}

package/workspace-snapshot/files/src/workflow/dispatch-metadata.ts

@@ -0,0 +1,59 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const DEFAULT_DISPATCH_METADATA_PATH = "runs/dispatch-metadata.json";
+
+const DISPATCH_METADATA_ENV_KEYS = [
+  "GITHUB_RUN_ID",
+  "LINEAR_DELIVERY_ID",
+  "TRIGGER",
+  "ISSUE_KEY",
+  "PHASE",
+  "REPO_CONFIG_ID",
+  "BASE_BRANCH",
+  "MERGE_CONCURRENCY_GROUP",
+  "EVENT_ACTION",
+  "REPO",
+  "PRODUCTION_BRANCH",
+  "SOURCE_REPO",
+  "AFTER",
+  "RECEIVED_AT",
+] as const;
+
+const ENV_KEY_TO_PAYLOAD_KEY: Record<(typeof DISPATCH_METADATA_ENV_KEYS)[number], string> = {
+  GITHUB_RUN_ID: "githubRunId",
+  LINEAR_DELIVERY_ID: "linearDeliveryId",
+  TRIGGER: "trigger",
+  ISSUE_KEY: "issueKey",
+  PHASE: "phase",
+  REPO_CONFIG_ID: "repoConfigId",
+  BASE_BRANCH: "baseBranch",
+  MERGE_CONCURRENCY_GROUP: "mergeConcurrencyGroup",
+  EVENT_ACTION: "eventAction",
+  REPO: "repo",
+  PRODUCTION_BRANCH: "productionBranch",
+  SOURCE_REPO: "sourceRepo",
+  AFTER: "after",
+  RECEIVED_AT: "receivedAt",
+};
+
+export function buildDispatchMetadataFromEnv(
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const envKey of DISPATCH_METADATA_ENV_KEYS) {
+    const value = env[envKey] ?? "";
+    if (value !== "") {
+      payload[ENV_KEY_TO_PAYLOAD_KEY[envKey]] = value;
+    }
+  }
+  return payload;
+}
+
+export function writeDispatchMetadata(
+  outputPath: string,
+  payload: Record<string, string>,
+): void {
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}

package/workspace-snapshot/files/src/workflow/manifest-summary.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { redactSecrets } from "../artifacts/redact.js";
+
+export interface ManifestSubset {
+  issueKey?: string;
+  phase?: string;
+  finalOutcome?: string;
+  errorClassification?: string | null;
+}
+
+function subsetFromRedacted(redacted: Record<string, unknown>): ManifestSubset {
+  return {
+    issueKey: typeof redacted.issueKey === "string" ? redacted.issueKey : undefined,
+    phase: typeof redacted.phase === "string" ? redacted.phase : undefined,
+    finalOutcome:
+      typeof redacted.finalOutcome === "string" ? redacted.finalOutcome : undefined,
+    errorClassification:
+      typeof redacted.errorClassification === "string" ||
+      redacted.errorClassification === null
+        ? (redacted.errorClassification as string | null)
+        : undefined,
+  };
+}
+
+export function readManifestSubsetFromString(raw: string): ManifestSubset | null {
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const redacted = redactSecrets(parsed) as Record<string, unknown>;
+    return subsetFromRedacted(redacted);
+  } catch {
+    return null;
+  }
+}
+
+export function readManifestSubsetFromFile(path: string): ManifestSubset | null {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return readManifestSubsetFromString(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function formatManifestSummaryLines(subset: ManifestSubset): string[] {
+  const lines: string[] = [];
+  if (subset.issueKey) {
+    lines.push(`- Issue key: \`${subset.issueKey}\``);
+  }
+  if (subset.phase) {
+    lines.push(`- Phase: \`${subset.phase}\``);
+  }
+  if (subset.finalOutcome) {
+    lines.push(`- Outcome: \`${subset.finalOutcome}\``);
+  }
+  lines.push(`- Error classification: \`${subset.errorClassification ?? "none"}\``);
+  return lines;
+}

package/workspace-snapshot/files/src/workflow/production-sync-dispatch.ts

@@ -0,0 +1,65 @@
+import type { HarnessConfig } from "../config/types.js";
+import { repoUrlsEquivalent } from "../resolver/normalize-repo.js";
+
+export class SyncDispatchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SyncDispatchError";
+  }
+}
+
+export interface ProductionSyncDispatchContext {
+  repoId: string;
+  sourceRepo?: string;
+  productionBranch?: string;
+  ref?: string;
+}
+
+function findRepoConfig(config: HarnessConfig, repoId: string) {
+  return config.repos.find((repo) => repo.id === repoId);
+}
+
+export function validateProductionSyncDispatch(
+  ctx: ProductionSyncDispatchContext,
+  config: HarnessConfig,
+): void {
+  const repoConfig = findRepoConfig(config, ctx.repoId);
+  if (!repoConfig) {
+    throw new SyncDispatchError(`unknown_repo_id: ${ctx.repoId}`);
+  }
+
+  if (ctx.sourceRepo?.trim()) {
+    if (!repoUrlsEquivalent(ctx.sourceRepo, repoConfig.targetRepo)) {
+      throw new SyncDispatchError(
+        `source_repo_mismatch: expected ${repoConfig.targetRepo}, got ${ctx.sourceRepo}`,
+      );
+    }
+  }
+
+  if (ctx.productionBranch?.trim()) {
+    if (ctx.productionBranch.trim() !== repoConfig.productionBranch) {
+      throw new SyncDispatchError(
+        `production_branch_mismatch: expected ${repoConfig.productionBranch}, got ${ctx.productionBranch}`,
+      );
+    }
+  }
+
+  if (ctx.ref?.trim()) {
+    const expectedRef = `refs/heads/${repoConfig.productionBranch}`;
+    if (ctx.ref.trim() !== expectedRef) {
+      throw new SyncDispatchError(
+        `ref_mismatch: expected ${expectedRef}, got ${ctx.ref}`,
+      );
+    }
+  }
+}
+
+export function hasProductionSyncDispatchContext(
+  ctx: ProductionSyncDispatchContext,
+): boolean {
+  return Boolean(
+    ctx.sourceRepo?.trim() ||
+      ctx.productionBranch?.trim() ||
+      ctx.ref?.trim(),
+  );
+}

package/workspace-snapshot/files/src/workflow/summarize-manifest.ts

@@ -0,0 +1,20 @@
+import {
+  formatManifestSummaryLines,
+  readManifestSubsetFromFile,
+} from "./manifest-summary.js";
+
+const path = process.argv[2];
+if (!path) {
+  console.error("Usage: summarize-manifest <json-path>");
+  process.exit(1);
+}
+
+const subset = readManifestSubsetFromFile(path);
+if (!subset) {
+  console.log("- Manifest: (unavailable or invalid JSON)");
+  process.exit(0);
+}
+
+for (const line of formatManifestSummaryLines(subset)) {
+  console.log(line);
+}