@apex-stack/core 0.1.8 → 0.1.9

package/dist/cli.js

@@ -13,8 +13,8 @@ import {
 } from "./chunk-IEXQ7E5C.js";
 
 // src/cli.ts
-import { resolve as resolve5 } from "path";
-import { defineCommand as defineCommand6, runMain } from "citty";
+import { resolve as resolve6 } from "path";
+import { defineCommand as defineCommand7, runMain } from "citty";
 
 // src/commands/build.ts
 import { cpSync, existsSync as existsSync2, mkdirSync, readdirSync as readdirSync2, rmSync, writeFileSync } from "fs";
@@ -417,15 +417,106 @@ var migrateCommand = defineCommand4({
   }
 });
 
-// src/commands/start.ts
-import { existsSync as existsSync5 } from "fs";
-import { join as join7, resolve as resolve4 } from "path";
+// src/commands/new.ts
+import { spawnSync } from "child_process";
+import { cpSync as cpSync2, existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync2, renameSync, writeFileSync as writeFileSync3 } from "fs";
+import { basename, join as join6, resolve as resolve4 } from "path";
+import { fileURLToPath } from "url";
 import { defineCommand as defineCommand5 } from "citty";
+var TEMPLATE_DIR = fileURLToPath(new URL("../templates/default", import.meta.url));
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  return "npm";
+}
+function run(cmd, cmdArgs, cwd, quiet = false) {
+  const res = spawnSync(cmd, cmdArgs, {
+    cwd,
+    stdio: quiet ? "ignore" : "inherit",
+    shell: process.platform === "win32"
+    // npm/pnpm/yarn are .cmd shims on Windows
+  });
+  return res.status === 0;
+}
+var c = {
+  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`
+};
+var newCommand = defineCommand5({
+  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)" }
+  },
+  run({ args }) {
+    const target = resolve4(process.cwd(), String(args.dir));
+    const name = basename(target);
+    if (existsSync4(target) && readdirSync3(target).length > 0) {
+      console.error(`
+  \u2717 Target directory is not empty: ${target}
+`);
+      process.exit(1);
+    }
+    cpSync2(TEMPLATE_DIR, target, { recursive: true });
+    const gitignore = join6(target, "_gitignore");
+    if (existsSync4(gitignore)) renameSync(gitignore, join6(target, ".gitignore"));
+    for (const rel of ["package.json", "README.md"]) {
+      const file = join6(target, rel);
+      if (existsSync4(file)) writeFileSync3(file, readFileSync2(file, "utf8").replaceAll("{{name}}", name));
+    }
+    const log = console.log;
+    log(`
+  ${c.cyan("Apex JS")} app created in ${args.dir}`);
+    const pm = detectPackageManager();
+    let gitOk = false;
+    if (args.git) {
+      const hasGit = spawnSync("git", ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0;
+      if (hasGit && run("git", ["init", "-q"], target, true)) {
+        run("git", ["add", "-A"], target, true);
+        run("git", ["commit", "-m", "Initial commit from Apex JS", "--no-gpg-sign"], target, true);
+        gitOk = true;
+      }
+    }
+    let installed = false;
+    if (args.install) {
+      log(`
+  Installing dependencies with ${c.cyan(pm)}\u2026 ${c.dim("(first install can take a minute)")}
+`);
+      const installArgs = pm === "npm" ? ["install", "--no-audit", "--no-fund"] : ["install"];
+      installed = run(pm, installArgs, target);
+      if (!installed) log(`
+  ${c.yellow("\u26A0")}  Dependency install failed \u2014 run it yourself after cd'ing in.
+`);
+    }
+    const runPrefix = pm === "npm" ? "npm run" : pm;
+    const steps = [`cd ${args.dir}`];
+    if (!installed) steps.push(pm === "yarn" ? "yarn" : `${pm} install`);
+    steps.push(`apex dev          ${c.dim("# start the dev server \u2192 http://localhost:3000")}`);
+    log(`
+  ${installed ? c.green("Ready.") : "Next steps:"}
+${steps.map((s) => `    ${s}`).join("\n")}
+
+  ${c.dim("Not global? Run")} ${c.cyan(runPrefix + " dev")}${c.dim(" instead of ")}${c.cyan("apex dev")}${c.dim(".")}
+  ${c.dim("Islands mode:")} apex dev --islands
+  ${gitOk ? c.dim("Git repository initialized. ") : ""}Your server/api/*.ts routes are also MCP tools at /mcp.
+`);
+  }
+});
+
+// src/commands/start.ts
+import { existsSync as existsSync6 } from "fs";
+import { join as join8, resolve as resolve5 } from "path";
+import { defineCommand as defineCommand6 } from "citty";
 
 // src/prod/server.ts
 import { createServer as createHttpServer } from "http";
-import { existsSync as existsSync4, readFileSync as readFileSync2, statSync } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync3, statSync } from "fs";
+import { join as join7 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   createApp,
@@ -450,8 +541,8 @@ var MIME = {
 async function startProdServer(options) {
   const dir = options.dir;
   const port = options.port ?? 3e3;
-  const manifest = JSON.parse(readFileSync2(join6(dir, "apex-manifest.json"), "utf8"));
-  const importServer = (relFile) => import(pathToFileURL2(join6(dir, "server", relFile)).href);
+  const manifest = JSON.parse(readFileSync3(join7(dir, "apex-manifest.json"), "utf8"));
+  const importServer = (relFile) => import(pathToFileURL2(join7(dir, "server", relFile)).href);
   const registry = {};
   let componentCss = "";
   for (const [name, file] of Object.entries(manifest.components)) {
@@ -473,12 +564,12 @@ async function startProdServer(options) {
       if (event.method !== "GET") return;
       const path = decodeURIComponent(getRequestURL(event).pathname);
       if (path === "/" || path.startsWith("/api") || path === "/mcp") return;
-      const file = join6(dir, path);
-      if (!file.startsWith(dir) || !existsSync4(file) || !statSync(file).isFile()) return;
+      const file = join7(dir, path);
+      if (!file.startsWith(dir) || !existsSync5(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");
-      return readFileSync2(file);
+      return readFileSync3(file);
     })
   );
   if (apiEntries.length) app.use("/api", createApiHandler(apiEntries));
@@ -508,20 +599,20 @@ async function startProdServer(options) {
     })
   );
   const server = createHttpServer(toNodeListener(app));
-  await new Promise((resolve6) => server.listen(port, resolve6));
+  await new Promise((resolve7) => server.listen(port, resolve7));
   return { server, port };
 }
 
 // src/commands/start.ts
-var startCommand = defineCommand5({
+var startCommand = defineCommand6({
   meta: { name: "start", description: "Run a production build (from `apex build --server`)" },
   args: {
     dir: { type: "positional", required: false, description: "Build directory", default: "dist" },
     port: { type: "string", description: "Port to listen on", default: "3000" }
   },
   async run({ args }) {
-    const dir = resolve4(process.cwd(), args.dir);
-    if (!existsSync5(join7(dir, "apex-manifest.json"))) {
+    const dir = resolve5(process.cwd(), args.dir);
+    if (!existsSync6(join8(dir, "apex-manifest.json"))) {
       console.error(`
   No build found in ${args.dir}/. Run \`apex build --server\` first.
 `);
@@ -536,7 +627,7 @@ var startCommand = defineCommand5({
 });
 
 // src/cli.ts
-var dev = defineCommand6({
+var dev = defineCommand7({
   meta: { name: "dev", description: "Start the Apex JS development server" },
   args: {
     root: { type: "positional", required: false, description: "Project root", default: "." },
@@ -544,7 +635,7 @@ var dev = defineCommand6({
     islands: { type: "boolean", description: "Render in islands mode (static-first)", default: false }
   },
   async run({ args }) {
-    const root = resolve5(process.cwd(), args.root);
+    const root = resolve6(process.cwd(), args.root);
     const port = Number(args.port);
     const { port: actual } = await startDevServer({ root, port, islands: args.islands });
     console.log(`
@@ -553,12 +644,13 @@ var dev = defineCommand6({
 `);
   }
 });
-var main = defineCommand6({
+var main = defineCommand7({
   meta: {
     name: "apex",
     description: "The full-stack meta-framework for Alpine.js"
   },
   subCommands: {
+    new: newCommand,
     dev,
     build: buildCommand,
     start: startCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-stack/core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The full-stack meta-framework for Alpine.js — CLI and runtime",
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -54,7 +55,7 @@
     "node": ">=20.19"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "node scripts/copy-templates.mjs && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit"
   }

package/templates/default/README.md

@@ -0,0 +1,33 @@
+# {{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.
+
+## Getting started
+
+```bash
+npm install
+npm run dev
+```
+
+Then open [http://localhost:3000](http://localhost:3000).
+
+## Islands mode
+
+Ship interactive JavaScript only where you need it:
+
+```bash
+apex dev --islands
+```
+
+## Project structure
+
+- `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`.
+
+## AI-native API
+
+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.

package/templates/default/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log

package/templates/default/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "apex dev",
+    "dev:islands": "apex dev --islands"
+  },
+  "dependencies": {
+    "alpinejs": "^3.14.8",
+    "@apex-stack/core": "latest",
+    "zod": "^4.0.0"
+  }
+}

package/templates/default/pages/index.alpine

@@ -0,0 +1,107 @@
+<script server lang="ts">
+  export function loader() {
+    return {
+      title: 'Welcome to Apex JS',
+      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>
+
+    <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.
+    </p>
+  </main>
+</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;
+  }
+</style>

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

@@ -0,0 +1,10 @@
+import { defineApexRoute } from '@apex-stack/core'
+import { z } from 'zod'
+
+export default defineApexRoute({
+  method: 'GET',
+  description: 'Say hello to someone by name',
+  input: { name: z.string() },
+  mcp: true,
+  handler: ({ input }) => ({ message: `Hello, ${input.name}!` }),
+})