@viglet/create-shio-app 2026.3.2

package/src/emit.mjs

@@ -0,0 +1,292 @@
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * SH119 — generate the `nextjs-starter` blueprint package from this package's
+ * `template/` tree, so there is one starter with two ways to get it: offline
+ * (`npm create shio-app`, which copies the tree) and from an instance
+ * (`shio init --blueprint nextjs-starter`, which downloads the package's `files`).
+ *
+ * SH156 — and generate the section-vocabulary packages' front-end half the same way, as
+ * **the same tree plus an overlay**. That is the answer to "how do packages share a tree
+ * instead of each carrying a copy": they each carry a copy and *nobody writes one*. A
+ * hand-maintained second starter would drift within a release; a generated one cannot,
+ * because `test/emit.test.mjs` fails the build the moment it disagrees with its sources.
+ *
+ * Why generate rather than share. A running Shio reads blueprints off the classpath
+ * and cannot run a JS build, so the bytes have to exist under
+ * `shio-app/src/main/resources/blueprints/`. That is a second copy by necessity, which
+ * is precisely why the drift test exists — the same discipline `shio-sections`' `emit`
+ * uses for post-type defs.
+ *
+ * Run: `pnpm -C create-shio-app run emit`
+ */
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { rangeFor, unpublished } from "./published.mjs";
+import { readTemplateFiles } from "./scaffold.mjs";
+
+/** Where the blueprint packages live, relative to this file. */
+const BLUEPRINTS = fileURLToPath(
+  new URL("../../shio-app/src/main/resources/blueprints/", import.meta.url)
+);
+
+/**
+ * The section vocabulary's front-end half, authored once (SH156).
+ *
+ * <p>It lives in `shio-sections` rather than here because the vocabulary owns how it
+ * renders — the same argument that puts its post-type defs in `src/post-types.ts`. This
+ * package owns the *starter*, that one owns the *sections*, and `emit` is where they
+ * meet.</p>
+ */
+const SECTIONS_OVERLAY = fileURLToPath(new URL("../../shio-sections/front-end/", import.meta.url));
+
+/**
+ * A package's own index page, one directory per package (SH216).
+ *
+ * <h2>Why these live here and the section overlay does not</h2>
+ *
+ * <p>The section overlay lives in `shio-sections` because <b>the vocabulary owns how it
+ * renders</b> — the same argument that puts its post-type defs in `src/post-types.ts`. These have
+ * no vocabulary. `blog`, `docs` and `product-catalog` are ordinary posts with an HTML field, and
+ * what each is missing is one page the starter cannot provide because it is about the *model*
+ * rather than about any page: the posts newest first, the documentation tree, the catalogue grid.
+ * That belongs to whoever owns the starter, which is this package.</p>
+ *
+ * <p><b>Not beside the blueprint</b>, which was the tempting answer: `blueprints/<name>/files/` is
+ * the tree `emit` <em>writes</em>, so a source overlay in the same directory would put input and
+ * output in one place and make the drift test compare a thing with itself.</p>
+ */
+const packageOverlay = (name) =>
+  fileURLToPath(new URL(`../overlays/${name}/`, import.meta.url));
+
+/** `@viglet/shio-sections`' own package.json — the version the overlay depends on. */
+const SECTIONS_MANIFEST = fileURLToPath(
+  new URL("../../shio-sections/package.json", import.meta.url)
+);
+
+/**
+ * Every package generated from the starter tree.
+ *
+ * <p>Named explicitly rather than globbed, for the same reason `shio-sections`' target
+ * list is: a package that stops carrying a front end is a decision, and it should look
+ * like one here.</p>
+ *
+ * <p><b>`blog`, `docs` and `product-catalog` carry an index page instead of the section
+ * overlay (SH216).</b> They do not compose sections — their models are ordinary posts with an
+ * HTML field, which the starter's catch-all already renders — so the section tree would ship a
+ * dependency they never import and let three packages claim a front end that renders their pages
+ * no better than the plain starter does. What each was actually missing is one page the starter
+ * cannot provide because it is about the <em>model</em>: a post list at `/blog`, a navigation tree
+ * at `/docs`, a grid at `/products`. Three shapes, which is exactly why it is three overlays and
+ * not one.</p>
+ */
+export const PACKAGES = [
+  { name: "nextjs-starter", overlay: null },
+  { name: "marketing-site", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
+  { name: "landing", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
+  // No `needs`: an index page uses the SDK the starter already depends on. That is the whole
+  // distinction from the section overlay, which brings a vocabulary with it.
+  { name: "blog", overlay: packageOverlay("blog") },
+  { name: "docs", overlay: packageOverlay("docs") },
+  { name: "product-catalog", overlay: packageOverlay("product-catalog") },
+];
+
+/** Where the carried tree lives inside a package. */
+const FILES_SUBDIR = "files";
+
+/** The starter's package directory — kept as a named export for SH119's callers. */
+export const PACKAGE_DIR = join(BLUEPRINTS, "nextjs-starter/");
+
+/**
+ * The manifest's `files` refs for a carried tree.
+ *
+ * <p>`path` is where the file goes in the caller's project; `from` is where its bytes
+ * live in the package. Both are always stated: the tree lives under `files/` so the
+ * package root stays readable (manifest, model, content, tree), and the two names differ
+ * for dotfiles anyway — a leading dot is stripped inside the package, which is the same
+ * dodge the npm template uses for `gitignore` and which the `path` now undoes *in the
+ * format* rather than in each consumer's code.</p>
+ *
+ * @param {Array<{path: string, text: string}>} files
+ */
+export function fileRefs(files) {
+  return files.map((file) => ({ path: file.path, from: sourcePath(file) }));
+}
+
+/** Where a row's bytes are written inside the package. */
+export function sourcePath(file) {
+  return `${FILES_SUBDIR}/${file.path.replace(/^\./, "")}`;
+}
+
+/** Read an overlay directory as the same `{path, text}` rows the template produces. */
+export async function readOverlay(dir) {
+  if (!dir || !existsSync(dir)) return [];
+  const rows = [];
+  for (const rel of await listFiles(dir)) {
+    rows.push({ path: rel, text: await readFile(join(dir, rel), "utf8") });
+  }
+  return rows.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+async function listFiles(dir, prefix = "") {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listFiles(join(dir, entry.name), rel)));
+    } else {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * The tree one package carries: the starter, with the overlay's files replacing or
+ * joining it, and the dependencies the overlay needs added to `package.json`.
+ *
+ * <p>Replace-by-path is what keeps the overlay small. The section-aware catch-all route
+ * is the starter's route plus one branch, so it <em>is</em> `app/[...slug]/page.tsx`
+ * rather than a second route the project would have to be told about.</p>
+ *
+ * @param {Array<{path: string, text: string}>} base    the starter tree
+ * @param {Array<{path: string, text: string}>} overlay files that replace or join it
+ * @param {Record<string, string>} dependencies         added to the project's package.json
+ */
+export function compose(base, overlay, dependencies = {}) {
+  const byPath = new Map(base.map((file) => [file.path, file]));
+  for (const file of overlay) {
+    byPath.set(file.path, file);
+  }
+  if (Object.keys(dependencies).length > 0) {
+    const manifest = byPath.get("package.json");
+    if (!manifest) {
+      throw new Error("emit: the starter tree has no package.json to add dependencies to");
+    }
+    const parsed = JSON.parse(manifest.text);
+    // Sorted, so adding one dependency does not reorder the ones already there and the
+    // generated diff is the change and nothing else (P5).
+    parsed.dependencies = Object.fromEntries(
+      Object.entries({ ...parsed.dependencies, ...dependencies }).sort(([a], [b]) =>
+        a.localeCompare(b)
+      )
+    );
+    byPath.set("package.json", {
+      path: "package.json",
+      text: `${JSON.stringify(parsed, null, 2)}\n`,
+    });
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * The dependency ranges an overlay's `needs` resolve to.
+ *
+ * <h3>The comment that used to be here was exactly backwards (SH446)</h3>
+ *
+ * <p>It read: "read from the workspace rather than written down here, so a release that bumps
+ * `@viglet/shio-sections` cannot leave the generated packages pointing at a version nobody
+ * published." Reading it from the workspace is what <em>guarantees</em> pointing at a version nobody
+ * published — the workspace is the version being <em>built</em>, and it is installable only in the
+ * instant after a release. Measured on `@viglet/shio-client`, whose template range was derived the
+ * same way: `^2026.3.1` against a registry that had `2026.2.1`, so `npm install` in a fresh scaffold
+ * failed `ETARGET` and nothing in the repository noticed, because nothing installs from the
+ * registry.</p>
+ *
+ * <p>So the published range wins when there is one ({@link rangeFor}), and the workspace's is the
+ * fallback for a package that has never been published at all — where no range is correct and
+ * writing *something* at least leaves a project that is right the day the release runs.
+ * {@link unpublishedNeeds} is what reports that state, and `emit` prints it.</p>
+ */
+export async function resolveNeeds(needs) {
+  if (!needs || needs.length === 0) return {};
+  const { version } = JSON.parse(await readFile(SECTIONS_MANIFEST, "utf8"));
+  return Object.fromEntries(needs.map((name) => [name, rangeFor(name) ?? `^${version}`]));
+}
+
+/** The `needs` across every package that name something the registry does not have (SH446). */
+export function unpublishedNeeds() {
+  return unpublished([...new Set(PACKAGES.flatMap((pkg) => pkg.needs ?? []))]);
+}
+
+/** The whole tree one entry of {@link PACKAGES} should carry. */
+export async function filesFor(pkg, base) {
+  const template = base ?? (await readTemplateFiles());
+  if (!pkg.overlay) return template;
+  return compose(template, await readOverlay(pkg.overlay), await resolveNeeds(pkg.needs));
+}
+
+/**
+ * Read a package's manifest with its `files` list replaced by what its tree currently
+ * holds — the shape `emit` would write. Pure, so the drift test can compare it against
+ * what is on disk without touching the filesystem twice.
+ */
+export async function expectedManifest(files, name = "nextjs-starter") {
+  const manifest = JSON.parse(await readFile(join(BLUEPRINTS, name, "blueprint.json"), "utf8"));
+  return { ...manifest, files: fileRefs(files) };
+}
+
+/** The bytes a package should carry, keyed by package-relative path. */
+export function expectedSources(files) {
+  return new Map(files.map((file) => [sourcePath(file), file.text]));
+}
+
+export async function emit({ log = console.log } = {}) {
+  const base = await readTemplateFiles();
+  const emitted = {};
+
+  for (const pkg of PACKAGES) {
+    const dir = join(BLUEPRINTS, pkg.name);
+    if (!existsSync(dir)) {
+      throw new Error(
+        `emit: the ${pkg.name} blueprint package is missing at ${dir}. ` +
+          "The manifest is hand-authored (it declares the params and the promise); only " +
+          "`files` and the carried tree are generated."
+      );
+    }
+    const files = await filesFor(pkg, base);
+
+    // Rewritten wholesale so a file deleted from the template disappears here too — a
+    // stale leftover would be shipped to every project that applies the package.
+    await rm(join(dir, FILES_SUBDIR), { recursive: true, force: true });
+    for (const file of files) {
+      const target = join(dir, sourcePath(file));
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.text, "utf8");
+    }
+
+    const manifest = await expectedManifest(files, pkg.name);
+    await writeFile(join(dir, "blueprint.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+    log(`✓ emitted ${files.length} file(s) into blueprints/${pkg.name}`);
+    emitted[pkg.name] = files.map((file) => file.path);
+  }
+
+  // SH446 — said at the moment the file is written, because the alternative is a stranger's
+  // `npm install` saying it, and by then the scaffold is on their disk and this repository is not.
+  const missing = unpublishedNeeds();
+  if (missing.length) {
+    log(
+      `\n! ${missing.join(" ")} ${missing.length === 1 ? "is" : "are"} NOT on the registry, so the `
+        + `starter${missing.length === 1 ? "" : "s"} carrying the section overlay cannot `
+        + `npm install outside this monorepo.\n`
+        + `  No range fixes it — publish them, then record the range in src/published.mjs.\n`
+        + `  \`shio init\` (no --blueprint) is unaffected: it carries only published packages.\n`,
+    );
+  }
+
+  return { files: emitted["nextjs-starter"], packages: emitted, unpublished: missing };
+}
+
+// `pathToFileURL`, not a hand-built `file://` string: on Windows `process.argv[1]` is
+// `D:\...` while `import.meta.url` is `file:///D:/...`, so the concatenated form never
+// matched and running the script did nothing at all — silently, which is the worst way for
+// a generator to fail.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await emit();
+}

package/src/index.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * create-shio-app — scaffold a Next.js App Router site wired to the Shio CDA.
+ *
+ *   npm create shio-app@latest my-site
+ *   npx create-shio-app my-site --url https://cms.example.com --site <id> --token <key>
+ */
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout, argv, env, exit } from "node:process";
+
+import { scaffold } from "./scaffold.mjs";
+
+function parseArgs(args) {
+  const opts = { yes: false };
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--url") opts.url = args[++i];
+    else if (a === "--site") opts.site = args[++i];
+    else if (a === "--token") opts.token = args[++i];
+    else if (a.startsWith("--url=")) opts.url = a.slice(6);
+    else if (a.startsWith("--site=")) opts.site = a.slice(7);
+    else if (a.startsWith("--token=")) opts.token = a.slice(8);
+    else if (!a.startsWith("-")) positionals.push(a);
+  }
+  opts.projectName = positionals[0];
+  return opts;
+}
+
+async function prompt(rl, question, fallback) {
+  const answer = (await rl.question(`${question}${fallback ? ` (${fallback})` : ""}: `)).trim();
+  return answer || fallback || "";
+}
+
+async function main() {
+  const opts = parseArgs(argv.slice(2));
+  const interactive = stdin.isTTY && !opts.yes;
+
+  let { projectName, url, site, token } = opts;
+
+  if (interactive) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+      projectName = projectName || (await prompt(rl, "Project name", "my-shio-site"));
+      url = url ?? (await prompt(rl, "Shio base URL", "http://localhost:2710"));
+      site = site ?? (await prompt(rl, "Shio site id", ""));
+      token = token ?? (await prompt(rl, "Shio CDA token", ""));
+    } finally {
+      rl.close();
+    }
+  }
+
+  projectName = projectName || "my-shio-site";
+  const targetDir = resolve(process.cwd(), projectName);
+
+  try {
+    const { files } = await scaffold({ targetDir, projectName, url, site, token });
+    const pm = detectPackageManager();
+    stdout.write(
+      `\n✓ Created ${projectName} (${files.length} files) at ${targetDir}\n\n` +
+        `Next steps:\n` +
+        `  cd ${projectName}\n` +
+        `  ${pm.install}\n` +
+        `  ${pm.dev}\n\n` +
+        `Edit .env.local to point at your Shio instance.\n` +
+        `Open http://localhost:3000 — the catch-all route resolves CDA paths to posts.\n`
+    );
+  } catch (err) {
+    stdout.write(`\n✗ ${err.message}\n`);
+    exit(1);
+  }
+}
+
+function detectPackageManager() {
+  const ua = env.npm_config_user_agent || "";
+  if (ua.startsWith("pnpm")) return { install: "pnpm install", dev: "pnpm dev" };
+  if (ua.startsWith("yarn")) return { install: "yarn", dev: "yarn dev" };
+  if (ua.startsWith("bun")) return { install: "bun install", dev: "bun dev" };
+  return { install: "npm install", dev: "npm run dev" };
+}
+
+main();

package/src/published.mjs

@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * SH446 — the versions a scaffold may declare, which are the ones the registry has.
+ *
+ * ## The defect this exists to make impossible
+ *
+ * The replication chain ran green to its last step and the last step did not install. `shio init`
+ * scaffolds the Next.js app that serves a converted site, prints `npm install` as the next command,
+ * and that command failed: `ETARGET — No matching version found for @viglet/shio-client@^2026.3.1`.
+ * The range came from **the workspace**, which is at `2026.3.1` and unpublished, so every release
+ * cycle re-broke every scaffold the moment the version was bumped and nothing said so until a human
+ * ran `npm install` by hand.
+ *
+ * That is worth stating as the end of the chain rather than a packaging chore: `clone`, `propose`,
+ * `convert` and `verify` all reported success, the gate said `ok — 0 error(s)`, and the replica was
+ * viewable by nobody, because the one artifact that would serve it could not be installed outside
+ * this monorepo. P9 failing at the last hop — every cheap textual proof passes and the perception
+ * loop never closes.
+ *
+ * ## Why a declared range and not the workspace's version
+ *
+ * A scaffold is consumed **outside** this repository, so the only version it may name is one the
+ * registry can serve. Reading it from the workspace answers a different question — "what is this
+ * checkout building" — and the two are equal only in the instant after a release. So the ranges
+ * live here, they are **caret** ranges on the latest *published* version, and they therefore pick
+ * up the new one automatically the day it ships: `^2026.2.1` resolves today and resolves to
+ * `2026.3.1` the moment that exists.
+ *
+ * `scaffold-versions.test.mjs` fails the build when the template disagrees with this file, and the
+ * SH448 conformance suite hands the result to **npm**, which is the only thing that can say whether
+ * a range is real.
+ */
+
+/**
+ * Package → the range a scaffold declares, or `null` for "never published".
+ *
+ * A `null` is not a placeholder to fill in with a guess: it means the package has no version on the
+ * registry at all, so **no range is correct** and any scaffold carrying it cannot install. It is
+ * recorded rather than hidden so the failure has a name, and `unpublished()` is what reports it.
+ */
+export const PUBLISHED = {
+  "@viglet/shio-client": "^2026.2.1",
+  // SH156 made these publishable and no release has run, so both answer E404. The section-carrying
+  // starters (`marketing-site`, `landing`) import the vocabulary, so they cannot be made installable
+  // by choosing a different range — only by publishing. Left declared so the gap is a row rather
+  // than an absence.
+  "@viglet/shio-model": null,
+  "@viglet/shio-sections": null,
+};
+
+/** The packages a scaffold would need and the registry does not have. */
+export function unpublished(names = Object.keys(PUBLISHED)) {
+  return names.filter((name) => PUBLISHED[name] === null);
+}
+
+/**
+ * The range to declare for a dependency, or `null` when there is none to declare.
+ *
+ * Falls through for anything not in this table: `next`, `react` and the rest are somebody else's
+ * packages on their own release cycle, and this file has no business having an opinion about them.
+ */
+export function rangeFor(name) {
+  return Object.hasOwn(PUBLISHED, name) ? PUBLISHED[name] : undefined;
+}

package/src/scaffold.mjs

@@ -0,0 +1,185 @@
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * Pure file-operations core for create-shio-app — no prompts, no process.exit,
+ * so it can be unit-tested directly.
+ *
+ * SH119 folded the starter into the blueprint format, which split this module in
+ * two. `readTemplateFiles()` reads the tree that ships in this package; `writeProject()`
+ * writes *a* tree — the local one, or the `files` a blueprint carried — substitutes
+ * parameters and writes `.env.local`. `scaffold()` is the first composed with the second,
+ * and `shio init --blueprint` is the second on its own.
+ *
+ * The template tree here stays the single source of truth: `npm run emit` generates the
+ * `nextjs-starter` blueprint package from it, and `test/emit.test.mjs` fails the build
+ * when the two drift. One starter, two ways to get it.
+ */
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_DIR = fileURLToPath(new URL("../template/", import.meta.url));
+
+/**
+ * npm strips or renames dotfiles in published packages, so the template ships
+ * `gitignore` and every consumer restores the leading dot. Keeping the mapping here
+ * means the blueprint package and the local scaffold cannot disagree about it.
+ */
+const DOTFILE_RENAMES = { gitignore: ".gitignore" };
+
+/**
+ * `{{name}}` and nothing else — character-for-character the rule `ShBlueprintParams`
+ * applies server-side, so a package cannot have a parameter one half substitutes and the
+ * other leaves standing. Narrow enough that JSX (`style={{ color: "#666" }}`) is not a
+ * placeholder, which is what lets a starter tree carry both.
+ */
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_.\-]+)\s*\}\}/g;
+
+/**
+ * Substitute `{{name}}` placeholders from `params`. An unknown placeholder is left
+ * alone rather than blanked: a starter file is source the developer will read, and a
+ * silently emptied string is harder to notice than a visible `{{typo}}`.
+ *
+ * <p>Deliberately the *client's* job for carried files, even though the server
+ * substitutes a blueprint's content. The server never writes a project file (it cannot
+ * see the working tree), and the one parameter a starter needs — the project's own name —
+ * is local identity the server has no business being told.</p>
+ *
+ * @param {string} text
+ * @param {Record<string, string>} params
+ */
+export function substituteParams(text, params) {
+  if (!text || !params) return text;
+  return text.replace(PLACEHOLDER, (match, name) =>
+    Object.hasOwn(params, name) && params[name] != null ? String(params[name]) : match
+  );
+}
+
+/**
+ * The starter tree that ships in this package, as `{ path, text }` rows — the same
+ * shape a blueprint's `files` come back in, so both paths write through one function.
+ *
+ * @returns {Promise<Array<{path: string, text: string}>>}
+ */
+export async function readTemplateFiles() {
+  const rows = [];
+  for (const rel of await listFiles(TEMPLATE_DIR)) {
+    rows.push({
+      path: DOTFILE_RENAMES[rel] ?? rel,
+      text: await readFile(join(TEMPLATE_DIR, rel), "utf8"),
+    });
+  }
+  return rows.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Write a starter tree into `targetDir`.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir  Absolute path of the project directory.
+ * @param {Array<{path: string, text: string}>} options.files The tree to write.
+ * @param {Record<string, string>} [options.params] `{{name}}` substitutions.
+ * @param {object} [options.env] Connection details for `.env.local`; omit to skip it.
+ * @param {boolean} [options.force] Overwrite existing files instead of skipping them.
+ * @param {boolean} [options.requireEmpty] Refuse a non-empty target (the `create` default).
+ * @returns {Promise<{targetDir: string, files: string[], skipped: string[]}>}
+ */
+export async function writeProject({
+  targetDir,
+  files,
+  params = {},
+  env,
+  force = false,
+  requireEmpty = false,
+}) {
+  if (!targetDir) throw new Error("writeProject: targetDir is required");
+  if (!Array.isArray(files) || files.length === 0) {
+    throw new Error("writeProject: files is required and must not be empty");
+  }
+
+  if (requireEmpty && existsSync(targetDir)) {
+    const entries = await readdir(targetDir);
+    if (entries.length > 0) {
+      throw new Error(`Target directory is not empty: ${targetDir}`);
+    }
+  }
+  await mkdir(targetDir, { recursive: true });
+
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    const target = join(targetDir, file.path);
+    if (!force && existsSync(target)) {
+      // A starter written over a project somebody has since edited is the one
+      // irreversible thing this module could do (P7), so it is opt-in.
+      skipped.push(file.path);
+      continue;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, substituteParams(file.text, params), "utf8");
+    written.push(file.path);
+  }
+
+  if (env) {
+    await writeFile(join(targetDir, ".env.local"), envFile(env), "utf8");
+    written.push(".env.local");
+  }
+  return { targetDir, files: written.sort(), skipped: skipped.sort() };
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.targetDir   Absolute path of the project directory to create.
+ * @param {string} options.projectName Package name written into the generated package.json.
+ * @param {string} [options.url]       Shio base URL → SHIO_URL.
+ * @param {string} [options.site]      Shio site id → SHIO_SITE_ID.
+ * @param {string} [options.token]     CDA token → SHIO_CDA_TOKEN.
+ * @returns {Promise<{targetDir: string, files: string[]}>}
+ */
+export async function scaffold({ targetDir, projectName, url, site, token }) {
+  if (!targetDir) throw new Error("scaffold: targetDir is required");
+  if (!projectName) throw new Error("scaffold: projectName is required");
+
+  const { files } = await writeProject({
+    targetDir,
+    files: await readTemplateFiles(),
+    params: { projectName },
+    env: { url, site, token },
+    requireEmpty: true,
+  });
+  return { targetDir, files };
+}
+
+export { TEMPLATE_DIR, DOTFILE_RENAMES };
+
+/**
+ * `.env.local`. The preview / webhook keys (SH9) are optional and start empty — see
+ * `.env.example`. Never carried by a blueprint: it holds a token, and a token has no
+ * business making a round trip through the CMS to get back to the machine that typed it.
+ */
+function envFile({ url, site, token } = {}) {
+  return (
+    `SHIO_URL=${url ?? "http://localhost:2710"}\n` +
+    `SHIO_SITE_ID=${site ?? ""}\n` +
+    `SHIO_CDA_TOKEN=${token ?? ""}\n` +
+    `SHIO_PREVIEW_TOKEN=\n` +
+    `SHIO_PREVIEW_SECRET=\n` +
+    `SHIO_WEBHOOK_SECRET=\n`
+  );
+}
+
+async function listFiles(dir, prefix = "") {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listFiles(join(dir, entry.name), rel)));
+    } else {
+      out.push(rel);
+    }
+  }
+  return out;
+}

package/template/.env.example

@@ -0,0 +1,15 @@
+# Shio Content Delivery API connection
+SHIO_URL=http://localhost:2710
+SHIO_SITE_ID=
+# PROD-env CDA token (serves PUBLISHED content)
+SHIO_CDA_TOKEN=
+
+# --- Optional: draft preview (SH9) ---
+# PREVIEW-env CDA token (serves draft-preferred content). Leave empty to disable.
+SHIO_PREVIEW_TOKEN=
+# Secret that gates the /api/preview entry point.
+SHIO_PREVIEW_SECRET=
+
+# --- Optional: on-demand revalidation (SH9) ---
+# Shared secret the publish webhook signs its body with (HMAC-SHA256).
+SHIO_WEBHOOK_SECRET=