create-zerodirs 0.1.0

package/dist/core/dataset.js

@@ -0,0 +1,88 @@
+/**
+ * Seed datasets — the taxonomy and identity a generated project starts from.
+ *
+ * Every dataset under `seed/datasets/<name>/` already declares what kind of
+ * directory it is (`meta.json`) and what its categories and tags are
+ * (`categories.json`, `tags.json`). The CLI reads all of that instead of asking
+ * the buyer to retype it: `kind: 'business'` is what turns
+ * `seo.jsonLd.listing` into `'localBusiness'`, which is what makes the built
+ * pages emit LocalBusiness structured data.
+ *
+ * Everything above `readDataset()` is pure so the mapping can be unit-tested
+ * without a template on disk.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where datasets live inside a template. */
+export const DATASETS_DIR = 'seed/datasets';
+/**
+ * `site.kind` -> `seo.jsonLd.listing`, mirroring `JSONLD_BY_KIND` in
+ * `src/config/defaults.ts`. The starter applies the same fallback, but the CLI
+ * writes the value explicitly: a config that says `localBusiness` out loud is
+ * one the buyer can find and change.
+ */
+export const JSONLD_BY_KIND = {
+    software: 'software',
+    service: 'organization',
+    business: 'localBusiness',
+};
+/** `site.kind` -> default `routes.listingBase` (design.md §11.1 step 3). */
+export const LISTING_BASE_BY_KIND = {
+    software: 'tools',
+    service: 'services',
+    business: 'places',
+};
+/** `site.kind` -> default `routes.listingNoun`. */
+export const LISTING_NOUN_BY_KIND = {
+    software: { singular: 'tool', plural: 'tools' },
+    service: { singular: 'service', plural: 'services' },
+    business: { singular: 'place', plural: 'places' },
+};
+/**
+ * What a dataset says about the directory it describes. Pure.
+ *
+ * `meta.json` wins over every default, and the per-kind defaults only fill the
+ * gaps, so a dataset that declares nothing but `kind` still produces a coherent
+ * set of routes.
+ */
+export function datasetIdentity(meta) {
+    const kind = meta.kind ?? 'software';
+    return {
+        kind,
+        listingBase: meta.listingBase ?? LISTING_BASE_BY_KIND[kind],
+        listingNoun: meta.listingNoun ?? LISTING_NOUN_BY_KIND[kind],
+        jsonLd: meta.jsonLd ?? JSONLD_BY_KIND[kind],
+    };
+}
+/** Dataset directory names inside a template, sorted. `[]` when there are none. */
+export function listDatasets(templateDir) {
+    const dir = join(templateDir, DATASETS_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+function readJson(path, fallback) {
+    if (!existsSync(path))
+        return fallback;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** Reads `meta.json` + `categories.json` + `tags.json` for one dataset. Throws when it is not there. */
+export function readDataset(templateDir, name) {
+    const dir = join(templateDir, DATASETS_DIR, name);
+    if (!existsSync(dir)) {
+        const available = listDatasets(templateDir);
+        throw new Error(`unknown dataset "${name}"\n` +
+            (available.length ? `available in ${DATASETS_DIR}: ${available.join(', ')}` : `${DATASETS_DIR} has no datasets`));
+    }
+    const meta = readJson(join(dir, 'meta.json'), {});
+    const categories = readJson(join(dir, 'categories.json'), []);
+    const tags = readJson(join(dir, 'tags.json'), []);
+    if (categories.length === 0)
+        throw new Error(`dataset "${name}" has no categories.json entries — site.config.ts needs at least one category`);
+    const listingsDir = join(dir, 'listings');
+    const listingCount = existsSync(listingsDir) ? readdirSync(listingsDir).filter((f) => f.endsWith('.md')).length : 0;
+    return { name, dir, meta, categories, tags, listingCount };
+}

package/dist/core/env-files.js

@@ -0,0 +1,45 @@
+/**
+ * `.dev.vars` and `.env`, generated from the template's own `*.example` files.
+ *
+ * Neither file is written from a hard-coded key list. `wrangler types` derives
+ * the `Env` type from `.dev.vars`, so §11.6 requires the key set to equal
+ * `.dev.vars.example` exactly — a CLI with its own list would drift from the
+ * template the first time a milestone adds a secret. Reading the example keeps
+ * them equal by construction, and keeps every comment the template wrote to
+ * explain what each key is for.
+ *
+ * Both functions are pure. `randomSecret()` is the only impure thing here, and
+ * the values it produces are written to the project and never printed.
+ */
+import { randomBytes } from 'node:crypto';
+/** 32 random bytes, base64url — the shape `.dev.vars.example` documents for ADMIN_SECRET / TOKEN_SECRET. */
+export function randomSecret() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Rewrites a `KEY=value` example file: every key listed in `values` gets that
+ * value, and comments, blank lines and key order survive untouched.
+ */
+export function renderEnvFile(example, values, options = {}) {
+    const blankUnlisted = options.blankUnlisted ?? false;
+    const lines = example.split('\n').map((line) => {
+        const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
+        if (!match)
+            return line;
+        const key = match[1];
+        if (key in values)
+            return `${key}=${values[key]}`;
+        return blankUnlisted ? `${key}=` : line;
+    });
+    return lines.join('\n');
+}
+/** The keys a `KEY=value` file declares, in order. */
+export function envKeys(example) {
+    const keys = [];
+    for (const line of example.split('\n')) {
+        const match = /^([A-Z][A-Z0-9_]*)=/.exec(line);
+        if (match?.[1])
+            keys.push(match[1]);
+    }
+    return keys;
+}

package/dist/core/exec.js

@@ -0,0 +1,47 @@
+/**
+ * Running other people's commands.
+ *
+ * Every external call goes through here so there is one place to look for what
+ * this CLI is capable of executing. It never runs a command that signs anyone
+ * in, uploads a secret, deploys, or touches a remote database: those are
+ * printed into `SETUP.md` for the buyer to run deliberately.
+ *
+ * Failures are values, not exceptions. A failed `pnpm install` should leave a
+ * complete project on disk and a line in the summary, not a half-written
+ * directory and a stack trace.
+ */
+import { execa } from 'execa';
+export async function run(command, args, options) {
+    try {
+        const result = await execa(command, args, {
+            cwd: options.cwd,
+            stdio: options.stdio === 'inherit' ? 'inherit' : 'pipe',
+            env: options.env,
+            timeout: options.timeout,
+            reject: false,
+        });
+        const stdout = String(result.stdout ?? '');
+        const stderr = String(result.stderr ?? '');
+        return {
+            ok: result.exitCode === 0,
+            stdout,
+            stderr,
+            message: firstLine(stderr) || firstLine(stdout) || `${command} exited ${String(result.exitCode)}`,
+            exitCode: result.exitCode,
+        };
+    }
+    catch (error) {
+        const message = error.message ?? String(error);
+        return { ok: false, stdout: '', stderr: message, message: firstLine(message), exitCode: undefined };
+    }
+}
+function firstLine(text) {
+    return (text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('▲'))[0] ?? '');
+}
+/** `npx wrangler …` — wrangler is never installed globally, and never `-g`. */
+export function wranglerArgs(args) {
+    return { command: 'npx', args: ['--yes', 'wrangler', ...args] };
+}

package/dist/core/files.js

@@ -0,0 +1,151 @@
+/**
+ * Filesystem work: copying a template into the project, and loading the
+ * dataset's own content into `src/content` and `public/logos`.
+ *
+ * Copy by exclusion, never by allowlist. An allowlist silently drops whatever
+ * the template gains next — the same reasoning `scripts/dist-starter.ts` gives
+ * for its denylist, and the same list, because the two are copying the same
+ * tree for the same reason.
+ *
+ * The content load mirrors `scripts/content.ts use <dataset> --yes` exactly, so
+ * a generated project passes its own `pnpm content:check <dataset>`. It is done
+ * here rather than by shelling out to that script because it has to work before
+ * `node_modules` exists.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Build output, dependency trees, audit artifacts, and the free edition's
+ * replacement files (which describe a build the buyer does not have).
+ * Matched as an exact relative path or as a `<entry>/` prefix.
+ */
+export const DENY_PATHS = [
+    'node_modules',
+    'dist',
+    '.astro',
+    '.wrangler',
+    '.git',
+    'seed/.out',
+    '.claude/skills',
+    '.lighthouseci',
+    'test-results',
+    'playwright-report',
+    'coverage',
+    'AGENTS.free.md',
+    'README.free.md',
+    'LICENSE.free',
+    'wrangler.free.jsonc',
+    // Never copy a live `.dev.vars` / `.env` out of somebody's working tree.
+    '.dev.vars',
+    '.env',
+    'SETUP.md',
+];
+/** Junk that can appear at any depth. */
+export const DENY_NAMES = new Set(['node_modules', '.DS_Store', '.git']);
+export function isDenied(relativePath, name) {
+    if (DENY_NAMES.has(name))
+        return true;
+    return DENY_PATHS.some((denied) => relativePath === denied || relativePath.startsWith(`${denied}/`));
+}
+/** Recursive copy honouring the denylist. Symlinks are resolved to their target's content. */
+export function copyTemplate(from, to) {
+    const result = { files: 0, skipped: [] };
+    walk('');
+    return result;
+    function walk(relative) {
+        const source = relative ? join(from, relative) : from;
+        for (const entry of readdirSync(source, { withFileTypes: true })) {
+            const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (isDenied(childRelative, entry.name)) {
+                if (!relative)
+                    result.skipped.push(entry.name);
+                continue;
+            }
+            const target = join(to, childRelative);
+            if (entry.isDirectory()) {
+                mkdirSync(target, { recursive: true });
+                walk(childRelative);
+                continue;
+            }
+            if (entry.isSymbolicLink() && !existsSync(join(source, entry.name)))
+                continue;
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(join(source, entry.name), target);
+            result.files += 1;
+        }
+    }
+}
+/** Every file under `dir` as paths relative to it, sorted. `[]` when `dir` is missing. */
+export function listFiles(dir, prefix = '') {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.DS_Store')
+            continue;
+        const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...listFiles(join(dir, entry.name), name));
+        else
+            out.push(name);
+    }
+    return out.sort();
+}
+/** True when the path does not exist, or is a directory with nothing in it. */
+export function isEmptyDir(path) {
+    if (!existsSync(path))
+        return true;
+    if (!statSync(path).isDirectory())
+        return false;
+    return readdirSync(path).filter((name) => name !== '.DS_Store').length === 0;
+}
+function clearDir(dir, options = {}) {
+    const { keep = [], match = () => true } = options;
+    mkdirSync(dir, { recursive: true });
+    for (const file of listFiles(dir)) {
+        if (keep.includes(file) || !match(file))
+            continue;
+        rmSync(join(dir, file), { force: true });
+    }
+}
+function copyDir(from, to) {
+    mkdirSync(to, { recursive: true });
+    const files = listFiles(from);
+    for (const file of files) {
+        const target = join(to, file);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(from, file), target);
+    }
+    return files.length;
+}
+/** `scripts/content.ts` keeps these: they belong to the starter, not to a dataset. */
+const STARTER_BLOG_FILES = ['unpublished-draft.md'];
+/**
+ * Loads `seed/datasets/<name>/{listings,blog,logos}` into `src/content` and
+ * `public/logos`, replacing whatever the template shipped.
+ *
+ * Without this the project would still carry the template's own demo content —
+ * whose categories belong to a different dataset, which the content loader
+ * rejects at build time with an unknown-category error.
+ */
+export function loadDatasetContent(projectDir, datasetDir) {
+    const pairs = [
+        [join(datasetDir, 'listings'), join(projectDir, 'src/content/listings')],
+        [join(datasetDir, 'blog'), join(projectDir, 'src/content/blog')],
+        [join(datasetDir, 'logos'), join(projectDir, 'public/logos')],
+    ];
+    for (const [source] of pairs) {
+        if (!existsSync(source))
+            throw new Error(`dataset is incomplete: ${source} does not exist`);
+    }
+    clearDir(join(projectDir, 'src/content/listings'), { match: (f) => f.endsWith('.md') });
+    clearDir(join(projectDir, 'src/content/blog'), { keep: STARTER_BLOG_FILES, match: (f) => f.endsWith('.md') });
+    clearDir(join(projectDir, 'public/logos'));
+    const [listings, blog, logos] = pairs.map(([source, target]) => copyDir(source, target));
+    return { listings, blog, logos };
+}
+/** Writes a file, creating parents. */
+export function write(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents, 'utf8');
+}

package/dist/core/setup-md.js

@@ -0,0 +1,118 @@
+const WRANGLER_AUTH_DOCS = 'https://developers.cloudflare.com/workers/wrangler/commands/#auth';
+const WORKERS_BUILDS_DOCS = 'https://developers.cloudflare.com/workers/ci-cd/builds/';
+const D1_TOKEN_DOCS = 'https://developers.cloudflare.com/d1/platform/client-api/';
+const R2_DOMAIN_DOCS = 'https://developers.cloudflare.com/r2/buckets/public-buckets/#custom-domains';
+const STRIPE_EVENTS = ['checkout.session.completed', 'checkout.session.async_payment_succeeded'];
+/** The host used in example URLs before the buyer has a domain. */
+function hostOf(plan) {
+    return plan.siteUrl.replace(/^https:\/\//, '');
+}
+export function renderSetupMd(context) {
+    const { plan } = context;
+    const run = context.runPrefix;
+    const pro = plan.answers.edition === 'pro';
+    const host = hostOf(plan);
+    const hasDomain = Boolean(plan.answers.domain);
+    const nouns = plan.identity.listingNoun.plural;
+    const sections = [];
+    sections.push(`# Setup — ${plan.siteConfig.site.name}`, '', `Everything \`create-zerodirs\` did **not** do, in the order it is worth doing. Delete this file when you are through it.`, '', '## What you have already', '', `- \`site.config.ts\` written from your answers: ${plan.siteConfig.categories.length} categories, ${plan.siteConfig.tags.length} tags, \`site.kind: '${plan.identity.kind}'\`, \`seo.jsonLd.listing: '${plan.identity.jsonLd}'\`.`, `- ${context.datasetListings} ${nouns} from the \`${context.dataset}\` sample dataset in \`src/content/listings/\`, with their blog posts and logos. Sample data — replace it before you launch (\`${run} content:reset --yes\` clears it down to one example per category).`, `- Template copied from ${context.templateSource}.`, pro ? '- `.dev.vars` with a freshly generated `ADMIN_SECRET` and `TOKEN_SECRET` (32 random bytes each) and empty placeholders for the rest.' : null, '- `.env` with `LISTINGS_SOURCE=files`.', context.installed ? '- Dependencies installed.' : null, '', '## 1. Run it', '', '```sh', context.installed ? `# dependencies are already installed` : context.installCommand, `${run} dev            # http://localhost:4321`, `${run} check          # config + types`, `${run} build          # production build`, '```', '');
+    sections.push('## 2. Make it yours', '', `- \`public/favicon.svg\` is the placeholder mark, and it is \`site.logo\`, so it is in the header of every page.`, `- \`public/og-default.png\` is the social-share fallback. Fix \`site.name\`/\`site.tagline\` first, then \`${run} og:default\`.`, '- `src/pages/about.astro` describes an editorial policy. Make it describe yours.', `- \`site.config.ts\` › \`site.social\` and \`seo.twitterHandle\` are unset; add them when you have the accounts.`, hasDomain ? null : '- `site.url` is `https://example.com`. Set your real domain — it is baked into canonicals, the sitemap, RSS and the OG images at **build** time.', '');
+    if (pro) {
+        sections.push(...cloudflareSection(context, host));
+        sections.push(...secretsSection(context));
+        sections.push(...providerSection(context, host));
+    }
+    else {
+        sections.push('## 3. Publish', '', `This edition builds to static assets — \`dist/client\` after \`${run} build\` — so it deploys as an assets-only Worker.`, '', `The steady-state way is Workers Builds: in the Cloudflare dashboard, connect this repository, set the root directory to this folder, the build command to \`${run} build\` and the output directory to \`dist/client\`. See ${WORKERS_BUILDS_DOCS}.`, '', `To upload from your machine instead, authenticate the wrangler CLI first (${WRANGLER_AUTH_DOCS}) and use its upload command — this CLI never touches your Cloudflare account.`, '');
+    }
+    sections.push('## Before you launch', '', `- [ ] Replace the sample ${nouns} with real ones (\`${run} content:reset --yes\`, then \`${run} listings:import\` or write them by hand).`, '- [ ] `site.config.ts` › `seo.strictLinks: true`. It ships as `false` so your first import cannot fail the build, and it is the only check that catches a page with fewer than two inbound internal links — one Google will struggle to find.', '- [ ] Rewrite `src/pages/about.astro`, `/terms/` and `/privacy/`.', `- [ ] \`${run} check && ${run} test\` clean.`, hasDomain ? `- [ ] \`https://${host}/sitemap-index.xml\` submitted to Google Search Console.` : '- [ ] Set `site.url`, then submit your sitemap to Google Search Console.', '');
+    return sections.filter((line) => line !== null).join('\n').replace(/\n{3,}/g, '\n\n');
+}
+function cloudflareSection(context, host) {
+    const { plan } = context;
+    const run = context.runPrefix;
+    const created = context.resourcesCreated;
+    return [
+        '## 3. Cloudflare resources',
+        '',
+        created
+            ? `The D1 database \`${plan.databaseName}\` and the R2 bucket \`${plan.bucketName}\` were created and written into \`wrangler.jsonc\`.`
+            : `None were created. Authenticate the wrangler CLI first (${WRANGLER_AUTH_DOCS}), then:`,
+        '',
+        created
+            ? null
+            : [
+                '```sh',
+                `npx wrangler d1 create ${plan.databaseName} --binding DB --update-config`,
+                `npx wrangler r2 bucket create ${plan.bucketName} --binding MEDIA --update-config`,
+                '```',
+                '',
+                'Both write the binding back into `wrangler.jsonc` themselves — there is no `--json` output to copy. R2 needs the subscription checkout completed once in the dashboard before the first bucket can be created.',
+                '',
+                'Then, in `site.config.ts`, turn `features.submissions` back on (and `features.newsletter: \'d1\'` if you want signups stored) — they were left off because there was no database to write to.',
+            ].join('\n'),
+        '',
+        '```sh',
+        `${run} cf:typegen        # regenerate worker-configuration.d.ts after any binding change`,
+        `${run} db:migrate:local  # local D1 (miniflare)`,
+        `${run} db:seed:local --dataset ${context.dataset}`,
+        '```',
+        '',
+        'For the production database, the same two steps have `:remote` variants (`db:migrate:remote`, `db:seed:remote`). They write to the real database, so run them when you mean to.',
+        '',
+        '## 4. Deploy',
+        '',
+        `Connect this repository to Workers Builds (${WORKERS_BUILDS_DOCS}) with the root directory set to this folder. Build variables:`,
+        '',
+        '| Variable | Value |',
+        '|---|---|',
+        '| `LISTINGS_SOURCE` | `d1` |',
+        '| `CLOUDFLARE_ACCOUNT_ID` | your account id |',
+        '| `D1_DATABASE_ID` | the id `wrangler.jsonc` now carries |',
+        '| `D1_READ_TOKEN` | **build secret** — an account API token with *D1 Read* scoped to this database |',
+        '| `PNPM_VERSION` | `10.12.4` (the build image ships an older pnpm) |',
+        '',
+        `The read token is a **separate** token from the one Workers Builds deploys with, and it is not \`CLOUDFLARE_API_TOKEN\`. Create it with a custom permission template: *Account* › *D1* › *Read*, restricted to this account. See ${D1_TOKEN_DOCS}.`,
+        '',
+        'Then create a **Deploy Hook** for the production branch, put its URL in `DEPLOY_HOOK_URL` (see secrets below) and set `providers.rebuild: \'deploy-hook\'` in `site.config.ts`. That is what makes approving a submission rebuild the site.',
+        '',
+        `\`${run} deploy\` uploads from your machine instead, once the wrangler CLI is authenticated.`,
+        '',
+    ];
+}
+function secretsSection(context) {
+    const run = context.runPrefix;
+    return [
+        '## 5. Secrets',
+        '',
+        `\`.dev.vars\` holds them for local development. For production, \`${run} cf:secrets\` prompts for each key named in \`.dev.vars.example\` and pipes what you type straight to wrangler — never through an argument list, a log, or this CLI. It does **not** read \`.dev.vars\`, so press Enter to skip a key you have not set yet; \`${run} cf:secrets --from-env\` takes the values from the shell's environment instead.`,
+        '',
+        '| Key | Needed when |',
+        '|---|---|',
+        '| `ADMIN_SECRET` | always — it is the admin login. Generated for you. |',
+        '| `TOKEN_SECRET` | always — signs status/checkout tokens, cookies and IP hashes. Generated for you. |',
+        '| `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET` | `providers.payment: \'stripe\'` |',
+        '| `RESEND_API_KEY` | `providers.email: \'resend\'` |',
+        '| `DEPLOY_HOOK_URL` | `providers.rebuild: \'deploy-hook\'` |',
+        '| `GITHUB_TOKEN` / `GITHUB_REPO` | `providers.rebuild: \'github-dispatch\'` |',
+        '',
+        'Every key in `.dev.vars` must also exist in `.dev.vars.example`: `wrangler types` derives the `Env` type from it, so an undeclared key breaks the build for everyone else.',
+        '',
+    ];
+}
+function providerSection(context, host) {
+    const { plan } = context;
+    const payments = plan.siteConfig.features.payments;
+    const email = plan.siteConfig.providers?.email ?? 'console';
+    const out = ['## 6. Providers', ''];
+    out.push('### Stripe', '', payments
+        ? 'Payments are on. Create the webhook endpoint in the Stripe dashboard:'
+        : 'Payments are off (`features.payments: false`). When you turn them on, create the webhook endpoint in the Stripe dashboard:', '', '```', `https://${host}/api/stripe/webhook/`, '```', '', '**Keep the trailing slash.** Every on-demand route redirects to its slashed form with a 308, and Stripe treats a 308 as a failed delivery — it will retry the same event for days.', '', `Events: ${STRIPE_EVENTS.map((event) => `\`${event}\``).join(', ')}. Set the endpoint's API version to match the SDK pin (\`2026-08-26.dahlia\`) — the payload follows the endpoint version, not the SDK.`, '', 'Then copy the signing secret into `STRIPE_WEBHOOK_SECRET`, and a restricted key (Checkout Sessions: write) into `STRIPE_SECRET_KEY`.', '');
+    out.push('### Email', '', email === 'resend'
+        ? 'Verify your sending domain in Resend, then put a sending-only API key in `RESEND_API_KEY`. `providers.emailFrom` must be an address on the verified domain.'
+        : email === 'cloudflare'
+            ? 'Cloudflare Email Sending needs the zone on Cloudflare DNS with Email Routing enabled, and `providers.emailFrom` inside the routing domain. The `send_email` binding is already in `wrangler.jsonc`; deploying it before Email Routing is on will fail the deploy.'
+            : 'Email is `console`: messages are logged, not sent. Switch `providers.email` to `resend` (or `cloudflare`) and set `providers.emailFrom` when you are ready.', '');
+    out.push('### R2 custom domain', '', 'Uploaded logos and screenshots are served from the bucket. Give it a hostname on your zone:', '', '```sh', `npx wrangler r2 bucket domain add ${plan.bucketName} --domain media.${host} --zone-id <your-zone-id>`, '```', '', `Then set \`media.baseUrl: 'https://media.${host}'\` in \`site.config.ts\`. Until that exists the build has nowhere to read uploaded media from. Zone id: dashboard › the zone › Overview › API section. See ${R2_DOMAIN_DOCS}.`, '');
+    return out;
+}

package/dist/core/site-config.js

@@ -0,0 +1,175 @@
+/**
+ * `site.config.ts` rewriting, through the module's AST.
+ *
+ * The file is a typed module — `defineSiteConfig({ ... })` with a validated
+ * shape — so the result has to keep type-checking and keep passing
+ * `pnpm check:config`. A regex that matches today's formatting would not
+ * survive the template being reformatted, a key being reordered, or a comment
+ * being added above the key it edits, so every change here is an assignment
+ * into the parsed object literal and the printer puts the file back together.
+ *
+ * `rewriteSiteConfig()` is a pure string -> string function: the tests feed it
+ * the real template and assert on what comes back.
+ */
+import { generateCode, parseModule } from 'magicast';
+/**
+ * recast reprints the nodes it was asked to change and leaves everything else
+ * byte-identical. Without an explicit tab width it guesses, and guesses wrong
+ * on this file (one space), so the two-space house style is stated outright.
+ */
+const FORMAT = {
+    tabWidth: 2,
+    useTabs: false,
+    quote: 'single',
+    trailingComma: true,
+    objectCurlySpacing: true,
+    arrowParensAlways: true,
+};
+function hasKey(object, key) {
+    return Object.keys(object).includes(key);
+}
+/** Walks (creating plain objects as it goes) and assigns the leaf. */
+function setPath(root, path, value) {
+    let node = root;
+    for (const key of path.slice(0, -1)) {
+        if (!hasKey(node, key) || typeof node[key] !== 'object' || node[key] === null)
+            node[key] = {};
+        node = node[key];
+    }
+    node[path[path.length - 1]] = value;
+}
+/** Deletes a key when it is there. `delete` on a missing key would be a no-op anyway; this keeps the intent readable. */
+function dropKey(object, key) {
+    if (hasKey(object, key))
+        delete object[key];
+}
+/**
+ * The one export. Takes the template's `site.config.ts` and the planned edits
+ * and returns the buyer's version of the same file.
+ *
+ * What it deliberately does NOT touch: `pseo.templates`, `seo.templates`,
+ * `listing.perPage` and friends, `legal`, `theme.tokens`. Those are the
+ * starter's opinions, they are valid for any dataset, and a buyer who wants
+ * them different is already in the file.
+ */
+export function rewriteSiteConfig(source, edits) {
+    const mod = parseModule(source, { sourceFileName: 'site.config.ts' });
+    const exported = mod.exports['siteConfig'];
+    if (!exported || exported.$type !== 'function-call' || !exported.$args?.length) {
+        throw new Error('site.config.ts does not look like `export const siteConfig = defineSiteConfig({ ... })` — refusing to rewrite it');
+    }
+    const config = exported.$args[0];
+    // --- file header --------------------------------------------------------
+    // Every other comment in the file is advice that is still true and is kept.
+    // This one is not: it names the template author's demo site and the dataset
+    // the template happened to ship with, and both are about to stop being true.
+    replaceFileHeader(mod, edits);
+    // --- site ---------------------------------------------------------------
+    const site = config['site'];
+    site['name'] = edits.site.name;
+    site['tagline'] = edits.site.tagline;
+    site['description'] = edits.site.description;
+    site['url'] = edits.site.url;
+    site['kind'] = edits.site.kind;
+    site['contactEmail'] = edits.site.contactEmail;
+    // The template's handles belong to whoever shipped it, not to the buyer.
+    dropKey(site, 'social');
+    // --- routes -------------------------------------------------------------
+    setPath(config, ['routes', 'listingBase'], edits.routes.listingBase);
+    setPath(config, ['routes', 'listingNoun'], { singular: edits.routes.listingNoun.singular, plural: edits.routes.listingNoun.plural });
+    // --- taxonomy -----------------------------------------------------------
+    config['categories'] = edits.categories.map((category) => stripUndefined(category));
+    config['tags'] = edits.tags.map((tag) => stripUndefined(tag));
+    if (edits.pricingTypes)
+        config['pricingTypes'] = edits.pricingTypes.map((type) => stripUndefined(type));
+    if (edits.customFields)
+        setPath(config, ['listing', 'customFields'], edits.customFields.map((field) => stripUndefined(field)));
+    // --- tiers --------------------------------------------------------------
+    // Cross-rule 3: an enabled tier with priceCents > 0 needs payments on. The
+    // prices stay in the file either way — the pricing table renders from them and
+    // `outboundRel()` treats a priced tier as sponsored (§6.4).
+    const tiers = config['tiers'];
+    if (Array.isArray(tiers)) {
+        for (const tier of tiers) {
+            const priced = typeof tier['priceCents'] === 'number' && tier['priceCents'] > 0;
+            tier['enabled'] = priced ? edits.enabledTierIds === 'all' : true;
+        }
+    }
+    // --- seo ----------------------------------------------------------------
+    // Written out rather than left to the `site.kind` fallback: `localBusiness` in
+    // the file is a value the buyer can find, and it is what makes the detail
+    // pages emit LocalBusiness instead of SoftwareApplication.
+    setPath(config, ['seo', 'jsonLd', 'listing'], edits.jsonLdListing);
+    // Orphan pages are a warning while the buyer is importing, not a build
+    // failure on day one. SETUP.md says to turn it back on before launch.
+    setPath(config, ['seo', 'strictLinks'], false);
+    dropKey(config['seo'], 'twitterHandle');
+    // --- theme, features, providers ----------------------------------------
+    setPath(config, ['theme', 'preset'], edits.themePreset);
+    const features = config['features'];
+    features['submissions'] = edits.features.submissions;
+    features['payments'] = edits.features.payments;
+    features['newsletter'] = edits.features.newsletter;
+    if (edits.providers) {
+        const providers = { email: edits.providers.email };
+        if (edits.providers.emailFrom)
+            providers['emailFrom'] = edits.providers.emailFrom;
+        providers['payment'] = edits.providers.payment;
+        providers['rebuild'] = edits.providers.rebuild;
+        config['providers'] = providers;
+    }
+    else {
+        // The free build has no server: 'console' email and 'none' payment are the
+        // defaults and the honest values, so the block is better absent than lying.
+        dropKey(config, 'providers');
+    }
+    // --- everything else ----------------------------------------------------
+    // `media.baseUrl` names the template author's R2 custom domain. It has a
+    // default (DEFAULT_MEDIA), so dropping the block is the correct neutral state;
+    // SETUP.md carries the command that creates the buyer's own.
+    dropKey(config, 'media');
+    setPath(config, ['newsletter', 'heading'], edits.newsletter.heading);
+    setPath(config, ['newsletter', 'blurb'], edits.newsletter.blurb);
+    setPath(config, ['budget', 'plan'], edits.budgetPlan);
+    return generateCode(mod, { format: FORMAT }).code;
+}
+/**
+ * Swaps the module's leading block comment for one that describes this project.
+ *
+ * The comment belongs to the first statement (the `defineSiteConfig` import),
+ * which is where both babel and recast attach it, so replacing it is a node
+ * edit like any other rather than a slice off the top of the string.
+ */
+function replaceFileHeader(mod, edits) {
+    // magicast hands back a `Program`; a plain babel parse would hand back a
+    // `File` wrapping one. Accept either rather than guessing.
+    const root = mod.$ast;
+    const first = (root.program?.body ?? root.body)?.[0];
+    if (!first)
+        return;
+    const text = [
+        '*',
+        ` * Site configuration for ${edits.site.name} — the one file that covers ~80% of`,
+        ' * customisation.',
+        ' *',
+        ` * Generated by create-zerodirs from the \`${edits.datasetName}\` sample dataset.`,
+        ' * `defineSiteConfig()` validates every field, fills in defaults and freezes the',
+        ' * result; run `pnpm check:config` after editing. Never put secrets here — they',
+        ' * live in `.dev.vars` / the Worker\'s own secrets (see `.dev.vars.example`).',
+        ' *',
+        ' * SETUP.md lists what is left to do.',
+        ' ',
+    ].join('\n');
+    const comment = { type: 'CommentBlock', value: text, leading: true, trailing: false };
+    first.comments = [comment];
+    first.leadingComments = [comment];
+}
+/** JSON round-trips drop `undefined`; an explicit `icon: undefined` would print as a hole. */
+function stripUndefined(value) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined)
+            out[key] = item;
+    }
+    return out;
+}