@devflow-tools/cli 0.16.1 → 0.16.3

package/dist/commands/doctor.d.ts

@@ -1,21 +1,6 @@
-export type DoctorStatus = "green" | "yellow" | "red";
-export type DoctorSeverity = "info" | "warning" | "error";
-export interface DoctorMetric {
-    key: string;
-    value: unknown;
-    target?: unknown;
-    ok: boolean;
-    severity?: DoctorSeverity;
-}
-export interface DoctorSection {
-    name: "Isolation" | "Distill" | "Vectors" | "Telemetry" | "Injection" | "Memory quality" | "Knowledge quality" | "Contract" | "Deadcode" | "Data face" | "Legacy paths" | "Runtime security" | "Benchmark" | "UI reachability" | "Hook path health";
-    status: DoctorStatus;
-    metrics: DoctorMetric[];
-}
-export interface DoctorResult {
-    sections: DoctorSection[];
-    exitCode: number;
-}
+import type { DoctorReportV1 } from "@devflow-tools/sdk";
+export type { DoctorMetric, DoctorReportV1, DoctorSection, DoctorSeverity, DoctorStatus, } from "@devflow-tools/sdk";
+export type DoctorResult = DoctorReportV1;
 export interface DoctorOptions {
     project?: string;
     json?: boolean;
@@ -38,6 +23,7 @@ export interface DoctorDependencies {
     installedPluginsPath?: string;
     knownMarketplacesPath?: string;
     pluginCachePath?: string;
+    activePluginRoot?: string;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
     openDatabase?: (path: string) => DoctorDatabase;
@@ -110,5 +96,4 @@ export declare function runDoctorReceipts(): {
     sessionId: string;
     data: unknown;
 };
-export {};
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.js

@@ -6,6 +6,8 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep }
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
+import { DOCTOR_SCHEMA_VERSION } from "@devflow-tools/sdk";
+import { resolveActivePlugin, scanClaudeSkillShadowing } from "../lib/plugin-setup.js";
 import { serverStatus } from "./server.js";
 import { getGlobalDevFlowDbPath } from "@devflow-tools/database";
 function getProjectHash(rootPath) {
@@ -108,6 +110,13 @@ function checkIsolation(project, dependencies) {
             ok: true,
             severity: "info",
         });
+        metrics.push({
+            key: "hook_daemon_registration",
+            value: { activeProjectRegistrations: 0 },
+            target: "0 when idle or 1 while active",
+            ok: true,
+            severity: "info",
+        });
     }
     else {
         try {
@@ -144,6 +153,13 @@ function checkIsolation(project, dependencies) {
                 ok: true,
                 severity: "info",
             });
+            metrics.push({
+                key: "hook_daemon_registration",
+                value: { activeProjectRegistrations: projectEntries.length },
+                target: "0 when idle or 1 while active",
+                ok: projectEntries.length <= 1,
+                severity: "warning",
+            });
             const registeredSocketPaths = projectEntries.map((entry) => getDaemonSocketPath(entry.rootPath));
             metrics.push({
                 key: "registered_daemon_socket_paths",
@@ -176,6 +192,13 @@ function checkIsolation(project, dependencies) {
                 ok: false,
                 severity: "warning",
             });
+            metrics.push({
+                key: "hook_daemon_registration",
+                value: "unreadable daemon registry",
+                target: "valid project registration",
+                ok: false,
+                severity: "warning",
+            });
         }
     }
     return { name: "Isolation", status: sectionStatus(metrics), metrics };
@@ -184,7 +207,9 @@ const REQUIRED_SCHEMA = {
     distill_leases: ["event_ids", "expires_at", "status"],
     observations: ["title"],
     session_events: ["created_at", "id", "processed"],
+    sessions: ["created_at", "id", "project_root", "status"],
 };
+const SESSION_STALE_MS = 60 * 60 * 1000;
 function checkRequiredSchema(db) {
     const tableRows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all();
     const tables = new Set(tableRows.map((row) => row.name));
@@ -340,6 +365,48 @@ function checkDistill(project, dependencies) {
             ok: staleUnleased === 0,
             severity: "error",
         });
+        const pendingEvents = doctorCount(openedDb, "SELECT COUNT(*) count FROM session_events WHERE processed = 0");
+        metrics.push({
+            key: "pending_memory_events",
+            value: pendingEvents,
+            target: "actively leased or younger than 5 minutes",
+            ok: staleUnleased === 0,
+            severity: "error",
+        });
+        const oldestPending = openedDb.prepare("SELECT MIN(created_at) oldest FROM session_events WHERE processed = 0").get();
+        const oldestPendingAt = oldestPending?.oldest == null ? null : Number(oldestPending.oldest);
+        metrics.push({
+            key: "pending_memory_oldest_age_ms",
+            value: oldestPendingAt === null ? 0 : Math.max(0, now - oldestPendingAt),
+            target: "<= 300000 when no active lease is present",
+            ok: oldestPendingAt === null || staleUnleased === 0,
+            severity: "warning",
+        });
+        const orphanEvents = doctorCount(openedDb, `
+      SELECT COUNT(*) count
+      FROM session_events event
+      LEFT JOIN sessions session ON session.id = event.session_id
+      WHERE TRIM(event.session_id) = '' OR session.id IS NULL
+    `);
+        metrics.push({
+            key: "orphan_memory_events",
+            value: orphanEvents,
+            target: 0,
+            ok: orphanEvents === 0,
+            severity: "error",
+        });
+        const staleSessions = doctorCount(openedDb, `
+      SELECT COUNT(*) count
+      FROM sessions
+      WHERE status = 'active' AND created_at < ?
+    `, now - SESSION_STALE_MS);
+        metrics.push({
+            key: "stale_memory_sessions",
+            value: staleSessions,
+            target: 0,
+            ok: staleSessions === 0,
+            severity: "error",
+        });
         const duplicates = openedDb.prepare(`
       SELECT COUNT(*) AS group_count, COALESCE(SUM(title_count), 0) AS row_count
       FROM (
@@ -386,6 +453,13 @@ function doctorOpenDatabase(path, dependencies) {
 function doctorTableExists(db, table) {
     return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(table));
 }
+function doctorTableColumns(db, table) {
+    if (!doctorTableExists(db, table))
+        return new Set();
+    return new Set(db.prepare(`PRAGMA table_info(${table})`).all()
+        .map((column) => column.name)
+        .filter((name) => typeof name === "string"));
+}
 function doctorCount(db, sql, ...params) {
     const row = db.prepare(sql).get(...params);
     return Number(row?.count ?? 0);
@@ -412,6 +486,14 @@ function checkVectors(project, dependencies) {
                 codegraphNodes = doctorCount(db, "SELECT COUNT(*) count FROM nodes");
                 metrics.push({ key: "codegraph_nodes", value: codegraphNodes, ok: true, severity: "info" });
             }
+            const freshnessMs = Math.max(0, (dependencies.now ?? Date.now)() - statSync(codegraphPath).mtimeMs);
+            metrics.push({
+                key: "index_freshness_ms",
+                value: freshnessMs,
+                target: "recently updated codegraph database",
+                ok: true,
+                severity: "info",
+            });
         }
         catch (error) {
             metrics.push({ key: "codegraph_db_read", value: error.message, target: "readable SQLite database", ok: false, severity: "error" });
@@ -574,10 +656,69 @@ function checkTelemetry(project, strict, dependencies) {
                 ? doctorCount(db, "SELECT COUNT(*) count FROM telemetry_failures WHERE created_at >= ?", cutoff)
                 : 0;
             metrics.push({ key: "telemetry_failures_24h", value: failures, target: 0, ok: failures === 0, severity: strictSeverity });
+            const sessionColumns = doctorTableColumns(db, "sessions");
+            const toolEventColumns = doctorTableColumns(db, "tool_call_events");
+            const executionColumns = doctorTableColumns(db, "skill_executions");
+            const sessionSchemaReady = ["id", "project_root", "started_at", "status"]
+                .every((column) => sessionColumns.has(column));
+            metrics.push({
+                key: "telemetry_session_schema",
+                value: sessionSchemaReady ? "canonical" : "sessions table or identity columns missing",
+                target: "canonical sessions table",
+                ok: sessionSchemaReady,
+                severity: "error",
+            });
+            if (sessionSchemaReady) {
+                const recentSessionStarts = doctorCount(db, `
+          SELECT COUNT(*) count FROM sessions
+          WHERE project_root = ? AND started_at >= ?
+        `, project, cutoff);
+                metrics.push({
+                    key: "session_start_evidence_24h",
+                    value: recentSessionStarts,
+                    target: "present after a Claude SessionStart",
+                    ok: true,
+                    severity: "info",
+                });
+                const staleSessions = doctorCount(db, `
+          SELECT COUNT(*) count FROM sessions
+          WHERE project_root = ? AND status = 'running' AND started_at < ?
+        `, project, (dependencies.now ?? Date.now)() - SESSION_STALE_MS);
+                metrics.push({
+                    key: "stale_telemetry_sessions",
+                    value: staleSessions,
+                    target: 0,
+                    ok: staleSessions === 0,
+                    severity: "error",
+                });
+                let orphanToolEvents = 0;
+                if (toolEventColumns.has("session_id")) {
+                    orphanToolEvents = doctorCount(db, `
+            SELECT COUNT(*) count
+            FROM tool_call_events event
+            LEFT JOIN sessions session ON session.id = event.session_id
+            WHERE TRIM(COALESCE(event.session_id, '')) = '' OR session.id IS NULL
+          `);
+                }
+                let orphanExecutions = 0;
+                if (executionColumns.has("session_id")) {
+                    orphanExecutions = doctorCount(db, `
+            SELECT COUNT(*) count
+            FROM skill_executions execution
+            LEFT JOIN sessions session ON session.id = execution.session_id
+            WHERE TRIM(COALESCE(execution.session_id, '')) = '' OR session.id IS NULL
+          `);
+                }
+                metrics.push({
+                    key: "orphan_telemetry_events",
+                    value: { toolCalls: orphanToolEvents, skillExecutions: orphanExecutions },
+                    target: { toolCalls: 0, skillExecutions: 0 },
+                    ok: orphanToolEvents === 0 && orphanExecutions === 0,
+                    severity: "error",
+                });
+            }
             if (doctorTableExists(db, "tool_call_events")) {
-                const eventColumns = db.prepare("PRAGMA table_info(tool_call_events)").all()
-                    .map(column => column.name);
-                if (eventColumns.includes("failure_category")) {
+                if (toolEventColumns.has("failure_category")) {
                     const rows = db.prepare(`
             SELECT failure_category category, COUNT(*) count
             FROM tool_call_events
@@ -2575,7 +2716,8 @@ function marketplaceSourceRoot(sourcePath) {
         join(sourcePath, "plugins", "claude-code"),
     ]) {
         const root = canonicalDirectory(candidate);
-        if (root && existsSync(join(root, "hooks.json")))
+        if (root && (existsSync(join(root, "hooks", "hooks.json"))
+            || existsSync(join(root, "hooks.json"))))
             return root;
     }
     return null;
@@ -3266,7 +3408,11 @@ function inspectLegacyRoot(project, homePath, target, inspection) {
             enqueueCommand(command);
     }
     if (target.inspectPluginConfig || !target.commands) {
-        const configPath = join(root, "hooks.json");
+        const conventionalConfigPath = join(root, "hooks", "hooks.json");
+        const legacyConfigPath = join(root, "hooks.json");
+        const configPath = existsSync(legacyConfigPath)
+            ? legacyConfigPath
+            : conventionalConfigPath;
         if (!existsSync(configPath)) {
             inspection.missing.push(configPath);
             enqueue(join(root, "hooks", "session-start"));
@@ -3395,6 +3541,111 @@ function inspectLegacyRoot(project, homePath, target, inspection) {
         }
     }
 }
+function installedPluginVersionsByRoot(dependencies) {
+    const installedPluginsPath = dependencies.installedPluginsPath
+        ?? join(dependencies.homePath ?? homedir(), ".claude", "plugins", "installed_plugins.json");
+    const versions = new Map();
+    if (!existsSync(installedPluginsPath))
+        return new Map();
+    try {
+        const manifest = asRecord(parseJsonFile(installedPluginsPath));
+        const plugins = asRecord(manifest?.plugins);
+        if (!plugins)
+            return new Map();
+        for (const entries of Object.values(plugins)) {
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                const record = asRecord(entry);
+                if (typeof record?.installPath !== "string" || typeof record.version !== "string")
+                    continue;
+                const root = canonicalDirectory(record.installPath);
+                if (!root)
+                    continue;
+                const rootVersions = versions.get(root) ?? new Set();
+                rootVersions.add(record.version);
+                versions.set(root, rootVersions);
+            }
+        }
+    }
+    catch {
+        return new Map();
+    }
+    return new Map([...versions].map(([root, values]) => [root, [...values].sort()]));
+}
+function readPluginVersion(path) {
+    try {
+        const metadata = asRecord(parseJsonFile(path));
+        return typeof metadata?.version === "string" ? metadata.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function inspectPluginLifecycle(targets, dependencies) {
+    const inspection = {
+        layoutIssues: [],
+        versionIssues: [],
+        versionRecords: [],
+        sessionStartIssues: [],
+        daemonIssues: [],
+    };
+    const installedVersions = installedPluginVersionsByRoot(dependencies);
+    for (const target of targets) {
+        const root = target.root;
+        const packagePath = join(root, "package.json");
+        const manifestPath = join(root, ".claude-plugin", "plugin.json");
+        const hasPackageMetadata = existsSync(packagePath) || existsSync(manifestPath);
+        if (!hasPackageMetadata)
+            continue;
+        const conventionalConfigPath = join(root, "hooks", "hooks.json");
+        const legacyConfigPath = join(root, "hooks.json");
+        if (!existsSync(conventionalConfigPath)) {
+            inspection.layoutIssues.push({ root, issue: "missing hooks/hooks.json" });
+        }
+        if (existsSync(legacyConfigPath)) {
+            inspection.layoutIssues.push({ root, issue: "retired root hooks.json is present" });
+        }
+        const activeConfigPath = existsSync(conventionalConfigPath)
+            ? conventionalConfigPath
+            : legacyConfigPath;
+        try {
+            const config = asRecord(parseJsonFile(activeConfigPath));
+            const hooks = asRecord(config?.hooks);
+            const commands = [];
+            collectCommandStrings(hooks?.SessionStart, commands);
+            if (!commands.some((command) => /(?:^|[/\\])session-start(?:\s|$|["'])/.test(command))) {
+                inspection.sessionStartIssues.push({ root, issue: "SessionStart wrapper is not registered" });
+            }
+        }
+        catch {
+            inspection.sessionStartIssues.push({ root, issue: "hook configuration is unreadable" });
+        }
+        const packageVersion = readPluginVersion(packagePath);
+        const manifestVersion = readPluginVersion(manifestPath);
+        const registryVersions = installedVersions.get(root) ?? [];
+        const versionRecord = { root, packageVersion, manifestVersion, registryVersions };
+        inspection.versionRecords.push(versionRecord);
+        if (!packageVersion
+            || !manifestVersion
+            || packageVersion !== manifestVersion
+            || registryVersions.some((version) => version !== packageVersion)) {
+            inspection.versionIssues.push(versionRecord);
+        }
+        const sessionStartPath = join(root, "hooks", "session-start");
+        const daemonPath = join(root, "dist", "hooks", "hook-daemon.js");
+        try {
+            const sessionStart = readFileSync(sessionStartPath, "utf8");
+            if (!existsSync(daemonPath) || !sessionStart.includes("hook-daemon.js")) {
+                inspection.daemonIssues.push({ root, issue: "SessionStart does not register the packaged hook daemon" });
+            }
+        }
+        catch {
+            inspection.daemonIssues.push({ root, issue: "SessionStart wrapper or hook daemon is missing" });
+        }
+    }
+    return inspection;
+}
 function checkLegacyPaths(project, dependencies) {
     const selection = selectActiveLegacyTargets(project, dependencies);
     const inspection = {
@@ -3438,6 +3689,40 @@ function checkLegacyPaths(project, dependencies) {
     const resolutionMethod = artifactResolutionFailed && !selection.method.endsWith("-unresolved")
         ? `${selection.method}-unresolved`
         : selection.method;
+    const lifecycle = inspectPluginLifecycle(selection.targets, dependencies);
+    const injectedSettingsHome = dependencies.claudeSettingsPath
+        ? dirname(dependencies.claudeSettingsPath)
+        : null;
+    const skillHome = dependencies.homePath
+        ?? (injectedSettingsHome && basename(injectedSettingsHome) === ".claude"
+            ? dirname(injectedSettingsHome)
+            : injectedSettingsHome)
+        ?? homedir();
+    const selectedSkillRoot = selection.targets
+        .map((target) => target.root)
+        .find((root) => existsSync(join(root, "skills"))) ?? null;
+    const activePlugin = dependencies.activePluginRoot
+        ? {
+            root: existsSync(dependencies.activePluginRoot) ? dependencies.activePluginRoot : null,
+            version: null,
+        }
+        : selectedSkillRoot
+            ? { root: selectedSkillRoot, version: null }
+            : resolveActivePlugin(skillHome, {
+                installedPluginsPath: dependencies.installedPluginsPath,
+                pluginCachePath: dependencies.pluginCachePath,
+            });
+    const activeSkillRoot = activePlugin.root;
+    const shadowedSkills = activeSkillRoot
+        ? scanClaudeSkillShadowing(skillHome, activeSkillRoot)
+        : [];
+    const remediation = shadowedSkills
+        .filter((skill) => !skill.isKnownDevFlowArtifact)
+        .map((skill) => ({
+        skillName: skill.skillName,
+        path: skill.globalPath,
+        action: "inspect manually; file is modified or not a known DevFlow artifact",
+    }));
     const metrics = [
         {
             key: "active_plugin_resolution",
@@ -3458,6 +3743,34 @@ function checkLegacyPaths(project, dependencies) {
             ok: true,
             severity: "info",
         },
+        {
+            key: "plugin_hook_layout",
+            value: lifecycle.layoutIssues,
+            target: "hooks/hooks.json present and root hooks.json absent",
+            ok: lifecycle.layoutIssues.length === 0,
+            severity: "error",
+        },
+        {
+            key: "plugin_version_parity",
+            value: lifecycle.versionRecords,
+            target: "manifest, package, and installed registry versions match",
+            ok: lifecycle.versionIssues.length === 0,
+            severity: "error",
+        },
+        {
+            key: "session_start_hook_registration",
+            value: lifecycle.sessionStartIssues,
+            target: [],
+            ok: lifecycle.sessionStartIssues.length === 0,
+            severity: "error",
+        },
+        {
+            key: "hook_daemon_artifact_registration",
+            value: lifecycle.daemonIssues,
+            target: [],
+            ok: lifecycle.daemonIssues.length === 0,
+            severity: "error",
+        },
         {
             key: "malformed_active_settings",
             value: selection.malformedSettings,
@@ -3541,7 +3854,40 @@ function checkLegacyPaths(project, dependencies) {
             ok: true,
             severity: "info",
         },
+        {
+            key: "skill_shadowing_count",
+            value: shadowedSkills.length,
+            target: 0,
+            ok: shadowedSkills.length === 0,
+            severity: "error",
+        },
+        {
+            key: "shadowed_skills",
+            value: shadowedSkills,
+            target: [],
+            ok: shadowedSkills.length === 0,
+            severity: "error",
+        },
+        {
+            key: "active_skill_source",
+            value: activeSkillRoot,
+            target: "existing plugin cache path",
+            ok: true,
+            severity: "info",
+        },
+        {
+            key: "skill_shadowing_remediation",
+            value: remediation,
+            target: [],
+            ok: true,
+            severity: "info",
+        },
     ];
+    const activePluginVersion = activePlugin.version
+        ?? lifecycle.versionRecords.find((record) => record.root === activeSkillRoot)?.packageVersion;
+    if (activePluginVersion) {
+        metrics.push({ key: "active_plugin_version", value: activePluginVersion, ok: true, severity: "info" });
+    }
     return { name: "Legacy paths", status: sectionStatus(metrics), metrics };
 }
 function loadAcceptanceManifest(dependencies) {
@@ -3839,7 +4185,7 @@ export async function runStructuredDoctor(options = {}, dependencies = {}) {
     const exitCode = options.strict && sections.some((section) => section.status !== "green")
         ? 1
         : 0;
-    return { sections, exitCode };
+    return { schemaVersion: DOCTOR_SCHEMA_VERSION, sections, exitCode };
 }
 export function runDoctor(options, dependencies = {}) {
     return options === undefined