@pachca/cli 2026.7.2 → 2026.8.1

package/dist/data/workflows.json

@@ -160,6 +160,10 @@
             {
                 "description": "Если в ответе `meta.paginate.next_page` — пройди по страницам через `--cursor`",
                 "command": "pachca threads list --last-message-at-after=2026-05-19T00:00:00.000Z --cursor=<next_page>"
+            },
+            {
+                "description": "Для каждого треда возьми `chat_id` и подтяни сообщения",
+                "command": "pachca messages list --chat-id=<thread.chat_id>"
             }
         ]
     },
@@ -366,7 +370,8 @@
         "steps": [
             {
                 "description": "Получи чаты без активности с нужной даты",
-                "command": "pachca chats list --last-message-at-before=<порог> --all"
+                "command": "pachca chats list --last-message-at-before=<порог> --all",
+                "notes": "Архивные чаты в выдачу не попадают, поэтому отсеивать уже заархивированные не нужно. Чтобы получить их вместе с активными, добавь `--archived` и смотри поле `archived` каждого чата"
             },
             {
                 "description": "Для каждого чата: архивируй",

package/dist/help.js

@@ -0,0 +1,21 @@
+import { Help } from '@oclif/core';
+/**
+ * Root help with a footer pointing at the web documentation.
+ *
+ * Terminal help is necessarily terse — it lists commands and flags, not
+ * scenarios. Somebody who did not find what they needed has nowhere to go from
+ * here unless we say where the long-form version lives.
+ *
+ * The footer goes after the command list, not before it: the end of the output
+ * is where the eye rests, and it is the last thing left on screen after a long
+ * list scrolls past.
+ */
+export default class PachcaHelp extends Help {
+    async showRootHelp() {
+        await super.showRootHelp();
+        this.log('ДОКУМЕНТАЦИЯ');
+        this.log('  Руководства и справочник API  https://dev.pachca.com');
+        this.log('  Сценарии в терминале          pachca guide');
+        this.log('');
+    }
+}

package/dist/hooks/command-not-found.js

@@ -34,7 +34,7 @@ const hook = async function (opts) {
         outputError(errorObj, 'json');
     }
     else {
-        process.stderr.write(`✗ Команда не найдена: ${commandId.replace(/:/g, ' ')}\n`);
+        process.stderr.write(`✗ Команда не найдена: ${commandId.replace(/:/g, ' ')}.\n`);
         if (suggestions.length > 0) {
             process.stderr.write(`\n  Возможно, вы имели в виду:\n`);
             for (const s of suggestions) {

package/dist/hooks/init.js

@@ -5,6 +5,7 @@ import { spawn } from 'node:child_process';
 import semver from 'semver';
 import ansis from 'ansis';
 import { getDefaults, resolveToken, TokenNotFoundError, ProfileNotFoundError, } from '../profiles.js';
+import { ensureFreshToken, isSessionExpired } from '../token-refresh.js';
 import { outputError } from '../output.js';
 import { defaultOutputFormat, isInteractive } from '../utils.js';
 /**
@@ -127,23 +128,51 @@ const hook = async function (opts) {
     const argvToken = tokenIdx !== -1 ? process.argv[tokenIdx + 1] : undefined;
     const profileIdx = process.argv.indexOf('--profile');
     const argvProfile = profileIdx !== -1 ? process.argv[profileIdx + 1] : undefined;
-    // Verify auth exists
+    // Verify auth exists, and renew an OAuth token that is about to run out.
+    // An OAuth session lives an hour, so without this a long agent run would lose
+    // access halfway through.
     try {
         const { profileName, profile } = resolveToken({ token: argvToken, profile: argvProfile });
+        if (profileName && profile) {
+            try {
+                await ensureFreshToken(profileName, profile);
+            }
+            catch (error) {
+                // A network hiccup during refresh is not worth blocking on: the command
+                // runs with the current token and reports the real API error itself.
+                if (!isSessionExpired(error))
+                    return;
+                const format = resolveOutputFromArgv();
+                if (format === 'json' || !process.stderr.isTTY) {
+                    outputError({
+                        error: 'Session expired',
+                        type: 'PACHCA_AUTH_ERROR',
+                        code: null,
+                        hint: 'pachca auth login',
+                    }, format);
+                }
+                else {
+                    process.stderr.write(`✗ Срок входа истёк. Войдите заново:\n\n`);
+                    process.stderr.write(`    pachca auth login\n`);
+                }
+                process.exit(3);
+            }
+        }
     }
     catch (error) {
         if (error instanceof TokenNotFoundError) {
             const format = resolveOutputFromArgv();
             if (format === 'json' || !process.stderr.isTTY) {
-                outputError({ error: 'Token not found', type: 'PACHCA_AUTH_ERROR', code: null, hint: 'pachca auth login --token <your-token>' }, format);
+                outputError({ error: 'Token not found', type: 'PACHCA_AUTH_ERROR', code: null, hint: 'pachca auth login, or set PACHCA_TOKEN' }, format);
             }
             else {
                 process.stderr.write(`✗ Токен не найден. Войдите в аккаунт:\n\n`);
-                process.stderr.write(`  Интерактивно (человек):\n`);
+                process.stderr.write(`  Вход через браузер:\n`);
                 process.stderr.write(`    pachca auth login\n\n`);
-                process.stderr.write(`  Неинтерактивно (агент, CI):\n`);
-                process.stderr.write(`    pachca auth login --token <ваш токен>\n\n`);
-                process.stderr.write(`  Получить токен: https://dev.pachca.com/guides/authorization\n`);
+                process.stderr.write(`  Готовым токеном (агент, CI):\n`);
+                process.stderr.write(`    pachca auth login --token <ваш токен>\n`);
+                process.stderr.write(`    либо переменная окружения PACHCA_TOKEN — без входа вообще\n\n`);
+                process.stderr.write(`  Получить токен: https://dev.pachca.com/api/authorization\n`);
             }
             process.exit(3);
         }

package/dist/lib/manifest.js

@@ -18,12 +18,23 @@ export function listCommandEntries(commands) {
     }));
 }
 /** `pachca introspect <command>` — full metadata for one command. */
-export function normalizeCommand(commandId, cmdMeta, baseFlagNames) {
+export function normalizeCommand(commandId, cmdMeta, baseFlagNames, baseFlagDescriptions) {
     const requiredFlagNames = new Set(cmdMeta.requiredFlags || []);
+    // Global flags are documented once in their own table, so they are dropped
+    // here. But a command may redefine one with a different meaning — `auth login`
+    // turns `--token` into "log in with this ready token" and `--profile` into
+    // "name of the profile to create". Those belong on the command: keep a
+    // base-named flag whenever its description differs from the global one.
+    const overridesBaseFlag = (name, meta) => {
+        const baseDescription = baseFlagDescriptions?.get(name);
+        if (baseDescription === undefined)
+            return false;
+        return (meta.description || '') !== baseDescription;
+    };
     const flagsMeta = cmdMeta.flags;
     const flags = flagsMeta
         ? Object.entries(flagsMeta)
-            .filter(([name]) => !baseFlagNames.has(name))
+            .filter(([name, meta]) => !baseFlagNames.has(name) || overridesBaseFlag(name, meta))
             .map(([name, meta]) => ({
             name,
             type: (meta.type || 'string'),
@@ -57,7 +68,7 @@ export function normalizeCommand(commandId, cmdMeta, baseFlagNames) {
  * e.g. "messages:create" → "messages"; "doctor" → "doctor"). Used by the
  * build-time emitter for the docs Commands page.
  */
-export function groupCommandsBySection(commands, baseFlagNames) {
+export function groupCommandsBySection(commands, baseFlagNames, baseFlagDescriptions) {
     // Collect backward-compat hidden aliases (old command ids kept working after an IA rename).
     // oclif registers them as resolvable command entries, but they must NOT appear in docs/help —
     // only the new canonical command names are shown.
@@ -71,7 +82,7 @@ export function groupCommandsBySection(commands, baseFlagNames) {
         if (hiddenAliasIds.has(id))
             continue; // hidden backward-compat alias — keep it out of docs/help
         const section = id.includes(':') ? id.split(':')[0] : id;
-        const normalized = normalizeCommand(id, meta, baseFlagNames);
+        const normalized = normalizeCommand(id, meta, baseFlagNames, baseFlagDescriptions);
         if (!bySection.has(section))
             bySection.set(section, []);
         bySection.get(section).push(normalized);

package/dist/oauth.js

@@ -0,0 +1,231 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { getBaseUrl } from './client.js';
+/** Uses the global timer on purpose: `node:timers/promises` is not fakeable in tests. */
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * OAuth device authorization grant (RFC 8628) against Pachca.
+ *
+ * The CLI is a public client: it ships no secret and identifies itself with a
+ * fixed `client_id`. Protection comes from the code never leaving the user's
+ * own screen — see `printDeviceInstructions` in `commands/auth/login.ts`.
+ */
+export const CLI_CLIENT_ID = 'pachca_cli';
+const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** Backend enforces a floor of 5 seconds between polls. */
+const MIN_POLL_INTERVAL_SECONDS = 5;
+/** RFC 8628: on `slow_down` the client raises its interval by 5 seconds. */
+const SLOW_DOWN_STEP_SECONDS = 5;
+export class OAuthError extends Error {
+    code;
+    description;
+    status;
+    constructor(code, description, status) {
+        super(description || code);
+        this.code = code;
+        this.description = description;
+        this.status = status;
+        this.name = 'OAuthError';
+    }
+}
+function oauthUrl(endpoint) {
+    return `${getBaseUrl()}/oauth/${endpoint}`;
+}
+async function postForm(endpoint, params) {
+    let response;
+    try {
+        response = await fetch(oauthUrl(endpoint), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body: new URLSearchParams(params).toString(),
+        });
+    }
+    catch (error) {
+        throw new OAuthError('network_error', error.message);
+    }
+    // Reading the body is a second trip over the network and fails on its own when
+    // the connection drops mid-response. Outside this guard it surfaced as a raw
+    // TypeError and killed a login that only needed another poll.
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new OAuthError('network_error', error.message);
+    }
+    let body = null;
+    if (text) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = null;
+        }
+    }
+    if (!response.ok) {
+        const record = (body ?? {});
+        const code = typeof record.error === 'string' ? record.error : `http_${response.status}`;
+        const description = typeof record.error_description === 'string' ? record.error_description : undefined;
+        throw new OAuthError(code, description, response.status);
+    }
+    return body;
+}
+/** Step 1 — ask the server for a device code and the code the user types in. */
+export async function requestDeviceCode() {
+    const body = (await postForm('device_authorization', { client_id: CLI_CLIENT_ID }));
+    if (!body?.device_code || !body.user_code || !body.verification_uri) {
+        throw new OAuthError('invalid_response', 'Сервер вернул неполный ответ на запрос кода');
+    }
+    return {
+        device_code: body.device_code,
+        user_code: body.user_code,
+        verification_uri: body.verification_uri,
+        expires_in: body.expires_in ?? 600,
+        interval: Math.max(body.interval ?? MIN_POLL_INTERVAL_SECONDS, MIN_POLL_INTERVAL_SECONDS),
+    };
+}
+async function exchangeDeviceCode(deviceCode) {
+    const body = (await postForm('token', {
+        grant_type: DEVICE_CODE_GRANT,
+        client_id: CLI_CLIENT_ID,
+        device_code: deviceCode,
+    }));
+    if (!body?.access_token) {
+        throw new OAuthError('invalid_response', 'Сервер вернул ответ без токена');
+    }
+    return body;
+}
+/**
+ * Step 2 — poll until the user confirms in the browser.
+ *
+ * `slow_down` and a throttled `429` both mean the same thing to us: back off and
+ * keep waiting. Everything else (`expired_token`, `access_denied`) ends the wait.
+ */
+export async function pollForToken(grant) {
+    let interval = grant.interval;
+    const deadline = Date.now() + grant.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await delay(interval * 1000);
+        try {
+            return await exchangeDeviceCode(grant.device_code);
+        }
+        catch (error) {
+            if (!(error instanceof OAuthError))
+                throw error;
+            if (error.code === 'authorization_pending')
+                continue;
+            if (error.code === 'slow_down' || error.status === 429) {
+                interval += SLOW_DOWN_STEP_SECONDS;
+                continue;
+            }
+            // A blip on one poll is not a failed login: the person is still in the
+            // browser and there are minutes of deadline left. Give up only when the
+            // code actually expires.
+            if (error.code === 'network_error')
+                continue;
+            throw error;
+        }
+    }
+    throw new OAuthError('expired_token', 'Код подтверждения истёк');
+}
+/**
+ * Put out an access token server-side (RFC 7009).
+ *
+ * The endpoint only accepts self-revocation: the same token must arrive both in
+ * the body and as the bearer, and it must belong to the CLI's public client.
+ * Returns false when the server declined, so the caller can say plainly that the
+ * token is gone from this machine but still alive.
+ */
+export async function revokeToken(token) {
+    try {
+        const response = await fetch(oauthUrl('revoke'), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: new URLSearchParams({ token }).toString(),
+        });
+        return response.ok;
+    }
+    catch {
+        // Offline logout is a normal thing to do. The profile still goes away.
+        return false;
+    }
+}
+/** Exchange a stored refresh token for a fresh access token. */
+export async function refreshAccessToken(refreshToken) {
+    const body = (await postForm('token', {
+        grant_type: 'refresh_token',
+        client_id: CLI_CLIENT_ID,
+        refresh_token: refreshToken,
+    }));
+    if (!body?.access_token) {
+        throw new OAuthError('invalid_response', 'Сервер вернул ответ без токена');
+    }
+    return body;
+}
+/**
+ * Copy the confirmation code to the clipboard. Best effort: no clipboard tool is
+ * a normal state on a server, and the code is printed anyway.
+ */
+export function copyToClipboard(text) {
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : process.platform === 'win32'
+            ? [['clip', []]]
+            : [
+                ['wl-copy', []],
+                ['xclip', ['-selection', 'clipboard']],
+                ['xsel', ['--clipboard', '--input']],
+            ];
+    for (const [command, args] of candidates) {
+        try {
+            const result = spawnSync(command, args, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+            if (!result.error && result.status === 0)
+                return true;
+        }
+        catch {
+            // try the next tool
+        }
+    }
+    return false;
+}
+/**
+ * Open the confirmation page. Best effort — the URL is printed either way, and a
+ * headless machine has nothing to open it with.
+ */
+export function openBrowser(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return false;
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => {
+            // no browser on this machine — the printed URL is the fallback
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/profiles.js

@@ -2,6 +2,32 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import * as TOML from 'smol-toml';
+import { deleteSecret, readSecret, writeSecret } from './secret-store.js';
+export function getSecretStorage(profile) {
+    return profile.storage === 'keyring' ? 'keyring' : 'file';
+}
+export function getAuthMethod(profile) {
+    return profile.auth === 'oauth' ? 'oauth' : 'token';
+}
+/** True when the profile holds a refreshable OAuth session. */
+export function isRefreshable(profile) {
+    return getAuthMethod(profile) === 'oauth' && !!profile.refresh_token;
+}
+/**
+ * True when the access token is gone or about to be. The skew keeps a command
+ * from starting with a token that expires while the request is in flight.
+ */
+export function isExpiring(profile, skewSeconds = 120) {
+    if (!profile.expires_at)
+        return false;
+    const expiresAt = Date.parse(profile.expires_at);
+    if (Number.isNaN(expiresAt))
+        return false;
+    return expiresAt - skewSeconds * 1000 <= Date.now();
+}
+export function expiresAtFromNow(expiresInSeconds) {
+    return new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+}
 const CONFIG_FILENAME = 'config.toml';
 function getConfigDir() {
     // C8 — explicit override (highest priority). Guarded: when PACHCA_HOME is
@@ -60,20 +86,106 @@ export function setActiveProfile(name) {
     config.active_profile = name;
     writeConfig(config);
 }
+/**
+ * Put the secret back on a profile read from the config file.
+ *
+ * A keyring-backed profile carries no token on disk, so every read has to go to
+ * the OS store. When the store cannot be read — locked keyring, moved config,
+ * removed entry — the token stays empty and `resolveToken` turns that into a
+ * message the user can act on, rather than an opaque 401 later.
+ */
+function hydrate(name, profile) {
+    if (getSecretStorage(profile) !== 'keyring')
+        return profile;
+    const secret = readSecret(name);
+    return {
+        ...profile,
+        token: secret?.token ?? '',
+        ...(secret?.refresh_token ? { refresh_token: secret.refresh_token } : {}),
+    };
+}
 export function getProfile(name) {
-    const config = readConfig();
-    return config.profiles?.[name];
+    const stored = readConfig().profiles?.[name];
+    return stored ? hydrate(name, stored) : undefined;
 }
+/**
+ * Write a profile, keeping the secret out of the config file when the profile
+ * asked for the OS store.
+ *
+ * A failed keyring write silently downgrades to the file: losing the session
+ * because the store went away between login and now would be worse than storing
+ * a token the way every previous version stored it.
+ */
 export function setProfile(name, profile) {
     const config = readConfig();
     if (!config.profiles) {
         config.profiles = {};
     }
+    if (getSecretStorage(profile) === 'keyring') {
+        const stored = writeSecret(name, {
+            token: profile.token,
+            ...(profile.refresh_token ? { refresh_token: profile.refresh_token } : {}),
+        });
+        if (stored) {
+            const { token: _token, refresh_token: _refresh, ...rest } = profile;
+            config.profiles[name] = { ...rest, token: '', storage: 'keyring' };
+            writeConfig(config);
+            return;
+        }
+        config.profiles[name] = { ...profile, storage: 'file' };
+        writeConfig(config);
+        return;
+    }
+    // Moving the other way (keyring → file) must not leave the old secret behind.
+    const previous = config.profiles[name];
+    if (previous && getSecretStorage(previous) === 'keyring') {
+        deleteSecret(name);
+    }
     config.profiles[name] = profile;
     writeConfig(config);
 }
+/**
+ * Overwrite just the token fields, re-reading the config first: a parallel CLI
+ * process may have written a different profile in the meantime, and a blind
+ * `setProfile` of a stale snapshot would drop its work.
+ */
+export function updateProfileTokens(name, tokens) {
+    const config = readConfig();
+    const profile = config.profiles?.[name];
+    if (!profile)
+        return undefined;
+    profile.auth = 'oauth';
+    profile.token = tokens.token;
+    profile.refresh_token = tokens.refresh_token ?? profile.refresh_token;
+    profile.expires_at = tokens.expires_at ?? profile.expires_at;
+    if (tokens.scopes)
+        profile.scopes = tokens.scopes;
+    // The refreshed pair goes wherever the profile already keeps its secrets, so a
+    // keyring-backed session does not quietly start writing tokens to disk an hour
+    // after login.
+    if (getSecretStorage(profile) === 'keyring') {
+        const refreshed = { ...profile };
+        const stored = writeSecret(name, {
+            token: profile.token,
+            ...(profile.refresh_token ? { refresh_token: profile.refresh_token } : {}),
+        });
+        if (stored) {
+            profile.token = '';
+            delete profile.refresh_token;
+            writeConfig(config);
+            return refreshed;
+        }
+        profile.storage = 'file';
+    }
+    writeConfig(config);
+    return profile;
+}
 export function deleteProfile(name) {
     const config = readConfig();
+    const stored = config.profiles?.[name];
+    if (stored && getSecretStorage(stored) === 'keyring') {
+        deleteSecret(name);
+    }
     if (config.profiles) {
         delete config.profiles[name];
     }
@@ -167,11 +279,31 @@ export function resolveToken(flags) {
     if (!profile) {
         throw new ProfileNotFoundError(profileName);
     }
+    if (!profile.token) {
+        throw new SecretStoreUnavailableError(profileName);
+    }
     return { token: profile.token, profileName, profile };
 }
+/**
+ * Refresh just the cached scope list from the server's answer.
+ *
+ * Deliberately does not touch the secret: the scopes live in the config file for
+ * every profile, keyring-backed or not, so there is nothing to write to the store.
+ */
+export function updateProfileScopes(name, scopes) {
+    const config = readConfig();
+    const profile = config.profiles?.[name];
+    if (!profile)
+        return;
+    profile.scopes = scopes;
+    writeConfig(config);
+}
 export function getConfigFilePath() {
     return getConfigPath();
 }
+export function getConfigDirPath() {
+    return getConfigDir();
+}
 export function getConfigFilePermissions() {
     const configPath = getConfigPath();
     if (!fs.existsSync(configPath))
@@ -195,3 +327,17 @@ export class ProfileNotFoundError extends Error {
         this.name = 'ProfileNotFoundError';
     }
 }
+/**
+ * The profile exists and points at the OS store, but the secret is not there.
+ * Usually a locked keyring or a config copied to another machine — both fixed by
+ * logging in again, which is what the message says.
+ */
+export class SecretStoreUnavailableError extends Error {
+    profileName;
+    constructor(profileName) {
+        super(`Token for profile "${profileName}" is stored in the OS credential store and cannot be read. ` +
+            `Unlock the store, or run: pachca auth login --profile ${profileName}`);
+        this.profileName = profileName;
+        this.name = 'SecretStoreUnavailableError';
+    }
+}