@apex-stack/core 0.1.19 → 0.2.0

package/templates/default/README.md

@@ -1,33 +1,79 @@
 # {{name}}
 
-An [Apex JS](https://github.com/andrecorugda/apexjs) app — a meta-framework for
-Alpine.js that renders on the server and hydrates in the browser.
+An [Apex JS](https://apexjs.site) app — HTML-first, server-rendered, AI-native.
 
-## Getting started
+## Commands
 
 ```bash
-npm install
-npm run dev
+npm run dev          # dev server → http://localhost:3000
+npm run dev:islands  # static-first islands mode (ship ~zero JS)
+npm run build        # production build
+npm start            # run the production server build
+npm test             # run tests (Vitest)
+npm run typecheck    # strict type-check
 ```
 
-Then open [http://localhost:3000](http://localhost:3000).
+> `apex` is a project command — run it via `npm run dev`, or install it globally
+> (`npm i -g @apex-stack/core`) to use `apex dev` directly.
 
-## Islands mode
+## Project structure
+
+```
+pages/         File-based routes (.alpine) — server-rendered, then hydrated.
+layouts/       Shared page shells; default.alpine wraps every page (<slot/>).
+components/    Reusable <PascalCase/> components with scoped styles.
+server/api/    Typed routes (defineApexRoute) — each is a REST endpoint AND an MCP tool.
+services/      Business logic as plain OO classes. Keep routes thin; delegate here.
+shared/        Types/interfaces shared by the backend and the frontend.
+stores/        Global, SSR-safe state — $store.x, reactive across pages/islands.
+composables/   Reusable client logic (useX) for <script client> blocks.
+tests/         Vitest tests. `npm test` runs them.
+db/            Optional: a database + resources. See db/README.md.
+public/        Static assets served as-is.
+```
 
-Ship interactive JavaScript only where you need it:
+## Conventions (clean code)
+
+- **Thin routes → services.** A route/loader validates input and delegates to a service
+  class in `services/`. Business logic stays testable in isolation and reusable everywhere.
+- **Types live in `shared/`.** One source of truth; strict TypeScript enforces them across
+  backend and frontend — no drift.
+- **Tests by default.** `npm test` runs Vitest (see `tests/greeting.test.ts`).
+
+## Generators
 
 ```bash
-apex dev --islands
+apex make page about
+apex make component Card
+apex make api todos
+apex make service Billing     # → services/BillingService.ts (OO class)
+apex make store cart
+apex make layout marketing
+apex make middleware auth      # → middleware/auth.ts (runs on every request)
+apex make test billing         # → tests/billing.test.ts
 ```
 
-## Project structure
+## Styling
 
-- `pages/*.alpine` — single-file components. The `<script server>` block runs on
-  the server; its `loader()` return value becomes the Alpine `x-data` scope.
-- `server/api/*.ts` — API routes defined with `defineApexRoute`.
+- **Scoped by default.** A `<style scoped>` block in an `.alpine` file is scoped to that component.
+- **Global / shared styles.** Create `app.css` (also `styles/app.css` or `src/app.css`) in the
+  project root — Apex auto-loads and processes it (Vite HMR in dev, bundled in build).
+- **Tailwind.** `npm i tailwindcss @tailwindcss/vite`, then `@import "tailwindcss";` at the top of
+  `app.css`. Apex auto-detects `@tailwindcss/vite` — no extra config.
 
-## AI-native API
+## Config & environment
+
+`apex.config.ts` declares `runtimeConfig` (see the file's comments). `public.*` values reach the
+browser; everything else is server-only. Override any value from `.env` — `APEX_<KEY>` (private) /
+`APEX_PUBLIC_<KEY>` (public). Read it via the loader/route `config` argument, `useRuntimeConfig()`,
+or `env('KEY', fallback)`. Real environment variables always win — build once, deploy with env.
+
+## Upgrading
+
+Adopt new scaffold defaults in this app without touching your code:
+
+```bash
+apex upgrade        # adds any new template files; never overwrites yours (package.json preserved)
+```
 
-Every route in `server/api/*.ts` is a REST endpoint **and** an MCP tool at the
-same time. Set `mcp: true` on a route (see `server/api/hello.ts`) and it is
-automatically exposed to AI agents at the `/mcp` endpoint — no extra wiring.
+Full docs: https://apexjs.site

package/templates/default/_gitignore

@@ -1,3 +1,8 @@
 node_modules
 dist
 *.log
+
+# Local env — keep .env.example committed, never real secrets
+.env
+.env.local
+.env.*.local

package/templates/default/apex.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from '@apex-stack/core'
+
+// Runtime configuration — declare defaults here, override any value from the
+// environment. Private keys map to APEX_<KEY>; public keys to APEX_PUBLIC_<KEY>
+// (camelCase ↔ SCREAMING_SNAKE). Values in .env win over these defaults.
+//
+// Read it anywhere:
+//   • loaders/routes:  ({ config }) => config.public.appName
+//   • components/composables (client): useRuntimeConfig().public.appName
+//   • raw escape hatch: env('SOME_KEY', 'fallback')
+export default defineConfig({
+  runtimeConfig: {
+    // Private — server-only, never sent to the browser.
+    apiSecret: '', // ← APEX_API_SECRET
+
+    // Public — serialized into the page, readable in the browser.
+    public: {
+      appName: '{{name}}', //            ← APEX_PUBLIC_APP_NAME
+      siteUrl: 'http://localhost:3000', // ← APEX_PUBLIC_SITE_URL
+    },
+  },
+})

package/templates/default/components/Counter.alpine

@@ -0,0 +1,15 @@
+<template x-data="{ count: Number(start) }">
+  <button class="counter" @click="count++" x-text="label + ': ' + count"></button>
+</template>
+
+<style scoped>
+  .counter {
+    padding: 0.45rem 0.9rem;
+    border: 1px solid #6366f1;
+    border-radius: 0.5rem;
+    background: #eef2ff;
+    color: #3730a3;
+    cursor: pointer;
+    font: inherit;
+  }
+</style>

package/templates/default/composables/useToggle.ts

@@ -0,0 +1,14 @@
+/**
+ * Reusable client logic. Import it in a <script client> block and use it in x-data:
+ *
+ *   <script client> import { useToggle } from '../composables/useToggle' </script>
+ *   <template x-data="useToggle(true)"> <button @click="toggle()" x-text="on"></button> </template>
+ */
+export function useToggle(initial = false) {
+  return {
+    on: initial,
+    toggle() {
+      this.on = !this.on
+    },
+  }
+}

package/templates/default/db/README.md

@@ -0,0 +1,18 @@
+# db/
+
+Data is opt-in. To add a database with resources that are REST **and** MCP by default:
+
+```bash
+npm i @apex-stack/data @libsql/client   # install only the driver you use
+```
+
+Then add `db/schema.ts` (Drizzle tables), `db/index.ts` (`createDb` + `applyMigrations`),
+and a resource in `server/api/*.ts`:
+
+```ts
+import { defineResource } from '@apex-stack/data'
+export default defineResource('posts', { db, table: schema.posts, insert: { title: z.string() } })
+```
+
+That one line gives you `GET/POST/PATCH/DELETE /api/posts` plus the MCP tools
+`posts_list/get/create/update/delete`. See https://apexjs.site/data.html

package/templates/default/layouts/default.alpine

@@ -0,0 +1,16 @@
+<template>
+  <header class="site-header">
+    <a class="brand" href="/">{{name}}</a>
+  </header>
+  <main>
+    <slot></slot>
+  </main>
+  <footer class="site-footer">Built with Apex JS</footer>
+</template>
+
+<style scoped>
+  .site-header { padding: 1rem 1.5rem; border-bottom: 1px solid #e2e8f0; }
+  .brand { font-weight: 700; color: #2563eb; text-decoration: none; }
+  main { max-width: 44rem; margin: 0 auto; padding: 2.5rem 1.5rem; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.6; color: #1e293b; }
+  .site-footer { padding: 1.5rem; text-align: center; color: #64748b; font-size: 0.9rem; border-top: 1px solid #e2e8f0; }
+</style>

package/templates/default/package.json

@@ -4,11 +4,20 @@
   "type": "module",
   "scripts": {
     "dev": "apex dev",
-    "dev:islands": "apex dev --islands"
+    "dev:islands": "apex dev --islands",
+    "build": "apex build",
+    "start": "apex start",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "alpinejs": "^3.14.8",
     "@apex-stack/core": "latest",
+    "alpinejs": "^3.14.8",
     "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
   }
 }

package/templates/default/pages/index.alpine

@@ -1,107 +1,38 @@
 <script server lang="ts">
   export function loader() {
     return {
-      title: 'Welcome to Apex JS',
+      title: 'Welcome to {{name}}',
       tagline: 'The meta-framework for Alpine.js — server-rendered, then hydrated.',
     }
   }
 </script>
 
 <template x-data="{ open: false }">
-  <main>
-    <h1 x-text="title"></h1>
-    <p class="tagline" x-text="tagline"></p>
+  <h1 x-text="title"></h1>
+  <p class="tagline" x-text="tagline"></p>
 
-    <section class="card">
-      <p>
-        This page was rendered on the server from
-        <code>pages/index.alpine</code>, then hydrated by Alpine in the browser.
-        Edit it and save to see your changes live.
-      </p>
-
-      <button type="button" @click="open = !open" x-text="open ? 'Hide the details' : 'Show me how'"></button>
-
-      <div x-show="open" x-transition class="details">
-        <p>
-          The <code>loader()</code> in the server block runs on the server and
-          hands its data straight to Alpine's <code>x-data</code> scope — no
-          fetch, no boilerplate.
-        </p>
-        <p>
-          Next, open <code>server/api/hello.ts</code>: it's a REST endpoint
-          <em>and</em> an MCP tool at <code>/mcp</code> at the same time.
-        </p>
-      </div>
-    </section>
-
-    <p class="hint">
-      Run <code>apex dev --islands</code> to ship interactive islands only where
-      you need them.
+  <section class="card">
+    <p>
+      This was rendered on the server from <code>pages/index.alpine</code>, wrapped in
+      <code>layouts/default.alpine</code>, then hydrated by Alpine. Edit and save to see it live.
     </p>
-  </main>
+    <button type="button" @click="open = !open" x-text="open ? 'Hide' : 'Show me how'"></button>
+    <div x-show="open" x-transition class="details">
+      <p>The <code>loader()</code> runs on the server and hands its data to Alpine's <code>x-data</code>.</p>
+      <p>Open <code>server/api/hello.ts</code>: a thin route → <code>GreetingService</code>, exposed as REST <em>and</em> an MCP tool.</p>
+    </div>
+  </section>
+
+  <p class="hint">A reusable component that hydrates in the browser:</p>
+  <Counter start="0" label="Clicks" />
 </template>
 
 <style scoped>
-  main {
-    max-width: 40rem;
-    margin: 4rem auto;
-    padding: 0 1.5rem;
-    font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-    line-height: 1.6;
-    color: #1e293b;
-  }
-
-  h1 {
-    color: #2563eb;
-    font-size: 2.5rem;
-    margin-bottom: 0.5rem;
-  }
-
-  .tagline {
-    font-size: 1.15rem;
-    color: #475569;
-    margin-top: 0;
-  }
-
-  .card {
-    margin-top: 2rem;
-    padding: 1.5rem;
-    border: 1px solid #e2e8f0;
-    border-radius: 0.75rem;
-    background: #f8fafc;
-  }
-
-  button {
-    margin-top: 0.5rem;
-    padding: 0.6rem 1.1rem;
-    font-size: 1rem;
-    font-weight: 600;
-    color: #fff;
-    background: #2563eb;
-    border: none;
-    border-radius: 0.5rem;
-    cursor: pointer;
-    transition: background 0.15s ease;
-  }
-
-  button:hover {
-    background: #1d4ed8;
-  }
-
-  .details {
-    margin-top: 1rem;
-  }
-
-  code {
-    padding: 0.1rem 0.35rem;
-    font-size: 0.9em;
-    background: #e2e8f0;
-    border-radius: 0.35rem;
-  }
-
-  .hint {
-    margin-top: 2rem;
-    font-size: 0.95rem;
-    color: #64748b;
-  }
+  h1 { color: #2563eb; font-size: 2.25rem; margin-bottom: 0.25rem; }
+  .tagline { font-size: 1.1rem; color: #475569; margin-top: 0; }
+  .card { margin-top: 1.5rem; padding: 1.25rem; border: 1px solid #e2e8f0; border-radius: 0.75rem; background: #f8fafc; }
+  .card button { margin-top: 0.5rem; padding: 0.55rem 1rem; font-weight: 600; color: #fff; background: #2563eb; border: none; border-radius: 0.5rem; cursor: pointer; }
+  .details { margin-top: 1rem; }
+  code { padding: 0.1rem 0.35rem; background: #e2e8f0; border-radius: 0.35rem; font-size: 0.9em; }
+  .hint { margin-top: 1.5rem; color: #64748b; font-size: 0.95rem; }
 </style>

package/templates/default/server/api/hello.ts

@@ -1,10 +1,18 @@
 import { defineApexRoute } from '@apex-stack/core'
 import { z } from 'zod'
+import { GreetingService } from '../../services/GreetingService'
 
+const greetings = new GreetingService()
+
+/**
+ * A route is a thin adapter: validate input, delegate to a service, return the
+ * result. Because `mcp: true`, this is ALSO an MCP tool named "hello" at /mcp —
+ * one definition, REST + AI-callable.
+ */
 export default defineApexRoute({
   method: 'GET',
-  description: 'Say hello to someone by name',
+  description: 'Greet someone by name',
   input: { name: z.string() },
   mcp: true,
-  handler: ({ input }) => ({ message: `Hello, ${input.name}!` }),
+  handler: ({ input }) => greetings.greet(input.name),
 })

package/templates/default/services/GreetingService.ts

@@ -0,0 +1,12 @@
+import type { Greeting } from '../shared/types'
+
+/**
+ * A service holds business logic as a plain class — testable in isolation and
+ * reusable from routes, page loaders, and jobs. Keep routes/loaders thin: they
+ * validate input and delegate to a service. This is the clean-code backbone.
+ */
+export class GreetingService {
+  greet(name: string): Greeting {
+    return { message: `Hello, ${name}!`, at: new Date().toISOString() }
+  }
+}

package/templates/default/shared/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared types — the single source of truth for shapes used across the app,
+ * on the BACKEND (routes, services) and the FRONTEND. Import from '../shared/types'.
+ *
+ * Defining types here (instead of inline) is what keeps a growing codebase clean:
+ * one place to change a shape, and the compiler enforces it everywhere it's used.
+ */
+export interface Greeting {
+  message: string
+  at: string
+}

package/templates/default/stores/ui.ts

@@ -0,0 +1,9 @@
+import { defineStore } from '@apex-stack/core'
+
+// Global, SSR-safe state shared across pages, components, and islands: $store.ui
+export default defineStore('ui', () => ({
+  menuOpen: false,
+  toggleMenu() {
+    this.menuOpen = !this.menuOpen
+  },
+}))

package/templates/default/tests/greeting.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { GreetingService } from '../services/GreetingService'
+
+// Services are plain classes, so they test in isolation — no server needed.
+// Generate more with:  apex make test <name>
+describe('GreetingService', () => {
+  it('greets by name', () => {
+    const g = new GreetingService().greet('Apex')
+    expect(g.message).toBe('Hello, Apex!')
+    expect(typeof g.at).toBe('string')
+  })
+})

package/templates/default/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["server", "services", "shared", "stores", "composables", "tests", "db"]
+}

package/templates/default/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})

package/dist/chunk-HRJTOSYH.js

@@ -1,8 +0,0 @@
-// src/api/resource.ts
-function isApexResource(x) {
-  return typeof x === "object" && x !== null && x.__apexResource === true;
-}
-
-export {
-  isApexResource
-};

package/dist/chunk-MZVLRU3R.js

@@ -1,15 +0,0 @@
-// src/store.ts
-function defineStore(name, factory) {
-  if (!name || /[^a-zA-Z0-9_$]/.test(name)) {
-    throw new Error(`defineStore: invalid store name "${name}" \u2014 use letters, digits, _ or $.`);
-  }
-  return { __apexStore: true, name, factory };
-}
-function isApexStore(x) {
-  return typeof x === "object" && x !== null && x.__apexStore === true;
-}
-
-export {
-  defineStore,
-  isApexStore
-};