kodu 2.1.2 → 2.2.0

package/src/core/registry/registry.service.ts

@@ -0,0 +1,128 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Injectable } from '@nestjs/common';
+import {
+  type ProjectEntry,
+  type Registry,
+  registrySchema,
+} from './registry.schema';
+
+/**
+ * Читает и пишет глобальный реестр проектов `~/.config/kodu/registry.json`
+ * (учитывает `$XDG_CONFIG_HOME`). Файл создаётся при первой записи — пока
+ * проектов нет, ничего в системе не создаётся.
+ */
+@Injectable()
+export class RegistryService {
+  private readonly dir = path.join(
+    process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), '.config'),
+    'kodu',
+  );
+  private readonly file = path.join(this.dir, 'registry.json');
+
+  /** Путь к файлу реестра (для подсказок пользователю). */
+  getFilePath(): string {
+    return this.file;
+  }
+
+  /** Загрузить реестр. Если файла ещё нет — вернуть пустой реестр. */
+  async load(): Promise<Registry> {
+    let raw: unknown;
+
+    try {
+      const content = await fs.readFile(this.file, 'utf8');
+      raw = JSON.parse(content);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return registrySchema.parse({});
+      }
+      throw new Error(
+        `Не удалось прочитать реестр ${this.file}: ${(error as Error).message}`,
+      );
+    }
+
+    const parsed = registrySchema.safeParse(raw);
+
+    if (!parsed.success) {
+      const issues = parsed.error.issues
+        .map(
+          (issue) => `- ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+        )
+        .join('\n');
+      throw new Error(`Реестр ${this.file} невалиден:\n${issues}`);
+    }
+
+    return parsed.data;
+  }
+
+  /** Сохранить реестр на диск (создаёт директорию при необходимости). */
+  async save(registry: Registry): Promise<void> {
+    const validated = registrySchema.parse(registry);
+    await fs.mkdir(this.dir, { recursive: true });
+    await fs.writeFile(
+      this.file,
+      `${JSON.stringify(validated, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  async list(): Promise<Registry['projects']> {
+    return (await this.load()).projects;
+  }
+
+  async get(name: string): Promise<ProjectEntry | undefined> {
+    return (await this.load()).projects[name];
+  }
+
+  async has(name: string): Promise<boolean> {
+    return Boolean(await this.get(name));
+  }
+
+  /** Добавить проект. По умолчанию запрещает перезапись существующего имени. */
+  async add(
+    name: string,
+    entry: ProjectEntry,
+    options: { overwrite?: boolean } = {},
+  ): Promise<void> {
+    const registry = await this.load();
+
+    if (registry.projects[name] && !options.overwrite) {
+      throw new Error(
+        `Проект с именем "${name}" уже есть в реестре. Выбери другое имя или обнови существующий проект.`,
+      );
+    }
+
+    registry.projects[name] = entry;
+    await this.save(registry);
+  }
+
+  /** Обновить поля существующего проекта. */
+  async update(
+    name: string,
+    patch: Partial<ProjectEntry>,
+  ): Promise<ProjectEntry> {
+    const registry = await this.load();
+    const existing = registry.projects[name];
+
+    if (!existing) {
+      throw new Error(`Проект "${name}" не найден в реестре.`);
+    }
+
+    const next: ProjectEntry = { ...existing, ...patch };
+    registry.projects[name] = next;
+    await this.save(registry);
+    return next;
+  }
+
+  async remove(name: string): Promise<void> {
+    const registry = await this.load();
+
+    if (!registry.projects[name]) {
+      throw new Error(`Проект "${name}" не найден в реестре.`);
+    }
+
+    delete registry.projects[name];
+    await this.save(registry);
+  }
+}

package/src/shared/runbook/runbook.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { RunbookService } from './runbook.service';
+
+@Global()
+@Module({
+  providers: [RunbookService],
+  exports: [RunbookService],
+})
+export class RunbookModule {}

package/src/shared/runbook/runbook.service.ts

@@ -0,0 +1,164 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { Injectable } from '@nestjs/common';
+import {
+  type ProjectConfig,
+  projectConfigSchema,
+} from '../../core/registry/registry.schema';
+import { type DetectedStack, renderRunbook } from './runbook.templates';
+
+const RUNBOOK_DIR = '.runbook';
+const GITIGNORE_ENTRY = '/.runbook/';
+/** Эквивалентные записи `.runbook/` в `.gitignore` — считаем дублем. */
+const GITIGNORE_EQUIVALENTS = new Set([
+  '/.runbook/',
+  '/.runbook',
+  '.runbook/',
+  '.runbook',
+]);
+
+/** Результат настройки `.gitignore`. */
+export type GitignoreResult = 'created' | 'added' | 'present' | 'no-git';
+
+/**
+ * Работа с per-project директорией `.runbook/`: скаффолд, чтение/запись
+ * `config.json`, чтение `runbook.md` и идемпотентная настройка `.gitignore`.
+ */
+@Injectable()
+export class RunbookService {
+  dirPath(root: string = process.cwd()): string {
+    return path.join(root, RUNBOOK_DIR);
+  }
+
+  configPath(root: string = process.cwd()): string {
+    return path.join(root, RUNBOOK_DIR, 'config.json');
+  }
+
+  runbookPath(root: string = process.cwd()): string {
+    return path.join(root, RUNBOOK_DIR, 'runbook.md');
+  }
+
+  /** Инициализирован ли проект (есть `.runbook/config.json`). */
+  async exists(root: string = process.cwd()): Promise<boolean> {
+    return this.pathExists(this.configPath(root));
+  }
+
+  async readConfig(root: string = process.cwd()): Promise<ProjectConfig> {
+    const content = await fs.readFile(this.configPath(root), 'utf8');
+    return projectConfigSchema.parse(JSON.parse(content));
+  }
+
+  async writeConfig(
+    config: ProjectConfig,
+    root: string = process.cwd(),
+  ): Promise<void> {
+    const validated = projectConfigSchema.parse(config);
+    await fs.mkdir(this.dirPath(root), { recursive: true });
+    await fs.writeFile(
+      this.configPath(root),
+      `${JSON.stringify(validated, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  async readRunbook(root: string = process.cwd()): Promise<string> {
+    return fs.readFile(this.runbookPath(root), 'utf8');
+  }
+
+  /**
+   * Создаёт `.runbook/` с config.json и (если ещё нет) runbook.md.
+   * Существующий runbook.md не перезаписывается — ручные правки сохраняются.
+   */
+  async scaffold(
+    options: { project: string; stands: string[]; activeStand: string },
+    root: string = process.cwd(),
+  ): Promise<void> {
+    await fs.mkdir(this.dirPath(root), { recursive: true });
+
+    await this.writeConfig(
+      {
+        project: options.project,
+        activeStand: options.activeStand,
+        stands: options.stands,
+      },
+      root,
+    );
+
+    if (!(await this.pathExists(this.runbookPath(root)))) {
+      const detected = await this.detectStack(root);
+      const markdown = renderRunbook(options.project, options.stands, detected);
+      await fs.writeFile(this.runbookPath(root), markdown, 'utf8');
+    }
+  }
+
+  /** Определяет наличие docker-compose / Dockerfile / .env.example. */
+  async detectStack(root: string = process.cwd()): Promise<DetectedStack> {
+    const [composeYml, composeYaml, dockerfile, envExample] = await Promise.all(
+      [
+        this.pathExists(path.join(root, 'docker-compose.yml')),
+        this.pathExists(path.join(root, 'docker-compose.yaml')),
+        this.pathExists(path.join(root, 'Dockerfile')),
+        this.pathExists(path.join(root, '.env.example')),
+      ],
+    );
+
+    return {
+      compose: composeYml || composeYaml,
+      dockerfile,
+      envExample,
+    };
+  }
+
+  /**
+   * Гарантирует, что `.runbook/` игнорируется git — автоматически и идемпотентно.
+   * - не git-репозиторий → ничего не пишем, возвращаем 'no-git';
+   * - запись уже есть → 'present';
+   * - `.gitignore` отсутствует → создаём с записью → 'created';
+   * - иначе дописываем в конец → 'added'.
+   */
+  async ensureGitignore(
+    root: string = process.cwd(),
+  ): Promise<GitignoreResult> {
+    if (!(await this.pathExists(path.join(root, '.git')))) {
+      return 'no-git';
+    }
+
+    const gitignorePath = path.join(root, '.gitignore');
+    let content = '';
+    let fileExists = true;
+
+    try {
+      content = await fs.readFile(gitignorePath, 'utf8');
+    } catch {
+      fileExists = false;
+    }
+
+    const alreadyIgnored = content
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .some((line) => GITIGNORE_EQUIVALENTS.has(line));
+
+    if (alreadyIgnored) {
+      return 'present';
+    }
+
+    const trimmed = content.trimEnd();
+    const next =
+      trimmed.length > 0
+        ? `${trimmed}\n${GITIGNORE_ENTRY}\n`
+        : `${GITIGNORE_ENTRY}\n`;
+
+    await fs.writeFile(gitignorePath, next, 'utf8');
+
+    return fileExists ? 'added' : 'created';
+  }
+
+  private async pathExists(target: string): Promise<boolean> {
+    try {
+      await fs.access(target);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/shared/runbook/runbook.templates.ts

@@ -0,0 +1,66 @@
+/** Что удалось определить про проект (для подсказок в runbook). */
+export type DetectedStack = {
+  compose: boolean;
+  dockerfile: boolean;
+  envExample: boolean;
+};
+
+const STAND_TITLES: Record<string, string> = {
+  local: 'локальная разработка',
+  dev: 'dev-стенд',
+  stage: 'stage-стенд',
+  prod: 'production (осторожно!)',
+};
+
+function renderStandSection(stand: string, detected: DetectedStack): string {
+  const title = STAND_TITLES[stand] ?? stand;
+
+  const startCmd = detected.compose
+    ? 'docker compose up -d'
+    : '<команда запуска, напр. docker compose up -d>';
+  const logsCmd = detected.compose
+    ? 'docker compose logs -f'
+    : '<команда логов>';
+  const envNote = detected.envExample
+    ? 'Скопируй `.env.example` → `.env` и заполни значения.'
+    : '<откуда взять переменные окружения / секреты>';
+
+  return [
+    `## Стенд: ${stand} (${title})`,
+    '',
+    '- **Где живёт / доступ**: <ssh user@host или localhost>',
+    '- **Рабочая директория**: <путь на сервере или локально>',
+    '- **Получить код**: `git clone <repo>` (первый раз) / `git pull` (обновить)',
+    `- **Запуск**: \`${startCmd}\``,
+    `- **Логи**: \`${logsCmd}\``,
+    '- **Деплой**: <пошаговые команды деплоя на этот стенд>',
+    '- **Откат**: <как откатиться, если что-то пошло не так>',
+    `- **Переменные окружения / секреты**: ${envNote}`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Стартовый runbook для проекта. Заполняется человеком/агентом — конкретные
+ * команды и пути подставляются под реальную инфраструктуру.
+ */
+export function renderRunbook(
+  project: string,
+  stands: string[],
+  detected: DetectedStack,
+): string {
+  const header = [
+    `# Runbook: ${project}`,
+    '',
+    '> Этот файл описывает, как работать со стендами проекта.',
+    '> Он лежит в `.gitignore` и не коммитится — здесь могут быть хосты и пути.',
+    '> Заполни плейсхолдеры `<...>` под свою инфраструктуру.',
+    '',
+  ].join('\n');
+
+  const sections = stands
+    .map((stand) => renderStandSection(stand, detected))
+    .join('\n');
+
+  return `${header}\n${sections}`;
+}