@nuxtseo/cli 0.2.0 → 0.3.0

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,362 @@
+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('content briefs list', context => context.client.content.listBriefs({
+        params: { siteId: context.siteId },
+        query: { limit: 25, offset: 0 },
+    }, { 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,10 @@ 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 { BacklinkAnchors, BacklinksHistory, BacklinksSummary, MentionsData, RecoverableBacklinksData, ReferringDomains } from '@nuxtseo/protocol/v1/backlinks';
 import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
 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 +16,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;
@@ -46,8 +46,8 @@ 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')),

package/dist/runtime.d.ts

@@ -9,11 +9,16 @@ export interface CliRuntime {
     inputIsTTY: boolean;
     interactive: boolean;
     signal: AbortSignal;
+    /** Read once per request. Each read carries its own `--timeout-ms` deadline. */
     requestSignal: AbortSignal;
     requestTimeoutMs?: number;
     readStdin: () => Promise<string>;
 }
 export declare function writeOutput(runtime: CliRuntime, text: string): void;
 export declare function writeDiagnostic(runtime: CliRuntime, text: string): void;
+/**
+ * Machine output is written through these two functions only. Both strip ANSI
+ * escapes, so no dependency can colour a string into a JSON envelope.
+ */
 export declare function writeProtocolResponse(runtime: CliRuntime, response: unknown): void;
 export declare function writeCliResponse(runtime: CliRuntime, response: unknown): void;

package/dist/runtime.js

@@ -1,12 +1,17 @@
+import { stringifyWithoutAnsi } from './ansi.js';
 export function writeOutput(runtime, text) {
     runtime.output.write(text.endsWith('\n') ? text : `${text}\n`);
 }
 export function writeDiagnostic(runtime, text) {
     runtime.error.write(text.endsWith('\n') ? text : `${text}\n`);
 }
+/**
+ * Machine output is written through these two functions only. Both strip ANSI
+ * escapes, so no dependency can colour a string into a JSON envelope.
+ */
 export function writeProtocolResponse(runtime, response) {
-    writeOutput(runtime, JSON.stringify(response));
+    writeOutput(runtime, stringifyWithoutAnsi(response));
 }
 export function writeCliResponse(runtime, response) {
-    writeOutput(runtime, JSON.stringify(response));
+    writeOutput(runtime, stringifyWithoutAnsi(response));
 }

package/dist/skill.d.ts

@@ -1,11 +1,31 @@
 import type { CliResult } from './failures.js';
+import type { StatePaths } from './state/index.js';
 export declare const SKILL_NAME = "nuxtseo-cli";
+/** The stamp an install leaves beside the skill so a later run can read its version. */
+export declare const SKILL_VERSION_FILENAME = ".skill-version.json";
+/** The skill entry file, which also carries the version in its frontmatter. */
+export declare const SKILL_MARKDOWN_FILENAME = "SKILL.md";
+/**
+ * How long one answer stays authoritative, matching the npm update check.
+ *
+ * Declared here rather than imported so `update-check.ts` can depend on this
+ * module and the two never form an import cycle.
+ */
+export declare const SKILL_CHECK_INTERVAL_MS: number;
 export declare const SKILL_AGENTS: readonly ['claude', 'codex'];
 export type SkillAgent = typeof SKILL_AGENTS[number];
 export interface SkillInstallation {
     agent: SkillAgent;
     source: string;
+    /** The path the caller asked for, which may be a symlink. */
     destination: string;
+    /** Where the files actually landed, after following a symlinked destination. */
+    resolvedDestination: string;
+    version: string;
+    /** Files written by this install. */
+    written: number;
+    /** Files removed because this release no longer ships them. */
+    pruned: number;
 }
 /**
  * The skill shipped inside this package. A global install puts it outside the
@@ -14,9 +34,88 @@ export interface SkillInstallation {
  */
 export declare function skillSourceDirectory(moduleUrl?: string): string;
 export declare function skillDestination(homeDirectory: string, agent: SkillAgent): string;
+/**
+ * The install target, followed through a symlink.
+ *
+ * People keep their skills in one directory and link each agent's skill folder
+ * at it. `fs.cp` lstats the target, sees a link rather than a directory, and
+ * refuses with `ERR_FS_CP_DIR_TO_NON_DIR` before it copies anything. That
+ * reported as a permission problem on a directory the user owned and could
+ * write. Follow the link first so the copy writes where the person pointed it.
+ */
+export declare function resolveSkillTarget(destination: string): Promise<string>;
+/** An errno or Node error as a person can act on it: code, call, and path. */
+export declare function describeIoCause(cause: unknown): string;
+/**
+ * Write the running version into the skill frontmatter.
+ *
+ * An agent reads `SKILL.md` and nothing else, so the file has to say which
+ * release it came from. Without it a skill from an older CLI hides every
+ * command added since, and the agent cannot tell.
+ */
+export declare function stampSkillVersion(markdown: string, version: string): string;
+/** The version recorded in a `SKILL.md` frontmatter, when it carries one. */
+export declare function frontmatterVersion(markdown: string): string | null;
+export type InstalledSkill = {
+    _tag: 'SkillMissing';
+} | {
+    _tag: 'SkillUnversioned';
+} | {
+    _tag: 'SkillVersion';
+    version: string;
+};
+/**
+ * Which version of the skill sits in a destination directory.
+ *
+ * Reads the stamp first, then the frontmatter, so a skill installed by hand or
+ * by an older release still reports something the caller can compare.
+ */
+export declare function readInstalledSkill(destination: string): Promise<InstalledSkill>;
+export interface SkillNotice {
+    agent: SkillAgent;
+    installed: string | null;
+    current: string;
+}
+/**
+ * A stale installed skill, or `null` when nothing needs saying.
+ *
+ * An absent skill is not stale: the person may not use one. Any other
+ * difference from the running binary is, in both directions, because the two
+ * describe different command sets.
+ */
+export declare function skillNoticeFor(installed: InstalledSkill, current: string, agent: SkillAgent): SkillNotice | null;
+export declare function skillNoticeLine(notice: SkillNotice): string;
+export interface SkillCheckCache {
+    lastCheckedAt: string;
+    cliVersion: string;
+    installed: Partial<Record<SkillAgent, string | null>>;
+}
+export declare function parseSkillCheckCache(content: string): SkillCheckCache | null;
+/**
+ * Whether the filesystem has to be read again.
+ *
+ * A cache from a different binary is never reusable: the binary version is half
+ * of the comparison, so an upgrade must warn on the very next run.
+ */
+export declare function skillCheckDue(cache: SkillCheckCache | null, now: Date, current: string): boolean;
+export interface SkillCheckOptions {
+    paths: StatePaths;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => Date;
+    /** The home the agent directories sit in; defaults to the state directory's parent. */
+    homeDirectory?: string;
+}
+/**
+ * One line's worth of "your installed skill is not this binary".
+ *
+ * Costs one cached read per day, and nothing at all when the caller disabled
+ * update checks.
+ */
+export declare function checkSkillVersion(options: SkillCheckOptions): Promise<SkillNotice | null>;
 export declare function installSkill(options: {
     agent: SkillAgent;
     homeDirectory: string;
     target?: string;
     sourceDirectory?: string;
+    paths?: StatePaths;
 }): Promise<CliResult<SkillInstallation>>;