create-zerodirs 0.1.0

package/dist/core/template.js

@@ -0,0 +1,66 @@
+/**
+ * Getting the template onto disk.
+ *
+ * Three sources, in the order they are tried:
+ *
+ *  1. `--template-dir <path>` / `ZERODIRS_TEMPLATE_DIR` — copy a local
+ *     directory. This is not only a test hook: it is how CI and this repository
+ *     exercise the whole flow today, because the free release tarball does not
+ *     exist until the release tag is cut.
+ *  2. free edition — the `zerodirs/zerodirs-oss` release tarball, via giget.
+ *  3. `--pro` — `git clone --depth 1` of the private starter the buyer has been
+ *     given access to. Their own git credentials do the authentication; this
+ *     CLI never sees a licence key or a token.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { copyTemplate } from './files.js';
+import { run } from './exec.js';
+export const FREE_REPO = 'zerodirs/zerodirs-oss';
+export const PRO_REPO = 'zerodirs/zerodirs';
+/** `--template-dir` wins over everything, including `--pro`. */
+export function resolveTemplateDir(option, env, cwd) {
+    const value = option ?? env;
+    if (!value)
+        return undefined;
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+export async function fetchTemplate(request) {
+    if (request.templateDir) {
+        const dir = request.templateDir;
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            throw new Error(`--template-dir: ${dir} is not a directory`);
+        if (!existsSync(resolve(dir, 'package.json')))
+            throw new Error(`--template-dir: ${dir} has no package.json — that is not a ZeroDirs template`);
+        const copied = copyTemplate(dir, request.target);
+        return { source: `${dir} (local)`, files: copied.files };
+    }
+    if (request.edition === 'free')
+        return fetchFreeTarball(request);
+    return cloneProRepo(request);
+}
+async function fetchFreeTarball(request) {
+    const source = `github:${FREE_REPO}${request.ref ? `#${request.ref}` : ''}`;
+    try {
+        const { downloadTemplate } = await import('giget');
+        const result = await downloadTemplate(source, { dir: request.target, force: true, preferOffline: false });
+        return { source: `${source} (${result.source ?? 'tarball'})`, files: -1 };
+    }
+    catch (error) {
+        throw new Error(`could not download the free template from ${source}: ${error.message}\n` +
+            `If the release has not been published yet, point at a local copy instead:\n` +
+            `  create-zerodirs <dir> --template-dir <path-to-zerodirs>/.derived/free`);
+    }
+}
+async function cloneProRepo(request) {
+    const url = `https://github.com/${PRO_REPO}.git`;
+    const args = ['clone', '--depth', '1', ...(request.ref ? ['--branch', request.ref] : []), url, request.target];
+    const result = await run('git', args, { cwd: request.cwd });
+    if (!result.ok) {
+        throw new Error(`could not clone ${url}: ${result.message}\n` +
+            `The paid starter is a private repository — make sure your git credentials can read it (this CLI never handles a licence key).\n` +
+            `To use a copy you already have:\n` +
+            `  create-zerodirs <dir> --pro --template-dir <path-to-starter>`);
+    }
+    return { source: `${url} (git clone --depth 1)`, files: -1 };
+}

package/dist/core/wrangler-config.js

@@ -0,0 +1,76 @@
+/**
+ * `wrangler.jsonc` rewriting.
+ *
+ * JSONC, not JSON: the starter's file is more comment than config — why `main`
+ * points at `src/worker.ts`, why `triggers` has to be present, and the whole
+ * `send_email` block that explains when the binding becomes legal. Parsing and
+ * re-serialising would throw all of that away, so the edits are applied with
+ * `jsonc-parser`, which rewrites one value at a time and leaves the surrounding
+ * bytes (comments, tabs, key order) untouched.
+ *
+ * Pure string -> string, like `rewriteSiteConfig()`.
+ */
+import { applyEdits, modify, parse } from 'jsonc-parser';
+/** The starter's file is tab-indented; `modify` re-indents only what it inserts. */
+const FORMATTING = { insertSpaces: false, tabSize: 1, eol: '\n' };
+/** Reads the file's current values without disturbing it. Throws on malformed JSONC. */
+export function parseWranglerConfig(source) {
+    const errors = [];
+    const value = parse(source, errors, { allowTrailingComma: true });
+    if (errors.length)
+        throw new Error(`wrangler.jsonc did not parse (${errors.length} error(s) at offset ${errors[0]?.offset})`);
+    return value ?? {};
+}
+function edit(source, path, value) {
+    return applyEdits(source, modify(source, path, value, { formattingOptions: FORMATTING }));
+}
+/**
+ * Applies the buyer's identity to `wrangler.jsonc`.
+ *
+ *  - `name` becomes the Worker name, which is also the `*.workers.dev` subdomain.
+ *  - `d1_databases[0].database_name` / `r2_buckets[0].bucket_name` become the
+ *    names the CLI (or SETUP.md) creates. `database_id` is emptied rather than
+ *    carried over: the template's id points at somebody else's database, and
+ *    `wrangler d1 create --update-config` fills the real one in.
+ *  - `routes` gets the buyer's custom domain, or is dropped when there is none.
+ *    A route naming a domain the buyer does not own fails their first deploy.
+ *  - `send_email` is only added when the config asks for it (R8) — the binding
+ *    is invalid until Email Routing is enabled on the zone, and an invalid
+ *    binding fails the deploy rather than degrading.
+ */
+export function rewriteWranglerConfig(source, edits) {
+    const current = parseWranglerConfig(source);
+    let out = source;
+    out = edit(out, ['name'], edits.name);
+    if (Array.isArray(current.d1_databases) && current.d1_databases.length > 0) {
+        out = edit(out, ['d1_databases', 0, 'database_name'], edits.databaseName);
+        if (current.d1_databases[0] && 'database_id' in current.d1_databases[0]) {
+            out = edit(out, ['d1_databases', 0, 'database_id'], '');
+        }
+    }
+    if (Array.isArray(current.r2_buckets) && current.r2_buckets.length > 0) {
+        out = edit(out, ['r2_buckets', 0, 'bucket_name'], edits.bucketName);
+    }
+    if (edits.domain) {
+        out = edit(out, ['routes'], [{ pattern: edits.domain, custom_domain: true }]);
+    }
+    else if (current.routes !== undefined) {
+        out = edit(out, ['routes'], undefined);
+    }
+    if (edits.sendEmail && current.send_email === undefined) {
+        out = edit(out, ['send_email'], [{ name: 'EMAIL', remote: true }]);
+    }
+    return out;
+}
+/**
+ * Removes a binding array so `wrangler <resource> create --binding … --update-config`
+ * can write a complete, correct block back — id included. Used immediately
+ * before a create call, and only then: the rewritten placeholder above is what
+ * a project without created resources keeps.
+ */
+export function dropBinding(source, key) {
+    const current = parseWranglerConfig(source);
+    if (current[key] === undefined)
+        return source;
+    return edit(source, [key], undefined);
+}

package/dist/create.js

@@ -0,0 +1,247 @@
+/**
+ * The flow, in the order design.md §11.1 lists it: check the environment, get
+ * the template, ask, write, (optionally) create resources, initialise locally,
+ * then print what is left and write it to `SETUP.md`.
+ *
+ * The last step is the one worth naming: the CLI prints `pnpm dev`, it does not
+ * run it. A scaffolder that ends by seizing the terminal with a dev server is a
+ * scaffolder you cannot use from a script.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { detectPackageManager, installCommand, runPrefix } from './cli/args.js';
+import { CancelledError, ask, askDataset, prompts as p } from './cli/prompts.js';
+import { planProject } from './core/answers.js';
+import { createD1, createR2, WRANGLER_AUTH_DOCS, whoami, wranglerFor } from './core/cloudflare.js';
+import { listDatasets, readDataset } from './core/dataset.js';
+import { renderEnvFile, randomSecret } from './core/env-files.js';
+import { run } from './core/exec.js';
+import { isEmptyDir, loadDatasetContent, write } from './core/files.js';
+import { renderSetupMd } from './core/setup-md.js';
+import { rewriteSiteConfig } from './core/site-config.js';
+import { fetchTemplate, resolveTemplateDir } from './core/template.js';
+import { rewriteWranglerConfig } from './core/wrangler-config.js';
+export async function create(options, environment) {
+    const { cwd, env } = environment;
+    const edition = options.pro ? 'pro' : 'free';
+    const manager = options.packageManager ?? detectPackageManager(env['npm_config_user_agent']);
+    const templateDir = resolveTemplateDir(options.templateDir, env['ZERODIRS_TEMPLATE_DIR'], cwd);
+    p.intro(`create-zerodirs · ${edition === 'pro' ? 'paid starter' : 'free edition'}`);
+    // 1. Where -------------------------------------------------------------
+    const dirName = options.dir ??
+        (options.yes
+            ? 'my-directory'
+            : (await p.text({ message: 'Where should the project go?', placeholder: './my-directory', defaultValue: './my-directory' })));
+    if (typeof dirName !== 'string' || p.isCancel(dirName))
+        throw new CancelledError();
+    const target = isAbsolute(dirName) ? dirName : resolve(cwd, dirName);
+    if (!isEmptyDir(target)) {
+        p.cancel(`${target} already has files in it. Pick an empty directory — this CLI never overwrites an existing project.`);
+        return 1;
+    }
+    const createdTarget = !existsSync(target);
+    mkdirSync(target, { recursive: true });
+    try {
+        // 2. Template --------------------------------------------------------
+        const spinner = p.spinner();
+        spinner.start(templateDir ? 'Copying template' : edition === 'pro' ? 'Cloning the starter' : 'Downloading the template');
+        let templateSource;
+        try {
+            const fetched = await fetchTemplate({ edition, ...(templateDir ? { templateDir } : {}), target, cwd });
+            templateSource = fetched.source;
+            spinner.stop(`Template: ${fetched.source}`);
+        }
+        catch (error) {
+            spinner.stop('Could not get the template');
+            throw error;
+        }
+        // A clone would otherwise leave the project pointing at somebody else's
+        // remote. The CLI does not run `git init` either — that is the buyer's call.
+        rmSync(join(target, '.git'), { recursive: true, force: true });
+        // 3. Questions -------------------------------------------------------
+        const datasetNames = listDatasets(target);
+        const askContext = {
+            options,
+            edition: edition,
+            projectDir: dirName.replace(/^\.\//, ''),
+            datasets: datasetNames.map((name) => {
+                const dataset = readDataset(target, name);
+                return { name, meta: dataset.meta, listings: dataset.listingCount };
+            }),
+            cloudflareAllowed: options.cloudflare,
+        };
+        const datasetName = await askDataset(askContext);
+        const dataset = readDataset(target, datasetName);
+        const answers = await ask(askContext, datasetName);
+        const plan = planProject(answers, dataset);
+        // 4. Write -----------------------------------------------------------
+        writeProjectFiles(target, plan);
+        const content = loadDatasetContent(target, dataset.dir);
+        // 5. Cloudflare resources -------------------------------------------
+        let resourcesCreated = false;
+        const notes = [];
+        if (answers.createResources && options.cloudflare) {
+            resourcesCreated = await provisionResources(target, plan, notes);
+        }
+        // 6. Local initialisation --------------------------------------------
+        let installed = false;
+        if (options.install) {
+            const installSpinner = p.spinner();
+            installSpinner.start(`${installCommand(manager)}`);
+            const result = await run(manager, ['install'], { cwd: target, timeout: 900_000 });
+            installed = result.ok;
+            if (result.ok)
+                installSpinner.stop('Dependencies installed');
+            else {
+                installSpinner.stop('Dependencies were not installed');
+                notes.push(`${installCommand(manager)} failed (${result.message}) — run it yourself in the project.`);
+            }
+        }
+        if (installed && resourcesCreated)
+            await initialiseLocalDatabase(target, manager, plan, notes);
+        // 7. What is left ----------------------------------------------------
+        const setup = renderSetupMd({
+            plan,
+            runPrefix: runPrefix(manager),
+            installCommand: installCommand(manager),
+            dataset: datasetName,
+            datasetListings: content.listings,
+            resourcesCreated,
+            installed,
+            templateSource,
+        });
+        write(join(target, 'SETUP.md'), setup);
+        p.note([
+            `${content.listings} listings, ${content.blog} blog posts, ${content.logos} logos from "${datasetName}"`,
+            `site.kind: ${plan.identity.kind} · /${plan.identity.listingBase}/ · seo.jsonLd.listing: ${plan.identity.jsonLd}`,
+            `${plan.siteConfig.categories.length} categories, ${plan.siteConfig.tags.length} tags`,
+            ...notes,
+        ].join('\n'), 'Project');
+        const relative = dirName.startsWith('.') || isAbsolute(dirName) ? dirName : `./${dirName}`;
+        p.outro([
+            'Next:',
+            `  cd ${relative}`,
+            installed ? null : `  ${installCommand(manager)}`,
+            `  ${runPrefix(manager)} dev`,
+            '',
+            'SETUP.md lists everything this CLI deliberately left to you.',
+        ]
+            .filter((line) => line !== null)
+            .join('\n'));
+        return 0;
+    }
+    catch (error) {
+        // Nothing reached the "project is written" line, so whatever is in the
+        // directory is a half-copied template. Leaving it behind would only make
+        // the next attempt fail on the non-empty check.
+        if (createdTarget)
+            rmSync(target, { recursive: true, force: true });
+        if (error instanceof CancelledError) {
+            p.cancel('Cancelled — nothing was kept.');
+            return 130;
+        }
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+function writeProjectFiles(target, plan) {
+    const siteConfigPath = join(target, 'site.config.ts');
+    if (!existsSync(siteConfigPath))
+        throw new Error('the template has no site.config.ts — that is not a ZeroDirs template');
+    write(siteConfigPath, rewriteSiteConfig(readFileSync(siteConfigPath, 'utf8'), plan.siteConfig));
+    const wranglerPath = join(target, 'wrangler.jsonc');
+    if (existsSync(wranglerPath))
+        write(wranglerPath, rewriteWranglerConfig(readFileSync(wranglerPath, 'utf8'), plan.wrangler));
+    // `.dev.vars` and `.env` are generated from the template's own example files,
+    // so their key sets stay equal to it by construction (§11.6: `wrangler types`
+    // derives `Env` from `.dev.vars`).
+    const devVarsExample = join(target, '.dev.vars.example');
+    if (existsSync(devVarsExample)) {
+        write(join(target, '.dev.vars'), renderEnvFile(readFileSync(devVarsExample, 'utf8'), { ADMIN_SECRET: randomSecret(), TOKEN_SECRET: randomSecret() }, { blankUnlisted: true }));
+    }
+    const envExample = join(target, '.env.example');
+    if (existsSync(envExample)) {
+        write(join(target, '.env'), renderEnvFile(readFileSync(envExample, 'utf8'), { LISTINGS_SOURCE: 'files' }));
+    }
+    renameProject(join(target, 'package.json'), plan.workerName);
+}
+/** The template's package is `@zerodirs/starter`; the buyer's is theirs. */
+function renameProject(path, name) {
+    if (!existsSync(path))
+        return;
+    const source = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(source);
+    parsed['name'] = name;
+    write(path, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+// ---------------------------------------------------------------------------
+// Cloudflare
+// ---------------------------------------------------------------------------
+async function provisionResources(target, plan, notes) {
+    const spinner = p.spinner();
+    spinner.start('Checking the Cloudflare account');
+    const account = await whoami(target);
+    if (!account.signedIn) {
+        spinner.stop('Not signed in — no resources created');
+        notes.push(`wrangler could not identify an account, so no resources were created. Authenticate it (${WRANGLER_AUTH_DOCS}) and run the commands in SETUP.md.`);
+        return false;
+    }
+    spinner.stop(`Cloudflare: ${account.message}`);
+    spinner.start(`Creating D1 database ${plan.databaseName}`);
+    const d1 = await createD1(target, plan.databaseName);
+    if (!d1.ok) {
+        spinner.stop(`D1 database not created`);
+        notes.push(d1.hint ?? `wrangler d1 create failed: ${d1.reason}`);
+        return false;
+    }
+    spinner.stop(`D1 database ${plan.databaseName} created and bound as DB`);
+    spinner.start(`Creating R2 bucket ${plan.bucketName}`);
+    const r2 = await createR2(target, plan.bucketName);
+    if (!r2.ok) {
+        spinner.stop('R2 bucket not created');
+        notes.push(r2.hint ?? `wrangler r2 bucket create failed: ${r2.reason}`);
+        // The database exists, so the project is usable; only media uploads are not.
+        return false;
+    }
+    spinner.stop(`R2 bucket ${plan.bucketName} created and bound as MEDIA`);
+    return true;
+}
+/**
+ * Local only. `db:migrate:local` and `db:seed:local` both talk to the miniflare
+ * database under `.wrangler/`; nothing here reaches the buyer's account.
+ */
+async function initialiseLocalDatabase(target, manager, plan, notes) {
+    const steps = [
+        { label: 'wrangler types', command: wranglerFor(target).command, args: [...wranglerFor(target).prefix, 'types'] },
+        { label: 'db:migrate:local', command: manager, args: [...runArgs(manager), 'db:migrate:local'] },
+        { label: 'db:seed:local', command: manager, args: [...runArgs(manager), 'db:seed:local', '--dataset', plan.answers.dataset] },
+    ];
+    for (const step of steps) {
+        const spinner = p.spinner();
+        spinner.start(step.label);
+        const result = await run(step.command, step.args, { cwd: target, timeout: 600_000 });
+        if (result.ok)
+            spinner.stop(step.label);
+        else {
+            spinner.stop(`${step.label} failed`);
+            notes.push(`${step.label} failed (${result.message}) — SETUP.md has the command.`);
+            return;
+        }
+    }
+}
+function runArgs(manager) {
+    return manager === 'npm' ? ['run'] : manager === 'yarn' ? [] : ['run'];
+}
+/** Exposed for the `--version` line. */
+export function readOwnVersion(packageJsonPath) {
+    try {
+        if (!existsSync(packageJsonPath) || !statSync(packageJsonPath).isFile())
+            return '0.0.0';
+        return String(JSON.parse(readFileSync(packageJsonPath, 'utf8')).version ?? '0.0.0');
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Deliberately thin: it checks the Node version *before* importing
+ * anything else, because a CLI whose first output is a SyntaxError from inside
+ * a dependency has told the user nothing. The real flow is a dynamic import
+ * that only happens once the runtime is known to be new enough.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { nodeVersionError, parseArgs, USAGE } from './cli/args.js';
+async function main() {
+    const versionProblem = nodeVersionError(process.versions.node);
+    if (versionProblem) {
+        console.error(versionProblem);
+        return 1;
+    }
+    const parsed = parseArgs(process.argv.slice(2));
+    if (!parsed.ok) {
+        console.error(parsed.message);
+        return 1;
+    }
+    const { create, readOwnVersion } = await import('./create.js');
+    if (parsed.options.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (parsed.options.version) {
+        console.log(readOwnVersion(join(dirname(fileURLToPath(import.meta.url)), '../package.json')));
+        return 0;
+    }
+    return create(parsed.options, { cwd: process.cwd(), env: process.env });
+}
+try {
+    process.exitCode = await main();
+}
+catch (error) {
+    console.error(`\ncreate-zerodirs: ${error.message ?? String(error)}`);
+    process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-zerodirs",
+  "version": "0.1.0",
+  "description": "Scaffold a ZeroDirs directory site: pick a dataset, answer a few questions, get a project that builds.",
+  "keywords": ["zerodirs", "directory", "astro", "cloudflare", "starter"],
+  "homepage": "https://docs.zerodirs.com/",
+  "bugs": {
+    "email": "hi@zerodirs.com"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-zerodirs": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "files": ["dist", "README.md"],
+  "packageManager": "pnpm@10.12.4",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.build.json --noEmit",
+    "test": "tsc -p tsconfig.build.json && vitest run"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "execa": "10.0.1",
+    "giget": "3.3.1",
+    "jsonc-parser": "3.3.1",
+    "magicast": "0.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.0",
+    "vitest": "4.1.11"
+  }
+}