@nuxtseo/cli 0.2.1 → 0.3.0

package/dist/ansi.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Removes every ANSI escape sequence from one string.
+ */
+export declare function stripAnsi(value: string): string;
+/**
+ * Serializes a value as JSON with every string value free of ANSI escapes.
+ */
+export declare function stringifyWithoutAnsi(value: unknown): string;

package/dist/ansi.js

@@ -0,0 +1,35 @@
+/**
+ * Terminal styling never belongs in machine output.
+ *
+ * `citty` builds its own argument errors with `cyan(...)`, and it decides once,
+ * at import time, whether to emit colour. The CLI cannot turn that decision off
+ * after the fact, and the same risk exists for any other dependency whose text
+ * reaches a JSON envelope. So the CLI strips escape sequences at the boundary
+ * where machine output is written, which covers every producer at once.
+ */
+/**
+ * A control sequence: `ESC [`, parameter and intermediate bytes, then one final
+ * byte. Colour, cursor moves and erase sequences all take this form.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_CONTROL_SEQUENCE = /\u001B\[[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]/g;
+/**
+ * An operating system command, such as a terminal hyperlink or a window title.
+ * It ends with BEL or with `ESC \`.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_OPERATING_SYSTEM_COMMAND = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/g;
+/**
+ * Removes every ANSI escape sequence from one string.
+ */
+export function stripAnsi(value) {
+    return value
+        .replace(ANSI_OPERATING_SYSTEM_COMMAND, '')
+        .replace(ANSI_CONTROL_SEQUENCE, '');
+}
+/**
+ * Serializes a value as JSON with every string value free of ANSI escapes.
+ */
+export function stringifyWithoutAnsi(value) {
+    return JSON.stringify(value, (_key, entry) => typeof entry === 'string' ? stripAnsi(entry) : entry);
+}

package/dist/cli.js

@@ -1,5 +1,6 @@
 import * as prompts from '@clack/prompts';
 import { renderUsage, runCommand } from 'citty';
+import { stripAnsi } from './ansi.js';
 import { fromStateError, loadApiContext } from './api.js';
 import { commandWithGlobalOptions, describeCommand, resolveCommand, validateCommandOptions, } from './command-contract.js';
 import { createRootCommand } from './commands.js';
@@ -15,6 +16,9 @@ function writeUpdateNotice(runtime, notice) {
 }
 function report(runtime, failure, json = false, notice = null) {
     if (json) {
+        // `--json` means a program reads both streams. Terminal styling is noise
+        // there, so stderr is stripped as well as stdout.
+        failure = { ...failure, message: stripAnsi(failure.message) };
         if (failure.protocolResponse !== undefined) {
             writeProtocolResponse(runtime, failure.protocolResponse);
         }
@@ -405,7 +409,7 @@ export async function runCli(rawArgs, runtime) {
     // Started before parsing so the registry round trip overlaps the command. The
     // check reads a local cache and never rejects; a slow registry only delays
     // this line, never the command result itself.
-    const updateCheck = checkForUpdate({ paths: runtime.paths, env: runtime.env });
+    const updateCheck = checkForUpdate({ paths: runtime.paths, env: runtime.env, onDiagnostic: line => writeDiagnostic(runtime, line) });
     const parsed = extractGlobalOptions(rawArgs);
     if (parsed._tag === 'Err') {
         const notice = await updateCheck;
@@ -416,10 +420,15 @@ export async function runCli(rawArgs, runtime) {
     const effectiveRuntime = {
         ...runtime,
         interactive: runtime.interactive && !globals.json && !globals.noInput,
-        requestSignal: AbortSignal.any([
-            runtime.requestSignal,
-            AbortSignal.timeout(globals.timeoutMs),
-        ]),
+        // A getter, so each request reads a fresh `--timeout-ms` deadline. One timer
+        // made here covered the whole process: an `--all` walk of healthy pages
+        // exited 6 once their SUM passed the per-request limit.
+        get requestSignal() {
+            return AbortSignal.any([
+                runtime.requestSignal,
+                AbortSignal.timeout(globals.timeoutMs),
+            ]);
+        },
         requestTimeoutMs: globals.timeoutMs,
     };
     if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {

package/dist/commands.d.ts

@@ -24,4 +24,11 @@ export type NextPage = {
 } | {
     _tag: 'Done';
 };
+/**
+ * The seed rule is known before the request runs. The provider answers a
+ * refused seed with 200, an empty list, and a `message`, which reads as "no
+ * demand for this topic". So the CLI checks the rule first and exits 2 without
+ * spending a research request.
+ */
+export declare function parseResearchTopic(topic: string): CliResult<string>;
 export declare function createRootCommand(runtime: CliRuntime, globals: GlobalOptions, execution: CommandExecution): CommandDef<any>;

package/dist/commands.js

@@ -8,17 +8,37 @@ import { openBrowser } from './browser.js';
 import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
 import { parseAbsolutePageUrl, parseChoice, parseInteger, parsePageUrlOrPath, parseRatio } from './parse.js';
+import { PULL_PERIODS, runPull } from './pull.js';
 import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { installSkill, SKILL_AGENTS } from './skill.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
 import { VERSION } from './version.js';
+/**
+ * Some read operations answer 200 with an empty list and a `message` that says
+ * why it is empty. A refused argument and a genuinely empty result look the
+ * same in the envelope, so a caller that reads only the list draws the wrong
+ * conclusion. Text output already prints the note. Machine output must not
+ * change the envelope, so the note goes to stderr, where it cannot be lost.
+ */
+function reportDataNote(runtime, value) {
+    const data = typeof value === 'object' && value !== null ? value.data : undefined;
+    if (typeof data !== 'object' || data === null)
+        return;
+    const { message, tip } = data;
+    const lines = [message, tip].filter((line) => typeof line === 'string' && line.trim().length > 0);
+    if (lines.length > 0)
+        writeDiagnostic(runtime, `Note: ${lines.join(' ')}`);
+}
 function emit(runtime, globals, value, render) {
-    if (globals.json)
+    if (globals.json) {
         writeProtocolResponse(runtime, value);
-    else
+        reportDataNote(runtime, value);
+    }
+    else {
         writeOutput(runtime, render(value));
+    }
 }
 function present(runtime, globals, result, render) {
     if (result._tag === 'Err')
@@ -718,7 +738,37 @@ async function researchOverview(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderResearchOverview(value.data));
 }
+/**
+ * DataForSEO refuses these characters, so the research provider removes them
+ * before it counts the words of a seed. Mirrored from
+ * `modules/dataforseo/src/runtime/server/utils/seo-tools/keyword-research.ts`.
+ */
+const RESEARCH_FORBIDDEN_CHARS = /[`!@%^()={};<>?\\|#/~\u2015\u{1F000}-\u{1FFFF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}]/gu;
+/** The provider accepts 1 to 3 words per seed keyword. */
+const RESEARCH_SEED_MAX_WORDS = 3;
+function sanitizeResearchSeed(seed) {
+    return seed.replace(RESEARCH_FORBIDDEN_CHARS, '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * The seed rule is known before the request runs. The provider answers a
+ * refused seed with 200, an empty list, and a `message`, which reads as "no
+ * demand for this topic". So the CLI checks the rule first and exits 2 without
+ * spending a research request.
+ */
+export function parseResearchTopic(topic) {
+    const seeds = topic.split(',').map(sanitizeResearchSeed).filter(seed => seed.length >= 2);
+    if (seeds.length === 0)
+        return fail(EXIT_CODE.invalidInput, 'topic must hold letters or digits. Characters like @ # / % ! are removed.');
+    const tooLong = seeds.find(seed => seed.split(' ').length > RESEARCH_SEED_MAX_WORDS);
+    if (tooLong !== undefined) {
+        return fail(EXIT_CODE.invalidInput, `topic seed "${tooLong}" holds more than ${RESEARCH_SEED_MAX_WORDS} words. Use 1 to 3 words per seed. Separate seeds with a comma.`);
+    }
+    return ok(topic);
+}
 async function researchKeywordIdeas(runtime, globals, args) {
+    const topic = parseResearchTopic(args.topic);
+    if (topic._tag === 'Err')
+        return topic;
     const minVolume = parseInteger(args.minVolume, { name: '--min-volume', minimum: 0, defaultValue: 10 });
     if (minVolume._tag === 'Err')
         return minVolume;
@@ -747,7 +797,7 @@ async function researchKeywordIdeas(runtime, globals, args) {
     const response = await withSpinner(runtime, 'Researching keyword ideas', () => resolved.value.api.client.research.keywords({
         params: { siteId: resolved.value.siteId },
         query: {
-            topic: args.topic,
+            topic: topic.value,
             minVolume: minVolume.value,
             maxVolume: maxVolume.value,
             minDifficulty: minDifficulty.value,
@@ -954,6 +1004,10 @@ async function analyticsQuery(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderAnalytics(view.value, value.data));
 }
+/** A count with its noun, so output never reads "1 files". */
+function count(total, noun) {
+    return `${total} ${noun}${total === 1 ? '' : 's'}`;
+}
 async function skillInstallCommand(runtime, globals, args) {
     const agent = parseChoice(args.agent, { name: '--agent', choices: SKILL_AGENTS, defaultValue: 'claude' });
     if (agent._tag === 'Err')
@@ -961,7 +1015,7 @@ async function skillInstallCommand(runtime, globals, args) {
     // The state directory is `<home>/.nuxtseo`, so its parent is the home the
     // agent directories sit beside.
     const homeDirectory = dirname(runtime.paths.directory);
-    const installed = await installSkill({ agent: agent.value, homeDirectory, target: args.target });
+    const installed = await installSkill({ agent: agent.value, homeDirectory, target: args.target, paths: runtime.paths });
     if (installed._tag === 'Err')
         return installed;
     if (globals.json) {
@@ -969,12 +1023,20 @@ async function skillInstallCommand(runtime, globals, args) {
             _tag: 'CliSkillInstall',
             schemaVersion: 1,
             agent: installed.value.agent,
+            version: installed.value.version,
             source: installed.value.source,
             destination: installed.value.destination,
+            resolvedDestination: installed.value.resolvedDestination,
+            written: installed.value.written,
+            pruned: installed.value.pruned,
         });
     }
     else {
-        writeOutput(runtime, `Installed the nuxtseo-cli skill for ${installed.value.agent} at ${installed.value.destination}.`);
+        writeOutput(runtime, [
+            `Installed the nuxtseo-cli skill ${installed.value.version} for ${installed.value.agent}.`,
+            `Location: ${installed.value.resolvedDestination}`,
+            `Wrote ${count(installed.value.written, 'file')}. Removed ${count(installed.value.pruned, 'stale file')}.`,
+        ].join('\n'));
     }
     return ok(undefined);
 }
@@ -2108,6 +2170,23 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
+    const pull = defineCommand({
+        meta: { name: 'pull', description: 'Write every stored-evidence read for one Site as NDJSON' },
+        args: {
+            'include': { type: 'string', description: 'Comma separated command names to run instead of the default set' },
+            'exclude': { type: 'string', description: 'Comma separated command names to drop' },
+            'with-research': { type: 'boolean', description: 'Add the reads that can start live research; they draw on the Team allowance' },
+            'period': { type: 'enum', options: [...PULL_PERIODS], description: 'Search Console period for the search analytics reads' },
+            'concurrency': { type: 'string', description: 'Reads in flight at once, 1 to 8' },
+        },
+        run: ({ args }) => capture(execution, () => runPull(runtime, globals, {
+            include: args.include,
+            exclude: args.exclude,
+            withResearch: args['with-research'],
+            period: args.period,
+            concurrency: args.concurrency,
+        }, apiAndSite), args._, 0)(),
+    });
     const timeline = defineCommand({
         meta: { name: 'timeline', description: 'Read the Timeline — what changed on the Site' },
         subCommands: {
@@ -2219,6 +2298,7 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => performance(runtime, globals), args._, 0)(),
             }),
             annotations,
+            pull,
             research,
             scans,
             search,

package/dist/failures.d.ts

@@ -12,7 +12,7 @@ export declare const EXIT_CODE: {
     readonly interrupted: 130;
 };
 export type ExitCode = typeof EXIT_CODE[keyof typeof EXIT_CODE];
-export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
+export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'pull_incomplete' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
 export type CliFailureCode = LocalFailureCode | Extract<SdkFailure, {
     _tag: 'ApiFailure';
 }>['code'];
@@ -24,14 +24,54 @@ export interface CliFailure {
     cause?: unknown;
     protocolResponse?: unknown;
 }
+export interface CliErr {
+    _tag: 'Err';
+    error: CliFailure;
+}
 export type CliResult<T> = {
     _tag: 'Ok';
     value: T;
+} | CliErr;
+export declare function ok<T>(value: T): CliResult<T>;
+export declare function fail(exitCode: ExitCode, message: string, cause?: unknown, code?: CliFailureCode): CliErr;
+/**
+ * Which side of a `contract_violation` runs the older contract.
+ *
+ * The CLI knows the contract version it was built against. The API reports its
+ * own in the `X-NuxtSEO-Version` response header, which the SDK keeps on
+ * `metadata.version`. When the two differ, the direction of the skew is a fact.
+ * When they match, or the header is absent, the CLI cannot observe a direction,
+ * so the message must not name one.
+ *
+ * Bug 2026-09-21: a field landed in a client response schema before the API
+ * deployed it. A newer CLI rejected an older API response, and the old message
+ * told the operator to update the CLI, which was already the newest part.
+ */
+export type ContractSkew = {
+    _tag: 'CliContractOlder';
+    cliContract: string;
+    apiContract: string;
 } | {
-    _tag: 'Err';
-    error: CliFailure;
+    _tag: 'ApiContractOlder';
+    cliContract: string;
+    apiContract: string;
+} | {
+    _tag: 'ContractVersionsMatch';
+    contract: string;
+} | {
+    _tag: 'ApiContractUnknown';
+    cliContract: string;
 };
-export declare function ok<T>(value: T): CliResult<T>;
-export declare function fail(exitCode: ExitCode, message: string, cause?: unknown, code?: CliFailureCode): CliResult<never>;
-export declare function fromSdkFailure(error: SdkFailure): CliResult<never>;
+/**
+ * Classify the skew from what the response actually carried.
+ *
+ * `apiContract` is the value of the `X-NuxtSEO-Version` response header, or
+ * `undefined` when the API sent no header the SDK could read.
+ */
+export declare function classifyContractSkew(apiContract: string | undefined, cliContract?: string): ContractSkew;
+/**
+ * The remediation a caller can act on, and nothing the CLI cannot observe.
+ */
+export declare function contractSkewLines(skew: ContractSkew): string[];
+export declare function fromSdkFailure(error: SdkFailure): CliErr;
 export declare function unexpectedFailure(cause: unknown): CliFailure;

package/dist/failures.js

@@ -1,11 +1,6 @@
+import { PUBLIC_V1_VERSION } from '@nuxtseo/protocol/v1/core';
 import { VERSION } from './version.js';
 const UPDATE_COMMAND = 'pnpm add -g @nuxtseo/cli';
-// `contract_violation` most often means this CLI is older than the server
-// contract. One line routes an agent to update before anything else.
-const CONTRACT_REMEDIATION = [
-    'Most common cause: this CLI is older than the server contract.',
-    `Update first with ${UPDATE_COMMAND}, then run the command again.`,
-].join(' ');
 export const EXIT_CODE = {
     success: 0,
     invalidInput: 2,
@@ -103,6 +98,99 @@ function requestIssueLine(issue) {
     const text = typeof message === 'string' && message ? message : JSON.stringify(issue);
     return field ? `${field}: ${text}` : text;
 }
+function contractOrder(version) {
+    const parts = version.split('.');
+    const numbers = parts.map(part => Number(part));
+    return numbers.every(part => Number.isSafeInteger(part) && part >= 0) ? numbers : undefined;
+}
+function compareContracts(left, right) {
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+/**
+ * Classify the skew from what the response actually carried.
+ *
+ * `apiContract` is the value of the `X-NuxtSEO-Version` response header, or
+ * `undefined` when the API sent no header the SDK could read.
+ */
+export function classifyContractSkew(apiContract, cliContract = PUBLIC_V1_VERSION) {
+    if (!apiContract)
+        return { _tag: 'ApiContractUnknown', cliContract };
+    if (apiContract === cliContract)
+        return { _tag: 'ContractVersionsMatch', contract: cliContract };
+    const api = contractOrder(apiContract);
+    const cli = contractOrder(cliContract);
+    if (!api || !cli)
+        return { _tag: 'ApiContractUnknown', cliContract };
+    const difference = compareContracts(cli, api);
+    if (difference < 0)
+        return { _tag: 'CliContractOlder', cliContract, apiContract };
+    if (difference > 0)
+        return { _tag: 'ApiContractOlder', cliContract, apiContract };
+    return { _tag: 'ContractVersionsMatch', contract: cliContract };
+}
+/**
+ * The remediation a caller can act on, and nothing the CLI cannot observe.
+ */
+export function contractSkewLines(skew) {
+    switch (skew._tag) {
+        case 'CliContractOlder':
+            return [
+                `Contract version: this CLI expects ${skew.cliContract}. The API reported ${skew.apiContract}.`,
+                'The API runs a newer contract than this CLI.',
+                `Update the CLI with ${UPDATE_COMMAND}, then run the command again.`,
+            ];
+        case 'ApiContractOlder':
+            return [
+                `Contract version: this CLI expects ${skew.cliContract}. The API reported ${skew.apiContract}.`,
+                'The API runs an older contract than this CLI.',
+                'Wait for the API deploy, then run the command again.',
+            ];
+        case 'ContractVersionsMatch':
+            return [
+                `Contract version: both sides reported ${skew.contract}.`,
+                'The CLI cannot tell which side changed.',
+                `If this CLI is older than the deployed API, update it with ${UPDATE_COMMAND}.`,
+                'If the deployed API is older than this CLI, wait for its deploy.',
+            ];
+        case 'ApiContractUnknown':
+            return [
+                `Contract version: this CLI expects ${skew.cliContract}. The API reported none.`,
+                'The CLI cannot tell which side changed.',
+                `If this CLI is older than the deployed API, update it with ${UPDATE_COMMAND}.`,
+                'If the deployed API is older than this CLI, wait for its deploy.',
+            ];
+    }
+}
+const MAX_SCHEMA_ISSUES = 5;
+/**
+ * The field paths that failed validation.
+ *
+ * The SDK already holds the zod issues at the point of failure, and the path is
+ * the one fact that names the unmet expectation. The old message dropped them.
+ */
+function contractIssueLines(issues) {
+    if (issues.length === 0)
+        return [];
+    const shown = issues.slice(0, MAX_SCHEMA_ISSUES).map(issue => `  ${requestIssueLine(issue)}`);
+    const hidden = issues.length - shown.length;
+    return [
+        'Schema issues:',
+        ...shown,
+        ...(hidden > 0 ? [`  and ${hidden} more.`] : []),
+    ];
+}
+function contractLines(apiContract, issues) {
+    return [
+        ...contractIssueLines(issues),
+        ...contractSkewLines(classifyContractSkew(apiContract)),
+        `CLI version: ${VERSION}.`,
+    ];
+}
 export function fromSdkFailure(error) {
     switch (error._tag) {
         case 'RequestFailure':
@@ -125,16 +213,19 @@ export function fromSdkFailure(error) {
                         error.code === 'auth_expired'
                             ? 'Open site settings in the dashboard, then Search Console, to reconnect.'
                             : undefined,
-                        error.code === 'contract_violation'
-                            ? CONTRACT_REMEDIATION
-                            : undefined,
+                        // The API reported the violation, so it carries no client-side issues.
+                        ...(error.code === 'contract_violation' ? contractLines(error.metadata.version, []) : []),
                     ].filter((line) => line !== undefined).join('\n'),
                     protocolResponse: error.response,
                 },
             };
         case 'ContractFailure':
-            return fail(EXIT_CODE.infrastructure, [`contract_violation: ${error.message}`, error.requestId ? `Request ID: ${error.requestId}` : undefined, CONTRACT_REMEDIATION, `Current CLI version: ${VERSION}`]
+            return fail(EXIT_CODE.infrastructure, [
+                `contract_violation: ${error.message}`,
+                error.requestId ? `Request ID: ${error.requestId}` : undefined,
+            ]
                 .filter((line) => line !== undefined)
+                .concat(contractLines(error.metadata.version, error.issues))
                 .join('\n'), undefined, 'contract_violation');
         case 'TransportFailure': {
             const timedOut = error.reason === 'aborted'

package/dist/pairing.js

@@ -5,10 +5,8 @@ import { VERSION } from './version.js';
 /**
  * Per-poll request deadline.
  *
- * `runtime.requestSignal` is NOT usable here: it is built once at startup as
- * `AbortSignal.any([runtime.signal, AbortSignal.timeout(globals.timeoutMs)])`,
- * so a poll loop bound to it would die after the default 30s. Each poll gets a
- * short deadline of its own, and the pairing deadline is tracked in the loop.
+ * Each poll gets a short deadline of its own, shorter than `--timeout-ms`, and
+ * the pairing deadline is tracked in the loop.
  */
 const POLL_REQUEST_TIMEOUT_MS = 8_000;
 export const CLIENT_NAME = 'nuxtseo-cli';

package/dist/pull.d.ts

@@ -0,0 +1,81 @@
+import type { PublicSdkResult, PublicV1Client, SdkFailure } from '@nuxtseo/sdk';
+import type { ApiContext } from './api.js';
+import type { CliFailure, CliResult, ExitCode } from './failures.js';
+import type { GlobalOptions } from './parse.js';
+import type { CliRuntime } from './runtime.js';
+type ProtocolResult = PublicSdkResult<unknown, SdkFailure>;
+/** Search Console periods `pull` accepts, mirrored from `search analytics`. */
+export declare const PULL_PERIODS: readonly ['7d', '28d', '3m', '6m', '12m'];
+export type PullPeriod = typeof PULL_PERIODS[number];
+export interface PullContext {
+    client: PublicV1Client;
+    siteId: string;
+    period: PullPeriod;
+    signal: AbortSignal;
+}
+/**
+ * One read `pull` performs, named by the command a caller would run alone.
+ *
+ * `spendsResearch` marks a read that can start live research, which draws on
+ * the Team research allowance. Those operations stay out of the default set.
+ */
+export interface PullOperation {
+    name: string;
+    spendsResearch: boolean;
+    request: (context: PullContext) => Promise<ProtocolResult>;
+}
+/**
+ * Every read `pull` knows, in the order it writes them.
+ *
+ * Only Site scoped, read-only, stored-evidence operations belong here. A
+ * mutation is excluded because a dump must never change server state. An
+ * operation that needs an argument a dump cannot invent, such as a URL, an
+ * action ID or a Scan ID, is excluded because there is nothing to pass.
+ */
+export declare const PULL_OPERATIONS: readonly PullOperation[];
+export interface PullSelection {
+    include?: string;
+    exclude?: string;
+    withResearch?: boolean;
+}
+/**
+ * The operations one `pull` run performs.
+ *
+ * The default set is every spend-free read. `--with-research` adds the reads
+ * that can start live research. `--include` narrows to the named commands, and
+ * naming a research read there is the same consent as `--with-research`.
+ * `--exclude` then removes what is left. An unknown name fails before any
+ * request, so a typo costs nothing.
+ */
+export declare function selectPullOperations(selection: PullSelection, operations?: readonly PullOperation[]): CliResult<readonly PullOperation[]>;
+export declare function worstExitCode(codes: readonly ExitCode[]): ExitCode;
+export interface PullOutcome {
+    /** The NDJSON line this read produced. */
+    line: unknown;
+    exitCode: ExitCode;
+    failure?: CliFailure;
+}
+/**
+ * One read as one NDJSON line.
+ *
+ * The server envelope is passed through whole, with one `command` field added
+ * beside `data` and `meta`. Nothing is merged, renamed, re-ranked or
+ * unwrapped, so a line reads exactly like the single command's own output. A
+ * failure with no server body writes a `CliError` value instead, tagged the
+ * same way.
+ */
+export declare function pullLine(command: string, result: ProtocolResult): PullOutcome;
+export interface PullArguments {
+    include?: string;
+    exclude?: string;
+    withResearch?: boolean;
+    period?: string;
+    concurrency?: string;
+}
+export declare const PULL_DEFAULT_CONCURRENCY = 4;
+export declare const PULL_MAX_CONCURRENCY = 8;
+export declare function runPull(runtime: CliRuntime, globals: GlobalOptions, args: PullArguments, resolve: (runtime: CliRuntime, globals: GlobalOptions) => Promise<CliResult<{
+    api: ApiContext;
+    siteId: string;
+}>>, catalogue?: readonly PullOperation[]): Promise<CliResult<void>>;
+export {};