@crafter/cli-tree 0.1.0

package/src/archaeology/cache.ts

@@ -0,0 +1,107 @@
+import type { ArchaeologyCache, EnrichedCLINode } from "./types";
+
+export interface CacheOptions {
+	cacheDir?: string;
+	ttlDays?: number;
+}
+
+function getCacheDir(opts?: CacheOptions): string {
+	if (opts?.cacheDir) return opts.cacheDir;
+	const home = process.env.HOME ?? "";
+	if (!home) throw new Error("HOME is not set; cannot determine cache directory");
+	return `${home}/.clitree/cache`;
+}
+
+function cachePath(cli: string, opts?: CacheOptions): string {
+	const dir = getCacheDir(opts);
+	const safe = cli.replace(/[^a-zA-Z0-9_-]/g, "_");
+	return `${dir}/${safe}.json`;
+}
+
+export async function loadCache(cli: string, opts?: CacheOptions): Promise<ArchaeologyCache | null> {
+	const path = cachePath(cli, opts);
+	const file = Bun.file(path);
+	const exists = await file.exists();
+	if (!exists) return null;
+
+	try {
+		const data = await file.json();
+		return data as ArchaeologyCache;
+	} catch {
+		return null;
+	}
+}
+
+export async function saveCache(cli: string, cache: ArchaeologyCache, opts?: CacheOptions): Promise<void> {
+	const dir = getCacheDir(opts);
+	await ensureDir(dir);
+
+	const path = cachePath(cli, opts);
+	await Bun.write(path, JSON.stringify(cache, null, 2));
+}
+
+export async function invalidateCache(cli: string, opts?: CacheOptions): Promise<void> {
+	const path = cachePath(cli, opts);
+	const file = Bun.file(path);
+	if (await file.exists()) {
+		await Bun.$`rm ${path}`.quiet();
+	}
+}
+
+export function isCacheStale(cache: ArchaeologyCache, currentVersion?: string, ttlDays?: number): boolean {
+	if (currentVersion && cache.cliVersion && cache.cliVersion !== currentVersion) {
+		return true;
+	}
+
+	if (ttlDays) {
+		const created = new Date(cache.createdAt).getTime();
+		const now = Date.now();
+		const ageDays = (now - created) / (1000 * 60 * 60 * 24);
+		if (ageDays > ttlDays) return true;
+	}
+
+	return false;
+}
+
+export async function detectCliVersion(binary: string): Promise<string | undefined> {
+	const candidates = ["--version", "-v", "version"];
+	for (const arg of candidates) {
+		try {
+			const proc = Bun.spawn([binary, arg], { stdout: "pipe", stderr: "pipe" });
+			const timeout = setTimeout(() => proc.kill(), 3000);
+
+			const [stdout, stderr] = await Promise.all([
+				new Response(proc.stdout).text(),
+				new Response(proc.stderr).text(),
+			]);
+			clearTimeout(timeout);
+			await proc.exited;
+
+			const output = (stdout || stderr).trim();
+			const match = output.match(/v?\d+\.\d+(?:\.\d+)?(?:-[a-zA-Z0-9.]+)?/);
+			if (match) return match[0];
+		} catch {}
+	}
+	return undefined;
+}
+
+async function ensureDir(dir: string): Promise<void> {
+	try {
+		await Bun.$`mkdir -p ${dir}`.quiet();
+	} catch {}
+}
+
+export function createEmptyCache(cli: string, tree: EnrichedCLINode, cliVersion?: string): ArchaeologyCache {
+	return {
+		cli,
+		cliVersion,
+		createdAt: new Date().toISOString(),
+		tree,
+		phases: {
+			survey: false,
+			excavation: false,
+			deepDive: false,
+			cartography: false,
+		},
+	};
+}

package/src/archaeology/delegate.ts

@@ -0,0 +1,113 @@
+import type { DeepDiveProposal, SurveyHypothesis, FlagConstraint } from "./types";
+
+export interface ArchaeologyDelegate {
+	readonly name: string;
+	readonly available: boolean;
+
+	survey?(cli: string, version?: string): Promise<SurveyHypothesis>;
+
+	proposeHiddenFlags?(cli: string, subcommand: string[]): Promise<DeepDiveProposal>;
+
+	proposeConstraints?(cli: string, subcommand: string[]): Promise<FlagConstraint[]>;
+}
+
+export class NullDelegate implements ArchaeologyDelegate {
+	readonly name = "null";
+	readonly available = false;
+}
+
+export class BridgeFileDelegate implements ArchaeologyDelegate {
+	readonly name = "bridge-file";
+	readonly available = true;
+	private requestsPath: string;
+	private responsesPath: string;
+	private timeoutMs: number;
+
+	constructor(opts: { requestsPath?: string; responsesPath?: string; timeoutMs?: number } = {}) {
+		const tmp = process.env.TMPDIR ?? "/tmp";
+		this.requestsPath = opts.requestsPath ?? `${tmp}/clitree-requests.jsonl`;
+		this.responsesPath = opts.responsesPath ?? `${tmp}/clitree-responses.jsonl`;
+		this.timeoutMs = opts.timeoutMs ?? 120_000;
+	}
+
+	async survey(cli: string, version?: string): Promise<SurveyHypothesis> {
+		const id = crypto.randomUUID();
+		await this.writeRequest({ id, kind: "survey", cli, version });
+		const response = await this.awaitResponse(id);
+		return response as SurveyHypothesis;
+	}
+
+	async proposeHiddenFlags(cli: string, subcommand: string[]): Promise<DeepDiveProposal> {
+		const id = crypto.randomUUID();
+		await this.writeRequest({ id, kind: "deep-dive", cli, subcommand });
+		const response = await this.awaitResponse(id);
+		return response as DeepDiveProposal;
+	}
+
+	async proposeConstraints(cli: string, subcommand: string[]): Promise<FlagConstraint[]> {
+		const id = crypto.randomUUID();
+		await this.writeRequest({ id, kind: "cartography", cli, subcommand });
+		const response = await this.awaitResponse(id);
+		return (response as { constraints: FlagConstraint[] }).constraints ?? [];
+	}
+
+	private async writeRequest(req: unknown): Promise<void> {
+		const existing = await this.readFile(this.requestsPath);
+		const line = JSON.stringify(req) + "\n";
+		await Bun.write(this.requestsPath, existing + line, { createPath: true });
+	}
+
+	private async awaitResponse(id: string): Promise<unknown> {
+		const start = Date.now();
+		while (Date.now() - start < this.timeoutMs) {
+			const text = await this.readFile(this.responsesPath);
+			const lines = text.split("\n").filter(l => l.trim());
+			for (const line of lines) {
+				try {
+					const parsed = JSON.parse(line);
+					if (parsed.id === id) return parsed.result;
+				} catch {}
+			}
+			await new Promise(r => setTimeout(r, 250));
+		}
+		throw new Error(`Timed out waiting for delegate response to request ${id}`);
+	}
+
+	private async readFile(path: string): Promise<string> {
+		try {
+			const file = Bun.file(path);
+			if (!(await file.exists())) return "";
+			return await file.text();
+		} catch {
+			return "";
+		}
+	}
+}
+
+export class InlineDelegate implements ArchaeologyDelegate {
+	readonly name = "inline";
+	readonly available = true;
+
+	constructor(
+		private handlers: {
+			survey?: (cli: string, version?: string) => Promise<SurveyHypothesis>;
+			proposeHiddenFlags?: (cli: string, subcommand: string[]) => Promise<DeepDiveProposal>;
+			proposeConstraints?: (cli: string, subcommand: string[]) => Promise<FlagConstraint[]>;
+		},
+	) {}
+
+	async survey(cli: string, version?: string): Promise<SurveyHypothesis> {
+		if (!this.handlers.survey) throw new Error("InlineDelegate: survey handler not provided");
+		return this.handlers.survey(cli, version);
+	}
+
+	async proposeHiddenFlags(cli: string, subcommand: string[]): Promise<DeepDiveProposal> {
+		if (!this.handlers.proposeHiddenFlags) throw new Error("InlineDelegate: proposeHiddenFlags handler not provided");
+		return this.handlers.proposeHiddenFlags(cli, subcommand);
+	}
+
+	async proposeConstraints(cli: string, subcommand: string[]): Promise<FlagConstraint[]> {
+		if (!this.handlers.proposeConstraints) throw new Error("InlineDelegate: proposeConstraints handler not provided");
+		return this.handlers.proposeConstraints(cli, subcommand);
+	}
+}

package/src/archaeology/index.ts

@@ -0,0 +1,48 @@
+export type {
+	Source,
+	SourceKind,
+	EnrichedCLINode,
+	EnrichedFlag,
+	EnrichedArg,
+	Example,
+	FlagConstraint,
+	SurveyHypothesis,
+	DeepDiveProposal,
+	ValidationVerdict,
+	ArchaeologyCache,
+	ArchaeologyOptions,
+} from "./types";
+
+export { toCLINode, fromCLINode } from "./types";
+
+export {
+	surveyPrompt,
+	excavationPrompt,
+	deepDivePrompt,
+	cartographyPrompt,
+	validationInstructions,
+	extractJsonFromLlmResponse,
+} from "./prompts";
+
+export {
+	runHelpCommand,
+	validateSubcommandExists,
+	validateSurvey,
+	excavateCommand,
+	validateDeepDive,
+	summarizeValidation,
+} from "./validate";
+
+export type { ValidationSummary } from "./validate";
+
+export { mergeNodes, filterUnverified } from "./merge";
+
+export { loadCache, saveCache, invalidateCache, isCacheStale, detectCliVersion, createEmptyCache } from "./cache";
+
+export type { CacheOptions } from "./cache";
+
+export type { ArchaeologyDelegate } from "./delegate";
+export { NullDelegate, BridgeFileDelegate, InlineDelegate } from "./delegate";
+
+export { runArchaeology, enrichedToTree } from "./orchestrator";
+export type { ArchaeologyProgress, ArchaeologyResult } from "./orchestrator";

package/src/archaeology/llm.ts

@@ -0,0 +1,10 @@
+// Deprecated module — archaeology LLM calls go through ArchaeologyDelegate
+// (see delegate.ts). This file is kept as a shim for backwards compatibility
+// with the orchestrator import path and will be removed in a future release.
+
+export {
+	type ArchaeologyDelegate,
+	NullDelegate,
+	BridgeFileDelegate,
+	InlineDelegate,
+} from "./delegate";

package/src/archaeology/merge.ts

@@ -0,0 +1,155 @@
+import type { EnrichedCLINode, EnrichedFlag, EnrichedArg, Source, SourceKind } from "./types";
+
+const SOURCE_PRIORITY: Record<SourceKind, number> = {
+	"user": 100,
+	"help": 90,
+	"llm-validated": 70,
+	"man": 60,
+	"completion": 55,
+	"llm-cartography": 40,
+	"llm-deep-dive": 35,
+	"llm-survey": 20,
+};
+
+function sourceRank(source: Source | undefined): number {
+	if (!source) return 0;
+	return SOURCE_PRIORITY[source.type] ?? 0;
+}
+
+export function mergeNodes(a: EnrichedCLINode, b: EnrichedCLINode): EnrichedCLINode {
+	if (a.name !== b.name) {
+		throw new Error(`Cannot merge nodes with different names: ${a.name} vs ${b.name}`);
+	}
+
+	const highPriority = sourceRank(a.source) >= sourceRank(b.source) ? a : b;
+	const lowPriority = highPriority === a ? b : a;
+
+	const merged: EnrichedCLINode = {
+		name: a.name,
+		source: highPriority.source,
+	};
+
+	merged.description = highPriority.description ?? lowPriority.description;
+
+	if (highPriority.aliases || lowPriority.aliases) {
+		const set = new Set([...(highPriority.aliases ?? []), ...(lowPriority.aliases ?? [])]);
+		merged.aliases = Array.from(set);
+	}
+
+	merged.hidden = highPriority.hidden ?? lowPriority.hidden;
+	merged.deprecated = highPriority.deprecated ?? lowPriority.deprecated;
+	merged.experimental = highPriority.experimental ?? lowPriority.experimental;
+
+	merged.flags = mergeFlags(highPriority.flags ?? [], lowPriority.flags ?? []);
+	if (merged.flags.length === 0) delete merged.flags;
+
+	merged.args = mergeArgs(highPriority.args ?? [], lowPriority.args ?? []);
+	if (merged.args.length === 0) delete merged.args;
+
+	merged.subcommands = mergeSubcommands(highPriority.subcommands ?? [], lowPriority.subcommands ?? []);
+	if (merged.subcommands.length === 0) delete merged.subcommands;
+
+	if (highPriority.constraints || lowPriority.constraints) {
+		merged.constraints = [...(highPriority.constraints ?? []), ...(lowPriority.constraints ?? [])];
+	}
+
+	if (highPriority.examples || lowPriority.examples) {
+		merged.examples = dedupeExamples([...(highPriority.examples ?? []), ...(lowPriority.examples ?? [])]);
+	}
+
+	return merged;
+}
+
+function mergeFlags(primary: EnrichedFlag[], secondary: EnrichedFlag[]): EnrichedFlag[] {
+	const byName = new Map<string, EnrichedFlag>();
+
+	for (const flag of primary) {
+		byName.set(flag.name, flag);
+	}
+
+	for (const flag of secondary) {
+		const existing = byName.get(flag.name);
+		if (!existing) {
+			byName.set(flag.name, flag);
+		} else {
+			byName.set(flag.name, mergeFlag(existing, flag));
+		}
+	}
+
+	return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function mergeFlag(a: EnrichedFlag, b: EnrichedFlag): EnrichedFlag {
+	const high = sourceRank(a.source) >= sourceRank(b.source) ? a : b;
+	const low = high === a ? b : a;
+
+	return {
+		...low,
+		...high,
+		description: high.description ?? low.description,
+		short: high.short ?? low.short,
+		examples: [...(high.examples ?? []), ...(low.examples ?? [])],
+		excludes: Array.from(new Set([...(high.excludes ?? []), ...(low.excludes ?? [])])),
+		requires: Array.from(new Set([...(high.requires ?? []), ...(low.requires ?? [])])),
+	};
+}
+
+function mergeArgs(primary: EnrichedArg[], secondary: EnrichedArg[]): EnrichedArg[] {
+	const byName = new Map<string, EnrichedArg>();
+	for (const arg of primary) byName.set(arg.name, arg);
+	for (const arg of secondary) {
+		if (!byName.has(arg.name)) byName.set(arg.name, arg);
+	}
+	return Array.from(byName.values());
+}
+
+function mergeSubcommands(primary: EnrichedCLINode[], secondary: EnrichedCLINode[]): EnrichedCLINode[] {
+	const byName = new Map<string, EnrichedCLINode>();
+
+	for (const sub of primary) byName.set(sub.name, sub);
+	for (const sub of secondary) {
+		const existing = byName.get(sub.name);
+		if (!existing) {
+			byName.set(sub.name, sub);
+		} else {
+			byName.set(sub.name, mergeNodes(existing, sub));
+		}
+	}
+
+	return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function dedupeExamples(examples: { command: string; description?: string; source?: Source }[]) {
+	const byCommand = new Map<string, { command: string; description?: string; source?: Source }>();
+	for (const ex of examples) {
+		const existing = byCommand.get(ex.command);
+		if (!existing || sourceRank(ex.source) > sourceRank(existing.source)) {
+			byCommand.set(ex.command, ex);
+		}
+	}
+	return Array.from(byCommand.values());
+}
+
+export function filterUnverified(node: EnrichedCLINode): EnrichedCLINode {
+	const copy: EnrichedCLINode = { ...node };
+
+	if (copy.flags) {
+		copy.flags = copy.flags.filter(f => {
+			const rank = sourceRank(f.source);
+			return rank >= SOURCE_PRIORITY["llm-validated"];
+		});
+		if (copy.flags.length === 0) delete copy.flags;
+	}
+
+	if (copy.subcommands) {
+		copy.subcommands = copy.subcommands
+			.filter(s => {
+				const rank = sourceRank(s.source);
+				return rank >= SOURCE_PRIORITY["llm-validated"];
+			})
+			.map(filterUnverified);
+		if (copy.subcommands.length === 0) delete copy.subcommands;
+	}
+
+	return copy;
+}

package/src/archaeology/orchestrator.ts

@@ -0,0 +1,185 @@
+import { parseHelpRecursive } from "../parse";
+import { validateSurvey, excavateCommand, validateDeepDive, summarizeValidation } from "./validate";
+import { loadCache, saveCache, isCacheStale, detectCliVersion, createEmptyCache } from "./cache";
+import { fromCLINode, toCLINode, type EnrichedCLINode, type ArchaeologyOptions, type ValidationVerdict, type Source } from "./types";
+import type { ArchaeologyDelegate } from "./delegate";
+import { NullDelegate } from "./delegate";
+import type { CLINode } from "../types";
+
+export interface ArchaeologyProgress {
+	phase: "cache" | "excavation" | "survey" | "deep-dive" | "cartography" | "merge" | "done";
+	message: string;
+	percent?: number;
+}
+
+export interface ArchaeologyResult {
+	tree: EnrichedCLINode;
+	stats: {
+		helpCommands: number;
+		llmProposed: number;
+		verified: number;
+		rejected: number;
+		unconfirmed: number;
+		hallucinations: string[];
+	};
+	fromCache: boolean;
+}
+
+export async function runArchaeology(
+	binary: string,
+	delegate: ArchaeologyDelegate = new NullDelegate(),
+	opts: ArchaeologyOptions & {
+		onProgress?: (p: ArchaeologyProgress) => void;
+		maxHelpDepth?: number;
+	} = {},
+): Promise<ArchaeologyResult> {
+	const report = opts.onProgress ?? (() => {});
+	const phases = {
+		survey: opts.phases?.survey ?? true,
+		excavation: opts.phases?.excavation ?? true,
+		deepDive: opts.phases?.deepDive ?? true,
+		cartography: opts.phases?.cartography ?? false,
+	};
+
+	report({ phase: "cache", message: "Checking cache..." });
+
+	const version = await detectCliVersion(binary);
+	if (!opts.skipCache) {
+		const cached = await loadCache(binary, { cacheDir: opts.cacheDir });
+		if (cached && !isCacheStale(cached, version, 30)) {
+			report({ phase: "done", message: "Loaded from cache" });
+			return {
+				tree: cached.tree,
+				stats: { helpCommands: 0, llmProposed: 0, verified: 0, rejected: 0, unconfirmed: 0, hallucinations: [] },
+				fromCache: true,
+			};
+		}
+	}
+
+	report({ phase: "excavation", message: `Parsing ${binary} --help recursively...` });
+	const helpTree = await parseHelpRecursive(binary, [], opts.maxHelpDepth ?? 2);
+	const helpSource: Source = { type: "help", confidence: 1.0, verifiedAt: new Date().toISOString() };
+	const tree: EnrichedCLINode = fromCLINode(helpTree, helpSource);
+	const helpCommandCount = countCommands(tree);
+
+	let llmProposed = 0;
+	const allVerdicts: ValidationVerdict[] = [];
+
+	if (delegate.available && phases.survey && delegate.survey) {
+		report({ phase: "survey", message: "Delegate hypothesis survey..." });
+		try {
+			const survey = await delegate.survey(binary, version);
+			const existingCommands = new Set(tree.subcommands?.map(s => s.name) ?? []);
+
+			const { confirmed } = await validateSurvey(binary, survey);
+			const llmSurveySource: Source = { type: "llm-validated", confidence: 0.8, verifiedAt: new Date().toISOString() };
+
+			for (const sub of confirmed) {
+				if (!existingCommands.has(sub)) {
+					llmProposed += 1;
+					const excavated = await excavateCommand(binary, [sub]);
+					if (excavated) {
+						const enriched = fromCLINode(excavated, llmSurveySource);
+						if (!tree.subcommands) tree.subcommands = [];
+						tree.subcommands.push(enriched);
+					}
+				}
+			}
+		} catch (e: any) {
+			report({ phase: "survey", message: `Survey failed: ${e.message}` });
+		}
+	}
+
+	if (delegate.available && phases.deepDive && delegate.proposeHiddenFlags && tree.subcommands) {
+		const topCommands = tree.subcommands.slice(0, 10);
+		report({ phase: "deep-dive", message: `Deep dive into ${topCommands.length} subcommands...` });
+
+		for (const sub of topCommands) {
+			try {
+				const proposal = await delegate.proposeHiddenFlags(binary, [sub.name]);
+				const verdict = await validateDeepDive(binary, proposal);
+				allVerdicts.push(verdict);
+
+				const verifiedSet = new Set(verdict.verifiedFlags);
+				const unconfirmedSet = new Set(verdict.unconfirmedFlags);
+
+				for (const flag of proposal.flags ?? []) {
+					if (verifiedSet.has(flag.name) || (opts.includeUnverified && unconfirmedSet.has(flag.name))) {
+						llmProposed += 1;
+						const source: Source = {
+							type: verifiedSet.has(flag.name) ? "llm-validated" : "llm-deep-dive",
+							confidence: verifiedSet.has(flag.name) ? 0.9 : 0.6,
+							verifiedAt: new Date().toISOString(),
+						};
+						if (!sub.flags) sub.flags = [];
+						const existing = sub.flags.find(f => f.name === flag.name);
+						if (!existing) {
+							sub.flags.push({
+								name: flag.name,
+								short: flag.short,
+								type: flag.type,
+								description: flag.description,
+								hidden: flag.hidden,
+								deprecated: flag.deprecated,
+								source,
+							});
+						}
+					}
+				}
+			} catch (e: any) {
+				report({ phase: "deep-dive", message: `Deep dive failed for ${sub.name}: ${e.message}` });
+			}
+		}
+	}
+
+	if (delegate.available && phases.cartography && delegate.proposeConstraints && tree.subcommands) {
+		report({ phase: "cartography", message: "Mapping flag constraints..." });
+		for (const sub of tree.subcommands.slice(0, 5)) {
+			try {
+				const constraints = await delegate.proposeConstraints(binary, [sub.name]);
+				if (constraints.length > 0) {
+					sub.constraints = constraints;
+				}
+			} catch {}
+		}
+	}
+
+	report({ phase: "merge", message: "Finalizing tree..." });
+	const summary = summarizeValidation(allVerdicts);
+
+	if (!opts.skipCache) {
+		const cache = createEmptyCache(binary, tree, version);
+		cache.phases = {
+			survey: phases.survey,
+			excavation: true,
+			deepDive: phases.deepDive,
+			cartography: phases.cartography,
+		};
+		await saveCache(binary, cache, { cacheDir: opts.cacheDir });
+	}
+
+	report({ phase: "done", message: "Archaeology complete" });
+
+	return {
+		tree,
+		stats: {
+			helpCommands: helpCommandCount,
+			llmProposed,
+			verified: summary.verified,
+			rejected: summary.rejected,
+			unconfirmed: summary.unconfirmed,
+			hallucinations: summary.hallucinations,
+		},
+		fromCache: false,
+	};
+}
+
+function countCommands(node: EnrichedCLINode): number {
+	let count = 1;
+	if (node.subcommands) for (const s of node.subcommands) count += countCommands(s);
+	return count;
+}
+
+export function enrichedToTree(enriched: EnrichedCLINode): CLINode {
+	return toCLINode(enriched);
+}