@monster-orange/den 0.0.0 → 0.2.0

package/src/pillars/smoke/playwright-global.config.ts

@@ -0,0 +1,141 @@
+/**
+ * Playwright Configuration — All Smoke Tests, All Repos
+ *
+ * Used by: make test-smk-global
+ *
+ * Creates one Playwright project per service per registered repo.
+ * All results appear in a single combined report.
+ *
+ * Environment variables:
+ *   E2E_ENVIRONMENT   — env config to load (default: local)
+ *   BASE_API_URL      — override API base URL
+ */
+
+import { defineConfig } from "@playwright/test";
+import * as fs from "fs";
+import * as path from "path";
+import { findManifest } from "./discover.js";
+import {
+  resolveManifestSmokeBaseUrl,
+  resolveSmokeBaseUrl,
+} from "./base-url.js";
+import type { Environment } from "../../shared/types/index.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { distPath, enginePath } from "../../shared/engine.js";
+
+import { product } from "../../shared/product.js";
+// Den-root anchored in lockstep with setup-global.ts (the manifest writer).
+const PROJECT_ROOT = getDistRoot();
+const SMOKE_RUN_DIR = path.resolve(PROJECT_ROOT, ".smoke-run");
+const environment = (process.env.E2E_ENVIRONMENT || "local") as Environment;
+
+const configPath = path.resolve(
+  PROJECT_ROOT,
+  `config/environments/${environment}.json`,
+);
+let envConfig: { baseUrls: { api: string; web: string } };
+try {
+  envConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+} catch {
+  console.error(
+    `\n❌ playwright-global.config: no env config for "${environment}"`,
+  );
+  console.error(`   Expected: config/environments/${environment}.json\n`);
+  process.exit(1);
+}
+
+// Read exactly what setup-global.ts staged — no second discoverRepos() call
+const globalManifestPath = path.join(SMOKE_RUN_DIR, "global-manifest.json");
+if (!fs.existsSync(globalManifestPath)) {
+  console.error(
+    `\n❌ No staged smoke tests found. Run: make test-smk-global\n`,
+  );
+  process.exit(1);
+}
+const staged: Array<{
+  repo: string;
+  svc: string;
+  dir: string;
+  testMatch: string;
+  baseUrlKey: string;
+}> = JSON.parse(fs.readFileSync(globalManifestPath, "utf-8"));
+
+if (!staged.length) {
+  console.error(
+    `\n❌ No smoke services staged. Check your ${product().manifestYml} smoke: keys.\n`,
+  );
+  process.exit(1);
+}
+
+const projects = staged.map(({ repo, svc, dir, testMatch, baseUrlKey }) => {
+  if (!fs.existsSync(dir)) {
+    console.error(`\n❌ Staging dir missing: ${dir}`);
+    console.error(`   Re-run: make test-smk-global\n`);
+    process.exit(1);
+  }
+
+  const configuredUrl =
+    baseUrlKey === "web" ? envConfig.baseUrls.web : envConfig.baseUrls.api;
+  const discovered = findManifest(repo);
+  if (!discovered) {
+    console.error(
+      `\n❌ No manifest found for repo "${repo}" in .${product().name}/`,
+    );
+    console.error(`   Run: make register-repos\n`);
+    process.exit(1);
+  }
+  const manifestUrl = resolveManifestSmokeBaseUrl({
+    manifest: discovered.manifest,
+    repoName: repo,
+    serviceName: svc,
+    environment,
+    baseUrlKey: baseUrlKey === "web" ? "web" : "api",
+  });
+  const baseUrl = resolveSmokeBaseUrl({
+    baseUrlKey: baseUrlKey === "web" ? "web" : "api",
+    configuredUrl,
+    manifestUrl,
+    overrideUrl: process.env.BASE_API_URL,
+  });
+
+  return {
+    name: `${repo}/${svc}`,
+    testDir: dir,
+    testMatch,
+    use: {
+      baseURL: baseUrl,
+      timeout: 30000,
+    },
+  };
+});
+
+export default defineConfig({
+  globalSetup: enginePath("src/pillars/smoke/global-setup-global.ts"),
+  globalTeardown: enginePath("src/pillars/smoke/global-teardown-global.ts"),
+
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+
+  reporter: [
+    [
+      "html",
+      {
+        outputFolder:
+          process.env.PLAYWRIGHT_HTML_REPORT || distPath("playwright-report"),
+        open: "never",
+      },
+    ],
+    ["list"],
+    [
+      "junit",
+      { outputFile: distPath("reports", "junit-smoke-global-results.xml") },
+    ],
+  ],
+
+  projects,
+
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});

package/src/pillars/smoke/playwright.config.ts

@@ -0,0 +1,162 @@
+/**
+ * Playwright Configuration for Smoke Tests
+ *
+ * Dynamically configured from the service's .den.json manifest.
+ * The testDir, testMatch, and baseURL are all resolved at config time
+ * from the manifest discovered in .den/<repo>/.den.json.
+ *
+ * Environment variables:
+ *   SMOKE_SERVICE     — service name in the manifest (default: api)
+ *   SMOKE_REPO        — repo name in .den/ (required)
+ *   E2E_ENVIRONMENT   — env config to load (default: local)
+ *   BASE_API_URL      — override base URL (useful for one-off runs)
+ */
+
+import { defineConfig } from "@playwright/test";
+import * as fs from "fs";
+import * as path from "path";
+import { findManifest, resolveService } from "./discover.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { distPath, enginePath } from "../../shared/engine.js";
+import {
+  resolveManifestSmokeBaseUrl,
+  resolveSmokeBaseUrl,
+} from "./base-url.js";
+import { smokeRepoName } from "./smoke-repo.js";
+
+import { product } from "../../shared/product.js";
+// Den-root anchored in lockstep with setup.ts (the .smoke-run writer).
+const PROJECT_ROOT = getDistRoot();
+
+function resolveConfig() {
+  const serviceName = process.env.SMOKE_SERVICE || "api";
+  const repoName = smokeRepoName();
+  const environment = process.env.E2E_ENVIRONMENT || "local";
+
+  // Discover the repo manifest
+  const discovered = findManifest(repoName);
+  if (!discovered) {
+    console.error(
+      `\n❌ Smoke config: no manifest found for repo "${repoName}" in .${product().name}/`,
+    );
+    console.error(`   Run: make smoke-link repo=${repoName}\n`);
+    process.exit(1);
+  }
+
+  const svc = resolveService(discovered, serviceName);
+  if (!svc) {
+    const available = Object.keys(discovered.manifest.smoke ?? {}).join(", ");
+    console.error(
+      `\n❌ Smoke config: service "${serviceName}" not found in ${repoName}/${product().manifestJson}`,
+    );
+    console.error(`   Available services: ${available}\n`);
+    process.exit(1);
+  }
+
+  // Load environment config for the base URL
+  const configPath = path.resolve(
+    PROJECT_ROOT,
+    `config/environments/${environment}.json`,
+  );
+  let envConfig: { baseUrls: { api: string; web: string } };
+  try {
+    envConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  } catch {
+    console.error(
+      `\n❌ Smoke config: no env config found for "${environment}"`,
+    );
+    console.error(`   Expected: config/environments/${environment}.json\n`);
+    process.exit(1);
+  }
+
+  const configuredUrl =
+    svc.baseUrlKey === "api" ? envConfig.baseUrls.api : envConfig.baseUrls.web;
+  const manifestUrl = resolveManifestSmokeBaseUrl({
+    manifest: discovered.manifest,
+    repoName,
+    serviceName,
+    environment: environment as
+      | "local"
+      | "dev"
+      | "sandbox"
+      | "staging"
+      | "production",
+    baseUrlKey: svc.baseUrlKey,
+  });
+  const baseUrl = resolveSmokeBaseUrl({
+    baseUrlKey: svc.baseUrlKey,
+    configuredUrl,
+    manifestUrl,
+    overrideUrl: process.env.BASE_API_URL,
+  });
+
+  // Use the staged test dir (.smoke-run/{repo}-{service}/) which has a
+  // node_modules shim pointing to den's playwright. This prevents the
+  // "Requiring @playwright/test second time" error caused by the repo's own
+  // @playwright/test in node_modules being found during test file loading.
+  const stagingDir = path.resolve(
+    PROJECT_ROOT,
+    `.smoke-run/${repoName}-${serviceName}`,
+  );
+  if (!fs.existsSync(stagingDir)) {
+    console.error(
+      `\n❌ Staging dir not found: .smoke-run/${repoName}-${serviceName}/`,
+    );
+    console.error(
+      `   The setup step runs automatically via make targets. If running`,
+    );
+    console.error(
+      `   playwright directly, run: SMOKE_SERVICE=${serviceName} SMOKE_REPO=${repoName} npx tsx src/pillars/smoke/setup.ts\n`,
+    );
+    process.exit(1);
+  }
+
+  return { svc: { ...svc, testDir: stagingDir }, baseUrl };
+}
+
+const { svc, baseUrl } = resolveConfig();
+
+export default defineConfig({
+  testDir: svc.testDir,
+  testMatch: svc.testMatch,
+
+  globalSetup: enginePath("src/pillars/smoke/global-setup.ts"),
+  globalTeardown: enginePath("src/pillars/smoke/global-teardown.ts"),
+
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+
+  reporter: [
+    [
+      "html",
+      {
+        outputFolder:
+          process.env.PLAYWRIGHT_HTML_REPORT || distPath("playwright-report"),
+        open: "never",
+      },
+    ],
+    ["list"],
+    ["junit", { outputFile: distPath("reports", "junit-smoke-results.xml") }],
+  ],
+
+  use: {
+    baseURL: baseUrl,
+    // JSON headers only for API services; web tests use a headless browser
+    ...(svc.baseUrlKey === "api"
+      ? {
+          extraHTTPHeaders: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+        }
+      : {}),
+    timeout: 30000,
+  },
+
+  projects: [{ name: "smoke", use: {} }],
+
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});

package/src/pillars/smoke/setup-env.ts

@@ -0,0 +1,132 @@
+/**
+ * Smoke Test Environment Setup
+ *
+ * For non-local environments: resolves the exact deployed SHA from the GitHub
+ * Deployments API and ensures the repo is cloned at that SHA inside
+ * .smoke-clones/{repo}/{env}/.
+ *
+ * For local: no-op — the local sibling repo is already linked via .den/.
+ *
+ * Usage (called by buildCommand before the staging step):
+ *   npx tsx src/pillars/smoke/setup-env.ts --env staging [--repo api]
+ *
+ * Multiple --repo flags are accepted for global runs:
+ *   npx tsx src/pillars/smoke/setup-env.ts --env staging --repo api --repo other-repo
+ *
+ * If --repo is omitted, all registered repos with smoke tests are resolved.
+ */
+
+import { discoverRepos, findManifest } from "./discover.js";
+import { resolveDeployedRef } from "../../shared/smoke/branch-resolver.js";
+import { ensureRepoAtSha } from "../../shared/smoke/repo-cloner.js";
+import {
+  getGitHubCoords,
+  getGitRemoteOrigin,
+} from "../../shared/smoke/git-remote.js";
+import type { Environment } from "../../shared/types/index.js";
+
+const LOCAL_ENV: Environment = "local";
+
+function parseArgs(): { environment: Environment; repoNames: string[] } {
+  const args = process.argv.slice(2);
+  let environment: Environment = LOCAL_ENV;
+  const repoNames: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--env" && args[i + 1]) {
+      environment = args[++i] as Environment;
+    } else if (args[i] === "--repo" && args[i + 1]) {
+      repoNames.push(args[++i]);
+    }
+  }
+
+  return { environment, repoNames };
+}
+
+async function main() {
+  const { environment, repoNames } = parseArgs();
+
+  if (environment === LOCAL_ENV) {
+    // Nothing to do — local tests use the sibling repo via .den/ symlink
+    console.log("  ℹ  local environment: using linked repo (no clone needed)");
+    return;
+  }
+
+  // Gather repos to resolve
+  let repos = discoverRepos().filter(
+    (r) =>
+      Object.keys(r.manifest.smoke ?? {}).length > 0 || !!r.manifest.synthetics,
+  );
+
+  if (repoNames.length > 0) {
+    const filtered = repoNames.map((name) => {
+      const found = findManifest(name);
+      if (!found) {
+        console.error(`❌ Repo "${name}" not found. Run: make register-repos`);
+        process.exit(1);
+      }
+      return found;
+    });
+    repos = filtered;
+  }
+
+  if (!repos.length) {
+    console.error(
+      "❌ No repos with smoke tests registered. Run: make register-repos",
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `\n🔍 Resolving deployed branch for ${repos.map((r) => r.repoName).join(", ")} @ ${environment}\n`,
+  );
+
+  for (const repo of repos) {
+    // Derive GitHub owner/repo from the local repo's git remote
+    const coords = getGitHubCoords(repo.repoPath);
+    if (!coords) {
+      console.error(
+        `❌ Cannot determine GitHub owner/repo for "${repo.repoName}". ` +
+          `No git remote origin found at ${repo.repoPath}`,
+      );
+      process.exit(1);
+    }
+
+    // Allow .den.yml to override the GitHub environment name
+    const githubEnv =
+      repo.manifest.github?.environments?.[environment] ?? environment;
+
+    let ref;
+    try {
+      ref = await resolveDeployedRef(coords.owner, coords.repo, githubEnv);
+    } catch (err) {
+      console.error(`❌ ${(err as Error).message}`);
+      process.exit(1);
+    }
+
+    console.log(
+      `  📦 ${repo.repoName}: ${coords.owner}/${coords.repo}@${githubEnv} → ` +
+        `${ref.sha.slice(0, 8)} (${ref.ref}, deployed ${new Date(ref.deployedAt).toLocaleString()})`,
+    );
+
+    // Get the git remote URL from the local symlinked/registered copy
+    const originUrl = getGitRemoteOrigin(repo.repoPath);
+    if (!originUrl) {
+      console.error(
+        `❌ Cannot get git remote origin URL for "${repo.repoName}" at ${repo.repoPath}`,
+      );
+      process.exit(1);
+    }
+
+    ensureRepoAtSha(repo.repoName, environment, originUrl, ref);
+  }
+
+  console.log(
+    `\n✅ All repos cloned/updated for environment "${environment}"\n`,
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/pillars/smoke/setup-global.ts

@@ -0,0 +1,126 @@
+/**
+ * Smoke Test Staging Setup — All Repos
+ *
+ * Stages smoke test files for every service in every registered repo.
+ * Used by: make test-smk-global
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { discoverRepos, resolveRepoPath, resolveService } from "./discover.js";
+import { stageSmokeTree } from "./staging.js";
+import type { Environment } from "../../shared/types/index.js";
+import { getDistRoot } from "../../shared/paths.js";
+
+// Den-root anchored, NOT process.cwd() — bulk writer of .smoke-run (see setup.ts).
+const PROJECT_ROOT = getDistRoot();
+const SMOKE_RUN_DIR = path.resolve(PROJECT_ROOT, ".smoke-run");
+const DEN_MODULES = path.resolve(PROJECT_ROOT, "node_modules");
+
+/** Separator used in staging dir names — must not appear in repo or service names. */
+export const STAGING_SEP = "__";
+
+/** Canonical staging dir for a repo+service pair. */
+export function stagingDirFor(repoName: string, svcName: string): string {
+  return path.join(SMOKE_RUN_DIR, `${repoName}${STAGING_SEP}${svcName}`);
+}
+
+async function main() {
+  const environment = (process.env.E2E_ENVIRONMENT || "local") as Environment;
+  const useLocalCheckout = process.env.USE_LOCAL_CHECKOUT === "1";
+  const repos = discoverRepos();
+  if (!repos.length) {
+    console.error("❌ No repos registered. Run: make register-repos");
+    process.exit(1);
+  }
+
+  let total = 0;
+  const staged: Array<{
+    repo: string;
+    svc: string;
+    dir: string;
+    testMatch: string;
+    baseUrlKey: string;
+  }> = [];
+
+  for (const repo of repos) {
+    const services = Object.keys(repo.manifest.smoke ?? {});
+    if (!services.length) continue;
+
+    // Resolve the staging root for this run: deployed clone by default for
+    // cloud envs, or the registered checkout when explicitly requested.
+    let repoPath: string;
+    try {
+      repoPath = resolveRepoPath(repo, environment, useLocalCheckout);
+    } catch (err) {
+      console.error(`❌ ${(err as Error).message}`);
+      process.exit(1);
+    }
+    const envRepo = { ...repo, repoPath };
+
+    for (const svcName of services) {
+      const svc = resolveService(envRepo, svcName);
+      if (!svc) continue;
+
+      const stagingDir = stagingDirFor(repo.repoName, svcName);
+      fs.rmSync(stagingDir, { recursive: true, force: true });
+      fs.mkdirSync(stagingDir, { recursive: true });
+
+      // Node modules shim — point @playwright/test to den's copy
+      const pwScopeDir = path.join(stagingDir, "node_modules", "@playwright");
+      fs.mkdirSync(pwScopeDir, { recursive: true });
+      fs.symlinkSync(
+        path.join(DEN_MODULES, "@playwright", "test"),
+        path.join(pwScopeDir, "test"),
+      );
+      fs.symlinkSync(
+        path.join(DEN_MODULES, "playwright"),
+        path.join(stagingDir, "node_modules", "playwright"),
+      );
+
+      let count = 0;
+      try {
+        const result = stageSmokeTree(svc.testDir, stagingDir, svc.testMatch);
+        count = result.matchedTestFiles;
+        if (result.matchedTestFiles === 0) {
+          console.warn(
+            `  ⚠  No files matching "${svc.testMatch}" in ${svc.testDir}`,
+          );
+        }
+        console.log(
+          `✅ ${repo.repoName}/${svcName}: staged ${result.matchedTestFiles} smoke test file(s) and ${result.copiedFiles} total file(s) → ${path.basename(stagingDir)}/`,
+        );
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          console.warn(`  ⚠  testDir not found, skipping: ${svc.testDir}`);
+          continue;
+        }
+        throw error;
+      }
+      staged.push({
+        repo: repo.repoName,
+        svc: svcName,
+        dir: stagingDir,
+        testMatch: svc.testMatch,
+        baseUrlKey: svc.baseUrlKey ?? "api",
+      });
+      total += count;
+    }
+  }
+
+  // Write a manifest so playwright-global.config.ts reads exactly what was staged
+  // (avoids a second discoverRepos() call that could diverge)
+  fs.writeFileSync(
+    path.join(SMOKE_RUN_DIR, "global-manifest.json"),
+    JSON.stringify(staged, null, 2),
+  );
+
+  console.log(
+    `\n  Total: ${total} smoke test file(s) staged across ${repos.length} repo(s)\n`,
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/pillars/smoke/setup.ts

@@ -0,0 +1,115 @@
+/**
+ * Smoke Test Staging Setup
+ *
+ * Creates .smoke-run/{repo}-{service}/ before each test run:
+ *
+ *   1. Copies all *.smoke.ts files from the repo's testDir
+ *   2. Creates node_modules/@playwright/test → den's playwright
+ *   3. Creates node_modules/playwright → den's playwright
+ *
+ * Why: service repos usually have their own @playwright/test in
+ * node_modules. If Playwright's test runner loads test files from those
+ * directories, Node resolves @playwright/test to the repo's copy — which is
+ * a different module instance than the runner's, causing the "Requiring
+ * @playwright/test second time" error.
+ *
+ * Staging the files inside den (with a node_modules shim) ensures
+ * there is exactly one @playwright/test instance: den's.
+ *
+ * The staged dir is gitignored (.smoke-run/) and re-created fresh each run.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { findManifest, resolveRepoPath, resolveService } from "./discover.js";
+import { stageSmokeTree } from "./staging.js";
+import type { Environment } from "../../shared/types/index.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { smokeRepoName } from "./smoke-repo.js";
+
+import { product } from "../../shared/product.js";
+// Den-root anchored, NOT process.cwd(): this stages (rm -rf + mkdir +
+// symlink + tree-copy) .smoke-run, and CLI-spawned runs inherit the user's cwd.
+const PROJECT_ROOT = getDistRoot();
+const SMOKE_RUN_DIR = path.resolve(PROJECT_ROOT, ".smoke-run");
+const ENGINE_MODULES = path.resolve(PROJECT_ROOT, "node_modules");
+
+async function main() {
+  const serviceName = process.env.SMOKE_SERVICE || "api";
+  const repoName = smokeRepoName();
+  const environment = (process.env.E2E_ENVIRONMENT || "local") as Environment;
+  const useLocalCheckout = process.env.USE_LOCAL_CHECKOUT === "1";
+
+  const discovered = findManifest(repoName);
+  if (!discovered) {
+    console.error(
+      `❌ No manifest found for repo "${repoName}" in .${product().name}/`,
+    );
+    console.error(`   Run: make smoke-link repo=${repoName}`);
+    process.exit(1);
+  }
+
+  // Non-local smoke runs stage from the deployed clone by default. Set
+  // USE_LOCAL_CHECKOUT=1 to stage from the registered checkout instead.
+  let repoPath: string;
+  try {
+    repoPath = resolveRepoPath(discovered, environment, useLocalCheckout);
+  } catch (err) {
+    console.error(`❌ ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  // Re-resolve the service from the selected staging root so testDir points
+  // into either the deployed clone or the registered checkout.
+  const envDiscovered = { ...discovered, repoPath };
+  const svc = resolveService(envDiscovered, serviceName);
+  if (!svc) {
+    const available = Object.keys(discovered.manifest.smoke ?? {}).join(", ");
+    console.error(
+      `❌ Service "${serviceName}" not found in ${repoName}/${product().manifestJson}`,
+    );
+    console.error(`   Available: ${available}`);
+    process.exit(1);
+  }
+
+  const stagingDir = path.join(SMOKE_RUN_DIR, `${repoName}-${serviceName}`);
+
+  // Clean and recreate staging dir
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+  fs.mkdirSync(stagingDir, { recursive: true });
+
+  // ── Node modules shim ──────────────────────────────────────────────────
+  // Symlink den's playwright into the staging dir's node_modules so
+  // that any @playwright/test import in copied test files resolves to the
+  // runner's copy, not the repo's own copy.
+  const nmDir = path.join(stagingDir, "node_modules");
+  const pwScopeDir = path.join(nmDir, "@playwright");
+  fs.mkdirSync(pwScopeDir, { recursive: true });
+
+  const pwTestSrc = path.join(ENGINE_MODULES, "@playwright", "test");
+  const pwTestDst = path.join(pwScopeDir, "test");
+  fs.symlinkSync(pwTestSrc, pwTestDst);
+
+  const pwSrc = path.join(ENGINE_MODULES, "playwright");
+  const pwDst = path.join(nmDir, "playwright");
+  fs.symlinkSync(pwSrc, pwDst);
+
+  // ── Copy test tree ─────────────────────────────────────────────────────
+  // Copy the full testDir so smoke tests can import shared helper modules
+  // that do not themselves match `testMatch`.
+  const result = stageSmokeTree(svc.testDir, stagingDir, svc.testMatch);
+  if (result.matchedTestFiles === 0) {
+    console.warn(
+      `  ⚠  No files matching "${svc.testMatch}" found in ${svc.testDir}`,
+    );
+  }
+
+  console.log(
+    `✅ Staged ${result.matchedTestFiles} smoke test file(s) and ${result.copiedFiles} total file(s) → .smoke-run/${repoName}-${serviceName}/`,
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/pillars/smoke/smoke-repo.ts

@@ -0,0 +1,16 @@
+/**
+ * The repo a smoke run targets. Always named by the caller (`make
+ * test-smoke repo=<name>` / the web UI set SMOKE_REPO); the engine has no
+ * default repo, so a missing name fails loudly instead of guessing one.
+ */
+export function smokeRepoName(env: NodeJS.ProcessEnv = process.env): string {
+  const name = env.SMOKE_REPO?.trim();
+  if (!name) {
+    console.error(
+      "\n❌ SMOKE_REPO is not set: name the repo whose smoke tests to run " +
+        "(make test-smoke repo=<name>).\n",
+    );
+    process.exit(1);
+  }
+  return name;
+}