@charlescms/astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Charles CMS
+
+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,366 @@
+# @charlescms/astro
+
+Static-first visual editing for Astro sites. Free and open source (MIT).
+
+> ⚠️ **Early days (0.x).** CharlesCMS is young and under active development — some
+> things may be rough or not work on every site yet. Source edits are byte-verified
+> and conservative by design, but please **test on a branch first** and
+> [report anything that breaks](https://github.com/Charles-CMS/astro/issues).
+> APIs may change before 1.0.
+
+## Quickstart (≈2 minutes)
+
+Requires Node.js 22.12 or newer and Astro 6.2.
+
+Local preview needs no service account. To publish edits, you only need a GitHub
+repository and a Cloudflare account; the connector is designed to fit within the
+Cloudflare Workers free tier for typical small-site use.
+
+```bash
+npm install @charlescms/astro
+```
+
+Astro 6 currently permits an `esbuild` release affected by June 2026 security
+advisories. Until Astro/Vite require the patched release themselves, pin it in
+the consuming site's root `package.json`, reinstall, and verify with
+`npm audit --omit=dev`:
+
+```json
+{
+  "overrides": {
+    "esbuild": "^0.28.1"
+  }
+}
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import charlesCMS from "@charlescms/astro";
+
+export default defineConfig({ integrations: [charlesCMS()] });
+```
+
+```bash
+npm run dev
+```
+
+Open **`/cms`**, then click any text or image on the page to edit it. That's the
+whole setup — no schema, no content models, no config.
+
+Edits are a local preview until you connect the connector (below) — then
+**Publish** commits them straight to your Git repo.
+
+## Publish your edits
+
+To go live, deploy the connector — a small Cloudflare Worker that commits edits to
+GitHub. One command walks you through it (GitHub repo, where you'll edit, Worker
+name, branch, and an editor password):
+
+```bash
+npx charlescms setup --deploy
+```
+
+Then **connect the site to it once on `/cms`** — paste the connector URL and the
+browser remembers it. No config editing needed.
+
+> **Optional:** to skip even that form, bake the connection into `astro.config` so
+> editors land straight on **Start editing**:
+>
+> ```js
+> charlesCMS({
+>   connector: "https://<your-worker>.workers.dev",
+>   repo: "owner/name",
+>   branch: "main",
+> })
+> ```
+
+Verify anytime:
+
+```bash
+npx charlescms doctor https://<your-worker>.workers.dev
+```
+
+No Wrangler install needed — `npx` fetches it. Prefer clicking or no CLI? See
+[Manual setup](#manual-setup).
+
+### CLI reference
+
+```bash
+npx charlescms setup [--deploy] [--open]   # scaffold the connector (and deploy)
+npx charlescms doctor [connector-url]      # check files + a live connector verify
+npx charlescms --help                      # all commands and options
+npx charlescms --version
+```
+
+`setup` detects your repository's default branch automatically, so edits target
+the right branch (`main`, `master`, …) without you having to pick. `--open` opens
+the GitHub App page for you; `--deploy` also stores the Worker secrets and runs
+`wrangler deploy`.
+
+## Deploy your site
+
+**Publish** commits to GitHub, so any host that rebuilds on push works — Cloudflare
+Pages, Netlify, Vercel, GitHub Pages, or your own CI.
+
+**Cloudflare keeps it simplest.** The connector already runs on Cloudflare Workers,
+so hosting the site on **Cloudflare Pages** keeps everything on one account and the
+same `wrangler` CLI. Connect the repo in the Cloudflare dashboard — build command
+`npm run build`, output directory `dist` — or push straight from the CLI:
+
+```bash
+npm run build
+npx wrangler pages deploy dist
+```
+
+Each **Publish** commits to GitHub; Pages rebuilds automatically. Edit → Publish →
+live.
+
+> The site is a standard static Astro build (`npm run build` → `dist/`), so any
+> static host works — only the connector requires Cloudflare Workers. When you host
+> elsewhere, add that site's URL to the connector's `ALLOWED_ORIGINS`.
+
+## Editor password
+
+Protect a public editor with one password — the Worker secret `AUTH_SECRET`.
+Editors enter it once on `/cms`.
+
+- **Set / change:** in the assistant, `npx wrangler secret put AUTH_SECRET`, or the
+  Cloudflare dashboard (Settings → Variables and Secrets). Takes effect immediately.
+- **Rotate:** replace it with `npx wrangler secret put AUTH_SECRET`.
+
+The connector **fails closed**: with no `AUTH_SECRET` set it refuses every edit
+(503), so a misconfigured deploy can never publish openly — always set one. The
+secret is sent as a header over HTTPS and compared in constant time; GitHub
+credentials stay in the Worker (never in the site or `localStorage`).
+
+It's a single shared editor identity (no per-user audit; revoke by rotating). For
+teams / per-user auth on higher-value sites, put the Worker behind **Cloudflare
+Access**, or add **GitHub OAuth** in the `authorizeRequest()` hook
+(`connector/worker.js`), plus a Cloudflare rate-limit rule on `/api/*`.
+
+## Add sections (optional)
+
+By default the editor changes existing content in place. **Optionally**, let editors
+insert whole new sections between developer-approved children. Mark the wrapper:
+
+```astro
+<main
+  data-charlescms-sections
+  data-charlescms-section-class="prose section-shell"
+  data-charlescms-section-tools="header,paragraph,list,image,quote,delimiter"
+>
+  <Hero />
+  <Features />
+  <Testimonials />
+</main>
+```
+
+That one attribute is the whole decision: sections can be inserted **exactly where
+the developer placed the wrapper**, and nowhere else — pages without it never show
+an insert control. The wrapper's direct children must be static markup (dynamic
+`.map()` children are skipped).
+
+- `data-charlescms-section-class` — class(es) every inserted section receives, so
+  new sections inherit the site's own spacing and look.
+- `data-charlescms-section-tools` — which blocks editors may use
+  (`header,paragraph,list,image,quote,delimiter`).
+
+Offer branded templates as static snippets in `src/charlescms/templates/`
+(recommended — you own the markup and classes). Every `.html` or `.astro` file
+there becomes a choice in the picker; the filename is the label
+(`team-quote.html` → “Team Quote”):
+
+```html
+<!-- src/charlescms/templates/newsletter.html -->
+<h2 class="display-lg">Stay in the loop</h2>
+<p>Occasional notes from the studio.</p>
+<a class="button" href="/newsletter">Subscribe</a>
+```
+
+Templates must be pure static markup: files containing scripts, frontmatter,
+`{expressions}` or components are skipped with a dev-server warning (a section is
+inserted verbatim as page content, so nothing dynamic can ride along).
+
+**What the editor experiences:**
+
+1. **Add section here** appears before, between, and after the wrapper's sections.
+2. Clicking it offers your templates; choosing one stages the section as a live
+   draft on the page. Clicking the draft offers **Remove section** — nothing
+   touches the repository until **Publish**.
+3. Publish commits the section as sanitized, static Astro source (wrapped in a
+   durable `data-charlescms-block`). From then on it is ordinary page content:
+   its text and images are edited right on the page, like everything else, and
+   the whole section can be removed again at any time.
+
+There is deliberately no free-form block builder: editors compose pages from
+sections you designed, and edit content in one consistent way — on the page.
+
+## What it can edit
+
+Everything visible is edited by clicking it on the page. **Page info** in the
+toolbar holds the fields that render nowhere visible — the Google/browser-tab
+title, the meta description, and other frontmatter.
+
+- **Static text & headings**, and safe inline **rich text** (bold, italic, inline
+  code, links, line breaks)
+- **Markdown** frontmatter and body — incl. Astro **Content Collections** (`.md`,
+  `.mdx`, and **JSON** `type: 'data'` collections)
+- **Data rendered with `.map()`** — arrays of objects *and* positional tuples
+  (`[["Name","Desc","8"], …]`): names, descriptions, prices, list items
+- **Config values** (`site.phone`, address, hours, …) and **component props**
+  (hero titles, section eyebrows) — clickable on the page, edited safely at source
+- **Navigation menus** — labels edit; destinations stay locked
+- **Links & downloads** — link text edits; PDFs/files replace in place
+- **Images, video, audio, embeds, iframes** — upload, swap, bounded remove
+- **New sections** (see above) and **versions / undo** via Git commits
+
+Rich vs plain is decided by how your site renders a value: where it interprets
+formatting (a Markdown body, `set:html`), you get full rich text; where it prints
+raw text (`{value}`), it stays plain so formatting can never show as literal
+characters. Pure logic — loops, conditions, computed expressions — is never
+editable (that's code, not content); clicking such generated content shows a
+calm "generated by the page, can't be edited here" hint instead of doing nothing.
+Every write is verified against the exact source bytes and refused if the source
+changed, so an edit can't silently corrupt surrounding code. Edited values are
+escaped as content — including the `{`/`}` Astro reads as expressions — so typed
+text stays text and can't be reinterpreted as code; a downstream `astro build`
+remains the final check on any committed file.
+
+CharlesCMS scans your source to know what's editable — automatically on save in
+dev, at build time in production (rebuild to pick up new content). It works on any
+Astro site, with or without a layout, alongside React/Svelte/Vue islands (those
+files are never touched).
+
+## Options
+
+```js
+charlesCMS({
+  // Connection (optional — bake in for one-click "Start editing"):
+  connector: "https://<your-worker>.workers.dev",
+  repo: "owner/name",
+  branch: "main",
+  sourceRoot: "website",             // monorepos only
+
+  editablePaths: ["/demo", "/blog"], // limit where the editor activates
+  previewOnly: false,                // true = local preview only, no publishing
+  adminPath: "/cms",                 // change the editor route
+})
+```
+
+Monorepos: `sourceRoot` is the app folder holding the Astro project, so
+`src/pages/index.astro` commits as `website/src/pages/index.astro`.
+
+## Manual setup
+
+Skip the assistant and set up the Worker by hand:
+
+1. Install + configure as in [Quickstart](#quickstart).
+
+2. Create the Worker:
+
+   ```bash
+   mkdir -p connector
+   cp node_modules/@charlescms/astro/connector/worker.js connector/worker.js
+   ```
+
+   ```toml
+   # connector/wrangler.toml
+   name = "<your-worker>"
+   main = "./worker.js"
+   compatibility_date = "2026-06-04"
+
+   [vars]
+   ALLOWED_ORIGINS = "https://www.yoursite.com"   # comma-separated; add http://localhost:4321 for dev
+   ALLOWED_REPOS = "owner/name"
+   DEFAULT_BRANCH = "main"
+   ```
+
+   ```bash
+   cd connector && npx wrangler login
+   ```
+
+3. Store secrets (GitHub App with `contents: write` + `metadata: read`, installed on
+   the repo) and the editor password:
+
+   ```bash
+   npx wrangler secret put GITHUB_APP_ID
+   npx wrangler secret put GITHUB_PRIVATE_KEY
+   npx wrangler secret put AUTH_SECRET   # required — the connector refuses to act without it
+   ```
+
+4. Deploy and verify:
+
+   ```bash
+   npx wrangler deploy
+   npx charlescms doctor https://<your-worker>.workers.dev
+   ```
+
+## Troubleshooting
+
+`npx charlescms doctor <url>` maps each failure to a fix:
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `401` on publish or in `doctor` | Missing/wrong editor password | Use the value matching the Worker's `AUTH_SECRET` (or set it with `wrangler secret put AUTH_SECRET`) |
+| `403` "not allowed" | Origin/repo not allow-listed | Fix `ALLOWED_ORIGINS` / `ALLOWED_REPOS` in `wrangler.toml`, redeploy |
+| `403` from GitHub | App lacks access, or stale Worker | Install/grant the GitHub App, then `wrangler deploy` |
+| `404` | GitHub App not installed on the repo | Install it (doctor prints the exact `github.com/apps/<app>/installations/new` link), or check the repo path |
+
+## How it works & safety
+
+The editor ships as static HTML/JS, reads a build-time source map, and stages edits
+as a live preview. Publish sends the exact source span to the Worker, which commits
+to GitHub — credentials stay in the Worker, never in the site or `localStorage`.
+Before each commit the file is re-read and the edit refused if the source changed;
+rich text and section HTML are re-sanitized before the authenticated connector
+writes the complete updated file.
+
+## Checks
+
+```bash
+npm test
+npm run test:coverage
+npm run test:e2e
+npm run build
+```
+
+GitHub Actions runs the coverage and browser suites on Linux plus the packed
+package smoke test on `ubuntu-latest`, `macos-latest`, and `windows-latest`.
+Each job installs the tarball in a clean Astro project, runs the CLI setup,
+builds, starts the dev server, and checks both `/` and `/cms`.
+
+## Runtime structure
+
+The browser editor is split by responsibility:
+
+- `src/client.js` is the composition root: shared state, module wiring, session
+  helpers, and the direct Tiptap imports required for reliable Vite
+  `file:` installs.
+- `src/runtime-controller.js`, `src/source-map-runtime.js`, and
+  `src/edit-affordance.js` own startup, source-map binding, and click/hover
+  behavior.
+- `src/element-editor.js`, `src/rich-text-editor.js`, and
+  `src/section-editor.js` own the three editing experiences.
+- `src/publishing.js` owns staging, publishing, uploads, replacements, and
+  bounded media removal.
+- `src/content-panel.js` owns the Page info (frontmatter/SEO) and data forms;
+  `src/content-bridge.js` maps rendered data to those deterministic forms.
+- `src/panel-manager.js`, `src/toolbar.js`, `src/versions-panel.js`, and
+  `src/editor-styles.js` own the surrounding editor UI.
+- `src/analyzer.js` handles Astro markup while `src/data-analyzer.js` handles
+  conservative JavaScript/TypeScript/JSON data collections. Both read source
+  through `src/js-ast.js`, a small layer over the Babel parser that locates
+  string literals at exact offsets (any nesting depth) without evaluating code.
+
+All source writes remain byte-verified in the shared source-editing layer; the
+DOM bridge only chooses which deterministic editor to open.
+
+## License
+
+CharlesCMS is free and open source under the [MIT License](./LICENSE) — use it
+for anything, including commercial work, no fees and no keys.
+Third-party dependency licences are summarized in
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+Everything self-hosts on your own Cloudflare and GitHub.

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security
+
+How CharlesCMS is built to be safe to install on a real site, what it deliberately
+does and does **not** protect, and how to report a problem.
+
+## Reporting a vulnerability
+
+Please do **not** open a public issue for security problems. Report them privately
+through [GitHub's private vulnerability reporting form](https://github.com/Charles-CMS/astro/security/advisories/new).
+Enable private vulnerability reporting in the repository settings before the
+first public release.
+
+## Trust model in one paragraph
+
+The published site is **100 % static** — none of the editor runs for visitors. The
+editor boots only on the admin route (`/cms` by default) and only does anything once
+an editor authenticates. All writes go through the **connector** (a Cloudflare
+Worker you host), which is the only server-side component and the only thing holding
+credentials.
+
+## Connector — the only component with secrets
+
+- **GitHub App installation tokens**, not a personal access token: short-lived
+  (~1 h), scoped to the installed repo, cached in memory. The token is never sent to
+  the browser and never committed.
+- **Editor auth**: a shared secret `AUTH_SECRET`, sent as the `x-charlescms-auth`
+  header and compared in **constant time** (both sides hashed to SHA-256, then a
+  branchless XOR) so neither length nor mismatch position leaks. **Fail-closed**:
+  with no `AUTH_SECRET` set, every action is refused (503) — a misconfigured deploy
+  can never publish openly.
+- **Origin allow-list** and **repo allow-list** — requests from other origins or for
+  other repositories are rejected (403). The origin check is browser-facing CSRF
+  defense, not the access boundary: browsers always attach an `Origin` a malicious
+  site can't forge, but a non-browser client can omit it. Access is gated by
+  `AUTH_SECRET` (above) and the repo allow-list, which apply to every request.
+- **Path traversal** is blocked everywhere (no `..`, no absolute paths).
+- Source writes require an existing Git blob SHA and are limited to supported
+  files below a `src` directory. New binary files may only be created below
+  `public/uploads`; existing public assets require their current SHA.
+- Recommended hardening before selling: a **Cloudflare rate-limit rule on `/api/*`**
+  to blunt password guessing; for multiple editors, put the Worker behind
+  **Cloudflare Access** and verify the access JWT instead of a single shared secret.
+
+## Source-edit safety and trust boundary
+
+- Every edit is applied **byte-exact** against a build-time source map. Before
+  writing, the browser re-reads the file through the connector and **refuses** if
+  the recorded bytes no longer match (the source drifted).
+- Rich text and Markdown are re-parsed and sanitized in the editor before the
+  complete updated source is sent to the connector.
+- The connector restricts repository paths and requires GitHub's current blob SHA,
+  so stale writes and writes to workflows or other repository metadata are rejected.
+
+The authenticated editor is still a trusted publisher. Anyone who obtains
+`AUTH_SECRET`, or gains script execution in an authenticated editor tab, can submit
+changes to allowed source files. Those files can contain executable Astro or
+JavaScript code. Protect the secret, prevent untrusted scripts on the editor origin,
+keep the GitHub App scoped to dedicated repositories, and use branch protection or
+a review branch for higher-value sites. A downstream `astro build` detects syntax
+errors; it is not a malware sandbox.
+
+## Supply-chain integrity (open, not obfuscated)
+
+The package is **open source and shipped readable** — deliberately not
+obfuscated. That lets anyone (or any scanner) audit exactly what runs, which matters
+because the connector has write access to your repo. To prove the published npm
+package is built from this public source and nothing was slipped in, releases are
+published from CI with **[npm provenance](https://docs.npmjs.com/generating-provenance-statements)**
+(`publishConfig.provenance`): a Sigstore-signed attestation linking the tarball to
+the exact commit and build. Look for the **Provenance** badge on the npm page.
+
+## Development-only endpoints
+
+In `astro dev` the integration exposes `/_charlescms/mirror-*` endpoints that write
+uploaded media and just-published source back to the **local working tree only**, so
+the dev preview stays in sync. They are restricted to the project directory (no
+traversal, source-file types only) and **do not exist in a production build**.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,56 @@
+# Third-party software
+
+CharlesCMS depends on third-party software. The npm package does not bundle its
+dependencies; npm installs them as separate packages with their own licence files.
+An Astro production build may bundle browser-side portions of these packages.
+
+## Direct runtime dependencies
+
+The following direct dependencies are licensed under the MIT License:
+
+- `@astrojs/compiler`
+- `@babel/parser`
+- `@tiptap/core`
+- `@tiptap/extension-bold`
+- `@tiptap/extension-code`
+- `@tiptap/extension-document`
+- `@tiptap/extension-hard-break`
+- `@tiptap/extension-italic`
+- `@tiptap/extension-link`
+- `@tiptap/extension-text`
+- `@tiptap/pm`
+- `js-yaml`
+- `mdast-util-from-markdown`
+- `mdast-util-gfm`
+- `mdast-util-to-markdown`
+- `mdast-util-to-string`
+- `micromark-extension-gfm`
+- `parse5`
+- `vite`
+
+Astro, the required peer dependency, is also MIT-licensed. Playwright, used only
+for development tests, is Apache-2.0 licensed.
+
+## Transitive audit
+
+The release audit found these licence families among installed production and
+peer dependencies:
+
+- MIT, ISC, BSD-2-Clause, BSD-3-Clause
+- Apache-2.0, BlueOak-1.0.0
+- CC0-1.0
+- Python-2.0 (`argparse`)
+- LGPL-3.0-or-later (the optional platform-specific `libvips` shared library
+  distributed for Sharp)
+
+These licences permit commercial use, subject to their notice, attribution,
+patent, source/relinking, and modification obligations. In particular, do not
+statically incorporate or distribute a modified `libvips` build without reviewing
+the LGPL requirements. Sharp's published platform packages use precompiled shared
+libraries and carry their licence information in the installed package.
+
+Full licence texts and copyright notices remain in each installed npm package.
+JavaScript legal comments are preserved by esbuild when bundling by default.
+
+Run `npm run check:licenses` and `npm sbom --omit=dev --sbom-format cyclonedx`
+for every release. This inventory is a technical compliance aid, not legal advice.