create-payload-canvas 0.4.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ pnpm create payload-canvas my-website
 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.
+The CLI asks for the project name, your Postgres details, which starter features to keep, 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
 
@@ -22,16 +22,31 @@ The CLI asks for the project name, your Postgres details, and whether to seed de
 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.
+3. Leaves out repo-only files: `node_modules`, `.next`, `.turbo`, `.env`, `next-env.d.ts`, Docker files (they expect the monorepo), `scripts/setup.ts` and its helpers `scripts/lib/create-database.ts` and `scripts/lib/generate-env.ts`, `scripts/_*`, `docs/qa`, screenshots, and uploaded files in `public/media`.
+4. Removes the starter features you left out (see [Features](#features)).
+5. Sets the package name, removes the repo-only scripts and the dev dependencies they needed, and points `payload-canvas` at a source (see below).
+6. Writes `.env` from `.env.example` with your `DATABASE_URL` and a new random `PAYLOAD_SECRET`.
+7. Creates the database.
+8. Installs dependencies with pnpm (npm if pnpm is missing).
+9. Runs `seed:demo` if you chose to seed. On a fresh database the seed creates the tables. Without the demo seed, it runs `seed:classes`, which adds the editable classes that the ready-made sections use.
+10. 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`.
 
+## Features
+
+The starter has a few parts you can leave out. All of them are kept by default. Without `--yes`, the CLI shows a list with all of them checked. Uncheck the ones you do not want. A `--no-<feature>` flag leaves a feature out without asking.
+
+| Feature | Flag | What you lose |
+|---|---|---|
+| Admin look | `--no-look` | Neutral colors and finer details in the admin (`src/admin/look`). |
+| Sidebar navigation | `--no-nav` | The grouped sidebar with icons (`src/admin/nav`). The admin uses Payload's default sidebar. |
+| Dashboard widgets | `--no-dashboard` | Quick actions, recent edits, drafts, form messages, site checks, scheduled publishes and analytics (`src/admin/dashboard`). The admin shows Payload's collection cards. |
+| Demo content | `--no-demo` | The demo pages, posts and images seed (`scripts/seed-demo.ts` and the `seed:demo` script). This also turns off seeding. |
+| AI assistant | `--no-ai` | The chat panel in the page builder, and its settings in `.env`. |
+
+The CLI deletes the feature's files and removes its lines from `src/payload.config.ts`, `src/app/(payload)/custom.scss`, `.env.example` and the admin import map. The project type-checks with any mix of features.
+
 ## Flags
 
 | Flag | Meaning |
@@ -48,6 +63,7 @@ It never runs `payload migrate`. Local development uses `push: true`, so the sch
 | `--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. |
+| `--no-look`, `--no-nav`, `--no-dashboard`, `--no-demo`, `--no-ai` | Leave out a starter feature. See [Features](#features). `--no-demo` also turns off 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. |
@@ -58,7 +74,7 @@ It never runs `payload migrate`. Local development uses `push: true`, so the sch
 | 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.4.0`). |
+| Neither | The version on npm (`^0.5.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`.
 
@@ -74,6 +90,9 @@ npx create-payload-canvas my-website --yes --db-url postgresql://postgres:postgr
 # Only the files, no install, no database
 npx create-payload-canvas my-website --yes --no-install --skip-db
 
+# Without the AI assistant and the demo content
+npx create-payload-canvas my-website --yes --no-ai --no-demo
+
 # 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
 
@@ -111,5 +130,7 @@ If the copy or pack step fails, the CLI deletes the half-made folder. If the ins
 ## 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.
+- The starter's `starter-features.json` lists each feature's files and scripts. In code, a line with `@feature:<id>` starts a part that belongs to a feature, and a line with `@end:<id>` ends it. The prompt and the flags come from `FEATURES` in `src/config.ts`. Add a new feature in both places.
+- `pnpm check:features` copies the starter for every mix of features, applies it, and runs the starter's TypeScript check. Run it after you change a feature. `pnpm test` runs the unit tests.
 - 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

@@ -9,12 +9,13 @@ 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.4.0';
+export const PUBLISHED_VERSION = '^0.5.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.
+//  - `setup.ts` is the repo's own scaffold script; the CLI replaces it. The two `scripts/lib` files
+//    were its helpers. Keep `scripts/lib/classes.ts`: the seed scripts import it.
 //  - `_` scripts are developer test helpers.
 export const SKIP_NAMES = new Set([
     'node_modules',
@@ -33,4 +34,14 @@ export const SKIP_NAMES = new Set([
     'docker-compose.yml',
 ]);
 // Paths relative to the starter folder.
-export const SKIP_PATHS = ['scripts/setup.ts', 'scripts/lib', 'docs/qa'];
+export const SKIP_PATHS = ['scripts/setup.ts', 'scripts/lib/create-database.ts', 'scripts/lib/generate-env.ts', 'docs/qa'];
+// Starter features the user can turn off. The CLI asks about these and has a `--no-<id>` flag for each.
+// The starter's `starter-features.json` says which files, config lines and scripts belong to each one.
+// A feature in that file but not in this list is always kept.
+export const FEATURES = [
+    { id: 'look', label: 'Admin look', hint: 'Neutral colors and finer details in the admin' },
+    { id: 'nav', label: 'Sidebar navigation', hint: 'Grouped sidebar with icons' },
+    { id: 'dashboard', label: 'Dashboard widgets', hint: 'Quick actions, recent edits, form messages, site checks, analytics' },
+    { id: 'demo', label: 'Demo content', hint: 'The demo pages, posts and images seed' },
+    { id: 'ai', label: 'AI assistant', hint: 'The chat panel in the page builder' },
+];

package/dist/features.js

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FEATURES } from './config.js';
+/**
+ * The starter's list of features. Each one names the files and scripts to delete when it is off.
+ * Labels and hints for the prompt are in `FEATURES` (config.ts).
+ */
+export const MANIFEST_FILE = 'starter-features.json';
+/** Payload writes this file. It imports every admin component by path. */
+export const IMPORT_MAP_FILE = 'src/app/(payload)/admin/importMap.js';
+const OPEN = /@feature:([\w-]+)/;
+const CLOSE = /@end:([\w-]+)/;
+const SKIP_DIRS = new Set(['node_modules', '.next', '.turbo', '.git', '.tarballs']);
+/**
+ * Removes the marked regions of features that are off. A line with `@feature:<id>` opens a region
+ * and a line with `@end:<id>` closes it. The marker lines always go. The lines between them go
+ * when `<id>` is not in `enabledIds`. `file` only makes error messages clearer.
+ */
+export function stripRegions(text, enabledIds, file = 'text') {
+    const enabled = new Set(enabledIds);
+    const open = [];
+    const kept = [];
+    const lines = text.split('\n');
+    lines.forEach((line, index) => {
+        const start = OPEN.exec(line);
+        if (start) {
+            open.push({ id: start[1], line: index + 1 });
+            return;
+        }
+        const end = CLOSE.exec(line);
+        if (end) {
+            const last = open.pop();
+            if (!last)
+                throw new Error(`${file}:${index + 1}: "@end:${end[1]}" has no matching "@feature:${end[1]}".`);
+            if (last.id !== end[1]) {
+                throw new Error(`${file}:${index + 1}: "@end:${end[1]}" closes "@feature:${last.id}" from line ${last.line}.`);
+            }
+            return;
+        }
+        if (open.every((region) => enabled.has(region.id)))
+            kept.push(line);
+    });
+    const unclosed = open.pop();
+    if (unclosed)
+        throw new Error(`${file}:${unclosed.line}: "@feature:${unclosed.id}" is never closed with "@end:${unclosed.id}".`);
+    return kept.join('\n');
+}
+/** The part of a deleted `src/` path that importMap.js uses, e.g. `src/admin/nav` -> `/admin/nav`. */
+function importMapKey(removedPath) {
+    const rel = removedPath.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (!rel.startsWith('src/'))
+        return null;
+    return rel.slice('src'.length).replace(/\.[cm]?[jt]sx?$/, '');
+}
+/**
+ * Removes the importMap.js lines that point into deleted files or folders: the import lines
+ * and the map entries. `removedPaths` are relative to the project root, like `src/admin/nav`.
+ */
+export function stripImportMap(text, removedPaths) {
+    const keys = removedPaths.map(importMapKey).filter((key) => key !== null);
+    if (keys.length === 0)
+        return text;
+    // The key must end at a path separator, a quote or the `#export` part, so `/admin/nav` does not match `/admin/navbar`.
+    const pointsIntoRemoved = (line) => keys.some((key) => {
+        let at = line.indexOf(key);
+        while (at !== -1) {
+            if (/^[/'"#]/.test(line.slice(at + key.length)))
+                return true;
+            at = line.indexOf(key, at + 1);
+        }
+        return false;
+    });
+    return text
+        .split('\n')
+        .filter((line) => !pointsIntoRemoved(line))
+        .join('\n');
+}
+/** Reads `starter-features.json`. Returns null when the starter has none (older versions). */
+export function readManifest(targetDir) {
+    const file = path.join(targetDir, MANIFEST_FILE);
+    if (!fs.existsSync(file))
+        return null;
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!Array.isArray(manifest.features))
+        throw new Error(`${MANIFEST_FILE} has no "features" list.`);
+    return manifest;
+}
+/** Resolves a manifest path inside the project. Throws if it points outside. */
+function resolveInside(targetDir, rel) {
+    const full = path.resolve(targetDir, rel);
+    const back = path.relative(targetDir, full);
+    if (!back || back.startsWith('..') || path.isAbsolute(back))
+        throw new Error(`${MANIFEST_FILE}: "${rel}" is outside the project.`);
+    return full;
+}
+/** All files under `dir`, without dependency and build folders. */
+function listFiles(dir) {
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return SKIP_DIRS.has(entry.name) ? [] : listFiles(full);
+        return entry.isFile() ? [full] : [];
+    });
+}
+/** The project files that hold `@feature:` or `@end:` markers, with their text. */
+export function filesWithMarkers(targetDir) {
+    return listFiles(targetDir).flatMap((file) => {
+        const buffer = fs.readFileSync(file);
+        if (buffer.includes(0))
+            return []; // binary file
+        const text = buffer.toString('utf8');
+        return OPEN.test(text) || CLOSE.test(text) ? [{ file, text }] : [];
+    });
+}
+/**
+ * Turns the starter's features on or off in a copied project. For each known feature that is not in
+ * `enabledIds`, it deletes the feature's files, its package.json scripts, its marked regions and its
+ * importMap.js lines. Then it deletes `starter-features.json`.
+ * Returns the ids it turned off, or null when the starter has no manifest (then it changes nothing).
+ */
+export function applyFeatures(targetDir, enabledIds) {
+    const manifest = readManifest(targetDir);
+    if (!manifest)
+        return null;
+    const enabled = new Set(enabledIds);
+    const known = new Set(FEATURES.map((feature) => feature.id));
+    const off = manifest.features.filter((feature) => known.has(feature.id) && !enabled.has(feature.id));
+    const offIds = new Set(off.map((feature) => feature.id));
+    const keptIds = manifest.features.map((feature) => feature.id).filter((id) => !offIds.has(id));
+    // Marked regions. Do this before deleting files, so a bad marker stops everything early.
+    for (const { file, text } of filesWithMarkers(targetDir)) {
+        const rel = path.relative(targetDir, file).split(path.sep).join('/');
+        for (const match of text.matchAll(/@(?:feature|end):([\w-]+)/g)) {
+            if (!manifest.features.some((feature) => feature.id === match[1])) {
+                throw new Error(`${rel} marks "${match[1]}", but ${MANIFEST_FILE} has no feature with that id.`);
+            }
+        }
+        fs.writeFileSync(file, stripRegions(text, keptIds, rel));
+    }
+    // Files and folders.
+    const removedPaths = off.flatMap((feature) => feature.paths);
+    for (const rel of removedPaths)
+        fs.rmSync(resolveInside(targetDir, rel), { recursive: true, force: true });
+    const importMap = path.join(targetDir, IMPORT_MAP_FILE);
+    if (removedPaths.length > 0 && fs.existsSync(importMap)) {
+        fs.writeFileSync(importMap, stripImportMap(fs.readFileSync(importMap, 'utf8'), removedPaths));
+    }
+    // package.json scripts.
+    const scripts = off.flatMap((feature) => feature.scripts ?? []);
+    const pkgFile = path.join(targetDir, 'package.json');
+    if (scripts.length > 0 && fs.existsSync(pkgFile)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+        for (const name of scripts)
+            delete pkg.scripts?.[name];
+        fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+    fs.rmSync(path.join(targetDir, MANIFEST_FILE));
+    return [...offIds];
+}

package/dist/index.js

@@ -2,8 +2,9 @@
 import * as p from '@clack/prompts';
 import fs from 'node:fs';
 import path from 'node:path';
-import { BUILDER_PACKAGE } from './config.js';
+import { BUILDER_PACKAGE, FEATURES } from './config.js';
 import { buildDatabaseUrl, checkDatabase, createDatabase } from './database.js';
+import { applyFeatures } from './features.js';
 import { resolveOptions } from './options.js';
 import { builderPackageIsPublished, checkProject, hasBuilderPackage, packBuilderPackage, updatePackageJson, writeEnv, } from './project.js';
 import { hasCommand, run } from './run.js';
@@ -47,10 +48,12 @@ async function main() {
             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.
+    // 1. Copy the starter and remove the features the user left out. 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;
+    let removed = null;
     try {
         fs.mkdirSync(targetDir, { recursive: true });
         if (localRepo) {
@@ -67,7 +70,10 @@ async function main() {
                 fs.rmSync(downloaded, { recursive: true, force: true });
             }
         }
+        removed = applyFeatures(targetDir, options.features);
         spinner.stop('Starter files ready.');
+        if (!removed)
+            p.log.warn('This starter version has no feature list, so all features are kept.');
         spinner.start(packagesRoot ? `Packing ${BUILDER_PACKAGE.name}...` : 'Writing package.json and .env...');
         tarball = packagesRoot ? packBuilderPackage(packagesRoot, targetDir) : null;
         updatePackageJson(targetDir, name, tarball, manager);
@@ -112,6 +118,13 @@ async function main() {
         if (!seeded)
             p.log.warn(`Seeding failed. Run "${manager} run seed:demo" in ${targetDir} to try again.`);
     }
+    else if (installed && !options.skipDb) {
+        // The ready-made sections use the site's editable classes (card, button-primary...): add them
+        // without the demo pages, or the sections look unstyled.
+        p.log.step('Adding the editable classes...');
+        if (!run(manager, ['run', 'seed:classes'], targetDir))
+            p.log.warn(`Adding the classes failed. Run "${manager} run seed:classes" 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;
@@ -120,6 +133,7 @@ async function main() {
         `Project:   ${targetDir}`,
         options.skipDb ? 'Database:  not set up (--skip-db)' : `Database:  ${db.name} on ${db.host}:${db.port}`,
         `Demo data: ${seeded ? 'seeded' : 'not seeded'}`,
+        `Features:  ${FEATURES.filter((feature) => !removed?.includes(feature.id)).map((feature) => feature.label).join(', ') || 'none'}`,
         '',
         'Next steps:',
         ...[

package/dist/options.js

@@ -2,7 +2,7 @@ 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 { DEFAULT_REF, FEATURES } from './config.js';
 import { databaseNameFor, parseDatabaseUrl } from './database.js';
 export const HELP = `Usage: create-payload-canvas [project-dir] [flags]
 
@@ -14,6 +14,13 @@ Project:
       --no-install          Do not install dependencies (this also skips seeding)
       --seed / --no-seed    Seed demo content (default: yes with --yes, else ask)
 
+Features (all kept by default; without --yes the CLI asks about the ones you did not pass):
+      --no-look             Leave out the admin look (neutral colors, finer details)
+      --no-nav              Leave out the grouped sidebar navigation
+      --no-dashboard        Leave out the dashboard widgets
+      --no-demo             Leave out the demo content seed (this also turns off seeding)
+      --no-ai               Leave out the AI assistant in the page builder
+
 Database (default user and password: postgres):
       --db-url <url>        postgresql://user:pass@host:5432/name (replaces the flags below)
       --db-host <host>      Default: localhost
@@ -32,6 +39,8 @@ Source:
 
   -h, --help                Show this help
 `;
+// One `--no-<id>` flag per starter feature.
+const featureFlags = Object.fromEntries(FEATURES.map((feature) => [`no-${feature.id}`, { type: 'boolean' }]));
 function parseFlags() {
     return parseArgs({
         allowPositionals: true,
@@ -48,6 +57,7 @@ function parseFlags() {
             seed: { type: 'boolean' },
             'no-seed': { type: 'boolean' },
             'no-install': { type: 'boolean' },
+            ...featureFlags,
             github: { type: 'boolean' },
             ref: { type: 'string' },
             packages: { type: 'string' },
@@ -146,9 +156,25 @@ export async function resolveOptions() {
         db.name = values['db-name'];
     // Source.
     const packages = values.packages ? path.resolve(process.cwd(), values.packages) : null;
+    // Features. A --no-<id> flag turns one off without asking. Ask about the rest.
+    const turnedOff = new Set(FEATURES.filter((feature) => values[`no-${feature.id}`] === true).map((feature) => feature.id));
+    const open = FEATURES.filter((feature) => !turnedOff.has(feature.id));
+    let features = open.map((feature) => feature.id);
+    if (!yes && open.length > 0) {
+        const answer = await p.multiselect({
+            message: 'Which starter features do you want? (space toggles, enter confirms)',
+            options: open.map((feature) => ({ value: feature.id, label: feature.label, hint: feature.hint })),
+            initialValues: features,
+            required: false,
+        });
+        if (p.isCancel(answer))
+            cancelled();
+        features = answer;
+    }
+    const demo = features.includes('demo');
     // Install and seed.
     const install = values['no-install'] !== true;
-    const canSeed = install && !skipDb;
+    const canSeed = install && !skipDb && demo;
     let seed;
     if (values['no-seed']) {
         seed = false;
@@ -169,7 +195,9 @@ export async function resolveOptions() {
         seed = answer;
     }
     if (seed && !canSeed) {
-        p.log.warn(`Seeding needs installed dependencies and a database, so ${skipDb ? '--skip-db' : '--no-install'} turns it off.`);
+        const reason = !demo ? 'the demo content feature' : 'installed dependencies and a database';
+        const cause = !demo ? 'leaving it out' : skipDb ? '--skip-db' : '--no-install';
+        p.log.warn(`Seeding needs ${reason}, so ${cause} turns it off.`);
         seed = false;
     }
     return {
@@ -183,5 +211,6 @@ export async function resolveOptions() {
         github: values.github === true,
         ref: values.ref ?? DEFAULT_REF,
         packages,
+        features,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-payload-canvas",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Create a new Payload CMS website with Payload Canvas: the visual page builder, Postgres, a seeded demo and the AI guides.",
   "keywords": [
     "payload",
@@ -54,6 +54,8 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit -p tsconfig.check.json",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "check:features": "tsx scripts/check-features.ts"
   }
 }