@soapjs/cli 1.0.0

package/build/commands/add/command-plan.d.ts

@@ -0,0 +1,15 @@
+import { PlannedFile } from "../../io/file-writer";
+export interface AddCommandPlan {
+    name: string;
+    feature: string;
+    featuresRoot: string;
+}
+export declare function createCommandFiles(plan: AddCommandPlan): PlannedFile[];
+export declare function createCommandIndexFile(feature: string, featuresRoot: string, commandNames: string[]): PlannedFile;
+export interface CqrsFeatureImports {
+    commands: string[];
+    queries?: string[];
+}
+export declare function createCqrsConfigFile(featuresRoot: string, importsByKind: CqrsFeatureImports | string[]): PlannedFile;
+export declare function commandNameFromPath(filePath: string): string | undefined;
+export declare function commandFeatureFromPath(filePath: string, featuresRoot: string): string | undefined;

package/build/commands/add/command-plan.js

@@ -0,0 +1,182 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandFeatureFromPath = exports.commandNameFromPath = exports.createCqrsConfigFile = exports.createCommandIndexFile = exports.createCommandFiles = void 0;
+const path_1 = __importDefault(require("path"));
+const naming_1 = require("../../templates/naming");
+function createCommandFiles(plan) {
+    const commandNames = (0, naming_1.createNameVariants)(plan.name);
+    const featureNames = (0, naming_1.createNameVariants)(plan.feature);
+    const root = path_1.default.posix.join(plan.featuresRoot, featureNames.kebabName, "application", "commands");
+    return [
+        {
+            path: `${root}/${commandNames.kebabName}.command.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createCommandTs(commandNames.pascalName),
+        },
+        {
+            path: `${root}/${commandNames.kebabName}.handler.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createCommandHandlerTs(commandNames.pascalName, commandNames.kebabName),
+        },
+        {
+            path: `${root}/${commandNames.kebabName}.handler.spec.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createCommandHandlerSpecTs(commandNames.pascalName, commandNames.kebabName),
+        },
+    ];
+}
+exports.createCommandFiles = createCommandFiles;
+function createCommandIndexFile(feature, featuresRoot, commandNames) {
+    const featureNames = (0, naming_1.createNameVariants)(feature);
+    const uniqueCommandNames = Array.from(new Set(commandNames)).sort();
+    const exports = uniqueCommandNames
+        .flatMap((commandName) => {
+        const names = (0, naming_1.createNameVariants)(commandName);
+        return [
+            `export * from './${names.kebabName}.command';`,
+            `export * from './${names.kebabName}.handler';`,
+        ];
+    })
+        .join("\n");
+    return {
+        path: path_1.default.posix.join(featuresRoot, featureNames.kebabName, "application", "commands", "index.ts"),
+        type: "config",
+        owner: featureNames.kebabName,
+        content: `${exports}
+`,
+    };
+}
+exports.createCommandIndexFile = createCommandIndexFile;
+function createCqrsConfigFile(featuresRoot, importsByKind) {
+    const normalized = Array.isArray(importsByKind)
+        ? { commands: importsByKind, queries: [] }
+        : { commands: importsByKind.commands, queries: importsByKind.queries ?? [] };
+    const importLines = [
+        ...Array.from(new Set(normalized.commands)).sort()
+            .map((feature) => `import '../${featuresRoot.replace(/^src\//, "")}/${feature}/application/commands';`),
+        ...Array.from(new Set(normalized.queries)).sort()
+            .map((feature) => `import '../${featuresRoot.replace(/^src\//, "")}/${feature}/application/queries';`),
+    ]
+        .join("\n");
+    return {
+        path: "src/config/cqrs.ts",
+        type: "config",
+        content: importLines
+            ? `${importLines}
+
+export {};
+`
+            : `// Generated CQRS handler imports. Updated by soap add command/query.
+export {};
+`,
+    };
+}
+exports.createCqrsConfigFile = createCqrsConfigFile;
+function commandNameFromPath(filePath) {
+    const match = filePath.match(/\/application\/commands\/([^/]+)\.command\.ts$/);
+    return match?.[1];
+}
+exports.commandNameFromPath = commandNameFromPath;
+function commandFeatureFromPath(filePath, featuresRoot) {
+    const escapedRoot = featuresRoot.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = filePath.match(new RegExp(`^${escapedRoot}/([^/]+)/application/commands/index\\.ts$`));
+    return match?.[1];
+}
+exports.commandFeatureFromPath = commandFeatureFromPath;
+function createCommandTs(className) {
+    return `import { BaseCommand } from '@soapjs/soap/cqrs';
+
+export interface ${className}Payload {
+  [key: string]: unknown;
+}
+
+export interface ${className}Result {
+  [key: string]: unknown;
+}
+
+export class ${className}Command extends BaseCommand<${className}Result> {
+  constructor(
+    public readonly payload: ${className}Payload = {},
+    initiatedBy?: string,
+    correlationId?: string
+  ) {
+    super(initiatedBy, correlationId);
+  }
+}
+`;
+}
+function createCommandHandlerTs(className, kebabName) {
+    return `import { Result } from '@soapjs/soap';
+import { CommandHandler as SoapCommandHandler } from '@soapjs/soap/cqrs';
+import { CommandHandler } from '@soapjs/soap-express/cqrs';
+import { ${className}Command, ${className}Result } from './${kebabName}.command';
+
+export interface ${className}Repository {
+  save(command: ${className}Command): Promise<${className}Result> | ${className}Result;
+}
+
+@CommandHandler(${className}Command)
+export class ${className}Handler implements SoapCommandHandler<${className}Command, ${className}Result> {
+  constructor(private readonly repository?: ${className}Repository) {}
+
+  async handle(command: ${className}Command): Promise<Result<${className}Result>> {
+    try {
+      const output = this.repository
+        ? await this.repository.save(command)
+        : ({ ...command.payload } as ${className}Result);
+
+      return Result.withSuccess(output);
+    } catch (error) {
+      return Result.withFailure(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+}
+`;
+}
+function createCommandHandlerSpecTs(className, kebabName) {
+    return `import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Result } from '@soapjs/soap';
+import { InMemoryCommandBus } from '@soapjs/soap/cqrs';
+import { ${className}Command, ${className}Result } from './${kebabName}.command';
+import { ${className}Handler, ${className}Repository } from './${kebabName}.handler';
+
+test('${className}Handler returns a successful Result from a repository port', async () => {
+  const repository: ${className}Repository = {
+    async save(command) {
+      return {
+        id: 'generated-id',
+        ...command.payload,
+      };
+    },
+  };
+  const handler = new ${className}Handler(repository);
+
+  const result = await handler.handle(new ${className}Command({ name: 'Ada' }));
+
+  assert.equal(result.isSuccess(), true);
+  assert.deepEqual(result.content, {
+    id: 'generated-id',
+    name: 'Ada',
+  });
+});
+
+test('${className}Command can be dispatched through a CQRS command bus', async () => {
+  const bus = new InMemoryCommandBus();
+  bus.register(${className}Command, new ${className}Handler());
+
+  const result: Result<${className}Result> = await bus.dispatch(new ${className}Command({ name: 'Ada' }));
+
+  assert.equal(result.isSuccess(), true);
+  assert.deepEqual(result.content, {
+    name: 'Ada',
+  });
+});
+`;
+}

package/build/commands/add/entity-plan.d.ts

@@ -0,0 +1,7 @@
+import { PlannedFile } from "../../io/file-writer";
+export interface AddEntityPlan {
+    name: string;
+    feature: string;
+    featuresRoot: string;
+}
+export declare function createEntityFiles(plan: AddEntityPlan): PlannedFile[];

package/build/commands/add/entity-plan.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntityFiles = void 0;
+const path_1 = __importDefault(require("path"));
+const naming_1 = require("../../templates/naming");
+function createEntityFiles(plan) {
+    const entityNames = (0, naming_1.createNameVariants)(plan.name);
+    const featureNames = (0, naming_1.createNameVariants)(plan.feature);
+    const root = path_1.default.posix.join(plan.featuresRoot, featureNames.kebabName, "domain");
+    return [
+        {
+            path: `${root}/${entityNames.kebabName}.entity.ts`,
+            type: "entity",
+            owner: featureNames.kebabName,
+            content: createEntityTs(entityNames.pascalName),
+        },
+        {
+            path: `${root}/${entityNames.kebabName}.entity.spec.ts`,
+            type: "entity",
+            owner: featureNames.kebabName,
+            content: createEntitySpecTs(entityNames.pascalName, entityNames.kebabName),
+        },
+    ];
+}
+exports.createEntityFiles = createEntityFiles;
+function createEntityTs(className) {
+    return `import { randomUUID } from 'crypto';
+
+export interface ${className}Props {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export class Invalid${className}Error extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'Invalid${className}Error';
+  }
+}
+
+export class ${className} {
+  private constructor(public readonly props: ${className}Props) {}
+
+  static create(input: Partial<Pick<${className}Props, 'id' | 'createdAt' | 'updatedAt'>> = {}): ${className} {
+    const now = new Date().toISOString();
+    const props: ${className}Props = {
+      id: input.id ?? randomUUID(),
+      createdAt: input.createdAt ?? now,
+      updatedAt: input.updatedAt ?? now,
+    };
+
+    ${className}.validate(props);
+    return new ${className}(props);
+  }
+
+  static rehydrate(props: ${className}Props): ${className} {
+    ${className}.validate(props);
+    return new ${className}(props);
+  }
+
+  get id(): string {
+    return this.props.id;
+  }
+
+  private static validate(props: ${className}Props): void {
+    if (!props.id) {
+      throw new Invalid${className}Error('${className} id is required.');
+    }
+
+    if (!props.createdAt || !props.updatedAt) {
+      throw new Invalid${className}Error('${className} timestamps are required.');
+    }
+  }
+}
+`;
+}
+function createEntitySpecTs(className, kebabName) {
+    return `import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Invalid${className}Error, ${className} } from './${kebabName}.entity';
+
+test('${className}.create generates identity and timestamps', () => {
+  const entity = ${className}.create();
+
+  assert.ok(entity.id);
+  assert.ok(entity.props.createdAt);
+  assert.ok(entity.props.updatedAt);
+});
+
+test('${className}.rehydrate rejects invalid props', () => {
+  assert.throws(
+    () =>
+      ${className}.rehydrate({
+        id: '',
+        createdAt: '',
+        updatedAt: '',
+      }),
+    Invalid${className}Error
+  );
+});
+`;
+}

package/build/commands/add/event-plan.d.ts

@@ -0,0 +1,8 @@
+import { PlannedFile } from "../../io/file-writer";
+export interface AddEventPlan {
+    name: string;
+    feature: string;
+    architecture: "regular" | "cqrs";
+    featuresRoot: string;
+}
+export declare function createEventFiles(plan: AddEventPlan): PlannedFile[];

package/build/commands/add/event-plan.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventFiles = void 0;
+const path_1 = __importDefault(require("path"));
+const naming_1 = require("../../templates/naming");
+function createEventFiles(plan) {
+    const eventNames = (0, naming_1.createNameVariants)(plan.name);
+    const featureNames = (0, naming_1.createNameVariants)(plan.feature);
+    const root = path_1.default.posix.join(plan.featuresRoot, featureNames.kebabName);
+    const files = [
+        {
+            path: `${root}/domain/events/${eventNames.kebabName}.event.ts`,
+            type: "resource",
+            owner: featureNames.kebabName,
+            content: createEventTs(eventNames.pascalName, eventNames.kebabName),
+        },
+    ];
+    if (plan.architecture === "cqrs") {
+        files.push({
+            path: `${root}/api/events/${eventNames.kebabName}.handler.ts`,
+            type: "resource",
+            owner: featureNames.kebabName,
+            content: createEventHandlerTs(eventNames.pascalName, eventNames.kebabName),
+        });
+    }
+    return files;
+}
+exports.createEventFiles = createEventFiles;
+function createEventTs(className, eventName) {
+    return `import { BaseDomainEvent } from '../../../../common/events/domain-event';
+
+export interface ${className}Data {
+  [key: string]: unknown;
+}
+
+export class ${className}Event extends BaseDomainEvent<${className}Data> {
+  static readonly type = '${eventName}';
+
+  constructor(aggregateId: string, data: ${className}Data = {}, version = 1) {
+    super(${className}Event.type, aggregateId, data, version);
+  }
+}
+`;
+}
+function createEventHandlerTs(className, eventName) {
+    return `import { EventHandler } from '@soapjs/soap-express/build/decorators/event';
+import { ${className}Event } from '../../domain/events/${eventName}.event';
+
+@EventHandler(${className}Event)
+export class ${className}Handler {
+  async handle(event: ${className}Event): Promise<void> {
+    void event;
+  }
+}
+`;
+}

package/build/commands/add/query-plan.d.ts

@@ -0,0 +1,10 @@
+import { PlannedFile } from "../../io/file-writer";
+export interface AddQueryPlan {
+    name: string;
+    feature: string;
+    featuresRoot: string;
+}
+export declare function createQueryFiles(plan: AddQueryPlan): PlannedFile[];
+export declare function createQueryIndexFile(feature: string, featuresRoot: string, queryNames: string[]): PlannedFile;
+export declare function queryNameFromPath(filePath: string): string | undefined;
+export declare function queryFeatureFromPath(filePath: string, featuresRoot: string): string | undefined;

package/build/commands/add/query-plan.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryFeatureFromPath = exports.queryNameFromPath = exports.createQueryIndexFile = exports.createQueryFiles = void 0;
+const path_1 = __importDefault(require("path"));
+const naming_1 = require("../../templates/naming");
+function createQueryFiles(plan) {
+    const queryNames = (0, naming_1.createNameVariants)(plan.name);
+    const featureNames = (0, naming_1.createNameVariants)(plan.feature);
+    const root = path_1.default.posix.join(plan.featuresRoot, featureNames.kebabName, "application", "queries");
+    return [
+        {
+            path: `${root}/${queryNames.kebabName}.query.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createQueryTs(queryNames.pascalName),
+        },
+        {
+            path: `${root}/${queryNames.kebabName}.handler.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createQueryHandlerTs(queryNames.pascalName, queryNames.kebabName),
+        },
+        {
+            path: `${root}/${queryNames.kebabName}.handler.spec.ts`,
+            type: "use-case",
+            owner: featureNames.kebabName,
+            content: createQueryHandlerSpecTs(queryNames.pascalName, queryNames.kebabName),
+        },
+    ];
+}
+exports.createQueryFiles = createQueryFiles;
+function createQueryIndexFile(feature, featuresRoot, queryNames) {
+    const featureNames = (0, naming_1.createNameVariants)(feature);
+    const uniqueQueryNames = Array.from(new Set(queryNames)).sort();
+    const exports = uniqueQueryNames
+        .flatMap((queryName) => {
+        const names = (0, naming_1.createNameVariants)(queryName);
+        return [
+            `export * from './${names.kebabName}.query';`,
+            `export * from './${names.kebabName}.handler';`,
+        ];
+    })
+        .join("\n");
+    return {
+        path: path_1.default.posix.join(featuresRoot, featureNames.kebabName, "application", "queries", "index.ts"),
+        type: "config",
+        owner: featureNames.kebabName,
+        content: `${exports}
+`,
+    };
+}
+exports.createQueryIndexFile = createQueryIndexFile;
+function queryNameFromPath(filePath) {
+    const match = filePath.match(/\/application\/queries\/([^/]+)\.query\.ts$/);
+    return match?.[1];
+}
+exports.queryNameFromPath = queryNameFromPath;
+function queryFeatureFromPath(filePath, featuresRoot) {
+    const escapedRoot = featuresRoot.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = filePath.match(new RegExp(`^${escapedRoot}/([^/]+)/application/queries/index\\.ts$`));
+    return match?.[1];
+}
+exports.queryFeatureFromPath = queryFeatureFromPath;
+function createQueryTs(className) {
+    return `import { BaseQuery } from '@soapjs/soap/cqrs';
+
+export interface ${className}Criteria {
+  [key: string]: unknown;
+}
+
+export interface ${className}Result {
+  [key: string]: unknown;
+}
+
+export class ${className}Query extends BaseQuery<${className}Result> {
+  constructor(
+    public readonly criteria: ${className}Criteria = {},
+    initiatedBy?: string,
+    correlationId?: string
+  ) {
+    super(initiatedBy, correlationId);
+  }
+}
+`;
+}
+function createQueryHandlerTs(className, kebabName) {
+    return `import { Result } from '@soapjs/soap';
+import { QueryHandler as SoapQueryHandler } from '@soapjs/soap/cqrs';
+import { QueryHandler } from '@soapjs/soap-express/cqrs';
+import { ${className}Query, ${className}Result } from './${kebabName}.query';
+
+export interface ${className}Repository {
+  find(query: ${className}Query): Promise<${className}Result> | ${className}Result;
+}
+
+@QueryHandler(${className}Query)
+export class ${className}Handler implements SoapQueryHandler<${className}Query, ${className}Result> {
+  constructor(private readonly repository?: ${className}Repository) {}
+
+  async handle(query: ${className}Query): Promise<Result<${className}Result>> {
+    try {
+      const output = this.repository
+        ? await this.repository.find(query)
+        : ({ ...query.criteria } as ${className}Result);
+
+      return Result.withSuccess(output);
+    } catch (error) {
+      return Result.withFailure(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+}
+`;
+}
+function createQueryHandlerSpecTs(className, kebabName) {
+    return `import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Result } from '@soapjs/soap';
+import { InMemoryQueryBus } from '@soapjs/soap/cqrs';
+import { ${className}Query, ${className}Result } from './${kebabName}.query';
+import { ${className}Handler, ${className}Repository } from './${kebabName}.handler';
+
+test('${className}Handler returns a successful Result from a repository port', async () => {
+  const repository: ${className}Repository = {
+    async find(query) {
+      return {
+        id: 'existing-id',
+        ...query.criteria,
+      };
+    },
+  };
+  const handler = new ${className}Handler(repository);
+
+  const result = await handler.handle(new ${className}Query({ id: 'existing-id' }));
+
+  assert.equal(result.isSuccess(), true);
+  assert.deepEqual(result.content, {
+    id: 'existing-id',
+  });
+});
+
+test('${className}Query can be dispatched through a CQRS query bus', async () => {
+  const bus = new InMemoryQueryBus();
+  bus.register(${className}Query, new ${className}Handler());
+
+  const result: Result<${className}Result> = await bus.dispatch(new ${className}Query({ id: 'existing-id' }));
+
+  assert.equal(result.isSuccess(), true);
+  assert.deepEqual(result.content, {
+    id: 'existing-id',
+  });
+});
+`;
+}

package/build/commands/add/repository-plan.d.ts

@@ -0,0 +1,11 @@
+import { DatabaseCapability } from "../../config/schemas/types";
+import { PlannedFile } from "../../io/file-writer";
+type RepositoryDb = Extract<DatabaseCapability, "mongo" | "postgres" | "mysql" | "sqlite">;
+export interface AddRepositoryPlan {
+    name: string;
+    feature: string;
+    db: RepositoryDb;
+    featuresRoot: string;
+}
+export declare function createRepositoryFiles(plan: AddRepositoryPlan): PlannedFile[];
+export {};