create-astroid 0.9.2 → 0.11.0

package/index.mjs

@@ -4,7 +4,7 @@
 // `create-astroid`—scaffold a new Astroid site in one command:
 //
 //   pnpm create astroid@latest my-site
-//   pnpm create astroid@latest my-site --key coracle --name "Coracle Coffee" --color "#1f6f78" --host coracle.coffee
+//   pnpm create astroid@latest my-site --key example --name "Example Organization" --color "#5b4bff" --host example.com
 //
 // It writes the floor: the `defineAstroid` config, the generated
 // schema/worker/middleware trio + wrangler.jsonc (via astroidjs), the Better Auth
@@ -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(
     [
       "",