@rubar/lavish-publish-cf 0.1.0

package/skill/references/manage.md

@@ -0,0 +1,68 @@
+# Manage existing CF pages
+
+Load when `/publish` is invoked with `list`, `manage`, or `pages`, or when the user says "list my published pages", "manage my pages", etc.
+
+This flow operates only on **Cloudflare-published** pages — local `.lavish/` files aren't tracked anywhere and aren't part of this list.
+
+## Step 1 — gather
+
+```bash
+publish-cf list-mine
+```
+
+One line per page: slug, URL, title, expires, comments, source. `list-mine` does **not** include password presence — fetch that per-slug via `publish-cf get <slug>` (returns `has_password`). Run the `get` calls in parallel.
+
+**Classify each entry** while parsing:
+
+- **Live** — `get` returns 200. URL is on the configured prod `api_base`.
+- **Dead — localhost** — URL uses `localhost` / `127.0.0.1`. Stale dev entries; the production CLI cannot reach them. Don't `get` against prod — they 404 noisily.
+- **Dead — expired** — `expires_at` is in the past, or `get` returns 404 with no localhost URL. KV TTL has already evicted them server-side; the local `keys.json` entry is orphaned.
+
+If `list-mine` returns "no pages saved on this machine", say so and exit.
+
+## Step 2 — render
+
+Print a compact one-row-per-page summary in chat as plain text (never a markdown table — the CLI doesn't render them). Group into a **Live** section and a **Dead** section so the action buckets in step 3 make sense. Format roughly as:
+
+```
+<slug>  <title-or-"Untitled">  pw:yes/no  comments:on/off  expires:<human>  <url>
+```
+
+If there are more than ~15 live pages, build a `.lavish/` HTML file and open it with `lavish-axi` instead (per global CLAUDE.md, long structured output goes to lavish).
+
+## Step 3 — pick the next action
+
+`AskUserQuestion` is capped at 4 options, so **don't try to enumerate every page as an option** — it won't fit. Instead, ask one bucket-style question and rely on the auto-`Other` slot for free-text slug entry. Header: `"Pick"`. Compose options from the relevant ones below (pick 2–4 that apply to the current state):
+
+- **"Act on a specific page"** — tell the user to type the slug in `Other`, or if they pick this option re-prompt with `AskUserQuestion` to capture the slug. Either way, jump to step 4 with that slug.
+- **"Clean up N dead entries"** — only include if there are dead entries. Removes them from local `keys.json` (no API calls — they're already gone server-side). See "Cleanup dead entries" below.
+- **"Delete all live pages"** — only include if the user has clearly signaled bulk-cleanup intent in this session. Otherwise omit; bulk deletion is destructive and shouldn't be a one-click default.
+- **"Done"** — always include.
+
+If the user typed a slug into `Other`, treat that as "act on this specific page".
+
+## Step 4 — pick an action on the picked page
+
+`AskUserQuestion` with header `"Action"` and these options (drop ones that don't apply — e.g. "Toggle password" branches differently based on `has_password`):
+
+- **Delete** — destructive. Confirm with a second `AskUserQuestion` (`"Delete <slug>? Yes / No"`), then `publish-cf delete <slug>`.
+- **Toggle comments** — flip current state via `publish-cf comments toggle <slug> --on` or `--off`.
+- **Toggle password** — branch on `has_password`:
+  - Off → on: generate (`openssl rand -base64 12 | tr -d '=+/' | cut -c1-12`), run `publish-cf password <slug> --set "<pw>"`, share the new password back in the reply.
+  - On → ask sub-question `"Password: replace / remove"`. Replace → generate new pw, `--set <newpw>`, share it back. Remove → `publish-cf password <slug> --clear`.
+- **Open** — `open <url>`.
+- **Back** — return to step 3.
+
+## Cleanup dead entries
+
+`publish-cf delete <slug>` calls the worker API first and only removes the local key on a 200 response. For localhost and KV-expired entries that path fails, so the orphaned key persists. To clean them up locally without an API call, edit `~/.publish-cloudflare/keys.json` directly.
+
+The snippet below backs up `keys.json` and then removes the dead slugs in one command — the backup is part of the chain so it cannot be skipped. Edit the `SLUG1,SLUG2` list before running, and report the printed backup path back to the user in the final reply so they can roll back if needed.
+
+```bash
+cp ~/.publish-cloudflare/keys.json ~/.publish-cloudflare/keys.json.backup-$(date +%s) && node -e "const fs=require('fs'),p=process.env.HOME+'/.publish-cloudflare/keys.json',k=JSON.parse(fs.readFileSync(p));const dead=['SLUG1','SLUG2'];const ok=k.owner_keys||k;dead.forEach(s=>delete ok[s]);fs.writeFileSync(p,JSON.stringify(k,null,2));console.log('removed',dead.length,'dead entries; backup at',p+'.backup-*')"
+```
+
+## Step 5 — loop
+
+After any action other than Done, return to step 1 (re-fetch — the list may have changed). Exit when the user picks Done.

package/skill/references/themes.md

@@ -0,0 +1,77 @@
+# Theme reference
+
+Per-theme content fit, markup conventions, and the placeholder-replacement checklist. Load this once when building a page.
+
+## Picking the theme shell
+
+Six shells live under `~/.lavish-themes/tier{1,2}/<slug>.html` (installed via [lavish-themes](https://github.com/natekettles/lavish-themes)):
+
+- **Tier 1** (vendored CSS, fully self-contained, no external deps): `latex`, `terminal`, `water`.
+- **Tier 2** (Google Fonts via `<link>` — still self-contained otherwise): `swiss`, `handwritten`, `zine`.
+
+All six render light by default. None should be modified — read the shell, replace content, leave styling intact.
+
+## Per-theme cues
+
+### latex (Tier 1)
+
+- **Fit**: research-feeling briefs, papers, citation-heavy writing, anything that should read like a working paper.
+- **Markup**: `<header>` with `<h1>`, optional `<p class="author">` and `<p class="abstract">`. Body in `<main>` with numbered `<h2>` sections.
+
+### terminal (Tier 1)
+
+- **Fit**: runbooks, postmortems, RFCs, CLI documentation, anything that should read like a developer note. Mono everywhere.
+- **Markup**: wrap content in `<div class="container">`. Keep `<body class="terminal">`.
+
+### water (Tier 1)
+
+- **Fit**: the neutral default. Generic reports, briefs, neutral product writing. Classless — just paste content into `<main>` and it looks correct.
+- **Markup**: classless. Drop content into `<main>`. Do not add wrapper divs unless the content genuinely needs them.
+
+### swiss (Tier 2)
+
+- **Fit**: decisive product/strategy briefs, memos, opinionated writing. Modernist grid, red accent.
+- **Markup**: `<h1>` inside `<header class="masthead">`, plus a `.meta` block. Keep the inline `<style>` block exactly as-is — replace only the content inside `<header>`, `<main>`, `<aside>`, etc.
+
+### handwritten (Tier 2)
+
+- **Fit**: personal notes, letters, journal-feeling pieces. Looser, more human.
+- **Markup**: `<h1>` in the header. Keep the inline `<style>` block exactly as-is.
+
+### zine (Tier 2)
+
+- **Fit**: loud manifestos, launch announcements, marketing-flavored pieces.
+- **Markup**: `<h1>` inside `<header class="cover">` (note the `<br>` line breaks in the sample). Keep the inline `<style>` block exactly as-is.
+
+For Tier 2 themes (swiss / handwritten / zine), **do not redesign**. The inline styling is load-bearing for the look. Replace text content only.
+
+## Placeholder-replacement checklist
+
+Every shell ships with sample copy that must not survive into the published page. Walk through this list every time:
+
+1. **`<title>` tag** — replace with the page's real title. The `publish-cf` CLI auto-extracts this and uses it as the wrapper title for comments-on pages, so a stale `<title>` becomes a visible bug.
+2. **Masthead heading** (per theme):
+   - **latex**: `<h1>` inside the `<header>` block.
+   - **terminal**: `<h1>` near the top of `<div class="container">`.
+   - **water**: `<h1>` near the top of `<main>`.
+   - **swiss**: `<h1>` inside `<header class="masthead">`, **plus** the `.meta` block underneath.
+   - **handwritten**: `<h1>` in the header.
+   - **zine**: `<h1>` inside `<header class="cover">`.
+3. **Body content** — replace every paragraph, list item, blockquote, etc. The shells ship with placeholder essays; none of it should leak.
+
+### Verify before saving
+
+After replacing, run this check on the file:
+
+```bash
+grep -E '— sample|The Quiet Architecture' <path>
+```
+
+It must return nothing. If it returns hits, you missed placeholder copy.
+
+## When in doubt
+
+- Pick `water` as the neutral fallback — it's classless and forgiving.
+- Pick `swiss` when the prose is opinionated and benefits from a strong masthead.
+- Pick `terminal` when the content is technical and reads naturally as monospace.
+- Avoid `zine` and `handwritten` unless the prompt explicitly suggests their tone — they are loud choices that shape how the content reads.

package/worker/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Self-hosted clone of htmlship.com running on Cloudflare Workers + KV. Two halves:
+
+- **Worker** (`src/index.ts`) — single-file TypeScript Worker. All routing, storage, rendering, comments, and auth live here.
+- **CLI** (`cli/index.js`) — zero-dep Node client (`publish-cf`) that talks to the deployed Worker. Stores per-slug `owner_key` and API base under `~/.publish-cloudflare/`.
+
+Both files are intentionally single-file. Don't split them up "for organization" — the design constraint is keeping the Worker deployable as one module and the CLI installable without `npm install`.
+
+## Commands
+
+Run these from the **repo root** (where `package.json` now lives). Wrangler is invoked with `--config worker/wrangler.toml`.
+
+```bash
+npm run dev         # wrangler dev — local Worker on http://localhost:8787 (in-memory KV)
+npm run deploy      # wrangler deploy to Cloudflare
+npm run tail        # wrangler tail — stream live logs from prod
+npm run types       # wrangler types — regenerate worker types
+
+# CLI against local dev server
+PUBLISH_CF_API=http://localhost:8787 node worker/cli/index.js publish foo.html
+PUBLISH_CF_API=http://localhost:8787 node worker/cli/index.js list-mine
+```
+
+`PUBLISH_CF_API` overrides `~/.publish-cloudflare/config.json`. There is no test suite, no linter, and no build step (Wrangler bundles the TS directly).
+
+## Architecture notes
+
+**Routing**: All paths are handled by a single `fetch` export at the bottom of `src/index.ts` using regex matches. Order matters — `/v/:slug/comments` and `/v/:slug/raw` must be matched before `/v/:slug`. When adding routes, add them in the same `fetch` handler, not via any framework.
+
+**Two CSPs, one wrapper-iframe split**:
+
+- `/v/:slug` serves a **wrapper page** (comment sidebar + UI JS) under `WRAPPER_CSP` (allows `'unsafe-inline'` scripts so the comment UI can run).
+- `/v/:slug/raw` serves the **user's artifact** under the strict `PAGE_CSP` (`script-src 'none'`), embedded in a same-origin iframe.
+- The wrapper never executes anything from the artifact. If you touch CSP or the wrapper HTML, preserve this boundary — the strict CSP on `/raw` is the only thing keeping user-supplied HTML from running scripts.
+
+**KV layout** (`PAGES` namespace):
+
+- `page:<slug>` → `PageRecord` (html, hashes, expiry)
+- `comment:<slug>:<id>` → one comment per key, listed via `PAGES.list({ prefix: "comment:<slug>:" })`. One-key-per-comment is deliberate, to avoid lost writes from concurrent commenters.
+
+**Auth model**:
+
+- `owner_key` (CLI side, plaintext `ws_…`) and `password` (viewer side, plaintext) are both stored on the server as SHA-256 hex hashes only. Compare with `timingSafeEqualHex`.
+- Viewer cookie `hp_<slug>=ok` (1h) gates `/v/:slug`, `/v/:slug/raw`, and comment read/write for password-protected pages.
+- `X-Owner-Key` header gates PATCH/DELETE on pages and comments.
+
+**Comment anchoring**: text-quote selector (quote + ~32 chars prefix/suffix). Comments whose anchor no longer matches after a republish are flagged `orphaned` rather than deleted. Anchor matching logic is in the wrapper page's inline JS (inside `wrapperHtml`), not server-side.
+
+## Conventions
+
+- The Worker has no dependencies beyond `@cloudflare/workers-types`. Don't add runtime deps — use Web Crypto, `fetch`, `Response`, KV directly.
+- The CLI has zero runtime deps. Don't add any. It calls the API with plain `fetch` and writes JSON to `~/.publish-cloudflare/` with mode `0600`.
+- Limits (`MAX_HTML_BYTES`, `MAX_EXPIRES_MINUTES`, etc.) are declared as top-level consts in `src/index.ts`. Change them there, not inline.
+- `wrangler.toml` has a real KV namespace id committed (`15dcacac…`). That's intentional — this is a personal worker, not a template.
+
+## When asked to change behavior
+
+- API surface is documented in `README.md` and is meant to mirror htmlship. If you change request/response shape, update the README table.
+- Skill at `~/.claude/skills/publish-cloudflare/SKILL.md` wraps the CLI for Claude Code use. If you rename a CLI command or change its flags, that skill likely needs updating too.

package/worker/README.md

@@ -0,0 +1,222 @@
+# worker — Cloudflare Worker + CLI
+
+The self-hosted side of [`lavish-publish-cf`](../README.md): a Cloudflare Worker (with KV) plus a Node CLI that talks to it. API-compatible with [htmlship.com](https://htmlship.com) — same shape, no third-party dependency, runs on your own Cloudflare account.
+
+- **Worker**: `src/index.ts` — single-file TypeScript Worker, KV-backed.
+- **CLI**: `cli/index.js` — `publish-cf` command, mirrors htmlship's commands.
+
+For the high-level overview (skill integration, install flow), see the [top-level README](../README.md).
+
+---
+
+## Deploy (one-time setup)
+
+You need a Cloudflare account with Workers enabled (free tier is plenty).
+
+Run these from the **repo root** (where `package.json` lives).
+
+```bash
+# 1. Install deps
+npm install
+
+# 2. Authenticate Wrangler with your Cloudflare account
+npx wrangler login
+
+# 3. Create the KV namespace and copy the returned id
+npx wrangler kv namespace create PAGES
+# → outputs something like:
+#   { binding = "PAGES", id = "abc123…" }
+
+# 4. Paste the id into worker/wrangler.toml (replace REPLACE_WITH_KV_NAMESPACE_ID)
+
+# 5. Deploy
+npm run deploy
+# → outputs the live URL, e.g. https://publish-cloudflare.<account>.workers.dev
+```
+
+After deploy, point the CLI at it:
+
+```bash
+publish-cf config set --api-base https://publish-cloudflare.<account>.workers.dev
+```
+
+(Or set `PUBLISH_CF_API` in your shell profile.)
+
+### Optional: custom view domain
+
+If you want pages served from `view.example.com` instead of the worker subdomain:
+
+1. Add a Worker route or custom domain in the Cloudflare dashboard.
+2. In `wrangler.toml`, set:
+   ```toml
+   [vars]
+   VIEW_BASE_URL = "https://view.example.com"
+   ```
+3. Redeploy.
+
+---
+
+## Install the CLI
+
+The fastest path is npm:
+
+```bash
+npm install -g @rubar/lavish-publish-cf
+publish-cf --help
+```
+
+Or from a checkout: `npm install -g .` from the repo root. Or invoke directly without install:
+`node <repo>/worker/cli/index.js …`, or `npx @rubar/lavish-publish-cf …`.
+
+---
+
+## CLI usage
+
+```bash
+publish-cf publish report.html
+publish-cf publish report.html --password "demo-pass"
+publish-cf publish report.html --title "Demo" --expires-in 60
+publish-cf publish report.html --no-comments              # disable the comment sidebar
+cat report.html | publish-cf publish -
+
+publish-cf get <slug>
+publish-cf update <slug> report.html
+publish-cf delete <slug>
+publish-cf list-mine
+
+publish-cf comments <slug>                                # list open comments
+publish-cf comments <slug> --format json --status all     # machine-readable
+publish-cf comments resolve <slug> <id> --note "..."      # owner-only
+publish-cf comments delete <slug> <id> --yes              # owner-only
+publish-cf comments toggle <slug> --on | --off            # flip the page-level switch
+
+publish-cf config show
+publish-cf config set --api-base https://...
+```
+
+State lives in `~/.publish-cloudflare/`:
+
+- `config.json` — `{ "api_base": "https://…" }`
+- `keys.json` — per slug: `owner_key`, `source_path`, `comments_enabled`, `title`, expiry, URL. `source_path` is read by `/address-comments` so it can find the local file without asking.
+
+`PUBLISH_CF_API` env var overrides the config file.
+
+---
+
+## API reference
+
+Base path: `/api/v1`
+
+| Method   | Path                                 | Auth                                  | Purpose                                                                                                                                                                                |
+| -------- | ------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST`   | `/api/v1/pages`                      | none                                  | Create page. Body: `{html, title?, password?, expires_in?, comments_enabled?}` (minutes for `expires_in`). Returns `{slug, url, owner_key, expires_at, size_bytes, comments_enabled}`. |
+| `GET`    | `/api/v1/pages/:slug`                | none                                  | Metadata only (no html).                                                                                                                                                               |
+| `PATCH`  | `/api/v1/pages/:slug`                | `X-Owner-Key`                         | Update `html`, `title`, and/or `comments_enabled`.                                                                                                                                     |
+| `DELETE` | `/api/v1/pages/:slug`                | `X-Owner-Key`                         | Delete page.                                                                                                                                                                           |
+| `GET`    | `/v/:slug`                           | cookie if password-protected          | Render the wrapper page (comment sidebar + iframe of the artifact). If `comments_enabled === false`, serves the artifact directly under strict CSP (same content as `/v/:slug/raw`).   |
+| `POST`   | `/v/:slug`                           | n/a                                   | Submit password (form-urlencoded `password=…`), sets `hp_<slug>` cookie.                                                                                                               |
+| `GET`    | `/v/:slug/comments?status=open\|all` | viewer (cookie if password-protected) | List comments on the page. Returns `403 comments_disabled` if the page has comments off.                                                                                               |
+| `POST`   | `/v/:slug/comments`                  | viewer (cookie if password-protected) | Add a comment. Body: `{body, author, anchor?}`. Returns `403 comments_disabled` if comments are off.                                                                                   |
+| `PATCH`  | `/v/:slug/comments/:id`              | `X-Owner-Key`                         | Resolve / unresolve a comment. Body: `{status, resolution_note?}`.                                                                                                                     |
+| `DELETE` | `/v/:slug/comments/:id`              | `X-Owner-Key`                         | Delete a comment.                                                                                                                                                                      |
+| `GET`    | `/healthz`                           | none                                  | Liveness probe.                                                                                                                                                                        |
+| `GET`    | `/`                                  | none                                  | Landing page.                                                                                                                                                                          |
+
+### Limits
+
+- `html` ≤ 5 MB (KV cap is 25 MB; we leave headroom).
+- `expires_in` ≤ 30 days (43,200 minutes).
+- Slug = 8 lowercase alphanumeric chars. 5 retries on collision.
+- `owner_key` = `ws_` + 32 random alphanumerics. Stored as SHA-256 hash on the server.
+- Passwords stored as SHA-256 hash. Cookie `hp_<slug>=ok` valid for 1 hour.
+
+### Content security
+
+The artifact itself is served at `/v/:slug/raw` with a strict CSP:
+
+```
+Content-Security-Policy: default-src 'self' data: blob: https:; script-src 'none'; style-src 'self' 'unsafe-inline' https:; img-src 'self' data: blob: https:; font-src 'self' data: https:; frame-ancestors 'none'; base-uri 'none';
+X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer
+```
+
+Inline `<script>` tags in the artifact are blocked. External CDN scripts are blocked. Inline CSS, images, fonts, and HTTPS subresources are allowed.
+
+The wrapper at `/v/:slug` ships its own JS for the comment UI, so it carries a slightly looser policy: `script-src 'self' 'unsafe-inline'` plus `frame-src 'self'` so it can host the iframe. The wrapper never executes anything from the artifact — the iframe (`/v/:slug/raw`) keeps the strict CSP above.
+
+---
+
+## Inline comments
+
+`/v/:slug` serves a thin **wrapper page** (comment sidebar + same-origin iframe). The iframe loads the artifact at `/v/:slug/raw` under the existing strict CSP, so the artifact itself stays untouched. Viewers select text inside the iframe, type a comment, and pick a display name — the name is stored in their browser `localStorage` (`pcf_name`); there are no accounts.
+
+Anchors use a **text-quote selector** (selected phrase plus ~32 chars of prefix/suffix), so comments survive a republish as long as the anchored phrase (or a near-match) still appears in the new HTML. Comments whose anchor no longer matches are flagged `orphaned` in the sidebar and in the JSON.
+
+Comment reads and writes are gated by the same viewer cookie as the page itself — password-protected pages get password-protected comments. Resolve and delete require `X-Owner-Key` and are intended to be driven from the CLI.
+
+The headline workflow: a reviewer drops comments, the owner asks Claude to address them, and Claude runs:
+
+```bash
+publish-cf comments <slug> --format json --status open
+# Claude edits the local HTML to address each anchored comment
+publish-cf update <slug> <local-file>
+# For each addressed comment:
+publish-cf comments resolve <slug> <id> --note "<short summary>"
+```
+
+Same URL throughout — the reviewer's tab just shows resolved comments on refresh.
+
+### Storage
+
+KV keys in the `PAGES` namespace:
+
+- `page:<slug>` — the artifact record (html, owner_key hash, password hash, expiry, etc.)
+- `comment:<slug>:<id>` — one comment per key (avoids lost writes from concurrent commenters; listed via `PAGES.list({ prefix: \`comment:${slug}:\` })`)
+
+---
+
+## vs htmlship.com
+
+|                 | htmlship.com            | publish-cloudflare                   |
+| --------------- | ----------------------- | ------------------------------------ |
+| Hosted by       | htmlship                | You (Cloudflare)                     |
+| Cost            | Free tier with limits   | Free tier (CF Workers: 100k req/day) |
+| CLI             | `npx htmlship`          | `publish-cf`                         |
+| Owner key store | `~/.htmlship/keys.json` | `~/.publish-cloudflare/keys.json`    |
+| API surface     | identical shape         | identical shape                      |
+| CSP             | strict, no scripts      | strict, no scripts (same policy)     |
+| Custom domain   | depends on plan         | yes, via Cloudflare                  |
+| Passwords       | yes                     | yes                                  |
+| Expiry          | yes                     | yes (≤ 30 days)                      |
+| Vendor lock-in  | yes                     | none — your worker, your KV          |
+
+---
+
+## Local development
+
+```bash
+npx wrangler dev --local
+```
+
+Uses an in-memory KV emulator on `http://localhost:8787`. No Cloudflare auth required for `--local`. Point the CLI at it:
+
+```bash
+PUBLISH_CF_API=http://localhost:8787 node worker/cli/index.js publish foo.html
+```
+
+---
+
+## Project layout
+
+```
+<repo-root>
+├── package.json        # npm publishable (@rubar/lavish-publish-cf)
+└── worker/
+    ├── README.md
+    ├── tsconfig.json
+    ├── wrangler.toml
+    ├── src/
+    │   └── index.ts    # Worker (single file)
+    └── cli/
+        └── index.js    # CLI client (zero-dep Node)
+```