@pachca/cli 2026.5.1 → 2026.5.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026.5.2  (17 мая 2026)
+
+- **Добавлено** (users create): Параметр `--chat-ids` — добавить сотрудника в указанные чаты сразу при создании. Параметр `--role` теперь принимает значение `guest`: для роли `guest` нужно передать `--chat-ids` ровно с одним активным чатом, иначе API вернёт `400`
+- **Добавлено** (api): Список эндпоинтов и справка по API прямо в CLI: `pachca api ls` (список всех эндпоинтов), `pachca api <МЕТОД> <путь> --describe` / `--spec` / `--docs` (параметры, тело, схема, пример). Данные берутся из той же OpenAPI-спецификации, из которой собран CLI, — всегда совпадают с актуальным API. Агенту не нужно искать эндпоинт в документации
+- **Добавлено** (api): Флаг `--data` — тело запроса инлайн JSON-строкой (`pachca api POST /messages --data '{...}'`)
+- **Добавлено**: Флаг `--plain` — плоский TSV-вывод для скриптов: без заголовка, колонка id первой, без цвета и обрезки
+- **Добавлено**: Переменная окружения `PACHCA_HOME` — переопределение каталога конфига (для изоляции в CI, тестах и у агентов)
+
 ## 2026.5.1  (6 мая 2026)
 
 - **Изменено**: Поддержка обновлённого формата курсорной пагинации в list-командах

package/README.md

@@ -223,17 +223,20 @@ pachca guide            # список всех сценариев
 
 | Флаг | Короткий | Описание |
 |------|----------|----------|
-| `--output <format>` | `-o` | Формат вывода: table, json, yaml, csv |
-| `--columns <list>` | `-c` | Колонки для table-вывода |
-| `--no-header` | | Скрыть заголовок таблицы |
-| `--profile <name>` | `-p` | Профиль для этой команды |
-| `--token <value>` | | Bearer-токен для этого вызова |
-| `--quiet` | `-q` | Подавить вывод кроме ошибок |
-| `--verbose` | `-v` | Показывать HTTP-детали |
-| `--no-input` | | Отключить промпты |
-| `--dry-run` | | Показать запрос без отправки |
-| `--timeout <seconds>` | | Таймаут запроса |
-| `--no-retry` | | Отключить авто-retry |
+| `--output <value>` | `-o` | Формат вывода: table, json, yaml, csv |
+| `--columns <value>` | `-c` | Колонки для table-вывода (через запятую) |
+| `--no-header` |  | Скрыть заголовок таблицы |
+| `--no-truncate` |  | Не обрезать длинные значения |
+| `--profile <value>` | `-p` | Профиль для этой команды |
+| `--token <value>` |  | Токен для этого вызова (без сохранения) |
+| `--quiet` | `-q` | Подавить вывод (только exit code и ошибки) |
+| `--no-color` |  | Отключить цвета |
+| `--verbose` | `-v` | Показывать HTTP-запросы и ответы |
+| `--no-input` |  | Отключить интерактивные промпты |
+| `--dry-run` |  | Показать запрос без отправки |
+| `--timeout <value>` |  | Таймаут запроса в секундах (по умолчанию 30) |
+| `--no-retry` |  | Отключить авто-retry при 429/503 |
+| `--plain` |  | Плоский вывод: TSV без заголовка, ID первым, без цвета (для скриптов) |
 
 <!-- AUTO:FLAGS:END -->
 
@@ -366,9 +369,9 @@ pachca changelog
 ## Shell completion
 
 ```
-pachca autocomplete zsh   # zsh completion
-pachca autocomplete bash  # bash completion
-pachca autocomplete fish  # fish completion
+pachca autocomplete zsh         # zsh completion
+pachca autocomplete bash        # bash completion
+pachca autocomplete powershell  # PowerShell completion
 ```
 
 ## Переменные окружения

package/README.template.md

@@ -200,9 +200,9 @@ pachca changelog
 ## Shell completion
 
 ```
-pachca autocomplete zsh   # zsh completion
-pachca autocomplete bash  # bash completion
-pachca autocomplete fish  # fish completion
+pachca autocomplete zsh         # zsh completion
+pachca autocomplete bash        # bash completion
+pachca autocomplete powershell  # PowerShell completion
 ```
 
 ## Переменные окружения

package/dist/api-introspect.js

@@ -0,0 +1,60 @@
+/**
+ * C1 — Self-documenting `pachca api`.
+ *
+ * Pure helpers over the build-time generated `src/data/endpoints.json`
+ * (emitted by scripts/generate-cli.ts from the OpenAPI spec).
+ *
+ * The heavy lifting (parsing, $ref resolution, markdown, examples, curl)
+ * is done at build time by reused apps/docs generators; at runtime the CLI
+ * only reads JSON — no YAML parser in the bundle.
+ */
+export function buildListRows(entries) {
+    return entries.map((e) => ({
+        method: e.method,
+        path: e.path,
+        summary: e.summary,
+        scope: e.scope ?? '',
+    }));
+}
+/**
+ * Detect a self-documenting mode from raw argv (before this.parse()).
+ * `pachca api` already requires the method positionally, so
+ * `pachca api POST /messages --describe` is unambiguous by construction
+ * (no `-X` needed, unlike Notion's `ntn api`).
+ */
+export function detectIntrospectMode(argv) {
+    if (argv.includes('--describe'))
+        return 'describe';
+    if (argv.includes('--spec'))
+        return 'spec';
+    if (argv.includes('--docs'))
+        return 'docs';
+    return null;
+}
+/**
+ * Leading run of positional tokens (method, path) — stops at the first flag,
+ * so flag values (e.g. `-o json`) are never mistaken for the path.
+ * `pachca api` always takes method and path before any flag.
+ */
+export function positionals(argv) {
+    const out = [];
+    for (const a of argv) {
+        if (a.startsWith('-'))
+            break;
+        out.push(a);
+    }
+    return out;
+}
+export function findEndpoint(entries, method, path) {
+    const m = method.toUpperCase();
+    const p = path.replace(/\/+$/, '') || '/';
+    return entries.find((e) => e.method === m && (e.path === path || e.path.replace(/\/+$/, '') === p));
+}
+/** Render the selected introspection output for a found endpoint. */
+export function renderIntrospect(entry, mode) {
+    if (mode === 'spec')
+        return JSON.stringify(entry.spec, null, 2);
+    if (mode === 'docs')
+        return entry.docs;
+    return entry.describe;
+}

package/dist/base-command.js

@@ -63,6 +63,10 @@ export class BaseCommand extends Command {
             default: false,
             hidden: true,
         }),
+        plain: Flags.boolean({
+            description: 'Plain output: TSV, no header, ID column first, no color (for scripts)',
+            default: false,
+        }),
     };
     _parsedFlags;
     get parsedFlags() { return this._parsedFlags; }
@@ -95,6 +99,7 @@ export class BaseCommand extends Command {
             noHeader: this.parsedFlags['no-header'],
             noTruncate: this.parsedFlags['no-truncate'],
             quiet: this.parsedFlags.quiet,
+            plain: this.parsedFlags.plain,
         };
     }
     /**

package/dist/commands/api.js

@@ -2,23 +2,30 @@ import * as fs from 'node:fs';
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
 import { outputError } from '../output.js';
+import { buildListRows, detectIntrospectMode, positionals, findEndpoint, renderIntrospect, } from '../api-introspect.js';
 export default class Api extends BaseCommand {
-    static description = 'Произвольный запрос к API';
+    static description = 'Произвольный запрос к API. Список и справка: `api ls` (список эндпоинтов), `api <МЕТОД> <путь> --describe` / `--spec` / `--docs`';
     static examples = [
         '<%= config.bin %> api GET /messages --query chat_id=123',
         '<%= config.bin %> api POST /messages -F message[chat_id]=12345 -f message[content]="Привет"',
         '<%= config.bin %> api POST /messages --input payload.json',
+        `<%= config.bin %> api POST /messages --data '{"message":{"entity_id":123,"content":"Привет"}}'`,
         '<%= config.bin %> api GET /profile -o yaml',
+        '<%= config.bin %> api ls',
+        '<%= config.bin %> api ls --json',
+        '<%= config.bin %> api POST /messages --describe',
+        '<%= config.bin %> api GET /messages --spec',
+        '<%= config.bin %> api POST /messages --docs',
     ];
     static strict = false;
     static args = {
         method: Args.string({
-            description: 'HTTP method (GET, POST, PUT, DELETE)',
+            description: 'HTTP-метод (GET, POST, PUT, DELETE, PATCH)',
             required: true,
             options: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
         }),
         path: Args.string({
-            description: 'API path (e.g., /messages)',
+            description: 'Путь API (например, /messages)',
             required: true,
         }),
     };
@@ -26,23 +33,40 @@ export default class Api extends BaseCommand {
         ...BaseCommand.baseFlags,
         'raw-field': Flags.string({
             char: 'f',
-            description: 'String field (key=value)',
+            description: 'Строковое поле (key=value)',
             multiple: true,
         }),
         field: Flags.string({
             char: 'F',
-            description: 'Typed field (numbers/bools auto-converted, @file reads file)',
+            description: 'Типизированное поле (числа/boolean автоматически, @file читает файл)',
             multiple: true,
         }),
         input: Flags.string({
-            description: 'JSON file to send as body (- for stdin)',
+            description: 'JSON-файл с телом запроса (- для stdin)',
+        }),
+        data: Flags.string({
+            description: 'Тело запроса инлайн JSON-строкой',
         }),
         query: Flags.string({
-            description: 'Query parameter (key=value)',
+            description: 'Query-параметр (key=value)',
             multiple: true,
         }),
     };
     async run() {
+        // C1 — self-documenting `api`. Intercept the raw argv BEFORE this.parse(Api):
+        // the `method` arg is required+enum, so `api ls` / `--describe` would fail
+        // oclif validation before run(). This branch is strictly additive — those
+        // argv shapes errored before; the normal request path below is untouched.
+        const raw = this.argv;
+        if (raw[0] === 'ls') {
+            await this.runApiList(raw.includes('--json'));
+            return;
+        }
+        const mode = detectIntrospectMode(raw);
+        if (mode) {
+            await this.runApiIntrospect(raw, mode);
+            return;
+        }
         const { args, flags } = await this.parse(Api);
         this.parsedFlags = flags;
         const format = this.getOutputFormat();
@@ -52,6 +76,11 @@ export default class Api extends BaseCommand {
             outputError({ error: '-f/-F and --input are mutually exclusive', type: 'PACHCA_USAGE_ERROR', code: null }, format);
             this.exit(2);
         }
+        // C6 — --data (inline JSON) shares the body path; only one body source allowed.
+        if (flags.data && (hasFields || flags.input)) {
+            outputError({ error: '--data is mutually exclusive with -f/-F and --input', type: 'PACHCA_USAGE_ERROR', code: null }, format);
+            this.exit(2);
+        }
         // Build query params
         const query = {};
         if (flags.query) {
@@ -88,6 +117,16 @@ export default class Api extends BaseCommand {
                 this.exit(2);
             }
         }
+        else if (flags.data) {
+            // Same string → JSON → body path as --input, just inline (thin alias).
+            try {
+                body = JSON.parse(flags.data);
+            }
+            catch {
+                outputError({ error: 'Invalid JSON in --data', type: 'PACHCA_USAGE_ERROR', code: null }, format);
+                this.exit(2);
+            }
+        }
         else if (hasFields) {
             const merged = {};
             // Process -f (raw string fields)
@@ -121,6 +160,49 @@ export default class Api extends BaseCommand {
         const { outputData } = await import('../output.js');
         outputData(data, { ...this.getOutputOptions(), format: outFormat });
     }
+    /** Load the build-time endpoint index (mirrors guide.ts workflows.json loading). */
+    async loadEndpoints() {
+        try {
+            const data = await import('../data/endpoints.json', { with: { type: 'json' } });
+            return (data.default || data);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** `pachca api ls [--json]` — list every API endpoint. */
+    async runApiList(asJson) {
+        const entries = await this.loadEndpoints();
+        const rows = buildListRows(entries);
+        const { outputData } = await import('../output.js');
+        outputData(rows, { format: asJson ? 'json' : 'table', quiet: false });
+    }
+    /** `pachca api <METHOD> <path> --spec|--docs|--describe`. */
+    async runApiIntrospect(raw, mode) {
+        const errFormat = process.stdout.isTTY ? 'table' : 'json';
+        const pos = positionals(raw);
+        const method = pos[0];
+        const path = pos[1];
+        if (!method || !path) {
+            outputError({
+                error: `Укажите метод и путь: pachca api <МЕТОД> <путь> --${mode}. Список: pachca api ls`,
+                type: 'PACHCA_USAGE_ERROR',
+                code: null,
+            }, errFormat);
+            this.exit(2);
+        }
+        const entries = await this.loadEndpoints();
+        const entry = findEndpoint(entries, method, path);
+        if (!entry) {
+            outputError({
+                error: `Эндпоинт не найден: ${method.toUpperCase()} ${path}. Список: pachca api ls`,
+                type: 'PACHCA_NOT_FOUND_ERROR',
+                code: null,
+            }, errFormat);
+            this.exit(2);
+        }
+        process.stdout.write(renderIntrospect(entry, mode) + '\n');
+    }
 }
 /**
  * Parse a bracket notation key and set the value in the target object.

package/dist/commands/auth/login.js

@@ -15,11 +15,11 @@ export default class AuthLogin extends BaseCommand {
         ...BaseCommand.baseFlags,
         profile: Flags.string({
             char: 'p',
-            description: 'Profile name (default: "default")',
+            description: 'Имя профиля (по умолчанию "default")',
             default: 'default',
         }),
         token: Flags.string({
-            description: 'Token to save (skips prompt)',
+            description: 'Токен для сохранения (без интерактивного ввода)',
         }),
     };
     async run() {

package/dist/commands/auth/logout.js

@@ -11,7 +11,7 @@ export default class AuthLogout extends BaseCommand {
     ];
     static args = {
         profile: Args.string({
-            description: 'Profile name to remove',
+            description: 'Имя профиля для удаления',
             required: false,
         }),
     };

package/dist/commands/auth/switch.js

@@ -9,7 +9,7 @@ export default class AuthSwitch extends BaseCommand {
     ];
     static args = {
         profile: Args.string({
-            description: 'Profile name to switch to',
+            description: 'Имя профиля для переключения',
             required: true,
         }),
     };

package/dist/commands/commands.js

@@ -12,7 +12,7 @@ export default class Commands extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         available: Flags.boolean({
-            description: 'Show only commands available to current token',
+            description: 'Показать только команды, доступные текущему токену',
             default: false,
         }),
     };

package/dist/commands/config/get.js

@@ -7,7 +7,7 @@ export default class ConfigGet extends BaseCommand {
         '<%= config.bin %> config get defaults.output',
     ];
     static args = {
-        key: Args.string({ description: 'Configuration key', required: true }),
+        key: Args.string({ description: 'Ключ настройки', required: true }),
     };
     static flags = {
         ...BaseCommand.baseFlags,

package/dist/commands/config/set.js

@@ -8,8 +8,8 @@ export default class ConfigSet extends BaseCommand {
         '<%= config.bin %> config set defaults.timeout 60',
     ];
     static args = {
-        key: Args.string({ description: 'Configuration key', required: true }),
-        value: Args.string({ description: 'Configuration value', required: true }),
+        key: Args.string({ description: 'Ключ настройки', required: true }),
+        value: Args.string({ description: 'Значение настройки', required: true }),
     };
     static flags = {
         ...BaseCommand.baseFlags,

package/dist/commands/guide.js

@@ -9,7 +9,7 @@ export default class Guide extends BaseCommand {
     ];
     static args = {
         query: Args.string({
-            description: 'Search query',
+            description: 'Поисковый запрос',
             required: false,
         }),
     };

package/dist/commands/introspect.js

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { Args } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
+import { listCommandEntries, normalizeCommand } from '../lib/manifest.js';
 export default class Introspect extends BaseCommand {
     static description = 'Метаданные команды в машиночитаемом формате';
     static examples = [
@@ -11,7 +12,7 @@ export default class Introspect extends BaseCommand {
     static strict = false;
     static args = {
         command: Args.string({
-            description: 'Command name (e.g., "messages create")',
+            description: 'Имя команды (например, "messages create")',
             required: false,
         }),
     };
@@ -37,15 +38,7 @@ export default class Introspect extends BaseCommand {
         const commandId = commandArgs.join(':');
         if (!commandId) {
             // List all commands with metadata
-            const entries = Object.entries(commands).map(([id, meta]) => ({
-                command: `pachca ${id.replace(/:/g, ' ')}`,
-                summary: meta.summary || meta.description || '',
-                method: meta.apiMethod || null,
-                path: meta.apiPath || null,
-                scope: meta.scope || null,
-                plan: meta.plan || null,
-            }));
-            this.output(entries);
+            this.output(listCommandEntries(commands));
             return;
         }
         // Single command introspection
@@ -53,39 +46,8 @@ export default class Introspect extends BaseCommand {
         if (!cmdMeta) {
             this.validationError([{ message: `Command not found: ${commandArgs.join(' ')}` }], { hint: 'pachca introspect', type: 'PACHCA_COMMAND_NOT_FOUND' });
         }
-        const baseFlagNames = new Set(['output', 'columns', 'no-header', 'no-truncate', 'profile', 'token', 'quiet', 'no-color', 'verbose', 'no-input', 'dry-run', 'timeout', 'no-retry', 'json']);
-        const requiredFlagNames = new Set(cmdMeta.requiredFlags || []);
-        const flagsMeta = cmdMeta.flags;
-        const flagEntries = flagsMeta
-            ? Object.entries(flagsMeta)
-                .filter(([name]) => !baseFlagNames.has(name))
-                .map(([name, meta]) => ({
-                name,
-                type: meta.type || 'string',
-                required: requiredFlagNames.has(name),
-                description: meta.description || '',
-                ...(meta.options ? { options: meta.options } : {}),
-                ...(meta.maxLength ? { maxLength: meta.maxLength } : {}),
-            }))
-            : [];
-        const argsMeta = cmdMeta.args;
-        const argEntries = argsMeta
-            ? Object.entries(argsMeta).map(([name, meta]) => ({
-                name,
-                required: meta.required || false,
-                description: meta.description || '',
-            }))
-            : [];
-        const result = {
-            command: `pachca ${commandId.replace(/:/g, ' ')}`,
-            summary: cmdMeta.summary || cmdMeta.description || '',
-            method: cmdMeta.apiMethod || null,
-            path: cmdMeta.apiPath || null,
-            scope: cmdMeta.scope || null,
-            plan: cmdMeta.plan || null,
-            ...(argEntries.length > 0 ? { args: argEntries } : {}),
-            flags: flagEntries,
-        };
-        this.output(result);
+        // D3 single source: baseFlagNames derived from BaseCommand.baseFlags
+        const baseFlagNames = new Set(Object.keys(BaseCommand.baseFlags));
+        this.output(normalizeCommand(commandId, cmdMeta, baseFlagNames));
     }
 }

package/dist/commands/users/create.js

@@ -48,6 +48,9 @@ export default class UsersCreate extends BaseCommand {
         'list-tags': Flags.string({
             description: "Массив тегов, привязываемых к сотруднику",
         }),
+        'chat-ids': Flags.string({
+            description: "Идентификаторы чатов, в которые сотрудник будет добавлен сразу при создании. Для роли `guest` параметр обязателен и должен содержать ровно один активный чат.",
+        }),
         'custom-properties': Flags.string({
             description: "Задаваемые дополнительные поля",
         }),
@@ -97,6 +100,7 @@ export default class UsersCreate extends BaseCommand {
                 role: flags['role'],
                 suspended: flags['suspended'],
                 list_tags: flags['list-tags'] ? this.parseJSON(flags['list-tags'], 'list-tags') : undefined,
+                chat_ids: flags['chat-ids'] ? this.parseJSON(flags['chat-ids'], 'chat-ids') : undefined,
                 custom_properties: flags['custom-properties'] ? this.parseJSON(flags['custom-properties'], 'custom-properties') : undefined,
             },
             skip_email_notify: flags['skip-email-notify'],

package/dist/data/changelog.json

@@ -1,4 +1,33 @@
 [
+    {
+        "version": "2026.5.2",
+        "date": "17 мая 2026",
+        "changes": [
+            {
+                "type": "+",
+                "command": "users create",
+                "description": "Параметр `--chat-ids` — добавить сотрудника в указанные чаты сразу при создании. Параметр `--role` теперь принимает значение `guest`: для роли `guest` нужно передать `--chat-ids` ровно с одним активным чатом, иначе API вернёт `400`"
+            },
+            {
+                "type": "+",
+                "command": "api",
+                "description": "Список эндпоинтов и справка по API прямо в CLI: `pachca api ls` (список всех эндпоинтов), `pachca api <МЕТОД> <путь> --describe` / `--spec` / `--docs` (параметры, тело, схема, пример). Данные берутся из той же OpenAPI-спецификации, из которой собран CLI, — всегда совпадают с актуальным API. Агенту не нужно искать эндпоинт в документации"
+            },
+            {
+                "type": "+",
+                "command": "api",
+                "description": "Флаг `--data` — тело запроса инлайн JSON-строкой (`pachca api POST /messages --data '{...}'`)"
+            },
+            {
+                "type": "+",
+                "description": "Флаг `--plain` — плоский TSV-вывод для скриптов: без заголовка, колонка id первой, без цвета и обрезки"
+            },
+            {
+                "type": "+",
+                "description": "Переменная окружения `PACHCA_HOME` — переопределение каталога конфига (для изоляции в CI, тестах и у агентов)"
+            }
+        ]
+    },
     {
         "version": "2026.5.1",
         "date": "6 мая 2026",