adapty 0.9.1 → 0.9.3

package/README.md

@@ -185,6 +185,16 @@ requiring confirmation exit **6** without it; there is no interactive prompt. Th
 status before refusing, but does not send the action request. After an action, check status again.
 After `revision_conflict`, read status and review the current action, input and confirmation before retrying.
 
+For an `agent` action (`migrate_code`), run it from the app's git repository, ideally from your coding agent. It
+writes the migration's data to `.git/adapty/<migration ID>/` and prints what the agent needs: a branch to work on (`adapty-migrate`), which skill to use, where the data
+is, and the server's guide. Outside an agent, paste the output into one. The agent reports back by running the
+action again with `--input`:
+
+```sh
+adapty migrations run migrate_code
+adapty migrations run migrate_code --input '{"summary": "Swapped the SDK; ADAPTY_SETUP.md leaves 3 steps"}'
+```
+
 For an `external` action, complete the step in the browser, then check status:
 
 ```sh
@@ -249,6 +259,22 @@ adapty migrations steps -m mig_7x2 --json | jq '.steps'
 adapty migrations show RESOURCE -m mig_7x2 --json | jq '.result'
 ```
 
+### Skills
+
+Install the Adapty skills into the coding agents on this machine. Claude Code, Codex and Gemini CLI found on
+`PATH` get them through their own plugin or skills command:
+
+```sh
+adapty skills install
+adapty skills install --agent claude-code
+adapty skills install --yes
+```
+
+When several agents are found, the command asks which to install into; with no one to ask (a pipe or
+`--json`), pass `--agent` or `--yes` for all of them, or it exits **2**. When none is found, it runs
+`npx skills add adaptyteam/adapty-skills --all --global`, which covers the other agents. Restart an agent to
+load the skills. Exit **1** means an install failed.
+
 ### Apple Search Ads
 
 Apple Search Ads commands live under `adapty asa` and talk to the ASA service rather than the Developer

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

@@ -1,4 +1,5 @@
 import { MigrationCommand } from '../../../base/adapty/index.js';
+import type { Handoff } from './lib/agent.js';
 import type { Envelope } from '../../../../sdk/adapty/index.js';
 export default class Run extends MigrationCommand {
     static summary: string;
@@ -18,8 +19,10 @@ export default class Run extends MigrationCommand {
         'no-browser': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         migration: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<Envelope>;
+    run(): Promise<Envelope | Handoff>;
     private prepare;
+    /** The agent that ran this command, or the one the developer pastes the output into, does the work. */
+    private handOff;
     private runExternalAction;
     private runInputAction;
 }

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

@@ -1,3 +1,5 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { Args, Flags } from '@oclif/core';
 import { MigrationCommand } from '../../../base/adapty/index.js';
 import { CliError, exitCode } from '../../../errors.js';
@@ -5,10 +7,11 @@ import { migrationFlags } from '../../../input/migration.js';
 import { renderEnvelope } from '../../../views/migrations/envelope/envelope.js';
 import { actionView } from './lib/action-view.js';
 import { findAction, unknownActionMessage, unsupportedActionMessage } from './lib/actions.js';
+import { buildHandoff, PATH_SEGMENT, repository } from './lib/agent.js';
 import { readActionInput } from './lib/input.js';
 import { openLink } from './lib/open-link.js';
 export default class Run extends MigrationCommand {
-    static summary = 'Run an input action or open an external action link';
+    static summary = 'Run an input action, open an external action link, or hand an agent action to a coding agent';
     static description = [
         'Choose an action ID from next_actions or available_actions in `adapty migrations status -m ID --json`.',
         'Replace ACTION_ID in the examples with an offered action ID.',
@@ -21,7 +24,12 @@ export default class Run extends MigrationCommand {
         'Pipes and --json require --open to launch a browser; BROWSER=none disables it.',
         'File uploads are not supported; use the dashboard or an offered Cloud Export action.',
         '',
-        'With --json, returns the full migration response (before the browser step for external actions).',
+        'An agent action writes the resources in reads to .git/adapty/<migration ID>/ in the app\'s git repository and',
+        'prints what a coding agent needs to do it. Run it from the agent, or paste its output into one. The agent',
+        'reports the result by running the action again with --input.',
+        '',
+        'With --json, returns the full migration response (before the browser step for external actions). For an agent',
+        'action without --input, returns { action_id, files, instructions }: the files written and the text for the agent.',
         'After a revision_conflict error, read status and review the action before retrying.',
     ].join('\n');
     static examples = [
@@ -89,6 +97,9 @@ export default class Run extends MigrationCommand {
         if (context.href !== undefined) {
             return this.runExternalAction(context, context.href);
         }
+        if (context.action.kind === 'agent' && context.input === undefined) {
+            return this.handOff(context);
+        }
         return this.runInputAction(context);
     }
     async prepare() {
@@ -108,20 +119,53 @@ export default class Run extends MigrationCommand {
         }
         return {
             action, envelope, flags, href, selection,
-            input: fromStdin && action.kind === 'input' ? await readActionInput(flags) : input,
+            input: fromStdin && (action.kind === 'input' || action.kind === 'agent') ? await readActionInput(flags) : input,
         };
     }
+    /** The agent that ran this command, or the one the developer pastes the output into, does the work. */
+    async handOff({ action, envelope }) {
+        const repo = await repository(process.cwd());
+        if (repo === undefined) {
+            throw new CliError(`\`${action.action_id}\` works on the app code: run it from the app's git repository.`, exitCode.usage, 'not_a_repository');
+        }
+        const migrationId = envelope.migration.id;
+        if (!PATH_SEGMENT.test(migrationId)) {
+            throw new CliError(`The server named a migration \`${migrationId}\` that cannot be a folder name.`, 1, 'migration_id_invalid');
+        }
+        // A folder per migration: two migrations handed off in one repository never read each other's data.
+        const dir = join(repo.gitDir, 'adapty', migrationId);
+        const files = [];
+        const guides = [];
+        await mkdir(dir, { recursive: true });
+        for (const name of action.reads) {
+            const { result } = await this.adapty.migrations.resource(migrationId, name);
+            if (typeof result === 'object' && result !== null && 'markdown' in result && typeof result.markdown === 'string') {
+                guides.push(result.markdown);
+            }
+            else if (PATH_SEGMENT.test(name)) {
+                const file = join(dir, `${name}.json`);
+                await writeFile(file, `${JSON.stringify(result, null, 2)}\n`);
+                files.push(`\`${name}\`: ${file}`);
+            }
+            else {
+                throw new CliError(`The server named a resource \`${name}\` that cannot be a file name.`, 1, 'resource_name_invalid');
+            }
+        }
+        const handoff = buildHandoff({ actionId: action.action_id, files, guides });
+        this.render(handoff, ({ instructions }) => instructions);
+        return handoff;
+    }
     async runExternalAction(context, href) {
         this.render({ action: context.action, migrationId: context.envelope.migration.id }, actionView);
         await openLink(href, context.flags, this.interactive);
         return context.envelope;
     }
     async runInputAction({ action, envelope, flags, input, selection }) {
-        if (action.kind !== 'input' && action.kind !== 'upload' && action.kind !== 'external') {
+        if (action.kind !== 'input' && action.kind !== 'upload' && action.kind !== 'external' && action.kind !== 'agent') {
             this.render({ action, migrationId: envelope.migration.id }, actionView);
             return envelope;
         }
-        if (action.kind !== 'input') {
+        if (action.kind !== 'input' && action.kind !== 'agent') {
             throw new CliError(unsupportedActionMessage(action), exitCode.usage, 'action_unsupported');
         }
         if (action.confirm !== null && !flags.yes) {

package/dist/cli/commands/migrations/run/lib/agent.d.ts

@@ -0,0 +1,24 @@
+/** In a worktree or a submodule `.git` is a file, so the git directory comes from git itself. */
+export declare const repository: (cwd: string) => Promise<{
+    gitDir: string;
+} | undefined>;
+export type HandoffInput = {
+    actionId: string;
+    /** `name`: absolute path, one per resource written to a file. */
+    files: string[];
+    /** Markdown resources, the server's instructions for this migration, handed to the agent as they are. */
+    guides: string[];
+};
+/** What `--json` returns for an agent action, and what the human view prints. */
+export type Handoff = {
+    action_id: string;
+    files: string[];
+    instructions: string;
+};
+/** A resource name or a migration ID becomes a path segment: no separators, no dots to climb out with. */
+export declare const PATH_SEGMENT: RegExp;
+/**
+ * The server says what to do; the CLI adds the one thing only it knows, where it put the data. Paths
+ * are absolute, so they open from any folder the agent runs in, a monorepo's app folder included.
+ */
+export declare const buildHandoff: ({ actionId, files, guides }: HandoffInput) => Handoff;

package/dist/cli/commands/migrations/run/lib/agent.js

@@ -0,0 +1,32 @@
+import { execFile } from 'node:child_process';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+const git = promisify(execFile);
+/** In a worktree or a submodule `.git` is a file, so the git directory comes from git itself. */
+export const repository = async (cwd) => {
+    try {
+        const { stdout } = await git('git', ['rev-parse', '--absolute-git-dir'], { cwd });
+        const gitDir = stdout.trim();
+        // git prints forward slashes on Windows too: resolve() gives the platform's own form.
+        return gitDir === '' ? undefined : { gitDir: resolve(gitDir) };
+    }
+    catch {
+        return undefined;
+    }
+};
+/** A resource name or a migration ID becomes a path segment: no separators, no dots to climb out with. */
+export const PATH_SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * The server says what to do; the CLI adds the one thing only it knows, where it put the data. Paths
+ * are absolute, so they open from any folder the agent runs in, a monorepo's app folder included.
+ */
+export const buildHandoff = ({ actionId, files, guides }) => ({
+    action_id: actionId,
+    files,
+    instructions: [
+        'adapty-cli wrote this migration\'s data to:',
+        ...files.map(file => `- ${file}`),
+        '',
+        ...guides.map(guide => guide.trim()),
+    ].join('\n'),
+});

package/dist/cli/commands/skills/install/command.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base/base-command.js';
+import type { InstallResult } from './lib/agents.js';
+export default class SkillsInstall extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<("claude-code" | "codex" | "gemini-cli")[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<InstallResult[]>;
+    private targets;
+    /** The skills CLI runs code from npm, so it needs a yes from someone at a terminal, whatever the flags say. */
+    private fallbackTarget;
+}

package/dist/cli/commands/skills/install/command.js

@@ -0,0 +1,78 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base/base-command.js';
+import { CliError, exitCode } from '../../../errors.js';
+import { agentIds, agents, fallback, FALLBACK_COMMAND, install, onPath, runQuietly } from './lib/agents.js';
+import { choose, confirm } from './lib/choose.js';
+import { renderInstall } from './lib/render.js';
+export default class SkillsInstall extends BaseCommand {
+    static description = 'Install the Adapty skills into the coding agents on this machine';
+    static examples = [
+        '<%= config.bin %> skills install',
+        '<%= config.bin %> skills install --agent claude-code',
+        '<%= config.bin %> skills install --yes',
+    ];
+    static flags = {
+        agent: Flags.option({
+            description: 'Install into this agent only. Repeat for several.',
+            multiple: true,
+            options: agentIds,
+        })(),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Install into every agent found without asking; required when several are found and no one can answer. '
+                + 'Never runs the npx fallback, which is always asked for',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(SkillsInstall);
+        const named = flags.agent !== undefined;
+        const chosen = named ? agents.filter(agent => flags.agent?.includes(agent.id)) : agents;
+        const results = [];
+        const found = [];
+        for (const agent of chosen) {
+            if (await onPath(agent.bin)) {
+                found.push(agent);
+            }
+            else if (named) {
+                results.push({ agent: agent.id, error: `\`${agent.bin}\` is not on PATH`, installed: false });
+            }
+        }
+        for (const agent of await this.targets({ found, named, yes: flags.yes })) {
+            results.push(await install(agent, runQuietly));
+        }
+        this.render(results, renderInstall);
+        if (results.some(result => !result.installed)) {
+            process.exitCode = 1;
+        }
+        return results;
+    }
+    async targets({ found, named, yes }) {
+        if (found.length === 0 && !named) {
+            return this.fallbackTarget();
+        }
+        if (named || yes || found.length === 1) {
+            return found;
+        }
+        if (!this.interactive || !process.stdin.isTTY) {
+            const names = found.map(agent => agent.name).join(', ');
+            throw new CliError(`Found ${names}. Choose with --agent, or pass --yes to install into all of them.`, exitCode.usage, 'agent_choice_required');
+        }
+        return choose(found, this.signal);
+    }
+    /** The skills CLI runs code from npm, so it needs a yes from someone at a terminal, whatever the flags say. */
+    async fallbackTarget() {
+        const bins = agents.map(agent => `\`${agent.bin}\``).join(', ');
+        if (!(await onPath(fallback.bin))) {
+            throw new CliError(`Found none of ${bins}, and no \`npx\` to run the skills CLI with.`, 1, 'no_agent_found');
+        }
+        if (!this.interactive || !process.stdin.isTTY) {
+            throw new CliError(`Found none of ${bins}. To install with the skills CLI, run \`${FALLBACK_COMMAND}\` yourself.`, exitCode.usage, 'fallback_confirmation_required');
+        }
+        const question = `Found none of ${bins}. Run \`${FALLBACK_COMMAND}\`? It downloads the skills CLI from npm `
+            + 'and installs the Adapty skills into every agent it finds.';
+        if (!(await confirm(question, this.signal))) {
+            throw new CliError('Nothing installed.', 1, 'fallback_declined');
+        }
+        return [fallback];
+    }
+}

package/dist/cli/commands/skills/install/index.d.ts

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

package/dist/cli/commands/skills/install/index.js

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

package/dist/cli/commands/skills/install/lib/agents.d.ts

@@ -0,0 +1,33 @@
+export declare const agentIds: readonly ["claude-code", "codex", "gemini-cli"];
+export type AgentId = (typeof agentIds)[number];
+export type Agent<Id extends string = AgentId | 'other'> = {
+    bin: string;
+    id: Id;
+    name: string;
+    steps: string[][];
+};
+/**
+ * Each agent's own installer, the same commands the docs' "Install agent tools" modal shows. A
+ * marketplace step fails harmlessly when the marketplace is already there, so only the last step
+ * decides the outcome.
+ */
+export declare const agents: readonly Agent<AgentId>[];
+/**
+ * For a machine where none of the agents above is found: the skills CLI detects the rest itself and
+ * installs into every agent it finds. It runs code from npm, so it only ever runs after a yes.
+ */
+export declare const fallback: Agent;
+export declare const FALLBACK_COMMAND = "npx skills@1.7.0 add adaptyteam/adapty-skills --all --global";
+export type Run = (bin: string, args: readonly string[]) => Promise<{
+    code: number | null;
+    stderr: string;
+}>;
+export type InstallResult = {
+    agent: Agent['id'];
+    error?: string;
+    installed: boolean;
+    warning?: string;
+};
+export declare const runQuietly: Run;
+export declare const onPath: (bin: string) => Promise<boolean>;
+export declare const install: (agent: Agent, run: Run) => Promise<InstallResult>;

package/dist/cli/commands/skills/install/lib/agents.js

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+const SOURCE = 'adaptyteam/adapty-skills';
+const STDERR_TAIL_LINES = 5;
+export const agentIds = ['claude-code', 'codex', 'gemini-cli'];
+/**
+ * Each agent's own installer, the same commands the docs' "Install agent tools" modal shows. A
+ * marketplace step fails harmlessly when the marketplace is already there, so only the last step
+ * decides the outcome.
+ */
+export const agents = [
+    {
+        bin: 'claude',
+        id: 'claude-code',
+        name: 'Claude Code',
+        steps: [['plugin', 'marketplace', 'add', SOURCE], ['plugin', 'install', 'adapty-skills@adapty']],
+    },
+    {
+        bin: 'codex',
+        id: 'codex',
+        name: 'Codex',
+        steps: [['plugin', 'marketplace', 'add', SOURCE], ['plugin', 'add', 'adapty-skills@adapty']],
+    },
+    { bin: 'gemini', id: 'gemini-cli', name: 'Gemini CLI', steps: [['skills', 'install', `https://github.com/${SOURCE}`]] },
+];
+/** Pinned: the fallback runs this package from npm, so a new release is taken on purpose, not by accident. */
+const SKILLS_CLI = 'skills@1.7.0';
+/**
+ * For a machine where none of the agents above is found: the skills CLI detects the rest itself and
+ * installs into every agent it finds. It runs code from npm, so it only ever runs after a yes.
+ */
+export const fallback = {
+    bin: 'npx',
+    id: 'other',
+    name: 'Other agents (skills CLI)',
+    steps: [['--yes', SKILLS_CLI, 'add', SOURCE, '--all', '--global']],
+};
+export const FALLBACK_COMMAND = `npx ${SKILLS_CLI} add ${SOURCE} --all --global`;
+// A Windows agent is a .cmd shim that only a shell resolves.
+const windows = process.platform === 'win32';
+export const runQuietly = async (bin, args) => new Promise((resolve) => {
+    const child = spawn(bin, args, { env: { ...process.env, NO_COLOR: '1' }, shell: windows, stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on('error', (error) => {
+        resolve({ code: null, stderr: error.message });
+    });
+    child.on('close', (code) => {
+        resolve({ code, stderr });
+    });
+});
+export const onPath = async (bin) => {
+    const extensions = windows ? (process.env.PATHEXT ?? '.EXE;.CMD').split(';') : [''];
+    const candidates = (process.env.PATH ?? '').split(delimiter).filter(Boolean)
+        .flatMap(dir => extensions.map(extension => join(dir, bin + extension)));
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+            return true;
+        }
+        catch {
+            // not in this directory
+        }
+    }
+    return false;
+};
+const tailOf = (stderr) => stderr.trim().split('\n').slice(-STDERR_TAIL_LINES).join('\n');
+export const install = async (agent, run) => {
+    const results = [];
+    for (const step of agent.steps) {
+        results.push(await run(agent.bin, step));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every agent has at least one step
+    const last = results.at(-1);
+    if (last.code !== 0) {
+        const error = tailOf(last.stderr) || `\`${agent.bin}\` exited with code ${String(last.code)}`;
+        return { agent: agent.id, error, installed: false };
+    }
+    // A marketplace that is already there fails the step, whether it is ours or another source under
+    // the same name; only the second installs someone else's skills, and the CLI cannot tell them apart.
+    const marketplace = results.length > 1 ? results[0] : undefined;
+    if (marketplace !== undefined && marketplace.code !== 0) {
+        const warning = `adding the marketplace failed (${tailOf(marketplace.stderr) || 'no message'}). If an \`adapty\` `
+            + `marketplace already existed, the skills came from its source: check it with \`${agent.bin} plugin marketplace list\`.`;
+        return { agent: agent.id, installed: true, warning };
+    }
+    return { agent: agent.id, installed: true };
+};

package/dist/cli/commands/skills/install/lib/choose.d.ts

@@ -0,0 +1,7 @@
+import type { Agent } from './agents.js';
+/** `1,3` or `1 3` picks those; an empty answer picks all of them. Anything else is asked again. */
+export declare const parseChoice: (answer: string, count: number) => number[] | undefined;
+export declare const choose: (found: readonly Agent[], signal: AbortSignal) => Promise<Agent[]>;
+/** An empty answer is a no: the question guards a command that runs code from npm. */
+export declare const parseConsent: (answer: string) => boolean | undefined;
+export declare const confirm: (question: string, signal: AbortSignal) => Promise<boolean>;

package/dist/cli/commands/skills/install/lib/choose.js

@@ -0,0 +1,62 @@
+import { createInterface } from 'node:readline/promises';
+import { CliError, exitCode } from '../../../../errors.js';
+/** `1,3` or `1 3` picks those; an empty answer picks all of them. Anything else is asked again. */
+export const parseChoice = (answer, count) => {
+    const trimmed = answer.trim();
+    if (trimmed === '') {
+        return Array.from({ length: count }, (_, index) => index);
+    }
+    const picked = trimmed.split(/[\s,]+/).map(Number);
+    if (picked.some(number => !Number.isInteger(number) || number < 1 || number > count)) {
+        return undefined;
+    }
+    return [...new Set(picked)].sort((a, b) => a - b).map(number => number - 1);
+};
+/**
+ * Asked on stderr, so the answer never mixes into what a program reads from stdout. A terminal's
+ * Ctrl+C reaches readline, not the process, so the prompt turns it into the usual exit 130 itself.
+ */
+const ask = async ({ question, retry, signal }, parse) => {
+    const reader = createInterface({ input: process.stdin, output: process.stderr });
+    const interrupted = new AbortController();
+    reader.on('SIGINT', () => {
+        interrupted.abort();
+    });
+    try {
+        for (;;) {
+            const answer = await reader.question(question, { signal: AbortSignal.any([signal, interrupted.signal]) });
+            const parsed = parse(answer);
+            if (parsed !== undefined) {
+                return parsed;
+            }
+            process.stderr.write(`${retry}\n`);
+        }
+    }
+    catch (error) {
+        if (signal.aborted || interrupted.signal.aborted) {
+            throw new CliError('Cancelled.', exitCode.cancelled, undefined, { cause: error });
+        }
+        throw error;
+    }
+    finally {
+        reader.close();
+    }
+};
+export const choose = async (found, signal) => {
+    const list = found.map((agent, index) => `  ${String(index + 1)}. ${agent.name}`).join('\n');
+    const picked = await ask({
+        question: `Found:\n${list}\nInstall into which? [all] `,
+        retry: `Type numbers from 1 to ${String(found.length)}, or press Enter for all.`,
+        signal,
+    }, answer => parseChoice(answer, found.length));
+    return picked.map(index => found[index]).filter(agent => agent !== undefined);
+};
+/** An empty answer is a no: the question guards a command that runs code from npm. */
+export const parseConsent = (answer) => {
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === '' || trimmed === 'n' || trimmed === 'no') {
+        return false;
+    }
+    return trimmed === 'y' || trimmed === 'yes' ? true : undefined;
+};
+export const confirm = async (question, signal) => ask({ question: `${question} [y/N] `, retry: 'Type y or n.', signal }, parseConsent);

package/dist/cli/commands/skills/install/lib/render.d.ts

@@ -0,0 +1,2 @@
+import type { InstallResult } from './agents.js';
+export declare const renderInstall: (results: InstallResult[]) => string;

package/dist/cli/commands/skills/install/lib/render.js

@@ -0,0 +1,16 @@
+import { agents, fallback, FALLBACK_COMMAND } from './agents.js';
+const known = [...agents, fallback];
+const nameOf = (result) => known.find(agent => agent.id === result.agent)?.name ?? result.agent;
+export const renderInstall = (results) => {
+    const lines = results.map((result) => {
+        if (!result.installed) {
+            return `✗ ${nameOf(result)}: ${result.error ?? 'not installed'}`;
+        }
+        const installed = `✓ ${nameOf(result)}: installed. Restart it to load the skills.`;
+        return result.warning === undefined ? installed : `${installed}\n  Warning: ${result.warning}`;
+    });
+    if (results.some(result => result.agent === fallback.id)) {
+        return lines.join('\n');
+    }
+    return [...lines, '', `Another agent? Run \`${FALLBACK_COMMAND}\`.`].join('\n');
+};

package/dist/cli/views/migrations/envelope/action-block.js

@@ -1,4 +1,4 @@
-const knownKinds = new Set(['external', 'input', 'upload']);
+const knownKinds = new Set(['agent', 'external', 'input', 'upload']);
 const indent = (text, pad) => {
     return text.split('\n').map(line => `${pad}${line}`).join('\n');
 };

package/dist/commands/skills/install.d.ts

@@ -0,0 +1 @@
+export { default } from '../../cli/commands/skills/install/index.js';

package/dist/commands/skills/install.js

@@ -0,0 +1,2 @@
+// Implementation lives in the new cli layer; oclif discovers commands only under src/commands.
+export { default } from '../../cli/commands/skills/install/index.js';

package/dist/lib/asa-schemas.d.ts

@@ -149,10 +149,15 @@ export type AsaSearchTermDTO = {
     campaign_group_id: string;
     campaign_id: string;
     country_or_region: string;
+    impression_midpoint_all: null | string;
+    impression_midpoint_first: null | string;
+    impression_share_all: null | string;
+    impression_share_first: null | string;
     keyword_id: null | string;
     match_type: AsaKeywordMatchType | null;
     metrics: AsaMetricsDTO;
-    rank: null | number;
+    rank_all: null | number;
+    rank_first: null | number;
     search_popularity: null | number;
     source: null | string;
     text: null | string;

package/dist/sdk/adapty/migrations/model.d.ts

@@ -1,5 +1,5 @@
 export type MigrationState = 'running' | 'action_required' | 'completed' | 'failed' | 'canceled';
-export type ActionKind = 'input' | 'upload' | 'external';
+export type ActionKind = 'input' | 'upload' | 'external' | 'agent';
 export type StepStatus = 'locked' | 'active' | 'done';
 export type JsonSchema = Record<string, unknown>;
 export type Envelope<TResult = unknown> = {
@@ -74,6 +74,9 @@ export type Action = ActionBase & ({
 } | {
     kind: 'external';
     href: string;
+} | {
+    kind: 'agent';
+    input_schema: JsonSchema | null;
 } | {
     kind: string;
     href?: string;

package/oclif.manifest.json

@@ -421,85 +421,6 @@
         "update.js"
       ]
     },
-    "asa:connect": {
-      "aliases": [],
-      "args": {},
-      "description": "Connect an Apple Search Ads account to this company",
-      "examples": [
-        "<%= config.bin %> asa connect",
-        "<%= config.bin %> asa connect --no-wait"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "timeout": {
-          "description": "Seconds to wait for the browser step",
-          "name": "timeout",
-          "default": 300,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "wait": {
-          "description": "Wait until Apple Ads reports as connected",
-          "name": "wait",
-          "allowNo": true,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "asa:connect",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "asa",
-        "connect.js"
-      ]
-    },
-    "asa:whoami": {
-      "aliases": [],
-      "args": {},
-      "description": "Show which company the token unlocks, whether Apple Ads is connected, and the request budgets it gets\n\nLimits are raised per company, so read them here rather than assuming the defaults: metrics_limit_per_minute\nand metrics_burst_limit govern asa metrics, keywords_read_limit_per_minute the keyword lists,\nmetrics_inflight_limit how many analytics calls may overlap, and max_breakdown_rows_per_page the size a\ngrouped page may project to before it is refused.",
-      "examples": [
-        "<%= config.bin %> asa whoami"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "asa:whoami",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "asa",
-        "whoami.js"
-      ]
-    },
     "attribution:dimensions": {
       "aliases": [],
       "args": {},
@@ -769,36 +690,13 @@
         "values.js"
       ]
     },
-    "auth:login": {
-      "aliases": [],
-      "args": {},
-      "description": "Authenticate with Adapty via browser",
-      "examples": [
-        "<%= config.bin %> auth login"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "auth:login",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "auth",
-        "login.js"
-      ]
-    },
-    "auth:logout": {
+    "asa:connect": {
       "aliases": [],
       "args": {},
-      "description": "Remove stored credentials and the saved migration selection",
+      "description": "Connect an Apple Search Ads account to this company",
       "examples": [
-        "<%= config.bin %> auth logout"
+        "<%= config.bin %> asa connect",
+        "<%= config.bin %> asa connect --no-wait"
       ],
       "flags": {
         "json": {
@@ -807,43 +705,25 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "auth:logout",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "auth",
-        "logout.js"
-      ]
-    },
-    "auth:revoke": {
-      "aliases": [],
-      "args": {},
-      "description": "Revoke the current token and remove matching stored credentials and migration selection",
-      "examples": [
-        "<%= config.bin %> auth revoke"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
+        },
+        "timeout": {
+          "description": "Seconds to wait for the browser step",
+          "name": "timeout",
+          "default": 300,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Wait until Apple Ads reports as connected",
+          "name": "wait",
+          "allowNo": true,
           "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "auth:revoke",
+      "id": "asa:connect",
       "pluginAlias": "adapty",
       "pluginName": "adapty",
       "pluginType": "core",
@@ -853,16 +733,16 @@
       "relativePath": [
         "dist",
         "commands",
-        "auth",
-        "revoke.js"
+        "asa",
+        "connect.js"
       ]
     },
-    "auth:status": {
+    "asa:whoami": {
       "aliases": [],
       "args": {},
-      "description": "Show the local authentication state (no network)",
+      "description": "Show which company the token unlocks, whether Apple Ads is connected, and the request budgets it gets\n\nLimits are raised per company, so read them here rather than assuming the defaults: metrics_limit_per_minute\nand metrics_burst_limit govern asa metrics, keywords_read_limit_per_minute the keyword lists,\nmetrics_inflight_limit how many analytics calls may overlap, and max_breakdown_rows_per_page the size a\ngrouped page may project to before it is refused.",
       "examples": [
-        "<%= config.bin %> auth status"
+        "<%= config.bin %> asa whoami"
       ],
       "flags": {
         "json": {
@@ -875,7 +755,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "auth:status",
+      "id": "asa:whoami",
       "pluginAlias": "adapty",
       "pluginName": "adapty",
       "pluginType": "core",
@@ -885,38 +765,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "auth",
-        "status.js"
-      ]
-    },
-    "auth:whoami": {
-      "aliases": [],
-      "args": {},
-      "description": "Show the current user from the server (verifies the token)",
-      "examples": [
-        "<%= config.bin %> auth whoami"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "auth:whoami",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "auth",
+        "asa",
         "whoami.js"
       ]
     },
@@ -1422,7 +1271,7 @@
           "required": true
         }
       },
-      "description": "Choose an action ID from next_actions or available_actions in `adapty migrations status -m ID --json`.\nReplace ACTION_ID in the examples with an offered action ID.\nFor input actions, read the resources in reads and prepare a JSON object matching input_schema.\nOmitting input sends {}. Review confirm before passing --yes.\nWithout --yes, actions requiring confirmation exit with code 6. No confirmation prompt is shown.\n\nExternal actions print a link and open it in an interactive terminal. Complete the browser step, then check status.\nExternal actions reject --input and --input-file, including stdin.\nPipes and --json require --open to launch a browser; BROWSER=none disables it.\nFile uploads are not supported; use the dashboard or an offered Cloud Export action.\n\nWith --json, returns the full migration response (before the browser step for external actions).\nAfter a revision_conflict error, read status and review the action before retrying.",
+      "description": "Choose an action ID from next_actions or available_actions in `adapty migrations status -m ID --json`.\nReplace ACTION_ID in the examples with an offered action ID.\nFor input actions, read the resources in reads and prepare a JSON object matching input_schema.\nOmitting input sends {}. Review confirm before passing --yes.\nWithout --yes, actions requiring confirmation exit with code 6. No confirmation prompt is shown.\n\nExternal actions print a link and open it in an interactive terminal. Complete the browser step, then check status.\nExternal actions reject --input and --input-file, including stdin.\nPipes and --json require --open to launch a browser; BROWSER=none disables it.\nFile uploads are not supported; use the dashboard or an offered Cloud Export action.\n\nAn agent action writes the resources in reads to .git/adapty/<migration ID>/ in the app's git repository and\nprints what a coding agent needs to do it. Run it from the agent, or paste its output into one. The agent\nreports the result by running the action again with --input.\n\nWith --json, returns the full migration response (before the browser step for external actions). For an agent\naction without --input, returns { action_id, files, instructions }: the files written and the text for the agent.\nAfter a revision_conflict error, read status and review the action before retrying.",
       "examples": [
         {
           "description": "Run an offered action on the saved migration after reviewing confirm:",
@@ -1521,7 +1370,7 @@
       "pluginName": "adapty",
       "pluginType": "core",
       "strict": true,
-      "summary": "Run an input action or open an external action link",
+      "summary": "Run an input action, open an external action link, or hand an agent action to a coding agent",
       "isESM": true,
       "relativePath": [
         "dist",
@@ -2691,6 +2540,210 @@
         "list.js"
       ]
     },
+    "skills:install": {
+      "aliases": [],
+      "args": {},
+      "description": "Install the Adapty skills into the coding agents on this machine",
+      "examples": [
+        "<%= config.bin %> skills install",
+        "<%= config.bin %> skills install --agent claude-code",
+        "<%= config.bin %> skills install --yes"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "agent": {
+          "description": "Install into this agent only. Repeat for several.",
+          "name": "agent",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "options": [
+            "claude-code",
+            "codex",
+            "gemini-cli"
+          ],
+          "type": "option"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Install into every agent found without asking; required when several are found and no one can answer. Never runs the npx fallback, which is always asked for",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "skills:install",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "skills",
+        "install.js"
+      ]
+    },
+    "auth:login": {
+      "aliases": [],
+      "args": {},
+      "description": "Authenticate with Adapty via browser",
+      "examples": [
+        "<%= config.bin %> auth login"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:login",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "login.js"
+      ]
+    },
+    "auth:logout": {
+      "aliases": [],
+      "args": {},
+      "description": "Remove stored credentials and the saved migration selection",
+      "examples": [
+        "<%= config.bin %> auth logout"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:logout",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "logout.js"
+      ]
+    },
+    "auth:revoke": {
+      "aliases": [],
+      "args": {},
+      "description": "Revoke the current token and remove matching stored credentials and migration selection",
+      "examples": [
+        "<%= config.bin %> auth revoke"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:revoke",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "revoke.js"
+      ]
+    },
+    "auth:status": {
+      "aliases": [],
+      "args": {},
+      "description": "Show the local authentication state (no network)",
+      "examples": [
+        "<%= config.bin %> auth status"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:status",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "status.js"
+      ]
+    },
+    "auth:whoami": {
+      "aliases": [],
+      "args": {},
+      "description": "Show the current user from the server (verifies the token)",
+      "examples": [
+        "<%= config.bin %> auth whoami"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "auth:whoami",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "auth",
+        "whoami.js"
+      ]
+    },
     "asa:ad-groups:create": {
       "aliases": [],
       "args": {},
@@ -6104,5 +6157,5 @@
       ]
     }
   },
-  "version": "0.9.1"
+  "version": "0.9.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "adapty",
   "description": "Adapty command line interface",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "author": "Adapty team <support@adapty.io>",
   "bin": {
     "adapty": "./bin/run.js"
@@ -99,6 +99,9 @@
       "segments": {
         "description": "List segments"
       },
+      "skills": {
+        "description": "Install the Adapty skills into coding agents"
+      },
       "migrations": {
         "description": "Manage migrations: catalog, transactions and store events"
       },