praxis-agent 0.17.1 → 0.18.0

package/dist/cli/interactive.js

@@ -274,12 +274,13 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
     const runtimeGitignoreRef = useRef(true);
     const loadDiffSnapshot = useMemo(() => diffLoader ?? (() => loadGitDiff(runtimeCwd)), [diffLoader, runtimeCwd]);
     const loadDoctorReport = useMemo(() => doctorLoader ??
-        (() => {
+        (async () => {
             const configuredRoot = process.env.CLAUDE_CONFIG_DIR || undefined;
             const configRoot = resolve(configuredRoot ?? resolve(homedir(), '.claude'));
             const claudeStatePath = configuredRoot
                 ? join(configRoot, '.claude.json')
                 : resolve(homedir(), '.claude.json');
+            const runtimeSettings = await loadRuntimeSettings(configTarget);
             return runDoctor({
                 version: display.version,
                 executablePath: resolve(process.argv[1] ??
@@ -290,8 +291,12 @@ export function InteractiveApp({ factory, initialSessions, initialPrompt, initia
                 claudeStatePath,
                 cwd: runtimeCwd,
                 environment: process.env,
+                autoUpdateChannel: runtimeSettings.autoUpdatesChannel,
+                ...(process.argv[1] === undefined
+                    ? {}
+                    : { invokedBinaryPath: process.argv[1] }),
             });
-        }), [doctorLoader, runtimeCwd, display.version]);
+        }), [doctorLoader, runtimeCwd, display.version, configTarget]);
     const loadFiles = useMemo(() => fileLoader ??
         (() => loadTuiFileEntries(runtimeCwd, {
             respectGitignore: runtimeGitignoreRef.current,

package/dist/cli.js

@@ -2078,6 +2078,10 @@ async function executeDoctorCommand(args, invocation, io) {
     const claudeStatePath = configuredRoot
         ? join(configRoot, '.claude.json')
         : resolve(homedir(), '.claude.json');
+    const runtimeSettings = await loadRuntimeSettings({
+        configRoot,
+        statePath: claudeStatePath,
+    });
     const report = await runDoctor({
         version: VERSION,
         executablePath: fileURLToPath(import.meta.url),
@@ -2087,6 +2091,10 @@ async function executeDoctorCommand(args, invocation, io) {
         claudeStatePath,
         cwd: process.cwd(),
         environment: process.env,
+        autoUpdateChannel: runtimeSettings.autoUpdatesChannel,
+        ...(process.argv[1] === undefined
+            ? {}
+            : { invokedBinaryPath: process.argv[1] }),
     });
     if (invocation.legacyJson || invocation.outputFormat === 'json') {
         writeJson(io, report);

package/dist/maintenance/doctor-diagnostic.d.ts

@@ -0,0 +1,54 @@
+export type DoctorInstallationType = 'npm' | 'source';
+export interface DoctorSearchStatus {
+    readonly working: boolean;
+    readonly mode: 'system';
+    readonly systemPath: string | null;
+}
+export interface DoctorDiagnosticWarning {
+    readonly issue: string;
+    readonly fix: string;
+}
+export interface DoctorInstallationDiagnostic {
+    readonly installationType: DoctorInstallationType;
+    readonly version: string;
+    readonly packageManager: string | null;
+    readonly installationPath: string;
+    readonly invokedBinary: string;
+    readonly configInstallMethod: string;
+    readonly search: DoctorSearchStatus;
+    readonly recommendation: string | null;
+    readonly multipleInstallations: readonly string[];
+    readonly warnings: readonly DoctorDiagnosticWarning[];
+}
+export interface DoctorUpdateDiagnostic {
+    readonly autoUpdates: string;
+    readonly hasUpdatePermissions: boolean | null;
+    readonly channel: 'latest' | 'stable';
+    readonly stableVersion: string | null;
+    readonly latestVersion: string | null;
+    readonly registryStatus: 'available' | 'unavailable';
+    readonly error?: string;
+}
+export interface PraxisDistTags {
+    stable?: string;
+    latest?: string;
+}
+export type PraxisDistTagLoader = () => Promise<PraxisDistTags>;
+export type DoctorUpdatePermissionChecker = (directory: string) => Promise<boolean | null>;
+export interface DoctorDiagnosticOptions {
+    version: string;
+    executablePath: string;
+    invokedBinaryPath?: string;
+    configRoot: string;
+    environment: NodeJS.ProcessEnv;
+    autoUpdateChannel: 'latest' | 'stable';
+    loadDistTags?: PraxisDistTagLoader;
+    checkUpdatePermissions?: DoctorUpdatePermissionChecker;
+}
+export interface DoctorDiagnosticsResult {
+    diagnostic: DoctorInstallationDiagnostic;
+    updates: DoctorUpdateDiagnostic;
+}
+export declare function loadPraxisDistTags(): Promise<PraxisDistTags>;
+export declare function collectDoctorDiagnostics(options: DoctorDiagnosticOptions): Promise<DoctorDiagnosticsResult>;
+//# sourceMappingURL=doctor-diagnostic.d.ts.map

package/dist/maintenance/doctor-diagnostic.js

@@ -0,0 +1,180 @@
+import { constants } from 'node:fs';
+import { access, realpath, stat } from 'node:fs/promises';
+import { basename, delimiter, dirname, resolve } from 'node:path';
+const PRAXIS_NPM_PACKAGE = 'praxis-agent';
+const DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PRAXIS_NPM_PACKAGE}/dist-tags`;
+const DIST_TAGS_TIMEOUT_MS = 5_000;
+const REGISTRY_ERROR = 'Failed to fetch version information from the npm registry';
+function parseDistTags(parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const record = parsed;
+    const tags = {};
+    for (const name of ['stable', 'latest']) {
+        const value = record[name];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            tags[name] = value.trim();
+        }
+    }
+    return tags;
+}
+export async function loadPraxisDistTags() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DIST_TAGS_TIMEOUT_MS);
+    try {
+        const response = await fetch(DIST_TAGS_URL, {
+            headers: { accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return {};
+        return parseDistTags(await response.json());
+    }
+    catch {
+        return {};
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readableExecutable(path) {
+    const metadata = await stat(path);
+    if (!metadata.isFile())
+        throw new Error(`Executable is not a file: ${path}`);
+    await access(path, constants.R_OK);
+    return realpath(path);
+}
+async function executableRealpath(path) {
+    try {
+        const metadata = await stat(path);
+        if (!metadata.isFile())
+            return null;
+        await access(path, constants.X_OK);
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}
+async function findOnPath(names, environment) {
+    for (const root of (environment.PATH ?? '')
+        .split(delimiter)
+        .filter(Boolean)) {
+        for (const name of names) {
+            const candidate = resolve(root, name);
+            const canonical = await executableRealpath(candidate);
+            if (canonical !== null)
+                return canonical;
+        }
+    }
+    return null;
+}
+async function praxisInstallations(installationPath, environment) {
+    const names = process.platform === 'win32' ? ['praxis.exe', 'praxis.cmd'] : ['praxis'];
+    const found = new Set();
+    for (const root of (environment.PATH ?? '')
+        .split(delimiter)
+        .filter(Boolean)) {
+        for (const name of names) {
+            const candidate = resolve(root, name);
+            const canonical = await executableRealpath(candidate);
+            if (canonical !== null)
+                found.add(canonical);
+        }
+    }
+    if (names.includes(basename(installationPath)))
+        found.add(installationPath);
+    return [...found].sort();
+}
+async function updatePermissions(directory) {
+    try {
+        await access(directory, constants.W_OK);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'EACCES' || code === 'EPERM' ? false : null;
+    }
+}
+async function buildUpdateDiagnostic(options, installation) {
+    const checkUpdatePermissions = options.checkUpdatePermissions ?? updatePermissions;
+    const hasUpdatePermissions = await checkUpdatePermissions(dirname(installation.invokedBinary));
+    let stableVersion = null;
+    let latestVersion = null;
+    let registryStatus = 'unavailable';
+    let error;
+    try {
+        const loader = options.loadDistTags ?? loadPraxisDistTags;
+        const tags = await loader();
+        const latest = tags.latest?.trim();
+        if (latest) {
+            registryStatus = 'available';
+            latestVersion = latest;
+            stableVersion = tags.stable?.trim() || null;
+        }
+        else {
+            error = REGISTRY_ERROR;
+        }
+    }
+    catch (cause) {
+        error = `${REGISTRY_ERROR}: ${cause instanceof Error ? cause.message : String(cause)}`;
+    }
+    return {
+        autoUpdates: installation.installationType === 'npm'
+            ? 'Manual (praxis update)'
+            : 'Managed by source checkout',
+        hasUpdatePermissions,
+        channel: options.autoUpdateChannel,
+        stableVersion,
+        latestVersion,
+        registryStatus,
+        ...(error === undefined ? {} : { error }),
+    };
+}
+export async function collectDoctorDiagnostics(options) {
+    const installationPath = await readableExecutable(options.executablePath);
+    const invokedBinary = resolve(options.invokedBinaryPath ?? options.executablePath);
+    const installationType = installationPath
+        .split(/[\\/]+/u)
+        .includes('node_modules')
+        ? 'npm'
+        : 'source';
+    const warnings = [];
+    const rgPath = await findOnPath(process.platform === 'win32' ? ['rg.exe'] : ['rg'], options.environment);
+    if (rgPath === null) {
+        warnings.push({
+            issue: 'The ripgrep (rg) command is not installed on PATH',
+            fix: "Install ripgrep and ensure it is on PATH (for example: 'brew install ripgrep', 'apt install ripgrep', or 'npm install -g @vscode/ripgrep')",
+        });
+    }
+    const search = {
+        working: rgPath !== null,
+        mode: 'system',
+        systemPath: rgPath,
+    };
+    const multipleInstallations = await praxisInstallations(installationPath, options.environment);
+    const recommendation = multipleInstallations.length > 1
+        ? 'Remove stale duplicate Praxis installations and keep only the executable reported by this doctor report'
+        : null;
+    const claudeConfigDir = options.environment.CLAUDE_CONFIG_DIR;
+    const diagnostic = {
+        installationType,
+        version: options.version,
+        packageManager: installationType === 'npm' ? 'npm' : null,
+        installationPath,
+        invokedBinary,
+        configInstallMethod: typeof claudeConfigDir === 'string' && claudeConfigDir.trim().length > 0
+            ? 'CLAUDE_CONFIG_DIR'
+            : 'default (~/.claude)',
+        search,
+        recommendation,
+        multipleInstallations,
+        warnings,
+    };
+    const updates = await buildUpdateDiagnostic(options, {
+        installationType,
+        invokedBinary,
+    });
+    return { diagnostic, updates };
+}
+//# sourceMappingURL=doctor-diagnostic.js.map

package/dist/maintenance/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type VersionCommand } from '../platform/claude-version.js';
+import { type DoctorInstallationDiagnostic, type DoctorUpdateDiagnostic, type PraxisDistTagLoader } from './doctor-diagnostic.js';
 export interface DoctorCheck {
     id: 'installation' | 'node' | 'provider' | 'config-root' | 'settings' | 'plugins' | 'mcp' | 'permissions' | 'resources' | 'hooks' | 'claude-runtime';
     status: 'pass' | 'warn' | 'fail';
@@ -9,6 +10,8 @@ export interface DoctorReport {
     type: 'doctor';
     ok: boolean;
     praxisVersion: string;
+    diagnostic: DoctorInstallationDiagnostic;
+    updates: DoctorUpdateDiagnostic;
     checks: readonly DoctorCheck[];
     summary: {
         passed: number;
@@ -27,6 +30,9 @@ export interface DoctorOptions {
     environment: NodeJS.ProcessEnv;
     detectClaudeVersion?: (execute?: VersionCommand) => Promise<string>;
     executeVersion?: VersionCommand;
+    autoUpdateChannel: 'latest' | 'stable';
+    invokedBinaryPath?: string;
+    loadDistTags?: PraxisDistTagLoader;
 }
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
 export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/maintenance/doctor.js

@@ -15,6 +15,7 @@ import { ContextBudget } from '../core/context-budget.js';
 import { ModelPricingRegistry } from '../core/usage.js';
 import { detectInstalledClaudeVersion, } from '../platform/claude-version.js';
 import { redactSensitiveText, sensitiveEnvironmentValues, } from '../platform/sensitive-data.js';
+import { collectDoctorDiagnostics, } from './doctor-diagnostic.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -127,6 +128,20 @@ async function capture(id, operation) {
 export async function runDoctor(options) {
     const configRoot = resolve(options.configRoot);
     const cwd = resolve(options.cwd);
+    const sensitiveValues = sensitiveEnvironmentValues(options.environment);
+    const { diagnostic, updates } = await collectDoctorDiagnostics({
+        version: options.version,
+        executablePath: options.executablePath,
+        ...(options.invokedBinaryPath === undefined
+            ? {}
+            : { invokedBinaryPath: options.invokedBinaryPath }),
+        configRoot,
+        environment: options.environment,
+        autoUpdateChannel: options.autoUpdateChannel,
+        ...(options.loadDistTags === undefined
+            ? {}
+            : { loadDistTags: options.loadDistTags }),
+    });
     let settings;
     const checks = [];
     checks.push(await capture('installation', async () => {
@@ -352,12 +367,17 @@ export async function runDoctor(options) {
         validateClaudeHooks(settings);
         return { summary: 'Hook configuration is valid' };
     }));
-    const sensitiveValues = sensitiveEnvironmentValues(options.environment);
     for (const check of checks) {
         if (check.status === 'fail') {
             check.summary = redactSensitiveText(check.summary, sensitiveValues);
         }
     }
+    const reportUpdates = updates.error === undefined
+        ? updates
+        : {
+            ...updates,
+            error: redactSensitiveText(updates.error, sensitiveValues),
+        };
     const summary = {
         passed: checks.filter((check) => check.status === 'pass').length,
         warnings: checks.filter((check) => check.status === 'warn').length,
@@ -367,12 +387,42 @@ export async function runDoctor(options) {
         type: 'doctor',
         ok: checks.every((check) => check.status !== 'fail'),
         praxisVersion: options.version,
+        diagnostic,
+        updates: reportUpdates,
         checks,
         summary,
     };
 }
 export function formatDoctorReport(report) {
     const lines = ['Praxis doctor', ''];
+    const { diagnostic, updates } = report;
+    lines.push('Diagnostics');
+    lines.push(`  Currently running: Praxis ${diagnostic.version} (${diagnostic.installationType})`);
+    if (diagnostic.packageManager !== null) {
+        lines.push(`  Package manager: ${diagnostic.packageManager}`);
+    }
+    lines.push(`  Path: ${diagnostic.installationPath}`);
+    lines.push(`  Invoked: ${diagnostic.invokedBinary}`);
+    lines.push(`  Config install method: ${diagnostic.configInstallMethod}`);
+    lines.push(`  Search: ${diagnostic.search.working
+        ? `${diagnostic.search.mode} (${diagnostic.search.systemPath})`
+        : 'unavailable'}`);
+    lines.push('', 'Updates');
+    lines.push(`  Auto-updates: ${updates.autoUpdates}`);
+    if (updates.hasUpdatePermissions !== null) {
+        lines.push(`  Update permissions: ${updates.hasUpdatePermissions ? 'yes' : 'no'}`);
+    }
+    lines.push(`  Update channel: ${updates.channel}`);
+    if (updates.registryStatus === 'available') {
+        if (updates.stableVersion !== null) {
+            lines.push(`  Stable version: ${updates.stableVersion}`);
+        }
+        lines.push(`  Latest version: ${updates.latestVersion ?? 'unknown'}`);
+    }
+    else {
+        lines.push('  └ Failed to fetch versions');
+    }
+    lines.push('');
     for (const check of report.checks) {
         lines.push(`[${check.status.toUpperCase()}] ${check.id}: ${check.summary}`);
         if (check.details) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",