demo-this-pr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Miret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+<p align="center">
+  <img src="./assets/demo-this-pr-logo.svg" alt="DEMO THIS PR animated wordmark" width="920">
+</p>
+
+# demo-this-pr
+
+`demo-this-pr` records the current local change before you open a pull request. Run one command from a working tree, get an isolated Chromium demo, a local MP4 with cursor/highlight overlays, captured test output, and a review report that explains what changed.
+
+It is not an AI detector. It is a PR-quality tool for avoiding vague descriptions, missing demos, and unverifiable testing claims.
+
+## One Command
+
+Run this from the repository that has local or unpushed changes:
+
+```bash
+demo-this-pr
+```
+
+Or point it at a repository from anywhere:
+
+```bash
+demo-this-pr --cwd /path/to/repository
+# or
+demo-this-pr /path/to/repository
+```
+
+The command will:
+
+- detect branch changes, including uncommitted files;
+- start the repository dev server when a `dev` script exists;
+- otherwise use a reachable local app on a common localhost port;
+- open isolated Playwright Chromium, never the user's normal Chrome profile;
+- record a slow local MP4 with captions, cursor movement, and highlighted elements;
+- run inferred safe test commands from `package.json`;
+- open a local report so the user can press play immediately;
+- write artifacts into a unique directory under `.demo-this-pr/runs/`.
+
+Each execution gets its own run directory, for example:
+
+```text
+.demo-this-pr/runs/20260515-164322-381-my-feature/
+```
+
+The run label comes from the current branch, then `package.json` `name`, then the folder name. Non-meaningful Git labels such as `HEAD` or `unknown` are not used in generated directory names. Artifacts from previous runs are not overwritten unless you explicitly pass `--output`.
+
+## Installation
+
+During local development of this tool:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+After publishing to npm, the intended installation paths are:
+
+```bash
+npm install -g demo-this-pr
+```
+
+or per repository:
+
+```bash
+npm install --save-dev demo-this-pr
+npx demo-this-pr
+```
+
+For CI or agent runners, prefer a pinned package version and a deterministic
+artifact directory:
+
+```bash
+npx demo-this-pr@0.1.0 ci
+```
+
+The command exits non-zero when Git context or a reachable local app is missing.
+CI systems can archive `.demo-this-pr/ci/` as a build artifact after the command
+finishes.
+
+## Publishing From A Private Repository
+
+The source repository can remain private. The lowest-friction public distribution path is a public npm package named `demo-this-pr` that ships only the compiled CLI, assets, README, package metadata, and license.
+
+Recommended package surface:
+
+- npm package: `demo-this-pr`.
+- CLI binary: `demo-this-pr`.
+- Optional short alias: `demo-pr`.
+- Public files: `dist/`, `assets/`, `README.md`, `package.json`, and `LICENSE`.
+- Private files: source history, local `.demo-this-pr/` runs, generated videos, and internal planning notes.
+
+When the repository is private, avoid public npm metadata that points to private GitHub issues or a private README URL. Add `repository`, `bugs`, and `homepage` later if there is a public docs site, public landing page, or public mirror.
+
+Pre-publish checks:
+
+```bash
+npm run publish:check
+npm publish
+```
+
+`npm run publish:check` builds the TypeScript output, runs tests, and verifies
+the package contents with `npm pack --dry-run`.
+
+## Requirements
+
+Runtime requirements:
+
+- Node.js `>=20`.
+- Git CLI available in `PATH`.
+- A Git working tree; uncommitted files are supported.
+- Run the command from inside the repository that contains the changes, or pass `--cwd <repo>` / `[repo]`. The automatic flow exits if Git context is unavailable instead of generating a generic report.
+- A local web application reachable by HTTP.
+- Playwright Chromium installed for the machine running the tool.
+
+Target project requirements:
+
+- Best case: a `package.json` with a `dev` script that prints a localhost URL.
+- Supported package managers for auto-start: npm, pnpm, Yarn, and Bun.
+- Supported app URLs for fallback detection include common localhost ports: `3000`, `3001`, `5173`, `4173`, `4321`, `8080`, and `8000`.
+- Optional test scripts: `test:ci`, `test`, `typecheck`, and `lint`.
+
+If Chromium is missing, install it once:
+
+```bash
+npx playwright install chromium
+```
+
+## Technical Stack
+
+`demo-this-pr` is a Node.js CLI implemented in TypeScript.
+
+Core stack:
+
+- TypeScript with ESM output.
+- Node.js `child_process` for dev-server and test-command orchestration.
+- Git CLI for branch, base, commit, and working-tree metadata.
+- Commander for CLI parsing.
+- Playwright for isolated Chromium automation, local video capture, screenshots, and report playback.
+- `ffmpeg-static` for WebM-to-MP4 conversion.
+- `picocolors` for terminal output.
+- Vitest for unit tests.
+
+Runtime architecture:
+
+- `src/auto.ts` detects repository context, starts or discovers the local app, infers tests, and builds the default demo plan.
+- `src/playwright.ts` records the Chromium demo, renders overlays, captures screenshots, and converts video to MP4.
+- `src/prKit.ts` writes the review kit.
+- `src/report.ts` renders Markdown and HTML reports.
+- `src/viewer.ts` opens the generated HTML report in isolated Chromium and exits when the viewer closes.
+
+No LLM or external API is required.
+
+## Output
+
+A normal run writes:
+
+```text
+.demo-this-pr/runs/<run-id>/
+  PR_REVIEW.md
+  PR_REVIEW.html
+  MCP_PLAYWRIGHT.md
+  mcp-playwright-demo.js
+  demo-plan.json
+  pr-demo.spec.ts
+  playwright.config.ts
+  assets/
+    demo-this-pr.mp4
+    demo-this-pr.webm
+    screenshots/
+    mcp-screenshots/
+    test-results/
+```
+
+The generated video is local review evidence. `.demo-this-pr/` is ignored by git and the MP4 is not uploaded automatically.
+
+## Common Commands
+
+Generate and open the report:
+
+```bash
+demo-this-pr
+```
+
+Generate without opening the report viewer:
+
+```bash
+demo-this-pr --no-open
+```
+
+Run without a visible browser window:
+
+```bash
+demo-this-pr --headless
+```
+
+Write to an explicit directory:
+
+```bash
+demo-this-pr --output .demo-this-pr/manual-checkout-demo
+```
+
+Generate in CI without a visible browser or report viewer:
+
+```bash
+demo-this-pr ci
+```
+
+Jenkins example:
+
+```groovy
+stage('PR demo') {
+  steps {
+    sh 'npm ci'
+    sh 'npx demo-this-pr@0.1.0 ci'
+  }
+  post {
+    always {
+      archiveArtifacts artifacts: '.demo-this-pr/ci/**', allowEmptyArchive: true
+    }
+  }
+}
+```
+
+`demo-this-pr ci` starts the repository `dev` script when one exists. If the
+application needs a non-standard start command, start it in the pipeline and run
+the explicit `demo` command with `--url`.
+
+Use an explicit flow:
+
+```bash
+demo-this-pr demo \
+  --url http://localhost:3000 \
+  --feature "Project creation flow" \
+  --why "Users can create projects without leaving the dashboard" \
+  --change "Project creation now happens inline" \
+  --tech "Next.js server actions and React form state" \
+  --step "goto:/dashboard" \
+  --step "click:text=New project" \
+  --step "fill:input[name=name]:Demo Project" \
+  --step "click:text=Create" \
+  --step "expect:Demo Project" \
+  --test "npm test"
+```
+
+## Demo Step DSL
+
+```text
+goto:/path
+click:text=Button label
+fill:input[name=email]:user@example.com
+press:input[name=q]:Enter
+expect:Expected text on screen
+screenshot:after-action
+wait:500
+```
+
+For richer demos, generate a JSON plan:
+
+```bash
+demo-this-pr init-demo --output demo-this-pr.demo.json
+```
+
+Then run:
+
+```bash
+demo-this-pr demo --demo-plan demo-this-pr.demo.json
+```
+
+## Playwright MCP
+
+Every run also writes an MCP-first browser verification guide:
+
+```text
+MCP_PLAYWRIGHT.md
+mcp-playwright-demo.js
+```
+
+Agents with Playwright MCP can load `mcp-playwright-demo.js` through `mcp__playwright__.browser_run_code_unsafe`, run the same browser flow, capture screenshots, and close the MCP tab afterwards.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run check
+```
+
+The repository includes a root `AGENTS.md` with the local browser-testing policy and implementation standards for future agents.

package/assets/demo-this-pr-logo.svg

@@ -0,0 +1,41 @@
+<svg width="1200" height="330" viewBox="0 0 1200 330" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">DEMO THIS PR animated wordmark</title>
+  <desc id="desc">Animated terminal-style wordmark reading DEMO THIS PR.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="330" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0B0F14"/>
+      <stop offset="0.58" stop-color="#111820"/>
+      <stop offset="1" stop-color="#171D24"/>
+    </linearGradient>
+    <linearGradient id="ink" x1="90" y1="0" x2="1090" y2="0" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#F8FAFC"/>
+      <stop offset="0.55" stop-color="#E7EEF7"/>
+      <stop offset="1" stop-color="#B9C7D7"/>
+    </linearGradient>
+    <filter id="shadow" x="-10%" y="-40%" width="120%" height="190%">
+      <feDropShadow dx="8" dy="8" stdDeviation="0" flood-color="#748094" flood-opacity="0.42"/>
+      <feDropShadow dx="13" dy="13" stdDeviation="0" flood-color="#334155" flood-opacity="0.5"/>
+      <feDropShadow dx="0" dy="22" stdDeviation="18" flood-color="#000000" flood-opacity="0.4"/>
+    </filter>
+  </defs>
+
+  <rect x="32" y="34" width="1136" height="262" rx="18" fill="url(#bg)"/>
+  <rect x="32" y="34" width="1136" height="262" rx="18" stroke="#2B3542" stroke-width="2"/>
+
+  <text x="78" y="82" fill="#91A4BA" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace" font-size="17" font-weight="800" letter-spacing="4">LOCAL PR DEMOS · PLAYWRIGHT MP4 · REVIEW EVIDENCE</text>
+
+  <g filter="url(#shadow)" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace" font-size="104" font-weight="950" letter-spacing="0" fill="url(#ink)">
+    <g><text x="78" y="202">D</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -11;0 0" dur="2.8s" begin="0s" repeatCount="indefinite"/></g>
+    <g><text x="145" y="202">E</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -9;0 0" dur="2.8s" begin="0.08s" repeatCount="indefinite"/></g>
+    <g><text x="212" y="202">M</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -13;0 0" dur="2.8s" begin="0.16s" repeatCount="indefinite"/></g>
+    <g><text x="296" y="202">O</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -10;0 0" dur="2.8s" begin="0.24s" repeatCount="indefinite"/></g>
+    <g><text x="410" y="202">T</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -8;0 0" dur="2.8s" begin="0.32s" repeatCount="indefinite"/></g>
+    <g><text x="477" y="202">H</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -12;0 0" dur="2.8s" begin="0.4s" repeatCount="indefinite"/></g>
+    <g><text x="544" y="202">I</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -9;0 0" dur="2.8s" begin="0.48s" repeatCount="indefinite"/></g>
+    <g><text x="611" y="202">S</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -13;0 0" dur="2.8s" begin="0.56s" repeatCount="indefinite"/></g>
+    <g><text x="728" y="202">P</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -10;0 0" dur="2.8s" begin="0.64s" repeatCount="indefinite"/></g>
+    <g><text x="795" y="202">R</text><animateTransform attributeName="transform" type="translate" values="0 0;0 -12;0 0" dur="2.8s" begin="0.72s" repeatCount="indefinite"/></g>
+  </g>
+
+  <text x="78" y="264" fill="#91A4BA" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace" font-size="17" font-weight="800" letter-spacing="2">SHOW THE CHANGE BEFORE THE PULL REQUEST</text>
+</svg>

package/dist/auto.d.ts

@@ -0,0 +1,17 @@
+import type { GitFileChange, PrKitOptions } from "./types.js";
+export interface AutoDemoResult {
+    options: PrKitOptions;
+    cleanup(): Promise<void>;
+    notes: string[];
+}
+export declare function resolveAutoDemo(cwd: string, overrides: {
+    headless: boolean;
+    output?: string;
+    open: boolean;
+}): Promise<AutoDemoResult>;
+export declare function titleForAutoRun(input: {
+    gitAvailable?: boolean;
+    branch: string;
+    commits: string[];
+    changedFiles: GitFileChange[];
+}): string;