@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/cli/doctor/report.ts

@@ -0,0 +1,176 @@
+import type { DoctorCheck, DoctorMode, DoctorRepair, DoctorReport, DoctorSummary, JsonValue, Verdict } from "./types";
+
+export const DOCTOR_EXIT_CODES = {
+	ok: 0,
+	findings: 1,
+	usage: 2,
+	incomplete: 3,
+	mutationFailure: 4,
+	interrupted: 130,
+} as const;
+export interface FinalizeInput {
+	readonly schemaVersion?: 1;
+	readonly runId: string;
+	readonly mode: DoctorMode;
+	readonly generatedAt: string;
+	readonly durationMs: number;
+	readonly subject: DoctorReport["subject"];
+	readonly selection: DoctorReport["selection"];
+	readonly coverage: DoctorReport["coverage"];
+	readonly checks: readonly DoctorCheck[];
+	readonly repairs?: readonly DoctorRepair[];
+	readonly limits?: DoctorReport["limits"];
+	readonly invocationError?: string;
+	readonly interrupted?: boolean;
+}
+function sanitize(value: unknown, depth = 0): unknown {
+	if (depth > 4) return "[bounded]";
+	if (typeof value === "string") return value.replace(/[\u0000-\u001f\u007f]/g, "?").slice(0, 512);
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return value;
+	if (Array.isArray(value)) return value.slice(0, 100).map(item => sanitize(item, depth + 1));
+	if (typeof value === "object" && value !== null) {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value).slice(0, 100)) {
+			out[k] = sanitize(v, depth + 1);
+		}
+		return out;
+	}
+	return "[omitted]";
+}
+const EVIDENCE_KEYS = new Set([
+	"runtimeVersion",
+	"platform",
+	"arch",
+	"channel",
+	"schemaCoverage",
+	"startupStatus",
+	"runtimeProbed",
+	"aclCoverage",
+	"mode",
+	"ownerMatches",
+	"contentsRead",
+	"authenticationProbed",
+	"present",
+	"errno",
+	"schemaLocation",
+	"enabled",
+	"counts",
+	"fileKind",
+	"version",
+	"integrityResult",
+	"processObservation",
+	"generation",
+	"occupancy",
+	"readiness",
+	"rootId",
+	"safeLabel",
+	"candidateCount",
+	"autoload",
+	"hasAuth",
+	"status",
+	"sourceClass",
+	"artifactStatus",
+	"transport",
+	"count",
+	"warningCount",
+]);
+function sanitizeEvidence(value: DoctorCheck["evidence"]): DoctorCheck["evidence"] {
+	const filtered: Record<string, JsonValue> = {};
+	for (const [key, raw] of Object.entries(value))
+		if (EVIDENCE_KEYS.has(key)) filtered[key] = sanitize(raw) as JsonValue;
+	return filtered;
+}
+export function finalizeReport(input: FinalizeInput): DoctorReport {
+	const checks = input.checks.map(check => ({ ...check, evidence: sanitizeEvidence(check.evidence) }));
+	const repairs = (input.repairs ?? []).map(repair => ({
+		...repair,
+		candidates: repair.candidates.map(candidate => ({
+			...candidate,
+			evidence: sanitizeEvidence(candidate.evidence),
+		})),
+	}));
+	const presentCheckIds = new Set(checks.map(check => check.id));
+	const historicalCheckIds = new Set(
+		repairs
+			.filter(repair => repair.afterCheckIds.length > 0 && repair.afterCheckIds.every(id => presentCheckIds.has(id)))
+			.flatMap(repair => repair.beforeCheckIds),
+	);
+	const currentChecks = checks.filter(check => !historicalCheckIds.has(check.id));
+	let verdict: Verdict = "healthy";
+	if (input.interrupted) verdict = "inconclusive";
+	else if (
+		currentChecks.some(
+			check =>
+				check.execution === "timeout" ||
+				check.execution === "blocked" ||
+				check.execution === "unsupported" ||
+				check.health === "unknown",
+		)
+	)
+		verdict = "inconclusive";
+	else if (currentChecks.some(check => check.health === "error")) verdict = "unhealthy";
+	else if (currentChecks.some(check => check.health === "warning")) verdict = "degraded";
+	const mutationFailure =
+		input.mode === "fix" &&
+		repairs.some(repair => {
+			if (repair.state === "verified" || repair.state === "not_needed") return false;
+			if (repair.sideEffectStarted === true) return true;
+			// Physical states establish effects even when an adapter incorrectly supplies a negative flag.
+			return ["pending_activation", "uncertain", "rolled_back", "rollback_conflict"].includes(repair.state);
+		});
+	if (mutationFailure) verdict = "inconclusive";
+	const incomplete = input.coverage.timedOut > 0 || input.coverage.blocked > 0 || input.coverage.unsupported > 0;
+	const readinessBlocked =
+		input.mode === "fix" && repairs.some(repair => repair.state !== "verified" && repair.state !== "not_needed");
+	const exitCode = input.interrupted
+		? DOCTOR_EXIT_CODES.interrupted
+		: input.invocationError
+			? DOCTOR_EXIT_CODES.usage
+			: mutationFailure
+				? DOCTOR_EXIT_CODES.mutationFailure
+				: incomplete || verdict === "inconclusive" || readinessBlocked
+					? DOCTOR_EXIT_CODES.incomplete
+					: verdict === "unhealthy"
+						? DOCTOR_EXIT_CODES.findings
+						: DOCTOR_EXIT_CODES.ok;
+	const summary: DoctorSummary = { verdict, exitCode };
+	return {
+		schemaVersion: 1,
+		command: "doctor",
+		runId: input.runId,
+		mode: input.mode,
+		generatedAt: input.generatedAt,
+		durationMs: input.durationMs,
+		subject: input.subject,
+		selection: input.selection,
+		coverage: input.coverage,
+		summary,
+		checks,
+		repairs,
+		limits: input.limits ?? ({} as DoctorReport["limits"]),
+		invocationError: input.invocationError,
+	};
+}
+export function renderDoctorJson(report: DoctorReport): string {
+	return `${JSON.stringify(report)}\n`;
+}
+export function renderDoctorText(report: DoctorReport): string {
+	const lines = [
+		`gjc doctor (${report.mode})`,
+		`verdict: ${report.summary.verdict}`,
+		`exit: ${report.summary.exitCode}`,
+		`checks: ${report.checks.length}`,
+		`repairs: ${report.repairs.length}`,
+	];
+	for (const check of report.checks) {
+		lines.push(`- ${check.id}: ${check.health} (${check.execution})`);
+		lines.push(`  target: ${check.targetId}`);
+		if (check.reasonCode) lines.push(`  reason: ${check.reasonCode}`);
+	}
+	for (const repair of report.repairs) {
+		lines.push(`- repair ${repair.id}: ${repair.state}`);
+		lines.push(`  target: ${repair.targetId}`);
+		if (repair.readiness.length) lines.push(`  readiness: ${repair.readiness.join(", ")}`);
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/cli/doctor/runner.ts

@@ -0,0 +1,342 @@
+import { randomUUID } from "node:crypto";
+import { VERSION } from "@gajae-code/utils/dirs";
+import type { DoctorOptions } from "./args";
+import { BASIC_DOCTOR_COLLECTORS, type DoctorCollector, doctorCheck } from "./checks";
+import { createDoctorContext, type DoctorContext } from "./context";
+import { collectPluginTargets } from "./plugin-targets";
+import { collectDoctorProbe } from "./probe-client";
+import { executeSelectedDoctorRepair, planSelectedDoctorRepair, refuseUnsettledDoctorRepair } from "./repairs";
+import { finalizeReport } from "./report";
+import { collectServiceTargets } from "./service-targets";
+import type { DoctorCheck, DoctorCoverage, DoctorRepair, DoctorReport } from "./types";
+
+const NATIVE_COLLECTOR: DoctorCollector = {
+	id: "native",
+	dependsOn: [],
+	timeoutMs: 5_000,
+	async collect(context) {
+		const result = await collectDoctorProbe(context, "native");
+		return [
+			doctorCheck("native.exports", `t1:native:${context.installRoot.rootId}`, {
+				execution:
+					result.status === "timeout" ? "timeout" : result.status === "cancelled" ? "cancelled" : "completed",
+				health: result.status === "completed" ? "ok" : result.status === "failed" ? "error" : "unknown",
+				evidenceLevel: "observed",
+				reasonCode: result.reasonCode,
+				evidence: { runtimeProbed: result.status === "completed" },
+				remediationIds: context.compiled ? ["install.restore-binary"] : [],
+			}),
+		];
+	},
+};
+
+const PROJECTION_COLLECTOR: DoctorCollector = {
+	id: "projection",
+	dependsOn: ["config"],
+	timeoutMs: 5_000,
+	async collect(context) {
+		const result = await collectDoctorProbe(context, "projection");
+		if (result.status === "completed" && result.receipt) return [...result.receipt.checks];
+		return [
+			doctorCheck("projection.coverage", `t1:projection:${context.agentRoot.rootId}`, {
+				execution:
+					result.status === "timeout" ? "timeout" : result.status === "cancelled" ? "cancelled" : "blocked",
+				health: "unknown",
+				evidenceLevel: "observed",
+				reasonCode: result.reasonCode,
+				dependsOn: ["config"],
+			}),
+		];
+	},
+};
+
+const SERVICE_COLLECTOR: DoctorCollector = {
+	id: "service",
+	dependsOn: [],
+	timeoutMs: 3_000,
+	collect: collectServiceTargets,
+};
+const PLUGIN_COLLECTOR: DoctorCollector = {
+	id: "plugin",
+	dependsOn: [],
+	timeoutMs: 3_000,
+	collect: collectPluginTargets,
+};
+const COLLECTORS: readonly DoctorCollector[] = [
+	...BASIC_DOCTOR_COLLECTORS,
+	SERVICE_COLLECTOR,
+	PLUGIN_COLLECTOR,
+	NATIVE_COLLECTOR,
+	PROJECTION_COLLECTOR,
+];
+
+function coverage(checks: readonly DoctorCheck[], requested: number): DoctorCoverage {
+	return {
+		requested,
+		expanded: checks.length,
+		attempted: checks.filter(check => check.execution !== "not_selected").length,
+		completed: checks.filter(check => check.execution === "completed").length,
+		blocked: checks.filter(check => check.execution === "blocked" || check.execution === "cancelled").length,
+		timedOut: checks.filter(check => check.execution === "timeout").length,
+		unsupported: checks.filter(check => check.execution === "unsupported").length,
+	};
+}
+
+function collectFailure(
+	context: DoctorContext,
+	collector: DoctorCollector,
+	execution: "blocked" | "cancelled" | "timeout",
+	reasonCode: string,
+): DoctorCheck[] {
+	return [
+		doctorCheck(`${collector.id}.coverage`, `t1:inspection:${context.agentRoot.rootId}:${collector.id}`, {
+			execution,
+			health: "unknown",
+			evidenceLevel: "observed",
+			reasonCode,
+			dependsOn: collector.dependsOn,
+		}),
+	];
+}
+
+/**
+ * One collector run plus whether its own work is over.
+ *
+ * `settled: false` means the collector never finished: it either lost the
+ * timeout race and is still running against the shared {@link DoctorContext},
+ * or it was refused before it could observe anything. Nothing here can stop an
+ * in-flight collector — a plain `collect(context)` promise is not cancellable —
+ * so the fact is carried out instead and repair planning refuses on it.
+ */
+interface CollectorRun {
+	readonly checks: DoctorCheck[];
+	readonly settled: boolean;
+}
+
+async function runCollector(context: DoctorContext, collector: DoctorCollector): Promise<CollectorRun> {
+	if (context.options.signal?.aborted)
+		return { checks: collectFailure(context, collector, "cancelled", "cancelled"), settled: false };
+	const started = performance.now();
+	const remaining = Math.min(collector.timeoutMs, context.deadline - started);
+	if (remaining <= 0)
+		return { checks: collectFailure(context, collector, "timeout", "deadline_exceeded"), settled: false };
+	const expired = Promise.withResolvers<{ checks: DoctorCheck[]; settled: false }>();
+	const timer = setTimeout(
+		() =>
+			expired.resolve({
+				checks: collectFailure(context, collector, "timeout", "collector_timeout"),
+				settled: false,
+			}),
+		remaining,
+	);
+	try {
+		const run = await Promise.race([
+			collector
+				.collect(context)
+				.then(checks => ({ checks, settled: true }))
+				// A rejection is still a finished collector: it is no longer writing to the context.
+				.catch(() => ({
+					checks: collectFailure(context, collector, "blocked", "collector_failed"),
+					settled: true,
+				})),
+			expired.promise,
+		]);
+		return {
+			checks: run.checks.map(check => ({ ...check, durationMs: Math.round(performance.now() - started) })),
+			settled: run.settled,
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+function selectedCollectors(options: DoctorOptions): { collectors: DoctorCollector[]; error?: string } {
+	const wanted = new Set<string>();
+	const registry = new Map(COLLECTORS.map(collector => [collector.id, collector]));
+	const add = (id: string) => {
+		if (wanted.has(id)) return;
+		const collector = registry.get(id);
+		if (!collector) return;
+		wanted.add(id);
+		for (const dependency of collector.dependsOn) add(dependency);
+	};
+	if (options.checks.length === 0) {
+		for (const collector of COLLECTORS)
+			if (options.mode !== "dry-run" || (collector.id !== "native" && collector.id !== "projection"))
+				add(collector.id);
+	} else {
+		for (const selector of options.checks) {
+			const id = selector.split(".")[0];
+			if (!registry.has(id)) return { collectors: [], error: "unknown_check" };
+			add(id);
+		}
+	}
+	if (options.repair) {
+		const domain = options.repair.split(".")[0];
+		add(domain === "install" ? "installation" : domain);
+	}
+	return { collectors: COLLECTORS.filter(collector => wanted.has(collector.id)) };
+}
+
+interface CollectedSelection {
+	readonly checks: DoctorCheck[];
+	readonly acceptedSelectors: string[];
+	readonly invocationError?: string;
+	/** False when a selected collector timed out, was cancelled, or is still running against the context. */
+	readonly settled: boolean;
+}
+
+async function collectSelectedChecks(context: DoctorContext): Promise<CollectedSelection> {
+	const options = context.options;
+	const selected = selectedCollectors(options);
+	const results = new Map<string, DoctorCheck[]>();
+	let settled = true;
+	const pending = [...selected.collectors];
+	while (pending.length > 0) {
+		const available = pending.filter(collector => collector.dependsOn.every(dependency => results.has(dependency)));
+		if (available.length === 0) {
+			for (const collector of pending)
+				results.set(collector.id, collectFailure(context, collector, "blocked", "dependency_unavailable"));
+			break;
+		}
+		const batch = available.slice(0, 3);
+		await Promise.all(
+			batch.map(async collector => {
+				pending.splice(pending.indexOf(collector), 1);
+				const failedDependency = collector.dependsOn.some(dependency =>
+					results.get(dependency)?.some(check => check.execution !== "completed" || check.health === "error"),
+				);
+				if (failedDependency) {
+					results.set(collector.id, collectFailure(context, collector, "blocked", "dependency_failed"));
+					return;
+				}
+				const run = await runCollector(context, collector);
+				if (!run.settled) settled = false;
+				results.set(collector.id, run.checks);
+			}),
+		);
+	}
+	const collectedChecks = selected.collectors.flatMap(collector => results.get(collector.id) ?? []);
+	const registryIds = new Set(COLLECTORS.map(collector => collector.id));
+	const explicitGroups = new Set(options.checks.map(selector => selector.split(".")[0]));
+	const acceptedSelectors = options.checks.filter(
+		selector => registryIds.has(selector) || collectedChecks.some(check => check.id === selector),
+	);
+	const unresolvedSelectors = options.checks.filter(selector => !acceptedSelectors.includes(selector));
+	const unresolvedInspection = unresolvedSelectors.some(selector =>
+		results.get(selector.split(".")[0])?.some(check => check.execution !== "completed"),
+	);
+	const invocationError =
+		selected.error ?? (unresolvedSelectors.length > 0 && !unresolvedInspection ? "unknown_check" : undefined);
+	const checks =
+		options.checks.length === 0
+			? collectedChecks
+			: selected.collectors.flatMap(collector => {
+					const items = results.get(collector.id) ?? [];
+					if (!explicitGroups.has(collector.id) || options.checks.includes(collector.id)) return items;
+					return items.filter(
+						check =>
+							options.checks.includes(check.id) ||
+							check.targetId === options.targetId ||
+							(unresolvedInspection && check.execution !== "completed"),
+					);
+				});
+	return { checks, acceptedSelectors, invocationError, settled };
+}
+
+/** Diagnose first; only a resolved, authorized single action can enter its domain transaction. */
+export async function collectDoctorReport(options: DoctorOptions): Promise<DoctorReport> {
+	const started = performance.now();
+	const runId = options.runId ?? randomUUID();
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(runId)) throw new Error("invalid_doctor_run_id");
+	const context = createDoctorContext(options);
+	const before = await collectSelectedChecks(context);
+	let checks = before.checks;
+	let currentChecks = checks;
+	let invocationError = before.invocationError;
+	const repairs: DoctorRepair[] = [];
+	// A collector that lost its timeout race is still running and still writing
+	// into this context's target map. Planning a repair against that state would
+	// bind the action to a partially-populated snapshot, so the whole repair lane
+	// is refused here; the diagnosis above still reports what was collected.
+	// `invocationError` stays untouched: this is not a usage error, so the run
+	// reports incomplete (exit 3) rather than exit 2.
+	const unsettled = before.settled ? undefined : refuseUnsettledDoctorRepair(context, checks);
+	if (unsettled) repairs.push(unsettled);
+	const plan = unsettled ? undefined : planSelectedDoctorRepair(context, checks);
+	if (plan && !invocationError) {
+		if (plan.readiness.includes("target_resolution_incomplete")) {
+			checks = [
+				...checks,
+				doctorCheck("repair.target_resolution", plan.targetId, {
+					execution: "blocked",
+					health: "unknown",
+					evidenceLevel: "not_probed",
+					reasonCode: "target_resolution_incomplete",
+				}),
+			];
+			currentChecks = checks;
+		}
+		if (plan.reasonCode === "unknown_target" || plan.reasonCode === "action_target_mismatch")
+			invocationError = plan.reasonCode;
+		if (options.mode !== "fix" || invocationError) {
+			repairs.push(plan);
+		} else {
+			const result = await executeSelectedDoctorRepair(context, runId, plan, async () => {
+				const remaining = context.deadline - performance.now();
+				if (remaining <= 0)
+					return [
+						doctorCheck("repair.postcheck", plan.targetId, {
+							execution: "timeout",
+							health: "unknown",
+							evidenceLevel: "not_probed",
+							reasonCode: "postcheck_deadline_exceeded",
+						}),
+					];
+				const freshContext = createDoctorContext({ ...options, mode: "diagnose", timeoutMs: remaining });
+				const fresh = await collectSelectedChecks(freshContext);
+				return fresh.checks;
+			});
+			invocationError = result.invocationError;
+			if (result.afterChecks?.length) {
+				const historical = before.checks.map(check => ({ ...check, id: `before.${check.id}` }));
+				currentChecks = [...result.afterChecks];
+				checks = [...historical, ...currentChecks];
+				repairs.push({
+					...result.repair,
+					beforeCheckIds: historical.map(check => check.id),
+					afterCheckIds: currentChecks.map(check => check.id),
+				});
+			} else {
+				repairs.push(result.repair);
+			}
+		}
+	}
+	return finalizeReport({
+		runId,
+		mode: options.mode,
+		generatedAt: new Date().toISOString(),
+		durationMs: Math.round(performance.now() - started),
+		subject: {
+			gjcVersion: VERSION,
+			platform: process.platform,
+			arch: process.arch,
+			channel: context.compiled ? "standalone" : "source",
+			scope: options.scope,
+			rootIds: [
+				...new Set([
+					context.agentRoot.rootId,
+					context.installRoot.rootId,
+					...context.sources.map(source => source.root.rootId),
+				]),
+			],
+		},
+		selection: { checks: before.acceptedSelectors, repair: options.repair, targetId: options.targetId },
+		coverage: coverage(currentChecks, options.checks.length || currentChecks.length),
+		checks,
+		repairs,
+		invocationError,
+		interrupted: options.signal?.aborted || repairs.some(repair => repair.reasonCode === "cancelled"),
+		limits: { fileBytes: 1024 * 1024, probeOutputBytes: 64 * 1024, timeoutMs: options.timeoutMs ?? 15_000 },
+	});
+}

package/src/cli/doctor/safety.ts

@@ -0,0 +1,40 @@
+import { constants } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { verifyOwnerOnlyFdSecurity } from "@gajae-code/natives";
+
+export interface DoctorSafetyResult {
+	readonly safe: boolean;
+	readonly reasonCode?: string;
+	readonly platform?: string;
+}
+export interface DoctorExpectedIdentity {
+	readonly dev: bigint;
+	readonly ino: bigint;
+}
+
+export async function authorizePosixConfigPermission(
+	filePath: string,
+	expected?: DoctorExpectedIdentity,
+): Promise<DoctorSafetyResult> {
+	if (process.platform === "win32") return { safe: false, reasonCode: "unsupported", platform: process.platform };
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(filePath, constants.O_RDWR | constants.O_NOFOLLOW);
+		const stat = await handle.stat({ bigint: true });
+		if (!stat.isFile()) return { safe: false, reasonCode: "not_regular" };
+		if (stat.nlink !== 1n) return { safe: false, reasonCode: "hardlink" };
+		if (expected && (stat.dev !== expected.dev || stat.ino !== expected.ino))
+			return { safe: false, reasonCode: "identity_mismatch" };
+		const parent = await fs.realpath(path.dirname(filePath));
+		if (path.dirname(path.resolve(filePath)) !== parent) return { safe: false, reasonCode: "unsafe_parent" };
+		const verified = verifyOwnerOnlyFdSecurity(filePath, "file", handle.fd);
+		return verified.ok
+			? { safe: true, platform: process.platform }
+			: { safe: false, reasonCode: verified.code, platform: process.platform };
+	} catch (error) {
+		return { safe: false, reasonCode: error instanceof Error ? error.name : "unavailable" };
+	} finally {
+		await handle?.close();
+	}
+}