@nuxtseo/cli 0.1.0

package/dist/commands.js

@@ -0,0 +1,626 @@
+import * as prompts from '@clack/prompts';
+import { defineCommand } from 'citty';
+import { createApiClient, fromStateError, loadApiContext } from './api.js';
+import { openBrowser } from './browser.js';
+import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
+import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
+import { parseAbsolutePageUrl, parseInteger } from './parse.js';
+import { renderAction, renderActionResolution, renderActions, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRecoverableBacklinks, renderSearchStatus, renderSites, 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';
+import { VERSION } from './version.js';
+function present(runtime, globals, result, render) {
+    if (result._tag === 'Err')
+        return fromSdkFailure(result.error);
+    if (globals.json)
+        writeProtocolResponse(runtime, result.value);
+    else
+        writeOutput(runtime, render(result.value));
+    return ok(undefined);
+}
+async function withSpinner(runtime, message, task) {
+    const spinner = runtime.interactive
+        ? prompts.spinner({ output: runtime.error, signal: runtime.signal })
+        : null;
+    spinner?.start(message);
+    return task().then((result) => {
+        spinner?.stop();
+        return result;
+    }, (cause) => {
+        spinner?.error('Request failed');
+        return Promise.reject(cause);
+    });
+}
+async function apiAndSite(runtime, globals) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const site = await resolveSite(api.value, runtime, globals);
+    return site._tag === 'Err'
+        ? site
+        : ok({ api: api.value, siteId: site.value });
+}
+async function confirmMutation(runtime, globals, message) {
+    if (globals.yes)
+        return ok(true);
+    if (!runtime.interactive) {
+        return fail(EXIT_CODE.invalidInput, 'confirmation_required: This mutation requires `--yes` outside an interactive terminal.', undefined, 'confirmation_required');
+    }
+    const confirmed = await prompts.confirm({
+        message,
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+        initialValue: false,
+    });
+    if (prompts.isCancel(confirmed))
+        return fail(EXIT_CODE.interrupted, 'interrupted: Mutation cancelled.');
+    return ok(confirmed);
+}
+async function readLoginToken(runtime) {
+    if (runtime.interactive) {
+        const token = await prompts.password({
+            message: 'Team API token',
+            mask: '*',
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+            validate: value => typeof value === 'string' && value.trim() ? undefined : 'Token is required.',
+        });
+        if (prompts.isCancel(token))
+            return fail(EXIT_CODE.interrupted, 'interrupted: Login cancelled.');
+        return ok(token.trim());
+    }
+    if (runtime.inputIsTTY) {
+        return fail(EXIT_CODE.invalidInput, 'token_input_required: Pipe the token to `nuxtseo login`; tokens are never accepted as command arguments.', undefined, 'token_input_required');
+    }
+    const token = (await runtime.readStdin()).trim();
+    return token
+        ? ok(token)
+        : fail(EXIT_CODE.invalidInput, 'token_input_required: No token was received on stdin.', undefined, 'token_input_required');
+}
+/**
+ * Browser pairing: start a request, show the code, open the browser, then wait.
+ *
+ * The user compares the code on screen with the code printed here, so both are
+ * on stderr where the human output lives. Nothing is granted until they approve.
+ */
+async function pairInBrowser(runtime, apiUrl, options) {
+    const client = createCliPairingClient(apiUrl);
+    const pairing = await startPairing(client, runtime);
+    if (pairing._tag === 'Err')
+        return pairing;
+    const opened = options.openBrowser ? openBrowser(pairing.value.verificationUrl) : false;
+    writeDiagnostic(runtime, [
+        `Pairing code: ${pairing.value.pairingCode}`,
+        opened
+            ? `Approve this login in your browser: ${pairing.value.verificationUrl}`
+            : `Open this URL to approve the login: ${pairing.value.verificationUrl}`,
+        'The code above must match the one shown in the browser.',
+    ].join('\n'));
+    const spinner = runtime.interactive
+        ? prompts.spinner({ output: runtime.error, signal: runtime.signal })
+        : null;
+    spinner?.start('Waiting for approval');
+    const approved = await awaitPairingApproval(client, runtime, pairing.value);
+    spinner?.stop(approved._tag === 'Ok' ? 'Approved' : 'Not approved');
+    return approved._tag === 'Err' ? approved : ok(approved.value.token);
+}
+async function login(runtime, globals, options) {
+    const apiUrl = await resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths });
+    if (apiUrl._tag === 'Err')
+        return fromStateError(apiUrl.error);
+    // Pairing needs a browser and a person. Without an interactive terminal the
+    // old paste path is the only one that can complete, so CI keeps working
+    // unchanged.
+    const token = options.withToken || !runtime.interactive
+        ? await readLoginToken(runtime)
+        : await pairInBrowser(runtime, apiUrl.value.apiUrl, { openBrowser: !options.noBrowser });
+    if (token._tag === 'Err')
+        return token;
+    const client = createApiClient(apiUrl.value.apiUrl, token.value);
+    const validated = await withSpinner(runtime, 'Validating token', () => client.sites.list({}, { signal: runtime.requestSignal }));
+    if (validated._tag === 'Err')
+        return fromSdkFailure(validated.error);
+    const saved = await saveCredential(token.value, { paths: runtime.paths });
+    if (saved._tag === 'Err')
+        return fromStateError(saved.error);
+    if (saved.value.warning)
+        writeDiagnostic(runtime, `warning: ${saved.value.warning.message}`);
+    if (globals.apiUrl) {
+        const configured = await updateConfig({ apiUrl: apiUrl.value.apiUrl }, { paths: runtime.paths });
+        if (configured._tag === 'Err') {
+            writeDiagnostic(runtime, 'warning: The credential was stored, but the API URL could not be saved.');
+            return fromStateError(configured.error);
+        }
+    }
+    if (runtime.env.NUXTSEO_TOKEN !== undefined) {
+        writeDiagnostic(runtime, 'warning: NUXTSEO_TOKEN remains active and takes precedence over the stored credential.');
+    }
+    if (globals.json)
+        writeProtocolResponse(runtime, validated.value);
+    else
+        writeOutput(runtime, `Logged in. ${validated.value.data.sites.length} Sites accessible. Credential: ${saved.value.storage}.`);
+    return ok(undefined);
+}
+async function logout(runtime, globals) {
+    const cleared = await clearCredential({ paths: runtime.paths });
+    if (cleared._tag === 'Err')
+        return fromStateError(cleared.error);
+    if (globals.json) {
+        writeCliResponse(runtime, {
+            _tag: 'CliLogout',
+            schemaVersion: 1,
+            removed: cleared.value.removed,
+        });
+    }
+    else {
+        writeOutput(runtime, cleared.value.removed ? 'Local credential removed.' : 'No stored credential.');
+    }
+    writeDiagnostic(runtime, 'Token revocation remains in the NuxtSEO dashboard. NUXTSEO_TOKEN, when set, is unchanged.');
+    return ok(undefined);
+}
+async function whoami(runtime, globals) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const listed = await withSpinner(runtime, 'Checking authentication', () => api.value.client.sites.list({}, { signal: runtime.requestSignal }));
+    if (listed._tag === 'Err')
+        return fromSdkFailure(listed.error);
+    if (globals.json) {
+        writeProtocolResponse(runtime, listed.value);
+    }
+    else {
+        writeOutput(runtime, [
+            'Authenticated Team API token.',
+            `API: ${api.value.apiUrl}`,
+            `Credential: ${api.value.credentialSource}`,
+            `Accessible Sites: ${listed.value.data.sites.length}`,
+            `Selected Site: ${api.value.config.siteId ?? 'none'}`,
+        ].join('\n'));
+    }
+    return ok(undefined);
+}
+async function config(runtime, globals) {
+    const [stored, apiUrl, auth] = await Promise.all([
+        readConfig({ paths: runtime.paths }),
+        resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths }),
+        getCredentialStatus({ env: runtime.env, paths: runtime.paths }),
+    ]);
+    if (stored._tag === 'Err')
+        return fromStateError(stored.error);
+    if (apiUrl._tag === 'Err')
+        return fromStateError(apiUrl.error);
+    if (auth._tag === 'Err')
+        return fromStateError(auth.error);
+    if (globals.json) {
+        writeCliResponse(runtime, {
+            _tag: 'CliConfig',
+            schemaVersion: 1,
+            path: runtime.paths.configFile,
+            api: { url: apiUrl.value.apiUrl, source: apiUrl.value.source },
+            siteId: stored.value.siteId ?? null,
+            authentication: auth.value,
+        });
+        return ok(undefined);
+    }
+    if (!runtime.interactive) {
+        writeOutput(runtime, [
+            `Config: ${runtime.paths.configFile}`,
+            `API: ${apiUrl.value.apiUrl} (${apiUrl.value.source})`,
+            `Selected Site: ${stored.value.siteId ?? 'none'}`,
+            `Authentication: ${auth.value.authenticated ? auth.value.source : 'not configured'}`,
+        ].join('\n'));
+        return ok(undefined);
+    }
+    const action = await prompts.select({
+        message: 'Configuration',
+        options: [
+            { value: 'api', label: 'Set API host', hint: apiUrl.value.apiUrl },
+            { value: 'production', label: 'Use production API host' },
+            { value: 'clear-site', label: 'Clear selected Site', hint: stored.value.siteId ?? 'none selected' },
+            { value: 'done', label: 'Done' },
+        ],
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+    });
+    if (prompts.isCancel(action) || action === 'done')
+        return ok(undefined);
+    if (action === 'api') {
+        const next = await prompts.text({
+            message: 'API host',
+            initialValue: stored.value.apiUrl ?? apiUrl.value.apiUrl,
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(next))
+            return fail(EXIT_CODE.interrupted, 'interrupted: Configuration cancelled.');
+        const written = await updateConfig({ apiUrl: next }, { paths: runtime.paths });
+        if (written._tag === 'Err')
+            return fromStateError(written.error);
+        writeOutput(runtime, `API host saved: ${written.value.apiUrl}`);
+        return ok(undefined);
+    }
+    const written = await updateConfig(action === 'production' ? { apiUrl: undefined } : { siteId: undefined }, { paths: runtime.paths });
+    if (written._tag === 'Err')
+        return fromStateError(written.error);
+    writeOutput(runtime, action === 'production' ? 'Production API host restored.' : 'Selected Site cleared.');
+    return ok(undefined);
+}
+async function sitesList(runtime, globals) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const listed = await withSpinner(runtime, 'Loading Sites', () => api.value.client.sites.list({}, { signal: runtime.requestSignal }));
+    return present(runtime, globals, listed, response => renderSites(response, api.value.config.siteId));
+}
+async function sitesUse(runtime, globals, siteId) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const listed = await withSpinner(runtime, 'Checking Site access', () => api.value.client.sites.list({}, { signal: runtime.requestSignal }));
+    if (listed._tag === 'Err')
+        return fromSdkFailure(listed.error);
+    const site = listed.value.data.sites.find(candidate => candidate.id === siteId);
+    if (!site) {
+        return fail(EXIT_CODE.notFound, `site_not_accessible: ${siteId} is not accessible to this token.`, undefined, 'site_not_accessible');
+    }
+    const saved = await updateConfig({ siteId }, { paths: runtime.paths });
+    if (saved._tag === 'Err')
+        return fromStateError(saved.error);
+    if (globals.json) {
+        writeCliResponse(runtime, {
+            _tag: 'CliSiteSelection',
+            schemaVersion: 1,
+            site: {
+                id: site.id,
+                name: site.name ?? null,
+                url: site.url ?? null,
+            },
+        });
+    }
+    else {
+        writeOutput(runtime, `Selected Site: ${site.name ?? site.url ?? site.id} (${site.id})`);
+    }
+    return ok(undefined);
+}
+async function usage(runtime, globals, group) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const response = await withSpinner(runtime, 'Loading usage', () => api.value.client.account.usage({ query: { group } }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, renderUsage);
+}
+async function actionsList(runtime, globals, limitInput, offsetInput) {
+    const limit = parseInteger(limitInput, { name: '--limit', minimum: 1, maximum: 25, defaultValue: 10 });
+    if (limit._tag === 'Err')
+        return limit;
+    const offset = parseInteger(offsetInput, { name: '--offset', minimum: 0, defaultValue: 0 });
+    if (offset._tag === 'Err')
+        return offset;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading next actions', () => resolved.value.api.client.actions.list({
+        params: { siteId: resolved.value.siteId },
+        query: { limit: limit.value, offset: offset.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderActions(value.data));
+}
+async function actionsShow(runtime, globals, args) {
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 50 });
+    if (limit._tag === 'Err')
+        return limit;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading action', () => resolved.value.api.client.actions.show({
+        params: { siteId: resolved.value.siteId, actionId: args.actionId },
+        query: { groupId: args.groupId, cursor: args.cursor, limit: limit.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderAction(value.data));
+}
+async function actionsResolve(runtime, globals, actionId) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const shown = await withSpinner(runtime, 'Loading action evidence', () => resolved.value.api.client.actions.show({
+        params: { siteId: resolved.value.siteId, actionId },
+        query: { limit: 50 },
+    }, { signal: runtime.requestSignal }));
+    if (shown._tag === 'Err')
+        return fromSdkFailure(shown.error);
+    const confirmed = await confirmMutation(runtime, globals, `Resolve ${actionId}: ${shown.value.data.diagnosis}?`);
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Mutation cancelled.');
+        return ok(undefined);
+    }
+    const response = await withSpinner(runtime, 'Resolving action', () => resolved.value.api.client.actions.resolve({
+        params: { siteId: resolved.value.siteId, actionId },
+        body: { artifactVersion: shown.value.data.artifactVersion },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderActionResolution(value.data));
+}
+async function pageInspect(runtime, globals, args) {
+    const url = parseAbsolutePageUrl(args.url);
+    if (url._tag === 'Err')
+        return url;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 200, defaultValue: 100 });
+    if (limit._tag === 'Err')
+        return limit;
+    const offset = parseInteger(args.offset, { name: '--offset', minimum: 0, defaultValue: 0 });
+    if (offset._tag === 'Err')
+        return offset;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Inspecting Page', () => resolved.value.api.client.pages.inspect({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            url: url.value,
+            includeResolved: args.includeResolved ? '1' : '0',
+            limit: limit.value,
+            offset: offset.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderPageInspection(value.data));
+}
+async function pageScan(runtime, globals, rawUrl) {
+    const url = parseAbsolutePageUrl(rawUrl);
+    if (url._tag === 'Err')
+        return url;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const confirmed = await confirmMutation(runtime, globals, `Start mobile and desktop scans for ${url.value}?`);
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Mutation cancelled.');
+        return ok(undefined);
+    }
+    const response = await withSpinner(runtime, 'Starting Page scans', () => resolved.value.api.client.pages.scan({
+        params: { siteId: resolved.value.siteId },
+        body: { url: url.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderPageScan(value.data));
+}
+async function performance(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading performance', () => resolved.value.api.client.performance.overview({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderPerformance(value.data));
+}
+async function searchStatus(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Search Console status', () => resolved.value.api.client.search.readStatus({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderSearchStatus(value.data));
+}
+async function backlinksRecoverable(runtime, globals, limitInput, offsetInput) {
+    const limit = parseInteger(limitInput, { name: '--limit', minimum: 1, maximum: 200, defaultValue: 100 });
+    if (limit._tag === 'Err')
+        return limit;
+    const offset = parseInteger(offsetInput, { name: '--offset', minimum: 0, defaultValue: 0 });
+    if (offset._tag === 'Err')
+        return offset;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading recoverable Backlinks', () => resolved.value.api.client.backlinks.recoverable({
+        params: { siteId: resolved.value.siteId },
+        query: { limit: limit.value, offset: offset.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderRecoverableBacklinks(value.data));
+}
+async function mentionsList(runtime, globals, args) {
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 200, defaultValue: 100 });
+    if (limit._tag === 'Err')
+        return limit;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Mentions', () => resolved.value.api.client.mentions.list({
+        params: { siteId: resolved.value.siteId },
+        query: { limit: limit.value, includeFiltered: args.includeFiltered ? '1' : '0' },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderMentions(value.data));
+}
+function capture(execution, task, positionalArguments, expectedPositionals) {
+    return async () => {
+        if (positionalArguments.length > expectedPositionals) {
+            execution.result = fail(EXIT_CODE.invalidInput, `invalid_cli_input: Unexpected argument ${JSON.stringify(positionalArguments[expectedPositionals])}.`);
+            return;
+        }
+        execution.result = await task();
+    };
+}
+function positional(name, description) {
+    return { type: 'positional', required: true, valueHint: name, description };
+}
+export function createRootCommand(runtime, globals, execution) {
+    const sites = defineCommand({
+        meta: { name: 'sites', description: 'List and select Sites' },
+        subCommands: {
+            list: defineCommand({
+                meta: { name: 'list', description: 'List accessible Sites' },
+                run: ({ args }) => capture(execution, () => sitesList(runtime, globals), args._, 0)(),
+            }),
+            use: defineCommand({
+                meta: { name: 'use', description: 'Select the Site used by Site scoped commands' },
+                args: { siteId: positional('site-id', 'Accessible Site ID') },
+                run: ({ args }) => capture(execution, () => sitesUse(runtime, globals, args.siteId), args._, 1)(),
+            }),
+        },
+    });
+    const actions = defineCommand({
+        meta: { name: 'actions', description: 'Read and resolve next actions' },
+        subCommands: {
+            list: defineCommand({
+                meta: { name: 'list', description: 'List server ranked next actions' },
+                args: {
+                    limit: { type: 'string', description: 'Maximum actions, 1 to 25' },
+                    offset: { type: 'string', description: 'Pagination offset' },
+                },
+                run: ({ args }) => capture(execution, () => actionsList(runtime, globals, args.limit, args.offset), args._, 0)(),
+            }),
+            show: defineCommand({
+                meta: { name: 'show', description: 'Show one action and its evidence' },
+                args: {
+                    'actionId': positional('action-id', 'Action ID'),
+                    'group-id': { type: 'string', description: 'Evidence group ID' },
+                    'cursor': { type: 'string', description: 'Evidence cursor' },
+                    'limit': { type: 'string', description: 'Maximum evidence items, 1 to 100' },
+                },
+                run: ({ args }) => capture(execution, () => actionsShow(runtime, globals, {
+                    actionId: args.actionId,
+                    groupId: args['group-id'],
+                    cursor: args.cursor,
+                    limit: args.limit,
+                }), args._, 1)(),
+            }),
+            resolve: defineCommand({
+                meta: { name: 'resolve', description: 'Claim an action and start server verification' },
+                args: { actionId: positional('action-id', 'Action ID') },
+                run: ({ args }) => capture(execution, () => actionsResolve(runtime, globals, args.actionId), args._, 1)(),
+            }),
+        },
+    });
+    const page = defineCommand({
+        meta: { name: 'page', description: 'Inspect and scan Pages' },
+        subCommands: {
+            inspect: defineCommand({
+                meta: { name: 'inspect', description: 'Read stored Page observations' },
+                args: {
+                    'url': positional('url', 'Absolute Page URL'),
+                    'include-resolved': { type: 'boolean', description: 'Include resolved observations' },
+                    'limit': { type: 'string', description: 'Maximum observations, 1 to 200' },
+                    'offset': { type: 'string', description: 'Pagination offset' },
+                },
+                run: ({ args }) => capture(execution, () => pageInspect(runtime, globals, {
+                    url: args.url,
+                    includeResolved: args['include-resolved'],
+                    limit: args.limit,
+                    offset: args.offset,
+                }), args._, 1)(),
+            }),
+            scan: defineCommand({
+                meta: { name: 'scan', description: 'Start mobile and desktop Page scans' },
+                args: { url: positional('url', 'Absolute Page URL') },
+                run: ({ args }) => capture(execution, () => pageScan(runtime, globals, args.url), args._, 1)(),
+            }),
+        },
+    });
+    const backlinks = defineCommand({
+        meta: { name: 'backlinks', description: 'Read stored inbound link evidence' },
+        subCommands: {
+            recoverable: defineCommand({
+                meta: { name: 'recoverable', description: 'List inbound links whose destination is broken' },
+                args: {
+                    limit: { type: 'string', description: 'Maximum links, 1 to 200' },
+                    offset: { type: 'string', description: 'Pagination offset' },
+                },
+                run: ({ args }) => capture(execution, () => backlinksRecoverable(runtime, globals, args.limit, args.offset), args._, 0)(),
+            }),
+        },
+    });
+    const mentions = defineCommand({
+        meta: { name: 'mentions', description: 'Read pages that name the Site without linking to it' },
+        subCommands: {
+            list: defineCommand({
+                meta: { name: 'list', description: 'List stored Mentions, newest first' },
+                args: {
+                    'limit': { type: 'string', description: 'Maximum Mentions, 1 to 200' },
+                    'include-filtered': { type: 'boolean', description: 'Keep Mentions AI triage marked a false positive' },
+                },
+                run: ({ args }) => capture(execution, () => mentionsList(runtime, globals, {
+                    limit: args.limit,
+                    includeFiltered: args['include-filtered'],
+                }), args._, 0)(),
+            }),
+        },
+    });
+    const search = defineCommand({
+        meta: { name: 'search', description: 'Read Search Console state' },
+        subCommands: {
+            status: defineCommand({
+                meta: { name: 'status', description: 'Read Search Console status' },
+                run: ({ args }) => capture(execution, () => searchStatus(runtime, globals), args._, 0)(),
+            }),
+        },
+    });
+    return defineCommand({
+        meta: {
+            name: 'nuxtseo',
+            version: VERSION,
+            description: 'Use NuxtSEO from a terminal or automation',
+        },
+        args: {
+            'api-url': { type: 'string', description: 'Override the NuxtSEO API host' },
+            'site': { type: 'string', description: 'Override the selected Site' },
+            'json': { type: 'boolean', description: 'Write machine JSON; protocol envelopes remain unchanged' },
+            'no-input': { type: 'boolean', description: 'Disable every interactive prompt' },
+            'timeout-ms': { type: 'string', description: 'Request deadline in milliseconds, 1 to 300000' },
+            'yes': { type: 'boolean', alias: 'y', description: 'Confirm a mutation without prompting' },
+        },
+        subCommands: {
+            login: defineCommand({
+                meta: { name: 'login', description: 'Approve this machine in a browser and store the Team API token it mints' },
+                args: {
+                    'with-token': { type: 'boolean', description: 'Paste an existing Team API token instead of pairing' },
+                    // `--no-browser` negates this. The option contract derives a negated
+                    // boolean from the `no-` prefix, so the definition is the positive.
+                    'browser': { type: 'boolean', default: true, description: 'Open a browser for approval; --no-browser prints the URL' },
+                },
+                run: ({ args }) => capture(execution, () => login(runtime, globals, {
+                    withToken: args['with-token'],
+                    noBrowser: args.browser === false,
+                }), args._, 0)(),
+            }),
+            logout: defineCommand({
+                meta: { name: 'logout', description: 'Remove the local credential' },
+                run: ({ args }) => capture(execution, () => logout(runtime, globals), args._, 0)(),
+            }),
+            whoami: defineCommand({
+                meta: { name: 'whoami', description: 'Validate and describe the active credential' },
+                run: ({ args }) => capture(execution, () => whoami(runtime, globals), args._, 0)(),
+            }),
+            config: defineCommand({
+                meta: { name: 'config', description: 'Show or edit local configuration' },
+                run: ({ args }) => capture(execution, () => config(runtime, globals), args._, 0)(),
+            }),
+            sites,
+            usage: defineCommand({
+                meta: { name: 'usage', description: 'Read account usage' },
+                args: {
+                    group: {
+                        type: 'enum',
+                        options: ['integrations', 'compute', 'capacity'],
+                        description: 'Filter meter group',
+                    },
+                },
+                run: ({ args }) => capture(execution, () => usage(runtime, globals, args.group), args._, 0)(),
+            }),
+            actions,
+            backlinks,
+            mentions,
+            page,
+            performance: defineCommand({
+                meta: { name: 'performance', description: 'Read the stored Site performance overview' },
+                run: ({ args }) => capture(execution, () => performance(runtime, globals), args._, 0)(),
+            }),
+            search,
+        },
+    });
+}

package/dist/failures.d.ts

@@ -0,0 +1,36 @@
+import type { SdkFailure } from '@nuxtseo/sdk';
+export declare const EXIT_CODE: {
+    readonly success: 0;
+    readonly invalidInput: 2;
+    readonly authentication: 3;
+    readonly authorization: 4;
+    readonly conflict: 5;
+    readonly retryable: 6;
+    readonly infrastructure: 7;
+    readonly notFound: 8;
+    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' | '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'];
+export interface CliFailure {
+    _tag: 'CliFailure';
+    code: CliFailureCode;
+    exitCode: ExitCode;
+    message: string;
+    cause?: unknown;
+    protocolResponse?: unknown;
+}
+export type CliResult<T> = {
+    _tag: 'Ok';
+    value: T;
+} | {
+    _tag: 'Err';
+    error: CliFailure;
+};
+export declare function ok<T>(value: T): CliResult<T>;
+export declare function fail(exitCode: ExitCode, message: string, cause?: unknown, code?: CliFailureCode): CliResult<never>;
+export declare function fromSdkFailure(error: SdkFailure): CliResult<never>;
+export declare function unexpectedFailure(cause: unknown): CliFailure;