create-aphex 0.2.0 → 0.3.0

package/README.md

@@ -1,12 +1,12 @@
 # create-aphex
 
-Scaffold a new Aphex CMS project. Copies the base template into a new
-directory and rewrites `workspace:*` deps to their published versions.
+Scaffold a new Aphex CMS project from an official standalone template.
 
 ## Usage
 
 ```bash
 pnpm create aphex my-app
+pnpm create aphex my-site --template website
 # or
 npm create aphex my-app
 # or
@@ -17,38 +17,44 @@ You can also invoke it through the [`aphx`](https://www.npmjs.com/package/aphx)
 CLI, which shells out to this package:
 
 ```bash
-pnpm aphex create
+aphx create my-site --template website
 ```
 
 ## What it does
 
 1. Prompts for a project name (or takes the positional argument).
-2. Prompts for a template (currently only `base`).
-3. Copies `templates/base/` into the new directory.
-4. Rewrites `workspace:*` dependencies to their published versions.
-5. Writes a default `.env` with working dev defaults.
+2. Prompts for an official template when `--template` is omitted.
+3. Downloads the selected standalone template repository.
+4. Sets the package name and writes a default `.env` with local development defaults.
+
+Official templates are pinned to the matching `create-aphex-vX.Y.Z` repository tag. A given CLI
+version therefore always scaffolds the same snapshot even after the template's `main` branch moves.
 
 ## Templates
 
 ### base
 
-A full-featured Aphex CMS application:
+A minimal Aphex CMS application for defining your own content model and public site.
+
+### website
+
+A content-focused website starter with:
 
 - Better Auth (email + password, email verification, password reset)
 - Organizations with parent/child hierarchy
-- PostgreSQL + Drizzle ORM with RLS policies
+- SQLite by default with optional PostgreSQL and Turso
 - S3-compatible storage (`@aphexcms/storage-s3`) with local-filesystem fallback
-- Mailpit in dev / Resend in prod
-- Auto-generated GraphQL API
-- In-memory cache adapter for published-perspective reads
+- Page builder, posts, categories, site navigation, and SEO
+
+Choose non-interactively with `--template base` or `--template website`. Set
+`APHEX_TEMPLATE` to a complete [giget](https://github.com/unjs/giget) source such
+as `github:owner/repo#branch` when testing a custom template repository.
 
 ## After scaffolding
 
 ```bash
 cd my-app
 pnpm install
-pnpm db:start      # Start PostgreSQL + Mailpit via Docker
-pnpm db:push       # Apply the schema (dev)
 pnpm dev           # http://localhost:5173
 ```
 

package/dist/env.js

@@ -0,0 +1,33 @@
+import { randomBytes } from 'crypto';
+/**
+ * Names the app accepts for the session-signing secret. `AUTH_SECRET` is the
+ * current one; `BETTER_AUTH_SECRET` is still read for backwards compatibility and
+ * is what older published templates ship, so a scaffold has to handle whichever
+ * the fetched template happens to use — `create-aphex` downloads the template
+ * from its own repo at run time, so the two versions are independent.
+ */
+const AUTH_SECRET_KEYS = ['AUTH_SECRET', 'BETTER_AUTH_SECRET'];
+/**
+ * Values that mean "nobody has set this yet" — empty, or one of the placeholder
+ * strings the templates ship. Anything else is left alone: a real value sitting
+ * in an example file is not ours to overwrite.
+ */
+function isUnsetSecret(value) {
+    const trimmed = value.trim().replace(/^["']|["']$/g, '');
+    if (trimmed === '')
+        return true;
+    return /change[-_ ]?(in[-_ ]?production|me)|your[-_ ]?secret|secret[-_ ]?key[-_ ]?here/i.test(trimmed);
+}
+/**
+ * Replace unset auth-secret values in a `.env` body with a freshly generated one.
+ *
+ * Lives in its own module rather than `index.ts` because that file runs the CLI
+ * on import — a test importing the helper from there would launch the prompt.
+ */
+export function withGeneratedAuthSecret(envBody) {
+    let result = envBody;
+    for (const key of AUTH_SECRET_KEYS) {
+        result = result.replace(new RegExp(`^(${key}=)(.*)$`, 'gm'), (line, prefix, value) => isUnsetSecret(value) ? `${prefix}${randomBytes(32).toString('base64url')}` : line);
+    }
+    return result;
+}

package/dist/index.js

@@ -1,34 +1,54 @@
 #!/usr/bin/env node
 import * as p from '@clack/prompts';
-import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import pc from 'picocolors';
 import { downloadTemplate } from 'giget';
-const TEMPLATE_REPO = process.env.APHEX_TEMPLATE || 'github:IcelandicIcecream/aphex-base';
+import { parseArgs, templates } from './options.js';
+import { withGeneratedAuthSecret } from './env.js';
 async function main() {
+    const cliOptions = parseArgs(process.argv.slice(2));
+    if (cliOptions.help) {
+        printHelp();
+        return;
+    }
     console.clear();
     p.intro(pc.bgCyan(pc.black(' create-aphex ')));
     const options = {
         projectName: '',
-        targetDir: ''
+        targetDir: '',
+        template: cliOptions.template ?? 'base'
     };
-    const projectName = await p.text({
-        message: 'What is your project name?',
-        placeholder: 'my-aphex-project',
-        validate: (value) => {
-            if (!value)
-                return 'Project name is required';
-            if (!/^[a-z0-9-]+$/.test(value)) {
-                return 'Project name can only contain lowercase letters, numbers, and hyphens';
-            }
-        }
-    });
+    const projectName = cliOptions.projectName ??
+        (await p.text({
+            message: 'What is your project name?',
+            placeholder: 'my-aphex-project',
+            validate: validateProjectName
+        }));
     if (p.isCancel(projectName)) {
         p.cancel('Operation cancelled');
         process.exit(0);
     }
     options.projectName = projectName;
     options.targetDir = resolve(process.cwd(), options.projectName);
+    const projectNameError = validateProjectName(options.projectName);
+    if (projectNameError)
+        throw new Error(projectNameError);
+    if (!cliOptions.template && !process.env.APHEX_TEMPLATE) {
+        const template = await p.select({
+            message: 'Which template would you like?',
+            options: Object.entries(templates).map(([value, template]) => ({
+                value: value,
+                label: template.label,
+                hint: template.description
+            }))
+        });
+        if (p.isCancel(template)) {
+            p.cancel('Operation cancelled');
+            process.exit(0);
+        }
+        options.template = template;
+    }
     if (existsSync(options.targetDir)) {
         const shouldOverwrite = await p.confirm({
             message: `Directory ${pc.cyan(options.projectName)} already exists. Overwrite?`,
@@ -39,10 +59,12 @@ async function main() {
             process.exit(0);
         }
     }
+    const selectedTemplate = templates[options.template];
+    const templateSource = process.env.APHEX_TEMPLATE || selectedTemplate.source;
     const spinner = p.spinner();
-    spinner.start(`Fetching template from ${TEMPLATE_REPO}...`);
+    spinner.start(`Fetching ${selectedTemplate.label} template...`);
     try {
-        await downloadTemplate(TEMPLATE_REPO, {
+        await downloadTemplate(templateSource, {
             dir: options.targetDir,
             force: true
         });
@@ -50,22 +72,27 @@ async function main() {
         if (existsSync(packageJsonPath)) {
             const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
             packageJson.name = options.projectName;
-            delete packageJson.private;
+            // `private: true` stays. A scaffolded project is an application, not a
+            // package to publish, and dropping the flag turns a stray `npm publish`
+            // in the project root from a refusal into an upload. Nothing about local
+            // development needs it gone.
+            packageJson.private = true;
             writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, '\t') + '\n');
         }
         const envPath = join(options.targetDir, '.env');
         const envExamplePath = join(options.targetDir, '.env.example');
         if (!existsSync(envPath) && existsSync(envExamplePath)) {
-            copyFileSync(envExamplePath, envPath);
+            // Copy `.env.example`, then fill in the auth secret. The example ships it
+            // unusable on purpose — empty in current templates, a
+            // `your-secret-key-here-change-in-production` placeholder in older ones —
+            // so a straight copy leaves the very first `pnpm dev` after scaffolding
+            // failing on a missing secret, which is the worst possible moment for it.
+            // Generating here is safe: the value is per-project, never leaves the
+            // machine, and `.env` is gitignored.
+            writeFileSync(envPath, withGeneratedAuthSecret(readFileSync(envExamplePath, 'utf-8')));
         }
         spinner.stop('Project created successfully!');
-        const nextSteps = [
-            `cd ${options.projectName}`,
-            'pnpm install',
-            'pnpm db:start',
-            'pnpm db:push',
-            'pnpm dev'
-        ];
+        const nextSteps = [`cd ${options.projectName}`, 'pnpm install', 'pnpm dev'];
         p.note(nextSteps.join('\n'), 'Next steps');
         p.outro(pc.green('Your Aphex CMS project is ready! Check out the README.md for more information.'));
     }
@@ -75,6 +102,27 @@ async function main() {
         process.exit(1);
     }
 }
+function validateProjectName(value) {
+    if (!value)
+        return 'Project name is required';
+    if (!/^[a-z0-9-]+$/.test(value)) {
+        return 'Project name can only contain lowercase letters, numbers, and hyphens';
+    }
+}
+function printHelp() {
+    console.log(`create-aphex
+
+Usage:
+  create-aphex [project-name] [options]
+
+Options:
+  -t, --template <name>  Template to use: base or website
+  -h, --help             Show this help message
+
+Examples:
+  pnpm create aphex my-site
+  pnpm create aphex my-site --template website`);
+}
 main().catch((error) => {
     console.error('Error:', error);
     process.exit(1);

package/dist/options.js

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const templateTag = `create-aphex-v${packageVersion.version}`;
+export const templates = {
+    base: {
+        label: 'Base',
+        description: 'Minimal starter for building your own content model',
+        source: `github:IcelandicIcecream/aphex-base#${templateTag}`
+    },
+    website: {
+        label: 'Website',
+        description: 'Page builder, blog, navigation, and SEO',
+        source: `github:IcelandicIcecream/aphex-website#${templateTag}`
+    }
+};
+export function parseArgs(args) {
+    const options = { help: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--help' || argument === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (argument === '--template' || argument === '-t') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-'))
+                throw new Error(`${argument} requires a template name`);
+            options.template = parseTemplate(value);
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--template=')) {
+            options.template = parseTemplate(argument.slice('--template='.length));
+            continue;
+        }
+        if (argument.startsWith('-'))
+            throw new Error(`Unknown option: ${argument}`);
+        if (options.projectName)
+            throw new Error(`Unexpected argument: ${argument}`);
+        options.projectName = argument;
+    }
+    return options;
+}
+function parseTemplate(value) {
+    if (value in templates)
+        return value;
+    throw new Error(`Unknown template "${value}". Available templates: ${Object.keys(templates).join(', ')}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-aphex",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold a new Aphex CMS project — invoked via `pnpm create aphex`",
   "publishConfig": {
     "provenance": true