pi-jev-wiki 0.2.0

package/src/config.ts

@@ -0,0 +1,168 @@
+/**
+ * Configuration for jev-wiki.
+ *
+ * Precedence: CLI overrides > process env > project .env > project config > global config > defaults.
+ * The API key is resolved from `apiKey` (`$VAR` indirection) with fallbacks to
+ * TYPESAFE_API_KEY and JEV_TOKEN.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type WriterMode = "guided" | "draft" | "auto";
+export type ReviewMode = "agent" | "human";
+
+export interface ProviderPreset {
+	baseUrl: string;
+	model: string;
+}
+
+export const PROVIDER_PRESETS: Record<string, ProviderPreset> = {
+	typesafe: { baseUrl: "https://api.typesafe.ai/v1/systemone", model: "jev-latest" },
+	openrouter: { baseUrl: "https://openrouter.ai/api/alpha/decisions", model: "~typesafe/jev-latest" },
+	aimlapi: { baseUrl: "https://api.aimlapi.com/v1/decisions", model: "typesafe/jev" },
+};
+
+export interface JevWikiConfig {
+	provider: string;
+	baseUrl?: string;
+	model?: string;
+	apiKey?: string;
+	envFile: string;
+	wikiRoot: string;
+	globalWikiRoot?: string;
+	stateRoot: string;
+	writer: { mode: WriterMode; model?: string | null };
+	routing: { shardSize: number; minFit: number; newPageConfidence: number };
+	review: { mode: ReviewMode; escalateCriticality: number; maxPerSession: number };
+	sync: { onSessionStart: "off" | "check"; onCommit: boolean; backstopLintDays: number };
+	thresholds: {
+		autoAccept: number;
+		minSupport: number;
+		minDerivable: number;
+		minNovelty: number;
+		minImportance: number;
+	};
+	weights: { grounded: number; importance: number; nonDerivable: number; authority: number };
+	toc: { maxTokens: number };
+	lint: { orphanMinAgeDays: number; duplicateSimilarity: number };
+	gitCommit: boolean;
+	capture: { onCompact: boolean; onSettle: boolean };
+	search: { engine: "index" | "bm25" | "qmd"; qmdCollection?: string };
+}
+
+export interface ResolvedConfig extends Omit<JevWikiConfig, "baseUrl" | "model"> {
+	baseUrl: string;
+	model: string;
+}
+
+export const DEFAULT_CONFIG: JevWikiConfig = {
+	provider: "typesafe",
+	envFile: ".env",
+	wikiRoot: "docs/wiki",
+	stateRoot: ".jev-wiki",
+	writer: { mode: "guided", model: null },
+	routing: { shardSize: 250, minFit: 0.6, newPageConfidence: 0.7 },
+	review: { mode: "agent", escalateCriticality: 0.85, maxPerSession: 10 },
+	sync: { onSessionStart: "check", onCommit: false, backstopLintDays: 14 },
+	thresholds: { autoAccept: 0.8, minSupport: 0.7, minDerivable: 0.5, minNovelty: 0.6, minImportance: 1 },
+	weights: { grounded: 0.45, importance: 0.25, nonDerivable: 0.2, authority: 0.1 },
+	toc: { maxTokens: 3000 },
+	lint: { orphanMinAgeDays: 7, duplicateSimilarity: 0.72 },
+	gitCommit: false,
+	capture: { onCompact: false, onSettle: false },
+	search: { engine: "index" },
+};
+
+export interface LoadedConfig {
+	cwd: string;
+	agentDir: string;
+	projectConfigPath: string;
+	globalConfigPath: string;
+	envFilePath: string;
+	env: Record<string, string>;
+	config: ResolvedConfig;
+	apiKey?: string;
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+	try {
+		if (!existsSync(path)) return undefined;
+		return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+	} catch {
+		return undefined;
+	}
+}
+
+export function parseEnvFile(text: string): Record<string, string> {
+	const env: Record<string, string> = {};
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		let value = line.slice(eq + 1).trim();
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+		if (key) env[key] = value;
+	}
+	return env;
+}
+
+function deepMerge<T>(base: T, patch: unknown): T {
+	if (patch === undefined || patch === null) return base;
+	if (Array.isArray(base) || typeof base !== "object") return patch as T;
+	if (typeof patch !== "object" || Array.isArray(patch)) return patch as T;
+	const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+		out[key] = deepMerge((base as Record<string, unknown>)[key], value);
+	}
+	return out as T;
+}
+
+function resolveEnvValue(value: string | undefined, env: Record<string, string>): string | undefined {
+	if (!value) return undefined;
+	if (!value.startsWith("$")) return value;
+	const name = value.slice(1);
+	return process.env[name] ?? env[name];
+}
+
+export function loadConfig(cwd: string, overrides?: Partial<JevWikiConfig>): LoadedConfig {
+	const agentDir = getAgentDir();
+	const globalConfigPath = join(agentDir, "jev-wiki.json");
+	const projectConfigPath = join(cwd, CONFIG_DIR_NAME, "jev-wiki.json");
+
+	const globalFile = readJson(globalConfigPath) ?? {};
+	const projectFile = readJson(projectConfigPath) ?? {};
+
+	let merged = deepMerge(DEFAULT_CONFIG, globalFile);
+	merged = deepMerge(merged, projectFile);
+	if (overrides) merged = deepMerge(merged, overrides);
+
+	const envFilePath = resolve(cwd, merged.envFile);
+	const env = existsSync(envFilePath) ? parseEnvFile(readFileSync(envFilePath, "utf8")) : {};
+
+	const preset = PROVIDER_PRESETS[merged.provider] ?? PROVIDER_PRESETS.typesafe;
+	const resolved: ResolvedConfig = {
+		...merged,
+		baseUrl: merged.baseUrl ?? preset.baseUrl,
+		model: merged.model ?? preset.model,
+	};
+
+	const configured = resolveEnvValue(merged.apiKey, env);
+	const providerVars: Record<string, string[]> = {
+		typesafe: ["TYPESAFE_API_KEY", "JEV_TOKEN"],
+		openrouter: ["OPENROUTER_API_KEY", "JEV_TOKEN", "TYPESAFE_API_KEY"],
+		aimlapi: ["AIMLAPI_API_KEY", "JEV_TOKEN"],
+	};
+	const candidates = providerVars[merged.provider] ?? ["JEV_TOKEN", "TYPESAFE_API_KEY", "OPENROUTER_API_KEY"];
+	let apiKey = configured;
+	for (const name of candidates) {
+		apiKey ??= process.env[name] ?? env[name];
+	}
+	apiKey ??= env.OPENROUTER_API_KEY ?? process.env.OPENROUTER_API_KEY;
+
+	return { cwd, agentDir, projectConfigPath, globalConfigPath, envFilePath, env, config: resolved, apiKey };
+}

package/src/doctor.ts

@@ -0,0 +1,171 @@
+/**
+ * Doctor: cheap, deterministic health checks for configuration, state, and
+ * environment. No model calls. Intended to be run before trusting a wiki or
+ * after moving it to a new machine/project.
+ */
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { LoadedConfig } from "./config.ts";
+import { git, headCommit, isGitRepo } from "./git.ts";
+import { readLedger } from "./ledger.ts";
+import { readReviews } from "./review.ts";
+import { readSyncState } from "./sync.ts";
+import { listMarkdownFiles, resolveLayout, type WikiLayout } from "./wiki/layout.ts";
+import { isLocked } from "./wiki/lock.ts";
+
+const run = promisify(execFile);
+
+export interface DoctorCheck {
+	name: string;
+	status: "ok" | "warn" | "fail";
+	detail: string;
+}
+
+export interface DoctorReport {
+	checks: DoctorCheck[];
+	summary: { ok: number; warn: number; fail: number };
+}
+
+function check(name: string, status: DoctorCheck["status"], detail: string): DoctorCheck {
+	return { name, status, detail };
+}
+
+function within(value: number, min: number, max: number): boolean {
+	return Number.isFinite(value) && value >= min && value <= max;
+}
+
+export async function runDoctor(loaded: LoadedConfig): Promise<DoctorReport> {
+	const checks: DoctorCheck[] = [];
+	const { config } = loaded;
+	const layout = resolveLayout(loaded.cwd, config.wikiRoot, config.stateRoot);
+
+	// --- configuration --------------------------------------------------------
+	const invalid: string[] = [];
+	for (const key of ["autoAccept", "minSupport", "minDerivable", "minNovelty"] as const) {
+		if (!within(config.thresholds[key], 0, 1)) invalid.push(`thresholds.${key}=${config.thresholds[key]}`);
+	}
+	if (config.thresholds.minImportance < 0 || config.thresholds.minImportance > 3) invalid.push(`thresholds.minImportance=${config.thresholds.minImportance}`);
+	if (!within(config.routing.minFit, 0, 1)) invalid.push(`routing.minFit=${config.routing.minFit}`);
+	if (!within(config.routing.newPageConfidence, 0, 1)) invalid.push(`routing.newPageConfidence=${config.routing.newPageConfidence}`);
+	if (!within(config.review.escalateCriticality, 0, 1)) invalid.push(`review.escalateCriticality=${config.review.escalateCriticality}`);
+	if (!within(config.lint.duplicateSimilarity, 0, 1)) invalid.push(`lint.duplicateSimilarity=${config.lint.duplicateSimilarity}`);
+	if (config.routing.shardSize < 10 || config.routing.shardSize > 255) invalid.push(`routing.shardSize=${config.routing.shardSize} (must be 10..255)`);
+	if (!["index", "bm25", "qmd"].includes(config.search.engine)) invalid.push(`search.engine=${config.search.engine}`);
+	checks.push(
+		invalid.length === 0
+			? check("config values", "ok", `provider ${config.provider}, writer ${config.writer.mode}, shard ${config.routing.shardSize}`)
+			: check("config values", "fail", `invalid: ${invalid.join(", ")}`),
+	);
+
+	let urlValid = false;
+	try {
+		const url = new URL(config.baseUrl);
+		urlValid = url.protocol === "https:" || url.protocol === "http:";
+	} catch {
+		urlValid = false;
+	}
+	checks.push(urlValid ? check("endpoint", "ok", config.baseUrl) : check("endpoint", "fail", `not a valid URL: ${config.baseUrl}`));
+	checks.push(
+		loaded.apiKey
+			? check("api key", "ok", `configured (${loaded.apiKey.slice(0, 5)}…, ${loaded.envFilePath})`)
+			: check(
+					"api key",
+					"fail",
+					`missing; run wiki_setup action=guide provider=typesafe|openrouter — or add TYPESAFE_API_KEY / OPENROUTER_API_KEY / JEV_TOKEN to ${loaded.envFilePath}`,
+				),
+	);
+	checks.push(
+		existsSync(loaded.envFilePath)
+			? check("env file", "ok", loaded.envFilePath)
+			: check("env file", "warn", `not found: ${loaded.envFilePath}`),
+	);
+
+	// --- layout and state -----------------------------------------------------
+	checks.push(
+		existsSync(layout.root)
+			? check("wiki root", "ok", layout.root)
+			: check("wiki root", "warn", `does not exist yet (created on first ingest): ${layout.root}`),
+	);
+	if (existsSync(layout.wikiDir)) {
+		const pages = (await listMarkdownFiles(layout.wikiDir)).length;
+		checks.push(check("wiki pages", "ok", `${pages} page file(s); index ${existsSync(`${layout.wikiDir}/index.md`) ? "present" : "MISSING"}, toc ${existsSync(`${layout.wikiDir}/toc.md`) ? "present" : "missing"}`));
+	}
+	const lock = await isLocked(layout);
+	if (lock.locked) {
+		checks.push(lock.stale ? check("wiki lock", "warn", `stale lock (${Math.round((lock.ageMs ?? 0) / 1000)}s old); next mutation takes it over`) : check("wiki lock", "warn", `held by another session (${Math.round((lock.ageMs ?? 0) / 1000)}s)`));
+	} else {
+		checks.push(check("wiki lock", "ok", "free"));
+	}
+
+	// --- ledger and queue -----------------------------------------------------
+	if (existsSync(layout.ledgerPath)) {
+		let bad = 0;
+		const lines = (await readFile(layout.ledgerPath, "utf8")).split(/\r?\n/).filter(Boolean);
+		for (const line of lines) {
+			try {
+				JSON.parse(line);
+			} catch {
+				bad++;
+			}
+		}
+		checks.push(bad === 0 ? check("ledger", "ok", `${lines.length} entries, all parse`) : check("ledger", "warn", `${bad} unparsable line(s) of ${lines.length}`));
+	} else {
+		checks.push(check("ledger", "ok", "no ledger yet"));
+	}
+	const reviews = await readReviews(layout);
+	const open = reviews.filter((item) => item.status === "open");
+	if (open.length > 10) {
+		const oldest = open.reduce((oldestDate, item) => (item.ts < oldestDate ? item.ts : oldestDate), open[0].ts);
+		checks.push(check("review queue", "warn", `${open.length} open items; oldest ${oldest.slice(0, 10)} — consider /wiki:review`));
+	} else {
+		checks.push(check("review queue", "ok", `${open.length} open item(s)`));
+	}
+
+	// --- git and sync ---------------------------------------------------------
+	if (await isGitRepo(loaded.cwd)) {
+		const head = await headCommit(loaded.cwd);
+		const state = await readSyncState(layout);
+		if (!state.lastSyncCommit) {
+			checks.push(check("sync baseline", "warn", `not initialized; run wiki_sync to set it at ${head?.slice(0, 7)}`));
+		} else if (state.lastSyncCommit === head) {
+			checks.push(check("sync baseline", "ok", `current at ${head?.slice(0, 7)}`));
+		} else {
+			const behind = await git(loaded.cwd, ["rev-list", "--count", `${state.lastSyncCommit}..HEAD`]);
+			checks.push(check("sync baseline", "warn", `${behind.stdout.trim() || "?"} commit(s) behind; run /wiki:sync`));
+		}
+		if (existsSync(loaded.envFilePath)) {
+			const ignored = await git(loaded.cwd, ["check-ignore", "-q", loaded.envFilePath]);
+			checks.push(ignored.code === 0 ? check("env gitignored", "ok", ".env is ignored") : check("env gitignored", "fail", `${loaded.envFilePath} is NOT gitignored — the token could be committed`));
+		}
+	} else {
+		checks.push(check("git", "warn", "not a repository; change-driven sync and commits are unavailable"));
+	}
+
+	// --- search ---------------------------------------------------------------
+	if (config.search.engine === "qmd") {
+		try {
+			await run("qmd", ["--version"], { timeout: 5000 });
+			checks.push(check("search engine", "ok", "qmd available"));
+		} catch {
+			checks.push(check("search engine", "warn", "search.engine=qmd but the qmd binary is not available; BM25 fallback will be used"));
+		}
+	} else {
+		checks.push(check("search engine", "ok", config.search.engine));
+	}
+
+	const summary = {
+		ok: checks.filter((item) => item.status === "ok").length,
+		warn: checks.filter((item) => item.status === "warn").length,
+		fail: checks.filter((item) => item.status === "fail").length,
+	};
+	return { checks, summary };
+}
+
+export function renderDoctor(report: DoctorReport): string {
+	const icon = { ok: "✅", warn: "⚠️", fail: "❌" } as const;
+	const lines = [`# Wiki doctor — ${report.summary.ok} ok · ${report.summary.warn} warn · ${report.summary.fail} fail`, ""];
+	for (const item of report.checks) lines.push(`${icon[item.status]} **${item.name}** — ${item.detail}`);
+	return lines.join("\n");
+}