kodu 2.1.2 → 2.2.0

package/src/commands/ops/ops-init.command.ts

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import { CommandRunner, Option, SubCommand } from 'nest-commander';
+import { DEFAULT_STANDS } from '../../core/registry/registry.schema';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { RunbookService } from '../../shared/runbook/runbook.service';
+
+type InitOptions = {
+  name?: string;
+  // Свойства называются по длинным флагам `--active` / `--stand`.
+  active?: string;
+  stand?: string[];
+};
+
+@SubCommand({
+  name: 'init',
+  description:
+    'Настроить стенды в текущем проекте: создать .runbook/, .gitignore и зарегистрировать проект',
+})
+export class OpsInitCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+    private readonly runbook: RunbookService,
+  ) {
+    super();
+  }
+
+  @Option({
+    flags: '-n, --name <name>',
+    description: 'Уникальное имя проекта (по умолчанию — имя папки)',
+  })
+  parseName(value: string): string {
+    return value;
+  }
+
+  @Option({
+    flags: '-a, --active <stand>',
+    description: 'Активный стенд по умолчанию (по умолчанию local)',
+  })
+  parseActive(value: string): string {
+    return value;
+  }
+
+  @Option({
+    flags: '-s, --stand <stand>',
+    description: 'Стенд проекта (можно повторять)',
+  })
+  parseStand(value: string, previous: string[] = []): string[] {
+    return [...previous, value];
+  }
+
+  async run(_inputs: string[], options: InitOptions): Promise<void> {
+    const root = process.cwd();
+    const name = options.name ?? path.basename(root);
+    const stands =
+      options.stand && options.stand.length > 0
+        ? options.stand
+        : [...DEFAULT_STANDS];
+    const activeStand = options.active ?? stands[0] ?? 'local';
+
+    try {
+      // 1. Скаффолд .runbook/ (config.json + runbook.md).
+      await this.runbook.scaffold({ project: name, stands, activeStand }, root);
+      this.ui.log.success(`Создан .runbook/ для проекта "${name}".`);
+      this.ui.log.info(`Активный стенд: ${activeStand}`);
+      this.ui.log.info(
+        `Заполни шаги деплоя в ${this.runbook.runbookPath(root)}`,
+      );
+
+      // 2. Гарантируем игнор .runbook/ — автоматически.
+      const gitignore = await this.runbook.ensureGitignore(root);
+      this.reportGitignore(gitignore);
+
+      // 3. Регистрируем проект в глобальном реестре (имя уникально).
+      await this.registerProject(name, root, stands);
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+
+  private reportGitignore(result: string): void {
+    switch (result) {
+      case 'created':
+        this.ui.log.success('Создан .gitignore с записью /.runbook/');
+        break;
+      case 'added':
+        this.ui.log.success('Добавил /.runbook/ в .gitignore');
+        break;
+      case 'present':
+        this.ui.log.info('/.runbook/ уже в .gitignore');
+        break;
+      case 'no-git':
+        this.ui.log.warn(
+          'Это не git-репозиторий — .gitignore не настроен. Не коммить .runbook/ вручную.',
+        );
+        break;
+    }
+  }
+
+  private async registerProject(
+    name: string,
+    root: string,
+    stands: string[],
+  ): Promise<void> {
+    const existing = await this.registry.get(name);
+
+    if (!existing) {
+      await this.registry.add(name, { path: root, stands });
+      this.ui.log.success(`Проект "${name}" добавлен в реестр.`);
+      return;
+    }
+
+    if (existing.path === root) {
+      this.ui.log.info(`Проект "${name}" уже в реестре.`);
+      return;
+    }
+
+    this.ui.log.warn(
+      `Имя "${name}" уже занято другим путём (${existing.path}). ` +
+        'Запусти заново с другим именем: kodu ops init --name <другое-имя>',
+    );
+  }
+}

package/src/commands/ops/ops-list.command.ts

@@ -0,0 +1,57 @@
+import { CommandRunner, SubCommand } from 'nest-commander';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { RunbookService } from '../../shared/runbook/runbook.service';
+
+@SubCommand({
+  name: 'list',
+  aliases: ['ls'],
+  description: 'Показать все проекты из реестра и их активные стенды',
+})
+export class OpsListCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+    private readonly runbook: RunbookService,
+  ) {
+    super();
+  }
+
+  async run(): Promise<void> {
+    try {
+      const projects = await this.registry.list();
+      const names = Object.keys(projects).sort((a, b) => a.localeCompare(b));
+
+      if (names.length === 0) {
+        this.ui.log.info(
+          'Реестр пуст. Добавь проект: kodu ops add <name> --path <dir>',
+        );
+        this.ui.log.info(`Файл реестра: ${this.registry.getFilePath()}`);
+        return;
+      }
+
+      for (const name of names) {
+        const entry = projects[name];
+        const active = await this.readActiveStand(entry.path);
+        const activeLabel = active ? ` [активный: ${active}]` : '';
+        this.ui.log.info(`${name}${activeLabel}`);
+        this.ui.log.info(`  путь:   ${entry.path}`);
+        this.ui.log.info(`  стенды: ${entry.stands.join(', ')}`);
+      }
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+
+  private async readActiveStand(root: string): Promise<string | undefined> {
+    try {
+      if (!(await this.runbook.exists(root))) {
+        return undefined;
+      }
+      return (await this.runbook.readConfig(root)).activeStand;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/commands/ops/ops-path.command.ts

@@ -0,0 +1,38 @@
+import { CommandRunner, SubCommand } from 'nest-commander';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { resolveProjectRoot } from './ops.helpers';
+
+@SubCommand({
+  name: 'path',
+  description:
+    'Напечатать путь к репозиторию проекта (удобно для cd $(kodu ops path <name>))',
+  arguments: '<name>',
+})
+export class OpsPathCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+  ) {
+    super();
+  }
+
+  async run(inputs: string[]): Promise<void> {
+    const name = inputs[0];
+
+    if (!name) {
+      this.ui.log.error('Укажи имя проекта: kodu ops path <name>');
+      process.exitCode = 1;
+      return;
+    }
+
+    try {
+      const root = await resolveProjectRoot(this.registry, name);
+      // Чистый вывод пути в stdout — чтобы работало в подстановке команды.
+      process.stdout.write(`${root}\n`);
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+}

package/src/commands/ops/ops-runbook.command.ts

@@ -0,0 +1,74 @@
+import { CommandRunner, SubCommand } from 'nest-commander';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { RunbookService } from '../../shared/runbook/runbook.service';
+import { resolveProjectRoot } from './ops.helpers';
+
+@SubCommand({
+  name: 'runbook',
+  description: 'Напечатать runbook проекта (или секцию конкретного стенда)',
+  arguments: '<name> [stand]',
+})
+export class OpsRunbookCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+    private readonly runbook: RunbookService,
+  ) {
+    super();
+  }
+
+  async run(inputs: string[]): Promise<void> {
+    const name = inputs[0];
+    const stand = inputs[1];
+
+    if (!name) {
+      this.ui.log.error('Укажи имя проекта: kodu ops runbook <name> [stand]');
+      process.exitCode = 1;
+      return;
+    }
+
+    try {
+      const root = await resolveProjectRoot(this.registry, name);
+
+      if (!(await this.runbook.exists(root))) {
+        this.ui.log.warn(
+          `В проекте "${name}" нет .runbook/. Запусти: kodu ops init`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      const markdown = await this.runbook.readRunbook(root);
+      const output = stand ? this.extractStand(markdown, stand) : markdown;
+
+      if (!output) {
+        this.ui.log.warn(`Секция для стенда "${stand}" не найдена в runbook.`);
+        process.exitCode = 1;
+        return;
+      }
+
+      process.stdout.write(`${output.trimEnd()}\n`);
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+
+  /** Возвращает блок `## Стенд: <stand> ...` до следующего заголовка `## `. */
+  private extractStand(markdown: string, stand: string): string | undefined {
+    const lines = markdown.split(/\r?\n/);
+    const startPrefix = `## Стенд: ${stand}`;
+    const start = lines.findIndex((line) => line.startsWith(startPrefix));
+
+    if (start === -1) {
+      return undefined;
+    }
+
+    const rest = lines.slice(start + 1);
+    const nextHeading = rest.findIndex((line) => line.startsWith('## '));
+    const end = nextHeading === -1 ? lines.length : start + 1 + nextHeading;
+
+    return lines.slice(start, end).join('\n');
+  }
+}

package/src/commands/ops/ops-status.command.ts

@@ -0,0 +1,47 @@
+import { CommandRunner, SubCommand } from 'nest-commander';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { RunbookService } from '../../shared/runbook/runbook.service';
+import { resolveProjectRoot } from './ops.helpers';
+
+@SubCommand({
+  name: 'status',
+  description:
+    'Показать активный стенд и стенды проекта (по имени или в текущей папке)',
+  arguments: '[name]',
+})
+export class OpsStatusCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+    private readonly runbook: RunbookService,
+  ) {
+    super();
+  }
+
+  async run(inputs: string[]): Promise<void> {
+    try {
+      const name = inputs[0];
+      const root = name
+        ? await resolveProjectRoot(this.registry, name)
+        : process.cwd();
+
+      if (!(await this.runbook.exists(root))) {
+        this.ui.log.warn(
+          `В ${root} нет .runbook/. Инициализируй проект: kodu ops init`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      const config = await this.runbook.readConfig(root);
+      this.ui.log.info(`Проект:        ${config.project}`);
+      this.ui.log.info(`Активный стенд: ${config.activeStand}`);
+      this.ui.log.info(`Стенды:        ${config.stands.join(', ')}`);
+      this.ui.log.info(`Путь:          ${root}`);
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+}

package/src/commands/ops/ops-use.command.ts

@@ -0,0 +1,76 @@
+import { CommandRunner, SubCommand } from 'nest-commander';
+import { RegistryService } from '../../core/registry/registry.service';
+import { UiService } from '../../core/ui/ui.service';
+import { RunbookService } from '../../shared/runbook/runbook.service';
+import { resolveProjectRoot } from './ops.helpers';
+
+@SubCommand({
+  name: 'use',
+  aliases: ['switch'],
+  description:
+    'Переключить активный стенд: "kodu ops use <stand>" в текущем проекте или "kodu ops use <name> <stand>"',
+  arguments: '<args...>',
+})
+export class OpsUseCommand extends CommandRunner {
+  constructor(
+    private readonly ui: UiService,
+    private readonly registry: RegistryService,
+    private readonly runbook: RunbookService,
+  ) {
+    super();
+  }
+
+  async run(inputs: string[]): Promise<void> {
+    try {
+      const { root, stand } = await this.resolveTarget(inputs);
+
+      if (!stand) {
+        this.ui.log.error(
+          'Укажи стенд: kodu ops use <stand> или kodu ops use <name> <stand>',
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      if (!(await this.runbook.exists(root))) {
+        this.ui.log.warn(
+          `В ${root} нет .runbook/. Инициализируй проект: kodu ops init`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      const config = await this.runbook.readConfig(root);
+      const stands = config.stands.includes(stand)
+        ? config.stands
+        : [...config.stands, stand];
+
+      if (!config.stands.includes(stand)) {
+        this.ui.log.info(`Стенд "${stand}" добавлен в список стендов проекта.`);
+      }
+
+      await this.runbook.writeConfig(
+        { ...config, activeStand: stand, stands },
+        root,
+      );
+      this.ui.log.success(
+        `Активный стенд проекта "${config.project}" → ${stand}`,
+      );
+    } catch (error) {
+      this.ui.log.error((error as Error).message);
+      process.exitCode = 1;
+    }
+  }
+
+  /** 1 аргумент → стенд в текущей папке; 2 аргумента → <name> <stand>. */
+  private async resolveTarget(
+    inputs: string[],
+  ): Promise<{ root: string; stand?: string }> {
+    if (inputs.length >= 2) {
+      const root = await resolveProjectRoot(this.registry, inputs[0]);
+      return { root, stand: inputs[1] };
+    }
+
+    return { root: process.cwd(), stand: inputs[0] };
+  }
+}

package/src/commands/ops/ops.command.ts

@@ -0,0 +1,42 @@
+import { Command, CommandRunner } from 'nest-commander';
+import { UiService } from '../../core/ui/ui.service';
+import { OpsAddCommand } from './ops-add.command';
+import { OpsInitCommand } from './ops-init.command';
+import { OpsListCommand } from './ops-list.command';
+import { OpsPathCommand } from './ops-path.command';
+import { OpsRunbookCommand } from './ops-runbook.command';
+import { OpsStatusCommand } from './ops-status.command';
+import { OpsUseCommand } from './ops-use.command';
+
+@Command({
+  name: 'ops',
+  description:
+    'Работа с проектами и стендами (local/dev/stage/prod) из любого места',
+  subCommands: [
+    OpsInitCommand,
+    OpsListCommand,
+    OpsAddCommand,
+    OpsStatusCommand,
+    OpsUseCommand,
+    OpsPathCommand,
+    OpsRunbookCommand,
+  ],
+})
+export class OpsCommand extends CommandRunner {
+  constructor(private readonly ui: UiService) {
+    super();
+  }
+
+  async run(): Promise<void> {
+    this.ui.log.info('Использование: kodu ops <команда>');
+    this.ui.log.info(
+      '  init                  — настроить стенды в текущем проекте',
+    );
+    this.ui.log.info('  list                  — список всех проектов');
+    this.ui.log.info('  add <name> --path <d> — зарегистрировать проект');
+    this.ui.log.info('  status [name]         — активный стенд проекта');
+    this.ui.log.info('  use <stand>           — переключить активный стенд');
+    this.ui.log.info('  path <name>           — путь к репозиторию проекта');
+    this.ui.log.info('  runbook <name> [stand]— показать инструкции по стенду');
+  }
+}

package/src/commands/ops/ops.helpers.ts

@@ -0,0 +1,20 @@
+import { RegistryService } from '../../core/registry/registry.service';
+
+/**
+ * Возвращает путь к репозиторию проекта по его имени из реестра.
+ * Бросает понятную ошибку, если проект не найден.
+ */
+export async function resolveProjectRoot(
+  registry: RegistryService,
+  name: string,
+): Promise<string> {
+  const entry = await registry.get(name);
+
+  if (!entry) {
+    throw new Error(
+      `Проект "${name}" не найден в реестре. Список проектов: kodu ops list`,
+    );
+  }
+
+  return entry.path;
+}

package/src/commands/ops/ops.module.ts

@@ -0,0 +1,23 @@
+import { Module } from '@nestjs/common';
+import { OpsCommand } from './ops.command';
+import { OpsAddCommand } from './ops-add.command';
+import { OpsInitCommand } from './ops-init.command';
+import { OpsListCommand } from './ops-list.command';
+import { OpsPathCommand } from './ops-path.command';
+import { OpsRunbookCommand } from './ops-runbook.command';
+import { OpsStatusCommand } from './ops-status.command';
+import { OpsUseCommand } from './ops-use.command';
+
+@Module({
+  providers: [
+    OpsCommand,
+    OpsInitCommand,
+    OpsListCommand,
+    OpsAddCommand,
+    OpsStatusCommand,
+    OpsUseCommand,
+    OpsPathCommand,
+    OpsRunbookCommand,
+  ],
+})
+export class OpsModule {}

package/src/core/registry/registry.module.ts

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

package/src/core/registry/registry.schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * Стандартный набор стендов. Можно использовать и любые другие имена —
+ * стенды хранятся как обычные строки, это лишь значение по умолчанию.
+ */
+export const DEFAULT_STANDS = ['local', 'dev', 'stage', 'prod'] as const;
+
+/** Один проект в глобальном реестре `~/.config/kodu/registry.json`. */
+export const projectEntrySchema = z.object({
+  /** Абсолютный путь к репозиторию проекта на этой машине. */
+  path: z.string().min(1),
+  /** URL репозитория (git clone), необязательно. */
+  repo: z.string().optional(),
+  /** Доступные стенды проекта. */
+  stands: z.array(z.string()).default([...DEFAULT_STANDS]),
+});
+
+export type ProjectEntry = z.infer<typeof projectEntrySchema>;
+
+/**
+ * Глобальный реестр всех проектов. Ключ объекта `projects` — уникальное имя
+ * проекта, по которому агент/CLI понимает, с каким репозиторием работать.
+ */
+export const registrySchema = z.object({
+  $schema: z.string().optional(),
+  projects: z.record(z.string(), projectEntrySchema).default({}),
+});
+
+export type Registry = z.infer<typeof registrySchema>;
+
+/**
+ * Per-project конфиг `.runbook/config.json` (лежит в `.gitignore`).
+ * Хранит текущий активный стенд конкретного разработчика.
+ */
+export const projectConfigSchema = z.object({
+  $schema: z.string().optional(),
+  /** Имя проекта — должно совпадать с ключом в глобальном реестре. */
+  project: z.string().min(1),
+  /** Текущий активный стенд. */
+  activeStand: z.string().default('local'),
+  /** Доступные стенды проекта. */
+  stands: z.array(z.string()).default([...DEFAULT_STANDS]),
+});
+
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;