@nuxtseo/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # NuxtSEO CLI
 
 Use NuxtSEO public Site operations from a terminal, script, or coding agent.
-The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP,
-private routes, or providers.
+The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP or
+private routes. Live research uses declared public API operations.
 
 ## Install
 
@@ -148,7 +148,8 @@ Agent controls:
 | `--no-input` | Disable every prompt even when stdin and stdout are TTYs |
 | `--timeout-ms <milliseconds>` | Apply one deadline to Site resolution, SDK retries, and the operation; default `30000`, maximum `300000` |
 
-Request timeouts return `CliError` code `request_timeout` and exit `6`.
+Request timeouts return `CliError` code `request_timeout` and exit `6`. The
+error prints an exact retry command with a longer deadline.
 `SIGINT` and `SIGTERM` abort the active request and return exit `130`.
 
 ## Commands and paging
@@ -170,8 +171,28 @@ nuxtseo page inspect <url>
 nuxtseo page scan <url>
 nuxtseo performance
 nuxtseo search status
+nuxtseo search analytics <pages|keywords>
+nuxtseo research overview
+nuxtseo research keywords <topic>
+nuxtseo research serp <keyword>
+nuxtseo research rankings <domain>
+nuxtseo audit link-opportunities
+nuxtseo audit content-decay
+nuxtseo audit duplicates
+nuxtseo content briefs list
+nuxtseo content briefs show <brief-id>
+nuxtseo content briefs create <keyword>
 ```
 
+Run bare `nuxtseo` in a terminal for a task-based menu. It groups Site fixes,
+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.
+`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.
+
 The CLI fetches one page per invocation. It does not auto-page or merge
 responses.
 
@@ -182,18 +203,29 @@ responses.
 | `page inspect` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
 | `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` |
+| `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
 cursor reported by the response. A cursor is opaque; do not edit or infer it.
 
 ## Coding agents
 
-The package ships an agent skill that teaches Claude Code how to drive the CLI.
-Copy it into a project after install:
+The package ships an agent skill that teaches coding agents how to drive the
+CLI. Copy it into a global skill directory after installation.
+
+Claude Code:
+
+```sh
+mkdir -p ~/.claude/skills
+cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.claude/skills/
+```
+
+Codex:
 
 ```sh
-mkdir -p .claude/skills
-cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli .claude/skills/
+mkdir -p ~/.codex/skills
+cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.codex/skills/
 ```
 
 The skill covers the JSON contract, Site selection, paging, mutation consent,

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,
@@ -135,6 +147,45 @@ async function promptPageUrl(runtime, action) {
         ? fail(EXIT_CODE.interrupted, `interrupted: ${action} cancelled.`)
         : ok(url);
 }
+async function promptTextValue(runtime, options) {
+    const value = await prompts.text({
+        message: options.message,
+        placeholder: options.placeholder,
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+        validate: input => typeof input === 'string' && input.trim().length > 1
+            ? undefined
+            : `${options.label} is required.`,
+    });
+    return prompts.isCancel(value)
+        ? fail(EXIT_CODE.interrupted, `interrupted: ${options.label} entry cancelled.`)
+        : ok(value.trim());
+}
+function displayCommand(args) {
+    return `nuxtseo ${args.map(argument => /\s/.test(argument) ? JSON.stringify(argument) : argument).join(' ')}`;
+}
+function timeoutRetryFailure(failure, rawArgs, timeoutMs) {
+    if (failure.code !== 'request_timeout')
+        return failure;
+    const args = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        const argument = rawArgs[index];
+        if (argument === '--timeout-ms') {
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--timeout-ms='))
+            continue;
+        args.push(argument);
+    }
+    args.push('--timeout-ms', String(Math.min(timeoutMs * 2, 300_000)));
+    return { ...failure, message: `${failure.message}\nRetry: ${displayCommand(args)}` };
+}
+async function runInteractiveCommand(args, runtime, globals) {
+    writeDiagnostic(runtime, `Command: ${displayCommand(args)}`);
+    return runExplicit(args, runtime, globals);
+}
 async function interactiveBare(runtime, globals) {
     const [auth, apiUrl, config] = await Promise.all([
         getCredentialStatus({ env: runtime.env, paths: runtime.paths }),
@@ -153,49 +204,160 @@ async function interactiveBare(runtime, globals) {
         `API: ${apiUrl.value.apiUrl}`,
         `Current Site: ${config.value.siteId ?? 'none'}`,
     ].join('\n'), 'Status', { input: runtime.input, output: runtime.error });
-    const selected = await prompts.select({
-        message: 'What would you like to do?',
+    const group = await prompts.select({
+        message: 'Choose a task',
         options: [
             ...(!auth.value.authenticated ? [{ value: 'login', label: 'Log in', hint: 'Team API token' }] : []),
+            { value: 'fix', label: 'Fix my Site', hint: 'Issues, Pages, and scans' },
+            { value: 'performance', label: 'Understand performance', hint: 'Performance and Search Console' },
+            { value: 'research', label: 'Research growth', hint: 'Keywords, SERPs, and competitors' },
+            { value: 'content', label: 'Plan content', hint: 'Briefs, decay, and duplicates' },
+            { value: 'account', label: 'Account and setup', hint: config.value.siteId ?? 'no Site selected' },
+            { value: 'exit', label: 'Exit' },
+        ],
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+    });
+    if (prompts.isCancel(group) || group === 'exit')
+        return ok(undefined);
+    if (group === 'login')
+        return runInteractiveCommand(['login'], runtime, globals);
+    if (group === 'fix') {
+        const task = await prompts.select({
+            message: 'Fix my Site',
+            options: [
+                { value: 'actions', label: 'Issues and opportunities' },
+                { value: 'inspect', label: 'Inspect a Page' },
+                { value: 'scan', label: 'Scan a Page' },
+                { value: 'backlinks', label: 'Recover broken Backlinks' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'inspect' || task === 'scan') {
+            const url = await promptPageUrl(runtime, task === 'inspect' ? 'Inspect' : 'Scan');
+            return url._tag === 'Err'
+                ? url
+                : runInteractiveCommand(['page', task, url.value], runtime, globals);
+        }
+        return runInteractiveCommand(task === 'actions' ? ['actions', 'list'] : ['backlinks', 'recoverable'], runtime, globals);
+    }
+    if (group === 'performance') {
+        const task = await prompts.select({
+            message: 'Understand performance',
+            options: [
+                { value: 'performance', label: 'Performance overview' },
+                { value: 'connection', label: 'Search Console connection' },
+                { value: 'pages', label: 'Search Console Pages' },
+                { value: 'keywords', label: 'Search Console queries' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        const command = task === 'performance'
+            ? ['performance']
+            : task === 'connection'
+                ? ['search', 'status']
+                : ['search', 'analytics', task];
+        return runInteractiveCommand(command, runtime, globals);
+    }
+    if (group === 'research') {
+        const task = await prompts.select({
+            message: 'Research growth',
+            options: [
+                { value: 'overview', label: 'Site and competitors', hint: 'stored data' },
+                { value: 'keywords', label: 'Keyword ideas', hint: 'uses live research allowance' },
+                { value: 'serp', label: 'SERP analysis', hint: 'uses live research allowance' },
+                { value: 'rankings', label: 'Domain rankings', hint: 'uses live research allowance' },
+                { value: 'links', label: 'Link opportunities', hint: 'stored data' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'overview')
+            return runInteractiveCommand(['research', 'overview'], runtime, globals);
+        if (task === 'links')
+            return runInteractiveCommand(['audit', 'link-opportunities'], runtime, globals);
+        const label = task === 'rankings' ? 'Domain' : 'Keyword';
+        const value = await promptTextValue(runtime, {
+            message: task === 'rankings' ? 'Which domain?' : 'Which keyword or topic?',
+            placeholder: task === 'rankings' ? 'example.com' : 'nuxt seo',
+            label,
+        });
+        if (value._tag === 'Err')
+            return value;
+        return runInteractiveCommand(['research', task, value.value], runtime, globals);
+    }
+    if (group === 'content') {
+        const task = await prompts.select({
+            message: 'Plan content',
+            options: [
+                { value: 'briefs', label: 'Content Briefs' },
+                { value: 'create', label: 'Create a Content Brief' },
+                { value: 'decay', label: 'Content decay' },
+                { value: 'duplicates', label: 'Duplicate clusters' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'briefs')
+            return runInteractiveCommand(['content', 'briefs', 'list'], runtime, globals);
+        if (task === 'decay')
+            return runInteractiveCommand(['audit', 'content-decay'], runtime, globals);
+        if (task === 'duplicates')
+            return runInteractiveCommand(['audit', 'duplicates'], runtime, globals);
+        const keyword = await promptTextValue(runtime, {
+            message: 'Which target keyword?',
+            placeholder: 'nuxt seo',
+            label: 'Keyword',
+        });
+        return keyword._tag === 'Err'
+            ? keyword
+            : runInteractiveCommand(['content', 'briefs', 'create', keyword.value], runtime, globals);
+    }
+    const task = await prompts.select({
+        message: 'Account and setup',
+        options: [
             { value: 'site', label: 'Switch Site', hint: config.value.siteId ?? 'none selected' },
-            { value: 'actions', label: 'Next actions' },
-            { value: 'inspect', label: 'Inspect a Page' },
-            { value: 'scan', label: 'Scan a Page' },
-            { value: 'performance', label: 'Performance overview' },
-            { value: 'search', label: 'Search Console status' },
             { value: 'usage', label: 'Account usage' },
             { value: 'config', label: 'Configuration' },
-            { value: 'exit', label: 'Exit' },
+            { value: 'logout', label: 'Log out' },
         ],
         input: runtime.input,
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(selected) || selected === 'exit')
+    if (prompts.isCancel(task))
         return ok(undefined);
-    if (selected === 'site')
+    if (task === 'site')
         return switchSite(runtime, globals);
-    if (selected === 'inspect' || selected === 'scan') {
-        const url = await promptPageUrl(runtime, selected === 'inspect' ? 'Inspect' : 'Scan');
-        return url._tag === 'Err'
-            ? url
-            : runExplicit(['page', selected, url.value], runtime, globals);
-    }
-    const commands = {
-        login: ['login'],
-        actions: ['actions', 'list'],
-        performance: ['performance'],
-        search: ['search', 'status'],
-        usage: ['usage'],
-        config: ['config'],
-    };
-    return runExplicit(commands[selected], runtime, globals);
+    return runInteractiveCommand([task], 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,
@@ -204,23 +366,31 @@ export async function runCli(rawArgs, runtime) {
             runtime.requestSignal,
             AbortSignal.timeout(globals.timeoutMs),
         ]),
+        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
@@ -228,5 +398,9 @@ export async function runCli(rawArgs, runtime) {
             ? await interactiveBare(effectiveRuntime, globals)
             : await nonInteractiveBare(effectiveRuntime, globals)
         : await runExplicit(args, effectiveRuntime, globals);
-    return result._tag === 'Ok' ? EXIT_CODE.success : report(effectiveRuntime, result.error, globals.json);
+    const notice = await updateCheck;
+    writeUpdateNotice(effectiveRuntime, notice);
+    return result._tag === 'Ok'
+        ? EXIT_CODE.success
+        : report(effectiveRuntime, timeoutRetryFailure(result.error, rawArgs, globals.timeoutMs), globals.json, notice);
 }