@nuxtseo/cli 0.1.1 → 0.1.3

package/README.md

@@ -172,6 +172,7 @@ nuxtseo page scan <url>
 nuxtseo performance
 nuxtseo search status
 nuxtseo search analytics <pages|keywords>
+nuxtseo search indexing <summary|urls>
 nuxtseo research overview
 nuxtseo research keywords <topic>
 nuxtseo research serp <keyword>
@@ -189,6 +190,7 @@ performance, research, content, and account setup. The menu prints the direct
 command it runs.
 
 `search status` reads stored connection state. It never waits for Google.
+`search indexing summary` reads retained URL Inspection coverage.
 `research keywords`, `research serp`, and `research rankings` can use the Team
 research allowance. Keyword responses report cache use in `evidence`. SERP and
 ranking responses report `cached: true`. Cached responses use no unit.
@@ -204,6 +206,7 @@ responses.
 | `backlinks recoverable` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
 | `mentions list` | `--limit 1..200` | `--limit 100` |
 | `search analytics` | `--limit 1..100`, `--page >=1` | `--limit 25 --page 1` |
+| `search indexing` | `--limit 1..500`, `--offset >=0` | `--limit 50 --offset 0` |
 | `content briefs list` | `--limit 1..100`, `--offset >=0` | `--limit 25 --offset 0` |
 
 Keep the server order for actions. For another page, pass the next offset or

package/dist/cli.js

@@ -7,16 +7,28 @@ import { EXIT_CODE, fail, fromSdkFailure, ok, unexpectedFailure } from './failur
 import { extractGlobalOptions } from './parse.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { getCredentialStatus, readConfig, resolveApiUrl, resolveSiteId, updateConfig } from './state/index.js';
+import { checkForUpdate, updateNoticeLine } from './update-check.js';
 import { VERSION } from './version.js';
-function report(runtime, failure, json = false) {
+function writeUpdateNotice(runtime, notice) {
+    if (notice)
+        writeDiagnostic(runtime, updateNoticeLine(notice));
+}
+function report(runtime, failure, json = false, notice = null) {
     if (json) {
         if (failure.protocolResponse !== undefined) {
             writeProtocolResponse(runtime, failure.protocolResponse);
         }
         else {
+            // Exit 2 and exit 7 are where a stale binary masquerades as broken docs
+            // or a broken server. Version skew is a plausible cause there, so the
+            // envelope names both versions and stderr carries the update command.
+            const carriesVersionSkew = failure.exitCode === EXIT_CODE.invalidInput || failure.exitCode === EXIT_CODE.infrastructure;
             writeCliResponse(runtime, {
                 _tag: 'CliError',
                 schemaVersion: 1,
+                ...(carriesVersionSkew
+                    ? { cliVersion: VERSION, ...(notice ? { latestKnownVersion: notice.latest } : {}) }
+                    : {}),
                 error: {
                     code: failure.code,
                     exitCode: failure.exitCode,
@@ -240,6 +252,7 @@ async function interactiveBare(runtime, globals) {
             options: [
                 { value: 'performance', label: 'Performance overview' },
                 { value: 'connection', label: 'Search Console connection' },
+                { value: 'indexing', label: 'Search indexing coverage' },
                 { value: 'pages', label: 'Search Console Pages' },
                 { value: 'keywords', label: 'Search Console queries' },
             ],
@@ -253,7 +266,9 @@ async function interactiveBare(runtime, globals) {
             ? ['performance']
             : task === 'connection'
                 ? ['search', 'status']
-                : ['search', 'analytics', task];
+                : task === 'indexing'
+                    ? ['search', 'indexing', 'summary']
+                    : ['search', 'analytics', task];
         return runInteractiveCommand(command, runtime, globals);
     }
     if (group === 'research') {
@@ -336,9 +351,16 @@ async function interactiveBare(runtime, globals) {
 }
 export async function runCli(rawArgs, runtime) {
     const jsonRequested = rawArgs.includes('--json');
+    // 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 parsed = extractGlobalOptions(rawArgs);
-    if (parsed._tag === 'Err')
-        return report(runtime, parsed.error, jsonRequested);
+    if (parsed._tag === 'Err') {
+        const notice = await updateCheck;
+        writeUpdateNotice(runtime, notice);
+        return report(runtime, parsed.error, jsonRequested, notice);
+    }
     const { args, options: globals } = parsed.value;
     const effectiveRuntime = {
         ...runtime,
@@ -350,21 +372,28 @@ export async function runCli(rawArgs, runtime) {
         requestTimeoutMs: globals.timeoutMs,
     };
     if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+        const notice = await updateCheck;
         if (globals.json)
             writeCliResponse(effectiveRuntime, { _tag: 'CliVersion', schemaVersion: 1, version: VERSION });
         else
             writeOutput(effectiveRuntime, VERSION);
+        writeUpdateNotice(effectiveRuntime, notice);
         return EXIT_CODE.success;
     }
     if (args.includes('--help') || args.includes('-h')) {
         const command = createRootCommand(effectiveRuntime, globals, { result: null });
         const validOptions = validateCommandOptions(command, args);
-        if (validOptions._tag === 'Err')
-            return report(effectiveRuntime, validOptions.error, globals.json);
+        if (validOptions._tag === 'Err') {
+            const notice = await updateCheck;
+            writeUpdateNotice(effectiveRuntime, notice);
+            return report(effectiveRuntime, validOptions.error, globals.json, notice);
+        }
         if (globals.json)
             writeCliResponse(effectiveRuntime, describeCommand(command, args, VERSION));
         else
             writeOutput(effectiveRuntime, await requestedUsage(effectiveRuntime, globals, args));
+        const notice = await updateCheck;
+        writeUpdateNotice(effectiveRuntime, notice);
         return EXIT_CODE.success;
     }
     const result = args.length === 0
@@ -372,7 +401,9 @@ export async function runCli(rawArgs, runtime) {
             ? await interactiveBare(effectiveRuntime, globals)
             : await nonInteractiveBare(effectiveRuntime, globals)
         : await runExplicit(args, effectiveRuntime, globals);
+    const notice = await updateCheck;
+    writeUpdateNotice(effectiveRuntime, notice);
     return result._tag === 'Ok'
         ? EXIT_CODE.success
-        : report(effectiveRuntime, timeoutRetryFailure(result.error, rawArgs, globals.timeoutMs), globals.json);
+        : report(effectiveRuntime, timeoutRetryFailure(result.error, rawArgs, globals.timeoutMs), globals.json, notice);
 }

package/dist/commands.js

@@ -5,7 +5,7 @@ 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 } from './parse.js';
-import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderUsage, } from './render.js';
+import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderIndexingDiagnostics, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
@@ -447,6 +447,36 @@ async function searchAnalytics(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderSearchAnalytics(value.data));
 }
+async function searchIndexing(runtime, globals, args) {
+    const view = parseChoice(args.view, { name: 'view', choices: ['summary', 'urls'] });
+    if (view._tag === 'Err')
+        return view;
+    const status = args.status === undefined
+        ? ok(undefined)
+        : parseChoice(args.status, { name: '--status', choices: ['indexed', 'not_indexed', 'pending'] });
+    if (status._tag === 'Err')
+        return status;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 500, defaultValue: 50 });
+    if (limit._tag === 'Err')
+        return limit;
+    const offset = parseInteger(args.offset, { name: '--offset', minimum: 0, defaultValue: 0 });
+    if (offset._tag === 'Err')
+        return offset;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Search Console indexing', () => resolved.value.api.client.search.readIndexingDiagnostics({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            view: view.value,
+            issue: args.issue,
+            status: status.value,
+            limit: limit.value,
+            offset: offset.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderIndexingDiagnostics(value.data));
+}
 async function researchOverview(runtime, globals) {
     const resolved = await apiAndSite(runtime, globals);
     if (resolved._tag === 'Err')
@@ -928,6 +958,23 @@ export function createRootCommand(runtime, globals, execution) {
                     sortDir: args['sort-dir'],
                 }), args._, 1)(),
             }),
+            indexing: defineCommand({
+                meta: { name: 'indexing', description: 'Read retained Search Console indexing coverage' },
+                args: {
+                    view: positional('summary-or-urls', 'summary or urls'),
+                    issue: { type: 'string', description: 'Filter URLs by issue type' },
+                    status: { type: 'enum', options: ['indexed', 'not_indexed', 'pending'], description: 'Filter URLs by indexing status' },
+                    limit: { type: 'string', description: 'Maximum URLs, 1 to 500' },
+                    offset: { type: 'string', description: 'Pagination offset' },
+                },
+                run: ({ args }) => capture(execution, () => searchIndexing(runtime, globals, {
+                    view: args.view,
+                    issue: args.issue,
+                    status: args.status,
+                    limit: args.limit,
+                    offset: args.offset,
+                }), args._, 1)(),
+            }),
         },
     });
     return defineCommand({

package/dist/failures.js

@@ -1,3 +1,11 @@
+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,
@@ -97,12 +105,15 @@ 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,
                     ].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]
+            return fail(EXIT_CODE.infrastructure, [`contract_violation: ${error.message}`, error.requestId ? `Request ID: ${error.requestId}` : undefined, CONTRACT_REMEDIATION, `Current CLI version: ${VERSION}`]
                 .filter((line) => line !== undefined)
                 .join('\n'), undefined, 'contract_violation');
         case 'TransportFailure': {

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export { runCli } from './cli.js';
 export { EXIT_CODE } from './failures.js';
 export type { CliFailure, CliFailureCode, CliResult, ExitCode, LocalFailureCode } from './failures.js';
 export type { CliRuntime } from './runtime.js';
+export { checkForUpdate, isNewerVersion, updateNoticeFor } from './update-check.js';
+export type { UpdateNotice } from './update-check.js';
 export { VERSION } from './version.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { runCli } from './cli.js';
 export { EXIT_CODE } from './failures.js';
+export { checkForUpdate, isNewerVersion, updateNoticeFor } from './update-check.js';
 export { VERSION } from './version.js';

package/dist/render.d.ts

@@ -3,7 +3,7 @@ import type { ActionList, ActionResolve, ActionShow } from '@nuxtseo/protocol/v1
 import type { AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities } from '@nuxtseo/protocol/v1/audit';
 import type { Mentions, RecoverableBacklinks } from '@nuxtseo/protocol/v1/backlinks';
 import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
-import type { SearchAnalyticsData, SearchStatusData } from '@nuxtseo/protocol/v1/gsc';
+import type { IndexingDiagnosticsData, SearchAnalyticsData, SearchStatusData } from '@nuxtseo/protocol/v1/gsc';
 import type { PageInspect, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
 import type { KeywordResearchData, RankingsResearchData, SerpResearchData, StoredResearchOverview } from '@nuxtseo/protocol/v1/research';
@@ -17,6 +17,7 @@ export declare function renderPageScan(data: PageScan): string;
 export declare function renderPerformance(data: SitePerformanceOverview): string;
 export declare function renderSearchStatus(data: SearchStatusData): string;
 export declare function renderSearchAnalytics(data: SearchAnalyticsData): string;
+export declare function renderIndexingDiagnostics(data: IndexingDiagnosticsData): string;
 export declare function renderResearchOverview(data: StoredResearchOverview): string;
 export declare function renderKeywordResearch(data: KeywordResearchData): string;
 export declare function renderSerpResearch(data: SerpResearchData): string;

package/dist/render.js

@@ -34,6 +34,13 @@ export function renderUsage(response) {
         });
     return [`Plan: ${response.data.plan}`, ...meters].join('\n');
 }
+function evidenceAgeLine(freshness) {
+    if (freshness.verdict === 'aged')
+        return `  evidence observed ${freshness.ageHours}h ago (${freshness.confidence})`;
+    if (freshness.verdict === 'unknown')
+        return '  evidence age unknown';
+    return '';
+}
 export function renderActions(data) {
     if (data.actions.length === 0)
         return 'No next actions.';
@@ -42,7 +49,8 @@ export function renderActions(data) {
         ...data.actions.map(action => [
             `${action.id}  ${action.diagnosis}`,
             `  ${action.status}, effort ${action.effort}, ${action.affectedPages ?? 'unknown'} affected pages`,
-        ].join('\n')),
+            evidenceAgeLine(action.evidence.freshness),
+        ].filter(Boolean).join('\n')),
         data.page.hasMore ? `More actions available after offset ${data.page.offset + data.page.limit}.` : '',
     ].filter(Boolean).join('\n');
 }
@@ -76,9 +84,12 @@ export function renderPageInspection(data) {
             ['SEO', data.performance.lighthouse.seo],
         ])
         : 'No Lighthouse scan.';
+    const empty = data.observations.coverage === 'issues-open'
+        ? ''
+        : ` (${data.observations.coverage})`;
     return [
         data.page.url,
-        `Observations: ${data.observations.total}`,
+        `Observations: ${data.observations.total}${empty}`,
         ...observations,
         lighthouse,
         `Tracked keywords: ${data.search.keywords.length}`,
@@ -140,6 +151,34 @@ export function renderSearchAnalytics(data) {
         ['Rows', 'rows' in data ? data.rows.length : data.type === 'timeseries' ? data.daily.length : 0],
     ]);
 }
+export function renderIndexingDiagnostics(data) {
+    if (data.view === 'summary') {
+        const indexedPercent = data.totalUrls > 0
+            ? `${(data.indexed / data.totalUrls * 100).toFixed(1)}%`
+            : '0.0%';
+        const issues = data.issues
+            .filter(issue => issue.count > 0)
+            .sort((left, right) => right.count - left.count)
+            .map(issue => `${issue.count}  ${issue.label}  ${issue.severity}`);
+        return [
+            fields([
+                ['Known URLs', data.totalUrls],
+                ['Indexed', data.indexed],
+                ['Not indexed', Math.max(0, data.totalUrls - data.indexed)],
+                ['Indexed rate', indexedPercent],
+                ['As of', data.asOf],
+            ]),
+            ...(issues.length > 0 ? ['Issues', ...issues] : []),
+        ].join('\n');
+    }
+    if (data.urls.length === 0)
+        return 'No Search Console indexing URLs match these filters.';
+    return [
+        `Search Console indexing URLs (${data.urls.length} of ${data.total})`,
+        ...data.urls.map(row => `${row.verdict ?? 'unknown'}  ${row.coverageState ?? 'unknown'}\n  ${row.url}`),
+        data.hasMore ? `More URLs available after offset ${data.offset + data.limit}.` : '',
+    ].filter(Boolean).join('\n');
+}
 export function renderResearchOverview(data) {
     const subject = data.subject
         ? fields([

package/dist/state/paths.d.ts

@@ -1,10 +1,12 @@
 export declare const STATE_DIRECTORY_NAME = ".nuxtseo";
 export declare const AUTH_FILENAME = "auth.json";
 export declare const CONFIG_FILENAME = "config.json";
+export declare const UPDATE_CHECK_FILENAME = "update-check.json";
 export interface StatePaths {
     directory: string;
     authFile: string;
     configFile: string;
+    updateCheckFile: string;
 }
 export declare function createStatePaths(homeDirectory: string): StatePaths;
 export declare function defaultStatePaths(): StatePaths;

package/dist/state/paths.js

@@ -3,12 +3,14 @@ import { join } from 'pathe';
 export const STATE_DIRECTORY_NAME = '.nuxtseo';
 export const AUTH_FILENAME = 'auth.json';
 export const CONFIG_FILENAME = 'config.json';
+export const UPDATE_CHECK_FILENAME = 'update-check.json';
 export function createStatePaths(homeDirectory) {
     const directory = join(homeDirectory, STATE_DIRECTORY_NAME);
     return {
         directory,
         authFile: join(directory, AUTH_FILENAME),
         configFile: join(directory, CONFIG_FILENAME),
+        updateCheckFile: join(directory, UPDATE_CHECK_FILENAME),
     };
 }
 export function defaultStatePaths() {

package/dist/update-check.d.ts

@@ -0,0 +1,25 @@
+import type { StatePaths } from './state/index.js';
+/** How long a registry answer stays authoritative, matching npm's update cache. */
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export interface UpdateNotice {
+    current: string;
+    latest: string;
+}
+export interface UpdateCheckCache {
+    lastCheckedAt: string;
+    latest: string | null;
+}
+export type RegistryLatestFetch = (url: string, signal: AbortSignal) => Promise<string | null>;
+export interface UpdateCheckOptions {
+    paths: StatePaths;
+    env?: Readonly<Record<string, string | undefined>>;
+    fetch?: RegistryLatestFetch;
+    now?: () => Date;
+}
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+export declare function updateNoticeFor(latest: string | null, current: string): UpdateNotice | null;
+export declare function updateCheckDue(cache: UpdateCheckCache | null, now: Date): boolean;
+export declare function parseUpdateCheckCache(content: string): UpdateCheckCache | null;
+export declare function fetchRegistryLatest(url: string, signal: AbortSignal): Promise<string | null>;
+export declare function checkForUpdate(options: UpdateCheckOptions): Promise<UpdateNotice | null>;
+export declare function updateNoticeLine(notice: UpdateNotice): string;

package/dist/update-check.js

@@ -0,0 +1,107 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { VERSION } from './version.js';
+/** How long a registry answer stays authoritative, matching npm's update cache. */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@nuxtseo/cli/latest';
+const FETCH_TIMEOUT_MS = 2_000;
+function updateCheckDisabled(env) {
+    return env?.NUXTSEO_NO_UPDATE_CHECK === '1' || env?.NUXTSEO_NO_UPDATE_CHECK === 'true';
+}
+export function isNewerVersion(candidate, current) {
+    const core = (value) => {
+        const parts = value.trim().replace(/^v/, '').split('-')[0].split('.');
+        if (parts.length < 3)
+            return null;
+        const numbers = parts.slice(0, 3).map(part => Number.parseInt(part, 10));
+        return numbers.some(part => Number.isNaN(part)) ? null : numbers;
+    };
+    const candidateCore = core(candidate);
+    const currentCore = core(current);
+    if (!candidateCore || !currentCore)
+        return false;
+    for (let index = 0; index < 3; index++) {
+        if (candidateCore[index] !== currentCore[index])
+            return candidateCore[index] > currentCore[index];
+    }
+    // Same core: a prerelease candidate is not an update over the stable current.
+    return false;
+}
+export function updateNoticeFor(latest, current) {
+    return latest !== null && isNewerVersion(latest, current) ? { current, latest } : null;
+}
+export function updateCheckDue(cache, now) {
+    if (!cache)
+        return true;
+    const checkedAt = Date.parse(cache.lastCheckedAt);
+    return Number.isNaN(checkedAt) || now.getTime() - checkedAt >= UPDATE_CHECK_INTERVAL_MS;
+}
+export function parseUpdateCheckCache(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt cache file is disposable state, not an error: refetch instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    if (typeof record.lastCheckedAt !== 'string')
+        return null;
+    if (record.latest !== null && typeof record.latest !== 'string')
+        return null;
+    return { lastCheckedAt: record.lastCheckedAt, latest: record.latest };
+}
+async function readUpdateCheckCache(paths) {
+    const content = await readFile(paths.updateCheckFile, 'utf8').catch(() => {
+        // A missing or unreadable cache file is the common first-run case.
+        return null;
+    });
+    return typeof content === 'string' ? parseUpdateCheckCache(content) : null;
+}
+async function writeUpdateCheckCache(paths, cache) {
+    // Persisting the cache is best effort. A failed write only costs one extra
+    // registry fetch on the next run, so the failure is ignorable by design.
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+    await writeFile(paths.updateCheckFile, `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+}
+export async function fetchRegistryLatest(url, signal) {
+    const response = await fetch(url, { signal, headers: { accept: 'application/json' } });
+    if (!response.ok)
+        return null;
+    const body = await response.json();
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const version = body.version;
+    return typeof version === 'string' && version ? version : null;
+}
+export async function checkForUpdate(options) {
+    if (updateCheckDisabled(options.env))
+        return null;
+    const now = options.now?.() ?? new Date();
+    const cache = await readUpdateCheckCache(options.paths);
+    if (!updateCheckDue(cache, now))
+        return updateNoticeFor(cache.latest, VERSION);
+    const fetchLatest = options.fetch ?? fetchRegistryLatest;
+    const latest = await fetchLatest(REGISTRY_LATEST_URL, AbortSignal.timeout(FETCH_TIMEOUT_MS)).catch(() => {
+        // Registry reachability is best effort. The run continues without a hint.
+        return null;
+    });
+    if (latest !== null)
+        await writeUpdateCheckCache(options.paths, { lastCheckedAt: now.toISOString(), latest });
+    // A stale cached answer still beats no answer while the registry is unreachable.
+    return updateNoticeFor(latest ?? cache?.latest ?? null, VERSION);
+}
+export function updateNoticeLine(notice) {
+    return `${notice.latest} available, current ${notice.current}. Update with: pnpm add -g @nuxtseo/cli`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -30,13 +30,11 @@
   "engines": {
     "node": ">=22"
   },
-  "peerDependencies": {
-    "@nuxtseo/sdk": "^0.1.1"
-  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "citty": "^0.2.2",
-    "pathe": "^2.0.3"
+    "pathe": "^2.0.3",
+    "@nuxtseo/sdk": "^0.1.3"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.3.0"
@@ -46,8 +44,7 @@
     "@types/node": "^26.2.0",
     "publint": "^0.3.24",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
-    "@nuxtseo/sdk": "0.1.1",
-    "@nuxtseo/protocol": "0.1.1"
+    "@nuxtseo/protocol": "0.1.3"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -26,6 +26,7 @@ report `cached`.
 
 `search status` reads stored connection state. It never waits for Google.
 `search analytics` reads Search Console rows through the public API.
+`search indexing` reads retained URL Inspection coverage through the public API.
 
 ## Get the binary
 
@@ -105,16 +106,17 @@ handling failures, read [CLI protocol](references/protocol.md).
 | `sites list` | Every accessible Site | Source of Site IDs |
 | `sites use <site-id>` | – | Persists a default Site for the human, not for you |
 | `usage` | Plan and meters | `--group integrations\|compute\|capacity` |
-| `actions list` | Server-ranked issues and opportunities | `--limit 1..25` (default 10), `--offset` |
+| `actions list` | Server-ranked issues and opportunities | `--limit 1..25` (default 10), `--offset`. JSON carries `evidence.freshness`; `verdict: "aged"` means the observation is over a day old, so live-check before fixing |
 | `actions show <action-id>` | One issue or opportunity plus evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
 | `actions resolve <action-id>` | – | Mutation. Claims the issue or opportunity and starts server verification |
 | `backlinks recoverable` | Stored recoverable backlinks | `--limit 1..200`, `--offset` |
 | `mentions list` | Stored mentions | `--limit 1..200` |
-| `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved` |
+| `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved`. JSON carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
 | `page scan <url>` | – | Mutation. Starts mobile and desktop scans |
 | `performance` | Site performance overview | Medians for perf, a11y, SEO, LCP, TBT, CLS |
 | `search status` | Stored Search Console connection | Provider free |
 | `search analytics <pages\|keywords>` | Search Console Page or query rows | `--period`, `--limit`, `--page`, `--search` |
+| `search indexing <summary\|urls>` | Retained URL Inspection coverage | `summary` returns indexed counts; `urls` supports `--issue`, `--status`, `--limit`, `--offset` |
 | `research overview` | Stored Site and competitor research | Metrics, history, gaps, and quick wins |
 | `research keywords <topic>` | Live keyword ideas | Volume, difficulty, intent, and cost data |
 | `research serp <keyword>` | Live SERP snapshot | Results, features, and fetch time |
@@ -141,7 +143,10 @@ flag, and prefer the table above for anything it already answers.
 This is the sequence that turns CLI output into a code change:
 
 1. `nuxtseo actions list --site <id> --json` gives ranked work with an ID, a
-   diagnosis, an effort, and an affected page count.
+   diagnosis, an effort, and an affected page count. Check
+   `evidence.freshness` per row: `verdict: "aged"` with a large `ageHours`
+   means the evidence is old. Live-check a cheap sample before fixing, because
+   the site may have moved on since the observation.
 2. `nuxtseo actions show <action-id> --site <id> --json` gives the evidence:
    which pages, which finding type, and when it was observed.
 3. Fix the cause in the repository. The evidence names URLs; map them back to
@@ -164,4 +169,6 @@ command exits `5` with `stale_evidence`; re-run step 2 and decide again.
 - Do not loop over Pages, keywords, or domains unattended. Check `usage` first.
 - Live research can consume allowance. A cached result does not consume a unit.
 - Report failures as they are. The CLI has no MCP or private-route fallback.
-- Do not treat an empty result as clean. The Site may have incomplete evidence.
+- Do not treat an empty result as clean. `page inspect` JSON says which empty
+  it is through `observations.coverage`; other commands may still have
+  incomplete evidence.

package/skills/nuxtseo-cli/references/protocol.md

@@ -32,6 +32,22 @@ Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
 
 Discriminate on `_tag`. Protocol envelopes never carry one.
 
+A `CliError` for exit `2` or exit `7` also carries `cliVersion`, and
+`latestKnownVersion` when the CLI knows the registry holds a newer version.
+Those two exits are where a stale binary looks like broken docs or a broken
+server; check the versions before debugging anything else.
+
+## Update hints
+
+Every run checks the npm registry for a newer CLI, cached for 24 hours. When a
+newer version is known, one line goes to stderr, for example:
+
+```
+0.2.0 available, current 0.1.1. Update with: pnpm add -g @nuxtseo/cli
+```
+
+Set `NUXTSEO_NO_UPDATE_CHECK=1` to disable the check, for example in CI.
+
 ## Paging
 
 One invocation makes one request. The CLI never auto-pages or merges responses.
@@ -51,7 +67,7 @@ Branch on the exit code, not message text.
 | `4` | Forbidden, scope, or entitlement failure | Report the plan or token blocker |
 | `5` | Conflict, stale evidence, or ambiguous Site | Re-read. Pass `--site` if ambiguous |
 | `6` | Rate limit, quota, provider outage, or timeout | Read retry metadata, then wait |
-| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID |
+| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID. If the message names `contract_violation`, update the CLI first |
 | `8` | Resource or Site not found | Run `sites list` for a valid Site ID |
 | `127` | Shell cannot find `nuxtseo` | Install the CLI |
 | `130` | Interrupted or cancelled | Check whether a mutation ran before retrying |