@classytic/arc 1.1.0 → 2.1.3

package/dist/cli/commands/introspect.d.mts

@@ -0,0 +1,10 @@
+//#region src/cli/commands/introspect.d.ts
+/**
+ * Arc CLI - Introspect Command
+ *
+ * Shows all registered resources and their configuration.
+ * Requires an entry file that exports defineResource() results.
+ */
+declare function introspect(args: string[]): Promise<void>;
+//#endregion
+export { introspect as default, introspect };

package/dist/cli/commands/introspect.mjs

@@ -0,0 +1,75 @@
+import { t as ResourceRegistry } from "../../ResourceRegistry-7Ic20ZMw.mjs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+//#region src/cli/commands/introspect.ts
+/**
+* Arc CLI - Introspect Command
+*
+* Shows all registered resources and their configuration.
+* Requires an entry file that exports defineResource() results.
+*/
+function describePermission(value) {
+	if (!value) return "none";
+	if (typeof value === "function") return value.name ? `${value.name}()` : "[anonymous permission function]";
+	if (Array.isArray(value)) return `[${value.join(", ")}]`;
+	if (typeof value === "object") return "[permission object]";
+	return String(value);
+}
+async function introspect(args) {
+	console.log("Introspecting Arc resources...\n");
+	try {
+		const entryPath = args[0];
+		if (!entryPath) {
+			console.log("Usage: arc introspect <entry-file>\n");
+			console.log("Where entry-file exports your defineResource() results.");
+			console.log("Example: arc introspect ./src/resources.js");
+			return;
+		}
+		const entryModule = await import(pathToFileURL(resolve(process.cwd(), entryPath)).href);
+		const registry = new ResourceRegistry();
+		let registered = 0;
+		function tryRegister(value) {
+			if (value && typeof value === "object" && "name" in value && "_registryMeta" in value && "toPlugin" in value) {
+				registry.register(value, value._registryMeta ?? {});
+				registered++;
+			}
+		}
+		for (const exported of Object.values(entryModule)) if (Array.isArray(exported)) exported.forEach(tryRegister);
+		else tryRegister(exported);
+		if (registered === 0) {
+			console.log("No resource definitions found in entry file.");
+			console.log("\nMake sure your file exports defineResource() results:");
+			console.log("  export const productResource = defineResource({ ... });");
+			return;
+		}
+		const resources = registry.getAll();
+		console.log(`Found ${resources.length} resource(s):\n`);
+		resources.forEach((resource, index) => {
+			console.log(`${index + 1}. ${resource.name}`);
+			console.log(`   Display Name: ${resource.displayName}`);
+			console.log(`   Prefix: ${resource.prefix}`);
+			console.log(`   Module: ${resource.module || "none"}`);
+			if (resource.permissions) {
+				console.log(`   Permissions:`);
+				Object.entries(resource.permissions).forEach(([op, permission]) => {
+					console.log(`     ${op}: ${describePermission(permission)}`);
+				});
+			}
+			if (resource.presets && resource.presets.length > 0) console.log(`   Presets: ${resource.presets.join(", ")}`);
+			if (resource.additionalRoutes && resource.additionalRoutes.length > 0) console.log(`   Additional Routes: ${resource.additionalRoutes.length}`);
+			console.log("");
+		});
+		const stats = registry.getStats();
+		console.log("Summary:");
+		console.log(`  Total Resources: ${stats.totalResources}`);
+		console.log(`  With Presets: ${resources.filter((r) => r.presets?.length > 0).length}`);
+		console.log(`  With Custom Routes: ${resources.filter((r) => r.additionalRoutes && r.additionalRoutes.length > 0).length}`);
+	} catch (error) {
+		if (error instanceof Error) throw error;
+		throw new Error(String(error));
+	}
+}
+
+//#endregion
+export { introspect as default, introspect };

package/dist/cli/index.d.mts

@@ -0,0 +1,16 @@
+import describe from "./commands/describe.mjs";
+import { exportDocs } from "./commands/docs.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 };

package/dist/cli/index.mjs

@@ -0,0 +1,156 @@
+import generate from "./commands/generate.mjs";
+import init from "./commands/init.mjs";
+import introspect from "./commands/introspect.mjs";
+import describe from "./commands/describe.mjs";
+import { exportDocs } from "./commands/docs.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+//#region src/cli/commands/doctor.ts
+/**
+* Arc CLI - Doctor Command
+*
+* Health check utility that validates the development environment.
+* Checks Node.js version, dependencies, configuration, and env variables.
+*/
+async function doctor(_args = []) {
+	console.log("\nArc Doctor\n");
+	const results = [];
+	const cwd = process.cwd();
+	const nodeVersion = process.versions.node;
+	if (parseInt(nodeVersion.split(".")[0] ?? "0", 10) >= 22) results.push({
+		status: "pass",
+		label: `Node.js ${nodeVersion}`,
+		detail: "required: >=22"
+	});
+	else results.push({
+		status: "fail",
+		label: `Node.js ${nodeVersion}`,
+		detail: "required: >=22"
+	});
+	const pkg = findPackageJson(cwd);
+	const allDeps = {
+		...pkg?.dependencies ?? {},
+		...pkg?.devDependencies ?? {}
+	};
+	const arcVersion = allDeps["@classytic/arc"];
+	if (arcVersion) results.push({
+		status: "pass",
+		label: `@classytic/arc ${arcVersion}`
+	});
+	else results.push({
+		status: "warn",
+		label: "@classytic/arc not found in dependencies"
+	});
+	const fastifyVersion = allDeps["fastify"];
+	if (fastifyVersion) {
+		const clean = fastifyVersion.replace(/^[\^~>=<]+/, "");
+		if (parseInt(clean.split(".")[0] ?? "0", 10) >= 5) results.push({
+			status: "pass",
+			label: `fastify ${fastifyVersion}`,
+			detail: "required: ^5.0.0"
+		});
+		else results.push({
+			status: "fail",
+			label: `fastify ${fastifyVersion}`,
+			detail: "required: ^5.0.0 — Arc requires Fastify 5"
+		});
+	} else results.push({
+		status: "fail",
+		label: "fastify not found in dependencies",
+		detail: "required: ^5.0.0"
+	});
+	const tsconfigPath = resolve(cwd, "tsconfig.json");
+	if (existsSync(tsconfigPath)) try {
+		const stripped = readFileSync(tsconfigPath, "utf-8").replace(/\/\/.*$/gm, "");
+		const moduleRes = JSON.parse(stripped)?.compilerOptions?.moduleResolution;
+		if (moduleRes && ![
+			"nodenext",
+			"node16",
+			"bundler"
+		].includes(moduleRes.toLowerCase())) results.push({
+			status: "warn",
+			label: "tsconfig.json found",
+			detail: `moduleResolution "${moduleRes}" — recommend "NodeNext" or "Bundler"`
+		});
+		else results.push({
+			status: "pass",
+			label: "tsconfig.json found"
+		});
+	} catch {
+		results.push({
+			status: "pass",
+			label: "tsconfig.json found"
+		});
+	}
+	else results.push({
+		status: "warn",
+		label: "tsconfig.json not found"
+	});
+	for (const dep of [
+		{
+			name: "@fastify/rate-limit",
+			purpose: "rate limiting"
+		},
+		{
+			name: "@fastify/helmet",
+			purpose: "security headers"
+		},
+		{
+			name: "@fastify/cors",
+			purpose: "CORS support"
+		}
+	]) if (allDeps[dep.name]) results.push({
+		status: "pass",
+		label: `${dep.name} installed`
+	});
+	else results.push({
+		status: "warn",
+		label: `${dep.name} not installed`,
+		detail: `${dep.purpose} disabled`
+	});
+	if (allDeps["better-auth"]) results.push({
+		status: "pass",
+		label: `better-auth ${allDeps["better-auth"]}`
+	});
+	for (const env of [{
+		name: "MONGO_URI",
+		severity: "warn",
+		detail: "required at runtime for MongoDB"
+	}, {
+		name: "BETTER_AUTH_SECRET",
+		severity: "warn",
+		detail: "required for Better Auth session encryption"
+	}]) if (process.env[env.name]) results.push({
+		status: "pass",
+		label: `${env.name} set`
+	});
+	else results.push({
+		status: env.severity,
+		label: `${env.name} not set`,
+		detail: env.detail
+	});
+	let passCount = 0;
+	let warnCount = 0;
+	let failCount = 0;
+	for (const r of results) {
+		const icon = r.status === "pass" ? "[pass]" : r.status === "warn" ? "[warn]" : "[FAIL]";
+		const detail = r.detail ? ` (${r.detail})` : "";
+		console.log(`  ${icon} ${r.label}${detail}`);
+		if (r.status === "pass") passCount++;
+		else if (r.status === "warn") warnCount++;
+		else failCount++;
+	}
+	console.log(`\n${passCount} passed, ${warnCount} warnings, ${failCount} failures\n`);
+	if (failCount > 0) process.exitCode = 1;
+}
+function findPackageJson(dir) {
+	const paths = [join(dir, "package.json"), join(dir, "..", "package.json")];
+	for (const p of paths) try {
+		if (existsSync(p)) return JSON.parse(readFileSync(p, "utf-8"));
+	} catch {}
+	return null;
+}
+
+//#endregion
+export { describe, doctor, exportDocs, generate, init, introspect };

package/dist/constants-DdXFXQtN.mjs

@@ -0,0 +1,84 @@
+//#region src/constants.ts
+/**
+* Arc Framework Constants — Single Source of Truth
+*
+* Every default value, magic string, and framework constant lives here.
+* Import from this module instead of hard-coding values inline.
+*
+* All exported values are deeply frozen (Object.freeze) to prevent
+* accidental mutation at runtime — inspired by Go's const blocks
+* and Rust's immutable-by-default philosophy.
+*/
+/** Standard CRUD operation names */
+const CRUD_OPERATIONS = Object.freeze([
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete"
+]);
+/** Mutation operations that emit events */
+const MUTATION_OPERATIONS = Object.freeze([
+	"create",
+	"update",
+	"delete"
+]);
+/** Lifecycle hook phases */
+const HOOK_PHASES = Object.freeze([
+	"before",
+	"around",
+	"after"
+]);
+/** Hook operations (superset of CRUD — includes 'read' alias for 'get') */
+const HOOK_OPERATIONS = Object.freeze([
+	"create",
+	"update",
+	"delete",
+	"read",
+	"list"
+]);
+/** Default items per page */
+const DEFAULT_LIMIT = 20;
+/** Maximum items per page (framework-wide ceiling) */
+const DEFAULT_MAX_LIMIT = 1e3;
+/** Default sort field (descending creation date) */
+const DEFAULT_SORT = "-createdAt";
+/** Default primary key field name */
+const DEFAULT_ID_FIELD = "_id";
+/** Default multi-tenant scoping field */
+const DEFAULT_TENANT_FIELD = "organizationId";
+/** Default HTTP method for update routes */
+const DEFAULT_UPDATE_METHOD = "PATCH";
+/** System-managed fields that cannot be set via request body */
+const SYSTEM_FIELDS = Object.freeze([
+	"_id",
+	"__v",
+	"createdAt",
+	"updatedAt",
+	"deletedAt"
+]);
+/** Maximum regex pattern length (ReDoS mitigation) */
+const MAX_REGEX_LENGTH = 200;
+/** Maximum search query length */
+const MAX_SEARCH_LENGTH = 200;
+/** Maximum filter nesting depth (prevents filter bombs) */
+const MAX_FILTER_DEPTH = 10;
+/**
+* Query parameters consumed by the framework — never treated as filters.
+* Shared by all query parsers (Arc built-in, Prisma, custom).
+*/
+const RESERVED_QUERY_PARAMS = Object.freeze(new Set([
+	"page",
+	"limit",
+	"sort",
+	"populate",
+	"search",
+	"select",
+	"after",
+	"cursor",
+	"lean",
+	"_policyFilters"
+]));
+
+//#endregion
+export { DEFAULT_SORT as a, HOOK_OPERATIONS as c, MAX_REGEX_LENGTH as d, MAX_SEARCH_LENGTH as f, SYSTEM_FIELDS as h, DEFAULT_MAX_LIMIT as i, HOOK_PHASES as l, RESERVED_QUERY_PARAMS as m, DEFAULT_ID_FIELD as n, DEFAULT_TENANT_FIELD as o, MUTATION_OPERATIONS as p, DEFAULT_LIMIT as r, DEFAULT_UPDATE_METHOD as s, CRUD_OPERATIONS as t, MAX_FILTER_DEPTH as u };

package/dist/core/index.d.mts

@@ -0,0 +1,5 @@
+import "../elevation-DGo5shaX.mjs";
+import { E as defineResource, T as ResourceDefinition, c as BaseController, d as QueryResolverConfig, f as BodySanitizer, h as AccessControlConfig, l as BaseControllerOptions, m as AccessControl, p as BodySanitizerConfig, u as QueryResolver } from "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { A as createCrudRouter, C as MutationOperation, D as ActionRouterConfig, E as ActionHandler, O as IdempotencyService, S as MUTATION_OPERATIONS, T as SYSTEM_FIELDS, _ as HookOperation, a as getControllerScope, b as MAX_REGEX_LENGTH, c as CrudOperation, d as DEFAULT_MAX_LIMIT, f as DEFAULT_SORT, g as HOOK_PHASES, h as HOOK_OPERATIONS, i as getControllerContext, j as createPermissionMiddleware, k as createActionRouter, l as DEFAULT_ID_FIELD, m as DEFAULT_UPDATE_METHOD, n as createFastifyHandler, o as sendControllerResponse, p as DEFAULT_TENANT_FIELD, r as createRequestContext, s as CRUD_OPERATIONS, t as createCrudHandlers, u as DEFAULT_LIMIT, v as HookPhase, w as RESERVED_QUERY_PARAMS, x as MAX_SEARCH_LENGTH, y as MAX_FILTER_DEPTH } from "../fastifyAdapter-C8DlE0YH.mjs";
+export { AccessControl, type AccessControlConfig, type ActionHandler, type ActionRouterConfig, BaseController, type BaseControllerOptions, BodySanitizer, type BodySanitizerConfig, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, type IdempotencyService, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, type QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };

package/dist/core/index.mjs

@@ -0,0 +1,4 @@
+import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-DdXFXQtN.mjs";
+import { _ as QueryResolver, c as createPermissionMiddleware, d as createFastifyHandler, f as createRequestContext, g as BaseController, h as sendControllerResponse, m as getControllerScope, n as defineResource, o as createActionRouter, p as getControllerContext, s as createCrudRouter, t as ResourceDefinition, u as createCrudHandlers, v as BodySanitizer, y as AccessControl } from "../defineResource-PXzSJ15_.mjs";
+
+export { AccessControl, BaseController, BodySanitizer, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, createActionRouter, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineResource, getControllerContext, getControllerScope, sendControllerResponse };