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

package/README.md

@@ -0,0 +1,76 @@
+# @pi-ohm/references
+
+Project references for Pi. Adds named local directories and Git repositories to
+agent system prompt guidance, with `@alias` autocomplete in the TUI.
+
+```bash
+pi install npm:@pi-ohm/references
+```
+
+Config lives under `references` in `.pi/ohm.json` or global `ohm.json`.
+
+```jsonc
+{
+  "references": {
+    "docs": {
+      "path": "../product-docs",
+      "description": "Use for product behavior and documentation conventions",
+    },
+    "sdk": {
+      "repository": "anomalyco/opencode-sdk-js",
+      "branch": "main",
+      "description": "Use for JavaScript SDK implementation details",
+    },
+  },
+}
+```
+
+No model-facing tool is registered. Agents use existing Pi tools with absolute
+paths from system guidance and per-prompt reference invocation blocks.
+
+## Prompt references
+
+Autocomplete inserts the reference alias, not the absolute path. If you select
+`@sdk`, the editor keeps `@sdk`.
+
+When a prompt contains `@alias` or `@alias/path`, the package adds a collapsed
+custom message for the agent with the resolved root path and grouped mentioned
+paths:
+
+```xml
+<reference name="sdk" token="@sdk" path="/home/user/.local/share/pi-ohm/agent/references/repos/github.com/anomalyco/opencode-sdk-js">
+The user inserted this project reference with @ autocomplete. Use the resolved path when reading or searching this referenced project.
+
+Use for JavaScript SDK implementation details
+
+<reference_files>
+  <file token="@sdk/packages/client" relative_path="packages/client" path="/home/user/.local/share/pi-ohm/agent/references/repos/github.com/anomalyco/opencode-sdk-js/packages/client" />
+  <file token="@sdk/README.md" relative_path="README.md" path="/home/user/.local/share/pi-ohm/agent/references/repos/github.com/anomalyco/opencode-sdk-js/README.md" />
+</reference_files>
+</reference>
+```
+
+The TUI shows this as a compact `[ref] @alias` block. Use `ctrl+o` to expand it.
+Nested autocomplete rows show relative descriptions like `packages/client`, not
+the full cache path. The XML still includes the exact absolute paths.
+
+Read-only path tools (`read`, `ls`, `grep`, `find`) also accept `@alias` and
+`@alias/path`; the extension rewrites those tool path arguments to absolute
+paths before execution.
+
+## Quirks
+
+Pi autocomplete providers are wrapper-ordered. A provider registered later can
+handle `@...` first and stop delegation, so file-search extensions can hide
+reference aliases.
+
+`@ff-labs/pi-fff` does this intentionally for FFF-backed `@` file search: it
+queries FFF first and only delegates when FFF returns no results. Since
+`@opencode` can fuzzy-match normal project files, references may never see the
+request if pi-fff is the outer wrapper.
+
+This package remedies that by bridging `ctx.ui.addAutocompleteProvider` during
+session startup. Providers registered after references are wrapped with
+references outside them, and providers registered before references are still
+wrapped by the normal registration path. Reference matches are merged first, so
+`@alias` entries stay visible without disabling pi-fff.

package/SPEC.md

@@ -0,0 +1,186 @@
+# @pi-ohm/references spec
+
+## Goal
+
+Add OpenCode-style project references to Pi as a small Pi package. A reference is
+a named local directory or Git repository that Pi can advertise to the agent as
+readable supporting context.
+
+References are not slash commands. Slash commands are user-only in Pi, so the
+agent must receive references through normal system prompt guidance and existing
+tools.
+
+## OpenCode behavior to replicate
+
+OpenCode exposes no dedicated model-facing reference tool. References are wired
+through:
+
+1. config parsing,
+2. local/Git materialization,
+3. system prompt guidance for references with descriptions,
+4. UI autocomplete and file attachments,
+5. external-directory permission allowlisting.
+
+This package should follow the same shape for Pi:
+
+- Do not register a model-facing `references` tool.
+- Do not make `/commands` part of the agent contract.
+- Inject resolved references into `before_agent_start` system prompt text.
+- Use Pi's existing read/bash/edit tools by giving the model absolute paths.
+
+## Config
+
+Config namespace: `references` in `.pi/ohm.json` and global `ohm.json` through
+`@pi-ohm/core/config`.
+
+Shape:
+
+```jsonc
+{
+  "references": {
+    "docs": {
+      "path": "../product-docs",
+      "description": "Use for product behavior and docs conventions",
+    },
+    "sdk": {
+      "repository": "anomalyco/opencode-sdk-js",
+      "branch": "main",
+      "description": "Use for JavaScript SDK implementation details",
+    },
+    "local-shorthand": "./docs",
+    "git-shorthand": "owner/repo",
+  },
+}
+```
+
+Entries:
+
+- `string | { path, description?, hidden? } | { repository, branch?, description?, hidden? }`
+- string values starting with `.`, `/`, or `~` are local paths
+- all other string values are Git repository references
+- aliases cannot be empty or contain `/`, whitespace, backticks, or commas
+- invalid aliases are ignored
+
+Path resolution:
+
+- `~/x` resolves against user home
+- absolute paths stay absolute
+- relative paths resolve from the current Pi cwd because `@pi-ohm/core/config`
+  does not expose per-file config origins
+
+## Git repository references
+
+Accept:
+
+- `owner/repo`
+- `github:owner/repo`
+- `github.com/owner/repo`
+- `gitlab.com/group/repo`
+- `git@github.com:owner/repo.git`
+- `https://github.com/owner/repo.git`
+- `ssh://git@github.com/owner/repo`
+
+Normalization:
+
+- trim input
+- remove leading `git+`
+- strip fragments after `#`
+- strip trailing slashes
+- strip `.git` from path segments
+
+Safety:
+
+- host cannot be empty, start with `-`, or contain whitespace, `/`, or `\`
+- path segment cannot be `.`, `..`, contain `:`, whitespace, `/`, or `\`
+- branch can contain alphanumeric, `/`, `_`, `.`, and `-`
+- branch cannot start with `-` or contain `..`
+- `file:` repositories are not supported through `repository`; use `path`
+
+Cache path:
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/pi-ohm/agent/references/repos/<host>/<path>
+```
+
+Materialization:
+
+- Git refs appear in guidance immediately at their deterministic cache path
+- clone/fetch happens asynchronously on `session_start`
+- existing cache with mismatched origin is deleted and recloned
+- clone uses `git clone --depth 100 [--branch branch] -- remote target`
+- refresh uses `git fetch --all --prune` and `git reset --hard`
+
+## Runtime model
+
+Runtime reference info:
+
+```ts
+type ReferenceInfo = {
+  name: string;
+  path: string;
+  description?: string;
+  hidden?: boolean;
+  source:
+    | { type: "local"; path: string; description?: string; hidden?: boolean }
+    | { type: "git"; repository: string; branch?: string; description?: string; hidden?: boolean };
+};
+```
+
+`hidden` only affects UI autocomplete. A hidden reference with a description is
+still included in agent guidance.
+
+Only references with descriptions are advertised in system prompt text.
+
+## System prompt guidance
+
+Append to `before_agent_start` only when at least one described reference exists:
+
+```xml
+Project references provide additional directories that can be accessed when relevant.
+<available_references>
+  <reference>
+    <name>docs</name>
+    <path>/absolute/path/to/docs</path>
+    <description>Use for product behavior and docs conventions</description>
+  </reference>
+</available_references>
+```
+
+Sort by reference name for deterministic prompt text.
+
+## User UI
+
+Initial package can include:
+
+- `/ohm-references` user command to inspect resolved references and cache status
+- optional autocomplete provider for `@alias` and `@alias/path` that keeps the
+  alias in the editor, shows nested picker descriptions as relative paths, and
+  emits a collapsed custom reference message on submit
+- grouped XML invocation blocks: one `<reference>` per alias with mentioned
+  `@alias/path` entries under `<reference_files>`
+- read-only tool path rewriting for `read`, `ls`, `grep`, and `find` so models
+  may use `@alias` path arguments without a dedicated reference tool
+
+The custom message renderer should mirror Pi's skill invocation shape: compact
+by default, expandable with the normal tool-output expansion key.
+
+## Agent tools
+
+This package exposes no new model-facing tool. The model uses existing Pi tools:
+
+- `read` to inspect files/directories by absolute path
+- `read`, `ls`, `grep`, and `find` may receive `@alias` paths, rewritten before
+  execution
+- `bash` for allowed shell inspection
+- `edit`/`write` only if normal Pi permissions allow mutation
+
+References do not grant mutation permission.
+
+## Out of scope for first implementation
+
+- DB-backed clone metadata
+- permission-policy mutation
+- background file watching
+- remote reference registries
+- branch-per-alias multi-checkout support for the same repo
+- rich TUI panels

package/dist/cache.d.ts

@@ -0,0 +1,26 @@
+import { ReferencesError, RemoteRepositoryReference } from "./repository.js";
+import { Result } from "better-result";
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+//#region src/cache.d.ts
+interface RepositoryCacheResult {
+  readonly repository: string;
+  readonly host: string;
+  readonly remote: string;
+  readonly localPath: string;
+  readonly status: "cached" | "cloned" | "refreshed";
+  readonly head?: string;
+  readonly branch?: string;
+}
+interface EnsureRepositoryInput {
+  readonly pi: Pick<ExtensionAPI, "exec">;
+  readonly reference: RemoteRepositoryReference;
+  readonly branch?: string;
+  readonly refresh?: boolean;
+  readonly signal?: AbortSignal;
+  readonly root?: string;
+}
+declare function defaultReferencesCacheRoot(): string;
+declare function ensureRepository(input: EnsureRepositoryInput): Promise<Result<RepositoryCacheResult, ReferencesError>>;
+//#endregion
+export { EnsureRepositoryInput, RepositoryCacheResult, defaultReferencesCacheRoot, ensureRepository };

package/dist/cache.js

@@ -0,0 +1,261 @@
+import { ReferencesError, parseRepositoryReference, repositoryCachePath, sameRepositoryReference, validateBranch } from "./repository.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Result } from "better-result";
+import { resolveOhmAgentDataHome } from "@pi-ohm/core/paths";
+
+//#region src/cache.ts
+const GIT_TIMEOUT_MS = 12e4;
+function defaultReferencesCacheRoot() {
+	return path.join(resolveOhmAgentDataHome(), "references", "repos");
+}
+function causeMessage(cause) {
+	if (cause instanceof Error && cause.message.trim().length > 0) return cause.message;
+	if (typeof cause === "string" && cause.trim().length > 0) return cause;
+	return String(cause);
+}
+function cacheError(input) {
+	return new ReferencesError(input);
+}
+async function exists(target) {
+	return fs.access(target).then(() => true, () => false);
+}
+async function cacheOperation(input) {
+	return Result.tryPromise({
+		try: input.run,
+		catch: (cause) => cacheError({
+			code: "cache_operation_failed",
+			path: input.target,
+			message: `${input.stage} failed for ${input.target}: ${causeMessage(cause)}`,
+			cause
+		})
+	});
+}
+async function git(input) {
+	const result = await Result.tryPromise({
+		try: () => input.pi.exec("git", [...input.args], {
+			cwd: input.cwd,
+			timeout: GIT_TIMEOUT_MS,
+			...input.signal ? { signal: input.signal } : {}
+		}),
+		catch: (cause) => cacheError({
+			code: "git_command_failed",
+			repository: input.repository,
+			message: `git ${input.args.join(" ")} failed: ${causeMessage(cause)}`,
+			cause
+		})
+	});
+	if (Result.isError(result)) return result;
+	if (result.value.code === 0) return result;
+	return Result.err(cacheError({
+		code: "git_command_failed",
+		repository: input.repository,
+		message: result.value.stderr.trim() || result.value.stdout.trim() || `git ${input.args.join(" ")} failed with exit code ${result.value.code}`
+	}));
+}
+async function gitOptional(input) {
+	const result = await Result.tryPromise({
+		try: () => input.pi.exec("git", [...input.args], {
+			cwd: input.cwd,
+			timeout: GIT_TIMEOUT_MS,
+			...input.signal ? { signal: input.signal } : {}
+		}),
+		catch: (cause) => cause
+	});
+	if (Result.isError(result)) return undefined;
+	if (result.value.code !== 0) return undefined;
+	const trimmed = result.value.stdout.trim();
+	if (trimmed.length === 0) return undefined;
+	return trimmed;
+}
+function statusForRepository(input) {
+	if (!input.reuse) return "cloned";
+	if (input.branchMatches === false || input.refresh) return "refreshed";
+	return "cached";
+}
+async function resetTarget(input) {
+	if (input.branch) return `origin/${input.branch}`;
+	const remoteHead = await gitOptional({
+		pi: input.pi,
+		cwd: input.cwd,
+		args: ["symbolic-ref", "refs/remotes/origin/HEAD"],
+		signal: input.signal
+	});
+	if (remoteHead) return remoteHead.replace(/^refs\/remotes\//, "");
+	const branch = await gitOptional({
+		pi: input.pi,
+		cwd: input.cwd,
+		args: [
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			"HEAD"
+		],
+		signal: input.signal
+	});
+	if (branch) return `origin/${branch}`;
+	return "HEAD";
+}
+async function ensureRepository(input) {
+	if (input.branch) {
+		const branch = validateBranch(input.branch);
+		if (Result.isError(branch)) return Result.err(branch.error);
+	}
+	const root = input.root ?? defaultReferencesCacheRoot();
+	const repository = input.reference.label;
+	const localPath = repositoryCachePath(root, input.reference);
+	const cloneTargetResult = parseRepositoryReference(input.reference.remote);
+	const cloneTarget = Result.isOk(cloneTargetResult) ? cloneTargetResult.value : input.reference;
+	const ensured = await cacheOperation({
+		stage: "ensure repository cache directory",
+		target: localPath,
+		run: () => fs.mkdir(path.dirname(localPath), { recursive: true })
+	});
+	if (Result.isError(ensured)) return Result.err(ensured.error);
+	const pathExists = await exists(localPath);
+	const hasGitDir = await exists(path.join(localPath, ".git"));
+	const origin = hasGitDir ? await gitOptional({
+		pi: input.pi,
+		cwd: localPath,
+		args: [
+			"config",
+			"--get",
+			"remote.origin.url"
+		],
+		signal: input.signal
+	}) : undefined;
+	const originReference = origin ? parseRepositoryReference(origin) : undefined;
+	const reuse = hasGitDir && originReference !== undefined && Result.isOk(originReference) && sameRepositoryReference(originReference.value, cloneTarget);
+	if (pathExists && !reuse) {
+		const removed = await cacheOperation({
+			stage: "remove stale repository cache",
+			target: localPath,
+			run: () => fs.rm(localPath, {
+				recursive: true,
+				force: true
+			})
+		});
+		if (Result.isError(removed)) return Result.err(removed.error);
+	}
+	const currentBranch = reuse ? await gitOptional({
+		pi: input.pi,
+		cwd: localPath,
+		args: [
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			"HEAD"
+		],
+		signal: input.signal
+	}) : undefined;
+	const status = statusForRepository({
+		reuse,
+		refresh: input.refresh,
+		...input.branch ? { branchMatches: currentBranch === input.branch } : {}
+	});
+	if (status === "cloned") {
+		const cloned = await git({
+			pi: input.pi,
+			cwd: path.dirname(localPath),
+			args: [
+				"clone",
+				"--depth",
+				"100",
+				...input.branch ? ["--branch", input.branch] : [],
+				"--",
+				input.reference.remote,
+				localPath
+			],
+			repository,
+			signal: input.signal
+		});
+		if (Result.isError(cloned)) return Result.err(cloned.error);
+	}
+	if (status === "refreshed") {
+		const fetched = await git({
+			pi: input.pi,
+			cwd: localPath,
+			args: [
+				"fetch",
+				"--all",
+				"--prune"
+			],
+			repository,
+			signal: input.signal
+		});
+		if (Result.isError(fetched)) return Result.err(fetched.error);
+		if (input.branch) {
+			const branchFetched = await git({
+				pi: input.pi,
+				cwd: localPath,
+				args: [
+					"fetch",
+					"origin",
+					`+refs/heads/${input.branch}:refs/remotes/origin/${input.branch}`
+				],
+				repository,
+				signal: input.signal
+			});
+			if (Result.isError(branchFetched)) return Result.err(branchFetched.error);
+			const checkedOut = await git({
+				pi: input.pi,
+				cwd: localPath,
+				args: [
+					"checkout",
+					"-B",
+					input.branch,
+					`origin/${input.branch}`
+				],
+				repository,
+				signal: input.signal
+			});
+			if (Result.isError(checkedOut)) return Result.err(checkedOut.error);
+		}
+		const reset = await git({
+			pi: input.pi,
+			cwd: localPath,
+			args: [
+				"reset",
+				"--hard",
+				await resetTarget({
+					pi: input.pi,
+					cwd: localPath,
+					branch: input.branch,
+					...input.signal ? { signal: input.signal } : {}
+				})
+			],
+			repository,
+			signal: input.signal
+		});
+		if (Result.isError(reset)) return Result.err(reset.error);
+	}
+	const head = await gitOptional({
+		pi: input.pi,
+		cwd: localPath,
+		args: ["rev-parse", "HEAD"],
+		signal: input.signal
+	});
+	const branch = await gitOptional({
+		pi: input.pi,
+		cwd: localPath,
+		args: [
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			"HEAD"
+		],
+		signal: input.signal
+	});
+	return Result.ok({
+		repository,
+		host: input.reference.host,
+		remote: input.reference.remote,
+		localPath,
+		status,
+		...head ? { head } : {},
+		...branch ? { branch } : {}
+	});
+}
+
+//#endregion
+export { defaultReferencesCacheRoot, ensureRepository };

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+import { StaticDecode, Type } from "typebox";
+
+//#region src/config.d.ts
+declare const LocalReferenceConfigSchema: Type.TObject<{
+  path: Type.TString;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>;
+declare const GitReferenceConfigSchema: Type.TObject<{
+  repository: Type.TString;
+  branch: Type.TOptional<Type.TString>;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>;
+declare const ReferenceEntryConfigSchema: Type.TUnion<[Type.TString, Type.TObject<{
+  path: Type.TString;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+  repository: Type.TString;
+  branch: Type.TOptional<Type.TString>;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>]>;
+declare const ReferencesConfigSchema: Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TObject<{
+  path: Type.TString;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+  repository: Type.TString;
+  branch: Type.TOptional<Type.TString>;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>]>>;
+type ReferencesConfigPatch = StaticDecode<typeof ReferencesConfigSchema>;
+interface LocalReferenceConfig {
+  readonly path: string;
+  readonly description?: string;
+  readonly hidden?: boolean;
+}
+interface GitReferenceConfig {
+  readonly repository: string;
+  readonly branch?: string;
+  readonly description?: string;
+  readonly hidden?: boolean;
+}
+type ReferenceEntryConfig = string | LocalReferenceConfig | GitReferenceConfig;
+type ReferencesRuntimeConfig = Readonly<Record<string, ReferenceEntryConfig>>;
+interface JsonMap {
+  readonly [key: string]: unknown;
+}
+declare const referencesConfigModule: import("@pi-ohm/core/config").ExtensionConfigModule<Readonly<Record<string, ReferenceEntryConfig>>, Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TObject<{
+  path: Type.TString;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>, Type.TObject<{
+  repository: Type.TString;
+  branch: Type.TOptional<Type.TString>;
+  description: Type.TOptional<Type.TString>;
+  hidden: Type.TOptional<Type.TBoolean>;
+}>]>>>;
+declare function isJsonMap(value: unknown): value is JsonMap;
+declare function validReferenceAlias(name: string): boolean;
+declare function mergeReferencesConfig(current: ReferencesRuntimeConfig | undefined, patch: ReferencesConfigPatch): ReferencesRuntimeConfig;
+declare function isReferencesRuntimeConfig(value: unknown): value is ReferencesRuntimeConfig;
+declare function loadReferencesConfig(cwd: string): Promise<import("better-result").Err<never, import("@pi-ohm/core/config").ExtensionConfigRuntimeError> | import("better-result").Ok<{
+  loaded: import("@pi-ohm/core/config").LoadedExtensionConfig;
+  config: Readonly<Record<string, ReferenceEntryConfig>>;
+}, never>>;
+//#endregion
+export { GitReferenceConfig, GitReferenceConfigSchema, LocalReferenceConfig, LocalReferenceConfigSchema, ReferenceEntryConfig, ReferenceEntryConfigSchema, ReferencesConfigSchema, ReferencesRuntimeConfig, isJsonMap, isReferencesRuntimeConfig, loadReferencesConfig, mergeReferencesConfig, referencesConfigModule, validReferenceAlias };