@nuxtseo/cli 0.5.0 → 0.5.3

package/dist/commands.js

@@ -1223,7 +1223,11 @@ async function actionDismiss(runtime, globals, args) {
         return fail(EXIT_CODE.invalidInput, 'Pass the action id to dismiss.', undefined, 'invalid_cli_input');
     if (!args.artifactVersion)
         return fail(EXIT_CODE.invalidInput, 'Pass --artifact-version, the artifactVersion returned with this action.', undefined, 'invalid_cli_input');
-    const confirmed = await confirmMutation(runtime, globals, `Dismiss action ${args.actionId}? The page stays removed.`);
+    if (args.note !== undefined && (!args.note.trim() || args.note.trim().length > 2000))
+        return fail(EXIT_CODE.invalidInput, 'Pass --note with 1 to 2000 characters.', undefined, 'invalid_cli_input');
+    const confirmed = await confirmMutation(runtime, globals, args.note
+        ? `Dismiss action ${args.actionId}? Your note records this decision. No fix is verified.`
+        : `Dismiss action ${args.actionId}? The page stays removed.`);
     if (confirmed._tag === 'Err')
         return confirmed;
     if (!confirmed.value) {
@@ -1235,7 +1239,7 @@ async function actionDismiss(runtime, globals, args) {
         return resolved;
     const response = await withSpinner(runtime, 'Dismissing action', () => resolved.value.api.client.actions.dismiss({
         params: { siteId: resolved.value.siteId, actionId: args.actionId },
-        body: { artifactVersion: args.artifactVersion },
+        body: { artifactVersion: args.artifactVersion, ...(args.note !== undefined ? { note: args.note.trim() } : {}) },
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderActionDismissal(value.data));
 }
@@ -1559,14 +1563,16 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => actionsResolve(runtime, globals, args.actionId), args._, 1)(),
             }),
             dismiss: defineCommand({
-                meta: { name: 'dismiss', description: 'Dismiss a broken-page action so the page stays removed' },
+                meta: { name: 'dismiss', description: 'Dismiss reviewed work with a note, or confirm an unlinked page removal' },
                 args: {
                     'actionId': positional('action-id', 'Action ID'),
                     'artifact-version': { type: 'string', description: 'The artifactVersion returned with this action' },
+                    'note': { type: 'string', description: 'Why this action is intentional or incorrect, 1 to 2000 characters' },
                 },
                 run: ({ args }) => capture(execution, () => actionDismiss(runtime, globals, {
                     actionId: args.actionId,
                     artifactVersion: args['artifact-version'],
+                    note: args.note,
                 }), 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,6 +319,15 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
         });
         const outcome = pullLine(candidate.name, result);
         writeProtocolResponse(runtime, outcome.line);
+        if (!explainedAnalyticsConnection
+            && candidate.name.startsWith('analytics ')
+            && result._tag === 'Err'
+            && result.error._tag === 'ApiFailure'
+            && result.error.code === 'conflict'
+            && result.error.details?.action === 'connect_web_analytics') {
+            explainedAnalyticsConnection = true;
+            writeDiagnostic(runtime, 'Web Analytics is not connected. Connect a property to read these views. For a full SEO pull, use --exclude analytics.');
+        }
         exitCodes.push(outcome.exitCode);
         completed++;
         // An expired or rejected credential fails every later read the same way.
@@ -325,6 +335,11 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
         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'}`);
+        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.
+            writeDiagnostic(runtime, `Retry: nuxtseo pull --site ${resolved.value.siteId} --include ${JSON.stringify(candidate.name)} --period ${period.value} --timeout-ms ${retryTimeout}${candidate.spendsResearch ? ' --with-research' : ''} --json`);
+        }
     });
     const failed = exitCodes.filter(code => code !== EXIT_CODE.success).length;
     writeDiagnostic(runtime, [

package/dist/render.js

@@ -445,7 +445,7 @@ export function renderIndexingDiagnostics(data) {
     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})`,
+        `Search Console indexing URLs (${data.urls.length} of ${data.totalSemantics === 'lower-bound' ? 'at least ' : ''}${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');
@@ -893,10 +893,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([
-            `Wasteful assets (${data.performanceIssues.length})`,
-            ...data.performanceIssues.map(issue => `  ${issue.wastedMs ?? 0}ms  ${issue.wastedBytes ?? 0}b  ${issue.subtype ?? issue.type}  ${issue.url ?? ''}`.trimEnd()),
+            `Observed trace LCP  ${trace.observedLcpMs}ms  throttling ${trace.throttlingMethod}`,
+            ...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 (${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.0",
+  "version": "0.5.3",
   "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.0",
-    "@nuxtseo/sdk": "^0.5.0",
+    "@nuxtseo/protocol": "^0.5.3",
+    "@nuxtseo/sdk": "^0.5.3",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -28,8 +28,18 @@ Read the matching file before you act on its subject:
    pnpm add -g @nuxtseo/cli                 # global install, Node 22+
    ```
 
-   Inside the Nuxt SEO monorepo, run `node packages/cli/dist/cli-entry.js`
-   instead.
+   Inside the Nuxt SEO monorepo, build the workspace dependencies in order
+   before using `node packages/cli/dist/cli-entry.js`:
+
+   ```sh
+   pnpm --filter @nuxtseo/protocol build
+   pnpm --filter @nuxtseo/sdk build
+   pnpm --filter @nuxtseo/cli build
+   node packages/cli/dist/cli-entry.js --version --json
+   ```
+
+   Use a task-owned worktree. Missing `dist` files and missing named exports
+   can mean stale builds. Rebuild all three packages before diagnosing source.
 
 2. **Skill version.** Run `nuxtseo --version --json`. Compare the CLI version
    with this file's frontmatter version. If the CLI is older, update the CLI
@@ -112,10 +122,20 @@ nuxtseo status --site <site-id> --json
   Route family: a lead to check, never the Site verdict. `assessment.aggregate`
   is always the whole-Site verdict. If `healthStage` is `quality_rejection`,
   the whole Site is affected, whatever a route family shows.
+  `quality_rejection` is a broad indexing stage. It includes discovery gaps.
+  Read the summary and Google coverage reasons before blaming content quality.
+  It does not prove that Google crawled and rejected the pages.
+  The stored assessment and retained indexing summary have separate clocks.
+  Compare `assessment.assessedAt` with indexing `asOf` before comparing their counts.
 - Read `dataQuality.status` before you quote the verdict. `degraded` means
   proofs were missing, so the verdict is Provisional. `unavailable` means it
   has not run.
 - If `nextAction.kind` is `action`, pass its `actionId` to step 3.
+- `openCount` counts open and in-progress Actions. `actions list` returns the
+  admitted, unclaimed worklist. These counts can differ. A stored Next Action
+  can still be readable through `actions show` when the worklist omits it.
+- A `candidate:` finding with diagnosis `Shadow observation` is a canary,
+  not a verified repair cause. Inspect its details before proposing work.
 
 For the whole Site instead of the next action, run one `pull`. It performs
 every spend-free Site read and writes one envelope per line:
@@ -124,6 +144,18 @@ every spend-free Site read and writes one envelope per line:
 nuxtseo pull --site <site-id> --json > site.ndjson
 ```
 
+Inspect every line's `command` and `error`. If one read times out, retry that
+read with the suggested timeout. Do not repeat successful or paid reads.
+If the longer request returns a provider failure, report the request ID.
+Retained `page issues` rows can name URLs, but do not replace Google's verdict.
+
+For full analytics exports, use `--all --limit 100`. Each run stops after
+50 requests. If it exits with `paging_cap_reached`, preserve the arguments
+and continue with the printed resume argument. Save each run separately.
+Check row keys for repeats across pages. Repeated keyword rows can indicate
+unstable upstream ordering. Report that gap instead of claiming complete
+keyword coverage. Use Site timeseries totals for the Site-wide comparison.
+
 **2. Pick a ranked action.**
 
 ```sh
@@ -133,6 +165,10 @@ nuxtseo actions list --site <site-id> --json
 Keep server order. Check `evidence.freshness` on each row. If `verdict` is
 `aged` with a large `ageHours`, live-check a cheap sample before you fix. The
 Site may have changed since the observation.
+If freshness `confidence` is `reasserted`, its age dates the repeated finding.
+It does not date the underlying page observation. Read evidence group source
+clocks in `actions show`. Live-check affected pages when those clocks are
+unknown or old, even when the finding was recently reasserted.
 
 **3. Read the evidence.**
 
@@ -142,7 +178,11 @@ nuxtseo actions show <action-id> --site <site-id> --json
 
 It names the pages, the finding type, and when it was observed. If
 `data.workPrompt` is not null, it is the Work Prompt: the task for this action,
-grounded in its evidence. Start the fix from it. Two reads go deeper:
+grounded in its evidence. Start the fix from it.
+The Work Prompt serves several clients and may name MCP alternatives.
+Use its CLI commands in this workflow. Never switch to MCP as a fallback.
+
+Two reads go deeper:
 
 - `page issues --action-id <action-id>`: the raw observations, with URLs,
   status codes, redirect targets, and Lighthouse selectors. This is the
@@ -175,8 +215,14 @@ from `actions show`, then:
 nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --yes --json
 ```
 
-The server admits a dismiss only for a broken-page action with complete 404 or
-410 evidence and no internal referrers.
+Without a note, the server admits a dismiss only for a broken-page action with
+complete 404 or 410 evidence and no internal referrers.
+
+If the owner confirms an action is intentional or incorrect, record that
+decision with `--note "<reason>"`. Review the exact scope first. A note dismisses
+the whole action, so never use it to hide a mix of intentional and broken URLs.
+Dismissal keeps the observations and does not verify a fix. The dashboard can
+restore the action later.
 
 **7. Mark the day.**
 
@@ -215,6 +261,13 @@ and do not route around it with `pull` or another read.
 `coverage.bestPracticesChecksTotal` from `scans show`. `possiblyTruncated:
 true` marks the list as a floor.
 
+For `search indexing urls`, read `totalSemantics` before quoting `total`.
+`lower-bound` means the provider used lookahead instead of counting every URL.
+The total can rise between pages without a filter change. Follow `hasMore` or
+use `--all`. A nonempty terminal page reports `exact` for that retained URL population.
+An empty page beyond offset zero reports `unknown`; its total can equal the requested offset.
+Do not compare this population with a summary or cohort from another capture.
+
 **Keep these datasets apart:**
 
 - `performance` and `scans *` read Lighthouse **lab** Scans. `vitals summary`
@@ -251,6 +304,19 @@ its two lists:
   with `statisticallyEstablished: false` is a lead to verify, for example by
   inspecting its URLs. Presenting it as a cause is a hard failure.
 
+**Compare equal windows.** Read `search analytics timeseries` for the Site's
+current and previous totals. `audit content-decay` ships its own `window`.
+It may span three months even when `pull --period 28d` selects 28-day analytics.
+Quote that window separately. Never present its losses as the 28-day decline.
+Content decay and duplicate reports return fixed shortlists. If `total` exceeds the returned
+row count, disclose both counts, even when `page.hasMore` is false. That flag
+does not promise the shortlist includes every Finding.
+
+**Check alternate formats.** A `.md` URL can serve the HTML page's content
+with a `Link: <html-url>; rel="canonical"` response header. Compare HTML
+siblings with HTML siblings. Do not remove a valid header canonical or add
+`noindex` just to clear a missing HTML canonical warning.
+
 ## Guardrails
 
 - **Get consent before a mutation.** `page scan`, `actions resolve`, `actions

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

@@ -124,7 +124,7 @@ lines.
 | `actions list` | Server-ranked issues and opportunities. `--limit 1..25` (default 10), `--offset`. Each row 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 its evidence. `--limit 1..100` (default 50), `--group-id`, `--cursor` |
 | `actions resolve <action-id>` | Mutation. Claims the issue or opportunity and starts server verification. Reads the action first and sends `artifactVersion` for you |
-| `actions dismiss <action-id>` | Mutation. Says the page stays removed. Needs `--artifact-version`, read from `actions show`. Admitted only for a broken-page action with complete 404 or 410 evidence and no internal referrers |
+| `actions dismiss <action-id>` | Mutation. Needs `--artifact-version`, read from `actions show`. `--note` records why the owner considers the action intentional or incorrect. Without a note, complete unlinked 404 or 410 evidence is required. Dismissal preserves observations and never verifies a fix |
 
 ## Pages, Scans, and lab performance
 
@@ -132,15 +132,52 @@ lines.
 | --- | --- |
 | `page inspect <url>` | Stored observations, Lighthouse rows and keywords for one Page. `--limit 1..200`, `--offset`, `--include-resolved`. Carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
 | `page issues` | Raw Page Issue rows. Pass `--action-id`, or pass both `--source` and `--issue`. Passing both selectors exits `2`. `--url`, `--path-prefix`, `--include-resolved`, `--limit 1..200`, `--offset`. When the selector matches nothing, `availableKeys` lists the pairs this Site does have. Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
-| `page scan <url>` | Mutation. Starts a mobile Scan and a desktop Scan |
+| `page scan <url>` | Mutation. Adds or re-enables the URL as a monitored Page, then starts mobile and desktop Scans |
 | `performance` | Stored Lighthouse lab overview for the Site: medians for perf, a11y, SEO, LCP, TBT, CLS. Lab Scans, never real-user field data |
 | `scans list` | Retained Lighthouse Scans, newest first, with scores, lab vitals, and the error on a failed Scan. `--limit 1..100` (default 25) |
 | `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.
+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
+the Page scan service, not the Team plan.
+
+`pageCreated: true` means a monitored Page was created. The URL may already
+have retained Scans. Automatic homepage assessment Scans use a separate
+slot without a monitored Page. A manual homepage Scan can therefore create
+a monitored Page while older homepage assessment Scans exist.
+The monitored Page then follows its own recurring schedule.
+
 ## Field Core Web Vitals
 
 | Command | What it returns, and its flags |
@@ -177,23 +214,33 @@ different numbers. Read the one that answers your question.
 | Field | What it counts |
 | --- | --- |
 | `total` | The number of rows the query matched, not clicks or impressions |
-| `totals` | Clicks, impressions, CTR and position for the full upstream query population. `totalsScope` says so in words. It may include rows outside this page. `null` when the server has no total |
+| `totals` | Upstream period totals from a separate read without grouping dimensions. These can include anonymized queries. Read `totalsScope`. `null` means unavailable |
 | `representedTotals` | Clicks and impressions for the rows in this response only, after local filtering. `representedTotalsScope` says so in words |
 
-So `representedTotals` is at or below `totals`, and raising `--limit` moves
-`representedTotals` while leaving `totals` still. Never sum `rows` by hand when
-`totals` is present.
+Raising `--limit` changes `representedTotals` while `totals` covers the full window.
+Grouped Page impressions can exceed whole-Site impressions when several Pages appear in one search.
+Do not assume `representedTotals` is at or below `totals`.
+Use `totals` for traffic totals, and `representedTotals` for the returned rows.
+Neither row filters nor pagination make `totals` a sum of the returned rows.
+
+Keyword lists omit `site:` and `inurl:` search operators after upstream paging.
+`total` and `page` still count upstream rows.
+Even `--all` can return fewer keyword rows than `total`.
+
+### Read keyword coverage separately
 
-### Never compare a keyword total with a page total
+Google suppresses query rows below a privacy threshold.
+Keyword rows therefore omit some traffic, even after `--all`.
+Their `representedTotals` measure only the returned keywords.
 
-Google suppresses query rows below a privacy threshold. So the `keywords` view
-sees a fraction of the traffic the `pages` view sees. On a typical property
-that is roughly half the impressions. Query-dimension totals are therefore
-always at or below page-dimension totals for the same Site and period. Never
-compare the two, and never report one as the Site total.
+The engine can read dimensionless totals that include anonymized traffic.
+Then `keywords.totals` can equal `pages.totals` for the same Site and period.
+Do not assume `keywords.totals` is the sum of visible keyword rows.
 
-Read the `pages` view for "how much traffic". Read the `keywords` view for
-"which terms are visible". A missing query row is never evidence of no demand.
+Read `timeseries.totals` for whole-Site traffic, `pages` rows for landing pages,
+and `keywords` rows for visible terms. Use `prevTotals` to compare Site traffic
+across periods.
+A missing query row is never evidence of no demand.
 
 ## Web Analytics