@nuxtseo/cli 0.5.4 → 0.5.7

package/README.md

@@ -206,6 +206,9 @@ nuxtseo sitemaps urls
 nuxtseo sitemaps submit <sitemap-url>
 nuxtseo sitemaps delete <sitemap-url>
 nuxtseo research overview
+nuxtseo research competitors list
+nuxtseo research competitors add <domain> --yes
+nuxtseo research competitors remove <competitor-id> --yes
 nuxtseo research domain-traffic <domain>
 nuxtseo research domain-availability <domains>
 nuxtseo research keywords <topic>

package/dist/commands.js

@@ -55,6 +55,7 @@ function present(runtime, globals, result, render) {
 export const ALL_PAGES_REQUEST_CAP = 50;
 async function collect(runtime, globals, options) {
     let position = options.start;
+    const seenKeys = new Set();
     for (let request = 1;; request++) {
         const response = await withSpinner(runtime, options.message, () => options.fetch(position));
         if (response._tag === 'Err')
@@ -62,6 +63,12 @@ async function collect(runtime, globals, options) {
         emit(runtime, globals, response.value, options.render);
         if (!options.all)
             return ok(undefined);
+        for (const key of options.rowKeys?.(response.value) ?? []) {
+            if (seenKeys.has(key)) {
+                return fail(EXIT_CODE.infrastructure, 'paging_unstable: Search Console pages repeated row keys. Export coverage is incomplete. Preserve these responses for investigation.', undefined, 'paging_unstable');
+            }
+            seenKeys.add(key);
+        }
         const next = options.next(response.value, position);
         if (next._tag === 'Done')
             return ok(undefined);
@@ -647,6 +654,24 @@ async function searchAnalytics(runtime, globals, args) {
             },
         }, { signal: runtime.requestSignal }),
         render: value => renderSearchAnalytics(value.data),
+        rowKeys: (value) => {
+            const data = value.data;
+            if (!('rows' in data) || view.value === 'analysis')
+                return [];
+            return data.rows.flatMap((row) => {
+                // Canonical URLs can repeat legitimately. Only Google's exact page
+                // dimension is unique; older responses can omit it.
+                if (view.value === 'pages')
+                    return 'gscPage' in row && typeof row.gscPage === 'string' ? [row.gscPage] : [];
+                if ('keyword' in row && typeof row.keyword === 'string')
+                    return [row.keyword];
+                if ('country' in row)
+                    return [row.country];
+                if ('device' in row)
+                    return [row.device];
+                return [];
+            });
+        },
         next: (value, position) => {
             const data = value.data;
             if (!('total' in data) || !('rows' in data))
@@ -762,6 +787,49 @@ async function researchOverview(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderResearchOverview(value.data));
 }
+async function competitorsList(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading competitors', () => resolved.value.api.client.research.listCompetitors({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => value.data.competitors.map(competitor => `${competitor.id}\t${competitor.domain}`).join('\n') || '0 tracked competitors');
+}
+async function competitorWrite(runtime, globals, action) {
+    const confirmed = await confirmMutation(runtime, globals, action._tag === 'Add'
+        ? `Track ${action.domain}? This uses the research limit.`
+        : `Remove competitor ${action.competitorId}? This cannot be undone.`);
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Mutation cancelled.');
+        return ok(undefined);
+    }
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    if (action._tag === 'Add') {
+        const response = await withSpinner(runtime, 'Adding competitor', () => resolved.value.api.client.research.addCompetitor({
+            params: { siteId: resolved.value.siteId },
+            body: { domain: action.domain },
+        }, { signal: runtime.requestSignal }));
+        // The add only queues the analysis. Name the read that shows it, so the
+        // caller is not left with "queued" and no way to see the result.
+        const overview = `\`nuxtseo research overview --site ${resolved.value.siteId}\``;
+        const result = present(runtime, globals, response, value => [
+            `${value.data.competitor.id}\t${value.data.competitor.domain}\tAnalysis queued`,
+            `Run ${overview} in a few minutes to read the analysis.`,
+        ].join('\n'));
+        if (result._tag === 'Ok' && globals.json)
+            writeDiagnostic(runtime, `Note: Analysis runs in the background. Read it with ${overview}. The competitor's collectedAt stays null until the analysis finishes.`);
+        return result;
+    }
+    const response = await withSpinner(runtime, 'Removing competitor', () => resolved.value.api.client.research.removeCompetitor({
+        params: { siteId: resolved.value.siteId, competitorId: action.competitorId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => `Removed competitor ${value.data.competitorId}`);
+}
 /**
  * DataForSEO refuses these characters, so the research provider removes them
  * before it counts the words of a seed. Mirrored from
@@ -989,7 +1057,19 @@ async function sitemapsAction(runtime, globals, action, rawUrl) {
         params: { siteId: resolved.value.siteId },
         body: { action, sitemapUrl: sitemapUrl.value },
     }, { signal: runtime.requestSignal }));
-    return present(runtime, globals, response, value => renderSitemapAction(value.data));
+    if (action === 'delete')
+        return present(runtime, globals, response, value => renderSitemapAction(value.data));
+    // Success means Search Console accepted the submit, not that Google read the
+    // file. Name the read that shows the download, so the caller does not take
+    // the submit for a fetch.
+    const list = `\`nuxtseo sitemaps list --site ${resolved.value.siteId}\``;
+    const result = present(runtime, globals, response, value => [
+        renderSitemapAction(value.data),
+        `Google downloads it later. Run ${list} to see when.`,
+    ].join('\n'));
+    if (result._tag === 'Ok' && globals.json)
+        writeDiagnostic(runtime, `Note: Search Console accepted the sitemap. Google downloads it later. Run ${list} and read lastDownloaded and isPending.`);
+    return result;
 }
 async function analyticsQuery(runtime, globals, args) {
     const view = parseChoice(args.view, { name: 'view', choices: ANALYTICS_VIEWS });
@@ -1833,6 +1913,25 @@ export function createRootCommand(runtime, globals, execution) {
     const research = defineCommand({
         meta: { name: 'research', description: 'Read stored and live search research' },
         subCommands: {
+            'competitors': defineCommand({
+                meta: { name: 'competitors', description: 'Manage tracked competitors for the Site' },
+                subCommands: {
+                    list: defineCommand({
+                        meta: { name: 'list', description: 'List tracked competitor domains and ids' },
+                        run: ({ args }) => capture(execution, () => competitorsList(runtime, globals), args._, 0)(),
+                    }),
+                    add: defineCommand({
+                        meta: { name: 'add', description: 'Track one competitor and queue its analysis' },
+                        args: { domain: positional('domain', 'Public competitor domain') },
+                        run: ({ args }) => capture(execution, () => competitorWrite(runtime, globals, { _tag: 'Add', domain: args.domain }), args._, 1)(),
+                    }),
+                    remove: defineCommand({
+                        meta: { name: 'remove', description: 'Remove one competitor using its listed id' },
+                        args: { competitorId: positional('competitorId', 'Competitor id from research competitors list') },
+                        run: ({ args }) => capture(execution, () => competitorWrite(runtime, globals, { _tag: 'Remove', competitorId: args.competitorId }), args._, 1)(),
+                    }),
+                },
+            }),
             'overview': defineCommand({
                 meta: { name: 'overview', description: 'Read stored Site metrics and competitor research' },
                 run: ({ args }) => capture(execution, () => researchOverview(runtime, globals), args._, 0)(),

package/dist/failures.d.ts

@@ -12,7 +12,7 @@ export declare const EXIT_CODE: {
     readonly interrupted: 130;
 };
 export type ExitCode = typeof EXIT_CODE[keyof typeof EXIT_CODE];
-export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'pull_incomplete' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
+export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'paging_unstable' | 'pull_incomplete' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
 export type CliFailureCode = LocalFailureCode | Extract<SdkFailure, {
     _tag: 'ApiFailure';
 }>['code'];

package/dist/render.js

@@ -469,6 +469,16 @@ export function renderIndexingDiagnostics(data) {
         data.hasMore ? `More URLs available after offset ${data.offset + data.limit}.` : '',
     ].filter(Boolean).join('\n');
 }
+function renderResearchCompetitor(row) {
+    // A competitor without a collection time is still queued; its zero counts
+    // mean nothing yet.
+    if (row.collectedAt === null)
+        return `${row.domain}  analysis pending`;
+    // Quick wins come from shared keywords. With none shared, "0 quick wins"
+    // says nothing about positions, so name the reason.
+    const overlap = row.sharedKeywords.length ? '' : '  no shared keywords';
+    return `${row.domain}  ${row.metrics.organicTraffic ?? 'unknown'} traffic  ${row.quickWins.length} quick wins${overlap}`;
+}
 export function renderResearchOverview(data) {
     const subject = data.subject
         ? fields([
@@ -480,13 +490,23 @@ export function renderResearchOverview(data) {
         : 'No stored Site research.';
     const competitors = data.competitors.length === 0
         ? 'No stored competitors.'
-        : data.competitors.map(row => `${row.domain}  ${row.metrics.organicTraffic ?? 'unknown'} traffic  ${row.quickWins.length} quick wins`).join('\n');
+        : data.competitors.map(renderResearchCompetitor).join('\n');
     return [subject, `Competitors: ${data.summary.competitorCount}`, competitors].join('\n');
 }
 export function renderKeywordResearch(data) {
+    const measured = data.topicMetrics.filter(row => row._tag === 'measured').length;
+    const topics = data.topicMetrics.length
+        ? [
+            `Requested topics (${measured}/${data.topicMetrics.length} measured)`,
+            ...data.topicMetrics.map(row => row._tag === 'measured'
+                ? `${row.metrics.volume ?? 'unknown'} volume  ${row.metrics.difficulty ?? 'unknown'} difficulty  ${row.metrics.intent ?? 'unknown intent'}\n  ${row.topic}`
+                : `No data returned\n  ${row.topic}`),
+        ]
+        : [];
     if (data.keywords.length === 0)
-        return data.message ?? `No keyword ideas found for ${data.topic}.`;
+        return [...topics, data.message ?? `No keyword ideas found for ${data.topic}.`, ...(data.tip ? [`Tip: ${data.tip}`] : [])].join('\n');
     return [
+        ...topics,
         `Keyword ideas for ${data.topic} (${data.keywords.length} of ${data.totalFound})${data.evidence._tag === 'cache' ? '  cached' : ''}`,
         ...data.keywords.map(row => `${row.volume ?? 'unknown'} volume  ${row.difficulty ?? 'unknown'} difficulty  ${row.intent ?? 'unknown intent'}\n  ${row.keyword}`),
         ...(data.tip ? [`Tip: ${data.tip}`] : []),

package/dist/skill.js

@@ -32,6 +32,15 @@ const AGENT_DIRECTORIES = {
     claude: '.claude',
     codex: '.codex',
 };
+/**
+ * The notice names the agent. The check reads every agent's install, so a
+ * line without the name reads as the caller's own skill when another agent's
+ * copy is the stale one.
+ */
+const AGENT_NAMES = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+};
 /**
  * The skill shipped inside this package. A global install puts it outside the
  * project, so the documented `cp -R node_modules/...` path does not exist for
@@ -210,7 +219,8 @@ export function skillNoticeFor(installed, current, agent) {
     return installed.version === current ? null : { agent, installed: installed.version, current };
 }
 export function skillNoticeLine(notice) {
-    const installed = notice.installed === null ? 'skill version unknown' : `skill ${notice.installed} installed`;
+    const agent = AGENT_NAMES[notice.agent];
+    const installed = notice.installed === null ? `${agent} skill version unknown` : `${agent} skill ${notice.installed} installed`;
     if (notice.installed !== null) {
         const installedParts = /^(\d+)\.(\d+)\.(\d+)$/.exec(notice.installed);
         const currentParts = /^(\d+)\.(\d+)\.(\d+)$/.exec(notice.current);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.5.4",
+  "version": "0.5.7",
   "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.4",
-    "@nuxtseo/sdk": "^0.5.4",
+    "@nuxtseo/protocol": "^0.5.7",
+    "@nuxtseo/sdk": "^0.5.7",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -44,9 +44,11 @@ Read the matching file before you act on its subject:
 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
    first. If the skill is older, run `nuxtseo skill install --agent claude` and
-   re-read this file. An older skill hides commands. If
-   `NUXTSEO_NO_UPDATE_CHECK` is set, the line never appears; compare this
-   file's frontmatter `version` with the binary instead.
+   re-read this file. An older skill hides commands. The stderr line names
+   the agent whose copy differs, such as `Codex skill 0.5.3 installed`.
+   Refresh only that agent. If `NUXTSEO_NO_UPDATE_CHECK` is set, the line
+   never appears; compare this file's frontmatter `version` with the binary
+   instead.
 
 3. **Token.** Run `nuxtseo whoami --json`. It returns the Team, role, scopes,
    and token expiry. Exit `3` means no working token. Ask the user to run
@@ -64,6 +66,7 @@ Read the matching file before you act on its subject:
    | `page scan` | `page:write` |
    | `actions resolve`, `actions dismiss` | `actions:write` |
    | `annotations` writes | `timeline:write` |
+   | `research competitors add`, `research competitors remove` | `research:write` |
    | `sitemaps submit`, `sitemaps delete` | `sites:write` |
 
    If a write scope is missing, do the reads, then hand the user the exact

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

@@ -199,7 +199,7 @@ The monitored Page then follows its own recurring schedule.
 | `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` |
-| `sitemaps submit <sitemap-url>` | Mutation. Submits one sitemap through the Site's stored Search Console credential |
+| `sitemaps submit <sitemap-url>` | Mutation. Submits one sitemap through the Site's stored Search Console credential. Success means Search Console accepted it, not that Google downloaded it. Read `lastDownloaded` and `isPending` in `sitemaps list` |
 | `sitemaps delete <sitemap-url>` | Mutation. Removes one sitemap through the Site's stored Search Console credential |
 
 Analysis presets for `search analytics analysis` are `striking-distance`,
@@ -252,12 +252,16 @@ A missing query row is never evidence of no demand.
 ## Research, backlinks, and mentions
 
 Every command here can start live research, except `research overview`,
+`research competitors list`, `research competitors remove`,
 `backlinks recoverable` and `mentions list`, which read retained rows. Read the
 research boundary in SKILL.md first.
 
 | Command | What it returns, and its flags |
 | --- | --- |
-| `research overview` | Stored Site and competitor research: metrics, history, gaps, quick wins. Takes no flags. Returns `data.competitors` and `data.summary` |
+| `research overview` | Stored Site and competitor research: metrics, history, gaps, quick wins. Takes no flags. Returns `data.competitors` and `data.summary`. A competitor with `collectedAt: null` is still queued, so its empty lists mean nothing yet. Quick wins come from `sharedKeywords`; when that list is empty, zero quick wins says nothing about positions |
+| `research competitors list` | Tracked competitor domains and ids for this Site. Suggested competitors stay excluded. Reads start no provider work. |
+| `research competitors add <domain>` | Mutation, requires `research:write` and `--yes`. Accepts a public domain or URL. Queues analysis within existing Site and Team limits. Returns `data.competitor.id` and `data.status: queued`. The analysis runs in the background; read it with `research overview` |
+| `research competitors remove <competitor-id>` | Mutation, requires `research:write` and `--yes`. Use an id from the list. Removes that Site's competitor without provider work. |
 | `research keywords <topic>` | Live keyword ideas, with volume, difficulty, intent, and cost data. The seed must be 1 to 3 words. The server refuses a longer seed. The refusal arrives as exit `0` with an empty `data.keywords`, so read `data.message` first. Comma-separate several short seeds instead. Special characters are stripped before the lookup. If a seed is under 2 characters after stripping, the server refuses it the same way. The server applies default filters and echoes them in `data.filters`: `--min-volume` (default 10), `--max-volume` (default 10000), `--min-difficulty 0..100` (default 0), `--max-difficulty 0..100` (default 60). So a default run hides keywords over difficulty 60 or under 10 searches. Also `--limit 1..100` (default 20), `--intent`, `--location-code` (default 2840), `--no-related` to drop related keywords, and `--verbose` for full evidence. If `--max-volume` is under `--min-volume`, the run exits `2`. The same holds for `--max-difficulty` under `--min-difficulty` |
 | `research serp <keyword>` | A live SERP snapshot: results, features, fetch time. `--depth 1..20` (default 10) sets how many organic results return. `--location-code` (default 2840). The keyword must be 2 to 200 characters. `data.cached` reports cache use |
 | `research rankings <domain>` | Live domain rankings: current keywords and domain metrics. `--limit 1..100` (default 50), `--min-position 1..100` (default 1), `--max-position 1..100` (default 20), `--location-code` (default 2840), `--order position\|traffic` (default `position`). So a default run returns only the top 20 positions. If `--max-position` is under `--min-position`, the run exits `2`. An unusable domain also exits `2`, with `invalid_request`. An empty `data.keywords` with exit `0` carries the reason in `data.message`. `data.cached` reports cache use |
@@ -270,6 +274,13 @@ research boundary in SKILL.md first.
 | `backlinks recoverable` | Stored recoverable backlinks. `--limit 1..200`, `--offset`. Reads retained rows |
 | `mentions list` | Stored mentions. `--limit 1..200` (default 100), `--include-filtered` to keep the Mentions AI triage marked a false positive. Reads retained rows |
 
+Keyword research returns `data.topicMetrics` for every accepted comma-separated topic.
+Read it separately from filtered `data.keywords`, which contains keyword ideas.
+A `measured` row preserves exact metrics, including zero volume and values outside idea filters.
+A `no-data` row means the provider returned no exact metrics. It does not mean zero volume.
+If any topic becomes shorter than two characters after sanitization, the server refuses the whole request.
+Cached reads preserve all topic metrics without another provider call.
+
 ## Crawl audit
 
 | Command | What it returns, and its flags |

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

@@ -89,6 +89,14 @@ The `--all` loop stops after 50 requests. If pages remain, the CLI exits `9`
 and stderr names the argument that resumes the read, for example `--offset 50`.
 Treat exit `9` as a stop, never as the end of the data.
 
+Search Console breakdown exports stop with exit `7` and `paging_unstable`
+when an exact row key repeats. The CLI preserves the offending response.
+The export is incomplete. Preserve the responses and report the ordering issue.
+Do not resume from a later page, because overlapping pages can also omit rows.
+Canonical page URLs can repeat. The check uses `gscPage`, Google's exact page string.
+Older page responses can omit `gscPage`, so those rows have no overlap check.
+Analysis shortlists have no unique row contract and are excluded from this check.
+
 Pass the reported `offset` or opaque `cursor` for another page. Never edit or
 infer a cursor. Keep server order for actions. Never re-rank merged results.