kodu 2.1.3 → 2.2.0

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>;

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 {}