@living-architecture/riviere-cli 0.2.1

package/README.md

@@ -0,0 +1,11 @@
+# cli
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build cli` to build the library.
+
+## Running unit tests
+
+Run `nx test cli` to execute the unit tests via [Vitest](https://vitest.dev/).

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+interface PackageJson {
+    version: string;
+}
+export declare function parsePackageJson(pkg: unknown): PackageJson;
+export declare function createProgram(): Command;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAQ1D;AASD,wBAAgB,aAAa,IAAI,OAAO,CAmCvC"}

package/dist/cli.js

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { createAddComponentCommand } from './commands/builder/add-component';
+import { createAddDomainCommand } from './commands/builder/add-domain';
+import { createAddSourceCommand } from './commands/builder/add-source';
+import { createInitCommand } from './commands/builder/init';
+import { createLinkCommand } from './commands/builder/link';
+import { createLinkExternalCommand } from './commands/builder/link-external';
+import { createLinkHttpCommand } from './commands/builder/link-http';
+import { createValidateCommand } from './commands/builder/validate';
+import { createFinalizeCommand } from './commands/builder/finalize';
+import { createEnrichCommand } from './commands/builder/enrich';
+import { createComponentSummaryCommand } from './commands/builder/component-summary';
+import { createComponentChecklistCommand } from './commands/builder/component-checklist';
+import { createCheckConsistencyCommand } from './commands/builder/check-consistency';
+import { createEntryPointsCommand } from './commands/query/entry-points';
+import { createDomainsCommand } from './commands/query/domains';
+import { createTraceCommand } from './commands/query/trace';
+import { createOrphansCommand } from './commands/query/orphans';
+import { createComponentsCommand } from './commands/query/components';
+import { createSearchCommand } from './commands/query/search';
+export function parsePackageJson(pkg) {
+    if (typeof pkg !== 'object' || pkg === null || !('version' in pkg)) {
+        throw new Error('Invalid package.json: missing version field');
+    }
+    if (typeof pkg.version !== 'string') {
+        throw new Error('Invalid package.json: version must be a string');
+    }
+    return { version: pkg.version };
+}
+function loadPackageJson() {
+    const require = createRequire(import.meta.url);
+    return parsePackageJson(require('../package.json'));
+}
+const packageJson = loadPackageJson();
+export function createProgram() {
+    const program = new Command();
+    program.name('riviere').version(packageJson.version);
+    const builderCmd = program
+        .command('builder')
+        .description('Commands for building a graph');
+    builderCmd.addCommand(createAddComponentCommand());
+    builderCmd.addCommand(createAddDomainCommand());
+    builderCmd.addCommand(createAddSourceCommand());
+    builderCmd.addCommand(createInitCommand());
+    builderCmd.addCommand(createLinkCommand());
+    builderCmd.addCommand(createLinkExternalCommand());
+    builderCmd.addCommand(createLinkHttpCommand());
+    builderCmd.addCommand(createValidateCommand());
+    builderCmd.addCommand(createFinalizeCommand());
+    builderCmd.addCommand(createEnrichCommand());
+    builderCmd.addCommand(createComponentSummaryCommand());
+    builderCmd.addCommand(createComponentChecklistCommand());
+    builderCmd.addCommand(createCheckConsistencyCommand());
+    const queryCmd = program
+        .command('query')
+        .description('Commands for querying a graph');
+    queryCmd.addCommand(createEntryPointsCommand());
+    queryCmd.addCommand(createDomainsCommand());
+    queryCmd.addCommand(createTraceCommand());
+    queryCmd.addCommand(createOrphansCommand());
+    queryCmd.addCommand(createComponentsCommand());
+    queryCmd.addCommand(createSearchCommand());
+    return program;
+}

package/dist/command-test-fixtures.d.ts

@@ -0,0 +1,110 @@
+export interface ErrorOutput {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        suggestions: string[];
+    };
+}
+export declare function isErrorOutput(value: unknown): value is ErrorOutput;
+export declare function parseErrorOutput(consoleOutput: string[]): ErrorOutput;
+export declare function parseSuccessOutput<T>(consoleOutput: string[], guard: (value: unknown) => value is T, errorMessage: string): T;
+export interface TestContext {
+    testDir: string;
+    originalCwd: string;
+    consoleOutput: string[];
+}
+export declare function createTestContext(): TestContext;
+export declare function setupCommandTest(ctx: TestContext): void;
+export declare function createGraph(testDir: string, graphData: object, subPath?: string): Promise<string>;
+export declare const baseMetadata: {
+    sources: {
+        repository: string;
+    }[];
+    domains: {
+        orders: {
+            description: string;
+            systemType: string;
+        };
+    };
+};
+export declare const sourceLocation: {
+    repository: string;
+    filePath: string;
+};
+export declare const useCaseComponent: {
+    id: string;
+    type: string;
+    name: string;
+    domain: string;
+    module: string;
+    sourceLocation: {
+        repository: string;
+        filePath: string;
+    };
+};
+export declare const apiComponent: {
+    id: string;
+    type: string;
+    name: string;
+    domain: string;
+    module: string;
+    sourceLocation: {
+        repository: string;
+        filePath: string;
+    };
+    apiType: string;
+    httpMethod: string;
+    path: string;
+};
+export declare const eventHandlerComponent: {
+    id: string;
+    type: string;
+    name: string;
+    domain: string;
+    module: string;
+    sourceLocation: {
+        repository: string;
+        filePath: string;
+    };
+    subscribedEvents: string[];
+};
+export declare const validLink: {
+    id: string;
+    source: string;
+    target: string;
+    type: string;
+};
+export declare function createGraphWithDomain(testDir: string, domainName: string): Promise<void>;
+export declare function createGraphWithSource(testDir: string, repository: string): Promise<void>;
+export declare function createGraphWithComponent(testDir: string, component: object): Promise<void>;
+export declare const domainOpComponent: {
+    id: string;
+    type: string;
+    name: string;
+    domain: string;
+    module: string;
+    operationName: string;
+    sourceLocation: {
+        repository: string;
+        filePath: string;
+    };
+};
+export declare const simpleUseCaseComponent: {
+    id: string;
+    type: string;
+    name: string;
+    domain: string;
+    module: string;
+    sourceLocation: {
+        repository: string;
+        filePath: string;
+    };
+};
+export declare function hasSuccessOutputStructure(value: unknown): value is {
+    success: true;
+    data: object;
+};
+export declare function testCommandRegistration(commandName: string): void;
+export declare function testCustomGraphPath<T>(ctx: TestContext, commandArgs: string[], parseOutput: (consoleOutput: string[]) => T): Promise<T>;
+//# sourceMappingURL=command-test-fixtures.d.ts.map

package/dist/command-test-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-test-fixtures.d.ts","sourceRoot":"","sources":["../src/command-test-fixtures.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;CACH;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAKlE;AAED,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,WAAW,CAUrE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,aAAa,EAAE,MAAM,EAAE,EACvB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EACrC,YAAY,EAAE,MAAM,GACnB,CAAC,CAUH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAM/C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAcvD;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,SAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAM3G;AAED,eAAO,MAAM,YAAY;;;;;;;;;;CAGxB,CAAC;AAEF,eAAO,MAAM,cAAc;;;CAAmF,CAAC;AAE/G,eAAO,MAAM,gBAAgB;;;;;;;;;;CAO5B,CAAC;AAEF,eAAO,MAAM,YAAY;;;;;;;;;;;;;CAUxB,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;CAQjC,CAAC;AAEF,eAAO,MAAM,SAAS;;;;;CAKrB,CAAC;AAEF,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9F;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9F;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAahG;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;CAQ7B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;CAOlC,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAKlG;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAOjE;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/command-test-fixtures.js

@@ -0,0 +1,184 @@
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { vi, beforeEach, afterEach, expect, it } from 'vitest';
+import { createProgram } from './cli';
+export function isErrorOutput(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('success' in value) || value.success !== false)
+        return false;
+    if (!('error' in value) || typeof value.error !== 'object' || value.error === null)
+        return false;
+    return true;
+}
+export function parseErrorOutput(consoleOutput) {
+    const firstLine = consoleOutput[0];
+    if (firstLine === undefined) {
+        throw new Error('Expected console output but got empty array');
+    }
+    const parsed = JSON.parse(firstLine);
+    if (!isErrorOutput(parsed)) {
+        throw new Error('Invalid error output');
+    }
+    return parsed;
+}
+export function parseSuccessOutput(consoleOutput, guard, errorMessage) {
+    const firstLine = consoleOutput[0];
+    if (firstLine === undefined) {
+        throw new Error('Expected console output but got empty array');
+    }
+    const parsed = JSON.parse(firstLine);
+    if (!guard(parsed)) {
+        throw new Error(errorMessage);
+    }
+    return parsed;
+}
+export function createTestContext() {
+    return {
+        testDir: '',
+        originalCwd: '',
+        consoleOutput: [],
+    };
+}
+export function setupCommandTest(ctx) {
+    beforeEach(async () => {
+        ctx.testDir = await mkdtemp(join(tmpdir(), 'riviere-test-'));
+        ctx.originalCwd = process.cwd();
+        ctx.consoleOutput = [];
+        process.chdir(ctx.testDir);
+        vi.spyOn(console, 'log').mockImplementation((msg) => ctx.consoleOutput.push(msg));
+    });
+    afterEach(async () => {
+        vi.restoreAllMocks();
+        process.chdir(ctx.originalCwd);
+        await rm(ctx.testDir, { recursive: true });
+    });
+}
+export async function createGraph(testDir, graphData, subPath = '.riviere') {
+    const graphDir = join(testDir, subPath);
+    await mkdir(graphDir, { recursive: true });
+    const graphPath = join(graphDir, 'graph.json');
+    await writeFile(graphPath, JSON.stringify(graphData), 'utf-8');
+    return graphPath;
+}
+export const baseMetadata = {
+    sources: [{ repository: 'https://github.com/org/repo' }],
+    domains: { orders: { description: 'Order management', systemType: 'domain' } },
+};
+export const sourceLocation = { repository: 'https://github.com/org/repo', filePath: 'src/orders/handler.ts' };
+export const useCaseComponent = {
+    id: 'orders:checkout:usecase:place-order',
+    type: 'UseCase',
+    name: 'place-order',
+    domain: 'orders',
+    module: 'checkout',
+    sourceLocation,
+};
+export const apiComponent = {
+    id: 'orders:checkout:api:place-order',
+    type: 'API',
+    name: 'place-order',
+    domain: 'orders',
+    module: 'checkout',
+    sourceLocation,
+    apiType: 'REST',
+    httpMethod: 'POST',
+    path: '/orders',
+};
+export const eventHandlerComponent = {
+    id: 'orders:checkout:eventhandler:on-order-placed',
+    type: 'EventHandler',
+    name: 'on-order-placed',
+    domain: 'orders',
+    module: 'checkout',
+    sourceLocation,
+    subscribedEvents: ['OrderPlaced'],
+};
+export const validLink = {
+    id: 'orders:checkout:api:place-order→orders:checkout:usecase:place-order:sync',
+    source: 'orders:checkout:api:place-order',
+    target: 'orders:checkout:usecase:place-order',
+    type: 'sync',
+};
+export async function createGraphWithDomain(testDir, domainName) {
+    const graphDir = join(testDir, '.riviere');
+    await mkdir(graphDir, { recursive: true });
+    const graph = {
+        version: '1.0',
+        metadata: {
+            sources: [{ repository: 'https://github.com/org/repo' }],
+            domains: { [domainName]: { description: 'Test domain', systemType: 'domain' } },
+        },
+        components: [],
+        links: [],
+    };
+    await writeFile(join(graphDir, 'graph.json'), JSON.stringify(graph), 'utf-8');
+}
+export async function createGraphWithSource(testDir, repository) {
+    const graphDir = join(testDir, '.riviere');
+    await mkdir(graphDir, { recursive: true });
+    const graph = {
+        version: '1.0',
+        metadata: {
+            sources: [{ repository }],
+            domains: { orders: { description: 'Orders', systemType: 'domain' } },
+        },
+        components: [],
+        links: [],
+    };
+    await writeFile(join(graphDir, 'graph.json'), JSON.stringify(graph), 'utf-8');
+}
+export async function createGraphWithComponent(testDir, component) {
+    const graphDir = join(testDir, '.riviere');
+    await mkdir(graphDir, { recursive: true });
+    const graph = {
+        version: '1.0',
+        metadata: {
+            sources: [{ repository: 'https://github.com/org/repo' }],
+            domains: { orders: { description: 'Order management', systemType: 'domain' } },
+        },
+        components: [component],
+        links: [],
+    };
+    await writeFile(join(graphDir, 'graph.json'), JSON.stringify(graph), 'utf-8');
+}
+export const domainOpComponent = {
+    id: 'orders:checkout:domainop:confirm-order',
+    type: 'DomainOp',
+    name: 'Confirm Order',
+    domain: 'orders',
+    module: 'checkout',
+    operationName: 'confirmOrder',
+    sourceLocation: { repository: 'https://github.com/org/repo', filePath: 'src/domain.ts' },
+};
+export const simpleUseCaseComponent = {
+    id: 'orders:checkout:usecase:place-order',
+    type: 'UseCase',
+    name: 'Place Order',
+    domain: 'orders',
+    module: 'checkout',
+    sourceLocation: { repository: 'https://github.com/org/repo', filePath: 'src/usecase.ts' },
+};
+export function hasSuccessOutputStructure(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('success' in value) || value.success !== true)
+        return false;
+    if (!('data' in value) || typeof value.data !== 'object' || value.data === null)
+        return false;
+    return true;
+}
+export function testCommandRegistration(commandName) {
+    it(`registers ${commandName} command under builder`, () => {
+        const program = createProgram();
+        const builderCmd = program.commands.find((cmd) => cmd.name() === 'builder');
+        const cmd = builderCmd?.commands.find((cmd) => cmd.name() === commandName);
+        expect(cmd?.name()).toBe(commandName);
+    });
+}
+export async function testCustomGraphPath(ctx, commandArgs, parseOutput) {
+    const customPath = await createGraph(ctx.testDir, { version: '1.0', metadata: baseMetadata, components: [], links: [] }, 'custom');
+    await createProgram().parseAsync(['node', 'riviere', ...commandArgs, '--graph', customPath, '--json']);
+    return parseOutput(ctx.consoleOutput);
+}

package/dist/commands/builder/add-component.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+export declare function getErrorMessage(error: unknown): string;
+export declare function createAddComponentCommand(): Command;
+//# sourceMappingURL=add-component.d.ts.map

package/dist/commands/builder/add-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-component.d.ts","sourceRoot":"","sources":["../../../src/commands/builder/add-component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKtD;AAyKD,wBAAgB,yBAAyB,IAAI,OAAO,CAkGnD"}

package/dist/commands/builder/add-component.js

@@ -0,0 +1,204 @@
+import { Command } from 'commander';
+import { readFile, writeFile } from 'node:fs/promises';
+import { CustomTypeNotFoundError, DomainNotFoundError, DuplicateComponentError, RiviereBuilder, } from '@living-architecture/riviere-builder';
+import { parseRiviereGraph } from '@living-architecture/riviere-schema';
+import { getDefaultGraphPathDescription, resolveGraphPath } from '../../graph-path';
+import { fileExists } from '../../file-existence';
+import { formatError, formatSuccess } from '../../output';
+import { CliErrorCode } from '../../error-codes';
+import { isValidComponentType, isValidApiType, VALID_COMPONENT_TYPES, } from '../../component-types';
+import { isValidHttpMethod } from '../../validation';
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return 'Unknown error';
+}
+function addUIComponent(builder, common, options) {
+    if (!options.route) {
+        throw new Error('--route is required for UI component');
+    }
+    const component = builder.addUI({ ...common, route: options.route });
+    return component.id;
+}
+function addAPIComponent(builder, common, options) {
+    if (!options.apiType || !isValidApiType(options.apiType)) {
+        throw new Error('--api-type is required for API component');
+    }
+    const input = {
+        ...common,
+        apiType: options.apiType,
+    };
+    if (options.httpMethod && isValidHttpMethod(options.httpMethod)) {
+        input.httpMethod = options.httpMethod;
+    }
+    if (options.httpPath) {
+        input.path = options.httpPath;
+    }
+    const component = builder.addApi(input);
+    return component.id;
+}
+function addUseCaseComponent(builder, common) {
+    const component = builder.addUseCase(common);
+    return component.id;
+}
+function addDomainOpComponent(builder, common, options) {
+    if (!options.operationName) {
+        throw new Error('--operation-name is required for DomainOp component');
+    }
+    const input = { ...common, operationName: options.operationName };
+    const component = options.entity
+        ? builder.addDomainOp({ ...input, entity: options.entity })
+        : builder.addDomainOp(input);
+    return component.id;
+}
+function addEventComponent(builder, common, options) {
+    if (!options.eventName) {
+        throw new Error('--event-name is required for Event component');
+    }
+    const component = builder.addEvent({ ...common, eventName: options.eventName });
+    return component.id;
+}
+function addEventHandlerComponent(builder, common, options) {
+    if (!options.subscribedEvents) {
+        throw new Error('--subscribed-events is required for EventHandler component');
+    }
+    const component = builder.addEventHandler({
+        ...common,
+        subscribedEvents: options.subscribedEvents
+            .split(',')
+            .map((e) => e.trim())
+            .filter((e) => e.length > 0),
+    });
+    return component.id;
+}
+const componentHandlers = {
+    UI: addUIComponent,
+    API: addAPIComponent,
+    UseCase: addUseCaseComponent,
+    DomainOp: addDomainOpComponent,
+    Event: addEventComponent,
+    EventHandler: addEventHandlerComponent,
+    Custom: (builder, common, options) => {
+        if (!options.customType) {
+            throw new Error('--custom-type is required for Custom component');
+        }
+        const component = builder.addCustom({ ...common, customTypeName: options.customType });
+        return component.id;
+    },
+};
+function addComponentToBuilder(builder, componentType, options, sourceLocation) {
+    const commonInput = {
+        name: options.name,
+        domain: options.domain,
+        module: options.module,
+        sourceLocation,
+        ...(options.description ? { description: options.description } : {}),
+    };
+    const handler = componentHandlers[componentType];
+    return handler(builder, commonInput, options);
+}
+function tryAddComponent(builder, componentType, options, sourceLocation) {
+    try {
+        return addComponentToBuilder(builder, componentType, options, sourceLocation);
+    }
+    catch (error) {
+        if (error instanceof DomainNotFoundError) {
+            console.log(JSON.stringify(formatError(CliErrorCode.DomainNotFound, error.message, ['Run riviere builder add-domain first'])));
+            return undefined;
+        }
+        if (error instanceof CustomTypeNotFoundError) {
+            console.log(JSON.stringify(formatError(CliErrorCode.CustomTypeNotFound, error.message, [
+                'Run riviere builder add-custom-type first',
+            ])));
+            return undefined;
+        }
+        if (error instanceof DuplicateComponentError) {
+            console.log(JSON.stringify(formatError(CliErrorCode.DuplicateComponent, error.message, [])));
+            return undefined;
+        }
+        const message = getErrorMessage(error);
+        console.log(JSON.stringify(formatError(CliErrorCode.ValidationError, message, [])));
+        return undefined;
+    }
+}
+export function createAddComponentCommand() {
+    return new Command('add-component')
+        .description('Add a component to the graph')
+        .addHelpText('after', `
+Examples:
+  # Add an API endpoint
+  $ riviere builder add-component --type API --name "place-order" \\
+      --domain orders --module api --repository ecommerce \\
+      --file-path src/api/orders.ts --api-type REST \\
+      --http-method POST --http-path /orders
+
+  # Add a UseCase
+  $ riviere builder add-component --type UseCase --name "place-order" \\
+      --domain orders --module checkout --repository ecommerce \\
+      --file-path src/usecases/PlaceOrder.ts
+
+  # Add a DomainOp
+  $ riviere builder add-component --type DomainOp --name "order-begin" \\
+      --domain orders --module domain --repository ecommerce \\
+      --file-path src/domain/Order.ts --entity Order --operation-name begin
+
+  # Add an Event
+  $ riviere builder add-component --type Event --name "order-placed" \\
+      --domain orders --module events --repository ecommerce \\
+      --file-path src/events/OrderPlaced.ts --event-name "order-placed"
+`)
+        .requiredOption('--type <type>', 'Component type (UI, API, UseCase, DomainOp, Event, EventHandler, Custom)')
+        .requiredOption('--name <name>', 'Component name')
+        .requiredOption('--domain <domain>', 'Domain name')
+        .requiredOption('--module <module>', 'Module name')
+        .requiredOption('--repository <url>', 'Source repository URL')
+        .requiredOption('--file-path <path>', 'Source file path')
+        .option('--route <route>', 'UI route path')
+        .option('--api-type <type>', 'API type (REST, GraphQL, other)')
+        .option('--http-method <method>', 'HTTP method')
+        .option('--http-path <path>', 'HTTP endpoint path')
+        .option('--operation-name <name>', 'Operation name (DomainOp)')
+        .option('--entity <entity>', 'Entity name (DomainOp)')
+        .option('--event-name <name>', 'Event name')
+        .option('--subscribed-events <events>', 'Comma-separated subscribed event names')
+        .option('--custom-type <name>', 'Custom type name')
+        .option('--description <desc>', 'Component description')
+        .option('--line-number <n>', 'Source line number')
+        .option('--graph <path>', getDefaultGraphPathDescription())
+        .option('--json', 'Output result as JSON')
+        .action(async (options) => {
+        if (!isValidComponentType(options.type)) {
+            console.log(JSON.stringify(formatError(CliErrorCode.ValidationError, `Invalid component type: ${options.type}`, [
+                `Valid types: ${VALID_COMPONENT_TYPES.join(', ')}`,
+            ])));
+            return;
+        }
+        const componentType = options.type;
+        const graphPath = resolveGraphPath(options.graph);
+        const graphExists = await fileExists(graphPath);
+        if (!graphExists) {
+            console.log(JSON.stringify(formatError(CliErrorCode.GraphNotFound, `Graph not found at ${graphPath}`, [
+                'Run riviere builder init first',
+            ])));
+            return;
+        }
+        const content = await readFile(graphPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        const graph = parseRiviereGraph(parsed);
+        const builder = RiviereBuilder.resume(graph);
+        const sourceLocation = {
+            repository: options.repository,
+            filePath: options.filePath,
+            ...(options.lineNumber ? { lineNumber: parseInt(options.lineNumber, 10) } : {}),
+        };
+        const componentId = tryAddComponent(builder, componentType, options, sourceLocation);
+        if (componentId === undefined) {
+            return;
+        }
+        await writeFile(graphPath, builder.serialize(), 'utf-8');
+        if (options.json) {
+            console.log(JSON.stringify(formatSuccess({ componentId })));
+        }
+    });
+}

package/dist/commands/builder/add-domain.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createAddDomainCommand(): Command;
+//# sourceMappingURL=add-domain.d.ts.map

package/dist/commands/builder/add-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-domain.d.ts","sourceRoot":"","sources":["../../../src/commands/builder/add-domain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBpC,wBAAgB,sBAAsB,IAAI,OAAO,CAoEhD"}

package/dist/commands/builder/add-domain.js

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { writeFile } from 'node:fs/promises';
+import { DuplicateDomainError } from '@living-architecture/riviere-builder';
+import { formatError, formatSuccess } from '../../output';
+import { CliErrorCode } from '../../error-codes';
+import { getDefaultGraphPathDescription } from '../../graph-path';
+import { isValidSystemType, VALID_SYSTEM_TYPES } from '../../component-types';
+import { withGraphBuilder } from './link-infrastructure';
+export function createAddDomainCommand() {
+    return new Command('add-domain')
+        .description('Add a domain to the graph')
+        .addHelpText('after', `
+Examples:
+  $ riviere builder add-domain --name orders --system-type domain \\
+      --description "Order management"
+
+  $ riviere builder add-domain --name checkout-bff --system-type bff \\
+      --description "Checkout backend-for-frontend"
+`)
+        .requiredOption('--name <name>', 'Domain name')
+        .requiredOption('--description <description>', 'Domain description')
+        .requiredOption('--system-type <type>', 'System type (domain, bff, ui, other)')
+        .option('--graph <path>', getDefaultGraphPathDescription())
+        .option('--json', 'Output result as JSON')
+        .action(async (options) => {
+        if (!isValidSystemType(options.systemType)) {
+            console.log(JSON.stringify(formatError(CliErrorCode.ValidationError, `Invalid system type: ${options.systemType}`, [`Valid types: ${VALID_SYSTEM_TYPES.join(', ')}`])));
+            return;
+        }
+        const systemType = options.systemType;
+        await withGraphBuilder(options.graph, async (builder, graphPath) => {
+            try {
+                builder.addDomain({
+                    name: options.name,
+                    description: options.description,
+                    systemType,
+                });
+            }
+            catch (error) {
+                if (error instanceof DuplicateDomainError) {
+                    console.log(JSON.stringify(formatError(CliErrorCode.DuplicateDomain, error.message, ['Use a different domain name'])));
+                    return;
+                }
+                throw error;
+            }
+            await writeFile(graphPath, builder.serialize(), 'utf-8');
+            if (options.json === true) {
+                console.log(JSON.stringify(formatSuccess({
+                    name: options.name,
+                    description: options.description,
+                    systemType: options.systemType,
+                })));
+            }
+        });
+    });
+}

package/dist/commands/builder/add-source.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createAddSourceCommand(): Command;
+//# sourceMappingURL=add-source.d.ts.map