@apex-stack/core 0.1.20 → 0.2.1

package/dist/{start-V2TBGKWH.js → start-3O3E43PT.js}

@@ -2,15 +2,17 @@ import {
   createApiHandler,
   createMcpHandler,
   expandApiModule,
-  hasMcpRoutes
-} from "./chunk-G77MLFUJ.js";
-import "./chunk-HRJTOSYH.js";
+  hasMcpRoutes,
+  runMiddleware
+} from "./chunk-HCNNKT4A.js";
+import "./chunk-2C2HRLIY.js";
 import {
+  applyEnvToRuntimeConfig,
   matchRoute,
   renderIslandsPage,
   renderPage
-} from "./chunk-4FUWZLVW.js";
-import "./chunk-MZVLRU3R.js";
+} from "./chunk-XDKJO6ZC.js";
+import "./chunk-JLIAISWM.js";
 
 // src/commands/start.ts
 import { existsSync as existsSync2 } from "fs";
@@ -25,6 +27,7 @@ import { pathToFileURL } from "url";
 import {
   createApp,
   defineEventHandler,
+  getRequestHeaders,
   getRequestURL,
   setResponseHeader,
   setResponseStatus,
@@ -46,6 +49,11 @@ async function startProdServer(options) {
   const dir = options.dir;
   const port = options.port ?? 3e3;
   const manifest = JSON.parse(readFileSync(join(dir, "apex-manifest.json"), "utf8"));
+  const runtimeConfig = applyEnvToRuntimeConfig(
+    manifest.runtimeConfig ?? { public: {} },
+    process.cwd()
+  );
+  const publicConfig = runtimeConfig.public ?? {};
   const importServer = (relFile) => import(pathToFileURL(join(dir, "server", relFile)).href);
   const registry = {};
   let componentCss = "";
@@ -60,7 +68,13 @@ async function startProdServer(options) {
     const mod = await importServer(serverFile);
     apiEntries.push(...expandApiModule(name, mod.default));
   }
+  const middleware = [];
+  for (const { serverFile } of manifest.middleware ?? []) {
+    const mod = await importServer(serverFile);
+    if (typeof mod.default === "function") middleware.push(mod.default);
+  }
   const serverFileFor = new Map(manifest.routes.map((r) => [r.pageId, r.serverFile]));
+  const errorPageId = serverFileFor.has("/pages/error.alpine") ? "/pages/error.alpine" : void 0;
   const loadModule = (id) => importServer(serverFileFor.get(id));
   const app = createApp();
   app.use(
@@ -77,8 +91,26 @@ async function startProdServer(options) {
       return readFileSync(file);
     })
   );
-  if (apiEntries.length) app.use("/api", createApiHandler(apiEntries));
-  if (hasMcpRoutes(apiEntries)) app.use("/mcp", createMcpHandler(apiEntries));
+  if (middleware.length) {
+    app.use(
+      defineEventHandler(async (event) => {
+        const { redirect, locals } = await runMiddleware(middleware, {
+          url: getRequestURL(event).pathname,
+          method: event.method,
+          config: runtimeConfig,
+          headers: getRequestHeaders(event)
+        });
+        event.context.apexLocals = locals;
+        if (redirect) {
+          setResponseStatus(event, redirect.status);
+          setResponseHeader(event, "Location", redirect.to);
+          return "";
+        }
+      })
+    );
+  }
+  if (apiEntries.length) app.use("/api", createApiHandler(apiEntries, runtimeConfig));
+  if (hasMcpRoutes(apiEntries)) app.use("/mcp", createMcpHandler(apiEntries, runtimeConfig));
   app.use(
     defineEventHandler(async (event) => {
       const url = getRequestURL(event).pathname;
@@ -97,7 +129,11 @@ async function startProdServer(options) {
         url,
         registry,
         componentCss,
-        clientHref: route?.clientHref
+        clientHref: route?.clientHref,
+        runtimeConfig,
+        publicConfig,
+        locals: event.context.apexLocals ?? {},
+        errorPageId
       });
       setResponseHeader(event, "Content-Type", "text/html");
       return html;

package/dist/upgrade-WC5F5FKY.js

@@ -0,0 +1,168 @@
+import {
+  offerExtension
+} from "./chunk-CHBSGOB3.js";
+import {
+  VERSION,
+  banner,
+  color
+} from "./chunk-QIXJSQLW.js";
+
+// src/commands/upgrade.ts
+import { spawnSync } from "child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { basename, dirname, join, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+import { defineCommand } from "citty";
+var TEMPLATE_DIR = fileURLToPath(new URL("../templates/default", import.meta.url));
+var PROTECTED = /* @__PURE__ */ new Set(["package.json"]);
+function projectName(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name || basename(root);
+  } catch {
+    return basename(root);
+  }
+}
+function bumpApexDeps(root) {
+  const pkgPath = join(root, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  let bumped = 0;
+  for (const field of ["dependencies", "devDependencies"]) {
+    const deps = pkg[field];
+    if (!deps) continue;
+    for (const dep of Object.keys(deps)) {
+      if (dep.startsWith("@apex-stack/") && /^[\d^~]/.test(deps[dep] ?? "")) {
+        if (deps[dep] !== `^${VERSION}`) {
+          deps[dep] = `^${VERSION}`;
+          bumped++;
+        }
+      }
+    }
+  }
+  if (bumped) writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`);
+  return bumped;
+}
+function detectPm() {
+  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 walk(dir, onFile) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, onFile);
+    else onFile(p);
+  }
+}
+function targetRelPath(rel) {
+  return basename(rel) === "_gitignore" ? join(dirname(rel), ".gitignore") : rel;
+}
+var upgradeCommand = defineCommand({
+  meta: {
+    name: "upgrade",
+    description: "Adopt new scaffold defaults in an existing app (non-destructive)"
+  },
+  args: {
+    root: { type: "positional", required: false, description: "Project root", default: "." },
+    force: {
+      type: "boolean",
+      default: false,
+      description: "Re-sync files that differ from the template (package.json is always preserved)"
+    },
+    install: {
+      type: "boolean",
+      default: true,
+      description: "Run the package manager after bumping @apex-stack/* (use --no-install to skip)"
+    },
+    vscode: {
+      type: "boolean",
+      description: "Install the Apex VS Code extension (skip the prompt)"
+    }
+  },
+  async run({ args }) {
+    const root = resolve(process.cwd(), String(args.root));
+    const log = console.log;
+    if (!existsSync(join(root, "package.json"))) {
+      console.error(`
+  ${color.red("\u2717")} No package.json in ${root} \u2014 is this an Apex project?
+`);
+      process.exit(1);
+    }
+    const name = projectName(root);
+    process.stdout.write(banner());
+    const added = [];
+    const updated = [];
+    let unchanged = 0;
+    walk(TEMPLATE_DIR, (absFile) => {
+      const rel = targetRelPath(relative(TEMPLATE_DIR, absFile));
+      const target = join(root, rel);
+      let content = readFileSync(absFile, "utf8");
+      if (content.includes("{{name}}")) content = content.replaceAll("{{name}}", name);
+      if (!existsSync(target)) {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        added.push(rel);
+        return;
+      }
+      if (args.force && !PROTECTED.has(rel)) {
+        if (readFileSync(target, "utf8") !== content) {
+          writeFileSync(target, content);
+          updated.push(rel);
+          return;
+        }
+      }
+      unchanged++;
+    });
+    if (added.length) {
+      log(`
+  ${color.green("+")} Added ${added.length} new file(s):`);
+      for (const f of added.sort()) log(`      ${color.green(f)}`);
+    }
+    if (updated.length) {
+      log(`
+  ${color.cyan("~")} Re-synced ${updated.length} file(s):`);
+      for (const f of updated.sort()) log(`      ${color.cyan(f)}`);
+    }
+    if (added.length || updated.length) {
+      log(`
+  ${color.gray(`${unchanged} existing file(s) left untouched.`)}`);
+    }
+    const bumped = bumpApexDeps(root);
+    if (bumped)
+      log(`
+  ${color.cyan("\u2191")} Bumped ${bumped} @apex-stack/* dependency \u2192 ^${VERSION}`);
+    if (!added.length && !updated.length && !bumped) {
+      log(`
+  ${color.green("\u2713")} Already up to date.`);
+    }
+    if (bumped && args.install) {
+      const pm = detectPm();
+      log(`
+  ${color.gray(`Installing with ${pm}\u2026`)}`);
+      const ok = spawnSync(pm, ["install"], {
+        cwd: root,
+        stdio: "inherit",
+        shell: process.platform === "win32"
+      }).status === 0;
+      log(
+        ok ? `  ${color.green("\u2713")} Dependencies updated` : `  ${color.red("\u2717")} Install failed \u2014 run ${color.cyan(`${pm} install`)} yourself`
+      );
+    } else if (bumped) {
+      log(
+        `  ${color.gray("Run")} ${color.cyan(`${detectPm()} install`)} ${color.gray("to apply.")}`
+      );
+    }
+    const ext = await offerExtension(args.vscode);
+    if (ext) log(`  ${color.green("\u2713")} ${ext}`);
+    log(
+      `
+  ${color.gray("Non-destructive: your files are never overwritten")}${args.force ? color.gray(" except with --force") : color.gray(" (use --force to re-sync)")}${color.gray("; package.json entries are only version-bumped.")}
+`
+    );
+  }
+});
+export {
+  upgradeCommand
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-stack/core",
-  "version": "0.1.20",
+  "version": "0.2.1",
   "description": "The full-stack meta-framework for Alpine.js — CLI and runtime",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,8 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "vscode"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -45,8 +46,8 @@
     "h3": "^1.13.0",
     "vite": "^6.0.7",
     "zod": "^4.4.3",
-    "@apex-stack/kit": "0.1.5",
-    "@apex-stack/vite": "0.1.5"
+    "@apex-stack/kit": "0.2.0",
+    "@apex-stack/vite": "0.1.6"
   },
   "peerDependencies": {
     "alpinejs": "^3.14.0"

package/templates/default/.env.example

@@ -0,0 +1,9 @@
+# Copy to `.env` and fill in. These override the defaults in apex.config.ts.
+# Private keys: APEX_<KEY>.  Public keys (sent to the browser): APEX_PUBLIC_<KEY>.
+
+# Private — server-only
+APEX_API_SECRET=
+
+# Public — readable in the browser
+APEX_PUBLIC_APP_NAME={{name}}
+APEX_PUBLIC_SITE_URL=http://localhost:3000

package/templates/default/README.md

@@ -49,7 +49,31 @@ 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
+apex make middleware auth      # → middleware/auth.ts (runs on every request)
+apex make test billing         # → tests/billing.test.ts
+```
+
+## Styling
+
+- **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.
+
+## 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)
 ```
 
 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/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
-};