@voila.dev/cliche 0.1.0

package/src/keys.ts

@@ -0,0 +1,24 @@
+import { basename, extname } from "node:path";
+
+/** S3 object keys only tolerate a narrow character set. */
+export function slugOf(rawPrefix: string): string {
+  return rawPrefix.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+
+/** The image's caption in the generated markdown. */
+export function captionOf(file: string): string {
+  return basename(file, extname(file)).replace(/[-_]+/g, " ");
+}
+
+function contentHash(bytes: Uint8Array): string {
+  return new Bun.CryptoHasher("sha256").update(bytes).digest("hex").slice(0, 8);
+}
+
+/**
+ * `<prefix>/<yyyy-mm-dd>-<basename>-<content-hash>.<ext>`: the hash makes
+ * re-uploads cache-safe, the date keeps the bucket browsable.
+ */
+export function objectKeyOf(prefix: string, file: string, bytes: Uint8Array, date: string): string {
+  const extension = extname(file);
+  return `${slugOf(prefix)}/${date}-${basename(file, extension)}-${contentHash(bytes)}${extension.toLowerCase()}`;
+}

package/src/mcp.ts

@@ -0,0 +1,220 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { capture as captureImplementation, type CaptureOptions } from "./capture.ts";
+import { parseLocalStorage, parseViewport } from "./options.ts";
+import { upload as uploadImplementation, type UploadedFile, type UploadOptions } from "./upload.ts";
+
+/**
+ * A hand-rolled MCP server: the stdio transport is newline-delimited JSON-RPC
+ * 2.0, and this server only needs initialize + tools, so the protocol fits in
+ * this file and the package stays zero-dependency.
+ */
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+interface JsonRpcMessage {
+  readonly jsonrpc: "2.0";
+  readonly id?: number | string;
+  readonly method?: string;
+  readonly params?: Record<string, unknown>;
+}
+
+/** The implementations, injectable for tests. */
+export interface McpDependencies {
+  readonly capture: (options: CaptureOptions) => Promise<void>;
+  readonly upload: (options: UploadOptions) => Promise<Array<UploadedFile>>;
+}
+
+const TOOLS = [
+  {
+    name: "screenshot",
+    description:
+      "Screenshot a web page locally with Bun.WebView (no browser install). Optionally upload it to the configured S3-compatible bucket and return its public URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The page to screenshot." },
+        out: {
+          type: "string",
+          description: "Where to write the PNG. Defaults to a temporary file.",
+        },
+        viewport: {
+          type: "string",
+          description: "Viewport as <width>x<height>. Defaults to 1440x900 (use 390x844 for mobile).",
+        },
+        wait_for: {
+          type: "string",
+          description: "CSS selector to wait for before shooting (15s timeout).",
+        },
+        scroll_to: {
+          type: "string",
+          description: "CSS selector scrolled into view before shooting.",
+        },
+        settle_ms: {
+          type: "number",
+          description: "Milliseconds to let the page settle after load. Defaults to 1500.",
+        },
+        full_page: {
+          type: "boolean",
+          description: "Grow the viewport to the full page height before shooting.",
+        },
+        local_storage: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description:
+            "Entries seeded into the target origin's localStorage before the page loads (e.g. a session token for authenticated screens).",
+        },
+        upload: {
+          type: "boolean",
+          description: "Upload the shot and return its public URL.",
+        },
+        prefix: {
+          type: "string",
+          description: "Object key prefix for the upload, e.g. pr-123.",
+        },
+        markdown: {
+          type: "boolean",
+          description: "Return a ![caption](url) markdown line instead of the bare URL.",
+        },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "upload",
+    description:
+      "Upload local images to the configured S3-compatible bucket and return their public URLs (content-hashed keys, safe to re-upload).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description: "Paths of the images to upload.",
+        },
+        prefix: {
+          type: "string",
+          description: "Object key prefix, e.g. pr-123.",
+        },
+        markdown: {
+          type: "boolean",
+          description: "Return ![caption](url) markdown lines instead of the bare URLs.",
+        },
+      },
+      required: ["files"],
+    },
+  },
+];
+
+function textResult(text: string, isError = false): Record<string, unknown> {
+  return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
+}
+
+function renderUploads(uploaded: ReadonlyArray<UploadedFile>, markdown: boolean): string {
+  return uploaded.map((entry) => (markdown ? entry.markdown : entry.url)).join("\n");
+}
+
+function temporaryOut(): string {
+  return join(tmpdir(), `cliche-${Date.now().toString(36)}.png`);
+}
+
+async function callTool(
+  name: string,
+  input: Record<string, unknown>,
+  dependencies: McpDependencies,
+): Promise<Record<string, unknown>> {
+  if (name === "screenshot") {
+    const out = typeof input.out === "string" ? input.out : temporaryOut();
+    await dependencies.capture({
+      url: String(input.url),
+      out,
+      ...(typeof input.viewport === "string" ? { viewport: parseViewport(input.viewport) } : {}),
+      ...(typeof input.wait_for === "string" ? { waitFor: input.wait_for } : {}),
+      ...(typeof input.scroll_to === "string" ? { scrollTo: input.scroll_to } : {}),
+      ...(typeof input.settle_ms === "number" ? { settleMilliseconds: input.settle_ms } : {}),
+      ...(input.full_page === true ? { fullPage: true } : {}),
+      ...(input.local_storage !== undefined && typeof input.local_storage === "object"
+        ? { localStorage: input.local_storage as Record<string, string> }
+        : {}),
+    });
+    if (input.upload !== true) {
+      return textResult(`Captured ${String(input.url)} -> ${out}`);
+    }
+    const uploaded = await dependencies.upload({
+      files: [out],
+      ...(typeof input.prefix === "string" ? { prefix: input.prefix } : {}),
+    });
+    return textResult(renderUploads(uploaded, input.markdown === true));
+  }
+  if (name === "upload") {
+    const uploaded = await dependencies.upload({
+      files: (input.files as Array<string>) ?? [],
+      ...(typeof input.prefix === "string" ? { prefix: input.prefix } : {}),
+    });
+    return textResult(renderUploads(uploaded, input.markdown === true));
+  }
+  return textResult(`Unknown tool: ${name}`, true);
+}
+
+/** Handle one JSON-RPC message; null means nothing to send back. */
+export async function handleMessage(
+  message: JsonRpcMessage,
+  dependencies: McpDependencies,
+): Promise<Record<string, unknown> | null> {
+  // Notifications carry no id and expect no response.
+  if (message.id === undefined) return null;
+  const reply = (result: Record<string, unknown>) => ({
+    jsonrpc: "2.0",
+    id: message.id,
+    result,
+  });
+  switch (message.method) {
+    case "initialize":
+      return reply({
+        protocolVersion:
+          typeof message.params?.protocolVersion === "string"
+            ? message.params.protocolVersion
+            : PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "cliche", version: "0.1.0" },
+      });
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({ tools: TOOLS });
+    case "tools/call": {
+      const name = String(message.params?.name);
+      const input = (message.params?.arguments ?? {}) as Record<string, unknown>;
+      try {
+        return reply(await callTool(name, input, dependencies));
+      } catch (error) {
+        return reply(textResult(error instanceof Error ? error.message : String(error), true));
+      }
+    }
+    default:
+      return {
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: -32601, message: `Method not found: ${message.method}` },
+      };
+  }
+}
+
+/** Serve MCP over stdio until stdin closes. */
+export async function runMcpServer(): Promise<void> {
+  const dependencies: McpDependencies = {
+    capture: captureImplementation,
+    upload: uploadImplementation,
+  };
+  for await (const line of console) {
+    if (line.trim() === "") continue;
+    let message: JsonRpcMessage;
+    try {
+      message = JSON.parse(line) as JsonRpcMessage;
+    } catch {
+      continue;
+    }
+    const response = await handleMessage(message, dependencies);
+    if (response !== null) console.log(JSON.stringify(response));
+  }
+}

package/src/options.ts

@@ -0,0 +1,141 @@
+import { parseArgs } from "node:util";
+import type { CaptureOptions, Viewport } from "./capture.ts";
+
+export interface CaptureCommand {
+  readonly kind: "capture";
+  readonly capture: CaptureOptions;
+  /** Upload the shot right after capturing it. */
+  readonly upload: boolean;
+  readonly prefix: string | undefined;
+  /** Print `![caption](url)` lines instead of the bare URLs. */
+  readonly markdown: boolean;
+}
+
+export interface UploadCommand {
+  readonly kind: "upload";
+  readonly files: ReadonlyArray<string>;
+  readonly prefix: string | undefined;
+  readonly markdown: boolean;
+}
+
+export interface McpCommand {
+  readonly kind: "mcp";
+}
+
+export interface SkillCommand {
+  readonly kind: "skill";
+}
+
+export interface SetupCommand {
+  readonly kind: "setup";
+  readonly bucket: string;
+}
+
+export interface AlbumCommand {
+  readonly kind: "album";
+  readonly port: number | undefined;
+}
+
+export interface HelpCommand {
+  readonly kind: "help";
+}
+
+export type Command =
+  | CaptureCommand
+  | UploadCommand
+  | McpCommand
+  | SkillCommand
+  | SetupCommand
+  | AlbumCommand
+  | HelpCommand;
+
+export function parseViewport(value: string): Viewport {
+  const match = value.match(/^(\d+)x(\d+)$/);
+  if (match === null) {
+    throw new Error(`Invalid --viewport ${value}: expected <width>x<height>, e.g. 1440x900.`);
+  }
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+export function parseLocalStorage(entries: ReadonlyArray<string>): Record<string, string> {
+  const parsed: Record<string, string> = {};
+  for (const entry of entries) {
+    const separator = entry.indexOf("=");
+    if (separator < 1) {
+      throw new Error(`Invalid --local-storage ${entry}: expected key=value.`);
+    }
+    parsed[entry.slice(0, separator)] = entry.slice(separator + 1);
+  }
+  return parsed;
+}
+
+export function parseCommand(argv: ReadonlyArray<string>): Command {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    allowPositionals: true,
+    options: {
+      viewport: { type: "string" },
+      "wait-for": { type: "string" },
+      "scroll-to": { type: "string" },
+      settle: { type: "string" },
+      "local-storage": { type: "string", multiple: true },
+      "full-page": { type: "boolean" },
+      upload: { type: "boolean" },
+      prefix: { type: "string" },
+      markdown: { type: "boolean" },
+      bucket: { type: "string" },
+      port: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (values.help === true || positionals.length === 0) {
+    return { kind: "help" };
+  }
+  if (positionals[0] === "mcp") {
+    return { kind: "mcp" };
+  }
+  if (positionals[0] === "skill") {
+    return { kind: "skill" };
+  }
+  if (positionals[0] === "setup") {
+    return { kind: "setup", bucket: values.bucket ?? "cliche-shots" };
+  }
+  if (positionals[0] === "album") {
+    const port = values.port === undefined ? undefined : Number(values.port);
+    if (port !== undefined && !Number.isInteger(port)) {
+      throw new Error(`Invalid --port ${values.port}: expected a number.`);
+    }
+    return { kind: "album", port };
+  }
+  if (positionals[0] === "upload") {
+    const files = positionals.slice(1);
+    if (files.length === 0) throw new Error("upload: pass at least one image file.");
+    return { kind: "upload", files, prefix: values.prefix, markdown: values.markdown === true };
+  }
+  const [url, out] = positionals;
+  if (url === undefined || out === undefined) {
+    throw new Error("capture: pass <url> <out.png> (or see --help).");
+  }
+  const settle = values.settle === undefined ? undefined : Number(values.settle);
+  if (settle !== undefined && !Number.isFinite(settle)) {
+    throw new Error(`Invalid --settle ${values.settle}: expected milliseconds.`);
+  }
+  return {
+    kind: "capture",
+    capture: {
+      url,
+      out,
+      ...(values.viewport === undefined ? {} : { viewport: parseViewport(values.viewport) }),
+      ...(values["wait-for"] === undefined ? {} : { waitFor: values["wait-for"] }),
+      ...(values["scroll-to"] === undefined ? {} : { scrollTo: values["scroll-to"] }),
+      ...(settle === undefined ? {} : { settleMilliseconds: settle }),
+      ...(values["local-storage"] === undefined
+        ? {}
+        : { localStorage: parseLocalStorage(values["local-storage"]) }),
+      ...(values["full-page"] === true ? { fullPage: true } : {}),
+    },
+    upload: values.upload === true,
+    prefix: values.prefix,
+    markdown: values.markdown === true,
+  };
+}

package/src/setup.ts

@@ -0,0 +1,104 @@
+/**
+ * One-command S3 setup on Cloudflare R2, riding the user's `wrangler login`
+ * session: create the bucket, enable its managed public r2.dev URL, and
+ * write the resulting configuration to `.env`. The only step wrangler cannot
+ * do is minting S3 API keys — the dashboard link for that is printed (and
+ * left as a comment in `.env`).
+ */
+
+const DASHBOARD_TOKENS_URL = "https://dash.cloudflare.com/?to=/:account/r2/api-tokens";
+
+async function wrangler(
+  args: Array<string>,
+  options: { interactive?: boolean } = {},
+): Promise<{ exitCode: number; output: string }> {
+  const subprocess = Bun.spawn(["bunx", "wrangler", ...args], {
+    stdin: "inherit",
+    stdout: options.interactive === true ? "inherit" : "pipe",
+    stderr: options.interactive === true ? "inherit" : "pipe",
+  });
+  const exitCode = await subprocess.exited;
+  const output =
+    options.interactive === true
+      ? ""
+      : (await new Response(subprocess.stdout).text()) +
+        (await new Response(subprocess.stderr).text());
+  return { exitCode, output };
+}
+
+export function parseAccountId(whoamiOutput: string): string | null {
+  // `wrangler whoami` prints an account table; a lone account is unambiguous.
+  const ids = [...new Set(whoamiOutput.match(/\b[0-9a-f]{32}\b/g) ?? [])];
+  return ids.length === 1 ? (ids[0] ?? null) : null;
+}
+
+export function parsePublicUrl(devUrlOutput: string): string | null {
+  return devUrlOutput.match(/https:\/\/[a-z0-9-]+\.r2\.dev/)?.[0] ?? null;
+}
+
+function environmentBlock(
+  bucket: string,
+  publicUrl: string | null,
+  accountId: string | null,
+): string {
+  const lines = [
+    "",
+    "# cliche — added by `cliche setup` (https://cliche.voila.dev)",
+    `S3_BUCKET=${bucket}`,
+    accountId === null
+      ? "# S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com"
+      : `S3_ENDPOINT=https://${accountId}.r2.cloudflarestorage.com`,
+    ...(publicUrl === null ? [] : [`CLICHE_PUBLIC_URL=${publicUrl}`]),
+    `# Mint the two keys at ${DASHBOARD_TOKENS_URL} (Object Read & Write on ${bucket}):`,
+    "# S3_ACCESS_KEY_ID=",
+    "# S3_SECRET_ACCESS_KEY=",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+export async function setup(bucket: string): Promise<void> {
+  console.error(`Setting up Cloudflare R2 bucket "${bucket}" via wrangler…`);
+
+  const whoami = await wrangler(["whoami"]);
+  if (whoami.exitCode !== 0 || whoami.output.includes("You are not authenticated")) {
+    throw new Error("wrangler is not logged in — run `bunx wrangler login` first.");
+  }
+  const accountId = parseAccountId(whoami.output);
+  if (accountId === null) {
+    console.error(
+      "Several Cloudflare accounts found: wrangler will ask which one to use (set CLOUDFLARE_ACCOUNT_ID to skip the prompt).",
+    );
+  }
+
+  const create = await wrangler(["r2", "bucket", "create", bucket], { interactive: true });
+  if (create.exitCode !== 0) {
+    // Most likely the bucket already exists, which is fine for reruns; the
+    // dev-url step below fails loudly if the bucket truly is not there.
+    console.error(`(bucket create exited ${create.exitCode} — continuing, it probably already exists)`);
+  }
+
+  console.error("Enabling the managed public r2.dev URL…");
+  await wrangler(["r2", "bucket", "dev-url", "enable", bucket, "--force"], { interactive: true });
+  const devUrl = await wrangler(["r2", "bucket", "dev-url", "get", bucket]);
+  const publicUrl = parsePublicUrl(devUrl.output);
+
+  const environmentFile = Bun.file(".env");
+  const existing = (await environmentFile.exists()) ? await environmentFile.text() : "";
+  if (existing.includes("S3_BUCKET=")) {
+    console.error(".env already has an S3_BUCKET — printing the block instead of appending:");
+    console.log(environmentBlock(bucket, publicUrl, accountId));
+  } else {
+    await Bun.write(".env", existing + environmentBlock(bucket, publicUrl, accountId));
+    console.error("Wrote the configuration to .env.");
+  }
+
+  console.error(`
+Almost there — one last step wrangler cannot do:
+  1. Open ${DASHBOARD_TOKENS_URL}
+  2. Create an API token with "Object Read & Write" on "${bucket}"
+  3. Put the two values in .env as S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY
+
+Then take your first cliché:
+  bunx @voila.dev/cliche https://example.com shot.png --upload`);
+}

package/src/skill.ts

@@ -0,0 +1,14 @@
+import { fileURLToPath } from "node:url";
+
+export const SKILL_TARGET = ".claude/skills/pr-screenshots/SKILL.md";
+
+/**
+ * Install the packaged PR-screenshots skill into the current repository.
+ * The skill ships with the package (`skill/SKILL.md`), so this works offline
+ * and always matches the installed cliche version.
+ */
+export async function installSkill(): Promise<string> {
+  const source = fileURLToPath(new URL("../skill/SKILL.md", import.meta.url));
+  await Bun.write(SKILL_TARGET, Bun.file(source));
+  return SKILL_TARGET;
+}

package/src/upload.ts

@@ -0,0 +1,72 @@
+import { extname } from "node:path";
+import { captionOf, objectKeyOf } from "./keys.ts";
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+export interface UploadOptions {
+  readonly files: ReadonlyArray<string>;
+  /** Object key prefix, e.g. `pr-123`. Defaults to `cliche`. */
+  readonly prefix?: string;
+}
+
+export interface UploadedFile {
+  readonly file: string;
+  readonly key: string;
+  readonly url: string;
+  /** A ready-to-paste `![caption](url)` line. */
+  readonly markdown: string;
+}
+
+/** The subset of Bun.S3Client the upload needs; injectable for tests. */
+export interface ObjectWriter {
+  write(key: string, bytes: Uint8Array, options: { type: string }): Promise<unknown>;
+}
+
+export function publicBaseUrl(): string {
+  const configured = process.env.CLICHE_PUBLIC_URL;
+  if (configured !== undefined) return configured.replace(/\/$/, "");
+  const bucket = process.env.S3_BUCKET ?? process.env.AWS_BUCKET;
+  if (bucket === undefined) {
+    throw new Error(
+      "No bucket configured: set S3_BUCKET (and S3_ENDPOINT + S3_ACCESS_KEY_ID + S3_SECRET_ACCESS_KEY), or CLICHE_PUBLIC_URL alone if the bucket is resolved elsewhere.",
+    );
+  }
+  const endpoint = process.env.S3_ENDPOINT ?? process.env.AWS_ENDPOINT;
+  if (endpoint !== undefined) return `${endpoint.replace(/\/$/, "")}/${bucket}`;
+  const region = process.env.AWS_REGION ?? process.env.S3_REGION ?? "us-east-1";
+  return `https://${bucket}.s3.${region}.amazonaws.com`;
+}
+
+/**
+ * Upload images to the S3-compatible bucket described by the standard
+ * environment variables Bun.S3Client already reads (S3_* / AWS_*), and
+ * return one markdown line per file. `CLICHE_PUBLIC_URL` overrides the
+ * public base URL (custom domains, R2 public buckets).
+ */
+export async function upload(options: UploadOptions, writer?: ObjectWriter): Promise<Array<UploadedFile>> {
+  const baseUrl = publicBaseUrl();
+  const client = writer ?? new Bun.S3Client();
+  const prefix = options.prefix ?? "cliche";
+  const date = new Date().toISOString().slice(0, 10);
+  const uploaded: Array<UploadedFile> = [];
+  for (const file of options.files) {
+    const contentType = CONTENT_TYPES[extname(file).toLowerCase()];
+    if (contentType === undefined) {
+      console.error(`Skipping ${file}: unsupported extension`);
+      continue;
+    }
+    const bytes = await Bun.file(file).bytes();
+    const key = objectKeyOf(prefix, file, bytes, date);
+    await client.write(key, bytes, { type: contentType });
+    console.error(`Uploaded ${file} -> ${key}`);
+    const url = `${baseUrl}/${key}`;
+    uploaded.push({ file, key, url, markdown: `![${captionOf(file)}](${url})` });
+  }
+  return uploaded;
+}