p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/p-dev/launch.ts

@@ -0,0 +1,173 @@
+import { spawn } from "node:child_process";
+import type { BrowserOpener } from "./browser.js";
+import { defaultBrowserOpener } from "./browser.js";
+import type { PDevCliOptions } from "./cli.js";
+import { parsePDevCliOptions } from "./cli.js";
+import { assertNodeVersion } from "./node-version.js";
+import {
+  resolveGuiDirectory,
+  resolvePackageRootFromModule,
+  resolveTemplatesDirectory,
+} from "./package-paths.js";
+import { createShutdownController } from "./shutdown.js";
+import { resolveNextBin } from "./next-bin.js";
+import {
+  checkConfigurePageHealth,
+  waitForConfigureServer,
+} from "../gui/configure-health.js";
+import { resolveAvailableGuiPort } from "../gui/port.js";
+import {
+  P_DEV_PACKAGE_VERSION_ENV,
+  readPDevPackageVersionFromPackageRoot,
+} from "./package-version.js";
+import {
+  isPathInsidePackageInstall,
+  P_DEV_HOME_ENV,
+  resolveWorkspaceDir,
+  seedWorkspaceTemplates,
+} from "./workspace.js";
+
+export const STARTUP_TIMEOUT_MS = 90_000;
+
+export interface LaunchPDevOptions {
+  argv?: string[];
+  moduleUrl: string;
+  browserOpener?: BrowserOpener;
+  spawnImpl?: typeof spawn;
+}
+
+export interface LaunchPDevResult {
+  url: string;
+  workspaceDir: string;
+  packageRoot: string;
+  port: number;
+  host: string;
+}
+
+function buildConfigureUrl(host: string, port: number, route: string): string {
+  const normalizedRoute = route.startsWith("/") ? route : `/${route}`;
+  return `http://${host}:${port}${normalizedRoute}`;
+}
+
+export async function launchPDev(
+  options: LaunchPDevOptions,
+): Promise<LaunchPDevResult> {
+  assertNodeVersion();
+
+  const cli = parsePDevCliOptions(options.argv ?? process.argv.slice(2));
+  const packageRoot = resolvePackageRootFromModule(options.moduleUrl);
+  const guiDir = resolveGuiDirectory(packageRoot);
+  const templatesDir = resolveTemplatesDirectory(packageRoot);
+
+  const workspace = resolveWorkspaceDir({
+    cliWorkspace: cli.workspace,
+    envWorkspace: process.env[P_DEV_HOME_ENV],
+  });
+
+  if (isPathInsidePackageInstall(workspace.workspaceDir, packageRoot)) {
+    throw new Error(
+      `Refusing to use package install directory as workspace (${workspace.workspaceDir}). Set ${P_DEV_HOME_ENV} or pass --workspace to a writable directory outside the installed package.`,
+    );
+  }
+
+  await seedWorkspaceTemplates({
+    workspaceDir: workspace.workspaceDir,
+    templatesDir,
+  });
+
+  const { host, port, requestedPort } = await resolveAvailableGuiPort({
+    host: cli.host,
+    port: cli.port,
+  });
+
+  const url = buildConfigureUrl(host, port, cli.route);
+  const nextBin = resolveNextBin(packageRoot);
+  const packagedVersion = readPDevPackageVersionFromPackageRoot(packageRoot);
+
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const shutdown = createShutdownController();
+
+  if (port !== requestedPort) {
+    console.warn(
+      `Port ${requestedPort} was busy. Using ${port} instead. Configure URL: ${url}`,
+    );
+  }
+
+  console.log(`Starting Product Development Harness Configure GUI at ${url}`);
+  console.log(`Operator workspace: ${workspace.workspaceDir}`);
+
+  const child = spawnImpl(
+    process.execPath,
+    [nextBin, "start", "--hostname", host, "--port", String(port)],
+    {
+      cwd: guiDir,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        [P_DEV_HOME_ENV]: workspace.workspaceDir,
+        HARNESS_REPO_ROOT: workspace.workspaceDir,
+        P_DEV_RUNTIME_MODE: "packaged",
+        [P_DEV_PACKAGE_VERSION_ENV]: packagedVersion,
+        HARNESS_GUI_HOST: host,
+        HARNESS_GUI_PORT: String(port),
+      },
+    },
+  );
+
+  shutdown.register(child);
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+
+  child.on("error", (error) => {
+    console.error(`p-dev failed to start Configure GUI: ${error.message}`);
+    process.exit(1);
+  });
+
+  const baseUrl = `http://${host}:${port}`;
+  await waitForConfigureServer(baseUrl, STARTUP_TIMEOUT_MS);
+  const health = await checkConfigurePageHealth(url);
+  if (!health.ok) {
+    await shutdown.cleanup();
+    throw new Error(
+      health.reason ?? "Configure GUI health check failed after startup.",
+    );
+  }
+
+  console.log(`Configure GUI is ready at ${url}`);
+
+  if (cli.openBrowser) {
+    const browserOpener = options.browserOpener ?? defaultBrowserOpener;
+    await browserOpener.open(url);
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`Configure GUI exited from signal ${signal}`));
+        return;
+      }
+      if (code && code !== 0) {
+        reject(new Error(`Configure GUI exited with code ${code}`));
+        return;
+      }
+      resolve();
+    });
+  });
+
+  return {
+    url,
+    workspaceDir: workspace.workspaceDir,
+    packageRoot,
+    port,
+    host,
+  };
+}
+
+export type { PDevCliOptions };

package/workspace-snapshot/files/src/p-dev/main.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { launchPDev } from "./launch.js";
+
+await launchPDev({
+  moduleUrl: import.meta.url,
+}).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`p-dev failed: ${message}`);
+  process.exit(1);
+});

package/workspace-snapshot/files/src/p-dev/next-bin.ts

@@ -0,0 +1,8 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+export function resolveNextBin(packageRoot: string): string {
+  const requireFromPackage = createRequire(path.join(packageRoot, "package.json"));
+  const nextPackageJson = requireFromPackage.resolve("next/package.json");
+  return path.join(path.dirname(nextPackageJson), "dist", "bin", "next");
+}

package/workspace-snapshot/files/src/p-dev/node-version.ts

@@ -0,0 +1,46 @@
+export const MIN_NODE_MAJOR = 22;
+
+export interface NodeVersionCheckResult {
+  ok: boolean;
+  message?: string;
+}
+
+export function parseNodeMajor(version: string): number {
+  const match = /^v?(\d+)/.exec(version.trim());
+  if (!match?.[1]) {
+    return Number.NaN;
+  }
+  return Number.parseInt(match[1], 10);
+}
+
+export function checkNodeVersion(
+  version = process.version,
+  minMajor = MIN_NODE_MAJOR,
+): NodeVersionCheckResult {
+  const major = parseNodeMajor(version);
+  if (!Number.isFinite(major)) {
+    return {
+      ok: false,
+      message: `Could not parse Node.js version from "${version}".`,
+    };
+  }
+
+  if (major < minMajor) {
+    return {
+      ok: false,
+      message: `p-dev requires Node.js ${minMajor}+. The active version is ${version}. Install a supported Node release and retry.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+export function assertNodeVersion(
+  version = process.version,
+  minMajor = MIN_NODE_MAJOR,
+): void {
+  const result = checkNodeVersion(version, minMajor);
+  if (!result.ok) {
+    throw new Error(result.message);
+  }
+}

package/workspace-snapshot/files/src/p-dev/package-paths.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const P_DEV_PACKAGE_NAME = "p-dev-harness";
+
+export function resolvePackageRootFromModule(moduleUrl: string): string {
+  let current = path.resolve(path.dirname(fileURLToPath(moduleUrl)));
+
+  while (true) {
+    const packageJsonPath = path.join(current, "package.json");
+    if (existsSync(packageJsonPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+          name?: string;
+        };
+        if (parsed.name === P_DEV_PACKAGE_NAME) {
+          return current;
+        }
+      } catch {
+        // keep walking
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  throw new Error(
+    `Could not resolve ${P_DEV_PACKAGE_NAME} package root from ${moduleUrl}.`,
+  );
+}
+
+export function resolveGuiDirectory(packageRoot: string): string {
+  return path.join(packageRoot, "gui");
+}
+
+export function resolveTemplatesDirectory(packageRoot: string): string {
+  return path.join(packageRoot, "templates");
+}
+
+export function resolveWorkspaceSnapshotDirectory(packageRoot: string): string {
+  return path.join(packageRoot, "workspace-snapshot");
+}

package/workspace-snapshot/files/src/p-dev/package-version.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isPackagedPDevRuntime } from "./runtime-mode.js";
+
+export const P_DEV_PACKAGE_VERSION_ENV = "P_DEV_PACKAGE_VERSION";
+
+const PACKAGE_JSON_RELATIVE = "../../package.json";
+const SEMVER_LIKE_PATTERN = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+
+export function readHarnessPackageVersion(
+  moduleUrl = import.meta.url,
+): string {
+  const packageJsonPath = path.resolve(
+    path.dirname(fileURLToPath(moduleUrl)),
+    PACKAGE_JSON_RELATIVE,
+  );
+  const raw = readFileSync(packageJsonPath, "utf8");
+  const parsed = JSON.parse(raw) as { version?: string };
+  return parsed.version?.trim() || "0.0.0";
+}
+
+export function readPDevPackageVersionFromPackageRoot(
+  packageRoot: string,
+): string {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  const raw = readFileSync(packageJsonPath, "utf8");
+  const parsed = JSON.parse(raw) as { version?: string };
+  const version = parsed.version?.trim();
+  if (!version || !SEMVER_LIKE_PATTERN.test(version)) {
+    throw new Error(
+      `Installed p-dev package is missing a valid version in ${packageJsonPath}.`,
+    );
+  }
+  return version;
+}
+
+export function validatePackagedRuntimeVersionValue(
+  raw: string | undefined,
+): string {
+  const version = raw?.trim();
+  if (!version) {
+    throw new Error(
+      `${P_DEV_PACKAGE_VERSION_ENV} is required in packaged p-dev runtime.`,
+    );
+  }
+  if (!SEMVER_LIKE_PATTERN.test(version)) {
+    throw new Error(
+      `${P_DEV_PACKAGE_VERSION_ENV} must be a valid package version string.`,
+    );
+  }
+  return version;
+}
+
+export function resolveHarnessPackageVersion(
+  env: NodeJS.ProcessEnv = process.env,
+  moduleUrl = import.meta.url,
+): string {
+  if (isPackagedPDevRuntime(env)) {
+    return validatePackagedRuntimeVersionValue(env[P_DEV_PACKAGE_VERSION_ENV]);
+  }
+  return readHarnessPackageVersion(moduleUrl);
+}

package/workspace-snapshot/files/src/p-dev/runtime-mode.ts

@@ -0,0 +1,28 @@
+export const P_DEV_RUNTIME_MODE_ENV = "P_DEV_RUNTIME_MODE";
+
+export type PDevRuntimeMode = "packaged" | "source";
+
+export function resolvePDevRuntimeMode(
+  env: NodeJS.ProcessEnv = process.env,
+): PDevRuntimeMode | null {
+  const raw = env[P_DEV_RUNTIME_MODE_ENV]?.trim().toLowerCase();
+  if (raw === "packaged") {
+    return "packaged";
+  }
+  if (raw === "source" || raw === "development") {
+    return "source";
+  }
+  return null;
+}
+
+export function isPackagedPDevRuntime(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return resolvePDevRuntimeMode(env) === "packaged";
+}
+
+export function isSourcePDevRuntime(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return resolvePDevRuntimeMode(env) === "source";
+}

package/workspace-snapshot/files/src/p-dev/shutdown.ts

@@ -0,0 +1,66 @@
+import type { ChildProcess } from "node:child_process";
+
+export interface ShutdownController {
+  register(child: ChildProcess): void;
+  cleanup(): Promise<void>;
+}
+
+export function createShutdownController(): ShutdownController {
+  let child: ChildProcess | undefined;
+  let shuttingDown = false;
+
+  const handleSignal = (signal: NodeJS.Signals) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+
+    if (child?.pid !== undefined) {
+      try {
+        child.kill(signal);
+      } catch {
+        // Child may already be gone.
+      }
+    }
+  };
+
+  process.once("SIGINT", handleSignal);
+  process.once("SIGTERM", handleSignal);
+
+  return {
+    register(nextChild: ChildProcess): void {
+      child = nextChild;
+    },
+    async cleanup(): Promise<void> {
+      if (child?.pid === undefined) {
+        return;
+      }
+
+      await new Promise<void>((resolve) => {
+        if (child?.killed || child?.exitCode !== null) {
+          resolve();
+          return;
+        }
+
+        child?.once("exit", () => {
+          resolve();
+        });
+
+        try {
+          child?.kill("SIGTERM");
+        } catch {
+          resolve();
+        }
+
+        setTimeout(() => {
+          try {
+            child?.kill("SIGKILL");
+          } catch {
+            // ignore
+          }
+          resolve();
+        }, 2_000).unref();
+      });
+    },
+  };
+}

package/workspace-snapshot/files/src/p-dev/workspace-snapshot-digest.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import type { WorkspaceSnapshotManifestFile } from "./workspace-snapshot-types.js";
+import {
+  compareUtf8Paths,
+  computeSnapshotRootTreeSha1,
+} from "./git-object-plumbing.js";
+
+export { computeSnapshotRootTreeSha1 };
+
+export function computeSnapshotFileSha256(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function sortSnapshotManifestFiles(
+  files: WorkspaceSnapshotManifestFile[],
+): WorkspaceSnapshotManifestFile[] {
+  return [...files].sort((left, right) => compareUtf8Paths(left.path, right.path));
+}
+
+export function computeSnapshotSha256(
+  files: WorkspaceSnapshotManifestFile[],
+): string {
+  const sorted = sortSnapshotManifestFiles(files);
+  const hash = createHash("sha256");
+  for (const file of sorted) {
+    hash.update(file.path);
+    hash.update("\0");
+    hash.update(file.mode);
+    hash.update("\0");
+    hash.update(String(file.size));
+    hash.update("\0");
+    hash.update(file.sha256);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+
+export function computeSnapshotContentId(input: {
+  packageVersion: string;
+  sourceCommit: string;
+  snapshotSha256: string;
+}): string {
+  return createHash("sha256")
+    .update(input.packageVersion)
+    .update("\0")
+    .update(input.sourceCommit)
+    .update("\0")
+    .update(input.snapshotSha256)
+    .digest("hex");
+}

package/workspace-snapshot/files/src/p-dev/workspace-snapshot-generator.ts

@@ -0,0 +1,112 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  assertNoForbiddenSnapshotPaths,
+  assertRequiredSnapshotPaths,
+  resolveSnapshotOutputPath,
+} from "./workspace-snapshot-policy.js";
+import {
+  assertCleanGitSource,
+  listGitTreeEntries,
+  readGitBlobContents,
+  resolveGitCommit,
+  selectSnapshotTreeEntries,
+} from "./workspace-snapshot-git.js";
+import { buildWorkspaceSnapshotManifest } from "./workspace-snapshot-manifest.js";
+import type {
+  WorkspaceSnapshotGenerationResult,
+  WorkspaceSnapshotTreeEntry,
+} from "./workspace-snapshot-types.js";
+import { computeSnapshotFileSha256 } from "./workspace-snapshot-digest.js";
+
+export interface GenerateWorkspaceSnapshotInput {
+  repoRoot: string;
+  packageVersion: string;
+  sourceRef?: string;
+  outputDir: string;
+}
+
+export async function generateWorkspaceSnapshot(
+  input: GenerateWorkspaceSnapshotInput,
+): Promise<WorkspaceSnapshotGenerationResult> {
+  const sourceRef = input.sourceRef ?? "HEAD";
+  await assertCleanGitSource(input.repoRoot, sourceRef);
+  const sourceCommit = await resolveGitCommit(input.repoRoot, sourceRef);
+  const treeEntries = await listGitTreeEntries(input.repoRoot, sourceCommit);
+  const selectedEntries = selectSnapshotTreeEntries(treeEntries);
+  const selectedPaths = selectedEntries.map((entry) => entry.path);
+  assertRequiredSnapshotPaths(selectedPaths);
+  assertNoForbiddenSnapshotPaths(selectedPaths);
+
+  const objectEntries = await readGitBlobContents(
+    input.repoRoot,
+    selectedEntries,
+  );
+  const manifest = buildWorkspaceSnapshotManifest({
+    packageVersion: input.packageVersion,
+    sourceCommit,
+    entries: objectEntries,
+  });
+
+  const filesDir = path.join(input.outputDir, "files");
+  await mkdir(filesDir, { recursive: true });
+  const snapshotEntries: WorkspaceSnapshotTreeEntry[] = [];
+
+  for (const entry of objectEntries) {
+    const sha256 = computeSnapshotFileSha256(entry.content);
+    const destination = resolveSnapshotOutputPath(input.outputDir, entry.path);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, entry.content);
+    snapshotEntries.push({
+      path: entry.path,
+      type: entry.type,
+      mode: entry.mode,
+      size: entry.size,
+      sha256,
+      gitBlobSha1: entry.gitBlobSha1,
+      content: entry.content,
+    });
+  }
+
+  const manifestPath = path.join(input.outputDir, "manifest.json");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  return {
+    sourceRef,
+    sourceCommit,
+    packageVersion: input.packageVersion,
+    manifest,
+    entries: snapshotEntries,
+  };
+}
+
+export async function readWorkspaceSnapshotManifest(
+  snapshotRoot: string,
+): Promise<WorkspaceSnapshotGenerationResult["manifest"]> {
+  const manifestPath = path.join(snapshotRoot, "manifest.json");
+  const raw = await readFile(manifestPath, "utf8");
+  const { parseWorkspaceSnapshotManifestJson } = await import(
+    "./workspace-snapshot-manifest.js"
+  );
+  const parsed = parseWorkspaceSnapshotManifestJson(raw);
+  if (!parsed.ok) {
+    throw new Error(parsed.reason);
+  }
+  return parsed.manifest;
+}
+
+export async function loadWorkspaceSnapshotEntryContent(input: {
+  snapshotRoot: string;
+  path: string;
+  expectedSha256: string;
+}): Promise<Buffer> {
+  const destination = resolveSnapshotOutputPath(input.snapshotRoot, input.path);
+  const content = await readFile(destination);
+  const sha256 = computeSnapshotFileSha256(content);
+  if (sha256 !== input.expectedSha256) {
+    throw new Error(
+      `Workspace snapshot file ${input.path} failed integrity check (expected ${input.expectedSha256}, got ${sha256}).`,
+    );
+  }
+  return content;
+}