@nuxtseo/cli 0.1.3 → 0.1.4

package/README.md

@@ -123,12 +123,14 @@ to stdout and writes the readable recovery message to stderr.
 
 Local outcomes have no server protocol body. With `--json`, commands such as
 bare `nuxtseo`, `config`, `logout`, and `sites use` emit a tagged CLI-owned JSON
-value with `schemaVersion: 1`. Local failures emit `CliError` with a stable code
-and exit code. These tags are separate from protocol envelopes.
-
-`--help --json` returns the selected command, global options, arguments, and
-subcommands as `CliHelp`. Option names are strict; an unknown option exits `2`
-before authentication or network work.
+value with `schemaVersion: 1`. `CliHelp` uses `schemaVersion: 2`. Local failures
+emit `CliError` with a stable code and exit code. These tags are separate from
+protocol envelopes.
+
+`--help --json` returns the selected command, inherited `globalOptions`,
+positional `arguments`, command-specific `localOptions`, and `subcommands` as
+`CliHelp`. Option names are strict. An unknown option exits `2` before
+authentication or network work.
 
 ## Automation controls
 

package/dist/command-contract.d.ts

@@ -16,12 +16,13 @@ export interface CliHelpArgument {
 }
 export interface CliHelpResponse {
     _tag: 'CliHelp';
-    schemaVersion: 1;
+    schemaVersion: 2;
     cliVersion: string;
     command: string;
     description?: string;
     globalOptions: CliHelpArgument[];
     arguments: CliHelpArgument[];
+    localOptions: CliHelpArgument[];
     subcommands: Array<{
         name: string;
         description?: string;

package/dist/command-contract.js

@@ -54,14 +54,16 @@ function argumentsFor(command) {
 export function describeCommand(root, rawArgs, cliVersion) {
     const resolved = resolveCommand(root, rawArgs.filter(argument => argument !== '--help' && argument !== '-h'));
     const meta = commandMeta(resolved.command);
+    const localArguments = resolved.command === root ? [] : argumentsFor(resolved.command);
     return {
         _tag: 'CliHelp',
-        schemaVersion: 1,
+        schemaVersion: 2,
         cliVersion,
         command: resolved.path.join(' '),
         ...(meta.description === undefined ? {} : { description: meta.description }),
         globalOptions: argumentsFor(root).filter(argument => argument.type !== 'positional'),
-        arguments: resolved.command === root ? [] : argumentsFor(resolved.command),
+        arguments: localArguments.filter(argument => argument.type === 'positional'),
+        localOptions: localArguments.filter(argument => argument.type !== 'positional'),
         subcommands: Object.entries(commandChildren(resolved.command)).flatMap(([name, value]) => {
             const child = childCommand(value);
             if (!child)

package/dist/commands.js

@@ -5,7 +5,7 @@ import { openBrowser } from './browser.js';
 import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
 import { parseAbsolutePageUrl, parseChoice, parseInteger } from './parse.js';
-import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderIndexingDiagnostics, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderUsage, } from './render.js';
+import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderIndexingDiagnostics, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderTimeline, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
@@ -606,6 +606,27 @@ async function auditLinkOpportunities(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderLinkOpportunities(value.data));
 }
+async function timelineEntries(runtime, globals, args) {
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 25 });
+    if (limit._tag === 'Err')
+        return limit;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Timeline', () => resolved.value.api.client.timeline.entries({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            kinds: args.kind,
+            feature: args.feature,
+            severity: args.severity,
+            since: args.since,
+            limit: limit.value,
+            cursor: args.cursor,
+            includeClosed: args.includeClosed,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderTimeline(value.data));
+}
 async function contentBriefList(runtime, globals, args) {
     const status = args.status === undefined
         ? ok(undefined)
@@ -977,6 +998,32 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
+    const timeline = defineCommand({
+        meta: { name: 'timeline', description: 'Read the Timeline — what changed on the Site' },
+        subCommands: {
+            list: defineCommand({
+                meta: { name: 'list', description: 'List Timeline Entries' },
+                args: {
+                    'kind': { type: 'string', description: 'Comma-separated Timeline Entry kinds, e.g. traffic.dropped,indexing.changed' },
+                    'feature': { type: 'string', description: 'Filter to the kinds registered under this feature' },
+                    'severity': { type: 'string', description: 'Comma-separated severities: info, notable, high' },
+                    'since': { type: 'string', description: 'Only entries at or after this ISO timestamp' },
+                    'limit': { type: 'string', description: 'Maximum Timeline Entries, 1 to 100' },
+                    'cursor': { type: 'string', description: 'Opaque pagination cursor from a previous page' },
+                    'include-closed': { type: 'boolean', description: 'Include closed episodes' },
+                },
+                run: ({ args }) => capture(execution, () => timelineEntries(runtime, globals, {
+                    kind: args.kind,
+                    feature: args.feature,
+                    severity: args.severity,
+                    since: args.since,
+                    limit: args.limit,
+                    cursor: args.cursor,
+                    includeClosed: args['include-closed'],
+                }), args._, 0)(),
+            }),
+        },
+    });
     return defineCommand({
         meta: {
             name: 'nuxtseo',
@@ -1041,6 +1088,7 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             research,
             search,
+            timeline,
         },
     });
 }

package/dist/render.d.ts

@@ -7,6 +7,7 @@ import type { IndexingDiagnosticsData, SearchAnalyticsData, SearchStatusData } f
 import type { PageInspect, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
 import type { KeywordResearchData, RankingsResearchData, SerpResearchData, StoredResearchOverview } from '@nuxtseo/protocol/v1/research';
+import type { TimelineEntries } from '@nuxtseo/protocol/v1/timeline';
 export declare function renderSites(response: SitesListResponse, selectedSiteId?: string): string;
 export declare function renderUsage(response: AccountUsageResponse): string;
 export declare function renderActions(data: ActionList): string;
@@ -28,5 +29,6 @@ export declare function renderContentBriefCreated(data: ContentBriefCreateData):
 export declare function renderContentDecay(data: AuditContentDecay): string;
 export declare function renderDuplicateClusters(data: AuditDuplicateClusters): string;
 export declare function renderLinkOpportunities(data: AuditLinkOpportunities): string;
+export declare function renderTimeline(data: TimelineEntries): string;
 export declare function renderRecoverableBacklinks(data: RecoverableBacklinks): string;
 export declare function renderMentions(data: Mentions): string;

package/dist/render.js

@@ -270,6 +270,18 @@ export function renderLinkOpportunities(data) {
         ...data.rows.map(row => `${row.phrase}\n  From: ${row.sourceUrl}\n  To: ${row.targetUrl}`),
     ].join('\n');
 }
+export function renderTimeline(data) {
+    if (data.entries.length === 0)
+        return 'No Timeline Entries match these filters.';
+    return [
+        `Timeline (${data.entries.length})`,
+        ...data.entries.map((entry) => {
+            const label = typeof entry.rendered?.label === 'string' ? entry.rendered.label : entry.kind;
+            return `${entry.occurredAt}  ${entry.severity ?? 'unrated'}  ${entry.kind}\n  ${label}`;
+        }),
+        data.nextCursor ? `More Timeline Entries available — pass --cursor ${JSON.stringify(data.nextCursor)}.` : '',
+    ].filter(Boolean).join('\n');
+}
 export function renderRecoverableBacklinks(data) {
     if (data.items.length === 0)
         return 'No recoverable Backlinks. Every stored inbound link resolves.';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -34,7 +34,7 @@
     "@clack/prompts": "^1.7.0",
     "citty": "^0.2.2",
     "pathe": "^2.0.3",
-    "@nuxtseo/sdk": "^0.1.3"
+    "@nuxtseo/sdk": "^0.1.4"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.3.0"
@@ -44,7 +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/protocol": "0.1.3"
+    "@nuxtseo/protocol": "0.1.4"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -132,11 +132,11 @@ handling failures, read [CLI protocol](references/protocol.md).
 `page inspect` and `page scan` take an absolute URL, for example
 `https://example.com/about`.
 
-`--help --json` returns a `CliHelp` value for one command level: its
-`arguments`, the inherited `globalOptions`, and its `subcommands` as names and
-descriptions only. To learn a subcommand's own flags, ask it directly, for
-example `nuxtseo actions list --help --json`. Use this instead of guessing a
-flag, and prefer the table above for anything it already answers.
+`--help --json` returns a `CliHelp` value for one command level. It separates
+positional `arguments`, command-specific `localOptions`, inherited
+`globalOptions`, and `subcommands`. To learn a subcommand's own flags, ask it
+directly, for example `nuxtseo actions list --help --json`. Use this instead of
+guessing a flag, and prefer the table above for anything it already answers.
 
 ## The triage loop
 

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

@@ -18,7 +18,8 @@ Protocol failure, still on stdout, with recovery details on stderr:
 
 Read `data`. The CLI does not unwrap, rename, rank, or enrich fields.
 
-Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
+Local outcomes have no server body. They carry one tag and their own schema
+version. `CliHelp` uses version 2. The other values use version 1.
 
 | `_tag` | Written by |
 | --- | --- |