@lmzhen/dsh-evolution-commands 0.3.54 → 0.3.56

package/lib/index.js

@@ -2,9 +2,186 @@ import { createRequire } from "node:module";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SkillLibrary, appendEvolutionEvent, buildLearnPrompt, clampedNumber, composePresetComposition, eventsFile, evolutionRoot, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
 import { buildEnrichment, buildMaintainFacts, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+//#region lib/types/doctor.js
+/**
+* `/evolution doctor` — read-only self-check (0.3.55, WB2).
+*
+* Turns "what the README would explain" into "the tool tells you directly":
+* install form, three-way conflict detection (all/host/preset + layered), the
+* environment surfaces that bit us before (v10 P2-12/13), and which evolution
+* services are actually mounted in this runtime. Always ends with suggested
+* actions so any finding carries its next step.
+*/
+/** Profile bundle rows for evolution-family packages across all profiles. */
+function collectEvolutionBundles(home) {
+	const profilesDir = join(home, "profiles");
+	if (!existsSync(profilesDir)) return [];
+	const bundles = [];
+	for (const profile of readdirSync(profilesDir, { withFileTypes: true })) {
+		if (!profile.isDirectory()) continue;
+		try {
+			const manifest = JSON.parse(readFileSync(join(profilesDir, profile.name, "package.json"), "utf8"));
+			for (const name of manifest.dsh?.profile?.bundles ?? []) if (/evolution-(all|host|preset)/.test(name)) bundles.push(name);
+		} catch {}
+	}
+	return bundles;
+}
+const SESSION_QUERY_MODES = new Set([
+	"startup",
+	"first-search",
+	"never"
+]);
+function envIssues() {
+	const issues = [];
+	const query = process.env.DSH_EVOLUTION_SESSION_QUERY;
+	if (query && !SESSION_QUERY_MODES.has(query)) issues.push(`DSH_EVOLUTION_SESSION_QUERY="${query}" is not one of startup|first-search|never — the patch normalizes it to 'startup' silently; set it to a listed mode.`);
+	return issues;
+}
+/**
+* Diagnose the deployment. `ctx` supplies service presence (a bare stub with
+* only `get` is enough); `home` defaults to the evolution root so tests can
+* point doctor at a temp DSH_HOME.
+*/
+async function diagnose(ctx, options = {}) {
+	const home = options.home ?? evolutionRoot();
+	const bundles = collectEvolutionBundles(home);
+	const has = (name) => ctx.get(name) !== void 0;
+	const full = bundles.some((name) => /evolution-all/.test(name));
+	const host = bundles.some((name) => /evolution-host/.test(name));
+	const preset = bundles.some((name) => /evolution-preset/.test(name));
+	const presetDir = join(home, ".agent-presets", "evolution");
+	const layered = host && existsSync(presetDir);
+	const conflicts = [];
+	if (full && host) conflicts.push("evolution-all and evolution-host are installed together — the infra rows double-mount and startup fails loud. Keep ONE: remove the other bundle.");
+	if (full && preset) conflicts.push("evolution-all and evolution-preset are installed together — the infra rows double-mount. Keep ONE.");
+	if (host && preset) conflicts.push("evolution-host and evolution-preset are installed together — the infra rows double-mount. Keep ONE.");
+	if (full && layered) conflicts.push("evolution-all and the layered Evolution preset are both present — the model rows double-mount. Keep ONE (use layered without all, or drop the preset).");
+	const services = {
+		review: has("evolutionReview"),
+		curator: has("evolutionCurator"),
+		approval: has("evolutionApproval"),
+		skillUsage: has("skillUsage"),
+		io: has("evolutionIo")
+	};
+	let pendingCount = null;
+	const approvalService = ctx.get("evolutionApproval");
+	if (approvalService?.list) try {
+		const rows = await approvalService.list("pending");
+		pendingCount = Array.isArray(rows) ? rows.length : null;
+	} catch {
+		pendingCount = null;
+	}
+	const installForm = full ? "full" : preset ? "preset" : layered ? "layered" : host ? "host" : "none";
+	const actions = [];
+	if (conflicts.length > 0) actions.push("Resolve the conflict first: keep exactly one of evolution-all / evolution-host / evolution-preset / layered.");
+	else if (installForm === "none") actions.push("Install the default full bundle: dsh plugin --profile web add @lmzhen/dsh-evolution-all");
+	else if (installForm === "layered") actions.push("Model tools follow the Evolution preset per session; add @lmzhen/dsh-evolution-all instead if every session should have them.");
+	const env = envIssues();
+	if (env.length > 0) actions.push("Fix the DSH_EVOLUTION_* variable listed above.");
+	if (services.review && !services.curator) actions.push("Curator service is not mounted — automatic curation is off; verify the host/all bundle row set is complete.");
+	if (pendingCount === null && services.approval) actions.push("Approval service is mounted but pending listing failed — check the evolution state service.");
+	return {
+		installForm,
+		bundles,
+		conflicts,
+		envIssues: env,
+		services,
+		pendingCount,
+		actions
+	};
+}
+function renderDoctorText(report) {
+	const lines = [
+		`Evolution doctor — install form: ${report.installForm}`,
+		`bundles: ${report.bundles.length > 0 ? report.bundles.join(", ") : "(none)"}`,
+		`services: review=${report.services.review} curator=${report.services.curator} approval=${report.services.approval} skillUsage=${report.services.skillUsage} io=${report.services.io}`,
+		`pending: ${report.pendingCount === null ? "unknown" : report.pendingCount}`
+	];
+	if (report.conflicts.length > 0) lines.push("conflicts:", ...report.conflicts.map((line) => `  ! ${line}`));
+	if (report.envIssues.length > 0) lines.push("env:", ...report.envIssues.map((line) => `  ! ${line}`));
+	if (report.actions.length > 0) lines.push("next steps:", ...report.actions.map((line) => `  → ${line}`));
+	return lines.join("\n");
+}
+//#endregion
+//#region lib/types/registry.js
+const COMMAND_ENTRIES = [
+	{
+		usage: "pending [--detail]",
+		summary: "list staged evolution writes (--detail shows staged args)"
+	},
+	{
+		usage: "approve <id>",
+		summary: "replay an approved staged write through its runner"
+	},
+	{
+		usage: "reject <id>",
+		summary: "drop a staged write without running it"
+	},
+	{
+		usage: "doctor",
+		summary: "read-only self-check: install form, conflicts, env, services"
+	},
+	{
+		usage: "curator run|pause|resume|status|report|scope",
+		summary: "run one curation pass, control or inspect automatic curation"
+	},
+	{
+		usage: "mutations",
+		summary: "list skill-mutation audit records"
+	},
+	{
+		usage: "restore",
+		summary: "restore skills from the latest snapshot"
+	},
+	{
+		usage: "consolidate <target> <sources...>",
+		summary: "merge source skills into a target umbrella skill"
+	},
+	{
+		usage: "skill restore <name>",
+		summary: "restore one archived skill by name"
+	},
+	{
+		usage: "skills health",
+		summary: "structure-health verdicts for the skill library"
+	},
+	{
+		usage: "skills refresh",
+		summary: "drop the catalog caches and re-read the tree"
+	},
+	{
+		usage: "learn [request]",
+		summary: "send a learning request to this session"
+	},
+	{
+		usage: "maintain [--timeout=<ms> | --facts]",
+		summary: "run a maintenance scan (--facts: 0-token preview)"
+	},
+	{
+		usage: "preset install",
+		summary: "generate the Evolution agent preset into the user root"
+	},
+	{
+		usage: "restructure <name> \"<heading>\" <to_file>",
+		summary: "move a body section into a references/ file"
+	},
+	{
+		usage: "replay",
+		summary: "compare prompt-bundle replay for this session"
+	}
+];
+/** The input-declaration hint (single line, ` | `-separated). */
+function renderHint() {
+	return COMMAND_ENTRIES.map((entry) => entry.usage).join(" | ");
+}
+/** The bare `/evolution` help body (one line per subcommand). */
+function renderHelpText() {
+	return COMMAND_ENTRIES.map((entry) => `  ${entry.usage.padEnd(44)} ${entry.summary}`).join("\n");
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Human commands for the evolution family: /evolution learn|pending|curator|restore|consolidate|skills refresh.
@@ -23,7 +200,7 @@ function apply(ctx, rawConfig = {}) {
 			name: "evolution",
 			description: "Self-evolution status and approval controls",
 			recordInput: false,
-			input: { hint: "pending [--detail] | approve <id> | reject <id> | curator run|pause|resume|status|report|scope | mutations | restore | consolidate <target> <sources...> | skill restore <name> | skills health | skills refresh | learn [request] | maintain [--timeout=<ms> | --facts] | preset install | restructure <name> \"<heading>\" <to_file> | replay" },
+			input: { hint: renderHint() },
 			async handler(invocation) {
 				const input = invocation.rawInput?.trim() ?? "";
 				const ok = (text) => ({
@@ -51,7 +228,7 @@ function apply(ctx, rawConfig = {}) {
 					const id = input.slice(8).trim();
 					const result = approval ? await approval.approve(id) : {
 						ok: false,
-						message: "approval service not mounted"
+						message: "E-301: approval service not mounted. Next: the evolution-approval row ships with evolution-host/evolution-all — run /evolution doctor to see which services are mounted."
 					};
 					return result.ok ? ok(result.message) : err(result.message);
 				}
@@ -59,19 +236,19 @@ function apply(ctx, rawConfig = {}) {
 					const id = input.slice(7).trim();
 					const result = approval ? await approval.reject(id) : {
 						ok: false,
-						message: "approval service not mounted"
+						message: "E-301: approval service not mounted. Next: the evolution-approval row ships with evolution-host/evolution-all — run /evolution doctor to see which services are mounted."
 					};
 					return result.ok ? ok(result.message) : err(result.message);
 				}
 				if (input === "curator run") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const result = await curator.run({ ignoreGates: true });
 					return ok(`Curator run complete: ${result.stale.length} stale, ${result.archived.length} archived, ${result.errors.length} failed.\nrunId=${result.report.runId}${result.report.snapshotPath ? `\nsnapshot=${result.report.snapshotPath}` : ""}`);
 				}
 				if (input === "curator pause" || input === "curator resume") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const paused = input === "curator pause";
 					await curator.setPaused(paused);
 					const notPersisted = ctx.get("evolutionState") !== void 0 ? "" : "\nNOTE: no evolution state service is mounted — this setting is NOT persisted and will not survive this process.";
@@ -79,7 +256,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				if (input === "curator status") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const state = await curator.status();
 					if (!state) return ok("No curator state yet: the first automatic pass is deferred until the interval elapses.");
 					const lastRun = typeof state.lastRunAt === "number" && Number.isFinite(state.lastRunAt) && state.lastRunAt > 0 ? new Date(state.lastRunAt).toISOString() : "unknown";
@@ -92,7 +269,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				if (input === "mutations") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const records = await curator.skills.listMutations();
 					const usable = Array.isArray(records) ? records.filter((row) => typeof row === "object" && row !== null && typeof row.at === "string" && typeof row.skillName === "string" && typeof row.action === "string" && typeof row.summary === "string") : [];
 					if (usable.length === 0) return ok("No mutation records yet.");
@@ -101,7 +278,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				if (input === "curator scope") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const view = await curator.scopeView();
 					const line = (label, names) => `${label}: ${names.length}${names.length === 0 ? "" : `\n  ${names.join(", ")}`}`;
 					return ok([
@@ -115,7 +292,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				if (input === "curator report") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const report = await curator.latestReport();
 					if (!report) return ok("No curator report available.");
 					if (typeof report !== "object" || typeof report.runId !== "string" || typeof report.startedAt !== "string" || !Array.isArray(report.archived) || !Array.isArray(report.failed)) return err("Report file unreadable.");
@@ -133,7 +310,7 @@ function apply(ctx, rawConfig = {}) {
 					const curator = ctx.get("evolutionCurator");
 					const result = curator ? await curator.restoreSnapshot() : {
 						ok: false,
-						message: "Curator service not mounted."
+						message: "E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor."
 					};
 					return result.ok ? ok(result.message) : err(result.message);
 				}
@@ -145,7 +322,7 @@ function apply(ctx, rawConfig = {}) {
 					const curator = ctx.get("evolutionCurator");
 					const result = curator ? await curator.consolidate(target, sources) : {
 						ok: false,
-						message: "Curator service not mounted."
+						message: "E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor."
 					};
 					if (!result.ok) return err(result.message);
 					return ok(planRunId ? `${result.message}\n[audit] plan=${planRunId}` : result.message);
@@ -156,13 +333,13 @@ function apply(ctx, rawConfig = {}) {
 					const curator = ctx.get("evolutionCurator");
 					const result = curator ? await curator.restore(name) : {
 						ok: false,
-						message: "Curator service not mounted."
+						message: "E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor."
 					};
 					return result.ok ? ok(result.message) : err(result.message);
 				}
 				if (input === "skills health") {
 					const curator = ctx.get("evolutionCurator");
-					if (!curator) return err("Curator service not mounted.");
+					if (!curator) return err("E-302: curator service not mounted. Next: mount the evolution-curator row (evolution-host/evolution-all) and run /evolution doctor.");
 					const [rows, observed] = await Promise.all([curator.healthView(), curator.usageObserved()]);
 					const banner = observed ? "" : "Usage observation not yet established — churn (write-ghost) rows are suppressed.";
 					const line = (row) => `${row.verdict.padEnd(18)} ${row.name}${row.reasons.length > 0 ? ` — ${row.reasons.join("; ")}` : ""}`;
@@ -312,10 +489,15 @@ function apply(ctx, rawConfig = {}) {
 				}
 				if (input === "replay") {
 					const replay = ctx.get("evolutionReplay");
-					if (!replay) return err("Replay service not mounted.");
+					if (!replay) return err("E-303: replay service not mounted. Next: mount the evolution-replay row (evolution-host/evolution-all) and run /evolution doctor.");
 					return ok(replay.compare().report);
 				}
-				return ok("Evolution: memory, skills, review, curator. Use /evolution pending | approve <id> | reject <id> | curator run | curator status | curator pause | curator resume | curator report | curator scope | mutations | restore | consolidate <target> <source...> | skill restore <name> | skills health | skills refresh | learn [request] | maintain [--timeout=<ms> | --facts] | preset install | restructure <name> \"<heading>\" <to_file> | replay.");
+				if (input === "doctor" || input === "doctor --json") {
+					const report = await diagnose(ctx, { home: evolutionRoot() });
+					if (input === "doctor --json") return ok(JSON.stringify(report, null, 2));
+					return ok(renderDoctorText(report));
+				}
+				return ok(`Evolution: memory, skills, review, curator — self-evolution status, approval and maintenance.\n${renderHelpText()}`);
 			}
 		}));
 	});

package/lib/types/doctor.d.ts

@@ -0,0 +1,29 @@
+export interface DoctorReport {
+    installForm: 'full' | 'host' | 'preset' | 'layered' | 'none';
+    bundles: string[];
+    conflicts: string[];
+    envIssues: string[];
+    services: {
+        review: boolean;
+        curator: boolean;
+        approval: boolean;
+        skillUsage: boolean;
+        io: boolean;
+    };
+    pendingCount: number | null;
+    actions: string[];
+}
+/** Profile bundle rows for evolution-family packages across all profiles. */
+export declare function collectEvolutionBundles(home: string): string[];
+/**
+ * Diagnose the deployment. `ctx` supplies service presence (a bare stub with
+ * only `get` is enough); `home` defaults to the evolution root so tests can
+ * point doctor at a temp DSH_HOME.
+ */
+export declare function diagnose(ctx: {
+    get(name: string): unknown;
+}, options?: {
+    home?: string;
+}): Promise<DoctorReport>;
+export declare function renderDoctorText(report: DoctorReport): string;
+//# sourceMappingURL=doctor.d.ts.map

package/lib/types/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Subcommand registry — the SINGLE SOURCE for the /evolution command surface.
+ *
+ * 0.3.55 (WD1): the input-declaration hint, the bare `/evolution` help output
+ * and the README command table all render FROM this table; a hand-written
+ * copy anywhere is drift waiting to happen (v10 R-13 proved it once).
+ * Keep `usage` in the exact shape a user can type after `/evolution`.
+ */
+export interface CommandEntry {
+    /** The subcommand as typed after `/evolution`. Variants use `|` (curator run|pause). */
+    usage: string;
+    /** One-line purpose rendered in the help output. */
+    summary: string;
+}
+export declare const COMMAND_ENTRIES: CommandEntry[];
+/** The input-declaration hint (single line, ` | `-separated). */
+export declare function renderHint(): string;
+/** The bare `/evolution` help body (one line per subcommand). */
+export declare function renderHelpText(): string;
+/** Markdown command table fragment for README surfaces (T-WD2 pins it).
+ * `|` inside a usage (curator run|pause|…) is escaped for the table cell. */
+export declare function renderCommandTable(): string;
+//# sourceMappingURL=registry.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
-  "description": "Human commands for the evolution family (community build)",
-  "version": "0.3.54",
+  "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
+  "version": "0.3.56",
   "publishConfig": {
     "access": "public"
   },
@@ -30,12 +30,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@lmzhen/dsh-evolution-approval": "^0.3.54",
-    "@lmzhen/dsh-evolution-core": "^0.3.54",
-    "@lmzhen/dsh-evolution-maintenance": "^0.3.54"
+    "@lmzhen/dsh-evolution-approval": "^0.3.56",
+    "@lmzhen/dsh-evolution-core": "^0.3.56",
+    "@lmzhen/dsh-evolution-maintenance": "^0.3.56"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.3.54"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.3.56"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",