adapty 0.8.9 → 0.9.0

package/dist/cli/commands/migrations/unuse/command.js

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../../base/base-command.js';
+import { openCurrentMigration } from '../../../context/migration/index.js';
+import { envSuppliesMigration } from '../../../views/migrations/notices.js';
+export default class Unuse extends BaseCommand {
+    static summary = 'Clear the saved migration selection (no network)';
+    static description = [
+        'Works without authentication, including when the saved context is malformed.',
+        'ADAPTY_MIGRATION remains active until you unset it in your shell.',
+    ].join('\n');
+    static examples = ['<%= config.bin %> migrations unuse'];
+    async run() {
+        await this.parse(Unuse);
+        // No session: removing a record does not depend on whose it is, or on being logged in.
+        const current = openCurrentMigration({ configDir: this.config.configDir });
+        await current.clear();
+        if (current.overridden) {
+            process.stderr.write(envSuppliesMigration);
+        }
+        const result = { currentMigrationId: null };
+        this.render(result, () => 'Saved migration selection cleared.');
+        return result;
+    }
+}

package/dist/cli/commands/migrations/unuse/index.d.ts

@@ -0,0 +1 @@
+export { default } from './command.js';

package/dist/cli/commands/migrations/unuse/index.js

@@ -0,0 +1 @@
+export { default } from './command.js';

package/dist/cli/commands/migrations/use/command.d.ts

@@ -0,0 +1,14 @@
+import { MigrationCommand } from '../../../base/adapty/index.js';
+type Result = {
+    currentMigrationId: string;
+};
+export default class Use extends MigrationCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<Result>;
+}
+export {};

package/dist/cli/commands/migrations/use/command.js

@@ -0,0 +1,24 @@
+import { MigrationCommand } from '../../../base/adapty/index.js';
+import { migrationArgs } from '../../../input/migration.js';
+import { envOverridesSelection } from '../../../views/migrations/notices.js';
+export default class Use extends MigrationCommand {
+    static summary = 'Save the current migration after verifying access';
+    static description = [
+        'Select a migration for the current token. This does not start or modify the migration.',
+        'Completed, canceled and failed migrations can also be selected for inspection.',
+        'ADAPTY_MIGRATION overrides the saved selection until you unset it in your shell.',
+    ].join('\n');
+    static examples = ['<%= config.bin %> migrations use mig_7x2'];
+    static args = { ...migrationArgs };
+    async run() {
+        const { args } = await this.parse(Use);
+        const { migration } = await this.adapty.migrations.get(args.id);
+        await this.currentMigration.set(migration.id);
+        if (this.currentMigration.overridden) {
+            process.stderr.write(envOverridesSelection);
+        }
+        const result = { currentMigrationId: migration.id };
+        this.render(result, value => `Current migration: ${value.currentMigrationId}`);
+        return result;
+    }
+}

package/dist/cli/commands/migrations/use/index.d.ts

@@ -0,0 +1 @@
+export { default } from './command.js';

package/dist/cli/commands/migrations/use/index.js

@@ -0,0 +1 @@
+export { default } from './command.js';

package/dist/cli/context/migration/current.d.ts

@@ -0,0 +1,32 @@
+import type { MigrationSession } from './model.js';
+import type { MigrationSelection } from './resolve.js';
+/**
+ * Everything a command may ask about "which migration am I on", behind verbs. The file, the token
+ * that scopes it and ADAPTY_MIGRATION are put together here, once, and not in every `run()`.
+ */
+export type CurrentMigration = {
+    /** Unconditional: `unuse` and `logout` remove a record they may not even be able to read. */
+    clear(): Promise<void>;
+    /**
+     * Only if the record belongs to this token: another token's selection stays usable — with
+     * ADAPTY_TOKEN set, the file may hold a different, still-valid one. The check is not atomic,
+     * and nothing here can make it so: a concurrent `login` landing between the read and the
+     * remove loses its fresh record. That costs one more `adapty auth login`, never a selection
+     * left behind for a dead token, so the file keeps the same last-writer-wins rule as `save`.
+     */
+    clearFor(token: string): Promise<void>;
+    get(explicit?: string): Promise<MigrationSelection | undefined>;
+    /** ADAPTY_MIGRATION is set, so neither a save nor a clear changes what the next command uses. */
+    readonly overridden: boolean;
+    readonly path: string;
+    require(explicit?: string): Promise<MigrationSelection>;
+    set(id: string): Promise<void>;
+};
+export type CurrentMigrationOptions = {
+    configDir: string;
+    /** The one place ADAPTY_MIGRATION is read; a parameter so a test needs no global. */
+    env?: NodeJS.ProcessEnv | undefined;
+    /** Absent for `unuse`, tokenless for `current`: neither needs credentials to answer. */
+    session?: MigrationSession | undefined;
+};
+export declare const openCurrentMigration: (options: CurrentMigrationOptions) => CurrentMigration;

package/dist/cli/context/migration/current.js

@@ -0,0 +1,30 @@
+import { AuthRequiredError } from '../../../sdk/core/errors.js';
+import { createMigrationContext, migrationTokenFingerprint } from './model.js';
+import { requireMigrationSelection, resolveMigrationSelection } from './resolve.js';
+import { createMigrationContextStore } from './store.js';
+export const openCurrentMigration = (options) => {
+    const store = createMigrationContextStore(options.configDir);
+    const session = options.session ?? {};
+    const envMigration = (options.env ?? process.env).ADAPTY_MIGRATION;
+    const sources = { envMigration, session, store };
+    return {
+        overridden: envMigration !== undefined && envMigration !== '',
+        path: store.path,
+        clear: () => store.clear(),
+        clearFor: async (token) => {
+            const stored = await store.load();
+            if (stored?.tokenFingerprint === migrationTokenFingerprint(token)) {
+                await store.clear();
+            }
+        },
+        get: explicit => resolveMigrationSelection({ ...sources, migration: explicit }),
+        require: explicit => requireMigrationSelection({ ...sources, migration: explicit }),
+        set: async (id) => {
+            const { token } = session;
+            if (token === undefined || token === '') {
+                throw new AuthRequiredError('missing');
+            }
+            await store.save(createMigrationContext({ ...session, token }, id));
+        },
+    };
+};

package/dist/cli/context/migration/index.d.ts

@@ -0,0 +1,4 @@
+export { openCurrentMigration } from './current.js';
+export { validateMigrationId } from './model.js';
+export type { CurrentMigration } from './current.js';
+export type { MigrationSelection } from './resolve.js';

package/dist/cli/context/migration/index.js

@@ -0,0 +1,2 @@
+export { openCurrentMigration } from './current.js';
+export { validateMigrationId } from './model.js';

package/dist/cli/context/migration/model.d.ts

@@ -0,0 +1,14 @@
+export type MigrationContext = {
+    version: 1;
+    tokenFingerprint: string;
+    currentMigrationId: string;
+};
+export type MigrationSession = {
+    token?: string | undefined;
+};
+export declare const migrationTokenFingerprint: (token: string) => string;
+export declare const validateMigrationId: (id: string) => string;
+export declare const createMigrationContext: (session: MigrationSession & {
+    token: string;
+}, currentMigrationId: string) => MigrationContext;
+export declare const isMigrationContext: (value: unknown) => value is MigrationContext;

package/dist/cli/context/migration/model.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+import { CliError, exitCode } from '../../errors.js';
+export const migrationTokenFingerprint = (token) => {
+    return createHash('sha256').update(token).digest('hex');
+};
+export const validateMigrationId = (id) => {
+    if (id.trim() === '') {
+        throw new CliError('Migration ID must not be empty or whitespace.', exitCode.usage, 'migration_required');
+    }
+    return id;
+};
+export const createMigrationContext = (session, currentMigrationId) => ({
+    version: 1,
+    tokenFingerprint: migrationTokenFingerprint(session.token),
+    currentMigrationId: validateMigrationId(currentMigrationId),
+});
+const isNonBlankString = (value) => {
+    return typeof value === 'string' && value.trim() !== '';
+};
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+export const isMigrationContext = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.version === 1
+        && typeof record.tokenFingerprint === 'string'
+        && SHA256_HEX.test(record.tokenFingerprint)
+        && isNonBlankString(record.currentMigrationId);
+};

package/dist/cli/context/migration/resolve.d.ts

@@ -0,0 +1,16 @@
+import type { MigrationSession } from './model.js';
+import type { MigrationContextStore } from './store.js';
+export type MigrationSelection = {
+    currentMigrationId: string;
+    source: 'flag' | 'env' | 'context';
+};
+type ResolutionOptions = {
+    migration?: string | undefined;
+    envMigration?: string | undefined;
+    session: MigrationSession;
+    store: Pick<MigrationContextStore, 'load'>;
+};
+/** Local-only and lazy: an explicit ID never reads context, even if it is broken. */
+export declare const resolveMigrationSelection: (options: ResolutionOptions) => Promise<MigrationSelection | undefined>;
+export declare const requireMigrationSelection: (options: ResolutionOptions) => Promise<MigrationSelection>;
+export {};

package/dist/cli/context/migration/resolve.js

@@ -0,0 +1,26 @@
+import { CliError, exitCode } from '../../errors.js';
+import { migrationTokenFingerprint, validateMigrationId } from './model.js';
+/** Local-only and lazy: an explicit ID never reads context, even if it is broken. */
+export const resolveMigrationSelection = async (options) => {
+    if (options.migration !== undefined) {
+        return { currentMigrationId: validateMigrationId(options.migration), source: 'flag' };
+    }
+    if (options.envMigration !== undefined && options.envMigration !== '') {
+        return { currentMigrationId: validateMigrationId(options.envMigration), source: 'env' };
+    }
+    if (options.session.token === undefined || options.session.token === '') {
+        return undefined;
+    }
+    const context = await options.store.load();
+    if (context?.tokenFingerprint !== migrationTokenFingerprint(options.session.token)) {
+        return undefined;
+    }
+    return { currentMigrationId: context.currentMigrationId, source: 'context' };
+};
+export const requireMigrationSelection = async (options) => {
+    const selection = await resolveMigrationSelection(options);
+    if (selection === undefined) {
+        throw new CliError('No migration selected. Run `adapty migrations list`, then `adapty migrations use <id>`, or supply `-m <id>`.', exitCode.usage, 'migration_required');
+    }
+    return selection;
+};

package/dist/cli/context/migration/store.d.ts

@@ -0,0 +1,9 @@
+import type { MigrationContext } from './model.js';
+export type MigrationContextStore = {
+    readonly path: string;
+    load(): Promise<MigrationContext | undefined>;
+    save(context: MigrationContext): Promise<void>;
+    clear(): Promise<void>;
+};
+/** CLI-owned state, separate from credentials. Concurrent mutations are applied in call order. */
+export declare const createMigrationContextStore: (dir: string) => MigrationContextStore;

package/dist/cli/context/migration/store.js

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, errorCode } from '../../errors.js';
+import { isMigrationContext } from './model.js';
+const REPLACE = 'Run `adapty migrations unuse` to remove it or `adapty migrations use <id>` to replace it.';
+/**
+ * Two stable codes, but not one text: a malformed record, a denied read and a full disk are fixed
+ * in three different places, and the errno is what says which. The original travels as `cause`
+ * rather than in the message, because that message may quote the record — and the record carries a
+ * token fingerprint.
+ */
+const contextError = (path, failure, cause) => {
+    const errno = errorCode(cause);
+    const file = errno === undefined ? path : `${path} (${errno})`;
+    const messages = {
+        invalid: `Invalid migration context: ${path}. ${REPLACE}`,
+        read: `Could not read migration context: ${file}. Check its permissions and ownership. ${REPLACE}`,
+        remove: `Could not remove migration context: ${file}. Check its permissions and ownership, or remove the file yourself.`,
+        write: `Could not save migration context: ${file}. Check the permissions and free space of its directory; the previous selection is unchanged.`,
+    };
+    return new CliError(messages[failure], 1, failure === 'invalid' ? 'migration_context_invalid' : 'migration_context_io', { cause });
+};
+const isMissing = (error) => {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+};
+/** CLI-owned state, separate from credentials. Concurrent mutations are applied in call order. */
+export const createMigrationContextStore = (dir) => {
+    const path = join(dir, 'context.json');
+    let mutations = Promise.resolve();
+    const mutate = (operation) => {
+        const result = mutations.then(operation);
+        // A failed mutation must not prevent later calls from running.
+        mutations = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const store = {
+        path,
+        async load() {
+            let raw;
+            try {
+                raw = await fs.readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    return undefined;
+                }
+                throw contextError(path, 'read', error);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                throw contextError(path, 'invalid', error);
+            }
+            if (!isMigrationContext(parsed)) {
+                throw contextError(path, 'invalid');
+            }
+            return parsed;
+        },
+        async save(context) {
+            if (!isMigrationContext(context)) {
+                throw contextError(path, 'invalid');
+            }
+            return mutate(async () => {
+                const temporary = join(dir, `.context-${randomUUID()}.tmp`);
+                try {
+                    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+                    await fs.writeFile(temporary, `${JSON.stringify(context, null, 2)}\n`, {
+                        encoding: 'utf8', flag: 'wx', mode: 0o600,
+                    });
+                    await fs.rename(temporary, path);
+                }
+                catch (error) {
+                    // Never remove the destination on failure: it may hold a previous selection.
+                    try {
+                        await fs.rm(temporary, { force: true });
+                    }
+                    catch {
+                        // Preserve the context-specific error if cleanup also fails.
+                    }
+                    throw contextError(path, 'write', error);
+                }
+            });
+        },
+        async clear() {
+            return mutate(async () => {
+                try {
+                    await fs.rm(path, { force: true });
+                }
+                catch (error) {
+                    throw contextError(path, 'remove', error);
+                }
+            });
+        },
+    };
+    return store;
+};

package/dist/cli/errors/wizard.d.ts

@@ -0,0 +1,5 @@
+import type { WizardError } from '../../sdk/adapty/migrations/index.js';
+export type WizardDiagnostics = Partial<Omit<WizardError['error'], 'code' | 'message'>>;
+/** Copy only known, correctly typed diagnostics from the untrusted response body. */
+export declare const wizardDiagnostics: (body: unknown) => WizardDiagnostics;
+export declare const wizardErrorMessage: (message: string, diagnostics: WizardDiagnostics) => string;

package/dist/cli/errors/wizard.js

@@ -0,0 +1,54 @@
+const isRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/** Copy only known, correctly typed diagnostics from the untrusted response body. */
+export const wizardDiagnostics = (body) => {
+    if (!isRecord(body) || (typeof body.error_code === 'string' && body.error_code !== '')) {
+        return {};
+    }
+    const error = body.error;
+    if (!isRecord(error) || typeof error.code !== 'string' || error.code === '') {
+        return {};
+    }
+    const diagnostics = {};
+    for (const key of ['detail', 'next_step']) {
+        if (typeof error[key] === 'string' || error[key] === null) {
+            diagnostics[key] = error[key];
+        }
+    }
+    if (typeof error.retryable === 'boolean') {
+        diagnostics.retryable = error.retryable;
+    }
+    const delay = error.retry_after_seconds;
+    if (delay === null || (typeof delay === 'number' && Number.isFinite(delay) && delay >= 0)) {
+        diagnostics.retry_after_seconds = delay;
+    }
+    if (typeof error.request_id === 'string') {
+        diagnostics.request_id = error.request_id;
+    }
+    if (Array.isArray(error.fields)) {
+        diagnostics.fields = [];
+        for (const field of error.fields) {
+            if (isRecord(field) && typeof field.path === 'string' && typeof field.message === 'string') {
+                diagnostics.fields.push({ path: field.path, message: field.message });
+            }
+        }
+    }
+    return diagnostics;
+};
+export const wizardErrorMessage = (message, diagnostics) => {
+    const lines = [message];
+    if (diagnostics.detail && diagnostics.detail !== message) {
+        lines.push(diagnostics.detail);
+    }
+    if (diagnostics.fields?.length) {
+        lines.push('', ...diagnostics.fields.map(field => `  ${field.path}: ${field.message}`));
+    }
+    if (diagnostics.next_step) {
+        lines.push('', `Next step: ${diagnostics.next_step}`);
+    }
+    if (diagnostics.request_id) {
+        lines.push(`Request ID: ${diagnostics.request_id}`);
+    }
+    return lines.join('\n');
+};

package/dist/cli/errors.d.ts

@@ -1,30 +1,46 @@
 import { Errors } from '@oclif/core';
+import type { WizardDiagnostics } from './errors/wizard.js';
 /**
  * Exit codes are the adapter's business: sdk errors carry none.
  *   2  usage     — the input is wrong (oclif's own parse errors exit 2 as well)
  *   3  auth      — no token, an expired one, or a refused authorization
  *   4  api       — the server rejected a well-formed request
  *   5  network   — the server was never reached
+ *   6  confirm   — nothing was done: the action changes production data and wants --yes
  * 130  cancelled — Ctrl+C, by the shell convention 128 + SIGINT
  */
 export declare const exitCode: {
     readonly api: 4;
     readonly auth: 3;
     readonly cancelled: 130;
+    readonly confirmRequired: 6;
     readonly network: 5;
     readonly usage: 2;
 };
 /** HTTP status is separate from the process exit code. Snake_case fields preserve the old JSON contract. */
-export type ErrorJson = {
+export type ErrorJson = WizardDiagnostics & {
     code?: string | undefined;
     error_code?: string | undefined;
     errors?: unknown;
     message: string;
-    /** The server's Retry-After in whole seconds, rounded up; absent when the server asked for no wait. */
-    retry_after_seconds?: number | undefined;
+    /**
+     * The server's wait in whole seconds: Retry-After rounded up, else the Wizard envelope's own field,
+     * which says null for no wait. Absent when the server said nothing.
+     */
+    retry_after_seconds?: number | null | undefined;
     status?: number | undefined;
     status_code?: number | undefined;
 };
+export type CliErrorOptions = {
+    /**
+     * The failure this error explains. It is not printed and not serialized: a foreign message may
+     * quote whatever was handed to the syscall, and these paths handle credentials. It travels so
+     * that a stack, a debugger or a test can still reach the original.
+     */
+    cause?: unknown;
+    /** Fields for --json beyond `message` and `code`. */
+    json?: Partial<ErrorJson> | undefined;
+};
 /**
  * oclif takes the exit code from two places: `handle()` reads `oclif.exit`, Command.catch under
  * --json reads `exitCode` and never rethrows. Set one and the other mode exits 1.
@@ -32,7 +48,7 @@ export type ErrorJson = {
 export declare class CliError extends Errors.CLIError {
     readonly exitCode: number;
     readonly json: ErrorJson;
-    constructor(message: string, exit: number, code?: string, data?: Partial<ErrorJson>);
+    constructor(message: string, exit: number, code?: string, options?: CliErrorOptions);
     /**
      * What a command still on oclif's own Command prints under --json, where the error object is
      * serialized as it is: the same `{ message, ... }` a migrated command prints, not its internals.
@@ -44,6 +60,23 @@ export declare class CliError extends Errors.CLIError {
  * json keeps the text as written; oclif prefixes only the human message with the flag's name.
  */
 export declare const usageError: (message: string) => CliError;
+/**
+ * An errno — ENOSPC, EACCES, EROFS — classifies a failure without repeating it. It is the part of
+ * a foreign error that is safe to show: a full disk and a denied write are fixed differently, and
+ * a message that only says "could not access" sends whoever reads it looking in the wrong place.
+ */
+export declare const errorCode: (error: unknown) => string | undefined;
+export type CleanupFailure = {
+    cause: unknown;
+    file: string;
+    reason: string;
+};
+/**
+ * Which files a best-effort cleanup could not finish, and why. Files and settled results are
+ * positional siblings, one per attempt: "could not remove these two" alone leaves the next person
+ * guessing between a permission, a read-only mount and a directory sitting where a file belongs.
+ */
+export declare const describeCleanupFailures: (files: readonly string[], results: readonly PromiseSettledResult<unknown>[]) => CleanupFailure[];
 /**
  * The one place where an sdk error gets a human text and an exit code. No default in the switch:
  * a new kind fails to compile until it is mapped here.

package/dist/cli/errors.js

@@ -1,17 +1,20 @@
 import { Errors } from '@oclif/core';
 import { isSdkError } from '../sdk/core/errors.js';
+import { wizardDiagnostics, wizardErrorMessage } from './errors/wizard.js';
 /**
  * Exit codes are the adapter's business: sdk errors carry none.
  *   2  usage     — the input is wrong (oclif's own parse errors exit 2 as well)
  *   3  auth      — no token, an expired one, or a refused authorization
  *   4  api       — the server rejected a well-formed request
  *   5  network   — the server was never reached
+ *   6  confirm   — nothing was done: the action changes production data and wants --yes
  * 130  cancelled — Ctrl+C, by the shell convention 128 + SIGINT
  */
 export const exitCode = {
     api: 4,
     auth: 3,
     cancelled: 130,
+    confirmRequired: 6,
     network: 5,
     usage: 2,
 };
@@ -22,11 +25,16 @@ export const exitCode = {
 export class CliError extends Errors.CLIError {
     exitCode;
     json;
-    constructor(message, exit, code, data = {}) {
+    constructor(message, exit, code, options = {}) {
         super(message, { exit });
         this.exitCode = exit;
         this.code = code;
-        this.json = { message, code, ...data };
+        this.json = { message, code, ...options.json };
+        // Assigned only when there is one: an own `cause: undefined` would read as "none known"
+        // where none was ever offered.
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
     }
     /**
      * What a command still on oclif's own Command prints under --json, where the error object is
@@ -41,7 +49,43 @@ export class CliError extends Errors.CLIError {
  * json keeps the text as written; oclif prefixes only the human message with the flag's name.
  */
 export const usageError = (message) => new CliError(message, exitCode.usage);
-const cliError = (message, exit, code, data) => new CliError(message, exit, code, data);
+const cliError = (message, exit, code, json) => {
+    return new CliError(message, exit, code, { json });
+};
+/**
+ * An errno — ENOSPC, EACCES, EROFS — classifies a failure without repeating it. It is the part of
+ * a foreign error that is safe to show: a full disk and a denied write are fixed differently, and
+ * a message that only says "could not access" sends whoever reads it looking in the wrong place.
+ */
+export const errorCode = (error) => {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
+};
+/** What a nested failure adds to an error of ours: our own text, or a stranger's errno alone. */
+const describeFailure = (error) => {
+    if (error instanceof CliError || isSdkError(error)) {
+        return error.message;
+    }
+    return errorCode(error) ?? 'unknown error';
+};
+/** `reason` is `any` on the settled result; naming it `unknown` is what keeps it from spreading. */
+const rejectionOf = (result) => {
+    return result?.status === 'rejected' ? result : undefined;
+};
+/**
+ * Which files a best-effort cleanup could not finish, and why. Files and settled results are
+ * positional siblings, one per attempt: "could not remove these two" alone leaves the next person
+ * guessing between a permission, a read-only mount and a directory sitting where a file belongs.
+ */
+export const describeCleanupFailures = (files, results) => {
+    const failures = [];
+    for (const [index, file] of files.entries()) {
+        const rejection = rejectionOf(results[index]);
+        if (rejection) {
+            failures.push({ cause: rejection.reason, file, reason: describeFailure(rejection.reason) });
+        }
+    }
+    return failures;
+};
 /** Issue.path is a camelCase sdk field; the user typed a kebab-case flag. */
 const flagName = (path) => `--${path.replace(/[A-Z]/g, char => `-${char.toLowerCase()}`)}`;
 const describeIssue = (issue) => (issue.path === undefined ? issue.message : `${flagName(issue.path)}: ${issue.message}`);
@@ -51,6 +95,11 @@ const describeIssue = (issue) => (issue.path === undefined ? issue.message : `${
  */
 export const toCliError = (error) => {
     if (!isSdkError(error)) {
+        // Parser errors carry only oclif.exit; JSON handling reads exitCode instead.
+        // Preserve the error instance and its diagnostics, including any explicit non-usage exit.
+        if (error instanceof Errors.CLIError && typeof error.oclif.exit === 'number' && !('exitCode' in error)) {
+            return Object.assign(error, { exitCode: error.oclif.exit });
+        }
         return error instanceof Error ? error : new Error(String(error));
     }
     switch (error.kind) {
@@ -61,10 +110,15 @@ export const toCliError = (error) => {
             const fields = typeof error.details === 'object' && error.details !== null && 'errors' in error.details
                 ? error.details.errors
                 : undefined;
-            return cliError(error.message, exitCode.api, code, {
+            const diagnostics = wizardDiagnostics(error.details);
+            // A permission denial is an auth failure; retain the server's explanation and diagnostics.
+            const exit = error.status === 403 ? exitCode.auth : exitCode.api;
+            return cliError(wizardErrorMessage(error.message, diagnostics), exit, code, {
+                ...diagnostics,
                 code: jsonCode,
                 error_code: jsonCode,
                 errors: fields,
+                message: error.message,
                 status: error.status,
                 status_code: error.status,
                 // Only when the server asked for a wait: an agent reads it instead of guessing one

package/dist/cli/input/app.d.ts

@@ -0,0 +1,8 @@
+/** Spread into a command: `static args = { ...appIdArg }`. Texts kept as published. */
+export declare const appIdArg: {
+    app_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+};
+/** `appIdArg` as a flag: `static flags = { ...appIdFlag }`. Texts kept as the published `--app`. */
+export declare const appIdFlag: {
+    app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};

package/dist/cli/{flags.js → input/app.js}

@@ -1,9 +1,9 @@
 import { Args, Flags } from '@oclif/core';
-import { usageError } from './errors.js';
+import { usageError } from '../errors.js';
 const UUID_PATTERN = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
 /** The published wording of both the `app_id` arg and the `--app` flag. */
 const APP_ID_HINT = 'Invalid app ID format. Run `adapty apps list` to find your app ID.';
-export const isUuid = (value) => UUID_PATTERN.test(value);
+const isUuid = (value) => UUID_PATTERN.test(value);
 /**
  * Checking the shape of a value is the parser's job, so a run() never starts with one. oclif turns
  * a *flag* parser's failure into exit 2 itself but passes an *arg* parser's error through, hence
@@ -28,10 +28,3 @@ export const appIdFlag = {
         required: true,
     }),
 };
-/** The published defaults, so a migrated `list` asks for the same page as an untouched one. */
-export const paginationFlags = {
-    'page': Flags.integer({ default: 1, description: 'Page number', min: 1 }),
-    'page-size': Flags.integer({ default: 20, description: 'Items per page (max 100)', max: 100, min: 1 }),
-};
-/** The one place where flag names meet sdk field names. */
-export const pageParams = (flags) => ({ page: flags.page, pageSize: flags['page-size'] });

package/dist/cli/input/migration.d.ts

@@ -0,0 +1,7 @@
+export declare const migrationArgs: {
+    id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+};
+/** Explicit ID wins over the environment and the saved selection, resolved after parsing. */
+export declare const migrationFlags: {
+    migration: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};