@nuxtseo/cli 0.2.0 → 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);
         }
@@ -126,7 +130,7 @@ async function switchSite(runtime, globals) {
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(selected))
+    if (typeof selected === 'symbol')
         return fail(EXIT_CODE.interrupted, 'interrupted: Site selection cancelled.');
     const saved = await updateConfig({ siteId: selected }, { paths: runtime.paths });
     if (saved._tag === 'Err')
@@ -143,7 +147,7 @@ async function promptPageUrl(runtime, action) {
         signal: runtime.signal,
         validate: value => typeof value === 'string' && URL.canParse(value) ? undefined : 'Enter an absolute URL.',
     });
-    return prompts.isCancel(url)
+    return typeof url === 'symbol'
         ? fail(EXIT_CODE.interrupted, `interrupted: ${action} cancelled.`)
         : ok(url);
 }
@@ -158,7 +162,7 @@ async function promptTextValue(runtime, options) {
             ? undefined
             : `${options.label} is required.`,
     });
-    return prompts.isCancel(value)
+    return typeof value === 'symbol'
         ? fail(EXIT_CODE.interrupted, `interrupted: ${options.label} entry cancelled.`)
         : ok(value.trim());
 }
@@ -219,7 +223,7 @@ async function interactiveBare(runtime, globals) {
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(group) || group === 'exit')
+    if (typeof group === 'symbol' || group === 'exit')
         return ok(undefined);
     if (group === 'login')
         return runInteractiveCommand(['login'], runtime, globals);
@@ -239,7 +243,7 @@ async function interactiveBare(runtime, globals) {
             output: runtime.error,
             signal: runtime.signal,
         });
-        if (prompts.isCancel(task))
+        if (typeof task === 'symbol')
             return ok(undefined);
         if (task === 'inspect' || task === 'scan') {
             const url = await promptPageUrl(runtime, task === 'inspect' ? 'Inspect' : 'Scan');
@@ -278,7 +282,7 @@ async function interactiveBare(runtime, globals) {
             output: runtime.error,
             signal: runtime.signal,
         });
-        if (prompts.isCancel(task))
+        if (typeof task === 'symbol')
             return ok(undefined);
         const command = task === 'performance'
             ? ['performance']
@@ -318,7 +322,7 @@ async function interactiveBare(runtime, globals) {
             output: runtime.error,
             signal: runtime.signal,
         });
-        if (prompts.isCancel(task))
+        if (typeof task === 'symbol')
             return ok(undefined);
         if (task === 'overview')
             return runInteractiveCommand(['research', 'overview'], runtime, globals);
@@ -362,7 +366,7 @@ async function interactiveBare(runtime, globals) {
             output: runtime.error,
             signal: runtime.signal,
         });
-        if (prompts.isCancel(task))
+        if (typeof task === 'symbol')
             return ok(undefined);
         if (task === 'briefs')
             return runInteractiveCommand(['content', 'briefs', 'list'], runtime, globals);
@@ -394,7 +398,7 @@ async function interactiveBare(runtime, globals) {
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(task))
+    if (typeof task === 'symbol')
         return ok(undefined);
     if (task === 'site')
         return switchSite(runtime, globals);
@@ -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

@@ -1,4 +1,5 @@
 import * as prompts from '@clack/prompts';
+import { accountFeedbackBodySchema } from '@nuxtseo/protocol/v1/account';
 import { publicV1BooleanFlagValue } from '@nuxtseo/protocol/v1/core';
 import { defineCommand } from 'citty';
 import { dirname } from 'pathe';
@@ -7,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')
@@ -97,7 +118,7 @@ async function confirmMutation(runtime, globals, message) {
         signal: runtime.signal,
         initialValue: false,
     });
-    if (prompts.isCancel(confirmed))
+    if (typeof confirmed === 'symbol')
         return fail(EXIT_CODE.interrupted, 'interrupted: Mutation cancelled.');
     return ok(confirmed);
 }
@@ -111,7 +132,7 @@ async function readLoginToken(runtime) {
             signal: runtime.signal,
             validate: value => typeof value === 'string' && value.trim() ? undefined : 'Token is required.',
         });
-        if (prompts.isCancel(token))
+        if (typeof token === 'symbol')
             return fail(EXIT_CODE.interrupted, 'interrupted: Login cancelled.');
         return ok(token.trim());
     }
@@ -277,7 +298,7 @@ async function config(runtime, globals) {
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(action) || action === 'done')
+    if (typeof action === 'symbol' || action === 'done')
         return ok(undefined);
     if (action === 'api') {
         const next = await prompts.text({
@@ -287,7 +308,7 @@ async function config(runtime, globals) {
             output: runtime.error,
             signal: runtime.signal,
         });
-        if (prompts.isCancel(next))
+        if (typeof next === 'symbol')
             return fail(EXIT_CODE.interrupted, 'interrupted: Configuration cancelled.');
         const written = await updateConfig({ apiUrl: next }, { paths: runtime.paths });
         if (written._tag === 'Err')
@@ -345,6 +366,25 @@ async function usage(runtime, globals, group) {
     const response = await withSpinner(runtime, 'Loading usage', () => api.value.client.account.usage({ query: { group } }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, renderUsage);
 }
+async function feedbackSubmit(runtime, globals, args) {
+    const body = accountFeedbackBodySchema.safeParse({ ...args, cliVersion: VERSION });
+    if (!body.success)
+        return fail(EXIT_CODE.invalidInput, 'Pass valid --command, --comment, and --agent values. Read feedback submit --help for limits.', undefined, 'invalid_cli_input');
+    const confirmed = await confirmMutation(runtime, globals, 'Submit this agent report to NuxtSEO feedback?');
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Feedback cancelled.');
+        return ok(undefined);
+    }
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const response = await withSpinner(runtime, 'Submitting feedback', () => api.value.client.account.feedback({
+        body: body.data,
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => `Feedback saved: ${value.data.id} (${value.data.status})`);
+}
 async function actionsList(runtime, globals, args) {
     const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 25, defaultValue: 10 });
     if (limit._tag === 'Err')
@@ -698,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;
@@ -727,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,
@@ -934,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')
@@ -941,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) {
@@ -949,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);
 }
@@ -1877,8 +1959,8 @@ export function createRootCommand(runtime, globals, execution) {
             'changes': defineCommand({
                 meta: { name: 'changes', description: 'Compare the latest crawl with its baseline' },
                 args: {
-                    from: { type: 'string', description: 'Baseline crawl generation' },
-                    to: { type: 'string', description: 'Comparison crawl generation' },
+                    from: { type: 'string', description: 'Baseline crawl number' },
+                    to: { type: 'string', description: 'Comparison crawl number' },
                 },
                 run: ({ args }) => capture(execution, () => auditChanges(runtime, globals, {
                     from: args.from,
@@ -2088,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: {
@@ -2155,6 +2254,28 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => config(runtime, globals), args._, 0)(),
             }),
             sites,
+            feedback: defineCommand({
+                meta: { name: 'feedback', description: 'Report CLI problems to NuxtSEO' },
+                subCommands: {
+                    submit: defineCommand({
+                        meta: { name: 'submit', description: 'Submit sanitized agent feedback without selecting a Site' },
+                        args: {
+                            'command': { type: 'string', required: true, description: 'Affected command without secrets or private arguments, maximum 200 characters' },
+                            'comment': { type: 'string', required: true, description: 'Agent disclosure, reproduction steps, expected result, actual result, and workaround, maximum 2000 characters' },
+                            'agent': { type: 'string', required: true, description: 'Reporting agent name, maximum 100 characters' },
+                            'intent': { type: 'enum', options: ['bug', 'improvement'], description: 'Feedback intent, default bug' },
+                            'request-id': { type: 'string', description: 'Request ID from the affected response, maximum 128 characters' },
+                        },
+                        run: ({ args }) => capture(execution, () => feedbackSubmit(runtime, globals, {
+                            command: args.command,
+                            comment: args.comment,
+                            agent: args.agent,
+                            intent: args.intent,
+                            requestId: args['request-id'],
+                        }), args._, 0)(),
+                    }),
+                },
+            }),
             usage: defineCommand({
                 meta: { name: 'usage', description: 'Read account usage' },
                 args: {
@@ -2177,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'