p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/setup/linear-setup-client.ts

@@ -0,0 +1,276 @@
+import { LinearClient } from "@linear/sdk";
+import type { Connection } from "@linear/sdk";
+import type { RequiredWorkflowStatus } from "./linear-status-contract.js";
+
+export interface LinearTeamSummary {
+  id: string;
+  key: string;
+  name: string;
+}
+
+export interface LinearProjectSummary {
+  id: string;
+  name: string;
+  /** Team IDs from `project.teams()` — not on the default Project list fragment. */
+  teamIds: string[];
+}
+
+export interface LinearWorkflowStateSummary {
+  id: string;
+  name: string;
+  type: string;
+}
+
+export interface LinearWebhookSummary {
+  id: string;
+  url: string;
+  enabled: boolean;
+  resourceTypes: string[];
+  teamId?: string;
+  secret?: string;
+}
+
+export interface LinearSetupCapabilities {
+  teamCreate: boolean;
+  projectCreate: boolean;
+  workflowStateCreate: boolean;
+  webhookCreate: boolean;
+  webhookList: boolean;
+}
+
+export function createLinearSetupClient(apiKey: string): LinearClient {
+  return new LinearClient({ apiKey: apiKey.trim() });
+}
+
+async function paginateConnection<T>(
+  connection: Connection<T>,
+): Promise<T[]> {
+  while (connection.pageInfo?.hasNextPage) {
+    await connection.fetchNext();
+  }
+  return connection.nodes ?? [];
+}
+
+/**
+ * Linear's default `projects()` list fragment does not include team IDs.
+ * Team association is loaded per project via `project.teams()`.
+ */
+async function resolveProjectTeamIds(
+  project: { id: string; teams: () => Promise<Connection<{ id: string }>> },
+): Promise<string[]> {
+  try {
+    const teamsConnection = await project.teams();
+    return (teamsConnection.nodes ?? []).map((team) => team.id);
+  } catch {
+    return [];
+  }
+}
+
+export async function listLinearTeams(
+  client: LinearClient,
+): Promise<LinearTeamSummary[]> {
+  const connection = await client.teams();
+  const teams = await paginateConnection(connection);
+  return teams.map((team) => ({
+    id: team.id,
+    key: team.key ?? "",
+    name: team.name ?? "",
+  }));
+}
+
+export async function listLinearProjects(
+  client: LinearClient,
+): Promise<LinearProjectSummary[]> {
+  const connection = await client.projects();
+  const projects = await paginateConnection(connection);
+  return Promise.all(
+    projects.map(async (project) => ({
+      id: project.id,
+      name: project.name ?? "",
+      teamIds: await resolveProjectTeamIds(project),
+    })),
+  );
+}
+
+export async function listTeamWorkflowStates(
+  client: LinearClient,
+  teamId: string,
+): Promise<LinearWorkflowStateSummary[]> {
+  const connection = await client.workflowStates({
+    filter: { team: { id: { eq: teamId } } },
+  });
+  const states = await paginateConnection(connection);
+  return states.map((state) => ({
+    id: state.id,
+    name: state.name ?? "",
+    type: state.type ?? "",
+  }));
+}
+
+export async function listLinearWebhooks(
+  client: LinearClient,
+): Promise<LinearWebhookSummary[]> {
+  const connection = await client.webhooks();
+  const webhooks = await paginateConnection(connection);
+  return webhooks.map((webhook) => ({
+    id: webhook.id,
+    url: webhook.url ?? "",
+    enabled: webhook.enabled ?? false,
+    resourceTypes: webhook.resourceTypes ?? [],
+    teamId: webhook.teamId ?? undefined,
+    secret: webhook.secret ?? undefined,
+  }));
+}
+
+export async function createLinearTeam(
+  client: LinearClient,
+  input: { name: string; key: string; description?: string },
+): Promise<LinearTeamSummary> {
+  const payload = await client.createTeam({
+    name: input.name,
+    key: input.key,
+    description: input.description,
+  });
+  const team = await payload.team;
+  if (!team) {
+    throw new Error("Linear team creation did not return a team");
+  }
+  return {
+    id: team.id,
+    key: team.key ?? input.key,
+    name: team.name ?? input.name,
+  };
+}
+
+export async function createLinearProject(
+  client: LinearClient,
+  input: { name: string; teamIds: string[]; description?: string },
+): Promise<LinearProjectSummary> {
+  const payload = await client.createProject({
+    name: input.name,
+    teamIds: input.teamIds,
+    description: input.description,
+  });
+  const project = await payload.project;
+  if (!project) {
+    throw new Error("Linear project creation did not return a project");
+  }
+  return {
+    id: project.id,
+    name: project.name ?? input.name,
+    teamIds: input.teamIds,
+  };
+}
+
+export async function createLinearWorkflowState(
+  client: LinearClient,
+  input: {
+    teamId: string;
+    name: string;
+    type: RequiredWorkflowStatus["category"];
+    color?: string;
+  },
+): Promise<LinearWorkflowStateSummary> {
+  const payload = await client.createWorkflowState({
+    teamId: input.teamId,
+    name: input.name,
+    type: input.type,
+    color: input.color ?? "#9CA3AF",
+  });
+  const state = await payload.workflowState;
+  if (!state) {
+    throw new Error("Linear workflow state creation did not return a state");
+  }
+  return {
+    id: state.id,
+    name: state.name ?? input.name,
+    type: state.type ?? input.type,
+  };
+}
+
+export function isDuplicateWorkflowStateError(error: unknown): boolean {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "";
+  return /duplicate workflow state/i.test(message);
+}
+
+export async function createLinearIssueWebhook(
+  client: LinearClient,
+  input: { url: string; teamId?: string; label?: string; secret?: string },
+): Promise<LinearWebhookSummary> {
+  const payload = await client.createWebhook({
+    url: input.url,
+    label: input.label ?? "Harness webhook bridge",
+    resourceTypes: ["Issue"],
+    teamId: input.teamId,
+    allPublicTeams: input.teamId ? undefined : true,
+    ...(input.secret ? { secret: input.secret } : {}),
+  });
+  const webhook = await payload.webhook;
+  if (!webhook) {
+    throw new Error("Linear webhook creation did not return a webhook");
+  }
+  const secret =
+    typeof (webhook as { secret?: unknown }).secret === "string"
+      ? ((webhook as { secret?: string }).secret ?? undefined)
+      : input.secret;
+  return {
+    id: webhook.id,
+    url: webhook.url ?? input.url,
+    enabled: webhook.enabled ?? true,
+    resourceTypes: webhook.resourceTypes ?? ["Issue"],
+    teamId: webhook.teamId ?? input.teamId,
+    secret,
+  };
+}
+
+export async function updateLinearIssueWebhook(
+  client: LinearClient,
+  input: {
+    webhookId: string;
+    url: string;
+    secret: string;
+    label?: string;
+  },
+): Promise<LinearWebhookSummary> {
+  const payload = await client.updateWebhook(input.webhookId, {
+    url: input.url,
+    label: input.label ?? "Harness webhook bridge",
+    resourceTypes: ["Issue"],
+    secret: input.secret,
+    enabled: true,
+  });
+  const webhook = await payload.webhook;
+  if (!webhook) {
+    throw new Error("Linear webhook update did not return a webhook");
+  }
+  return {
+    id: webhook.id,
+    url: webhook.url ?? input.url,
+    enabled: webhook.enabled ?? true,
+    resourceTypes: webhook.resourceTypes ?? ["Issue"],
+    teamId: webhook.teamId ?? undefined,
+    secret: webhook.secret ?? input.secret,
+  };
+}
+
+export async function deleteLinearWebhook(
+  client: LinearClient,
+  webhookId: string,
+): Promise<void> {
+  await client.deleteWebhook(webhookId);
+}
+
+export function getLinearSetupCapabilities(): LinearSetupCapabilities {
+  return {
+    teamCreate: true,
+    projectCreate: true,
+    workflowStateCreate: true,
+    webhookCreate: true,
+    webhookList: true,
+  };
+}

package/workspace-snapshot/files/src/setup/linear-setup-plan.ts

@@ -0,0 +1,353 @@
+import { createHash } from "node:crypto";
+import {
+  lookupRequiredStatus,
+  requiredCreatableStatuses,
+  getDispatchTriggerStatuses,
+  type RequiredWorkflowStatus,
+} from "./linear-status-contract.js";
+import {
+  createLinearSetupClient,
+  getLinearSetupCapabilities,
+  listLinearProjects,
+  listLinearTeams,
+  listLinearWebhooks,
+  listTeamWorkflowStates,
+  type LinearProjectSummary,
+  type LinearTeamSummary,
+  type LinearWorkflowStateSummary,
+} from "./linear-setup-client.js";
+import { SETUP_PERMISSIONS } from "./permission-model.js";
+import { tokenizeSecretInput } from "./secret-change-token.js";
+
+export const LINEAR_SETUP_ACTIONS = {
+  preview: {
+    id: "preview-linear-setup",
+    permission: SETUP_PERMISSIONS.remoteRead,
+  },
+  apply: {
+    id: "apply-linear-setup",
+    permission: SETUP_PERMISSIONS.linearWrite,
+  },
+} as const;
+
+export interface LinearTeamPlanInput {
+  mode: "existing" | "create";
+  teamId?: string;
+  teamKey?: string;
+  teamName?: string;
+}
+
+export interface LinearProjectPlanInput {
+  mode: "existing" | "create";
+  projectId?: string;
+  projectName?: string;
+  description?: string;
+}
+
+export interface LinearSetupPlanInput {
+  linearApiKey: string;
+  team: LinearTeamPlanInput;
+  project: LinearProjectPlanInput;
+}
+
+export interface WorkflowStatusPlanEntry {
+  name: string;
+  category: RequiredWorkflowStatus["category"];
+  role: RequiredWorkflowStatus["role"];
+  present: boolean;
+  existingType?: string;
+  action: "skip" | "create" | "manual";
+  creatable: boolean;
+}
+
+export interface LinearSetupPreview {
+  actionId: string;
+  capabilities: ReturnType<typeof getLinearSetupCapabilities>;
+  teams: LinearTeamSummary[];
+  projects: LinearProjectSummary[];
+  selectedTeam?: LinearTeamSummary;
+  selectedProject?: LinearProjectSummary;
+  workflowStates: WorkflowStatusPlanEntry[];
+  dispatchTriggerStatuses: readonly string[];
+  missingStatuses: string[];
+  createActions: Array<{ kind: "team" | "project" | "workflow-state"; name: string }>;
+  manualSteps: string[];
+  fingerprint: string;
+  permission: typeof SETUP_PERMISSIONS.remoteRead;
+  validationError?: string;
+}
+
+function hashPreview(input: unknown): string {
+  return createHash("sha256")
+    .update(JSON.stringify(input))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export function normalizeLinearName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+export function matchWorkflowStates(
+  existing: LinearWorkflowStateSummary[],
+): WorkflowStatusPlanEntry[] {
+  const byName = new Map(
+    existing.map((state) => [normalizeLinearName(state.name), state]),
+  );
+
+  return requiredCreatableStatuses().map((required) => {
+    const match = byName.get(normalizeLinearName(required.name));
+    const present = Boolean(match);
+    let action: WorkflowStatusPlanEntry["action"] = "skip";
+    if (!present) {
+      action = required.creatable ? "create" : "manual";
+    }
+    return {
+      name: required.name,
+      category: required.category,
+      role: required.role,
+      present,
+      existingType: match?.type,
+      action,
+      creatable: required.creatable,
+    };
+  });
+}
+
+export function findExistingTeamForCreateInput(
+  teams: LinearTeamSummary[],
+  input: { teamKey: string; teamName: string },
+): LinearTeamSummary | undefined {
+  const key = input.teamKey.trim().toLowerCase();
+  const name = normalizeLinearName(input.teamName);
+  return (
+    teams.find((team) => team.key.trim().toLowerCase() === key) ??
+    teams.find((team) => normalizeLinearName(team.name) === name)
+  );
+}
+
+export function findExistingProjectForCreateInput(
+  projects: LinearProjectSummary[],
+  input: { projectName: string; teamId?: string },
+): LinearProjectSummary | undefined {
+  const name = normalizeLinearName(input.projectName);
+  return projects.find((project) => {
+    if (normalizeLinearName(project.name) !== name) {
+      return false;
+    }
+    if (!input.teamId) {
+      return true;
+    }
+    if (project.teamIds.length === 0) {
+      return true;
+    }
+    return project.teamIds.includes(input.teamId);
+  });
+}
+
+export function isWorkflowStatusCoverageComplete(
+  workflowStates: WorkflowStatusPlanEntry[],
+): boolean {
+  return workflowStates.every((entry) => entry.present || !entry.creatable);
+}
+
+export async function previewLinearSetup(
+  input: LinearSetupPlanInput,
+): Promise<LinearSetupPreview> {
+  const capabilities = getLinearSetupCapabilities();
+  const manualSteps: string[] = [];
+  const createActions: LinearSetupPreview["createActions"] = [];
+
+  if (!input.linearApiKey.trim()) {
+    return {
+      actionId: LINEAR_SETUP_ACTIONS.preview.id,
+      capabilities,
+      teams: [],
+      projects: [],
+      workflowStates: [],
+      dispatchTriggerStatuses: getDispatchTriggerStatuses(),
+      missingStatuses: requiredCreatableStatuses()
+        .filter((status) => status.creatable)
+        .map((status) => status.name),
+      createActions: [],
+      manualSteps: ["Add LINEAR_API_KEY in Step 1 before previewing Linear setup."],
+      fingerprint: hashPreview({ invalid: "missing-linear-key" }),
+      permission: LINEAR_SETUP_ACTIONS.preview.permission,
+      validationError: "LINEAR_API_KEY is required for Linear setup preview.",
+    };
+  }
+
+  const client = createLinearSetupClient(input.linearApiKey);
+  const teams = await listLinearTeams(client);
+  const projects = await listLinearProjects(client);
+
+  let selectedTeam: LinearTeamSummary | undefined;
+  if (input.team.mode === "existing") {
+    selectedTeam = teams.find((team) => team.id === input.team.teamId);
+    if (!selectedTeam && input.team.teamId) {
+      return {
+        actionId: LINEAR_SETUP_ACTIONS.preview.id,
+        capabilities,
+        teams,
+        projects,
+        workflowStates: [],
+        dispatchTriggerStatuses: getDispatchTriggerStatuses(),
+        missingStatuses: [],
+        createActions: [],
+        manualSteps: [],
+        fingerprint: hashPreview({ invalid: "team-not-found" }),
+        permission: LINEAR_SETUP_ACTIONS.preview.permission,
+        validationError: "Selected Linear team was not found.",
+      };
+    }
+  } else if (input.team.teamName && input.team.teamKey) {
+    const existingTeam = findExistingTeamForCreateInput(teams, {
+      teamKey: input.team.teamKey,
+      teamName: input.team.teamName,
+    });
+    if (existingTeam) {
+      selectedTeam = existingTeam;
+    } else {
+      createActions.push({
+        kind: "team",
+        name: `${input.team.teamName} (${input.team.teamKey})`,
+      });
+      selectedTeam = {
+        id: "pending-team",
+        key: input.team.teamKey,
+        name: input.team.teamName,
+      };
+    }
+  }
+
+  let selectedProject: LinearProjectSummary | undefined;
+  if (input.project.mode === "existing") {
+    selectedProject = projects.find(
+      (project) => project.id === input.project.projectId,
+    );
+  } else if (input.project.projectName && selectedTeam) {
+    const existingProject = findExistingProjectForCreateInput(projects, {
+      projectName: input.project.projectName,
+      teamId: selectedTeam.id === "pending-team" ? undefined : selectedTeam.id,
+    });
+    if (existingProject) {
+      selectedProject = existingProject;
+    } else {
+      createActions.push({
+        kind: "project",
+        name: input.project.projectName,
+      });
+      selectedProject = {
+        id: "pending-project",
+        name: input.project.projectName,
+        teamIds: selectedTeam.id === "pending-team" ? [] : [selectedTeam.id],
+      };
+    }
+  }
+
+  let workflowStates: WorkflowStatusPlanEntry[] = [];
+  if (selectedTeam && selectedTeam.id !== "pending-team") {
+    const existingStates = await listTeamWorkflowStates(client, selectedTeam.id);
+    workflowStates = matchWorkflowStates(existingStates);
+    for (const entry of workflowStates) {
+      if (entry.action === "create") {
+        createActions.push({ kind: "workflow-state", name: entry.name });
+      }
+      if (entry.action === "manual") {
+        manualSteps.push(
+          `${entry.name} is Linear-managed and must be verified manually in the workspace.`,
+        );
+      }
+      if (
+        entry.present &&
+        entry.existingType &&
+        lookupRequiredStatus(entry.name)?.category !== entry.existingType
+      ) {
+        manualSteps.push(
+          `${entry.name} exists but uses category ${entry.existingType}; harness expects ${lookupRequiredStatus(entry.name)?.category}. Rename manually if needed.`,
+        );
+      }
+    }
+  } else if (selectedTeam) {
+    workflowStates = requiredCreatableStatuses().map((required) => ({
+      name: required.name,
+      category: required.category,
+      role: required.role,
+      present: false,
+      action: required.creatable ? "create" : "manual",
+      creatable: required.creatable,
+    }));
+    for (const entry of workflowStates) {
+      if (entry.action === "create") {
+        createActions.push({ kind: "workflow-state", name: entry.name });
+      }
+    }
+  }
+
+  const missingStatuses = workflowStates
+    .filter((entry) => !entry.present && entry.creatable)
+    .map((entry) => entry.name);
+
+  const fingerprint = hashPreview({
+    actionId: LINEAR_SETUP_ACTIONS.preview.id,
+    team: input.team,
+    project: input.project,
+    workflowStates: workflowStates.map((entry) => ({
+      name: entry.name,
+      action: entry.action,
+    })),
+    linearApiKeyToken: tokenizeSecretInput(input.linearApiKey),
+  });
+
+  return {
+    actionId: LINEAR_SETUP_ACTIONS.preview.id,
+    capabilities,
+    teams,
+    projects,
+    selectedTeam,
+    selectedProject,
+    workflowStates,
+    dispatchTriggerStatuses: getDispatchTriggerStatuses(),
+    missingStatuses,
+    createActions,
+    manualSteps,
+    fingerprint,
+    permission: LINEAR_SETUP_ACTIONS.preview.permission,
+  };
+}
+
+export async function summarizeLinearWebhookReadiness(input: {
+  linearApiKey: string;
+  webhookUrl: string;
+  teamId?: string;
+}): Promise<{
+  webhooks: Awaited<ReturnType<typeof listLinearWebhooks>>;
+  matchingWebhook?: Awaited<ReturnType<typeof listLinearWebhooks>>[number];
+  manualSteps: string[];
+}> {
+  const client = createLinearSetupClient(input.linearApiKey);
+  const webhooks = await listLinearWebhooks(client);
+  const normalizedTarget = input.webhookUrl.trim().replace(/\/$/, "");
+  const matchingWebhook = webhooks.find((webhook) => {
+    const normalized = webhook.url.trim().replace(/\/$/, "");
+    const teamMatches = input.teamId ? webhook.teamId === input.teamId : true;
+    return (
+      teamMatches &&
+      normalized === normalizedTarget &&
+      webhook.enabled &&
+      webhook.resourceTypes.includes("Issue")
+    );
+  });
+
+  const manualSteps: string[] = [];
+  if (!matchingWebhook) {
+    manualSteps.push(
+      `Create a Linear Issue webhook pointing at ${input.webhookUrl}.`,
+    );
+    manualSteps.push(
+      "Copy the webhook signing secret into Vercel production env var LINEAR_WEBHOOK_SECRET.",
+    );
+  }
+
+  return { webhooks, matchingWebhook, manualSteps };
+}

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

@@ -0,0 +1,33 @@
+import { readExistingEnvFile } from "./env-merge.js";
+import { readControlPlaneSetupState } from "./control-plane-setup-state.js";
+import type { ControlPlaneSetupState } from "./control-plane-types.js";
+import { getLinearSetupCapabilities } from "./linear-setup-client.js";
+import { summarizeLinearWorkspaceStatus } from "./control-plane-readiness.js";
+import { getDispatchTriggerStatuses } from "./linear-status-contract.js";
+import { resolveLocalFilePaths } from "./setup-state.js";
+
+export interface LinearSetupSummary {
+  capabilities: ReturnType<typeof getLinearSetupCapabilities>;
+  controlPlane: ControlPlaneSetupState | null;
+  workspace: ReturnType<typeof summarizeLinearWorkspaceStatus>;
+  dispatchTriggerStatuses: readonly string[];
+  linearApiKeyConfigured: boolean;
+}
+
+export async function buildLinearSetupSummary(
+  cwd?: string,
+): Promise<LinearSetupSummary> {
+  const paths = resolveLocalFilePaths(cwd);
+  const existingEnv = await readExistingEnvFile(paths);
+  const controlPlane = await readControlPlaneSetupState(cwd);
+
+  return {
+    capabilities: getLinearSetupCapabilities(),
+    controlPlane,
+    workspace: summarizeLinearWorkspaceStatus({
+      state: controlPlane,
+    }),
+    dispatchTriggerStatuses: getDispatchTriggerStatuses(),
+    linearApiKeyConfigured: Boolean(existingEnv?.presence.LINEAR_API_KEY),
+  };
+}