p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/setup/setup-actions.ts

@@ -0,0 +1,183 @@
+import { mkdir } from "node:fs/promises";
+import type { SetupPermission } from "./permission-model.js";
+import { SETUP_PERMISSIONS } from "./permission-model.js";
+import {
+  scaffoldConfigFromExample,
+  writeConfigLocal,
+} from "./config-writer.js";
+import { scaffoldEnvFromExample, writeEnvLocal } from "./env-writer.js";
+import {
+  generateGitHubSecretInstructions,
+  generateHarnessConfigB64Instructions,
+} from "./generated-instructions.js";
+import {
+  REMOTE_SETUP_ACTIONS,
+} from "./remote-actions.js";
+import {
+  resolveLocalFilePaths,
+  type SetupActionOutcome,
+  type SetupExecutionMode,
+  type SetupScaffoldOptions,
+} from "./setup-state.js";
+
+export interface SetupActionResult {
+  actionId: string;
+  outcome: SetupActionOutcome;
+  targetPath?: string;
+  content?: string;
+  reason?: string;
+  permission: SetupPermission;
+  manualInstructions?: string[];
+  logMessage?: string;
+}
+
+export interface SetupActionDescriptor {
+  id: string;
+  label: string;
+  description: string;
+  permission: SetupPermission;
+}
+
+export const SETUP_ACTIONS = {
+  scaffoldEnvLocal: {
+    id: "scaffold-env-local",
+    label: "Scaffold .env.local",
+    description: "Create or update local environment file from committed example",
+    permission: SETUP_PERMISSIONS.localFileWrite,
+  },
+  scaffoldConfigLocal: {
+    id: "scaffold-config-local",
+    label: "Scaffold .harness/config.local.json",
+    description:
+      "Create or update private harness config from committed example",
+    permission: SETUP_PERMISSIONS.localFileWrite,
+  },
+  generateHarnessConfigB64Instructions: {
+    id: "generate-harness-config-b64-instructions",
+    label: "Generate HARNESS_CONFIG_JSON_B64 instructions",
+    description: "Produce manual copy-paste steps for GitHub Actions config secret",
+    permission: SETUP_PERMISSIONS.readOnly,
+  },
+  generateGitHubSecretInstructions: {
+    id: "generate-github-secret-instructions",
+    label: "Generate GitHub Actions secret instructions",
+    description: "Produce manual copy-paste steps for harness repo secrets",
+    permission: SETUP_PERMISSIONS.readOnly,
+  },
+  applyHarnessSecrets: {
+    id: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.id,
+    label: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.label,
+    description: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.description,
+    permission: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.permission,
+  },
+  futureSetGitHubSecrets: {
+    id: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.id,
+    label: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.label,
+    description: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.description,
+    permission: REMOTE_SETUP_ACTIONS.applyHarnessSecrets.permission,
+  },
+  previewHarnessSecrets: {
+    id: REMOTE_SETUP_ACTIONS.previewHarnessSecrets.id,
+    label: REMOTE_SETUP_ACTIONS.previewHarnessSecrets.label,
+    description: REMOTE_SETUP_ACTIONS.previewHarnessSecrets.description,
+    permission: REMOTE_SETUP_ACTIONS.previewHarnessSecrets.permission,
+  },
+  previewTargetWorkflowPr: {
+    id: REMOTE_SETUP_ACTIONS.previewTargetWorkflowPr.id,
+    label: REMOTE_SETUP_ACTIONS.previewTargetWorkflowPr.label,
+    description: REMOTE_SETUP_ACTIONS.previewTargetWorkflowPr.description,
+    permission: REMOTE_SETUP_ACTIONS.previewTargetWorkflowPr.permission,
+  },
+  applyTargetWorkflowPr: {
+    id: REMOTE_SETUP_ACTIONS.applyTargetWorkflowPr.id,
+    label: REMOTE_SETUP_ACTIONS.applyTargetWorkflowPr.label,
+    description: REMOTE_SETUP_ACTIONS.applyTargetWorkflowPr.description,
+    permission: REMOTE_SETUP_ACTIONS.applyTargetWorkflowPr.permission,
+  },
+} as const satisfies Record<string, SetupActionDescriptor>;
+
+export interface OperatorScaffoldResult {
+  results: SetupActionResult[];
+  logMessages: string[];
+}
+
+function resolveMode(options?: SetupScaffoldOptions): SetupExecutionMode {
+  return options?.mode ?? "apply";
+}
+
+export async function runOperatorScaffold(
+  options?: SetupScaffoldOptions,
+): Promise<OperatorScaffoldResult> {
+  const paths = resolveLocalFilePaths(options?.cwd);
+  const force = options?.force ?? false;
+  const mode = resolveMode(options);
+  const results: SetupActionResult[] = [];
+  const logMessages: string[] = [];
+
+  if (mode === "apply") {
+    await mkdir(paths.harnessDir, { recursive: true });
+  }
+
+  const envResult = await scaffoldEnvFromExample({
+    paths,
+    force,
+    mode,
+  });
+  results.push(envResult);
+  if (envResult.logMessage) {
+    logMessages.push(envResult.logMessage);
+  }
+
+  const configResult = await scaffoldConfigFromExample({
+    paths,
+    force,
+    mode,
+  });
+  results.push(configResult);
+  if (configResult.logMessage) {
+    logMessages.push(configResult.logMessage);
+  }
+
+  return { results, logMessages };
+}
+
+export function previewHarnessConfigB64Instructions(options?: {
+  configPath?: string;
+}): SetupActionResult {
+  const instructions = generateHarnessConfigB64Instructions(options);
+  return {
+    actionId: SETUP_ACTIONS.generateHarnessConfigB64Instructions.id,
+    outcome: "preview",
+    permission: SETUP_ACTIONS.generateHarnessConfigB64Instructions.permission,
+    manualInstructions: instructions.steps,
+    content: instructions.command,
+    reason: instructions.summary,
+  };
+}
+
+export function previewGitHubSecretInstructions(options?: {
+  harnessRepo?: string;
+}): SetupActionResult {
+  const instructions = generateGitHubSecretInstructions(options);
+  return {
+    actionId: SETUP_ACTIONS.generateGitHubSecretInstructions.id,
+    outcome: "preview",
+    permission: SETUP_ACTIONS.generateGitHubSecretInstructions.permission,
+    manualInstructions: instructions.steps,
+    reason: instructions.summary,
+  };
+}
+
+export function describeDeferredRemoteHarnessSecretWrite(): SetupActionResult {
+  const instructions = generateGitHubSecretInstructions();
+  return {
+    actionId: SETUP_ACTIONS.futureSetGitHubSecrets.id,
+    outcome: "preview",
+    permission: SETUP_ACTIONS.futureSetGitHubSecrets.permission,
+    manualInstructions: instructions.steps,
+    reason:
+      "Remote secret writes are previewable in setup core. GUI apply remains deferred to Milestone 5 PR 2.",
+  };
+}
+
+export { writeConfigLocal, writeEnvLocal };

package/workspace-snapshot/files/src/setup/setup-github-auth.ts

@@ -0,0 +1,15 @@
+import { readExistingEnvFile } from "./env-merge.js";
+import { resolveLocalFilePaths } from "./setup-state.js";
+
+export async function loadGithubTokenFromEnvLocal(options?: {
+  cwd?: string;
+}): Promise<string | undefined> {
+  const paths = resolveLocalFilePaths(options?.cwd);
+  const existingEnv = await readExistingEnvFile(paths);
+  const token = existingEnv?.values.GITHUB_TOKEN?.trim();
+  return token || undefined;
+}
+
+export function hasGithubTokenConfigured(token?: string): boolean {
+  return Boolean(token?.trim());
+}

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

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+export type SetupExecutionMode = "dry-run" | "apply";
+
+export type SetupActionOutcome =
+  | "changed"
+  | "skipped"
+  | "wouldChange"
+  | "preview";
+
+export const ENV_EXAMPLE = ".env.example";
+export const ENV_LOCAL = ".env.local";
+export const HARNESS_DIR = ".harness";
+export const CONFIG_EXAMPLE = path.join(HARNESS_DIR, "config.example.json");
+export const CONFIG_LOCAL = path.join(HARNESS_DIR, "config.local.json");
+export const DEFAULT_HARNESS_CONFIG_PATH = ".harness/config.local.json";
+
+export interface LocalFilePaths {
+  cwd: string;
+  envExample: string;
+  envLocal: string;
+  harnessDir: string;
+  configExample: string;
+  configLocal: string;
+}
+
+export interface SetupScaffoldOptions {
+  force?: boolean;
+  cwd?: string;
+  mode?: SetupExecutionMode;
+}
+
+export interface TargetRepoSetupInput {
+  id: string;
+  linearProjects?: string[];
+  linearTeams?: string[];
+  targetRepo: string;
+  baseBranch?: string;
+  productionBranch?: string;
+  previewProvider?: string;
+  integrationPreviewUrl?: string;
+  productionUrl?: string;
+  integrationSuccessStatus?: string;
+  productionSuccessStatus?: string;
+  validationCommands?: string[];
+}
+
+export interface SetupEnvInput {
+  harnessConfigPath?: string;
+  githubDispatchRepository?: string;
+  githubDispatchRepositoryId?: string;
+  linearApiKey?: string;
+  cursorApiKey?: string;
+  githubToken?: string;
+  vercelToken?: string;
+}
+
+export interface SetupConfigBuildInput {
+  repos: TargetRepoSetupInput[];
+  linearTeamKey?: string;
+  modelId?: string;
+}
+
+export function resolveLocalFilePaths(cwd?: string): LocalFilePaths {
+  const root = cwd ?? process.cwd();
+  return {
+    cwd: root,
+    envExample: path.join(root, ENV_EXAMPLE),
+    envLocal: path.join(root, ENV_LOCAL),
+    harnessDir: path.join(root, HARNESS_DIR),
+    configExample: path.join(root, CONFIG_EXAMPLE),
+    configLocal: path.join(root, CONFIG_LOCAL),
+  };
+}

package/workspace-snapshot/files/src/setup/stale-smoke-repo.ts

@@ -0,0 +1,141 @@
+import type { SetupGuiViewModel } from "./gui-view-model.js";
+import { parseGitHubRepoSlug } from "./github-repo-slug.js";
+
+export const STALE_SMOKE_HARNESS_PATTERN = /pdh-smoke-harness-/i;
+export const STALE_SMOKE_TARGET_PATTERN = /pdh-smoke-target-/i;
+
+export type StaleSmokeRepoKind =
+  | "harness-dispatch"
+  | "target-repo"
+  | "allowed-target-repo";
+
+export interface StaleSmokeRepoFinding {
+  kind: StaleSmokeRepoKind;
+  value: string;
+  source: string;
+}
+
+export interface StaleSmokeDiagnostics {
+  hasStaleConfig: boolean;
+  findings: StaleSmokeRepoFinding[];
+  staleHarnessDispatchRepo?: string;
+  staleTargetRepos: string[];
+  suggestedHarnessDispatchRepo?: string;
+}
+
+export function isStaleSmokeHarnessRepo(value: string): boolean {
+  return STALE_SMOKE_HARNESS_PATTERN.test(value.trim());
+}
+
+export function isStaleSmokeTargetRepo(value: string): boolean {
+  return STALE_SMOKE_TARGET_PATTERN.test(value.trim());
+}
+
+export function detectStaleSmokeRepoFindings(input: {
+  harnessDispatchRepo?: string;
+  configSummary?: SetupGuiViewModel["configSummary"];
+  targetRepos?: Array<{ id: string; targetRepo: string }>;
+  allowedTargetRepos?: string[];
+}): StaleSmokeRepoFinding[] {
+  const findings: StaleSmokeRepoFinding[] = [];
+
+  if (
+    input.harnessDispatchRepo &&
+    isStaleSmokeHarnessRepo(input.harnessDispatchRepo)
+  ) {
+    findings.push({
+      kind: "harness-dispatch",
+      value: input.harnessDispatchRepo,
+      source: "GITHUB_DISPATCH_REPOSITORY",
+    });
+  }
+
+  const repos =
+    input.configSummary?.repos ??
+    input.targetRepos?.map((repo) => ({
+      id: repo.id,
+      targetRepo: repo.targetRepo,
+      baseBranch: "main",
+      productionBranch: "main",
+    })) ??
+    [];
+
+  const allowedTargetRepos =
+    input.configSummary?.allowedTargetRepos ?? input.allowedTargetRepos ?? [];
+
+  for (const repo of repos) {
+    if (isStaleSmokeTargetRepo(repo.targetRepo)) {
+      findings.push({
+        kind: "target-repo",
+        value: repo.targetRepo,
+        source: `repos[].targetRepo (${repo.id})`,
+      });
+    }
+  }
+
+  for (const allowedRepo of allowedTargetRepos) {
+    if (isStaleSmokeTargetRepo(allowedRepo)) {
+      findings.push({
+        kind: "allowed-target-repo",
+        value: allowedRepo,
+        source: "allowedTargetRepos[]",
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function deriveStaleSmokeDiagnostics(input: {
+  harnessDispatchRepo?: string;
+  gitRemoteOriginUrl?: string | null;
+  configSummary?: SetupGuiViewModel["configSummary"];
+  targetRepos?: Array<{ id: string; targetRepo: string }>;
+  allowedTargetRepos?: string[];
+}): StaleSmokeDiagnostics {
+  const findings = detectStaleSmokeRepoFindings(input);
+  const suggestedHarnessDispatchRepo = input.gitRemoteOriginUrl
+    ? parseGitHubRepoSlug(input.gitRemoteOriginUrl) ?? undefined
+    : undefined;
+
+  const staleHarnessDispatchRepo = findings.find(
+    (finding) => finding.kind === "harness-dispatch",
+  )?.value;
+
+  const staleTargetRepos = [
+    ...new Set(
+      findings
+        .filter(
+          (finding) =>
+            finding.kind === "target-repo" ||
+            finding.kind === "allowed-target-repo",
+        )
+        .map((finding) => finding.value),
+    ),
+  ];
+
+  return {
+    hasStaleConfig: findings.length > 0,
+    findings,
+    staleHarnessDispatchRepo,
+    staleTargetRepos,
+    suggestedHarnessDispatchRepo,
+  };
+}
+
+export function remoteSetupBlockedByStaleSmoke(
+  diagnostics: StaleSmokeDiagnostics,
+): boolean {
+  return diagnostics.hasStaleConfig;
+}
+
+export function shouldSuppressRemoteDownstreamStatus(
+  diagnostics: StaleSmokeDiagnostics,
+  harnessRepoAccess: "available" | "denied" | "unknown",
+): boolean {
+  return (
+    diagnostics.hasStaleConfig &&
+    (diagnostics.staleHarnessDispatchRepo !== undefined ||
+      harnessRepoAccess === "denied")
+  );
+}

package/workspace-snapshot/files/src/setup/sync-downstream-summaries.ts

@@ -0,0 +1,105 @@
+import type { SetupGuiViewModel } from "./gui-view-model.js";
+import type { LinearSetupSummary } from "./linear-setup-summary.js";
+import type { VercelSetupSummary } from "./vercel-setup-summary.js";
+import type { RemoteSetupSummary } from "./remote-setup-summary.js";
+import {
+  type HarnessActionsSecretName,
+} from "./remote-actions.js";
+
+export const VERCEL_MISSING_TOKEN_GATE_MESSAGE =
+  "Add VERCEL_TOKEN in Step 1 before configuring Vercel settings.";
+
+type EnvKeyPresence = SetupGuiViewModel["envKeyPresence"];
+
+function localSecretAvailableForHarnessAction(
+  envKeyPresence: EnvKeyPresence,
+  secretName: HarnessActionsSecretName,
+): boolean {
+  switch (secretName) {
+    case "LINEAR_API_KEY":
+      return envKeyPresence.LINEAR_API_KEY;
+    case "CURSOR_API_KEY":
+      return envKeyPresence.CURSOR_API_KEY;
+    case "HARNESS_GITHUB_TOKEN":
+      return envKeyPresence.GITHUB_TOKEN;
+    case "HARNESS_CONFIG_JSON_B64":
+      return false;
+  }
+}
+
+export function syncLinearSummaryFromEnvPresence(
+  current: LinearSetupSummary,
+  envKeyPresence: EnvKeyPresence,
+): LinearSetupSummary {
+  return {
+    ...current,
+    linearApiKeyConfigured: envKeyPresence.LINEAR_API_KEY,
+  };
+}
+
+export function syncVercelSummaryFromEnvPresence(
+  current: VercelSetupSummary,
+  envKeyPresence: EnvKeyPresence,
+): VercelSetupSummary {
+  return {
+    ...current,
+    vercelTokenConfigured: envKeyPresence.VERCEL_TOKEN,
+    linearApiKeyConfigured: envKeyPresence.LINEAR_API_KEY,
+  };
+}
+
+export function syncRemoteSummaryFromEnvPresence(
+  current: RemoteSetupSummary,
+  envKeyPresence: EnvKeyPresence,
+): RemoteSetupSummary {
+  const harnessSecretStatuses = current.harnessSecretStatuses.map((entry) => {
+    if (entry.status === "present") {
+      return entry;
+    }
+    if (
+      entry.status === "missing" &&
+      localSecretAvailableForHarnessAction(envKeyPresence, entry.name)
+    ) {
+      return { ...entry, status: "unknown" as const };
+    }
+    return entry;
+  });
+
+  return {
+    ...current,
+    githubTokenConfigured: envKeyPresence.GITHUB_TOKEN,
+    harnessSecretStatuses,
+  };
+}
+
+export function syncDownstreamSummariesFromEnvPresence(input: {
+  envKeyPresence: EnvKeyPresence;
+  linearSummary: LinearSetupSummary;
+  vercelSummary: VercelSetupSummary;
+  remoteSummary: RemoteSetupSummary;
+}): {
+  linearSummary: LinearSetupSummary;
+  vercelSummary: VercelSetupSummary;
+  remoteSummary: RemoteSetupSummary;
+} {
+  return {
+    linearSummary: syncLinearSummaryFromEnvPresence(
+      input.linearSummary,
+      input.envKeyPresence,
+    ),
+    vercelSummary: syncVercelSummaryFromEnvPresence(
+      input.vercelSummary,
+      input.envKeyPresence,
+    ),
+    remoteSummary: syncRemoteSummaryFromEnvPresence(
+      input.remoteSummary,
+      input.envKeyPresence,
+    ),
+  };
+}
+
+export function vercelBridgeShowsMissingTokenGate(
+  vercelSummary: VercelSetupSummary,
+): boolean {
+  return !vercelSummary.vercelTokenConfigured;
+}

package/workspace-snapshot/files/src/setup/target-workflow-finalization-lock.ts

@@ -0,0 +1,95 @@
+import type { TargetWorkflowFinalizationResult } from "./target-workflow-finalization-types.js";
+
+const activeLocks = new Set<string>();
+const latestResults = new Map<string, TargetWorkflowFinalizationResult>();
+
+export function buildFinalizationLockKey(
+  targetRepoSlug: string,
+  repoConfigId: string,
+): string {
+  return `${targetRepoSlug}:${repoConfigId}`;
+}
+
+export function isFinalizationLockActive(key: string): boolean {
+  return activeLocks.has(key);
+}
+
+export function getCachedFinalizationResult(
+  key: string,
+): TargetWorkflowFinalizationResult | undefined {
+  return latestResults.get(key);
+}
+
+export function setCachedFinalizationResult(
+  key: string,
+  result: TargetWorkflowFinalizationResult,
+): void {
+  latestResults.set(key, result);
+}
+
+export function clearCachedFinalizationResult(key: string): void {
+  latestResults.delete(key);
+}
+
+/**
+ * Serializes finalization for one target repo config. Concurrent callers wait for
+ * the in-flight advancement, then receive the latest cached result without
+ * issuing duplicate mutations.
+ */
+export async function withTargetWorkflowFinalizationLock<T>(
+  key: string,
+  fn: () => Promise<T>,
+): Promise<{ result: T; lockContended: boolean }> {
+  if (activeLocks.has(key)) {
+    const cached = latestResults.get(key);
+    if (cached) {
+      return { result: cached as unknown as T, lockContended: true };
+    }
+    await waitForLockRelease(key);
+    const afterWait = latestResults.get(key);
+    if (afterWait) {
+      return { result: afterWait as unknown as T, lockContended: true };
+    }
+  }
+
+  activeLocks.add(key);
+  try {
+    const result = await fn();
+    if (
+      typeof result === "object" &&
+      result !== null &&
+      "lifecycle" in result
+    ) {
+      const finalization = result as unknown as TargetWorkflowFinalizationResult;
+      latestResults.set(key, finalization);
+      if (finalization.lifecycle === "complete") {
+        latestResults.delete(key);
+      }
+    }
+    return { result, lockContended: false };
+  } finally {
+    activeLocks.delete(key);
+    notifyLockReleased(key);
+  }
+}
+
+const lockWaiters = new Map<string, Array<() => void>>();
+
+function waitForLockRelease(key: string): Promise<void> {
+  if (!activeLocks.has(key)) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const waiters = lockWaiters.get(key) ?? [];
+    waiters.push(resolve);
+    lockWaiters.set(key, waiters);
+  });
+}
+
+export function notifyLockReleased(key: string): void {
+  const waiters = lockWaiters.get(key) ?? [];
+  lockWaiters.delete(key);
+  for (const resolve of waiters) {
+    resolve();
+  }
+}

package/workspace-snapshot/files/src/setup/target-workflow-finalization-types.ts

@@ -0,0 +1,55 @@
+export type WorkflowInstallLifecycle =
+  | "preparing"
+  | "pr-created"
+  | "pr-updated"
+  | "waiting-for-checks"
+  | "updating-branch"
+  | "merging"
+  | "verifying"
+  | "complete"
+  | "blocked";
+
+export type WorkflowInstallBlockedCategory =
+  | "checks-pending"
+  | "checks-failing"
+  | "mergeability-pending"
+  | "branch-behind"
+  | "review-required"
+  | "permission-denied"
+  | "merge-conflict"
+  | "unexpected-pr-content"
+  | "merge-queue-required"
+  | "merge-api-failure"
+  | "verification-failed";
+
+export interface TargetWorkflowFinalizationResult {
+  repoConfigId: string;
+  targetRepo: string;
+  targetRepoSlug: string;
+  productionBranch: string;
+  branchName: string;
+  lifecycle: WorkflowInstallLifecycle;
+  blockedCategory?: WorkflowInstallBlockedCategory;
+  message: string;
+  prUrl?: string;
+  prNumber?: number;
+  validatedHeadSha?: string;
+  workflowStatus: "present" | "missing" | "differs" | "unknown";
+  canRetry: boolean;
+  requiresGitHubIntervention: boolean;
+  advancedThisRequest: boolean;
+  lockContended: boolean;
+}
+
+export interface TargetWorkflowFinalizeInput {
+  repoConfigId: string;
+  targetRepo: string;
+  productionBranch: string;
+  manualHarnessDispatchRepo?: string;
+  prUrl?: string;
+  branchName?: string;
+}
+
+export const WORKFLOW_INSTALL_CHECK_POLL_TIMEOUT_MS = 120_000;
+export const WORKFLOW_INSTALL_VERIFICATION_TIMEOUT_MS = 60_000;
+export const WORKFLOW_INSTALL_SHORT_POLL_INTERVAL_MS = 2_000;