better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-har-derived-api-client.md

@@ -1,180 +0,0 @@
----
-title: "Har Derived Api Client — Record a site's XHR into a HAR, derive an HTTP client"
-sidebar_label: "Har Derived Api Client"
-description: "Record a site's XHR into a HAR, derive an HTTP client"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Har Derived Api Client
-
-Record a site's XHR into a HAR, derive an HTTP client.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/web-development/har-derived-api-client` |
-| Path | `optional-skills/web-development\har-derived-api-client` |
-| Version | `0.1.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Browser`, `HAR`, `API`, `Reverse-Engineering`, `Playwright` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# HAR-Derived API Client
-
-Drive a website once with a real browser while recording its network traffic
-to a HAR file, then distill that HAR into the site's private JSON API so you
-can call it directly with plain HTTP — far cheaper and faster than
-browser-controlling the page on every request. Credit: trick by Jared Longster,
-popularized by Dax (thdxr). This captures and replays; it does NOT bypass
-auth, solve CAPTCHAs, or defeat bot-detection — if the site needs a logged-in
-session, you carry its headers/cookies forward, you don't forge them.
-
-The scripts are stdlib-plus-Playwright: capture needs Playwright, derivation
-is pure stdlib, replay needs only `requests`/`httpx` (or `curl`).
-
-Covers **every Hermes browser pathway**: the default local `browser_navigate`
-backend, plus the cloud/remote backends (Browserbase, Browser-Use, Firecrawl)
-and any `/browser connect` CDP endpoint. There are two capture scripts — one
-for a browser you launch, one for a browser you attach to over CDP — because
-HAR recording works differently in each case (see How to Run).
-
-## When to Use
-
-- "Build a CLI/client for <website>" — derive its API instead of scripting clicks.
-- "This site has no public API but the page clearly fetches JSON."
-- You're about to loop `browser_navigate` for the same query repeatedly — stop and derive the endpoint once.
-- Reverse-engineering an autocomplete, search, feed, or checkout XHR.
-- You captured a session on a cloud backend (Browserbase / Browser-Use / Firecrawl) or via `/browser connect` and want the API without re-renting the browser.
-
-## Prerequisites
-
-- Playwright + a browser binary (capture step only):
-  - `pip install playwright` then `playwright install chromium`
-  - (If a system Playwright already has browsers under `~/.cache/ms-playwright`, reuse it.)
-- `requests` or `httpx` for the replay step (stdlib `urllib` also works).
-- No API keys. Any keys/tokens the client needs are the ones the HAR captured.
-- For the CDP path (`har_capture_cdp.py`): a reachable CDP endpoint. On Hermes,
-  run `/browser connect` to print the active endpoint, or read `BROWSER_CDP_URL`
-  / `browser.cdp_url` in config. Cloud backends expose it as `cdpUrl`/`connectUrl`.
-
-## How to Run
-
-Scripts under this skill's `scripts/`, invoked through the `terminal` tool.
-**Pick the capturer by pathway** — this is the part that trips people up:
-
-| Browser pathway | How Hermes reaches it | Capturer |
-|---|---|---|
-| Local `browser_navigate` (default, agent-browser/Playwright) | launched locally | `har_capture.py` |
-| Camofox (`CAMOFOX_URL` set) | local REST/CDP | `har_capture_cdp.py` if it exposes CDP, else drive it yourself |
-| Browserbase / Browser-Use / Firecrawl (cloud) | **CDP** (`cdpUrl`) | `har_capture_cdp.py` |
-| `/browser connect <url>` / `BROWSER_CDP_URL` | **CDP** | `har_capture_cdp.py` |
-
-Rule of thumb: **if Hermes *launched* the browser, use `har_capture.py`; if it
-*connected to* one over CDP, use `har_capture_cdp.py`.** `har_capture.py` uses
-Playwright's `record_har_path`, which only works on a locally-owned context.
-`har_capture_cdp.py` attaches with `connect_over_cdp()` and assembles the HAR
-from `page.on("request"/"response")` events, because `record_har_path` is
-unavailable on a connected browser.
-
-Then, for either path:
-
-- `har_to_client.py` — filters the HAR to XHR/fetch/JSON, groups by endpoint, and prints params, headers, bodies, and replay hints (User-Agent / cookie / auth).
-
-Resolve paths against this skill's directory. Canonical loop:
-
-```bash
-# 1a. Capture, LOCAL browser (Hermes launched it)
-python3 scripts/har_capture.py "https://SITE/" out.har \
-  --action "fill:input[name=search]:my query" --action "sleep:3" --wait 2
-
-# 1b. Capture, CDP browser (cloud backend or /browser connect)
-#     get the endpoint from /browser connect or BROWSER_CDP_URL
-python3 scripts/har_capture_cdp.py "ws://HOST/devtools/browser/..." out.har \
-  --goto "https://SITE/" --action "fill:input[name=search]:my query" \
-  --action "sleep:3" --wait 2
-
-# 2. Derive — read the endpoints out of the HAR
-python3 scripts/har_to_client.py out.har --host SITE --max-body 400
-
-# 3. Replay — write a tiny client from the printed endpoint (see Procedure)
-```
-
-## Quick Reference
-
-```
-har_capture.py <url> <out.har> [--wait S] [--headed] [--action SPEC ...]
-  action SPEC:  fill:SELECTOR:TEXT | press:SELECTOR:KEY | click:SELECTOR
-                goto:URL | sleep:SECONDS      (run in order after page load)
-  use when Hermes LAUNCHED the browser (local browser_navigate default)
-
-har_capture_cdp.py <cdp_url> <out.har> [--goto URL] [--wait S] [--action SPEC ...]
-  same action SPEC; attaches to an existing CDP browser and does NOT close it
-  use for cloud backends (Browserbase/Browser-Use/Firecrawl) & /browser connect
-
-har_to_client.py <in.har> [--host SUBSTR] [--include-static] [--max-body N]
-  default: keeps only XHR/fetch/JSON; --host narrows to one domain
-  prints per endpoint: query params, non-boring req headers, req body sample,
-                       response status/content-type + body sample
-  prints "### Replay hints": the browser User-Agent, cookie/auth presence
-```
-
-## Procedure
-
-0. **Pick the capturer by pathway** (see How to Run table). Launched-locally → `har_capture.py`; reached over CDP → `har_capture_cdp.py`. On Hermes, `/browser connect` tells you the CDP endpoint when a cloud/remote backend is active.
-1. **Find the interaction.** Open the site with `browser_navigate` (or `--headed` capture) to see which selector to type into / click, and confirm a JSON XHR fires in devtools/network.
-2. **Capture the HAR** via the `terminal` tool. Order `--action` to reach the request: `fill` the box, then `sleep` long enough for the debounced XHR, and always leave `--wait` at the end so late responses flush. Both capturers embed response bodies, so the derived client sees real payload shapes.
-3. **Derive** with `har_to_client.py --host <domain>`. Read off: the method, the URL/path template (numeric/UUID segments collapse to `{id}`), query params, request-body JSON, and the `### Replay hints` block.
-4. **Write the client.** Recreate the request exactly — same method, path, query params, body. Send the headers the site actually needs: at minimum copy the **User-Agent** from the replay hints. If hints report cookies or an auth/token header, resend those too.
-5. **Test browserless.** Run the client with the `terminal` tool and confirm it returns the same data the browser saw. This is the payoff: no browser in the loop.
-6. **(Optional) Wrap as a CLI** — a small `argparse` script over the derived call, e.g. `search.py "frank herbert"`.
-
-Worked example (Wikipedia search-title, derived + replayed live):
-
-```python
-import requests
-r = requests.get(
-    "https://en.wikipedia.org/w/rest.php/v1/search/title",
-    params={"q": "frank herbert", "limit": 5},
-    headers={"accept": "application/json",
-             "User-Agent": "Mozilla/5.0 ... Chrome/131 Safari/537.36"},  # from HAR
-    timeout=15,
-)
-for p in r.json()["pages"]:
-    print(p["title"], "-", p.get("description"))
-```
-
-## Pitfalls
-
-- **Default library User-Agent gets 403.** Many sites (Wikipedia, Cloudflare-fronted APIs) reject `python-requests/x.y`. Always send the browser UA from the replay hints. This is the #1 reason a derived client fails when the browser succeeded.
-- **A failed `--action` aborts before the HAR flushes** — you get no file. If capture errors on a selector, the run produced nothing; fix the selector (use `--headed` to watch) and rerun. Don't debug a missing HAR.
-- **Server-rendered pages have no XHR** to derive — `har_to_client.py` prints "No API-looking entries". The data came in the HTML; scrape it or find the interaction that does fetch JSON.
-- **Debounced/typeahead XHRs need a real pause.** Add `--action "sleep:3"` after `fill`; typing alone won't have fired the request when the HAR closes.
-- **Auth/session endpoints** need the captured `Cookie`/`Authorization` header, and those expire. The derived client is only as durable as the credential; re-capture when it 401s. HARs contain live secrets — treat `out.har` as sensitive and delete it after deriving.
-- **`record_har_content="embed"` makes big HARs.** Use `--max-body` to cap what's printed; the file itself can be large for media-heavy pages.
-- **Endpoints shift.** Sites change private APIs without notice. Re-run the capture→derive loop when a client breaks rather than patching URLs by hand.
-- **Wrong capturer = empty/no HAR.** `har_capture.py` on a cloud/CDP backend records nothing (it launches its own local browser instead of the one you meant). `har_capture_cdp.py` needs the endpoint; on Hermes get it from `/browser connect` or `BROWSER_CDP_URL`. Match the capturer to the pathway (How to Run table).
-- **Headless-Chrome UA is a weak tell.** Local/agent-browser capture yields a `HeadlessChrome/...` User-Agent; some sites sniff the "Headless" token. Cloud backends (Browserbase/Browser-Use) send a real desktop-Chrome UA, so a client derived from a cloud capture replays more reliably. If a headless-derived client 403s where the browser didn't, swap the "Headless" UA for a normal Chrome UA string before assuming the endpoint changed.
-- **CDP capture doesn't close the browser.** `har_capture_cdp.py` attaches to a browser it doesn't own and leaves it running — correct for cloud/remote sessions Hermes manages. Don't add a close; let the owning backend tear it down.
-
-## Verification
-
-End-to-end proof against a live site with no API key:
-
-```bash
-python3 scripts/har_capture.py "https://en.wikipedia.org/wiki/Main_Page" /tmp/wiki.har \
-  --action "fill:input[name=search]:dune messiah" --action "sleep:3" --wait 2
-python3 scripts/har_to_client.py /tmp/wiki.har --host wikipedia.org --max-body 200
-```
-
-Expect the derivation to print `GET https://en.wikipedia.org/w/rest.php/v1/search/title`
-with `q` and `limit` params and a JSON `pages` response — then replay it with the
-Procedure snippet and confirm matching titles come back over plain HTTP.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-page-agent.md

@@ -1,207 +0,0 @@
----
-title: "Page Agent — Embed an in-page natural-language GUI copilot in web apps"
-sidebar_label: "Page Agent"
-description: "Embed an in-page natural-language GUI copilot in web apps"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Page Agent
-
-Embed an in-page natural-language GUI copilot in web apps.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/web-development/page-agent` |
-| Path | `optional-skills/web-development\page-agent` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `web`, `javascript`, `agent`, `browser`, `gui`, `alibaba`, `embed`, `copilot`, `saas` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# page-agent
-
-alibaba/page-agent (https://github.com/alibaba/page-agent, 17k+ stars, MIT) is an in-page GUI agent written in TypeScript. It lives inside a webpage, reads the DOM as text (no screenshots, no multi-modal LLM), and executes natural-language instructions like "click the login button, then fill username as John" against the current page. Pure client-side — the host site just includes a script and passes an OpenAI-compatible LLM endpoint.
-
-## When to use this skill
-
-Load this skill when a user wants to:
-
-- **Ship an AI copilot inside their own web app** (SaaS, admin panel, B2B tool, ERP, CRM) — "users on my dashboard should be able to type 'create invoice for Acme Corp and email it' instead of clicking through five screens"
-- **Modernize a legacy web app** without rewriting the frontend — page-agent drops on top of existing DOM
-- **Add accessibility via natural language** — voice / screen-reader users drive the UI by describing what they want
-- **Demo or evaluate page-agent** against a local (Ollama) or hosted (Qwen, OpenAI, OpenRouter) LLM
-- **Build interactive training / product demos** — let an AI walk a user through "how to submit an expense report" live in the real UI
-
-## When NOT to use this skill
-
-- User wants **Hermes itself to drive a browser** → use Hermes' built-in browser tool (Browserbase / Camofox). page-agent is the *opposite* direction.
-- User wants **cross-tab automation without embedding** → use Playwright, browser-use, or the page-agent Chrome extension
-- User needs **visual grounding / screenshots** → page-agent is text-DOM only; use a multimodal browser agent instead
-
-## Prerequisites
-
-- Node 22.13+ or 24+, npm 10+ (docs claim 11+ but 10.9 works fine)
-- An OpenAI-compatible LLM endpoint: Qwen (DashScope), OpenAI, Ollama, OpenRouter, or anything speaking `/v1/chat/completions`
-- Browser with devtools (for debugging)
-
-## Path 1 — 30-second demo via CDN (no install)
-
-Fastest way to see it work. Uses alibaba's free testing LLM proxy — **for evaluation only**, subject to their terms.
-
-Add to any HTML page (or paste into the devtools console as a bookmarklet):
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>
-```
-
-A panel appears. Type an instruction. Done.
-
-Bookmarklet form (drop into bookmarks bar, click on any page):
-
-```javascript
-javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();
-```
-
-## Path 2 — npm install into your own web app (production use)
-
-Inside an existing web project (React / Vue / Svelte / plain):
-
-```bash
-npm install page-agent
-```
-
-Wire it up with your own LLM endpoint — **never ship the demo CDN to real users**:
-
-```javascript
-import { PageAgent } from 'page-agent'
-
-const agent = new PageAgent({
-    model: 'qwen3.5-plus',
-    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-    apiKey: process.env.LLM_API_KEY,   // never hardcode
-    language: 'en-US',
-})
-
-// Show the panel for end users:
-agent.panel.show()
-
-// Or drive it programmatically:
-await agent.execute('Click submit button, then fill username as John')
-```
-
-Provider examples (any OpenAI-compatible endpoint works):
-
-| Provider | `baseURL` | `model` |
-|----------|-----------|---------|
-| Qwen / DashScope | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.5-plus` |
-| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
-| Ollama (local) | `http://localhost:11434/v1` | `qwen3:14b` |
-| OpenRouter | `https://openrouter.ai/api/v1` | `anthropic/claude-sonnet-4.6` |
-
-**Key config fields** (passed to `new PageAgent({...})`):
-
-- `model`, `baseURL`, `apiKey` — LLM connection
-- `language` — UI language (`en-US`, `zh-CN`, etc.)
-- Allowlist and data-masking hooks exist for locking down what the agent can touch — see https://alibaba.github.io/page-agent/ for the full option list
-
-**Security.** Don't put your `apiKey` in client-side code for a real deployment — proxy LLM calls through your backend and point `baseURL` at your proxy. The demo CDN exists because alibaba runs that proxy for evaluation.
-
-## Path 3 — clone the source repo (contributing, or hacking on it)
-
-Use this when the user wants to modify page-agent itself, test it against arbitrary sites via a local IIFE bundle, or develop the browser extension.
-
-```bash
-git clone https://github.com/alibaba/page-agent.git
-cd page-agent
-npm ci              # exact lockfile install (or `npm i` to allow updates)
-```
-
-Create `.env` in the repo root with an LLM endpoint. Example:
-
-```
-LLM_MODEL_NAME=gpt-4o-mini
-LLM_API_KEY=sk-...
-LLM_BASE_URL=https://api.openai.com/v1
-```
-
-Ollama flavor:
-
-```
-LLM_BASE_URL=http://localhost:11434/v1
-LLM_API_KEY=NA
-LLM_MODEL_NAME=qwen3:14b
-```
-
-Common commands:
-
-```bash
-npm start           # docs/website dev server
-npm run build       # build every package
-npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
-npm run dev:ext     # develop the browser extension (WXT + React)
-npm run build:ext   # build the extension
-```
-
-**Test on any website** using the local IIFE bundle. Add this bookmarklet:
-
-```javascript
-javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();
-```
-
-Then: `npm run dev:demo`, click the bookmarklet on any page, and the local build injects. Auto-rebuilds on save.
-
-**Warning:** your `.env` `LLM_API_KEY` is inlined into the IIFE bundle during dev builds. Don't share the bundle. Don't commit it. Don't paste the URL into Slack. (Verified: grepping the public dev bundle returns the literal values from `.env`.)
-
-## Repo layout (Path 3)
-
-Monorepo with npm workspaces. Key packages:
-
-| Package | Path | Purpose |
-|---------|------|---------|
-| `page-agent` | `packages/page-agent/` | Main entry with UI panel |
-| `@page-agent/core` | `packages/core/` | Core agent logic, no UI |
-| `@page-agent/mcp` | `packages/mcp/` | MCP server (beta) |
-| — | `packages/llms/` | LLM client |
-| — | `packages/page-controller/` | DOM ops + visual feedback |
-| — | `packages/ui/` | Panel + i18n |
-| — | `packages/extension/` | Chrome/Firefox extension |
-| — | `packages/website/` | Docs + landing site |
-
-## Verifying it works
-
-After Path 1 or Path 2:
-1. Open the page in a browser with devtools open
-2. You should see a floating panel. If not, check the console for errors (most common: CORS on the LLM endpoint, wrong `baseURL`, or a bad API key)
-3. Type a simple instruction matching something visible on the page ("click the Login link")
-4. Watch the Network tab — you should see a request to your `baseURL`
-
-After Path 3:
-1. `npm run dev:demo` prints `Accepting connections at http://localhost:5174`
-2. `curl -I http://localhost:5174/page-agent.demo.js` returns `HTTP/1.1 200 OK` with `Content-Type: application/javascript`
-3. Click the bookmarklet on any site; panel appears
-
-## Pitfalls
-
-- **Demo CDN in production** — don't. It's rate-limited, uses alibaba's free proxy, and their terms forbid production use.
-- **API key exposure** — any key passed to `new PageAgent({apiKey: ...})` ships in your JS bundle. Always proxy through your own backend for real deployments.
-- **Non-OpenAI-compatible endpoints** fail silently or with cryptic errors. If your provider needs native Anthropic/Gemini formatting, use an OpenAI-compatibility proxy (LiteLLM, OpenRouter) in front.
-- **CSP blocks** — sites with strict Content-Security-Policy may refuse to load the CDN script or disallow inline eval. In that case, self-host from your origin.
-- **Restart dev server** after editing `.env` in Path 3 — Vite only reads env at startup.
-- **Node version** — the repo declares `^22.13.0 || >=24`. Node 20 will fail `npm ci` with engine errors.
-- **npm 10 vs 11** — docs say npm 11+; npm 10.9 actually works fine.
-
-## Reference
-
-- Repo: https://github.com/alibaba/page-agent
-- Docs: https://alibaba.github.io/page-agent/
-- License: MIT (built on browser-use's DOM processing internals, Copyright 2024 Gregor Zunic)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/web-development/web-development-publish-site.md

@@ -1,174 +0,0 @@
----
-title: "Publish Site — Versioned site deploys to GitHub/Cloudflare/Netlify Pages"
-sidebar_label: "Publish Site"
-description: "Versioned site deploys to GitHub/Cloudflare/Netlify Pages"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Publish Site
-
-Versioned site deploys to GitHub/Cloudflare/Netlify Pages.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/web-development/publish-site` |
-| Path | `optional-skills/web-development\publish-site` |
-| Version | `1.0.0` |
-| Author | Hermes Agent (Nous Research) |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `publish`, `deploy`, `hosting`, `github-pages`, `cloudflare-pages`, `netlify`, `static-site`, `versioning`, `rollback`, `web-development` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Publish Site
-
-Take a website, dashboard, or web app the user built (or you built for them) and put it online on infrastructure the user owns — GitHub Pages by default, Cloudflare Pages or Netlify when they need more. The discipline: preview locally for sign-off, version every deploy with a git tag, deploy through a provider ladder, verify the live URL with a real HTTP check, and keep rollback one command away.
-
-This skill covers static sites and SPA build output (plain HTML/CSS/JS, or the `dist/`/`build/` folder from Vite/Next-export/Astro/etc.). It does not cover server-side runtimes — for throwaway serverless deploys with zero account setup, use the `cloudflare-temporary-deploy` optional skill instead.
-
-## When to Use
-
-Load this skill when the user asks to:
-
-- **Put a site online** — "publish this", "host this somewhere", "give me a link I can share"
-- **Deploy a dashboard, report, portfolio, docs site, or prototype** you just generated
-- **Update an already-published site** with new content (redeploy = new version)
-- **Roll back** a bad deploy to the previous version
-- **Pick a host** — they don't care where, they just want a URL
-
-## Prerequisites
-
-At least ONE authenticated provider CLI (check in this order):
-
-- **GitHub Pages (default):** `gh auth status` succeeds. Needs `git` too.
-- **Cloudflare Pages:** `wrangler whoami` succeeds (or `CLOUDFLARE_API_TOKEN` is set). Install: `npm i -g wrangler` or use `npx wrangler@latest`.
-- **Netlify (fallback):** `netlify status` succeeds. Install: `npm i -g netlify-cli`.
-
-Plus:
-
-- A directory of static output to publish (site root or a `dist/`/`build/` folder). If the project needs a build step, run it first and publish the output directory, never the source.
-- For local preview sharing: `cloudflared` (optional — `python3 -m http.server` covers local-only preview).
-
-## How to Run
-
-All commands below run via the `terminal` tool from the site's project directory. The pipeline is always the same five moves:
-
-1. Build → 2. Preview for sign-off → 3. Commit + tag (version-before-deploy) → 4. Deploy via the provider ladder → 5. Verify the live URL with `curl` and report it.
-
-## Quick Reference
-
-| Step | Command |
-|---|---|
-| Local preview | `python3 -m http.server 8080 --directory dist` |
-| Shareable preview | `cloudflared tunnel --url http://localhost:8080` |
-| Version a deploy | `git add -A && git commit -m "deploy: <what>" && git tag deploy-YYYYMMDD-HHMM` |
-| GitHub Pages (branch mode) | `git subtree push --prefix dist origin gh-pages` |
-| Enable Pages on repo | `gh api repos/{owner}/{repo}/pages -X POST -f 'source[branch]=gh-pages' -f 'source[path]=/'` |
-| Cloudflare Pages | `npx wrangler@latest pages deploy dist --project-name <name>` |
-| Netlify | `netlify deploy --prod --dir dist` |
-| Rollback | `git checkout <previous-tag> -- . && redeploy` (or provider dashboard) |
-| Verify live | `curl -sS -o /dev/null -w '%{http_code}' <url>` → expect `200` |
-
-## Procedure
-
-### 1. Build and preview locally
-
-Build if needed (`npm run build`, etc.) and identify the output directory. Serve it:
-
-```bash
-python3 -m http.server 8080 --directory dist
-```
-
-For a shareable preview link (user on another machine, or you want their sign-off before going live), open a quick tunnel in a background `terminal` session:
-
-```bash
-cloudflared tunnel --url http://localhost:8080
-```
-
-Give the user the `https://*.trycloudflare.com` URL and get sign-off before deploying. Kill the tunnel afterwards.
-
-### 2. Version before deploy — no exceptions
-
-Every deploy must come from a git commit, so every deploy is reproducible and rollback is trivial.
-
-```bash
-git init 2>/dev/null; git add -A
-git commit -m "deploy: <short description>"
-git tag "deploy-$(date +%Y%m%d-%H%M)"
-```
-
-If the project already has a repo, just commit + tag. Never deploy uncommitted files.
-
-### 3. Deploy — provider ladder
-
-**Rung 1 — GitHub Pages (default: free, zero extra accounts if `gh` is authed):**
-
-```bash
-gh repo create <name> --public --source . --push   # skip if repo exists
-git subtree push --prefix dist origin gh-pages      # publish build output
-gh api "repos/{owner}/<name>/pages" -X POST \
-  -f 'source[branch]=gh-pages' -f 'source[path]=/'  # first time only
-```
-
-Site appears at `https://<owner>.github.io/<name>/`. If the site is the repo root (no build dir), push `main` and set Pages source to `main` instead of using subtree. For build-step projects that will redeploy often, prefer the official `actions/deploy-pages` workflow so pushes auto-publish.
-
-**Rung 2 — Cloudflare Pages (when the user wants a custom domain, redirects/headers, or Functions):**
-
-```bash
-npx wrangler@latest pages deploy dist --project-name <name>
-```
-
-First run creates the project and prints the `https://<name>.pages.dev` URL. Custom domains attach via the Cloudflare dashboard (Pages → project → Custom domains).
-
-**Rung 3 — Netlify (fallback, or when the user already lives there):**
-
-```bash
-netlify deploy --prod --dir dist
-```
-
-`netlify deploy --dir dist` (no `--prod`) gives a draft URL — useful as a second preview stage.
-
-### 4. Rollback
-
-Rollback = redeploy a previous tag. Never hand-edit live output.
-
-```bash
-git checkout deploy-<previous> -- .   # or: git checkout deploy-<previous>; rebuild
-# then rerun the same deploy command from step 3
-```
-
-Cloudflare Pages and Netlify also keep per-deploy history in their dashboards ("Rollback to this deploy"), which is faster when the CLI isn't handy.
-
-### 5. Secrets and environment variables
-
-- **NEVER commit secrets, API keys, or `.env` files** — they'd be public on Pages hosting. Check with `git status` before the first commit and keep `.env*` in `.gitignore`.
-- Runtime env vars belong in the provider's dashboard: Cloudflare Pages → Settings → Environment variables; Netlify → Site settings → Environment variables. GitHub Pages is static-only — no server env; anything embedded in the bundle is public by definition. Warn the user if their build inlines a key.
-
-## Pitfalls
-
-- **SPA routes 404 on GitHub Pages.** Pages has no rewrite rules. Copy `index.html` to `404.html` in the output dir (`cp dist/index.html dist/404.html`) so client-side routing recovers. Cloudflare Pages and Netlify handle SPAs via `_redirects` (`/* /index.html 200`).
-- **GitHub Pages build lag.** The site can take 1–10 minutes to appear after the first enable, and ~1 minute per subsequent push. Don't declare failure on the first 404 — poll `curl` a few times before investigating.
-- **Case-sensitive paths.** Pages hosts are case-sensitive Linux; a site that worked on macOS/Windows can 404 on assets referenced as `Logo.PNG` but committed as `logo.png`. Grep the HTML for mismatched casing when an asset 404s.
-- **Project-page base path.** `https://<owner>.github.io/<name>/` serves under `/<name>/` — absolute asset URLs like `/app.js` break. Use relative paths or set the build tool's base (`vite build --base=/<name>/`).
-- **`wrangler` auth flow needs a browser.** `wrangler login` opens OAuth; in a headless session prefer `CLOUDFLARE_API_TOKEN` (user creates it at dash.cloudflare.com → API Tokens) and never echo the token into logs.
-- **DNS propagation on custom domains.** New CNAMEs can take minutes to hours. Verify against the provider's default URL (`*.pages.dev`, `*.netlify.app`, `*.github.io`) first, then check the custom domain separately — don't conflate the two failures.
-- **Deploying source instead of build output.** Publishing the repo root when the real site lives in `dist/` yields a directory listing or raw JSX. Always confirm the output dir contains an `index.html`.
-
-## Verification
-
-Do NOT report success from the deploy log alone. Before telling the user anything:
-
-1. `curl -sS -o /dev/null -w '%{http_code}' <live-url>` returns `200` (retry over ~2 minutes for a first GitHub Pages deploy).
-2. `curl -sS <live-url> | head -30` shows the expected `index.html` content — optionally confirm markup with `web_extract` on the live URL.
-3. For SPAs, also curl one deep route (e.g. `/about`) and confirm it returns `200`, not `404`.
-4. `git tag --list 'deploy-*'` shows the tag for this deploy.
-
-Then report the live URL to the user, along with the deploy tag they can roll back to.