p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/src/config/cloud-config-fingerprint.ts

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+
+/** Non-secret GitHub Actions repository variable paired with HARNESS_CONFIG_JSON_B64. */
+export const HARNESS_CONFIG_FINGERPRINT_VARIABLE = "HARNESS_CONFIG_FINGERPRINT";
+
+export function fingerprintHarnessConfigBytes(bytes: Buffer | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function fingerprintHarnessConfigJsonB64(b64: string): string {
+  const bytes = Buffer.from(b64.trim(), "base64");
+  return fingerprintHarnessConfigBytes(bytes);
+}
+
+export type CloudConfigFingerprintCheckResult =
+  | { ok: true; fingerprint: string }
+  | {
+      ok: false;
+      errorClassification: "cloud_config_stale";
+      message: string;
+      decodedFingerprint: string | null;
+      expectedFingerprint: string | null;
+    };
+
+/**
+ * Compare decoded HARNESS_CONFIG_JSON_B64 fingerprint against the paired
+ * repository variable. Fail closed when either side is missing or they differ.
+ */
+export function checkCloudConfigFingerprint(input: {
+  configJsonB64?: string | null;
+  expectedFingerprint?: string | null;
+  /** When false (local/dev), skip the check. */
+  enforce?: boolean;
+}): CloudConfigFingerprintCheckResult {
+  if (input.enforce === false) {
+    return { ok: true, fingerprint: input.expectedFingerprint?.trim() || "" };
+  }
+
+  const b64 = input.configJsonB64?.trim() || "";
+  const expected = input.expectedFingerprint?.trim() || "";
+
+  if (!b64 && !expected) {
+    return { ok: true, fingerprint: "" };
+  }
+
+  if (!b64 || !expected) {
+    return {
+      ok: false,
+      errorClassification: "cloud_config_stale",
+      message:
+        "cloud_config_stale: HARNESS_CONFIG_JSON_B64 and HARNESS_CONFIG_FINGERPRINT must both be present",
+      decodedFingerprint: b64 ? fingerprintHarnessConfigJsonB64(b64) : null,
+      expectedFingerprint: expected || null,
+    };
+  }
+
+  let decodedFingerprint: string;
+  try {
+    decodedFingerprint = fingerprintHarnessConfigJsonB64(b64);
+  } catch {
+    return {
+      ok: false,
+      errorClassification: "cloud_config_stale",
+      message: "cloud_config_stale: HARNESS_CONFIG_JSON_B64 could not be decoded",
+      decodedFingerprint: null,
+      expectedFingerprint: expected,
+    };
+  }
+
+  if (decodedFingerprint !== expected) {
+    return {
+      ok: false,
+      errorClassification: "cloud_config_stale",
+      message:
+        "cloud_config_stale: decoded harness config fingerprint does not match HARNESS_CONFIG_FINGERPRINT",
+      decodedFingerprint,
+      expectedFingerprint: expected,
+    };
+  }
+
+  return { ok: true, fingerprint: decodedFingerprint };
+}
+
+export function shouldEnforceCloudConfigFingerprint(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.HARNESS_SKIP_CLOUD_CONFIG_FINGERPRINT === "1") {
+    return false;
+  }
+  // Enforce in GitHub Actions when the secret is loaded from env.
+  return Boolean(env.GITHUB_ACTIONS === "true" && env.HARNESS_CONFIG_JSON_B64?.trim());
+}

package/workspace-snapshot/files/src/config/legacy-linear-top-level.ts

@@ -0,0 +1,69 @@
+import type { HarnessConfig, LinearAssociation } from "./types.js";
+import {
+  resolveLinearAssociationsFromConfig,
+  uniqueTeamIdsFromAssociations,
+} from "./resolve-linear-workspace.js";
+
+/**
+ * Derive legacy top-level linear.* fields from associations.
+ * Only populate teamId/teamKey when exactly one unique team is configured.
+ * Never pick an arbitrary "first" team when multiple teams exist.
+ */
+export function deriveLegacyLinearTopLevel(input: {
+  workspaceId?: string;
+  associations: Array<Pick<LinearAssociation, "workspaceId" | "teamId" | "teamKey">>;
+}): {
+  workspaceId?: string;
+  teamId?: string;
+  teamKey?: string;
+} {
+  const workspaceIds = [
+    ...new Set(
+      [
+        input.workspaceId?.trim(),
+        ...input.associations.map((association) => association.workspaceId.trim()),
+      ].filter((value): value is string => Boolean(value)),
+    ),
+  ];
+  const teamIds = uniqueTeamIdsFromAssociations(input.associations);
+  const result: {
+    workspaceId?: string;
+    teamId?: string;
+    teamKey?: string;
+  } = {};
+
+  if (workspaceIds.length === 1) {
+    result.workspaceId = workspaceIds[0];
+  }
+
+  if (teamIds.length === 1) {
+    const teamId = teamIds[0]!;
+    const sample = input.associations.find(
+      (association) => association.teamId === teamId,
+    );
+    result.teamId = teamId;
+    if (sample?.teamKey?.trim()) {
+      result.teamKey = sample.teamKey.trim();
+    }
+  }
+
+  return result;
+}
+
+export function applyLegacyLinearTopLevelToConfig(
+  config: HarnessConfig,
+  workspaceId?: string,
+): HarnessConfig["linear"] {
+  const associations = resolveLinearAssociationsFromConfig(config);
+  const derived = deriveLegacyLinearTopLevel({
+    workspaceId: workspaceId ?? config.linear?.workspaceId,
+    associations,
+  });
+
+  return {
+    ...config.linear,
+    workspaceId: derived.workspaceId,
+    teamId: derived.teamId,
+    teamKey: derived.teamKey,
+  };
+}

package/workspace-snapshot/files/src/config/linear-association-gate.ts

@@ -0,0 +1,80 @@
+import type { HarnessConfig } from "./types.js";
+import type { ErrorClassification } from "../types/run.js";
+import {
+  assertLinearAssociationConfigured,
+  hasLinearAssociationsInConfig,
+  resolveLinearAssociationForIssue,
+} from "./resolve-linear-workspace.js";
+
+export type LinearAssociationGateResult =
+  | { ok: true }
+  | {
+      ok: false;
+      code: "linear_team_project_not_configured";
+      message: string;
+      errorClassification: ErrorClassification;
+    };
+
+export function runLinearAssociationGate(input: {
+  config: HarnessConfig;
+  teamId?: string | null;
+  teamKey?: string | null;
+  teamName?: string | null;
+  projectId?: string | null;
+}): LinearAssociationGateResult {
+  if (!hasLinearAssociationsInConfig(input.config)) {
+    return { ok: true };
+  }
+
+  const teamId = input.teamId?.trim();
+  const projectId = input.projectId?.trim();
+  const teamKey = input.teamKey?.trim();
+  const teamName = input.teamName?.trim();
+
+  if (!projectId || (!teamId && !teamKey && !teamName)) {
+    return {
+      ok: false,
+      code: "linear_team_project_not_configured",
+      message:
+        "linear_team_project_not_configured: issue team and project identity are required when linearAssociations are configured",
+      errorClassification: "linear_team_project_not_configured",
+    };
+  }
+
+  const result = assertLinearAssociationConfigured(input.config, {
+    teamId,
+    teamKey,
+    teamName,
+    projectId,
+  });
+
+  if (!result.ok) {
+    return {
+      ok: false,
+      code: result.code,
+      message: `${result.code}: no harness association matches team ${teamId ?? teamKey ?? teamName} and project ${projectId}`,
+      errorClassification: result.code,
+    };
+  }
+
+  return { ok: true };
+}
+
+export function resolveAssociationTargetRepo(input: {
+  config: HarnessConfig;
+  teamId?: string | null;
+  teamKey?: string | null;
+  teamName?: string | null;
+  projectId?: string | null;
+}): ReturnType<typeof resolveLinearAssociationForIssue> {
+  const projectId = input.projectId?.trim();
+  if (!projectId) {
+    return null;
+  }
+  return resolveLinearAssociationForIssue(input.config, {
+    teamId: input.teamId,
+    teamKey: input.teamKey,
+    teamName: input.teamName,
+    projectId,
+  });
+}

package/workspace-snapshot/files/src/config/resolve-linear-team.ts

@@ -0,0 +1,41 @@
+import type { HarnessConfig } from "./types.js";
+import {
+  resolveLinearAssociationsFromConfig,
+  uniqueTeamIdsFromAssociations,
+} from "./resolve-linear-workspace.js";
+
+export async function resolveAuthoritativeLinearTeamId(input: {
+  config: HarnessConfig;
+  workspaceRoot?: string;
+  configPath?: string;
+  baseDir?: string;
+}): Promise<string | undefined> {
+  void input.workspaceRoot;
+  void input.configPath;
+  void input.baseDir;
+  return resolveAuthoritativeLinearTeamIdFromConfig(input.config);
+}
+
+export function resolveAuthoritativeLinearTeamIdFromConfig(
+  config: HarnessConfig,
+): string | undefined {
+  const associations = resolveLinearAssociationsFromConfig(config);
+  if (associations.length > 0) {
+    return uniqueTeamIdsFromAssociations(associations)[0];
+  }
+
+  const configuredTeamId = config.linear?.teamId?.trim();
+  return configuredTeamId || undefined;
+}
+
+export function resolveAuthoritativeLinearTeamIds(
+  config: HarnessConfig,
+): string[] {
+  const associations = resolveLinearAssociationsFromConfig(config);
+  if (associations.length > 0) {
+    return uniqueTeamIdsFromAssociations(associations);
+  }
+
+  const configuredTeamId = config.linear?.teamId?.trim();
+  return configuredTeamId ? [configuredTeamId] : [];
+}

package/workspace-snapshot/files/src/config/resolve-linear-workspace.ts

@@ -0,0 +1,391 @@
+import type { HarnessConfig, LinearAssociation, RepoMapping } from "./types.js";
+import type {
+  ControlPlaneSetupState,
+  LinearWorkspaceEvidence,
+} from "../setup/control-plane-types.js";
+
+export type ResolvedLinearAssociation = LinearAssociation & {
+  targetRepo: string;
+  repoConfigId: string;
+};
+
+export type LinearAssociationKey = {
+  workspaceId: string;
+  teamId: string;
+  projectId: string;
+};
+
+export type ResolveLinearAssociationInput = {
+  workspaceId?: string;
+  teamId?: string | null;
+  teamKey?: string | null;
+  teamName?: string | null;
+  projectId?: string | null;
+};
+
+export function linearAssociationKey(
+  association: LinearAssociationKey,
+): string {
+  return `${association.workspaceId}:${association.teamId}:${association.projectId}`;
+}
+
+function normalizeIdentity(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function resolveLinearAssociationsFromConfig(
+  config: HarnessConfig,
+): ResolvedLinearAssociation[] {
+  const resolved: ResolvedLinearAssociation[] = [];
+
+  for (const repo of config.repos) {
+    for (const association of repo.linearAssociations ?? []) {
+      resolved.push({
+        ...association,
+        targetRepo: repo.targetRepo,
+        repoConfigId: repo.id,
+      });
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve an issue association using:
+ * 1. Exact teamId + projectId
+ * 2. Exact teamId with a uniquely configured project
+ * 3. Exact normalized teamKey + projectId
+ * 4. Exact normalized full teamName + projectId
+ * 5. null when ambiguous or unconfigured
+ *
+ * Never compares a full team name against a team key.
+ */
+export function resolveLinearAssociationForIssue(
+  config: HarnessConfig,
+  input: ResolveLinearAssociationInput,
+): ResolvedLinearAssociation | null {
+  const associations = resolveLinearAssociationsFromConfig(config);
+  if (associations.length === 0) {
+    return null;
+  }
+
+  const teamId = input.teamId?.trim() || undefined;
+  const projectId = input.projectId?.trim() || undefined;
+  const teamKey = input.teamKey?.trim() || undefined;
+  const teamName = input.teamName?.trim() || undefined;
+  const workspaceId = input.workspaceId?.trim() || undefined;
+
+  const workspaceFilter = (association: ResolvedLinearAssociation): boolean => {
+    if (!workspaceId) return true;
+    return association.workspaceId === workspaceId;
+  };
+
+  // 1. Exact teamId + projectId
+  if (teamId && projectId) {
+    const exact = associations.filter(
+      (association) =>
+        workspaceFilter(association) &&
+        association.teamId === teamId &&
+        association.projectId === projectId,
+    );
+    if (exact.length === 1) return exact[0]!;
+    if (exact.length > 1) return null;
+    // Explicit wrong projectId must fail closed — do not fall through to unique-project.
+  }
+
+  // 2. Exact teamId with a uniquely configured project (only when projectId omitted)
+  if (teamId && !projectId) {
+    const byTeam = associations.filter(
+      (association) =>
+        workspaceFilter(association) && association.teamId === teamId,
+    );
+    if (byTeam.length === 1) return byTeam[0]!;
+    return null;
+  }
+
+  // 3. Exact normalized teamKey + projectId
+  if (teamKey && projectId) {
+    const key = normalizeIdentity(teamKey);
+    const byKey = associations.filter(
+      (association) =>
+        workspaceFilter(association) &&
+        association.projectId === projectId &&
+        normalizeIdentity(association.teamKey) === key,
+    );
+    if (byKey.length === 1) return byKey[0]!;
+    if (byKey.length > 1) return null;
+  }
+
+  // 4. Exact normalized full teamName + projectId (never match against teamKey)
+  if (teamName && projectId) {
+    const name = normalizeIdentity(teamName);
+    const byName = associations.filter(
+      (association) =>
+        workspaceFilter(association) &&
+        association.projectId === projectId &&
+        Boolean(association.teamName?.trim()) &&
+        normalizeIdentity(association.teamName!) === name,
+    );
+    if (byName.length === 1) return byName[0]!;
+    if (byName.length > 1) return null;
+  }
+
+  return null;
+}
+
+export type LinearAssociationAssertResult =
+  | { ok: true; association: ResolvedLinearAssociation }
+  | { ok: false; code: "linear_team_project_not_configured" };
+
+export function assertLinearAssociationConfigured(
+  config: HarnessConfig,
+  input: ResolveLinearAssociationInput,
+): LinearAssociationAssertResult {
+  const association = resolveLinearAssociationForIssue(config, input);
+  if (!association) {
+    return { ok: false, code: "linear_team_project_not_configured" };
+  }
+  return { ok: true, association };
+}
+
+export type SharedProjectTargetRepoResult =
+  | { ok: true }
+  | {
+      ok: false;
+      code: "linear_project_target_repo_conflict";
+      projectId: string;
+      targetRepos: string[];
+    };
+
+export function assertSharedProjectTargetRepoConsistency(
+  associations: Array<Pick<LinearAssociation, "projectId"> & { targetRepo: string }>,
+): SharedProjectTargetRepoResult {
+  const byProject = new Map<string, Set<string>>();
+
+  for (const association of associations) {
+    const existing = byProject.get(association.projectId) ?? new Set<string>();
+    existing.add(association.targetRepo);
+    byProject.set(association.projectId, existing);
+  }
+
+  for (const [projectId, targetRepos] of byProject.entries()) {
+    if (targetRepos.size > 1) {
+      return {
+        ok: false,
+        code: "linear_project_target_repo_conflict",
+        projectId,
+        targetRepos: [...targetRepos],
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+export function groupAssociationsByTeam(
+  associations: ResolvedLinearAssociation[],
+): Map<string, ResolvedLinearAssociation[]> {
+  const grouped = new Map<string, ResolvedLinearAssociation[]>();
+  for (const association of associations) {
+    const existing = grouped.get(association.teamId) ?? [];
+    existing.push(association);
+    grouped.set(association.teamId, existing);
+  }
+  return grouped;
+}
+
+export function uniqueProjectIdsFromAssociations(
+  associations: Array<Pick<LinearAssociation, "projectId">>,
+): string[] {
+  return [...new Set(associations.map((association) => association.projectId))];
+}
+
+export function uniqueTeamIdsFromAssociations(
+  associations: Array<Pick<LinearAssociation, "teamId">>,
+): string[] {
+  return [...new Set(associations.map((association) => association.teamId))];
+}
+
+export function buildLinearAssociationsForRepo(input: {
+  repo: RepoMapping;
+  associations: LinearAssociation[];
+}): LinearAssociation[] {
+  return input.associations.map((association) => ({ ...association }));
+}
+
+export function hasLinearAssociationsInConfig(config: HarnessConfig): boolean {
+  return config.repos.some(
+    (repo) => (repo.linearAssociations?.length ?? 0) > 0,
+  );
+}
+
+export function getLinearWorkspaceIdFromConfig(
+  config: HarnessConfig,
+): string | undefined {
+  const configured = config.linear?.workspaceId?.trim();
+  if (configured) {
+    return configured;
+  }
+
+  const associations = resolveLinearAssociationsFromConfig(config);
+  const workspaceIds = [
+    ...new Set(associations.map((association) => association.workspaceId)),
+  ];
+  return workspaceIds.length === 1 ? workspaceIds[0] : undefined;
+}
+
+export function formatLinearTeamLabel(association: {
+  teamName?: string;
+  teamKey: string;
+}): string {
+  const name = association.teamName?.trim();
+  if (name && name !== association.teamKey) {
+    return `${name} (${association.teamKey})`;
+  }
+  if (name) {
+    return name;
+  }
+  return association.teamKey;
+}
+
+export function evidenceFromAssociations(input: {
+  workspaceId: string;
+  workspaceName: string;
+  associations: ResolvedLinearAssociation[];
+  appliedFingerprint?: string;
+  appliedAt?: string;
+  migratedFromVersion?: LinearWorkspaceEvidence["migratedFromVersion"];
+  migratedAt?: string;
+}): LinearWorkspaceEvidence {
+  const teams = new Map<
+    string,
+    {
+      teamId: string;
+      teamKey: string;
+      teamName: string;
+      projects: LinearWorkspaceEvidence["teams"][number]["projects"];
+      lastVerifiedAt?: string;
+    }
+  >();
+
+  for (const association of input.associations) {
+    // Never copy teamKey into teamName — legacy associations without a name stay unnamed.
+    const teamName = association.teamName?.trim() || "(unnamed team)";
+    const team =
+      teams.get(association.teamId) ??
+      {
+        teamId: association.teamId,
+        teamKey: association.teamKey,
+        teamName,
+        projects: [],
+      };
+
+    if (association.teamName?.trim()) {
+      team.teamName = association.teamName.trim();
+    }
+
+    if (!team.projects.some((project) => project.projectId === association.projectId)) {
+      team.projects.push({
+        projectId: association.projectId,
+        projectName: association.projectName,
+        targetRepo: association.targetRepo,
+        health: "verification_pending",
+      });
+    }
+
+    teams.set(association.teamId, team);
+  }
+
+  return {
+    workspaceId: input.workspaceId,
+    workspaceName: input.workspaceName,
+    teams: [...teams.values()].map((team) => ({
+      ...team,
+      health: "verification_pending" as const,
+    })),
+    appliedFingerprint: input.appliedFingerprint,
+    appliedAt: input.appliedAt,
+    migratedFromVersion: input.migratedFromVersion,
+    migratedAt: input.migratedAt,
+  };
+}
+
+export type ConfigControlPlaneDriftFinding = {
+  code:
+    | "association_count_mismatch"
+    | "team_id_mismatch"
+    | "project_id_mismatch"
+    | "workspace_id_mismatch"
+    | "target_repo_mismatch";
+  message: string;
+  teamId?: string;
+  projectId?: string;
+};
+
+export function detectConfigControlPlaneDrift(input: {
+  config: HarnessConfig;
+  controlPlane: ControlPlaneSetupState | null;
+}): ConfigControlPlaneDriftFinding[] {
+  const findings: ConfigControlPlaneDriftFinding[] = [];
+  const evidence = input.controlPlane?.linearWorkspace;
+  if (!evidence) {
+    return findings;
+  }
+
+  const configAssociations = resolveLinearAssociationsFromConfig(input.config);
+  const evidencePairs = evidence.teams.flatMap((team) =>
+    team.projects.map((project) => ({
+      workspaceId: evidence.workspaceId,
+      teamId: team.teamId,
+      projectId: project.projectId,
+      targetRepo: project.targetRepo,
+    })),
+  );
+
+  if (configAssociations.length !== evidencePairs.length) {
+    findings.push({
+      code: "association_count_mismatch",
+      message: `Harness config has ${configAssociations.length} association(s) but control-plane evidence has ${evidencePairs.length}.`,
+    });
+  }
+
+  const workspaceId = getLinearWorkspaceIdFromConfig(input.config);
+  if (workspaceId && workspaceId !== evidence.workspaceId) {
+    findings.push({
+      code: "workspace_id_mismatch",
+      message: `Harness config workspaceId (${workspaceId}) does not match control-plane (${evidence.workspaceId}).`,
+    });
+  }
+
+  for (const configAssociation of configAssociations) {
+    const evidenceMatch = evidencePairs.find(
+      (pair) =>
+        pair.teamId === configAssociation.teamId &&
+        pair.projectId === configAssociation.projectId,
+    );
+    if (!evidenceMatch) {
+      findings.push({
+        code: "project_id_mismatch",
+        message: `Association ${configAssociation.teamId}/${configAssociation.projectId} exists in harness config but not in control-plane evidence.`,
+        teamId: configAssociation.teamId,
+        projectId: configAssociation.projectId,
+      });
+      continue;
+    }
+
+    if (
+      evidenceMatch.targetRepo &&
+      evidenceMatch.targetRepo !== configAssociation.targetRepo
+    ) {
+      findings.push({
+        code: "target_repo_mismatch",
+        message: `Target repo for ${configAssociation.projectId} differs between harness config and control-plane evidence.`,
+        teamId: configAssociation.teamId,
+        projectId: configAssociation.projectId,
+      });
+    }
+  }
+
+  return findings;
+}

package/workspace-snapshot/files/src/config/role-models.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const ROLE_MODEL_ROLES = ["planner", "builder"] as const;
+export type RoleModelRole = (typeof ROLE_MODEL_ROLES)[number];
+
+export const modelParameterValueSchema = z.object({
+  id: z.string().min(1),
+  value: z.string(),
+});
+
+export const roleModelSelectionSchema = z
+  .object({
+    id: z.string().min(1),
+    params: z.array(modelParameterValueSchema).optional(),
+  })
+  .superRefine((selection, ctx) => {
+    const paramIds = selection.params?.map((param) => param.id) ?? [];
+    const unique = new Set(paramIds);
+    if (unique.size !== paramIds.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "duplicate parameter ids are not allowed within a role model selection",
+      });
+    }
+  });
+
+export const roleModelsSchema = z
+  .object({
+    planner: roleModelSelectionSchema.optional(),
+    builder: roleModelSelectionSchema.optional(),
+  })
+  .strict();
+
+export type RoleModelSelection = z.infer<typeof roleModelSelectionSchema>;
+export type RoleModelsConfig = z.infer<typeof roleModelsSchema>;
+
+export function isRoleModelRole(value: string): value is RoleModelRole {
+  return (ROLE_MODEL_ROLES as readonly string[]).includes(value);
+}