@apex-stack/core 0.1.19 → 0.1.20

package/dist/{build-J47A3B4Y.js → build-PETU3URU.js}

@@ -5,7 +5,7 @@ import {
   renderIslandsPage,
   renderPage,
   scanPages
-} from "./chunk-XSN6NDWP.js";
+} from "./chunk-4FUWZLVW.js";
 import "./chunk-MZVLRU3R.js";
 
 // src/commands/build.ts
@@ -38,8 +38,8 @@ async function buildClient(root, routes, outDir) {
         return [
           `import Alpine from 'alpinejs'`,
           `import ${JSON.stringify(pageId)}`,
-          `window.Alpine = Alpine`,
-          `Alpine.start()`
+          "window.Alpine = Alpine",
+          "Alpine.start()"
         ].join("\n");
       }
     }
@@ -55,7 +55,9 @@ async function buildClient(root, routes, outDir) {
       rollupOptions: { input }
     }
   });
-  const manifest = JSON.parse(readFileSync(join(outDir, ".vite", "manifest.json"), "utf8"));
+  const manifest = JSON.parse(
+    readFileSync(join(outDir, ".vite", "manifest.json"), "utf8")
+  );
   const hrefs = /* @__PURE__ */ new Map();
   for (const r of routes) {
     const virt = `${VIRT}${r.pageId}`;
@@ -136,8 +138,16 @@ var buildCommand = defineCommand({
   args: {
     root: { type: "positional", required: false, description: "Project root", default: "." },
     outDir: { type: "string", description: "Output directory", default: "dist" },
-    islands: { type: "boolean", description: "Static-first islands mode (zero-JS static)", default: false },
-    server: { type: "boolean", description: "Build a Node server (dynamic routes + API/MCP)", default: false }
+    islands: {
+      type: "boolean",
+      description: "Static-first islands mode (zero-JS static)",
+      default: false
+    },
+    server: {
+      type: "boolean",
+      description: "Build a Node server (dynamic routes + API/MCP)",
+      default: false
+    }
   },
   async run({ args }) {
     const root = resolve(process.cwd(), args.root);
@@ -179,7 +189,7 @@ var buildCommand = defineCommand({
       if (existsSync2(pub)) cpSync(pub, outDir, { recursive: true });
       console.log(
         `
-  Built ${staticRoutes.length} page(s) \u2192 ${args.outDir}/` + (args.islands ? " (islands / static-first)" : " (prerendered + hydrated)")
+  Built ${staticRoutes.length} page(s) \u2192 ${args.outDir}/${args.islands ? " (islands / static-first)" : " (prerendered + hydrated)"}`
       );
       if (dynamic.length) {
         console.log(

package/dist/{chunk-XSN6NDWP.js → chunk-4FUWZLVW.js}

@@ -176,7 +176,11 @@ function storesInitialState(stores) {
 }
 
 // src/dev/renderPage.ts
-import { renderComponent, renderFragment, stateIsland } from "@apex-stack/kit";
+import {
+  renderComponent,
+  renderFragment,
+  stateIsland
+} from "@apex-stack/kit";
 function escAttr(s) {
   return String(s).replace(
     /[&<>"]/g,
@@ -186,10 +190,14 @@ function escAttr(s) {
 function renderHead(head) {
   const parts = [`<title>${head?.title ? escAttr(head.title) : "Apex JS"}</title>`];
   for (const m of head?.meta ?? []) {
-    parts.push(`<meta ${Object.entries(m).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`);
+    parts.push(
+      `<meta ${Object.entries(m).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`
+    );
   }
   for (const l of head?.link ?? []) {
-    parts.push(`<link ${Object.entries(l).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`);
+    parts.push(
+      `<link ${Object.entries(l).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`
+    );
   }
   return parts.join("\n  ");
 }

package/dist/{chunk-JWYNLP4L.js → chunk-G77MLFUJ.js}

@@ -111,7 +111,10 @@ function buildServer(entries) {
         inputSchema: entry.route.inputShape ?? {}
       },
       async (args) => {
-        const result = await entry.route.handler({ input: args ?? {}, url: `mcp://${entry.mcpName}` });
+        const result = await entry.route.handler({
+          input: args ?? {},
+          url: `mcp://${entry.mcpName}`
+        });
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
       }
     );

package/dist/cli.js

@@ -11,11 +11,21 @@ import { defineCommand as defineCommand2, runMain } from "citty";
 
 // src/commands/new.ts
 import { spawn, spawnSync } from "child_process";
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "fs";
 import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { defineCommand } from "citty";
 var TEMPLATE_DIR = fileURLToPath(new URL("../templates/default", import.meta.url));
+function substituteName(dir, name) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) substituteName(p, name);
+    else {
+      const txt = readFileSync(p, "utf8");
+      if (txt.includes("{{name}}")) writeFileSync(p, txt.replaceAll("{{name}}", name));
+    }
+  }
+}
 function detectPackageManager() {
   const ua = process.env.npm_config_user_agent || "";
   if (ua.startsWith("pnpm")) return "pnpm";
@@ -37,9 +47,22 @@ function installAsync(pm, cwd) {
 var newCommand = defineCommand({
   meta: { name: "new", description: "Scaffold a new Apex JS app" },
   args: {
-    dir: { type: "positional", required: false, description: "Target directory", default: "apex-app" },
-    install: { type: "boolean", default: true, description: "Install dependencies (use --no-install to skip)" },
-    git: { type: "boolean", default: true, description: "Initialize a git repository (use --no-git to skip)" }
+    dir: {
+      type: "positional",
+      required: false,
+      description: "Target directory",
+      default: "apex-app"
+    },
+    install: {
+      type: "boolean",
+      default: true,
+      description: "Install dependencies (use --no-install to skip)"
+    },
+    git: {
+      type: "boolean",
+      default: true,
+      description: "Initialize a git repository (use --no-git to skip)"
+    }
   },
   async run({ args }) {
     const dir = String(args.dir);
@@ -55,10 +78,7 @@ var newCommand = defineCommand({
     cpSync(TEMPLATE_DIR, target, { recursive: true });
     const gitignore = join(target, "_gitignore");
     if (existsSync(gitignore)) renameSync(gitignore, join(target, ".gitignore"));
-    for (const rel of ["package.json", "README.md"]) {
-      const file = join(target, rel);
-      if (existsSync(file)) writeFileSync(file, readFileSync(file, "utf8").replaceAll("{{name}}", name));
-    }
+    substituteName(target, name);
     log(`  ${color.green("\u2713")} Created ${color.bold(dir)}`);
     const pm = detectPackageManager();
     let gitOk = false;
@@ -73,7 +93,9 @@ var newCommand = defineCommand({
     if (gitOk) log(`  ${color.green("\u2713")} Initialized a git repository`);
     let installed = false;
     if (args.install) {
-      const sp = spinner(`Installing dependencies with ${pm}\u2026  ${color.dim("(first run can take a minute)")}`);
+      const sp = spinner(
+        `Installing dependencies with ${pm}\u2026  ${color.dim("(first run can take a minute)")}`
+      );
       installed = await installAsync(pm, target);
       if (installed) sp.succeed(`Dependencies installed with ${pm}`);
       else sp.fail(`Install failed \u2014 run ${color.cyan(`${pm} install`)} inside ${dir}`);
@@ -84,10 +106,14 @@ var newCommand = defineCommand({
     log(`    ${color.cyan(`cd ${dir}`)}`);
     if (!installed) log(`    ${color.cyan(pm === "yarn" ? "yarn" : `${pm} install`)}`);
     log(`    ${color.cyan("apex dev")}          ${color.gray("# \u2192 http://localhost:3000")}`);
-    log(`
-  ${color.gray("Not installed globally? Use")} ${color.cyan(`${runPrefix} dev`)}${color.gray(".")}`);
-    log(`  ${color.gray("Islands mode:")} ${color.cyan("apex dev --islands")}${color.gray("  \xB7  API routes are also MCP tools at /mcp.")}
-`);
+    log(
+      `
+  ${color.gray("Not installed globally? Use")} ${color.cyan(`${runPrefix} dev`)}${color.gray(".")}`
+    );
+    log(
+      `  ${color.gray("Islands mode:")} ${color.cyan("apex dev --islands")}${color.gray("  \xB7  API routes are also MCP tools at /mcp.")}
+`
+    );
   }
 });
 
@@ -109,27 +135,31 @@ var main = defineCommand2({
   },
   subCommands: {
     new: newCommand,
-    dev: () => import("./dev-OCVQRCCE.js").then((m) => m.devCommand),
-    build: () => import("./build-J47A3B4Y.js").then((m) => m.buildCommand),
-    start: () => import("./start-AUJJ7HAY.js").then((m) => m.startCommand),
-    make: () => import("./make-JAW22LQZ.js").then((m) => m.makeCommand),
-    migrate: () => import("./migrate-NOGFOFV2.js").then((m) => m.migrateCommand),
-    mcp: () => import("./mcp-DL4J6JFJ.js").then((m) => m.mcpCommand)
+    dev: () => import("./dev-6YCKNYJ4.js").then((m) => m.devCommand),
+    build: () => import("./build-PETU3URU.js").then((m) => m.buildCommand),
+    start: () => import("./start-V2TBGKWH.js").then((m) => m.startCommand),
+    make: () => import("./make-WM6DLDCR.js").then((m) => m.makeCommand),
+    migrate: () => import("./migrate-X6LIHMIE.js").then((m) => m.migrateCommand),
+    mcp: () => import("./mcp-CH7L4GF3.js").then((m) => m.mcpCommand)
   },
   // Shown for a bare `apex` (no subcommand): the brand banner + a command menu.
   run({ rawArgs }) {
     if (rawArgs.length > 0) return;
     process.stdout.write(banner());
     const log = console.log;
-    log(`  ${color.bold("Usage")}  ${color.gray("apex")} ${color.cyan("<command>")} ${color.gray("[options]")}
-`);
+    log(
+      `  ${color.bold("Usage")}  ${color.gray("apex")} ${color.cyan("<command>")} ${color.gray("[options]")}
+`
+    );
     log(`  ${color.bold("Commands")}`);
     for (const [name, desc] of COMMANDS) {
       log(`    ${color.cyan(`apex ${name}`.padEnd(13))} ${color.gray(desc)}`);
     }
-    log(`
+    log(
+      `
   ${color.gray("Run")} ${color.cyan("apex <command> --help")} ${color.gray("for details.")}
-`);
+`
+    );
   }
 });
 runMain(main);

package/dist/{dev-OCVQRCCE.js → dev-6YCKNYJ4.js}

@@ -12,7 +12,11 @@ var devCommand = defineCommand({
   args: {
     root: { type: "positional", required: false, description: "Project root", default: "." },
     port: { type: "string", description: "Port to listen on", default: "3000" },
-    islands: { type: "boolean", description: "Render in islands mode (static-first)", default: false }
+    islands: {
+      type: "boolean",
+      description: "Render in islands mode (static-first)",
+      default: false
+    }
   },
   async run({ args }) {
     const root = resolve(process.cwd(), String(args.root));
@@ -20,7 +24,7 @@ var devCommand = defineCommand({
     process.stdout.write(banner());
     const sp = spinner(`Starting dev server${args.islands ? " (islands mode)" : ""}\u2026`);
     try {
-      const { startDevServer } = await import("./server-L3V34B5X.js");
+      const { startDevServer } = await import("./server-62UM2N5C.js");
       const { port: actual } = await startDevServer({ root, port, islands: Boolean(args.islands) });
       sp.succeed("Dev server ready");
       ready([

package/dist/{make-JAW22LQZ.js → make-WM6DLDCR.js}

@@ -79,32 +79,74 @@ export default defineApexRoute({
 })
 `;
 }
+function serviceTemplate(name) {
+  const cls = `${pascalCase(name)}Service`;
+  return `/**
+ * ${cls} \u2014 business logic as a plain, testable class. Keep routes and loaders
+ * thin and delegate to services like this one (the clean-code backbone).
+ */
+export class ${cls} {
+  // Replace with your methods.
+  run(input: string): string {
+    return input
+  }
+}
+`;
+}
+function testTemplate(name) {
+  return `import { describe, expect, it } from 'vitest'
+
+describe('${name}', () => {
+  it('works', () => {
+    expect(true).toBe(true)
+  })
+})
+`;
+}
 function plan(kind, name, root) {
   switch (kind) {
     case "page":
       return { path: join(root, "pages", `${name}.alpine`), contents: pageTemplate(name) };
     case "component":
-      return { path: join(root, "components", `${pascalCase(name)}.alpine`), contents: componentTemplate() };
+      return {
+        path: join(root, "components", `${pascalCase(name)}.alpine`),
+        contents: componentTemplate()
+      };
     case "api":
       return { path: join(root, "server", "api", `${name}.ts`), contents: apiTemplate(name) };
     case "store":
       return { path: join(root, "stores", `${name}.ts`), contents: storeTemplate(name) };
     case "layout":
       return { path: join(root, "layouts", `${name}.alpine`), contents: layoutTemplate() };
+    case "service":
+      return {
+        path: join(root, "services", `${pascalCase(name)}Service.ts`),
+        contents: serviceTemplate(name)
+      };
+    case "test":
+      return { path: join(root, "tests", `${name}.test.ts`), contents: testTemplate(name) };
   }
 }
 var makeCommand = defineCommand({
-  meta: { name: "make", description: "Generate a page, component, API route, store, or layout" },
+  meta: {
+    name: "make",
+    description: "Generate a page, component, API route, store, layout, service, or test"
+  },
   args: {
-    kind: { type: "positional", required: true, description: "page | component | api | store | layout" },
+    kind: {
+      type: "positional",
+      required: true,
+      description: "page | component | api | store | layout | service | test"
+    },
     name: { type: "positional", required: true, description: "Name (about, Counter, todos, \u2026)" },
     root: { type: "string", description: "Project root", default: "." }
   },
   run({ args }) {
     const kind = args.kind;
-    if (kind !== "page" && kind !== "component" && kind !== "api" && kind !== "store" && kind !== "layout") {
+    const kinds = ["page", "component", "api", "store", "layout", "service", "test"];
+    if (!kinds.includes(kind)) {
       console.error(`
-  Unknown type "${args.kind}". Use: page | component | api | store | layout
+  Unknown type "${args.kind}". Use: ${kinds.join(" | ")}
 `);
       process.exit(1);
     }

package/dist/{mcp-DL4J6JFJ.js → mcp-CH7L4GF3.js}

@@ -30,7 +30,7 @@ var mcpCommand = defineCommand({
       console.log(`
   \x1B[36m${args.call}\x1B[0m(${args.args}) \u2192`);
       for (const part of result.content) {
-        console.log("  " + (part.text ?? JSON.stringify(part)));
+        console.log(`  ${part.text ?? JSON.stringify(part)}`);
       }
       console.log();
     } else {

package/dist/{migrate-NOGFOFV2.js → migrate-X6LIHMIE.js}

@@ -19,7 +19,9 @@ var migrateCommand = defineCommand({
       const require2 = createRequire(join(root, "package.json"));
       data = await import(pathToFileURL(require2.resolve("@apex-stack/data")).href);
     } catch {
-      console.error("\n  @apex-stack/data is not installed in this project. Run: npm i @apex-stack/data\n");
+      console.error(
+        "\n  @apex-stack/data is not installed in this project. Run: npm i @apex-stack/data\n"
+      );
       process.exit(1);
     }
     const config = args.driver === "postgres" ? { driver: "postgres", url: args.url } : args.driver === "pglite" ? { driver: "pglite", dir: args.url } : resolve(root, args.db);

package/dist/{server-L3V34B5X.js → server-62UM2N5C.js}

@@ -5,7 +5,7 @@ import {
   createApiHandler,
   createMcpHandler,
   loadApiRoutes
-} from "./chunk-JWYNLP4L.js";
+} from "./chunk-G77MLFUJ.js";
 import "./chunk-HRJTOSYH.js";
 import {
   loadStores,
@@ -13,7 +13,7 @@ import {
   renderIslandsPage,
   renderPage,
   scanPages
-} from "./chunk-XSN6NDWP.js";
+} from "./chunk-4FUWZLVW.js";
 import "./chunk-MZVLRU3R.js";
 
 // src/dev/server.ts
@@ -36,20 +36,24 @@ import { createServer as createViteServer } from "vite";
 // src/dev/errorPage.ts
 import { existsSync, readFileSync } from "fs";
 function esc(s) {
-  return s.replace(/[&<>"]/g, (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : "&quot;");
+  return s.replace(
+    /[&<>"]/g,
+    (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : "&quot;"
+  );
 }
 function firstFileFrame(stack, root) {
   const re = /(?:file:\/\/\/?)?((?:[A-Za-z]:[\\/]|\/)[^\s():]+):(\d+):(\d+)/g;
-  let m;
   const frames = [];
-  while (m = re.exec(stack)) {
+  let m = re.exec(stack);
+  while (m) {
     const raw = m[1];
-    if (!raw) continue;
-    if (/^[A-Za-z]:[\\/]/.test(raw) === false && !raw.startsWith("/")) continue;
-    const file = raw.replace(/\//g, process.platform === "win32" ? "\\" : "/");
-    if (existsSync(file) && !file.includes("node_modules")) {
-      frames.push({ file, line: Number(m[2] ?? 0), col: Number(m[3] ?? 0) });
+    if (raw && (/^[A-Za-z]:[\\/]/.test(raw) || raw.startsWith("/"))) {
+      const file = raw.replace(/\//g, process.platform === "win32" ? "\\" : "/");
+      if (existsSync(file) && !file.includes("node_modules")) {
+        frames.push({ file, line: Number(m[2] ?? 0), col: Number(m[3] ?? 0) });
+      }
     }
+    m = re.exec(stack);
   }
   return frames.find((f) => f.file.startsWith(root)) ?? frames[0];
 }
@@ -174,7 +178,9 @@ async function startDevServer(options) {
     plugins.unshift(tw());
   } catch {
   }
-  const appCssRel = ["app.css", "styles/app.css", "src/app.css"].find((p) => existsSync2(join(options.root, p)));
+  const appCssRel = ["app.css", "styles/app.css", "src/app.css"].find(
+    (p) => existsSync2(join(options.root, p))
+  );
   const appCss = appCssRel ? `/${appCssRel}` : void 0;
   const vite = await createViteServer({
     root: options.root,
@@ -195,8 +201,14 @@ async function startDevServer(options) {
   const app = createApp();
   app.use(fromNodeMiddleware(vite.middlewares));
   const loadEntries = () => loadApiRoutes(options.root, (id) => ssrLoad(id));
-  app.use("/api", defineEventHandler((event) => loadEntries().then((e) => createApiHandler(e)(event))));
-  app.use("/mcp", defineEventHandler((event) => loadEntries().then((e) => createMcpHandler(e)(event))));
+  app.use(
+    "/api",
+    defineEventHandler((event) => loadEntries().then((e) => createApiHandler(e)(event)))
+  );
+  app.use(
+    "/mcp",
+    defineEventHandler((event) => loadEntries().then((e) => createMcpHandler(e)(event)))
+  );
   app.use(
     defineEventHandler(async (event) => {
       const url = event.path || "/";
@@ -252,9 +264,7 @@ async function startDevServer(options) {
     port,
     close: async () => {
       await vite.close();
-      await new Promise(
-        (resolve, reject) => server.close((e) => e ? reject(e) : resolve())
-      );
+      await new Promise((resolve, reject) => server.close((e) => e ? reject(e) : resolve()));
     }
   };
 }

package/dist/{start-AUJJ7HAY.js → start-V2TBGKWH.js}

@@ -3,13 +3,13 @@ import {
   createMcpHandler,
   expandApiModule,
   hasMcpRoutes
-} from "./chunk-JWYNLP4L.js";
+} from "./chunk-G77MLFUJ.js";
 import "./chunk-HRJTOSYH.js";
 import {
   matchRoute,
   renderIslandsPage,
   renderPage
-} from "./chunk-XSN6NDWP.js";
+} from "./chunk-4FUWZLVW.js";
 import "./chunk-MZVLRU3R.js";
 
 // src/commands/start.ts
@@ -18,8 +18,8 @@ import { join as join2, resolve } from "path";
 import { defineCommand } from "citty";
 
 // src/prod/server.ts
-import { createServer as createHttpServer } from "http";
 import { existsSync, readFileSync, statSync } from "fs";
+import { createServer as createHttpServer } from "http";
 import { join } from "path";
 import { pathToFileURL } from "url";
 import {
@@ -72,7 +72,8 @@ async function startProdServer(options) {
       if (!file.startsWith(dir) || !existsSync(file) || !statSync(file).isFile()) return;
       const ext = path.slice(path.lastIndexOf("."));
       setResponseHeader(event, "Content-Type", MIME[ext] ?? "application/octet-stream");
-      if (path.startsWith("/assets/")) setResponseHeader(event, "Cache-Control", "public, max-age=31536000, immutable");
+      if (path.startsWith("/assets/"))
+        setResponseHeader(event, "Cache-Control", "public, max-age=31536000, immutable");
       return readFileSync(file);
     })
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-stack/core",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "The full-stack meta-framework for Alpine.js — CLI and runtime",
   "type": "module",
   "license": "MIT",

package/templates/default/README.md

@@ -1,33 +1,55 @@
 # {{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
-
-Ship interactive JavaScript only where you need it:
+## Project structure
 
-```bash
-apex dev --islands
+```
+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.
 ```
 
-## Project structure
+## 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`).
 
-- `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`.
+## Generators
 
-## AI-native API
+```bash
+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 test billing        # → tests/billing.test.ts
+```
 
-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/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'],
+  },
+})