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

package/src/project/configuration.d.mts

@@ -8,6 +8,17 @@ export interface RehearsalConfig {
     migrationDirectory: string;
     rehearsalConfig: string;
     runtimeWorkdir: string;
+    authentication?: {
+      enableLocalSignup: true;
+      environmentFile: string;
+      providers: Array<{
+        name: "google" | "github";
+        clientIdEnvironmentVariable: string;
+        clientSecretEnvironmentVariable: string;
+        skipNonceCheck?: boolean;
+        emailOptional?: boolean;
+      }>;
+    };
     serviceEnvironmentFile?: string;
     serviceEnvironmentVariables?: string[];
   };

package/src/project/configuration.mjs

@@ -61,6 +61,7 @@ const POSTGRES_IMAGE_PATTERN = /^postgres:\d+(?:\.\d+)?-alpine$/u;
 const SAFE_COMMAND_PATTERN = /^[^\n\r\0]+$/u;
 const ENVIRONMENT_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
 const ENVIRONMENT_REFERENCE_PATTERN = /^[a-z0-9][a-z0-9-]*:[A-Z][A-Z0-9_]*$/u;
+const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
 
 const isPlainObject = (value) =>
   value !== null &&
@@ -251,6 +252,7 @@ const normalizeConfig = (input) => {
         "migrationDirectory",
         "rehearsalConfig",
         "runtimeWorkdir",
+        "authentication",
         "serviceEnvironmentFile",
         "serviceEnvironmentVariables",
       ],
@@ -437,8 +439,123 @@ const normalizeConfig = (input) => {
   if (!Array.isArray(commands)) {
     throw new Error("config.verification.commands must be an array.");
   }
-  const serviceEnvironmentVariables =
-    supabase?.serviceEnvironmentVariables ?? [];
+  const authentication =
+    supabase?.authentication === undefined
+      ? null
+      : assertPlainObject(
+          supabase.authentication,
+          "config.supabase.authentication",
+        );
+  let normalizedAuthentication = null;
+  if (authentication) {
+    assertKnownKeys(
+      authentication,
+      ["enableLocalSignup", "environmentFile", "providers"],
+      "config.supabase.authentication",
+    );
+    if (authentication.enableLocalSignup !== true) {
+      throw new Error(
+        "config.supabase.authentication.enableLocalSignup must be true to create the disposable local identity used by an OAuth sign-in.",
+      );
+    }
+    if (
+      supabase.serviceEnvironmentFile !== undefined ||
+      supabase.serviceEnvironmentVariables !== undefined
+    ) {
+      throw new Error(
+        "config.supabase.authentication cannot be combined with the legacy serviceEnvironmentFile or serviceEnvironmentVariables fields.",
+      );
+    }
+    if (safety.authenticationProviders !== undefined) {
+      throw new Error(
+        "config.safety.authenticationProviders is derived from config.supabase.authentication and must be omitted.",
+      );
+    }
+    if (
+      !Array.isArray(authentication.providers) ||
+      authentication.providers.length === 0
+    ) {
+      throw new Error(
+        "config.supabase.authentication.providers must be a non-empty array.",
+      );
+    }
+    const providers = authentication.providers.map((entry, index) => {
+      const path = `config.supabase.authentication.providers[${index}]`;
+      const value = assertPlainObject(entry, path);
+      assertKnownKeys(
+        value,
+        [
+          "name",
+          "clientIdEnvironmentVariable",
+          "clientSecretEnvironmentVariable",
+          "skipNonceCheck",
+          "emailOptional",
+        ],
+        path,
+      );
+      const name = assertNonEmptyString(value.name, `${path}.name`);
+      if (!SUPPORTED_SUPABASE_OAUTH_PROVIDERS.has(name)) {
+        throw new Error(
+          `${path}.name must be one of: ${[...SUPPORTED_SUPABASE_OAUTH_PROVIDERS].join(", ")}.`,
+        );
+      }
+      const environmentVariable = (key) => {
+        const variable = assertNonEmptyString(value[key], `${path}.${key}`);
+        if (!ENVIRONMENT_KEY_PATTERN.test(variable)) {
+          throw new Error(
+            `${path}.${key} must be a safe environment variable name.`,
+          );
+        }
+        return variable;
+      };
+      const optionalBoolean = (key) => {
+        if (value[key] === undefined) return false;
+        if (typeof value[key] !== "boolean") {
+          throw new Error(`${path}.${key} must be a boolean.`);
+        }
+        return value[key];
+      };
+      return Object.freeze({
+        name,
+        clientIdEnvironmentVariable: environmentVariable(
+          "clientIdEnvironmentVariable",
+        ),
+        clientSecretEnvironmentVariable: environmentVariable(
+          "clientSecretEnvironmentVariable",
+        ),
+        skipNonceCheck: optionalBoolean("skipNonceCheck"),
+        emailOptional: optionalBoolean("emailOptional"),
+      });
+    });
+    if (new Set(providers.map(({ name }) => name)).size !== providers.length) {
+      throw new Error(
+        "config.supabase.authentication.providers must not contain duplicate providers.",
+      );
+    }
+    const credentialVariables = providers.flatMap((provider) => [
+      provider.clientIdEnvironmentVariable,
+      provider.clientSecretEnvironmentVariable,
+    ]);
+    if (new Set(credentialVariables).size !== credentialVariables.length) {
+      throw new Error(
+        "config.supabase.authentication provider environment variables must be unique.",
+      );
+    }
+    normalizedAuthentication = Object.freeze({
+      enableLocalSignup: true,
+      environmentFile: assertRelativePath(
+        authentication.environmentFile,
+        "config.supabase.authentication.environmentFile",
+      ),
+      providers: Object.freeze(providers),
+    });
+  }
+  const serviceEnvironmentVariables = normalizedAuthentication
+    ? normalizedAuthentication.providers.flatMap((provider) => [
+        provider.clientIdEnvironmentVariable,
+        provider.clientSecretEnvironmentVariable,
+      ])
+    : (supabase?.serviceEnvironmentVariables ?? []);
   if (!Array.isArray(serviceEnvironmentVariables)) {
     throw new Error(
       "config.supabase.serviceEnvironmentVariables must be an array.",
@@ -460,19 +577,23 @@ const normalizeConfig = (input) => {
     );
   }
   if (
-    Boolean(supabase?.serviceEnvironmentFile) !==
-    Boolean(normalizedServiceEnvironmentVariables.length)
+    Boolean(
+      normalizedAuthentication?.environmentFile ??
+      supabase?.serviceEnvironmentFile,
+    ) !== Boolean(normalizedServiceEnvironmentVariables.length)
   ) {
     throw new Error(
       "config.supabase.serviceEnvironmentFile and serviceEnvironmentVariables must be configured together.",
     );
   }
-  const authenticationProviders = safety.authenticationProviders
-    ? assertStringArray(
-        safety.authenticationProviders,
-        "config.safety.authenticationProviders",
-      )
-    : [];
+  const authenticationProviders = normalizedAuthentication
+    ? normalizedAuthentication.providers.map(({ name }) => name)
+    : safety.authenticationProviders
+      ? assertStringArray(
+          safety.authenticationProviders,
+          "config.safety.authenticationProviders",
+        )
+      : [];
   if (runtimeTarget === "postgresql" && authenticationProviders.length > 0) {
     throw new Error(
       "config.safety.authenticationProviders is available only for the Supabase target.",
@@ -500,12 +621,15 @@ const normalizeConfig = (input) => {
             supabase.runtimeWorkdir,
             "config.supabase.runtimeWorkdir",
           ),
-          serviceEnvironmentFile: supabase.serviceEnvironmentFile
-            ? assertRelativePath(
-                supabase.serviceEnvironmentFile,
-                "config.supabase.serviceEnvironmentFile",
-              )
-            : null,
+          authentication: normalizedAuthentication,
+          serviceEnvironmentFile: normalizedAuthentication
+            ? normalizedAuthentication.environmentFile
+            : supabase.serviceEnvironmentFile
+              ? assertRelativePath(
+                  supabase.serviceEnvironmentFile,
+                  "config.supabase.serviceEnvironmentFile",
+                )
+              : null,
           serviceEnvironmentVariables: Object.freeze(
             normalizedServiceEnvironmentVariables,
           ),
@@ -1005,9 +1129,21 @@ export default defineRehearsalConfig({
 		rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
 		runtimeWorkdir: ".rehearsal/runtime",
 
-		// Optional local-only identity-provider credentials. Enable both keys together.
-		// serviceEnvironmentFile: ".env.rehearsal-service.local",
-		// serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+		// Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+		// Register http://127.0.0.1:${ports.api}/auth/v1/callback with the provider.
+		// authentication: {
+		// 	enableLocalSignup: true,
+		// 	environmentFile: ".env.rehearsal-service.local",
+		// 	providers: [
+		// 		{
+		// 			name: "google",
+		// 			clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+		// 			clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+		// 			skipNonceCheck: false,
+		// 			emailOptional: false,
+		// 		},
+		// 	],
+		// },
 	},
 
 	// Immutable local baseline files. Rehearsal never reads production on your behalf.
@@ -1028,7 +1164,8 @@ export default defineRehearsalConfig({
 	// },
 	// Optional reviewed schemas/extensions/triggers/local-only rows.
 	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
-	// Optional signup defaults, role/reference transfer, Storage paths, and token checks.
+	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
+	// raw emails/subjects and provider credentials stay in ignored environment files.
 	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
 
 	// Reuse any running Docker-compatible engine; start Colima only when needed.
@@ -1136,7 +1273,8 @@ export default defineRehearsalConfig({
 	// },
 	// Optional reviewed schemas/extensions/triggers/local-only rows.
 	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
-	// Optional signup defaults, role/reference transfer, Storage paths, and token checks.
+	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
+	// raw emails/subjects and provider credentials stay in ignored environment files.
 	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
 
 	// Reuse any running Docker-compatible engine; start Colima only when needed.

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,
+  };
+};