@juangadm/pre-post 0.1.0

package/dist/upload.js

@@ -0,0 +1,116 @@
+/**
+ * Image upload for generating shareable URLs.
+ * Default: git-native (commits to .pre-post/ on current branch).
+ * Opt-in: 0x0.st, Vercel Blob, generic PUT via --upload-url.
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const DEFAULT_UPLOAD_URL = 'https://0x0.st';
+/**
+ * Upload an image and return a public URL.
+ * Auto-detects upload method from URL pattern.
+ */
+export async function uploadImage(image, filename, uploadUrl = DEFAULT_UPLOAD_URL) {
+    // 0x0.st uses multipart form upload
+    if (uploadUrl.includes('0x0.st')) {
+        return upload0x0st(image, filename, uploadUrl);
+    }
+    // Vercel Blob uses PUT with specific headers
+    if (uploadUrl.includes('blob.vercel')) {
+        return uploadVercelBlob(image, filename, uploadUrl);
+    }
+    // Generic PUT upload (common for S3-compatible services)
+    return uploadGenericPut(image, filename, uploadUrl);
+}
+async function upload0x0st(image, filename, url) {
+    const formData = new FormData();
+    formData.append('file', new Blob([image]), filename);
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'User-Agent': 'before-after-cli/1.0' },
+        body: formData,
+    });
+    const result = (await response.text()).trim();
+    if (!result.startsWith('http')) {
+        throw new Error(`Upload failed: ${result}`);
+    }
+    return result;
+}
+async function uploadVercelBlob(image, filename, url) {
+    const response = await fetch(`${url}/${filename}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'image/png' },
+        body: image,
+    });
+    if (!response.ok) {
+        throw new Error(`Upload failed: ${response.statusText}`);
+    }
+    const result = await response.json();
+    return result.url;
+}
+async function uploadGenericPut(image, filename, url) {
+    const response = await fetch(`${url}/${filename}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'image/png' },
+        body: image,
+    });
+    if (!response.ok) {
+        throw new Error(`Upload failed: ${response.statusText}`);
+    }
+    // Try to parse JSON response, fall back to URL from location header or constructed URL
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        const result = await response.json();
+        if (result.url)
+            return result.url;
+    }
+    return response.headers.get('location') || `${url}/${filename}`;
+}
+/**
+ * Write an image to .pre-post/ in the repo root, stage it, and return
+ * the raw.githubusercontent.com URL it will resolve to after push.
+ */
+export function uploadGitNative(image, filename) {
+    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+    const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+    // Parse owner/repo from HTTPS or SSH remote URL
+    const ownerRepo = remoteUrl
+        .replace(/^(https?:\/\/github\.com\/|git@github\.com:)/, '')
+        .replace(/\.git$/, '');
+    const destDir = path.join(repoRoot, '.pre-post');
+    fs.mkdirSync(destDir, { recursive: true });
+    const dest = path.join(destDir, filename);
+    fs.writeFileSync(dest, image);
+    execSync(`git add -f "${dest}"`);
+    return `https://raw.githubusercontent.com/${ownerRepo}/${branch}/.pre-post/${filename}`;
+}
+/**
+ * Commit and push all staged .pre-post/ screenshots in one batch.
+ */
+export function commitAndPushScreenshots() {
+    execSync('git commit -m "chore: add pre/post screenshots"');
+    execSync('git push origin HEAD');
+}
+/**
+ * Upload before/after images and return URLs.
+ * When uploadUrl is provided, uses the HTTP-based upload path.
+ * Otherwise, uses git-native (commit to .pre-post/).
+ */
+export async function uploadBeforeAfter(before, after, uploadUrl) {
+    // If an explicit upload URL is provided, use HTTP upload
+    if (uploadUrl) {
+        const [beforeUrl, afterUrl] = await Promise.all([
+            uploadImage(before.image, before.filename, uploadUrl),
+            uploadImage(after.image, after.filename, uploadUrl),
+        ]);
+        return { beforeUrl, afterUrl };
+    }
+    // Default: git-native — stage both, then commit+push once
+    const beforeUrl = uploadGitNative(before.image, before.filename);
+    const afterUrl = uploadGitNative(after.image, after.filename);
+    commitAndPushScreenshots();
+    return { beforeUrl, afterUrl };
+}
+//# sourceMappingURL=upload.js.map

package/dist/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"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"}

package/dist/viewport.d.ts

@@ -0,0 +1,3 @@
+import { ViewportConfig, ViewportSize } from './types.js';
+export declare function resolveViewport(config?: ViewportConfig): ViewportSize;
+//# sourceMappingURL=viewport.d.ts.map

package/dist/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAoC,MAAM,YAAY,CAAC;AAE5F,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,YAAY,CAQrE"}

package/dist/viewport.js

@@ -0,0 +1,11 @@
+import { VIEWPORT_PRESETS } from './types.js';
+export function resolveViewport(config) {
+    if (!config) {
+        return VIEWPORT_PRESETS.desktop;
+    }
+    if (typeof config === 'string') {
+        return VIEWPORT_PRESETS[config];
+    }
+    return config;
+}
+//# sourceMappingURL=viewport.js.map

package/dist/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE5F,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,gBAAgB,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,gBAAgB,CAAC,MAAwB,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@juangadm/pre-post",
+  "version": "0.1.0",
+  "description": "Visual diff tool for PRs — captures before/after screenshots of web pages",
+  "author": "Juan Gabriel Delgado (forked from James Clements)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juangadm/pre-post.git"
+  },
+  "homepage": "https://github.com/juangadm/pre-post",
+  "bugs": {
+    "url": "https://github.com/juangadm/pre-post/issues"
+  },
+  "keywords": [
+    "screenshot",
+    "before-after",
+    "visual-diff",
+    "comparison",
+    "capture",
+    "web",
+    "testing",
+    "cli",
+    "playwright",
+    "pr-screenshots"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pre-post": "dist/bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.pkg.json",
+    "prepublishOnly": "rm -rf dist && npm run build && npm run test:unit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:browser": "vitest run tests/browser",
+    "test:integration": "vitest run tests/integration"
+  },
+  "dependencies": {
+    "playwright": "^1.50.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "5.7.3",
+    "vitest": "^3.2.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "@types/react": "19.2.7",
+      "@types/react-dom": "19.2.3"
+    }
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: pre-post
+description: Captures before/after screenshots of web pages for visual comparison in PRs. Use when user says "take before and after", "screenshot comparison", "visual diff", "PR screenshots", or after making visual UI changes.
+allowed-tools:
+  - Bash(npx pre-post *)
+  - Bash(pre-post *)
+  - Bash(*/upload-and-copy.sh *)
+  - Bash(git add *)
+  - Bash(git commit -m *)
+  - Bash(git push origin *)
+  - Bash(curl -s -o /dev/null -w *)
+  - Bash(gh pr view *)
+  - Bash(gh pr edit *)
+  - Bash(lsof -i *)
+  - Bash(mkdir -p /tmp/pre-post)
+  - Bash(git diff *)
+---
+
+# Pre-Post Screenshot Skill
+
+> **Package:** `pre-post`
+> Visual diff tool for PRs — fastest path from code change to visual documentation.
+
+## Agent Behavior Rules
+
+**DO NOT:**
+- Switch git branches, stash changes, start dev servers, or assume what "before" is
+- Use `--full` unless user explicitly asks for full page / full scroll capture
+- Post screenshots to PR without user approval
+
+**DO:**
+- Use `--markdown` when user wants PR integration or markdown output
+- Use `--responsive` to capture both desktop and mobile viewports
+- Use `--mobile` / `--tablet` if user mentions phone, mobile, tablet, responsive
+- Assume current state is **After** (localhost = after, production = before)
+- Show screenshots to user before posting to PR
+- If user provides only one URL, **ASK**: "What URL should I use for the 'before' state? (production URL, preview deployment, or another local port)"
+
+## Execution Order
+
+### 1. Pre-flight Checks
+
+```bash
+# Detect running dev server
+lsof -i :3000 2>/dev/null || lsof -i :3001 2>/dev/null || lsof -i :5173 2>/dev/null || lsof -i :8080 2>/dev/null
+```
+
+If no dev server is running, tell the user to start one.
+
+```bash
+# Check production URL is accessible
+curl -s -o /dev/null -w "%{http_code}" "<production-url>"
+```
+
+- **200** → proceed
+- **401/403** → warn user: "Production URL requires authentication. Options: (1) provide a public URL, (2) skip 'before' and capture after-only, (3) provide auth cookies"
+- **No production URL** → "after-only" mode: screenshot localhost only, label as current state
+
+### 2. Route Detection + Refinement
+
+```bash
+# Detect affected routes from git diff
+npx pre-post detect
+```
+
+This outputs JSON with detected routes, confidence levels, and source files.
+
+**Claude's role:** Review the JSON output using conversation context:
+- Add routes you know are affected from the work done in this session
+- Remove false positives (e.g., API-only changes)
+- For dynamic routes (e.g., `/blog/[slug]`), ask user for a sample value
+- Present to user: "I'll screenshot these routes: `/dashboard`, `/settings`. Want to add or change any?"
+
+### 3. Screenshot Capture
+
+**Option A: CLI (preferred — deterministic)**
+
+```bash
+# Single route, desktop only
+npx pre-post compare \
+  --before-base https://prod.com \
+  --after-base http://localhost:3000 \
+  --routes /dashboard \
+  --output /tmp/pre-post
+
+# Multiple routes, responsive (desktop + mobile)
+npx pre-post compare \
+  --before-base https://prod.com \
+  --after-base http://localhost:3000 \
+  --routes /dashboard,/settings,/ \
+  --responsive \
+  --output /tmp/pre-post
+```
+
+**Option B: Playwright MCP (for more control)**
+
+Use when you need custom waits, interactions, or complex page states:
+
+```
+browser_resize(1280, 800)
+browser_navigate("https://prod.com/dashboard")
+browser_wait_for(time: 3)
+browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-before.png")
+
+browser_navigate("http://localhost:3000/dashboard")
+browser_wait_for(time: 3)
+browser_take_screenshot(filename: "/tmp/pre-post/dashboard-desktop-after.png")
+
+# Mobile
+browser_resize(375, 812)
+browser_navigate("https://prod.com/dashboard")
+browser_wait_for(time: 3)
+browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-before.png")
+
+browser_navigate("http://localhost:3000/dashboard")
+browser_wait_for(time: 3)
+browser_take_screenshot(filename: "/tmp/pre-post/dashboard-mobile-after.png")
+```
+
+### 4. User Approval
+
+Show screenshots in conversation. Ask: "Here are the before/after screenshots. Should I post to PR, retake any, or add more pages?"
+
+### 5. Upload + PR Markdown
+
+```bash
+# Upload and generate markdown
+mkdir -p /tmp/pre-post
+./scripts/upload-and-copy.sh /tmp/pre-post/before.png /tmp/pre-post/after.png --markdown
+```
+
+Or use the CLI's built-in upload:
+
+```bash
+npx pre-post <before.png> <after.png> --markdown
+```
+
+For multi-route PRs, generate this format:
+
+```markdown
+## Visual Changes
+
+### `/dashboard`
+
+<details open>
+<summary>Desktop (1280x800)</summary>
+
+| Pre | Post |
+|:---:|:----:|
+| ![Pre](url) | ![Post](url) |
+</details>
+
+<details>
+<summary>Mobile (375x812)</summary>
+
+| Pre | Post |
+|:---:|:----:|
+| ![Pre](url) | ![Post](url) |
+</details>
+
+---
+*Captured by [pre-post](https://github.com/juangadm/pre-post)*
+```
+
+### 6. PR Integration
+
+```bash
+# Get current PR
+gh pr view --json number,body
+
+# Append screenshots to PR body
+gh pr edit <number> --body "<existing-body>
+
+<generated-markdown>"
+```
+
+If no `gh` CLI: output markdown and tell user to paste manually.
+
+## Quick Reference
+
+```bash
+# Basic usage (two URLs)
+pre-post site.com localhost:3000
+
+# Detect routes from git diff
+pre-post detect
+pre-post detect --framework nextjs-app
+
+# Compare with auto-detected routes
+pre-post run --before-base https://prod.com --after-base http://localhost:3000
+
+# Compare specific routes
+pre-post compare --before-base URL --after-base URL --routes /dashboard,/settings
+
+# Responsive (desktop + mobile)
+pre-post compare --before-base URL --after-base URL --responsive
+
+# From existing images
+pre-post before.png after.png --markdown
+
+# Via npx
+npx pre-post detect
+npx pre-post compare --before-base URL --after-base URL
+```
+
+| Flag | Description |
+|------|-------------|
+| `-m, --mobile` | Mobile viewport (375x812) |
+| `-t, --tablet` | Tablet viewport (768x1024) |
+| `--size <WxH>` | Custom viewport |
+| `-f, --full` | Full scrollable page |
+| `-s, --selector` | CSS selector to capture |
+| `-r, --responsive` | Desktop + mobile capture |
+| `--routes <paths>` | Explicit route list (comma-separated) |
+| `--max-routes <n>` | Max detected routes (default: 5) |
+| `--framework <name>` | Force framework detection |
+| `--before-base <url>` | Production URL |
+| `--after-base <url>` | Localhost URL |
+| `-o, --output` | Output directory (default: ~/Downloads) |
+| `--markdown` | Upload images & output markdown |
+| `--upload-url <url>` | Upload endpoint (overrides git-native default) |
+
+## Image Upload
+
+Screenshots are committed to `.pre-post/` on the current PR branch and served via `raw.githubusercontent.com`. This is the default — no external services needed.
+
+```bash
+# Default (git-native — commits to PR branch)
+./scripts/upload-and-copy.sh before.png after.png --markdown
+
+# Fallback: 0x0.st (no signup needed, 365-day expiry)
+IMAGE_ADAPTER=0x0st ./scripts/upload-and-copy.sh before.png after.png --markdown
+
+# GitHub Gist
+IMAGE_ADAPTER=gist ./scripts/upload-and-copy.sh before.png after.png --markdown
+```
+
+## Error Reference
+
+| Error | Fix |
+|-------|-----|
+| `command not found` | `npm install -g pre-post` |
+| `browserType.launch: Executable doesn't exist` | `npx playwright install chromium` |
+| 401/403 on production URL | See pre-flight section above |
+| Element not found | Verify selector exists on page |
+| No changed files detected | Specify routes manually with `--routes` |

package/skill/scripts/adapters/0x0st.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# 0x0.st adapter - Free, no-signup file hosting
+# https://0x0.st
+#
+# Usage: ./0x0st.sh <file>
+# Output: URL to uploaded file (stdout)
+#
+# Notes:
+#   - Files expire after 365 days (or sooner for larger files)
+#   - Max file size: 512 MiB
+#   - No authentication required
+
+set -e
+
+FILE="$1"
+
+if [[ -z "$FILE" ]]; then
+    echo "Usage: $0 <file>" >&2
+    exit 1
+fi
+
+if [[ ! -f "$FILE" ]]; then
+    echo "Error: File not found: $FILE" >&2
+    exit 1
+fi
+
+# Upload to 0x0.st - returns the URL directly
+URL=$(curl -s -A "before-after-cli/1.0" -F "file=@$FILE" https://0x0.st)
+
+# Validate we got a URL back
+if [[ ! "$URL" =~ ^https?:// ]]; then
+    echo "Error: Upload failed. Response: $URL" >&2
+    exit 1
+fi
+
+echo "$URL"

package/skill/scripts/adapters/blob.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Custom blob storage adapter - For self-hosted or custom endpoints
+#
+# Usage: ./blob.sh <file>
+# Output: URL to uploaded file (stdout)
+#
+# Environment:
+#   BLOB_UPLOAD_URL    Required. URL endpoint for uploading images
+#
+# Notes:
+#   - Expects endpoint to accept multipart form upload with "file" field
+#   - Expects response to be either:
+#     - Plain text URL
+#     - JSON with "url" field
+
+set -e
+
+FILE="$1"
+
+if [[ -z "$FILE" ]]; then
+    echo "Usage: $0 <file>" >&2
+    exit 1
+fi
+
+if [[ ! -f "$FILE" ]]; then
+    echo "Error: File not found: $FILE" >&2
+    exit 1
+fi
+
+if [[ -z "$BLOB_UPLOAD_URL" ]]; then
+    echo "Error: BLOB_UPLOAD_URL environment variable not set" >&2
+    echo "" >&2
+    echo "Set it with:" >&2
+    echo "  export BLOB_UPLOAD_URL='https://your-blob-service.com/upload'" >&2
+    exit 1
+fi
+
+# Upload file
+RESPONSE=$(curl -s -X POST -F "file=@$FILE" "$BLOB_UPLOAD_URL")
+
+# Try to extract URL from JSON response
+URL=$(echo "$RESPONSE" | grep -o '"url"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"url"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//' || true)
+
+# Fallback: maybe the response is just the URL
+if [[ -z "$URL" ]]; then
+    URL="$RESPONSE"
+fi
+
+# Validate we got a URL back
+if [[ ! "$URL" =~ ^https?:// ]]; then
+    echo "Error: Upload failed. Response: $RESPONSE" >&2
+    exit 1
+fi
+
+echo "$URL"

package/skill/scripts/adapters/gist.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# GitHub Gist adapter - Upload images via gh CLI
+#
+# Usage: ./gist.sh <file>
+# Output: Raw URL to uploaded file (stdout)
+#
+# Requirements:
+#   - gh CLI installed and authenticated
+#
+# Notes:
+#   - Creates a public gist for each upload
+#   - Files persist indefinitely
+#   - Requires GitHub authentication
+
+set -e
+
+FILE="$1"
+
+if [[ -z "$FILE" ]]; then
+    echo "Usage: $0 <file>" >&2
+    exit 1
+fi
+
+if [[ ! -f "$FILE" ]]; then
+    echo "Error: File not found: $FILE" >&2
+    exit 1
+fi
+
+# Check gh is available
+if ! command -v gh &> /dev/null; then
+    echo "Error: gh CLI not found. Install from https://cli.github.com" >&2
+    exit 1
+fi
+
+# Create gist and capture output
+GIST_OUTPUT=$(gh gist create "$FILE" --public 2>&1)
+
+# Extract the gist URL from output
+GIST_URL=$(echo "$GIST_OUTPUT" | grep -o 'https://gist.github.com/[^ ]*' | head -1)
+
+if [[ -z "$GIST_URL" ]]; then
+    echo "Error: Failed to create gist. Output: $GIST_OUTPUT" >&2
+    exit 1
+fi
+
+# Convert to raw URL
+# Format: https://gist.github.com/user/id -> https://gist.githubusercontent.com/user/id/raw/filename
+GIST_ID=$(echo "$GIST_URL" | sed 's|.*/||')
+FILENAME=$(basename "$FILE")
+
+# Get the raw URL via gh api
+RAW_URL=$(gh api "gists/$GIST_ID" --jq ".files[\"$FILENAME\"].raw_url")
+
+if [[ -z "$RAW_URL" ]]; then
+    echo "Error: Could not get raw URL for gist" >&2
+    exit 1
+fi
+
+echo "$RAW_URL"

package/skill/scripts/adapters/git-native.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Git-native adapter - Commit screenshots to .pre-post/ on the PR branch
+#
+# Usage: ./git-native.sh <file>
+# Output: raw.githubusercontent.com URL (stdout)
+#
+# Requirements:
+#   - Inside a git repo with a remote named "origin"
+#   - Current branch pushed to origin
+#
+# Notes:
+#   - Stages only the specific file, never `git add .`
+#   - Does NOT commit or push — the caller (upload-and-copy.sh) batches that
+#   - Returns the raw GitHub URL the file will be available at after push
+
+set -e
+
+FILE="$1"
+
+if [[ -z "$FILE" ]]; then
+    echo "Usage: $0 <file>" >&2
+    exit 1
+fi
+
+if [[ ! -f "$FILE" ]]; then
+    echo "Error: File not found: $FILE" >&2
+    exit 1
+fi
+
+# Must be inside a git repo
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+    echo "Error: Not inside a git repository" >&2
+    exit 1
+fi
+
+# Parse owner/repo from origin remote
+REMOTE_URL=$(git remote get-url origin 2>/dev/null)
+if [[ -z "$REMOTE_URL" ]]; then
+    echo "Error: No 'origin' remote found" >&2
+    exit 1
+fi
+
+# Extract owner/repo from HTTPS or SSH URL
+# HTTPS: https://github.com/owner/repo.git
+# SSH:   git@github.com:owner/repo.git
+OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's#^(https?://github\.com/|git@github\.com:)##; s#\.git$##')
+
+if [[ -z "$OWNER_REPO" || ! "$OWNER_REPO" =~ / ]]; then
+    echo "Error: Could not parse owner/repo from remote: $REMOTE_URL" >&2
+    exit 1
+fi
+
+# Get current branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+if [[ -z "$BRANCH" || "$BRANCH" == "HEAD" ]]; then
+    echo "Error: Could not determine current branch (detached HEAD?)" >&2
+    exit 1
+fi
+
+# Copy file into .pre-post/ at the repo root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+DEST_DIR="$REPO_ROOT/.pre-post"
+mkdir -p "$DEST_DIR"
+
+FILENAME=$(basename "$FILE")
+DEST="$DEST_DIR/$FILENAME"
+cp "$FILE" "$DEST"
+
+# Stage only this specific file (-f to override .gitignore)
+git add -f "$DEST"
+
+echo "Staged: .pre-post/$FILENAME" >&2
+
+# Return the raw GitHub URL (will resolve after push)
+echo "https://raw.githubusercontent.com/$OWNER_REPO/$BRANCH/.pre-post/$FILENAME"