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

package/dist/references.js

@@ -0,0 +1,180 @@
+import { parseRemoteRepositoryReference, repositoryCachePath, validateBranch } from "./repository.js";
+import { defaultReferencesCacheRoot, ensureRepository } from "./cache.js";
+import path from "node:path";
+import { Result } from "better-result";
+import os from "node:os";
+
+//#region src/references.ts
+function expandHome(value) {
+	if (value === "~") return os.homedir();
+	if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+	return value;
+}
+function resolveLocalPath(cwd, value) {
+	const expanded = expandHome(value);
+	if (path.isAbsolute(expanded)) return path.normalize(expanded);
+	return path.resolve(cwd, expanded);
+}
+function stringEntryIsLocal(value) {
+	return value.startsWith(".") || value.startsWith("/") || value.startsWith("~");
+}
+function entryDescription(entry) {
+	return entry.description;
+}
+function entryHidden(entry) {
+	return entry.hidden;
+}
+function resolveEntry(input) {
+	if (typeof input.entry === "string" && stringEntryIsLocal(input.entry)) {
+		const source = {
+			type: "local",
+			path: resolveLocalPath(input.cwd, input.entry)
+		};
+		return Result.ok({
+			name: input.name,
+			path: source.path,
+			source
+		});
+	}
+	if (typeof input.entry !== "string" && "path" in input.entry) {
+		const source = {
+			type: "local",
+			path: resolveLocalPath(input.cwd, input.entry.path),
+			...entryDescription(input.entry) ? { description: entryDescription(input.entry) } : {},
+			...entryHidden(input.entry) !== undefined ? { hidden: entryHidden(input.entry) } : {}
+		};
+		return Result.ok({
+			name: input.name,
+			path: source.path,
+			...source.description ? { description: source.description } : {},
+			...source.hidden !== undefined ? { hidden: source.hidden } : {},
+			source
+		});
+	}
+	const repository = typeof input.entry === "string" ? input.entry : input.entry.repository;
+	const branch = typeof input.entry === "string" ? undefined : input.entry.branch;
+	const description = typeof input.entry === "string" ? undefined : input.entry.description;
+	const hidden = typeof input.entry === "string" ? undefined : input.entry.hidden;
+	const parsed = parseRemoteRepositoryReference(repository);
+	if (Result.isError(parsed)) {
+		return Result.err({
+			name: input.name,
+			message: parsed.error.message,
+			cause: parsed.error
+		});
+	}
+	if (branch) {
+		const validated = validateBranch(branch);
+		if (Result.isError(validated)) {
+			return Result.err({
+				name: input.name,
+				message: validated.error.message,
+				cause: validated.error
+			});
+		}
+	}
+	const source = {
+		type: "git",
+		repository,
+		...branch ? { branch } : {},
+		...description ? { description } : {},
+		...hidden !== undefined ? { hidden } : {}
+	};
+	return Result.ok({
+		name: input.name,
+		path: repositoryCachePath(input.cacheRoot, parsed.value),
+		...description ? { description } : {},
+		...hidden !== undefined ? { hidden } : {},
+		source
+	});
+}
+function resolveConfiguredReferences(input) {
+	const cacheRoot = input.cacheRoot ?? defaultReferencesCacheRoot();
+	return Object.entries(input.config).map(([name, entry]) => resolveEntry({
+		cwd: input.cwd,
+		cacheRoot,
+		name,
+		entry
+	})).reduce((state, result) => {
+		if (Result.isOk(result)) {
+			return {
+				references: [...state.references, result.value],
+				diagnostics: state.diagnostics
+			};
+		}
+		return {
+			references: state.references,
+			diagnostics: [...state.diagnostics, result.error]
+		};
+	}, {
+		references: [],
+		diagnostics: []
+	});
+}
+function renderReferenceGuidance(references) {
+	const available = [...references].filter((reference) => reference.description !== undefined).sort((left, right) => left.name.localeCompare(right.name));
+	if (available.length === 0) return undefined;
+	return [
+		"Project references provide additional directories that can be accessed when relevant.",
+		"<available_references>",
+		...available.flatMap((reference) => [
+			"  <reference>",
+			`    <name>${reference.name}</name>`,
+			`    <path>${reference.path}</path>`,
+			`    <description>${reference.description}</description>`,
+			"  </reference>"
+		]),
+		"</available_references>"
+	].join("\n");
+}
+async function materializeGitReferences(input) {
+	const cacheRoot = input.cacheRoot ?? defaultReferencesCacheRoot();
+	const materialized = await Promise.all(input.references.flatMap((reference) => {
+		if (reference.source.type !== "git") return [];
+		const source = reference.source;
+		return [(async () => {
+			const parsed = parseRemoteRepositoryReference(source.repository);
+			if (Result.isError(parsed)) {
+				return Result.err({
+					name: reference.name,
+					message: parsed.error.message,
+					cause: parsed.error
+				});
+			}
+			const result = await ensureRepository({
+				pi: input.pi,
+				reference: parsed.value,
+				branch: source.branch,
+				refresh: true,
+				root: cacheRoot,
+				...input.signal ? { signal: input.signal } : {}
+			});
+			if (Result.isError(result)) {
+				return Result.err({
+					name: reference.name,
+					message: result.error.message,
+					cause: result.error
+				});
+			}
+			return Result.ok(result.value);
+		})()];
+	}));
+	return materialized.reduce((state, result) => {
+		if (Result.isOk(result)) {
+			return {
+				results: [...state.results, result.value],
+				diagnostics: state.diagnostics
+			};
+		}
+		return {
+			results: state.results,
+			diagnostics: [...state.diagnostics, result.error]
+		};
+	}, {
+		results: [],
+		diagnostics: []
+	});
+}
+
+//#endregion
+export { materializeGitReferences, renderReferenceGuidance, resolveConfiguredReferences };

package/dist/repository.d.ts

@@ -0,0 +1,40 @@
+import { Result } from "better-result";
+
+//#region src/repository.d.ts
+type ReferenceErrorCode = "invalid_repository" | "unsupported_file_repository" | "invalid_branch" | "cache_operation_failed" | "git_command_failed";
+declare const ReferencesError_base: import("better-result").TaggedErrorClass<"ReferencesError", {
+  readonly code: ReferenceErrorCode;
+  readonly message: string;
+  readonly repository?: string;
+  readonly branch?: string;
+  readonly path?: string;
+  readonly cause?: unknown;
+}>;
+declare class ReferencesError extends ReferencesError_base {}
+interface BaseRepositoryReference {
+  readonly host: string;
+  readonly path: string;
+  readonly segments: readonly string[];
+  readonly owner?: string;
+  readonly repo: string;
+  readonly remote: string;
+  readonly label: string;
+}
+interface RemoteRepositoryReference extends BaseRepositoryReference {
+  readonly type: "remote";
+  readonly protocol?: string;
+}
+interface FileRepositoryReference extends BaseRepositoryReference {
+  readonly type: "file";
+  readonly host: "file";
+  readonly protocol: "file:";
+}
+type RepositoryReference = RemoteRepositoryReference | FileRepositoryReference;
+declare function parseRepositoryReference(input: string): Result<RepositoryReference, ReferencesError>;
+declare function parseRemoteRepositoryReference(input: string): Result<RemoteRepositoryReference, ReferencesError>;
+declare function validateBranch(branch: string): Result<string, ReferencesError>;
+declare function repositoryCachePath(root: string, reference: RepositoryReference): string;
+declare function repositoryCacheIdentity(reference: RepositoryReference): string;
+declare function sameRepositoryReference(left: RepositoryReference, right: RepositoryReference): boolean;
+//#endregion
+export { FileRepositoryReference, ReferenceErrorCode, ReferencesError, RemoteRepositoryReference, RepositoryReference, parseRemoteRepositoryReference, parseRepositoryReference, repositoryCacheIdentity, repositoryCachePath, sameRepositoryReference, validateBranch };

package/dist/repository.js

@@ -0,0 +1,165 @@
+import path from "node:path";
+import { Result, TaggedError } from "better-result";
+import { fileURLToPath } from "node:url";
+
+//#region src/repository.ts
+var ReferencesError = class extends TaggedError("ReferencesError")() {};
+function error(input) {
+	return new ReferencesError(input);
+}
+function normalizeInput(input) {
+	return input.trim().replace(/^git\+/, "").replace(/#.*$/, "").replace(/\/+$/, "");
+}
+function trimGitSuffix(input) {
+	return input.replace(/\.git$/, "");
+}
+function parts(input) {
+	return input.split("/").map((item) => trimGitSuffix(item.trim())).filter((item) => item.length > 0);
+}
+function safeHost(input) {
+	return input.length > 0 && !input.startsWith("-") && !/[\s/\\]/.test(input);
+}
+function safeSegment(input) {
+	return input !== "." && input !== ".." && !input.includes(":") && !/[\s/\\]/.test(input);
+}
+function hostLike(input) {
+	return input.includes(".") || input.includes(":") || input === "localhost";
+}
+function withSlash(input) {
+	if (input.endsWith("/")) return input;
+	return `${input}/`;
+}
+function githubRemote(pathname) {
+	const base = process.env.OPENCODE_REPO_CLONE_GITHUB_BASE_URL;
+	if (!base) return `https://github.com/${pathname}.git`;
+	return new URL(`${pathname}.git`, withSlash(base)).href;
+}
+function invalidRepository(repository) {
+	return error({
+		code: "invalid_repository",
+		repository,
+		message: "Repository must be a git URL, host/path reference, or GitHub owner/repo shorthand"
+	});
+}
+function buildRemote(input) {
+	const segments = input.segments.map(trimGitSuffix).filter((segment) => segment.length > 0);
+	if (!safeHost(input.host) || segments.length === 0 || segments.some((segment) => !safeSegment(segment))) {
+		return Result.err(invalidRepository(input.remote ?? input.host));
+	}
+	const repositoryPath = segments.join("/");
+	const host = input.host.toLowerCase();
+	const repo = segments.at(-1);
+	if (!repo) return Result.err(invalidRepository(input.remote ?? input.host));
+	return Result.ok({
+		type: "remote",
+		host,
+		path: repositoryPath,
+		segments,
+		...segments.length === 2 ? { owner: segments[0] } : {},
+		repo,
+		remote: input.remote ?? (host === "github.com" ? githubRemote(repositoryPath) : `https://${host}/${repositoryPath}.git`),
+		label: host === "github.com" && segments.length === 2 ? repositoryPath : `${host}/${repositoryPath}`,
+		...input.protocol ? { protocol: input.protocol } : {}
+	});
+}
+function buildFile(input) {
+	const filePath = path.normalize(fileURLToPath(input.url));
+	const segments = filePath.split(/[\\/]+/).filter((segment) => segment.length > 0);
+	const repo = segments.at(-1);
+	if (!repo) return Result.err(invalidRepository(input.remote));
+	return Result.ok({
+		type: "file",
+		host: "file",
+		path: filePath,
+		segments: segments.map((segment) => segment.replace(/:$/, "")),
+		repo: trimGitSuffix(repo),
+		remote: input.remote,
+		label: filePath,
+		protocol: "file:"
+	});
+}
+function parseRepositoryReference(input) {
+	const cleaned = normalizeInput(input);
+	if (cleaned.length === 0) return Result.err(invalidRepository(input));
+	const githubPrefixed = cleaned.match(/^github:([^/\s]+)\/([^/\s]+)$/);
+	const githubOwner = githubPrefixed?.[1];
+	const githubRepo = githubPrefixed?.[2];
+	if (githubOwner && githubRepo) {
+		return buildRemote({
+			host: "github.com",
+			segments: [githubOwner, githubRepo]
+		});
+	}
+	if (!cleaned.includes("://")) {
+		const scp = cleaned.match(/^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/);
+		const scpHost = scp?.[1];
+		const scpPath = scp?.[2];
+		if (scpHost && scpPath) {
+			return buildRemote({
+				host: scpHost,
+				segments: parts(scpPath),
+				remote: cleaned
+			});
+		}
+		const direct = parts(cleaned);
+		const first = direct[0];
+		if (direct.length >= 2 && first && hostLike(first)) {
+			return buildRemote({
+				host: first,
+				segments: direct.slice(1)
+			});
+		}
+		if (direct.length === 2) return buildRemote({
+			host: "github.com",
+			segments: direct
+		});
+	}
+	const parsed = Result.try({
+		try: () => new URL(cleaned),
+		catch: (cause) => cause
+	});
+	if (Result.isError(parsed)) return Result.err(invalidRepository(input));
+	if (parsed.value.protocol === "file:") return buildFile({
+		url: parsed.value,
+		remote: cleaned
+	});
+	const segments = parts(parsed.value.pathname);
+	return buildRemote({
+		host: parsed.value.host,
+		segments,
+		remote: parsed.value.host === "github.com" ? githubRemote(segments.join("/")) : cleaned,
+		protocol: parsed.value.protocol
+	});
+}
+function parseRemoteRepositoryReference(input) {
+	const reference = parseRepositoryReference(input);
+	if (Result.isError(reference)) return Result.err(reference.error);
+	if (reference.value.type === "remote") return Result.ok(reference.value);
+	return Result.err(error({
+		code: "unsupported_file_repository",
+		repository: input,
+		message: "Local file repositories are not supported through repository; use path instead"
+	}));
+}
+function validateBranch(branch) {
+	if (/^[A-Za-z0-9/_.-]+$/.test(branch) && !branch.startsWith("-") && !branch.includes("..")) {
+		return Result.ok(branch);
+	}
+	return Result.err(error({
+		code: "invalid_branch",
+		branch,
+		message: "Branch must contain only alphanumeric characters, /, _, ., and -, and cannot start with - or contain .."
+	}));
+}
+function repositoryCachePath(root, reference) {
+	return path.join(root, ...reference.host.split(":"), ...reference.segments);
+}
+function repositoryCacheIdentity(reference) {
+	return `${reference.host}/${reference.path}`;
+}
+function sameRepositoryReference(left, right) {
+	return repositoryCacheIdentity(left) === repositoryCacheIdentity(right);
+}
+
+//#endregion
+export { ReferencesError, parseRemoteRepositoryReference, parseRepositoryReference, repositoryCacheIdentity, repositoryCachePath, sameRepositoryReference, validateBranch };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pi-ohm/references",
+  "version": "0.6.4-dev.27705031416.1.1d8069f",
+  "homepage": "https://github.com/pi-ohm/pi-ohm/tree/dev/packages/references#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pi-ohm/pi-ohm.git",
+    "directory": "packages/references"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "SPEC.md"
+  ],
+  "type": "module",
+  "main": "dist/extension.js",
+  "types": "dist/extension.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/extension.d.ts",
+      "default": "./dist/extension.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./repository": {
+      "types": "./dist/repository.d.ts",
+      "default": "./dist/repository.js"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./references": {
+      "types": "./dist/references.d.ts",
+      "default": "./dist/references.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "vp pack src/extension.ts src/config.ts src/repository.ts src/cache.ts src/references.ts"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.79.4",
+    "@earendil-works/pi-tui": "0.79.4",
+    "@pi-ohm/core": "0.6.4-dev.27705031416.1.1d8069f",
+    "better-result": "2.9.2",
+    "typebox": "^1.0.68"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.79.4",
+    "@earendil-works/pi-tui": "0.79.4"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  }
+}