Add AID export: OpenAPI from api-format and app generator bundle

Nest: POST /aid/export/openapi, POST /aid/export/app. Tools: api-format-to-openapi CLI. Generator: --print-bundle-json. Optional env: AID_EXPORT_API_KEY, AID_GENERATOR_ALLOW_APPLY.

server/src/aid-export/README.md

@@ -0,0 +1,85 @@
+# AID export: OpenAPI + генератор приложения
+
+HTTP-эндпоинты для интеграции с **AID** как **сервис-экспортёры**.
+
+---
+
+## 1. `api-format` → OpenAPI 3.0
+
+`POST /aid/export/openapi`
+
+Внутри: `tools/api-format-to-openapi/convert.mjs` (режимы `deterministic` и `llm`).
+
+**Тело:**
+
+```json
+{
+  "apiFormat": { "apiFormatVersion": "1", "...": "..." },
+  "mode": "deterministic"
+}
+```
+
+**Ответ:** `{ "openapi": { ... } }`
+
+---
+
+## 2. DSL → сгенерированное приложение (бандл или запись на диск)
+
+`POST /aid/export/app`
+
+Внутри: `generation/generate.mjs`.
+
+**Тело:**
+
+```json
+{
+  "dsl": "domain TOiR {\n  ...\n}\n",
+  "apply": false
+}
+```
+
+- **`apply` по умолчанию `false` (рекомендуется для AID):** ответ содержит `files` — карта **путь от корня репозитория → текст файла** (Prisma, Nest-модули, React Admin и обновлённые `app.module.ts` / `App.tsx`). **На диск ничего не пишется.**
+- **`apply: true`:** выполняется тот же процесс, что и `npm run generate:from-dsl` с `--apply` — **перезапись файлов в рабочей копии** на машине, где запущен Nest. Включено только если в окружении задано **`AID_GENERATOR_ALLOW_APPLY=1`** (или `true`). Иначе `403 Forbidden`.
+
+**Ответ (бандл):**
+
+```json
+{
+  "applied": false,
+  "entityCount": 3,
+  "enumCount": 3,
+  "files": {
+    "server/prisma/schema.prisma": "...",
+    "server/src/modules/equipment/equipment.controller.ts": "...",
+    "client/src/App.tsx": "..."
+  }
+}
+```
+
+**Ответ (apply):**
+
+```json
+{
+  "applied": true,
+  "message": "Generated 3 entities from ..."
+}
+```
+
+### CLI-аналог бандла (без Nest)
+
+Из **корня репозитория**:
+
+```bash
+node generation/generate.mjs --print-bundle-json --dsl examples/TOiR.domain.dsl > bundle.json
+```
+
+---
+
+## Безопасность
+
+- Если в `.env` задан **`AID_EXPORT_API_KEY`**, для **обоих** эндпоинтов нужен заголовок **`X-AID-Export-Key`** с тем же значением.
+- Не включайте **`AID_GENERATOR_ALLOW_APPLY`** на публичных инстансах без понимания рисков.
+
+## Требования
+
+- Запуск Nest с **cwd = `server/`** относительно корня репо, чтобы находились `../generation/generate.mjs` и `../tools/...`.

server/src/aid-export/aid-export.controller.ts

@@ -0,0 +1,112 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  ForbiddenException,
+  Headers,
+  HttpCode,
+  Post,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { AidExportService, OpenApiExportMode } from './aid-export.service';
+
+/**
+ * HTTP-экспортёры для AID: OpenAPI из api-format и генерация приложения из DSL.
+ */
+@Controller('aid/export')
+export class AidExportController {
+  constructor(
+    private readonly aidExport: AidExportService,
+    private readonly config: ConfigService,
+  ) {}
+
+  private assertExportKey(exportKey: string | undefined) {
+    const requiredKey = this.config.get<string>('AID_EXPORT_API_KEY');
+    if (requiredKey && exportKey !== requiredKey) {
+      throw new UnauthorizedException('Invalid or missing X-AID-Export-Key');
+    }
+  }
+
+  /**
+   * POST /aid/export/openapi
+   * Body: { "apiFormat": <объект api-format>, "mode"?: "deterministic" | "llm" }
+   * Response: { "openapi": <OpenAPI 3.0.3 document> }
+   *
+   * mode=llm требует OPENAI_API_KEY в окружении сервера.
+   *
+   * Если задан AID_EXPORT_API_KEY, клиент должен передать заголовок X-AID-Export-Key с тем же значением.
+   */
+  @Post('openapi')
+  @HttpCode(200)
+  async exportOpenApi(
+    @Body()
+    body: { apiFormat?: unknown; mode?: string },
+    @Headers('x-aid-export-key') exportKey?: string,
+  ) {
+    this.assertExportKey(exportKey);
+
+    if (body == null || typeof body !== 'object' || body.apiFormat == null) {
+      throw new BadRequestException('Body must be a JSON object with an "apiFormat" property');
+    }
+    if (typeof body.apiFormat !== 'object' || Array.isArray(body.apiFormat)) {
+      throw new BadRequestException('"apiFormat" must be a JSON object');
+    }
+
+    const mode: OpenApiExportMode =
+      body.mode === 'llm' ? 'llm' : 'deterministic';
+
+    const openapi = await this.aidExport.convertApiFormatToOpenApi(
+      body.apiFormat,
+      mode,
+    );
+    return { openapi };
+  }
+
+  /**
+   * POST /aid/export/app
+   * Body: { "dsl": "<текст DSL как в examples/TOiR.domain.dsl>", "apply"?: boolean }
+   *
+   * По умолчанию `apply: false` — возвращается JSON с полем `files` (пути относительно корня репо → содержимое),
+   * без записи на диск (безопасно для вызова из AID).
+   *
+   * `apply: true` перезаписывает файлы в **текущей** рабочей копии репозитория на машине, где крутится Nest.
+   * Разрешено только если в окружении задано `AID_GENERATOR_ALLOW_APPLY=1` (или `true`).
+   */
+  @Post('app')
+  @HttpCode(200)
+  async exportApp(
+    @Body()
+    body: { dsl?: string; apply?: boolean },
+    @Headers('x-aid-export-key') exportKey?: string,
+  ) {
+    this.assertExportKey(exportKey);
+
+    if (body == null || typeof body !== 'object') {
+      throw new BadRequestException('Body must be a JSON object');
+    }
+    if (typeof body.dsl !== 'string' || !body.dsl.trim()) {
+      throw new BadRequestException('Body must include a non-empty string "dsl"');
+    }
+
+    const apply = body.apply === true;
+    if (apply) {
+      const allow = this.config.get<string>('AID_GENERATOR_ALLOW_APPLY');
+      if (allow !== '1' && allow !== 'true') {
+        throw new ForbiddenException(
+          'apply=true is disabled. Set AID_GENERATOR_ALLOW_APPLY=1 on the server to allow writing generated files to disk.',
+        );
+      }
+      const { message } = await this.aidExport.generateAppApply(body.dsl);
+      return { applied: true, message };
+    }
+
+    const bundle = await this.aidExport.generateAppBundle(body.dsl);
+    return {
+      applied: false,
+      entityCount: bundle.entityCount,
+      enumCount: bundle.enumCount,
+      files: bundle.files,
+    };
+  }
+}

server/src/aid-export/aid-export.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { AidExportController } from './aid-export.controller';
+import { AidExportService } from './aid-export.service';
+
+@Module({
+  controllers: [AidExportController],
+  providers: [AidExportService],
+})
+export class AidExportModule {}

server/src/aid-export/aid-export.service.ts

@@ -0,0 +1,154 @@
+import { Injectable, InternalServerErrorException } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { execFile } from 'child_process';
+import { access, readFile, unlink, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+const LARGE_BUFFER = 64 * 1024 * 1024;
+
+export type OpenApiExportMode = 'deterministic' | 'llm';
+
+export type AppGeneratorBundle = {
+  entityCount: number;
+  enumCount: number;
+  files: Record<string, string>;
+};
+
+@Injectable()
+export class AidExportService {
+  /**
+   * Путь к tools/api-format-to-openapi/convert.mjs относительно cwd процесса (обычно каталог server/).
+   */
+  private resolveConvertScript(): string {
+    return join(process.cwd(), '..', 'tools', 'api-format-to-openapi', 'convert.mjs');
+  }
+
+  /** Путь к generation/generate.mjs относительно cwd = server/. */
+  private resolveGenerateScript(): string {
+    return join(process.cwd(), '..', 'generation', 'generate.mjs');
+  }
+
+  async convertApiFormatToOpenApi(
+    apiFormat: unknown,
+    mode: OpenApiExportMode,
+  ): Promise<Record<string, unknown>> {
+    const script = this.resolveConvertScript();
+    try {
+      await access(script);
+    } catch {
+      throw new InternalServerErrorException(
+        `Converter script not found at ${script}. Run the server with cwd = server/ from repo root.`,
+      );
+    }
+
+    const id = randomUUID();
+    const inPath = join(tmpdir(), `api-format-${id}.json`);
+    const outPath = join(tmpdir(), `openapi-${id}.json`);
+
+    try {
+      await writeFile(inPath, JSON.stringify(apiFormat), 'utf8');
+      const { stderr } = await execFileAsync(
+        process.execPath,
+        [script, '--in', inPath, '--out', outPath, '--mode', mode],
+        {
+          env: { ...process.env },
+          maxBuffer: 16 * 1024 * 1024,
+        },
+      );
+      if (stderr?.trim()) {
+        // convert.mjs пишет ошибки в stderr при падении; при успехе обычно пусто
+        console.warn('[aid-export]', stderr);
+      }
+      const raw = await readFile(outPath, 'utf8');
+      return JSON.parse(raw) as Record<string, unknown>;
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new InternalServerErrorException(`OpenAPI conversion failed: ${msg}`);
+    } finally {
+      await unlink(inPath).catch(() => undefined);
+      await unlink(outPath).catch(() => undefined);
+    }
+  }
+
+  /**
+   * DSL → снимок сгенерированных файлов (без записи в репозиторий).
+   * Использует `generation/generate.mjs --print-bundle-json`.
+   */
+  async generateAppBundle(dsl: string): Promise<AppGeneratorBundle> {
+    const script = this.resolveGenerateScript();
+    try {
+      await access(script);
+    } catch {
+      throw new InternalServerErrorException(
+        `Generator script not found at ${script}. Run the server with cwd = server/ from repo root.`,
+      );
+    }
+
+    const id = randomUUID();
+    const dslPath = join(tmpdir(), `domain-${id}.dsl`);
+
+    try {
+      await writeFile(dslPath, dsl, 'utf8');
+      const { stdout, stderr } = await execFileAsync(
+        process.execPath,
+        [script, '--print-bundle-json', '--dsl', dslPath],
+        {
+          env: { ...process.env },
+          maxBuffer: LARGE_BUFFER,
+        },
+      );
+      if (stderr?.trim()) console.warn('[aid-export][generate]', stderr);
+      const bundle = JSON.parse(stdout) as AppGeneratorBundle;
+      if (!bundle.files || typeof bundle.files !== 'object') {
+        throw new Error('Invalid bundle: missing files');
+      }
+      return bundle;
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new InternalServerErrorException(`App generator (bundle) failed: ${msg}`);
+    } finally {
+      await unlink(dslPath).catch(() => undefined);
+    }
+  }
+
+  /**
+   * DSL → запись сгенерированного кода в рабочую копию репозитория (`--apply`).
+   * Опасно для публичных эндпоинтов; включать только осознанно.
+   */
+  async generateAppApply(dsl: string): Promise<{ message: string }> {
+    const script = this.resolveGenerateScript();
+    try {
+      await access(script);
+    } catch {
+      throw new InternalServerErrorException(
+        `Generator script not found at ${script}. Run the server with cwd = server/ from repo root.`,
+      );
+    }
+
+    const id = randomUUID();
+    const dslPath = join(tmpdir(), `domain-${id}.dsl`);
+
+    try {
+      await writeFile(dslPath, dsl, 'utf8');
+      const { stdout, stderr } = await execFileAsync(
+        process.execPath,
+        [script, '--apply', '--dsl', dslPath],
+        {
+          env: { ...process.env },
+          maxBuffer: LARGE_BUFFER,
+        },
+      );
+      if (stderr?.trim()) console.warn('[aid-export][generate-apply]', stderr);
+      return { message: (stdout || 'ok').trim() };
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new InternalServerErrorException(`App generator (apply) failed: ${msg}`);
+    } finally {
+      await unlink(dslPath).catch(() => undefined);
+    }
+  }
+}

server/src/app.module.ts

@@ -5,11 +5,13 @@ import { HealthModule } from './health/health.module';
 import { EquipmentTypeModule } from './modules/equipment-type/equipment-type.module';
 import { EquipmentModule } from './modules/equipment/equipment.module';
 import { RepairOrderModule } from './modules/repair-order/repair-order.module';
+import { AidExportModule } from './aid-export/aid-export.module';
 
 @Module({
   imports: [ConfigModule.forRoot({ isGlobal: true }),
     PrismaModule,
     HealthModule,
+    AidExportModule,
     EquipmentTypeModule,
     EquipmentModule,
     RepairOrderModule,