create-zerodirs 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# create-zerodirs
+
+Scaffold a [ZeroDirs](https://zerodirs.com) directory site: pick a sample dataset, answer a few
+questions, and get a project that builds.
+
+```sh
+npm  create zerodirs@latest my-directory -- --pro   # npm needs the `--`
+pnpm create zerodirs        my-directory --pro
+yarn create zerodirs        my-directory --pro
+bun  create zerodirs        my-directory --pro
+```
+
+Node 22.18 or newer.
+
+## What it does
+
+1. Copies the template — the free MIT edition by default, the paid starter with `--pro`.
+2. Asks for the name, the domain, a theme and (paid only) the plan, whether to take public
+   submissions, and how to send email.
+3. Writes `site.config.ts` **through its AST**, so the file keeps its comments, keeps
+   type-checking and does not depend on how it happened to be formatted.
+4. Rewrites `wrangler.jsonc` — Worker name, database name, bucket name, custom-domain route —
+   with `jsonc-parser`, so every comment in it survives.
+5. Generates `.dev.vars` (a fresh 32-byte `ADMIN_SECRET` and `TOKEN_SECRET`) and `.env` from the
+   template's own `*.example` files, so their key sets stay equal to it.
+6. Loads the chosen dataset's listings, blog posts and logos into `src/content` and `public/logos`.
+7. Optionally creates a D1 database and an R2 bucket, using your existing wrangler sign-in.
+8. Writes `SETUP.md` — everything it deliberately left to you.
+
+Everything the site *is* — the URL scheme, the listing noun, the structured-data type, the
+categories and tags — comes from the dataset's own `meta.json`, `categories.json` and `tags.json`.
+A dataset with `kind: "business"` produces `seo.jsonLd.listing: 'localBusiness'`, which is what
+makes the detail pages emit LocalBusiness structured data.
+
+## What it never does
+
+- No sign-in. Your Cloudflare credentials are yours; a browser OAuth window opening in the middle
+  of a scaffold is a surprise. If wrangler cannot identify an account, resource creation is skipped
+  and `SETUP.md` says where to authenticate.
+- No secret upload. Secrets never pass through this process, an argument list or a log.
+- No deploy, and nothing written to a remote database.
+- No dev server. It prints the command.
+- No overwriting: it refuses a directory that already has files in it.
+- No telemetry, no global installs, no `git init` and no remote rewriting.
+
+## Options
+
+```
+create-zerodirs [directory] [options]
+
+  --pro                    Use the paid starter template (default: the free MIT edition)
+  --dataset <name>         ai-tools | indie-tools | local-businesses
+  --template-dir <path>    Copy the template from a local directory instead of fetching it
+                           (env: ZERODIRS_TEMPLATE_DIR)
+  --name <name>            Site name
+  --domain <host>          Production domain, e.g. dir.example.com
+  --theme <preset>         default | warm | mono
+  --package-manager <pm>   pnpm | npm | yarn | bun
+  -y, --yes                Accept every default; ask nothing
+  --no-cloudflare          Never call wrangler; create no Cloudflare resources
+  --no-install             Do not install dependencies
+  -h, --help               Show this
+  -v, --version            Print the version
+```
+
+`--yes` takes the conservative answer to every question — no submissions, no payments, `console`
+email, the free plan — because each of the alternatives needs an account, a key or a domain that
+a non-interactive run cannot have.
+
+`--template-dir` is not only a test hook. It is how the starter's own CI exercises the whole
+flow, and how you scaffold from a copy of the starter you already have.
+
+## Development
+
+```sh
+pnpm test      # typecheck + unit tests
+pnpm build     # dist/
+
+# end to end, against a local checkout of the starter (or its derived free tree)
+node dist/index.js /tmp/zd-free --yes --no-cloudflare \
+  --dataset ai-tools --template-dir <path-to-zerodirs>/.derived/free
+```
+
+The unit tests run against copies of the starter's files in `tests/fixtures/starter/`; set
+`ZERODIRS_STARTER_DIR` to a checkout of `zerodirs/zerodirs` to run them against the real thing.

package/dist/cli/args.js

@@ -0,0 +1,128 @@
+const PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
+export const USAGE = `Usage: create-zerodirs [directory] [options]
+
+Options:
+  --pro                    Use the paid starter template (default: the free MIT edition)
+  --dataset <name>         Sample data to start from: ai-tools | indie-tools | local-businesses
+  --template-dir <path>    Copy the template from a local directory instead of fetching it
+                           (env: ZERODIRS_TEMPLATE_DIR)
+  --name <name>            Site name (skips the question)
+  --domain <host>          Production domain, e.g. dir.example.com
+  --theme <preset>         Theme preset name
+  --package-manager <pm>   pnpm | npm | yarn | bun (default: whichever ran this command)
+  -y, --yes                Accept every default; ask nothing
+  --no-cloudflare          Never call wrangler; create no Cloudflare resources
+  --no-install             Do not install dependencies
+  -h, --help               Show this
+  -v, --version            Print the version
+
+Examples:
+  npm create zerodirs@latest my-directory -- --pro --dataset local-businesses
+  pnpm create zerodirs my-directory --dataset ai-tools --yes --no-cloudflare`;
+/** Flags that take a value. */
+const VALUE_FLAGS = new Set(['--dataset', '--template-dir', '--name', '--domain', '--theme', '--package-manager']);
+export function parseArgs(argv) {
+    const options = { pro: false, yes: false, cloudflare: true, install: true, help: false, version: false };
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('-')) {
+            positional.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        const flag = equals === -1 ? arg : arg.slice(0, equals);
+        const inline = equals === -1 ? undefined : arg.slice(equals + 1);
+        if (VALUE_FLAGS.has(flag)) {
+            const value = inline ?? argv[++index];
+            if (value === undefined || value === '')
+                return { ok: false, message: `${flag} needs a value\n\n${USAGE}` };
+            switch (flag) {
+                case '--dataset':
+                    options.dataset = value;
+                    break;
+                case '--template-dir':
+                    options.templateDir = value;
+                    break;
+                case '--name':
+                    options.name = value;
+                    break;
+                case '--domain':
+                    options.domain = value;
+                    break;
+                case '--theme':
+                    options.theme = value;
+                    break;
+                case '--package-manager': {
+                    if (!PACKAGE_MANAGERS.includes(value)) {
+                        return { ok: false, message: `--package-manager must be one of ${PACKAGE_MANAGERS.join(', ')}, got "${value}"` };
+                    }
+                    options.packageManager = value;
+                    break;
+                }
+            }
+            continue;
+        }
+        switch (flag) {
+            case '--pro':
+                options.pro = true;
+                break;
+            case '--free':
+                options.pro = false;
+                break;
+            case '-y':
+            case '--yes':
+                options.yes = true;
+                break;
+            case '--no-cloudflare':
+                options.cloudflare = false;
+                break;
+            case '--cloudflare':
+                options.cloudflare = true;
+                break;
+            case '--no-install':
+                options.install = false;
+                break;
+            case '-h':
+            case '--help':
+                options.help = true;
+                break;
+            case '-v':
+            case '--version':
+                options.version = true;
+                break;
+            default:
+                return { ok: false, message: `unknown option "${flag}"\n\n${USAGE}` };
+        }
+    }
+    if (positional.length > 1)
+        return { ok: false, message: `expected at most one directory, got ${positional.length}: ${positional.join(', ')}\n\n${USAGE}` };
+    if (positional[0])
+        options.dir = positional[0];
+    return { ok: true, options };
+}
+/** `npm_config_user_agent` is set by every package manager that ran us. */
+export function detectPackageManager(userAgent) {
+    if (!userAgent)
+        return 'pnpm';
+    const name = userAgent.split('/')[0];
+    return PACKAGE_MANAGERS.includes(name) ? name : 'pnpm';
+}
+/** How this package manager runs a package script (`pnpm build` vs `npm run build`). */
+export function runPrefix(manager) {
+    return manager === 'npm' ? 'npm run' : manager;
+}
+export function installCommand(manager) {
+    return `${manager} install`;
+}
+/**
+ * Node ≥ 22.18. Checked before anything else runs, so an old Node produces a
+ * sentence instead of a SyntaxError from inside a dependency.
+ */
+export function nodeVersionError(version, minimum = [22, 18]) {
+    const parts = version.replace(/^v/, '').split('.').map((piece) => Number.parseInt(piece, 10));
+    const [major = 0, minor = 0] = parts;
+    if (major > minimum[0] || (major === minimum[0] && minor >= minimum[1]))
+        return null;
+    return `create-zerodirs needs Node ${minimum[0]}.${minimum[1]} or newer; this is Node ${version.replace(/^v/, '')}.\nInstall a current Node (https://nodejs.org) and run it again.`;
+}

package/dist/cli/prompts.js

@@ -0,0 +1,148 @@
+/**
+ * The question flow.
+ *
+ * Short on purpose. Everything the dataset already declares — what kind of
+ * directory this is, what the listing route and noun are, what structured data
+ * the detail pages emit, what the categories and tags are — is read from its
+ * `meta.json`, `categories.json` and `tags.json` rather than asked for. The
+ * questions that remain are the ones only the buyer can answer.
+ *
+ * `--yes` skips all of it and takes the conservative answer to each: no
+ * submissions, no payments, `console` email, the free plan. Every one of those
+ * is a thing that needs an account, a key or a domain, and a scaffold should
+ * not pretend to have any of them.
+ */
+import * as p from '@clack/prompts';
+import { datasetIdentity } from '../core/dataset.js';
+export const THEME_PRESETS = [
+    { value: 'default', label: 'default', hint: 'blue, 0.5rem radius' },
+    { value: 'warm', label: 'warm', hint: 'orange, 1rem radius' },
+    { value: 'mono', label: 'mono', hint: 'black, no radius' },
+];
+export class CancelledError extends Error {
+    constructor() {
+        super('cancelled');
+        this.name = 'CancelledError';
+    }
+}
+function unwrap(value) {
+    if (p.isCancel(value))
+        throw new CancelledError();
+    return value;
+}
+/** The `--yes` answers: nothing that needs an account, a key or a domain. */
+export function defaultAnswers(context, dataset) {
+    return {
+        edition: context.edition,
+        projectDir: context.projectDir,
+        siteName: context.options.name ?? suggestedName(context, dataset),
+        ...(context.options.domain ? { domain: context.options.domain } : {}),
+        dataset,
+        themePreset: context.options.theme ?? 'default',
+        plan: 'free',
+        submissions: false,
+        payments: false,
+        email: 'console',
+        createResources: false,
+    };
+}
+function suggestedName(context, dataset) {
+    const found = context.datasets.find((entry) => entry.name === dataset);
+    return found?.meta.suggestedName ?? 'My Directory';
+}
+/** Which dataset to start from, when `--dataset` did not say. */
+export async function askDataset(context) {
+    if (context.options.dataset)
+        return context.options.dataset;
+    if (context.datasets.length === 0)
+        throw new Error('the template ships no seed datasets');
+    if (context.datasets.length === 1 || context.options.yes)
+        return context.datasets[0].name;
+    return unwrap(await p.select({
+        message: 'Which sample data do you want to start from?',
+        options: context.datasets.map((entry) => {
+            const identity = datasetIdentity(entry.meta);
+            return {
+                value: entry.name,
+                label: entry.name,
+                hint: `${entry.listings} ${identity.listingNoun.plural} · /${identity.listingBase}/ · ${identity.kind}`,
+            };
+        }),
+    }));
+}
+export async function ask(context, dataset) {
+    if (context.options.yes)
+        return defaultAnswers(context, dataset);
+    const identity = datasetIdentity(context.datasets.find((entry) => entry.name === dataset)?.meta ?? {});
+    const isPro = context.edition === 'pro';
+    const siteName = context.options.name ??
+        unwrap(await p.text({
+            message: 'What is the directory called?',
+            placeholder: suggestedName(context, dataset),
+            defaultValue: suggestedName(context, dataset),
+        }));
+    const domain = context.options.domain ??
+        unwrap(await p.text({
+            message: 'Which domain will it live on? (blank if you do not know yet)',
+            placeholder: 'directory.example.com',
+            defaultValue: '',
+            validate: (value) => (value && /\s|^https?:/i.test(value) ? 'Just the host, e.g. directory.example.com' : undefined),
+        }));
+    p.note([
+        `kind:               ${identity.kind}`,
+        `listing URLs:       /${identity.listingBase}/<slug>/`,
+        `listing noun:       ${identity.listingNoun.singular} / ${identity.listingNoun.plural}`,
+        `structured data:    ${identity.jsonLd}`,
+    ].join('\n'), `From the ${dataset} dataset`);
+    const themePreset = context.options.theme ?? unwrap(await p.select({ message: 'Theme preset?', options: THEME_PRESETS, initialValue: 'default' }));
+    let plan = 'free';
+    let submissions = false;
+    let payments = false;
+    let email = 'console';
+    let createResources = false;
+    if (isPro) {
+        plan = unwrap(await p.select({
+            message: 'Which Cloudflare Workers plan is this account on?',
+            options: [
+                { value: 'free', label: 'Free', hint: 'tighter budget assertions in the build' },
+                { value: 'paid', label: 'Paid ($5/mo)', hint: 'needed for Cloudflare Email Sending' },
+            ],
+            initialValue: 'free',
+        }));
+        createResources = context.cloudflareAllowed
+            ? unwrap(await p.confirm({
+                message: 'Create the D1 database and R2 bucket now? (uses your existing wrangler sign-in)',
+                initialValue: false,
+            }))
+            : false;
+        if (createResources) {
+            submissions = unwrap(await p.confirm({ message: 'Accept public submissions? (form + review queue)', initialValue: true }));
+            if (submissions) {
+                payments = unwrap(await p.confirm({ message: 'Charge for express / featured listings? (Stripe)', initialValue: false }));
+            }
+        }
+        email = unwrap(await p.select({
+            message: 'How should the site send email?',
+            options: [
+                { value: 'console', label: 'Not yet', hint: 'log messages; decide later' },
+                { value: 'resend', label: 'Resend', hint: 'API key + verified domain' },
+                { value: 'cloudflare', label: 'Cloudflare Email Sending', hint: 'Workers paid plan + Email Routing on the zone' },
+            ],
+            initialValue: plan === 'paid' ? 'cloudflare' : 'resend',
+        }));
+    }
+    return {
+        edition: context.edition,
+        projectDir: context.projectDir,
+        siteName: siteName.trim() || suggestedName(context, dataset),
+        ...(domain.trim() ? { domain: domain.trim() } : {}),
+        dataset,
+        themePreset,
+        plan,
+        submissions,
+        payments,
+        email,
+        createResources,
+    };
+}
+export const prompts = p;

package/dist/core/answers.js

@@ -0,0 +1,162 @@
+/**
+ * Answers -> the values every generated file is written from.
+ *
+ * This module is pure, and it is the one the unit tests aim at: given a set of
+ * answers and a dataset, `planProject()` returns the exact edits that
+ * `site.config.ts`, `wrangler.jsonc`, `.dev.vars`, `.env` and `SETUP.md` are
+ * produced from. Nothing here touches the filesystem, the network or a prompt.
+ *
+ * Every value it produces has to survive `src/config/schema.ts`, so the
+ * constraints that schema enforces are enforced here instead of being
+ * discovered by the buyer at the first `pnpm check:config`:
+ * `site.description` ≤ 160 chars, `providers.emailFrom` shaped like
+ * `Name <addr@host>`, a Worker name that is a valid subdomain label, and a
+ * priced tier only ever enabled together with payments.
+ */
+import { datasetIdentity, } from './dataset.js';
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+/**
+ * A Worker name / resource-name stem: lowercase, `[a-z0-9-]`, no leading or
+ * trailing dash, ≤ 40 chars so `<stem>-media` still fits Cloudflare's 63-char
+ * limit. Falls back to `my-directory` when the input has nothing usable in it
+ * (a name written entirely in a non-Latin script, for instance).
+ */
+export function slugifyName(value, fallback = 'my-directory') {
+    const slug = value
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/g, '');
+    return slug || fallback;
+}
+/** `https://host`, or the schema-valid placeholder when no domain is known. */
+export function siteUrlFor(domain) {
+    const host = normalizeDomain(domain);
+    return host ? `https://${host}` : 'https://example.com';
+}
+/** Strips scheme, path, `www.` and any trailing slash from whatever the buyer typed. */
+export function normalizeDomain(value) {
+    if (!value)
+        return '';
+    const trimmed = value.trim().replace(/^https?:\/\//i, '').replace(/\/.*$/, '').replace(/\.$/, '');
+    return trimmed.toLowerCase();
+}
+/** `hello@<domain>`, or the placeholder address. `site.contactEmail` must parse as an email. */
+export function contactEmailFor(domain) {
+    const host = normalizeDomain(domain);
+    return host ? `hello@${host}` : 'hello@example.com';
+}
+/**
+ * `providers.emailFrom` — cross-rule 7 wants exactly `Name <addr@host>`, and
+ * the name half may not contain angle brackets.
+ */
+export function emailFromFor(siteName, domain) {
+    const name = siteName.replace(/[<>]/g, '').trim() || 'My Directory';
+    return `${name} <${contactEmailFor(domain)}>`;
+}
+/** `site.description` is capped at 160 characters (it is the home meta description). */
+export function clampDescription(text, max = 160) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max);
+    const lastSpace = cut.lastIndexOf(' ');
+    return (lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd();
+}
+export function defaultTagline(noun) {
+    return `Every ${noun} worth knowing, hand-picked and fast`;
+}
+export function defaultDescription(siteName, nouns) {
+    return clampDescription(`${siteName} is a curated directory of ${nouns} — hand-picked, sorted into categories and tags, searchable, and fast on every page.`);
+}
+// ---------------------------------------------------------------------------
+// The plan
+// ---------------------------------------------------------------------------
+/**
+ * Answers + dataset -> every value the generated files carry.
+ *
+ * Two rules are load-bearing and both come from `crossRules()` in
+ * `src/config/schema.ts`:
+ *
+ *  - a priced tier may only be `enabled` when `features.payments` is true AND
+ *    `providers.payment` is `'stripe'`, so those three move together;
+ *  - `providers.emailFrom` is required as soon as `providers.email` is not
+ *    `'console'`.
+ *
+ * And one comes from the starter's shape rather than its schema: `submissions`
+ * and the `d1` newsletter both write to D1, so neither is turned on unless the
+ * CLI actually created a database.
+ */
+export function planProject(answers, dataset) {
+    const identity = datasetIdentity(dataset.meta);
+    const domain = normalizeDomain(answers.domain);
+    const siteUrl = siteUrlFor(domain);
+    const contactEmail = contactEmailFor(domain);
+    const siteName = answers.siteName.trim() || dataset.meta.suggestedName || 'My Directory';
+    const nouns = identity.listingNoun.plural;
+    const tagline = (answers.tagline ?? '').trim() || defaultTagline(identity.listingNoun.singular);
+    const description = defaultDescription(siteName, nouns);
+    const stem = slugifyName(siteName, slugifyName(answers.projectDir));
+    const isPro = answers.edition === 'pro';
+    // Submissions need a database; payments need submissions.
+    const submissions = isPro && answers.submissions && answers.createResources;
+    const payments = submissions && answers.payments;
+    const siteConfig = {
+        datasetName: dataset.name,
+        site: { name: siteName, tagline, description, url: siteUrl, kind: identity.kind, contactEmail },
+        routes: { listingBase: identity.listingBase, listingNoun: identity.listingNoun },
+        categories: dataset.categories,
+        tags: dataset.tags,
+        ...(dataset.meta.suggestedPricingTypes?.length ? { pricingTypes: dataset.meta.suggestedPricingTypes } : {}),
+        ...(dataset.meta.suggestedCustomFields?.length ? { customFields: dataset.meta.suggestedCustomFields } : {}),
+        jsonLdListing: identity.jsonLd,
+        themePreset: answers.themePreset,
+        enabledTierIds: payments ? 'all' : 'free-only',
+        features: {
+            submissions,
+            payments,
+            // The d1 newsletter posts to /api/newsletter/, which needs the binding.
+            newsletter: submissions ? 'd1' : 'off',
+        },
+        ...(isPro
+            ? {
+                providers: {
+                    email: answers.email,
+                    ...(answers.email === 'console' ? {} : { emailFrom: emailFromFor(siteName, domain) }),
+                    payment: payments ? 'stripe' : 'none',
+                    // The rebuild provider posts to a Deploy Hook that does not exist yet;
+                    // SETUP.md is where it gets created.
+                    rebuild: 'none',
+                },
+            }
+            : {}),
+        newsletter: {
+            heading: `New ${nouns}, weekly`,
+            blurb: `One email a week with the best new ${nouns}. No spam, unsubscribe any time.`,
+        },
+        budgetPlan: answers.plan,
+    };
+    return {
+        answers,
+        identity,
+        siteUrl,
+        contactEmail,
+        workerName: stem,
+        databaseName: `${stem}-db`,
+        bucketName: `${stem}-media`,
+        siteConfig,
+        wrangler: {
+            name: stem,
+            databaseName: `${stem}-db`,
+            bucketName: `${stem}-media`,
+            ...(domain ? { domain } : {}),
+            // R8: only valid once Email Routing is enabled on the zone, so it is opt-in
+            // via the email provider rather than always present.
+            sendEmail: isPro && answers.email === 'cloudflare',
+        },
+    };
+}

package/dist/core/cloudflare.js

@@ -0,0 +1,88 @@
+/**
+ * The Cloudflare steps — and, more importantly, the ones that are not here.
+ *
+ * This CLI creates two resources and nothing else. It does not sign anyone in
+ * (the account is the buyer's, and an OAuth browser window opening in the
+ * middle of a scaffold is a surprise), it does not upload secrets, it does not
+ * deploy, and it never writes to a remote database. Those all live in
+ * `SETUP.md` as commands the buyer runs when they mean to.
+ *
+ * `wrangler d1 create` and `wrangler r2 bucket create` have no `--json` output,
+ * so there is no id to parse: `--binding DB --update-config` makes wrangler
+ * write the finished binding back into `wrangler.jsonc` itself. The existing
+ * placeholder binding is removed first so wrangler writes a complete block
+ * rather than appending a second one, and is restored if the create fails.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { dropBinding } from './wrangler-config.js';
+import { run } from './exec.js';
+export const WRANGLER_AUTH_DOCS = 'https://developers.cloudflare.com/workers/wrangler/commands/#auth';
+export const R2_SUBSCRIPTION_DOCS = 'https://developers.cloudflare.com/r2/get-started/';
+/** Prefers the project's own pinned wrangler; falls back to fetching one. */
+export function wranglerFor(projectDir) {
+    const local = join(projectDir, 'node_modules/.bin/wrangler');
+    if (existsSync(local))
+        return { command: local, prefix: [] };
+    return { command: 'npx', prefix: ['--yes', 'wrangler'] };
+}
+/**
+ * Read-only account check. When it says no, the CLI skips resource creation and
+ * says where to authenticate — it does not start an auth flow on the buyer's
+ * behalf.
+ */
+export async function whoami(projectDir) {
+    const { command, prefix } = wranglerFor(projectDir);
+    const result = await run(command, [...prefix, 'whoami'], { cwd: projectDir, timeout: 120_000 });
+    if (result.ok && /account/i.test(result.stdout))
+        return { signedIn: true, message: firstAccountLine(result.stdout) };
+    return { signedIn: false, message: result.message || 'wrangler could not identify an account' };
+}
+function firstAccountLine(stdout) {
+    const line = stdout.split('\n').find((entry) => /@|account id/i.test(entry));
+    return (line ?? '').trim() || 'signed in';
+}
+/**
+ * `wrangler d1 create <name> --binding DB --update-config`.
+ *
+ * Note what is absent: no `--use-remote` (that flag makes the new binding a
+ * remote one, which is not what a fresh project wants), no location hint (the
+ * buyer's account default is a better guess than ours), and no migration run
+ * against the production database.
+ */
+export async function createD1(projectDir, databaseName) {
+    return createResource(projectDir, 'd1_databases', ['d1', 'create', databaseName, '--binding', 'DB', '--update-config'], (message) => /already exists/i.test(message) ? `a D1 database called "${databaseName}" already exists on this account` : undefined);
+}
+/**
+ * `wrangler r2 bucket create <name> --binding MEDIA --update-config`.
+ *
+ * R2 needs the subscription checkout completed once in the dashboard before the
+ * first bucket can be created. That failure is detected and reported rather
+ * than left as a half-made project — the rest of the scaffold is fine, and
+ * SETUP.md carries the command to run afterwards.
+ */
+export async function createR2(projectDir, bucketName) {
+    return createResource(projectDir, 'r2_buckets', ['r2', 'bucket', 'create', bucketName, '--binding', 'MEDIA', '--update-config'], (message) => /not (yet )?(been )?(enabled|signed up)|subscri|10042|must be enabled/i.test(message)
+        ? `R2 is not enabled on this account yet — complete the R2 subscription checkout in the dashboard (${R2_SUBSCRIPTION_DOCS}), then run the command in SETUP.md`
+        : /already exists|BucketAlreadyOwnedByYou/i.test(message)
+            ? `an R2 bucket called "${bucketName}" already exists on this account`
+            : undefined);
+}
+async function createResource(projectDir, bindingKey, args, explain) {
+    const configPath = join(projectDir, 'wrangler.jsonc');
+    const before = existsSync(configPath) ? readFileSync(configPath, 'utf8') : undefined;
+    if (before !== undefined)
+        writeFileSync(configPath, dropBinding(before, bindingKey), 'utf8');
+    const { command, prefix } = wranglerFor(projectDir);
+    const result = await run(command, [...prefix, ...args], { cwd: projectDir, timeout: 180_000 });
+    if (!result.ok) {
+        // Put the placeholder binding back: a project with a named-but-uncreated
+        // binding is something SETUP.md can talk about; one with no binding at all
+        // silently loses the shape the buyer is meant to fill in.
+        if (before !== undefined)
+            writeFileSync(configPath, before, 'utf8');
+        const combined = `${result.stderr}\n${result.stdout}`;
+        return { ok: false, reason: result.message, ...(explain(combined) ? { hint: explain(combined) } : {}) };
+    }
+    return { ok: true };
+}