@detergent-software/atk 9.0.0-dev.2 → 9.0.0-dev.3

package/build/lib/diagnostics.js

@@ -1,20 +1,81 @@
 import { existsSync } from 'node:fs';
-import { adapterForScope, loadAdapter } from './adapter.js';
-import { resolveApiUrl } from './api-client.js';
-import { isExcludedAtVersion, isExcludedForTool, isExcludedForTools, isUndeclaredForTool } from './asset-tools.js';
-import { getCredential, getLastEntraSession, validateToken } from './auth.js';
+import { gt as semverGt, valid as semverValid } from 'semver';
+import { z } from 'zod';
+import { adapterAsPlaced, adapterForScope, loadAdapter, resolveInstalledPaths } from './adapter.js';
+import { getAtkForToken, resolveApiUrl } from './api-client.js';
+import { declarationAllows, isExcludedAtVersion, isExcludedForTool, isExcludedForTools, isUndeclaredForTool, } from './asset-tools.js';
+import { isAtkError } from './atk-api/index.js';
+import { getCredential, getLastEntraSession, getTokenExpiry } from './auth.js';
 import { isFrozenInConfig, loadConfig } from './config.js';
 import { crossScopeInstall, describeClashes } from './cross-scope.js';
 import { detectTools, getAdapterDiagnostics } from './detector.js';
 import { getEntraCachePath } from './entra.js';
-import { errorMessage } from './errors.js';
+import { errorGuidance, errorMessage } from './errors.js';
+import { formatAge } from './format-age.js';
 import { hookScriptPath, lacksExecBit } from './hook-script.js';
 import { identityKey, lockfileExists, readLockfile } from './lockfile.js';
 import { isOffline } from './offline.js';
 import { formatOrgName } from './org.js';
-import { fetchRegistry, versionTools } from './registry.js';
+import { fetchRegistry, getCacheStatus, isCacheReadable, isDeprecated, versionTools } from './registry.js';
 import { fromRoot } from './root-path.js';
 import { loadScopeConfig, resolveScope, resolveUserRoot, scopedCommand } from './scope.js';
+import { getVersionStatus } from './update-check.js';
+import { CLI_VERSION, isPreRelease, upgradeCommand } from './version.js';
+/** How long the `/health` probe waits for the ATK API before it fails the check. */
+export const HEALTH_TIMEOUT_MS = 5_000;
+const HealthBodySchema = z.object({
+    environment: z.string().optional(),
+    status: z.string(),
+    version: z.string().optional(),
+});
+/**
+ * Call the ATK API's anonymous `GET /health` once, with no bearer and no retries, so a down API
+ * fails the check in {@link HEALTH_TIMEOUT_MS} at most. It doesn't go through the process-wide
+ * client, whose connection-failure latch would then fail the registry check too.
+ */
+export async function checkApiHealth(apiUrl, source) {
+    const id = 'api';
+    const name = 'ATK API';
+    const url = `${apiUrl.replace(/\/+$/, '')}/health`;
+    const advice = source ? `${source}. Check that URL and your network connection.` : 'Check your network connection.';
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            headers: { accept: 'application/json', 'X-Atk-Cli-Version': CLI_VERSION },
+            signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        const timedOut = err instanceof Error && err.name === 'TimeoutError';
+        return {
+            detail: advice,
+            id,
+            message: timedOut
+                ? `${url} did not answer within ${HEALTH_TIMEOUT_MS / 1000}s`
+                : `Couldn't reach ${url}: ${describeFetchFailure(err)}`,
+            name,
+            status: 'fail',
+        };
+    }
+    const body = HealthBodySchema.safeParse(await response.json().catch(() => undefined));
+    if (!response.ok || !body.success || body.data.status !== 'ok') {
+        return {
+            detail: advice,
+            id,
+            message: `${url} answered HTTP ${response.status}${body.success ? ` (status: ${body.data.status})` : ''}`,
+            name,
+            status: 'fail',
+        };
+    }
+    const about = [body.data.environment, body.data.version].filter(Boolean).join(', ');
+    return {
+        ...(source ? { detail: source } : {}),
+        id,
+        message: about ? `${apiUrl} (${about})` : apiUrl,
+        name,
+        status: 'pass',
+    };
+}
 /**
  * Check for assets installed both in the project and at the user scope, with the version at each and
  * which copy each tool that has both uses. A copy uninstalled for every tool of its scope doesn't
@@ -39,11 +100,79 @@ export async function checkBothScopes(project, user) {
     const one = lines.length === 1;
     return {
         detail: `${lines.join('; ')}. Run \`atk uninstall <name> --type <type>\` (with \`--org <org>\` for an org asset), adding \`--user\` for the user copy, to keep one copy.`,
+        id: 'both-scopes',
         message: `${lines.length} asset${one ? ' is' : 's are'} installed at both scopes`,
         name: 'Both scopes',
         status: 'warn',
     };
 }
+/**
+ * Compare this CLI with its release channel on npm: `dev` for a prerelease, `latest` otherwise.
+ * A CLI ahead of npm (a local build) passes. `offline` (`--offline`): npm isn't asked, so only
+ * a cached version is compared.
+ */
+export function checkCliVersion(status, offline = false) {
+    const { channel, currentVersion, enabled, latestVersion } = status;
+    const id = 'cli-version';
+    const name = 'CLI version';
+    if (!enabled) {
+        return {
+            detail: 'Not compared with npm: checkUpdates is false in the config.',
+            id,
+            message: `v${currentVersion}`,
+            name,
+            status: 'pass',
+        };
+    }
+    if (!latestVersion || !semverValid(latestVersion) || !semverValid(currentVersion)) {
+        return {
+            ...(offline ? {} : { detail: 'Check your network connection and run `atk doctor` again.' }),
+            id,
+            message: offline
+                ? `v${currentVersion} (not compared with npm with --offline)`
+                : `v${currentVersion} (couldn't read the npm ${channel} version)`,
+            name,
+            status: 'warn',
+        };
+    }
+    if (semverGt(latestVersion, currentVersion)) {
+        const command = upgradeCommand(channel);
+        return {
+            command,
+            detail: `Run \`${command}\` to update.`,
+            id,
+            message: `v${currentVersion} (v${latestVersion} is on npm ${channel})`,
+            name,
+            status: 'warn',
+        };
+    }
+    return { id, message: `v${currentVersion} (current on npm ${channel})`, name, status: 'pass' };
+}
+/**
+ * Check for installed assets the registry deprecates, with each one's reason and replacement.
+ * Returns undefined when there are none.
+ */
+export function checkDeprecated(registry, assets) {
+    const lines = [];
+    for (const asset of assets) {
+        const deprecation = isDeprecated(registry, asset.name, asset.type, asset.org);
+        if (!deprecation.deprecated)
+            continue;
+        const reason = deprecation.reason ? `: ${deprecation.reason}` : '';
+        const replacement = deprecation.replacement ? ` (use ${deprecation.replacement})` : '';
+        lines.push(`${formatOrgName(asset.org, asset.name)} (${asset.type})${reason}${replacement}`);
+    }
+    if (lines.length === 0)
+        return undefined;
+    const one = lines.length === 1;
+    return {
+        detail: `${lines.join('; ')}. Install the replacement, then remove the deprecated asset with \`atk uninstall <name> --type <type>\`.`,
+        id: 'deprecated',
+        message: `${lines.length} installed asset${one ? ' is' : 's are'} deprecated`,
+        name: 'Deprecated assets',
+        status: 'warn',
+    };
+}
 /**
  * Check that the hook scripts a configured tool runs directly are executable. Returns
  * undefined when there is nothing to check: on Windows, which has no exec bit, or when
@@ -60,7 +189,7 @@ export async function checkHookScripts(projectDir, tools, assets, platform = pro
             adapter = adapterForScope(await loadAdapter(tool), scope ?? 'project', projectDir);
         }
         catch {
-            // The Adapters check already reports adapters that fail to load.
+            // The tool's adapter check already reports adapters that fail to load.
             continue;
         }
         for (const asset of assets) {
@@ -82,13 +211,17 @@ export async function checkHookScripts(projectDir, tools, assets, platform = pro
     }
     if (notExecutable.length === 0) {
         return {
+            id: 'hook-scripts',
             message: `${scripts.size} hook script${scripts.size === 1 ? '' : 's'} executable`,
             name: 'Hook scripts',
             status: 'pass',
         };
     }
+    const sync = scopedCommand('atk sync', scope);
     return {
-        detail: `${notExecutable.join(', ')}. Run \`${scopedCommand('atk sync', scope)}\` to reinstall them, or \`chmod +x\` the script of a frozen asset.`,
+        command: sync,
+        detail: `${notExecutable.join(', ')}. Run \`${sync}\` to reinstall them, or \`chmod +x\` the script of a frozen asset.`,
+        id: 'hook-scripts',
         message: `${notExecutable.length} hook script${notExecutable.length === 1 ? ' is' : 's are'} not executable`,
         name: 'Hook scripts',
         status: 'warn',
@@ -115,13 +248,73 @@ export function checkLiftedHooks(projectConfig, assets, registry, scope) {
     if (lifted.length === 0)
         return undefined;
     const one = lifted.length === 1;
+    const sync = scopedCommand('atk sync', scope);
     return {
-        detail: `${lifted.join(', ')}. ${one ? 'Its locked version now declares that tool' : 'Their locked versions now declare those tools'}. Run \`${scopedCommand('atk sync', scope)}\` to place ${one ? 'it' : 'them'}.`,
+        command: sync,
+        detail: `${lifted.join(', ')}. ${one ? 'Its locked version now declares that tool' : 'Their locked versions now declare those tools'}. Run \`${sync}\` to place ${one ? 'it' : 'them'}.`,
+        id: 'hooks-to-place',
         message: `${lifted.length} hook${one ? ' is' : 's are'} not placed yet`,
         name: 'Hooks to place',
         status: 'warn',
     };
 }
+/**
+ * Check that each installed asset's placed files are on disk for every configured tool, as the
+ * scope's adapter places them. Frozen assets, those uninstalled for a tool and hooks whose locked
+ * version doesn't declare the tool (with `registry`) are left out, as `atk audit` and `atk sync`
+ * leave them. Only presence is checked; `atk audit` verifies content. Returns undefined when there
+ * is nothing to check. The sync command it suggests runs in `scope`.
+ */
+export async function checkMissingFiles(root, tools, assets, projectConfig, scope, registry) {
+    const missing = [];
+    let checked = 0;
+    for (const tool of tools) {
+        let adapter;
+        try {
+            adapter = adapterForScope(await loadAdapter(tool), scope ?? 'project', root);
+        }
+        catch {
+            // The tool's adapter check reports it.
+            continue;
+        }
+        for (const asset of assets) {
+            if (isExcludedForTool(asset, tool))
+                continue;
+            if (isFrozenInConfig(projectConfig, asset.name, asset.type, asset.org))
+                continue;
+            const lockedTools = registry && asset.type === 'hook' ? versionTools(registry, asset, asset.version) : null;
+            if (isExcludedAtVersion(asset, tool, lockedTools) ||
+                !declarationAllows(asset.type, lockedTools ?? undefined, tool)) {
+                continue;
+            }
+            const { files } = resolveInstalledPaths(asset, adapterAsPlaced(adapter, asset), root);
+            checked += 1;
+            if (files.some((f) => !existsSync(fromRoot(root, f.installedPath)))) {
+                missing.push(`${formatOrgName(asset.org, asset.name)} (${asset.type}, ${tool})`);
+            }
+        }
+    }
+    if (checked === 0)
+        return undefined;
+    if (missing.length === 0) {
+        return {
+            id: 'missing-files',
+            message: `Every installed asset's files are in place`,
+            name: 'Placed files',
+            status: 'pass',
+        };
+    }
+    const one = missing.length === 1;
+    const sync = scopedCommand('atk sync', scope);
+    return {
+        command: sync,
+        detail: `${missing.join(', ')}. Run \`${sync}\` to place ${one ? 'it' : 'them'} again.`,
+        id: 'missing-files',
+        message: `${missing.length} installed asset${one ? ' is' : 's are'} missing files`,
+        name: 'Placed files',
+        status: 'warn',
+    };
+}
 /**
  * Check whether the given Node.js version string meets the project requirements.
  *
@@ -132,6 +325,7 @@ export function checkNodeVersion(version) {
     const nodeMajor = parseInt(version.slice(1), 10);
     if (nodeMajor >= 24) {
         return {
+            id: 'node',
             message: `${version} (recommended)`,
             name: 'Node.js',
             status: 'pass',
@@ -139,6 +333,7 @@ export function checkNodeVersion(version) {
     }
     else if (nodeMajor >= 20) {
         return {
+            id: 'node',
             message: `${version} (Node 24+ recommended)`,
             name: 'Node.js',
             status: 'warn',
@@ -146,12 +341,49 @@ export function checkNodeVersion(version) {
     }
     else {
         return {
+            id: 'node',
             message: `${version} (Node 20+ required, 24+ recommended)`,
             name: 'Node.js',
             status: 'fail',
         };
     }
 }
+/**
+ * Check the registry cache file: its age against the TTL, and whether it parses. An expired cache
+ * passes (the next read refreshes it); one that doesn't parse fails, with `atk cache clear` to
+ * remove it. Run after the registry check, which replaces an unreadable cache when it can fetch.
+ */
+export async function checkRegistryCache() {
+    const id = 'cache';
+    const name = 'Registry cache';
+    try {
+        const status = await getCacheStatus();
+        if (!status.exists) {
+            return { detail: status.path, id, message: 'No cached registry yet', name, status: 'pass' };
+        }
+        if ((await isCacheReadable()) === false) {
+            return {
+                command: 'atk cache clear',
+                detail: `${status.path}. Run \`atk cache clear\` to remove it; the next command fetches a fresh copy.`,
+                id,
+                message: 'The cached registry does not parse',
+                name,
+                status: 'fail',
+            };
+        }
+        const expired = status.expired ? ', expired: the next read refreshes it' : '';
+        return {
+            detail: status.path,
+            id,
+            message: `${formatAge(status.ageMs)} old (TTL ${status.ttlMinutes}m${expired})`,
+            name,
+            status: 'pass',
+        };
+    }
+    catch (err) {
+        return { id, message: errorMessage(err), name, status: 'warn' };
+    }
+}
 /**
  * Run all environment diagnostic checks and return the results.
  * Extracted from the `doctor` command so it can be tested independently.
@@ -172,6 +404,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     try {
         config = await loadConfig();
         checks.push({
+            id: 'config',
             message: 'Loaded',
             name: 'Config',
             status: 'pass',
@@ -179,49 +412,69 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     catch (err) {
         checks.push({
+            id: 'config',
             message: errorMessage(err),
             name: 'Config',
             status: 'fail',
         });
     }
-    // Report the ATK API the CLI will talk to
-    progress('Resolving ATK API...');
+    // Call the ATK API the CLI will talk to (not offline: that is the one thing --offline rules out)
+    progress('Checking the ATK API...');
     const apiUrl = resolveApiUrl(config);
-    checks.push({
-        detail: process.env['ATK_API_URL'] ? 'From ATK_API_URL' : config?.apiUrl ? 'From apiUrl in config' : undefined,
-        message: apiUrl,
-        name: 'ATK API',
-        status: 'pass',
-    });
-    // Check authentication against the ATK API (not offline: validating the credential is an API call)
+    const apiSource = process.env['ATK_API_URL']
+        ? 'From ATK_API_URL'
+        : config?.apiUrl
+            ? 'From apiUrl in config'
+            : undefined;
+    const apiCheck = isOffline()
+        ? {
+            ...(apiSource ? { detail: apiSource } : {}),
+            id: 'api',
+            message: `${apiUrl} (not checked with --offline)`,
+            name: 'ATK API',
+            status: 'warn',
+        }
+        : await checkApiHealth(apiUrl, apiSource);
+    checks.push(apiCheck);
+    progress('Checking the CLI version...');
+    checks.push(checkCliVersion(await getVersionStatus(), isOffline()));
+    // Check authentication against the ATK API (not offline: validating the credential is an API call).
+    // With the API down, a validation would read as a rejected credential and send --fix to sign in again.
     progress('Checking authentication...');
     checks.push(isOffline()
-        ? { message: 'Not checked with --offline', name: 'Authentication', status: 'warn' }
-        : await checkAuthentication());
-    // Check registry access
+        ? { id: 'auth', message: 'Not checked with --offline', name: 'Authentication', status: 'warn' }
+        : await checkAuthentication(apiUrl, apiCheck.status !== 'fail'));
+    // Check registry access, through the cache as every command reads it (offline, the cache of any age)
     progress('Checking registry access...');
+    const servedFromCache = isOffline() || (await cacheWillServe());
     let registry;
     try {
-        registry = await fetchRegistry({ force: true });
+        registry = isOffline() ? await fetchRegistry({ stale: true }) : await fetchRegistry();
         checks.push({
-            message: `Accessible (${registry.assets.length} assets, ${(registry.bundles ?? []).length} bundles)`,
+            id: 'registry',
+            message: `Accessible (${registry.assets.length} assets, ${(registry.bundles ?? []).length} bundles; ${servedFromCache ? 'from the cache' : 'fetched from the ATK API'})`,
             name: 'Registry',
             status: 'pass',
         });
     }
     catch (err) {
         checks.push({
+            id: 'registry',
             message: errorMessage(err),
             name: 'Registry',
             status: 'fail',
         });
     }
+    progress('Checking the registry cache...');
+    checks.push(await checkRegistryCache());
     // Check tool detection
     progress('Detecting tools...');
     const detectedTools = await detectTools(projectDir);
+    const setup = scopedCommand('atk setup', scope);
     if (detectedTools.length > 0) {
         const toolNames = detectedTools.map((t) => `${t.displayName} (${t.confidence})`).join(', ');
         checks.push({
+            id: 'tools',
             message: toolNames,
             name: 'Tool detection',
             status: 'pass',
@@ -229,8 +482,9 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     else {
         checks.push({
-            detail: 'Use --tool flag or run from a project with a supported tool.',
-            message: 'No agentic tool detected in current directory',
+            detail: `Run atk from a project that uses a supported tool, or run \`${setup}\` to choose one.`,
+            id: 'tools',
+            message: `No agentic tool detected in ${scope === 'user' ? 'the user root' : 'the project'}`,
             name: 'Tool detection',
             status: 'warn',
         });
@@ -240,6 +494,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     const adapterDiag = await getAdapterDiagnostics();
     if (!adapterDiag.directoryExists) {
         checks.push({
+            id: 'adapters',
             message: `Adapters directory not found at: ${adapterDiag.adaptersDir}`,
             name: 'Adapters',
             status: 'warn',
@@ -249,6 +504,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
         const failDetails = adapterDiag.failures.map((f) => `${f.filename}: ${f.reason}`).join('; ');
         checks.push({
             detail: failDetails,
+            id: 'adapters',
             message: `${adapterDiag.failures.length} adapter(s) failed to load`,
             name: 'Adapters',
             status: 'warn',
@@ -256,6 +512,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     else {
         checks.push({
+            id: 'adapters',
             message: `${adapterDiag.adaptersLoaded} adapter(s) loaded`,
             name: 'Adapters',
             status: 'pass',
@@ -269,7 +526,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     // Check the scope's config: the project's .atkrc.json, or the user scope's tools in the user config
     const configName = scope === 'user' ? 'User scope config' : 'Project config';
-    const setup = scopedCommand('atk setup', scope);
+    const configId = scope === 'user' ? 'user-scope-config' : 'project-config';
     const setupDetail = `Run \`${setup}\` to initialize ${configName.toLowerCase()}.`;
     progress(`Checking ${configName.toLowerCase()}...`);
     let configuredTools = [];
@@ -279,6 +536,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
         if (projectConfig) {
             configuredTools = projectConfig.tools;
             checks.push({
+                id: configId,
                 message: projectConfig.tools.length === 0
                     ? 'Loaded (no tools configured)'
                     : `Loaded (tools: ${projectConfig.tools.join(', ')})`,
@@ -288,7 +546,9 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
         }
         else {
             checks.push({
+                command: setup,
                 detail: setupDetail,
+                id: configId,
                 message: `No ${configName.toLowerCase()} found`,
                 name: configName,
                 status: 'warn',
@@ -297,18 +557,27 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     catch (err) {
         checks.push({
+            command: setup,
             detail: setupDetail,
+            id: configId,
             message: errorMessage(err),
             name: configName,
             status: 'warn',
         });
     }
+    // Each configured tool's adapter: the one the scope's commands place with
+    progress('Checking configured tools...');
+    for (const tool of configuredTools) {
+        checks.push(await checkToolAdapter(tool, projectDir));
+    }
     // Check lockfile
     progress('Checking lockfile...');
     let installedAssets = [];
     if (!lockfileExists(projectDir)) {
         checks.push({
+            command: setup,
             detail: `Run \`${setup}\` to initialize`,
+            id: 'lockfile',
             message: 'No lockfile found',
             name: 'Lockfile',
             status: 'warn',
@@ -320,6 +589,7 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
             installedAssets = lockfile.assets ?? [];
             const assetCount = installedAssets.length;
             checks.push({
+                id: 'lockfile',
                 message: `Found .atk-lock.json (${assetCount} asset${assetCount === 1 ? '' : 's'})`,
                 name: 'Lockfile',
                 status: 'pass',
@@ -327,21 +597,25 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
         }
         catch (err) {
             checks.push({
+                command: setup,
                 detail: `Run \`${setup}\` to re-initialize`,
+                id: 'lockfile',
                 message: errorMessage(err),
                 name: 'Lockfile',
                 status: 'warn',
             });
         }
     }
+    progress('Checking placed files...');
+    const missingFiles = await checkMissingFiles(projectDir, configuredTools, installedAssets, projectConfig, scope, registry);
+    const deprecated = registry && checkDeprecated(registry, installedAssets);
     progress('Checking hook scripts...');
     const hookScripts = await checkHookScripts(projectDir, configuredTools, installedAssets, process.platform, scope);
-    if (hookScripts) {
-        checks.push(hookScripts);
-    }
     const liftedHooks = registry && projectConfig && checkLiftedHooks(projectConfig, installedAssets, registry, scope);
-    if (liftedHooks) {
-        checks.push(liftedHooks);
+    for (const check of [missingFiles, deprecated, hookScripts, liftedHooks]) {
+        if (check) {
+            checks.push(check);
+        }
     }
     // In a project, the user scope's installs sit beside the project's, so check them too
     if (scope === 'project') {
@@ -353,6 +627,29 @@ export async function runDiagnostics(progress, { projectRoot, user } = {}) {
     }
     return checks;
 }
+/** Whether the next registry read is served from the cache: a cache within its TTL that parses. */
+async function cacheWillServe() {
+    try {
+        const status = await getCacheStatus();
+        return status.exists && !status.expired && (await isCacheReadable()) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** One configured tool's adapter: whether it loads, with setup's command when it doesn't. */
+async function checkToolAdapter(tool, root) {
+    const id = `adapter-${tool}`;
+    const name = `Adapter: ${tool}`;
+    try {
+        const adapter = await loadAdapter(tool, root);
+        return { id, message: `Loaded (${adapter.displayName})`, name, status: 'pass' };
+    }
+    catch (err) {
+        const { command } = errorGuidance(err);
+        return { ...(command ? { command } : {}), id, message: errorMessage(err), name, status: 'fail' };
+    }
+}
 /**
  * Report the user root: its path, where it comes from (`ATK_USER_ROOT`, the `userRoot` config key
  * or the home directory), and a warning when it doesn't exist. `root` is set when it can be checked.
@@ -363,7 +660,7 @@ async function checkUserRoot(config) {
         root = await resolveUserRoot();
     }
     catch (err) {
-        return { check: { message: errorMessage(err), name: 'User root', status: 'warn' } };
+        return { check: { id: 'user-root', message: errorMessage(err), name: 'User root', status: 'warn' } };
     }
     const source = process.env['ATK_USER_ROOT']
         ? 'From ATK_USER_ROOT'
@@ -374,13 +671,14 @@ async function checkUserRoot(config) {
         return {
             check: {
                 detail: `${source}. Create it, or point ATK_USER_ROOT or the userRoot config key at an existing directory.`,
+                id: 'user-root',
                 message: `${root} does not exist`,
                 name: 'User root',
                 status: 'warn',
             },
         };
     }
-    return { check: { detail: source, message: root, name: 'User root', status: 'pass' }, root };
+    return { check: { detail: source, id: 'user-root', message: root, name: 'User root', status: 'pass' }, root };
 }
 /**
  * The user scope's checks for a project's doctor run: its config (tools), its lockfile, its hooks,
@@ -394,6 +692,7 @@ async function checkUserScope(userRoot, registry, project) {
         userConfig = await loadScopeConfig(userRoot);
         checks.push(userConfig
             ? {
+                id: 'user-scope-config',
                 message: userConfig.tools.length === 0
                     ? 'Loaded (no tools configured)'
                     : `Loaded (tools: ${userConfig.tools.join(', ')})`,
@@ -402,6 +701,7 @@ async function checkUserScope(userRoot, registry, project) {
             }
             : {
                 detail: 'Run `atk setup --user` to install assets at the user scope.',
+                id: 'user-scope-config',
                 message: 'Not set up',
                 name: 'User scope config',
                 status: 'pass',
@@ -409,7 +709,9 @@ async function checkUserScope(userRoot, registry, project) {
     }
     catch (err) {
         checks.push({
+            command: 'atk setup --user',
             detail: 'Run `atk setup --user` to initialize user scope config.',
+            id: 'user-scope-config',
             message: errorMessage(err),
             name: 'User scope config',
             status: 'warn',
@@ -417,12 +719,13 @@ async function checkUserScope(userRoot, registry, project) {
     }
     let userAssets = [];
     if (!lockfileExists(userRoot)) {
-        checks.push({ message: 'None (no user installs)', name: 'User lockfile', status: 'pass' });
+        checks.push({ id: 'user-lockfile', message: 'None (no user installs)', name: 'User lockfile', status: 'pass' });
     }
     else {
         try {
             userAssets = (await readLockfile(userRoot)).assets ?? [];
             checks.push({
+                id: 'user-lockfile',
                 message: `Found .atk-lock.json (${userAssets.length} asset${userAssets.length === 1 ? '' : 's'})`,
                 name: 'User lockfile',
                 status: 'pass',
@@ -430,7 +733,9 @@ async function checkUserScope(userRoot, registry, project) {
         }
         catch (err) {
             checks.push({
+                command: 'atk setup --user',
                 detail: 'Run `atk setup --user` to re-initialize',
+                id: 'user-lockfile',
                 message: errorMessage(err),
                 name: 'User lockfile',
                 status: 'warn',
@@ -442,7 +747,7 @@ async function checkUserScope(userRoot, registry, project) {
     const liftedHooks = registry && userConfig && checkLiftedHooks(userConfig, userAssets, registry, 'user');
     for (const check of [hookScripts, liftedHooks]) {
         if (check) {
-            checks.push({ ...check, name: `User ${check.name.toLowerCase()}` });
+            checks.push({ ...check, id: `user-${check.id}`, name: `User ${check.name.toLowerCase()}` });
         }
     }
     const bothScopes = await checkBothScopes(project, { assets: userAssets, root: userRoot, tools: userTools });
@@ -456,45 +761,123 @@ const SOURCE_LABELS = {
     entra: 'atk login session',
 };
 /**
- * Resolve the credential chain and validate the result against `GET /me`.
- * When the chain is empty but an Entra session file exists, the detail says
- * why the file yielded nothing, since that usually means `atk login` again.
+ * Resolve the credential chain and validate the result against `GET /me` (with exactly that
+ * token, never the process-cached one), with the token's
+ * expiry from its `exp` claim. When the chain is empty but an Entra session file exists, the
+ * detail says why the file yielded nothing, since that usually means `atk login` again. When the
+ * API didn't answer `/health`, the credential is described but not validated, and warns.
  */
-async function checkAuthentication() {
+async function checkAuthentication(apiUrl, apiAnswered) {
+    const id = 'auth';
     const name = 'Authentication';
     let credential;
     try {
         credential = await getCredential();
     }
     catch (err) {
+        const { command } = errorGuidance(err);
+        const session = getLastEntraSession();
+        if (!apiAnswered && session && !session.ok && session.reason === 'error') {
+            return {
+                detail: 'The ATK API check failed too, so this looks like the network rather than the session.',
+                id,
+                message: errorMessage(err),
+                name,
+                status: 'warn',
+            };
+        }
         return {
+            command: command ?? 'atk login',
             detail: staleEntraSessionNote(),
+            id,
             message: errorMessage(err),
             name,
             status: 'fail',
         };
     }
-    const validation = await validateToken(credential.token);
     const source = SOURCE_LABELS[credential.source];
-    if (!validation.valid) {
+    const expiry = describeExpiry(getTokenExpiry(credential.token));
+    if (!apiAnswered) {
         return {
-            detail: credential.source === 'entra'
-                ? 'Run `atk login --force` to sign in again.'
-                : 'Check ATK_TOKEN: it must be a current Entra access token for the ATK API. Unset it to use your `atk login` session.',
-            message: `Credential from ${source} was rejected by the ATK API`,
+            detail: 'The ATK API check failed, so the credential was not validated.',
+            id,
+            message: `Not validated (from ${source}${expiry ? `; token ${expiry}` : ''})`,
             name,
-            status: 'fail',
+            status: 'warn',
         };
     }
-    const principal = validation.principal;
-    const who = principal?.login ?? validation.username ?? 'unknown';
-    const scheme = principal?.scheme ?? 'unknown';
+    let principal;
+    try {
+        principal = await getAtkForToken(credential.token, apiUrl).me();
+    }
+    catch (err) {
+        return describeRefusal(err, credential.source, `${source}${expiry ? ` (${expiry})` : ''}`);
+    }
     return {
-        message: `Signed in as ${who} via ${scheme} (from ${source})`,
+        ...(credential.source === 'entra' && expiry ? { detail: 'The session renews the token on its own.' } : {}),
+        id,
+        message: `Signed in as ${principal.login} via ${principal.scheme} (from ${source}${expiry ? `; token ${expiry}` : ''})`,
         name,
         status: 'pass',
     };
 }
+/** "expires in 52m" or "expired 3h ago"; undefined when the token carries no expiry. */
+function describeExpiry(expiry, now = Date.now()) {
+    if (!expiry)
+        return undefined;
+    const ms = expiry.getTime() - now;
+    return ms > 0 ? `expires in ${formatAge(ms)}` : `expired ${formatAge(-ms)} ago`;
+}
+/** Why a fetch never got a response, by its cause's code (`ECONNREFUSED`, `ENOTFOUND`) when it has one. */
+function describeFetchFailure(err) {
+    const cause = err instanceof Error ? err.cause : undefined;
+    const code = typeof cause === 'object' && cause !== null && 'code' in cause ? cause.code : undefined;
+    return typeof code === 'string' ? code : errorMessage(err);
+}
+/**
+ * Why `GET /me` refused the credential. Only a 401 means the credential itself is bad, so only
+ * then does an Entra session get `atk login --force`: an outdated CLI, a forbidden account or a
+ * server error isn't fixed by signing in again, and `--fix` acts on the command.
+ */
+function describeRefusal(err, credentialSource, from) {
+    const id = 'auth';
+    const name = 'Authentication';
+    if (isAtkError(err, 'unauthenticated')) {
+        return credentialSource === 'entra'
+            ? {
+                command: 'atk login --force',
+                detail: 'Run `atk login --force` to sign in again.',
+                id,
+                message: `Credential from ${from} was rejected by the ATK API`,
+                name,
+                status: 'fail',
+            }
+            : {
+                detail: 'Check ATK_TOKEN: it must be a current Entra access token for the ATK API. Unset it to use your `atk login` session.',
+                id,
+                message: `Credential from ${from} was rejected by the ATK API`,
+                name,
+                status: 'fail',
+            };
+    }
+    if (isAtkError(err, 'client_outdated')) {
+        const command = upgradeCommand(isPreRelease() ? 'dev' : 'latest');
+        return {
+            command,
+            detail: `Run \`${command}\` to update.`,
+            id,
+            message: err.problem.message,
+            name,
+            status: 'fail',
+        };
+    }
+    return {
+        id,
+        message: `Couldn't validate the credential from ${from}: ${errorMessage(err)}`,
+        name,
+        status: 'fail',
+    };
+}
 /** A note when `~/.atk/auth/msal-cache.json` exists but yielded no session. */
 function staleEntraSessionNote() {
     if (!existsSync(getEntraCachePath())) {