p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/setup/control-plane-readiness.ts

@@ -0,0 +1,291 @@
+import type { SetupGuiViewModel } from "./gui-view-model.js";
+import type { ControlPlaneReadinessContext } from "./control-plane-types.js";
+import { requiredStatusNames } from "./linear-status-contract.js";
+import { isVercelBridgeStale } from "./vercel-bridge-readiness.js";
+import type { ReadinessBlocker } from "./first-run-readiness.js";
+
+function pushBlocker(
+  blockers: ReadinessBlocker[],
+  blocker: Omit<ReadinessBlocker, "blocking" | "tone"> & {
+    blocking?: boolean;
+    tone?: "setup_needed" | "error";
+  },
+): void {
+  blockers.push({
+    blocking: true,
+    tone: blocker.tone ?? "setup_needed",
+    ...blocker,
+  });
+}
+
+export function collectConnectServicesBlockers(
+  summary: SetupGuiViewModel,
+): ReadinessBlocker[] {
+  const blockers: ReadinessBlocker[] = [];
+
+  if (!summary.envKeyPresence.LINEAR_API_KEY) {
+    pushBlocker(blockers, {
+      id: "missing-linear-key",
+      stepId: "connect-services",
+      message: "Setup needed: LINEAR_API_KEY is not configured yet.",
+      action: "Add it in Step 1 · Connect services.",
+      priority: 103,
+    });
+  }
+
+  if (!summary.envKeyPresence.CURSOR_API_KEY) {
+    pushBlocker(blockers, {
+      id: "missing-cursor-key",
+      stepId: "connect-services",
+      message: "Setup needed: CURSOR_API_KEY is not configured yet.",
+      action: "Add it in Step 1 · Connect services.",
+      priority: 104,
+    });
+  }
+
+  if (!summary.envKeyPresence.GITHUB_TOKEN) {
+    pushBlocker(blockers, {
+      id: "missing-github-token",
+      stepId: "connect-services",
+      message: "Setup needed: GITHUB_TOKEN is not configured yet.",
+      action: "Add it in Step 1 · Connect services.",
+      priority: 105,
+    });
+  }
+
+  if (!summary.envKeyPresence.VERCEL_TOKEN) {
+    pushBlocker(blockers, {
+      id: "missing-vercel-token",
+      stepId: "connect-services",
+      message: "Setup needed: VERCEL_TOKEN is not configured yet.",
+      action: "Add it in Step 1 · Connect services.",
+      priority: 106,
+    });
+  }
+
+  return blockers.sort((left, right) => left.priority - right.priority);
+}
+
+export function collectLinearWorkspaceBlockers(
+  context: ControlPlaneReadinessContext,
+  uiState?: { linearPreviewStale?: boolean },
+): ReadinessBlocker[] {
+  const blockers: ReadinessBlocker[] = [];
+  const linear = context.state?.linear;
+
+  if (!linear?.teamKey) {
+    pushBlocker(blockers, {
+      id: "linear-workspace-not-applied",
+      stepId: "linear-workspace",
+      message: "Setup needed: Linear workspace setup is not complete yet.",
+      action:
+        "Next: Preview and apply Linear team, project, and workflow statuses.",
+      priority: 150,
+    });
+  } else if (!linear.statusCoverageComplete && !linear.manualComplete) {
+    pushBlocker(blockers, {
+      id: "linear-status-coverage-incomplete",
+      stepId: "linear-workspace",
+      message: "Blocked: Required Linear workflow statuses are still missing.",
+      action:
+        "Next: Complete Linear workspace setup or confirm manual status coverage.",
+      priority: 151,
+    });
+  }
+
+  if (uiState?.linearPreviewStale) {
+    pushBlocker(blockers, {
+      id: "linear-preview-stale",
+      stepId: "linear-workspace",
+      message: "Blocked: Linear setup preview is out of date.",
+      action: "Next: Regenerate the Linear setup preview, then confirm and apply.",
+      priority: 152,
+      tone: "error",
+    });
+  }
+
+  return blockers.sort((left, right) => left.priority - right.priority);
+}
+
+export function collectVercelBridgeBlockers(
+  context: ControlPlaneReadinessContext,
+  uiState?: { vercelPreviewStale?: boolean },
+): ReadinessBlocker[] {
+  const blockers: ReadinessBlocker[] = [];
+  const vercel = context.state?.vercel;
+  const linearTeamKey = context.state?.linear?.teamKey;
+
+  if (!vercel?.projectId) {
+    pushBlocker(blockers, {
+      id: "vercel-bridge-not-applied",
+      stepId: "vercel-bridge",
+      message: "Setup needed: Vercel webhook bridge setup is not complete yet.",
+      action:
+        "Next: Preview and apply Vercel bridge env vars and webhook readiness.",
+      priority: 160,
+    });
+  } else {
+    if (!vercel.endpointReachable) {
+      pushBlocker(blockers, {
+        id: "vercel-endpoint-unreachable",
+        stepId: "vercel-bridge",
+        message:
+          "Blocked: Vercel /api/linear-webhook endpoint is not reachable yet.",
+        action:
+          "Next: Deploy the bridge project and confirm the public webhook route is reachable.",
+        priority: 161,
+        tone: "error",
+      });
+    }
+
+    for (const [key, status] of Object.entries(vercel.envVarPresence ?? {})) {
+      if (status === "missing") {
+        pushBlocker(blockers, {
+          id: `vercel-env-missing-${key}`,
+          stepId: "vercel-bridge",
+          message: `Blocked: Vercel production env var ${key} is missing.`,
+          action: "Next: Apply Vercel bridge env vars or set them manually.",
+          priority: 162,
+          tone: "error",
+        });
+      }
+    }
+
+    if (!vercel.linearWebhookVerified) {
+      pushBlocker(blockers, {
+        id: "linear-webhook-unverified",
+        stepId: "vercel-bridge",
+        message:
+          "Blocked: Linear Issue webhook is not verified for the Vercel bridge URL.",
+        action:
+          "Next: Create or verify the Linear webhook, then refresh bridge readiness.",
+        priority: 163,
+        tone: "error",
+      });
+    }
+
+    if (!vercel.signedProbeVerified) {
+      pushBlocker(blockers, {
+        id: "signed-probe-unverified",
+        stepId: "vercel-bridge",
+        message:
+          "Blocked: Signed webhook delivery verification has not passed against production.",
+        action:
+          "Next: Apply Vercel bridge settings and wait for signed probe verification to pass.",
+        priority: 164,
+        tone: "error",
+      });
+    }
+
+    if (vercel.deploymentRedeployRequired) {
+      pushBlocker(blockers, {
+        id: "vercel-redeploy-required",
+        stepId: "vercel-bridge",
+        message:
+          "Blocked: Vercel production must be redeployed after env var changes before signed verification can pass.",
+        action: "Next: Redeploy production, then retry Vercel bridge apply.",
+        priority: 165,
+        tone: "error",
+      });
+    }
+
+    if (
+      linearTeamKey &&
+      vercel.envVarPresence?.HARNESS_TEAM_KEY === "present" &&
+      context.state?.linear?.teamKey &&
+      isVercelBridgeStale({
+        configuredTeamKey: context.state.linear.teamKey,
+        selectedTeamKey: linearTeamKey,
+      })
+    ) {
+      pushBlocker(blockers, {
+        id: "vercel-team-key-stale",
+        stepId: "vercel-bridge",
+        message:
+          "Blocked: Vercel HARNESS_TEAM_KEY may be stale after Linear team changes.",
+        action: "Next: Re-apply Vercel bridge setup with the current team key.",
+        priority: 166,
+        tone: "error",
+      });
+    }
+  }
+
+  if (uiState?.vercelPreviewStale) {
+    pushBlocker(blockers, {
+      id: "vercel-preview-stale",
+      stepId: "vercel-bridge",
+      message: "Blocked: Vercel bridge preview is out of date.",
+      action:
+        "Next: Regenerate the Vercel bridge preview, then confirm and apply.",
+      priority: 167,
+      tone: "error",
+    });
+  }
+
+  return blockers.sort((left, right) => left.priority - right.priority);
+}
+
+
+function normalizeCloudSecretsConfigState(input: {
+  setupSummary: SetupGuiViewModel;
+  controlPlaneContext?: ControlPlaneReadinessContext;
+}) {
+  const configSummary = input.setupSummary.configSummary;
+  return {
+    configResolved: input.setupSummary.overview.configResolved,
+    operatorConfigResolved: input.setupSummary.overview.operatorConfigResolved,
+    linearTeamKeyFromConfig:
+      input.controlPlaneContext?.linearTeamKeyFromConfig ?? null,
+    linearTeamKeyFromControlPlane:
+      input.controlPlaneContext?.state?.linear?.teamKey ?? null,
+    repoIds: (configSummary?.repos ?? [])
+      .map((repo) => repo.id)
+      .sort((left, right) => left.localeCompare(right)),
+    repoTargets: (configSummary?.repos ?? [])
+      .map((repo) => ({ id: repo.id, targetRepo: repo.targetRepo }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    allowedTargetRepos: [...(configSummary?.allowedTargetRepos ?? [])].sort(
+      (left, right) => left.localeCompare(right),
+    ),
+  };
+}
+
+export function computeCloudSecretsConfigStateFingerprint(input: {
+  setupSummary: SetupGuiViewModel;
+  controlPlaneContext?: ControlPlaneReadinessContext;
+}): string {
+  // JSON snapshot only — used for equality checks in client + server bundles.
+  return JSON.stringify(normalizeCloudSecretsConfigState(input));
+}
+
+export function isCloudSecretsStaleFromControlPlane(
+  context: ControlPlaneReadinessContext,
+): boolean {
+  const linearTeamKey = context.state?.linear?.teamKey;
+  const configTeamKey = context.linearTeamKeyFromConfig;
+  if (linearTeamKey && configTeamKey && linearTeamKey !== configTeamKey) {
+    return true;
+  }
+  return false;
+}
+
+export function summarizeLinearWorkspaceStatus(
+  context: ControlPlaneReadinessContext,
+): {
+  configured: boolean;
+  teamKey?: string;
+  projectName?: string;
+  statusCoverageComplete: boolean;
+  requiredStatusCount: number;
+} {
+  const linear = context.state?.linear;
+  return {
+    configured: Boolean(linear?.teamKey),
+    teamKey: linear?.teamKey,
+    projectName: linear?.projectName,
+    statusCoverageComplete: Boolean(
+      linear?.statusCoverageComplete || linear?.manualComplete,
+    ),
+    requiredStatusCount: requiredStatusNames().length,
+  };
+}

package/workspace-snapshot/files/src/setup/control-plane-setup-state.ts

@@ -0,0 +1,60 @@
+import { access, readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveLocalFilePaths } from "./setup-state.js";
+import type { ControlPlaneSetupState } from "./control-plane-types.js";
+
+export type {
+  ControlPlaneSetupState,
+  ControlPlaneReadinessContext,
+  LinearWorkspaceSelection,
+  VercelBridgeSelection,
+} from "./control-plane-types.js";
+
+const STATE_FILE = path.join(".harness", "control-plane-setup.json");
+
+function statePath(cwd?: string): string {
+  const paths = resolveLocalFilePaths(cwd);
+  return path.join(paths.cwd, STATE_FILE);
+}
+
+export async function readControlPlaneSetupState(
+  cwd?: string,
+): Promise<ControlPlaneSetupState | null> {
+  const filePath = statePath(cwd);
+  try {
+    await access(filePath);
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw) as ControlPlaneSetupState;
+    if (parsed.version !== 1) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeControlPlaneSetupState(
+  state: ControlPlaneSetupState,
+  cwd?: string,
+): Promise<void> {
+  const paths = resolveLocalFilePaths(cwd);
+  await mkdir(paths.harnessDir, { recursive: true });
+  await writeFile(statePath(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export async function updateControlPlaneSetupState(
+  patch: Partial<ControlPlaneSetupState>,
+  cwd?: string,
+): Promise<ControlPlaneSetupState> {
+  const current = (await readControlPlaneSetupState(cwd)) ?? { version: 1 };
+  const next: ControlPlaneSetupState = {
+    ...current,
+    ...patch,
+    version: 1,
+    linear: patch.linear ?? current.linear,
+    vercel: patch.vercel ?? current.vercel,
+  };
+  await writeControlPlaneSetupState(next, cwd);
+  return next;
+}

package/workspace-snapshot/files/src/setup/control-plane-types.ts

@@ -0,0 +1,121 @@
+export interface LinearWorkspaceSelection {
+  teamMode: "existing" | "create";
+  teamId?: string;
+  teamKey: string;
+  teamName: string;
+  projectMode: "existing" | "create";
+  projectId?: string;
+  projectName: string;
+  statusCoverageComplete: boolean;
+  appliedFingerprint?: string;
+  appliedAt?: string;
+  manualComplete?: boolean;
+}
+
+export interface VercelSignedProbeEvidence {
+  passed: boolean;
+  statusCode?: number;
+  result:
+    | "accepted_ignored"
+    | "auth_failed"
+    | "unreachable"
+    | "protection_redirect"
+    | "error";
+  reason?: string;
+  probedAt: string;
+  webhookHost?: string;
+  webhookPath?: string;
+}
+
+export type VercelBridgeRedeployVerificationStatus =
+  | "triggered"
+  | "building"
+  | "ready"
+  | "failed"
+  | "timeout"
+  | "no_source_deployment"
+  | "verify_failed"
+  | "verified";
+
+export type VercelBridgeCandidateSecretSource =
+  | "operator"
+  | "reused-readable"
+  | "generated"
+  | "unreadable";
+
+/** Non-secret/tokenized inputs used to compute the preview fingerprint hash. */
+export interface VercelBridgePreviewFingerprintInputs {
+  actionId: string;
+  teamId?: string;
+  teamMode?: string;
+  teamSlug?: string;
+  projectId: string;
+  projectMode?: string;
+  projectName?: string;
+  envWritePlan: Array<{
+    key: string;
+    action: string;
+    source: string;
+    existingType?: string;
+    desiredType?: string;
+  }>;
+  linearWebhookSecretToken: string;
+  githubDispatchTokenToken: string;
+  harnessTeamKey: string;
+  vercelTokenToken: string;
+}
+
+export interface VercelBridgeRedeployVerification {
+  actionId: string;
+  projectId: string;
+  projectName: string;
+  teamId?: string;
+  webhookUrl: string;
+  fingerprint: string;
+  fingerprintInputs?: VercelBridgePreviewFingerprintInputs;
+  candidateSecretSource?: VercelBridgeCandidateSecretSource;
+  sourceDeploymentId?: string;
+  newDeploymentId?: string;
+  status: VercelBridgeRedeployVerificationStatus;
+  startedAt: string;
+  updatedAt: string;
+  deadlineAt: string;
+  verifyAttempted: boolean;
+  completedAt?: string;
+  message?: string;
+  blockedMessage?: string;
+  blockedNextSteps?: string[];
+  writtenEnvKeys?: string[];
+  skippedEnvKeys?: string[];
+}
+
+export interface VercelBridgeSelection {
+  teamId?: string;
+  teamName?: string;
+  projectId: string;
+  projectName: string;
+  productionUrl: string;
+  webhookUrl: string;
+  endpointReachable: boolean;
+  envVarPresence: Record<string, "present" | "missing" | "unknown">;
+  linearWebhookVerified: boolean;
+  signedProbeVerified?: boolean;
+  signedProbe?: VercelSignedProbeEvidence;
+  verificationFingerprint?: string;
+  deploymentRedeployRequired?: boolean;
+  appliedFingerprint?: string;
+  appliedAt?: string;
+  manualComplete?: boolean;
+  redeployVerification?: VercelBridgeRedeployVerification;
+}
+
+export interface ControlPlaneSetupState {
+  version: 1;
+  linear?: LinearWorkspaceSelection;
+  vercel?: VercelBridgeSelection;
+}
+
+export interface ControlPlaneReadinessContext {
+  state: ControlPlaneSetupState | null;
+  linearTeamKeyFromConfig?: string;
+}

package/workspace-snapshot/files/src/setup/doctor-summary.ts

@@ -0,0 +1,96 @@
+export interface DoctorCheckResult {
+  label: string;
+  ok: boolean;
+  detail?: string;
+  skipped?: boolean;
+}
+
+export type DoctorCheckGroup =
+  | "configuration"
+  | "linear"
+  | "cursor"
+  | "github"
+  | "filesystem";
+
+export interface DoctorCheckGroupSummary {
+  group: DoctorCheckGroup;
+  checks: DoctorCheckResult[];
+}
+
+const GROUP_RULES: Array<{
+  group: DoctorCheckGroup;
+  match: (label: string) => boolean;
+}> = [
+  {
+    group: "configuration",
+    match: (label) =>
+      label.includes("harness config") ||
+      label.includes("allowedTargetRepos") ||
+      label.includes("harness.config.json"),
+  },
+  {
+    group: "filesystem",
+    match: (label) => label.includes("runs/ directory writable"),
+  },
+  {
+    group: "linear",
+    match: (label) => label.startsWith("LINEAR_API_KEY"),
+  },
+  {
+    group: "cursor",
+    match: (label) =>
+      label.startsWith("CURSOR_API_KEY") ||
+      label.startsWith("Cursor models.list") ||
+      label.startsWith("Cursor repositories.list"),
+  },
+  {
+    group: "github",
+    match: (label) =>
+      label.startsWith("GITHUB_TOKEN") ||
+      label.includes("base branch exists") ||
+      label.includes("PR head-branch write"),
+  },
+];
+
+export function summarizeDoctorChecks(
+  checks: DoctorCheckResult[],
+): DoctorCheckGroupSummary[] {
+  const grouped = new Map<DoctorCheckGroup, DoctorCheckResult[]>();
+
+  for (const check of checks) {
+    const group =
+      GROUP_RULES.find((rule) => rule.match(check.label))?.group ?? "configuration";
+    const existing = grouped.get(group) ?? [];
+    existing.push(check);
+    grouped.set(group, existing);
+  }
+
+  const order: DoctorCheckGroup[] = [
+    "configuration",
+    "filesystem",
+    "linear",
+    "cursor",
+    "github",
+  ];
+
+  return order
+    .filter((group) => grouped.has(group))
+    .map((group) => ({
+      group,
+      checks: grouped.get(group) ?? [],
+    }));
+}
+
+export function doctorChecksFailed(checks: DoctorCheckResult[]): boolean {
+  return checks.some((check) => !check.ok && !check.skipped);
+}
+
+export function formatDoctorCheckLine(check: DoctorCheckResult): string {
+  const icon = check.skipped ? "○" : check.ok ? "✓" : "✗";
+  const suffix = check.detail ? ` — ${check.detail}` : "";
+  return `${icon} ${check.label}${suffix}`;
+}
+
+export function formatDoctorCheckLines(checks: DoctorCheckResult[]): string[] {
+  return checks.map(formatDoctorCheckLine);
+}