@bugmole/cli 0.4.0

package/src/runtime/web-suite.test.ts

@@ -0,0 +1,97 @@
+import { strict as assert } from "node:assert";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { journeyIdFor, listFlowFiles, runWebSuite, summarize } from "./web-suite.js";
+
+async function flowDir(names: readonly string[]): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-suite-"));
+  for (const name of names) await fs.writeFile(path.join(dir, name), "url: http://localhost\n---\n- launchApp\n", "utf8");
+  return dir;
+}
+
+test("flows run in file-name order so a numbered suite reads as one journey", async () => {
+  const dir = await flowDir(["02-second.yaml", "01-first.yaml", "notes.md", "03-third.yml"]);
+  assert.deepEqual((await listFlowFiles(dir)).map(journeyIdFor), ["01-first", "02-second", "03-third"]);
+});
+
+test("grep narrows a suite to one journey", async () => {
+  const dir = await flowDir(["01-viewer.yaml", "02-creator-editor.yaml"]);
+  assert.deepEqual((await listFlowFiles(dir, "creator")).map(journeyIdFor), ["02-creator-editor"]);
+});
+
+test("grep accepts several journeys so a debugging run can include sign-in", async () => {
+  const dir = await flowDir(["01-signin.yaml", "02-editor.yaml", "03-billing.yaml"]);
+  assert.deepEqual((await listFlowFiles(dir, "signin, editor")).map(journeyIdFor), ["01-signin", "02-editor"]);
+});
+
+test("an empty flow directory is an error, not a vacuous pass", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-suite-empty-"));
+  await assert.rejects(
+    runWebSuite({ flowsDir: dir, baseUrl: "http://localhost", artifactsDir: dir, projectId: "demo" }),
+    /No flow files found/,
+  );
+});
+
+test("totals count every outcome", () => {
+  const totals = summarize([
+    { journeyId: "a", flowPath: "a", status: "passed", message: "", durationMs: 1, artifacts: [] },
+    { journeyId: "b", flowPath: "b", status: "failed", message: "", durationMs: 1, artifacts: [] },
+    { journeyId: "c", flowPath: "c", status: "blocked", message: "", durationMs: 1, artifacts: [] },
+  ]);
+  assert.deepEqual(totals, { total: 3, passed: 1, failed: 1, blocked: 1 });
+});
+
+test("typed secrets never reach the uploaded log, and the shared session is deleted after the suite", async (t) => {
+  const { chromium } = await import("playwright");
+  try {
+    await fs.access(chromium.executablePath());
+  } catch {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const http = await import("node:http");
+  const server = http.createServer((_request, response) => {
+    response.writeHead(200, { "content-type": "text/html", "set-cookie": "session=abc; Path=/" });
+    response.end('<!doctype html><label>Password <input type="password" name="pw"></label><p>Welcome</p>');
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-suite-secret-"));
+  const flows = path.join(dir, "flows");
+  await fs.mkdir(flows);
+  await fs.writeFile(path.join(flows, "01-signin.yaml"), [
+    "name: signin",
+    "---",
+    "- launchApp",
+    '- tapOn: "Password"',
+    '- inputText: "{{secret.SUITE_PASSWORD}}"',
+    '- inputText: "literal-hunter2"',
+    '- assertVisible: "Welcome"',
+    "",
+  ].join("\n"));
+  process.env.BUGMOLE_FLOW_SECRET_SUITE_PASSWORD = "env-hunter2";
+  try {
+    const report = await runWebSuite({
+      flowsDir: flows,
+      baseUrl: `http://127.0.0.1:${port}/`,
+      artifactsDir: path.join(dir, "artifacts"),
+      projectId: "demo",
+      runId: "run-secret",
+      shareSession: true,
+    });
+    assert.equal(report.totals.passed, 1, report.flows[0]?.message);
+    const logPath = report.flows[0].artifacts.find((file) => file.endsWith("playwright.log"));
+    assert.ok(logPath);
+    const log = await fs.readFile(logPath, "utf8");
+    assert.doesNotMatch(log, /hunter2/);
+    assert.match(log, /inputText/);
+    assert.doesNotMatch(JSON.stringify(report), /hunter2/);
+    await assert.rejects(fs.access(path.join(dir, "artifacts", "demo", "run-secret", "session-state.json")));
+  } finally {
+    delete process.env.BUGMOLE_FLOW_SECRET_SUITE_PASSWORD;
+    server.close();
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/web-suite.ts

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { PlaywrightDriver } from "./playwright-driver.js";
+import type { DriverResult } from "./driver.js";
+import { targetLabel, type RunTarget } from "./browser-matrix.js";
+import { resolveTargetConcurrency, runPool } from "./target-runner.js";
+
+export interface WebSuiteOptions {
+  flowsDir: string;
+  baseUrl: string;
+  artifactsDir: string;
+  projectId: string;
+  runId?: string;
+  headless?: boolean;
+  timeoutMs?: number;
+  /**
+   * Comma-separated substrings matched against flow file names, for re-running
+   * part of a suite. Include the sign-in flow when the suite shares a session.
+   */
+  grep?: string;
+  /**
+   * Carry cookies and local storage from one flow to the next, so a numbered
+   * suite reads as one continuous session (sign in once, then keep working).
+   * Off by default: independent flows must not prop each other up.
+   */
+  shareSession?: boolean;
+  /**
+   * Browsers/devices to run the suite on. Each target runs the flows in order
+   * in its own session; targets run in parallel. Omit for desktop Chromium.
+   */
+  targets?: RunTarget[];
+  concurrency?: number;
+}
+
+export interface WebSuiteFlowResult {
+  journeyId: string;
+  /** Set when the suite ran across a browser/device matrix. */
+  targetId?: string;
+  flowPath: string;
+  status: DriverResult["status"];
+  message: string;
+  failureCode?: string;
+  durationMs: number;
+  artifacts: string[];
+}
+
+export interface WebSuiteReport {
+  projectId: string;
+  runId: string;
+  baseUrl: string;
+  targets?: RunTarget[];
+  startedAt: string;
+  finishedAt: string;
+  totals: { total: number; passed: number; failed: number; blocked: number };
+  flows: WebSuiteFlowResult[];
+  reportPath: string;
+}
+
+/** Flow files run in file-name order so a suite reads as a numbered journey. */
+export async function listFlowFiles(flowsDir: string, grep?: string): Promise<string[]> {
+  const patterns = (grep ?? "").split(",").map((pattern) => pattern.trim()).filter(Boolean);
+  const entries = await fs.readdir(flowsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
+    .map((entry) => entry.name)
+    .filter((name) => patterns.length === 0 || patterns.some((pattern) => name.includes(pattern)))
+    .sort((left, right) => left.localeCompare(right, "en"))
+    .map((name) => path.join(flowsDir, name));
+}
+
+export function journeyIdFor(flowPath: string): string {
+  return path.basename(flowPath).replace(/\.ya?ml$/i, "");
+}
+
+export function summarize(flows: readonly WebSuiteFlowResult[]) {
+  return {
+    total: flows.length,
+    passed: flows.filter((flow) => flow.status === "passed").length,
+    failed: flows.filter((flow) => flow.status === "failed").length,
+    blocked: flows.filter((flow) => flow.status === "blocked").length,
+  };
+}
+
+/**
+ * Runs every flow in a directory against one base URL and writes a JSON
+ * report next to the run's artifacts.
+ *
+ * Flows run sequentially and each one gets its own browser context, so a
+ * journey that leaves state behind cannot silently prop up the next one --
+ * unless `shareSession` opts the suite into one continuous signed-in session.
+ */
+export async function runWebSuite(options: WebSuiteOptions): Promise<WebSuiteReport> {
+  const runId = options.runId ?? `suite-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  const flowPaths = await listFlowFiles(options.flowsDir, options.grep);
+  if (flowPaths.length === 0) {
+    throw new Error(`No flow files found in ${options.flowsDir}${options.grep ? ` matching "${options.grep}"` : ""}.`);
+  }
+
+  const driver = new PlaywrightDriver({ headless: options.headless ?? true });
+  const startedAt = new Date().toISOString();
+  const targets = options.targets?.length ? options.targets : undefined;
+
+  const sessionStatePaths: string[] = [];
+  const runLane = async (target: RunTarget | undefined): Promise<WebSuiteFlowResult[]> => {
+    const results: WebSuiteFlowResult[] = [];
+    // Scoped to the run (and target): a suite must start from a clean browser
+    // every time, or yesterday's cookies and saved drafts quietly become this
+    // run's fixtures. Use --grep with the sign-in flow included to debug a
+    // single journey.
+    const sessionStatePath = options.shareSession
+      ? path.join(options.artifactsDir, options.projectId, runId, ...(target ? [target.id] : []), "session-state.json")
+      : undefined;
+    if (sessionStatePath) {
+      sessionStatePaths.push(sessionStatePath);
+      await fs.mkdir(path.dirname(sessionStatePath), { recursive: true });
+    }
+
+    for (const flowPath of flowPaths) {
+      const journeyId = journeyIdFor(flowPath);
+      const startedMs = Date.now();
+      const result = await driver.run({
+        runId,
+        projectId: options.projectId,
+        journeyId,
+        flowPath,
+        platform: "web",
+        target: { baseUrl: options.baseUrl },
+        timeoutMs: options.timeoutMs ?? 30_000,
+        artifactsDir: options.artifactsDir,
+        sessionStatePath,
+        ...(target ? { runTarget: target } : {}),
+      });
+      results.push({
+        journeyId,
+        ...(target ? { targetId: target.id } : {}),
+        flowPath,
+        status: result.status,
+        message: result.message,
+        failureCode: result.failureCode,
+        durationMs: result.durationMs ?? Date.now() - startedMs,
+        artifacts: result.artifacts.map((artifact) => artifact.path),
+      });
+      const icon = result.status === "passed" ? "PASS" : result.status === "blocked" ? "BLOCK" : "FAIL";
+      console.log(`${icon} ${target ? `[${targetLabel(target)}] ` : ""}${journeyId} — ${result.message}`);
+    }
+    return results;
+  };
+
+  let flows: WebSuiteFlowResult[];
+  try {
+    flows = targets
+      ? (await runPool(targets, resolveTargetConcurrency(options.concurrency, targets.length), (target) => runLane(target))).flat()
+      : await runLane(undefined);
+  } finally {
+    // The shared session holds the app's cookies and tokens; it exists only
+    // to carry sign-in between flows and must not outlive the suite.
+    await Promise.all(sessionStatePaths.map((file) => fs.rm(file, { force: true })));
+  }
+
+  const runDir = path.join(options.artifactsDir, options.projectId, runId);
+  await fs.mkdir(runDir, { recursive: true });
+  const reportPath = path.join(runDir, "web-suite-report.json");
+  const report: WebSuiteReport = {
+    projectId: options.projectId,
+    runId,
+    baseUrl: options.baseUrl,
+    ...(targets ? { targets } : {}),
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    totals: summarize(flows),
+    flows,
+    reportPath,
+  };
+  await fs.writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  return report;
+}

package/src/storage/create-object-store.ts

@@ -0,0 +1,144 @@
+import { Storage } from "@google-cloud/storage";
+import { LocalObjectStore, type ObjectStore, type StorageProvider, type StoredObject } from "./object-store.js";
+import { S3ObjectStore } from "./remote-object-store.js";
+import { RegistryObjectStore } from "./registry-object-store.js";
+import { resolveLocalStorageDirectory, type StorageSettings } from "./storage-directory.js";
+
+export { resolveLocalStorageDirectory, type StorageSettings };
+
+class GcsObjectStore implements ObjectStore {
+  readonly provider = "gcs" as const;
+  private readonly bucket;
+
+  constructor(bucketName: string, projectId?: string, credentialsJson?: string) {
+    const storage = new Storage({
+      projectId,
+      credentials: credentialsJson ? JSON.parse(credentialsJson) : undefined,
+    });
+    this.bucket = storage.bucket(bucketName);
+  }
+
+  async put(key: string, body: string | Uint8Array, contentType?: string): Promise<StoredObject> {
+    const file = this.bucket.file(key);
+    await file.save(body, { resumable: false, contentType });
+    const [metadata] = await file.getMetadata();
+    return { key, size: Number(metadata.size ?? 0), modifiedAt: metadata.updated ?? new Date().toISOString(), contentType };
+  }
+
+  async get(key: string): Promise<Uint8Array> {
+    const [body] = await this.bucket.file(key).download();
+    return new Uint8Array(body);
+  }
+
+  async getText(key: string): Promise<string> {
+    return new TextDecoder().decode(await this.get(key));
+  }
+
+  async has(key: string): Promise<boolean> {
+    const [exists] = await this.bucket.file(key).exists();
+    return exists;
+  }
+
+  async list(prefix: string): Promise<StoredObject[]> {
+    const [files] = await this.bucket.getFiles({ prefix });
+    return files.map((file) => ({
+      key: file.name,
+      size: Number(file.metadata.size ?? 0),
+      modifiedAt: file.metadata.updated ?? new Date(0).toISOString(),
+      contentType: file.metadata.contentType,
+    }));
+  }
+
+  async deletePrefix(prefix: string): Promise<void> {
+    const [files] = await this.bucket.getFiles({ prefix });
+    await Promise.all(files.map((file) => file.delete()));
+  }
+
+  async publicUrl(key: string, expiresInSeconds = 300): Promise<string> {
+    const [url] = await this.bucket.file(key).getSignedUrl({
+      action: "read",
+      expires: Date.now() + expiresInSeconds * 1000,
+    });
+    return url;
+  }
+}
+
+export type ObjectStoreConfig = {
+  provider: StorageProvider;
+  local?: { directory?: string };
+  gcs?: { bucket?: string; project_id?: string; credentials_json?: string };
+  s3?: { bucket?: string; region?: string; endpoint?: string; access_key_id?: string; secret_access_key?: string };
+  r2?: { bucket?: string; account_id?: string; endpoint?: string; access_key_id?: string; secret_access_key?: string };
+  bugmole?: { registry_url?: string; project_id?: string };
+  localDirectory?: string;
+  /** The Bugmole project whose managed storage to use. */
+  bugmoleProjectId?: string;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  accountId?: string;
+  projectId?: string;
+  credentialsJson?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+};
+
+/** Rewrites a pre-rename `provider: valkyrie` config (and its `valkyrie:` block) to `bugmole`. */
+function withCurrentProviderName(cfg: StorageSettings): StorageSettings {
+  const storage = cfg.storage as (Record<string, unknown> & { provider?: string }) | undefined;
+  if (storage?.provider !== "valkyrie") return cfg;
+  const { valkyrie, ...rest } = storage;
+  return { ...cfg, storage: { ...rest, provider: "bugmole", ...(valkyrie ? { bugmole: valkyrie } : {}) } as StorageSettings["storage"] };
+}
+
+/** The project's storage config, with a local store's directory filled in. */
+export function resolveStorageConfig(cfg: StorageSettings, fallback = "./runs"): ObjectStoreConfig {
+  cfg = withCurrentProviderName(cfg);
+  const provider = cfg.storage?.provider ?? "local";
+  if (provider === "bugmole") return { ...(cfg.storage as ObjectStoreConfig), bugmoleProjectId: cfg.project?.id };
+  if (provider !== "local") return cfg.storage as ObjectStoreConfig;
+  return { ...cfg.storage, provider, localDirectory: resolveLocalStorageDirectory(cfg, fallback) };
+}
+
+/** Opens the project's configured object store. */
+export function createProjectObjectStore(cfg: StorageSettings, fallback = "./runs"): ObjectStore {
+  return createObjectStore(resolveStorageConfig(cfg, fallback));
+}
+
+export function createObjectStore(config: ObjectStoreConfig): ObjectStore {
+  const nested = (config as Record<string, unknown>)[config.provider] as Record<string, string | undefined> | undefined;
+  const value = (name: string, fallback?: string) => nested?.[name] ?? fallback;
+  if (config.provider === "local") {
+    return new LocalObjectStore(value("directory", config.localDirectory) ?? "./qa/bugmole-runs");
+  }
+  if (config.provider === "bugmole") {
+    const registryUrl = value("registry_url") || process.env.BUGMOLE_REGISTRY_URL?.trim();
+    // A hosted runner carries a run token; everything else uses the project's API key.
+    const token = process.env.BUGMOLE_RUN_TOKEN?.trim() || process.env.BUGMOLE_API_KEY?.trim();
+    const projectId = value("project_id", config.bugmoleProjectId);
+    if (!registryUrl || !token || !projectId) {
+      throw new Error("Bugmole storage needs BUGMOLE_REGISTRY_URL, an API key (BUGMOLE_API_KEY), and the project id");
+    }
+    return new RegistryObjectStore({ registryUrl, token, projectId });
+  }
+  const bucket = value("bucket", config.bucket);
+  if (!bucket) throw new Error(`${config.provider} storage requires a bucket`);
+  if (config.provider === "gcs") {
+    return new GcsObjectStore(bucket, value("project_id", config.projectId), value("credentials_json", config.credentialsJson));
+  }
+  const accessKeyId = value("access_key_id", config.accessKeyId);
+  const secretAccessKey = value("secret_access_key", config.secretAccessKey);
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error(`${config.provider} storage requires access key credentials`);
+  }
+  return new S3ObjectStore({
+    provider: config.provider,
+    bucket,
+    region: value("region", config.region) ?? (config.provider === "r2" ? "auto" : "us-east-1"),
+    endpoint: value("endpoint", config.endpoint) ?? (config.provider === "r2" && (value("account_id", config.accountId))
+      ? `https://${value("account_id", config.accountId)}.r2.cloudflarestorage.com`
+      : undefined),
+    accessKeyId,
+    secretAccessKey,
+  });
+}

package/src/storage/keys.ts

@@ -0,0 +1,34 @@
+export function projectPrefix(projectId: string): string {
+  return `projects/${encodeURIComponent(projectId)}`;
+}
+
+export function runPrefix(projectId: string, runId: string): string {
+  return `${projectPrefix(projectId)}/runs/${encodeURIComponent(runId)}`;
+}
+
+export function runKey(projectId: string, runId: string, name: string): string {
+  return `${runPrefix(projectId, runId)}/${name.replace(/^\/+/, "")}`;
+}
+
+export type RunManifest = {
+  version: 1;
+  projectId: string;
+  tenantId?: string;
+  environmentId?: string;
+  runId: string;
+  planId: string;
+  journeyId: string;
+  driver?: string;
+  platform?: string;
+  failureCode?: string;
+  recoveryAttempts?: number;
+  status: "success" | "error" | "partial";
+  startedAt: string;
+  completedAt: string;
+  stepsExecuted: number;
+  stepsPassed: number;
+  stepsFailed: number;
+  artifacts: Array<{ key: string; contentType?: string; size?: number }>;
+  /** Per browser/device results when the run fanned out across a matrix. */
+  targets?: Array<Record<string, unknown>>;
+};