@astrosheep/pi-context 0.22.0 → 0.22.1

package/README.md

@@ -59,6 +59,10 @@ The dreamer model is configured under the same key. `--dreamer <model pattern>`
 }
 ```
 
+## Check the notes store
+
+Run `dream doctor` (or `dream doctor --notes-home <dir>`) to check home layout, note frontmatter, concrete backtick-quoted note addresses, MAP entries, and lock presence/format. It is read-only: no model, git commits, directory creation, or repairs. Exit status is 0 when clean and 1 when issues are found. References needing an unavailable project context are reported as unresolved; prose and example/glob addresses are not validated. A present lock is reported without inferring process liveness.
+
 ## The dream lock
 
 The `dream` CLI takes an exclusive `.dream.lock` in the notes home with a single O_CREAT|O_EXCL creation. The lock is Git-style existence locking: an existing lock refuses a new run regardless of its contents, PID, or age, and `--force` bypasses only the scheduling and material gates, never the lock. A lock is released only by the run that acquired it (and repeated cleanup is harmless), so a live dream is never displaced.

package/dist/src/dream/cli.js

@@ -7,6 +7,7 @@ import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer } from "./runner.js";
 import { gitCommit } from "./git.js";
 import { readDreamerSettings } from "../thresholds.js";
+import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -67,9 +68,20 @@ function finishDream(home, stamp, reportPath, failed, body, writes) {
     return failed || !audit.ok || reportError !== undefined ? 1 : 0;
 }
 export async function main(argv = process.argv.slice(2), deps = {}) {
+    if (argv[0] === "doctor") {
+        const options = args(argv.slice(1));
+        if (options.help) {
+            console.log("dream doctor [--notes-home <dir>] — read-only diagnostics; no model or repairs");
+            return 0;
+        }
+        const home = resolve(String(options["notes-home"] ?? notesRoot()));
+        const issues = doctor(home);
+        console.log(issues.length ? issues.join("\n") : `dream doctor: OK (${home})`);
+        return issues.length ? 1 : 0;
+    }
     const a = args(argv);
     if (a.help) {
-        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
+        console.log("dream doctor [--notes-home <dir>] — read-only diagnostics\ndream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
         return 0;
     }
     const home = resolve(String(a["notes-home"] ?? notesRoot()));

package/dist/src/dream/doctor.js

@@ -0,0 +1,138 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { assertAddress } from "../notes/address.js";
+/** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
+export function doctor(home) {
+    const issues = [];
+    const report = (path, message) => issues.push(`${relative(home, path) || "."}: ${message}`);
+    const inspect = (path, action) => {
+        try {
+            action();
+        }
+        catch (error) {
+            report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const directory = (path) => {
+        const stat = lstatSync(path);
+        if (stat.isDirectory())
+            return true;
+        report(path, "expected a directory (symlinks are not followed); check its location/type");
+        return false;
+    };
+    const checkNote = (path, root, project) => {
+        const raw = readFileSync(path, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+        if (!match) {
+            report(path, "missing or unclosed frontmatter; add a valid metadata block");
+            return;
+        }
+        const fields = new Map();
+        for (const line of match[1].split(/\r?\n/)) {
+            const field = /^([\w]+):\s*(.*?)\s*$/.exec(line);
+            if (!field)
+                continue;
+            if (fields.has(field[1]))
+                report(path, `duplicate metadata key ${field[1]}; keep one value`);
+            fields.set(field[1], field[2].replace(/^(["'])(.*)\1$/, "$2"));
+        }
+        for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+            if (!valid.test(fields.get(key) ?? ""))
+                report(path, `missing/invalid ${key}; repair frontmatter`);
+        }
+        for (const key of ["created_at", "updated_at", "last_accessed"]) {
+            const value = fields.get(key);
+            if (!value || !Number.isFinite(Date.parse(value)))
+                report(path, `missing/invalid ${key}; use an ISO timestamp`);
+        }
+        if (fields.has("scope"))
+            report(path, "obsolete scope field; remove it (home determines scope)");
+        // Check concrete, code-formatted addresses; examples/globs and prose are not links.
+        for (const link of raw.slice(match[0].length).matchAll(/`([^`\n]+)`/g)) {
+            const address = link[1];
+            if (!address.endsWith(".md") || /[<>*?\s]/.test(address))
+                continue;
+            if (!address.startsWith("@") && basename(path) !== "MAP.md")
+                continue;
+            try {
+                const parsed = assertAddress(address);
+                const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+                if (!targetHome) {
+                    report(path, `${address}: project context unavailable; use a resolvable reference`);
+                    continue;
+                }
+                if (!existsSync(join(targetHome, parsed.path)))
+                    report(path, `${address}: target missing; update or remove the reference`);
+            }
+            catch {
+                report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`);
+            }
+        }
+    };
+    const walk = (dir, root, project) => {
+        for (const name of readdirSync(dir)) {
+            const path = join(dir, name);
+            inspect(path, () => {
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    report(path, "symlink not inspected; replace with a regular note/directory");
+                else if (stat.isDirectory())
+                    walk(path, root, project);
+                else if (stat.isFile() && name.endsWith(".md"))
+                    checkNote(path, root, project);
+                else
+                    report(path, "unexpected file in note home; inspect and relocate it");
+            });
+        }
+    };
+    inspect(home, () => {
+        if (!directory(home))
+            return;
+        for (const name of readdirSync(home)) {
+            const path = join(home, name);
+            inspect(path, () => {
+                if (name === "global") {
+                    report(path, "legacy home; manually migrate to personal/ without overwriting existing files");
+                    return;
+                }
+                if (name === ".dream.lock") {
+                    const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
+                    report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
+                    return;
+                }
+                if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name))
+                    return;
+                if (name === "personal") {
+                    if (directory(path))
+                        walk(path, path);
+                    return;
+                }
+                if (name === "project" || name === "pi") {
+                    if (!directory(path))
+                        return;
+                    const homes = name === "pi" ? join(path, "session") : path;
+                    if (name === "pi") {
+                        for (const entry of readdirSync(path))
+                            if (entry !== "session")
+                                report(join(path, entry), "unexpected directory; expected pi/session/<id>/");
+                        if (!existsSync(homes) || !directory(homes))
+                            return;
+                    }
+                    for (const id of readdirSync(homes)) {
+                        const root = join(homes, id);
+                        inspect(root, () => {
+                            if (!directory(root))
+                                return;
+                            if (name === "project" && !/^.+-[\da-f]{8}$/.test(id))
+                                report(root, "invalid project key; expected <name>-<8 hex>");
+                            walk(root, root, name === "project" ? root : undefined);
+                        });
+                    }
+                    return;
+                }
+                report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+            });
+        }
+    });
+    return issues;
+}

package/dist/test/doctor.test.js

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { doctor } from "../src/dream/doctor.js";
+import { main } from "../src/dream/cli.js";
+const note = (body = "") => `---\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\nlast_accessed: 2026-01-01T00:00:00Z\naccess_count: 0\n---\n\n${body}`;
+const home = () => mkdtempSync(join(tmpdir(), "dream-doctor-"));
+test("doctor validates note homes and references without changing files", async () => {
+    const root = home();
+    mkdirSync(join(root, "personal"));
+    writeFileSync(join(root, "personal/a.md"), note());
+    writeFileSync(join(root, "personal/MAP.md"), note("- `a.md`\n- `@personal/a.md`"));
+    const before = readFileSync(join(root, "personal/a.md"));
+    assert.deepEqual(doctor(root), []);
+    assert.equal(await main(["doctor", "--notes-home", root], { runDreamer: async () => { throw new Error("must not run"); } }), 0);
+    assert.deepEqual(readFileSync(join(root, "personal/a.md")), before);
+    assert.deepEqual(readdirSync(root), ["personal"]);
+});
+test("doctor reports layout, metadata, links and locks; never repairs", () => {
+    const root = home();
+    mkdirSync(join(root, "global"));
+    mkdirSync(join(root, "project/bad"), { recursive: true });
+    writeFileSync(join(root, "project/bad/MAP.md"), note("`missing.md` `@global/old.md`"));
+    writeFileSync(join(root, "project/bad/broken.md"), "---\norigin: nope\n---\n");
+    writeFileSync(join(root, ".dream.lock"), "garbage");
+    symlinkSync(join(root, "project"), join(root, "project/bad/link"));
+    const output = doctor(root).join("\n");
+    for (const expected of ["legacy home", "invalid project key", "target missing", "invalid address", "invalid origin", "invalid created_at", "malformed lock", "symlink"])
+        assert.ok(output.includes(expected), expected);
+    assert.equal(readFileSync(join(root, ".dream.lock"), "utf8"), "garbage");
+    assert.ok(existsSync(join(root, "global")));
+});
+test("doctor reports missing homes without creating them, including CLI", async () => {
+    const missing = join(home(), "absent");
+    assert.equal(await main(["doctor", "--notes-home", missing]), 1);
+    assert.equal(existsSync(missing), false);
+});
+test("doctor reports valid lock presence without claiming it is stale", () => {
+    const root = home();
+    writeFileSync(join(root, ".dream.lock"), "123 12345678-1234-1234-1234-123456789abc");
+    assert.match(doctor(root).join("\n"), /lock present.*liveness not inferred/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/dream/cli.ts

@@ -7,6 +7,7 @@ import { materialGate, timeGate } from "./gates.js";
 import { loadPlaybook, runDreamer, type DreamerSessionFactory, type DreamResult, type DreamWrite } from "./runner.js";
 import { gitCommit } from "./git.js";
 import { readDreamerSettings, type DreamerSetting } from "../thresholds.js";
+import { doctor } from "./doctor.js";
 import { notesRoot } from "../notes/paths.js";
 
 function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
@@ -55,7 +56,15 @@ function finishDream(home: string, stamp: string, reportPath: string, failed: bo
 }
 
 export async function main(argv = process.argv.slice(2), deps: DreamDependencies = {}): Promise<number> {
-	const a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
+	if (argv[0] === "doctor") {
+		const options = args(argv.slice(1));
+		if (options.help) { console.log("dream doctor [--notes-home <dir>] — read-only diagnostics; no model or repairs"); return 0; }
+		const home = resolve(String(options["notes-home"] ?? notesRoot()));
+		const issues = doctor(home);
+		console.log(issues.length ? issues.join("\n") : `dream doctor: OK (${home})`);
+		return issues.length ? 1 : 0;
+	}
+	const a = args(argv); if (a.help) { console.log("dream doctor [--notes-home <dir>] — read-only diagnostics\ndream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDreamer model: --dreamer wins, else pi-context.dreamer from settings, else the automatic model. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
 	const home = resolve(String(a["notes-home"] ?? notesRoot())); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
 	const lockPath = join(home, ".dream.lock"); const stampPath = lastRunPath(lockPath);
 	const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);

package/src/dream/doctor.ts

@@ -0,0 +1,97 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { assertAddress } from "../notes/address.js";
+
+/** Read-only diagnostics. Never follows symlinks or acquires/removes a dream lock. */
+export function doctor(home: string): string[] {
+	const issues: string[] = [];
+	const report = (path: string, message: string) => issues.push(`${relative(home, path) || "."}: ${message}`);
+	const inspect = (path: string, action: () => void) => {
+		try { action(); } catch (error) { report(path, `cannot inspect: ${error instanceof Error ? error.message : String(error)}`); }
+	};
+	const directory = (path: string): boolean => {
+		const stat = lstatSync(path);
+		if (stat.isDirectory()) return true;
+		report(path, "expected a directory (symlinks are not followed); check its location/type");
+		return false;
+	};
+	const checkNote = (path: string, root: string, project?: string) => {
+		const raw = readFileSync(path, "utf8");
+		const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+		if (!match) { report(path, "missing or unclosed frontmatter; add a valid metadata block"); return; }
+		const fields = new Map<string, string>();
+		for (const line of match[1]!.split(/\r?\n/)) {
+			const field = /^([\w]+):\s*(.*?)\s*$/.exec(line);
+			if (!field) continue;
+			if (fields.has(field[1]!)) report(path, `duplicate metadata key ${field[1]}; keep one value`);
+			fields.set(field[1]!, field[2]!.replace(/^(["'])(.*)\1$/, "$2"));
+		}
+		for (const [key, valid] of Object.entries({ origin: /^(user|self|external)$/, status: /^(active|superseded|pending|archived)$/, stale: /^(true|false)$/, access_count: /^\d+$/ })) {
+			if (!valid.test(fields.get(key) ?? "")) report(path, `missing/invalid ${key}; repair frontmatter`);
+		}
+		for (const key of ["created_at", "updated_at", "last_accessed"]) {
+			const value = fields.get(key);
+			if (!value || !Number.isFinite(Date.parse(value))) report(path, `missing/invalid ${key}; use an ISO timestamp`);
+		}
+		if (fields.has("scope")) report(path, "obsolete scope field; remove it (home determines scope)");
+		// Check concrete, code-formatted addresses; examples/globs and prose are not links.
+		for (const link of raw.slice(match[0].length).matchAll(/`([^`\n]+)`/g)) {
+			const address = link[1]!;
+			if (!address.endsWith(".md") || /[<>*?\s]/.test(address)) continue;
+			if (!address.startsWith("@") && basename(path) !== "MAP.md") continue;
+			try {
+				const parsed = assertAddress(address);
+				const targetHome = parsed.scope === "personal" ? join(home, "personal") : parsed.scope === "project" ? project : root;
+				if (!targetHome) { report(path, `${address}: project context unavailable; use a resolvable reference`); continue; }
+				if (!existsSync(join(targetHome, parsed.path))) report(path, `${address}: target missing; update or remove the reference`);
+			} catch { report(path, `${address}: invalid address; use bare, @project/ or @personal/ addresses`); }
+		}
+	};
+	const walk = (dir: string, root: string, project?: string) => {
+		for (const name of readdirSync(dir)) {
+			const path = join(dir, name);
+			inspect(path, () => {
+				const stat = lstatSync(path);
+				if (stat.isSymbolicLink()) report(path, "symlink not inspected; replace with a regular note/directory");
+				else if (stat.isDirectory()) walk(path, root, project);
+				else if (stat.isFile() && name.endsWith(".md")) checkNote(path, root, project);
+				else report(path, "unexpected file in note home; inspect and relocate it");
+			});
+		}
+	};
+	inspect(home, () => {
+		if (!directory(home)) return;
+		for (const name of readdirSync(home)) {
+			const path = join(home, name);
+			inspect(path, () => {
+				if (name === "global") { report(path, "legacy home; manually migrate to personal/ without overwriting existing files"); return; }
+				if (name === ".dream.lock") {
+					const valid = lstatSync(path).isFile() && /^[1-9]\d* [\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}\s*$/i.test(readFileSync(path, "utf8"));
+					report(path, `${valid ? "lock present" : "malformed lock"}; verify no dream is running before manual removal; liveness not inferred`);
+					return;
+				}
+				if ([".git", "dreams", "snapshots", "trash", ".dream.lock.last-run"].includes(name)) return;
+				if (name === "personal") { if (directory(path)) walk(path, path); return; }
+				if (name === "project" || name === "pi") {
+					if (!directory(path)) return;
+					const homes = name === "pi" ? join(path, "session") : path;
+					if (name === "pi") {
+						for (const entry of readdirSync(path)) if (entry !== "session") report(join(path, entry), "unexpected directory; expected pi/session/<id>/");
+						if (!existsSync(homes) || !directory(homes)) return;
+					}
+					for (const id of readdirSync(homes)) {
+						const root = join(homes, id);
+						inspect(root, () => {
+							if (!directory(root)) return;
+							if (name === "project" && !/^.+-[\da-f]{8}$/.test(id)) report(root, "invalid project key; expected <name>-<8 hex>");
+							walk(root, root, name === "project" ? root : undefined);
+						});
+					}
+					return;
+				}
+				report(path, "unexpected root entry; expected personal/, project/, pi/session/ or dream artifacts");
+			});
+		}
+	});
+	return issues;
+}