@pachca/cli 2026.10.2 → 2026.10.4

package/dist/help.js

@@ -15,7 +15,6 @@ export default class PachcaHelp extends Help {
         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

@@ -43,7 +43,6 @@ const hook = async function (opts) {
             }
         }
         process.stderr.write(`\n  Все команды: pachca commands\n`);
-        process.stderr.write(`  Помощь по сценариям: pachca guide\n`);
     }
     process.exit(2);
 };

package/dist/hooks/init.js

@@ -4,10 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import semver from 'semver';
 import ansis from 'ansis';
-import { getDefaults, resolveToken, TokenNotFoundError, ProfileNotFoundError, } from '../profiles.js';
+import { getDefaults, profileFlag, resolveToken, TokenNotFoundError, ProfileNotFoundError, } from '../profiles.js';
 import { ensureFreshToken, isSessionExpired } from '../token-refresh.js';
 import { outputError } from '../output.js';
 import { defaultOutputFormat, isInteractive } from '../utils.js';
+import { detectIntrospectMode } from '../api-introspect.js';
 /**
  * Resolve output format from argv before flags are parsed by oclif.
  */
@@ -40,7 +41,6 @@ const SKIP_AUTH = new Set([
     'doctor',
     'autocomplete',
     'commands',
-    'guide',
     'introspect',
     'changelog',
     'upgrade',
@@ -102,6 +102,10 @@ const hook = async function (opts) {
     // Skip auth for exempt commands
     if (SKIP_AUTH.has(commandId))
         return;
+    // `api ls` and `api <METHOD> <path> --describe|--spec|--docs` read the bundled
+    // spec and never call the API, so an agent can study the API before signing in.
+    if (commandId === 'api' && (opts.argv[0] === 'ls' || detectIntrospectMode(opts.argv)))
+        return;
     // Skip auth when --help, --version, or --dry-run flag is passed
     if (process.argv.includes('--help') || process.argv.includes('-h'))
         return;
@@ -142,18 +146,22 @@ const hook = async function (opts) {
                 // runs with the current token and reports the real API error itself.
                 if (!isSessionExpired(error))
                     return;
+                // The server no longer renews this login: it was revoked (in the «Токены CLI»
+                // list, by an admin) or ran out. Name the profile, like the 401 hint does,
+                // so the command can be pasted as is.
+                const relogin = `pachca auth login${profileFlag(profileName)}`;
                 const format = resolveOutputFromArgv();
                 if (format === 'json' || !process.stderr.isTTY) {
                     outputError({
                         error: 'Session expired',
                         type: 'PACHCA_AUTH_ERROR',
                         code: null,
-                        hint: 'pachca auth login',
+                        hint: relogin,
                     }, format);
                 }
                 else {
-                    process.stderr.write(`✗ Срок входа истёк. Войдите заново:\n\n`);
-                    process.stderr.write(`    pachca auth login\n`);
+                    process.stderr.write(`✗ Вход завершён или отозван. Войдите заново:\n\n`);
+                    process.stderr.write(`    ${relogin}\n`);
                 }
                 process.exit(3);
             }

package/dist/lib/flags.js

@@ -0,0 +1,25 @@
+import { Errors, Flags } from '@oclif/core';
+/**
+ * Flags for body fields the spec marks nullable.
+ *
+ * In such a field `null` carries meaning of its own: `--kind null` deletes a
+ * bot's incoming webhook, `--parent-message-id null` takes the reply off a
+ * draft. A plain string flag would send the text "null", which the API refuses,
+ * and an integer flag would not accept the word at all. These flags read the
+ * literal `null` as JSON null and pass every other value through as before.
+ */
+export const nullableString = Flags.custom({
+    async parse(input) {
+        return input === 'null' ? null : input;
+    },
+});
+export const nullableInteger = Flags.custom({
+    async parse(input) {
+        if (input === 'null')
+            return null;
+        if (!/^-?\d+$/.test(input)) {
+            throw new Errors.CLIError(`Expected an integer or null but received: ${input}`);
+        }
+        return Number.parseInt(input, 10);
+    },
+});

package/dist/oauth.js

@@ -12,7 +12,8 @@ function delay(ms) {
  *
  * 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`.
+ * own screen: the CLI prints the address and the code apart and never a link
+ * with the code in it.
  */
 export const CLI_CLIENT_ID = 'pachca_cli';
 const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
@@ -162,10 +163,15 @@ export async function pollForToken(grant) {
 /**
  * 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.
+ * The endpoint only accepts self-revocation: the same access token must arrive
+ * both in the body and as the bearer, and it must belong to the CLI's public
+ * client. A refresh token is refused here: the CLI does not know the client's
+ * real `client_id`, and self-revocation compares the body with the bearer.
+ *
+ * `true` proves the revocation only for a live token. The server answers `200`
+ * to an expired one too, yet leaves its record and refresh token untouched.
+ * Pass a token known to be live — `revokeSession` in `token-refresh.ts` does.
+ * Returns false when the server declined or could not be reached.
  */
 export async function revokeToken(token) {
     try {

package/dist/profiles.js

@@ -9,6 +9,10 @@ export function getSecretStorage(profile) {
 export function getAuthMethod(profile) {
     return profile.auth === 'oauth' ? 'oauth' : 'token';
 }
+/** ` --profile <name>` to paste into a suggested command; empty for the default profile. */
+export function profileFlag(profileName) {
+    return !profileName || profileName === 'default' ? '' : ` --profile ${profileName}`;
+}
 /** True when the profile holds a refreshable OAuth session. */
 export function isRefreshable(profile) {
     return getAuthMethod(profile) === 'oauth' && !!profile.refresh_token;
@@ -262,19 +266,20 @@ export function setConfigValue(key, value) {
  * command silently wrote to the wrong workspace with the wrong token.
  */
 export function resolveToken(flags) {
+    const source = tokenSource(flags);
     // 1. --token flag (highest priority)
-    if (flags.token) {
+    if (source.kind === 'flag') {
         return { token: flags.token };
     }
     // 2. PACHCA_TOKEN env — unless a profile was named explicitly
-    if (!flags.profile && process.env.PACHCA_TOKEN) {
+    if (source.kind === 'env') {
         return { token: process.env.PACHCA_TOKEN };
     }
     // 3. --profile flag or PACHCA_PROFILE env
-    const profileName = flags.profile || process.env.PACHCA_PROFILE || getActiveProfile();
-    if (!profileName) {
+    if (source.kind === 'none') {
         throw new TokenNotFoundError();
     }
+    const { profileName } = source;
     const profile = getProfile(profileName);
     if (!profile) {
         throw new ProfileNotFoundError(profileName);
@@ -284,6 +289,19 @@ export function resolveToken(flags) {
     }
     return { token: profile.token, profileName, profile };
 }
+export function tokenSource(flags) {
+    if (flags.token)
+        return { kind: 'flag' };
+    if (!flags.profile && process.env.PACHCA_TOKEN)
+        return { kind: 'env' };
+    if (flags.profile)
+        return { kind: 'profile', profileName: flags.profile, via: '--profile' };
+    if (process.env.PACHCA_PROFILE) {
+        return { kind: 'profile', profileName: process.env.PACHCA_PROFILE, via: 'PACHCA_PROFILE' };
+    }
+    const active = getActiveProfile();
+    return active ? { kind: 'profile', profileName: active, via: 'active_profile' } : { kind: 'none' };
+}
 /**
  * Refresh just the cached scope list from the server's answer.
  *

package/dist/token-refresh.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getConfigDirPath, getProfile, isExpiring, isRefreshable, updateProfileTokens, expiresAtFromNow, } from './profiles.js';
-import { OAuthError, refreshAccessToken } from './oauth.js';
+import { OAuthError, refreshAccessToken, revokeToken } from './oauth.js';
 const LOCK_FILENAME = 'refresh.lock';
 /** A lock older than this belonged to a process that died mid-refresh. */
 const LOCK_STALE_MS = 30_000;
@@ -65,46 +65,46 @@ function releaseLock(fd) {
  * Returns the profile to use. Throws `OAuthError` only when the session is truly
  * dead and the user has to log in again.
  */
-export async function ensureFreshToken(profileName, profile) {
-    if (!isRefreshable(profile) || !isExpiring(profile))
+export async function ensureFreshToken(profileName, profile, needsRefresh = isExpiring) {
+    if (!isRefreshable(profile) || !needsRefresh(profile))
         return profile;
     const fd = acquireLock();
     if (fd === null) {
-        const waited = await waitForOtherProcess(profileName);
+        const waited = await waitForOtherProcess(profileName, needsRefresh);
         if (waited)
             return waited;
         // The holder gave up or is stuck — refresh ourselves rather than fail.
-        return refreshAndStore(profileName, profile);
+        return refreshAndStore(profileName, profile, needsRefresh);
     }
     try {
         // Re-read: the previous holder may have refreshed while we queued for the lock.
         const current = getProfile(profileName) ?? profile;
-        if (!isExpiring(current))
+        if (!needsRefresh(current))
             return current;
-        return await refreshAndStore(profileName, current);
+        return await refreshAndStore(profileName, current, needsRefresh);
     }
     finally {
         releaseLock(fd);
     }
 }
-async function waitForOtherProcess(profileName) {
+async function waitForOtherProcess(profileName, needsRefresh) {
     const deadline = Date.now() + LOCK_WAIT_MS;
     while (Date.now() < deadline) {
         await sleep(LOCK_POLL_MS);
         const current = getProfile(profileName);
-        if (current && !isExpiring(current))
+        if (current && !needsRefresh(current))
             return current;
         if (!fs.existsSync(lockPath())) {
             // The holder finished between our read of the profile and this check. Look
             // once more before refreshing ourselves: their new token is already on disk,
             // and ours has just been spent.
             const after = getProfile(profileName);
-            return after && !isExpiring(after) ? after : undefined;
+            return after && !needsRefresh(after) ? after : undefined;
         }
     }
     return undefined;
 }
-async function refreshAndStore(profileName, profile) {
+async function refreshAndStore(profileName, profile, needsRefresh) {
     let grant;
     try {
         grant = await refreshAccessToken(profile.refresh_token);
@@ -116,21 +116,68 @@ async function refreshAndStore(profileName, profile) {
         // Without this check a lost race logs the user out for no reason.
         if (error instanceof OAuthError && error.code === 'invalid_grant') {
             const current = getProfile(profileName);
-            if (current?.token && !isExpiring(current))
+            if (current?.token && !needsRefresh(current))
                 return current;
         }
         throw error;
     }
-    const updated = updateProfileTokens(profileName, {
+    const tokens = {
         token: grant.access_token,
         refresh_token: grant.refresh_token,
         expires_at: grant.expires_in ? expiresAtFromNow(grant.expires_in) : undefined,
         scopes: grant.scope ? grant.scope.split(' ').filter(Boolean) : undefined,
+    };
+    const updated = updateProfileTokens(profileName, tokens);
+    // The profile can vanish from the config mid-refresh. The new token is still
+    // the one in force: hand it back with its expiry so a caller can revoke it.
+    return (updated ?? {
+        ...profile,
+        token: tokens.token,
+        refresh_token: tokens.refresh_token ?? profile.refresh_token,
+        expires_at: tokens.expires_at ?? profile.expires_at,
     });
-    return updated ?? { ...profile, token: grant.access_token };
 }
 /** True when the failure means the session is gone for good, not a hiccup. */
 export function isSessionExpired(error) {
     return (error instanceof OAuthError &&
         ['invalid_grant', 'invalid_request', 'invalid_client', 'unauthorized_client'].includes(error.code));
 }
+/**
+ * True only when the access token will outlive the request about to use it.
+ * Unknown expiry counts as not live: revoking is only proof when the token is.
+ */
+function hasLiveToken(profile) {
+    if (!profile.token || !profile.expires_at)
+        return false;
+    if (Number.isNaN(Date.parse(profile.expires_at)))
+        return false;
+    return !isExpiring(profile);
+}
+/**
+ * Close the profile's OAuth login on the server.
+ *
+ * The revoke endpoint answers `200` even when it skipped the token: an expired
+ * access token is not revocable, so the record stays as it was, refresh token
+ * included, and that refresh token can still mint new access tokens. Revoking
+ * by the refresh token itself is not open to the CLI: self-revocation takes only
+ * the access token that also came as the bearer. So the token sent is always a
+ * live one — refreshed first when the saved one has run out. The refresh retires
+ * the old record on the server, and the revoke then closes the new one.
+ */
+export async function revokeSession(profileName, profile) {
+    let current;
+    try {
+        current = await ensureFreshToken(profileName, profile, (p) => !hasLiveToken(p));
+    }
+    catch (error) {
+        // `invalid_grant` on refresh: the token is revoked or gone on the server.
+        if (error instanceof OAuthError && error.code === 'invalid_grant')
+            return 'closed';
+        return 'open';
+    }
+    // No refresh token and the access token has run out, or it never came back
+    // from the OS store: there is nothing to revoke with that would prove anything.
+    if (!hasLiveToken(current))
+        return 'open';
+    return (await revokeToken(current.token)) ? 'revoked' : 'open';
+}