@classytic/arc 2.3.0 → 2.4.2

package/dist/cli/commands/init.mjs

@@ -1,9 +1,8 @@
-import { accessSync } from "node:fs";
 import * as path from "node:path";
+import { accessSync } from "node:fs";
+import { execSync, spawn } from "node:child_process";
 import * as fs from "node:fs/promises";
 import * as readline from "node:readline";
-import { execSync, spawn } from "node:child_process";
-
 //#region src/cli/commands/init.ts
 /**
 * Arc CLI - Init Command
@@ -166,6 +165,20 @@ async function gatherConfig(options) {
 		if (options.typescript === void 0 && !nonInteractive) typescript = await question("Language [1=TypeScript (recommended), 2=JavaScript]: ") !== "2";
 		let edge = options.edge ?? false;
 		if (options.edge === void 0 && !nonInteractive) edge = await question("Deployment target [1=Node.js Server (default), 2=Edge/Serverless]: ") === "2";
+		if (edge && adapter === "mongokit" && !nonInteractive) {
+			console.log("");
+			console.log("  ⚠ Edge + MongoKit: Mongoose does NOT work on Cloudflare Workers.");
+			console.log("    MongoDB Atlas works with the raw driver (mongodb 6.15+ with nodejs_compat_v2),");
+			console.log("    but MongoKit depends on Mongoose. Options:");
+			console.log("    1. Use AWS Lambda / Vercel Serverless (Node.js) — Mongoose works normally");
+			console.log("    2. Use Cloudflare Hyperdrive + PostgreSQL (switch to Prisma/Drizzle adapter)");
+			console.log("    3. Continue with MongoKit — works on Lambda/Vercel, NOT on Cloudflare Workers");
+			console.log("");
+			if ((await question("Continue with MongoKit? [y/N]: ")).toLowerCase() !== "y") {
+				adapter = "custom";
+				console.log("  Switched to custom adapter. You can wire Drizzle, Prisma, or the raw MongoDB driver.");
+			}
+		}
 		return {
 			name,
 			adapter,
@@ -234,12 +247,18 @@ async function createProjectStructure(projectPath, config) {
 	files[`src/resources/example/example.schemas.${ext}`] = exampleSchemasTemplate(config);
 	files[`tests/example.test.${ext}`] = exampleTestTemplate(config);
 	if (config.auth === "jwt") files[`tests/auth.test.${ext}`] = authTestTemplate(config);
-	files[".arcrc"] = JSON.stringify({
+	if (!config.edge) {
+		files.Dockerfile = dockerfileTemplate(config);
+		files[".dockerignore"] = dockerignoreTemplate();
+		files["docker-compose.yml"] = dockerComposeTemplate(config);
+	}
+	if (config.edge) files["wrangler.toml"] = wranglerTemplate(config);
+	files[".arcrc"] = `${JSON.stringify({
 		adapter: config.adapter,
 		auth: config.auth,
 		tenant: config.tenant,
 		typescript: config.typescript
-	}, null, 2) + "\n";
+	}, null, 2)}\n`;
 	for (const [filePath, content] of Object.entries(files)) {
 		const fullPath = path.join(projectPath, filePath);
 		await fs.mkdir(path.dirname(fullPath), { recursive: true });
@@ -248,12 +267,27 @@ async function createProjectStructure(projectPath, config) {
 	}
 }
 function packageJsonTemplate(config) {
-	const scripts = config.typescript ? {
+	const scripts = config.typescript ? config.edge ? {
+		dev: "tsx watch src/index.ts",
+		build: "tsc",
+		start: "node dist/index.js",
+		deploy: "wrangler deploy",
+		"deploy:dev": "wrangler dev",
+		test: "vitest run",
+		"test:watch": "vitest"
+	} : {
 		dev: "tsx watch src/index.ts",
 		build: "tsc",
 		start: "node dist/index.js",
 		test: "vitest run",
 		"test:watch": "vitest"
+	} : config.edge ? {
+		dev: "node --watch src/index.js",
+		start: "node src/index.js",
+		deploy: "wrangler deploy",
+		"deploy:dev": "wrangler dev",
+		test: "vitest run",
+		"test:watch": "vitest"
 	} : {
 		dev: "node --watch src/index.js",
 		start: "node src/index.js",
@@ -335,10 +369,11 @@ node_modules/
 dist/
 *.js.map
 
-# Environment
-.env
+# Environment (local overrides — never commit secrets)
 .env.local
 .env.*.local
+# Uncomment if your .env contains secrets:
+# .env
 
 # IDE
 .vscode/
@@ -359,7 +394,15 @@ coverage/
 `;
 }
 function envExampleTemplate(config) {
-	let content = `# Server
+	let content = `# Environment Files (Next.js-style priority):
+#   .env.local         → machine-specific overrides (gitignored)
+#   .env.production    → production defaults
+#   .env.development   → development defaults (or .env.dev)
+#   .env               → shared defaults (fallback)
+#
+# Tip: Copy this file to .env.local for local development
+
+# Server
 PORT=8040
 HOST=0.0.0.0
 NODE_ENV=development
@@ -443,7 +486,7 @@ tests/
 
 ### Entry Points
 
-- **\`src/index.${ext}\`** - HTTP server entry point
+- **\`src/index.${ext}\`** - ${config.edge ? "Edge/serverless fetch handler (Cloudflare Workers, Lambda, Vercel)" : "HTTP server entry point"}
 - **\`src/app.${ext}\`** - App factory (import for workers/tests)
 
 \`\`\`${config.typescript ? "typescript" : "javascript"}
@@ -501,12 +544,14 @@ arc introspect
 arc docs
 \`\`\`
 
-## Environment Files
+## Environment Files (Next.js-style)
+
+Priority (first loaded wins):
+1. \`.env.local\` — Machine-specific overrides (gitignored)
+2. \`.env.{environment}\` — e.g., \`.env.production\`, \`.env.development\`, \`.env.test\`
+3. \`.env\` — Shared defaults (fallback)
 
-- \`.env.development\` / \`.env.dev\` - Development (default)
-- \`.env.test\` / \`.env.qa\` - Testing / QA
-- \`.env.production\` / \`.env.prod\` - Production
-- \`.env\` - Fallback
+Short forms also supported: \`.env.prod\`, \`.env.dev\`, \`.env.test\`
 
 ## API Documentation
 
@@ -526,10 +571,29 @@ API documentation is available via Scalar UI:
 | POST | /examples | Create |
 | PATCH | /examples/:id | Update |
 | DELETE | /examples/:id | Delete |
+
+## Docker Deployment
+
+This project comes ready for containerization:
+
+\`\`\`bash
+# Build the production image
+docker build -t ${config.name} .
+
+# Run the container
+docker run -p 8040:8040 --env-file .env ${config.name}
+\`\`\`
+
+If you're using a database (like MongoDB), you can use Docker Compose to spin up the full stack locally:
+
+\`\`\`bash
+docker-compose up -d
+\`\`\`
 `;
 }
 function indexTemplate(config) {
 	const ts = config.typescript;
+	if (config.edge) return edgeIndexTemplate(config);
 	return `/**
  * ${config.name} - Server Entry Point
  * Generated by Arc CLI
@@ -566,6 +630,48 @@ main().catch((err) => {
 });
 `;
 }
+/**
+* Edge/serverless entry point — exports a Web Standards fetch handler.
+* Works on Cloudflare Workers, AWS Lambda, Vercel Serverless, etc.
+*/
+function edgeIndexTemplate(config) {
+	const ts = config.typescript;
+	const dbNote = config.adapter === "mongokit" ? ` *\n * NOTE: Mongoose does NOT work on Cloudflare Workers. This entry point\n * works on AWS Lambda and Vercel Serverless (Node.js runtime) where\n * Mongoose/MongoKit works normally. For Cloudflare Workers, switch to\n * Drizzle + Hyperdrive (PostgreSQL) or the raw mongodb driver.` : "";
+	return `/**
+ * ${config.name} - Edge/Serverless Entry Point
+ * Generated by Arc CLI
+ *
+ * Exports a Web Standards fetch handler that works on:
+ * - Cloudflare Workers (enable nodejs_compat in wrangler.toml)
+ * - AWS Lambda (via fetch-based adapter)
+ * - Vercel Serverless Functions
+ * - Any runtime supporting the Web Standards Request/Response API
+ *
+ * No app.listen() — routes through Fastify's .inject() internally.
+${dbNote}
+ */
+
+import { toFetchHandler } from '@classytic/arc/factory';
+import { createAppInstance } from './app.js';
+
+const app = await createAppInstance();
+const handler = toFetchHandler(app);
+
+/**
+ * Cloudflare Workers / generic fetch handler
+ */
+export default {
+  async fetch(request${ts ? ": Request" : ""})${ts ? ": Promise<Response>" : ""} {
+    return handler(request);
+  },
+};
+
+/**
+ * Named export for platforms that expect it (Vercel, AWS Lambda adapters)
+ */
+export { handler };
+`;
+}
 function appTemplate(config) {
 	const ts = config.typescript;
 	const typeImport = ts ? "import type { FastifyInstance } from 'fastify';\n" : "";
@@ -582,9 +688,9 @@ import { getAuth } from './auth.js';
  *
  * Creates and configures the Fastify app instance.
  * Can be imported by:
- * - index.ts (HTTP server)
+ * - index.ts (HTTP server via app.listen, or edge handler via toFetchHandler)
  * - worker.ts (background workers)
- * - tests (integration tests)
+ * - tests (integration tests via app.inject)
  */
 
 ${typeImport}import config from '#config/index.js';
@@ -613,6 +719,9 @@ export async function createAppInstance()${ts ? ": Promise<FastifyInstance>" : "
       credentials: config.cors.credentials,
     },
     trustProxy: true,
+    arcPlugins: {
+      metrics: config.env === 'production',  // Prometheus /_metrics endpoint
+    },
   });
 
   // Register app-specific plugins (explicit dependency injection)
@@ -633,44 +742,64 @@ function envLoaderTemplate(config) {
  * Environment Loader
  *
  * MUST be imported FIRST before any other imports.
- * Loads .env files based on NODE_ENV.
+ * Loads .env files based on NODE_ENV with Next.js-style priority:
+ *
+ *   .env.local        (always loaded first — gitignored, machine-specific overrides)
+ *   .env.{environment} (e.g., .env.production, .env.dev, .env.test)
+ *   .env              (fallback defaults)
+ *
+ * Supports both long-form (production, development, test) and
+ * short-form (prod, dev, test) env file names.
  *
  * Usage:
- *   import './config/env.js';  // First line of entry point
+ *   import '#config/env.js';  // First line of entry point
  */
 
 import dotenv from 'dotenv';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-/**
- * Normalize environment string to short form
- */
-function normalizeEnv(env${ts ? ": string | undefined" : ""})${ts ? ": string" : ""} {
-  const normalized = (env || '').toLowerCase();
-  if (normalized === 'production' || normalized === 'prod') return 'prod';
-  if (normalized === 'test' || normalized === 'qa') return 'test';
+${ts ? "type EnvName = 'prod' | 'dev' | 'test';\n" : ""}const ENV_ALIASES${ts ? ": Record<EnvName, string>" : ""} = {
+  prod: 'production',
+  dev: 'development',
+  test: 'test',
+};
+
+function normalizeEnv(env${ts ? ": string | undefined" : ""})${ts ? ": EnvName" : ""} {
+  const raw = (env || '').toLowerCase();
+  if (raw === 'production' || raw === 'prod') return 'prod';
+  if (raw === 'test' || raw === 'qa') return 'test';
   return 'dev';
 }
 
-// Determine environment
 const env = normalizeEnv(process.env.NODE_ENV);
+const longForm = ENV_ALIASES[env];
+
+// Priority: .env.local → .env.{long} → .env.{short} → .env
+// Same convention as Next.js — .env.local always wins, never committed to git
+const candidates = [
+  '.env.local',
+  \`.env.\${longForm}\`,
+  \`.env.\${env}\`,
+  '.env',
+].map((f) => resolve(process.cwd(), f));
+
+const loaded${ts ? ": string[]" : ""} = [];
+for (const file of candidates) {
+  if (existsSync(file)) {
+    // override: false means earlier files take priority (first loaded wins)
+    dotenv.config({ path: file, override: false });
+    loaded.push(file.split(/[\\\\/]/).pop()${ts ? "!" : ""});
+  }
+}
 
-// Load environment-specific .env file
-const envFile = resolve(process.cwd(), \`.env.\${env}\`);
-const defaultEnvFile = resolve(process.cwd(), '.env');
-
-if (existsSync(envFile)) {
-  dotenv.config({ path: envFile });
-  console.log(\`Loaded: .env.\${env}\`);
-} else if (existsSync(defaultEnvFile)) {
-  dotenv.config({ path: defaultEnvFile });
-  console.log('Loaded: .env');
-} else {
-  console.warn('Warning: No .env file found');
+// Only log in development (silent in production/test)
+if (env === 'dev' && loaded.length > 0) {
+  console.log(\`env: \${loaded.join(' + ')}\`);
+} else if (loaded.length === 0) {
+  console.warn('No .env file found — using process environment only');
 }
 
-// Export for reference
 export const ENV = env;
 `;
 }
@@ -1461,14 +1590,16 @@ import {
   Repository,
   softDeletePlugin,
   methodRegistryPlugin,
+  mongoOperationsPlugin,
 } from '@classytic/mongokit';
 ${ts ? "import type { ExampleDocument } from './example.model.js';\n" : ""}import Example from './example.model.js';
 
 class ExampleRepository extends Repository${ts ? "<ExampleDocument>" : ""} {
   constructor() {
     super(Example, [
-      methodRegistryPlugin(),  // Required for plugin method registration
-      softDeletePlugin(),      // Soft delete support
+      methodRegistryPlugin(),
+      softDeletePlugin(),
+      mongoOperationsPlugin(),
     ]);
   }
 
@@ -1513,12 +1644,17 @@ function exampleResourceTemplate(config) {
  */
 
 import { defineResource } from '@classytic/arc';
+import { QueryParser } from '@classytic/mongokit';
 import { createAdapter } from '#shared/adapter.js';
 import { ${config.tenant === "multi" ? "orgStaffPermissions" : "publicReadPermissions"} } from '#shared/permissions.js';
 ${config.tenant === "multi" ? "import { flexibleMultiTenantPreset } from '#shared/presets/flexible-multi-tenant.js';\n" : ""}import Example${ts ? ", { type ExampleDocument }" : ""} from './example.model.js';
 import exampleRepository from './example.repository.js';
 import exampleController from './example.controller.js';
 
+const queryParser = new QueryParser({
+  allowedFilterFields: ['isActive'],
+});
+
 const exampleResource = defineResource${ts ? "<ExampleDocument>" : ""}({
   name: 'example',
   displayName: 'Examples',
@@ -1526,9 +1662,11 @@ const exampleResource = defineResource${ts ? "<ExampleDocument>" : ""}({
 
   adapter: createAdapter(Example, exampleRepository),
   controller: exampleController,
+  queryParser,
 
   presets: [
-    'softDelete',${config.tenant === "multi" ? `
+    'softDelete',
+    'bulk',${config.tenant === "multi" ? `
     flexibleMultiTenantPreset({ tenantField: 'organizationId' }),` : ""}
   ],
 
@@ -1549,6 +1687,7 @@ export default exampleResource;
 `;
 }
 function exampleControllerTemplate(config) {
+	config.typescript;
 	return `/**
  * Example Controller
  * Generated by Arc CLI
@@ -1565,7 +1704,7 @@ import { exampleSchemaOptions } from './example.schemas.js';
 
 class ExampleController extends BaseController {
   constructor() {
-    super(exampleRepository${config.typescript ? " as any" : ""}, {
+    super(exampleRepository, {
       schemaOptions: exampleSchemaOptions,${config.tenant === "multi" ? `
       tenantField: 'organizationId', // Configurable tenant field for multi-tenant` : `
       // tenantField: 'organizationId', // For multi-tenant apps`}
@@ -2617,6 +2756,137 @@ Documentation:
   https://github.com/classytic/arc
 `);
 }
+function dockerignoreTemplate() {
+	return `node_modules
+dist
+.env
+.env.*
+.git
+.vscode
+.idea
+Dockerfile
+docker-compose.yml
+coverage
+npm-debug.log*
+.DS_Store
+`;
+}
+function dockerfileTemplate(config) {
+	return `# Multi-stage Dockerfile for Arc + Fastify
+# Optimized for production and caching
+
+# 1. Build Stage
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+${config.typescript ? "COPY tsconfig*.json ./" : ""}
+# If using pnpm, bun, or yarn, adjust the lockfile here
+RUN npm ci
+
+COPY . .
+${config.typescript ? "RUN npm run build" : ""}
+
+# 2. Production Stage
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+${config.typescript ? "COPY --from=builder /app/dist ./dist" : "COPY src ./src"}
 
+EXPOSE 8040
+CMD ["npm", "start"]
+`;
+}
+function dockerComposeTemplate(config) {
+	let content = `version: '3.8'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8040:8040"
+    environment:
+      - NODE_ENV=development
+      - PORT=8040
+      - HOST=0.0.0.0`;
+	if (config.adapter === "mongokit") content += `
+      - MONGODB_URI=mongodb://mongo:27017/${config.name}
+    depends_on:
+      - mongo
+
+  mongo:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo-data:/data/db`;
+	content += `
+
+volumes:`;
+	if (config.adapter === "mongokit") content += `
+  mongo-data:
+`;
+	return content;
+}
+function wranglerTemplate(config) {
+	const entry = config.typescript ? "dist/index.js" : "src/index.js";
+	const compatFlag = config.adapter === "mongokit" ? "nodejs_compat_v2" : "nodejs_compat";
+	let dbConfig = "";
+	if (config.adapter === "mongokit") dbConfig = `
+# MongoDB Atlas — store URI as a secret:
+#   npx wrangler secret put MONGODB_URI
+#
+# IMPORTANT: Mongoose does NOT work on Workers. Use the raw mongodb driver (6.15+).
+# For Lambda/Vercel (Node.js), Mongoose works normally.
+`;
+	else dbConfig = `
+# Database options for Cloudflare Workers:
+#
+# PostgreSQL via Hyperdrive (recommended — connection pooling + caching):
+#   npx wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db"
+#   Then uncomment:
+# [[hyperdrive]]
+# binding = "HYPERDRIVE"
+# id = "<your-hyperdrive-id>"
+#
+# Turso (edge SQLite):
+#   npx wrangler secret put TURSO_URL
+#   npx wrangler secret put TURSO_AUTH_TOKEN
+#
+# Neon (serverless PostgreSQL via HTTP):
+#   npx wrangler secret put DATABASE_URL
+#
+# D1 (Cloudflare's native SQLite):
+# [[d1_databases]]
+# binding = "DB"
+# database_name = "${config.name}-db"
+# database_id = "<run: npx wrangler d1 create ${config.name}-db>"
+`;
+	return `# Cloudflare Workers configuration
+# Generated by Arc CLI — see https://developers.cloudflare.com/workers/
+
+name = "${config.name}"
+main = "${entry}"
+compatibility_date = "2025-03-20"
+
+# Required for Arc — enables node:crypto and AsyncLocalStorage
+compatibility_flags = ["${compatFlag}"]
+
+[vars]
+NODE_ENV = "production"
+
+# Secrets (never commit these — use wrangler secret put):
+#   npx wrangler secret put JWT_SECRET
+${dbConfig}
+# Custom domain:
+# [routes]
+# { pattern = "api.example.com/*", zone_name = "example.com" }
+`;
+}
 //#endregion
-export { init as default, init };
+export { init as default, init };

package/dist/cli/commands/introspect.mjs

@@ -1,7 +1,6 @@
-import { t as ResourceRegistry } from "../../ResourceRegistry-7Ic20ZMw.mjs";
+import { t as ResourceRegistry } from "../../ResourceRegistry-DeCIFlix.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-
 //#region src/cli/commands/introspect.ts
 /**
 * Arc CLI - Introspect Command
@@ -70,6 +69,5 @@ async function introspect(args) {
 		throw new Error(String(error));
 	}
 }
-
 //#endregion
-export { introspect as default, introspect };
+export { introspect as default, introspect };

package/dist/cli/index.d.mts

@@ -1,16 +1,7 @@
 import describe from "./commands/describe.mjs";
 import { exportDocs } from "./commands/docs.mjs";
+import { doctor } from "./commands/doctor.mjs";
 import generate from "./commands/generate.mjs";
 import init from "./commands/init.mjs";
 import introspect from "./commands/introspect.mjs";
-
-//#region src/cli/commands/doctor.d.ts
-/**
- * Arc CLI - Doctor Command
- *
- * Health check utility that validates the development environment.
- * Checks Node.js version, dependencies, configuration, and env variables.
- */
-declare function doctor(_args?: string[]): Promise<void>;
-//#endregion
 export { describe, doctor, exportDocs, generate, init, introspect };