create-filament 1.0.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-filament",
+  "version": "1.0.0",
+  "description": "Scaffold a new Filament application",
+  "type": "module",
+  "bin": {
+    "create-filament": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "filament",
+    "scaffold",
+    "typescript",
+    "api",
+    "framework"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.0.0",
+    "test-battery": "^3.2.1"
+  }
+}

package/templates/api/src/config/app.ts

@@ -0,0 +1,17 @@
+/**
+ * Application configuration
+ */
+
+export const config = {
+  port: parseInt(process.env.PORT || '3000', 10),
+  nodeEnv: process.env.NODE_ENV || 'development',
+  logLevel: process.env.LOG_LEVEL || 'info',
+};
+
+/**
+ * Validate required environment variables
+ */
+export function validateConfig() {
+  // Add validation for required env vars here
+  return true;
+}

package/templates/api/src/handlers/errors.ts

@@ -0,0 +1,32 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+});
+
+/**
+ * Register error handlers
+ */
+export function registerErrorHandlers(app: Application<AppMeta>) {
+  app.onError(async (err, req, res) => {
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'error') {
+      logger.error({
+        error: err.message,
+        stack: err.stack,
+        method: req.method,
+        path: req.path,
+      });
+    }
+
+    if (!res.headersSent) {
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: process.env.NODE_ENV === 'development' ? err.message : undefined,
+      });
+    }
+  });
+}

package/templates/api/src/handlers/finalizers.ts

@@ -0,0 +1,27 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+});
+
+/**
+ * Register finalizers (always run)
+ */
+export function registerFinalizers(app: Application<AppMeta>) {
+  app.onFinalize(async (req, res) => {
+    const duration = Date.now() - (req._startTime || Date.now());
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'info') {
+      logger.info({
+        method: req.method,
+        path: req.path,
+        status: res.statusCode,
+        duration,
+        event: 'request.complete',
+      });
+    }
+  });
+}

package/templates/api/src/handlers/transforms.ts

@@ -0,0 +1,18 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+
+/**
+ * Register response transformers
+ */
+export function registerTransformers(app: Application<AppMeta>) {
+  // Add custom headers based on tags
+  app.onTransform(async (req, res) => {
+    const tags = req.endpointMeta.tags;
+
+    if (tags.includes('api')) {
+      res.setHeader('X-API-Version', '1.0');
+    }
+
+    // Add more transformations here
+  });
+}

package/templates/api/src/index.ts

@@ -0,0 +1,45 @@
+import { createApp } from 'filamentjs';
+import { defaultMeta } from './meta/defaults.js';
+import { config, validateConfig } from './config/app.js';
+import { registerMiddleware } from './middleware/index.js';
+import { registerRoutes } from './routes/index.js';
+import { registerErrorHandlers } from './handlers/errors.js';
+import { registerTransformers } from './handlers/transforms.js';
+import { registerFinalizers } from './handlers/finalizers.js';
+
+// Validate configuration
+validateConfig();
+
+// Create Filament application
+const app = createApp(defaultMeta);
+
+// Register middleware
+registerMiddleware(app);
+
+// Register routes
+registerRoutes(app);
+
+// Register post-request handlers
+registerErrorHandlers(app);
+registerTransformers(app);
+registerFinalizers(app);
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM received, shutting down gracefully...');
+  await app.close();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  console.log('SIGINT received, shutting down gracefully...');
+  await app.close();
+  process.exit(0);
+});
+
+// Start server
+app.listen(config.port, () => {
+  console.log(`🔥 Filament server running on http://localhost:${config.port}`);
+  console.log(`   Environment: ${config.nodeEnv}`);
+  console.log(`   Log level: ${config.logLevel}`);
+});

package/templates/api/src/meta/defaults.ts

@@ -0,0 +1,28 @@
+import { AppMeta } from './index.js';
+
+/**
+ * Default metadata for all endpoints
+ * 
+ * Individual endpoints can override these values with Partial<AppMeta>
+ */
+export const defaultMeta: AppMeta = {
+  requiresAuth: false,
+  rateLimit: 100,
+  logging: {
+    level: 'info',
+  },
+  tags: [],
+};
+
+/**
+ * Common metadata presets for convenience
+ */
+export const PUBLIC: Partial<AppMeta> = {
+  requiresAuth: false,
+  rateLimit: 100,
+};
+
+export const AUTHENTICATED: Partial<AppMeta> = {
+  requiresAuth: true,
+  rateLimit: 50,
+};

package/templates/api/src/meta/index.ts

@@ -0,0 +1,50 @@
+import { FrameworkMeta } from 'filamentjs';
+
+/**
+ * Application metadata interface
+ * 
+ * Extend this interface to add your own metadata properties.
+ * Middleware can inspect req.endpointMeta to make decisions.
+ */
+export interface AppMeta extends FrameworkMeta {
+  /**
+   * Whether this endpoint requires authentication
+   */
+  requiresAuth: boolean;
+
+  /**
+   * Required role for this endpoint
+   */
+  role?: 'admin' | 'user';
+
+  /**
+   * Whether this endpoint requires a session
+   */
+  requiresSession: boolean;
+
+  /**
+   * Rate limit for this endpoint (requests per minute)
+   */
+  rateLimit: number;
+
+  /**
+   * Logging configuration
+   */
+  logging: {
+    level: 'debug' | 'info' | 'warn' | 'error';
+  };
+
+  /**
+   * Tags for categorizing endpoints
+   */
+  tags: string[];
+
+  /**
+   * OpenAPI documentation
+   */
+  openapi?: {
+    summary: string;
+    description?: string;
+    tags?: string[];
+  };
+}

package/templates/api/src/middleware/index.ts

@@ -0,0 +1,36 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+    },
+  },
+});
+
+/**
+ * Register all middleware
+ */
+export function registerMiddleware(app: Application<AppMeta>) {
+  // Request logging middleware
+  app.use(async (req, res, next) => {
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'info') {
+      logger.info({
+        method: req.method,
+        path: req.path,
+        event: 'request.start',
+      });
+    }
+
+    await next();
+  });
+
+  // Add more middleware here
+  // Example: Authentication, rate limiting, etc.
+}

package/templates/api/src/routes/index.ts

@@ -0,0 +1,26 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import { PUBLIC } from '../meta/defaults.js';
+
+/**
+ * Register all routes
+ */
+export function registerRoutes(app: Application<AppMeta>) {
+  // Health check endpoint
+  app.get('/health', PUBLIC, async (req, res) => {
+    res.json({
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  // Example endpoint
+  app.get('/', PUBLIC, async (req, res) => {
+    res.json({
+      message: 'Welcome to your Filament API',
+      endpoints: {
+        health: 'GET /health',
+      },
+    });
+  });
+}

package/templates/api/tests/integration/example.test.ts

@@ -0,0 +1,20 @@
+import { suite, it, before, after } from 'node:test';
+import { TestBattery } from 'test-battery';
+
+suite('Example Test', () => {
+  before(() => {
+    // Setup code here
+  });
+
+  after(() => {
+    // Cleanup code here
+  });
+
+  TestBattery.test('should pass', (battery) => {
+    battery.test('1 + 1 = 2').value(1 + 1).value(2).equal;
+  });
+
+  TestBattery.test('should work with async', async (battery) => {
+    battery.test('result = 42').value(Promise.resolve(42)).value(42).equal;
+  });
+});

package/templates/full/src/config/app.ts

@@ -0,0 +1,17 @@
+/**
+ * Application configuration
+ */
+
+export const config = {
+  port: parseInt(process.env.PORT || '3000', 10),
+  nodeEnv: process.env.NODE_ENV || 'development',
+  logLevel: process.env.LOG_LEVEL || 'info',
+};
+
+/**
+ * Validate required environment variables
+ */
+export function validateConfig() {
+  // Add validation for required env vars here
+  return true;
+}

package/templates/full/src/handlers/errors.ts

@@ -0,0 +1,32 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+});
+
+/**
+ * Register error handlers
+ */
+export function registerErrorHandlers(app: Application<AppMeta>) {
+  app.onError(async (err, req, res) => {
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'error') {
+      logger.error({
+        error: err.message,
+        stack: err.stack,
+        method: req.method,
+        path: req.path,
+      });
+    }
+
+    if (!res.headersSent) {
+      res.status(500).json({
+        error: 'Internal Server Error',
+        message: process.env.NODE_ENV === 'development' ? err.message : undefined,
+      });
+    }
+  });
+}

package/templates/full/src/handlers/finalizers.ts

@@ -0,0 +1,27 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+});
+
+/**
+ * Register finalizers (always run)
+ */
+export function registerFinalizers(app: Application<AppMeta>) {
+  app.onFinalize(async (req, res) => {
+    const duration = Date.now() - (req._startTime || Date.now());
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'info') {
+      logger.info({
+        method: req.method,
+        path: req.path,
+        status: res.statusCode,
+        duration,
+        event: 'request.complete',
+      });
+    }
+  });
+}

package/templates/full/src/handlers/transforms.ts

@@ -0,0 +1,18 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+
+/**
+ * Register response transformers
+ */
+export function registerTransformers(app: Application<AppMeta>) {
+  // Add custom headers based on tags
+  app.onTransform(async (req, res) => {
+    const tags = req.endpointMeta.tags;
+
+    if (tags.includes('api')) {
+      res.setHeader('X-API-Version', '1.0');
+    }
+
+    // Add more transformations here
+  });
+}

package/templates/full/src/index.ts

@@ -0,0 +1,45 @@
+import { createApp } from 'filamentjs';
+import { defaultMeta } from './meta/defaults.js';
+import { config, validateConfig } from './config/app.js';
+import { registerMiddleware } from './middleware/index.js';
+import { registerRoutes } from './routes/index.js';
+import { registerErrorHandlers } from './handlers/errors.js';
+import { registerTransformers } from './handlers/transforms.js';
+import { registerFinalizers } from './handlers/finalizers.js';
+
+// Validate configuration
+validateConfig();
+
+// Create Filament application
+const app = createApp(defaultMeta);
+
+// Register middleware
+registerMiddleware(app);
+
+// Register routes
+registerRoutes(app);
+
+// Register post-request handlers
+registerErrorHandlers(app);
+registerTransformers(app);
+registerFinalizers(app);
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  console.log('SIGTERM received, shutting down gracefully...');
+  await app.close();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  console.log('SIGINT received, shutting down gracefully...');
+  await app.close();
+  process.exit(0);
+});
+
+// Start server
+app.listen(config.port, () => {
+  console.log(`🔥 Filament server running on http://localhost:${config.port}`);
+  console.log(`   Environment: ${config.nodeEnv}`);
+  console.log(`   Log level: ${config.logLevel}`);
+});

package/templates/full/src/meta/defaults.ts

@@ -0,0 +1,28 @@
+import { AppMeta } from './index.js';
+
+/**
+ * Default metadata for all endpoints
+ * 
+ * Individual endpoints can override these values with Partial<AppMeta>
+ */
+export const defaultMeta: AppMeta = {
+  requiresAuth: false,
+  rateLimit: 100,
+  logging: {
+    level: 'info',
+  },
+  tags: [],
+};
+
+/**
+ * Common metadata presets for convenience
+ */
+export const PUBLIC: Partial<AppMeta> = {
+  requiresAuth: false,
+  rateLimit: 100,
+};
+
+export const AUTHENTICATED: Partial<AppMeta> = {
+  requiresAuth: true,
+  rateLimit: 50,
+};

package/templates/full/src/meta/index.ts

@@ -0,0 +1,31 @@
+import { FrameworkMeta } from 'filamentjs';
+
+/**
+ * Application metadata interface
+ * 
+ * Extend this interface to add your own metadata properties.
+ * Middleware can inspect req.endpointMeta to make decisions.
+ */
+export interface AppMeta extends FrameworkMeta {
+  /**
+   * Whether this endpoint requires authentication
+   */
+  requiresAuth: boolean;
+
+  /**
+   * Rate limit for this endpoint (requests per minute)
+   */
+  rateLimit: number;
+
+  /**
+   * Logging configuration
+   */
+  logging: {
+    level: 'debug' | 'info' | 'warn' | 'error';
+  };
+
+  /**
+   * Tags for categorizing endpoints
+   */
+  tags: string[];
+}

package/templates/full/src/middleware/index.ts

@@ -0,0 +1,36 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+    },
+  },
+});
+
+/**
+ * Register all middleware
+ */
+export function registerMiddleware(app: Application<AppMeta>) {
+  // Request logging middleware
+  app.use(async (req, res, next) => {
+    const level = req.endpointMeta.logging.level;
+
+    if (level === 'debug' || level === 'info') {
+      logger.info({
+        method: req.method,
+        path: req.path,
+        event: 'request.start',
+      });
+    }
+
+    await next();
+  });
+
+  // Add more middleware here
+  // Example: Authentication, rate limiting, etc.
+}

package/templates/full/src/routes/index.ts

@@ -0,0 +1,26 @@
+import { Application } from 'filamentjs';
+import { AppMeta } from '../meta/index.js';
+import { PUBLIC } from '../meta/defaults.js';
+
+/**
+ * Register all routes
+ */
+export function registerRoutes(app: Application<AppMeta>) {
+  // Health check endpoint
+  app.get('/health', PUBLIC, async (req, res) => {
+    res.json({
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  // Example endpoint
+  app.get('/', PUBLIC, async (req, res) => {
+    res.json({
+      message: 'Welcome to your Filament API',
+      endpoints: {
+        health: 'GET /health',
+      },
+    });
+  });
+}

package/templates/full/tests/integration/example.test.ts

@@ -0,0 +1,20 @@
+import { suite, it, before, after } from 'node:test';
+import { TestBattery } from 'test-battery';
+
+suite('Example Test', () => {
+  before(() => {
+    // Setup code here
+  });
+
+  after(() => {
+    // Cleanup code here
+  });
+
+  TestBattery.test('should pass', (battery) => {
+    battery.test('1 + 1 = 2').value(1 + 1).value(2).equal;
+  });
+
+  TestBattery.test('should work with async', async (battery) => {
+    battery.test('result = 42').value(Promise.resolve(42)).value(42).equal;
+  });
+});

package/templates/minimal/src/config/app.ts

@@ -0,0 +1,17 @@
+/**
+ * Application configuration
+ */
+
+export const config = {
+  port: parseInt(process.env.PORT || '3000', 10),
+  nodeEnv: process.env.NODE_ENV || 'development',
+  logLevel: process.env.LOG_LEVEL || 'info',
+};
+
+/**
+ * Validate required environment variables
+ */
+export function validateConfig() {
+  // Add validation for required env vars here
+  return true;
+}