demo-this-pr 0.1.0

package/dist/prKit.d.ts

@@ -0,0 +1,2 @@
+import type { PrKitOptions, PrKitResult } from "./types.js";
+export declare function createPrKit(options: PrKitOptions): Promise<PrKitResult>;

package/dist/prKit.js

@@ -0,0 +1,99 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { buildDemoPlan } from "./demoPlan.js";
+import { readGitContext } from "./git.js";
+import { writePlaywrightArtifacts, runPlaywrightDemo } from "./playwright.js";
+import { renderHtmlReport, renderMarkdownReport } from "./report.js";
+import { runShellCommand } from "./shell.js";
+export async function createPrKit(options) {
+    const cwd = resolve(options.cwd);
+    const outputDir = resolve(cwd, options.outputDir);
+    await mkdir(outputDir, { recursive: true });
+    const git = await readGitContext(cwd, options.base);
+    const feature = options.feature?.trim() || titleFromBranch(git.branch);
+    const why = options.why?.trim() || "Explain why this PR exists before requesting review.";
+    const flow = options.flow.length > 0 ? options.flow : defaultFlow(git.changedFiles.map((file) => file.path));
+    const changes = options.changes.length > 0 ? options.changes : defaultChanges(git.changedFiles.map((file) => file.path));
+    const technologies = options.technologies;
+    const demoPlan = await buildDemoPlan({
+        feature,
+        why,
+        demoUrl: options.demoUrl,
+        demoSteps: options.demoSteps,
+        demoPlanPath: options.demoPlanPath
+    });
+    const testResults = [];
+    for (const command of options.testCommands) {
+        testResults.push(await runShellCommand(command, cwd));
+    }
+    demoPlan.context = {
+        changes,
+        technologies,
+        tests: testResults.map((testResult) => ({
+            command: testResult.command,
+            status: testResult.exitCode === 0 ? "passed" : "failed",
+            durationMs: testResult.durationMs
+        })),
+        branch: git.branch,
+        base: git.base,
+        changedFiles: git.changedFiles.map((file) => `${file.status} ${file.path}`)
+    };
+    const { specPath, configPath, planPath, mcpGuidePath, mcpScriptPath } = await writePlaywrightArtifacts(outputDir, demoPlan);
+    const demoRun = options.runDemo
+        ? await runPlaywrightDemo(outputDir, demoPlan, { headed: options.headed })
+        : { attempted: false, passed: false };
+    const result = {
+        outputDir,
+        markdownPath: join(outputDir, "PR_REVIEW.md"),
+        htmlPath: join(outputDir, "PR_REVIEW.html"),
+        demoSpecPath: specPath,
+        demoPlanPath: planPath,
+        mcpGuidePath,
+        mcpScriptPath,
+        git,
+        feature,
+        why,
+        flow,
+        changes,
+        technologies,
+        testResults,
+        demoRun
+    };
+    await writeFile(result.markdownPath, renderMarkdownReport(result), "utf8");
+    await writeFile(result.htmlPath, renderHtmlReport(result), "utf8");
+    return result;
+}
+function defaultChanges(changedFiles) {
+    if (changedFiles.length === 0) {
+        return ["Current branch changes are shown through the configured demo flow."];
+    }
+    const files = changedFiles.slice(0, 5).join(", ");
+    return [`Current branch changes touch: ${files}${changedFiles.length > 5 ? ", ..." : ""}.`];
+}
+function titleFromBranch(branch) {
+    if (!branch || branch === "unknown" || branch === "HEAD") {
+        return "PR review kit";
+    }
+    return branch
+        .replace(/^[a-z]+\/+/iu, "")
+        .split(/[-_/\s]+/u)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function defaultFlow(changedFiles) {
+    const files = changedFiles.slice(0, 4);
+    if (files.length === 0) {
+        return [
+            "Read the PR summary and confirm the intended behavior.",
+            "Run the generated Playwright demo or edit the demo plan.",
+            "Run the listed test commands before requesting review."
+        ];
+    }
+    return [
+        "Start with the PR summary and the reason for the change.",
+        `Review the primary touched files: ${files.join(", ")}${changedFiles.length > files.length ? ", ..." : ""}.`,
+        "Watch or run the Playwright demo to verify the user-visible flow.",
+        "Check the captured test commands and any failing output before approval."
+    ];
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import type { PrKitResult } from "./types.js";
+export declare function renderMarkdownReport(result: PrKitResult): string;
+export declare function renderHtmlReport(result: PrKitResult): string;

package/dist/report.js

@@ -0,0 +1,239 @@
+import { basename } from "node:path";
+export function renderMarkdownReport(result) {
+    const lines = [];
+    lines.push(`# ${result.feature}`);
+    lines.push("");
+    lines.push(`## Why`);
+    lines.push("");
+    lines.push(result.why);
+    lines.push("");
+    lines.push("## Review flow");
+    lines.push("");
+    result.flow.forEach((step, index) => {
+        lines.push(`${index + 1}. ${step}`);
+    });
+    lines.push("");
+    lines.push("## What changed");
+    lines.push("");
+    result.changes.forEach((change) => {
+        lines.push(`- ${change}`);
+    });
+    lines.push("");
+    if (result.technologies.length > 0) {
+        lines.push("## Technology used");
+        lines.push("");
+        result.technologies.forEach((technology) => {
+            lines.push(`- ${technology}`);
+        });
+        lines.push("");
+    }
+    lines.push("## Demo");
+    lines.push("");
+    lines.push("Primary browser flow: Playwright MCP or Playwright Test with isolated Chromium.");
+    lines.push("");
+    lines.push("Video policy: generated locally for review evidence; ignored by git and not uploaded automatically.");
+    lines.push("");
+    lines.push(`MCP guide: \`${basename(result.mcpGuidePath)}\``);
+    lines.push(`MCP script: \`${basename(result.mcpScriptPath)}\``);
+    lines.push("");
+    if (result.demoRun.mp4Path) {
+        lines.push(`<video src="${result.demoRun.mp4Path}" controls width="960"></video>`);
+        lines.push("");
+        lines.push(`[Open local MP4 demo](${result.demoRun.mp4Path})`);
+    }
+    else if (result.demoRun.videoPath) {
+        lines.push(`<video src="${result.demoRun.videoPath}" controls width="960"></video>`);
+        lines.push("");
+        lines.push(`[Open local demo video](${result.demoRun.videoPath})`);
+        if (result.demoRun.conversionError) {
+            lines.push("");
+            lines.push(`MP4 conversion failed: ${result.demoRun.conversionError}`);
+        }
+    }
+    else if (result.demoRun.attempted) {
+        lines.push("Demo attempted, but no video artifact was produced.");
+    }
+    else {
+        lines.push("Demo spec generated but not run yet.");
+    }
+    lines.push("");
+    lines.push(`Optional video spec: \`${basename(result.demoSpecPath)}\``);
+    lines.push("");
+    lines.push("## Testing");
+    lines.push("");
+    if (result.testResults.length === 0) {
+        lines.push("No test command was run. Add `--test \"<command>\"` to capture test evidence.");
+    }
+    else {
+        for (const testResult of result.testResults) {
+            lines.push(formatTestResult(testResult));
+        }
+    }
+    lines.push("");
+    lines.push("## Regression guardrails");
+    lines.push("");
+    lines.push(regressionSummary(result));
+    lines.push("");
+    lines.push("## Changed files");
+    lines.push("");
+    lines.push(renderChangedFiles(result.git));
+    lines.push("");
+    lines.push("## Git context");
+    lines.push("");
+    lines.push(`- Branch: \`${displayGitValue(result.git.branch)}\``);
+    lines.push(`- Base: \`${displayGitValue(result.git.base)}\``);
+    lines.push(`- Head: \`${displayGitValue(result.git.headSha)}\``);
+    if (result.git.commits.length > 0) {
+        lines.push(`- Commits:`);
+        for (const commit of result.git.commits.slice(0, 8)) {
+            lines.push(`  - ${commit}`);
+        }
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+export function renderHtmlReport(result) {
+    const video = result.demoRun.videoPath
+        ? `<video src="${escapeHtml(result.demoRun.videoPath)}" controls></video>`
+        : `<p class="muted">${result.demoRun.attempted ? "Demo attempted, but no video was produced." : "Demo spec generated but not run yet."}</p>`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(result.feature)} · PR review kit</title>
+  <style>
+    :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; background: #f7f8fb; color: #18202f; }
+    main { max-width: 1040px; margin: 0 auto; padding: 40px 24px 64px; }
+    h1 { margin: 0 0 10px; font-size: 32px; letter-spacing: 0; }
+    h2 { margin-top: 32px; font-size: 18px; }
+    p, li { line-height: 1.55; }
+    .panel { background: white; border: 1px solid #d9deea; border-radius: 8px; padding: 22px; margin-top: 18px; }
+    .meta { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+    .pill { border: 1px solid #cad1df; border-radius: 999px; padding: 6px 10px; font-size: 13px; background: #fff; }
+    video { width: 100%; border-radius: 8px; border: 1px solid #ccd3e0; background: #111827; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    pre { white-space: pre-wrap; overflow-wrap: anywhere; background: #101827; color: #edf2ff; padding: 14px; border-radius: 8px; }
+    .muted { color: #647085; }
+    .pass { color: #0f7a43; font-weight: 700; }
+    .fail { color: #b42318; font-weight: 700; }
+    @media (prefers-color-scheme: dark) {
+      body { background: #10131a; color: #edf2ff; }
+      .panel, .pill { background: #161b25; border-color: #2b3446; }
+      .muted { color: #aab4c8; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>${escapeHtml(result.feature)}</h1>
+    <p>${escapeHtml(result.why)}</p>
+    <div class="meta">
+      <span class="pill">Branch: ${escapeHtml(displayGitValue(result.git.branch))}</span>
+      <span class="pill">Base: ${escapeHtml(displayGitValue(result.git.base))}</span>
+      <span class="pill">Head: ${escapeHtml(displayGitValue(result.git.headSha))}</span>
+    </div>
+
+    <section class="panel">
+      <h2>Demo</h2>
+      <p>Primary browser flow: Playwright MCP or Playwright Test with isolated Chromium.</p>
+      <p class="muted">Local-only review evidence. The video is ignored by git and is not uploaded automatically.</p>
+      <p><code>${escapeHtml(basename(result.mcpGuidePath))}</code> · <code>${escapeHtml(basename(result.mcpScriptPath))}</code></p>
+      ${video}
+    </section>
+
+    <section class="panel">
+      <h2>Review flow</h2>
+      <ol>${result.flow.map((step) => `<li>${escapeHtml(step)}</li>`).join("")}</ol>
+    </section>
+
+    <section class="panel">
+      <h2>What changed</h2>
+      <ul>${result.changes.map((change) => `<li>${escapeHtml(change)}</li>`).join("")}</ul>
+    </section>
+
+    ${result.technologies.length > 0 ? `<section class="panel">
+      <h2>Technology used</h2>
+      <ul>${result.technologies.map((technology) => `<li>${escapeHtml(technology)}</li>`).join("")}</ul>
+    </section>` : ""}
+
+    <section class="panel">
+      <h2>Testing</h2>
+      ${renderHtmlTests(result.testResults)}
+    </section>
+
+    <section class="panel">
+      <h2>Regression guardrails</h2>
+      <p>${escapeHtml(regressionSummary(result))}</p>
+    </section>
+
+    <section class="panel">
+      <h2>Changed files</h2>
+      ${renderHtmlChangedFiles(result.git)}
+    </section>
+  </main>
+</body>
+</html>
+`;
+}
+function formatTestResult(result) {
+    const status = result.exitCode === 0 ? "PASS" : "FAIL";
+    const body = trimTestOutput(`${result.stdout}\n${result.stderr}`);
+    const lines = [`- ${status} \`${result.command}\` (${formatMs(result.durationMs)})`];
+    if (body) {
+        lines.push("");
+        lines.push("```text");
+        lines.push(body);
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function displayGitValue(value) {
+    return value && value !== "unknown" && value !== "HEAD" ? value : "unavailable";
+}
+function regressionSummary(result) {
+    const passingTests = result.testResults.filter((testResult) => testResult.exitCode === 0).length;
+    const failingTests = result.testResults.filter((testResult) => testResult.exitCode !== 0).length;
+    const demoStatus = result.demoRun.passed ? "demo passed" : result.demoRun.attempted ? "demo attempted with issues" : "demo not run";
+    return `This PR kit does not claim the change is risk-free. It shows ${passingTests} passing test command(s), ${failingTests} failing test command(s), ${demoStatus}, and ${result.git.changedFiles.length} changed file(s) for review.`;
+}
+function renderChangedFiles(git) {
+    if (git.changedFiles.length === 0) {
+        return git.available ? "No changed files detected against the selected base." : "Git metadata unavailable.";
+    }
+    return git.changedFiles.map((file) => `- ${file.status} \`${file.path}\``).join("\n");
+}
+function renderHtmlChangedFiles(git) {
+    if (git.changedFiles.length === 0) {
+        return `<p class="muted">${git.available ? "No changed files detected against the selected base." : "Git metadata unavailable."}</p>`;
+    }
+    return `<ul>${git.changedFiles.map((file) => `<li><code>${escapeHtml(file.status)} ${escapeHtml(file.path)}</code></li>`).join("")}</ul>`;
+}
+function renderHtmlTests(results) {
+    if (results.length === 0) {
+        return `<p class="muted">No test command was run. Add <code>--test "&lt;command&gt;"</code> to capture test evidence.</p>`;
+    }
+    return results
+        .map((result) => {
+        const passed = result.exitCode === 0;
+        const output = trimTestOutput(`${result.stdout}\n${result.stderr}`);
+        return `<div>
+        <p><span class="${passed ? "pass" : "fail"}">${passed ? "PASS" : "FAIL"}</span> <code>${escapeHtml(result.command)}</code> (${formatMs(result.durationMs)})</p>
+        ${output ? `<pre>${escapeHtml(output)}</pre>` : ""}
+      </div>`;
+    })
+        .join("");
+}
+function trimTestOutput(output) {
+    return output.trim().split("\n").slice(-30).join("\n");
+}
+function formatMs(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function escapeHtml(value) {
+    return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}

package/dist/runs.d.ts

@@ -0,0 +1 @@
+export declare function defaultRunOutputDir(label: string | undefined): string;

package/dist/runs.js

@@ -0,0 +1,30 @@
+export function defaultRunOutputDir(label) {
+    return `.demo-this-pr/runs/${timestamp()}-${slug(normalizeLabel(label))}`;
+}
+function timestamp() {
+    const now = new Date();
+    const pad = (value, size = 2) => String(value).padStart(size, "0");
+    return [
+        now.getFullYear(),
+        pad(now.getMonth() + 1),
+        pad(now.getDate())
+    ].join("")
+        + "-"
+        + [pad(now.getHours()), pad(now.getMinutes()), pad(now.getSeconds())].join("")
+        + `-${pad(now.getMilliseconds(), 3)}`;
+}
+function slug(value) {
+    return value
+        .toLowerCase()
+        .replace(/^[a-z]+\/+/u, "")
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-|-$/gu, "")
+        .slice(0, 56) || "current-changes";
+}
+function normalizeLabel(label) {
+    const trimmed = label?.trim();
+    if (!trimmed || trimmed === "unknown" || trimmed === "HEAD") {
+        return "current-changes";
+    }
+    return trimmed;
+}

package/dist/shell.d.ts

@@ -0,0 +1,3 @@
+import type { CommandResult } from "./types.js";
+export declare function runShellCommand(command: string, cwd: string): Promise<CommandResult>;
+export declare function runProcess(command: string, args: string[], cwd: string): Promise<CommandResult>;

package/dist/shell.js

@@ -0,0 +1,61 @@
+import { spawn } from "node:child_process";
+export async function runShellCommand(command, cwd) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            stderr += `\n${error.message}`;
+        });
+        child.on("close", (exitCode) => {
+            resolve({
+                command,
+                exitCode,
+                durationMs: Date.now() - startedAt,
+                stdout,
+                stderr
+            });
+        });
+    });
+}
+export async function runProcess(command, args, cwd) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            stderr += `\n${error.message}`;
+        });
+        child.on("close", (exitCode) => {
+            resolve({
+                command: [command, ...args].join(" "),
+                exitCode,
+                durationMs: Date.now() - startedAt,
+                stdout,
+                stderr
+            });
+        });
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+export interface PrKitOptions {
+    cwd: string;
+    outputDir: string;
+    feature?: string;
+    why?: string;
+    base?: string;
+    flow: string[];
+    changes: string[];
+    technologies: string[];
+    testCommands: string[];
+    runDemo: boolean;
+    headed: boolean;
+    showReport: boolean;
+    demoUrl?: string;
+    demoSteps: string[];
+    demoPlanPath?: string;
+}
+export interface GitFileChange {
+    status: string;
+    path: string;
+}
+export interface GitContext {
+    available: boolean;
+    root: string;
+    branch: string;
+    base: string;
+    headSha: string;
+    commits: string[];
+    changedFiles: GitFileChange[];
+}
+export interface DemoPlan {
+    title: string;
+    baseUrl?: string;
+    why?: string;
+    context?: DemoContext;
+    steps: DemoStep[];
+}
+export interface DemoContext {
+    changes: string[];
+    technologies: string[];
+    tests: TestSummary[];
+    branch: string;
+    base: string;
+    changedFiles: string[];
+}
+export interface TestSummary {
+    command: string;
+    status: "passed" | "failed";
+    durationMs: number;
+}
+export interface DemoStep {
+    caption?: string;
+    goto?: string;
+    click?: string;
+    fill?: {
+        selector: string;
+        value: string;
+    };
+    press?: {
+        selector: string;
+        key: string;
+    };
+    expectText?: string;
+    screenshot?: string;
+    waitMs?: number;
+}
+export interface CommandResult {
+    command: string;
+    exitCode: number | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+}
+export interface DemoRunResult {
+    attempted: boolean;
+    passed: boolean;
+    command?: string;
+    output?: string;
+    videoPath?: string;
+    webmPath?: string;
+    mp4Path?: string;
+    conversionError?: string;
+    error?: string;
+}
+export interface PrKitResult {
+    outputDir: string;
+    markdownPath: string;
+    htmlPath: string;
+    demoSpecPath: string;
+    demoPlanPath: string;
+    mcpGuidePath: string;
+    mcpScriptPath: string;
+    git: GitContext;
+    feature: string;
+    why: string;
+    flow: string[];
+    changes: string[];
+    technologies: string[];
+    testResults: CommandResult[];
+    demoRun: DemoRunResult;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/viewer.d.ts

@@ -0,0 +1 @@
+export declare function openReportViewer(htmlPath: string): Promise<void>;

package/dist/viewer.js

@@ -0,0 +1,32 @@
+import { pathToFileURL } from "node:url";
+import { chromium } from "@playwright/test";
+export async function openReportViewer(htmlPath) {
+    const browser = await chromium.launch({ headless: false });
+    const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+    await page.goto(pathToFileURL(htmlPath).toString());
+    await page.bringToFront();
+    await new Promise((resolve) => {
+        let finished = false;
+        const finish = async () => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                if (browser.isConnected()) {
+                    await browser.close();
+                }
+            }
+            catch {
+                // Browser may already be closed by the user.
+            }
+            resolve();
+        };
+        browser.on("disconnected", () => {
+            finished = true;
+            resolve();
+        });
+        page.on("close", () => {
+            void finish();
+        });
+    });
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "demo-this-pr",
+  "version": "0.1.0",
+  "description": "Record local PR demos with isolated Playwright Chromium, MP4 evidence, test output, and review-ready reports.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "demo-this-pr": "dist/cli.js",
+    "demo-pr": "dist/cli.js"
+  },
+  "files": [
+    "assets",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "pull-request",
+    "playwright",
+    "demo",
+    "review",
+    "mp4",
+    "developer-tools"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "npm run build && npm test",
+    "dev": "tsx src/cli.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run build",
+    "publish:check": "npm run check && npm run pack:dry-run",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.57.0",
+    "commander": "^14.0.2",
+    "ffmpeg-static": "^5.3.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.13"
+  },
+  "license": "MIT"
+}