GitHub - Amal-David/pagecast: Publish local HTML, Markdow...

Preview local HTML reports, Markdown docs, and static mini apps, then publish them to shareable Cloudflare Pages URLs from the terminal or your coding agent.

Live app: https://pagecasthq.pages.dev/

About

Pagecast is a local-first publishing tool for agent-generated reports and small static web projects. It gives you a local admin UI for previewing files, managing published versions, renaming links, re-syncing updates, and revoking old URLs. For automation, it exposes headless pagecast publish commands, a small Cloudflare Pages CLI abstraction, and Codex / Claude agent skills.

Good fits:

HTML reports, dashboards, coverage output, Playwright or Lighthouse reports.
Markdown plans, proposals, release notes, docs, and summaries.
Static mini apps from build folders such as dist, build, out, or public.
Coding-agent workflows that should ask before publishing a finished artifact.

Not a fit:

Private drafts or scratch notes.
Server-rendered apps that need a running backend.
Python/Ruby/Node services unless they first export static assets.

Requirements

Node.js 20 or newer.
npx for one-command use.
A Cloudflare account for public publishing.
pnpm only when rebuilding the web UI from web/.

The root CLI/server has no runtime npm dependencies. The React admin UI is built from web/ into public/ and is already included in the package.

Install And Run

Use Pagecast without installing it globally:

This starts the local app and opens the admin UI.

Admin UI: http://127.0.0.1:4173
Local published-page server: http://127.0.0.1:4174
Local data/config: .pagecast/ in your current working directory

Use the admin UI on 4173 for normal work. The 4174 server is intentionally separate: it serves local published-page routes such as /p/<slug>/ so Pagecast can preview the same URL shape it deploys to Cloudflare Pages. Its root path is not an app and returns 404; use /healthz only to check that it is running.

From a clone:

git clone https://github.com/Amal-David/pagecast.git
cd pagecast
npm start

First-Time Cloudflare Setup

Run the app once:

Open the Cloudflare Pages panel and click Connect Cloudflare. Pagecast uses scoped Wrangler OAuth (account:read, user:read, pages:write), detects your account, and creates the Pages project if needed.

Or do the same setup from the terminal:

npx pagecast pages setup --project pagecast

If you prefer a token for automation, create a scoped Cloudflare API token with Account > Cloudflare Pages > Edit permission, then run:

CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ACCOUNT_ID=... npx pagecast pages status --json

If more than one Cloudflare account is available, Pagecast asks you to choose the account once in the admin UI, or you can pass it directly:

npx pagecast pages setup --account 90e4c638bea527f464ec6fa7caebfd4e --project pagecast

Publish From The Terminal

Publish an HTML file:

npx pagecast publish "/absolute/path/report.html" --json
# -> {"ok":true,"url":"https://<project>.pages.dev/p/<token>/", ...}

Publish Markdown:

npx pagecast publish "/absolute/path/report.md" --json

Publish a static web project as a shareable snapshot by building first, then publishing the generated entry file:

npm run build
npx pagecast publish "$(pwd)/dist/index.html" --json

This creates a /p/<token>/ link and stages sibling assets from the build folder.

Deploy a whole static folder directly to a named Cloudflare Pages project:

npx pagecast publish site "$(pwd)/dist" --project pagecasthq --branch main --json

--branch is optional. If you omit it, Pagecast deploys to main:

npx pagecast pages deploy "$(pwd)/dist" --project pagecasthq --json

That command is the Pagecast abstraction over raw Wrangler deploys. It replaces:

CLOUDFLARE_ACCOUNT_ID=90e4c638bea527f464ec6fa7caebfd4e npx wrangler pages deploy /private/tmp/pagecasthq-deploy --project-name pagecasthq --branch main

with:

npx pagecast pages deploy /private/tmp/pagecasthq-deploy --project pagecasthq --branch main --json

Direct site deploys replace the target Pages project contents. For source-folder build settings, link renaming, re-sync, and revoke controls, use the app:

Common headless errors:

{"ok":false,"statusCode":401}: run npx pagecast pages setup once, or run npx pagecast and connect Cloudflare.
{"ok":false,"statusCode":409}: pass --account <account-id>, or run npx pagecast once and choose the Cloudflare account.

Cloudflare Pages Commands

Pagecast wraps the Wrangler commands needed for normal Pages publishing:

npx pagecast pages setup --project pagecast --json
npx pagecast pages status --json
npx pagecast pages projects list --json
npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --branch main --json
npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --json

Agents and CI should prefer --json. Human terminal output stays concise by default. Direct deploys use main when --branch is not provided.

Chrome Extension (Local to Public)

When an agent writes an HTML file and opens it as file:///…/report.html, the bundled Chrome extension adds a one-click Publish to Pagecast button. It publishes the local file through your running Pagecast server and returns a public link; re-publishing the same file updates the same URL.

Install (load unpacked):

chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder.
Open the extension's Details and enable "Allow access to file URLs".
Run npx pagecast (connected to Cloudflare), open a local .html/.md file, click the toolbar icon → Publish.

The server must be running (a browser extension can't start it). The admin server exposes a POST /api/publish-local { path } endpoint and reflects CORS only for chrome-extension:// origins. See extension/README.md for details.

Use From Codex And Other Agents

Pagecast includes a Codex-native skill and a portable Agent-Skills file. The skill tells the agent to offer once for finished, shareable HTML/Markdown/static artifacts and to publish only after explicit confirmation.

Codex CLI Or Codex Desktop

From a clone of this repo:

mkdir -p ~/.codex/skills
cp -R .codex/skills/publish-report ~/.codex/skills/

Start a new Codex session, then ask:

Use $publish-report to publish /absolute/path/report.md with Pagecast.

For a web project:

Use $publish-report to build this project and publish dist/index.html with Pagecast.

Claude Code

/plugin marketplace add Amal-David/pagecast
/plugin install pagecast@pagecast

This installs the portable publish-report skill and the Claude Code report-detection hook.

Other Agent-Skills Tools

Copy the portable skill into your agent's skills folder:

cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md

More detail is in plugin/README.md.

Admin UI Features

Add .html, .htm, .md, and .markdown files by absolute path or file:///... URL.
Add deployable static folders.
Add source folders with an explicit build command and output directory.
Drop or choose HTML/Markdown files and browser-supported folder uploads.
Drag to reorder reports.
Publish a shareable URL, revoke one version, or revoke all versions for a report.
Rename a published URL. Old links redirect to the new path.
Re-sync a published page in place at the same URL.
Enable auto-sync for path-backed reports.
Edit HTML in the app without overwriting the original source file.

Local Development

Run the packaged app from source:

Run the verification suite:

Rebuild the React admin UI into public/:

Work on the React UI with Vite:

pnpm -C web install --frozen-lockfile --ignore-scripts
npm start
pnpm -C web run dev

Vite runs on http://127.0.0.1:5173 and proxies /api, /preview, and /p to the local Pagecast server on http://127.0.0.1:4173.

Project Layout

src/                         Node CLI, server, Cloudflare Pages publisher
public/                      Built admin UI served by the package
web/                         Vite + React source for the admin UI
plugin/                      Claude/portable Agent-Skills integration
.codex/skills/publish-report/ Codex-native Pagecast skill
llms.txt                     Agent-readable command and workflow map
test/                        Node test suite

Packaging And Release Checks

Before publishing a package:

npm run build
npm run check
npm test
npm pack --dry-run

The npm package includes src/, public/, plugin/, llms.txt, and the Codex skill under .codex/skills/publish-report/.

Security Model

The admin UI binds to 127.0.0.1.
Draft previews are admin-only local routes.
Public access works only through active /p/<token>/ publication links.
Revoked publication tokens return 404 after the Pages redeploy finishes.
Public report routes reject parent-directory traversal and hidden-file paths.
Path-based reports and snapshots include non-hidden sibling assets from the report folder, so anything in that folder can become public if referenced or guessed.
The Pages root does not publish a report listing.

License

Pagecast is released under the MIT License. See LICENSE.

Contributing

Issues and pull requests are welcome. Keep changes focused, run the verification commands above, and rebuild public/ with npm run build whenever you change files under web/.

推荐订阅源

Show HN