@bugmole/cli 0.4.0

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

@@ -0,0 +1,28 @@
+import { strict as assert } from "node:assert";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { LocalObjectStore, normalizeKey } from "./object-store.js";
+
+describe("local object store contract", () => {
+  it("writes, reads, lists, and deletes provider-neutral keys", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "bugmole-store-"));
+    try {
+      const store = new LocalObjectStore(root);
+      await store.put("projects/demo/runs/run-1/manifest.json", '{"runId":"run-1"}', "application/json");
+      await store.put("projects/demo/runs/run-1/evidence/shot.png", new Uint8Array([1, 2, 3]), "image/png");
+      assert.equal(await store.getText("projects/demo/runs/run-1/manifest.json"), '{"runId":"run-1"}');
+      assert.equal((await store.list("projects/demo/runs/run-1/")).length, 2);
+      await store.deletePrefix("projects/demo/runs/run-1");
+      assert.equal(await store.has("projects/demo/runs/run-1/manifest.json"), false);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects traversal keys", () => {
+    assert.throws(() => normalizeKey("../secret"));
+    assert.throws(() => normalizeKey("projects/./secret"));
+  });
+});

package/src/storage/object-store.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** "bugmole" is Bugmole-managed storage, reached through the registry. */
+export type StorageProvider = "local" | "gcs" | "s3" | "r2" | "bugmole";
+
+export type StoredObject = {
+  key: string;
+  size: number;
+  modifiedAt: string;
+  contentType?: string;
+};
+
+export type ObjectStore = {
+  provider: StorageProvider;
+  put(key: string, body: string | Uint8Array, contentType?: string): Promise<StoredObject>;
+  get(key: string): Promise<Uint8Array>;
+  getText(key: string): Promise<string>;
+  has(key: string): Promise<boolean>;
+  list(prefix: string): Promise<StoredObject[]>;
+  deletePrefix(prefix: string): Promise<void>;
+  publicUrl?(key: string, expiresInSeconds?: number): Promise<string>;
+};
+
+export function normalizeKey(key: string): string {
+  const normalized = key.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (!normalized || normalized.split("/").some((part) => part === ".." || part === ".")) {
+    throw new Error(`Invalid storage key: ${key}`);
+  }
+  return normalized;
+}
+
+export class LocalObjectStore implements ObjectStore {
+  readonly provider = "local" as const;
+
+  constructor(private readonly root: string) {}
+
+  private filePath(key: string): string {
+    return path.join(this.root, normalizeKey(key));
+  }
+
+  async put(key: string, body: string | Uint8Array, contentType?: string): Promise<StoredObject> {
+    const filePath = this.filePath(key);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, body);
+    const stat = await fs.stat(filePath);
+    return { key: normalizeKey(key), size: stat.size, modifiedAt: stat.mtime.toISOString(), contentType };
+  }
+
+  async get(key: string): Promise<Uint8Array> {
+    return fs.readFile(this.filePath(key));
+  }
+
+  async getText(key: string): Promise<string> {
+    return fs.readFile(this.filePath(key), "utf8");
+  }
+
+  async has(key: string): Promise<boolean> {
+    try {
+      await fs.access(this.filePath(key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(prefix: string): Promise<StoredObject[]> {
+    const root = this.filePath(prefix);
+    const results: StoredObject[] = [];
+    const walk = async (directory: string) => {
+      let entries;
+      try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) await walk(absolute);
+        else {
+          const stat = await fs.stat(absolute);
+          results.push({
+            key: normalizeKey(path.relative(this.root, absolute)),
+            size: stat.size,
+            modifiedAt: stat.mtime.toISOString(),
+          });
+        }
+      }
+    };
+    await walk(root);
+    return results.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+  }
+
+  async deletePrefix(prefix: string): Promise<void> {
+    await fs.rm(this.filePath(prefix), { recursive: true, force: true });
+  }
+}
+
+export function json(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}

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

@@ -0,0 +1,88 @@
+import type { ObjectStore, StoredObject } from "./object-store.js";
+import { normalizeKey } from "./object-store.js";
+
+export type RegistryObjectStoreOptions = {
+  registryUrl: string;
+  /** A project API key, or a hosted runner's run token. */
+  token: string;
+  projectId: string;
+  fetch?: typeof fetch;
+};
+
+/**
+ * Bugmole-managed storage. Objects live in Bugmole's bucket and are read and
+ * written through the registry, so neither the CLI nor a hosted runner holds
+ * bucket credentials.
+ */
+export class RegistryObjectStore implements ObjectStore {
+  readonly provider = "bugmole" as const;
+  private readonly base: string;
+  private readonly doFetch: typeof fetch;
+
+  constructor(private readonly options: RegistryObjectStoreOptions) {
+    this.base = `${options.registryUrl.replace(/\/$/, "")}/api/projects/${encodeURIComponent(options.projectId)}/artifacts`;
+    this.doFetch = options.fetch ?? fetch;
+  }
+
+  private async request(path: string, params: Record<string, string>, init: RequestInit = {}): Promise<Response> {
+    const url = `${this.base}${path}?${new URLSearchParams(params)}`;
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${this.options.token}`);
+    return this.doFetch(url, { ...init, headers });
+  }
+
+  private async fail(response: Response, action: string): Promise<never> {
+    const body = await response.json().catch(() => ({})) as { error?: string };
+    throw new Error(`Bugmole storage couldn't ${action} (${response.status})${body.error ? `: ${body.error}` : ""}`);
+  }
+
+  async put(key: string, body: string | Uint8Array, contentType?: string): Promise<StoredObject> {
+    const normalized = normalizeKey(key);
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    const response = await this.request("/object", { key: normalized }, {
+      method: "PUT",
+      headers: { "content-type": contentType ?? "application/octet-stream" },
+      body: bytes,
+    });
+    if (!response.ok) await this.fail(response, `save ${normalized}`);
+    return { key: normalized, size: bytes.byteLength, modifiedAt: new Date().toISOString(), contentType };
+  }
+
+  async get(key: string): Promise<Uint8Array> {
+    const normalized = normalizeKey(key);
+    const response = await this.request("/object", { key: normalized });
+    if (!response.ok) await this.fail(response, `read ${normalized}`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  async getText(key: string): Promise<string> {
+    return new TextDecoder().decode(await this.get(key));
+  }
+
+  async has(key: string): Promise<boolean> {
+    const response = await this.request("/object", { key: normalizeKey(key) });
+    if (response.status === 404) return false;
+    if (!response.ok) await this.fail(response, `check ${key}`);
+    await response.body?.cancel();
+    return true;
+  }
+
+  async list(prefix: string): Promise<StoredObject[]> {
+    const objects: StoredObject[] = [];
+    let cursor: string | undefined;
+    do {
+      const response = await this.request("", { prefix: normalizeKey(prefix), ...(cursor ? { cursor } : {}) });
+      if (!response.ok) await this.fail(response, `list ${prefix}`);
+      const page = await response.json() as { objects: StoredObject[]; cursor?: string };
+      objects.push(...page.objects);
+      cursor = page.cursor;
+    } while (cursor);
+    return objects;
+  }
+
+  async deletePrefix(prefix: string): Promise<void> {
+    const folder = normalizeKey(prefix).replace(/\/?$/, "/");
+    const response = await this.request("", { prefix: folder }, { method: "DELETE" });
+    if (!response.ok) await this.fail(response, `delete ${folder}`);
+  }
+}

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

@@ -0,0 +1,104 @@
+import {
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  DeleteObjectsCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import type { ObjectStore, StorageProvider, StoredObject } from "./object-store.js";
+
+type S3Options = {
+  provider: "s3" | "r2";
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+};
+
+export class S3ObjectStore implements ObjectStore {
+  readonly provider: StorageProvider;
+  private readonly client: S3Client;
+
+  constructor(private readonly options: S3Options) {
+    this.provider = options.provider;
+    this.client = new S3Client({
+      region: options.region,
+      endpoint: options.endpoint,
+      forcePathStyle: Boolean(options.endpoint),
+      credentials: {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+      },
+    });
+  }
+
+  async put(key: string, body: string | Uint8Array, contentType?: string): Promise<StoredObject> {
+    const normalized = key.replaceAll("\\", "/").replace(/^\/+/, "");
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.options.bucket,
+      Key: normalized,
+      Body: body,
+      ContentType: contentType,
+    }));
+    return { key: normalized, size: typeof body === "string" ? Buffer.byteLength(body) : body.byteLength, modifiedAt: new Date().toISOString(), contentType };
+  }
+
+  async get(key: string): Promise<Uint8Array> {
+    const result = await this.client.send(new GetObjectCommand({ Bucket: this.options.bucket, Key: key }));
+    if (!result.Body) throw new Error(`Object has no body: ${key}`);
+    return new Uint8Array(await result.Body.transformToByteArray());
+  }
+
+  async getText(key: string): Promise<string> {
+    return new TextDecoder().decode(await this.get(key));
+  }
+
+  async has(key: string): Promise<boolean> {
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: this.options.bucket, Key: key }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async list(prefix: string): Promise<StoredObject[]> {
+    const results: StoredObject[] = [];
+    let token: string | undefined;
+    do {
+      const page = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.options.bucket,
+        Prefix: prefix,
+        ContinuationToken: token,
+      }));
+      for (const item of page.Contents ?? []) {
+        if (item.Key) results.push({
+          key: item.Key,
+          size: item.Size ?? 0,
+          modifiedAt: (item.LastModified ?? new Date(0)).toISOString(),
+        });
+      }
+      token = page.IsTruncated ? page.NextContinuationToken : undefined;
+    } while (token);
+    return results;
+  }
+
+  async deletePrefix(prefix: string): Promise<void> {
+    const objects = await this.list(prefix);
+    if (objects.length) {
+      await this.client.send(new DeleteObjectsCommand({
+        Bucket: this.options.bucket,
+        Delete: { Objects: objects.map(({ key }) => ({ Key: key })) },
+      }));
+    }
+  }
+
+  async publicUrl(key: string, expiresInSeconds = 300): Promise<string> {
+    return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.options.bucket, Key: key }), {
+      expiresIn: expiresInSeconds,
+    });
+  }
+}

package/src/storage/storage-directory.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { createProjectObjectStore, resolveStorageConfig } from "./create-object-store.js";
+import { resolveLocalStorageDirectory } from "./storage-directory.js";
+
+test("a local store without a directory lives in runtime.artifacts_dir", () => {
+  const cfg = { storage: { provider: "local" }, runtime: { artifacts_dir: "/tmp/bugmole-artifacts" } };
+  assert.equal(resolveLocalStorageDirectory(cfg), "/tmp/bugmole-artifacts");
+  assert.equal(resolveStorageConfig(cfg).localDirectory, "/tmp/bugmole-artifacts");
+  // No storage block at all resolves the same way.
+  assert.equal(resolveLocalStorageDirectory({ runtime: { artifacts_dir: "/tmp/bugmole-artifacts" } }), "/tmp/bugmole-artifacts");
+});
+
+test("an explicit local directory wins over artifacts_dir", () => {
+  const runtime = { artifacts_dir: "/tmp/bugmole-artifacts" };
+  assert.equal(resolveLocalStorageDirectory({ storage: { provider: "local", local: { directory: "/data/store" } }, runtime }), "/data/store");
+  assert.equal(resolveLocalStorageDirectory({ storage: { provider: "local", localDirectory: "/data/flat" }, runtime }), "/data/flat");
+});
+
+test("falls back only when nothing is configured", () => {
+  assert.equal(resolveLocalStorageDirectory({}), "./runs");
+  assert.equal(resolveLocalStorageDirectory({}, "./artifacts"), "./artifacts");
+});
+
+test("remote providers are passed through untouched", () => {
+  const storage = { provider: "r2" as const, r2: { bucket: "evidence" } };
+  assert.equal(resolveStorageConfig({ storage, runtime: { artifacts_dir: "/tmp/x" } }), storage);
+});
+
+test("objects written through the project store land where the artifact bridge reads", async () => {
+  const artifactsDir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-storage-dir-"));
+  try {
+    const cfg = { storage: { provider: "local" }, runtime: { artifacts_dir: artifactsDir } };
+    await createProjectObjectStore(cfg).put("projects/demo/runs/run-1/artifacts/chromium/final.png", "png", "image/png");
+    const written = path.join(resolveLocalStorageDirectory(cfg), "projects/demo/runs/run-1/artifacts/chromium/final.png");
+    assert.equal(await fs.readFile(written, "utf8"), "png");
+  } finally {
+    await fs.rm(artifactsDir, { recursive: true, force: true });
+  }
+});

package/src/storage/storage-directory.ts

@@ -0,0 +1,24 @@
+// Kept free of storage SDK imports so the CLI can resolve the directory
+// without loading every provider at startup.
+
+export type StorageSettings = {
+  storage?: {
+    provider?: string;
+    local?: { directory?: string };
+    localDirectory?: string;
+    [key: string]: unknown;
+  };
+  runtime?: { artifacts_dir?: string };
+  project?: { id?: string };
+};
+
+/**
+ * Where a local store keeps its objects. An explicit `storage.local.directory`
+ * (or `storage.localDirectory`) wins; otherwise it is `runtime.artifacts_dir`,
+ * so the executor that writes artifacts and the loopback bridge the dashboard
+ * reads through always agree on the same folder.
+ */
+export function resolveLocalStorageDirectory(cfg: StorageSettings, fallback = "./runs"): string {
+  return cfg.storage?.local?.directory || cfg.storage?.localDirectory || cfg.runtime?.artifacts_dir || fallback;
+}
+

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    // @types/node 26 uses iterator helpers and Symbol.dispose throughout its
+    // URL/stream signatures, so the lib has to be new enough to describe them.
+    "lib": ["ES2023"],
+    "moduleResolution": "nodenext",
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["scripts/**/*", "src/**/*"],
+  "typeRoots": ["./node_modules/@types", "./src/types"],
+  "exclude": ["node_modules", "dist", "runs"]
+}