create-aphex 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# create-aphex
+
+Scaffold a new Aphex CMS project. Copies the base template into a new
+directory and rewrites `workspace:*` deps to their published versions.
+
+## Usage
+
+```bash
+pnpm create aphex my-app
+# or
+npm create aphex my-app
+# or
+npx create-aphex my-app
+```
+
+You can also invoke it through the [`aphx`](https://www.npmjs.com/package/aphx)
+CLI, which shells out to this package:
+
+```bash
+npx aphx create
+```
+
+## 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.
+
+## Templates
+
+### base
+
+A full-featured Aphex CMS application:
+
+- Better Auth (email + password, email verification, password reset)
+- Organizations with parent/child hierarchy
+- PostgreSQL + Drizzle ORM with RLS policies
+- 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
+
+## 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
+```
+
+Open `http://localhost:5173/admin` — the first user to sign up becomes the
+super admin.

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import pc from 'picocolors';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const templates = ['base'];
+async function main() {
+    console.clear();
+    p.intro(pc.bgCyan(pc.black(' create-aphex ')));
+    const options = {
+        projectName: '',
+        template: 'base',
+        targetDir: ''
+    };
+    // Get project name
+    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';
+            }
+        }
+    });
+    if (p.isCancel(projectName)) {
+        p.cancel('Operation cancelled');
+        process.exit(0);
+    }
+    options.projectName = projectName;
+    options.targetDir = resolve(process.cwd(), options.projectName);
+    // Check if directory already exists
+    if (existsSync(options.targetDir)) {
+        const shouldOverwrite = await p.confirm({
+            message: `Directory ${pc.cyan(options.projectName)} already exists. Overwrite?`,
+            initialValue: false
+        });
+        if (p.isCancel(shouldOverwrite) || !shouldOverwrite) {
+            p.cancel('Operation cancelled');
+            process.exit(0);
+        }
+    }
+    options.template = 'base';
+    // Start scaffolding
+    const spinner = p.spinner();
+    spinner.start('Creating your Aphex project...');
+    try {
+        // Find the templates directory
+        // When running from npx, we need to look in the right place
+        const templatesDir = findTemplatesDir();
+        if (!templatesDir) {
+            throw new Error('Could not find templates directory');
+        }
+        const templatePath = join(templatesDir, options.template);
+        if (!existsSync(templatePath)) {
+            throw new Error(`Template "${options.template}" not found`);
+        }
+        // Create target directory
+        mkdirSync(options.targetDir, { recursive: true });
+        // Copy template files
+        cpSync(templatePath, options.targetDir, { recursive: true });
+        // Update package.json with project name and resolve workspace: references
+        const packageJsonPath = join(options.targetDir, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            packageJson.name = options.projectName;
+            // Replace workspace:* references with actual package versions
+            for (const depType of ['dependencies', 'devDependencies']) {
+                const deps = packageJson[depType];
+                if (!deps)
+                    continue;
+                for (const [name, version] of Object.entries(deps)) {
+                    if (typeof version === 'string' && version.startsWith('workspace:')) {
+                        // Look up the actual version from the package in the monorepo
+                        const pkgDir = findPackageDir(templatesDir, name);
+                        if (pkgDir) {
+                            const pkgJson = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));
+                            deps[name] = `^${pkgJson.version}`;
+                        }
+                    }
+                }
+            }
+            // Remove private flag and workspace-specific fields
+            delete packageJson.private;
+            writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, '\t') + '\n');
+        }
+        // Create .env from .env.example if it doesn't exist
+        const envPath = join(options.targetDir, '.env');
+        const envExamplePath = join(options.targetDir, '.env.example');
+        if (!existsSync(envPath) && existsSync(envExamplePath)) {
+            cpSync(envExamplePath, envPath);
+        }
+        spinner.stop('Project created successfully!');
+        // Show next steps
+        const nextSteps = [
+            `cd ${options.projectName}`,
+            'cp .env.example .env',
+            'pnpm install',
+            'pnpm db:start',
+            'pnpm db:push',
+            '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.'));
+    }
+    catch (error) {
+        spinner.stop('Failed to create project');
+        p.log.error(pc.red(error.message));
+        process.exit(1);
+    }
+}
+function findPackageDir(templatesDir, packageName) {
+    // Templates sit alongside packages/ in the monorepo, or the packages
+    // are bundled relative to the templates dir in the npm package
+    const possibleRoots = [
+        resolve(templatesDir, '..'), // monorepo root (templates/ -> ../)
+        resolve(templatesDir, '../..') // npm package (dist/templates -> ../../)
+    ];
+    for (const root of possibleRoots) {
+        const packagesDir = join(root, 'packages');
+        if (!existsSync(packagesDir))
+            continue;
+        for (const dir of readdirSync(packagesDir)) {
+            const pkgJsonPath = join(packagesDir, dir, 'package.json');
+            if (existsSync(pkgJsonPath)) {
+                const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+                if (pkgJson.name === packageName) {
+                    return join(packagesDir, dir);
+                }
+            }
+        }
+    }
+    return null;
+}
+function findTemplatesDir() {
+    // Try different possible locations for the templates directory
+    const possiblePaths = [
+        // When installed via npm/npx (templates are bundled in package)
+        resolve(__dirname, '../templates'),
+        // When running from built dist in package
+        resolve(__dirname, '../../templates'),
+        // When running from source in monorepo
+        resolve(__dirname, '../../../templates')
+    ];
+    for (const path of possiblePaths) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    return null;
+}
+main().catch((error) => {
+    console.error('Error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "create-aphex",
+	"version": "0.1.0",
+	"description": "Scaffold a new Aphex CMS project — invoked via `pnpm create aphex`",
+	"publishConfig": {},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/IcelandicIcecream/aphex.git",
+		"directory": "packages/create-aphex"
+	},
+	"type": "module",
+	"bin": {
+		"create-aphex": "./dist/index.js"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"scripts": {
+		"build": "node scripts/copy-templates.js && tsc",
+		"prepublishOnly": "pnpm build"
+	},
+	"keywords": [
+		"aphex",
+		"cms",
+		"cli",
+		"scaffolding",
+		"template"
+	],
+	"author": "",
+	"license": "MIT",
+	"dependencies": {
+		"@clack/prompts": "^0.11.0",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"typescript": "^5.9.3"
+	}
+}

package/templates/base/.dockerignore

@@ -0,0 +1,44 @@
+# Build artifacts
+build
+node_modules
+.svelte-kit
+dist
+
+# Environment files
+.env
+.env.*
+!.env.example
+!.env.docker
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Storage
+storage/assets/
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# Documentation
+README.md
+CONTRIBUTING.md
+LICENSE
+
+# Git
+.git
+.gitignore
+
+# Testing
+coverage
+.nyc_output

package/templates/base/.env.example

@@ -0,0 +1,38 @@
+# ============================
+# Database Configuration
+# ============================
+
+## Option (1): Using a full DATABASE_URL
+## -------------------------------------
+DATABASE_URL="postgres://root:mysecretpassword@localhost:5432/local"
+
+## Option (2): Using individual connection settings
+## -----------------------------------------------
+## Uncomment and set these if not using DATABASE_URL
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_USER=root
+# PG_PASSWORD=mysecretpassword
+# PG_DATABASE=local
+
+# ============================
+# Auth Configuration
+# ============================
+# BETTER_AUTH_SECRET / BETTER_AUTH_URL also work for backwards compatibility
+BETTER_AUTH_SECRET=your-secret-key-here-change-in-production
+BETTER_AUTH_URL=http://localhost:5173
+AUTH_TRUSTED_ORIGINS=http://localhost:5173
+
+# ============================
+# Resend Email Configuration (optional)
+# ============================
+RESEND_API_KEY=re_your_api_key_here
+
+# ============================
+# S3_COMPATIBLE CONFIGURATION (optional)
+# ============================
+R2_ENDPOINT=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=
+R2_PUBLIC_URL=

package/templates/base/CHANGELOG.md

@@ -0,0 +1,118 @@
+---
+**Heads up:** This project was scaffolded from `@aphexcms/base` `v0.0.2`.
+When upgrading, read `CHANGELOG.md` in the template repo for notes on
+what changed upstream and which files you may want to port into your
+customized project.
+---
+
+# AphexCMS Template Changelog
+
+Notes for users upgrading an existing project scaffolded from this template.
+Because the template is meant to be customized, changes here are **not**
+automatically applied to your project — this file describes what changed
+upstream so you can cherry-pick the bits you care about.
+
+Format: each entry lists the files touched and a one-line reason. Use
+`git diff` against the mirror repo (`IcelandicIcecream/aphex-base`) at the
+tag matching the version you started from to see the exact changes.
+
+## Unreleased
+
+- **feat(api): move invitation email-wrap into `aphex.config.ts → api`**
+  - Deleted: `src/routes/api/organizations/invitations/+server.ts` —
+    the SK shim that wrapped the built-in invite handler to send email.
+  - Added: `src/lib/server/email/invitation-hook.ts` — same logic, now a
+    Hono middleware registered via `config.api`. Runs BEFORE built-in
+    routes mount (Hono is registration-order-strict, so middleware needs
+    to register first to wrap a downstream handler).
+  - `aphex.config.ts` now passes `api: (app) => registerInvitationEmailHook(app)`.
+  - Why: lets us drop the last invitation-related entry from
+    `routes-exports.ts` and the matching SK route file in cms-core. The
+    only remaining `routes-exports` entry is `serveAssetCDN` (CDN URLs
+    live outside `/api` so can't move onto the catch-all).
+  - Upgrade: copy `src/lib/server/email/invitation-hook.ts` and the new
+    `api:` block in `aphex.config.ts`; delete your old
+    `src/routes/api/organizations/invitations/+server.ts`.
+
+- **feat(api): replace per-endpoint `+server.ts` shims with a single Hono catch-all**
+  - Added: `src/routes/api/[...slug]/+server.ts` — forwards any unmatched
+    `/api/**` request to the Aphex Hono app on `event.locals.aphexCMS.apiApp`.
+  - Deleted (24 files) — all CMS-feature shims that just re-exported handlers
+    from `@aphexcms/cms-core/server`. They're now served by the catch-all:
+    - `src/routes/api/{schemas,documents,assets,organizations,roles,user}/+server.ts`
+    - `src/routes/api/schemas/[type]/+server.ts`
+    - `src/routes/api/documents/{query,[id]}/+server.ts`
+    - `src/routes/api/documents/[id]/{publish,versions}/+server.ts`
+    - `src/routes/api/documents/[id]/versions/[version]/+server.ts`
+    - `src/routes/api/documents/[id]/versions/[version]/restore/+server.ts`
+    - `src/routes/api/assets/{bulk,[id]}/+server.ts`
+    - `src/routes/api/assets/[id]/references/+server.ts`
+    - `src/routes/api/assets/references/counts/+server.ts`
+    - `src/routes/api/organizations/{switch,members,[id]}/+server.ts`
+    - `src/routes/api/roles/[name]/+server.ts`
+    - `src/routes/api/user/{cms-preference,reset-password,request-password-reset}/+server.ts`
+  - Kept (studio-locals — your own endpoints): `instance-settings`,
+    `invitations`, `invitations/[id]/{accept,reject}`,
+    `organizations/invitations`, `settings/api-keys`, `settings/api-keys/[id]`.
+  - Why: SvelteKit prefers specific routes over the catch-all, so any
+    `+server.ts` you keep wins. Custom endpoints can still go in
+    `src/routes/**/+server.ts` as before, OR be registered onto the Hono
+    app via `aphex.config.ts → api: (app) => { app.post(...) }`.
+  - Upgrade: copy `src/routes/api/[...slug]/+server.ts` from the template,
+    then delete any of the 24 shims you haven't customized. If you
+    customized one, leave it — it'll continue to win over the catch-all.
+
+## 0.0.2
+
+- **chore(deps): bump `@aphexcms/cms-core` to `^2.1.2` and `@aphexcms/ui` to `^0.3.4`**
+  - Fixes ESM resolution of the `schema-context.svelte` rune module
+    (`ERR_MODULE_NOT_FOUND`) and adds the `svelte` export condition on
+    subpath exports (`/client`, `/server`, `/schema`, `/routes/*`, etc.) so
+    SvelteKit's Vite plugin claims them instead of Node's default loader
+    trying to import raw `.svelte` files (`ERR_UNKNOWN_FILE_EXTENSION`).
+  - No source changes required in the template — reinstall to pick it up.
+
+- **chore(styles): drop `@import '@aphexcms/ui/themes/aphex'` from `src/app.css`**
+  - The `@aphexcms/ui/themes/aphex` theme file was removed from
+    `@aphexcms/ui@0.3.4`. If you kept that import in your own `app.css`,
+    delete the line when you upgrade or the build will fail to resolve it.
+
+- **fix(admin): delete-asset modal + document-editor header + boolean autosave**
+  - All three fixes live in `@aphexcms/cms-core`; upgrading the dep is enough.
+  - Long asset filenames no longer stretch the delete confirm dialog.
+  - Document editor top-row actions are vertically centered.
+  - Autosave compares against an initial-defaults snapshot — unchecking a
+    boolean now saves, and fields with `initialValue: true` no longer
+    auto-create an empty doc on mount.
+
+- **chore(drizzle): regenerate initial migration**
+  - `drizzle/0000_tiny_redwing.sql`, `drizzle/meta/0000_snapshot.json`, `drizzle/meta/_journal.json`
+  - Template migration was stale vs. the current schema (missing
+    `cms_document_versions`, `cms_instance_settings`, `cms_roles`, the
+    `version_event` enum, and the `unpublished` document status).
+  - If you've already run `db:push` against your project DB you're fine;
+    users starting fresh from this template will now get the full schema.
+
+- **chore(admin): comment out `<PermissionsDebug />`**
+  - `src/routes/(protected)/admin/+layout.svelte`
+  - Debug overlay disabled by default in the shipped template.
+
+<!--
+Example entry:
+
+- **fix(members): reject self-invitation and duplicate members**
+  - `src/routes/(protected)/admin/settings/members/+page.svelte`
+  - Handled server-side in cms-core; UI unchanged. Safe to skip if you
+    haven't customized the invite flow.
+
+- **feat(versions): add document versions API routes**
+  - `src/routes/api/documents/[id]/versions/+server.ts`
+  - `src/routes/api/documents/[id]/versions/[version]/+server.ts`
+  - `src/routes/api/documents/[id]/versions/[version]/restore/+server.ts`
+  - Clean re-exports from `@aphexcms/cms-core/server`. Port these over to
+    get version history in your admin UI.
+-->
+
+## 0.0.1
+
+- Initial template.

package/templates/base/Dockerfile

@@ -0,0 +1,69 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+# Install pnpm
+RUN npm install -g pnpm
+
+WORKDIR /app
+
+# Copy workspace files
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY turbo.json ./
+COPY tsconfig.json ./
+
+# Copy all packages and apps
+COPY packages ./packages
+COPY apps/studio ./apps/studio
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Build arguments for environment variables needed at build time
+ARG ACCESS_API_KEY
+ARG GITHUB_TOKEN
+ARG RESEND_API_KEY
+ARG AUTH_SECRET
+ARG AUTH_URL
+ARG DATABASE_URL
+
+# Set as environment variables for the build
+ENV ACCESS_API_KEY=$ACCESS_API_KEY
+ENV GITHUB_TOKEN=$GITHUB_TOKEN
+ENV RESEND_API_KEY=$RESEND_API_KEY
+ENV AUTH_SECRET=$AUTH_SECRET
+ENV AUTH_URL=$AUTH_URL
+ENV DATABASE_URL=$DATABASE_URL
+
+# Build the application
+WORKDIR /app/apps/studio
+RUN pnpm build
+
+# Production stage
+FROM node:20-alpine AS runner
+
+# Copy workspace root files first
+COPY --from=builder /app/package.json /app/package.json
+COPY --from=builder /app/pnpm-workspace.yaml /app/pnpm-workspace.yaml
+COPY --from=builder /app/node_modules /app/node_modules
+COPY --from=builder /app/packages /app/packages
+
+# Set working directory for the app
+WORKDIR /app/apps/studio
+
+# Copy studio app files
+COPY --from=builder /app/apps/studio/build ./build
+COPY --from=builder /app/apps/studio/package.json ./package.json
+COPY --from=builder /app/apps/studio/node_modules ./node_modules
+COPY --from=builder /app/apps/studio/drizzle ./drizzle
+COPY --from=builder /app/apps/studio/drizzle.config.ts ./drizzle.config.ts
+
+# Expose port
+EXPOSE 3000
+
+# Set environment to production
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV NODE_PATH=/app/node_modules
+
+# Start the application
+CMD ["node", "build"]

package/templates/base/README.md

@@ -0,0 +1,147 @@
+# Aphex CMS
+
+A clean starting point for building with Aphex CMS. No example schemas — just the wiring.
+
+> This directory is mirrored to [**IcelandicIcecream/aphex-base**](https://github.com/IcelandicIcecream/aphex-base) on every change, so you can clone it directly as a standalone project:
+>
+> ```bash
+> git clone https://github.com/IcelandicIcecream/aphex-base my-app
+> cd my-app && pnpm install
+> ```
+>
+> Or scaffold via the CLI: `npx aphx create`.
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Set Up Environment Variables
+
+Copy the example file and update as needed:
+
+```bash
+cp .env.example .env
+```
+
+### 3. Start PostgreSQL Database
+
+```bash
+pnpm db:start
+```
+
+### 4. Run Database Migrations
+
+```bash
+pnpm db:migrate
+```
+
+### 5. Start Development Server
+
+```bash
+pnpm dev
+```
+
+Your application will be available at `http://localhost:5173`
+
+### 6. First Login
+
+1. Go to `http://localhost:5173/login`
+2. Sign up with your email and password — the first user automatically becomes the super admin with a default organization
+3. Access God Mode at `/god-mode` for instance-level administration
+
+## Defining Content Schemas
+
+Add your content schemas in `src/lib/schemaTypes/`. Two types are available:
+
+- **`document`** — Top-level entities (e.g. Page, Post, Product)
+- **`object`** — Reusable nested structures (e.g. SEO, Hero)
+
+Example:
+
+```typescript
+// src/lib/schemaTypes/post.ts
+import type { SchemaType } from '@aphexcms/cms-core';
+
+const post: SchemaType = {
+	type: 'document',
+	name: 'post',
+	title: 'Post',
+	fields: [
+		{
+			name: 'title',
+			type: 'string',
+			title: 'Title',
+			validation: (Rule) => Rule.required()
+		},
+		{
+			name: 'slug',
+			type: 'slug',
+			title: 'Slug',
+			source: 'title'
+		},
+		{
+			name: 'body',
+			type: 'text',
+			title: 'Body'
+		}
+	]
+};
+
+export default post;
+```
+
+Then register it in `src/lib/schemaTypes/index.ts`:
+
+```typescript
+import post from './post.js';
+
+export const schemaTypes = [post];
+```
+
+Available field types: `string`, `text`, `number`, `boolean`, `slug`, `image`, `date`, `datetime`, `url`, `array`, `object`, `reference`
+
+## Available Scripts
+
+- `pnpm dev` — Start the development server
+- `pnpm build` — Build for production
+- `pnpm preview` — Preview production build
+- `pnpm db:start` — Start PostgreSQL via Docker
+- `pnpm db:migrate` — Run database migrations
+- `pnpm db:push` — Push schema changes (dev only)
+- `pnpm db:generate` — Generate migration files
+- `pnpm db:studio` — Open Drizzle Studio
+
+## Project Structure
+
+```
+.
+├── src/
+│   ├── lib/
+│   │   ├── server/
+│   │   │   ├── auth/         # Authentication (Better Auth)
+│   │   │   ├── db/           # Database connection and schema
+│   │   │   ├── email/        # Email templates and adapter
+│   │   │   ├── services/     # Business logic
+│   │   │   └── storage/      # File storage adapter
+│   │   ├── schemaTypes/      # Your content type definitions
+│   │   └── utils/            # Utility functions
+│   └── routes/
+│       ├── (protected)/admin/ # Admin panel
+│       ├── api/               # API endpoints
+│       ├── god-mode/          # Super admin panel
+│       └── login/             # Authentication
+├── aphex.config.ts            # CMS configuration
+├── drizzle/                   # Database migrations
+└── docker-compose.yml         # PostgreSQL setup
+```
+
+## Learn More
+
+- [Aphex CMS](https://github.com/IcelandicIcecream/aphex)
+- [SvelteKit](https://kit.svelte.dev)
+- [Drizzle ORM](https://orm.drizzle.team)
+- [Better Auth](https://better-auth.com)