diff --git a/apps/cli-e2e/package.json b/apps/cli-e2e/package.json index 616559a701..5d581f65ce 100644 --- a/apps/cli-e2e/package.json +++ b/apps/cli-e2e/package.json @@ -9,6 +9,10 @@ "test:e2e:run": "bun --bun vitest run", "replay:serve": "bun scripts/replay-serve.ts", "record": "RECORD=true pnpm run test:e2e:run", + "gallery": "bun scripts/gallery.ts", + "gallery:help": "bun scripts/gallery-help.ts", + "gallery:refresh": "bun scripts/gallery-refresh.ts", + "gallery:serve": "bun scripts/gallery-serve.ts", "types:check": "tsc --noEmit" }, "dependencies": { diff --git a/apps/cli-e2e/scripts/gallery-help.ts b/apps/cli-e2e/scripts/gallery-help.ts new file mode 100644 index 0000000000..d26aa91d0e --- /dev/null +++ b/apps/cli-e2e/scripts/gallery-help.ts @@ -0,0 +1,87 @@ +/* oxlint-disable effecttsgo/global-console, effecttsgo/async-function, effecttsgo/node-builtin-import, effecttsgo/process-env, effecttsgo/new-promise -- standalone Bun dev script for the output gallery, not CLI runtime code */ +/* Captures `--help` for every command into gallery records, walking the SUBCOMMANDS sections. + Usage: bun scripts/gallery-help.ts [command words...]; words limit it to that command + and its subcommands. */ +import { mkdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { cpus, tmpdir } from "node:os"; +import { createHarness, exec } from "@supabase/cli-test-helpers"; + +/** Width of the pseudo-terminal the gallery captures in; override with GALLERY_COLUMNS. */ +const GALLERY_COLUMNS = Number(process.env["GALLERY_COLUMNS"]) || 160; + +const [recordsDir, ...prefix] = process.argv.slice(2); +if (!recordsDir) { + console.error("usage: bun scripts/gallery-help.ts "); + process.exit(1); +} +mkdirSync(recordsDir, { recursive: true }); + +const harness = createHarness({ + apiUrl: "http://127.0.0.1:9", + accessToken: "sbp_" + "0".repeat(40), + cwd: tmpdir(), +}); + +const subcommands = (help: string): string[] => { + const section = help.split(/\n(?=[A-Z][A-Z ]+\n)/).find((part) => part.startsWith("SUBCOMMANDS")); + if (!section) return []; + return section + .split("\n") + .slice(1) + .map((line) => /^ {2}([a-z][\w-]*)\s{2,}/.exec(line)?.[1]) + .filter((name): name is string => name !== undefined); +}; + +const concurrency = Number(process.env["GALLERY_CONCURRENCY"]) || cpus().length; + +const capture = async (path: string[]): Promise>> => { + const args = [...path, "--help"]; + const [piped, tty] = await Promise.all([ + exec(harness, args), + exec(harness, args, { tty: { columns: GALLERY_COLUMNS, rows: 50 } }), + ]); + const slug = ["help", ...path].join("-") || "help-root"; + writeFileSync( + join(recordsDir, `${slug}.json`), + JSON.stringify({ + suite: `--help ${path[0] ?? "supabase"}`, + test: ["supabase", ...path].join(" "), + slug, + file: "--help", + args, + piped, + tty, + }), + ); + return subcommands(piped.stdout).map((name) => [...path, name]); +}; + +const started = performance.now(); +const queue: Array> = [prefix]; +let captured = 0; +let active = 0; +await new Promise((done) => { + const pump = () => { + if (queue.length === 0 && active === 0) return done(); + while (active < concurrency && queue.length > 0) { + const path = queue.shift()!; + active += 1; + void capture([...path]) + .catch((cause: unknown) => { + console.error(`help capture failed for "${path.join(" ")}": ${String(cause)}`); + return []; + }) + .then((children) => { + captured += 1; + active -= 1; + queue.push(...children); + pump(); + }); + } + }; + pump(); +}); +console.log( + `captured ${captured} help pages in ${((performance.now() - started) / 1000).toFixed(1)}s at concurrency ${concurrency}`, +); diff --git a/apps/cli-e2e/scripts/gallery-refresh.ts b/apps/cli-e2e/scripts/gallery-refresh.ts new file mode 100644 index 0000000000..2b30fc7d76 --- /dev/null +++ b/apps/cli-e2e/scripts/gallery-refresh.ts @@ -0,0 +1,40 @@ +/* oxlint-disable effecttsgo/global-console, effecttsgo/async-function, effecttsgo/node-builtin-import, effecttsgo/process-env, effecttsgo/new-promise -- standalone Bun dev script for the output gallery, not CLI runtime code */ +/* Re-captures one command (its --help pages and e2e tests) and rebuilds the gallery page. + Usage: bun scripts/gallery-refresh.ts + e.g. bun scripts/gallery-refresh.ts $G projects list */ +import { join } from "node:path"; + +const [galleryDir, ...words] = process.argv.slice(2); +if (!galleryDir || words.length === 0) { + console.error("usage: bun scripts/gallery-refresh.ts "); + process.exit(1); +} +const records = join(galleryDir, "records"); +const started = performance.now(); + +const step = async (label: string, cmd: string[], env: Record = {}) => { + const t = performance.now(); + const proc = Bun.spawn(cmd, { + cwd: join(import.meta.dir, ".."), + env: { ...process.env, ...env }, + stdout: "inherit", + stderr: "inherit", + }); + await proc.exited; + console.log(`${label}: ${((performance.now() - t) / 1000).toFixed(1)}s`); +}; + +// Describe blocks name commands as "projects:list" or "db push"; accept either separator. +const testPattern = `(^|\\s)${words.map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[ :]")}\\b`; + +await Promise.all([ + step("help", ["bun", "scripts/gallery-help.ts", records, ...words]), + step("e2e", ["bun", "--bun", "vitest", "run", "--reporter=dot", "-t", testPattern], { + CLI_GALLERY_DIR: records, + CLI_E2E_FROM_SOURCE: "1", + }), +]); +await step("page", ["bun", "scripts/gallery.ts", records, join(galleryDir, "index.html")]); +console.log( + `refreshed "${words.join(" ")}" in ${((performance.now() - started) / 1000).toFixed(1)}s`, +); diff --git a/apps/cli-e2e/scripts/gallery-serve.ts b/apps/cli-e2e/scripts/gallery-serve.ts new file mode 100644 index 0000000000..017f21193d --- /dev/null +++ b/apps/cli-e2e/scripts/gallery-serve.ts @@ -0,0 +1,27 @@ +/* oxlint-disable effecttsgo/global-console, effecttsgo/async-function, effecttsgo/node-builtin-import, effecttsgo/process-env, effecttsgo/new-promise -- standalone Bun dev script for the output gallery, not CLI runtime code */ +/* Serves the gallery page without caching, so a reload always shows the latest capture. + Usage: bun scripts/gallery-serve.ts [port] */ +import { join, normalize } from "node:path"; + +const [galleryDir, portArg] = process.argv.slice(2); +if (!galleryDir) { + console.error("usage: bun scripts/gallery-serve.ts [port]"); + process.exit(1); +} + +const server = Bun.serve({ + hostname: "127.0.0.1", + port: Number(portArg) || 8787, + fetch(request) { + const path = normalize(new URL(request.url).pathname).replace(/^(\.\.[/\\])+/, ""); + const file = Bun.file(join(galleryDir, path === "/" ? "index.html" : path)); + return file + .exists() + .then((found) => + found + ? new Response(file, { headers: { "Cache-Control": "no-store" } }) + : new Response("Not found", { status: 404 }), + ); + }, +}); +console.log(`gallery at http://${server.hostname}:${server.port}/`); diff --git a/apps/cli-e2e/scripts/gallery.ts b/apps/cli-e2e/scripts/gallery.ts new file mode 100644 index 0000000000..4f0fef741d --- /dev/null +++ b/apps/cli-e2e/scripts/gallery.ts @@ -0,0 +1,553 @@ +/* oxlint-disable effecttsgo/global-console, effecttsgo/async-function, effecttsgo/node-builtin-import, effecttsgo/process-env, effecttsgo/new-promise -- standalone Bun dev script for the output gallery, not CLI runtime code */ +/* Builds a single HTML page from the records written by an e2e run with CLI_GALLERY_DIR set. + Usage: bun scripts/gallery.ts */ +import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +/** Width of the pseudo-terminal the gallery captures in; override with GALLERY_COLUMNS. */ +const GALLERY_COLUMNS = Number(process.env["GALLERY_COLUMNS"]) || 160; + +interface RunResult { + stdout: string; + stderr: string; + exitCode: number; + timedOut?: boolean; + error?: string; +} + +interface GalleryRecord { + suite: string; + test: string; + slug: string; + file: string; + args: string[]; + piped: RunResult | null; + tty: RunResult; +} + +/* ---------- minimal terminal emulator ---------- */ + +interface Style { + fg: string | null; + bg: string | null; + bold: boolean; + dim: boolean; + italic: boolean; + underline: boolean; + inverse: boolean; + strike: boolean; + hidden: boolean; +} + +interface Cell { + ch: string; + style: Style; +} + +/* The 16 theme colours are CSS variables so the page's light and dark palettes can redefine them. */ +const BASE16 = Array.from({ length: 16 }, (_, n) => `var(--ansi-${n})`); + +function color256(n: number): string { + if (n < 16) return BASE16[n]!; + if (n < 232) { + const i = n - 16; + const steps = [0, 95, 135, 175, 215, 255]; + return `rgb(${steps[Math.floor(i / 36)]},${steps[Math.floor(i / 6) % 6]},${steps[i % 6]})`; + } + const g = 8 + (n - 232) * 10; + return `rgb(${g},${g},${g})`; +} + +const defaultStyle = (): Style => ({ + fg: null, + bg: null, + bold: false, + dim: false, + italic: false, + underline: false, + inverse: false, + strike: false, + hidden: false, +}); + +class Terminal { + lines: Cell[][] = [[]]; + row = 0; + col = 0; + style = defaultStyle(); + saved: [number, number] = [0, 0]; + + constructor( + readonly cols: number, + readonly rows: number, + ) {} + + get top(): number { + return Math.max(0, this.lines.length - this.rows); + } + + line(r: number): Cell[] { + while (this.lines.length <= r) this.lines.push([]); + return this.lines[r]!; + } + + put(ch: string) { + if (this.col >= this.cols) { + this.col = 0; + this.row++; + } + const l = this.line(this.row); + while (l.length < this.col) l.push({ ch: " ", style: defaultStyle() }); + l[this.col] = { ch, style: { ...this.style } }; + this.col++; + } + + sgr(params: number[]) { + if (params.length === 0) params = [0]; + for (let i = 0; i < params.length; i++) { + const p = params[i]!; + if (p === 0) this.style = defaultStyle(); + else if (p === 1) this.style.bold = true; + else if (p === 2) this.style.dim = true; + else if (p === 3) this.style.italic = true; + else if (p === 4) this.style.underline = true; + else if (p === 7) this.style.inverse = true; + else if (p === 8) this.style.hidden = true; + else if (p === 28) this.style.hidden = false; + else if (p === 9) this.style.strike = true; + else if (p === 22) this.style.bold = this.style.dim = false; + else if (p === 23) this.style.italic = false; + else if (p === 24) this.style.underline = false; + else if (p === 27) this.style.inverse = false; + else if (p === 29) this.style.strike = false; + else if (p >= 30 && p <= 37) this.style.fg = BASE16[p - 30]!; + else if (p >= 90 && p <= 97) this.style.fg = BASE16[p - 90 + 8]!; + else if (p === 39) this.style.fg = null; + else if (p >= 40 && p <= 47) this.style.bg = BASE16[p - 40]!; + else if (p >= 100 && p <= 107) this.style.bg = BASE16[p - 100 + 8]!; + else if (p === 49) this.style.bg = null; + else if (p === 38 || p === 48) { + let c: string | null = null; + if (params[i + 1] === 5) { + c = color256(params[i + 2] ?? 0); + i += 2; + } else if (params[i + 1] === 2) { + c = `rgb(${params[i + 2] ?? 0},${params[i + 3] ?? 0},${params[i + 4] ?? 0})`; + i += 4; + } + if (p === 38) this.style.fg = c; + else this.style.bg = c; + } + } + } + + csi(raw: string, final: string) { + const priv = raw.startsWith("?"); + const params = (priv ? raw.slice(1) : raw).split(";").map((s) => (s === "" ? NaN : Number(s))); + const n = (i: number, d = 1) => + Number.isNaN(params[i]!) || params[i] === undefined ? d : params[i]!; + if (priv) return; + switch (final) { + case "A": + this.row = Math.max(this.top, this.row - n(0)); + break; + case "B": + case "E": + this.row += n(0); + if (final === "E") this.col = 0; + break; + case "F": + this.row = Math.max(this.top, this.row - n(0)); + this.col = 0; + break; + case "C": + this.col = Math.min(this.cols - 1, this.col + n(0)); + break; + case "D": + this.col = Math.max(0, this.col - n(0)); + break; + case "G": + this.col = Math.max(0, n(0) - 1); + break; + case "H": + case "f": + this.row = this.top + n(0) - 1; + this.col = n(1) - 1; + break; + case "K": { + const l = this.line(this.row); + const mode = n(0, 0); + if (mode === 0) l.length = Math.min(l.length, this.col); + else if (mode === 1) + for (let c = 0; c <= this.col && c < l.length; c++) + l[c] = { ch: " ", style: defaultStyle() }; + else l.length = 0; + break; + } + case "J": { + const mode = n(0, 0); + if (mode === 0) { + this.line(this.row).length = Math.min(this.line(this.row).length, this.col); + this.lines.length = this.row + 1; + } else if (mode === 2 || mode === 3) { + for (let r = this.top; r < this.lines.length; r++) this.lines[r] = []; + } + break; + } + case "m": + this.sgr(params.map((p) => (Number.isNaN(p) ? 0 : p))); + break; + default: + break; + } + } + + write(data: string) { + const chars = Array.from(data); + for (let i = 0; i < chars.length; i++) { + const ch = chars[i]!; + if (ch === "\x1b") { + const next = chars[i + 1]; + if (next === "[") { + let j = i + 2; + let raw = ""; + while (j < chars.length && !/[@-~]/.test(chars[j]!)) raw += chars[j++]; + this.csi(raw, chars[j] ?? ""); + i = j; + } else if (next === "]") { + let j = i + 2; + while ( + j < chars.length && + chars[j] !== "\x07" && + !(chars[j] === "\x1b" && chars[j + 1] === "\\") + ) + j++; + i = chars[j] === "\x07" ? j : j + 1; + } else if (next === "7") { + this.saved = [this.row, this.col]; + i++; + } else if (next === "8") { + [this.row, this.col] = this.saved; + i++; + } else { + i++; + } + } else if (ch === "\r") this.col = 0; + else if (ch === "\n") this.row++; + else if (ch === "\b") this.col = Math.max(0, this.col - 1); + else if (ch === "\t") this.col = Math.min(this.cols - 1, (Math.floor(this.col / 8) + 1) * 8); + else if (ch < " " || ch === "\x7f") continue; + else this.put(ch); + this.line(this.row); + } + } + + toHtml(): string { + const out = this.lines.map((l) => { + let html = ""; + let cur = ""; + let buf = ""; + const flush = () => { + if (buf) html += cur ? `${esc(buf)}` : esc(buf); + buf = ""; + }; + for (const cell of l) { + const css = styleCss(cell.style); + if (css !== cur) { + flush(); + cur = css; + } + buf += cell.style.hidden ? " " : cell.ch; + } + flush(); + return html; + }); + while (out.length > 0 && out[out.length - 1]!.trim() === "") out.pop(); + return out.join("\n"); + } +} + +function styleCss(s: Style): string { + let fg = s.fg; + let bg = s.bg; + if (s.inverse) [fg, bg] = [bg ?? "var(--term-bg)", fg ?? "var(--term-fg)"]; + const parts: string[] = []; + if (fg) parts.push(`color:${fg}`); + if (bg) parts.push(`background:${bg}`); + if (s.bold) parts.push("font-weight:700"); + if (s.dim) parts.push("opacity:.6"); + if (s.italic) parts.push("font-style:italic"); + const deco = [s.underline && "underline", s.strike && "line-through"].filter(Boolean); + if (deco.length) parts.push(`text-decoration:${deco.join(" ")}`); + return parts.join(";"); +} + +function esc(s: string): string { + return s.replace(/&/g, "&").replace(//g, ">"); +} + +function renderTty(raw: string): string { + const t = new Terminal(GALLERY_COLUMNS, 50); + t.write(raw); + return t.toHtml(); +} + +/* ---------- page ---------- */ + +function isJson(args: string[]): boolean { + return args.some( + (a, i) => + a === "--output=json" || + a === "-o=json" || + ((a === "--output" || a === "-o") && args[i + 1] === "json"), + ); +} + +function isHelp(args: string[]): boolean { + return args.includes("--help") || args.includes("-h"); +} + +function kindOf(args: string[]): "help" | "json" | "interactive" { + return isHelp(args) ? "help" : isJson(args) ? "json" : "interactive"; +} + +function shellQuote(a: string): string { + return /^[\w./:=@%+,-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`; +} + +function prettyJson(s: string): string { + try { + return JSON.stringify(JSON.parse(s), null, 2); + } catch { + return s; + } +} + +function exitBadge(r: RunResult | null, label: string): string { + if (!r) return `${label}: no result`; + if (r.error) return `${label}: ${esc(r.error)}`; + if (r.timedOut) return `${label}: timed out (killed)`; + return `${label} exit ${r.exitCode}`; +} + +function seconds(r: RunResult | null): string { + const ms = (r as { durationMs?: number } | null)?.durationMs; + return ms === undefined ? "" : ` (${(ms / 1000).toFixed(3)}s)`; +} + +function card(rec: GalleryRecord): string { + const json = isJson(rec.args); + const cmd = ["supabase", ...rec.args].map(shellQuote).join(" "); + const pane = json + ? esc(prettyJson(rec.piped?.stdout ?? "")) + : rec.tty.error + ? esc(rec.tty.error) + : renderTty(rec.tty.stdout); + const piped = rec.piped; + return `
+
${esc(rec.test)}
+
${json ? 'json' : 'tty'} ${exitBadge(rec.tty, "tty")} ${exitBadge(piped, "piped")} ${esc(rec.file)}
+
my-app — zsh — 100×40
+
~/my-app git:(main)${seconds(json ? rec.piped : rec.tty)}
${esc(cmd)}
you@Mac my-app % ${esc(cmd)}
${pane}
+
piped stdout / stderr +
stdout
${esc(piped?.stdout ?? "")}
+
stderr
${esc(piped?.stderr ?? "")}
+
+
`; +} + +/* Within a command: --help, then successful runs, JSON, --debug, and failures last. */ +function cardOrder(rec: GalleryRecord): number { + if (isHelp(rec.args)) return 0; + const result = isJson(rec.args) ? rec.piped : rec.tty; + if (result === null || result.error !== undefined || result.timedOut || result.exitCode !== 0) { + return 4; + } + if (rec.args.includes("--debug")) return 3; + return isJson(rec.args) ? 2 : 1; +} + +/* One section per command: e2e describe names ("orgs:list", "db push") and --help paths share a key. */ +function commandOf(rec: GalleryRecord): string { + if (isHelp(rec.args)) + return rec.args.filter((a) => a !== "--help" && a !== "-h").join(" ") || "supabase"; + return (rec.suite || rec.file).replace(/:/g, " "); +} + +const [recordsDir, outFile] = process.argv.slice(2); +if (!recordsDir || !outFile) { + console.error("usage: bun scripts/gallery.ts "); + process.exit(1); +} + +const records: GalleryRecord[] = readdirSync(recordsDir) + .filter((f) => f.endsWith(".json")) + .map((f) => JSON.parse(readFileSync(join(recordsDir, f), "utf8")) as GalleryRecord) + .sort( + (a, b) => + commandOf(a).localeCompare(commandOf(b)) || + cardOrder(a) - cardOrder(b) || + a.test.localeCompare(b.test), + ); + +const groups = new Map(); +for (const r of records) { + const key = commandOf(r); + groups.set(key, [...(groups.get(key) ?? []), r]); +} + +const count = (kind: string) => records.filter((r) => kindOf(r.args) === kind).length; +const jsonCount = count("json"); +const sectionId = (suite: string) => + `s-${suite.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "")}`; +interface NavNode { + readonly name: string; + readonly path: string; + readonly children: Map; +} +const navRoot: NavNode = { name: "", path: "", children: new Map() }; +for (const command of groups.keys()) { + let node = navRoot; + for (const word of command.split(" ")) { + const path = node.path ? `${node.path} ${word}` : word; + if (!node.children.has(word)) + node.children.set(word, { name: word, path, children: new Map() }); + node = node.children.get(word)!; + } +} +const navLink = (node: NavNode, depth: number): string => { + const recs = groups.get(node.path); + const pad = depth === 0 ? "" : `style="padding-left:8px"`; + return recs + ? `${esc(node.name)}${recs.length}` + : `
${esc(node.name)}
`; +}; +const renderNav = (node: NavNode, depth: number): string => + [...node.children.values()] + .map((child) => + child.children.size === 0 + ? navLink(child, depth) + : `
${navLink(child, depth)}${renderNav(child, depth + 1)}
`, + ) + .join("\n"); +const nav = renderNav(navRoot, 0); +const sections = [...groups] + .map( + ([suite, recs]) => + `

${esc(suite)}

${recs.map(card).join("\n")}
`, + ) + .join("\n"); + +const html = `Supabase CLI output gallery + + +
+

Supabase CLI output gallery

+
+ + + + +Interactive cards show a ${GALLERY_COLUMNS}-column pseudo-terminal re-run; JSON cards show piped stdout. + + +
+${sections} +
+ +`; + +mkdirSync(dirname(outFile), { recursive: true }); +writeFileSync(outFile, html); +console.log( + `wrote ${outFile}: ${records.length} records (${records.length - jsonCount} interactive, ${jsonCount} json)`, +);