create-payload-canvas 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Lominos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# create-payload-canvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://github.com/jon8800/payload-canvas/blob/main/docs/media/drag-and-drop.mp4"><img src="https://raw.githubusercontent.com/jon8800/payload-canvas/main/docs/media/drag-and-drop.gif" width="960" alt="Dragging a section on the canvas while the other sections slide out of the way, reordering it in the Layers tree, and dropping a ready-made section onto the page"></a>
+</p>
+
+Creates a new Payload CMS website builder project from the Payload Canvas starter.
+
+Requirements: Node.js 20.9 or later, a running PostgreSQL server, and pnpm (npm works too). The starter itself is downloaded from GitHub, so the first run needs network access.
+
+```bash
+pnpm create payload-canvas my-website
+# or
+npx create-payload-canvas my-website
+```
+
+The CLI asks for the project name, your Postgres details, and whether to seed demo content. It asks nothing when you pass `--yes`, or when the input is not a terminal (CI, agents). Every question has a flag.
+
+## What it does
+
+1. Checks Postgres first: the server must be reachable, and the database must not exist yet. If something is wrong, it stops before it writes any file.
+2. Copies the starter app (`apps/starter`) and the AI guides it links to (`docs/ai`).
+   - Inside a checkout of the repo, it copies from the checkout.
+   - Anywhere else, it downloads the repo from GitHub (`jon8800/payload-canvas`).
+3. Leaves out repo-only files: `node_modules`, `.next`, `.turbo`, `.env`, `next-env.d.ts`, Docker files (they expect the monorepo), `scripts/setup.ts`, `scripts/lib`, `scripts/_*`, `docs/qa`, screenshots, and uploaded files in `public/media`.
+4. Sets the package name, removes the repo-only scripts and the dev dependencies they needed, and points `payload-canvas` at a source (see below).
+5. Writes `.env` from `.env.example` with your `DATABASE_URL` and a new random `PAYLOAD_SECRET`.
+6. Creates the database.
+7. Installs dependencies with pnpm (npm if pnpm is missing).
+8. Runs `seed:demo` if you chose to seed. On a fresh database the seed creates the tables.
+9. Prints a summary with the exact next commands.
+
+It never runs `payload migrate`. Local development uses `push: true`, so the schema syncs when you run `pnpm dev`.
+
+## Flags
+
+| Flag | Meaning |
+|---|---|
+| `[project-dir]` | Folder to create. Its name is the package name. Lowercase letters, numbers, `-` and `_`. The folder must not exist, or must be empty. Default with `--yes`: `my-website`. |
+| `-y`, `--yes` | Ask nothing. Use defaults. Seeds demo content unless you pass `--no-seed`. |
+| `--db-url <url>` | `postgresql://user:password@host:5432/name`. Replaces the five flags below. |
+| `--db-host <host>` | Default `localhost`. |
+| `--db-port <port>` | Default `5432`. |
+| `--db-user <user>` | Default `postgres`. |
+| `--db-password <pw>` | Default `postgres`. |
+| `--db-name <name>` | Default: the project name, with `_` instead of `-`. |
+| `--reuse-db` | Use the database if it already exists. Without this flag, an existing database is an error. |
+| `--skip-db` | Do not connect to Postgres. Writes `.env` only. This also skips seeding. |
+| `--seed` / `--no-seed` | Seed demo content, or not. |
+| `--no-install` | Do not install. This also skips seeding. |
+| `--github` | Download the starter from GitHub, even when the CLI runs inside a checkout. |
+| `--ref <name>` | Branch or tag to download. Default `main`. |
+| `--packages <path>` | Path to a checkout of the repo. The CLI packs the `payload-canvas` package from there. |
+| `-h`, `--help` | Show help. |
+
+## Where the package comes from
+
+| Case | `payload-canvas` in the new project |
+|---|---|
+| The CLI runs inside a checkout, or you pass `--packages <path>` | a `file:./.tarballs/...` tarball, packed with `pnpm pack` (it builds `dist/` first). Commit `.tarballs/` with the project. |
+| Neither | The version on npm (`^0.1.0`). |
+
+Without `--packages`, and outside a checkout, the CLI checks the npm registry first. If the package is not on npm (for example, a `--ref` with an unreleased version), it stops before it writes any file and tells you to use `--packages <path>` or `--no-install`.
+
+## Examples
+
+```bash
+# Interactive
+pnpm create payload-canvas
+
+# Fully non-interactive, with demo content
+npx create-payload-canvas my-website --yes --db-url postgresql://postgres:postgres@localhost:5432/my_website
+
+# Only the files, no install, no database
+npx create-payload-canvas my-website --yes --no-install --skip-db
+
+# From GitHub, with the package from a local checkout (before it is published)
+npx create-payload-canvas my-website --yes --github --packages C:\code\payload-canvas
+
+# Use a database that already exists
+npx create-payload-canvas my-website --yes --db-name my_site --reuse-db
+```
+
+## After it finishes
+
+```bash
+cd my-website
+pnpm dev
+```
+
+Open http://localhost:3000/admin and create the first user.
+
+Before your first production deploy, run this in the project and commit the new files in `src/migrations`:
+
+```bash
+pnpm payload migrate:create
+```
+
+Migrations belong to your app, not to the plugin. Do not run `payload migrate` on your local database.
+
+## Errors it explains
+
+- Postgres is not running, the host is wrong, or the password is wrong.
+- The database already exists (use `--reuse-db` or another `--db-name`).
+- The folder already exists and is not empty.
+- The `payload-canvas` package is not on npm.
+- The GitHub download fails, or the `--ref` does not exist.
+
+If the copy or pack step fails, the CLI deletes the half-made folder. If the install fails, it keeps the folder so you can fix the problem and run `pnpm install` there.
+
+## Maintainers
+
+- The GitHub owner is `GITHUB_OWNER` in `src/config.ts`. The list of files the CLI leaves out is `SKIP_NAMES` and `SKIP_PATHS` in the same file.
+- After copying, the CLI checks the new project for leftovers (`workspace:` links, paths into `packages/`, `baseUrl`, Docker files) and prints a warning for each one it finds.
+- Build with `pnpm build`. Run from the repo with `node dist/index.js`. `pnpm pack` builds first (`prepack`).

package/dist/config.js

@@ -0,0 +1,36 @@
+// The GitHub repo that hosts Payload Canvas. Change it here if the repo moves.
+export const GITHUB_OWNER = 'jon8800';
+export const GITHUB_REPO = 'payload-canvas';
+export const DEFAULT_REF = 'main';
+export const STARTER_SUBDIR = 'apps/starter';
+// Guides that the starter's .env.example points to. They live at the repo root.
+export const DOCS_SUBDIR = 'docs/ai';
+export function tarballUrl(ref) {
+    return `https://codeload.github.com/${GITHUB_OWNER}/${GITHUB_REPO}/tar.gz/${ref}`;
+}
+// Version range for the payload-canvas package when it comes from npm.
+export const PUBLISHED_VERSION = '^0.1.0';
+// The package the starter depends on: its npm name and its folder under `packages/` in the repo.
+export const BUILDER_PACKAGE = { name: 'payload-canvas', dir: 'payload-canvas' };
+// Files and folders of the starter that only make sense inside the repo. The CLI does not copy them.
+//  - Docker files expect the repo root as build context and the workspace packages.
+//  - `setup.ts` is the repo's own scaffold script; the CLI replaces it.
+//  - `_` scripts are developer test helpers.
+export const SKIP_NAMES = new Set([
+    'node_modules',
+    '.next',
+    '.turbo',
+    '.git',
+    '.env',
+    '.tarballs',
+    '.playwright-mcp',
+    '.claude',
+    'screenshots',
+    'tsconfig.tsbuildinfo',
+    'next-env.d.ts',
+    'Dockerfile',
+    'Dockerfile.dockerignore',
+    'docker-compose.yml',
+]);
+// Paths relative to the starter folder.
+export const SKIP_PATHS = ['scripts/setup.ts', 'scripts/lib', 'docs/qa'];

package/dist/database.js

@@ -0,0 +1,95 @@
+import { Client } from 'pg';
+export function buildDatabaseUrl(db) {
+    const user = encodeURIComponent(db.user);
+    const password = encodeURIComponent(db.password);
+    return `postgresql://${user}:${password}@${db.host}:${db.port}/${db.name}`;
+}
+export function parseDatabaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        throw new Error('The database URL is not valid. Use postgresql://USER:PASSWORD@HOST:PORT/DATABASE', { cause: error });
+    }
+    if (url.protocol !== 'postgresql:' && url.protocol !== 'postgres:') {
+        throw new Error('The database URL must start with postgresql:// or postgres://');
+    }
+    const name = decodeURIComponent(url.pathname.slice(1));
+    if (!name)
+        throw new Error('The database URL has no database name.');
+    return {
+        host: url.hostname || 'localhost',
+        port: Number(url.port || 5432),
+        user: decodeURIComponent(url.username) || 'postgres',
+        password: decodeURIComponent(url.password),
+        name,
+    };
+}
+/** Turns a project name into a safe Postgres database name. */
+export function databaseNameFor(projectName) {
+    return projectName.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'payload_site';
+}
+/** Turns a driver error into a short message that says what to do. Never includes the password. */
+export function describeDbError(error, db) {
+    const code = error?.code;
+    const raw = error instanceof Error ? error.message : String(error);
+    const where = `${db.host}:${db.port}`;
+    switch (code) {
+        case 'ECONNREFUSED':
+        case 'ETIMEDOUT':
+            return `Cannot reach Postgres at ${where}. Start the server, or set --db-host and --db-port (or --db-url). Use --skip-db to continue without a database.`;
+        case 'ENOTFOUND':
+            return `The Postgres host "${db.host}" was not found. Check --db-host (or --db-url).`;
+        case '28P01':
+        case '28000':
+            return `Postgres at ${where} rejected the login for user "${db.user}". Check --db-user and --db-password (or --db-url).`;
+        case '42501':
+            return `User "${db.user}" is not allowed to create databases. Use a user that can, or create "${db.name}" yourself and pass --reuse-db.`;
+        default:
+            return `Postgres error at ${where}: ${raw}`;
+    }
+}
+function connect(db, database) {
+    return new Client({
+        host: db.host,
+        port: db.port,
+        user: db.user,
+        password: db.password,
+        database,
+        connectionTimeoutMillis: 8000,
+    });
+}
+/** Connects to the server and says if the database exists. Throws a clear error when it cannot connect. */
+export async function checkDatabase(db) {
+    const client = connect(db, db.name);
+    client.on('error', () => { });
+    try {
+        await client.connect();
+        return 'exists';
+    }
+    catch (error) {
+        // 3D000: the server is fine, the database does not exist.
+        if (error.code === '3D000')
+            return 'missing';
+        throw new Error(describeDbError(error, db), { cause: error });
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+/** Creates the database. */
+export async function createDatabase(db) {
+    const client = connect(db, 'postgres');
+    client.on('error', () => { });
+    try {
+        await client.connect();
+        await client.query(`CREATE DATABASE "${db.name.replaceAll('"', '""')}"`);
+    }
+    catch (error) {
+        throw new Error(describeDbError(error, db), { cause: error });
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}

package/dist/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BUILDER_PACKAGE } from './config.js';
+import { buildDatabaseUrl, checkDatabase, createDatabase } from './database.js';
+import { resolveOptions } from './options.js';
+import { builderPackageIsPublished, checkProject, hasBuilderPackage, packBuilderPackage, updatePackageJson, writeEnv, } from './project.js';
+import { hasCommand, run } from './run.js';
+import { copyStarterFromRepo, downloadRepo, findRepoRoot, isRepoRoot } from './source.js';
+/** Works out where the starter files and the payload-canvas package come from. Stops early if the install cannot work. */
+async function resolveSource(options) {
+    if (options.packages && !hasBuilderPackage(options.packages)) {
+        throw new Error(`--packages "${options.packages}" is not a Payload Canvas checkout (no packages/${BUILDER_PACKAGE.dir} folder).`);
+    }
+    // A repo checkout also holds the matching starter, so use it unless --github says otherwise.
+    const checkout = options.packages && isRepoRoot(options.packages) ? options.packages : null;
+    const localRepo = options.github ? null : (findRepoRoot() ?? checkout);
+    // Where `pnpm pack` finds the payload-canvas package. Null means: use the version on npm.
+    const packagesRoot = options.packages ?? localRepo;
+    if (!packagesRoot && options.install) {
+        const published = await builderPackageIsPublished();
+        if (published === false) {
+            throw new Error([
+                `${BUILDER_PACKAGE.name} is not published to npm yet, so the install would fail.`,
+                'Pick one:',
+                '  --packages <path-to-a-payload-canvas-checkout>    pack it from a local checkout',
+                '  --no-install                                      only create the files, install later',
+            ].join('\n'));
+        }
+    }
+    return { localRepo, packagesRoot };
+}
+const quote = (value) => (/\s/.test(value) ? `"${value}"` : value);
+async function main() {
+    const options = await resolveOptions();
+    if (!options)
+        return;
+    const { targetDir, name, db } = options;
+    // 0. Check everything that can fail before we write a single file.
+    const { localRepo, packagesRoot } = await resolveSource(options);
+    const manager = hasCommand('pnpm') ? 'pnpm' : 'npm';
+    let dbState = 'missing';
+    if (!options.skipDb) {
+        dbState = await checkDatabase(db);
+        if (dbState === 'exists' && !options.reuseDb) {
+            throw new Error(`The database "${db.name}" already exists on ${db.host}:${db.port}. Pass --reuse-db to use it, or pick another --db-name.`);
+        }
+    }
+    // 1. Copy the starter. 2. Point payload-canvas at a local tarball or at npm. Write .env.
+    // If this part fails, delete the half-made folder so the command can run again.
+    const spinner = p.spinner();
+    let tarball = null;
+    try {
+        fs.mkdirSync(targetDir, { recursive: true });
+        if (localRepo) {
+            spinner.start('Copying the starter from the repo...');
+            copyStarterFromRepo(localRepo, targetDir);
+        }
+        else {
+            spinner.start(`Downloading the starter from GitHub (${options.ref})...`);
+            const downloaded = await downloadRepo(options.ref);
+            try {
+                copyStarterFromRepo(downloaded, targetDir);
+            }
+            finally {
+                fs.rmSync(downloaded, { recursive: true, force: true });
+            }
+        }
+        spinner.stop('Starter files ready.');
+        spinner.start(packagesRoot ? `Packing ${BUILDER_PACKAGE.name}...` : 'Writing package.json and .env...');
+        tarball = packagesRoot ? packBuilderPackage(packagesRoot, targetDir) : null;
+        updatePackageJson(targetDir, name, tarball, manager);
+        writeEnv(targetDir, buildDatabaseUrl(db));
+        spinner.stop('package.json and .env written.');
+    }
+    catch (error) {
+        spinner.error('Failed.');
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        throw error;
+    }
+    for (const problem of checkProject(targetDir))
+        p.log.warn(problem);
+    if (!tarball && !options.install) {
+        p.log.warn(`${BUILDER_PACKAGE.name} comes from npm. It must be published before "${manager} install" works.`);
+    }
+    // 3. Create the database.
+    if (options.skipDb) {
+        p.log.info(`Skipped the database. Put your connection string in ${path.join(targetDir, '.env')}.`);
+    }
+    else if (dbState === 'exists') {
+        p.log.success(`Using the existing database "${db.name}".`);
+    }
+    else {
+        await createDatabase(db);
+        p.log.success(`Created database "${db.name}".`);
+    }
+    // 4. Install. The schema syncs on the first `dev` run (push: true), so there is no migrate step.
+    let installed = false;
+    if (options.install) {
+        p.log.step(`Installing dependencies with ${manager}...`);
+        installed = run(manager, ['install'], targetDir);
+        if (!installed) {
+            throw new Error(`"${manager} install" failed. The project is in ${targetDir}. Fix the error above, then run "${manager} install" there.`);
+        }
+    }
+    // 5. Seed.
+    let seeded = false;
+    if (options.seed) {
+        p.log.step('Seeding demo content...');
+        seeded = run(manager, ['run', 'seed:demo'], targetDir);
+        if (!seeded)
+            p.log.warn(`Seeding failed. Run "${manager} run seed:demo" in ${targetDir} to try again.`);
+    }
+    // 6. Summary.
+    const relative = path.relative(process.cwd(), targetDir);
+    const cdTarget = !relative ? null : relative.startsWith('..') || path.isAbsolute(relative) ? targetDir : relative;
+    const run_ = manager === 'pnpm' ? 'pnpm' : 'npm run';
+    const lines = [
+        `Project:   ${targetDir}`,
+        options.skipDb ? 'Database:  not set up (--skip-db)' : `Database:  ${db.name} on ${db.host}:${db.port}`,
+        `Demo data: ${seeded ? 'seeded' : 'not seeded'}`,
+        '',
+        'Next steps:',
+        ...[
+            cdTarget ? `cd ${quote(cdTarget)}` : null,
+            options.install ? null : `${manager} install`,
+            options.skipDb ? 'Set DATABASE_URL in .env' : null,
+            `${run_} dev`,
+        ]
+            .filter((step) => step !== null)
+            .map((step) => `  ${step}`),
+        '  Open http://localhost:3000/admin and create the first user.',
+        '',
+        'Do not run "payload migrate" on the local database. "dev" syncs the schema.',
+        'Before your first production deploy, run this in the project:',
+        `  ${manager === 'pnpm' ? 'pnpm' : 'npx'} payload migrate:create`,
+        'Commit the new files in src/migrations. Migrations belong to your app, not the plugin.',
+    ];
+    p.note(lines.join('\n'), 'Done');
+    p.outro('Your project is ready.');
+}
+main().catch((error) => {
+    p.log.error(error instanceof Error ? error.message : String(error));
+    p.cancel('Setup failed.');
+    process.exit(1);
+});

package/dist/options.js

@@ -0,0 +1,187 @@
+import * as p from '@clack/prompts';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { DEFAULT_REF } from './config.js';
+import { databaseNameFor, parseDatabaseUrl } from './database.js';
+export const HELP = `Usage: create-payload-canvas [project-dir] [flags]
+
+Creates a Payload CMS website with the Payload Canvas builder. Nothing is asked when you pass --yes
+or when the input is not a terminal.
+
+Project:
+  -y, --yes                 Use defaults and ask nothing
+      --no-install          Do not install dependencies (this also skips seeding)
+      --seed / --no-seed    Seed demo content (default: yes with --yes, else ask)
+
+Database (default user and password: postgres):
+      --db-url <url>        postgresql://user:pass@host:5432/name (replaces the flags below)
+      --db-host <host>      Default: localhost
+      --db-port <port>      Default: 5432
+      --db-user <user>
+      --db-password <pw>
+      --db-name <name>      Default: the project name with underscores
+      --reuse-db            Use the database if it already exists (default: stop with an error)
+      --skip-db             Do not connect to Postgres. Writes .env only. Skips seeding.
+
+Source:
+      --github              Download the starter from GitHub, even inside the repo
+      --ref <name>          Branch or tag to download (default: ${DEFAULT_REF})
+      --packages <path>     Path to a Payload Canvas checkout. The payload-canvas package is
+                            packed from there. Use this until it is published to npm.
+
+  -h, --help                Show this help
+`;
+function parseFlags() {
+    return parseArgs({
+        allowPositionals: true,
+        options: {
+            yes: { type: 'boolean', short: 'y' },
+            'db-url': { type: 'string' },
+            'db-host': { type: 'string' },
+            'db-port': { type: 'string' },
+            'db-user': { type: 'string' },
+            'db-password': { type: 'string' },
+            'db-name': { type: 'string' },
+            'reuse-db': { type: 'boolean' },
+            'skip-db': { type: 'boolean' },
+            seed: { type: 'boolean' },
+            'no-seed': { type: 'boolean' },
+            'no-install': { type: 'boolean' },
+            github: { type: 'boolean' },
+            ref: { type: 'string' },
+            packages: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+}
+function cancelled() {
+    p.cancel('Cancelled.');
+    process.exit(0);
+}
+async function ask(prompt) {
+    const value = await prompt;
+    if (typeof value !== 'string')
+        cancelled();
+    return value;
+}
+function validateName(value) {
+    if (!value || !/^[a-z0-9][a-z0-9-_]*$/.test(value)) {
+        return 'Use lowercase letters, numbers, hyphens and underscores.';
+    }
+}
+function validateTarget(dir) {
+    if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory())
+        return `"${dir}" exists and is a file.`;
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) {
+        return `The folder "${dir}" already exists and is not empty. Pick another name, or delete it.`;
+    }
+}
+/** Reads flags, asks for anything missing, and returns the final options. Returns null after --help. */
+export async function resolveOptions() {
+    let parsed;
+    try {
+        parsed = parseFlags();
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}\nRun with --help to see the flags.`, { cause: error });
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        console.log(HELP);
+        return null;
+    }
+    p.intro('Create Payload Canvas');
+    // Without a terminal nobody can answer a prompt, so use the defaults.
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const yes = values.yes === true || !interactive;
+    if (!interactive && values.yes !== true)
+        p.log.info('No terminal found. Using defaults for everything you did not pass as a flag.');
+    // Project directory and name.
+    let dirInput = positionals[0];
+    if (!dirInput) {
+        dirInput = yes
+            ? 'my-website'
+            : await ask(p.text({
+                message: 'Project name (also the folder name)',
+                placeholder: 'my-website',
+                defaultValue: 'my-website',
+                validate: (value) => {
+                    const text = value || 'my-website';
+                    return validateName(text) ?? validateTarget(path.resolve(process.cwd(), text));
+                },
+            }));
+    }
+    const targetDir = path.resolve(process.cwd(), dirInput);
+    const name = path.basename(targetDir);
+    const nameError = validateName(name) ?? validateTarget(targetDir);
+    if (nameError)
+        throw new Error(nameError);
+    // Database.
+    const skipDb = values['skip-db'] === true;
+    let db;
+    if (values['db-url']) {
+        db = parseDatabaseUrl(values['db-url']);
+    }
+    else {
+        const field = async (flag, message, fallback, secret = false) => {
+            if (flag !== undefined)
+                return flag;
+            if (yes || skipDb)
+                return fallback;
+            if (secret)
+                return ask(p.password({ message }));
+            return ask(p.text({ message, placeholder: fallback, defaultValue: fallback }));
+        };
+        const host = await field(values['db-host'], 'Postgres host', 'localhost');
+        const port = await field(values['db-port'], 'Postgres port', '5432');
+        const user = await field(values['db-user'], 'Postgres user', 'postgres');
+        const password = await field(values['db-password'], 'Postgres password', 'postgres', true);
+        const dbName = await field(values['db-name'], 'Database name', databaseNameFor(name));
+        if (!/^\d+$/.test(port) || Number(port) > 65535)
+            throw new Error(`"${port}" is not a valid Postgres port.`);
+        db = { host, port: Number(port), user, password, name: dbName };
+    }
+    if (values['db-name'] && values['db-url'])
+        db.name = values['db-name'];
+    // Source.
+    const packages = values.packages ? path.resolve(process.cwd(), values.packages) : null;
+    // Install and seed.
+    const install = values['no-install'] !== true;
+    const canSeed = install && !skipDb;
+    let seed;
+    if (values['no-seed']) {
+        seed = false;
+    }
+    else if (values.seed) {
+        seed = true;
+    }
+    else if (!canSeed) {
+        seed = false;
+    }
+    else if (yes) {
+        seed = true;
+    }
+    else {
+        const answer = await p.confirm({ message: 'Seed demo content?', initialValue: true });
+        if (p.isCancel(answer))
+            cancelled();
+        seed = answer;
+    }
+    if (seed && !canSeed) {
+        p.log.warn(`Seeding needs installed dependencies and a database, so ${skipDb ? '--skip-db' : '--no-install'} turns it off.`);
+        seed = false;
+    }
+    return {
+        targetDir,
+        name,
+        db,
+        seed,
+        install,
+        skipDb,
+        reuseDb: values['reuse-db'] === true,
+        github: values.github === true,
+        ref: values.ref ?? DEFAULT_REF,
+        packages,
+    };
+}

package/dist/project.js

@@ -0,0 +1,115 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BUILDER_PACKAGE, PUBLISHED_VERSION } from './config.js';
+import { capture } from './run.js';
+function readPackageJson(dir) {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+}
+/** Checks that `<root>/packages/payload-canvas` exists. */
+export function hasBuilderPackage(root) {
+    return fs.existsSync(path.join(root, 'packages', BUILDER_PACKAGE.dir, 'package.json'));
+}
+/**
+ * Packs payload-canvas from a repo checkout into `<target>/.tarballs` and returns the file name.
+ * `pnpm pack` runs the package's `prepack` script, which builds `dist/` first.
+ */
+export function packBuilderPackage(repoRoot, targetDir) {
+    const destination = path.join(targetDir, '.tarballs');
+    fs.mkdirSync(destination, { recursive: true });
+    const dir = path.join(repoRoot, 'packages', BUILDER_PACKAGE.dir);
+    const result = capture('pnpm', ['pack', '--pack-destination', destination], dir);
+    if (!result.ok)
+        throw new Error(`"pnpm pack" failed in ${dir}:\n${result.error}`);
+    const file = `${BUILDER_PACKAGE.name}-${readPackageJson(dir).version ?? '0.0.0'}.tgz`;
+    if (!fs.existsSync(path.join(destination, file)))
+        throw new Error(`Expected tarball ${file} was not created.`);
+    return file;
+}
+/** Asks the npm registry if payload-canvas exists. Returns null when the registry cannot be reached. */
+export async function builderPackageIsPublished() {
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${BUILDER_PACKAGE.name}`, {
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (response.status === 404)
+            return false;
+        return response.ok ? true : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if any source file in the project imports the package. */
+function isImported(targetDir, pkg) {
+    const pattern = new RegExp(`from\\s+['"]${pkg}(/[^'"]*)?['"]|require\\(['"]${pkg}['"]\\)`);
+    const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).some((entry) => {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return !SKIP_DIRS.has(entry.name) && walk(full);
+        return /\.(m?[jt]sx?)$/.test(entry.name) && pattern.test(fs.readFileSync(full, 'utf8'));
+    });
+    return walk(targetDir);
+}
+const SKIP_DIRS = new Set(['node_modules', '.next', '.tarballs']);
+export function updatePackageJson(targetDir, name, tarball, manager) {
+    const file = path.join(targetDir, 'package.json');
+    const pkg = readPackageJson(targetDir);
+    pkg.name = name;
+    pkg.version = '0.1.0';
+    delete pkg.private;
+    // Repo-only scripts: the repo's own scaffold script and `_` developer test helpers.
+    for (const key of Object.keys(pkg.scripts ?? {})) {
+        if (key === 'setup' || key.startsWith('_'))
+            delete pkg.scripts?.[key];
+    }
+    // Only the removed scaffold script used these packages. Keep them if the app imports them.
+    for (const dep of ['@clack/prompts', 'pg', '@types/pg']) {
+        if (pkg.devDependencies?.[dep] && !isImported(targetDir, dep.replace('@types/', ''))) {
+            delete pkg.devDependencies[dep];
+        }
+    }
+    pkg.dependencies = {
+        ...pkg.dependencies,
+        [BUILDER_PACKAGE.name]: tarball ? `file:./.tarballs/${tarball}` : PUBLISHED_VERSION,
+    };
+    // The build-script list lets pnpm 10 run the install scripts that the dependencies need.
+    if (manager === 'pnpm')
+        pkg.pnpm = { ...pkg.pnpm, onlyBuiltDependencies: ['esbuild', 'sharp', 'unrs-resolver'] };
+    fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+const secret = () => crypto.randomBytes(32).toString('hex');
+const set = (content, key, value) => content.replace(new RegExp(`^${key}=.*$`, 'm'), () => `${key}=${value}`);
+export function writeEnv(targetDir, databaseUrl) {
+    const example = path.join(targetDir, '.env.example');
+    if (!fs.existsSync(example))
+        throw new Error('.env.example not found in the template.');
+    let content = fs.readFileSync(example, 'utf8');
+    content = set(content, 'DATABASE_URL', databaseUrl);
+    content = set(content, 'PAYLOAD_SECRET', secret());
+    content = set(content, 'NEXT_PUBLIC_SERVER_URL', 'http://localhost:3000');
+    fs.writeFileSync(path.join(targetDir, '.env'), content);
+}
+/** Looks for repo-only leftovers in the generated project. Returns one message per problem. */
+export function checkProject(targetDir) {
+    const problems = [];
+    const read = (file) => {
+        const full = path.join(targetDir, file);
+        return fs.existsSync(full) ? fs.readFileSync(full, 'utf8') : '';
+    };
+    const manifest = read('package.json');
+    if (manifest.includes('workspace:'))
+        problems.push('package.json still has a "workspace:" dependency.');
+    if (/\.\.\/(\.\.\/)*packages\//.test(read('next.config.ts') + read('tsconfig.json'))) {
+        problems.push('next.config.ts or tsconfig.json still points into ../packages/.');
+    }
+    if (/"baseUrl"/.test(read('tsconfig.json')))
+        problems.push('tsconfig.json has "baseUrl", which TypeScript 7 removed.');
+    const leftovers = ['Dockerfile', 'docker-compose.yml', 'scripts/setup.ts', 'docs/qa', 'screenshots', '.next', 'node_modules'];
+    for (const item of leftovers) {
+        if (fs.existsSync(path.join(targetDir, item)))
+            problems.push(`"${item}" should not be in the generated project.`);
+    }
+    return problems;
+}

package/dist/run.js

@@ -0,0 +1,16 @@
+import spawn from 'cross-spawn';
+/** Runs a command, shows its output, and returns true if it exits with code 0. */
+export function run(command, args, cwd) {
+    return spawn.sync(command, args, { cwd, stdio: 'inherit' }).status === 0;
+}
+/** Runs a command and returns its output. On failure it returns null and the error text. */
+export function capture(command, args, cwd) {
+    const result = spawn.sync(command, args, { cwd, encoding: 'utf8' });
+    if (result.status === 0)
+        return { ok: true, stdout: String(result.stdout) };
+    const error = result.error?.message ?? (String(result.stderr).trim() || `exit code ${result.status}`);
+    return { ok: false, error };
+}
+export function hasCommand(command) {
+    return spawn.sync(command, ['--version'], { stdio: 'ignore' }).status === 0;
+}

package/dist/source.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+import { x as extractTar } from 'tar';
+import { DOCS_SUBDIR, GITHUB_OWNER, GITHUB_REPO, SKIP_NAMES, SKIP_PATHS, STARTER_SUBDIR, tarballUrl } from './config.js';
+/** True for files that must not be copied. `rel` is relative to the starter folder, with `/` separators. */
+function shouldSkip(rel) {
+    const parts = rel.split('/').filter(Boolean);
+    if (parts.some((part) => SKIP_NAMES.has(part)))
+        return true;
+    if (SKIP_PATHS.some((skip) => rel === skip || rel.startsWith(`${skip}/`)))
+        return true;
+    // Developer test helpers, such as scripts/_dev-user.ts.
+    if (parts[0] === 'scripts' && parts[1]?.startsWith('_'))
+        return true;
+    // Uploaded files: keep the folder, drop the files.
+    return parts[0] === 'public' && parts[1] === 'media' && parts.length > 2;
+}
+export function isRepoRoot(dir) {
+    return fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) && fs.existsSync(path.join(dir, STARTER_SUBDIR, 'package.json'));
+}
+/** Finds the repo root when the CLI file lives inside the Payload Canvas repo. */
+export function findRepoRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        if (isRepoRoot(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Copies the starter, and the AI guides it links to, from a repo checkout into `targetDir`. */
+export function copyStarterFromRepo(repoRoot, targetDir) {
+    const source = path.join(repoRoot, STARTER_SUBDIR);
+    fs.cpSync(source, targetDir, {
+        recursive: true,
+        filter: (src) => !shouldSkip(path.relative(source, src).split(path.sep).join('/')),
+    });
+    const docs = path.join(repoRoot, DOCS_SUBDIR);
+    if (fs.existsSync(docs))
+        fs.cpSync(docs, path.join(targetDir, DOCS_SUBDIR), { recursive: true });
+    ensureMediaFolder(targetDir);
+}
+/**
+ * Downloads the repo from GitHub and unpacks only the starter and the AI guides into a temp folder.
+ * The result has the same layout as a repo checkout. The caller deletes it.
+ */
+export async function downloadRepo(ref) {
+    const url = tarballUrl(ref);
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+    }
+    catch (error) {
+        throw new Error(`Could not reach GitHub (${error instanceof Error ? error.message : String(error)}). Check your network, or run the CLI from a Payload Canvas checkout.`, { cause: error });
+    }
+    if (response.status === 404) {
+        throw new Error(`Branch or tag "${ref}" was not found in ${GITHUB_OWNER}/${GITHUB_REPO}.`);
+    }
+    if (!response.ok || !response.body)
+        throw new Error(`Download failed (HTTP ${response.status}) from ${url}`);
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'create-payload-canvas-'));
+    try {
+        // GitHub puts everything in one top folder, `strip: 1` removes it.
+        const wanted = [`${STARTER_SUBDIR}/`, `${DOCS_SUBDIR}/`];
+        await pipeline(Readable.fromWeb(response.body), extractTar({
+            cwd: temp,
+            strip: 1,
+            filter: (entryPath) => {
+                const inner = entryPath.split('/').slice(1).join('/');
+                return wanted.some((prefix) => inner.startsWith(prefix));
+            },
+        }));
+    }
+    catch (error) {
+        fs.rmSync(temp, { recursive: true, force: true });
+        throw error;
+    }
+    if (!fs.existsSync(path.join(temp, STARTER_SUBDIR, 'package.json'))) {
+        fs.rmSync(temp, { recursive: true, force: true });
+        throw new Error(`The download has no ${STARTER_SUBDIR} folder. Is "${ref}" the right branch?`);
+    }
+    return temp;
+}
+/** Makes sure `public/media` exists, so uploads work on the first run. */
+function ensureMediaFolder(targetDir) {
+    const media = path.join(targetDir, 'public', 'media');
+    fs.mkdirSync(media, { recursive: true });
+    fs.writeFileSync(path.join(media, '.gitkeep'), '');
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "create-payload-canvas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Create a new Payload CMS website with Payload Canvas: the visual page builder, Postgres, a seeded demo and the AI guides.",
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "create",
+    "scaffold",
+    "starter",
+    "template",
+    "website-builder",
+    "page-builder",
+    "nextjs",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Eugene Lominos <hello@eugenelominos.com>",
+  "homepage": "https://github.com/jon8800/payload-canvas/tree/main/packages/create-payload-canvas#readme",
+  "bugs": "https://github.com/jon8800/payload-canvas/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jon8800/payload-canvas.git",
+    "directory": "packages/create-payload-canvas"
+  },
+  "type": "module",
+  "bin": {
+    "create-payload-canvas": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "cross-spawn": "^7.0.6",
+    "pg": "^8.23.1",
+    "tar": "^7.5.22"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^24.19.1",
+    "@types/pg": "^8.23.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  }
 }