@monster-orange/den 0.0.0 → 0.2.0

package/src/pillars/smoke/admin-probe.ts

@@ -0,0 +1,68 @@
+/**
+ * Pre-flight check: storage teardown scripts often call admin HTTP APIs (e.g. a service's
+ * `POST /api/v1/admin/purge`). If admin routes are disabled, fail before Playwright/k6.
+ * The probe path and 403 hint come from the manifest fixture (`adminProbePath`,
+ * `adminProbe403Hint`).
+ *
+ * Service-specific error hints belong to the caller via `hintOn403` — this module stays
+ * generic and has no knowledge of any particular service's error format.
+ */
+
+export interface AssertStorageAdminProbeOptions {
+  baseUrl: string;
+  /** e.g. `/api/v1/admin/status` (GET, idempotent, passes admin guard only when enabled). */
+  adminProbePath: string;
+  /** Shown in errors (e.g. `files-api / api`). */
+  label: string;
+  /**
+   * Optional callback invoked on a 403 response to produce a service-specific remediation hint.
+   * Return a non-empty string to append it to the error message; return "" for generic output.
+   */
+  hintOn403?: (body: string) => string;
+}
+
+function joinBaseUrlAndProbePath(baseUrl: string, probePath: string): string {
+  const trimmedBase = baseUrl.replace(/\/$/, "");
+  const path = probePath.startsWith("/") ? probePath : `/${probePath}`;
+  return `${trimmedBase}${path}`;
+}
+
+/**
+ * GET `{baseUrl}{adminProbePath}` — expect 2xx when admin APIs are allowed for this deployment.
+ * Throws with a clear error (and optional caller-supplied hint) on non-2xx.
+ */
+export async function assertStorageAdminProbe(
+  options: AssertStorageAdminProbeOptions,
+): Promise<void> {
+  const url = joinBaseUrlAndProbePath(options.baseUrl, options.adminProbePath);
+  console.log(`🔒 Admin API probe (${options.label}): ${url}`);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Admin probe failed for ${options.label}: cannot reach ${url} (${message})`,
+    );
+  }
+  const body = await response.text();
+  if (response.ok) {
+    console.log(`  ✓ Admin endpoints reachable (${response.status})`);
+    return;
+  }
+  if (response.status === 403) {
+    const hint = options.hintOn403?.(body) ?? "";
+    const detail =
+      `Admin probe failed for ${options.label}: ${url} returned 403.` +
+      (hint
+        ? `\n${hint}`
+        : `\n  Response body (truncated): ${body.slice(0, 500)}`);
+    throw new Error(detail);
+  }
+  throw new Error(
+    `Admin probe failed for ${options.label}: ${url} returned ${response.status}: ${body.slice(0, 500)}`,
+  );
+}

package/src/pillars/smoke/base-url.ts

@@ -0,0 +1,56 @@
+/**
+ * Smoke-specific re-exports of the shared service URL resolution helpers.
+ *
+ * All smoke consumers import from this module. The underlying logic now lives
+ * in `src/shared/service-url.ts` so the perf pillar (and future pillars) can
+ * reuse it without importing from `pillars/smoke/`.
+ */
+import type {
+  Environment,
+  RawManifest,
+  SmokeServiceConfig,
+} from "../../shared/types/index.js";
+import {
+  resolveManifestBaseUrl,
+  resolveServiceBaseUrl,
+} from "../../shared/service-url.js";
+
+export {
+  resolveManifestBaseUrl as resolveManifestSmokeBaseUrl,
+  resolveServiceBaseUrl as resolveSmokeBaseUrl,
+} from "../../shared/service-url.js";
+
+export type {
+  ResolveManifestBaseUrlOptions as ResolveManifestSmokeBaseUrlOptions,
+  ResolveServiceBaseUrlOptions as ResolveSmokeBaseUrlOptions,
+} from "../../shared/service-url.js";
+
+/** Same precedence as single-service smoke setup: override → manifest health URL → env config. */
+export function resolveSmokeBaseUrlForService(
+  manifest: RawManifest,
+  repoName: string,
+  serviceName: string,
+  service: SmokeServiceConfig,
+  environment: Environment,
+  envConfig: { baseUrls: { api: string; web: string } },
+  /** Explicit override URL (pass `process.env.BASE_API_URL` at the call site). */
+  overrideUrl?: string | null,
+): string {
+  const configuredUrl =
+    service.baseUrlKey === "api"
+      ? envConfig.baseUrls.api
+      : envConfig.baseUrls.web;
+  const manifestUrl = resolveManifestBaseUrl({
+    manifest,
+    repoName,
+    serviceName,
+    environment,
+    baseUrlKey: service.baseUrlKey,
+  });
+  return resolveServiceBaseUrl({
+    baseUrlKey: service.baseUrlKey,
+    configuredUrl,
+    manifestUrl,
+    overrideUrl,
+  });
+}

package/src/pillars/smoke/cleanup.ts

@@ -0,0 +1,8 @@
+export {
+  acquireFixture,
+  fixtureInstanceId,
+  releaseFixturesForConsumer,
+  resetFixtureManagerForTests,
+  runRepoShellCommand,
+  type ManagedFixtureSpec,
+} from "./fixture-manager.js";

package/src/pillars/smoke/discover.ts

@@ -0,0 +1,237 @@
+/**
+ * Manifest Discovery
+ *
+ * Generic layer: scans .den/ for repos that have a .den.json
+ * manifest file and returns the raw parsed manifest.
+ *
+ * Smoke-specific helpers (resolveService) live below and read from the
+ * `smoke` key — unrelated to the `services` (service management) key.
+ *
+ * Local:  .den/<repo> → symlink to sibling repo  (make smoke-link)
+ * CI:     .den/<repo> → actual checkout           (smoke.yml workflow)
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { readManifest } from "../../shared/manifest/read-manifest.js";
+import { cloneDirFor } from "../../shared/smoke/repo-cloner.js";
+import { isLocalEnabled } from "../../shared/den-config.js";
+import {
+  getActiveWorkspace,
+  listWorkspaceServices,
+} from "../../shared/environment-manager/workspaces.js";
+import { readCatalog } from "../../shared/environment-manager/catalog.js";
+import { getDistRoot } from "../../shared/paths.js";
+import type {
+  DiscoveredRepo,
+  Environment,
+  PerformanceServiceConfig,
+  SmokeServiceConfig,
+} from "../../shared/types/index.js";
+
+import { product } from "../../shared/product.js";
+// Den-root anchored so the legacy-registry branch agrees with the already
+// anchored workspace branch from any cwd (reads only — never written).
+const ROOT = getDistRoot();
+const REGISTERED_FILE = path.resolve(
+  ROOT,
+  "config",
+  "local",
+  "registered-repos.json",
+);
+const LINKED_REPOS_DIR = path.resolve(ROOT, `.${product().name}`);
+
+// ── Generic layer ─────────────────────────────────────────────────────────────
+
+/**
+ * Discover all registered repos.
+ *
+ * When Local Dev is enabled, the active workspace is the source of truth —
+ * tests run against the same repos you're developing against. When Local Dev
+ * is disabled, we fall back to the legacy registry:
+ *   1. config/local/registered-repos.json  (set via `make register-repos`)
+ *   2. .den/ symlinks / checkouts       (CI / legacy manual links)
+ */
+export function discoverRepos(): DiscoveredRepo[] {
+  if (isLocalEnabled()) {
+    return discoverFromWorkspace();
+  }
+  return discoverFromRegistry();
+}
+
+/** Resolve repos from the active workspace's service set. */
+function discoverFromWorkspace(): DiscoveredRepo[] {
+  const active = getActiveWorkspace();
+  if (!active) return discoverFromRegistry(); // no workspace → fall back
+
+  const catalog = readCatalog();
+  const services = listWorkspaceServices(active.config, catalog, active.name);
+
+  const results: DiscoveredRepo[] = [];
+  const seen = new Set<string>();
+
+  for (const svc of services) {
+    if (!svc.repoPath || seen.has(svc.repoName)) continue;
+    seen.add(svc.repoName);
+    addRepo(results, seen, svc.repoPath, svc.repoName);
+  }
+
+  return results;
+}
+
+/** Legacy discovery from registered-repos.json and .den/ symlinks. */
+function discoverFromRegistry(): DiscoveredRepo[] {
+  const results: DiscoveredRepo[] = [];
+  const seen = new Set<string>();
+
+  // Source 1: config/local/registered-repos.json
+  if (fs.existsSync(REGISTERED_FILE)) {
+    try {
+      const paths = JSON.parse(
+        fs.readFileSync(REGISTERED_FILE, "utf-8"),
+      ) as string[];
+      for (const p of paths) addRepo(results, seen, p, path.basename(p));
+    } catch (err) {
+      console.warn(`  ⚠  Failed to read ${REGISTERED_FILE}: ${err}`);
+    }
+  }
+
+  // Source 2: .den/ symlinks / CI checkouts
+  if (fs.existsSync(LINKED_REPOS_DIR)) {
+    for (const entry of fs.readdirSync(LINKED_REPOS_DIR)) {
+      const repoPath = path.join(LINKED_REPOS_DIR, entry);
+      try {
+        fs.lstatSync(repoPath);
+      } catch {
+        continue;
+      }
+      addRepo(results, seen, repoPath, entry);
+    }
+  }
+
+  return results;
+}
+
+function addRepo(
+  results: DiscoveredRepo[],
+  seen: Set<string>,
+  repoPath: string,
+  fallbackName: string,
+): void {
+  const manifest = readManifest(repoPath);
+  if (!manifest) return;
+  try {
+    const resolved = fs.realpathSync(repoPath);
+    if (seen.has(resolved)) return;
+    seen.add(resolved);
+    results.push({
+      repoName: manifest.name ?? fallbackName,
+      repoPath: resolved,
+      manifest,
+    });
+  } catch (err) {
+    // A held manifest can resolve for a managed clone that was never made.
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      console.warn(
+        `  ⚠  ${fallbackName}: no checkout at ${repoPath}, skipped. ` +
+          `Use your own (${product().cli} use-local ${fallbackName}) or let ${product().cli} clone it (${product().cli} up ${fallbackName}).`,
+      );
+      return;
+    }
+    console.warn(`  ⚠  Failed to register repo at ${repoPath}: ${err}`);
+  }
+}
+
+/**
+ * Registered sibling checkout path (no smoke-clone semantics).
+ * Used when environment is `local`, `useLocalCheckout` is true, or callers only
+ * need the linked repo root (e.g. repo-owned perf tests staging from checkout).
+ */
+export function resolveRegisteredRepoPath(discovered: DiscoveredRepo): string {
+  return discovered.repoPath;
+}
+
+/**
+ * Resolve the local filesystem path for a repo given a target environment.
+ *
+ * - local  → the registered/symlinked path (existing behaviour, no clone)
+ * - other  → .smoke-clones/{repoName}/{environment}/ by default
+ * - any env with useLocalCheckout=true → the registered/symlinked path
+ *
+ * This is the single integration point for environment-aware path resolution.
+ * All callers (setup.ts, setup-global.ts) should go through here instead of
+ * reaching into DiscoveredRepo.repoPath directly when running against non-local
+ * environments.
+ */
+export function resolveRepoPath(
+  discovered: DiscoveredRepo,
+  environment: Environment,
+  useLocalCheckout = false,
+): string {
+  if (environment === "local" || useLocalCheckout) {
+    return resolveRegisteredRepoPath(discovered);
+  }
+
+  const cloneDir = cloneDirFor(discovered.repoName, environment);
+  if (!fs.existsSync(cloneDir)) {
+    throw new Error(
+      `Smoke clone for "${discovered.repoName}@${environment}" not found at ${cloneDir}.\n` +
+        `  Run first: npx tsx src/pillars/smoke/setup-env.ts --env ${environment} --repo ${discovered.repoName}\n` +
+        `  Or via make: make smoke-clone env=${environment} repo=${discovered.repoName}`,
+    );
+  }
+  return cloneDir;
+}
+
+/**
+ * Find a specific repo manifest by name.
+ */
+export function findManifest(repoName: string): DiscoveredRepo | null {
+  const all = discoverRepos();
+  return (
+    all.find(
+      (r) => r.repoName === repoName || path.basename(r.repoPath) === repoName,
+    ) ?? null
+  );
+}
+
+// ── Smoke-specific layer ──────────────────────────────────────────────────────
+
+export interface ResolvedSmokeService extends SmokeServiceConfig {
+  /** Absolute path to the smoke test directory */
+  testDir: string;
+}
+
+export interface ResolvedPerformanceService extends PerformanceServiceConfig {
+  /** Absolute path to the performance test directory */
+  testDir: string;
+}
+
+/**
+ * Resolve a smoke service config to absolute paths.
+ * Reads from `manifest.smoke.<serviceName>` — not `services`.
+ * Returns null if the service is not defined in the manifest.
+ */
+export function resolveService(
+  discovered: DiscoveredRepo,
+  serviceName: string,
+): ResolvedSmokeService | null {
+  const svc = discovered.manifest.smoke?.[serviceName];
+  if (!svc) return null;
+  return {
+    ...svc,
+    testDir: path.resolve(discovered.repoPath, svc.testDir),
+  };
+}
+
+export function resolvePerformanceService(
+  discovered: DiscoveredRepo,
+  moduleName: string,
+): ResolvedPerformanceService | null {
+  const perf = discovered.manifest.performance?.[moduleName];
+  if (!perf) return null;
+  return {
+    ...perf,
+    testDir: path.resolve(discovered.repoPath, perf.testDir),
+  };
+}

package/src/pillars/smoke/ensure-smoke-teardown.ts

@@ -0,0 +1,40 @@
+/**
+ * Post–smoke-run check: if Playwright global teardown ran, it removes
+ * `.smoke-run/smoke-fixture-handoff.json` after releasing storage fixtures.
+ *
+ * A leftover file means global teardown did not complete — storage side effects
+ * may still exist (MinIO buckets, etc.). Fail loudly so CI/UI runs do not
+ * silently leak fixtures.
+ *
+ * Safe when no storage fixture was acquired (file never created): exits 0.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { getDistRoot } from "../../shared/paths.js";
+
+import { product } from "../../shared/product.js";
+// Den-root anchored: must resolve the SAME handoff path global-teardown.ts
+// writes, or a cwd mismatch silently reports leaked fixtures as clean.
+const PROJECT_ROOT = getDistRoot();
+const HANDOFF = path.join(
+  PROJECT_ROOT,
+  ".smoke-run",
+  "smoke-fixture-handoff.json",
+);
+
+function main(): void {
+  if (fs.existsSync(HANDOFF)) {
+    console.error(
+      `[${product().cli}] smoke fixture handoff still present:\n  ${HANDOFF}\n` +
+        `  Playwright global teardown did not finish releasing storage fixtures.\n` +
+        `  Fix: ensure tests exit normally so globalTeardown runs; check for crashes/kill -9.`,
+    );
+    process.exit(1);
+  }
+  console.log(
+    `[${product().cli}] smoke teardown verification: no stale storage fixture handoff`,
+  );
+}
+
+main();

package/src/pillars/smoke/fixture-manager.ts

@@ -0,0 +1,217 @@
+import { spawn } from "child_process";
+import type { CommandDef } from "../../shared/types/index.js";
+
+export interface ManagedFixtureSpec {
+  fixtureKey: string;
+  resolvedPayload: Record<string, unknown>;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  setup?: CommandDef;
+  teardown?: CommandDef;
+}
+
+function commandText(commandDef: CommandDef): string {
+  return typeof commandDef === "string" ? commandDef : commandDef.cmd;
+}
+
+const UNDEFINED_SENTINEL = "__fixture_manager_undefined__";
+
+/** Recursively sort object keys so serialization is stable for arbitrary payloads. */
+function stableSortValue(value: unknown): unknown {
+  if (value === undefined) {
+    return UNDEFINED_SENTINEL;
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(stableSortValue);
+  }
+  const obj = value as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = stableSortValue(obj[key]);
+  }
+  return sorted;
+}
+
+/**
+ * Deterministic identity for a managed fixture instance: stable serialization of
+ * fixtureKey + resolvedPayload.
+ */
+export function fixtureInstanceId(
+  fixtureKey: string,
+  resolvedPayload: Record<string, unknown>,
+): string {
+  return JSON.stringify({
+    fixtureKey,
+    resolvedPayload: stableSortValue(resolvedPayload),
+  });
+}
+
+function normalizedCommand(
+  commandDef: CommandDef | undefined,
+): string | undefined {
+  return commandDef === undefined ? undefined : commandText(commandDef);
+}
+
+function specConflictKey(spec: ManagedFixtureSpec): string {
+  return JSON.stringify(
+    stableSortValue({
+      cwd: spec.cwd,
+      env: spec.env,
+      setup: normalizedCommand(spec.setup),
+      teardown: normalizedCommand(spec.teardown),
+    }),
+  );
+}
+
+export async function runRepoShellCommand(
+  command: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const proc = spawn(command, [], {
+      cwd,
+      env,
+      shell: true,
+      stdio: "inherit",
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(`Command failed with exit code ${code ?? 1}: ${command}`),
+      );
+    });
+
+    proc.on("error", (error) => {
+      reject(
+        new Error(`Failed to start command "${command}": ${error.message}`),
+      );
+    });
+  });
+}
+
+interface RegistryEntry {
+  refCount: number;
+  spec: ManagedFixtureSpec;
+  specConflictKey: string;
+}
+
+const registry = new Map<string, RegistryEntry>();
+const instanceTails = new Map<string, Promise<unknown>>();
+
+function enqueueForInstance<T>(
+  instanceId: string,
+  task: () => Promise<T>,
+): Promise<T> {
+  const prev = instanceTails.get(instanceId) ?? Promise.resolve();
+  const result = prev.then(() => task());
+  instanceTails.set(
+    instanceId,
+    result.catch(() => {}),
+  );
+  return result as Promise<T>;
+}
+
+/**
+ * Acquire a shared fixture: runs `setup` once per instance identity, increments refCount.
+ * Returns a release function — call it in `finally` so teardown runs even when work fails.
+ * The release function is idempotent (safe to call at most once; repeats are no-ops).
+ */
+export async function acquireFixture(
+  spec: ManagedFixtureSpec,
+): Promise<() => Promise<void>> {
+  const instanceId = fixtureInstanceId(spec.fixtureKey, spec.resolvedPayload);
+  const currentSpecConflictKey = specConflictKey(spec);
+
+  return enqueueForInstance(instanceId, async () => {
+    let entry = registry.get(instanceId);
+    if (!entry) {
+      entry = { refCount: 0, spec, specConflictKey: currentSpecConflictKey };
+      registry.set(instanceId, entry);
+    } else if (entry.specConflictKey !== currentSpecConflictKey) {
+      throw new Error(
+        `Conflicting fixture specs for shared fixture identity ${instanceId}`,
+      );
+    }
+
+    if (entry.refCount === 0 && spec.setup !== undefined) {
+      try {
+        await runRepoShellCommand(commandText(spec.setup), spec.cwd, spec.env);
+      } catch (error) {
+        registry.delete(instanceId);
+        throw error;
+      }
+    }
+
+    entry.refCount += 1;
+
+    let released = false;
+    return async () => {
+      await enqueueForInstance(instanceId, async () => {
+        if (released) {
+          return;
+        }
+        released = true;
+
+        const current = registry.get(instanceId);
+        if (!current) {
+          throw new Error(
+            `Fixture release for unknown instance (already torn down?): ${instanceId}`,
+          );
+        }
+
+        current.refCount -= 1;
+        if (current.refCount < 0) {
+          throw new Error(`Fixture refCount underflow for ${instanceId}`);
+        }
+
+        if (current.refCount === 0) {
+          if (current.spec.teardown !== undefined) {
+            await runRepoShellCommand(
+              commandText(current.spec.teardown),
+              current.spec.cwd,
+              current.spec.env,
+            );
+          }
+          registry.delete(instanceId);
+          instanceTails.delete(instanceId);
+        }
+      });
+    };
+  });
+}
+
+/**
+ * Release multiple acquire handles in LIFO order (typical nested `try/finally` stack).
+ * Runs every release even when one fails, then throws {@link AggregateError} if any failed.
+ */
+export async function releaseFixturesForConsumer(
+  releases: ReadonlyArray<() => Promise<void>>,
+): Promise<void> {
+  const errors: Error[] = [];
+  for (let i = releases.length - 1; i >= 0; i -= 1) {
+    try {
+      await releases[i]();
+    } catch (e) {
+      errors.push(e instanceof Error ? e : new Error(String(e)));
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(
+      errors,
+      `Fixture teardown failed (${errors.length} instance(s))`,
+    );
+  }
+}
+
+export function resetFixtureManagerForTests(): void {
+  registry.clear();
+  instanceTails.clear();
+}