@nuxtseo/cli 0.2.1 → 0.4.0

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 {};

package/dist/pull.js

@@ -0,0 +1,358 @@
+import { publicV1BooleanFlagValue } from '@nuxtseo/protocol/v1/core';
+import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
+import { DEFAULT_TIMEOUT_MS, parseChoice, parseInteger } from './parse.js';
+import { writeDiagnostic, writeProtocolResponse } from './runtime.js';
+/** Search Console periods `pull` accepts, mirrored from `search analytics`. */
+export const PULL_PERIODS = ['7d', '28d', '3m', '6m', '12m'];
+function operation(name, request) {
+    return { name, spendsResearch: false, request };
+}
+function researchOperation(name, request) {
+    return { name, spendsResearch: true, request };
+}
+const SEARCH_ANALYTICS_VIEWS = ['pages', 'keywords', 'countries', 'devices', 'timeseries'];
+const ANALYTICS_VIEWS = ['performance', 'top-pages', 'source-medium', 'key-events', 'countries', 'devices'];
+/**
+ * Per-operation row limits.
+ *
+ * `search indexing urls` timed out twice at 500 rows on the 30000 ms deadline
+ * and answered at 50. A dump needs every operation to finish, so the limits
+ * here favour completion over depth. If one read needs more rows, run that
+ * command alone with `--all`.
+ */
+const SEARCH_INDEXING_URL_LIMIT = 50;
+const SITEMAP_URL_LIMIT = 200;
+/**
+ * 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 const PULL_OPERATIONS = [
+    operation('status', context => context.client.sites.status({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('actions list', context => context.client.actions.list({
+        params: { siteId: context.siteId },
+        query: { limit: 25, offset: 0 },
+    }, { signal: context.signal })),
+    operation('audit changes', context => context.client.audit.changes({
+        params: { siteId: context.siteId },
+        query: {},
+    }, { signal: context.signal })),
+    operation('audit content-decay', context => context.client.audit.contentDecay({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('audit duplicates', context => context.client.audit.duplicateClusters({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('audit link-opportunities', context => context.client.audit.linkOpportunities({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('audit link-structure', context => context.client.audit.linkStructure({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('performance', context => context.client.performance.overview({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('scans list', context => context.client.performance.scans({
+        params: { siteId: context.siteId },
+        query: { limit: 25 },
+    }, { signal: context.signal })),
+    operation('scans pages', context => context.client.performance.monitoredPages({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('vitals summary', context => context.client.performance.vitals({
+        params: { siteId: context.siteId },
+        query: { formFactor: 'PHONE', view: 'summary' },
+    }, { signal: context.signal })),
+    operation('vitals trend', context => context.client.performance.vitals({
+        params: { siteId: context.siteId },
+        query: { formFactor: 'PHONE', view: 'trend' },
+    }, { signal: context.signal })),
+    operation('vitals findings', context => context.client.performance.vitalFindings({
+        params: { siteId: context.siteId },
+        query: { onlyFailing: publicV1BooleanFlagValue(true), limit: 20, offset: 0 },
+    }, { signal: context.signal })),
+    operation('search status', context => context.client.search.readStatus({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    ...SEARCH_ANALYTICS_VIEWS.map(view => operation(`search analytics ${view}`, context => context.client.search.queryAnalytics({
+        params: { siteId: context.siteId },
+        query: { view, period: context.period, limit: 25, page: 1, sort: 'clicks', sortDir: 'desc' },
+    }, { signal: context.signal }))),
+    operation('search indexing summary', context => context.client.search.readIndexingDiagnostics({
+        params: { siteId: context.siteId },
+        query: { view: 'summary', limit: SEARCH_INDEXING_URL_LIMIT, offset: 0 },
+    }, { signal: context.signal })),
+    operation('search indexing urls', context => context.client.search.readIndexingDiagnostics({
+        params: { siteId: context.siteId },
+        query: { view: 'urls', limit: SEARCH_INDEXING_URL_LIMIT, offset: 0 },
+    }, { signal: context.signal })),
+    operation('search cohorts', context => context.client.search.readIndexingCohorts({
+        params: { siteId: context.siteId },
+        query: { limit: 12, minSectionPages: 5 },
+    }, { signal: context.signal })),
+    operation('search index-history', context => context.client.search.readIndexingHistory({
+        params: { siteId: context.siteId },
+        query: { days: 180 },
+    }, { signal: context.signal })),
+    operation('sitemaps list', context => context.client.sitemaps.list({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('sitemaps urls', context => context.client.sitemaps.listUrls({
+        params: { siteId: context.siteId },
+        query: { limit: SITEMAP_URL_LIMIT },
+    }, { signal: context.signal })),
+    ...ANALYTICS_VIEWS.map(view => operation(`analytics ${view}`, context => context.client.analytics.query({
+        params: { siteId: context.siteId, view },
+        query: {
+            period: '28d',
+            compare: 'previous',
+            stableData: true,
+            hostScope: true,
+            performancePhase: 'full',
+            comparePrior: true,
+            fresh: false,
+        },
+    }, { signal: context.signal }))),
+    operation('research overview', context => context.client.research.overview({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    operation('backlinks recoverable', context => context.client.backlinks.recoverable({
+        params: { siteId: context.siteId },
+        query: { limit: 100, offset: 0 },
+    }, { signal: context.signal })),
+    operation('mentions list', context => context.client.mentions.list({
+        params: { siteId: context.siteId },
+        query: { limit: 100, includeFiltered: publicV1BooleanFlagValue(false) },
+    }, { signal: context.signal })),
+    operation('timeline list', context => context.client.timeline.entries({
+        params: { siteId: context.siteId },
+        query: { limit: 25 },
+    }, { signal: context.signal })),
+    operation('annotations list', context => context.client.timeline.listAnnotations({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    researchOperation('backlinks summary', context => context.client.backlinks.summary({
+        params: { siteId: context.siteId },
+    }, { signal: context.signal })),
+    researchOperation('backlinks referring-domains', context => context.client.backlinks.referringDomains({
+        params: { siteId: context.siteId },
+        query: { limit: 100 },
+    }, { signal: context.signal })),
+    researchOperation('backlinks anchors', context => context.client.backlinks.anchors({
+        params: { siteId: context.siteId },
+        query: { limit: 100 },
+    }, { signal: context.signal })),
+    researchOperation('backlinks history', context => context.client.backlinks.history({
+        params: { siteId: context.siteId },
+        query: {},
+    }, { signal: context.signal })),
+];
+function selectorTokens(input) {
+    return (input ?? '').split(',').map(token => token.trim()).filter(Boolean);
+}
+/**
+ * A token selects an operation when it names that operation, or names a
+ * command that contains it. `audit` selects every `audit *` read, so a caller
+ * narrows a family without spelling each leaf.
+ */
+function matches(token, name) {
+    return name === token || name.startsWith(`${token} `);
+}
+/**
+ * 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 function selectPullOperations(selection, operations = PULL_OPERATIONS) {
+    const include = selectorTokens(selection.include);
+    const exclude = selectorTokens(selection.exclude);
+    const unknown = [...include, ...exclude]
+        .filter(token => !operations.some(candidate => matches(token, candidate.name)));
+    if (unknown.length > 0) {
+        return fail(EXIT_CODE.invalidInput, [
+            `invalid_cli_input: No pull operation is named ${unknown.map(token => JSON.stringify(token)).join(', ')}.`,
+            `Valid names: ${operations.map(candidate => candidate.name).join(', ')}.`,
+        ].join('\n'));
+    }
+    const selected = operations.filter((candidate) => {
+        const chosen = include.length > 0
+            ? include.some(token => matches(token, candidate.name))
+            : !candidate.spendsResearch || selection.withResearch === true;
+        return chosen && !exclude.some(token => matches(token, candidate.name));
+    });
+    if (selected.length === 0)
+        return fail(EXIT_CODE.invalidInput, 'invalid_cli_input: The selected filters leave no operation to run.');
+    return ok(selected);
+}
+/**
+ * How bad each outcome is, so one run reports its worst.
+ *
+ * Authentication outranks the rest because it stops the run: every later read
+ * would fail the same way. Interrupted outranks that again, because the caller
+ * asked for the stop.
+ */
+const EXIT_SEVERITY = new Map([
+    [EXIT_CODE.success, 0],
+    [EXIT_CODE.pagingCapReached, 1],
+    [EXIT_CODE.retryable, 2],
+    [EXIT_CODE.conflict, 3],
+    [EXIT_CODE.notFound, 4],
+    [EXIT_CODE.authorization, 5],
+    [EXIT_CODE.invalidInput, 6],
+    [EXIT_CODE.infrastructure, 7],
+    [EXIT_CODE.authentication, 8],
+    [EXIT_CODE.interrupted, 9],
+]);
+export function worstExitCode(codes) {
+    return codes.reduce((worst, code) => (EXIT_SEVERITY.get(code) ?? 0) > (EXIT_SEVERITY.get(worst) ?? 0) ? code : worst, EXIT_CODE.success);
+}
+/**
+ * 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 function pullLine(command, result) {
+    if (result._tag === 'Ok')
+        return { line: { command, ...result.value }, exitCode: EXIT_CODE.success };
+    const converted = fromSdkFailure(result.error);
+    const failure = converted.error;
+    const body = failure.protocolResponse;
+    return {
+        line: body !== undefined && body !== null && typeof body === 'object'
+            ? { command, ...body }
+            : {
+                command,
+                _tag: 'CliError',
+                schemaVersion: 1,
+                error: { code: failure.code, exitCode: failure.exitCode, message: failure.message },
+            },
+        exitCode: failure.exitCode,
+        failure,
+    };
+}
+async function forEachBounded(items, concurrency, worker) {
+    let cursor = 0;
+    const next = async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            await worker(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, next));
+}
+export const PULL_DEFAULT_CONCURRENCY = 4;
+export const PULL_MAX_CONCURRENCY = 8;
+function spendNotice(operations) {
+    const spending = operations.filter(candidate => candidate.spendsResearch);
+    return spending.length === 0
+        ? undefined
+        : [
+            `These reads can start live research and draw on the Team research allowance: ${spending.map(candidate => candidate.name).join(', ')}.`,
+            'Each envelope reports cache use in `evidence`. Run `nuxtseo usage` to read the allowance.',
+        ].join('\n');
+}
+export async function runPull(runtime, globals, args, resolve, catalogue = PULL_OPERATIONS) {
+    // `pull` answers with NDJSON and nothing else. There is no text rendering
+    // for a stream of thirty envelopes, so the flag is required rather than
+    // silently ignored.
+    if (!globals.json)
+        return fail(EXIT_CODE.invalidInput, 'invalid_cli_input: `pull` writes NDJSON only. Run it with --json.');
+    const period = parseChoice(args.period, { name: '--period', choices: PULL_PERIODS, defaultValue: '28d' });
+    if (period._tag === 'Err')
+        return period;
+    const concurrency = parseInteger(args.concurrency, {
+        name: '--concurrency',
+        minimum: 1,
+        maximum: PULL_MAX_CONCURRENCY,
+        defaultValue: PULL_DEFAULT_CONCURRENCY,
+    });
+    if (concurrency._tag === 'Err')
+        return concurrency;
+    const selected = selectPullOperations({
+        include: args.include,
+        exclude: args.exclude,
+        withResearch: args.withResearch,
+    }, catalogue);
+    if (selected._tag === 'Err')
+        return selected;
+    const resolved = await resolve(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const operations = selected.value;
+    const notice = spendNotice(operations);
+    if (notice)
+        writeDiagnostic(runtime, notice);
+    writeDiagnostic(runtime, `Pulling ${operations.length} reads for ${resolved.value.siteId}, ${concurrency.value} at a time.`);
+    // Every read gets its own deadline. The global `--timeout-ms` signal starts
+    // when the process starts, so sharing it would abort the later reads of a
+    // long run before they were even sent.
+    const timeoutMs = runtime.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const exitCodes = [];
+    const skipped = [];
+    let stopped = false;
+    let completed = 0;
+    await forEachBounded(operations, concurrency.value, async (candidate) => {
+        if (stopped) {
+            skipped.push(candidate.name);
+            return;
+        }
+        const signal = AbortSignal.any([runtime.signal, AbortSignal.timeout(timeoutMs)]);
+        const result = await candidate.request({
+            client: resolved.value.api.client,
+            siteId: resolved.value.siteId,
+            period: period.value,
+            signal,
+        });
+        const outcome = pullLine(candidate.name, result);
+        writeProtocolResponse(runtime, outcome.line);
+        exitCodes.push(outcome.exitCode);
+        completed++;
+        // An expired or rejected credential fails every later read the same way.
+        // Stopping there saves the requests and keeps the reason on one line.
+        if (outcome.exitCode === EXIT_CODE.authentication || outcome.exitCode === EXIT_CODE.interrupted)
+            stopped = true;
+        writeDiagnostic(runtime, `[${completed}/${operations.length}] ${candidate.name} ${outcome.failure ? `failed: ${outcome.failure.code}` : 'ok'}`);
+    });
+    const failed = exitCodes.filter(code => code !== EXIT_CODE.success).length;
+    writeDiagnostic(runtime, [
+        `Pull finished: ${exitCodes.length - failed} ok, ${failed} failed`,
+        skipped.length > 0 ? `, ${skipped.length} skipped after an authentication failure` : '',
+        '.',
+    ].join(''));
+    if (skipped.length > 0)
+        writeDiagnostic(runtime, `Skipped: ${skipped.join(', ')}.`);
+    const worst = worstExitCode(exitCodes);
+    if (worst === EXIT_CODE.success)
+        return ok(undefined);
+    const message = `pull_incomplete: ${failed} of ${operations.length} reads failed. Read each failed line for the cause.`;
+    // The run summary is the last NDJSON line, so stdout stays one value per
+    // line and the caller never has to read stderr to learn the outcome.
+    return {
+        _tag: 'Err',
+        error: {
+            _tag: 'CliFailure',
+            code: 'pull_incomplete',
+            exitCode: worst,
+            message,
+            protocolResponse: {
+                command: 'pull',
+                _tag: 'CliError',
+                schemaVersion: 1,
+                error: { code: 'pull_incomplete', exitCode: worst, message },
+            },
+        },
+    };
+}

package/dist/render.d.ts

@@ -3,10 +3,9 @@ import type { AccountTokenData } from '@nuxtseo/protocol/v1/account';
 import type { ActionDismiss, ActionList, ActionResolve, ActionShow } from '@nuxtseo/protocol/v1/actions';
 import type { AnalyticsQueryData, AnalyticsView } from '@nuxtseo/protocol/v1/analytics';
 import type { AuditChanges, AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities, AuditLinkStructure } from '@nuxtseo/protocol/v1/audit';
-import type { BacklinkAnchors, BacklinksHistory, BacklinksSummary, Mentions, RecoverableBacklinks, ReferringDomains } from '@nuxtseo/protocol/v1/backlinks';
-import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
+import type { BacklinkAnchors, BacklinksHistory, BacklinksSummary, MentionsData, RecoverableBacklinksData, ReferringDomains } from '@nuxtseo/protocol/v1/backlinks';
 import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData } from '@nuxtseo/protocol/v1/gsc';
-import type { PageInspect, PageIssues, PageScan } from '@nuxtseo/protocol/v1/pages';
+import type { PageInspectData, PageIssues, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { FieldVitalFindings, FieldVitals, MonitoredPages, PerformanceScanDetail, PerformanceScans, SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
 import type { DomainAvailability, DomainTraffic, KeywordResearchData, RankingsResearchData, SerpResearchData, StoredResearchOverview } from '@nuxtseo/protocol/v1/research';
 import type { SiteSitemapActionResponse, SiteSitemapsResponse, SiteSitemapUrlsResponse } from '@nuxtseo/protocol/v1/sitemaps';
@@ -16,7 +15,7 @@ export declare function renderUsage(response: AccountUsageResponse): string;
 export declare function renderActions(data: ActionList): string;
 export declare function renderAction(data: ActionShow): string;
 export declare function renderActionResolution(data: ActionResolve): string;
-export declare function renderPageInspection(data: PageInspect): string;
+export declare function renderPageInspection(data: PageInspectData): string;
 export declare function renderPageScan(data: PageScan): string;
 export declare function renderPerformance(data: SitePerformanceOverview): string;
 export declare function renderSearchStatus(data: SearchStatusData): string;
@@ -39,15 +38,12 @@ export declare function renderResearchOverview(data: StoredResearchOverview): st
 export declare function renderKeywordResearch(data: KeywordResearchData): string;
 export declare function renderSerpResearch(data: SerpResearchData): string;
 export declare function renderRankingsResearch(data: RankingsResearchData): string;
-export declare function renderContentBriefs(data: ContentBriefListData): string;
-export declare function renderContentBrief(data: ContentBrief): string;
-export declare function renderContentBriefCreated(data: ContentBriefCreateData): string;
 export declare function renderContentDecay(data: AuditContentDecay): string;
 export declare function renderDuplicateClusters(data: AuditDuplicateClusters): string;
 export declare function renderLinkOpportunities(data: AuditLinkOpportunities): string;
 export declare function renderTimeline(data: TimelineEntries): string;
-export declare function renderRecoverableBacklinks(data: RecoverableBacklinks): string;
-export declare function renderMentions(data: Mentions): string;
+export declare function renderRecoverableBacklinks(data: RecoverableBacklinksData): string;
+export declare function renderMentions(data: MentionsData): string;
 export declare function renderFieldVitals(data: FieldVitals): string;
 export declare function renderFieldVitalFindings(data: FieldVitalFindings): string;
 export declare function renderBacklinksSummary(data: BacklinksSummary): string;

package/dist/render.js

@@ -190,7 +190,7 @@ export function renderSearchAnalytics(data) {
     return [
         `${data.preset} (${data.rows.length} of ${data.total})  ${data.description}`,
         ...data.rows.map(row => [
-            `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos.toFixed(1)}`,
+            `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos === null ? 'none' : row.pos.toFixed(1)}`,
             `  ${row.keyword}`,
             row.page ? `  ${row.page}` : '',
         ].filter(Boolean).join('\n')),
@@ -482,27 +482,6 @@ export function renderRankingsResearch(data) {
         ...data.keywords.map(row => `${row.position}. ${row.keyword}  ${row.volume} volume  ${row.traffic} traffic\n  ${row.url}`),
     ].join('\n');
 }
-export function renderContentBriefs(data) {
-    if (data.briefs.length === 0)
-        return 'No Content Briefs match these filters.';
-    return [
-        `Content Briefs (${data.briefs.length} of ${data.page.total})`,
-        ...data.briefs.map(brief => `${brief.id}  ${brief.status}\n  ${brief.keyword}`),
-    ].join('\n');
-}
-export function renderContentBrief(data) {
-    return fields([
-        ['Content Brief', data.id],
-        ['Keyword', data.keyword],
-        ['Status', data.status],
-        ['Generated', data.generatedAt],
-        ['Updated', data.updatedAt],
-        ['Error', data.error],
-    ]);
-}
-export function renderContentBriefCreated(data) {
-    return `${data.created ? 'Created' : 'Found existing'} Content Brief.\n${renderContentBrief(data.brief)}`;
-}
 export function renderContentDecay(data) {
     if (!data.connected)
         return 'Connect Search Console to find content decay.';