create-astroid 0.4.0 → 0.5.0

package/index.mjs

@@ -94,16 +94,32 @@ const slugify = (s) =>
  * config. CI could not see it — the clean-room smoke test pins both packages to
  * tarballs via pnpm `overrides`, which is exactly what erases these ranges.
  *
- * `pnpm pack` rewrites `workspace:*` to the concrete version, so in a PUBLISHED
- * create-astroid the declared dep is already exact and we just widen it to a
- * caret. Run from the workspace it is still `workspace:*`, so fall back to the
- * version of the copy actually resolved on disk — which is what the scaffold
- * would install anyway.
+ * Three shapes reach the `declared` value, and all three have to end up as one
+ * caret range:
+ *
+ *   - `workspace:*` — a sibling in this repo (`astroidjs`). Falls back to the
+ *     version of the copy actually resolved on disk, which is what the scaffold
+ *     would install anyway. `pnpm pack` rewrites these to a concrete version, so
+ *     a PUBLISHED create-astroid never carries one.
+ *   - an exact version — what `pnpm pack` leaves behind for a former
+ *     `workspace:*`.
+ *   - an already-caretted range — what an external dependency is written as now
+ *     that `louise-toolkit` and `@louise-toolkit/astro` live in another repo.
+ *
+ * That last one is why `stripRange` exists. Prefixing `^` onto `^0.27.0` yields
+ * `^^0.27.0`, which npm rejects as invalid, and every scaffolded project would
+ * fail at `pnpm install` before anything type-checked. It cost nothing to guard
+ * and would have been invisible until the first scaffold after the repo split.
  *
  * Caret on a 0.x is minor-locked (`^0.2.0` := `>=0.2.0 <0.3.0`), which is the
  * behaviour we want while the toolkit is pre-1.0 and marks breaking changes as
  * minors: patches flow, a breaking minor does not.
  */
+/** `^1.2.3` / `~1.2.3` / `>=1.2.3` → `1.2.3`. See {@link toolkitRanges}. */
+function stripRange(version) {
+  return String(version).replace(/^[\^~]|^>=\s*/, "");
+}
+
 function toolkitRanges() {
   const req = createRequire(import.meta.url);
   const self = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
@@ -121,7 +137,7 @@ function toolkitRanges() {
           "This is a packaging fault — please file an issue rather than editing the scaffold by hand.",
       );
     }
-    ranges[name] = `^${version}`;
+    ranges[name] = `^${stripRange(version)}`;
   }
   return ranges;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astroid",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffold a new Astroid site — an editable, multi-editor Astro app on Cloudflare Workers — in one command.",
   "keywords": [
     "astro",
@@ -15,7 +15,7 @@
   "author": "BowenLabs",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bowenlabs/louise-toolkit.git",
+    "url": "git+https://github.com/bowenlabs/astroidjs.git",
     "directory": "packages/create-astroid"
   },
   "bin": {
@@ -31,12 +31,12 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.2",
+    "@louise-toolkit/astro": "^0.1.1",
     "better-auth": "^1.7.2",
-    "louise-toolkit": "0.27.0",
-    "@louise-toolkit/astro": "0.1.0",
-    "astroidjs": "0.9.5"
+    "louise-toolkit": "^0.28.0",
+    "astroidjs": "0.10.0"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=26.0.0"
   }
 }

package/template/README.md

@@ -128,3 +128,20 @@ single charge.
 | `src/pages/` · `src/components/` · `src/layouts/` | Your Astro app. |
 | `migrations/` | `0000_content.sql` (content + FTS) · `0001_auth.sql` (Better Auth). |
 | `scripts/seed-editors.mjs` | Bootstrap the first editor. |
+| `docs/` | ARCHITECTURE · RUNBOOK · DECISIONS — stubs to fill in as you go. |
+
+## The docs/ trio
+
+Three near-empty documents, scaffolded on purpose. Three production Astroid sites
+each wrote the same three without coordinating, and converged on the same
+headings — so you inherit the questions rather than a blank directory.
+
+| | What goes in it |
+| --- | --- |
+| `docs/ARCHITECTURE.md` | How this site is put together — request flow, content model, bindings. |
+| `docs/RUNBOOK.md` | Operating it — local dev, migrations, secrets, deploy, and **common breakages**. |
+| `docs/DECISIONS.md` | Choices the framework leaves open, and why you made yours. |
+
+`DECISIONS.md` ships with a list of the questions every Astroid site has to
+answer — editors, rich-text storage, sections, commerce, migrations, CSP, edge
+caching. Delete each one as it becomes a real entry.

package/template/docs/ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+How __BRAND_NAME__ is put together: what happens to a request, where content
+lives, and which pieces are the framework's rather than yours.
+
+> Scaffolded by `create-astroid`. Describe what is TRUE of this site, not what
+> Astroid does in general — that is documented at
+> <https://docs.astroidjs.org>. The useful content here is the part that would
+> surprise someone who knows the framework.
+
+## Request flow
+
+One Worker serves everything: pages, the editor API, and static assets.
+
+```
+request → middleware (session, edit mode, rate limits)
+        → Astro route
+        → Louise primitives (content, media, forms) over D1 / R2 / KV
+```
+
+<!-- Anything site-specific in the path: extra middleware, a host check, a
+     redirect layer, routes that bypass the editor entirely. -->
+
+## Content model
+
+<!-- The collections this site defines and what each one is for. Note which
+     fields are rich text, which are structured, and anything a section depends
+     on being present. The schema is generated from astroid.config.ts — link to
+     it rather than restating it, and record the REASONING here. -->
+
+## Editing
+
+<!-- Which parts of a page are editable and how they are marked. Sections vs
+     inline fields vs settings. If a section is deliberately not editable, that
+     is worth a line — the next person will assume it was an oversight. -->
+
+## Auth
+
+<!-- Editors, and customers if this site has them. Astroid ships DB-managed
+     editors on one Better Auth instance. If you split it, added a portal, or
+     changed the allowlist model, describe it here and record WHY in
+     DECISIONS.md. -->
+
+## Bindings
+
+<!-- The bindings in wrangler.jsonc and what each is actually used for. A
+     binding whose purpose is not written down is a binding nobody dares remove.
+
+     D1, R2, KV (RL / DRAFTS), and whatever the enabled modules added. -->
+
+## Rendering
+
+<!-- Layouts, the section library, and where site-owned components live. Which
+     styling approach, and any deliberate constraint (no client JS on these
+     routes, CSP rules that shape what a section may do). -->

package/template/docs/DECISIONS.md

@@ -0,0 +1,46 @@
+# Decisions
+
+Choices __BRAND_NAME__ made that the framework deliberately leaves open, and why.
+
+> Scaffolded by `create-astroid`. This is the document that ages best, because a
+> decision's *reasoning* is the part nobody can reconstruct later. Record the
+> choice when you make it, while the alternatives are still fresh.
+>
+> Not an ADR log — no status field, no numbering ceremony. One heading per
+> decision, newest at the top, and a line about what you did instead.
+
+## Template
+
+```md
+## <the decision, as a statement>
+
+<What was chosen, in one or two sentences.>
+
+**Why.** The reason that actually drove it — the constraint, the incident, the
+thing that would have gone wrong otherwise.
+
+**Instead of.** The alternative that was genuinely considered, and what it would
+have cost. If there wasn't one, say so; "no real alternative" is a finding.
+```
+
+## Questions this site will have to answer
+
+Delete each one as it becomes a real entry above. Every Astroid site meets these,
+and the framework takes no position on any of them:
+
+- **Editors** — DB-managed rows, or an environment allowlist? One auth instance
+  or two, if customers sign in as well?
+- **Rich text storage** — HTML or document JSON? This is very hard to change
+  later; the sites that picked HTML did it for portability and said so.
+- **Sections** — the shipped library as-is, fixed slots, or bespoke sections
+  injected into the catalog?
+- **Commerce** — none, or which provider? If there is a catalog: live reads, or a
+  D1 mirror? Where money is calculated, and what makes that server-authoritative.
+- **Migrations** — hand-authored SQL is the default. If you adopt a generator,
+  write down what happens to the existing hand-authored files.
+- **Content security policy** — generated, or hand-maintained in
+  `astro.config.mjs`? A section that needs an inline style forces this question.
+- **Edge caching** — off by default. Turning it on has a revalidation story that
+  belongs here, not in a commit message.
+- **Service worker / PWA** — a manifest is cheap; a service worker is a cache
+  invalidation problem you now own.

package/template/docs/RUNBOOK.md

@@ -0,0 +1,96 @@
+# Runbook
+
+Operating __BRAND_NAME__: local dev, migrations, secrets, deploy, and what to do
+when something breaks.
+
+> Scaffolded by `create-astroid`. The headings are the ones three production
+> Astroid sites arrived at independently — fill them in as you go. A heading with
+> nothing under it is a question you have not had to answer yet, which is useful
+> information on its own.
+
+## Local development
+
+```sh
+pnpm install
+pnpm dev        # astroid dev — regenerates, then astro dev on workerd
+```
+
+The site renders from seed content with no configuration. To exercise the editor
+locally, apply migrations and seed yourself as an editor:
+
+```sh
+pnpm exec wrangler d1 migrations apply DB --local
+OWNER_EMAIL=you@example.com pnpm seed:editors
+```
+
+Then open `/louise` and request the magic link — in local dev it is **printed to
+the dev console**, since there is no email binding. Follow it to `/?louise` for
+edit mode.
+
+## Provisioning (first deploy)
+
+Create the resources, then paste the ids into `wrangler.jsonc`:
+
+```sh
+wrangler d1 create __KEY__
+wrangler r2 bucket create __KEY__-media
+wrangler kv namespace create RL
+wrangler kv namespace create DRAFTS
+```
+
+<!-- Record anything that was NOT obvious: custom domains, DNS, account ids when
+     more than one Cloudflare account is in play. -->
+
+## Deploy
+
+```sh
+pnpm doctor     # validate config, bindings, and the generated files
+wrangler deploy
+```
+
+<!-- Who deploys, from where, and what gates it? If deploys are automatic on push
+     to main, say so here — that is the first thing a new person asks. -->
+
+## D1 migrations
+
+```sh
+wrangler d1 migrations apply DB --remote
+```
+
+<!-- Migrations are hand-authored SQL under migrations/. Note the ordering rules
+     you adopt, and anything that must be applied before a deploy rather than
+     after. -->
+
+## Seeding content
+
+```sh
+wrangler d1 execute DB --remote --file seed/home.seed.sql
+```
+
+<!-- What is seeded, what is authored in the editor, and which is authoritative
+     when they disagree. -->
+
+## Secrets
+
+```sh
+wrangler secret put SESSION_SECRET
+```
+
+<!-- Where each secret lives (wrangler secret, Secrets Store, a var in
+     wrangler.jsonc) and who can rotate it. Never the values themselves. -->
+
+## Editing the live site
+
+<!-- Who the editors are and how they are added. Astroid ships DB-managed editors
+     by default — `pnpm seed:editors` writes the first one — rather than an env
+     allowlist. If you changed that, this is where it is written down. -->
+
+## Common breakages
+
+<!-- The section that pays for the whole document. Add an entry every time
+     something surprises you, with the symptom FIRST — that is what someone
+     searches for at the time.
+
+     Format that works:
+       **Symptom.** What you actually saw.
+       Cause, and the fix. -->