pagecast 0.1.0

package/plugin/README.md

@@ -0,0 +1,99 @@
+# Pagecast — agent plugin
+
+Lets your coding agent (Claude Code, Codex, or any Agent-Skills-compatible tool)
+offer to publish a freshly created **HTML or Markdown** report, plan, or doc to a
+shareable public URL.
+
+How it works: a passive `PostToolUse` hook notices when an HTML/Markdown file is
+written and hints the agent. The `publish-report` skill tells the agent to offer
+(once, only for finished/shareable artifacts) *"Want me to publish this with
+Pagecast?"* and, on an explicit **yes**, run the headless CLI:
+
+```sh
+npx pagecast publish "/absolute/path/file.md" --json
+# → {"ok":true,"url":"https://pagecast.pages.dev/p/<token>/", ...}
+```
+
+## Setup (one time)
+
+### 1. Install the agent integration
+
+**Codex CLI / Codex desktop** — copy the Codex-native skill:
+
+```sh
+mkdir -p ~/.codex/skills
+# from a clone of the repo:
+cp -R .codex/skills/publish-report ~/.codex/skills/
+```
+
+Start a new Codex session so the skill is discovered. Then you can ask:
+
+```text
+Use $publish-report to publish /absolute/path/report.md with Pagecast.
+```
+
+**Claude Code** — add the marketplace from the public repo, then install:
+
+```sh
+/plugin marketplace add Amal-David/pagecast
+/plugin install pagecast@pagecast
+```
+
+This wires up both the `publish-report` skill and the report-detection hook.
+
+**Other Agent-Skills tools** — copy the portable skill:
+
+```sh
+# from a clone of the repo:
+cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md
+```
+
+The portable `SKILL.md` is the Agent-Skills format. The detection hook is
+Claude-Code-specific; elsewhere the skill still triggers when a report is created
+or when you ask to publish one.
+
+### 2. Connect Cloudflare
+
+```sh
+npx pagecast
+```
+
+Click **Connect Cloudflare** in the panel. Or sign in directly:
+
+```sh
+npx pagecast pages setup --project pagecast
+```
+
+That's the whole setup. **After this, publishing is headless** — when your agent
+makes a report and you say "yes", it publishes with no further prompts.
+
+## What to expect
+
+Once installed and connected: when your agent writes a report, plan, dashboard, or
+other shareable HTML/Markdown, it offers *"Want me to publish this with Pagecast?"*
+Say **yes** and you get back a public `pagecast.pages.dev` link you own. Say no and
+it drops it — it won't nag. You can rename, re-sync, or revoke any link from
+`npx pagecast`.
+
+For static web projects that should get a new share link, build first and publish
+the generated entry file, such as `dist/index.html`.
+
+For whole-site Cloudflare Pages deploys, use Pagecast's Wrangler abstraction:
+
+```sh
+npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --branch main --json
+```
+
+If you omit `--branch`, Pagecast deploys to `main`:
+
+```sh
+npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --json
+```
+
+Direct site deploys replace the target Pages project contents. Use `npx pagecast`
+for source-folder build settings, URL renaming, re-sync, and revoke controls.
+
+## Requirements
+
+- Node.js >= 20 and `npx` (Wrangler is fetched via `npx` on first use).
+- A Cloudflare account.

package/plugin/hooks/detect-report.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Passive PostToolUse hook: when a Write/Edit/MultiEdit creates or updates an
+// HTML or Markdown file (a report, plan, doc, or dashboard), inject a
+// non-blocking hint so the agent can offer to publish it with Pagecast. This
+// hook NEVER blocks and NEVER publishes anything — it only adds context, and the
+// skill decides whether the file is actually worth offering. Any error exits 0
+// silently so it can't disrupt the agent.
+
+// Obvious non-artifacts the agent should not be nudged to publish. The skill
+// applies the real judgment; this just keeps the common noise down.
+const SKIP_BASENAMES = new Set([
+  "readme.md",
+  "readme.markdown",
+  "changelog.md",
+  "contributing.md",
+  "license.md",
+  "code_of_conduct.md",
+  "security.md",
+  "agents.md",
+  "claude.md",
+  "todo.md",
+  "tasks.md",
+  "notes.md"
+]);
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+
+function reportPathFrom(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") {
+    return null;
+  }
+  const candidate = toolInput.file_path || toolInput.path || toolInput.filePath;
+  if (typeof candidate !== "string") {
+    return null;
+  }
+  const lower = candidate.toLowerCase();
+  const isPublishable =
+    lower.endsWith(".html") ||
+    lower.endsWith(".htm") ||
+    lower.endsWith(".md") ||
+    lower.endsWith(".markdown");
+  if (!isPublishable) {
+    return null;
+  }
+
+  const base = candidate.split("/").pop() || "";
+  // Skip obvious non-artifacts: build/dependency dirs, hidden files, and common
+  // repo-meta files that nobody wants to publish.
+  if (
+    candidate.includes("/node_modules/") ||
+    candidate.includes("/dist/") ||
+    candidate.includes("/.git/") ||
+    base.startsWith(".") ||
+    SKIP_BASENAMES.has(base.toLowerCase())
+  ) {
+    return null;
+  }
+  return candidate;
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    if (!raw.trim()) {
+      process.exit(0);
+    }
+    const event = JSON.parse(raw);
+    const filePath = reportPathFrom(event.tool_input);
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    const additionalContext =
+      `An HTML or Markdown file was just written at "${filePath}". ` +
+      `If it is a substantial, finished artifact worth sharing (a report, plan, doc, or dashboard) — ` +
+      `not a scratch/internal file — offer once: ask the user "Want me to publish this with Pagecast?" ` +
+      `and only on an explicit yes run \`npx pagecast publish "${filePath}" --json\` to get a shareable ` +
+      `public URL. Never publish without confirmation, and don't re-ask for this file.`;
+
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext
+        }
+      })
+    );
+    process.exit(0);
+  } catch {
+    // Never disrupt the agent loop.
+    process.exit(0);
+  }
+}
+
+main();

package/plugin/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/detect-report.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,117 @@
+---
+name: publish-report
+description: Use when an HTML or Markdown report, plan, doc, dashboard, or built static web project has just been created (or the user wants to share one) and it is worth publishing as a public link. Offers to publish it with Pagecast, then returns the URL.
+version: 0.2.0
+---
+
+# Publish with Pagecast
+
+Pagecast turns a local **HTML or Markdown** file (a report, plan, doc, or
+dashboard) into a shareable public URL. Use this skill to offer that at the
+right moment, then do it on a yes.
+
+## When to offer
+
+Offer **once** when a substantial, finished, shareable artifact appears:
+
+- An `.html`/`.htm` or `.md`/`.markdown` file was just generated that a person
+  would actually want to share — a test/coverage/Lighthouse/Playwright report, a
+  data dashboard, a written plan or proposal, a "here's what I built" summary, a
+  design doc, release notes, etc.
+- A static web project was just built and has a generated entry file such as
+  `dist/index.html`, `build/index.html`, `out/index.html`, or `public/index.html`.
+- The user asks to "share", "publish", "make a link for", or "send" a report/doc.
+- A `PostToolUse` hint says an HTML/Markdown file was created (the bundled hook).
+
+**Use judgment — do not nag.** Offer only for finished, worth-sharing artifacts.
+Do **not** offer for scratch notes, internal repo files (README, CHANGELOG,
+CONTRIBUTING, LICENSE, AGENTS.md, TODO/tasks), config, source code, or anything
+under `node_modules`/`dist`/`.git`. Ask **at most once per file**; if the user
+declines or ignores it, drop it and don't re-ask.
+
+## The one question to ask
+
+> "Want me to publish this with Pagecast? It'll create a shareable public link."
+
+Only on an explicit **yes** do you proceed. Publishing makes the file publicly
+reachable — **never publish without confirmation.**
+
+## How to publish
+
+Run the headless CLI with the **absolute path** and `--json`:
+
+```sh
+npx pagecast publish "/absolute/path/to/file.md" --json
+```
+
+(HTML and Markdown both work — Markdown is rendered to a clean page. If `pagecast`
+is installed globally/in the project, `pagecast publish "<path>" --json` is the same.)
+
+For static web projects that should get a new shareable `/p/<token>/` link,
+build first and publish the generated entry file:
+
+```sh
+npm run build
+npx pagecast publish "/absolute/path/to/dist/index.html" --json
+```
+
+If the user asks to deploy or update an entire static site/project, deploy the
+built folder directly to a named Cloudflare Pages project:
+
+```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 Pages project contents, so do not guess
+the `--project`; use the user's named project or ask for it.
+
+Parse the JSON on stdout:
+
+- **Success** → `{ "ok": true, "url": "https://<project>.pages.dev/p/<token>/", ... }`
+  - Give the user the `url`. Offer to drop it into a PR/Slack message, and
+    mention they can rename the URL, re-sync, or revoke it from `npx pagecast`.
+- **Not signed in** → `{ "ok": false, "statusCode": 401, ... }`
+  - This is the one-time setup. Tell the user to run
+    **`npx pagecast pages setup`** once, or run **`npx pagecast`** and click
+    **Connect Cloudflare**, then offer to retry. After that, publishing is
+    headless — a plain "yes" is enough every time.
+- **Multiple accounts** → `{ "ok": false, "statusCode": 409, ... }`
+  - Tell the user to run `npx pagecast pages setup --account <account-id>` once,
+    or run `npx pagecast` to pick which Cloudflare account to publish from, then
+    retry.
+- **Any other error** → relay `error` concisely and offer to retry.
+
+## Cloudflare Pages commands
+
+Use these lower-level commands when the user explicitly asks about Cloudflare
+setup, status, project listing, or direct Pages 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`.
+
+## Notes
+
+- Always pass an **absolute** path (resolve relative paths against the cwd first).
+- The first publish auto-creates the user's Pages project — no manual setup beyond
+  the one-time Connect Cloudflare login.
+- Use `npx pagecast publish site` or `npx pagecast pages deploy` for direct
+  static-folder deploys to a named Pages project.
+- Use `npx pagecast` for source-folder build settings, URL renaming, re-sync,
+  and revoke controls.
+- To update a page **in place at the same URL**, the user can re-sync from the
+  Pagecast app; re-running `publish` creates a new link. Old links keep working
+  until revoked.