astroidjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BowenLabs
+
+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,105 @@
+# astroidjs
+
+**Astroid** — an opinionated meta-framework over
+[Louise Toolkit](https://github.com/bowenlabs/louise-toolkit/tree/main/packages/louise)
+and Astro for building editable, multi-editor sites on Cloudflare Workers.
+
+> **Status: pre-1.0, experimental.** The API will change between minor versions —
+> pin an exact version if you depend on it. Astroid lives in the same workspace as
+> Louise so its opinions co-evolve with the toolkit.
+
+## What it is
+
+Louise is the unopinionated toolkit — primitives you assemble by hand. Astroid is
+the opinionated preset on top: a theme system, a section library, and a single
+config that generates the Louise wiring (worker routes, middleware, schema,
+theme) a site would otherwise hand-write per repo.
+
+```
+Astro        →  renderer / router / build
+  Louise     →  unopinionated primitives + framework glue   (louise-toolkit)
+    Astroid  →  opinions: theme, sections, config, scaffold  (astroidjs)
+```
+
+## Design rule
+
+Dependencies flow one way: **`astroidjs` → `louise-toolkit`, never the reverse.**
+Louise must never import Astroid, and nothing opinionated is allowed into Louise's
+exports. This keeps the toolkit neutral while Astroid holds the opinions.
+
+## Configure
+
+The whole shape of a project — its brand + theme + editable home, its commerce
+backend and optional modules — collapses into one typed config. **One brand per
+project:** every site Astroid targets serves a single brand from a single deploy,
+so the config describes one brand, not an array. What actually multiplexes is
+*editors* (Louise's org plugin) and *audiences* (a gated portal beside the public
+site) — both options on the one brand. The vocabulary is drawn from the real
+sites Astroid targets: a storefront (coracle.coffee), a wholesale front
+(ghostfire.coffee), an artist portfolio (themidwestartist.com), and a plain
+marketing baseline (louise-web).
+
+```ts
+import { defineAstroid } from "astroidjs";
+
+export default defineAstroid({
+  key: "coracle",
+  archetype: "storefront",
+  theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
+  sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+  commerce: { provider: "square" },
+  deploy: { platform: "cloudflare" },
+});
+```
+
+A portfolio with a gated client area, for contrast:
+
+```ts
+export default defineAstroid({
+  key: "megbowen",
+  archetype: "portfolio",
+  theme: { name: "Meg Bowen Studio", colors: { brand: "#2b2b2b" } },
+  sections: ["hero", "gallery", "story", "contact"],
+  portal: { enabled: true, gated: true },
+  deploy: { platform: "cloudflare" },
+});
+```
+
+## CLI
+
+The `astroid` command turns the config into the Louise wiring and keeps it in
+sync. It loads your `astroid.config.ts` with Node's native TypeScript stripping,
+so there is no separate config-compile step.
+
+```
+astroid generate   regenerate src/schema.ts, src/worker.ts, src/middleware.ts from the config
+astroid doctor     validate the config, the wrangler bindings, and generated-file freshness
+astroid dev        regenerate, then run `astro dev`
+astroid build      regenerate, then run `astro build`
+astroid deploy     provision bindings + migrate + secrets + deploy (--dry-run / --yes)
+```
+
+`deploy` is plan-first: it prints exactly what it will run and refuses to
+provision non-interactively without `--yes` (use `--dry-run` to preview).
+
+The generated trio carries a "do not hand-edit" banner — `generate` (and
+`dev`/`build`) rewrite them on every run, and `doctor` diffs them against your
+config to catch drift. Your `wrangler.jsonc` is scaffolded once and then yours to
+edit (real binding ids, secrets); `generate` never touches it.
+
+New projects come from the `create-astroid` scaffold (`npm create astroid`), which
+writes the floor — config, the generated trio, `wrangler.jsonc`, and the baseline
+Astro app — in one step.
+
+## Roadmap
+
+1. ✅ **Config surface** (`defineAstroid`) — single brand per project.
+2. ✅ Config → generated Drizzle schema.
+3. ✅ Config → generated `worker.ts` + middleware (no hand-wired route ordering).
+4. ✅ `<Section>` / `<Editable>` / `<Collection>` component primitives.
+5. ✅ **CLI** — `astroid generate / doctor / dev / build / deploy`; `create-astroid`
+   scaffold (`npm create astroid`).
+
+## License
+
+[MIT](https://github.com/bowenlabs/louise-toolkit/blob/main/LICENSE) © BowenLabs

package/bin/astroid.mjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `astroid` CLI — the meta-framework's project commands:
+//
+//   astroid generate [--config <path>] [--cwd <dir>]   regenerate schema/worker/middleware from the config
+//   astroid doctor   [--config <path>] [--cwd <dir>]   validate config + bindings + generated-file freshness
+//   astroid dev      [...astro args]                   generate, then `astro dev`
+//   astroid build    [...astro args]                   generate, then `astro build`
+//   astroid deploy   [--dry-run] [--yes] [--local]     provision + migrate + secrets + deploy
+//
+// It loads the project's `astroid.config.ts` with Node's native TypeScript
+// stripping (the config only imports the built `astroidjs`, so it resolves), and
+// consumes this package's own built generators from ../dist — the same version the
+// CLI ships in, no dependency on node_modules layout (mirrors the louise bin).
+
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+
+const GENERATORS_URL = new URL("../dist/index.js", import.meta.url).href;
+
+// --- tiny arg parser -------------------------------------------------------
+// Splits at the first non-flag token into { command, flags, rest }. `rest` is
+// everything after the command, preserved verbatim so `dev`/`build` can forward
+// arbitrary astro flags.
+function parseArgs(argv) {
+  const [command, ...tail] = argv;
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < tail.length; i++) {
+    const a = tail[i];
+    if (a === "--config" || a === "-c") flags.config = tail[++i];
+    else if (a === "--cwd") flags.cwd = tail[++i];
+    else rest.push(a);
+  }
+  return { command, flags, rest };
+}
+
+// --- config loading --------------------------------------------------------
+const CONFIG_CANDIDATES = ["astroid.config.ts", "astroid.config.mjs", "astroid.config.js"];
+
+function resolveConfigPath(cwd, explicit) {
+  if (explicit) {
+    const abs = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+    if (!existsSync(abs)) fail(`Config not found: ${explicit}`);
+    return abs;
+  }
+  for (const name of CONFIG_CANDIDATES) {
+    const abs = join(cwd, name);
+    if (existsSync(abs)) return abs;
+  }
+  fail(
+    `No Astroid config found in ${cwd}.\n` +
+      `Expected one of: ${CONFIG_CANDIDATES.join(", ")} (or pass --config <path>).`,
+  );
+}
+
+async function loadConfig(cwd, explicit) {
+  const path = resolveConfigPath(cwd, explicit);
+  let mod;
+  try {
+    mod = await import(pathToFileURL(path).href);
+  } catch (err) {
+    // A `defineAstroid` invariant violation (bad key/theme) throws here at import.
+    fail(`Failed to load ${path}:\n${err instanceof Error ? err.message : String(err)}`);
+  }
+  const config = mod.default ?? mod.config;
+  if (!config || typeof config !== "object") {
+    fail(`${path} must \`export default defineAstroid({ … })\`.`);
+  }
+  return { config, path };
+}
+
+// --- commands --------------------------------------------------------------
+async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
+  const { generateAstroidProject } = await import(GENERATORS_URL);
+  const { config } = await loadConfig(cwd, flags.config);
+  const files = generateAstroidProject(config);
+  for (const file of files) {
+    const abs = join(cwd, file.path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, file.contents);
+    if (!quiet) out(`  ✓ ${file.path}`);
+  }
+  if (!quiet) out(`Generated ${files.length} file(s) from your defineAstroid config.`);
+  return files;
+}
+
+async function cmdDoctor(cwd, flags) {
+  const { generateAstroidProject } = await import(GENERATORS_URL);
+  const { config, path: configPath } = await loadConfig(cwd, flags.config);
+
+  const problems = []; // { level: "error" | "warn", msg }
+  const err = (msg) => problems.push({ level: "error", msg });
+  const warn = (msg) => problems.push({ level: "warn", msg });
+  const oks = [];
+  const ok = (msg) => oks.push(msg);
+
+  ok(`config loads and validates (${rel(cwd, configPath)})`);
+
+  // 1. Generated trio freshness — regenerate in memory, diff against disk.
+  for (const file of generateAstroidProject(config)) {
+    const abs = join(cwd, file.path);
+    if (!existsSync(abs)) {
+      err(`${file.path} is missing — run \`astroid generate\`.`);
+    } else if (readFileSync(abs, "utf8") !== file.contents) {
+      warn(`${file.path} is stale (out of sync with your config) — run \`astroid generate\`.`);
+    } else {
+      ok(`${file.path} is up to date`);
+    }
+  }
+
+  // 2. wrangler.jsonc bindings — presence checks + placeholder detection. Read as
+  //    text (JSONC with comments/trailing commas) rather than parse, to stay robust.
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  if (!existsSync(wranglerPath)) {
+    err("wrangler.jsonc is missing — scaffold with `create-astroid`.");
+  } else {
+    const w = readFileSync(wranglerPath, "utf8");
+    const hasBinding = (name) => new RegExp(`"binding"\\s*:\\s*"${name}"`).test(w);
+    if (hasBinding("DB")) ok("wrangler: D1 `DB` binding present");
+    else err("wrangler.jsonc has no D1 `DB` binding.");
+    if (hasBinding("MEDIA")) ok("wrangler: R2 `MEDIA` binding present");
+    else err("wrangler.jsonc has no R2 `MEDIA` binding.");
+    if (/"main"\s*:\s*"src\/worker\.ts"/.test(w)) ok("wrangler: `main` → src/worker.ts");
+    else warn("wrangler.jsonc `main` does not point at src/worker.ts.");
+    const placeholders = w.match(/<run:[^>]*>|<your-[^>]*>/g);
+    if (placeholders) {
+      warn(
+        `wrangler.jsonc has ${placeholders.length} unresolved placeholder(s) ` +
+          `(create the bindings, e.g. \`wrangler d1 create\`, then fill the ids).`,
+      );
+    }
+  }
+
+  // 3. migrations directory (matches the generated wrangler `migrations_dir`).
+  if (existsSync(join(cwd, "migrations"))) ok("migrations/ directory present");
+  else warn("no migrations/ directory — create your D1 schema migrations there.");
+
+  // --- report ---
+  for (const m of oks) out(`  ✓ ${m}`);
+  for (const p of problems) {
+    if (p.level === "warn") out(`  ! ${p.msg}`);
+    else out(`  ✗ ${p.msg}`);
+  }
+  const errors = problems.filter((p) => p.level === "error").length;
+  const warns = problems.filter((p) => p.level === "warn").length;
+  out("");
+  if (errors) {
+    out(`doctor: ${errors} error(s), ${warns} warning(s).`);
+    process.exit(1);
+  }
+  out(warns ? `doctor: healthy, ${warns} warning(s).` : "doctor: all checks passed.");
+}
+
+async function cmdAstro(cwd, subcommand, flags, rest) {
+  // Regenerate first so schema/worker/middleware always match the config, then
+  // hand off to the project's own astro. `dev`/`build` are thin wrappers.
+  out(`astroid: regenerating from config…`);
+  await cmdGenerate(cwd, flags, { quiet: true });
+  const astroBin = resolveBin(cwd, "astro", "astro");
+  if (!astroBin) {
+    fail("Could not find `astro` in this project. Run inside an Astroid project (with astro installed).");
+  }
+  const child = spawn(process.execPath, [astroBin, subcommand, ...rest], { stdio: "inherit", cwd });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+/** Resolve a project-local CLI bin (astro, wrangler) to an absolute path via the
+ *  project's own dependency resolution — so we run the version it ships. */
+function resolveBin(cwd, pkgName, binName) {
+  try {
+    const require = createRequire(join(cwd, "package.json"));
+    const pkgPath = require.resolve(`${pkgName}/package.json`);
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[binName];
+    return binRel ? join(dirname(pkgPath), binRel) : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- deploy ----------------------------------------------------------------
+// `astroid deploy` orchestrates the one-time platform bring-up: provision the
+// bindings that still hold placeholder ids (D1/R2/KV), apply migrations, prompt
+// for secrets, and deploy — all by shelling out to the project's own `wrangler`.
+// It's plan-first: it prints exactly what it will run, and only proceeds past the
+// irreversible steps on an interactive `y` (or `--yes`). `--dry-run` prints the
+// plan and stops; `--local` targets the local D1 for migrations.
+
+const isPlaceholder = (v) => !v || /^<.*>$/.test(v);
+
+/** Pull the deploy-relevant bits out of wrangler.jsonc by regex — robust against
+ *  its JSONC comments + trailing commas (a strict JSON.parse would throw). */
+function readWranglerFacts(text) {
+  return {
+    name: text.match(/"name":\s*"([^"]+)"/)?.[1],
+    d1Name: text.match(/"database_name":\s*"([^"]+)"/)?.[1],
+    d1Id: text.match(/"database_id":\s*"([^"]*)"/)?.[1],
+    r2: [...text.matchAll(/"bucket_name":\s*"([^"]+)"/g)].map((m) => m[1]),
+    kv: [...text.matchAll(/{\s*"binding":\s*"([^"]+)",\s*"id":\s*"([^"]*)"/g)].map((m) => ({
+      binding: m[1],
+      id: m[2],
+    })),
+    // Real (uncommented) account_id line, filled in?
+    hasAccount: /^\s*"account_id":\s*"[^<][^"]*"/m.test(text),
+  };
+}
+
+/** Build the ordered provisioning plan from the still-placeholder bindings. */
+function provisionPlan(facts) {
+  const steps = [];
+  for (const bucket of facts.r2) {
+    steps.push({ kind: "r2", name: bucket, args: ["r2", "bucket", "create", bucket] });
+  }
+  if (facts.d1Name && isPlaceholder(facts.d1Id)) {
+    steps.push({ kind: "d1", name: facts.d1Name, args: ["d1", "create", facts.d1Name] });
+  }
+  for (const { binding, id } of facts.kv) {
+    if (isPlaceholder(id)) {
+      steps.push({ kind: "kv", name: binding, args: ["kv", "namespace", "create", binding] });
+    }
+  }
+  return steps;
+}
+
+/** Look up a just-created resource's id by name via a `… list` JSON command. */
+function lookupId(wranglerBin, cwd, args, pick) {
+  try {
+    const rows = JSON.parse(execFileSync(process.execPath, [wranglerBin, ...args], { cwd, encoding: "utf8" }));
+    return pick(Array.isArray(rows) ? rows : []) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Replace a KV binding's placeholder id in the wrangler.jsonc text. */
+function patchKvId(text, binding, id) {
+  return text.replace(
+    new RegExp(`("binding":\\s*"${binding}",\\s*"id":\\s*)"<[^"]*>"`),
+    `$1${JSON.stringify(id)}`,
+  );
+}
+
+async function cmdDeploy(cwd, flags, rest) {
+  const dryRun = rest.includes("--dry-run");
+  const assumeYes = rest.includes("--yes") || rest.includes("-y");
+  const remoteArgs = rest.includes("--local") ? [] : ["--remote"];
+
+  await loadConfig(cwd, flags.config); // validates the config (throws on a bad shape)
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
+
+  // Regenerate so the shipped worker/schema always match the config.
+  await cmdGenerate(cwd, flags, { quiet: true });
+
+  let wrangler = readFileSync(wranglerPath, "utf8");
+  const facts = readWranglerFacts(wrangler);
+  const plan = provisionPlan(facts);
+
+  // Print the plan.
+  out("astroid deploy — plan:\n");
+  out("  Provision:");
+  if (plan.length === 0) out("    (all bindings already have ids)");
+  for (const s of plan) out(`    wrangler ${s.args.join(" ")}`);
+  out(`\n  Migrate:  wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
+  out("  Secrets:  wrangler secret put SESSION_SECRET   (prompted)");
+  out("  Deploy:   wrangler deploy\n");
+  if (!facts.hasAccount) {
+    out("  ! No account_id set — uncomment it in wrangler.jsonc or export CLOUDFLARE_ACCOUNT_ID.\n");
+  }
+
+  if (dryRun) {
+    out("(dry run — nothing executed)");
+    return;
+  }
+
+  // Gate the irreversible work behind a clear yes.
+  if (!assumeYes) {
+    if (!process.stdin.isTTY) {
+      fail("Refusing to provision + deploy non-interactively. Re-run with --yes (or --dry-run to preview).");
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("Provision the above, then migrate + deploy? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (answer !== "y" && answer !== "yes") {
+      out("Aborted.");
+      return;
+    }
+  }
+
+  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
+  if (!wranglerBin) fail("Could not find `wrangler` in this project (add it as a devDependency).");
+  const runInherit = (args) => spawnSync(process.execPath, [wranglerBin, ...args], { cwd, stdio: "inherit" });
+
+  // 1) Provision, patching discovered ids back into wrangler.jsonc.
+  for (const s of plan) {
+    out(`\n▸ wrangler ${s.args.join(" ")}`);
+    const res = runInherit(s.args);
+    // R2 bucket create is idempotent-ish (an existing bucket errors) — tolerate it.
+    if (res.status !== 0 && s.kind !== "r2") fail(`Provisioning failed at: wrangler ${s.args.join(" ")}`);
+
+    if (s.kind === "d1") {
+      const id = lookupId(wranglerBin, cwd, ["d1", "list", "--json"], (rows) => rows.find((r) => r.name === s.name)?.uuid);
+      if (id) {
+        wrangler = wrangler.replace(/"database_id":\s*"<[^"]*>"/, `"database_id": ${JSON.stringify(id)}`);
+        writeFileSync(wranglerPath, wrangler);
+        out(`  ↳ database_id = ${id}`);
+      } else {
+        out("  ↳ couldn't auto-detect the id — fill database_id in wrangler.jsonc by hand.");
+      }
+    } else if (s.kind === "kv") {
+      const id = lookupId(wranglerBin, cwd, ["kv", "namespace", "list"], (rows) =>
+        rows.find((r) => typeof r.title === "string" && r.title.endsWith(s.name))?.id,
+      );
+      if (id) {
+        wrangler = patchKvId(wrangler, s.name, id);
+        writeFileSync(wranglerPath, wrangler);
+        out(`  ↳ ${s.name} id = ${id}`);
+      } else {
+        out(`  ↳ couldn't auto-detect ${s.name}'s id — fill it in wrangler.jsonc by hand.`);
+      }
+    }
+  }
+
+  // 2) Migrations.
+  out(`\n▸ wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
+  if (runInherit(["d1", "migrations", "apply", "DB", ...remoteArgs]).status !== 0) fail("Migrations failed.");
+
+  // 3) Secrets (interactive; wrangler prompts for the value).
+  out("\n▸ wrangler secret put SESSION_SECRET");
+  runInherit(["secret", "put", "SESSION_SECRET"]);
+
+  // 4) Deploy.
+  out("\n▸ wrangler deploy");
+  if (runInherit(["deploy"]).status !== 0) fail("Deploy failed.");
+  out("\n✓ Deployed.");
+}
+
+// --- helpers ---------------------------------------------------------------
+function out(s) {
+  process.stdout.write(`${s}\n`);
+}
+function fail(msg) {
+  process.stderr.write(`astroid: ${msg}\n`);
+  process.exit(1);
+}
+function rel(cwd, abs) {
+  return abs.startsWith(cwd) ? abs.slice(cwd.length + 1) : abs;
+}
+
+const USAGE = `astroid — the Astroid meta-framework CLI
+
+Usage:
+  astroid generate [--config <path>] [--cwd <dir>]   regenerate src/schema.ts, src/worker.ts, src/middleware.ts
+  astroid doctor   [--config <path>] [--cwd <dir>]   validate config, bindings, and generated-file freshness
+  astroid dev      [...astro args]                   regenerate, then run \`astro dev\`
+  astroid build    [...astro args]                   regenerate, then run \`astro build\`
+  astroid deploy   [--dry-run] [--yes] [--local]     provision bindings + migrate + secrets + deploy
+
+New project:  npm create astroid@latest
+`;
+
+async function main() {
+  const { command, flags, rest } = parseArgs(process.argv.slice(2));
+  const cwd = flags.cwd ? resolve(flags.cwd) : process.cwd();
+
+  switch (command) {
+    case "generate":
+    case "gen":
+      await cmdGenerate(cwd, flags);
+      break;
+    case "doctor":
+      await cmdDoctor(cwd, flags);
+      break;
+    case "dev":
+      await cmdAstro(cwd, "dev", flags, rest);
+      break;
+    case "build":
+      await cmdAstro(cwd, "build", flags, rest);
+      break;
+    case "deploy":
+      await cmdDeploy(cwd, flags, rest);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      out(USAGE);
+      process.exit(command ? 0 : 1);
+      break;
+    default:
+      process.stderr.write(`astroid: unknown command "${command}"\n\n${USAGE}`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack : String(err)}\n`);
+  process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The starting shape the front-end takes. Not a fork — each archetype is a preset
+ * of defaults (which sections/modules are on, nav shape) that the site then tunes.
+ * `marketing` = the lean brochure floor (louise-web, no commerce); `storefront` =
+ * DTC shop (coracle); `wholesale` = B2B/private-label (ghostfire); `portfolio` =
+ * gallery + prints + client portal (megbowen).
+ */
+export type Archetype = "marketing" | "storefront" | "wholesale" | "portfolio";
+/**
+ * The section vocabulary — the editable home page is an ordered list of these, top
+ * to bottom. Each maps to a themeable component in the Astroid section library.
+ * Drawn from real usage across the target sites (annotated below).
+ */
+export type SectionKind = "hero" | "marquee" | "featureGrid" | "featured" | "productGrid" | "gallery" | "story" | "visit" | "cta" | "testimonial" | "contact";
+/**
+ * Optional capabilities the site switches on. Pluggable, not core — a portfolio
+ * site runs none of the commerce ones. `orderTracking` is shared across both
+ * coffee brands, so it's first-class but still opt-in.
+ */
+export type ModuleKind = "orderTracking" | "subscriptions" | "giftCards" | "wholesaleInquiry" | "privateLabel";
+/** Commerce backend — mirrors Louise's provider set (louise-toolkit/commerce). */
+export type CommerceProvider = "stripe" | "square" | "fourthwall";
+export interface Theme {
+    /** Display name — the brand, used in nav, `<title>`, OG cards. */
+    name: string;
+    /** Path to the primary logo (media-library asset or a `/brand/*` file). */
+    logo?: string;
+    /**
+     * Brand color tokens → CSS variables + a daisyUI theme, surfaced in Louise
+     * Settings so the brand is editable in place (not hard-coded). `brand` is
+     * required; `secondary`/`tertiary` mirror `site_settings`' existing columns.
+     */
+    colors: {
+        brand: string;
+        secondary?: string;
+        tertiary?: string;
+    };
+    /** Font preset key (a bundled `@font-face` set) or a custom family name. */
+    font?: string;
+}
+export interface Portal {
+    enabled: boolean;
+    /** Require a session to view the whole site (Meg Bowen's gated preview), not
+     *  just the account area. Default `false`. */
+    gated?: boolean;
+    /** Modules exposed inside the account area (e.g. `orderTracking`). */
+    features?: ModuleKind[];
+}
+export interface CommerceConfig {
+    provider: CommerceProvider;
+}
+export interface DeployConfig {
+    platform: "cloudflare";
+    /** Media base for R2 + `cf-image` resizing — matches Louise's media route
+     *  (`media.<brand>/cdn-cgi/image`). Default `"/media"`. */
+    mediaBase?: string;
+}
+export interface AstroidConfig {
+    /**
+     * Stable project slug — the worker/D1/R2 base name and default subdomain (e.g.
+     * `"coracle"`). Required and non-empty; it drives the generated binding names.
+     */
+    key: string;
+    /** Hostname(s) this site serves (prod + preview), for custom-domain routes. */
+    hosts?: string[];
+    /** Starting shape; sets section/module/nav defaults the site can override. */
+    archetype: Archetype;
+    /** The single brand's theme (display name + color tokens + font). */
+    theme: Theme;
+    /** The editable home page, top to bottom. Omit to take the archetype default. */
+    sections?: SectionKind[];
+    /** Optional capabilities switched on for this site. */
+    modules?: ModuleKind[];
+    /** Gated account/portal area (order tracking, client galleries). */
+    portal?: Portal;
+    /** Commerce backend. */
+    commerce?: CommerceConfig;
+    deploy?: DeployConfig;
+}
+/**
+ * Define an Astroid project. An identity function in the shape of Astro's
+ * `defineConfig`: it returns the config verbatim with full type-checking +
+ * inference, and validates the invariants that would otherwise fail deep inside
+ * generation (a non-empty project `key`, since it names the generated bindings;
+ * a brand `theme.name` + `colors.brand`, since they seed the site and theme).
+ *
+ * ```ts
+ * export default defineAstroid({
+ *   key: "coracle",
+ *   archetype: "storefront",
+ *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
+ *   sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+ *   commerce: { provider: "square" },
+ *   deploy: { platform: "cloudflare" },
+ * });
+ * ```
+ */
+export declare function defineAstroid(config: AstroidConfig): AstroidConfig;

package/dist/config.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `defineAstroid` — the Astroid project configuration surface.
+//
+// Astroid is the opinionated layer over Louise Toolkit + Astro. A site's whole
+// shape — its brand + theme + editable home, its commerce backend, its optional
+// modules — collapses into ONE typed config here. Astroid consumes it to generate
+// the Louise wiring (worker routes, middleware, Drizzle schema, theme tokens) a
+// site would otherwise hand-write per repo.
+//
+// ONE brand per project. Every site Astroid targets (coracle.coffee,
+// ghostfire.coffee, themidwestartist.com, louise-web) serves a single brand from a
+// single deploy — none does host/tenant dispatch. The axis that genuinely
+// multiplexes is *editors* (Louise's org plugin, #100) and *audiences* (a gated
+// portal alongside the public site), not brands — so both live here as options on
+// the one brand, not as a `brands[]` array.
+//
+// The vocabulary below is not invented: `Archetype`, `SectionKind`, and
+// `ModuleKind` are extracted from the real sites Astroid targets — a storefront
+// (coracle), a wholesale front (ghostfire), an artist portfolio (megbowen), and a
+// plain marketing baseline (louise-web).
+import { AstroidConfigError } from "./errors.js";
+/**
+ * Define an Astroid project. An identity function in the shape of Astro's
+ * `defineConfig`: it returns the config verbatim with full type-checking +
+ * inference, and validates the invariants that would otherwise fail deep inside
+ * generation (a non-empty project `key`, since it names the generated bindings;
+ * a brand `theme.name` + `colors.brand`, since they seed the site and theme).
+ *
+ * ```ts
+ * export default defineAstroid({
+ *   key: "coracle",
+ *   archetype: "storefront",
+ *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
+ *   sections: ["hero", "marquee", "featured", "productGrid", "visit"],
+ *   commerce: { provider: "square" },
+ *   deploy: { platform: "cloudflare" },
+ * });
+ * ```
+ */
+export function defineAstroid(config) {
+    if (!config.key || config.key.trim().length === 0) {
+        throw new AstroidConfigError("Astroid config requires a non-empty `key` (it names the generated worker/D1/R2 bindings)");
+    }
+    if (!config.theme || !config.theme.name || config.theme.name.trim().length === 0) {
+        throw new AstroidConfigError("Astroid config requires `theme.name` (the brand's display name)");
+    }
+    if (!config.theme.colors || !config.theme.colors.brand) {
+        throw new AstroidConfigError("Astroid config requires `theme.colors.brand` (the primary brand color)");
+    }
+    return config;
+}