@rehearsal-db/core 0.1.0-beta.10 → 0.1.0-beta.11

package/src/project/install_scaffold.mjs

@@ -0,0 +1,291 @@
+/**
+ * Purpose: Resolve an npm consumer root conservatively and create the same
+ * project-owned scaffolding used by the guided setup command.
+ */
+
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { applyRehearsalSetup, planRehearsalSetup } from "./setup.mjs";
+import {
+  findRehearsalConfigPath,
+  inspectDetectedProject,
+  loadRehearsalConfig,
+} from "./configuration.mjs";
+
+const PACKAGE_NAME = "@rehearsal-db/core";
+const DEPENDENCY_GROUPS = Object.freeze([
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+]);
+const CACHE_SEGMENTS = new Set(["_cacache", "_npx", ".cache"]);
+
+const pathExists = (path) =>
+  access(path)
+    .then(() => true)
+    .catch((error) => {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    });
+
+const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const isInside = (parent, child) => {
+  const path = relative(resolve(parent), resolve(child));
+  return path === "" || (!path.startsWith(`..${sep}`) && path !== "..");
+};
+
+const pathSegments = (path) => resolve(path).split(sep).filter(Boolean);
+
+const isCachePath = (path) =>
+  pathSegments(path).some((segment) => CACHE_SEGMENTS.has(segment));
+
+const isInstalledPackagePath = (packageRoot) => {
+  const segments = pathSegments(packageRoot);
+  return (
+    segments.at(-3) === "node_modules" &&
+    segments.at(-2) === "@rehearsal-db" &&
+    segments.at(-1) === "core"
+  );
+};
+
+const declaresRehearsal = (manifest) =>
+  DEPENDENCY_GROUPS.some((group) =>
+    Object.hasOwn(manifest[group] ?? {}, PACKAGE_NAME),
+  );
+
+const readProject = async (root) => {
+  const path = join(root, "package.json");
+  if (!(await pathExists(path))) return null;
+  const metadata = await stat(path);
+  if (!metadata.isFile()) return null;
+  return { root: resolve(root), manifest: await readJson(path) };
+};
+
+const workspacePatterns = (manifest) => {
+  const value = manifest.workspaces;
+  if (Array.isArray(value)) return value;
+  if (value && Array.isArray(value.packages)) return value.packages;
+  return [];
+};
+
+const expandWorkspacePattern = async (root, pattern) => {
+  if (
+    typeof pattern !== "string" ||
+    !pattern ||
+    isAbsolute(pattern) ||
+    pattern.split(/[\\/]/u).includes("..")
+  ) {
+    return [];
+  }
+  if (!pattern.includes("*")) return [resolve(root, pattern)];
+  if (!pattern.endsWith("/*") || pattern.slice(0, -2).includes("*")) {
+    return [];
+  }
+  const parent = resolve(root, pattern.slice(0, -2));
+  const entries = await readdir(parent, { withFileTypes: true }).catch(
+    (error) => {
+      if (error?.code === "ENOENT") return [];
+      throw error;
+    },
+  );
+  return entries
+    .filter((entry) => entry.isDirectory() && entry.name !== "node_modules")
+    .map((entry) => join(parent, entry.name));
+};
+
+const workspaceProjectsFromManifest = async (project) => {
+  const roots = (
+    await Promise.all(
+      workspacePatterns(project.manifest).map((pattern) =>
+        expandWorkspacePattern(project.root, pattern),
+      ),
+    )
+  ).flat();
+  return (
+    await Promise.all(
+      roots.map((root) =>
+        isInside(project.root, root) ? readProject(root) : null,
+      ),
+    )
+  ).filter(Boolean);
+};
+
+const workspaceProjectsFromLock = async (root) => {
+  const path = join(root, "package-lock.json");
+  if (!(await pathExists(path))) return [];
+  const lock = await readJson(path);
+  return (
+    await Promise.all(
+      Object.entries(lock.packages ?? {})
+        .filter(
+          ([name, manifest]) =>
+            name &&
+            !name.split("/").includes("node_modules") &&
+            declaresRehearsal(manifest),
+        )
+        .map(([name]) => readProject(resolve(root, name))),
+    )
+  ).filter(Boolean);
+};
+
+const uniqueProjects = (projects) => [
+  ...new Map(
+    projects.filter(Boolean).map((entry) => [entry.root, entry]),
+  ).values(),
+];
+
+const skip = (reason) => ({ status: "skipped", reason });
+
+export const resolveRehearsalConsumerRoot = async ({
+  packageRoot,
+  initCwd,
+  localPrefix,
+  globalInstall = false,
+  workspace,
+} = {}) => {
+  if (globalInstall === true || ["1", "true"].includes(globalInstall)) {
+    return skip("global installations do not own an application project");
+  }
+  if (!packageRoot || !isInstalledPackagePath(packageRoot)) {
+    return skip("the package is not running from a consumer node_modules tree");
+  }
+  if (isCachePath(packageRoot)) {
+    return skip(
+      "package-cache and temporary npx installs are not project roots",
+    );
+  }
+
+  const anchorRoots = [...new Set([initCwd, localPrefix].filter(Boolean))]
+    .map((path) => resolve(path))
+    .filter(
+      (path) =>
+        !pathSegments(path).includes("node_modules") && !isCachePath(path),
+    );
+  const anchors = uniqueProjects(
+    await Promise.all(anchorRoots.map((root) => readProject(root))),
+  );
+  if (anchors.length === 0) {
+    return skip("no application package.json was found for this installation");
+  }
+  const installationAnchors = anchors.filter((project) =>
+    isInside(project.root, packageRoot),
+  );
+  if (installationAnchors.length === 0) {
+    return skip(
+      "the installed package is outside the candidate application root",
+    );
+  }
+
+  const declared = [];
+  const workspaces = [];
+  for (const anchor of installationAnchors) {
+    if (declaresRehearsal(anchor.manifest)) declared.push(anchor);
+    const [manifestWorkspaces, lockWorkspaces] = await Promise.all([
+      workspaceProjectsFromManifest(anchor),
+      workspaceProjectsFromLock(anchor.root),
+    ]);
+    workspaces.push(...manifestWorkspaces, ...lockWorkspaces);
+    declared.push(
+      ...manifestWorkspaces.filter((project) =>
+        declaresRehearsal(project.manifest),
+      ),
+      ...lockWorkspaces,
+    );
+  }
+  if (workspace) {
+    const requested = String(workspace).trim().replace(/\\/gu, "/");
+    const selected = uniqueProjects(workspaces).filter(
+      (project) =>
+        project.manifest.name === requested ||
+        installationAnchors.some(
+          (anchor) =>
+            relative(anchor.root, project.root).replace(/\\/gu, "/") ===
+            requested.replace(/^\.\//u, ""),
+        ),
+    );
+    if (selected.length === 1) {
+      return { status: "resolved", projectRoot: selected[0].root };
+    }
+    if (selected.length > 1) {
+      return skip("the npm workspace selector matched multiple applications");
+    }
+  }
+  const candidates = uniqueProjects(declared);
+  if (candidates.length === 1) {
+    return { status: "resolved", projectRoot: candidates[0].root };
+  }
+  if (candidates.length > 1) {
+    return skip(
+      `multiple workspace applications declare ${PACKAGE_NAME}; run Rehearsal inside each application`,
+    );
+  }
+
+  const exact = initCwd ? await readProject(resolve(initCwd)) : null;
+  const workspaceRoot = installationAnchors.some(
+    (project) => workspacePatterns(project.manifest).length > 0,
+  );
+  if (
+    exact &&
+    installationAnchors.some((anchor) => isInside(anchor.root, exact.root)) &&
+    (!workspaceRoot || exact.root !== installationAnchors[0].root)
+  ) {
+    return { status: "resolved", projectRoot: exact.root };
+  }
+  if (!workspaceRoot && installationAnchors.length === 1) {
+    return {
+      status: "resolved",
+      projectRoot: installationAnchors[0].root,
+    };
+  }
+  return skip("the workspace application root is ambiguous");
+};
+
+export const createInstalledRehearsalScaffold = async ({
+  packageRoot,
+  environment = process.env,
+  isPortAvailable,
+} = {}) => {
+  const resolution = await resolveRehearsalConsumerRoot({
+    packageRoot,
+    initCwd: environment.INIT_CWD,
+    localPrefix: environment.npm_config_local_prefix,
+    globalInstall: environment.npm_config_global,
+    workspace: environment.npm_config_workspace,
+  });
+  if (resolution.status !== "resolved") return resolution;
+
+  const detected = await inspectDetectedProject({
+    projectRoot: resolution.projectRoot,
+  });
+  const hasExistingConfig = await findRehearsalConfigPath({
+    projectRoot: resolution.projectRoot,
+  })
+    .then(() => true)
+    .catch((error) => {
+      if (
+        String(error?.message ?? error).startsWith("No Rehearsal configuration")
+      ) {
+        return false;
+      }
+      throw error;
+    });
+  const plan = await planRehearsalSetup({
+    projectRoot: resolution.projectRoot,
+    target: hasExistingConfig
+      ? undefined
+      : detected.hasSupabaseConfig
+        ? "supabase"
+        : "postgresql",
+    isPortAvailable,
+  });
+  const result = await applyRehearsalSetup(plan);
+  await loadRehearsalConfig({ projectRoot: resolution.projectRoot });
+  return {
+    status: "ready",
+    projectRoot: resolution.projectRoot,
+    target: plan.target,
+    files: result.files,
+  };
+};

package/src/project/setup.mjs

@@ -3,11 +3,22 @@
  * contacting hosted services or overwriting project-owned files.
  */
 
+import { randomUUID } from "node:crypto";
 import { createConnection, createServer } from "node:net";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
 import {
+  access,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import {
+  findRehearsalConfigPath,
   inspectDetectedProject,
+  loadRehearsalConfig,
   renderDetectedConfig,
   renderDetectedPostgresqlConfig,
 } from "./configuration.mjs";
@@ -178,7 +189,7 @@ enabled = false
 enabled = false
 `;
 
-const appendGitignoreEntries = (source) => {
+export const appendRehearsalGitignoreEntries = (source) => {
   const original = source ?? "";
   const lines = new Set(
     original
@@ -200,6 +211,75 @@ const appendGitignoreEntries = (source) => {
   return `${prefix}${separator}# Rehearsal local artifacts\n${missing.join("\n")}\n`;
 };
 
+const findExistingConfigPath = async ({ projectRoot, configPath }) => {
+  try {
+    return await findRehearsalConfigPath({ projectRoot, configPath });
+  } catch (error) {
+    if (
+      String(error?.message ?? error).startsWith("No Rehearsal configuration")
+    ) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+const deriveSupabasePorts = (runtimePorts) => ({
+  shadow: runtimePorts.database - 2,
+  api: runtimePorts.api,
+  database: runtimePorts.database,
+  studio: runtimePorts.studio,
+  smtp: runtimePorts.database + 2,
+  pooler: runtimePorts.database + 7,
+});
+
+const applyGitignoreChange = async (file) => {
+  if (file.action === "unchanged") return;
+  if (file.action === "create") {
+    await writeFile(file.absolutePath, file.content, {
+      flag: "wx",
+      mode: file.mode,
+    });
+    return;
+  }
+
+  const lockPath = `${file.absolutePath}.rehearsal.lock`;
+  let lock;
+  let temporaryPath;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+    const current = await readOptionalFile(file.absolutePath);
+    if (current !== file.originalContent) {
+      throw new Error(
+        ".gitignore changed after the setup preview; rerun rehearsal setup before writing.",
+      );
+    }
+    temporaryPath = join(
+      dirname(file.absolutePath),
+      `.${basename(file.absolutePath)}.rehearsal-${process.pid}-${randomUUID()}.tmp`,
+    );
+    await writeFile(temporaryPath, file.content, {
+      flag: "wx",
+      mode: file.mode,
+    });
+    await rename(temporaryPath, file.absolutePath);
+    temporaryPath = null;
+  } catch (error) {
+    if (error?.code === "EEXIST" && !lock) {
+      throw new Error(
+        "Another Rehearsal process is updating .gitignore; rerun setup after it finishes.",
+      );
+    }
+    throw error;
+  } finally {
+    if (temporaryPath) await rm(temporaryPath, { force: true });
+    if (lock) {
+      await lock.close();
+      await rm(lockPath, { force: true });
+    }
+  }
+};
+
 const assertCreateTargetAvailable = async (file) => {
   if (file.action === "create" && (await pathExists(file.absolutePath))) {
     throw new Error(
@@ -210,41 +290,63 @@ const assertCreateTargetAvailable = async (file) => {
 
 export const planRehearsalSetup = async ({
   projectRoot = process.cwd(),
+  configPath,
   isPortAvailable,
-  target = "supabase",
+  target,
 } = {}) => {
   const root = resolve(projectRoot);
-  const runtimeTarget = resolveRuntimeTarget(target).id;
   const detected = await inspectDetectedProject({ projectRoot: root });
-  const ports = await findAvailableRehearsalPorts({
-    ...(isPortAvailable ? { isAvailable: isPortAvailable } : {}),
+  const existingConfigPath = await findExistingConfigPath({
+    projectRoot: root,
+    configPath,
   });
-  const applicationUrl = "http://localhost:5175";
-  const projectId = `${detected.projectName}-rehearsal`;
+  const existing = existingConfigPath
+    ? await loadRehearsalConfig({ projectRoot: root, configPath })
+    : null;
+  const requestedTarget = resolveRuntimeTarget(
+    target ?? existing?.config.runtime.target ?? "supabase",
+  ).id;
+  const runtimeTarget = existing?.config.runtime.target ?? requestedTarget;
+  if (existing && target && runtimeTarget !== requestedTarget) {
+    throw new Error(
+      `The existing Rehearsal configuration targets ${runtimeTarget}; setup will not replace it with ${requestedTarget}.`,
+    );
+  }
+  const ports = existing
+    ? runtimeTarget === "supabase"
+      ? deriveSupabasePorts(existing.config.runtime.ports)
+      : { database: existing.config.runtime.ports.database }
+    : await findAvailableRehearsalPorts({
+        ...(isPortAvailable ? { isAvailable: isPortAvailable } : {}),
+      });
+  const applicationUrl =
+    existing?.config.runtime.applicationUrl ?? "http://localhost:5175";
+  const projectId =
+    existing?.config.runtime.projectId ?? `${detected.projectName}-rehearsal`;
   const sourceSupabaseConfig =
     runtimeTarget === "supabase"
       ? await readOptionalFile(join(root, "supabase/config.toml"))
       : null;
   const originalGitignore = await readOptionalFile(join(root, GITIGNORE_PATH));
-  const nextGitignore = appendGitignoreEntries(originalGitignore);
-  for (const path of [
-    CONFIG_PATH,
-    ...(runtimeTarget === "supabase" ? [LOCAL_SUPABASE_CONFIG_PATH] : []),
-  ]) {
-    if (await pathExists(join(root, path))) {
-      throw new Error(
-        `Rehearsal setup will not overwrite the existing file at ${path}.`,
-      );
-    }
-  }
+  const nextGitignore = appendRehearsalGitignoreEntries(originalGitignore);
+  const rehearsalConfigPath = existing?.paths.rehearsalConfig;
+  const localSupabasePath = rehearsalConfigPath
+    ? relative(root, rehearsalConfigPath)
+    : LOCAL_SUPABASE_CONFIG_PATH;
+  const localSupabaseExists = rehearsalConfigPath
+    ? await pathExists(rehearsalConfigPath)
+    : false;
   const files = [
     {
-      path: CONFIG_PATH,
-      absolutePath: join(root, CONFIG_PATH),
-      action: "create",
+      path: existingConfigPath
+        ? relative(root, existingConfigPath)
+        : CONFIG_PATH,
+      absolutePath: existingConfigPath ?? join(root, CONFIG_PATH),
+      action: existingConfigPath ? "unchanged" : "create",
       mode: 0o600,
-      content:
-        runtimeTarget === "supabase"
+      content: existingConfigPath
+        ? null
+        : runtimeTarget === "supabase"
           ? renderDetectedConfig(detected, {
               applicationUrl,
               ports,
@@ -257,17 +359,20 @@ export const planRehearsalSetup = async ({
     ...(runtimeTarget === "supabase"
       ? [
           {
-            path: LOCAL_SUPABASE_CONFIG_PATH,
-            absolutePath: join(root, LOCAL_SUPABASE_CONFIG_PATH),
-            action: "create",
+            path: localSupabasePath,
+            absolutePath:
+              rehearsalConfigPath ?? join(root, LOCAL_SUPABASE_CONFIG_PATH),
+            action: localSupabaseExists ? "unchanged" : "create",
             mode: 0o600,
-            content: renderSafeLocalSupabaseConfig({
-              projectId,
-              applicationUrl,
-              ports,
-              databaseMajorVersion:
-                databaseMajorVersionFrom(sourceSupabaseConfig),
-            }),
+            content: localSupabaseExists
+              ? null
+              : renderSafeLocalSupabaseConfig({
+                  projectId,
+                  applicationUrl,
+                  ports,
+                  databaseMajorVersion:
+                    databaseMajorVersionFrom(sourceSupabaseConfig),
+                }),
           },
         ]
       : []),
@@ -293,6 +398,11 @@ export const planRehearsalSetup = async ({
     applicationUrl,
     detected,
     ports: runtimeTarget === "supabase" ? ports : { database: ports.database },
+    requiresAvailablePorts: files.some(
+      (file) =>
+        file.action === "create" &&
+        [CONFIG_PATH, localSupabasePath].includes(file.path),
+    ),
     isPortAvailable: isPortAvailable ?? isRehearsalPortAvailable,
     files,
     safety: [
@@ -314,14 +424,16 @@ export const planRehearsalSetup = async ({
 
 export const applyRehearsalSetup = async (plan) => {
   assertSupportedRehearsalNodeRuntime();
-  const unavailablePorts = (
-    await Promise.all(
-      Object.values(plan.ports).map(async (port) => ({
-        port,
-        available: await plan.isPortAvailable(port),
-      })),
-    )
-  ).filter(({ available }) => !available);
+  const unavailablePorts = plan.requiresAvailablePorts
+    ? (
+        await Promise.all(
+          Object.values(plan.ports).map(async (port) => ({
+            port,
+            available: await plan.isPortAvailable(port),
+          })),
+        )
+      ).filter(({ available }) => !available)
+    : [];
   if (unavailablePorts.length) {
     throw new Error(
       `Rehearsal setup ports became occupied after the preview (${unavailablePorts.map(({ port }) => port).join(", ")}); rerun setup to choose another local port block.`,
@@ -329,16 +441,9 @@ export const applyRehearsalSetup = async (plan) => {
   }
   for (const file of plan.files) await assertCreateTargetAvailable(file);
   const gitignore = plan.files.find((file) => file.path === GITIGNORE_PATH);
-  if (gitignore?.action === "update") {
-    const current = await readOptionalFile(gitignore.absolutePath);
-    if (current !== gitignore.originalContent) {
-      throw new Error(
-        ".gitignore changed after the setup preview; rerun rehearsal setup before writing.",
-      );
-    }
-  }
+  if (gitignore) await applyGitignoreChange(gitignore);
   for (const file of plan.files.filter(
-    (entry) => entry.action !== "unchanged",
+    (entry) => entry.action !== "unchanged" && entry.path !== GITIGNORE_PATH,
   )) {
     await mkdir(dirname(file.absolutePath), { recursive: true, mode: 0o700 });
     await writeFile(file.absolutePath, file.content, {