p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/setup/harness-template-identity.ts

@@ -0,0 +1,151 @@
+/**
+ * Template provenance contract for packaged p-dev harness repo provisioning.
+ *
+ * External prerequisite (operator-owned, not created by automation):
+ * - Public GitHub template repo `weston-uribe/p-dev-harness-template` must exist,
+ *   be marked `is_template: true`, and include `.harness/p-dev-template.json`.
+ * - Real-account validation is blocked until that prerequisite is complete.
+ */
+
+export const HARNESS_TEMPLATE_OWNER = "weston-uribe";
+export const HARNESS_TEMPLATE_REPO = "p-dev-harness-template";
+export const HARNESS_TEMPLATE_SLUG = `${HARNESS_TEMPLATE_OWNER}/${HARNESS_TEMPLATE_REPO}`;
+
+export const HARNESS_DEFAULT_DESTINATION_REPO_NAME = "p-dev-harness";
+export const HARNESS_DEFAULT_DESTINATION_DESCRIPTION =
+  "Private p-dev Product Development Harness workspace";
+
+export const HARNESS_TEMPLATE_IDENTITY_FILE = ".harness/p-dev-template.json";
+export const HARNESS_MANAGED_REPO_MARKER_FILE = ".harness/p-dev-managed-repo.json";
+
+export const HARNESS_TEMPLATE_IDENTITY = "p-dev-harness-template";
+export const HARNESS_PRODUCT = "p-dev";
+export const HARNESS_TEMPLATE_ROLE = "harness-template";
+export const HARNESS_WORKSPACE_ROLE = "harness-workspace";
+
+export const HARNESS_SCHEMA_VERSION = 1;
+export const HARNESS_COMPATIBILITY_VERSION = 1;
+export const HARNESS_MARKER_VERSION = 1;
+
+/** Legacy public source repo — not a valid packaged managed destination. */
+export const HARNESS_LEGACY_PUBLIC_SOURCE_REPO =
+  "weston-uribe/agentic-product-development-harness";
+
+export interface HarnessTemplateIdentity {
+  schemaVersion: number;
+  product: string;
+  role: string;
+  templateIdentity: string;
+  templateVersion: number;
+  compatibilityVersion: number;
+  templateContentId: string;
+  source?: {
+    repository?: string;
+    release?: string;
+    packageVersion?: string;
+  };
+}
+
+export type HarnessTemplateIdentityValidationResult =
+  | { ok: true; identity: HarnessTemplateIdentity }
+  | { ok: false; reason: string };
+
+export function parseHarnessTemplateIdentityJson(
+  raw: string,
+): HarnessTemplateIdentityValidationResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "Template identity JSON is malformed." };
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    return { ok: false, reason: "Template identity JSON is malformed." };
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const schemaVersion = record.schemaVersion;
+  const product = record.product;
+  const role = record.role;
+  const templateIdentity = record.templateIdentity;
+  const templateVersion = record.templateVersion;
+  const compatibilityVersion = record.compatibilityVersion;
+  const templateContentId = record.templateContentId;
+
+  if (schemaVersion !== HARNESS_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reason: `Unsupported template schema version ${String(schemaVersion)}.`,
+    };
+  }
+  if (product !== HARNESS_PRODUCT) {
+    return {
+      ok: false,
+      reason: `Unexpected template product ${String(product)}.`,
+    };
+  }
+  if (role !== HARNESS_TEMPLATE_ROLE) {
+    return {
+      ok: false,
+      reason: `Unexpected template role ${String(role)}.`,
+    };
+  }
+  if (templateIdentity !== HARNESS_TEMPLATE_IDENTITY) {
+    return {
+      ok: false,
+      reason: `Unexpected template identity ${String(templateIdentity)}.`,
+    };
+  }
+  if (templateVersion !== HARNESS_MARKER_VERSION) {
+    return {
+      ok: false,
+      reason: `Unsupported template version ${String(templateVersion)}.`,
+    };
+  }
+  if (compatibilityVersion !== HARNESS_COMPATIBILITY_VERSION) {
+    return {
+      ok: false,
+      reason: `Incompatible template compatibility version ${String(compatibilityVersion)}.`,
+    };
+  }
+  if (typeof templateContentId !== "string" || !templateContentId.trim()) {
+    return {
+      ok: false,
+      reason: "Template identity is missing templateContentId.",
+    };
+  }
+
+  const source =
+    record.source && typeof record.source === "object"
+      ? (record.source as HarnessTemplateIdentity["source"])
+      : undefined;
+
+  return {
+    ok: true,
+    identity: {
+      schemaVersion: HARNESS_SCHEMA_VERSION,
+      product: HARNESS_PRODUCT,
+      role: HARNESS_TEMPLATE_ROLE,
+      templateIdentity: HARNESS_TEMPLATE_IDENTITY,
+      templateVersion: HARNESS_MARKER_VERSION,
+      compatibilityVersion: HARNESS_COMPATIBILITY_VERSION,
+      templateContentId: templateContentId.trim(),
+      source,
+    },
+  };
+}
+
+export function fingerprintHarnessTemplateIdentity(
+  identity: HarnessTemplateIdentity,
+): string {
+  return JSON.stringify({
+    schemaVersion: identity.schemaVersion,
+    product: identity.product,
+    role: identity.role,
+    templateIdentity: identity.templateIdentity,
+    templateVersion: identity.templateVersion,
+    compatibilityVersion: identity.compatibilityVersion,
+    templateContentId: identity.templateContentId,
+  });
+}

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

@@ -0,0 +1,105 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  resolvePackageRootFromModule,
+  resolveWorkspaceSnapshotDirectory,
+} from "../p-dev/package-paths.js";
+import { readPDevPackageVersionFromPackageRoot } from "../p-dev/package-version.js";
+import {
+  fingerprintWorkspaceSnapshotManifest,
+  parseWorkspaceSnapshotManifestJson,
+} from "../p-dev/workspace-snapshot-manifest.js";
+import type { WorkspaceSnapshotManifest } from "../p-dev/workspace-snapshot-types.js";
+import { validateEmbeddedSnapshotFiles } from "../p-dev/workspace-snapshot-validation.js";
+
+export type EmbeddedWorkspaceSnapshotLoadResult =
+  | {
+      ok: true;
+      packageRoot: string;
+      snapshotRoot: string;
+      packageVersion: string;
+      manifest: WorkspaceSnapshotManifest;
+      fingerprint: string;
+    }
+  | { 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,
+): Promise<EmbeddedWorkspaceSnapshotLoadResult> {
+  let packageRoot: string;
+  try {
+    packageRoot = resolvePackageRootFromModule(moduleUrl);
+  } catch (error) {
+    return {
+      ok: false,
+      state: "snapshot-unavailable",
+      message:
+        error instanceof Error
+          ? error.message
+          : "Could not resolve packaged workspace snapshot root.",
+    };
+  }
+
+  const snapshotRoot = resolveWorkspaceSnapshotDirectory(packageRoot);
+  const manifestPath = path.join(snapshotRoot, "manifest.json");
+  let manifestRaw: string;
+  try {
+    manifestRaw = await readFile(manifestPath, "utf8");
+  } catch {
+    return {
+      ok: false,
+      state: "snapshot-manifest-missing",
+      message: "Embedded workspace snapshot manifest is missing from the package.",
+    };
+  }
+
+  const parsed = parseWorkspaceSnapshotManifestJson(manifestRaw);
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      state: "snapshot-manifest-invalid",
+      message: parsed.reason,
+    };
+  }
+
+  let packageVersion: string;
+  try {
+    packageVersion = readPDevPackageVersionFromPackageRoot(packageRoot);
+  } catch (error) {
+    return {
+      ok: false,
+      state: "snapshot-incompatible",
+      message:
+        error instanceof Error ? error.message : "Packaged version metadata is invalid.",
+    };
+  }
+
+  if (parsed.manifest.packageVersion !== packageVersion) {
+    return {
+      ok: false,
+      state: "snapshot-incompatible",
+      message: `Embedded snapshot package version ${parsed.manifest.packageVersion} does not match installed package ${packageVersion}.`,
+    };
+  }
+
+  const embeddedValidation = await validateEmbeddedSnapshotFiles({
+    snapshotRoot,
+    manifest: parsed.manifest,
+  });
+  if (!embeddedValidation.ok) {
+    return {
+      ok: false,
+      state: "snapshot-tampered",
+      message: embeddedValidation.reason,
+    };
+  }
+
+  return {
+    ok: true,
+    packageRoot,
+    snapshotRoot,
+    packageVersion,
+    manifest: parsed.manifest,
+    fingerprint: fingerprintWorkspaceSnapshotManifest(parsed.manifest),
+  };
+}

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

@@ -0,0 +1,270 @@
+import { access, readFile } from "node:fs/promises";
+import type { LinearClient } from "@linear/sdk";
+import { harnessConfigSchema } from "../config/schema.js";
+import {
+  updateControlPlaneSetupState,
+} from "./control-plane-setup-state.js";
+import type { LinearWorkspaceSelection } from "./control-plane-types.js";
+import {
+  createLinearProject,
+  createLinearSetupClient,
+  createLinearTeam,
+  createLinearWorkflowState,
+  isDuplicateWorkflowStateError,
+  listLinearProjects,
+  listLinearTeams,
+  listTeamWorkflowStates,
+  type LinearProjectSummary,
+  type LinearTeamSummary,
+} from "./linear-setup-client.js";
+import { lookupRequiredStatus } from "./linear-status-contract.js";
+import {
+  LINEAR_SETUP_ACTIONS,
+  findExistingProjectForCreateInput,
+  findExistingTeamForCreateInput,
+  isWorkflowStatusCoverageComplete,
+  matchWorkflowStates,
+  normalizeLinearName,
+  previewLinearSetup,
+  type LinearSetupPlanInput,
+  type LinearSetupPreview,
+} from "./linear-setup-plan.js";
+import {
+  assertRemoteSetupConfirmed,
+  assertRemoteSetupFingerprint,
+  assertRemoteSetupPermissionScope,
+} from "./remote-actions.js";
+import { SETUP_PERMISSIONS } from "./permission-model.js";
+import { resolveLocalFilePaths } from "./setup-state.js";
+
+export interface LinearSetupApplyResult {
+  actionId: string;
+  team: LinearTeamSummary;
+  project: LinearProjectSummary;
+  created: string[];
+  skipped: string[];
+  statusCoverageComplete: boolean;
+  verified: boolean;
+  fingerprint: string;
+  permission: typeof SETUP_PERMISSIONS.linearWrite;
+  configUpdated: boolean;
+}
+
+async function updateHarnessConfigLinearMapping(input: {
+  cwd?: string;
+  teamKey: string;
+  projectName: string;
+}): Promise<boolean> {
+  const paths = resolveLocalFilePaths(input.cwd);
+  try {
+    await access(paths.configLocal);
+  } catch {
+    return false;
+  }
+
+  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 { writeConfigLocal } = await import("./config-writer.js");
+  await writeConfigLocal({
+    paths,
+    content: `${JSON.stringify(next, null, 2)}\n`,
+    force: true,
+  });
+  return true;
+}
+
+export async function ensureWorkflowStatesForTeam(input: {
+  client: LinearClient;
+  teamId: string;
+  created: string[];
+  skipped: string[];
+}): Promise<boolean> {
+  const { client, teamId, created, skipped } = input;
+
+  const runEnsurePass = async () => {
+    const existingStates = await listTeamWorkflowStates(client, teamId);
+    const plan = matchWorkflowStates(existingStates);
+
+    for (const entry of plan) {
+      if (entry.action !== "create") {
+        if (entry.present) {
+          skipped.push(`status:${entry.name}`);
+        }
+        continue;
+      }
+
+      const required = lookupRequiredStatus(entry.name);
+      if (!required) {
+        continue;
+      }
+
+      try {
+        await createLinearWorkflowState(client, {
+          teamId,
+          name: entry.name,
+          type: required.category,
+        });
+        created.push(`status:${entry.name}`);
+      } catch (error) {
+        if (!isDuplicateWorkflowStateError(error)) {
+          throw error;
+        }
+        const refreshed = await listTeamWorkflowStates(client, teamId);
+        const reused = refreshed.find(
+          (state) =>
+            normalizeLinearName(state.name) === normalizeLinearName(entry.name),
+        );
+        if (!reused) {
+          throw error;
+        }
+        skipped.push(`status:${entry.name}`);
+      }
+    }
+  };
+
+  await runEnsurePass();
+
+  const finalStates = await listTeamWorkflowStates(client, teamId);
+  return isWorkflowStatusCoverageComplete(matchWorkflowStates(finalStates));
+}
+
+export async function applyLinearSetup(input: {
+  plan: LinearSetupPlanInput;
+  confirmed: boolean;
+  fingerprint: string;
+  cwd?: string;
+}): Promise<LinearSetupApplyResult> {
+  assertRemoteSetupConfirmed(input.confirmed);
+  assertRemoteSetupPermissionScope(
+    LINEAR_SETUP_ACTIONS.apply.permission.scope,
+    SETUP_PERMISSIONS.linearWrite.scope,
+  );
+
+  const preview = await previewLinearSetup(input.plan);
+  assertRemoteSetupFingerprint(input.fingerprint, preview.fingerprint);
+  if (preview.validationError) {
+    throw new Error(preview.validationError);
+  }
+
+  const client = createLinearSetupClient(input.plan.linearApiKey);
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  let team: LinearTeamSummary;
+  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.");
+    }
+    const teams = await listLinearTeams(client);
+    const existingTeam = findExistingTeamForCreateInput(teams, {
+      teamKey: input.plan.team.teamKey,
+      teamName: input.plan.team.teamName,
+    });
+    if (existingTeam) {
+      team = existingTeam;
+      skipped.push(`team:${team.key}`);
+    } else {
+      team = await createLinearTeam(client, {
+        name: input.plan.team.teamName,
+        key: input.plan.team.teamKey,
+      });
+      created.push(`team:${team.key}`);
+    }
+  } else {
+    const existing = preview.selectedTeam;
+    if (!existing) {
+      throw new Error("Selected Linear team is required for apply.");
+    }
+    team = existing;
+    skipped.push(`team:${team.key}`);
+  }
+
+  let project: LinearProjectSummary;
+  if (input.plan.project.mode === "create") {
+    if (!input.plan.project.projectName) {
+      throw new Error("New Linear project requires a name.");
+    }
+    const projects = await listLinearProjects(client);
+    const existingProject = findExistingProjectForCreateInput(projects, {
+      projectName: input.plan.project.projectName,
+      teamId: team.id,
+    });
+    if (existingProject) {
+      project = existingProject;
+      skipped.push(`project:${project.name}`);
+    } else {
+      project = await createLinearProject(client, {
+        name: input.plan.project.projectName,
+        teamIds: [team.id],
+        description: input.plan.project.description,
+      });
+      created.push(`project:${project.name}`);
+    }
+  } else {
+    const existing = preview.selectedProject;
+    if (!existing) {
+      throw new Error("Selected Linear project is required for apply.");
+    }
+    project = existing;
+    skipped.push(`project:${project.name}`);
+  }
+
+  const statusCoverageComplete = await ensureWorkflowStatesForTeam({
+    client,
+    teamId: team.id,
+    created,
+    skipped,
+  });
+
+  const selection: LinearWorkspaceSelection = {
+    teamMode: input.plan.team.mode,
+    teamId: team.id,
+    teamKey: team.key,
+    teamName: team.name,
+    projectMode: input.plan.project.mode,
+    projectId: project.id,
+    projectName: project.name,
+    statusCoverageComplete,
+    appliedFingerprint: preview.fingerprint,
+    appliedAt: new Date().toISOString(),
+  };
+
+  await updateControlPlaneSetupState({ linear: selection }, input.cwd);
+  const configUpdated = await updateHarnessConfigLinearMapping({
+    cwd: input.cwd,
+    teamKey: team.key,
+    projectName: project.name,
+  });
+
+  return {
+    actionId: LINEAR_SETUP_ACTIONS.apply.id,
+    team,
+    project,
+    created,
+    skipped,
+    statusCoverageComplete,
+    verified: Boolean(team.id && project.id && statusCoverageComplete),
+    fingerprint: preview.fingerprint,
+    permission: LINEAR_SETUP_ACTIONS.apply.permission,
+    configUpdated,
+  };
+}
+
+export type { LinearSetupPlanInput, LinearSetupPreview };