@nuxtseo/cli 0.2.1 → 0.4.0

package/dist/runtime.d.ts

@@ -9,11 +9,16 @@ export interface CliRuntime {
     inputIsTTY: boolean;
     interactive: boolean;
     signal: AbortSignal;
+    /** Read once per request. Each read carries its own `--timeout-ms` deadline. */
     requestSignal: AbortSignal;
     requestTimeoutMs?: number;
     readStdin: () => Promise<string>;
 }
 export declare function writeOutput(runtime: CliRuntime, text: string): void;
 export declare function writeDiagnostic(runtime: CliRuntime, text: string): void;
+/**
+ * Machine output is written through these two functions only. Both strip ANSI
+ * escapes, so no dependency can colour a string into a JSON envelope.
+ */
 export declare function writeProtocolResponse(runtime: CliRuntime, response: unknown): void;
 export declare function writeCliResponse(runtime: CliRuntime, response: unknown): void;

package/dist/runtime.js

@@ -1,12 +1,17 @@
+import { stringifyWithoutAnsi } from './ansi.js';
 export function writeOutput(runtime, text) {
     runtime.output.write(text.endsWith('\n') ? text : `${text}\n`);
 }
 export function writeDiagnostic(runtime, text) {
     runtime.error.write(text.endsWith('\n') ? text : `${text}\n`);
 }
+/**
+ * Machine output is written through these two functions only. Both strip ANSI
+ * escapes, so no dependency can colour a string into a JSON envelope.
+ */
 export function writeProtocolResponse(runtime, response) {
-    writeOutput(runtime, JSON.stringify(response));
+    writeOutput(runtime, stringifyWithoutAnsi(response));
 }
 export function writeCliResponse(runtime, response) {
-    writeOutput(runtime, JSON.stringify(response));
+    writeOutput(runtime, stringifyWithoutAnsi(response));
 }

package/dist/skill.d.ts

@@ -1,11 +1,31 @@
 import type { CliResult } from './failures.js';
+import type { StatePaths } from './state/index.js';
 export declare const SKILL_NAME = "nuxtseo-cli";
+/** The stamp an install leaves beside the skill so a later run can read its version. */
+export declare const SKILL_VERSION_FILENAME = ".skill-version.json";
+/** The skill entry file, which also carries the version in its frontmatter. */
+export declare const SKILL_MARKDOWN_FILENAME = "SKILL.md";
+/**
+ * How long one answer stays authoritative, matching the npm update check.
+ *
+ * Declared here rather than imported so `update-check.ts` can depend on this
+ * module and the two never form an import cycle.
+ */
+export declare const SKILL_CHECK_INTERVAL_MS: number;
 export declare const SKILL_AGENTS: readonly ['claude', 'codex'];
 export type SkillAgent = typeof SKILL_AGENTS[number];
 export interface SkillInstallation {
     agent: SkillAgent;
     source: string;
+    /** The path the caller asked for, which may be a symlink. */
     destination: string;
+    /** Where the files actually landed, after following a symlinked destination. */
+    resolvedDestination: string;
+    version: string;
+    /** Files written by this install. */
+    written: number;
+    /** Files removed because this release no longer ships them. */
+    pruned: number;
 }
 /**
  * The skill shipped inside this package. A global install puts it outside the
@@ -14,9 +34,88 @@ export interface SkillInstallation {
  */
 export declare function skillSourceDirectory(moduleUrl?: string): string;
 export declare function skillDestination(homeDirectory: string, agent: SkillAgent): string;
+/**
+ * The install target, followed through a symlink.
+ *
+ * People keep their skills in one directory and link each agent's skill folder
+ * at it. `fs.cp` lstats the target, sees a link rather than a directory, and
+ * refuses with `ERR_FS_CP_DIR_TO_NON_DIR` before it copies anything. That
+ * reported as a permission problem on a directory the user owned and could
+ * write. Follow the link first so the copy writes where the person pointed it.
+ */
+export declare function resolveSkillTarget(destination: string): Promise<string>;
+/** An errno or Node error as a person can act on it: code, call, and path. */
+export declare function describeIoCause(cause: unknown): string;
+/**
+ * Write the running version into the skill frontmatter.
+ *
+ * An agent reads `SKILL.md` and nothing else, so the file has to say which
+ * release it came from. Without it a skill from an older CLI hides every
+ * command added since, and the agent cannot tell.
+ */
+export declare function stampSkillVersion(markdown: string, version: string): string;
+/** The version recorded in a `SKILL.md` frontmatter, when it carries one. */
+export declare function frontmatterVersion(markdown: string): string | null;
+export type InstalledSkill = {
+    _tag: 'SkillMissing';
+} | {
+    _tag: 'SkillUnversioned';
+} | {
+    _tag: 'SkillVersion';
+    version: string;
+};
+/**
+ * Which version of the skill sits in a destination directory.
+ *
+ * Reads the stamp first, then the frontmatter, so a skill installed by hand or
+ * by an older release still reports something the caller can compare.
+ */
+export declare function readInstalledSkill(destination: string): Promise<InstalledSkill>;
+export interface SkillNotice {
+    agent: SkillAgent;
+    installed: string | null;
+    current: string;
+}
+/**
+ * A stale installed skill, or `null` when nothing needs saying.
+ *
+ * An absent skill is not stale: the person may not use one. Any other
+ * difference from the running binary is, in both directions, because the two
+ * describe different command sets.
+ */
+export declare function skillNoticeFor(installed: InstalledSkill, current: string, agent: SkillAgent): SkillNotice | null;
+export declare function skillNoticeLine(notice: SkillNotice): string;
+export interface SkillCheckCache {
+    lastCheckedAt: string;
+    cliVersion: string;
+    installed: Partial<Record<SkillAgent, string | null>>;
+}
+export declare function parseSkillCheckCache(content: string): SkillCheckCache | null;
+/**
+ * Whether the filesystem has to be read again.
+ *
+ * A cache from a different binary is never reusable: the binary version is half
+ * of the comparison, so an upgrade must warn on the very next run.
+ */
+export declare function skillCheckDue(cache: SkillCheckCache | null, now: Date, current: string): boolean;
+export interface SkillCheckOptions {
+    paths: StatePaths;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => Date;
+    /** The home the agent directories sit in; defaults to the state directory's parent. */
+    homeDirectory?: string;
+}
+/**
+ * One line's worth of "your installed skill is not this binary".
+ *
+ * Costs one cached read per day, and nothing at all when the caller disabled
+ * update checks.
+ */
+export declare function checkSkillVersion(options: SkillCheckOptions): Promise<SkillNotice | null>;
 export declare function installSkill(options: {
     agent: SkillAgent;
     homeDirectory: string;
     target?: string;
     sourceDirectory?: string;
+    paths?: StatePaths;
 }): Promise<CliResult<SkillInstallation>>;

package/dist/skill.js

@@ -1,8 +1,25 @@
-import { cp, mkdir, stat } from 'node:fs/promises';
+import { copyFile, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative } from 'pathe';
 import { EXIT_CODE, fail, ok } from './failures.js';
+import { VERSION } from './version.js';
 export const SKILL_NAME = 'nuxtseo-cli';
+/** The stamp an install leaves beside the skill so a later run can read its version. */
+export const SKILL_VERSION_FILENAME = '.skill-version.json';
+/** The skill entry file, which also carries the version in its frontmatter. */
+export const SKILL_MARKDOWN_FILENAME = 'SKILL.md';
+const SKILL_CHECK_FILENAME = 'skill-check.json';
+/**
+ * How long one answer stays authoritative, matching the npm update check.
+ *
+ * Declared here rather than imported so `update-check.ts` can depend on this
+ * module and the two never form an import cycle.
+ */
+export const SKILL_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** The same escape hatch the npm update check honours. */
+function checksDisabled(env) {
+    return env?.NUXTSEO_NO_UPDATE_CHECK === '1' || env?.NUXTSEO_NO_UPDATE_CHECK === 'true';
+}
 /**
  * Directories inside the packaged skill that exist for this repository and not
  * for the person installing it. `npm` keeps them out of the tarball through the
@@ -26,6 +43,314 @@ export function skillSourceDirectory(moduleUrl = import.meta.url) {
 export function skillDestination(homeDirectory, agent) {
     return join(homeDirectory, AGENT_DIRECTORIES[agent], 'skills', SKILL_NAME);
 }
+/**
+ * The install target, followed through a symlink.
+ *
+ * People keep their skills in one directory and link each agent's skill folder
+ * at it. `fs.cp` lstats the target, sees a link rather than a directory, and
+ * refuses with `ERR_FS_CP_DIR_TO_NON_DIR` before it copies anything. That
+ * reported as a permission problem on a directory the user owned and could
+ * write. Follow the link first so the copy writes where the person pointed it.
+ */
+export async function resolveSkillTarget(destination) {
+    return await realpath(destination).catch(() => {
+        // Nothing installed yet, so there is no link to follow. Create the literal path.
+        return destination;
+    });
+}
+/** An errno or Node error as a person can act on it: code, call, and path. */
+export function describeIoCause(cause) {
+    if (!cause || typeof cause !== 'object')
+        return String(cause);
+    const error = cause;
+    const parts = [
+        typeof error.code === 'string' ? error.code : undefined,
+        typeof error.syscall === 'string' ? `during ${error.syscall}` : undefined,
+        typeof error.path === 'string' ? `on ${error.path}` : undefined,
+        typeof error.dest === 'string' ? `to ${error.dest}` : undefined,
+    ].filter((part) => part !== undefined);
+    if (parts.length > 0)
+        return parts.join(' ');
+    return typeof error.message === 'string' ? error.message : String(cause);
+}
+async function collectSkillFiles(root, directory = root) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const collected = [];
+    for (const entry of entries) {
+        const source = join(directory, entry.name);
+        const path = relative(root, source);
+        const [segment] = path.split('/');
+        if (segment && SKILL_LOCAL_ONLY.has(segment))
+            continue;
+        if (entry.isDirectory())
+            collected.push(...await collectSkillFiles(root, source));
+        else if (entry.isFile())
+            collected.push({ path, source });
+    }
+    return collected;
+}
+/**
+ * Write the running version into the skill frontmatter.
+ *
+ * An agent reads `SKILL.md` and nothing else, so the file has to say which
+ * release it came from. Without it a skill from an older CLI hides every
+ * command added since, and the agent cannot tell.
+ */
+export function stampSkillVersion(markdown, version) {
+    const stamp = `version: ${version}`;
+    const lines = markdown.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return `---\n${stamp}\n---\n\n${markdown}`;
+    const closing = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (closing === -1)
+        return `---\n${stamp}\n---\n\n${markdown}`;
+    const block = lines.slice(1, closing).filter(line => !/^version\s*:/.test(line));
+    return [lines[0], ...block, stamp, ...lines.slice(closing)].join('\n');
+}
+/** The version recorded in a `SKILL.md` frontmatter, when it carries one. */
+export function frontmatterVersion(markdown) {
+    const lines = markdown.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return null;
+    const closing = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (closing === -1)
+        return null;
+    for (const line of lines.slice(1, closing)) {
+        const match = /^version\s*:\s*(\S+)\s*$/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function parseVersionStamp(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt stamp is disposable state; the frontmatter answers instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const version = value.version;
+    return typeof version === 'string' && version ? version : null;
+}
+/**
+ * The file manifest a previous install recorded in its stamp.
+ *
+ * Pruning may only ever touch paths this tool wrote itself. A stamp without a
+ * readable manifest (a hand copy, an older release, a mangled file) therefore
+ * parses as `null`, and `pruneRemoved` deletes nothing rather than guessing.
+ */
+function parseInstallManifest(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // Same deal as a corrupt version stamp: never prune on a guess.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const files = value.files;
+    if (!Array.isArray(files))
+        return null;
+    const manifest = new Set();
+    for (const file of files) {
+        if (typeof file !== 'string' || !file)
+            return null;
+        manifest.add(file);
+    }
+    return manifest;
+}
+async function readInstallManifest(destination) {
+    const content = await readFile(join(destination, SKILL_VERSION_FILENAME), 'utf8').catch(() => {
+        // No stamp: nothing was ever recorded, so nothing may be pruned.
+        return null;
+    });
+    return content === null ? null : parseInstallManifest(content);
+}
+/**
+ * Which version of the skill sits in a destination directory.
+ *
+ * Reads the stamp first, then the frontmatter, so a skill installed by hand or
+ * by an older release still reports something the caller can compare.
+ */
+export async function readInstalledSkill(destination) {
+    const stamp = await readFile(join(destination, SKILL_VERSION_FILENAME), 'utf8').catch(() => {
+        // No stamp means an older install or a hand copy. Fall through to the frontmatter.
+        return null;
+    });
+    const stamped = stamp === null ? null : parseVersionStamp(stamp);
+    if (stamped !== null)
+        return { _tag: 'SkillVersion', version: stamped };
+    const markdown = await readFile(join(destination, SKILL_MARKDOWN_FILENAME), 'utf8').catch(() => {
+        // No entry file means no skill is installed for this agent.
+        return null;
+    });
+    if (markdown === null)
+        return { _tag: 'SkillMissing' };
+    const declared = frontmatterVersion(markdown);
+    return declared === null ? { _tag: 'SkillUnversioned' } : { _tag: 'SkillVersion', version: declared };
+}
+/**
+ * A stale installed skill, or `null` when nothing needs saying.
+ *
+ * An absent skill is not stale: the person may not use one. Any other
+ * difference from the running binary is, in both directions, because the two
+ * describe different command sets.
+ */
+export function skillNoticeFor(installed, current, agent) {
+    if (installed._tag === 'SkillMissing')
+        return null;
+    if (installed._tag === 'SkillUnversioned')
+        return { agent, installed: null, current };
+    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`;
+    return `${installed}, CLI ${notice.current}. Refresh with: nuxtseo skill install --agent ${notice.agent}`;
+}
+export function parseSkillCheckCache(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt cache file is disposable state, not an error: recheck instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    if (typeof record.lastCheckedAt !== 'string' || typeof record.cliVersion !== 'string')
+        return null;
+    if (typeof record.installed !== 'object' || record.installed === null)
+        return null;
+    const installed = {};
+    for (const agent of SKILL_AGENTS) {
+        const entry = record.installed[agent];
+        if (typeof entry === 'string' || entry === null)
+            installed[agent] = entry;
+    }
+    return { lastCheckedAt: record.lastCheckedAt, cliVersion: record.cliVersion, installed };
+}
+/**
+ * Whether the filesystem has to be read again.
+ *
+ * A cache from a different binary is never reusable: the binary version is half
+ * of the comparison, so an upgrade must warn on the very next run.
+ */
+export function skillCheckDue(cache, now, current) {
+    if (!cache || cache.cliVersion !== current)
+        return true;
+    const checkedAt = Date.parse(cache.lastCheckedAt);
+    return Number.isNaN(checkedAt) || now.getTime() - checkedAt >= SKILL_CHECK_INTERVAL_MS;
+}
+function skillCheckFile(paths) {
+    return join(paths.directory, SKILL_CHECK_FILENAME);
+}
+async function readSkillCheckCache(paths) {
+    const content = await readFile(skillCheckFile(paths), 'utf8').catch(() => {
+        // A missing cache file is the common first-run case.
+        return null;
+    });
+    return typeof content === 'string' ? parseSkillCheckCache(content) : null;
+}
+async function writeSkillCheckCache(paths, cache) {
+    // Persisting the cache is best effort. A failed write only costs one extra
+    // directory read on the next run, so the failure is ignorable by design.
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+    await writeFile(skillCheckFile(paths), `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+}
+function noticeFromCache(cache, current) {
+    for (const agent of SKILL_AGENTS) {
+        const version = cache.installed[agent];
+        if (version === undefined)
+            continue;
+        const installed = version === null
+            ? { _tag: 'SkillUnversioned' }
+            : { _tag: 'SkillVersion', version };
+        const notice = skillNoticeFor(installed, current, agent);
+        if (notice)
+            return notice;
+    }
+    return null;
+}
+/**
+ * One line's worth of "your installed skill is not this binary".
+ *
+ * Costs one cached read per day, and nothing at all when the caller disabled
+ * update checks.
+ */
+export async function checkSkillVersion(options) {
+    if (checksDisabled(options.env))
+        return null;
+    const now = options.now?.() ?? new Date();
+    const cache = await readSkillCheckCache(options.paths);
+    if (cache && !skillCheckDue(cache, now, VERSION))
+        return noticeFromCache(cache, VERSION);
+    const homeDirectory = options.homeDirectory ?? dirname(options.paths.directory);
+    const installed = {};
+    let notice = null;
+    for (const agent of SKILL_AGENTS) {
+        const destination = await resolveSkillTarget(skillDestination(homeDirectory, agent));
+        const state = await readInstalledSkill(destination);
+        if (state._tag === 'SkillMissing')
+            continue;
+        installed[agent] = state._tag === 'SkillVersion' ? state.version : null;
+        notice ??= skillNoticeFor(state, VERSION, agent);
+    }
+    await writeSkillCheckCache(options.paths, {
+        lastCheckedAt: now.toISOString(),
+        cliVersion: VERSION,
+        installed,
+    });
+    return notice;
+}
+function sourceFailure(source, cause) {
+    return fail(EXIT_CODE.infrastructure, `skill_source_unreadable: Could not read the packaged skill at ${source}.\nCause: ${describeIoCause(cause)}.\nReinstall @nuxtseo/cli, then run the command again.`, cause);
+}
+function destinationFailure(destination, cause) {
+    return fail(EXIT_CODE.infrastructure, `skill_install_failed: Could not write the skill to ${destination}.\nCause: ${describeIoCause(cause)}.\nRead the cause above, repair that path, then run the command again.`, cause);
+}
+/**
+ * Remove installed files the previous install recorded and this release no
+ * longer ships.
+ *
+ * A plain recursive copy only adds. A reference file dropped from the package
+ * stays in the install forever and keeps answering an agent that asks for it.
+ * The prune set is the previous stamp's manifest, nothing more: a file the
+ * install never wrote (or cannot prove it wrote) belongs to the person, and
+ * deleting it would destroy data this package never shipped.
+ */
+async function pruneRemoved(destination, keep, recorded) {
+    if (!recorded)
+        return 0;
+    const existing = await collectSkillFiles(destination).catch(() => {
+        // A fresh install has nothing to prune.
+        return [];
+    });
+    let pruned = 0;
+    for (const entry of existing) {
+        if (keep.has(entry.path) || !recorded.has(entry.path))
+            continue;
+        await rm(entry.source, { force: true });
+        pruned += 1;
+    }
+    return pruned;
+}
 export async function installSkill(options) {
     const source = options.sourceDirectory ?? skillSourceDirectory();
     const readable = await stat(source).catch(() => {
@@ -36,21 +361,53 @@ export async function installSkill(options) {
     if (!readable?.isDirectory()) {
         return fail(EXIT_CODE.infrastructure, `skill_source_missing: The packaged skill is missing at ${source}.\nReinstall @nuxtseo/cli, then run the command again.`);
     }
+    const files = await collectSkillFiles(source).catch((cause) => cause);
+    if (!Array.isArray(files))
+        return sourceFailure(source, files);
     const destination = options.target
         ? join(options.target, SKILL_NAME)
         : skillDestination(options.homeDirectory, options.agent);
-    const written = await mkdir(dirname(destination), { recursive: true })
-        .then(() => cp(source, destination, {
-        recursive: true,
-        force: true,
-        filter: (entry) => {
-            const [segment] = relative(source, entry).split('/');
-            return !segment || !SKILL_LOCAL_ONLY.has(segment);
-        },
-    }))
-        .then(() => ok(undefined))
-        .catch(cause => fail(EXIT_CODE.infrastructure, `skill_install_failed: Could not write the skill to ${destination}.\nCheck the directory permissions, then run the command again.`, cause));
-    if (written._tag === 'Err')
-        return written;
-    return ok({ agent: options.agent, source, destination });
+    const resolvedDestination = await resolveSkillTarget(destination);
+    // Read before the stamp is overwritten: the previous install's manifest is
+    // the only proof of what a prune may touch.
+    const previous = await readInstallManifest(resolvedDestination);
+    const keep = new Set([SKILL_VERSION_FILENAME]);
+    const write = async () => {
+        await mkdir(resolvedDestination, { recursive: true });
+        for (const file of files) {
+            const target = join(resolvedDestination, file.path);
+            await mkdir(dirname(target), { recursive: true });
+            if (file.path === SKILL_MARKDOWN_FILENAME)
+                await writeFile(target, stampSkillVersion(await readFile(file.source, 'utf8'), VERSION), 'utf8');
+            else
+                await copyFile(file.source, target);
+            keep.add(file.path);
+        }
+        await writeFile(join(resolvedDestination, SKILL_VERSION_FILENAME), `${JSON.stringify({ version: VERSION, skill: SKILL_NAME, installedAt: new Date().toISOString(), files: [...keep].sort() }, null, 2)}\n`, 'utf8');
+        return await pruneRemoved(resolvedDestination, keep, previous);
+    };
+    const result = await write().then(pruned => ok(pruned)).catch(cause => destinationFailure(resolvedDestination, cause));
+    if (result._tag === 'Err')
+        return result;
+    if (options.paths) {
+        // The freshly installed version is now the answer, so clear the stale
+        // notice the same run rather than a day later. Merge into the recorded
+        // map: another agent's entry still has to answer for its own skill, and
+        // replacing the map would hide its stale warning until the cache expires.
+        const cached = await readSkillCheckCache(options.paths);
+        await writeSkillCheckCache(options.paths, {
+            lastCheckedAt: new Date().toISOString(),
+            cliVersion: VERSION,
+            installed: { ...cached?.installed, [options.agent]: VERSION },
+        });
+    }
+    return ok({
+        agent: options.agent,
+        source,
+        destination,
+        resolvedDestination,
+        version: VERSION,
+        written: files.length,
+        pruned: result.value,
+    });
 }

package/dist/state/auth.js

@@ -65,7 +65,7 @@ function keyringFailure(operation, paths, cause) {
         _tag: 'KeychainFailure',
         operation,
         path: paths.authFile,
-        message: `Could not ${operation} the NuxtSEO credential in the OS keychain. Local auth state is recorded at ${paths.authFile}.`,
+        message: `Could not ${operation} the Nuxt SEO credential in the OS keychain. Local auth state is recorded at ${paths.authFile}.`,
         cause,
     });
 }
@@ -148,7 +148,7 @@ export async function saveCredential(value, options = {}) {
         return err({
             _tag: 'InvalidCredential',
             source: 'input',
-            message: 'The NuxtSEO API token cannot be empty.',
+            message: 'The Nuxt SEO API token cannot be empty.',
         });
     }
     const paths = options.paths ?? defaultStatePaths();

package/dist/state/files.js

@@ -19,7 +19,7 @@ function statePath(paths, kind) {
 function corruptState(kind, path, detail, cause) {
     const common = {
         path,
-        message: `Could not parse NuxtSEO ${kind} state at ${path}: ${detail}`,
+        message: `Could not parse Nuxt SEO ${kind} state at ${path}: ${detail}`,
         ...(cause === undefined ? {} : { cause }),
     };
     return kind === 'auth'
@@ -37,7 +37,7 @@ export async function readStateJson(paths, kind) {
             kind,
             operation: 'read',
             path,
-            message: `Could not read NuxtSEO ${kind} state at ${path}.`,
+            message: `Could not read Nuxt SEO ${kind} state at ${path}.`,
             cause: content,
         });
     }
@@ -76,7 +76,7 @@ export async function writeStateJson(paths, kind, value) {
             kind,
             operation: 'write',
             path,
-            message: `Could not write NuxtSEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
+            message: `Could not write Nuxt SEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
             cause,
         }
         : {
@@ -84,7 +84,7 @@ export async function writeStateJson(paths, kind, value) {
             kind,
             operation: 'write',
             path,
-            message: `Could not write NuxtSEO ${kind} state at ${path}.`,
+            message: `Could not write Nuxt SEO ${kind} state at ${path}.`,
             cause,
         }));
     if (written._tag === 'Err' && temporaryCreated) {
@@ -110,7 +110,7 @@ export async function removeStateFile(paths, kind) {
                 kind,
                 operation: 'delete',
                 path,
-                message: `Could not remove NuxtSEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
+                message: `Could not remove Nuxt SEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
                 cause,
             }
             : {
@@ -118,7 +118,7 @@ export async function removeStateFile(paths, kind) {
                 kind,
                 operation: 'delete',
                 path,
-                message: `Could not remove NuxtSEO ${kind} state at ${path}.`,
+                message: `Could not remove Nuxt SEO ${kind} state at ${path}.`,
                 cause,
             });
     });

package/dist/update-check.d.ts

@@ -15,6 +15,11 @@ export interface UpdateCheckOptions {
     env?: Readonly<Record<string, string | undefined>>;
     fetch?: RegistryLatestFetch;
     now?: () => Date;
+    /**
+     * Receives one diagnostic line per stale local artefact, before this check
+     * resolves. The caller owns the stream, so this module never writes to one.
+     */
+    onDiagnostic?: (line: string) => void;
 }
 export declare function isNewerVersion(candidate: string, current: string): boolean;
 export declare function updateNoticeFor(latest: string | null, current: string): UpdateNotice | null;