xpine 0.0.58 → 0.0.60

package/.claude/worktrees/jolly-hofstadter-2764be/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "xpine",
+  "version": "0.0.59",
+  "main": "dist/index.js",
+  "dependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.758.0",
+    "@tailwindcss/postcss": "^4.1.12",
+    "builtin-modules": "^4.0.0",
+    "chokidar": "^4.0.3",
+    "dotenv": "^16.4.7",
+    "esbuild": "^0.25.0",
+    "express": "^4.21.2",
+    "express-ws": "^5.0.2",
+    "fs-extra": "^11.3.0",
+    "glob": "^11.0.1",
+    "jsonwebtoken": "^9.0.2",
+    "micromatch": "^4.0.8",
+    "minify-xml": "^4.5.2",
+    "postcss": "^8.5.3",
+    "request-ip": "^3.3.0",
+    "shelljs": "^0.9.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "yargs": "^17.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/dan-caldwell/xpine.git"
+  },
+  "scripts": {
+    "build": "tsx ./src/scripts/run-build-module.ts && npm run build:types",
+    "build:types": "sh ./src/scripts/build-types.sh",
+    "xpine-dev-server": "tsx ./src/scripts/xpine-dev-server.ts",
+    "test": "cd ./tests && npm run test",
+    "test:dev": "cd ./tests && npm run dev",
+    "test:start": "cd ./tests && npm run build && npm start",
+    "test:build": "cd ./tests && npm run build",
+    "test:build:dev": "cd ./tests && npm run build:dev",
+    "lint": "npx eslint",
+    "fix": "npx eslint --fix",
+    "release:patch": "npm run build && npm version patch && npm publish"
+  },
+  "bin": {
+    "xpine-build": "dist/src/scripts/xpine-build.js",
+    "xpine-dev": "dist/src/scripts/xpine-dev.js"
+  },
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@tailwindcss/oxide-darwin-arm64": "^4.1.3",
+    "@types/express": "^5.0.0",
+    "@types/micromatch": "^4.0.9",
+    "@types/node": "^22.13.5",
+    "@types/request-ip": "^0.0.41",
+    "@types/shelljs": "^0.8.15",
+    "@types/yargs": "^17.0.33",
+    "axios": "^1.8.4",
+    "lightningcss-darwin-arm64": "^1.29.3",
+    "typescript-eslint": "^8.29.0"
+  }
+}

package/.claude/worktrees/jolly-hofstadter-2764be/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxFragmentFactory": "html.fragment",
+    "jsxFactory": "html.createElement",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": false,
+    "forceConsistentCasingInFileNames": false,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "target": "esnext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsxImportSource": "xpine",
+    "incremental": true,
+    "allowImportingTsExtensions": true,
+    // Generate d.ts files
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "declarationMap": true,
+    "types": []
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "./node_modules",
+    "./node_modules/*",
+    "./node_modules/@types/node/index.d.ts",
+    "dist",
+    "**/*.js"
+  ],
+}

package/.claude/worktrees/jolly-hofstadter-2764be/types.ts

@@ -0,0 +1,55 @@
+import { NextFunction, Request, Response } from 'express';
+import ts from 'typescript';
+
+export type XPineConfig = {
+  [key: string]: any;
+}
+
+export type TokenUser = {
+  email?: string;
+  username?: string;
+}
+
+export type ServerRequest = Request & {
+  user?: TokenUser;
+  clientIp?: string;
+}
+
+export type WrapperProps = {
+  req: ServerRequest;
+  children: any;
+  config: ConfigFile;
+  data?: any;
+  routePath?: string;
+}
+
+export type ConfigFile = {
+  staticPaths?: boolean | (() => Promise<{ [key: string]: string }[]> | { [key: string]: string }[]);
+  wrapper?: (props: WrapperProps) => Promise<any>;
+  data?: (req: ServerRequest) => Promise<any>;
+  routeMiddleware?: (req: ServerRequest, res: Response, next: NextFunction) => void;
+  // For multi-segment dynamic routes ([...slug]): validate a slug that was not
+  // generated at build time so it can be resolved safely at request time.
+  // Return false (the default for unknown slugs) to fall through to the 404 handler.
+  isValid?: (slug: string, req: ServerRequest) => boolean | Promise<boolean>;
+}
+
+export type PageProps = {
+  req: ServerRequest;
+  res: Response;
+  data: any;
+  routePath: string;
+}
+
+export type FileItem = {
+  file: string;
+  size: number;
+}
+
+export type ComponentData = {
+  path: string;
+  contents: string;
+  clientContent: string;
+  configFiles: string[];
+  source: ts.SourceFile;
+}

package/.claude/worktrees/jolly-hofstadter-2764be/xpine.config.mjs

@@ -0,0 +1 @@
+export default {};

package/README.md

@@ -2,6 +2,17 @@
 
 Combines JSX with Alpine.js for a simpler, easier development experience. Includes a static site generator.
 
+### Quick start
+
+Scaffold a new app with pages, demo content, and an API endpoint already set up:
+
+```
+npx create-xpine-app my-app
+cd my-app
+npm install
+npm run dev
+```
+
 ### Install
 
 `npm install xpine`
@@ -155,6 +166,47 @@ You can create catch all routes by naming the file \_all\_.(jsx|tsx|js|ts). You
 
 You can get the route param in your function with req.params[0], such as how express handles catch all routes.
 
+### Multi-segment dynamic routes (`[...slug]`)
+
+Catch all (`_all_`) routes register a single Express wildcard, which means they match _every_ path under their prefix — including paths that should not exist. For deeply nested but known dynamic routes (e.g. a blog post at `/blog/technology/devops/my-blog-post`), use a multi-segment dynamic param instead. Name the file `[...slug].(jsx|tsx|js|ts)`; the captured value (which may contain slashes) is available as `req.params.slug`.
+
+Instead of a wildcard, XPine registers an **explicit Express route for each slug** returned by the `staticPaths` config function, so unknown paths safely fall through to your 404 page:
+
+```
+// /src/pages/blog/+config.ts
+export default {
+  staticPaths() {
+    // Slugs can come from a CMS/database
+    return [
+      { slug: 'technology/devops/my-blog-post' },
+    ];
+  },
+};
+```
+
+```
+// /src/pages/blog/[...slug].tsx
+import { PageProps } from 'xpine/dist/types';
+
+export default function BlogPost({ req }: PageProps) {
+  return <div>{req.params.slug}</div>;
+}
+```
+
+Each slug from `staticPaths` is also statically generated at build time. To allow slugs that are not known at build time (without falling back to an unsafe catch-all), add an `isValid` function to the config. It receives the requested slug and runs at request time; return `false` (the default for unknown slugs) to fall through to the 404 handler:
+
+```
+export default {
+  staticPaths() {
+    return [{ slug: 'technology/devops/my-blog-post' }];
+  },
+  // Resolve newly-published slugs without a rebuild
+  async isValid(slug, req) {
+    return await postExists(slug);
+  },
+};
+```
+
 ### Route specific middleware
 
 If you need route specific middleware, e.g. for file uploads, you can specify a `routeMiddleware` function in a config variable in the endpoint file:
@@ -168,6 +220,58 @@ export const config = {
 }
 ```
 
+### CSRF protection
+
+Because authentication is cookie based, state-changing requests (POST/PUT/PATCH/DELETE) are exposed to cross-site request forgery. Enable the built-in guard by setting `csrf` in your `xpine.config.mjs`:
+
+```
+export default {
+  csrf: true,
+}
+```
+
+It uses a stateless **signed double-submit cookie**. On safe requests (GET/HEAD/OPTIONS) it sets a `csrfToken` cookie (readable by client JS). On state-changing requests it requires that same token to be echoed back in an `x-csrf-token` header (or a `_csrf` form field) — a cross-site attacker can make the browser send the cookie but cannot read it or set the header, so forged requests are rejected with a 403. The token is HMAC-signed so it can't be forged even by an attacker who can plant a cookie.
+
+Set a secret via the `CSRF_SECRET` env var (it falls back to `JWT_PRIVATE_KEY`). The server fails to start if neither is set.
+
+For `fetch`/Alpine requests, read the cookie and send it back:
+```
+const token = document.cookie.split('; ').find(c => c.startsWith('csrfToken='))?.split('=')[1];
+await fetch('/api/thing', {
+  method: 'POST',
+  headers: { 'x-csrf-token': decodeURIComponent(token) },
+});
+```
+For server-rendered HTML forms, the token is available on `res.locals.csrfToken` (pages receive `res`); render it as a hidden `<input name="_csrf">`.
+
+You can customize the cookie/header/field names, cookie attributes, and skip specific path prefixes (e.g. signed webhooks):
+```
+export default {
+  csrf: {
+    headerName: 'x-csrf-token',
+    cookie: { sameSite: 'strict', secure: true },
+    ignorePaths: ['/api/webhooks/'],
+  },
+}
+```
+
+### HTML escaping (XSS protection)
+
+Values interpolated into JSX are HTML-escaped by default, so rendering user input is safe:
+```
+// req.params.slug = '<img src=x onerror=alert(1)>'
+<div>{req.params.slug}</div>   // renders &lt;img src=x onerror=alert(1)&gt;
+```
+Nested components and elements are not re-escaped, and attribute values are escaped too. Text inside `<script>`/`<style>` is left raw (it isn't HTML) — never interpolate untrusted data there.
+
+If you have trusted HTML that should render as-is, opt out explicitly with `raw()`:
+```
+import { raw } from 'xpine';
+
+<div>{raw(trustedHtmlString)}</div>
+```
+Only use `raw()` with HTML you control — never with user input.
+
 ### Static Site Generation
 
 Generate path specific static pages by specifying in the config of either the page's file, such as `/src/pages/about.tsx` with a config export:

package/create-xpine-app/README.md

@@ -0,0 +1,20 @@
+# create-xpine-app
+
+Scaffold a new [XPine](https://github.com/dan-caldwell/xpine) app (Alpine.js + JSX + Tailwind) with one command:
+
+```
+npx create-xpine-app my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Run `npx create-xpine-app .` to scaffold into the current directory.
+
+The generated app includes:
+
+- File-based routing with a shared page wrapper
+- Server-side data fetching from the [JSONPlaceholder API](https://jsonplaceholder.typicode.com) (posts and users pages)
+- A dynamic route (`/posts/[id]`) with static generation for known paths
+- An Express API endpoint (`/api/posts`)
+- Alpine.js interactivity examples and Tailwind CSS styling

package/create-xpine-app/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+
+const templateDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'template');
+
+const helpMessage = `
+Usage: npx create-xpine-app [project-name]
+
+Scaffolds a new XPine app in a directory named [project-name].
+Pass "." to scaffold into the current directory.
+
+Options:
+  -h, --help  Show this message
+`;
+
+function exitWithError(message) {
+  console.error(`\x1b[31m${message}\x1b[0m`);
+  process.exit(1);
+}
+
+function isValidProjectName(name) {
+  return /^[a-z0-9~-][a-z0-9._~-]*$/.test(name);
+}
+
+function isEmptyDir(dir) {
+  return fs.readdirSync(dir).filter((file) => file !== '.git').length === 0;
+}
+
+async function getProjectName() {
+  const arg = process.argv[2];
+  if (arg) return arg;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question('Project name: (my-xpine-app) ');
+  rl.close();
+  return answer.trim() || 'my-xpine-app';
+}
+
+if (['-h', '--help'].includes(process.argv[2])) {
+  console.log(helpMessage);
+  process.exit(0);
+}
+
+const projectName = await getProjectName();
+const useCurrentDir = projectName === '.';
+const targetDir = useCurrentDir ? process.cwd() : path.resolve(process.cwd(), projectName);
+const packageName = useCurrentDir ? path.basename(targetDir) : projectName;
+
+if (!isValidProjectName(packageName)) {
+  exitWithError(`Invalid project name: "${packageName}". Use lowercase letters, numbers, dashes, dots, and underscores.`);
+}
+
+if (fs.existsSync(targetDir) && !isEmptyDir(targetDir)) {
+  exitWithError(`The directory ${useCurrentDir ? 'you are in' : `"${projectName}"`} already exists and is not empty.`);
+}
+
+console.log(`\nScaffolding XPine app in ${targetDir}...`);
+
+fs.cpSync(templateDir, targetDir, { recursive: true });
+
+// npm strips .gitignore files from published packages, so the template ships
+// it as "gitignore" and it gets renamed here
+fs.renameSync(path.join(targetDir, 'gitignore'), path.join(targetDir, '.gitignore'));
+
+const packageJsonPath = path.join(targetDir, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+packageJson.name = packageName;
+fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+console.log(`
+Done! Next steps:
+${useCurrentDir ? '' : `
+  cd ${projectName}`}
+  npm install
+  npm run dev
+
+Your app will be running at http://localhost:3000
+`);

package/create-xpine-app/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-xpine-app",
+  "version": "0.0.1",
+  "description": "Scaffold a new XPine app with one command",
+  "type": "module",
+  "bin": {
+    "create-xpine-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/dan-caldwell/xpine.git",
+    "directory": "create-xpine-app"
+  },
+  "keywords": [
+    "xpine",
+    "create-xpine-app",
+    "alpinejs",
+    "jsx",
+    "tailwind",
+    "scaffold"
+  ],
+  "license": "ISC"
+}

package/create-xpine-app/template/README.md

@@ -0,0 +1,50 @@
+# My XPine App
+
+A starter app built with [XPine](https://github.com/dan-caldwell/xpine) — Alpine.js + JSX + Tailwind. Demo content comes from the [JSONPlaceholder API](https://jsonplaceholder.typicode.com).
+
+## Getting started
+
+```
+npm install
+npm run dev
+```
+
+Then open http://localhost:3000
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the dev server with live reload |
+| `npm run build` | Build the app for production (includes static page generation) |
+| `npm start` | Run the production build |
+| `npm run lint` | Lint the code |
+
+## Project structure
+
+```
+src/
+  components/       Shared JSX components (Base layout, Navbar)
+  pages/            File-based routes
+    +config.tsx     Shared page wrapper (applies to all pages in this folder and below)
+    index.tsx       / — home page with Alpine.js examples
+    posts/
+      index.tsx     /posts — post list fetched server-side
+      [id].tsx      /posts/:id — dynamic route with static generation for known ids
+    users/
+      index.tsx     /users
+    api/
+      posts.GET.ts  /api/posts — Express API endpoint
+    404.tsx         Not-found page
+  public/
+    scripts/        Client-side entry (starts Alpine.js)
+    styles/         Global CSS (Tailwind)
+  server/           Express server setup
+  util/             Shared server-side helpers
+```
+
+## Learn more
+
+- Page routing, static generation, API endpoints, and more: [XPine README](https://github.com/dan-caldwell/xpine#readme)
+- Alpine.js docs: https://alpinejs.dev
+- Tailwind CSS docs: https://tailwindcss.com

package/create-xpine-app/template/eslint.config.mjs

@@ -0,0 +1,27 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    rules: {
+      'eol-last': 2,
+      'quotes': ['error', 'single'],
+      'comma-dangle': ['error', {
+        'objects': 'always',
+        'arrays': 'never',
+        'imports': 'never',
+        'exports': 'never',
+        'functions': 'never',
+      }],
+      'semi': 'error',
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+    files: ['src/**/*.{js,mjs,ts,tsx,jsx}'],
+  },
+  {
+    ignores: ['dist/'],
+  }
+);

package/create-xpine-app/template/gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env*
+*.tsbuildinfo
+.DS_Store

package/create-xpine-app/template/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "xpine-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "PORT=3000 LOCALHOST=1 xpine-dev",
+    "build": "xpine-build --removePreviousBuild",
+    "start": "PORT=3000 node ./dist/server/run/prod.js",
+    "lint": "npx eslint",
+    "fix": "npx eslint --fix"
+  },
+  "dependencies": {
+    "alpinejs": "^3.14.8",
+    "cookie-parser": "^1.4.7",
+    "express": "^4.21.2",
+    "morgan": "^1.10.0",
+    "tailwindcss": "^4.1.12",
+    "xpine": "^0.0.59"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/alpinejs": "^3.13.11",
+    "@types/cookie-parser": "^1.4.8",
+    "@types/express": "^5.0.0",
+    "@types/morgan": "^1.9.9",
+    "@types/node": "^22.13.5",
+    "eslint": "^9.24.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.29.0"
+  }
+}

package/create-xpine-app/template/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxFragmentFactory": "html.fragment",
+    "jsxFactory": "html.createElement",
+    "jsxImportSource": "xpine",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "target": "esnext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": false,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": false,
+    "incremental": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "eslint.config.mjs"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.js"
+  ]
+}

package/create-xpine-app/template/xpine.config.mjs

@@ -0,0 +1 @@
+export default {};

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './src/util/env';
 export * from './src/util/get-config';
 export * from './src/scripts/build';
 export * from './src/auth';
+export * from './src/csrf';
 export * from './src/util/html';
 export * from './src/context';
 export * from './src/util/web';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}