mdkg 0.3.0 → 0.3.2

package/dist/commands/doctor.js

@@ -15,10 +15,35 @@ const template_schema_1 = require("../graph/template_schema");
 const visibility_1 = require("../graph/visibility");
 const sqlite_index_1 = require("../graph/sqlite_index");
 const project_db_1 = require("../core/project_db");
+const project_db_migrations_1 = require("../core/project_db_migrations");
 const errors_1 = require("../util/errors");
 const REQUIRED_NODE_MAJOR = 24;
 const REQUIRED_NODE_MINOR = 15;
 const ARCHIVE_RAW_ALLOWED_DIRS = new Set(["source"]);
+const SELECTED_GOAL_STATE_PATH = path_1.default.join(".mdkg", "state", "selected-goal.json");
+function makeCheck(input) {
+    const level = input.level ?? (input.ok ? undefined : "fail");
+    const effectiveLevel = level ?? "ok";
+    const status = !input.ok || effectiveLevel === "fail" ? "fail" : effectiveLevel === "warn" ? "warn" : "pass";
+    const severity = status === "fail" ? "error" : status === "warn" ? "warning" : "info";
+    return {
+        id: input.id,
+        name: input.name,
+        ok: input.ok,
+        level,
+        detail: input.detail,
+        status,
+        severity,
+        message: input.message ?? input.detail,
+        remediation: input.remediation ?? "No action required.",
+        refs: input.refs,
+        strictFail: input.strictFail,
+    };
+}
+function publicCheck(result) {
+    const { strictFail: _strictFail, ...publicResult } = result;
+    return publicResult;
+}
 function parseNodeVersion(version) {
     const [majorRaw, minorRaw, patchRaw] = version.split(".");
     const major = Number.parseInt(majorRaw ?? "", 10);
@@ -33,55 +58,67 @@ function runNodeVersionCheck() {
     const nodeVersion = process.versions.node;
     const parsed = parseNodeVersion(nodeVersion);
     if (parsed === null) {
-        return {
+        return makeCheck({
+            id: "runtime.node_version",
             name: "node-version",
             ok: false,
             detail: `unable to parse Node.js version: ${nodeVersion}`,
-        };
+            remediation: `Run mdkg with Node.js >=${REQUIRED_NODE_MAJOR}.${REQUIRED_NODE_MINOR}.0.`,
+        });
     }
     if (parsed.major < REQUIRED_NODE_MAJOR ||
         (parsed.major === REQUIRED_NODE_MAJOR && parsed.minor < REQUIRED_NODE_MINOR)) {
-        return {
+        return makeCheck({
+            id: "runtime.node_version",
             name: "node-version",
             ok: false,
             detail: `Node.js ${nodeVersion} is unsupported (requires >=${REQUIRED_NODE_MAJOR}.${REQUIRED_NODE_MINOR}.0)`,
-        };
+            remediation: `Install Node.js >=${REQUIRED_NODE_MAJOR}.${REQUIRED_NODE_MINOR}.0 and rerun mdkg.`,
+        });
     }
-    return {
+    return makeCheck({
+        id: "runtime.node_version",
         name: "node-version",
         ok: true,
         detail: `Node.js ${nodeVersion} (ok)`,
-    };
+    });
 }
 function runSqliteCheck(root, config) {
     if (!(0, sqlite_index_1.isSqliteBackend)(config)) {
-        return {
+        return makeCheck({
+            id: "graph.sqlite_cache",
             name: "sqlite-cache",
             ok: true,
             detail: "SQLite backend disabled; JSON cache backend active",
-        };
+        });
     }
     const health = (0, sqlite_index_1.sqliteHealth)(root, config);
     if (health.errors.length > 0) {
-        return {
+        return makeCheck({
+            id: "graph.sqlite_cache",
             name: "sqlite-cache",
             ok: false,
             detail: health.errors.join("; "),
-        };
+            remediation: "Run `mdkg index` to rebuild the SQLite graph cache.",
+        });
     }
     if (health.warnings.length > 0) {
-        return {
+        return makeCheck({
+            id: "graph.sqlite_cache",
             name: "sqlite-cache",
             ok: true,
             level: "warn",
             detail: health.warnings.join("; "),
-        };
+            remediation: "Run `mdkg index` to refresh the SQLite graph cache.",
+            strictFail: true,
+        });
     }
-    return {
+    return makeCheck({
+        id: "graph.sqlite_cache",
         name: "sqlite-cache",
         ok: true,
         detail: `.mdkg SQLite cache ok (${health.size} bytes)`,
-    };
+    });
 }
 function walkFiles(root) {
     if (!fs_1.default.existsSync(root)) {
@@ -115,26 +152,31 @@ function runArchiveStorageCheck(root) {
         .map((filePath) => path_1.default.relative(root, filePath).split(path_1.default.sep).join("/"))
         .sort();
     if (strayRaw.length === 0) {
-        return {
+        return makeCheck({
+            id: "archive.storage",
             name: "archive-storage",
             ok: true,
             detail: ".mdkg/archive has no stray raw files outside managed source directories",
-        };
+        });
     }
-    return {
+    return makeCheck({
+        id: "archive.storage",
         name: "archive-storage",
         ok: true,
         level: "warn",
         detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; run \`mdkg archive add <file>\` or move raw files under a managed archive source directory`,
-    };
+        remediation: "Run `mdkg archive add <file>` or move raw files under a managed archive source directory.",
+        refs: strayRaw,
+    });
 }
 function runArchiveLargeCacheCheck(root, warningBytes) {
     if (warningBytes === 0) {
-        return {
+        return makeCheck({
+            id: "archive.large_cache",
             name: "archive-large-cache",
             ok: true,
             detail: "archive large-cache warning disabled",
-        };
+        });
     }
     const archiveRoot = path_1.default.join(root, ".mdkg", "archive");
     const largeCaches = walkFiles(archiveRoot)
@@ -146,103 +188,130 @@ function runArchiveLargeCacheCheck(root, warningBytes) {
         .filter((entry) => entry.size > warningBytes)
         .sort((a, b) => a.path.localeCompare(b.path));
     if (largeCaches.length === 0) {
-        return {
+        return makeCheck({
+            id: "archive.large_cache",
             name: "archive-large-cache",
             ok: true,
             detail: `no archive ZIP cache exceeds ${warningBytes} bytes`,
-        };
+        });
     }
-    return {
+    return makeCheck({
+        id: "archive.large_cache",
         name: "archive-large-cache",
         ok: true,
         level: "warn",
         detail: `archive ZIP cache(s) exceed ${warningBytes} bytes: ${largeCaches
             .map((entry) => `${entry.path} (${entry.size} bytes)`)
             .join(", ")}; keep large caches private or move bulky originals to repo policy-managed storage`,
-    };
+        remediation: "Keep large caches private or move bulky originals to repo policy-managed storage.",
+        refs: largeCaches.map((entry) => entry.path),
+    });
 }
 function runBundleStorageCheck(root, outputDir) {
     const bundleRoot = path_1.default.resolve(root, outputDir);
     if (!fs_1.default.existsSync(bundleRoot)) {
-        return {
+        return makeCheck({
+            id: "bundle.storage",
             name: "bundle-storage",
             ok: true,
             detail: `no bundle directory found; run \`mdkg bundle create --profile private\` when a snapshot should be tracked`,
-        };
+            remediation: "Run `mdkg bundle create --profile private` when a snapshot should be tracked.",
+        });
     }
     const bundles = walkFiles(bundleRoot)
         .filter((filePath) => filePath.endsWith(".mdkg.zip"))
         .map((filePath) => path_1.default.relative(root, filePath).split(path_1.default.sep).join("/"))
         .sort();
     if (bundles.length === 0) {
-        return {
+        return makeCheck({
+            id: "bundle.storage",
             name: "bundle-storage",
             ok: true,
             detail: `bundle directory has no .mdkg.zip files; run \`mdkg bundle create --profile private\` when a snapshot should be tracked`,
-        };
+            remediation: "Run `mdkg bundle create --profile private` when a snapshot should be tracked.",
+        });
     }
-    return {
+    return makeCheck({
+        id: "bundle.storage",
         name: "bundle-storage",
         ok: true,
         detail: `${bundles.length} bundle(s) found; run \`mdkg bundle verify <path>\` to check freshness before handoff`,
-    };
+        remediation: "Run `mdkg bundle verify <path>` to check freshness before handoff.",
+        refs: bundles,
+    });
 }
 function runProjectDbRuntimePolicyCheck(root) {
     const files = (0, project_db_1.listProjectDbRuntimePolicyFiles)(root);
     if (files.length === 0) {
-        return {
+        return makeCheck({
+            id: "db.runtime_transient_files",
             name: "project-db-runtime",
             ok: true,
             detail: "no active project DB runtime or transient files found",
-        };
+        });
     }
-    return {
+    return makeCheck({
+        id: "db.runtime_transient_files",
         name: "project-db-runtime",
         ok: true,
         level: "warn",
         detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}`,
-    };
+        remediation: "Keep runtime DB and transient files ignored; commit sealed state only by explicit repo policy.",
+        refs: files,
+    });
 }
 function runSubgraphChecks(root, config) {
     const projection = (0, subgraphs_1.buildSubgraphsIndex)(root, config);
     if (projection.index.subgraphs.length === 0) {
         return [
-            {
+            makeCheck({
+                id: "subgraph.configured_state",
                 name: "subgraphs",
                 ok: true,
                 detail: "no subgraphs configured",
-            },
+            }),
         ];
     }
     return projection.index.subgraphs.map((item) => {
         if (!item.enabled) {
-            return {
+            return makeCheck({
+                id: "subgraph.configured_state",
                 name: `subgraph:${item.alias}`,
                 ok: true,
                 level: "warn",
                 detail: "disabled subgraph",
-            };
+                remediation: `Run \`mdkg subgraph enable ${item.alias}\` if this subgraph should participate in graph views.`,
+                refs: [item.alias],
+            });
         }
         if (item.error_count > 0) {
-            return {
+            return makeCheck({
+                id: "subgraph.configured_state",
                 name: `subgraph:${item.alias}`,
                 ok: false,
                 detail: item.errors.join("; "),
-            };
+                remediation: `Run \`mdkg subgraph verify ${item.alias} --json\` and refresh or remove the failing bundle source.`,
+                refs: [item.alias],
+            });
         }
         if (item.stale || item.warning_count > 0) {
-            return {
+            return makeCheck({
+                id: "subgraph.configured_state",
                 name: `subgraph:${item.alias}`,
                 ok: true,
                 level: "warn",
                 detail: `subgraph is stale or has warnings; run \`mdkg subgraph verify ${item.alias}\` (${item.warnings.join("; ")})`,
-            };
+                remediation: `Run \`mdkg subgraph verify ${item.alias}\` and refresh stale sources if needed.`,
+                refs: [item.alias],
+            });
         }
-        return {
+        return makeCheck({
+            id: "subgraph.configured_state",
             name: `subgraph:${item.alias}`,
             ok: true,
             detail: `subgraph loaded from ${item.sources.map((source) => source.path).join(", ")}`,
-        };
+            refs: [item.alias],
+        });
     });
 }
 function runVisibilityPolicyCheck(root, config, options) {
@@ -251,184 +320,399 @@ function runVisibilityPolicyCheck(root, config, options) {
             root,
             config,
             useCache: !options.noCache,
-            allowReindex: !options.noReindex,
+            allowReindex: !options.noReindex && !options.strict,
         });
         const messages = (0, visibility_1.visibilityViolationMessages)((0, visibility_1.collectVisibilityViolations)(index, config));
         if (messages.length === 0) {
-            return {
+            return makeCheck({
+                id: "visibility.policy",
                 name: "visibility-policy",
                 ok: true,
                 detail: "public/internal records do not reference less-visible mdkg records",
-            };
+            });
         }
-        return {
+        return makeCheck({
+            id: "visibility.policy",
             name: "visibility-policy",
             ok: false,
             detail: `${messages.length} violation(s): ${messages.join("; ")}`,
-        };
+            remediation: "Adjust visibility metadata or remove references from more-visible records to less-visible records.",
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        return makeCheck({
+            id: "visibility.policy",
             name: "visibility-policy",
             ok: false,
             detail: message,
-        };
+            remediation: "Run `mdkg validate --json` for graph visibility diagnostics.",
+        });
+    }
+}
+function readSelectedGoalState(root) {
+    const filePath = path_1.default.join(root, SELECTED_GOAL_STATE_PATH);
+    if (!fs_1.default.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+        if (typeof parsed.qid === "string" &&
+            typeof parsed.id === "string" &&
+            typeof parsed.ws === "string" &&
+            typeof parsed.selected_at === "string") {
+            return {
+                state: {
+                    qid: parsed.qid.toLowerCase(),
+                    id: parsed.id.toLowerCase(),
+                    ws: parsed.ws.toLowerCase(),
+                    selected_at: parsed.selected_at,
+                },
+            };
+        }
+        return { warning: "selected goal state is malformed" };
+    }
+    catch {
+        return { warning: "selected goal state is unreadable" };
+    }
+}
+function runSelectedGoalChecks(root, config, options) {
+    const selected = readSelectedGoalState(root);
+    if (selected.warning) {
+        return [
+            makeCheck({
+                id: "goal.selected_missing",
+                name: "selected-goal",
+                ok: true,
+                level: "warn",
+                detail: selected.warning,
+                remediation: "Run `mdkg goal select <goal-id>` or `mdkg goal clear`.",
+                strictFail: true,
+            }),
+        ];
+    }
+    if (!selected.state) {
+        return [
+            makeCheck({
+                id: "goal.selected_missing",
+                name: "selected-goal",
+                ok: true,
+                detail: "no selected goal state found",
+                remediation: "Run `mdkg goal select <goal-id>` when pursuing a long-running goal.",
+            }),
+        ];
+    }
+    try {
+        const { index } = (0, index_cache_1.loadIndex)({
+            root,
+            config,
+            useCache: !options.noCache,
+            allowReindex: !options.noReindex && !options.strict,
+        });
+        const node = index.nodes[selected.state.qid];
+        if (!node) {
+            return [
+                makeCheck({
+                    id: "goal.selected_missing",
+                    name: "selected-goal",
+                    ok: true,
+                    level: "warn",
+                    detail: `selected goal ${selected.state.qid} is missing from the graph`,
+                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    refs: [selected.state.qid],
+                    strictFail: true,
+                }),
+            ];
+        }
+        const achieved = node.status === "done" || String(node.attributes.goal_state ?? "") === "achieved";
+        if (achieved) {
+            return [
+                makeCheck({
+                    id: "goal.selected_achieved",
+                    name: "selected-goal",
+                    ok: true,
+                    level: "warn",
+                    detail: `selected goal ${selected.state.qid} is achieved but still current`,
+                    remediation: "Run `mdkg goal select <active-goal>` or `mdkg goal clear`.",
+                    refs: [selected.state.qid],
+                    strictFail: true,
+                }),
+            ];
+        }
+        return [
+            makeCheck({
+                id: "goal.selected_achieved",
+                name: "selected-goal",
+                ok: true,
+                detail: `selected goal ${selected.state.qid} is active`,
+                refs: [selected.state.qid],
+            }),
+        ];
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return [
+            makeCheck({
+                id: "goal.selected_missing",
+                name: "selected-goal",
+                ok: true,
+                level: "warn",
+                detail: `selected goal could not be checked: ${message}`,
+                remediation: "Run `mdkg index` and `mdkg goal current --json` to inspect selected-goal state.",
+                refs: [selected.state.qid],
+                strictFail: true,
+            }),
+        ];
+    }
+}
+function runProjectDbVerifyCheck(root, config) {
+    if (!config.db.enabled) {
+        return makeCheck({
+            id: "db.project_verify",
+            name: "project-db-verify",
+            ok: true,
+            detail: "project DB is disabled",
+            remediation: "Run `mdkg db init` only when project DB state is needed.",
+        });
+    }
+    const verification = (0, project_db_migrations_1.verifyProjectDb)(root, config);
+    if (verification.ok) {
+        return makeCheck({
+            id: "db.project_verify",
+            name: "project-db-verify",
+            ok: true,
+            detail: `project DB verified (${verification.database})`,
+            refs: [verification.database],
+        });
+    }
+    return makeCheck({
+        id: "db.project_verify",
+        name: "project-db-verify",
+        ok: true,
+        level: "warn",
+        detail: verification.errors.join("; "),
+        remediation: "Run `mdkg db verify --json`, then `mdkg db init` or `mdkg db migrate` as directed.",
+        refs: [verification.database],
+        strictFail: true,
+    });
+}
+function applyStrict(results, strict) {
+    if (!strict) {
+        return results;
     }
+    return results.map((result) => {
+        if (!result.strictFail || !result.ok) {
+            return result;
+        }
+        return {
+            ...result,
+            ok: false,
+            level: "fail",
+            status: "fail",
+            severity: "error",
+        };
+    });
 }
 function runDoctorCommand(options) {
     const results = [];
+    const strict = options.strict ?? false;
     results.push(runNodeVersionCheck());
     const configPath = path_1.default.resolve(options.root, ".mdkg", "config.json");
     if (!fs_1.default.existsSync(configPath)) {
-        results.push({
+        results.push(makeCheck({
+            id: "repo.root_config",
             name: "config",
             ok: false,
             detail: `missing config at ${configPath}`,
-        });
+            remediation: "Run from a repo root, pass `--root <path>`, or run `mdkg init`.",
+            refs: [path_1.default.relative(options.root, configPath).split(path_1.default.sep).join("/")],
+        }));
     }
     else {
-        results.push({
+        results.push(makeCheck({
+            id: "repo.root_config",
             name: "config",
             ok: true,
             detail: `found ${configPath}`,
-        });
+            refs: [path_1.default.relative(options.root, configPath).split(path_1.default.sep).join("/")],
+        }));
     }
     let config;
     try {
         config = (0, config_1.loadConfig)(options.root);
-        results.push({
+        results.push(makeCheck({
+            id: "repo.root_config",
             name: "config-schema",
             ok: true,
             detail: "config schema valid",
-        });
+        }));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        results.push({
+        results.push(makeCheck({
+            id: "repo.root_config",
             name: "config-schema",
             ok: false,
             detail: message,
-        });
+            remediation: "Fix `.mdkg/config.json` and rerun `mdkg doctor`.",
+            refs: [".mdkg/config.json"],
+        }));
     }
     if (config) {
         results.push(runArchiveStorageCheck(options.root));
         results.push(runArchiveLargeCacheCheck(options.root, config.archive.large_cache_warning_bytes));
         results.push(runBundleStorageCheck(options.root, config.bundles.output_dir));
         results.push(runProjectDbRuntimePolicyCheck(options.root));
+        results.push(runProjectDbVerifyCheck(options.root, config));
         results.push(runSqliteCheck(options.root, config));
         results.push(...runSubgraphChecks(options.root, config));
         results.push(runVisibilityPolicyCheck(options.root, config, options));
+        results.push(...runSelectedGoalChecks(options.root, config, options));
         try {
             const templateSchemaInfo = (0, template_schema_1.loadTemplateSchemasWithInfo)(options.root, config, node_1.ALLOWED_TYPES);
-            results.push({
+            results.push(makeCheck({
+                id: "repo.templates",
                 name: "templates",
                 ok: true,
                 detail: "template schema set loaded",
-            });
+            }));
             if (templateSchemaInfo.fallbackTypes.length > 0) {
-                results.push({
+                results.push(makeCheck({
+                    id: "repo.templates",
                     name: "local-templates",
                     ok: true,
                     level: "warn",
                     detail: `missing local template schema(s) covered by bundled fallback: ${templateSchemaInfo.fallbackTypes.join(", ")}; run \`mdkg upgrade --apply\` to vendor them`,
-                });
+                    remediation: "Run `mdkg upgrade --apply` to vendor missing managed template schemas.",
+                    refs: templateSchemaInfo.fallbackTypes,
+                }));
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            results.push({
+            results.push(makeCheck({
+                id: "repo.templates",
                 name: "templates",
                 ok: false,
                 detail: message,
-            });
+                remediation: "Repair `.mdkg/templates` or run `mdkg upgrade --apply` when managed assets should be restored.",
+            }));
         }
         try {
             const { rebuilt, stale } = (0, index_cache_1.loadIndex)({
                 root: options.root,
                 config,
                 useCache: !options.noCache,
-                allowReindex: !options.noReindex,
+                allowReindex: !options.noReindex && !strict,
             });
             if (rebuilt) {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.index_cache",
                     name: "index",
                     ok: true,
                     detail: "index cache rebuilt and loaded",
-                });
+                    remediation: "No action required; non-strict doctor rebuilt the cache.",
+                }));
             }
             else if (stale) {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.index_cache",
                     name: "index",
                     ok: true,
+                    level: "warn",
                     detail: "index cache is stale (run mdkg index to refresh)",
-                });
+                    remediation: "Run `mdkg index` to refresh generated graph caches.",
+                    strictFail: true,
+                }));
             }
             else {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.index_cache",
                     name: "index",
                     ok: true,
                     detail: "index cache loaded",
-                });
+                }));
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            results.push({
+            results.push(makeCheck({
+                id: "graph.validate",
                 name: "index",
                 ok: false,
                 detail: message,
-            });
+                remediation: "Run `mdkg validate --json` and repair graph errors, then run `mdkg index`.",
+            }));
         }
         try {
             const { rebuilt, stale } = (0, capabilities_index_cache_1.loadCapabilitiesIndex)({
                 root: options.root,
                 config,
                 useCache: !options.noCache,
-                allowReindex: !options.noReindex,
+                allowReindex: !options.noReindex && !strict,
             });
             if (rebuilt) {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.capability_cache",
                     name: "capabilities-index",
                     ok: true,
                     detail: "capabilities cache rebuilt and loaded",
-                });
+                    remediation: "No action required; non-strict doctor rebuilt the cache.",
+                }));
             }
             else if (stale) {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.capability_cache",
                     name: "capabilities-index",
                     ok: true,
+                    level: "warn",
                     detail: "capabilities cache is stale (run mdkg index to refresh)",
-                });
+                    remediation: "Run `mdkg index` to refresh generated capability caches.",
+                    strictFail: true,
+                }));
             }
             else {
-                results.push({
+                results.push(makeCheck({
+                    id: "graph.capability_cache",
                     name: "capabilities-index",
                     ok: true,
                     detail: "capabilities cache loaded",
-                });
+                }));
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            results.push({
+            results.push(makeCheck({
+                id: "graph.capability_cache",
                 name: "capabilities-index",
                 ok: false,
                 detail: message,
-            });
+                remediation: "Run `mdkg index` to rebuild generated capability caches.",
+            }));
         }
     }
-    const failures = results.filter((result) => !result.ok);
+    const finalResults = applyStrict(results, strict);
+    const publicResults = finalResults.map(publicCheck);
+    const summary = {
+        ok: finalResults.every((result) => result.ok),
+        errors: finalResults.filter((result) => result.severity === "error").length,
+        warnings: finalResults.filter((result) => result.severity === "warning").length,
+        infos: finalResults.filter((result) => result.severity === "info").length,
+    };
+    const failures = finalResults.filter((result) => !result.ok);
     if (options.json) {
         const payload = {
+            action: "doctor",
             ok: failures.length === 0,
-            checks: results,
+            strict,
+            checks: publicResults,
+            summary,
             failure_count: failures.length,
         };
         console.log(JSON.stringify(payload, null, 2));
     }
     else {
-        for (const result of results) {
+        for (const result of finalResults) {
             const prefix = result.ok ? result.level ?? "ok" : "fail";
             console.log(`${prefix}: ${result.name} - ${result.detail}`);
         }