pagecast 0.1.0

package/.codex/skills/publish-report/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: publish-report
+description: Publish finished local HTML, Markdown, or built static web projects with Pagecast. Use when the user asks Codex to publish, share, make a public link for, or send a local report/doc/dashboard/web project from terminal, Codex CLI, or Codex desktop, or when Codex has just created a substantial shareable .html, .htm, .md, .markdown, or static build output.
+---
+
+# Publish With Pagecast
+
+## Overview
+
+Use Pagecast to turn a finished local artifact into a shareable public URL backed
+by the user's Cloudflare Pages project. Prefer `pagecast publish <file>` for
+reports, docs, and built entry files. Use `pagecast publish site <dir>` only when
+the user intentionally wants to deploy a whole static folder to a named
+Cloudflare Pages project.
+
+Never publish without explicit confirmation. Publishing makes the selected
+artifact publicly reachable.
+
+## What To Publish
+
+Offer once for finished, shareable artifacts:
+
+- HTML reports, dashboards, coverage reports, Playwright/Lighthouse output, or
+  static single-page mini apps.
+- Markdown reports, plans, docs, proposals, release notes, or summaries meant to
+  be read by someone else.
+- Static web projects after they are built. Publish the generated entry file,
+  usually `dist/index.html`, `build/index.html`, `out/index.html`, or
+  `public/index.html`; Pagecast stages sibling assets from that output folder.
+
+Do not offer for scratch notes, source files, repo metadata, README/CHANGELOG,
+AGENTS.md/CLAUDE.md, task files, secrets, config files, dependency/build folders,
+hidden files, or anything the user has not made shareable.
+
+## Confirmation
+
+Ask one direct question before publishing:
+
+```text
+Want me to publish this with Pagecast?
+```
+
+Proceed only after an explicit yes. If the user declines or ignores the offer,
+drop it and do not ask again for that artifact.
+
+## Headless CLI Workflow
+
+Resolve the target to an absolute path, then run:
+
+```sh
+npx pagecast publish "/absolute/path/to/report-or-built-index.html" --json
+```
+
+Markdown works too:
+
+```sh
+npx pagecast publish "/absolute/path/to/report.md" --json
+```
+
+For a web project that should get a new shareable `/p/<token>/` link:
+
+1. Run the project's existing build command, such as `npm run build`, only if the
+   user expects the current project state to be published.
+2. Find the static output entry file, usually `dist/index.html`,
+   `build/index.html`, `out/index.html`, or `public/index.html`.
+3. Publish that entry file with `npx pagecast publish "<absolute-entry-path>" --json`.
+
+If the user asks to deploy or update an entire static site/project rather than
+create a new share link, deploy the built folder directly:
+
+```sh
+npx pagecast publish site "/absolute/path/to/dist" --project "project-name" --branch main --json
+```
+
+`--branch` is optional and defaults to `main`, so this also works:
+
+```sh
+npx pagecast pages deploy "/absolute/path/to/dist" --project "project-name" --json
+```
+
+Use this instead of raw Wrangler commands like `npx wrangler pages deploy`.
+Direct site deploys replace the target Cloudflare Pages project contents, so do
+not guess the `--project`; use the user's named project or ask for it.
+
+Parse stdout as JSON:
+
+- Success: `{ "ok": true, "url": "https://<project>.pages.dev/p/<token>/", ... }`
+  Return the `url` and mention that the user can rename, re-sync, or revoke it
+  from `npx pagecast`.
+- `401`: the user has not connected Cloudflare. Tell them to run
+  `npx pagecast pages setup` once, or run `npx pagecast` and click
+  **Connect Cloudflare**, then retry if they want.
+- `409`: multiple Cloudflare accounts are available. Tell them to run
+  `npx pagecast pages setup --account <account-id>` once, or run `npx pagecast`
+  and choose the account, then retry.
+- Other errors: relay the error concisely and do not claim success.
+
+## Cloudflare Pages Workflow
+
+Use these lower-level commands when the user explicitly asks about Cloudflare
+setup or project deployment:
+
+```sh
+npx pagecast pages setup --project "project-name" --json
+npx pagecast pages status --json
+npx pagecast pages projects list --json
+npx pagecast pages deploy "/absolute/path/to/dist" --project "project-name" --branch main --json
+```
+
+If the user does not specify a branch, omit `--branch`; Pagecast deploys to
+`main`.
+
+`pages deploy` is the Pagecast abstraction over `npx wrangler pages deploy`; it
+passes the account to Wrangler internally through `CLOUDFLARE_ACCOUNT_ID` when
+needed.
+
+## App Workflow
+
+Use the app when the user needs to manage folders or existing links:
+
+```sh
+npx pagecast
+```
+
+The app opens at `http://127.0.0.1:4173` and supports:
+
+- Adding HTML/Markdown files.
+- Adding deployable static folders.
+- Adding source folders with an explicit build command and output directory.
+- Publishing, renaming, re-syncing, and revoking URLs.
+
+## Codex Usage Notes
+
+- From Codex CLI or desktop, run terminal commands in the user's current project
+  directory so `.pagecast/` config and publish history stay with that project.
+- Always use absolute paths in `pagecast publish` and `pagecast pages deploy`.
+- If the user asks only for a command, provide the command and any one-time setup
+  note instead of running it.
+- If the user asks Codex to publish, run the command after confirmation and
+  report the resulting URL or exact failure.

package/.codex/skills/publish-report/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Pagecast"
+  short_description: "Publish local reports with Pagecast."
+  default_prompt: "Use $publish-report to publish this finished local HTML, Markdown, or static web project with Pagecast."
+
+policy:
+  allow_implicit_invocation: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pagecast
+
+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,318 @@
+# Pagecast
+
+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:
+
+```sh
+npx pagecast
+```
+
+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:
+
+```sh
+git clone https://github.com/Amal-David/pagecast.git
+cd pagecast
+npm start
+```
+
+## First-Time Cloudflare Setup
+
+Run the app once:
+
+```sh
+npx pagecast
+```
+
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+npx pagecast pages setup --account 90e4c638bea527f464ec6fa7caebfd4e --project pagecast
+```
+
+## Publish From The Terminal
+
+Publish an HTML file:
+
+```sh
+npx pagecast publish "/absolute/path/report.html" --json
+# -> {"ok":true,"url":"https://<project>.pages.dev/p/<token>/", ...}
+```
+
+Publish Markdown:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+npx pagecast publish site "$(pwd)/dist" --project pagecasthq --branch main --json
+```
+
+`--branch` is optional. If you omit it, Pagecast deploys to `main`:
+
+```sh
+npx pagecast pages deploy "$(pwd)/dist" --project pagecasthq --json
+```
+
+That command is the Pagecast abstraction over raw Wrangler deploys. It replaces:
+
+```sh
+CLOUDFLARE_ACCOUNT_ID=90e4c638bea527f464ec6fa7caebfd4e npx wrangler pages deploy /private/tmp/pagecasthq-deploy --project-name pagecasthq --branch main
+```
+
+with:
+
+```sh
+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:
+
+```sh
+npx pagecast
+```
+
+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:
+
+```sh
+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.
+
+## 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:
+
+```sh
+mkdir -p ~/.codex/skills
+cp -R .codex/skills/publish-report ~/.codex/skills/
+```
+
+Start a new Codex session, then ask:
+
+```text
+Use $publish-report to publish /absolute/path/report.md with Pagecast.
+```
+
+For a web project:
+
+```text
+Use $publish-report to build this project and publish dist/index.html with Pagecast.
+```
+
+### Claude Code
+
+```sh
+/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:
+
+```sh
+cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md
+```
+
+More detail is in [plugin/README.md](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:
+
+```sh
+npm start
+```
+
+Run the verification suite:
+
+```sh
+npm run check
+npm test
+```
+
+Rebuild the React admin UI into `public/`:
+
+```sh
+npm run build
+```
+
+Work on the React UI with Vite:
+
+```sh
+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
+
+```text
+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:
+
+```sh
+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](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/`.

package/llms.txt

@@ -0,0 +1,50 @@
+# Pagecast
+
+> Local-first CLI and app for previewing HTML/Markdown reports and static web projects, then publishing them to Cloudflare Pages URLs.
+
+## Links
+
+- Website: https://pagecasthq.pages.dev/
+- GitHub: https://github.com/Amal-David/pagecast
+- README: https://github.com/Amal-David/pagecast/blob/main/README.md
+- Codex skill: https://github.com/Amal-David/pagecast/tree/main/.codex/skills/publish-report
+- Portable agent skill: https://github.com/Amal-David/pagecast/blob/main/plugin/skills/publish-report/SKILL.md
+
+## Install
+
+- One-command app: `npx pagecast`
+- From source: `git clone https://github.com/Amal-David/pagecast.git && cd pagecast && npm start`
+
+## Command discovery
+
+Use `pagecast --help` to confirm the current interface.
+
+## Common workflows
+
+- Start the app: `npx pagecast`
+- One-time Cloudflare setup: `npx pagecast pages setup --project pagecast --json`
+- Publish an HTML report snapshot: `npx pagecast publish "/absolute/path/report.html" --json`
+- Publish Markdown as a page: `npx pagecast publish "/absolute/path/report.md" --json`
+- Publish a built app entry as a share link: `npx pagecast publish "/absolute/path/dist/index.html" --json`
+- Deploy a whole static folder to Pages: `npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --branch main --json`
+- Deploy without specifying a branch: `npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --json`
+- Equivalent high-level site deploy: `npx pagecast publish site "/absolute/path/dist" --project pagecasthq --branch main --json`
+- Show Pages status: `npx pagecast pages status --json`
+- List Pages projects: `npx pagecast pages projects list --json`
+
+## Notes for agents
+
+- Never publish without explicit user confirmation; publishing creates a public URL.
+- Prefer `--json` for automation.
+- Use absolute paths.
+- Use `publish <file>` for new shareable `/p/<token>/` links.
+- Use `publish site` or `pages deploy` only when the user intends to deploy a whole static folder to a named Cloudflare Pages project.
+- Direct site deploys replace the target Pages project contents.
+- `--branch` is optional for direct site deploys; Pagecast uses `main` by default.
+- Do not call raw `npx wrangler pages deploy` unless Pagecast is unavailable or the user explicitly asks for Wrangler.
+
+## Error handling
+
+- `401`: run `npx pagecast pages setup`, or run `npx pagecast` and connect Cloudflare.
+- `409`: multiple Cloudflare accounts are available; pass `--account <account-id>` or choose one in the app.
+- Other errors: relay the `error` field and do not claim success.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pagecast",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Preview local HTML reports and static mini apps, then publish them to shareable URLs.",
+  "license": "MIT",
+  "homepage": "https://pagecasthq.pages.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Amal-David/pagecast.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Amal-David/pagecast/issues"
+  },
+  "keywords": [
+    "html",
+    "markdown",
+    "report",
+    "cloudflare",
+    "cloudflare-pages",
+    "publish",
+    "share",
+    "static-site",
+    "codex",
+    "claude-code",
+    "ai-agents",
+    "agent-skill"
+  ],
+  "bin": {
+    "pagecast": "src/cli.js"
+  },
+  "exports": "./src/server.js",
+  "files": [
+    "src/",
+    "public/",
+    "plugin/",
+    ".codex/skills/publish-report/",
+    "llms.txt"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "build": "pnpm -C web install --frozen-lockfile --ignore-scripts && pnpm -C web run build",
+    "check": "node --check src/server.js && node --check src/cli.js && node --check src/markdown.js",
+    "test": "node --test",
+    "prepack": "npm run build && npm run check && npm test",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "pagecast",
+  "displayName": "Pagecast",
+  "version": "0.2.0",
+  "description": "When your agent finishes an HTML or Markdown report, plan, or doc, it offers to publish it to a shareable public URL with Pagecast.",
+  "author": {
+    "name": "Pagecast"
+  },
+  "license": "MIT"
+}