@classytic/arc 2.11.4 → 2.14.0

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

@@ -1,18 +1,94 @@
+import { V as ResourceDefinition, ft as RouteSchemaOptions, rt as RateLimitConfig } from "../../index-BtW7qYwa.mjs";
+
 //#region src/cli/commands/describe.d.ts
+interface DescribedResource {
+  name: string;
+  displayName: string;
+  prefix: string;
+  tag: string;
+  module?: string;
+  adapter: {
+    type: string;
+    name: string;
+  } | null;
+  permissions: Record<string, PermissionDescription>;
+  presets: string[];
+  fields?: Record<string, FieldDescription>;
+  pipeline?: PipelineDescription;
+  routes: RouteDescription[];
+  events: EventDescription[];
+  /**
+   * Declarative `POST /:id/action` entries surfaced for tooling parity
+   * with OpenAPI/MCP. Empty when the resource declares no actions.
+   */
+  actions: ActionDescription[];
+  /** Per-resource fallback for actions without their own permission. */
+  actionPermissions?: PermissionDescription;
+  /**
+   * Declarative `GET /aggregations/:name` entries (v2.13). Empty when
+   * the resource declares no aggregations.
+   */
+  aggregations: AggregationDescription[];
+  schemaOptions?: RouteSchemaOptions;
+  rateLimit?: RateLimitConfig | false;
+  middlewares: string[];
+}
+interface ActionDescription {
+  name: string;
+  description?: string;
+  hasSchema: boolean;
+  permission: PermissionDescription;
+}
+interface AggregationDescription {
+  name: string;
+  summary?: string;
+  description?: string;
+  groupBy: unknown;
+  measures: string[];
+  permission: PermissionDescription;
+  requiresDateRange: boolean;
+  hasRequiredFilters: boolean;
+}
+interface PermissionDescription {
+  type: "public" | "requireAuth" | "requireRoles" | "custom";
+  roles?: readonly string[];
+}
+interface FieldDescription {
+  type: string;
+  roles?: readonly string[];
+  redactValue?: unknown;
+}
+interface PipelineDescription {
+  guards: PipelineStepDescription[];
+  transforms: PipelineStepDescription[];
+  interceptors: PipelineStepDescription[];
+}
+interface PipelineStepDescription {
+  name: string;
+  operations?: string[];
+}
+interface RouteDescription {
+  method: string;
+  path: string;
+  operation: string;
+  summary?: string;
+  description?: string;
+  permission?: PermissionDescription;
+}
+interface EventDescription {
+  name: string;
+  description?: string;
+  hasSchema: boolean;
+  hasHandler: boolean;
+}
 /**
- * Arc CLI - Describe Command
- *
- * Machine-readable resource metadata for AI agents.
- * Outputs JSON with fields, permissions, pipeline, routes, events —
- * everything an LLM needs to understand and generate code for the API.
- *
- * @example
- * ```bash
- * arc describe ./src/resources.js --json
- * arc describe ./src/resources.js --resource product
- * arc describe ./src/resources.js --pretty
- * ```
+ * Programmatic entry for the same surface the `arc describe` CLI emits per
+ * resource. Exported so cross-surface contract tests can verify that the
+ * CLI describe output stays in lockstep with registry / OpenAPI / MCP.
+ * Hosts that want a JSON dump of one resource without spawning the CLI
+ * can call this directly.
  */
+declare function describeResource(resource: ResourceDefinition<unknown>, module?: string): DescribedResource;
 declare function describe(args: string[]): Promise<void>;
 //#endregion
-export { describe };
+export { describe, describeResource };

package/dist/cli/commands/describe.mjs

@@ -1,4 +1,5 @@
-import { t as CRUD_OPERATIONS } from "../../constants-BhY1OHoH.mjs";
+import { t as CRUD_OPERATIONS } from "../../constants-Cxde4rpC.mjs";
+import { n as stringifyMeasureMap } from "../../ResourceRegistry-CTERg_2x.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/cli/commands/describe.ts
@@ -147,12 +148,60 @@ function describeEvents(resourceName, events) {
 		hasHandler: !!def.handler
 	}));
 }
+/**
+* Surface declarative `actions:` so the CLI matches what OpenAPI / MCP /
+* the registry already emit for the same definition. Resolves each
+* action's permission via the same fallback chain runtime uses:
+* per-action `permissions` → resource-level `actionPermissions` → custom.
+*/
+function describeActions(actions, fallback) {
+	if (!actions) return [];
+	return Object.entries(actions).map(([name, entry]) => {
+		if (typeof entry === "function") return {
+			name,
+			hasSchema: false,
+			permission: describePermission(fallback)
+		};
+		return {
+			name,
+			description: entry.description,
+			hasSchema: !!entry.schema,
+			permission: describePermission(entry.permissions ?? fallback)
+		};
+	});
+}
+/**
+* Surface declarative `aggregations:` (v2.13). Reuses
+* `stringifyMeasureMap` from the registry so the measure render matches
+* OpenAPI/MCP byte-for-byte — single source of truth for `'sum:price'`
+* vs `'count'` vs `'percentile:latency:0.95'`.
+*/
+function describeAggregations(aggregations) {
+	if (!aggregations) return [];
+	return Object.entries(aggregations).map(([name, entry]) => ({
+		name,
+		summary: entry.summary,
+		description: entry.description,
+		groupBy: entry.groupBy,
+		measures: Object.values(stringifyMeasureMap(entry.measures)),
+		permission: describePermission(entry.permissions),
+		requiresDateRange: !!entry.requireDateRange,
+		hasRequiredFilters: !!entry.requireFilters && entry.requireFilters.length > 0
+	}));
+}
 function describeMiddlewares(middlewares) {
 	if (!middlewares) return [];
 	const ops = [];
 	for (const [op, handlers] of Object.entries(middlewares)) if (handlers?.length) ops.push(`${op}(${handlers.length})`);
 	return ops;
 }
+/**
+* Programmatic entry for the same surface the `arc describe` CLI emits per
+* resource. Exported so cross-surface contract tests can verify that the
+* CLI describe output stays in lockstep with registry / OpenAPI / MCP.
+* Hosts that want a JSON dump of one resource without spawning the CLI
+* can call this directly.
+*/
 function describeResource(resource, module) {
 	return {
 		name: resource.name,
@@ -170,6 +219,9 @@ function describeResource(resource, module) {
 		pipeline: describePipeline(resource.pipe),
 		routes: describeRoutes(resource),
 		events: describeEvents(resource.name, resource.events),
+		actions: describeActions(resource.actions, resource.actionPermissions),
+		actionPermissions: resource.actionPermissions ? describePermission(resource.actionPermissions) : void 0,
+		aggregations: describeAggregations(resource.aggregations),
 		schemaOptions: Object.keys(resource.schemaOptions ?? {}).length > 0 ? resource.schemaOptions : void 0,
 		rateLimit: resource.rateLimit,
 		middlewares: describeMiddlewares(resource.middlewares)
@@ -240,6 +292,8 @@ async function describe(args) {
 				totalEvents: described.reduce((sum, r) => sum + r.events.length, 0),
 				totalCatalogedEvents: eventCatalog?.length ?? 0,
 				totalFields,
+				totalActions: described.reduce((sum, r) => sum + r.actions.length, 0),
+				totalAggregations: described.reduce((sum, r) => sum + r.aggregations.length, 0),
 				presetUsage: presetCounts,
 				pipelineSteps: totalPipelineSteps
 			}
@@ -252,4 +306,4 @@ async function describe(args) {
 	}
 }
 //#endregion
-export { describe };
+export { describe, describeResource };

package/dist/cli/commands/docs.mjs

@@ -1,5 +1,5 @@
-import { t as ResourceRegistry } from "../../ResourceRegistry-DkAeAuTX.mjs";
-import { t as buildOpenApiSpec } from "../../openapi-D7G1V7ex.mjs";
+import { t as ResourceRegistry } from "../../ResourceRegistry-CTERg_2x.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-noXno2CV.mjs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { mkdirSync, writeFileSync } from "node:fs";

package/dist/cli/commands/generate.mjs

@@ -1,4 +1,4 @@
-import { t as pluralize } from "../../pluralize-CWP6MB39.mjs";
+import { t as pluralize } from "../../pluralize-DQgqgifU.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/generate.ts
@@ -49,37 +49,73 @@ function getTemplates(ts, config = {}) {
  * Generated by Arc CLI
  */
 
-import mongoose${ts ? ", { type HydratedDocument }" : ""} from 'mongoose';
+${ts ? "import mongoose, { type HydratedDocument, type Model, type Types } from 'mongoose';" : "import mongoose from 'mongoose';"}
 
 const { Schema } = mongoose;
-${ts ? `
-export interface I${name} {
-  name: string;
-  description?: string;
-  ${isMultiTenant ? "organizationId: string;\n  " : ""}isActive: boolean;
-}
-
-export type ${name}Document = HydratedDocument<I${name}>;
-` : ""}
+${ts ? [
+				"",
+				"/**",
+				" * Persisted shape — what `.lean()` and `.toObject()` return. Carrying this",
+				` * through \`Model<I${name}>\` lets \`.select(...)\` / \`.find(...)\` / \`.lean()\``,
+				" * infer correctly so domain methods don't need `as` casts.",
+				" *",
+				" * Replace the placeholder fields with your real domain shape.",
+				" */",
+				`export interface I${name} {`,
+				"  _id: Types.ObjectId;",
+				...isMultiTenant ? ["  organizationId: Types.ObjectId;"] : [],
+				"  // TODO: define your fields here",
+				"  createdAt: Date;",
+				"  updatedAt: Date;",
+				"}",
+				"",
+				`export type ${name}Document = HydratedDocument<I${name}>;`,
+				""
+			].join("\n") : ""}
 const ${camel}Schema = new Schema${ts ? `<I${name}>` : ""}(
   {
-    name: { type: String, required: true, trim: true },
-    description: { type: String, trim: true },
-    ${isMultiTenant ? "organizationId: { type: String, required: true, index: true },\n    " : ""}isActive: { type: Boolean, default: true },
+${isMultiTenant ? "    organizationId: { type: Schema.Types.ObjectId, required: true, index: true },\n" : ""}    // TODO: declare your fields here, e.g. name: { type: String, required: true, trim: true },
   },
   { timestamps: true }
 );
 
-// Indexes
-${camel}Schema.index({ name: 1 });
-${isMultiTenant ? `${camel}Schema.index({ organizationId: 1, isActive: 1 });\n` : ""}${camel}Schema.index({ isActive: 1 });
+${isMultiTenant ? `${camel}Schema.index({ organizationId: 1, createdAt: -1 });\n` : ""}${ts ? [
+				`const ${name}: Model<I${name}> =`,
+				`  (mongoose.models.${name} as Model<I${name}> | undefined) ??`,
+				`  mongoose.model<I${name}>('${name}', ${camel}Schema);`
+			].join("\n") : `const ${name} = mongoose.models.${name} || mongoose.model('${name}', ${camel}Schema);`}
 
-const ${name} = mongoose.models.${name} || mongoose.model('${name}', ${camel}Schema);
 export default ${name};
 `;
 		},
 		repository: (name, fileName) => {
 			const camel = toCamelCase(name);
+			if (!(config.adapter === "mongokit" || !config.adapter)) {
+				const generic = ts ? `<I${name}>` : "";
+				return `/**
+ * ${name} Repository
+ * Generated by Arc CLI
+ *
+ * This project uses a custom adapter — wire your repository to whichever
+ * kit you're using (sqlitekit, prismakit, custom). Replace the body below
+ * with your kit's Repository constructor. Arc only requires the
+ * \`MinimalRepo\` floor (getAll/getById/create/update/delete) declared in
+ * \`@classytic/repo-core/repository\`.
+ */
+${ts ? `\nimport type { I${name} } from './${fileName}.model.js';` : ""}
+
+// Replace with your kit's repository instance:
+//   import { Repository } from '@classytic/sqlitekit';
+//   const ${camel}Repository = new Repository${generic}(${name}Table);
+//   export default ${camel}Repository;
+
+const ${camel}Repository = {
+  // TODO: implement MinimalRepo<${ts ? `I${name}` : "any"}>
+} as never;
+
+export default ${camel}Repository;
+`;
+			}
 			const generic = ts ? `<I${name}>` : "";
 			return `/**
  * ${name} Repository
@@ -90,25 +126,17 @@ import {
   Repository,
   methodRegistryPlugin,
   softDeletePlugin,
-  mongoOperationsPlugin,
 } from '@classytic/mongokit';
 import ${name} from './${fileName}.model.js';${ts ? `\nimport type { I${name} } from './${fileName}.model.js';` : ""}
 
 class ${name}Repository extends Repository${generic} {
   constructor() {
-    super(${name}, [
-      methodRegistryPlugin(),
-      softDeletePlugin(),
-      mongoOperationsPlugin(),
-    ]);
+    super(${name}, [methodRegistryPlugin(), softDeletePlugin()]);
   }
 
-  /**
-   * Find all active records
-   */
-  async findActive() {
-    return this.Model.find({ isActive: true, deletedAt: null }).lean();
-  }
+  // Add domain methods here. arc + mongokit ship the standard CRUD
+  // (getAll/getById/create/update/delete) on the base class, so only
+  // write a method when there's real domain logic to capture.
 }
 
 const ${camel}Repository = new ${name}Repository();
@@ -149,7 +177,7 @@ export default ${camel}Controller;
  */
 
 import ${name} from './${fileName}.model.js';
-import { buildCrudSchemasFromModel } from '@classytic/mongokit/utils';
+import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 
 /**
  * CRUD Schemas with Field Rules
@@ -171,8 +199,10 @@ const crudSchemas = buildCrudSchemasFromModel(${name}, {
     // organizationId: { systemManaged: true, preserveForElevated: true },
   },
   query: {
+    // Add your filterable fields here. createdAt is the default so the
+    // generated routes accept ?createdAt[gte]=2026-01-01 with no extra
+    // wiring. Add domain fields below as your model grows.
     filterableFields: {
-      isActive: 'boolean',
       createdAt: 'date',
     },
   },
@@ -183,23 +213,38 @@ export default crudSchemas;
 		resource: (name, fileName) => {
 			const camel = toCamelCase(name);
 			const useMongoKit = config.adapter === "mongokit" || !config.adapter;
-			const queryParserImport = useMongoKit ? `\nimport { QueryParser } from '@classytic/mongokit';\n\nconst queryParser = new QueryParser({\n  allowedFilterFields: ['isActive'],\n});\n` : "";
+			const schemaGeneratorImport = useMongoKit ? `import { buildCrudSchemasFromModel } from '@classytic/mongokit';\n` : "";
+			const queryParserImport = useMongoKit ? `\nimport { QueryParser } from '@classytic/mongokit';\n\nconst queryParser = new QueryParser({\n  // Whitelist the fields this resource accepts in URL filters.\n  // Empty by default — only \`createdAt\` is implicit; add yours.\n  allowedFilterFields: [],\n});\n` : "";
+			const adapterCall = useMongoKit ? `createMongooseAdapter({ model: ${name}, repository: ${camel}Repository, schemaGenerator: buildCrudSchemasFromModel })` : `createMongooseAdapter({ model: ${name}, repository: ${camel}Repository })`;
 			const queryParserConfig = useMongoKit ? `\n  queryParser,` : "";
 			return isMultiTenant ? `/**
  * ${name} Resource
  * Generated by Arc CLI
  */
 
-import { defineResource, createMongooseAdapter } from '@classytic/arc';
+import { defineResource } from '@classytic/arc';
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
 import { allOf, requireOrgMembership, requireRoles } from '@classytic/arc/permissions';
 import { multiTenantPreset } from '@classytic/arc/presets';
-import ${name}${ts ? `, { type I${name} }` : ""} from './${fileName}.model.js';
+${schemaGeneratorImport}import ${name}${ts ? `, { type I${name} }` : ""} from './${fileName}.model.js';
 import ${camel}Repository from './${fileName}.repository.js';${queryParserImport}
 
 const ${camel}Resource = defineResource${ts ? `<I${name}>` : ""}({
   name: '${fileName}',
-  adapter: createMongooseAdapter({ model: ${name}, repository: ${camel}Repository }),${queryParserConfig}
+  adapter: ${adapterCall},${queryParserConfig}
+
+  // Multi-tenant default: scope reads/writes by \`organizationId\`. For
+  // company-wide tables (lookup data, platform settings) set
+  // \`tenantField: false\` instead — otherwise queries silently return
+  // nothing because the column doesn't exist.
+  //
+  // Multi-level tenancy (org + branch + project, etc.) — replace with:
+  //   multiTenantPreset({ tenantFields: [
+  //     { field: 'organizationId', type: 'org' },
+  //     { field: 'branchId', contextKey: 'branchId' },
+  //   ] })
   presets: ['softDelete', multiTenantPreset({ tenantField: 'organizationId' })],
+
   permissions: {
     list: requireOrgMembership(),
     get: requireOrgMembership(),
@@ -215,15 +260,22 @@ export default ${camel}Resource;
  * Generated by Arc CLI
  */
 
-import { defineResource, createMongooseAdapter } from '@classytic/arc';
+import { defineResource } from '@classytic/arc';
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
 import { requireAuth, requireRoles } from '@classytic/arc/permissions';
-import ${name}${ts ? `, { type I${name} }` : ""} from './${fileName}.model.js';
+${schemaGeneratorImport}import ${name}${ts ? `, { type I${name} }` : ""} from './${fileName}.model.js';
 import ${camel}Repository from './${fileName}.repository.js';${queryParserImport}
 
 const ${camel}Resource = defineResource${ts ? `<I${name}>` : ""}({
   name: '${fileName}',
-  adapter: createMongooseAdapter({ model: ${name}, repository: ${camel}Repository }),${queryParserConfig}
+  adapter: ${adapterCall},${queryParserConfig}
+
+  // Single-tenant default: arc auto-infers \`tenantField: false\` when
+  // the model has no \`organizationId\` path (silent-zero-results
+  // footgun closed in 2.12). Set \`tenantField: '<field>'\` to opt INTO
+  // tenant scoping, or \`tenantField: false\` to make it explicit.
   presets: ['softDelete'],
+
   permissions: {
     list: requireAuth(),
     get: requireAuth(),
@@ -278,13 +330,20 @@ ${ts ? "import { z } from 'zod';\n" : "const { z } = require('zod');\n"}
  * ${name} Tests
  * Generated by Arc CLI
  *
- * 2.11 testing surface:
+ * Testing surface (arc 2.12+):
  *   - createTestApp   turnkey Fastify + in-memory Mongo + auth + fixtures
- *   - expectArc       fluent envelope matchers (.ok, .unauthorized, .forbidden, ...)
+ *   - expectArc       fluent matchers — .ok / .failed / .unauthorized /
+ *                     .forbidden / .notFound / .conflict / .validationError /
+ *                     .paginated / .hidesField / .hasData / .hasStatus
  *   - ctx.auth        unified TestAuthProvider — register a role, reuse .headers
+ *
+ * Wire shape (post-2.12): single-doc responses are flat (\`{_id, name, ...}\`),
+ * paginated responses are \`{ method: 'offset', data: [...], page, ... }\`.
+ * No \`success\` envelope — HTTP status discriminates success vs error;
+ * errors carry the canonical ErrorContract \`{ code, message, status }\`.
  */
 
-import { describe, it, beforeAll, afterAll } from 'vitest';
+import { describe, it, beforeAll, afterAll, expect } from 'vitest';
 import { createTestApp, expectArc } from '@classytic/arc/testing';
 import type { TestAppContext } from '@classytic/arc/testing';
 import ${camel}Resource from '../src/resources/${fileName}/${fileName}.resource.js';
@@ -308,17 +367,42 @@ describe('${name} Resource', () => {
   afterAll(() => ctx.close());
 
   describe('GET /${pluralize(fileName)}', () => {
-    it('should return a paginated list', async () => {
-      const res = await ctx.app.inject({ method: 'GET', url: '/${pluralize(fileName)}' });
+    it('returns a paginated list', async () => {
+      const res = await ctx.app.inject({
+        method: 'GET',
+        url: '/${pluralize(fileName)}',
+        headers: ctx.auth${ts ? "!" : ""}.as('admin').headers,
+      });
       expectArc(res).ok().paginated();
     });
+
+    it('rejects unauthenticated requests', async () => {
+      const res = await ctx.app.inject({ method: 'GET', url: '/${pluralize(fileName)}' });
+      expectArc(res).unauthorized();
+    });
+  });
+
+  describe('POST /${pluralize(fileName)}', () => {
+    it('creates a record (flat wire shape — no envelope)', async () => {
+      const res = await ctx.app.inject({
+        method: 'POST',
+        url: '/${pluralize(fileName)}',
+        headers: ctx.auth${ts ? "!" : ""}.as('admin').headers,
+        payload: { name: 'Example' },
+      });
+      expectArc(res).ok(201);
+      // Single-doc response is flat: \`body._id\` (not \`body.data._id\`).
+      const body = res.json()${ts ? " as { _id: string; name: string }" : ""};
+      expect(body._id).toBeDefined();
+      expect(body.name).toBe('Example');
+    });
   });
 
-  // More coverage patterns:
-  //   - expectArc(res).unauthorized() for missing auth
-  //   - expectArc(res).forbidden() for wrong role
-  //   - ctx.auth.as('admin').headers for authenticated requests
+  // More patterns to extend:
+  //   - expectArc(res).forbidden() / .notFound() / .validationError()
+  //   - expectArc(res).hidesField('password') for field-level perms
   //   - ctx.fixtures.create('${fileName}', {...}) for seeded data
+  //   - error wire shape: body.code === 'arc.not_found' (ErrorContract)
 });
 `;
 		}
@@ -333,6 +417,21 @@ async function generate(type, args) {
 	if (!name) throw new Error("Missing name argument\nUsage: arc generate <type> <name>\nExample: arc generate resource product");
 	const capitalizedName = toPascalCase(name);
 	const lowerName = name.toLowerCase();
+	if ((type === "resource" || type === "r" || type === "model" || type === "m") && new Set([
+		"user",
+		"session",
+		"account",
+		"verification",
+		"organization",
+		"member",
+		"invitation",
+		"team",
+		"team-member",
+		"apikey"
+	]).has(lowerName)) {
+		console.warn(`\n[arc generate] "${lowerName}" is a Better Auth-owned collection.\nBetter Auth's organization/admin/bearer plugins write this collection directly,\nso generating a parallel arc model would create a duplicate registration.\n\nRecommended pattern:\n  import { createBetterAuthOverlay } from '@classytic/mongokit/better-auth';\n  const adapter = await createBetterAuthOverlay({\n    auth, mongoose, collection: '${lowerName}',\n  });\n  // ...then \`defineResource({ name: '${lowerName}', adapter, ... })\` reads\n  //    BA's collection through arc with full pagination/filters/permissions.\n\nAborting. Re-run with a different name if you need a separate domain model.\n`);
+		return;
+	}
 	const projectConfig = readProjectConfig();
 	const ts = projectConfig.typescript ?? isTypeScriptProject();
 	const ext = ts ? "ts" : "js";

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

@@ -14,6 +14,19 @@ interface InitOptions {
   adapter?: "mongokit" | "custom";
   auth?: "jwt" | "better-auth";
   tenant?: "multi" | "single";
+  /**
+   * Enable Better Auth's `apiKey` plugin (`@better-auth/api-key`) for
+   * machine-to-machine authentication alongside cookie/session auth.
+   * Only used when `auth === 'better-auth'`. Default: false.
+   */
+  apiKey?: boolean;
+  /**
+   * Session strategy when using Better Auth.
+   * - `cookie` (default): browser cookie + DB-backed session (BA's default)
+   * - `bearer`: Authorization: Bearer header (mobile apps, SPA, M2M)
+   * Both can coexist — `bearer: true` adds bearer alongside cookies.
+   */
+  session?: "cookie" | "bearer" | "both";
   typescript?: boolean;
   edge?: boolean;
   skipInstall?: boolean;