@apso/cli 0.16.1 → 0.18.0

package/dist/commands/generate.js

@@ -13,7 +13,7 @@ class Generate extends base_command_1.default {
         const { flags } = await this.parse(Generate);
         const skipFormat = flags["skip-format"];
         const totalBuildStart = perf_hooks_1.performance.now();
-        const { rootFolder, entities, relationshipMap, apiType, auth, language: configLanguage } = (0, lib_1.parseApsorc)();
+        const { rootFolder, entities, relationshipMap, apiType, auth, emitEvents, language: configLanguage } = (0, lib_1.parseApsorc)();
         // Resolve language: flag > .apsorc > prompt
         let language;
         if (flags.language) {
@@ -63,6 +63,7 @@ class Generate extends base_command_1.default {
             entities,
             relationshipMap,
             auth,
+            emitEvents,
         };
         const generator = (0, lib_1.createGenerator)(generatorConfig);
         const validationResult = generator.validateConfig(generatorConfig);
@@ -148,8 +149,15 @@ class Generate extends base_command_1.default {
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
         generatedFileCount += guardFiles.length;
+        // Generate domain-event spine (only when at least one entity opts in)
+        const domainEventFiles = await generator.generateDomainEvents(entities, lowerCaseApiType, { emitEvents });
+        for (const file of domainEventFiles) {
+            const fullPath = path.join(autogenPath, file.path);
+            // eslint-disable-next-line no-await-in-loop
+            await (0, file_system_1.createFile)(fullPath, file.content);
+        }
         // Generate index module
-        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType);
+        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents });
         for (const file of indexFiles) {
             const fullPath = path.join(autogenPath, file.path);
             // eslint-disable-next-line no-await-in-loop

package/dist/commands/mcp/serve.js

@@ -923,6 +923,7 @@ const INLINE_SCHEMA_REFERENCE = `# Schema Quick Reference
   "updated_at": true,
   "primaryKeyType": "serial",
   "scopeBy": "organizationId",
+  "emitEvents": true,
   "fields": [
     { "name": "fieldName", "type": "text", "length": 100 }
   ],
@@ -932,6 +933,19 @@ const INLINE_SCHEMA_REFERENCE = `# Schema Quick Reference
 }
 \`\`\`
 
+## Domain Events (emitEvents)
+Set \`emitEvents: true\` (per-entity or as a top-level default) to durably log
+state changes. A top-level \`emitEvents: true\` enables it for every entity; an
+individual entity can opt out with \`emitEvents: false\` (effective value is
+\`entity.emitEvents ?? <top-level emitEvents> ?? false\`).
+
+When at least one entity opts in, the generator emits a single schema-derived
+manifest at \`autogen/events/event-emitting.entities.ts\` exporting
+\`EVENT_EMITTING_ENTITIES\` (the opted-in entity classes) and
+\`EVENT_EMITTING_ENTITY_NAMES\`. The domain-event engine itself ships in the
+\`@apso/domain-events\` library and is wired by the \`domain-events\` skill; the
+CLI no longer generates the engine code.
+
 ## Relationship Types
 - OneToMany: parent has many children
 - ManyToOne: child belongs to parent

package/dist/lib/apsorc-parser.d.ts

@@ -14,6 +14,12 @@ export type ApsorcType = {
     relationships: ApsorcRelationship[];
     auth?: AuthConfig;
     language?: TargetLanguage;
+    /**
+     * Top-level default for the opt-in DomainEvent ("emitEvents") feature.
+     * When true, every entity emits domain events unless it opts out with
+     * its own `emitEvents: false`.
+     */
+    emitEvents?: boolean;
 };
 type ParsedApsorcData = {
     entities: Entity[];
@@ -26,6 +32,8 @@ type ParsedApsorc = {
     relationshipMap: RelationshipMap;
     auth?: AuthConfig;
     language?: TargetLanguage;
+    /** Top-level default for the DomainEvent ("emitEvents") feature. */
+    emitEvents?: boolean;
 };
 export declare const parseApsorcV1: (apsorc: ApsorcType) => ParsedApsorcData;
 export declare const parseApsorcV2: (apsorc: ApsorcType) => ParsedApsorcData;

package/dist/lib/apsorc-parser.js

@@ -36,6 +36,7 @@ const parseRc = () => {
     const relationships = apsoConfig.relationships || [];
     const auth = apsoConfig.auth;
     const language = apsoConfig.language;
+    const emitEvents = apsoConfig.emitEvents;
     return {
         rootFolder,
         apiType,
@@ -44,6 +45,7 @@ const parseRc = () => {
         relationships,
         auth,
         language,
+        emitEvents,
     };
 };
 const parseApsorc = () => {
@@ -63,6 +65,7 @@ const parseApsorc = () => {
                     apiType: apsoConfig.apiType,
                     auth: apsoConfig.auth,
                     language: apsoConfig.language,
+                    emitEvents: apsoConfig.emitEvents,
                     ...(0, exports.parseApsorcV1)(apsoConfig),
                 };
                 if (debug) {
@@ -79,6 +82,7 @@ const parseApsorc = () => {
                     apiType: apsoConfig.apiType,
                     auth: apsoConfig.auth,
                     language: apsoConfig.language,
+                    emitEvents: apsoConfig.emitEvents,
                     ...(() => {
                         const relStart = perf_hooks_1.performance.now();
                         const parsed = (0, exports.parseApsorcV2)(apsoConfig);

package/dist/lib/events.d.ts

@@ -0,0 +1,32 @@
+import { Entity } from "./types";
+/**
+ * Helpers for the opt-in DomainEvent ("emitEvents") feature.
+ *
+ * Under the Apso Distribution Model the domain-event engine ships in the
+ * `@apso/domain-events` library (wired by the `domain-events` skill). The CLI
+ * only uses these helpers to compute which entities opted in, and emits a
+ * schema-derived manifest (`events/event-emitting.entities.ts`).
+ *
+ * Flag resolution: the effective per-entity value is
+ *   `entity.emitEvents ?? globalEmitEvents ?? false`
+ * so a top-level `emitEvents: true` enables it for every entity, while an
+ * individual entity can opt out with `emitEvents: false` (global default WITH
+ * per-entity opt-out).
+ */
+/**
+ * Computes whether a single entity has domain events enabled, given the
+ * top-level (global) default.
+ */
+export declare function isEmitEventsEnabled(entity: Entity, globalEmitEvents?: boolean): boolean;
+/**
+ * Computes the set of entities that have opted in to domain-event emission.
+ * This is the single source of truth used everywhere (generator, wiring,
+ * subscriber scoping).
+ */
+export declare function getEventEmittingEntities(entities: Entity[], globalEmitEvents?: boolean): Entity[];
+/**
+ * Returns true when at least one entity has domain events enabled, meaning the
+ * event-emitting manifest (`events/event-emitting.entities.ts`) should be
+ * generated.
+ */
+export declare function hasEventEmittingEntities(entities: Entity[], globalEmitEvents?: boolean): boolean;

package/dist/lib/events.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasEventEmittingEntities = exports.getEventEmittingEntities = exports.isEmitEventsEnabled = void 0;
+/**
+ * Helpers for the opt-in DomainEvent ("emitEvents") feature.
+ *
+ * Under the Apso Distribution Model the domain-event engine ships in the
+ * `@apso/domain-events` library (wired by the `domain-events` skill). The CLI
+ * only uses these helpers to compute which entities opted in, and emits a
+ * schema-derived manifest (`events/event-emitting.entities.ts`).
+ *
+ * Flag resolution: the effective per-entity value is
+ *   `entity.emitEvents ?? globalEmitEvents ?? false`
+ * so a top-level `emitEvents: true` enables it for every entity, while an
+ * individual entity can opt out with `emitEvents: false` (global default WITH
+ * per-entity opt-out).
+ */
+/**
+ * Computes whether a single entity has domain events enabled, given the
+ * top-level (global) default.
+ */
+function isEmitEventsEnabled(entity, globalEmitEvents) {
+    var _a, _b;
+    return (_b = (_a = entity.emitEvents) !== null && _a !== void 0 ? _a : globalEmitEvents) !== null && _b !== void 0 ? _b : false;
+}
+exports.isEmitEventsEnabled = isEmitEventsEnabled;
+/**
+ * Computes the set of entities that have opted in to domain-event emission.
+ * This is the single source of truth used everywhere (generator, wiring,
+ * subscriber scoping).
+ */
+function getEventEmittingEntities(entities, globalEmitEvents) {
+    return entities.filter((entity) => isEmitEventsEnabled(entity, globalEmitEvents));
+}
+exports.getEventEmittingEntities = getEventEmittingEntities;
+/**
+ * Returns true when at least one entity has domain events enabled, meaning the
+ * event-emitting manifest (`events/event-emitting.entities.ts`) should be
+ * generated.
+ */
+function hasEventEmittingEntities(entities, globalEmitEvents) {
+    return entities.some((entity) => isEmitEventsEnabled(entity, globalEmitEvents));
+}
+exports.hasEventEmittingEntities = hasEventEmittingEntities;

package/dist/lib/generators/base.d.ts

@@ -52,7 +52,9 @@ export declare abstract class BaseGenerator implements LanguageGenerator {
     /**
      * Generate the index/main module file
      */
-    abstract generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    abstract generateIndexModule(entities: Entity[], apiType: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Generate guard files (auth, scope, etc.)
      */
@@ -62,6 +64,15 @@ export declare abstract class BaseGenerator implements LanguageGenerator {
      * Default no-op. Override in language generators that need query utils.
      */
     generateQueryUtils(_entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
+    /**
+     * Emit a schema-derived manifest of entities that opt in to `emitEvents`.
+     * The domain-event engine ships in the `@apso/domain-events` library (wired
+     * by the `domain-events` skill); the generator only declares participants.
+     * Default no-op. Override in language generators that support it.
+     */
+    generateDomainEvents(_entities: Entity[], _apiType?: string, _opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Render a template file with the given data
      */

package/dist/lib/generators/base.js

@@ -27,6 +27,15 @@ class BaseGenerator {
     async generateQueryUtils(_entities, _apiType) {
         return [];
     }
+    /**
+     * Emit a schema-derived manifest of entities that opt in to `emitEvents`.
+     * The domain-event engine ships in the `@apso/domain-events` library (wired
+     * by the `domain-events` skill); the generator only declares participants.
+     * Default no-op. Override in language generators that support it.
+     */
+    async generateDomainEvents(_entities, _apiType, _opts) {
+        return [];
+    }
     /**
      * Render a template file with the given data
      */

package/dist/lib/generators/typescript.d.ts

@@ -16,8 +16,30 @@ export declare class TypeScriptGenerator extends BaseGenerator {
     generateModule(options: EntityGenerationOptions): Promise<GeneratedFile[]>;
     generateMigration(_options: MigrationGenerationOptions): Promise<GeneratedFile[]>;
     generateEnums(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
-    generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    generateIndexModule(entities: Entity[], apiType: string, _opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     generateGuards(entities: Entity[], auth?: AuthConfig): Promise<GeneratedFile[]>;
+    /**
+     * Emits a schema-derived manifest of the entities that have opted in to
+     * domain-event emission (`.apsorc` `emitEvents`).
+     *
+     * Under the Apso Distribution Model the domain-event engine no longer ships
+     * as generated code; it lives in the `@apso/domain-events` library and is
+     * wired by the `domain-events` skill. The CLI's only responsibility is to
+     * declare WHICH entities participate, via a single generated file:
+     * `events/event-emitting.entities.ts`.
+     *
+     * Returns an empty array when no entity is opted in, so callers can skip
+     * wiring entirely.
+     *
+     * @param entities All entities from the configuration
+     * @param _apiType API type (unused; events are REST/Graphql agnostic)
+     * @param opts.emitEvents Top-level (global) default for emitEvents
+     */
+    generateDomainEvents(entities: Entity[], _apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Normalizes auth config by applying defaults for DB session providers
      */

package/dist/lib/generators/typescript.js

@@ -15,6 +15,7 @@ const fs = tslib_1.__importStar(require("fs"));
 const os = tslib_1.__importStar(require("os"));
 const util_1 = require("util");
 const guards_1 = require("../guards");
+const events_1 = require("../events");
 const auth_1 = require("../types/auth");
 const unlinkAsync = (0, util_1.promisify)(fs.unlink);
 /**
@@ -302,7 +303,7 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
             },
         ];
     }
-    async generateIndexModule(entities, apiType) {
+    async generateIndexModule(entities, apiType, _opts) {
         const content = await this.renderTemplate(`./${apiType}/index-module-${apiType}`, { entities });
         return [
             {
@@ -355,6 +356,40 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
         });
         return files;
     }
+    /**
+     * Emits a schema-derived manifest of the entities that have opted in to
+     * domain-event emission (`.apsorc` `emitEvents`).
+     *
+     * Under the Apso Distribution Model the domain-event engine no longer ships
+     * as generated code; it lives in the `@apso/domain-events` library and is
+     * wired by the `domain-events` skill. The CLI's only responsibility is to
+     * declare WHICH entities participate, via a single generated file:
+     * `events/event-emitting.entities.ts`.
+     *
+     * Returns an empty array when no entity is opted in, so callers can skip
+     * wiring entirely.
+     *
+     * @param entities All entities from the configuration
+     * @param _apiType API type (unused; events are REST/Graphql agnostic)
+     * @param opts.emitEvents Top-level (global) default for emitEvents
+     */
+    async generateDomainEvents(entities, _apiType, opts) {
+        const emittingEntities = (0, events_1.getEventEmittingEntities)(entities, opts === null || opts === void 0 ? void 0 : opts.emitEvents);
+        if (emittingEntities.length === 0) {
+            return [];
+        }
+        const content = await this.renderTemplate("./events/event-emitting.entities.eta", {
+            emittingEntities: emittingEntities.map((entity) => ({
+                name: entity.name,
+            })),
+        });
+        return [
+            {
+                path: "events/event-emitting.entities.ts",
+                content,
+            },
+        ];
+    }
     /**
      * Normalizes auth config by applying defaults for DB session providers
      */

package/dist/lib/index.d.ts

@@ -1,5 +1,6 @@
 export { Entity, RelationshipMap } from "./types";
 export { parseApsorc } from "./apsorc-parser";
 export { hasScopedEntities, getScopedEntities } from "./guards";
+export { isEmitEventsEnabled, getEventEmittingEntities, hasEventEmittingEntities, } from "./events";
 export { BaseGenerator, TypeScriptGenerator, createGenerator, isLanguageSupported, getSupportedLanguages, getImplementedLanguages, } from "./generators";
 export type { TargetLanguage, GeneratedFile, ValidationResult, GeneratorConfig, LanguageGenerator, } from "./types";

package/dist/lib/index.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getImplementedLanguages = exports.getSupportedLanguages = exports.isLanguageSupported = exports.createGenerator = exports.TypeScriptGenerator = exports.BaseGenerator = exports.getScopedEntities = exports.hasScopedEntities = exports.parseApsorc = void 0;
+exports.getImplementedLanguages = exports.getSupportedLanguages = exports.isLanguageSupported = exports.createGenerator = exports.TypeScriptGenerator = exports.BaseGenerator = exports.hasEventEmittingEntities = exports.getEventEmittingEntities = exports.isEmitEventsEnabled = exports.getScopedEntities = exports.hasScopedEntities = exports.parseApsorc = void 0;
 var apsorc_parser_1 = require("./apsorc-parser");
 Object.defineProperty(exports, "parseApsorc", { enumerable: true, get: function () { return apsorc_parser_1.parseApsorc; } });
 var guards_1 = require("./guards");
 Object.defineProperty(exports, "hasScopedEntities", { enumerable: true, get: function () { return guards_1.hasScopedEntities; } });
 Object.defineProperty(exports, "getScopedEntities", { enumerable: true, get: function () { return guards_1.getScopedEntities; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "isEmitEventsEnabled", { enumerable: true, get: function () { return events_1.isEmitEventsEnabled; } });
+Object.defineProperty(exports, "getEventEmittingEntities", { enumerable: true, get: function () { return events_1.getEventEmittingEntities; } });
+Object.defineProperty(exports, "hasEventEmittingEntities", { enumerable: true, get: function () { return events_1.hasEventEmittingEntities; } });
 // Generator exports
 var generators_1 = require("./generators");
 Object.defineProperty(exports, "BaseGenerator", { enumerable: true, get: function () { return generators_1.BaseGenerator; } });

package/dist/lib/templates/events/event-emitting.entities.eta

@@ -0,0 +1,23 @@
+<%~ includeFile('../header.eta') %>
+
+<% it.emittingEntities.forEach((entity) => { %>
+import { <%= entity.name %> } from '../<%= entity.name %>/<%= entity.name %>.entity';
+<%}) %>
+
+/**
+ * Schema-derived manifest of entities that opted in to domain-event emission
+ * (`.apsorc` `emitEvents`). The domain-event engine itself lives in the
+ * `@apso/domain-events` library and is wired by the `domain-events` skill;
+ * this file only declares WHICH entities participate.
+ */
+export const EVENT_EMITTING_ENTITIES = [
+<% it.emittingEntities.forEach((entity) => { %>
+  <%= entity.name %>,
+<%}) %>
+];
+
+export const EVENT_EMITTING_ENTITY_NAMES = [
+<% it.emittingEntities.forEach((entity) => { %>
+  '<%= entity.name %>',
+<%}) %>
+];

package/dist/lib/types/entity.d.ts

@@ -45,5 +45,15 @@ export interface Entity {
      * Optional configuration for how scope enforcement should behave.
      */
     scopeOptions?: ScopeOptions;
+    /**
+     * When true, state changes to this entity (insert/update/remove) emit a
+     * durable DomainEvent row written in the SAME database transaction as the
+     * change (transactional-outbox pattern, surfaced as generic "domain events").
+     *
+     * Resolution: the effective value is `entity.emitEvents ?? <global emitEvents> ?? false`.
+     * This means a top-level `emitEvents: true` enables it for every entity, while
+     * an individual entity can opt out with `emitEvents: false`.
+     */
+    emitEvents?: boolean;
     associations?: Association[];
 }

package/dist/lib/types/generator.d.ts

@@ -104,6 +104,11 @@ export interface GeneratorConfig {
      * Authentication configuration (optional)
      */
     auth?: AuthConfig;
+    /**
+     * Top-level default for the opt-in DomainEvent ("emitEvents") feature.
+     * Effective per-entity value is `entity.emitEvents ?? emitEvents ?? false`.
+     */
+    emitEvents?: boolean;
     /**
      * Language-specific configuration options
      */
@@ -229,7 +234,9 @@ export interface LanguageGenerator {
     /**
      * Generate the index/main module file that ties everything together
      */
-    generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    generateIndexModule(entities: Entity[], apiType: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Generate guard files (auth, scope, etc.)
      */
@@ -238,6 +245,13 @@ export interface LanguageGenerator {
      * Generate shared query utility files (filter, sort, pagination)
      */
     generateQueryUtils(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    /**
+     * Emit a schema-derived manifest of entities that opt in to `emitEvents`
+     * (engine lives in `@apso/domain-events`). Returns [] when none are opted in.
+     */
+    generateDomainEvents(entities: Entity[], apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
 }
 /**
  * Factory function type for creating language generators

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.16.1",
+      "version": "0.18.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@electric-sql/pglite": "^0.2.17",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.16.1",
+  "version": "0.18.0",
   "commands": {
     "config": {
       "id": "config",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",