@nuxtseo/cli 0.1.1 → 0.1.2

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,
@@ -336,9 +348,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 +369,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 +398,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/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.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}`,

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.2",
   "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.2"
   },
   "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.2"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -105,12 +105,12 @@ 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 |
@@ -141,7 +141,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 +167,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 |