@pi-ohm/references 0.6.4-dev.27705031416.1.1d8069f

package/dist/config.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+import { Result } from "better-result";
+import { Type } from "typebox";
+import { loadConfig, pickConfig, registerConfig } from "@pi-ohm/core/config";
+
+//#region src/config.ts
+const LocalReferenceConfigSchema = Type.Object({
+	path: Type.String({ minLength: 1 }),
+	description: Type.Optional(Type.String()),
+	hidden: Type.Optional(Type.Boolean())
+}, { additionalProperties: false });
+const GitReferenceConfigSchema = Type.Object({
+	repository: Type.String({ minLength: 1 }),
+	branch: Type.Optional(Type.String()),
+	description: Type.Optional(Type.String()),
+	hidden: Type.Optional(Type.Boolean())
+}, { additionalProperties: false });
+const ReferenceEntryConfigSchema = Type.Union([
+	Type.String({ minLength: 1 }),
+	LocalReferenceConfigSchema,
+	GitReferenceConfigSchema
+]);
+const ReferencesConfigSchema = Type.Record(Type.String({ minLength: 1 }), ReferenceEntryConfigSchema);
+const DEFAULT_REFERENCES_CONFIG = {};
+const referencesConfigModule = registerConfig({
+	namespace: "references",
+	schema: ReferencesConfigSchema,
+	defaults: DEFAULT_REFERENCES_CONFIG,
+	merge(base, patch) {
+		return Result.ok(mergeReferencesConfig(base, patch));
+	}
+});
+function isJsonMap(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function trimString(value) {
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	return trimmed;
+}
+function optionalString(value) {
+	if (value === undefined) return undefined;
+	return trimString(value);
+}
+function normalizeEntry(entry) {
+	if (typeof entry === "string") return trimString(entry);
+	if ("path" in entry) {
+		const resolved = trimString(entry.path);
+		if (!resolved) return undefined;
+		return {
+			path: resolved,
+			...optionalString(entry.description) ? { description: optionalString(entry.description) } : {},
+			...entry.hidden !== undefined ? { hidden: entry.hidden } : {}
+		};
+	}
+	const repository = trimString(entry.repository);
+	if (!repository) return undefined;
+	return {
+		repository,
+		...optionalString(entry.branch) ? { branch: optionalString(entry.branch) } : {},
+		...optionalString(entry.description) ? { description: optionalString(entry.description) } : {},
+		...entry.hidden !== undefined ? { hidden: entry.hidden } : {}
+	};
+}
+function validReferenceAlias(name) {
+	return name.length > 0 && !/[/\s`,]/.test(name);
+}
+function mergeReferencesConfig(current, patch) {
+	const entries = Object.entries(patch).reduce((next, [rawName, rawEntry]) => {
+		const name = rawName.trim();
+		if (!validReferenceAlias(name)) return next;
+		const entry = normalizeEntry(rawEntry);
+		if (!entry) return next;
+		return {
+			...next,
+			[name]: entry
+		};
+	}, { ...current ?? DEFAULT_REFERENCES_CONFIG });
+	return entries;
+}
+function isLocalReferenceConfig(value) {
+	if (!isJsonMap(value)) return false;
+	if (typeof value.path !== "string") return false;
+	if (value.description !== undefined && typeof value.description !== "string") return false;
+	if (value.hidden !== undefined && typeof value.hidden !== "boolean") return false;
+	return true;
+}
+function isGitReferenceConfig(value) {
+	if (!isJsonMap(value)) return false;
+	if (typeof value.repository !== "string") return false;
+	if (value.branch !== undefined && typeof value.branch !== "string") return false;
+	if (value.description !== undefined && typeof value.description !== "string") return false;
+	if (value.hidden !== undefined && typeof value.hidden !== "boolean") return false;
+	return true;
+}
+function isReferencesRuntimeConfig(value) {
+	if (!isJsonMap(value)) return false;
+	return Object.values(value).every((entry) => typeof entry === "string" || isLocalReferenceConfig(entry) || isGitReferenceConfig(entry));
+}
+async function loadReferencesConfig(cwd) {
+	const loaded = await loadConfig({
+		cwd: path.resolve(cwd),
+		modules: [referencesConfigModule]
+	});
+	if (Result.isError(loaded)) return Result.err(loaded.error);
+	const config = pickConfig({
+		loaded: loaded.value,
+		module: referencesConfigModule,
+		is: isReferencesRuntimeConfig
+	});
+	if (Result.isError(config)) return Result.err(config.error);
+	return Result.ok({
+		loaded: loaded.value,
+		config: config.value
+	});
+}
+
+//#endregion
+export { GitReferenceConfigSchema, LocalReferenceConfigSchema, ReferenceEntryConfigSchema, ReferencesConfigSchema, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, mergeReferencesConfig, referencesConfigModule, validReferenceAlias };

package/dist/extension.d.ts

@@ -0,0 +1,32 @@
+import { FileRepositoryReference, ReferenceErrorCode, ReferencesError, RemoteRepositoryReference, RepositoryReference, parseRemoteRepositoryReference, parseRepositoryReference, repositoryCacheIdentity, repositoryCachePath, sameRepositoryReference, validateBranch } from "./repository.js";
+import { EnsureRepositoryInput, RepositoryCacheResult, defaultReferencesCacheRoot, ensureRepository } from "./cache.js";
+import { GitReferenceConfig, GitReferenceConfigSchema, LocalReferenceConfig, LocalReferenceConfigSchema, ReferenceEntryConfig, ReferenceEntryConfigSchema, ReferencesConfigSchema, ReferencesRuntimeConfig, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, mergeReferencesConfig, referencesConfigModule, validReferenceAlias } from "./config.js";
+import { GitReferenceSource, LocalReferenceSource, MaterializeReferencesResult, ReferenceDiagnostic, ReferenceInfo, ReferenceSource, ResolvedReferences, materializeGitReferences, renderReferenceGuidance, resolveConfiguredReferences } from "./references.js";
+import { AutocompleteProvider } from "@earendil-works/pi-tui";
+import { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+//#region src/extension.d.ts
+interface ReferenceInvocation {
+  readonly name: string;
+  readonly token: string;
+  readonly path: string;
+  readonly rootPath: string;
+  readonly relativePath: string | undefined;
+  readonly description: string | undefined;
+}
+type AddAutocompleteProvider = ExtensionContext["ui"]["addAutocompleteProvider"];
+interface AutocompleteHost {
+  addAutocompleteProvider: AddAutocompleteProvider;
+}
+declare function resolveReferenceToken(token: string, references: readonly ReferenceInfo[]): ReferenceInvocation | undefined;
+declare function findReferenceInvocations(text: string, references: readonly ReferenceInfo[]): readonly ReferenceInvocation[];
+declare function renderReferenceInvocation(invocations: readonly ReferenceInvocation[]): string | undefined;
+declare function rewriteReferencePath(value: string | undefined, references: readonly ReferenceInfo[]): string | undefined;
+declare function createReferencesAutocompleteProvider(current: AutocompleteProvider, getReferences: () => readonly ReferenceInfo[]): AutocompleteProvider;
+declare function bridgeReferencesAutocomplete(input: {
+  readonly host: AutocompleteHost;
+  readonly getReferences: () => readonly ReferenceInfo[];
+}): AddAutocompleteProvider;
+declare function registerReferencesExtension(pi: ExtensionAPI): void;
+//#endregion
+export { EnsureRepositoryInput, FileRepositoryReference, GitReferenceConfig, GitReferenceConfigSchema, GitReferenceSource, LocalReferenceConfig, LocalReferenceConfigSchema, LocalReferenceSource, MaterializeReferencesResult, ReferenceDiagnostic, ReferenceEntryConfig, ReferenceEntryConfigSchema, ReferenceErrorCode, ReferenceInfo, ReferenceInvocation, ReferenceSource, ReferencesConfigSchema, ReferencesError, ReferencesRuntimeConfig, RemoteRepositoryReference, RepositoryCacheResult, RepositoryReference, ResolvedReferences, bridgeReferencesAutocomplete, createReferencesAutocompleteProvider, registerReferencesExtension as default, defaultReferencesCacheRoot, ensureRepository, findReferenceInvocations, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, materializeGitReferences, mergeReferencesConfig, parseRemoteRepositoryReference, parseRepositoryReference, referencesConfigModule, renderReferenceGuidance, renderReferenceInvocation, repositoryCacheIdentity, repositoryCachePath, resolveConfiguredReferences, resolveReferenceToken, rewriteReferencePath, sameRepositoryReference, validReferenceAlias, validateBranch };

package/dist/extension.js

@@ -0,0 +1,414 @@
+import { GitReferenceConfigSchema, LocalReferenceConfigSchema, ReferenceEntryConfigSchema, ReferencesConfigSchema, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, mergeReferencesConfig, referencesConfigModule, validReferenceAlias } from "./config.js";
+import { ReferencesError, parseRemoteRepositoryReference, parseRepositoryReference, repositoryCacheIdentity, repositoryCachePath, sameRepositoryReference, validateBranch } from "./repository.js";
+import { defaultReferencesCacheRoot, ensureRepository } from "./cache.js";
+import { materializeGitReferences, renderReferenceGuidance, resolveConfiguredReferences } from "./references.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Result } from "better-result";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+//#region src/extension.ts
+const STATUS_KEY = "ohm-references";
+const MAX_AUTOCOMPLETE_ITEMS = 30;
+const AUTOCOMPLETE_DESCRIPTION_TAG = "[Ω:REF]";
+const REFERENCE_MESSAGE_TYPE = "ohm-reference";
+const REFERENCE_INVOCATION_BLURB = "The user inserted this project reference with @ autocomplete. Use the resolved path when reading or searching this referenced project.";
+const EMPTY_REFERENCES_STATE = {
+	references: [],
+	diagnostics: []
+};
+const BRIDGED_HOSTS = new WeakMap();
+function aliasValue(reference, relative) {
+	const suffix = relative ? `/${relative.replaceAll("\\", "/")}` : "";
+	return `@${reference.name}${suffix}`;
+}
+function extractReferenceToken(textBeforeCursor) {
+	const match = textBeforeCursor.match(/(?:^|[ \t])@([^\s@]*)$/);
+	return match?.[1];
+}
+function visibleReferences(references) {
+	return references.filter((reference) => reference.hidden !== true);
+}
+function taggedDescription(description) {
+	return `${AUTOCOMPLETE_DESCRIPTION_TAG} ${description}`;
+}
+function aliasItems(references, token) {
+	const normalized = token.toLowerCase();
+	return [...visibleReferences(references)].filter((reference) => reference.name.toLowerCase().includes(normalized)).sort((left, right) => left.name.localeCompare(right.name)).slice(0, MAX_AUTOCOMPLETE_ITEMS).map((reference) => ({
+		value: aliasValue(reference),
+		label: `@${reference.name}`,
+		description: reference.source.type === "git" ? taggedDescription(reference.source.repository) : taggedDescription(reference.source.path)
+	}));
+}
+async function childItems(input) {
+	const parentTail = input.tail.endsWith("/") ? input.tail : path.dirname(input.tail);
+	const query = input.tail.endsWith("/") ? "" : path.basename(input.tail);
+	const parent = parentTail === "." ? input.reference.path : path.join(input.reference.path, parentTail);
+	const entries = await fs.readdir(parent, { withFileTypes: true }).then((items) => items, () => []);
+	return entries.filter((entry) => entry.name.toLowerCase().startsWith(query.toLowerCase())).sort((left, right) => {
+		if (left.isDirectory() && !right.isDirectory()) return -1;
+		if (!left.isDirectory() && right.isDirectory()) return 1;
+		return left.name.localeCompare(right.name);
+	}).slice(0, MAX_AUTOCOMPLETE_ITEMS).map((entry) => {
+		const relative = parentTail === "." ? entry.name : path.join(parentTail, entry.name);
+		const display = `@${input.reference.name}/${relative.replaceAll("\\", "/")}${entry.isDirectory() ? "/" : ""}`;
+		const relativeDisplay = `${relative.replaceAll("\\", "/")}${entry.isDirectory() ? "/" : ""}`;
+		return {
+			value: aliasValue(input.reference, `${relative}${entry.isDirectory() ? "/" : ""}`),
+			label: display,
+			description: taggedDescription(relativeDisplay)
+		};
+	});
+}
+function escapeXmlAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function escapeXmlText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function resolveReferenceTarget(input) {
+	if (!input.suffix) return {
+		path: input.reference.path,
+		relativePath: undefined
+	};
+	const withoutLeadingSlash = input.suffix.startsWith("/") ? input.suffix.slice(1) : input.suffix;
+	if (!withoutLeadingSlash) return {
+		path: input.reference.path,
+		relativePath: undefined
+	};
+	if (withoutLeadingSlash.includes("\0") || withoutLeadingSlash.includes("\\")) {
+		return undefined;
+	}
+	const normalized = path.normalize(withoutLeadingSlash);
+	if (normalized === "." || path.isAbsolute(normalized)) return undefined;
+	const target = path.join(input.reference.path, normalized);
+	const relative = path.relative(input.reference.path, target);
+	if (relative === "") return {
+		path: target,
+		relativePath: undefined
+	};
+	if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+		return undefined;
+	}
+	return {
+		path: target,
+		relativePath: normalized.replaceAll("\\", "/")
+	};
+}
+function resolveReferenceToken(token, references) {
+	if (!token.startsWith("@")) return undefined;
+	const slashIndex = token.indexOf("/");
+	const name = slashIndex === -1 ? token.slice(1) : token.slice(1, slashIndex);
+	const suffix = slashIndex === -1 ? undefined : token.slice(slashIndex + 1);
+	const reference = references.find((candidate) => candidate.name === name);
+	if (!reference) return undefined;
+	const target = resolveReferenceTarget({
+		reference,
+		suffix
+	});
+	if (!target) return undefined;
+	return {
+		name: reference.name,
+		token,
+		path: target.path,
+		rootPath: reference.path,
+		relativePath: target.relativePath,
+		description: reference.description
+	};
+}
+function resolveReferenceTokenInText(token, references) {
+	const direct = resolveReferenceToken(token, references);
+	if (direct) return direct;
+	const trimmed = token.replace(/[.:;!?)}\]]+$/u, "");
+	if (trimmed === token) return undefined;
+	return resolveReferenceToken(trimmed, references);
+}
+function findReferenceInvocations(text, references) {
+	const matches = text.matchAll(/(?:^|[\s([{])(@([^/\s`,]+)(?:\/([^\s`,]*))?)/g);
+	const invocations = Array.from(matches).map((match) => resolveReferenceTokenInText(match[1] ?? "", references)).filter((invocation) => invocation !== undefined);
+	return [...new Map(invocations.map((invocation) => [invocation.token, invocation])).values()].sort((left, right) => left.token.localeCompare(right.token));
+}
+function renderReferenceInvocation(invocations) {
+	if (invocations.length === 0) return undefined;
+	const groups = Array.from(invocations.reduce((state, invocation) => {
+		const previous = state.get(invocation.name) ?? [];
+		return new Map([...state, [invocation.name, [...previous, invocation]]]);
+	}, new Map()).values()).sort((left, right) => (left[0]?.name ?? "").localeCompare(right[0]?.name ?? ""));
+	return groups.map((group) => {
+		const reference = group[0];
+		if (!reference) return "";
+		const description = reference.description ? escapeXmlText(reference.description) : "";
+		const files = group.filter((invocation) => invocation.relativePath !== undefined).sort((left, right) => left.relativePath?.localeCompare(right.relativePath ?? "") ?? 0);
+		return [
+			`<reference name="${escapeXmlAttribute(reference.name)}" token="${escapeXmlAttribute(`@${reference.name}`)}" path="${escapeXmlAttribute(reference.rootPath)}">`,
+			escapeXmlText(REFERENCE_INVOCATION_BLURB),
+			...description ? ["", description] : [],
+			...files.length > 0 ? [
+				"",
+				"<reference_files>",
+				...files.map((file) => `  <file token="${escapeXmlAttribute(file.token)}" relative_path="${escapeXmlAttribute(file.relativePath ?? "")}" path="${escapeXmlAttribute(file.path)}" />`),
+				"</reference_files>"
+			] : [],
+			"</reference>"
+		].join("\n");
+	}).join("\n\n");
+}
+function rewriteReferencePath(value, references) {
+	if (!value?.startsWith("@")) return value;
+	return resolveReferenceToken(value, references)?.path ?? value;
+}
+function createReferenceMessage(invocations) {
+	const content = renderReferenceInvocation(invocations);
+	if (!content) return undefined;
+	return {
+		customType: REFERENCE_MESSAGE_TYPE,
+		content,
+		display: true,
+		details: { references: invocations }
+	};
+}
+function renderReferenceMessage(details, expanded, color) {
+	const references = details?.references ?? [];
+	const groups = Array.from(references.reduce((state, reference) => {
+		const previous = state.get(reference.name) ?? [];
+		return new Map([...state, [reference.name, [...previous, reference]]]);
+	}, new Map())).sort((left, right) => left[0].localeCompare(right[0]));
+	const labels = groups.length > 0 ? groups.map(([name, group]) => {
+		const pathCount = group.filter((reference) => reference.relativePath !== undefined).length;
+		return pathCount > 0 ? `@${name} (${pathCount} paths)` : `@${name}`;
+	}).join(" ") : "references";
+	const box = new Box(1, 1, (text) => color.bg("customMessageBg", text));
+	const label = color.fg("customMessageLabel", "\x1B[1m[ref]\x1B[22m");
+	if (!expanded) {
+		box.addChild(new Text(`${label} ${color.fg("customMessageText", labels)} ${color.fg("dim", "(ctrl+o to expand)")}`, 0, 0));
+		return box;
+	}
+	box.addChild(new Text(`${label} ${color.fg("customMessageText", labels)}`, 0, 0));
+	box.addChild(new Text(color.fg("customMessageText", references.map((reference) => {
+		const description = reference.description ? `\n${reference.description}` : "";
+		const relative = reference.relativePath ? `\nrelative: ${reference.relativePath}` : "";
+		return `${reference.token}${relative}\npath: ${reference.path}${description}`;
+	}).join("\n\n")), 0, 0));
+	return box;
+}
+function uniqueItems(items) {
+	return Array.from(items.reduce((state, item) => {
+		const key = `${item.value}\u0000${item.label}`;
+		if (state.has(key)) return state;
+		return new Map([...state, [key, item]]);
+	}, new Map()).values());
+}
+function mergeSuggestions(input) {
+	if (!input.references) return input.current;
+	if (!input.current) return input.references;
+	if (input.references.prefix !== input.current.prefix) return input.references;
+	return {
+		prefix: input.references.prefix,
+		items: [...uniqueItems([...input.references.items, ...input.current.items])]
+	};
+}
+async function referenceSuggestions(input) {
+	const slashIndex = input.token.indexOf("/");
+	if (slashIndex === -1) {
+		const items = aliasItems(input.references, input.token);
+		if (items.length === 0) return null;
+		return {
+			items: [...items],
+			prefix: `@${input.token}`
+		};
+	}
+	const alias = input.token.slice(0, slashIndex);
+	const tail = input.token.slice(slashIndex + 1);
+	const reference = visibleReferences(input.references).find((candidate) => candidate.name === alias);
+	if (!reference) return null;
+	const items = await childItems({
+		reference,
+		token: input.token,
+		tail
+	});
+	if (items.length === 0) return null;
+	return {
+		items: [...items],
+		prefix: `@${input.token}`
+	};
+}
+function createReferencesAutocompleteProvider(current, getReferences) {
+	return {
+		triggerCharacters: ["@"],
+		async getSuggestions(lines, cursorLine, cursorCol, options) {
+			const currentLine = lines[cursorLine] ?? "";
+			const textBeforeCursor = currentLine.slice(0, cursorCol);
+			const token = extractReferenceToken(textBeforeCursor);
+			if (token === undefined) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			const [references, currentSuggestions] = await Promise.all([referenceSuggestions({
+				references: getReferences(),
+				token
+			}), current.getSuggestions(lines, cursorLine, cursorCol, options)]);
+			if (options.signal.aborted) return null;
+			return mergeSuggestions({
+				references,
+				current: currentSuggestions
+			});
+		},
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		}
+	};
+}
+function bridgeReferencesAutocomplete(input) {
+	const existing = BRIDGED_HOSTS.get(input.host);
+	if (existing) return existing;
+	const add = input.host.addAutocompleteProvider.bind(input.host);
+	input.host.addAutocompleteProvider = (factory) => {
+		add((current) => createReferencesAutocompleteProvider(factory(current), input.getReferences));
+	};
+	BRIDGED_HOSTS.set(input.host, add);
+	return add;
+}
+async function loadResolvedReferences(cwd) {
+	const config = await loadReferencesConfig(cwd);
+	if (Result.isError(config)) return Result.err(config.error);
+	return Result.ok({
+		loaded: config.value.loaded,
+		resolved: resolveConfiguredReferences({
+			cwd,
+			config: config.value.config
+		})
+	});
+}
+function renderReferences(references) {
+	if (references.length === 0) return "No references configured.";
+	return references.slice().sort((left, right) => left.name.localeCompare(right.name)).map((reference) => {
+		const source = reference.source.type === "git" ? `${reference.source.repository}${reference.source.branch ? `#${reference.source.branch}` : ""}` : reference.source.path;
+		const flags = [reference.description ? "described" : "no description", reference.hidden ? "hidden" : "visible"];
+		return [
+			`@${reference.name}`,
+			`  path: ${reference.path}`,
+			`  source: ${source}`,
+			`  ${flags.join(" · ")}`
+		].join("\n");
+	}).join("\n\n");
+}
+function startMaterialization(input) {
+	void materializeGitReferences({
+		pi: input.pi,
+		references: input.references,
+		...input.ctx.signal ? { signal: input.ctx.signal } : {}
+	}).then((result) => {
+		if (!input.ctx.hasUI) return;
+		if (result.diagnostics.length > 0) {
+			input.ctx.ui.notify(`references: ${result.diagnostics.length} git materialization issue(s)`, "error");
+			return;
+		}
+		if (result.results.length > 0) {
+			input.ctx.ui.setStatus(STATUS_KEY, `refs:${input.references.length}`);
+		}
+	});
+}
+function registerReferencesExtension(pi) {
+	const states = new Map();
+	pi.registerMessageRenderer(REFERENCE_MESSAGE_TYPE, (message, { expanded }, theme) => renderReferenceMessage(message.details, expanded, theme));
+	pi.on("session_start", async (_event, ctx) => {
+		const key = ctx.sessionManager.getSessionFile() ?? ctx.cwd;
+		const getReferences = () => states.get(key)?.references ?? EMPTY_REFERENCES_STATE.references;
+		const addAutocomplete = ctx.hasUI ? bridgeReferencesAutocomplete({
+			host: ctx.ui,
+			getReferences
+		}) : undefined;
+		const loaded = await loadResolvedReferences(ctx.cwd);
+		if (Result.isError(loaded)) return;
+		const references = loaded.value.resolved.references;
+		states.set(key, loaded.value.resolved);
+		if (ctx.hasUI) {
+			ctx.ui.setStatus(STATUS_KEY, `refs:${references.length}`);
+			addAutocomplete?.((current) => createReferencesAutocompleteProvider(current, getReferences));
+		}
+		startMaterialization({
+			pi,
+			ctx,
+			references
+		});
+	});
+	pi.on("before_agent_start", async (event, ctx) => {
+		const loaded = await loadResolvedReferences(ctx.cwd);
+		if (Result.isError(loaded)) return;
+		const references = loaded.value.resolved.references;
+		const guidance = renderReferenceGuidance(references);
+		const invocations = findReferenceInvocations(event.prompt, references);
+		const message = createReferenceMessage(invocations);
+		if (!guidance && !message) return;
+		startMaterialization({
+			pi,
+			ctx,
+			references
+		});
+		return {
+			...message ? { message } : {},
+			...guidance ? { systemPrompt: `${event.systemPrompt}\n\n${guidance}` } : {}
+		};
+	});
+	pi.on("tool_call", async (event, ctx) => {
+		const loaded = await loadResolvedReferences(ctx.cwd);
+		if (Result.isError(loaded)) return;
+		const references = loaded.value.resolved.references;
+		if (isToolCallEventType("read", event)) {
+			event.input.path = rewriteReferencePath(event.input.path, references) ?? event.input.path;
+			return;
+		}
+		if (isToolCallEventType("ls", event)) {
+			event.input.path = rewriteReferencePath(event.input.path, references);
+			return;
+		}
+		if (isToolCallEventType("grep", event)) {
+			event.input.path = rewriteReferencePath(event.input.path, references);
+			return;
+		}
+		if (isToolCallEventType("find", event)) {
+			event.input.path = rewriteReferencePath(event.input.path, references);
+			return;
+		}
+		if (isToolCallEventType("edit", event) || isToolCallEventType("write", event)) {
+			const invocation = resolveReferenceToken(event.input.path, references);
+			if (invocation) {
+				return {
+					block: true,
+					reason: "Reference aliases are read-only. Use an absolute path if mutation is intentional."
+				};
+			}
+		}
+	});
+	pi.registerCommand("ohm-references", {
+		description: "Show resolved project references",
+		handler: async (_args, ctx) => {
+			const loaded = await loadResolvedReferences(ctx.cwd);
+			if (Result.isError(loaded)) {
+				console.log(loaded.error.message);
+				return;
+			}
+			const text = [
+				"Pi OHM references",
+				"",
+				renderReferences(loaded.value.resolved.references),
+				"",
+				`loadedFrom: ${loaded.value.loaded.loadedFrom.length > 0 ? loaded.value.loaded.loadedFrom.join(", ") : "defaults"}`,
+				...loaded.value.resolved.diagnostics.length > 0 ? [
+					"",
+					"Diagnostics:",
+					...loaded.value.resolved.diagnostics.map((diagnostic) => `- ${diagnostic.name}: ${diagnostic.message}`)
+				] : []
+			].join("\n");
+			if (!ctx.hasUI) {
+				console.log(text);
+				return;
+			}
+			await ctx.ui.editor("pi-ohm references", text);
+		}
+	});
+}
+
+//#endregion
+export { GitReferenceConfigSchema, LocalReferenceConfigSchema, ReferenceEntryConfigSchema, ReferencesConfigSchema, ReferencesError, bridgeReferencesAutocomplete, createReferencesAutocompleteProvider, registerReferencesExtension as default, defaultReferencesCacheRoot, ensureRepository, findReferenceInvocations, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, materializeGitReferences, mergeReferencesConfig, parseRemoteRepositoryReference, parseRepositoryReference, referencesConfigModule, renderReferenceGuidance, renderReferenceInvocation, repositoryCacheIdentity, repositoryCachePath, resolveConfiguredReferences, resolveReferenceToken, rewriteReferencePath, sameRepositoryReference, validReferenceAlias, validateBranch };

package/dist/references.d.ts

@@ -0,0 +1,54 @@
+import { ReferencesError } from "./repository.js";
+import { RepositoryCacheResult } from "./cache.js";
+import { ReferencesRuntimeConfig } from "./config.js";
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+//#region src/references.d.ts
+interface LocalReferenceSource {
+  readonly type: "local";
+  readonly path: string;
+  readonly description?: string;
+  readonly hidden?: boolean;
+}
+interface GitReferenceSource {
+  readonly type: "git";
+  readonly repository: string;
+  readonly branch?: string;
+  readonly description?: string;
+  readonly hidden?: boolean;
+}
+type ReferenceSource = LocalReferenceSource | GitReferenceSource;
+interface ReferenceInfo {
+  readonly name: string;
+  readonly path: string;
+  readonly description?: string;
+  readonly hidden?: boolean;
+  readonly source: ReferenceSource;
+}
+interface ReferenceDiagnostic {
+  readonly name: string;
+  readonly message: string;
+  readonly cause: ReferencesError;
+}
+interface ResolvedReferences {
+  readonly references: readonly ReferenceInfo[];
+  readonly diagnostics: readonly ReferenceDiagnostic[];
+}
+interface MaterializeReferencesResult {
+  readonly results: readonly RepositoryCacheResult[];
+  readonly diagnostics: readonly ReferenceDiagnostic[];
+}
+declare function resolveConfiguredReferences(input: {
+  readonly cwd: string;
+  readonly config: ReferencesRuntimeConfig;
+  readonly cacheRoot?: string;
+}): ResolvedReferences;
+declare function renderReferenceGuidance(references: readonly ReferenceInfo[]): string | undefined;
+declare function materializeGitReferences(input: {
+  readonly pi: Pick<ExtensionAPI, "exec">;
+  readonly references: readonly ReferenceInfo[];
+  readonly cacheRoot?: string;
+  readonly signal?: AbortSignal;
+}): Promise<MaterializeReferencesResult>;
+//#endregion
+export { GitReferenceSource, LocalReferenceSource, MaterializeReferencesResult, ReferenceDiagnostic, ReferenceInfo, ReferenceSource, ResolvedReferences, materializeGitReferences, renderReferenceGuidance, resolveConfiguredReferences };