@classytic/arc 2.15.3 → 2.15.4

package/dist/cli/commands/init.mjs

@@ -376,20 +376,29 @@ function packageJsonTemplate(config) {
 		test: "vitest run",
 		"test:watch": "vitest"
 	};
+	const imports = config.typescript ? {
+		"#config/*": "./dist/config/*",
+		"#shared/*": "./dist/shared/*",
+		"#resources/*": "./dist/resources/*",
+		"#plugins/*": "./dist/plugins/*",
+		"#services/*": "./dist/services/*",
+		"#lib/*": "./dist/lib/*",
+		"#utils/*": "./dist/utils/*"
+	} : {
+		"#config/*": "./src/config/*",
+		"#shared/*": "./src/shared/*",
+		"#resources/*": "./src/resources/*",
+		"#plugins/*": "./src/plugins/*",
+		"#services/*": "./src/services/*",
+		"#lib/*": "./src/lib/*",
+		"#utils/*": "./src/utils/*"
+	};
 	return JSON.stringify({
 		name: config.name,
 		version: "1.0.0",
 		type: "module",
 		main: config.typescript ? "dist/index.js" : "src/index.js",
-		imports: {
-			"#config/*": "./src/config/*",
-			"#shared/*": "./src/shared/*",
-			"#resources/*": "./src/resources/*",
-			"#plugins/*": "./src/plugins/*",
-			"#services/*": "./src/services/*",
-			"#lib/*": "./src/lib/*",
-			"#utils/*": "./src/utils/*"
-		},
+		imports,
 		scripts,
 		dependencies,
 		devDependencies,

package/dist/index.mjs

@@ -6,6 +6,6 @@ import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf,
 import { v as getControllerScope } from "./routerShared-DrOa-26E.mjs";
 import { a as defineResource, i as defineResourceVariants, l as defineAggregation, o as ResourceDefinition } from "./core-CvmOqEms.mjs";
 //#region src/index.ts
-const version = "2.15.3";
+const version = "2.15.4";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, getUserId, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/integrations/streamline.d.mts

@@ -50,7 +50,40 @@ interface WorkflowLike {
     }; /** Repository — used by the list-runs endpoint to query workflow_runs. */
     repository?: {
       getAll(params: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+      /**
+       * Tenant-scoped lookup by id. Used by the DELETE handler for a
+       * defense-in-depth pre-flight: streamline 2.3.3's `wf.get(runId)` /
+       * `engine.get` does NOT accept tenant options, so a cross-tenant
+       * runId can leak data through the engine path. Going through the
+       * repository here means mongokit's tenant-filter plugin scopes the
+       * read — cross-tenant requests get a clean 404 and DELETEs only
+       * touch rows the caller actually owns.
+       */
+      getById?(id: string, options?: Record<string, unknown>): Promise<WorkflowRunLike | null>;
+      /**
+       * Hard-delete a run by id. Routed through mongokit's inherited
+       * `Repository.delete()` so multi-tenant scope + audit/cache plugins
+       * fire. Wired into `DELETE /:workflowId/runs/:runId` — operator
+       * escape hatch for dead-lettered or stuck rows.
+       */
+      delete?(id: string, options?: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * Streamline >= 2.3.2 — explicit deploy-time index sync (TTL on
+     * terminal runs + tenant compounds). When the host configured
+     * `createContainer({ retention })`, arc's app-level deploy hook
+     * should call `await container.syncRetentionIndexes()` after
+     * `mongoose.connect`. Optional so older streamline versions
+     * (and partial mocks) still satisfy the structural shape.
+     */
+    syncRetentionIndexes?: () => Promise<void>;
+    /**
+     * Streamline >= 2.3.2 — stop background sweepers and release timers.
+     * Arc's `onClose` hook below calls this on every workflow's container
+     * during graceful shutdown so SIGTERM doesn't leave the stale-run
+     * sweeper running. Optional + idempotent.
+     */
+    dispose?: () => void;
   };
 }
 interface WorkflowRunLike {
@@ -67,7 +100,36 @@ interface WorkflowRunLike {
   stepLogs?: unknown[];
   createdAt?: Date;
   updatedAt?: Date;
+  /**
+   * Streamline >= 2.3.3 — pinned definition version (semver) the run
+   * started under. Hosts surfacing a "stuck on old version" UI read this
+   * to decide whether to nudge a migration. Optional for back-compat
+   * with runs created before 2.3.3.
+   */
+  definitionVersion?: string;
+  /**
+   * Streamline >= 2.3.3 — count of stale-recovery / sweeper transitions
+   * applied to this run. Sweeper dead-letters once this hits
+   * `RetentionOptions.maxStaleRecoveries`; UIs can highlight runs trending
+   * toward dead-letter.
+   */
+  recoveryAttempts?: number;
 }
+/**
+ * Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
+ * `'failed'`; the discrimination is `error.code`:
+ *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
+ *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
+ *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
+ *     resume against; admin must rewind / migrate / cancel.
+ *
+ * Hosts switch on `error.code` for dashboards / alerting.
+ */
+declare const STREAMLINE_FAILURE_CODES: {
+  readonly STALE_HEARTBEAT: "stale_heartbeat";
+  readonly DEAD_LETTERED: "dead_lettered";
+  readonly VERSION_MISMATCH: "VERSION_MISMATCH";
+};
 interface StreamlinePluginOptions {
   /** Array of workflows created with createWorkflow() */
   workflows: WorkflowLike[];
@@ -176,7 +238,14 @@ declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed",
  * the run is still active after them.
  */
 declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled"];
-/** Pluggable streamline integration for Arc */
+/**
+ * Pluggable streamline integration for Arc.
+ *
+ * Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
+ * plain plugin option (NOT an encapsulation prefix). Without the wrapper,
+ * Fastify would prepend `options.prefix` to every route, then the plugin
+ * code would prepend it again — the duplicate-prefix bug.
+ */
 declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };

package/dist/integrations/streamline.mjs

@@ -1,6 +1,22 @@
 import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-j4aJm1Wg.mjs";
+import fp from "fastify-plugin";
 //#region src/integrations/streamline.ts
 /**
+* Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
+* `'failed'`; the discrimination is `error.code`:
+*   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
+*   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
+*   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
+*     resume against; admin must rewind / migrate / cancel.
+*
+* Hosts switch on `error.code` for dashboards / alerting.
+*/
+const STREAMLINE_FAILURE_CODES = {
+	STALE_HEARTBEAT: "stale_heartbeat",
+	DEAD_LETTERED: "dead_lettered",
+	VERSION_MISMATCH: "VERSION_MISMATCH"
+};
+/**
 * Full event list published on a streamline workflow's internal `eventBus`
 * (tracks streamline 2.3's `EventPayloadMap` in
 * `@classytic/streamline/src/core/events.ts`).
@@ -44,6 +60,7 @@ const STREAMLINE_TERMINAL_EVENTS = [
 ];
 const streamlinePluginImpl = async (fastify, options) => {
 	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms } = options;
+	const routeScope = prefix;
 	const bridgeBus = options.bridgeBusEvents ?? false;
 	const registry = /* @__PURE__ */ new Map();
 	for (const wf of workflows) {
@@ -70,7 +87,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 		return check(request);
 	};
 	for (const [id, wf] of registry) {
-		const routePrefix = `${prefix}/${id}`;
+		const routePrefix = `${routeScope}/${id}`;
 		fastify.post(`${routePrefix}/start`, { preHandler: authPreHandler }, async (request, reply) => {
 			if (!await checkPerm("start", request)) throw new ForbiddenError();
 			const { input, meta, idempotencyKey, priority } = request.body ?? {};
@@ -161,6 +178,24 @@ const streamlinePluginImpl = async (fastify, options) => {
 			const { runId } = request.params;
 			return await wf.engine.execute(runId);
 		});
+		const deleteRepo = wf.container?.repository;
+		const repoDeleteFn = deleteRepo?.delete;
+		const repoGetByIdFn = deleteRepo?.getById;
+		if (repoDeleteFn && repoGetByIdFn) fastify.delete(`${routePrefix}/runs/:runId`, { preHandler: authPreHandler }, async (request, reply) => {
+			if (!await checkPerm("cancel", request)) throw new ForbiddenError();
+			const { runId } = request.params;
+			const tenantOpts = resolveTenantOpts(request);
+			const repoOpts = {
+				...tenantOpts.tenantId !== void 0 ? { tenantId: tenantOpts.tenantId } : {},
+				...tenantOpts.bypassTenant ? { bypassTenant: true } : {}
+			};
+			if (!await repoGetByIdFn(runId, repoOpts)) throw new NotFoundError(`Workflow run ${runId} not found`);
+			try {
+				await wf.cancel(runId);
+			} catch {}
+			await repoDeleteFn(runId, repoOpts);
+			return reply.status(204).send();
+		});
 		if (wf.engine.waitFor) fastify.get(`${routePrefix}/runs/:runId/wait`, { preHandler: authPreHandler }, async (request, _reply) => {
 			if (!await checkPerm("get", request)) throw new ForbiddenError();
 			const { runId } = request.params;
@@ -239,7 +274,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 	}
 	if (enableHookEndpoint) {
 		let resumeHookFn;
-		fastify.post(`${prefix}/hooks/:token`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routeScope}/hooks/:token`, { preHandler: authPreHandler }, async (request, _reply) => {
 			if (!resumeHookFn) resumeHookFn = (await import("@classytic/streamline")).resumeHook;
 			const { token } = request.params;
 			const result = await resumeHookFn(token, request.body);
@@ -249,7 +284,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			};
 		});
 	}
-	fastify.get(prefix, { preHandler: authPreHandler }, async () => {
+	fastify.get(routeScope || "/", { preHandler: authPreHandler }, async () => {
 		return Array.from(registry.entries()).map(([id, wf]) => ({
 			id,
 			name: wf.definition.name ?? id,
@@ -257,10 +292,23 @@ const streamlinePluginImpl = async (fastify, options) => {
 		}));
 	});
 	fastify.addHook("onClose", async () => {
-		for (const wf of registry.values()) wf.shutdown?.();
+		for (const wf of registry.values()) {
+			wf.shutdown?.();
+			wf.container?.dispose?.();
+		}
 	});
 };
-/** Pluggable streamline integration for Arc */
-const streamlinePlugin = streamlinePluginImpl;
+/**
+* Pluggable streamline integration for Arc.
+*
+* Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
+* plain plugin option (NOT an encapsulation prefix). Without the wrapper,
+* Fastify would prepend `options.prefix` to every route, then the plugin
+* code would prepend it again — the duplicate-prefix bug.
+*/
+const streamlinePlugin = fp(streamlinePluginImpl, {
+	name: "streamline-routes",
+	fastify: "5.x"
+});
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_TERMINAL_EVENTS, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, streamlinePlugin };

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.15.3";
+	const resolvedVersion = serviceVersion ?? "2.15.4";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.15.3",
+  "version": "2.15.4",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -245,9 +245,9 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.4.0",
+    "@classytic/primitives": ">=0.5.0",
     "@classytic/repo-core": ">=0.4.1",
-    "@classytic/streamline": ">=2.3.0",
+    "@classytic/streamline": ">=2.3.3",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
     "@fastify/jwt": ">=10.0.0",
@@ -361,7 +361,7 @@
     "@classytic/primitives": "^0.4.0",
     "@classytic/repo-core": "^0.4.1",
     "@classytic/sqlitekit": "^0.3.1",
-    "@classytic/streamline": "^2.3.0",
+    "@classytic/streamline": "^2.3.3",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
@@ -420,4 +420,4 @@
     "type": "git",
     "url": "https://github.com/classytic/arc.git"
   }
-}
+}

package/skills/arc/SKILL.md

@@ -27,7 +27,7 @@ progressive_disclosure:
   entry_point:
     summary: "Resource-oriented Fastify framework: defineResource(), presets, permissions, QueryCache, events, multi-tenant, OpenAPI, MCP"
     when_to_use: "Building REST APIs with Fastify, resource CRUD, authentication, presets, caching, events, or production deployment"
-    quick_start: "1. arc init my-api --mongokit --jwt --ts  2. defineResource({ name, adapter, presets, permissions })  3. createApp({ preset: 'production', resources, auth })"
+    quick_start: "1. npx @classytic/arc init my-api --mongokit --better-auth --single --ts  2. defineResource({ name, adapter, presets, permissions })  3. createApp({ preset: 'production', resources, auth })"
 ---
 
 # @classytic/arc
@@ -39,11 +39,11 @@ One `defineResource()` call → REST + auth + permissions + events + cache + Ope
 ## Scaffold a project
 
 ```bash
-npx @classytic/arc@latest init my-api --mongokit --jwt --ts
+npx @classytic/arc@latest init my-api --mongokit --better-auth --single --ts
 cd my-api && npm install && npm run dev
 ```
 
-Flags: `--mongokit | --custom`, `--jwt | --better-auth`, `--single | --multi`, `--ts | --js`. The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass.
+Flags: `--mongokit | --custom`, `--better-auth | --jwt`, `--single | --multi`, `--ts | --js`, `--edge`, `--force`, `--skip-install`. Defaults: `--mongokit --better-auth --single --ts`. The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass.
 
 ## createApp()
 
@@ -691,6 +691,19 @@ the kit's multi-tenant plugin reads `context.organizationId`, casts
 correctly, and merges into the request. Authors never inject the
 tenant key into `aggReq.filter` themselves.
 
+**2.15.3 — `multiTenantPreset` now wires `/aggregations/:name`.** Pre-2.15.3
+the preset only scoped CRUD; aggregation routes leaked across orgs for any
+caller whose `scope.kind !== 'member'`. Adding `multiTenantPreset({ tenantField: 'organizationId' })`
+now emits an `aggregations` middleware slot alongside the five CRUD slots, so
+member callers see only their org and `kind: 'elevated'` callers WITHOUT a
+target org get `bypassTenant: true` (platform-admin cross-tenant dashboards).
+**Kit config note:** set `scope: true` (or `scope: { fieldType: 'objectId' }`)
+on revenue/order/etc. engines — the pre-2.15.2 advice to use `scope: false`
+"to avoid double-scoping with arc" is no longer correct; arc 2.15.2+
+deliberately leaves `aggReq.filter` clean and relies on the kit. Required
+peers: `@classytic/repo-core ≥ 0.4.1`, `@classytic/mongokit ≥ 3.13.2`,
+`@classytic/sqlitekit ≥ 0.3.1`.
+
 **Caller filters via query string compose with `groupBy` / measures:**
 
 ```
@@ -833,14 +846,17 @@ Full testing recipes → [references/testing.md](references/testing.md).
 
 ## CLI
 
+The bin is `arc` (registered by `@classytic/arc`). Outside an arc project use `npx @classytic/arc <cmd>`; inside one (devDep installed) bare `arc` resolves through `node_modules/.bin`.
+
 ```bash
-arc init my-api --mongokit --jwt --ts          # scaffold (also: --custom, --better-auth, --multi)
-arc generate resource product                   # generate a resource
-arc generate resource product --mcp             # + MCP tools file
-arc generate mcp analytics                      # standalone MCP tools file
-arc docs ./openapi.json --entry ./dist/index.js # emit OpenAPI
-arc introspect --entry ./dist/index.js
-arc doctor
+npx @classytic/arc init my-api --mongokit --better-auth --single --ts   # scaffold (also: --custom, --jwt, --multi, --js, --edge)
+npx @classytic/arc generate resource product                            # generate a resource (alias: arc g r product)
+npx @classytic/arc generate resource product --mcp                      # + MCP tools file
+npx @classytic/arc generate mcp analytics                               # standalone MCP tools file
+npx @classytic/arc docs ./openapi.json --entry ./dist/index.js          # emit OpenAPI
+npx @classytic/arc introspect --entry ./dist/index.js
+npx @classytic/arc describe ./dist/resources.js --json                  # JSON metadata for AI agents
+npx @classytic/arc doctor
 ```
 
 Set `"mcp": true` in `.arcrc` to always generate `.mcp.ts` alongside resources.