pi-provider-utils 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# pi-provider-utils
+
+Shared provider mirror, stream, and agent-path helpers for Pi extension packages.
+
+## Status
+
+This package extracts duplicated helper code from `pi-credential-vault` and `pi-multicodex` into a single shared dependency. It provides generic provider and agent utilities — not vault-specific or multicodex-specific policy.
+
+Current consumers:
+
+- `@victor-software-house/pi-credential-vault`
+- `@victor-software-house/pi-multicodex`
+
+Current next steps:
+
+1. publish this package to npm
+2. switch consuming repos from `link:` to npm dependency
+3. adopt pnpm workspace and Turborepo once the published package is the common dependency boundary
+
+## Install
+
+This package is a shared library, not a standalone Pi extension. Do not install it with `pi install`.
+
+Consume it from another package instead:
+
+```json
+{
+  "peerDependencies": {
+    "@victor-software-house/pi-provider-utils": "*"
+  },
+  "devDependencies": {
+    "@victor-software-house/pi-provider-utils": "*"
+  }
+}
+```
+
+For local multi-repo development before publication, use a `link:` dev dependency:
+
+```json
+{
+  "devDependencies": {
+    "@victor-software-house/pi-provider-utils": "link:../pi-provider-utils"
+  }
+}
+```
+
+## Entrypoints
+
+### `@victor-software-house/pi-provider-utils/providers`
+
+Provider mirror metadata and model-registry helpers.
+
+```typescript
+import {
+  mirrorProvider,
+  listProviderIdsWithModels,
+  type MirroredProvider,
+  type MirroredModelDef,
+} from "@victor-software-house/pi-provider-utils/providers";
+
+// Mirror an existing provider's configuration for re-registration
+const mirror = mirrorProvider("openai");
+
+// List all provider IDs that have registered models
+const ids = listProviderIdsWithModels();
+```
+
+### `@victor-software-house/pi-provider-utils/streams`
+
+Stream and error primitives for extension-owned provider wrappers.
+
+```typescript
+import {
+  normalizeUnknownError,
+  createErrorAssistantMessage,
+  pushErrorEvent,
+  createImmediateErrorStream,
+  pipeAssistantStream,
+  rewriteProviderOnEvent,
+  createLinkedAbortController,
+  createTimeoutController,
+} from "@victor-software-house/pi-provider-utils/streams";
+
+// Normalize an unknown thrown value into a string
+const msg = normalizeUnknownError(error);
+
+// Create a stream that immediately emits an error
+const stream = createImmediateErrorStream(model, "no credentials");
+
+// Pipe events from one stream to another
+await pipeAssistantStream(source, target);
+
+// Rewrite the provider field on stream events
+const rewritten = rewriteProviderOnEvent(event, "my-provider");
+
+// Create an AbortController linked to a parent signal
+const controller = createLinkedAbortController(parentSignal);
+
+// Create a linked controller that auto-aborts after a timeout
+const { controller: tc, clear } = createTimeoutController(signal, 30_000);
+```
+
+### `@victor-software-house/pi-provider-utils/agent-paths`
+
+Canonical `~/.pi/agent/*` path helpers and JSON file I/O.
+
+```typescript
+import {
+  getAgentPath,
+  getAgentSettingsPath,
+  getAgentAuthPath,
+  readJsonObjectFile,
+  writeJsonObjectFile,
+  ensureParentDir,
+} from "@victor-software-house/pi-provider-utils/agent-paths";
+
+// Resolve a path relative to ~/.pi/agent/
+const vaultPath = getAgentPath("vault.age.json");
+
+// Read and write JSON object files (sync)
+const settings = readJsonObjectFile(getAgentSettingsPath());
+settings["my-extension"] = { enabled: true };
+writeJsonObjectFile(getAgentSettingsPath(), settings);
+
+// Async variants are also available
+import {
+  readJsonObjectFileAsync,
+  writeJsonObjectFileAsync,
+} from "@victor-software-house/pi-provider-utils/agent-paths";
+```
+
+## What this package does NOT contain
+
+- OAuth login or refresh orchestration
+- Quota classification or retry policy
+- Vault backend registry logic
+- Multicodex account selection logic
+- Footer rendering or settings-panel components
+
+These belong in the owning extension packages (`pi-credential-vault`, `pi-multicodex`), not in shared utilities.
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+npm pack --dry-run
+```
+
+Validation status at extraction time:
+
+- 52 tests covering all three entrypoints
+- `pnpm typecheck` passes
+- `npm pack --dry-run` includes only the library contract and tests

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "pi-provider-utils",
+	"version": "0.0.0",
+	"description": "Shared provider mirror, stream, and agent-path helpers for Pi extension packages",
+	"license": "MIT",
+	"type": "module",
+	"packageManager": "pnpm@10.32.1",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-coding-agent",
+		"provider",
+		"stream",
+		"utilities"
+	],
+	"exports": {
+		"./providers": "./src/providers.ts",
+		"./streams": "./src/streams.ts",
+		"./agent-paths": "./src/agent-paths.ts"
+	},
+	"scripts": {
+		"lint": "biome check .",
+		"test": "vitest run",
+		"tsgo": "tsgo -p tsconfig.json",
+		"check": "pnpm lint && pnpm tsgo && pnpm test",
+		"release:dry": "pnpm exec semantic-release --dry-run"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/victor-software-house/pi-provider-utils.git"
+	},
+	"homepage": "https://github.com/victor-software-house/pi-provider-utils#readme",
+	"bugs": {
+		"url": "https://github.com/victor-software-house/pi-provider-utils/issues"
+	},
+	"author": "Victor",
+	"files": [
+		"src/",
+		"README.md",
+		"LICENSE"
+	],
+	"peerDependencies": {
+		"@mariozechner/pi-ai": "*",
+		"@mariozechner/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.7",
+		"@commitlint/cli": "^20.4.4",
+		"@commitlint/config-conventional": "^20.4.4",
+		"@mariozechner/pi-ai": "^0.63.1",
+		"@mariozechner/pi-coding-agent": "^0.63.1",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/commit-analyzer": "^13.0.1",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.6",
+		"@semantic-release/npm": "^13.1.5",
+		"@semantic-release/release-notes-generator": "^14.1.0",
+		"@typescript/native-preview": "7.0.0-dev.20260314.1",
+		"semantic-release": "^25.0.3",
+		"vitest": "^4.1.0"
+	},
+	"engines": {
+		"node": "24.14.0"
+	}
+}

package/src/__tests__/agent-paths.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Tests for agent-path helpers and JSON file I/O.
+ */
+
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock pi-coding-agent before importing the module under test
+vi.mock("@mariozechner/pi-coding-agent", () => ({
+	getAgentDir: () => path.join(os.homedir(), ".pi", "agent"),
+}));
+
+import {
+	ensureParentDir,
+	getAgentAuthPath,
+	getAgentPath,
+	getAgentSettingsPath,
+	readJsonObjectFile,
+	readJsonObjectFileAsync,
+	writeJsonObjectFile,
+	writeJsonObjectFileAsync,
+} from "../agent-paths.js";
+
+// Use a temp directory for file I/O tests
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-provider-utils-"));
+});
+
+afterEach(() => {
+	fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+describe("getAgentPath", () => {
+	it("returns the agent directory when called with no arguments", () => {
+		const result = getAgentPath();
+		expect(result).toBe(path.join(os.homedir(), ".pi", "agent"));
+	});
+
+	it("joins segments onto the agent directory", () => {
+		const result = getAgentPath("settings.json");
+		expect(result).toBe(
+			path.join(os.homedir(), ".pi", "agent", "settings.json"),
+		);
+	});
+
+	it("joins multiple segments", () => {
+		const result = getAgentPath("data", "vault.age.json");
+		expect(result).toBe(
+			path.join(os.homedir(), ".pi", "agent", "data", "vault.age.json"),
+		);
+	});
+});
+
+describe("getAgentSettingsPath", () => {
+	it("returns the settings.json path", () => {
+		expect(getAgentSettingsPath()).toBe(
+			path.join(os.homedir(), ".pi", "agent", "settings.json"),
+		);
+	});
+});
+
+describe("getAgentAuthPath", () => {
+	it("returns the auth.json path", () => {
+		expect(getAgentAuthPath()).toBe(
+			path.join(os.homedir(), ".pi", "agent", "auth.json"),
+		);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// ensureParentDir
+// ---------------------------------------------------------------------------
+
+describe("ensureParentDir", () => {
+	it("creates parent directories that do not exist", () => {
+		const filePath = path.join(tmpDir, "a", "b", "file.json");
+
+		ensureParentDir(filePath);
+
+		expect(fs.existsSync(path.join(tmpDir, "a", "b"))).toBe(true);
+	});
+
+	it("is a no-op when the parent directory already exists", () => {
+		const filePath = path.join(tmpDir, "file.json");
+
+		ensureParentDir(filePath);
+
+		expect(fs.existsSync(tmpDir)).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// readJsonObjectFile (sync)
+// ---------------------------------------------------------------------------
+
+describe("readJsonObjectFile", () => {
+	it("returns empty object for nonexistent file", () => {
+		const result = readJsonObjectFile(path.join(tmpDir, "missing.json"));
+		expect(result).toEqual({});
+	});
+
+	it("reads a valid JSON object file", () => {
+		const filePath = path.join(tmpDir, "test.json");
+		fs.writeFileSync(filePath, JSON.stringify({ key: "value" }));
+
+		const result = readJsonObjectFile(filePath);
+
+		expect(result).toEqual({ key: "value" });
+	});
+
+	it("returns empty object for a JSON array file", () => {
+		const filePath = path.join(tmpDir, "array.json");
+		fs.writeFileSync(filePath, JSON.stringify([1, 2, 3]));
+
+		const result = readJsonObjectFile(filePath);
+
+		expect(result).toEqual({});
+	});
+
+	it("returns empty object for invalid JSON", () => {
+		const filePath = path.join(tmpDir, "bad.json");
+		fs.writeFileSync(filePath, "not json at all");
+
+		const result = readJsonObjectFile(filePath);
+
+		expect(result).toEqual({});
+	});
+
+	it("returns empty object for a JSON null file", () => {
+		const filePath = path.join(tmpDir, "null.json");
+		fs.writeFileSync(filePath, "null");
+
+		const result = readJsonObjectFile(filePath);
+
+		expect(result).toEqual({});
+	});
+
+	it("preserves nested objects", () => {
+		const data = { outer: { inner: 42 }, list: [1, 2] };
+		const filePath = path.join(tmpDir, "nested.json");
+		fs.writeFileSync(filePath, JSON.stringify(data));
+
+		const result = readJsonObjectFile(filePath);
+
+		expect(result).toEqual(data);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// writeJsonObjectFile (sync)
+// ---------------------------------------------------------------------------
+
+describe("writeJsonObjectFile", () => {
+	it("writes a JSON object with 2-space indentation", () => {
+		const filePath = path.join(tmpDir, "out.json");
+
+		writeJsonObjectFile(filePath, { hello: "world" });
+
+		const raw = fs.readFileSync(filePath, "utf-8");
+		expect(raw).toBe(JSON.stringify({ hello: "world" }, null, 2));
+	});
+
+	it("creates parent directories when needed", () => {
+		const filePath = path.join(tmpDir, "deep", "nested", "out.json");
+
+		writeJsonObjectFile(filePath, { created: true });
+
+		expect(fs.existsSync(filePath)).toBe(true);
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<
+			string,
+			unknown
+		>;
+		expect(parsed).toEqual({ created: true });
+	});
+
+	it("overwrites an existing file", () => {
+		const filePath = path.join(tmpDir, "overwrite.json");
+		fs.writeFileSync(filePath, JSON.stringify({ old: true }));
+
+		writeJsonObjectFile(filePath, { new: true });
+
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<
+			string,
+			unknown
+		>;
+		expect(parsed).toEqual({ new: true });
+	});
+});
+
+// ---------------------------------------------------------------------------
+// readJsonObjectFileAsync
+// ---------------------------------------------------------------------------
+
+describe("readJsonObjectFileAsync", () => {
+	it("returns empty object for nonexistent file", async () => {
+		const result = await readJsonObjectFileAsync(
+			path.join(tmpDir, "missing.json"),
+		);
+		expect(result).toEqual({});
+	});
+
+	it("reads a valid JSON object file", async () => {
+		const filePath = path.join(tmpDir, "test.json");
+		await fsp.writeFile(filePath, JSON.stringify({ async: true }));
+
+		const result = await readJsonObjectFileAsync(filePath);
+
+		expect(result).toEqual({ async: true });
+	});
+
+	it("returns empty object for a JSON array file", async () => {
+		const filePath = path.join(tmpDir, "array.json");
+		await fsp.writeFile(filePath, JSON.stringify([1, 2]));
+
+		const result = await readJsonObjectFileAsync(filePath);
+
+		expect(result).toEqual({});
+	});
+});
+
+// ---------------------------------------------------------------------------
+// writeJsonObjectFileAsync
+// ---------------------------------------------------------------------------
+
+describe("writeJsonObjectFileAsync", () => {
+	it("writes a JSON object with 2-space indentation", async () => {
+		const filePath = path.join(tmpDir, "async-out.json");
+
+		await writeJsonObjectFileAsync(filePath, { async: "write" });
+
+		const raw = await fsp.readFile(filePath, "utf-8");
+		expect(raw).toBe(JSON.stringify({ async: "write" }, null, 2));
+	});
+
+	it("creates parent directories when needed", async () => {
+		const filePath = path.join(tmpDir, "deep", "async", "out.json");
+
+		await writeJsonObjectFileAsync(filePath, { deep: true });
+
+		const exists = await fsp
+			.stat(filePath)
+			.then(() => true)
+			.catch(() => false);
+		expect(exists).toBe(true);
+	});
+});

package/src/__tests__/providers.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for provider mirror metadata and model-registry helpers.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock pi-ai before importing the module under test
+vi.mock("@mariozechner/pi-ai", () => ({
+	getModels: vi.fn(),
+	getProviders: vi.fn(),
+	getApiProvider: vi.fn(),
+}));
+
+import { getApiProvider, getModels, getProviders } from "@mariozechner/pi-ai";
+import type { MirroredProvider } from "../providers.js";
+import { listProviderIdsWithModels, mirrorProvider } from "../providers.js";
+
+// Cast to vi.Mock for mock API access without strict generics
+const mockGetModels = getModels as unknown as ReturnType<typeof vi.fn>;
+const mockGetProviders = getProviders as unknown as ReturnType<typeof vi.fn>;
+const mockGetApiProvider = getApiProvider as unknown as ReturnType<
+	typeof vi.fn
+>;
+
+function createMockModel(overrides: Record<string, unknown> = {}) {
+	return {
+		id: "gpt-4o",
+		name: "GPT-4o",
+		reasoning: false,
+		input: ["text", "image"],
+		cost: { input: 5, output: 15, cacheRead: 2.5, cacheWrite: 5 },
+		contextWindow: 128_000,
+		maxTokens: 16_384,
+		api: "openai",
+		provider: "openai",
+		baseUrl: "https://api.openai.com/v1",
+		...overrides,
+	};
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe("mirrorProvider", () => {
+	it("returns undefined when the provider has no models", () => {
+		mockGetModels.mockReturnValue([]);
+
+		const result = mirrorProvider("openai");
+		expect(result).toBeUndefined();
+	});
+
+	it("mirrors a provider with a single model", () => {
+		const model = createMockModel();
+		mockGetModels.mockReturnValue([model]);
+		mockGetApiProvider.mockReturnValue({
+			api: "openai",
+			stream: vi.fn(),
+			streamSimple: vi.fn(),
+		});
+
+		const result = mirrorProvider("openai");
+
+		expect(result).toBeDefined();
+		const mirror = result as MirroredProvider;
+		expect(mirror.providerId).toBe("openai");
+		expect(mirror.baseUrl).toBe("https://api.openai.com/v1");
+		expect(mirror.api).toBe("openai");
+		expect(mirror.hasStreamSimple).toBe(true);
+		expect(mirror.models).toHaveLength(1);
+		expect(mirror.models[0]?.id).toBe("gpt-4o");
+	});
+
+	it("mirrors a provider with multiple models", () => {
+		const models = [
+			createMockModel({ id: "gpt-4o", name: "GPT-4o" }),
+			createMockModel({
+				id: "gpt-4o-mini",
+				name: "GPT-4o Mini",
+				maxTokens: 8_192,
+			}),
+		];
+		mockGetModels.mockReturnValue(models);
+		mockGetApiProvider.mockReturnValue({
+			api: "openai",
+			stream: vi.fn(),
+			streamSimple: vi.fn(),
+		});
+
+		const result = mirrorProvider("openai");
+
+		expect(result).toBeDefined();
+		const mirror = result as MirroredProvider;
+		expect(mirror.models).toHaveLength(2);
+		expect(mirror.models[0]?.id).toBe("gpt-4o");
+		expect(mirror.models[1]?.id).toBe("gpt-4o-mini");
+	});
+
+	it("reports hasStreamSimple false when no API provider found", () => {
+		mockGetModels.mockReturnValue([createMockModel()]);
+		mockGetApiProvider.mockReturnValue(undefined);
+
+		const result = mirrorProvider("openai");
+
+		expect(result).toBeDefined();
+		const mirror = result as MirroredProvider;
+		expect(mirror.hasStreamSimple).toBe(false);
+	});
+
+	it("uses empty string for baseUrl when model has none", () => {
+		const model = createMockModel({ baseUrl: undefined });
+		mockGetModels.mockReturnValue([model]);
+		mockGetApiProvider.mockReturnValue({
+			api: "openai",
+			stream: vi.fn(),
+			streamSimple: vi.fn(),
+		});
+
+		const result = mirrorProvider("openai");
+
+		expect(result).toBeDefined();
+		const mirror = result as MirroredProvider;
+		expect(mirror.baseUrl).toBe("");
+	});
+
+	it("preserves model cost and dimension fields", () => {
+		const model = createMockModel({
+			cost: { input: 10, output: 30, cacheRead: 5, cacheWrite: 10 },
+			contextWindow: 200_000,
+			maxTokens: 32_768,
+			reasoning: true,
+		});
+		mockGetModels.mockReturnValue([model]);
+		mockGetApiProvider.mockReturnValue({
+			api: "openai",
+			stream: vi.fn(),
+			streamSimple: vi.fn(),
+		});
+
+		const result = mirrorProvider("openai");
+
+		expect(result).toBeDefined();
+		const mirror = result as MirroredProvider;
+		const mirrored = mirror.models[0];
+		expect(mirrored).toBeDefined();
+		expect(mirrored?.cost).toEqual({
+			input: 10,
+			output: 30,
+			cacheRead: 5,
+			cacheWrite: 10,
+		});
+		expect(mirrored?.contextWindow).toBe(200_000);
+		expect(mirrored?.maxTokens).toBe(32_768);
+		expect(mirrored?.reasoning).toBe(true);
+	});
+});
+
+describe("listProviderIdsWithModels", () => {
+	it("returns only providers that have registered models", () => {
+		mockGetProviders.mockReturnValue(["openai", "anthropic", "groq"]);
+		mockGetModels.mockImplementation((id: string) => {
+			if (id === "openai") return [createMockModel()];
+			if (id === "anthropic") return [createMockModel({ api: "anthropic" })];
+			return [];
+		});
+
+		const ids = listProviderIdsWithModels();
+
+		expect(ids).toEqual(["openai", "anthropic"]);
+	});
+
+	it("returns empty array when no providers have models", () => {
+		mockGetProviders.mockReturnValue(["openai", "anthropic"]);
+		mockGetModels.mockReturnValue([]);
+
+		const ids = listProviderIdsWithModels();
+
+		expect(ids).toEqual([]);
+	});
+
+	it("returns empty array when no providers exist", () => {
+		mockGetProviders.mockReturnValue([]);
+
+		const ids = listProviderIdsWithModels();
+
+		expect(ids).toEqual([]);
+	});
+});