p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/src/setup/harness-workspace-snapshot-loader.ts

@@ -1,10 +1,12 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import {
+  resolveInstalledPackageRootFromEnv,
   resolvePackageRootFromModule,
   resolveWorkspaceSnapshotDirectory,
 } from "../p-dev/package-paths.js";
 import { readPDevPackageVersionFromPackageRoot } from "../p-dev/package-version.js";
+import { isPackagedPDevRuntime } from "../p-dev/runtime-mode.js";
 import {
   fingerprintWorkspaceSnapshotManifest,
   parseWorkspaceSnapshotManifestJson,
@@ -23,12 +25,26 @@ export type EmbeddedWorkspaceSnapshotLoadResult =
     }
   | { ok: false; state: "snapshot-unavailable" | "snapshot-manifest-missing" | "snapshot-manifest-invalid" | "snapshot-incompatible" | "snapshot-tampered"; message: string };
 
-export async function loadEmbeddedWorkspaceSnapshot(
-  moduleUrl: string = import.meta.url,
+async function loadEmbeddedWorkspaceSnapshotIdentity(
+  moduleUrl: string,
+  env: NodeJS.ProcessEnv,
+  signal?: AbortSignal,
 ): Promise<EmbeddedWorkspaceSnapshotLoadResult> {
+  if (signal?.aborted) {
+    return {
+      ok: false,
+      state: "snapshot-unavailable",
+      message: "Embedded workspace snapshot load was aborted.",
+    };
+  }
+
   let packageRoot: string;
   try {
-    packageRoot = resolvePackageRootFromModule(moduleUrl);
+    // Packaged Next bundles retain synthetic source-style import.meta.url values.
+    // Resolve exclusively from the launcher-validated install root.
+    packageRoot = isPackagedPDevRuntime(env)
+      ? resolveInstalledPackageRootFromEnv(env)
+      : resolvePackageRootFromModule(moduleUrl);
   } catch (error) {
     return {
       ok: false,
@@ -44,6 +60,13 @@ export async function loadEmbeddedWorkspaceSnapshot(
   const manifestPath = path.join(snapshotRoot, "manifest.json");
   let manifestRaw: string;
   try {
+    if (signal?.aborted) {
+      return {
+        ok: false,
+        state: "snapshot-unavailable",
+        message: "Embedded workspace snapshot load was aborted.",
+      };
+    }
     manifestRaw = await readFile(manifestPath, "utf8");
   } catch {
     return {
@@ -82,9 +105,40 @@ export async function loadEmbeddedWorkspaceSnapshot(
     };
   }
 
-  const embeddedValidation = await validateEmbeddedSnapshotFiles({
+  return {
+    ok: true,
+    packageRoot,
     snapshotRoot,
+    packageVersion,
     manifest: parsed.manifest,
+    fingerprint: fingerprintWorkspaceSnapshotManifest(parsed.manifest),
+  };
+}
+
+/**
+ * Status-path identity load: manifest + package version only.
+ * Does not re-hash every embedded snapshot file.
+ */
+export async function loadEmbeddedWorkspaceSnapshotIdentityForStatus(
+  moduleUrl: string = import.meta.url,
+  env: NodeJS.ProcessEnv = process.env,
+  signal?: AbortSignal,
+): Promise<EmbeddedWorkspaceSnapshotLoadResult> {
+  return loadEmbeddedWorkspaceSnapshotIdentity(moduleUrl, env, signal);
+}
+
+export async function loadEmbeddedWorkspaceSnapshot(
+  moduleUrl: string = import.meta.url,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<EmbeddedWorkspaceSnapshotLoadResult> {
+  const identity = await loadEmbeddedWorkspaceSnapshotIdentity(moduleUrl, env);
+  if (!identity.ok) {
+    return identity;
+  }
+
+  const embeddedValidation = await validateEmbeddedSnapshotFiles({
+    snapshotRoot: identity.snapshotRoot,
+    manifest: identity.manifest,
   });
   if (!embeddedValidation.ok) {
     return {
@@ -94,12 +148,5 @@ export async function loadEmbeddedWorkspaceSnapshot(
     };
   }
 
-  return {
-    ok: true,
-    packageRoot,
-    snapshotRoot,
-    packageVersion,
-    manifest: parsed.manifest,
-    fingerprint: fingerprintWorkspaceSnapshotManifest(parsed.manifest),
-  };
+  return identity;
 }

package/workspace-snapshot/files/src/setup/initial-setup-lifecycle.ts

@@ -0,0 +1,181 @@
+import { access } from "node:fs/promises";
+import type { ControlPlaneSetupState } from "./control-plane-types.js";
+import {
+  readControlPlaneSetupState,
+  updateControlPlaneSetupState,
+} from "./control-plane-setup-state.js";
+import type { RemoteSetupSummary } from "./remote-setup-summary.js";
+import type { SetupGuiViewModel } from "./gui-view-model.js";
+import { resolveLocalFilePaths } from "./setup-state.js";
+import { HARNESS_ACTIONS_SECRET_NAMES } from "./remote-actions.js";
+
+export type InitialSetupCompletionEvidence = {
+  localConfigPresent: boolean;
+  linearConfigured: boolean;
+  vercelConfigured: boolean;
+  cloudSecretsVerified: boolean;
+  targetWorkflowsVerified: boolean;
+};
+
+export function isInitialSetupComplete(
+  state: ControlPlaneSetupState | null | undefined,
+): boolean {
+  return state?.initialSetup?.status === "complete";
+}
+
+export function assessCompletionEvidence(input: {
+  setupSummary: SetupGuiViewModel;
+  remoteSummary: RemoteSetupSummary;
+  controlPlane: ControlPlaneSetupState | null;
+}): InitialSetupCompletionEvidence {
+  const { setupSummary, remoteSummary, controlPlane } = input;
+
+  const localConfigPresent =
+    setupSummary.overview.configResolved &&
+    setupSummary.overview.localFilesPresent &&
+    setupSummary.overview.readyForLocalDoctor;
+
+  const linearConfigured = Boolean(
+    controlPlane?.linearWorkspace?.teams.some(
+      (team) => team.projects.length > 0,
+    ) ||
+      (controlPlane?.linear?.teamId?.trim() &&
+        controlPlane.linear.teamKey?.trim()),
+  );
+
+  const vercelConfigured = Boolean(controlPlane?.vercel?.projectId?.trim());
+
+  const cloudSecretsVerified =
+    remoteSummary.harnessSecretStatuses.length > 0 &&
+    HARNESS_ACTIONS_SECRET_NAMES.every((name) =>
+      remoteSummary.harnessSecretStatuses.some(
+        (entry) => entry.name === name && entry.status === "present",
+      ),
+    );
+
+  const targetWorkflowsVerified =
+    remoteSummary.targetRepos.length > 0 &&
+    remoteSummary.targetRepos.every(
+      (repo) => repo.workflowStatus === "present",
+    );
+
+  return {
+    localConfigPresent,
+    linearConfigured,
+    vercelConfigured,
+    cloudSecretsVerified,
+    targetWorkflowsVerified,
+  };
+}
+
+export function isCompletionEvidenceSatisfied(
+  evidence: InitialSetupCompletionEvidence,
+): evidence is {
+  localConfigPresent: true;
+  linearConfigured: true;
+  vercelConfigured: true;
+  cloudSecretsVerified: true;
+  targetWorkflowsVerified: true;
+} {
+  return (
+    evidence.localConfigPresent &&
+    evidence.linearConfigured &&
+    evidence.vercelConfigured &&
+    evidence.cloudSecretsVerified &&
+    evidence.targetWorkflowsVerified
+  );
+}
+
+export async function writeInitialSetupComplete(
+  cwd: string | undefined,
+  evidence: {
+    localConfigPresent: true;
+    linearConfigured: true;
+    vercelConfigured: true;
+    cloudSecretsVerified: true;
+    targetWorkflowsVerified: true;
+  },
+  completedByVersion?: string,
+): Promise<ControlPlaneSetupState> {
+  return updateControlPlaneSetupState(
+    {
+      initialSetup: {
+        status: "complete",
+        completedAt: new Date().toISOString(),
+        completedByVersion,
+        completionEvidence: evidence,
+      },
+    },
+    cwd,
+  );
+}
+
+export async function migrateExistingCompletedWorkspace(input: {
+  cwd?: string;
+  setupSummary: SetupGuiViewModel;
+  remoteSummary: RemoteSetupSummary;
+}): Promise<ControlPlaneSetupState | null> {
+  const cwd = input.cwd;
+  const existing = await readControlPlaneSetupState(cwd);
+  if (isInitialSetupComplete(existing)) {
+    return existing;
+  }
+
+  const evidence = assessCompletionEvidence({
+    setupSummary: input.setupSummary,
+    remoteSummary: input.remoteSummary,
+    controlPlane: existing,
+  });
+
+  if (!isCompletionEvidenceSatisfied(evidence)) {
+    return existing;
+  }
+
+  return writeInitialSetupComplete(cwd, evidence, "v0.4-configure-migration");
+}
+
+export async function completeInitialSetupFromServer(input: {
+  cwd?: string;
+  setupSummary: SetupGuiViewModel;
+  remoteSummary: RemoteSetupSummary;
+}): Promise<
+  | { ok: true; state: ControlPlaneSetupState }
+  | { ok: false; evidence: InitialSetupCompletionEvidence }
+> {
+  const cwd = input.cwd;
+  const controlPlane = await readControlPlaneSetupState(cwd);
+  if (isInitialSetupComplete(controlPlane)) {
+    return { ok: true, state: controlPlane! };
+  }
+
+  const evidence = assessCompletionEvidence({
+    setupSummary: input.setupSummary,
+    remoteSummary: input.remoteSummary,
+    controlPlane,
+  });
+
+  if (!isCompletionEvidenceSatisfied(evidence)) {
+    return { ok: false, evidence };
+  }
+
+  const state = await writeInitialSetupComplete(cwd, evidence);
+  return { ok: true, state };
+}
+
+export async function readInitialSetupRoutingState(cwd?: string): Promise<{
+  complete: boolean;
+  state: ControlPlaneSetupState | null;
+}> {
+  const paths = resolveLocalFilePaths(cwd);
+  try {
+    await access(paths.harnessDir);
+  } catch {
+    return { complete: false, state: null };
+  }
+
+  const state = await readControlPlaneSetupState(cwd);
+  return {
+    complete: isInitialSetupComplete(state),
+    state,
+  };
+}

package/workspace-snapshot/files/src/setup/linear-category-labels.ts

@@ -0,0 +1,18 @@
+export function formatLinearCategoryLabel(category: string): string {
+  switch (category) {
+    case "unstarted":
+      return "Unstarted";
+    case "started":
+      return "Started";
+    case "backlog":
+      return "Backlog";
+    case "completed":
+      return "Completed";
+    case "canceled":
+      return "Canceled";
+    case "duplicate":
+      return "Duplicate";
+    default:
+      return category;
+  }
+}

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

@@ -20,6 +20,7 @@ import {
 import { lookupRequiredStatus } from "./linear-status-contract.js";
 import {
   LINEAR_SETUP_ACTIONS,
+  buildNewProductProjectDescription,
   findExistingProjectForCreateInput,
   findExistingTeamForCreateInput,
   isWorkflowStatusCoverageComplete,
@@ -29,6 +30,11 @@ import {
   type LinearSetupPlanInput,
   type LinearSetupPreview,
 } from "./linear-setup-plan.js";
+import {
+  writeLinearSetupProgress,
+  type LinearSetupProgressPhase,
+} from "./linear-setup-progress.js";
+import { executeWorkflowStatusRepairs } from "./linear-workflow-status-repair.js";
 import {
   assertRemoteSetupConfirmed,
   assertRemoteSetupFingerprint,
@@ -43,6 +49,7 @@ export interface LinearSetupApplyResult {
   project: LinearProjectSummary;
   created: string[];
   skipped: string[];
+  repaired: string[];
   statusCoverageComplete: boolean;
   verified: boolean;
   fingerprint: string;
@@ -52,8 +59,14 @@ export interface LinearSetupApplyResult {
 
 async function updateHarnessConfigLinearMapping(input: {
   cwd?: string;
+  workspaceId?: string;
+  teamId: string;
   teamKey: string;
+  teamName: string;
+  projectId: string;
   projectName: string;
+  targetRepo?: string;
+  repoConfigId?: string;
 }): Promise<boolean> {
   const paths = resolveLocalFilePaths(input.cwd);
   try {
@@ -64,21 +77,39 @@ async function updateHarnessConfigLinearMapping(input: {
 
   const raw = await readFile(paths.configLocal, "utf8");
   const parsed = harnessConfigSchema.parse(JSON.parse(raw));
-  const next = harnessConfigSchema.parse({
-    ...parsed,
-    linear: {
-      ...parsed.linear,
-      teamKey: input.teamKey,
-    },
-    repos: parsed.repos.map((repo, index) =>
-      index === 0
-        ? {
-            ...repo,
-            linearProjects: [input.projectName],
-            linearTeams: [input.teamKey],
-          }
-        : repo,
-    ),
+  const targetRepo =
+    input.targetRepo ??
+    parsed.repos[0]?.targetRepo;
+  const repoConfigId =
+    input.repoConfigId ??
+    parsed.repos.find((repo) => repo.targetRepo === targetRepo)?.id ??
+    parsed.repos[0]?.id;
+
+  if (!targetRepo || !repoConfigId) {
+    return false;
+  }
+
+  const workspaceId =
+    input.workspaceId?.trim() ||
+    parsed.linear?.workspaceId?.trim() ||
+    "unknown-workspace";
+
+  const { buildRequestedHarnessConfig } = await import("./linear-workspace-plan.js");
+  const next = buildRequestedHarnessConfig({
+    current: parsed,
+    workspaceId,
+    requestedAssociations: [
+      {
+        workspaceId,
+        teamId: input.teamId,
+        teamKey: input.teamKey,
+        teamName: input.teamName,
+        projectId: input.projectId,
+        projectName: input.projectName,
+        targetRepo,
+        repoConfigId,
+      },
+    ],
   });
 
   const { writeConfigLocal } = await import("./config-writer.js");
@@ -151,12 +182,28 @@ export async function applyLinearSetup(input: {
   fingerprint: string;
   cwd?: string;
 }): Promise<LinearSetupApplyResult> {
+  const progressStartedAt = new Date().toISOString();
+  const writeProgress = (
+    phase: LinearSetupProgressPhase,
+    completed = false,
+  ) =>
+    writeLinearSetupProgress(
+      {
+        actionId: LINEAR_SETUP_ACTIONS.apply.id,
+        phase,
+        startedAt: progressStartedAt,
+        completed,
+      },
+      input.cwd,
+    );
+
   assertRemoteSetupConfirmed(input.confirmed);
   assertRemoteSetupPermissionScope(
     LINEAR_SETUP_ACTIONS.apply.permission.scope,
     SETUP_PERMISSIONS.linearWrite.scope,
   );
 
+  await writeProgress("validate");
   const preview = await previewLinearSetup(input.plan);
   assertRemoteSetupFingerprint(input.fingerprint, preview.fingerprint);
   if (preview.validationError) {
@@ -166,8 +213,10 @@ export async function applyLinearSetup(input: {
   const client = createLinearSetupClient(input.plan.linearApiKey);
   const created: string[] = [];
   const skipped: string[] = [];
+  const repaired: string[] = [];
 
   let team: LinearTeamSummary;
+  await writeProgress("team");
   if (input.plan.team.mode === "create") {
     if (!input.plan.team.teamName || !input.plan.team.teamKey) {
       throw new Error("New Linear team requires name and key.");
@@ -197,6 +246,7 @@ export async function applyLinearSetup(input: {
   }
 
   let project: LinearProjectSummary;
+  await writeProgress("project");
   if (input.plan.project.mode === "create") {
     if (!input.plan.project.projectName) {
       throw new Error("New Linear project requires a name.");
@@ -210,10 +260,17 @@ export async function applyLinearSetup(input: {
       project = existingProject;
       skipped.push(`project:${project.name}`);
     } else {
+      const description =
+        input.plan.project.targetRepo
+          ? buildNewProductProjectDescription({
+              baseDescription: input.plan.project.description,
+              targetRepo: input.plan.project.targetRepo,
+            })
+          : input.plan.project.description;
       project = await createLinearProject(client, {
         name: input.plan.project.projectName,
         teamIds: [team.id],
-        description: input.plan.project.description,
+        description,
       });
       created.push(`project:${project.name}`);
     }
@@ -226,13 +283,31 @@ export async function applyLinearSetup(input: {
     skipped.push(`project:${project.name}`);
   }
 
-  const statusCoverageComplete = await ensureWorkflowStatesForTeam({
+  await writeProgress("statuses");
+  let statusCoverageComplete = await ensureWorkflowStatesForTeam({
     client,
     teamId: team.id,
     created,
     skipped,
   });
 
+  const repairEntries = preview.workflowStates.filter(
+    (entry) => entry.action === "repair",
+  );
+  if (repairEntries.length > 0) {
+    const repairResults = await executeWorkflowStatusRepairs({
+      client,
+      teamId: team.id,
+      entries: repairEntries,
+    });
+    repaired.push(...repairResults);
+    const finalStates = await listTeamWorkflowStates(client, team.id);
+    statusCoverageComplete = isWorkflowStatusCoverageComplete(
+      matchWorkflowStates(finalStates),
+    );
+  }
+
+  await writeProgress("verify");
   const selection: LinearWorkspaceSelection = {
     teamMode: input.plan.team.mode,
     teamId: team.id,
@@ -249,9 +324,13 @@ export async function applyLinearSetup(input: {
   await updateControlPlaneSetupState({ linear: selection }, input.cwd);
   const configUpdated = await updateHarnessConfigLinearMapping({
     cwd: input.cwd,
+    teamId: team.id,
     teamKey: team.key,
+    teamName: team.name,
+    projectId: project.id,
     projectName: project.name,
   });
+  await writeProgress("verify", true);
 
   return {
     actionId: LINEAR_SETUP_ACTIONS.apply.id,
@@ -259,6 +338,7 @@ export async function applyLinearSetup(input: {
     project,
     created,
     skipped,
+    repaired,
     statusCoverageComplete,
     verified: Boolean(team.id && project.id && statusCoverageComplete),
     fingerprint: preview.fingerprint,

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

@@ -11,6 +11,7 @@ export interface LinearTeamSummary {
 export interface LinearProjectSummary {
   id: string;
   name: string;
+  description?: string | null;
   /** Team IDs from `project.teams()` — not on the default Project list fragment. */
   teamIds: string[];
 }
@@ -87,11 +88,40 @@ export async function listLinearProjects(
     projects.map(async (project) => ({
       id: project.id,
       name: project.name ?? "",
+      description: project.description ?? null,
       teamIds: await resolveProjectTeamIds(project),
     })),
   );
 }
 
+export async function getLinearProject(
+  client: LinearClient,
+  projectId: string,
+): Promise<LinearProjectSummary | null> {
+  try {
+    const project = await client.project(projectId);
+    if (!project) {
+      return null;
+    }
+    return {
+      id: project.id,
+      name: project.name ?? "",
+      description: project.description ?? null,
+      teamIds: await resolveProjectTeamIds(project),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function updateLinearProjectDescription(
+  client: LinearClient,
+  projectId: string,
+  description: string,
+): Promise<void> {
+  await client.updateProject(projectId, { description });
+}
+
 export async function listTeamWorkflowStates(
   client: LinearClient,
   teamId: string,
@@ -198,6 +228,62 @@ export function isDuplicateWorkflowStateError(error: unknown): boolean {
   return /duplicate workflow state/i.test(message);
 }
 
+export async function updateLinearWorkflowState(
+  client: LinearClient,
+  input: {
+    id: string;
+    name?: string;
+    color?: string;
+    description?: string;
+    position?: number;
+  },
+): Promise<LinearWorkflowStateSummary> {
+  const payload = await client.updateWorkflowState(input.id, {
+    name: input.name,
+    color: input.color,
+    description: input.description,
+    position: input.position,
+  });
+  const state = await payload.workflowState;
+  if (!state) {
+    throw new Error("Linear workflow state update did not return a state");
+  }
+  return {
+    id: state.id,
+    name: state.name ?? input.name ?? "",
+    type: state.type ?? "",
+  };
+}
+
+export async function listIssueIdsForWorkflowState(input: {
+  client: LinearClient;
+  teamId: string;
+  stateId: string;
+}): Promise<string[]> {
+  const connection = await input.client.issues({
+    filter: {
+      team: { id: { eq: input.teamId } },
+      state: { id: { eq: input.stateId } },
+    },
+  });
+  const issues = await paginateConnection(connection);
+  return issues.map((issue) => issue.id);
+}
+
+export async function updateLinearIssueState(
+  client: LinearClient,
+  input: { issueId: string; stateId: string },
+): Promise<void> {
+  await client.updateIssue(input.issueId, { stateId: input.stateId });
+}
+
+export async function archiveLinearWorkflowState(
+  client: LinearClient,
+  stateId: string,
+): Promise<void> {
+  await client.archiveWorkflowState(stateId);
+}
+
 export async function createLinearIssueWebhook(
   client: LinearClient,
   input: { url: string; teamId?: string; label?: string; secret?: string },
@@ -265,6 +351,16 @@ export async function deleteLinearWebhook(
   await client.deleteWebhook(webhookId);
 }
 
+export async function getLinearOrganizationSummary(
+  client: LinearClient,
+): Promise<{ id: string; name: string }> {
+  const organization = await client.organization;
+  return {
+    id: organization.id,
+    name: organization.name?.trim() || "Linear workspace",
+  };
+}
+
 export function getLinearSetupCapabilities(): LinearSetupCapabilities {
   return {
     teamCreate: true,