@pachca/cli 2026.10.1 → 2026.10.3

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

@@ -8,6 +8,7 @@ import { getDefaults, resolveToken, TokenNotFoundError, ProfileNotFoundError, }
 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;

package/dist/oauth.js

@@ -162,10 +162,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/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';
+}