create-astroid 0.10.0 → 0.11.0

package/index.mjs

@@ -13,8 +13,17 @@
 // wrangler) fills them in. The generators are the SAME ones `astroid generate`
 // uses, so a fresh project is already in sync.
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import {
@@ -31,8 +40,41 @@ import {
   generateAstroidSecretsEnv,
   generateAstroidWrangler,
 } from "astroidjs";
+import {
+  addWorkspacePackage,
+  INTO_REPOSITORY_FILES,
+  intoPathProblem,
+  intoRootScripts,
+  intoScriptName,
+  mergeRootScripts,
+  workersBuildsSettings,
+} from "./into.mjs";
 import { toolkitRanges } from "./toolkit-ranges.mjs";
 
+/** The repository root holding `cwd`, or null outside a git checkout. */
+function gitRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Whether git ignores `path` (relative to `root`); null when git can't say. */
+function gitIgnores(root, path) {
+  try {
+    execFileSync("git", ["check-ignore", "-q", path], { cwd: root, stdio: "ignore" });
+    return true;
+  } catch (error) {
+    // Exit 1 is "not ignored"; anything else is git failing to answer.
+    return error?.status === 1 ? false : null;
+  }
+}
+
 const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
 
 // Files (and dirs) whose leading `_` is stripped on copy (npm strips real
@@ -45,6 +87,24 @@ const DOTFILE_RENAMES = {
   _github: ".github",
 };
 
+// The editor-free app shape (`--app`, `editor: false`). It starts from the same
+// template, leaves out the editor's files, and lays `template/_app/` over the
+// rest, so the two shapes share every file that doesn't depend on an editor.
+const APP_OVERLAY = "_app";
+const APP_SKIP = new Set([
+  "migrations/0000_content.sql",
+  "scripts/seed-editors.mjs",
+  "src/auth.ts",
+  "src/components/Hero.astro",
+  "src/components/LouiseEdit.astro",
+  "src/layouts/Site.astro",
+  "src/lib/pages.ts",
+  "src/pages/[...slug].astro",
+  "src/pages/api/auth/[...all].ts",
+  "src/pages/contact.astro",
+  "src/pages/login.astro",
+]);
+
 // Archetype → default editable home sections. Imported from astroidjs rather
 // than duplicated here: as a literal in this file it could name a section that
 // doesn't exist and nothing would say so (it did—`marquee`, `featured`,
@@ -99,15 +159,21 @@ async function prompt(question, fallback) {
 }
 
 // --- scaffold --------------------------------------------------------------
-function copyTemplate(srcDir, destDir, tokens) {
-  mkdirSync(destDir, { recursive: true });
+// `skip` holds template-relative POSIX paths to leave out. Directories are made
+// only when a file lands in them, so skipping a directory's every file leaves
+// no empty directory behind.
+function copyTemplate(srcDir, destDir, tokens, { skip = new Set(), rel = "" } = {}) {
   for (const entry of readdirSync(srcDir)) {
+    // The app overlay is copied on its own, over the rest, and only for `--app`.
+    if (rel === "" && entry === APP_OVERLAY) continue;
     const src = join(srcDir, entry);
+    const path = rel ? `${rel}/${entry}` : entry;
     const renamed = DOTFILE_RENAMES[entry] ?? entry;
     const dest = join(destDir, renamed);
     if (statSync(src).isDirectory()) {
-      copyTemplate(src, dest, tokens);
-    } else {
+      copyTemplate(src, dest, tokens, { skip, rel: path });
+    } else if (!skip.has(path)) {
+      mkdirSync(destDir, { recursive: true });
       const raw = readFileSync(src, "utf8");
       writeFileSync(dest, applyTokens(raw, tokens));
     }
@@ -128,12 +194,15 @@ function astroidConfigSource(config) {
     "export default defineAstroid({",
     `  key: ${JSON.stringify(config.key)},`,
     `  archetype: ${JSON.stringify(config.archetype)},`,
+    // Must be emitted: every generator reads the shape from THIS file, so a
+    // config without it would regenerate an editor this app has no seam for.
+    ...(config.editor === false ? ["  editor: false,"] : []),
     ...(config.hosts?.length ? [`  hosts: ${JSON.stringify(config.hosts)},`] : []),
     "  theme: {",
     `    name: ${JSON.stringify(config.theme.name)},`,
     `    colors: { brand: ${JSON.stringify(config.theme.colors.brand)} },`,
     "  },",
-    `  sections: ${JSON.stringify(config.sections)},`,
+    ...(config.sections ? [`  sections: ${JSON.stringify(config.sections)},`] : []),
     // `square` must be emitted too: `astroid doctor` derives the required
     // secrets from THIS file, so a multi-location project whose config lost the
     // option would be told it is missing a SQUARE_LOCATION_ID it must not have.
@@ -169,6 +238,15 @@ function astroidConfigSource(config) {
           "  },",
         ]
       : []),
+    // Must be emitted: the scaffold's layout reads `credit` from THIS file at
+    // render time, so a config without it renders no footer.
+    ...(config.credit
+      ? [
+          `  credit: { name: ${JSON.stringify(config.credit.name)}, href: ${JSON.stringify(
+            config.credit.href,
+          )} },`,
+        ]
+      : []),
     '  deploy: { platform: "cloudflare" },',
     "});",
     "",
@@ -206,11 +284,24 @@ Options:
                         with presence, field sync, and a rich-text soft-lock
   --portal              Add a customer/member portal: a second, isolated auth
                         instance plus role-gated routes
+  --into <path>         Scaffold one app into an existing repository at <path>
+                        (for example, workers/order), beside the app already
+                        there: adds it to the root pnpm-workspace.yaml and adds
+                        namespaced root scripts, and leaves the rest alone
+  --app                 Scaffold an app with no pages to edit (editor: false):
+                        no editor, sign-in, or content tables, and a versioned
+                        JSON API under /api/v1. Its settings stay in the editor
+                        of a site that has one
+  --credit-name <name>  Credit who built the site in the footer ("Site by <name>")
+  --credit-href <url>   Where the credit links; needs --credit-name, and the
+                        other way round
   -h, --help            Show this help
   -v, --version         Show the create-astroid version
 
 Anything not passed as a flag is prompted for; in a non-TTY every prompt takes
 its default, so the command is CI-safe. The target directory must be empty.
+With --app there is no archetype prompt; --archetype still sets the business
+type in structured data.
 `;
 
 async function main() {
@@ -231,15 +322,45 @@ async function main() {
     return;
   }
 
-  const dirArg = positionals[0] ?? flags.dir;
+  // `--into <path>`: one app into a repository that already holds one. The
+  // path is the app's directory, relative to where this runs, and has to land
+  // inside the repository, whose root gets the workspace entry and scripts.
+  const intoArg = flags.into;
+  if (intoArg !== undefined && (typeof intoArg !== "string" || positionals[0] || flags.dir)) {
+    process.stderr.write(
+      typeof intoArg !== "string"
+        ? "create-astroid: --into needs a path, for example --into workers/order\n"
+        : "create-astroid: --into names the directory, so it can't go with --dir or a positional one\n",
+    );
+    process.exit(1);
+  }
+  const into = typeof intoArg === "string";
+  // Real paths on both sides: git reports the root through symlinks (macOS's
+  // /tmp is /private/tmp), and a relative path across the two would climb out.
+  const cwd = realpathSync(process.cwd());
+  const repoRoot = into ? (gitRoot(cwd) ?? cwd) : null;
+  const intoPath = into ? relative(repoRoot, resolve(cwd, intoArg)).split(sep).join("/") : null;
+  if (into) {
+    const problem = intoPathProblem(intoPath);
+    if (problem) {
+      process.stderr.write(`create-astroid: ${problem}\n`);
+      process.exit(1);
+    }
+  }
+
+  const dirArg = into ? intoArg : (positionals[0] ?? flags.dir);
   const rawName = flags.name || (dirArg ? basename(resolve(dirArg)) : undefined);
   const name = await prompt("Brand / site name", rawName || "My Astroid Site");
   const key = slugify(
     flags.key || (await prompt("Project key (slug)", slugify(name) || "my-site")),
   );
   const dir = resolve(dirArg || (await prompt("Directory", key)) || key);
+  // An app with no pages to edit (`editor: false`). Its archetype chooses no
+  // sections, so it isn't prompted for; it only sets the structured-data type.
+  const app = flags.app === true || flags.app === "true";
   const archetypeRaw = (
-    flags.archetype || (await prompt(`Archetype (${ARCHETYPES.join("/")})`, "marketing"))
+    flags.archetype ||
+    (app ? "marketing" : await prompt(`Archetype (${ARCHETYPES.join("/")})`, "marketing"))
   ).toLowerCase();
   const archetype = ARCHETYPES.includes(archetypeRaw) ? archetypeRaw : "marketing";
   const color = flags.color || (await prompt("Brand color (hex)", "#5b4bff"));
@@ -247,7 +368,9 @@ async function main() {
   // The customer PORTAL is opt-in via --portal, but a storefront IMPLIES one—a
   // shop has customers who sign in, reorder, and track orders—so enable it there
   // by default. (Commerce below stays opt-in: infra a marketing site shouldn't carry.)
-  const portal = flags.portal === true || flags.portal === "true" || archetype === "storefront";
+  // An app gets one only when asked: its customers may sign in on the site.
+  const portal =
+    flags.portal === true || flags.portal === "true" || (archetype === "storefront" && !app);
   // The map module is opt-in and pulls real weight (maplibre-gl is ~1 MB), so
   // it is never on by default.
   const map = flags.map === true || flags.map === "true";
@@ -289,18 +412,70 @@ async function main() {
     process.exit(1);
   }
 
+  // A pair or nothing: a credit with no link, or a link with nothing to show,
+  // is a half-typed flag rather than a choice.
+  const creditName = typeof flags["credit-name"] === "string" ? flags["credit-name"] : undefined;
+  const creditHref = typeof flags["credit-href"] === "string" ? flags["credit-href"] : undefined;
+  if (
+    (flags["credit-name"] !== undefined || flags["credit-href"] !== undefined) &&
+    !(creditName && creditHref)
+  ) {
+    process.stderr.write("create-astroid: --credit-name and --credit-href go together\n");
+    process.exit(1);
+  }
+
+  // Refused here with the flag's name, rather than by `defineAstroid` with a
+  // stack trace: live editing needs an editor to edit with.
+  if (app && realtime) {
+    process.stderr.write("create-astroid: --realtime needs an editor, so it can't go with --app\n");
+    process.exit(1);
+  }
+
   if (existsSync(dir) && readdirSync(dir).length > 0) {
     process.stderr.write(`create-astroid: target directory is not empty: ${dir}\n`);
     process.exit(1);
   }
 
+  // Every root edit `--into` makes, worked out before anything is written, so
+  // a root file it can't edit stops the scaffold rather than leaving half of it.
+  const rootEdits = [];
+  if (into) {
+    const workspacePath = join(repoRoot, "pnpm-workspace.yaml");
+    if (existsSync(workspacePath)) {
+      const current = readFileSync(workspacePath, "utf8");
+      const next = addWorkspacePackage(current, intoPath);
+      if (next === null) {
+        process.stderr.write(
+          `create-astroid: can't add ${intoPath} to pnpm-workspace.yaml's \`packages\` safely. ` +
+            "Add it by hand, then run this again.\n",
+        );
+        process.exit(1);
+      }
+      if (next !== current) {
+        rootEdits.push({
+          path: workspacePath,
+          contents: next,
+          what: "pnpm-workspace.yaml (added the app)",
+        });
+      }
+      // The app's install runs from the root, under the root's build approvals.
+      if (!/workerd/.test(current)) {
+        rootEdits.push({
+          note:
+            "pnpm-workspace.yaml approves no `workerd` build, so `pnpm install` may refuse it. " +
+            "Add `allowBuilds: { esbuild: true, workerd: true }`.",
+        });
+      }
+    }
+  }
+
   // Validate + normalize through the real config surface (throws on a bad shape).
   const config = defineAstroid({
     key,
     archetype,
     ...(host ? { hosts: [host] } : {}),
     theme: { name, colors: { brand: color } },
-    sections: ARCHETYPE_SECTIONS[archetype],
+    ...(app ? { editor: false } : { sections: ARCHETYPE_SECTIONS[archetype] }),
     ...(commerce
       ? {
           commerce: {
@@ -317,6 +492,7 @@ async function main() {
     // : {})` spreads would let the later one overwrite the earlier, silently
     // dropping a module whenever both were passed.
     ...(modules.length > 0 ? { modules } : {}),
+    ...(creditName && creditHref ? { credit: { name: creditName, href: creditHref } } : {}),
     deploy: { platform: "cloudflare" },
   });
 
@@ -328,6 +504,21 @@ async function main() {
   const realtimeEnv = generateAstroidRealtimeEnv(config);
   // The Square Web Payments public vars, or nothing.
   const checkoutEnv = generateAstroidCheckoutEnv(config);
+  // An app's portal is the only thing in it that signs anyone in or sends mail,
+  // so the session secret, the mail binding, and the sender come with it. The
+  // editor shape's env.d.ts and .env.example declare these for every project.
+  const appPortalEnv =
+    app && portal
+      ? [
+          "  /** Cloudflare Email Sending: the portal's password-reset mail. */",
+          '  EMAIL: import("louise-toolkit/email").EmailSender;',
+          "  /** Signs the portal's Better Auth sessions (`wrangler secret put SESSION_SECRET`). */",
+          "  SESSION_SECRET: string;",
+          "  /** `from` address for the portal's mail. */",
+          "  MAIL_FROM: string;",
+        ].join("\n")
+      : "";
+  const envMembers = [appPortalEnv, envBindings, realtimeEnv, checkoutEnv].filter(Boolean);
   const tokens = {
     KEY: key,
     BRAND_NAME: name,
@@ -337,9 +528,7 @@ async function main() {
     // Extra CloudflareEnv members the queue pipeline needs, or nothing. A
     // declaration is a promise—a marketing site must not claim a binding its
     // wrangler.jsonc never creates.
-    ASTROID_ENV_BINDINGS: [envBindings, realtimeEnv, checkoutEnv].filter(Boolean).join("\n")
-      ? `\n${[envBindings, realtimeEnv, checkoutEnv].filter(Boolean).join("\n")}`
-      : "",
+    ASTROID_ENV_BINDINGS: envMembers.length > 0 ? `\n${envMembers.join("\n")}` : "",
     // The portal session on App.Locals, or nothing—a project that types a
     // local it never sets invites a null-check nobody needs.
     ASTROID_PORTAL_LOCALS: portalLocals ? `\n${portalLocals}` : "",
@@ -348,10 +537,84 @@ async function main() {
     // module takes its dormant path deliberately rather than tripping over
     // an undefined binding. Empty for a project with no credentialed module.
     ASTROID_MODULE_SECRETS: generateAstroidSecretsEnv(config),
+    // The app shape's .env.example: the portal's secrets, or nothing.
+    ASTROID_APP_SECRETS:
+      app && portal
+        ? [
+            "",
+            "# --- portal ---------------------------------------------------------------",
+            "#",
+            "# Signs the portal's Better Auth sessions. Generate: `openssl rand -base64 32`.",
+            "# Empty is fine under `pnpm dev`, which serves on localhost.",
+            "SESSION_SECRET=",
+            "",
+            "# `from` address for the portal's password-reset mail.",
+            `MAIL_FROM=no-reply@${key}.example`,
+          ].join("\n")
+        : "",
   };
 
   // 1. The static floor (Astro app, auth seam, config files) with tokens filled.
-  copyTemplate(TEMPLATE_DIR, dir, tokens);
+  //    An app leaves out the editor's files and lays its own over the rest.
+  //    `--into` leaves out the repository's files too; see 1a.
+  const skip = new Set([...(app ? APP_SKIP : []), ...(into ? INTO_REPOSITORY_FILES : [])]);
+  copyTemplate(TEMPLATE_DIR, dir, tokens, { skip });
+  if (app) copyTemplate(join(TEMPLATE_DIR, APP_OVERLAY), dir, tokens);
+
+  // 1a. `--into`: the repository's files. Each is the root's, so it's written
+  //     there only when the root has none, and an existing one is left alone
+  //     apart from the edits worked out above.
+  const intoNotes = [];
+  const intoWrote = [];
+  if (into) {
+    const fromTemplate = (rel) =>
+      applyTokens(readFileSync(join(TEMPLATE_DIR, rel), "utf8"), tokens);
+    for (const edit of rootEdits) {
+      if (edit.note) intoNotes.push(edit.note);
+      else {
+        writeFileSync(edit.path, edit.contents);
+        intoWrote.push(edit.what);
+      }
+    }
+    if (!existsSync(join(repoRoot, "pnpm-workspace.yaml"))) {
+      // The template's header says it isn't a workspace, which this one is.
+      const workspace = fromTemplate("pnpm-workspace.yaml").replace(
+        /^# Not a workspace — .*\n# .*\n/m,
+        "# The workspace for this repository's apps. pnpm reads its settings from\n" +
+          "# THIS file, and `overrides` in package.json is silently ignored.\n",
+      );
+      write(repoRoot, "pnpm-workspace.yaml", addWorkspacePackage(workspace, intoPath));
+      intoWrote.push("pnpm-workspace.yaml");
+    }
+    for (const doc of ["docs/ARCHITECTURE.md", "docs/DECISIONS.md", "docs/RUNBOOK.md"]) {
+      if (existsSync(join(repoRoot, doc))) continue;
+      write(repoRoot, doc, fromTemplate(doc));
+      intoWrote.push(doc);
+    }
+    // The root's .gitignore when there is one, as long as it keeps this app's
+    // secrets out. A pattern anchored to the root (`/.dev.vars`) wouldn't, so
+    // git is asked, and when it can't say, the app gets its own.
+    if (!existsSync(join(repoRoot, ".gitignore"))) {
+      write(repoRoot, ".gitignore", fromTemplate("_gitignore"));
+      intoWrote.push(".gitignore");
+    } else {
+      const ignored = gitIgnores(repoRoot, `${intoPath}/.dev.vars`);
+      if (ignored !== true) {
+        write(dir, ".gitignore", fromTemplate("_gitignore"));
+        intoNotes.push(
+          ignored === false
+            ? `The root .gitignore doesn't ignore ${intoPath}/.dev.vars, so the app has its own .gitignore.`
+            : `git couldn't say whether ${intoPath}/.dev.vars is ignored, so the app has its own .gitignore.`,
+        );
+      }
+    }
+    // The workflow runs the root app's checks from the root, so the second
+    // app's would be new steps in it; they're the repository's to add.
+    intoNotes.push(
+      `CI: add \`pnpm run doctor:${intoScriptName(intoPath)}\` and ` +
+        `\`pnpm run build:${intoScriptName(intoPath)}\` to the repository's workflow.`,
+    );
+  }
 
   // 1b. Toolkit versions + module dependencies, merged into the copied package.json.
   //
@@ -374,9 +637,38 @@ async function main() {
     pkg.dependencies = Object.fromEntries(
       Object.entries({ ...pkg.dependencies, ...extraDeps }).sort(([a], [b]) => a.localeCompare(b)),
     );
+    // An app has no editors to seed, and no script to seed them with.
+    if (app) delete pkg.scripts["seed:editors"];
+    // The root's pnpm runs the workspace, so the app doesn't pin its own.
+    if (into) delete pkg.packageManager;
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
   }
 
+  // 1c. `--into`: the root scripts that run this app from the root, added
+  //     beside the existing ones and never over one. A root with no
+  //     package.json gets a private one, pinning pnpm the way a scaffold does.
+  let intoScripts = { added: [], skipped: [] };
+  if (into) {
+    const rootPkgPath = join(repoRoot, "package.json");
+    const template = JSON.parse(readFileSync(join(TEMPLATE_DIR, "package.json"), "utf8"));
+    const rootPkg = existsSync(rootPkgPath)
+      ? JSON.parse(readFileSync(rootPkgPath, "utf8"))
+      : {
+          name: slugify(basename(repoRoot)) || "workspace",
+          private: true,
+          packageManager: template.packageManager,
+        };
+    intoScripts = mergeRootScripts(
+      rootPkg.scripts ?? {},
+      intoRootScripts(intoScriptName(intoPath), intoPath),
+    );
+    rootPkg.scripts = intoScripts.scripts;
+    writeFileSync(rootPkgPath, `${JSON.stringify(rootPkg, null, 2)}\n`);
+    for (const name of intoScripts.skipped) {
+      intoNotes.push(`The root already has a \`${name}\` script, so it was left as it was.`);
+    }
+  }
+
   // 2. The typed config the generators + the app read.
   write(dir, "astroid.config.ts", astroidConfigSource(config));
 
@@ -387,7 +679,8 @@ async function main() {
   // 3a. The home page seed, built from the config's own `sections`. It used to be
   //     a fixed template file that seeded the marketing sections for every
   //     archetype, and token substitution can't escape a brand name for SQL.
-  write(dir, "seed/home.seed.sql", generateAstroidHomeSeed(config));
+  //     An app has no pages, so it seeds none.
+  if (!app) write(dir, "seed/home.seed.sql", generateAstroidHomeSeed(config));
 
   // 3b. Every scaffold-once module file this config implies—the queue seam and
   //     webhook receivers, the portfolio gallery page, the PWA service worker +
@@ -420,13 +713,19 @@ async function main() {
   //    resolvable at scaffold time. If not, leave a stub + a one-liner to generate
   //    it after install (the project has `louise` on its path then).
   let authMigrationOk = false;
+  // An app has no editor instance, so its portal's tables are its first.
+  const portalMigration = app
+    ? "migrations/0001_portal_auth.sql"
+    : "migrations/0002_portal_auth.sql";
   try {
     const { generateAuthSchemaSql } = await import("louise-toolkit/auth");
     // The EDITOR instance's tables—`louise_`-prefixed (the editor convention),
     // leaving the unprefixed `user`/`session` names free for a second/portal
     // instance. Must match the `tablePrefix` in src/auth.ts and the `louise_user`
     // table the generated `editorsRoute` reads.
-    write(dir, "migrations/0001_auth.sql", generateAuthSchemaSql({ tablePrefix: "louise_" }));
+    if (!app) {
+      write(dir, "migrations/0001_auth.sql", generateAuthSchemaSql({ tablePrefix: "louise_" }));
+    }
     // The portal's own auth tables—a SECOND Better Auth instance sharing one D1
     // but never a row, so a portal account can't sign into the studio and an
     // editor doesn't appear in the portal. `customers: true` (email + password)
@@ -436,31 +735,110 @@ async function main() {
     if (config.portal?.enabled) {
       write(
         dir,
-        "migrations/0002_portal_auth.sql",
+        portalMigration,
         generateAuthSchemaSql({ customers: true, tablePrefix: config.portal.tablePrefix ?? "" }),
       );
     }
     authMigrationOk = true;
   } catch {
-    write(
-      dir,
-      "migrations/0001_auth.sql",
-      "-- Better Auth tables (editor, louise_ prefix) — generate after install:\n--   pnpm exec louise gen-auth-schema --table-prefix louise_ --out migrations/0001_auth.sql\n",
-    );
+    if (!app) {
+      write(
+        dir,
+        "migrations/0001_auth.sql",
+        "-- Better Auth tables (editor, louise_ prefix) — generate after install:\n--   pnpm exec louise gen-auth-schema --table-prefix louise_ --out migrations/0001_auth.sql\n",
+      );
+    }
     // Same stub for the portal's prefixed set. Without it a portal scaffold
     // looks complete, builds, and fails on the first sign-in with a missing
     // table—the one failure mode a stub exists to prevent.
     if (config.portal?.enabled) {
       write(
         dir,
-        "migrations/0002_portal_auth.sql",
+        portalMigration,
         "-- Portal Better Auth tables (customers, unprefixed) — generate after install:\n" +
-          "--   pnpm exec louise gen-auth-schema --out migrations/0002_portal_auth.sql\n",
+          `--   pnpm exec louise gen-auth-schema --out ${portalMigration}\n`,
       );
     }
   }
 
+  // An app with no tables of its own still gets the directory, because
+  // `astroid ship` applies migrations from it on every deploy until the config
+  // says another app owns the database (`deploy.migrations: false`).
+  if (app && !existsSync(join(dir, "migrations"))) write(dir, "migrations/.gitkeep", "");
+
+  if (into) {
+    // Everything runs from the root: one install, one lockfile, and the root
+    // scripts added above.
+    const scriptName = intoScriptName(intoPath);
+    const inApp = `pnpm --dir ${intoPath}`;
+    const settings = workersBuildsSettings(intoPath);
+    const width = Math.max(...settings.map(([label]) => label.length));
+    process.stdout.write(
+      [
+        "",
+        `✓ Scaffolded ${name} → ${intoPath}${app ? " (an app with no editor)" : ""}`,
+        ...(intoWrote.length ? [`  at the repository root: ${intoWrote.join(", ")}`] : []),
+        ...(intoScripts.added.length ? [`  root scripts: ${intoScripts.added.join(", ")}`] : []),
+        "",
+        "Next steps, from the repository root:",
+        "  pnpm install",
+        ...(authMigrationOk
+          ? []
+          : [
+              "  # generate the Better Auth migration(s), as the stub files in its",
+              "  # migrations/ directory say, before applying migrations",
+            ]),
+        `  ${inApp} exec astroid provision`,
+        ...(app
+          ? []
+          : [
+              `  ${inApp} exec wrangler d1 migrations apply DB --remote`,
+              `  ${inApp} exec wrangler d1 execute DB --remote --file seed/home.seed.sql`,
+              `  OWNER_EMAIL=you@example.com ${inApp} run seed:editors`,
+            ]),
+        `  pnpm run dev:${scriptName}`,
+        `  pnpm run doctor:${scriptName}`,
+        "",
+        "A second app is a second Workers Builds project. Create one with:",
+        ...settings.map(([label, value]) => `  ${`${label}:`.padEnd(width + 2)}${value}`),
+        "Both projects deploy from the same release tag, through the one",
+        ".github/workflows/release.yml `astroid generate` writes at the root.",
+        ...(intoNotes.length ? ["", ...intoNotes.map((note) => `Note: ${note}`)] : []),
+        "",
+      ].join("\n"),
+    );
+    return;
+  }
+
   const rel = dir === process.cwd() ? "." : basename(dir);
+  if (app) {
+    process.stdout.write(
+      [
+        "",
+        `✓ Scaffolded ${name} → ${rel} (an app with no editor)`,
+        "",
+        "Next steps:",
+        `  cd ${rel}`,
+        "  pnpm install",
+        ...(authMigrationOk || !config.portal?.enabled
+          ? []
+          : [
+              "  # generate the portal's Better Auth migration:",
+              `  pnpm exec louise gen-auth-schema --out ${portalMigration}`,
+            ]),
+        "  # create the Cloudflare resources wrangler.jsonc names, filling in their ids.",
+        "  # To share another app's database instead, bind it by id and set",
+        "  # `deploy: { migrations: false }` in astroid.config.ts.",
+        "  pnpm exec astroid provision",
+        "  # develop / ship:",
+        "  pnpm dev            # astroid dev (regenerates, then astro dev)",
+        "  pnpm run doctor     # validate config + bindings (`run` is required)",
+        "  pnpm exec astroid ship production",
+        "",
+      ].join("\n"),
+    );
+    return;
+  }
   process.stdout.write(
     [
       "",

package/into.mjs

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `create-astroid --into <path>`: one app scaffolded into a repository that
+// already holds one. The pure half of it, a module of its own so the test suite
+// can import it without running the scaffolder: which workspace globs cover a
+// path, how to add one, the root scripts, and the Workers Builds settings.
+//
+// Every edit here is text, not a parse and re-serialize. These are files a
+// person owns, with their comments and their formatting, and an edit that
+// rewrote the whole file to add one line would bury that line in a diff nobody
+// reads.
+
+/**
+ * Template-relative paths that belong to the repository rather than an app.
+ * `--into` never writes them into the app; each is written at the root only
+ * when the root has none.
+ */
+export const INTO_REPOSITORY_FILES = [
+  "pnpm-workspace.yaml",
+  "_gitignore",
+  "_github/workflows/ci.yml",
+  "docs/ARCHITECTURE.md",
+  "docs/DECISIONS.md",
+  "docs/RUNBOOK.md",
+];
+
+/**
+ * Why a path can't be scaffolded into, or null when it can. The path goes into
+ * root scripts and a workspace glob unquoted, so it's held to characters that
+ * need no quoting in either.
+ */
+export function intoPathProblem(path) {
+  if (!path || path === ".")
+    return "--into needs a path inside the repository, such as workers/order";
+  if (path.startsWith("..") || path.startsWith("/")) {
+    return `--into path "${path}" is outside the repository`;
+  }
+  if (!/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(path)) {
+    return `--into path "${path}" may use only letters, digits, ".", "_", "-", and "/"`;
+  }
+  return null;
+}
+
+/** A workspace glob as a regular expression over a POSIX path. */
+function globToRegExp(glob) {
+  const clean = glob.replace(/^\.\//, "").replace(/\/+$/, "");
+  let source = "";
+  for (let i = 0; i < clean.length; i++) {
+    const c = clean[i];
+    if (c === "*" && clean[i + 1] === "*") {
+      source += ".*";
+      i++;
+    } else if (c === "*") source += "[^/]*";
+    else if (c === "?") source += "[^/]";
+    else source += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * The `packages` list of a pnpm-workspace.yaml, or null when it has none. Reads
+ * the two shapes pnpm's own docs use, a block list and a flow list.
+ */
+export function workspacePackages(yaml) {
+  const lines = yaml.split("\n");
+  const at = lines.findIndex((line) => /^packages\s*:/.test(line));
+  if (at === -1) return null;
+  const unquote = (s) => s.trim().replace(/^["']|["']$/g, "");
+  const rest = lines[at]
+    .replace(/^packages\s*:/, "")
+    .replace(/\s+#.*$/, "")
+    .trim();
+  if (rest.startsWith("[")) {
+    return rest
+      .replace(/^\[|\]$/g, "")
+      .split(",")
+      .map(unquote)
+      .filter(Boolean);
+  }
+  const items = [];
+  for (const line of lines.slice(at + 1)) {
+    if (/^\s*(#.*)?$/.test(line)) continue;
+    const item = line.match(/^\s+-\s*(.+?)\s*(#.*)?$/);
+    if (!item) break;
+    items.push(unquote(item[1]));
+  }
+  return items;
+}
+
+/** Whether a workspace's `packages` globs already include `path`. */
+export function workspaceCovers(patterns, path) {
+  const matches = (glob) => globToRegExp(glob).test(path);
+  const included = patterns.filter((p) => !p.startsWith("!")).some(matches);
+  const excluded = patterns.filter((p) => p.startsWith("!")).some((p) => matches(p.slice(1)));
+  return included && !excluded;
+}
+
+/**
+ * The workspace file with `path` added to its `packages`, the same text when
+ * a glob already covers it, or null when the list is in a shape this can't
+ * edit safely (the caller then asks for it by hand).
+ */
+export function addWorkspacePackage(yaml, path) {
+  const patterns = workspacePackages(yaml);
+  if (patterns && workspaceCovers(patterns, path)) return yaml;
+  const lines = yaml.split("\n");
+
+  if (patterns === null) {
+    // No list yet. Insert one before the first top-level key, and before the
+    // comment that introduces that key, so the comment stays with it.
+    let at = lines.findIndex((line) => /^[A-Za-z]/.test(line));
+    if (at === -1) at = lines.length;
+    while (at > 0 && lines[at - 1].startsWith("#")) at--;
+    const block = [
+      "# The workspace. pnpm always includes the root project; each app",
+      "# `create-astroid --into` scaffolds is listed here.",
+      "packages:",
+      `  - ${path}`,
+      "",
+    ];
+    return [...lines.slice(0, at), ...block, ...lines.slice(at)].join("\n");
+  }
+
+  const at = lines.findIndex((line) => /^packages\s*:/.test(line));
+  const rest = lines[at].replace(/^packages\s*:/, "").trim();
+  if (rest.startsWith("[")) {
+    // A flow list with no comment after it is one line to rewrite; anything
+    // fancier is left to a person.
+    if (!/^\[[^\]]*\]$/.test(rest)) return null;
+    const inner = rest.slice(1, -1).trim();
+    lines[at] = `packages: [${inner ? `${inner}, ` : ""}${JSON.stringify(path)}]`;
+    return lines.join("\n");
+  }
+  if (rest && !rest.startsWith("#")) return null;
+
+  // A block list: append after its last item, at its indentation.
+  let last = at;
+  let indent = "  ";
+  for (let i = at + 1; i < lines.length; i++) {
+    if (/^\s*(#.*)?$/.test(lines[i])) continue;
+    const item = lines[i].match(/^(\s+)-/);
+    if (!item) break;
+    last = i;
+    indent = item[1];
+  }
+  lines.splice(last + 1, 0, `${indent}- ${path}`);
+  return lines.join("\n");
+}
+
+/** The name an app's root scripts are namespaced by: its directory's name. */
+export function intoScriptName(path) {
+  return path
+    .split("/")
+    .pop()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-");
+}
+
+/** The root scripts that run one app's commands from the repository root. */
+export function intoRootScripts(name, path) {
+  const inApp = `pnpm --dir ${path}`;
+  return {
+    [`dev:${name}`]: `${inApp} run dev`,
+    [`build:${name}`]: `${inApp} run build`,
+    [`doctor:${name}`]: `${inApp} run doctor`,
+    [`ship:${name}:production`]: `${inApp} exec astroid ship production`,
+    [`ship:${name}:preview`]: `${inApp} exec astroid ship preview`,
+  };
+}
+
+/**
+ * The root package.json's scripts with the app's added, never replacing one
+ * that exists: `skipped` names each that was already taken, so the caller can
+ * say so rather than overwrite someone's script.
+ */
+export function mergeRootScripts(existing, scripts) {
+  const merged = { ...existing };
+  const added = [];
+  const skipped = [];
+  for (const [name, command] of Object.entries(scripts)) {
+    if (name in merged) skipped.push(name);
+    else {
+      merged[name] = command;
+      added.push(name);
+    }
+  }
+  return { scripts: merged, added, skipped };
+}
+
+/**
+ * The settings of the new app's Workers Builds project. A second app is a
+ * second project, building from its own directory and deploying through
+ * `astroid ship`, so the deploy steps stay in the repository.
+ */
+export function workersBuildsSettings(path) {
+  return [
+    ["Root directory", path],
+    ["Build command", "pnpm run build"],
+    ["Deploy command", "pnpm exec astroid ship production"],
+    ["Non-production branch deploy command", "pnpm exec astroid ship preview"],
+    ["Production branch", "deploy/production"],
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astroid",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Scaffold a new Astroid site — an editable, multi-editor Astro app on Cloudflare Workers — in one command.",
   "keywords": [
     "astro",
@@ -23,6 +23,7 @@
   },
   "files": [
     "index.mjs",
+    "into.mjs",
     "template",
     "toolkit-ranges.mjs"
   ],
@@ -32,10 +33,10 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.2",
-    "@louise-toolkit/astro": "^0.5.0",
-    "astroidjs": "0.19.0",
+    "@louise-toolkit/astro": "^0.6.0",
+    "astroidjs": "0.20.0",
     "better-auth": "^1.7.2",
-    "louise-toolkit": "^0.36.0"
+    "louise-toolkit": "^0.37.0"
   },
   "engines": {
     "node": ">=26.0.0"

package/template/_app/README.md

@@ -0,0 +1,62 @@
+# __BRAND_NAME__
+
+An app on Cloudflare Workers with no pages to edit, scaffolded with
+[Astroid](https://docs.astroidjs.org) (Astro + Louise Toolkit) in its
+editor-free shape (`editor: false`).
+
+It has no Louise editor: no sign-in for editors, no content tables, no media
+library. Its settings, if it reads any, belong to a site that has an editor, and
+that site stays the only place they're edited. What Astroid still generates
+here is the rate limiter, the Content-Security-Policy, the security headers,
+the public status route, and whatever modules the config switches on: a
+customer portal, an installable app (PWA), or commerce.
+
+The whole shape lives in one typed config, [`astroid.config.ts`](./astroid.config.ts).
+`src/schema.ts`, `src/worker.ts`, and `src/middleware.ts` are **generated** from
+it (they carry a "do not hand-edit" banner). Run `pnpm generate` after any
+config change, or use `pnpm dev` and `pnpm build`, which regenerate first.
+
+## Develop
+
+```sh
+pnpm install
+cp .env.example .dev.vars   # local secrets for `astro dev`
+pnpm dev                    # astroid dev: regenerate, then astro dev
+```
+
+## The API
+
+The web app is the first client of a versioned JSON API under `/api/v1`
+(`src/pages/api/v1/`). A native client later calls the same routes, so each
+one answers JSON, reads its input from the body or the URL, and needs no
+browser-only header. The middleware rate-limits every POST under `/api/v1`.
+
+## Deploy
+
+Astroid wrote `wrangler.jsonc` with placeholder binding ids:
+
+```sh
+pnpm astroid provision   # create the D1 database and the RL namespace, filling in their ids
+pnpm run doctor          # validate config, bindings, and generated-file freshness
+pnpm astroid ship production
+```
+
+### Sharing another app's database
+
+To read tables another app owns, such as its `site_settings`, bind its D1
+database by id in `wrangler.jsonc` and set `deploy: { migrations: false }` in
+`astroid.config.ts`. One app owns a database's schema: this one then applies no
+migrations, and an additive migration in the other app ships in a release
+before this app's code reads it.
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `astroid.config.ts` | The one typed config. |
+| `src/schema.ts` · `src/worker.ts` · `src/middleware.ts` | **Generated**—don't hand-edit. |
+| `src/schema.site.ts` | This app's own Drizzle tables, if it has any. |
+| `wrangler.jsonc` | Yours to edit—real binding ids, routes, secrets. |
+| `src/pages/api/v1/` | The versioned JSON API. |
+| `src/pages/` · `src/components/` · `src/layouts/` | Your Astro app. |
+| `docs/` | ARCHITECTURE · RUNBOOK · DECISIONS—stubs to fill in as you go. |

package/template/_app/_env.example

@@ -0,0 +1,12 @@
+# Local dev secrets (wrangler reads .dev.vars; copy this there for `astro dev`).
+# In production these are set with `wrangler secret put`, NOT committed.
+#
+# Astroid's convention: an unprovisioned secret leaves its feature DORMANT, never
+# broken. A secret that is empty, or still holds the DUMMY_REPLACE_ME sentinel,
+# reads as "not configured", so a fresh clone boots and runs with no external
+# accounts at all. Replace a value to switch that feature on.
+#
+# This app has no editor, so it needs no editor sign-in secrets. Anything below
+# belongs to a module your config switched on.
+__ASTROID_APP_SECRETS__
+__ASTROID_MODULE_SECRETS__

package/template/_app/astro.config.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+import cloudflare from "@astrojs/cloudflare";
+import { cacheCloudflare } from "@astrojs/cloudflare/cache";
+import solid from "@astrojs/solid-js";
+import tailwindcss from "@tailwindcss/vite";
+import { ASTROID_VITE_BUILD, astroidSecurity } from "astroidjs/astro";
+import { defineConfig } from "astro/config";
+import astroidConfig from "./astroid.config.ts";
+
+// SSR (`output: server`) because an app answers per request: its JSON API under
+// /api/v1, and pages that read live data. Solid islands for the interactive UI.
+// Tailwind v4 + daisyUI drive the theme (src/styles/site.css). Cloudflare
+// *bindings* are read via `import { env } from "cloudflare:workers"` (typed in
+// src/env.d.ts), so there is no astro:env schema here.
+export default defineConfig({
+  site: "__SITE_URL__",
+  output: "server",
+  adapter: cloudflare(),
+  integrations: [solid()],
+  vite: {
+    plugins: [tailwindcss()],
+    build: { ...ASTROID_VITE_BUILD },
+  },
+  // Route caching (ADR 0004). This provider is what turns `Astro.cache.set(...)`
+  // into a `Cloudflare-CDN-Cache-Control` header, which the generated worker's
+  // `withEdgeCache` layer reads as its "store this" signal and then strips, so
+  // Cloudflare's own cookie-blind edge cache never sees it. Nothing is cached
+  // unless a route opts in, and a route that reads a signed-in customer never
+  // should.
+  cache: { provider: cacheCloudflare() },
+  // Content-Security-Policy, composed by Astroid from your config: the origins
+  // your modules need (a commerce provider's card SDK) plus the hash of Solid's
+  // hydration bootstrap. Astro owns `script-src`, so avoid is:inline and
+  // define:vars scripts, which can't be hashed and would be blocked. Need
+  // another origin? Add it to `security.cspOrigins` in astroid.config.ts.
+  security: astroidSecurity(astroidConfig),
+});

package/template/_app/src/env.d.ts

@@ -0,0 +1,33 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+/// <reference types="@cloudflare/workers-types" />
+
+// The Cloudflare bindings this app's Worker exposes (wrangler.jsonc), read via
+// `import { env } from "cloudflare:workers"`. An app with no editor binds only
+// what it uses. Add a binding here when you add one to wrangler.jsonc (a KV
+// namespace for a cache, a Queue, a Durable Object).
+type CloudflareEnv = {
+  /** D1: this app's own tables, or the database of the app that owns the schema. */
+  DB: D1Database;
+  /** The app's public origin, declared in wrangler.jsonc `vars`. */
+  SITE_URL: string;
+  /** KV: the security rate limiter. */
+  RL: KVNamespace;
+  /** Static assets (bound by the @astrojs/cloudflare adapter). */
+  ASSETS: Fetcher;__ASTROID_ENV_BINDINGS__
+};
+
+// `env` from `cloudflare:workers` is typed as the augmentable `Cloudflare.Env`.
+declare namespace Cloudflare {
+  interface Env extends CloudflareEnv {}
+}
+
+// Middleware sets these; bindings themselves come from `cloudflare:workers`.
+declare namespace App {
+  interface Locals {
+    /** Always null: this app has no editor, so no request resolves to one. */
+    editor: null;
+    /** Always false, for the same reason. The shared middleware still sets it. */
+    editMode: boolean;__ASTROID_PORTAL_LOCALS__
+  }
+}

package/template/_app/src/layouts/App.astro

@@ -0,0 +1,49 @@
+---
+// The base HTML shell. This app has no editor, so there's no settings row it
+// owns and no edit mode: the head comes from astroid.config.ts, and a page
+// overrides the title or description through props.
+//
+// Reading another app's settings (opening hours, a tagline) is a query against
+// its table: import `siteSettings` from "louise-toolkit/db" where you need it.
+import Credit from "astroidjs/components/Credit.astro";
+import Seo from "astroidjs/components/Seo.astro";
+import astroidConfig from "../../astroid.config.js";
+import "../styles/site.css";
+
+interface Props {
+  title?: string;
+  description?: string;
+  /** Keep this page out of search indexes (account, order status). */
+  noindex?: boolean;
+}
+
+const { title, description, noindex } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en" data-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <Seo
+      settings={{ siteName: astroidConfig.theme.name }}
+      title={title}
+      description={description}
+      noindex={noindex}
+      titleTemplate={astroidConfig.seo?.titleTemplate}
+      twitterHandle={astroidConfig.seo?.twitterHandle}
+      locale={astroidConfig.seo?.locale}
+    />
+  </head>
+  <body class="min-h-screen bg-base-100 text-base-content">
+    <slot />
+    {
+      /* The agency credit, when astroid.config.ts sets `credit`. */
+      astroidConfig.credit && (
+        <footer class="mx-auto flex max-w-6xl justify-center px-6 py-8">
+          <Credit config={astroidConfig} />
+        </footer>
+      )
+    }
+  </body>
+</html>

package/template/_app/src/pages/api/v1/index.ts

@@ -0,0 +1,22 @@
+// GET /api/v1—the root of this app's versioned JSON API.
+//
+// Every route the app's clients call lives under /api/v1: the web app first,
+// and a native client later against the same routes. So each one answers JSON,
+// reads its input from the body or the URL (never an HTML form post), and
+// needs no browser-only header. A breaking change is a new prefix, /api/v2,
+// beside this one, because a native client on a customer's phone updates on
+// its own schedule.
+//
+// The generated middleware rate-limits every POST under /api/v1 per client IP.
+// Add a tighter rule for one route with `security.rateRules` in
+// astroid.config.ts.
+import type { APIRoute } from "astro";
+import astroidConfig from "../../../../astroid.config.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = () =>
+  Response.json(
+    { name: astroidConfig.theme.name, version: "v1" },
+    { headers: { "cache-control": "no-store" } },
+  );

package/template/_app/src/pages/index.astro

@@ -0,0 +1,18 @@
+---
+// The app's first screen. Replace it with yours. It reads its data from the
+// same versioned JSON API a native client would call (src/pages/api/v1/), so
+// the web app stays that API's first client rather than a special case.
+import App from "../layouts/App.astro";
+
+export const prerender = false;
+---
+
+<App>
+  <main class="mx-auto flex min-h-screen max-w-xl flex-col justify-center gap-4 px-6 py-16">
+    <h1 class="text-4xl font-bold">__BRAND_NAME__</h1>
+    <p class="text-base-content/70">
+      This app has no pages to edit. Build its screens here, and its API under
+      <code>/api/v1</code>.
+    </p>
+  </main>
+</App>

package/template/_app/src/pages/sitemap.xml.ts

@@ -0,0 +1,24 @@
+// sitemap.xml—the app's public screens. Scaffolded once and yours to edit: add
+// each screen a search engine should find to `entries`.
+//
+// It doesn't read a `pages` table, even when this app shares a database with a
+// site that has one: those pages are served from the site's origin, not this
+// app's. `astroidSitemapXml` drops anything matching the config's noindex
+// prefixes, so this file and robots.txt can never disagree.
+import type { APIRoute } from "astro";
+import { astroidSitemapXml, type SitemapEntry } from "astroidjs";
+import astroidConfig from "../../astroid.config.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = (context) => {
+  const origin = new URL(context.request.url).origin;
+  const entries: SitemapEntry[] = [{ path: "/" }];
+
+  return new Response(astroidSitemapXml(astroidConfig, entries, { origin }), {
+    headers: {
+      "content-type": "application/xml; charset=utf-8",
+      "cache-control": "public, max-age=3600",
+    },
+  });
+};

package/template/src/layouts/Site.astro

@@ -6,6 +6,7 @@
 // description, and OG image, and a page overrides any of them via props.
 // <StructuredData> emits the schema.org graph (business + WebSite), with the
 // business `@type` chosen from your archetype.
+import Credit from "astroidjs/components/Credit.astro";
 import Seo from "astroidjs/components/Seo.astro";
 import StructuredData from "astroidjs/components/StructuredData.astro";
 import { env } from "cloudflare:workers";
@@ -96,6 +97,15 @@ const settings = {
   </head>
   <body class="min-h-screen bg-base-100 text-base-content" data-edit-mode={editMode ? "" : undefined}>
     <slot />
+    {
+      /* The agency credit, when astroid.config.ts sets `credit`. A site with
+         its own footer can move <Credit config={astroidConfig} /> into it. */
+      astroidConfig.credit && (
+        <footer class="mx-auto flex max-w-6xl justify-center px-6 py-8">
+          <Credit config={astroidConfig} />
+        </footer>
+      )
+    }
     <LouiseEdit versionedPageId={versionedPageId} sections={sections} />
     {
       /* Real-visitor Core Web Vitals. A static file from public/, so it is