create-apexjs 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apexjs",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Scaffold a new Apex JS app",
   "type": "module",
   "license": "MIT",

package/templates/default/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md — building this app with an AI agent
+
+This is an **Apex JS** app. Apex is a full-stack, AI-native meta-framework for
+Alpine.js: file-based routing, SSR, islands, and **every typed API route is also
+an MCP tool**. This file tells you (the agent) how to work here effectively.
+
+## Golden rules
+1. **Prefer generators over hand-writing.** Run `apex make …` / `apex extend …` /
+   `apex add …` to create files — they produce correct, conventional, typed code.
+   Hand-writing boilerplate is where you make mistakes.
+2. **Everything has one place.** Follow the structure below; don't invent folders.
+3. **Security is the framework's job, not yours.** Use `auth`/`can`/`scope` — never
+   hand-roll auth. Defaults are fail-closed.
+4. **Verify your work.** Add tests with `createTestApp` and run `apex test`.
+5. **TypeScript is strict.** If it compiles, it's probably right; lean on the types.
+
+## Do things with the CLI (this is the fast path)
+```bash
+apex make page dashboard          # pages/dashboard.alpine (a route → /dashboard)
+apex make component Card          # components/Card.alpine  (<Card /> in templates)
+apex make model Post title:string body:string   # models/Post.ts → migration + REST + MCP CRUD
+apex make api webhooks            # server/api/webhooks.ts (defineApexRoute; also an MCP tool)
+apex make service Billing         # services/BillingService.ts
+apex extend auth                  # add sealed-cookie sessions + login/logout + /account
+apex extend data                  # add a DB-backed model + /guestbook demo (Supabase-ready)
+apex extend i18n                  # add locales/*.json + /fr routing
+apex add button card modal        # copy themeable UI components in
+apex migrate                      # apply DB migrations
+apex build --preset vercel        # build + Vercel config (also: netlify, docker); then deploy
+apex test                         # run Vitest
+```
+`apex make <kind> …` kinds: `page component api service store layout middleware test model migration auth`.
+
+## Project structure
+```
+pages/**/*.alpine   Routes. File path → URL. [param] = dynamic. index.alpine → parent path.
+layouts/*.alpine    Shared shells; default.alpine wraps every page (<slot/>).
+components/*.alpine  Reusable <PascalCase/> components (props via attributes).
+server/api/*.ts     Typed routes (defineApexRoute) / model resources → REST + MCP.
+server/auth.ts      Identity (sessionAuth) → ctx.user everywhere. (from `apex extend auth`)
+models/*.ts         defineModel → schema + migration + table + REST/MCP CRUD.
+db/                 createDb + migrations. Uses DATABASE_URL (Postgres) or in-memory libSQL.
+locales/*.json      i18n catalogs. (from `apex extend i18n`)
+services/*.ts       Business logic (classes). Keep routes thin; delegate here.
+stores/*.ts         Global SSR-safe state ($store.x).
+composables/*.ts    Reusable client logic (useX) for <script client>.
+shared/*.ts         Types shared by server + client.
+tests/*.test.ts     Vitest. createTestApp boots the whole app in-process.
+```
+
+## The `.alpine` single-file component
+```alpine
+<script server lang="ts">
+  // Runs on the server. loader() data becomes the page's x-data (real HTML first).
+  export function loader() { return { title: 'Hello' } }
+  export function head() { return { title: 'Hello' } }   // SEO
+</script>
+<script client lang="ts">
+  // Optional client-only logic; import composables here.
+</script>
+<template x-data>
+  <h1 x-text="title"></h1>
+  <Counter start="0" client:load />   <!-- island: client:load | client:visible | client:idle -->
+</template>
+<style scoped> h1 { color: var(--color-primary); } </style>
+```
+
+## APIs you'll use (import from `@apex-stack/core`, `/server`, `/testing`; data from `@apex-stack/data`)
+- **Route** → `defineApexRoute({ method, input: { …zod }, mcp: true, auth: true, can, handler })`. `mcp: true` makes it an AI-callable tool at `/mcp`.
+- **Model** → `defineModel('posts', { fields: {…}, use: [timestamps(), owned()] })` → `.resource(handle)` mounts REST + MCP CRUD.
+- **Auth** → `server/auth.ts` default-exports `sessionAuth({ password })`; gate routes with `auth: true` / `can`. In loaders, the user is `locals.user`.
+- **Config** → `apex.config.ts`: `defineConfig({ runtimeConfig: { …, public: {…} }, i18n: {…} })`. Read with `useRuntimeConfig()`.
+- **Test** → `createTestApp({ root })` → `app.get/post(path, body?, { user })`, `app.mcp.listTools()`.
+
+The full stability contract of public APIs is in the framework's `API.md` — 🟢 Stable ones won't break; 🟡 Experimental ones might.
+
+## Deploy
+`apex build --preset vercel|netlify|docker`. Set `DATABASE_URL` (Supabase/Neon/Postgres or Turso) + `APEX_SESSION_PASSWORD` (≥32 chars) in the host env. See the deploy docs.
+
+## Drive Apex as MCP tools (optional, powerful)
+Apex ships an MCP server for its own CLI — run `apex mcp-server` (stdio). Point your
+agent host at it to get `apex_make`, `apex_extend`, `apex_add`, `apex_build`, and
+`apex_list` as structured tools, so you scaffold by calling tools instead of shelling out.
+
+Docs: https://apexjs.site/docs/

package/templates/features/auth/pages/account.alpine

@@ -0,0 +1,54 @@
+<script server lang="ts">
+  // The user resolved by server/auth.ts is seeded into locals — so the page
+  // renders the signed-in state on the SERVER, no flash of "logged out".
+  export function loader({ locals }: { locals: Record<string, unknown> }) {
+    return { user: (locals.user as { name: string } | undefined) ?? null }
+  }
+
+  export function head() {
+    return { title: 'Account — apex-showcase' }
+  }
+</script>
+
+<template x-data="{
+    name: '',
+    async login() {
+      if (!this.name.trim()) return
+      await fetch('/api/login', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: this.name }),
+      })
+      location.reload()
+    },
+    async logout() {
+      await fetch('/api/logout', { method: 'POST' })
+      location.reload()
+    },
+  }">
+  <section class="py-8">
+    <h1 class="font-title text-3xl font-extrabold tracking-tight text-on-surface-strong dark:text-on-surface-dark-strong">Account</h1>
+    <p class="mt-2 max-w-2xl text-on-surface/80 dark:text-on-surface-dark/80">
+      Sealed-cookie sessions via <code>server/auth.ts</code>. The signed-in name below is
+      rendered on the server from <code>locals.user</code>, and the gated route
+      <code>/api/whoami</code> returns 401 until you log in.
+    </p>
+
+    <div class="mt-6 max-w-md rounded-radius border border-outline p-5 dark:border-outline-dark">
+      <template x-if="user">
+        <div class="flex flex-col items-start gap-3">
+          <p class="text-on-surface-strong dark:text-on-surface-dark-strong">Signed in as <strong x-text="user.name"></strong>.</p>
+          <button type="button" @click="logout()" class="rounded-radius border border-outline px-4 py-2 text-sm font-medium transition hover:opacity-75 dark:border-outline-dark">Log out</button>
+        </div>
+      </template>
+
+      <template x-if="!user">
+        <form class="flex flex-col items-start gap-3" @submit.prevent="login()">
+          <p class="text-on-surface/80 dark:text-on-surface-dark/80">You are not signed in.</p>
+          <input x-model="name" placeholder="Your name" class="w-full rounded-radius border border-outline bg-transparent px-3 py-2 dark:border-outline-dark" />
+          <button type="submit" class="inline-flex items-center justify-center gap-2 rounded-radius border border-primary bg-primary px-4 py-2 text-sm font-medium text-on-primary transition hover:opacity-75 dark:border-primary-dark dark:bg-primary-dark dark:text-on-primary-dark">Log in</button>
+        </form>
+      </template>
+    </div>
+  </section>
+</template>

package/templates/features/auth/server/api/login.ts

@@ -0,0 +1,16 @@
+import { defineApexRoute, useRuntimeConfig } from '@apex-stack/core'
+import { login } from '@apex-stack/core/server'
+import { z } from 'zod'
+
+// Demo login: accept a name and seal it into the session. A real app would
+// verify a password / OAuth code here first, then call login() with the result.
+export default defineApexRoute({
+  method: 'POST',
+  description: 'Log in (demo: name only) and start a session',
+  input: { name: z.string().min(1) },
+  handler: async ({ input, event }) => {
+    const user = { id: input.name.toLowerCase().replace(/\s+/g, '-'), name: input.name }
+    await login(event, { user }, { password: String(useRuntimeConfig().sessionPassword) })
+    return { user }
+  },
+})

package/templates/features/auth/server/api/logout.ts

@@ -0,0 +1,11 @@
+import { defineApexRoute, useRuntimeConfig } from '@apex-stack/core'
+import { logout } from '@apex-stack/core/server'
+
+export default defineApexRoute({
+  method: 'POST',
+  description: 'Clear the session cookie',
+  handler: async ({ event }) => {
+    await logout(event, { password: String(useRuntimeConfig().sessionPassword) })
+    return { ok: true }
+  },
+})

package/templates/features/auth/server/api/whoami.ts

@@ -0,0 +1,11 @@
+import { defineApexRoute } from '@apex-stack/core'
+
+// A gated route: `auth: true` → 401 for anonymous callers, and it's hidden from
+// the MCP tool list for users who can't reach it. ctx.user is the session identity.
+export default defineApexRoute({
+  method: 'GET',
+  description: 'Return the currently signed-in user',
+  auth: true,
+  mcp: true,
+  handler: ({ user }) => ({ user }),
+})

package/templates/features/auth/server/auth.ts

@@ -0,0 +1,10 @@
+import { useRuntimeConfig } from '@apex-stack/core'
+import { sessionAuth } from '@apex-stack/core/server'
+
+// Identity for the whole app. sessionAuth resolves the caller from the sealed
+// (encrypted + signed, HttpOnly) session cookie and injects the result as
+// ctx.user into every loader, API route and MCP tool. Anonymous → user = null.
+// Swap this file for a JWT/OAuth adapter without touching any route.
+export default sessionAuth({
+  password: String(useRuntimeConfig().sessionPassword),
+})

package/templates/features/data/db/index.ts

@@ -0,0 +1,28 @@
+import { createDb } from '@apex-stack/data'
+import { Message } from '../models/Message.js'
+
+// Use a hosted Postgres (Supabase / Neon / any Postgres) when DATABASE_URL is
+// set — otherwise an in-memory libSQL for zero-setup local dev. createDb
+// auto-tunes Postgres for a transaction pooler (e.g. Supabase's, on port 6543):
+// it disables prepared statements and enables SSL. Requires the `postgres` driver
+// (already a dependency of this app).
+const url = process.env.DATABASE_URL
+export const handle = url
+  ? await createDb({ driver: 'postgres', url })
+  : await createDb({ driver: 'libsql', url: ':memory:' })
+
+// Create the schema — dialect-aware (SQLite vs Postgres) and idempotent, straight
+// from the model. For a long-lived Postgres you'd normally run `apex migrate`
+// once and drop this; keeping it makes the showcase zero-setup on either backend.
+await handle.exec(Message.migrationSql(handle.dialect))
+
+// Seed a couple of rows if the table is empty.
+const now = handle.dialect === 'postgres' ? 'now()' : "datetime('now')"
+const seeded = await handle.query('SELECT COUNT(*) AS n FROM messages')
+if (Number(seeded[0]?.n ?? 0) === 0) {
+  await handle.exec(
+    `INSERT INTO messages (author, body, created_at, updated_at) VALUES
+      ('Ada Lovelace', 'Apex feels like HTML with superpowers.', ${now}, ${now}),
+      ('Alan Turing', 'One route — and my AI assistant can call it too.', ${now}, ${now})`,
+  )
+}

package/templates/features/data/models/Message.ts

@@ -0,0 +1,21 @@
+import { defineModel, timestamps } from '@apex-stack/data'
+
+// A model is Apex's single source of truth for a piece of data. This ONE
+// definition derives, with no extra wiring:
+//   • a typed Zod schema for insert/update validation
+//   • the SQL migration in db/migrations
+//   • a Drizzle table (per dialect: sqlite/libSQL/postgres)
+//   • a full REST + MCP resource — GET/POST /api/messages, tools
+//     messages_list / messages_get / messages_create / …
+//
+// Behaviors are composable, reusable lifecycle add-ons. `timestamps()` stamps
+// created_at on insert + updated_at on every write and keeps them out of the
+// client-writable insert shape. Others ship in @apex-stack/data: owned() (per-user
+// ownership + auth gating), softDeletes(), auditable(), observable().
+export const Message = defineModel('messages', {
+  fields: {
+    author: { type: 'string', notNull: true },
+    body: { type: 'string', notNull: true },
+  },
+  use: [timestamps()],
+})

package/templates/features/data/pages/guestbook.alpine

@@ -0,0 +1,56 @@
+<script server lang="ts">
+  import { handle } from '../db/index.js'
+
+  // Runs on the server: reads straight from the database, so the message list is
+  // real, indexable HTML before any JS loads. The data comes from the SAME model
+  // (models/Message.ts) that powers /api/messages and the messages_* MCP tools.
+  export async function loader() {
+    const messages = await handle.query(
+      'SELECT id, author, body, created_at FROM messages ORDER BY id DESC LIMIT 20',
+    )
+    return { messages }
+  }
+
+  export function head() {
+    return { title: 'Guestbook — apex-showcase' }
+  }
+</script>
+
+<template x-data="{
+    async submit(e) {
+      const f = new FormData(e.target)
+      await fetch('/api/messages', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ author: f.get('author') || 'Anonymous', body: f.get('body') }),
+      })
+      location.reload()
+    }
+  }">
+  <section class="py-8">
+    <h1 class="font-title text-3xl font-extrabold tracking-tight text-on-surface-strong dark:text-on-surface-dark-strong">Guestbook</h1>
+    <p class="mt-2 max-w-2xl text-on-surface/80 dark:text-on-surface-dark/80">
+      A database-backed model in action. The list is server-rendered from
+      <code>models/Message.ts</code>; the form posts to <code>/api/messages</code>
+      — the very same route your AI can call as the <code>messages_create</code> MCP tool.
+    </p>
+
+    <ul class="mt-6 divide-y divide-outline dark:divide-outline-dark">
+      <template x-for="m in messages" :key="m.id">
+        <li class="flex gap-3 py-3">
+          <span class="grid size-9 flex-none place-items-center rounded-full bg-primary font-bold text-sm text-on-primary dark:bg-primary-dark dark:text-on-primary-dark" x-text="(m.author || '?').slice(0,1).toUpperCase()"></span>
+          <div>
+            <p class="text-on-surface-strong dark:text-on-surface-dark-strong" x-text="m.body"></p>
+            <p class="text-sm text-on-surface/70 dark:text-on-surface-dark/70"><strong x-text="m.author"></strong> · <span x-text="m.created_at"></span></p>
+          </div>
+        </li>
+      </template>
+    </ul>
+
+    <form class="mt-6 grid max-w-lg gap-3 rounded-radius border border-outline p-4 dark:border-outline-dark" @submit.prevent="submit($event)">
+      <input name="author" placeholder="Your name" class="rounded-radius border border-outline bg-transparent px-3 py-2 dark:border-outline-dark" />
+      <textarea name="body" placeholder="Say something…" required maxlength="280" class="rounded-radius border border-outline bg-transparent px-3 py-2 dark:border-outline-dark"></textarea>
+      <div><button type="submit" class="inline-flex items-center justify-center gap-2 rounded-radius border border-primary bg-primary px-4 py-2 text-sm font-medium text-on-primary transition hover:opacity-75 dark:border-primary-dark dark:bg-primary-dark dark:text-on-primary-dark">Sign the guestbook</button></div>
+    </form>
+  </section>
+</template>

package/templates/features/data/server/api/messages.ts

@@ -0,0 +1,8 @@
+import { handle } from '../../db/index.js'
+import { Message } from '../../models/Message.js'
+
+// The model becomes a live REST + MCP resource with zero extra wiring:
+//   GET  /api/messages       · MCP tool messages_list
+//   GET  /api/messages/:id   · MCP tool messages_get
+//   POST /api/messages       · MCP tool messages_create   (+ update / delete)
+export default Message.resource(handle)

package/templates/features/i18n/locales/en.json

@@ -0,0 +1,5 @@
+{
+  "greeting": "Hello from Apex!",
+  "intro": "This paragraph was translated on the server, before any JavaScript ran. Switch to /fr/hello for French — the /<locale> path prefix (or the Accept-Language header) selects the catalog.",
+  "nav": { "home": "Home", "guestbook": "Guestbook", "account": "Account", "hello": "i18n" }
+}

package/templates/features/i18n/locales/fr.json

@@ -0,0 +1,5 @@
+{
+  "greeting": "Bonjour depuis Apex !",
+  "intro": "Ce paragraphe a été traduit sur le serveur, avant l’exécution du moindre JavaScript. Passez à /hello pour l’anglais — le préfixe /<locale> (ou l’en-tête Accept-Language) choisit le catalogue.",
+  "nav": { "home": "Accueil", "guestbook": "Livre d’or", "account": "Compte", "hello": "i18n" }
+}

package/templates/features/i18n/pages/hello.alpine

@@ -0,0 +1,24 @@
+<script server lang="ts">
+  // locals.t and locals.locale are injected by the i18n runtime once i18n is
+  // declared in apex.config.ts. Translation happens on the server, so the HTML
+  // arrives already localized — great for SEO.
+  export function loader({ locals }: { locals: Record<string, unknown> }) {
+    const t = locals.t as (k: string, p?: Record<string, unknown>) => string
+    return { greeting: t('greeting'), intro: t('intro'), locale: locals.locale as string }
+  }
+  export function head({ data }: { data: { greeting: string } }) {
+    return { title: data.greeting }
+  }
+</script>
+
+<template x-data>
+  <section class="py-8">
+    <p class="text-sm text-on-surface/70 dark:text-on-surface-dark/70">active locale: <strong x-text="locale"></strong></p>
+    <h1 class="mt-2 font-title text-3xl font-extrabold tracking-tight text-on-surface-strong dark:text-on-surface-dark-strong" x-text="greeting"></h1>
+    <p class="mt-3 max-w-2xl text-on-surface/80 dark:text-on-surface-dark/80" x-text="intro"></p>
+    <div class="mt-5 flex gap-3">
+      <a href="/hello" class="text-primary hover:opacity-75 dark:text-primary-dark">English</a>
+      <a href="/fr/hello" class="text-primary hover:opacity-75 dark:text-primary-dark">Français</a>
+    </div>
+  </section>
+</template>