@apex-stack/core 0.5.0 → 0.7.0

package/templates/default/layouts/default.alpine

@@ -1,16 +1,41 @@
+<!-- The default layout wraps every page. It's themed entirely with Apex tokens
+     (bg-surface / text-on-surface / dark:*), so restyling the whole app is one
+     `apex theme` command away. <slot></slot> is where the page renders. -->
 <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>
+  <div class="flex min-h-svh flex-col bg-surface text-on-surface dark:bg-surface-dark dark:text-on-surface-dark">
+    <header class="border-b border-outline dark:border-outline-dark">
+      <nav
+        class="mx-auto flex max-w-5xl items-center gap-2 px-6 py-4"
+        x-data="{ dark: false }"
+        x-init="dark = localStorage.getItem('theme') ? localStorage.getItem('theme') === 'dark' : (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches); document.documentElement.classList.toggle('dark', dark)"
+        client:load
+      >
+        <a href="/" class="mr-auto flex items-center gap-2 font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">
+          <img src="/favicon.svg" alt="" width="24" height="24" class="size-6" />
+          {{name}}
+        </a>
+        <a href="/" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Home</a>
+        <a href="/blog" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Blog</a>
+        <a href="/about" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">About</a>
+        <button
+          type="button"
+          aria-label="Toggle dark mode"
+          class="ml-1 rounded-radius border border-outline p-2 text-on-surface hover:bg-surface-alt dark:border-outline-dark dark:text-on-surface-dark dark:hover:bg-surface-dark-alt"
+          @click="dark = !dark; document.documentElement.classList.toggle('dark', dark); localStorage.setItem('theme', dark ? 'dark' : 'light')"
+        >
+          <svg x-show="!dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
+          <svg x-cloak x-show="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+      </nav>
+    </header>
+
+    <main class="mx-auto w-full max-w-5xl flex-1 px-6 py-10">
+      <slot></slot>
+    </main>
 
-<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>
+    <footer class="border-t border-outline px-6 py-6 text-center text-sm text-on-surface/70 dark:border-outline-dark dark:text-on-surface-dark/70">
+      Built with
+      <a href="https://apexjs.site" class="font-medium text-primary dark:text-primary-dark">Apex JS</a>
+    </footer>
+  </div>
+</template>

package/templates/default/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "apex dev",
     "dev:islands": "apex dev --islands",
-    "build": "apex build",
+    "build": "apex build --server",
+    "build:static": "apex build",
     "start": "apex start",
     "test": "vitest run",
     "test:watch": "vitest",

package/templates/default/pages/about.alpine

@@ -0,0 +1,29 @@
+<script server lang="ts">
+  export function loader() {
+    return {}
+  }
+
+  // SEO for this page — server-rendered <title> + meta description.
+  export function head() {
+    return {
+      title: 'About · {{name}}',
+      meta: [{ name: 'description', content: 'What this Apex JS starter demonstrates.' }],
+    }
+  }
+</script>
+
+<template x-data>
+  <h1 class="font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong">About this starter</h1>
+  <p class="mt-3 max-w-2xl">This app was scaffolded with <code>create-apexjs</code>. It's a small tour of what Apex gives you out of the box:</p>
+
+  <ul class="mt-6 grid gap-3 sm:grid-cols-2">
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">File routing</b><span class="text-sm">Pages, dynamic <code>[slug]</code>, and a shared layout — see <code>pages/</code>.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">SSR + hydration</b><span class="text-sm">Loaders render real HTML; Alpine hydrates it with no flash.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">Themed components</b><span class="text-sm">Add more with <code>apex add &lt;name&gt;</code>; restyle with <code>apex theme</code>.</span></Card></li>
+    <li><Card><b class="text-on-surface-strong dark:text-on-surface-dark-strong">AI-native API</b><span class="text-sm">Routes double as MCP tools at <code>/mcp</code>.</span></Card></li>
+  </ul>
+
+  <p class="mt-8 text-sm text-on-surface/80 dark:text-on-surface-dark/80">
+    Edit any file under <code>pages/</code>, <code>components/</code>, or <code>app.css</code> and save — the dev server updates instantly.
+  </p>
+</template>

package/templates/default/pages/blog/[slug].alpine

@@ -0,0 +1,38 @@
+<script server lang="ts">
+  import { PostService } from '../../services/PostService'
+
+  const posts = new PostService()
+
+  // Dynamic route: pages/blog/[slug].alpine → /blog/:slug. The matched param
+  // arrives in loader({ params }).
+  export function loader({ params }: { params: Record<string, string> }) {
+    const post = posts.bySlug(params.slug)
+    return { post: post ?? null }
+  }
+
+  export function head({ data }: { data: { post: { title: string } | null } }) {
+    return { title: `${data.post ? data.post.title : 'Not found'} · {{name}}` }
+  }
+</script>
+
+<template x-data>
+  <a href="/blog" class="text-sm text-primary hover:opacity-75 dark:text-primary-dark">← Back to blog</a>
+
+  <template x-if="post">
+    <article class="mt-4">
+      <div class="flex items-center gap-2 text-sm text-on-surface/70 dark:text-on-surface-dark/70">
+        <Badge><span x-text="post.author"></span></Badge>
+        <span x-text="post.date"></span>
+      </div>
+      <h1 class="mt-3 font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong" x-text="post.title"></h1>
+      <p class="mt-4 text-lg leading-relaxed" x-text="post.body"></p>
+    </article>
+  </template>
+
+  <template x-if="!post">
+    <div class="mt-8">
+      <h1 class="font-title text-2xl font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Post not found</h1>
+      <p class="mt-2 text-on-surface/80 dark:text-on-surface-dark/80">That post doesn't exist. Try the <a href="/blog" class="text-primary dark:text-primary-dark">blog index</a>.</p>
+    </div>
+  </template>
+</template>

package/templates/default/pages/blog/index.alpine

@@ -0,0 +1,37 @@
+<script server lang="ts">
+  import { PostService } from '../../services/PostService'
+
+  const posts = new PostService()
+
+  export function loader() {
+    return { posts: posts.all() }
+  }
+
+  // head() drives <title> and meta tags — SEO, rendered on the server.
+  export function head() {
+    return { title: 'Blog · {{name}}' }
+  }
+</script>
+
+<template x-data>
+  <h1 class="font-title text-3xl font-extrabold text-on-surface-strong dark:text-on-surface-dark-strong">Blog</h1>
+  <p class="mt-2 text-on-surface/80 dark:text-on-surface-dark/80">Sample posts served from a service — no database required.</p>
+
+  <!-- Apex components work inside x-for/x-if — <Card> here is re-created per item
+       on the client, fully styled. That's the "Alpine Extreme" bit. -->
+  <div class="mt-8 grid gap-4 sm:grid-cols-2">
+    <template x-for="p in posts" :key="p.slug">
+      <a :href="'/blog/' + p.slug" class="block transition hover:opacity-75">
+        <Card>
+          <div class="flex items-center gap-2 text-xs text-on-surface/70 dark:text-on-surface-dark/70">
+            <span x-text="p.author"></span>
+            <span>·</span>
+            <span x-text="p.date"></span>
+          </div>
+          <h2 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong" x-text="p.title"></h2>
+          <p class="text-sm" x-text="p.excerpt"></p>
+        </Card>
+      </a>
+    </template>
+  </div>
+</template>

package/templates/default/pages/index.alpine

@@ -1,38 +1,72 @@
 <script server lang="ts">
+  import { PostService } from '../services/PostService'
+
+  const posts = new PostService()
+
+  // Runs on the server. Its return value becomes the page's x-data — so the
+  // HTML is rendered from real data before a single byte of JS runs.
   export function loader() {
     return {
       title: 'Welcome to {{name}}',
-      tagline: 'The meta-framework for Alpine.js — server-rendered, then hydrated.',
+      tagline: 'A full-stack, server-rendered app built on Alpine.js — themed, typed, and AI-native.',
+      recent: posts.recent(3),
     }
   }
 </script>
 
-<template x-data="{ open: false }">
-  <h1 x-text="title"></h1>
-  <p class="tagline" x-text="tagline"></p>
-
-  <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.
+<template x-data>
+  <!-- Hero -->
+  <section class="flex flex-col items-center py-10 text-center sm:py-16">
+    <img src="/favicon.svg" alt="Apex JS" width="72" height="72" class="size-16 sm:size-20 drop-shadow" />
+    <p class="mt-5 inline-flex items-center gap-2 rounded-full border border-outline px-3 py-1 text-xs font-medium text-on-surface/80 dark:border-outline-dark dark:text-on-surface-dark/80">
+      Built with <span class="font-title font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Apex&nbsp;JS</span>
     </p>
-    <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>
+    <h1 class="mt-5 font-title text-4xl font-extrabold tracking-tight text-on-surface-strong sm:text-6xl dark:text-on-surface-dark-strong" x-text="title"></h1>
+    <p class="mx-auto mt-4 max-w-2xl text-lg" x-text="tagline"></p>
+    <div class="mt-7 flex flex-wrap justify-center gap-3">
+      <a href="/blog"><Button>Read the blog</Button></a>
+      <a href="https://apexjs.site" class="inline-flex items-center justify-center rounded-radius border border-outline px-4 py-2 text-sm font-medium text-on-surface transition hover:opacity-75 dark:border-outline-dark dark:text-on-surface-dark">Docs</a>
     </div>
   </section>
 
-  <p class="hint">A reusable component that hydrates in the browser:</p>
-  <Counter start="0" label="Clicks" />
-</template>
+  <!-- Feature cards -->
+  <section class="mt-6 grid gap-4 sm:grid-cols-3">
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Server-rendered</h3>
+      <p class="text-sm">Every page is real HTML from a <code>loader()</code>, then hydrated by Alpine — fast and indexable.</p>
+    </Card>
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Themed</h3>
+      <p class="text-sm">All components use theme tokens. Restyle the whole app with one <code>apex theme</code> command.</p>
+    </Card>
+    <Card>
+      <h3 class="font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">AI-native</h3>
+      <p class="text-sm">Every typed API route is also an MCP tool your AI can call. See <code>server/api/posts.ts</code>.</p>
+    </Card>
+  </section>
 
-<style scoped>
-  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>
+  <!-- Recent posts, from the loader -->
+  <section class="mt-10">
+    <h2 class="font-title text-xl font-bold text-on-surface-strong dark:text-on-surface-dark-strong">Recent posts</h2>
+    <ul class="mt-3 divide-y divide-outline dark:divide-outline-dark">
+      <template x-for="p in recent" :key="p.slug">
+        <li class="py-3">
+          <a :href="'/blog/' + p.slug" class="font-medium text-primary hover:opacity-75 dark:text-primary-dark" x-text="p.title"></a>
+          <p class="text-sm text-on-surface/80 dark:text-on-surface-dark/80" x-text="p.excerpt"></p>
+        </li>
+      </template>
+    </ul>
+  </section>
+
+  <!-- A hydrated, interactive island. `client:load` hydrates it immediately in
+       islands mode; in default mode the whole page hydrates anyway. -->
+  <section class="mt-10 flex flex-col items-start gap-3" x-data="{ show: false }" client:load>
+    <p class="text-sm text-on-surface/80 dark:text-on-surface-dark/80">Hydrated in the browser — click it:</p>
+    <Counter start="0" label="Clicks" />
+    <button type="button" class="text-sm text-primary hover:opacity-75 dark:text-primary-dark" @click="show = !show" x-text="show ? 'Hide details' : 'How does this work?'"></button>
+    <p x-show="show" x-transition class="max-w-2xl text-sm text-on-surface/80 dark:text-on-surface-dark/80">
+      This page is <code>pages/index.alpine</code>, wrapped in <code>layouts/default.alpine</code>.
+      The server ran <code>loader()</code>, rendered the HTML, and Alpine took over in the browser — the counter and this toggle are proof.
+    </p>
+  </section>
+</template>

package/templates/default/public/favicon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Apex">
+  <defs>
+    <linearGradient id="apexLit" x1="0" y1="1" x2="1" y2="0">
+      <stop offset="0" stop-color="#22d3ee"/>
+      <stop offset="1" stop-color="#6366f1"/>
+    </linearGradient>
+  </defs>
+  <!-- Apex mark: an "A" that is also a summit. Left face lit, right face in shadow. -->
+  <path d="M32 7 L32 35 L20 56 L4 56 Z" fill="url(#apexLit)"/>
+  <path d="M32 7 L60 56 L44 56 L32 35 Z" fill="#6366f1"/>
+</svg>

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

@@ -0,0 +1,20 @@
+import { defineApexRoute } from '@apex-stack/core'
+import { z } from 'zod'
+import { PostService } from '../../services/PostService'
+
+const posts = new PostService()
+
+/**
+ * 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 "posts" at /mcp —
+ * one definition, REST + AI-callable. Try:
+ *   curl "http://localhost:3000/api/posts"
+ *   curl "http://localhost:3000/api/posts?slug=hello-apex"
+ */
+export default defineApexRoute({
+  method: 'GET',
+  description: 'List blog posts, or fetch one by slug',
+  input: { slug: z.string().optional() },
+  mcp: true,
+  handler: ({ input }) => (input.slug ? (posts.bySlug(input.slug) ?? null) : posts.all()),
+})

package/templates/default/services/PostService.ts

@@ -0,0 +1,51 @@
+import type { Post } from '../shared/types'
+
+/**
+ * A service holds business logic as a plain class — testable in isolation and
+ * reusable from routes, page loaders, and jobs. Here it stands in for a database
+ * with in-memory sample data; swap the array for a real query (see the `db/`
+ * folder and `defineResource`) and nothing else in the app changes.
+ */
+const POSTS: Post[] = [
+  {
+    slug: 'hello-apex',
+    title: 'Hello, Apex',
+    excerpt: 'Why Alpine deserved a full-stack meta-framework.',
+    author: 'Ada Lovelace',
+    date: '2026-02-01',
+    body: 'Apex renders your pages on the server as real, indexable HTML, then Alpine hydrates them in the browser — no client-side framework tax, no flash. This whole app is server-rendered from .alpine files and made interactive by Alpine.',
+  },
+  {
+    slug: 'ssr-then-hydrate',
+    title: 'SSR first, hydrate second',
+    excerpt: 'Real HTML on the first byte. Interactivity right after.',
+    author: 'Grace Hopper',
+    date: '2026-02-08',
+    body: 'Each page has a loader() that runs on the server. Its return value is handed to Alpine as x-data, so the markup you see is the markup search engines and users get instantly — then the same state powers client interactivity.',
+  },
+  {
+    slug: 'routes-are-tools',
+    title: 'Every route is also an MCP tool',
+    excerpt: 'Ship an API your AI can call — from one definition.',
+    author: 'Alan Turing',
+    date: '2026-02-15',
+    body: 'Open server/api/posts.ts: one defineApexRoute is a validated REST endpoint AND an MCP tool at /mcp. Point an AI client at it and it can list your posts with no extra glue.',
+  },
+]
+
+export class PostService {
+  /** All posts, newest first. */
+  all(): Post[] {
+    return [...POSTS].sort((a, b) => b.date.localeCompare(a.date))
+  }
+
+  /** The N most recent posts. */
+  recent(n: number): Post[] {
+    return this.all().slice(0, n)
+  }
+
+  /** A single post by its slug, or undefined. */
+  bySlug(slug: string): Post | undefined {
+    return POSTS.find((p) => p.slug === slug)
+  }
+}

package/templates/default/shared/types.ts

@@ -1,11 +1,16 @@
 /**
  * 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'.
+ * on the BACKEND (routes, services) and the FRONTEND (pages, components).
+ * 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
+export interface Post {
+  slug: string
+  title: string
+  excerpt: string
+  author: string
+  date: string
+  body: string
 }

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { PostService } from '../services/PostService'
+
+// Services are plain classes → unit-test them in isolation, no server needed.
+describe('PostService', () => {
+  const posts = new PostService()
+
+  it('lists posts newest first', () => {
+    const dates = posts.all().map((p) => p.date)
+    expect(dates.length).toBeGreaterThan(0)
+    expect(dates).toEqual([...dates].sort((a, b) => b.localeCompare(a)))
+  })
+
+  it('limits recent()', () => {
+    expect(posts.recent(2)).toHaveLength(2)
+  })
+
+  it('finds a post by slug', () => {
+    expect(posts.bySlug('hello-apex')?.title).toBe('Hello, Apex')
+    expect(posts.bySlug('nope')).toBeUndefined()
+  })
+})

package/vscode/version.txt

@@ -0,0 +1 @@
+0.1.3

package/dist/chunk-CHBSGOB3.js

@@ -1,42 +0,0 @@
-// src/vscode.ts
-import { spawnSync } from "child_process";
-import { existsSync } from "fs";
-import { createInterface } from "readline";
-import { fileURLToPath } from "url";
-var VSIX = fileURLToPath(new URL("../vscode/apex-alpine.vsix", import.meta.url));
-var WIN = process.platform === "win32";
-function extensionBundled() {
-  return existsSync(VSIX);
-}
-function hasCodeCli() {
-  try {
-    return spawnSync("code", ["--version"], { stdio: "ignore", shell: WIN }).status === 0;
-  } catch {
-    return false;
-  }
-}
-function installExtension() {
-  if (!existsSync(VSIX)) return false;
-  return spawnSync("code", ["--install-extension", VSIX, "--force"], { stdio: "inherit", shell: WIN }).status === 0;
-}
-function promptYesNo(question, def = true) {
-  if (!process.stdin.isTTY) return Promise.resolve(def);
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`${question} ${def ? "(Y/n) " : "(y/N) "}`, (answer) => {
-      rl.close();
-      const a = answer.trim().toLowerCase();
-      resolve(a === "" ? def : a === "y" || a === "yes");
-    });
-  });
-}
-async function offerExtension(choice) {
-  if (!extensionBundled() || !hasCodeCli()) return null;
-  const yes = choice ?? await promptYesNo("Install the Apex .alpine VS Code extension (syntax highlighting)?");
-  if (!yes) return null;
-  return installExtension() ? "VS Code extension installed" : "VS Code extension install failed";
-}
-
-export {
-  offerExtension
-};