@nuxtseo/cli 0.5.1 → 0.5.4

package/README.md

@@ -256,7 +256,9 @@ reads retained rows and spends nothing.
 `search status` reads stored connection state. It never waits for Google.
 `search indexing summary` reads retained URL Inspection coverage. `asOf` and `oldestCheckAt` bound the age of its verdicts.
 `search index-history` dates an indexing change against known releases.
-`search inspect <url>` reads Google's own verdict for one URL.
+`search inspect <url>` reads the latest retained Google URL Inspection for one URL.
+`search inspect <url> --fresh --yes` requests Google URL Inspection through the Site connection and uses inspection quota.
+Fresh inspection reports errors and skipped URLs with a nonzero exit code. If the request needs more time, add `--timeout-ms 60000`.
 `page inspect <url>` reads the Nuxt SEO observation store for the same URL.
 `research keywords`, `research serp`, and `research rankings` can use the Team
 research limit. Keyword responses report cache use in `evidence`. SERP and

package/dist/commands.js

@@ -9,7 +9,7 @@ import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
 import { parseAbsolutePageUrl, parseChoice, parseInteger, parsePageUrlOrPath, parseRatio } from './parse.js';
 import { PULL_PERIODS, runPull } from './pull.js';
-import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUsage, } from './render.js';
+import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUrlInspectionRefresh, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { installSkill, SKILL_AGENTS } from './skill.js';
@@ -717,13 +717,36 @@ async function searchIndexHistory(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderIndexingHistory(value.data));
 }
-async function searchInspect(runtime, globals, rawUrl) {
+async function searchInspect(runtime, globals, rawUrl, fresh = false) {
     const url = parsePageUrlOrPath(rawUrl);
     if (url._tag === 'Err')
         return url;
+    if (fresh) {
+        const confirmed = await confirmMutation(runtime, globals, `Request a fresh URL Inspection for ${url.value}? This uses inspection quota.`);
+        if (confirmed._tag === 'Err')
+            return confirmed;
+        if (!confirmed.value)
+            return ok(undefined);
+    }
     const resolved = await apiAndSite(runtime, globals);
     if (resolved._tag === 'Err')
         return resolved;
+    if (fresh) {
+        const response = await withSpinner(runtime, 'Requesting URL Inspection', () => resolved.value.api.client.search.refreshUrlInspection({
+            params: { siteId: resolved.value.siteId },
+            body: { url: url.value },
+        }, { signal: runtime.requestSignal }));
+        if (response._tag === 'Err')
+            return fromSdkFailure(response.error);
+        if (response.value.data.errors.length || response.value.data.skipped.length || response.value.data.results.length !== 1) {
+            const incomplete = fail(EXIT_CODE.conflict, 'Fresh URL Inspection did not complete. Read the errors or skipped URLs in the response.');
+            if (globals.json)
+                return { _tag: 'Err', error: { ...incomplete.error, protocolResponse: response.value } };
+            writeOutput(runtime, renderUrlInspectionRefresh(response.value.data));
+            return incomplete;
+        }
+        return present(runtime, globals, response, value => renderUrlInspectionRefresh(value.data));
+    }
     const response = await withSpinner(runtime, 'Loading URL Inspection', () => resolved.value.api.client.search.readUrlInspection({
         params: { siteId: resolved.value.siteId },
         query: { url: url.value },
@@ -2016,8 +2039,11 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             'inspect': defineCommand({
                 meta: { name: 'inspect', description: 'Read the latest URL Inspection result for one URL' },
-                args: { url: positional('url', 'Page URL or path') },
-                run: ({ args }) => capture(execution, () => searchInspect(runtime, globals, args.url), args._, 1)(),
+                args: {
+                    url: positional('url', 'Page URL or path'),
+                    fresh: { type: 'boolean', description: 'Request Google URL Inspection using inspection quota', default: false },
+                },
+                run: ({ args }) => capture(execution, () => searchInspect(runtime, globals, args.url, args.fresh), args._, 1)(),
             }),
         },
     });

package/dist/pull.js

@@ -304,6 +304,7 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
     const skipped = [];
     let stopped = false;
     let completed = 0;
+    let explainedAnalyticsConnection = false;
     await forEachBounded(operations, concurrency.value, async (candidate) => {
         if (stopped) {
             skipped.push(candidate.name);
@@ -318,13 +319,25 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
         });
         const outcome = pullLine(candidate.name, result);
         writeProtocolResponse(runtime, outcome.line);
-        exitCodes.push(outcome.exitCode);
+        const analyticsUnconnected = candidate.name.startsWith('analytics ')
+            && result._tag === 'Err'
+            && result.error._tag === 'ApiFailure'
+            && result.error.code === 'conflict'
+            && result.error.details?.action === 'connect_web_analytics';
+        if (!explainedAnalyticsConnection && analyticsUnconnected) {
+            explainedAnalyticsConnection = true;
+            writeDiagnostic(runtime, 'Web Analytics is not connected. Connect a property to read these views. For a full SEO pull, use --exclude analytics.');
+        }
+        // Default pulls include optional integrations. An explicit include asks
+        // for those reads, so their missing connection still fails that request.
+        const optionalUnavailable = analyticsUnconnected && !args.include;
+        exitCodes.push(optionalUnavailable ? EXIT_CODE.success : 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'}`);
+        writeDiagnostic(runtime, `[${completed}/${operations.length}] ${candidate.name} ${optionalUnavailable ? 'unavailable' : outcome.failure ? `failed: ${outcome.failure.code}` : 'ok'}`);
         if (outcome.failure?.code === 'request_timeout' && timeoutMs < 300_000) {
             const retryTimeout = Math.min(timeoutMs * 2, 300_000);
             // Retry only this read. Repeating a full paid pull can spend twice.

package/dist/render.d.ts

@@ -4,7 +4,7 @@ import type { ActionDismiss, ActionList, ActionResolve, ActionShow } from '@nuxt
 import type { AnalyticsQueryData, AnalyticsView } from '@nuxtseo/protocol/v1/analytics';
 import type { AuditChanges, AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities, AuditLinkStructure } from '@nuxtseo/protocol/v1/audit';
 import type { BacklinkAnchorsData, BacklinksHistory, BacklinksSummaryData, MentionsData, RecoverableBacklinksData, ReferringDomainsData } from '@nuxtseo/protocol/v1/backlinks';
-import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData } from '@nuxtseo/protocol/v1/gsc';
+import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData, UrlInspectionRefreshData } from '@nuxtseo/protocol/v1/gsc';
 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';
@@ -21,6 +21,7 @@ export declare function renderPerformance(data: SitePerformanceOverview): string
 export declare function renderSearchStatus(data: SearchStatusData): string;
 export declare function renderSearchAnalytics(data: SearchAnalyticsData): string;
 export declare function renderIndexingHistory(data: IndexingHistoryData): string;
+export declare function renderUrlInspectionRefresh(data: UrlInspectionRefreshData): string;
 export declare function renderUrlInspection(data: UrlInspectionData): string;
 export declare function renderAuditChanges(data: AuditChanges): string;
 export declare function renderLinkStructure(data: AuditLinkStructure): string;

package/dist/render.js

@@ -232,6 +232,25 @@ export function renderIndexingHistory(data) {
         }),
     ].join('\n');
 }
+export function renderUrlInspectionRefresh(data) {
+    return [
+        `URL Inspection request completed at ${data.checkedAt}.`,
+        ...data.results.map(result => fields([
+            ['URL', result.url],
+            ['Verdict', result.verdict],
+            ['Coverage', result.coverageState],
+            ['Indexing', result.indexingState],
+            ['robots.txt', result.robotsTxtState],
+            ['Page fetch', result.pageFetchState],
+            ['User canonical', result.userCanonical],
+            ['Google canonical', result.googleCanonical],
+            ['Last crawl', result.lastCrawlTime],
+        ])),
+        ...data.errors.map(result => `Inspection failed for ${result.url}: ${result.error}`),
+        ...data.skipped.map(result => `Inspection skipped for ${result.url}: ${result.reason}`),
+        `Inspection quota remaining: ${data.rateLimit.remaining} of ${data.rateLimit.limit}.`,
+    ].join('\n');
+}
 export function renderUrlInspection(data) {
     if (data._tag === 'no-inspection-data')
         return `No retained URL Inspection for ${data.requestedUrl}.`;
@@ -604,7 +623,7 @@ export function renderFieldVitals(data) {
             ['As of', summary.asOf],
             ...['lcp', 'inp', 'cls'].map(metric => [
                 metric.toUpperCase(),
-                `${vitalValue(metric, summary[metric].p75)}  ${summary[metric].status ?? 'unrated'}  delta ${summary[metric].deltaOverPeriod ?? 'none'}`,
+                `${vitalValue(metric, summary[metric].p75)}  ${summary[metric].status ?? 'unrated'}  delta ${summary[metric].deltaOverPeriod ?? 'none'}  As of ${summary[metric].asOf ?? 'unknown'}`,
             ]),
         ]),
     ].join('\n');
@@ -893,10 +912,26 @@ export function renderScanDetail(data) {
     ];
     if (data.lcpElement)
         blocks.push(`LCP element  ${data.lcpElement.selector ?? data.lcpElement.nodeLabel ?? 'unknown'}`);
-    if (data.performanceIssues.length) {
+    if (data.observedTrace?._tag === 'available') {
+        const trace = data.observedTrace;
+        blocks.push([
+            `Observed trace LCP  ${trace.observedLcpMs}ms  throttling ${trace.throttlingMethod ?? 'not reported'}`,
+            ...trace.phases.map(phase => `  ${phase.id}  ${phase.durationMs}ms`),
+            'Trace phases describe observed LCP. Reported LCP can be simulated.',
+        ].join('\n'));
+    }
+    else {
+        blocks.push(`Observed trace unavailable  ${data.observedTrace?.reason ?? 'legacy-response'}`);
+    }
+    if (data.javascript) {
+        const bytes = (amount) => amount === null ? 'unknown' : `${amount}b`;
+        blocks.push(`JavaScript  ${bytes(data.javascript.transferBytes)} transferred  ${bytes(data.javascript.decodedBytes)} decoded  ${data.javascript.scriptCount ?? 'unknown'} resources`);
+    }
+    const waste = data.performanceIssues.filter(issue => issue.subtype !== 'js-transfer-weight');
+    if (waste.length) {
         blocks.push([
-            `Wasteful assets (${data.performanceIssues.length})`,
-            ...data.performanceIssues.map(issue => `  ${issue.wastedMs ?? 0}ms  ${issue.wastedBytes ?? 0}b  ${issue.subtype ?? issue.type}  ${issue.url ?? ''}`.trimEnd()),
+            `Wasteful assets (${waste.length})`,
+            ...waste.map(issue => `  ${issue.wastedMs ?? 0}ms  ${issue.wastedBytes ?? 0}b  ${issue.subtype ?? issue.type}  ${issue.url ?? ''}`.trimEnd()),
         ].join('\n'));
     }
     if (data.thirdParties.length) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.5.4",
   "description": "Command line interface for the Nuxt SEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
-    "@nuxtseo/protocol": "^0.5.1",
-    "@nuxtseo/sdk": "^0.5.1",
+    "@nuxtseo/protocol": "^0.5.4",
+    "@nuxtseo/sdk": "^0.5.4",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -277,7 +277,10 @@ Do not compare this population with a summary or cohort from another capture.
 - `status` is the verdict, `performance` the lab score, `vitals` what real
   users measured. Never substitute one for another.
 - `page inspect` reads the Nuxt SEO observation store. `search inspect` reads
-  Google's index verdict for the same URL.
+  the latest retained Google URL Inspection for the same URL.
+  `search inspect <url> --fresh --yes` requests Google URL Inspection through
+  the Site connection and uses inspection quota. Errors or skipped URLs mean
+  the fresh inspection did not complete. Never present them as fresh verdicts.
 - `search status` reads the stored connection and never waits for Google.
   `search analytics`, `search indexing`, `search index-history`, and
   `search inspect` read retained Search Console evidence.

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

@@ -138,9 +138,36 @@ lines.
 | `scans show <scan-id>` | One Scan, and the evidence behind its scores: wasteful assets, repeat-visit cache policy, third-party scripts, the LCP element, and every failing accessibility and best-practices check with its CSS selectors and DOM snippets. Read `coverage` before quoting a total |
 | `scans pages` | The Pages this Site scans on a schedule. Add one with `page scan <url>` |
 
+`scans show` can include `observedTrace` from the retained Lighthouse projection.
+If its tag is `available`, its phases describe `observedLcpMs` from the browser trace.
+`throttlingMethod` names how Lighthouse computed the reported metrics.
+If it is `null`, the provider omitted the method. Do not infer a method from the timings.
+With `simulate`, reported `lcp` is modeled. Observed trace phases do not partition that modeled value.
+With `devtools` or `provided`, Lighthouse uses observed metrics.
+Neither value is real-user field data.
+An `unavailable` tag names missing, invalid, or legacy evidence.
+Older servers can omit the field. Omission also means unavailable.
+This command never reads raw reports or starts a projection backfill.
+
 `page inspect` and `page scan` take an absolute URL, for example
 `https://example.com/about`.
 
+### JavaScript byte measurements
+
+`scans show` returns `data.javascript` with stored `transferBytes`, `decodedBytes`, and `scriptCount`.
+Each measurement is nullable. `javascript: null` means no stored JavaScript measurement.
+An older server may omit the field.
+
+The extractor counts JavaScript by resource type, MIME type, or `.js` / `.mjs` URL.
+It includes downloaded JavaScript labelled `Other`, which can include prefetch requests.
+The stored totals do not separate prefetch from executed JavaScript.
+They do not measure parse, compile, or execution work.
+
+For a `js-transfer-weight` diagnostic, `wastedBytes` holds total decoded JavaScript bytes.
+It is not removable code or Lighthouse unused-byte savings.
+Use `data.javascript` for byte comparisons, and `unused` findings for unused-byte evidence.
+Do not infer a reduction in executed JavaScript from download totals alone.
+
 `page scan` enables recurring monitoring.
 Read `scans pages` before scanning many new URLs. The server refuses a new
 Page when five monitored Pages are already enabled. That limit comes from
@@ -168,7 +195,7 @@ The monitored Page then follows its own recurring schedule.
 | `search analytics <view>` | Search Console rows, trend, detail, or analysis. Views: `pages`, `keywords`, `countries`, `devices`, `timeseries`, `page-detail`, `keyword-detail`, `analysis`. `--period 7d\|28d\|3m\|6m\|12m` (default `28d`). No other period value is accepted; `90d` exits `2`, and `3m` is the three-month window. `--limit 1..100` (default 25), `--page` (default 1), `--search`, `--sort clicks\|impressions\|ctr\|position` (default `clicks`), `--sort-dir asc\|desc` (default `desc`), `--filter top-level\|new\|lost\|improving\|declining`, `--min-clicks`, `--max-clicks`, `--min-impressions`, `--max-impressions`, `--min-position 1..100`, `--max-position 1..100`, `--max-ctr 0..1`. The `page-detail` view needs `--page-url`, `keyword-detail` needs `--keyword`, and `analysis` needs `--preset`. The brand presets also need `--brand-terms` |
 | `search indexing <summary\|urls>` | Retained URL Inspection coverage. `summary` returns indexed counts. `urls` supports `--issue`, `--status`, `--limit 1..500` (default 50), `--offset` |
 | `search index-history` | Retained indexing changes and candidate causes. `--url`, `--field`, `--days 1..730`. Dates a regression against a release |
-| `search inspect <url>` | Google's own verdict for one URL. Takes an absolute URL or a site-relative path |
+| `search inspect <url>` | Latest retained Google URL Inspection for one URL. Takes an absolute URL or a site-relative path. `--fresh --yes` requests Google URL Inspection through the Site connection and uses inspection quota. Errors or skipped URLs produce a nonzero exit code |
 | `search cohorts` | Not-indexed rate per route family. Returns `analysed: false` when the not-indexed list is a sample (`reason: sampled-index-state`). `--limit 1..50` (default 12), `--min-pages 1..500` (default 5). Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
 | `sitemaps list` | Search Console sitemap snapshot: errors, warnings, URL counts, sync status |
 | `sitemaps urls` | Sitemap URL membership. `--generation-id`, `--feedpath`, `--cursor`, `--limit 1..1000` |

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

@@ -63,5 +63,6 @@ Keep these reads separate:
 | What is the indexed count for retained URLs? | `search indexing summary` | `totalUrls`, `indexed`, `oldestCheckAt`, `asOf` |
 | Which retained URLs are indexed or not indexed? | `search indexing urls` | `total`, then the complete `urls` stream |
 | Which URLs appeared in the current period? | `search analytics pages` | Rows with `impressions > 0`, then each `url` |
-| What does Google say about one URL now? | `search inspect <url>` | The returned URL Inspection verdict |
+| What did Google say at the last inspection? | `search inspect <url>` | The retained verdict and inspection date |
+| What does Google say about one URL now? | `search inspect <url>` | Add `--fresh --yes`. Report fresh results, quota, and explicit errors or skipped URLs |
 | Which URLs did the Site submit? | `sitemaps list`, then `sitemaps urls` | Sitemap totals and membership |