pi-model-profiles 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+No unreleased changes.
+
+## [0.2.0] - 2026-04-26
+
+### Added
+- Phase 6: Git & publishing preparation.
+- NPM package metadata, README, CHANGELOG, LICENSE, and package ignore rules.
+- Profile update, removal, persisted sorting, configuration, and file-gated debug logging.
+
+### Fixed
+- Confirmation prompts now accept typed input before update or removal actions run.
+- Sort menu keyboard handling now works regardless of focused pane and closes without exiting the modal.
+- Profile update and removal command handlers now avoid duplicate scans and duplicate removal events.
+
+## [0.1.0] - 2026-04-25
+
+### Added
+- Initial extension structure
+- Core profile management functionality
+- Frontmatter parser implementation
+- Profile store with atomic writes
+- Import service for external profiles
+- Agent writer for profile application
+- Type definitions and error handling
+- Test suite for core functionality

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+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,162 @@
+# pi-model-profiles
+
+[![npm version](https://img.shields.io/npm/v/pi-model-profiles?style=flat-square)](https://www.npmjs.com/package/pi-model-profiles) [![License](https://img.shields.io/github/license/MasuRii/pi-model-profiles?style=flat-square)](LICENSE)
+
+<img width="1389" height="768" alt="image" src="https://github.com/user-attachments/assets/7170fed2-018f-4719-a147-3bd7967456bc" />
+
+`pi-model-profiles` is a Pi extension for saving, updating, deleting, sorting, and applying whole-agent model frontmatter snapshots.
+
+- **Command:** `/model-profiles`
+- **npm:** https://www.npmjs.com/package/pi-model-profiles
+- **GitHub:** https://github.com/MasuRii/pi-model-profiles
+
+## Features
+
+- Save the current user/project agent model frontmatter as a reusable snapshot.
+- Apply a saved snapshot across matching agent markdown files with atomic writes.
+- Rename, update, remove, and sort saved snapshots from the interactive modal.
+- Preserve profile data in `profiles.json` with schema-versioned migration support.
+- Write optional debug logs only to the extension-local `debug/` directory when enabled.
+
+## Installation
+
+### npm package
+
+```bash
+pi install npm:pi-model-profiles
+```
+
+### Git repository
+
+```bash
+pi install git:github.com/MasuRii/pi-model-profiles
+```
+
+### Local extension folder
+
+Place this folder in one of Pi's extension discovery paths:
+
+| Scope | Path |
+|-------|------|
+| Global default | `~/.pi/agent/extensions/pi-model-profiles` (respects `PI_CODING_AGENT_DIR`) |
+| Project | `.pi/extensions/pi-model-profiles` |
+
+Pi discovers the extension through the root `index.ts` entry listed in `package.json`.
+
+## Usage
+
+Run the command in interactive TUI mode:
+
+```text
+/model-profiles
+```
+
+Modal shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| `↑` / `↓` | Move through snapshots |
+| `Tab` / `→` | Switch between snapshots and details panes |
+| `Enter` | Apply selected snapshot |
+| `s` | Save current agent state as a new snapshot |
+| `r` | Rename selected snapshot |
+| `Ctrl+U` | Update selected snapshot from current agent state |
+| `Delete` / `Ctrl+D` | Remove selected snapshot after confirmation |
+| `Ctrl+S` | Open sort menu |
+| `Esc` | Close modal, cancel input, or close sort menu |
+
+## Configuration
+
+Runtime configuration lives in `config.json` at the extension root. The extension creates the file automatically with defaults on first load if it does not already exist.
+
+A starter template is included at `config/config.example.json`. Copy it to `config.json` for local customization, or let the extension create `config.json` with defaults on first load.
+
+```json
+{
+  "debug": false,
+  "profiles": {
+    "autoSave": true,
+    "maxProfiles": 100
+  },
+  "sorting": {
+    "defaultSort": "date-desc"
+  }
+}
+```
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `debug` | `boolean` | `false` | Enables debug logging under `debug/` directory |
+| `profiles.autoSave` | `boolean` | `true` | Reserved profile persistence setting |
+| `profiles.maxProfiles` | `number` | `100` | Reserved maximum profile retention setting |
+| `sorting.defaultSort` | `name-asc \| name-desc \| date-asc \| date-desc` | `date-desc` | Default snapshot sort order |
+
+## Profile Storage
+
+Profile data is persisted in `profiles.json` at the extension root and should not be edited while Pi is running.
+
+```json
+{
+  "version": 2,
+  "importedAt": "2026-04-26T00:00:00.000Z",
+  "profiles": [
+    {
+      "id": "profile-id",
+      "name": "Current agents snapshot",
+      "createdAt": "2026-04-26T00:00:00.000Z",
+      "updatedAt": "2026-04-26T00:00:00.000Z",
+      "agents": [
+        {
+          "fileName": "code.md",
+          "agentName": "code",
+          "fields": {
+            "model": "provider/model",
+            "temperature": 0.2,
+            "reasoningEffort": "medium"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Debug Logging
+
+Debug logging is controlled by the `debug` property in `config.json`.
+
+- When `debug` is `false` or absent, no debug file handles are opened and no debug files are written.
+- When `debug` is `true`, debug events are appended to `debug/pi-model-profiles-debug.jsonl`.
+- Debug output is never written to console, stdout, or stderr.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run lint
+npm run test
+npm run check
+npm run package:dry-run
+```
+
+## Publishing
+
+The package metadata follows the same publish-ready shape used by established Pi extensions:
+
+- entrypoint: `index.ts`
+- package exports: `.` → `./index.ts`
+- Pi extension manifest: `pi.extensions`
+- published files: source, README, changelog, license, and config template
+- runtime `config.json`, `profiles.json`, and `debug/` logs excluded from npm publication
+
+## Related Pi Extensions
+
+- [pi-context-injector](https://github.com/MasuRii/pi-context-injector) — Inject compact project context into first-turn and compaction prompts
+- [pi-agent-router](https://github.com/MasuRii/pi-agent-router) — Active-agent routing and controlled subagent delegation
+- [pi-multi-auth](https://github.com/MasuRii/pi-multi-auth) — Multi-provider credential management, OAuth login, and account rotation
+- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
+
+## License
+
+[MIT](LICENSE)

package/config/config.example.json

@@ -0,0 +1,10 @@
+{
+  "debug": false,
+  "profiles": {
+    "autoSave": true,
+    "maxProfiles": 100
+  },
+  "sorting": {
+    "defaultSort": "date-desc"
+  }
+}

package/index.ts

@@ -0,0 +1,3 @@
+import modelProfilesExtension from "./src/index.js";
+
+export default modelProfilesExtension;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-model-profiles",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Pi extension for saving, importing, and applying agent model frontmatter profiles.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "config/config.example.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.9.2 tsc -p tsconfig.json",
+    "lint": "npm run build",
+    "test:clean": "node -e \"require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
+    "prepublishOnly": "npm run test",
+    "pretest": "npm run test:clean",
+    "test": "npx --yes -p typescript@5.9.2 tsc --strict --skipLibCheck --module nodenext --moduleResolution nodenext --target ES2022 --outDir .test-dist src/types-shims.d.ts src/errors.ts src/types.ts src/constants.ts src/atomic-write.ts src/profile-fields.ts src/frontmatter-parser.ts src/profile-store.ts src/agent-writer.ts src/import-service.ts test/frontmatter-parser.test.ts test/import-service.test.ts test/agent-writer.test.ts test/profile-store.test.ts && node --test .test-dist/test/frontmatter-parser.test.js .test-dist/test/import-service.test.js .test-dist/test/agent-writer.test.js .test-dist/test/profile-store.test.js",
+    "posttest": "npm run test:clean",
+    "check": "npm run build && npm run test",
+    "package:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "model-profiles",
+    "frontmatter",
+    "agent-configuration",
+    "profiles"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "homepage": "https://github.com/MasuRii/pi-model-profiles#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-model-profiles.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-model-profiles/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.5",
+    "@mariozechner/pi-tui": "^0.70.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent-writer.ts

@@ -0,0 +1,331 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { AGENTS_DIR } from "./constants.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { ModelProfilesError } from "./errors.js";
+import {
+	listAppliedKeys,
+	listRemovedKeys,
+	readAgentNameFromMarkdown,
+	readProfileFieldsFromMarkdown,
+	updateMarkdownProfileFields,
+} from "./frontmatter-parser.js";
+import { normalizeProfileFields } from "./profile-fields.js";
+import type {
+	AgentFileRecord,
+	AgentScanResult,
+	AgentSnapshotResult,
+	AppliedAgentUpdate,
+	ApplyProfileResult,
+	ProfileFields,
+	SavedProfile,
+	SavedProfileAgent,
+} from "./types.js";
+
+interface SessionEntryLike {
+	type?: unknown;
+	customType?: unknown;
+	data?: unknown;
+}
+
+interface SessionManagerLike {
+	getEntries(): readonly unknown[];
+}
+
+type AgentScope = "user" | "project" | "both";
+
+export interface AgentSelectionOptions {
+	cwd?: string;
+	agentsDir?: string;
+	scope?: AgentScope;
+}
+
+const PROJECT_AGENT_SOURCE_DIRS = [
+	[".omp", "agents"],
+	[".pi", "agents"],
+	[".claude", "agents"],
+] as const;
+
+function toRecord(value: unknown): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return {};
+	}
+	return value as Record<string, unknown>;
+}
+
+function normalizeName(value: unknown): string | null {
+	if (typeof value !== "string") {
+		return null;
+	}
+	const trimmed = value.trim();
+	return trimmed ? trimmed : null;
+}
+
+function normalizeCompareValue(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+function parseActiveAgentFromPrompt(systemPrompt: string): string | null {
+	const identityMatch = /<active_agent_identity\s+name=["']([^"']+)["']/i.exec(systemPrompt);
+	if (identityMatch?.[1]) {
+		return identityMatch[1].trim() || null;
+	}
+
+	const summaryMatch = /The selected active agent identity is "([^"]+)"\./i.exec(systemPrompt);
+	if (summaryMatch?.[1]) {
+		return summaryMatch[1].trim() || null;
+	}
+
+	return null;
+}
+
+function cloneSavedAgent(agent: SavedProfileAgent): SavedProfileAgent {
+	return {
+		fileName: agent.fileName,
+		agentName: agent.agentName,
+		fields: normalizeProfileFields(agent.fields),
+	};
+}
+
+function normalizeSavedAgents(agents: readonly SavedProfileAgent[]): SavedProfileAgent[] {
+	return [...agents]
+		.map((agent) => cloneSavedAgent(agent))
+		.sort((left, right) => left.fileName.localeCompare(right.fileName) || left.agentName.localeCompare(right.agentName));
+}
+
+export function detectActiveAgentName(sessionManager: SessionManagerLike, systemPrompt = ""): string | null {
+	const entries = sessionManager.getEntries();
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index] as SessionEntryLike | undefined;
+		if (entry?.type !== "custom" || entry.customType !== "active_agent") {
+			continue;
+		}
+
+		const data = toRecord(entry.data);
+		if (data.name === null) {
+			return null;
+		}
+
+		const name = normalizeName(data.name);
+		if (name) {
+			return name;
+		}
+
+		return null;
+	}
+
+	return parseActiveAgentFromPrompt(systemPrompt);
+}
+
+function normalizeCompareKey(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return existsSync(path) && readdirSync(path, { withFileTypes: true }).length >= 0;
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentDirs(cwd: string): string[] {
+	let currentDir = resolve(cwd);
+
+	while (true) {
+		const candidates = PROJECT_AGENT_SOURCE_DIRS.map((segments) => join(currentDir, ...segments)).filter((candidate) =>
+			isDirectory(candidate),
+		);
+		if (candidates.length > 0) {
+			return candidates;
+		}
+
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) {
+			return [];
+		}
+		currentDir = parentDir;
+	}
+}
+
+function resolveAgentSourceDirs(options: string | AgentSelectionOptions = AGENTS_DIR): string[] {
+	if (typeof options === "string") {
+		return [options];
+	}
+
+	const scope = options.scope ?? "user";
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const projectDirs = scope === "user" ? [] : findNearestProjectAgentDirs(cwd);
+	const userAgentsDir = options.agentsDir ?? AGENTS_DIR;
+	const userDirs = scope === "project" ? [] : [userAgentsDir].filter((candidate) => isDirectory(candidate));
+	return [...userDirs.slice().reverse(), ...projectDirs.slice().reverse()];
+}
+
+export function readAgentFileRecord(filePath: string): AgentFileRecord {
+	if (!existsSync(filePath)) {
+		throw new ModelProfilesError(`Agent file '${filePath}' was not found.`, "AGENT_NOT_FOUND");
+	}
+
+	const markdown = readFileSync(filePath, "utf-8");
+	return {
+		path: filePath,
+		fileName: basename(filePath),
+		agentName: readAgentNameFromMarkdown(markdown),
+		fields: readProfileFieldsFromMarkdown(markdown),
+	};
+}
+
+export function scanAgentFiles(options: string | AgentSelectionOptions = AGENTS_DIR): AgentScanResult {
+	const sourceDirs = resolveAgentSourceDirs(options);
+	if (sourceDirs.length === 0) {
+		const targetDescription = typeof options === "string" ? options : options.agentsDir ?? options.cwd ?? AGENTS_DIR;
+		throw new ModelProfilesError(`Unable to read agents directory '${targetDescription}'.`, "AGENTS_DIR_UNAVAILABLE");
+	}
+
+	const warnings: string[] = [];
+	const agentsByName = new Map<string, AgentFileRecord>();
+
+	for (const agentsDir of sourceDirs) {
+		let entries: Array<{ name: string; isFile(): boolean }>;
+		try {
+			entries = readdirSync(agentsDir, { withFileTypes: true }) as Array<{ name: string; isFile(): boolean }>;
+		} catch {
+			throw new ModelProfilesError(`Unable to read agents directory '${agentsDir}'.`, "AGENTS_DIR_UNAVAILABLE");
+		}
+
+		for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+			if (!entry.isFile() || !entry.name.endsWith(".md")) {
+				continue;
+			}
+
+			const filePath = join(agentsDir, entry.name);
+			try {
+				const record = readAgentFileRecord(filePath);
+				agentsByName.set(normalizeCompareKey(record.agentName), record);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				warnings.push(`Skipped agent file '${filePath}': ${message}`);
+			}
+		}
+	}
+
+	return {
+		agents: [...agentsByName.values()].sort(
+			(left, right) => left.fileName.localeCompare(right.fileName) || left.agentName.localeCompare(right.agentName),
+		),
+		warnings,
+	};
+}
+
+export function findAgentRecordByName(agentName: string, options: string | AgentSelectionOptions = AGENTS_DIR): AgentFileRecord | null {
+	const target = normalizeCompareValue(agentName);
+	const scan = scanAgentFiles(options);
+	return scan.agents.find((agent) => normalizeCompareValue(agent.agentName) === target) ?? null;
+}
+
+export function captureAgentSnapshots(options: string | AgentSelectionOptions = AGENTS_DIR): AgentSnapshotResult {
+	const scan = scanAgentFiles(options);
+	if (scan.agents.length === 0) {
+		const targetDescription = typeof options === "string" ? options : options.agentsDir ?? options.cwd ?? AGENTS_DIR;
+		throw new ModelProfilesError(`No readable agent markdown files were found in '${targetDescription}'.`, "NO_AGENT_FILES");
+	}
+
+	return {
+		agents: normalizeSavedAgents(
+			scan.agents.map((agent) => ({
+				fileName: agent.fileName,
+				agentName: agent.agentName,
+				fields: agent.fields,
+			})),
+		),
+		warnings: scan.warnings,
+	};
+}
+
+export function applyProfileToAgentRecord(agent: AgentFileRecord, fields: ProfileFields): AppliedAgentUpdate {
+	const normalizedFields = normalizeProfileFields(fields);
+	const markdown = readFileSync(agent.path, "utf-8");
+	const updatedMarkdown = updateMarkdownProfileFields(markdown, normalizedFields);
+	writeFileAtomic(agent.path, updatedMarkdown);
+	return {
+		updatedPath: agent.path,
+		fileName: agent.fileName,
+		agentName: agent.agentName,
+		appliedKeys: listAppliedKeys(normalizedFields),
+		removedKeys: listRemovedKeys(normalizedFields),
+	};
+}
+
+export function applySavedProfile(profile: SavedProfile, options: string | AgentSelectionOptions = AGENTS_DIR): ApplyProfileResult {
+	if (profile.agents.length === 0) {
+		throw new ModelProfilesError(`Saved profile '${profile.name}' does not contain any agent snapshots.`, "EMPTY_PROFILE");
+	}
+
+	const warnings: string[] = [];
+	const missingAgents: string[] = [];
+	const pendingWrites: Array<{ target: AgentFileRecord; updatedMarkdown: string; fields: ProfileFields }> = [];
+	const seenFiles = new Set<string>();
+	const scan = scanAgentFiles(options);
+	const targetByFileName = new Map(scan.agents.map((agent) => [normalizeCompareKey(agent.fileName), agent] as const));
+	const targetByAgentName = new Map(scan.agents.map((agent) => [normalizeCompareKey(agent.agentName), agent] as const));
+	const targetDescription = typeof options === "string" ? options : options.agentsDir ?? options.cwd ?? AGENTS_DIR;
+
+	for (const savedAgent of normalizeSavedAgents(profile.agents)) {
+		const sourceKey = savedAgent.fileName.toLowerCase();
+		if (seenFiles.has(sourceKey)) {
+			throw new ModelProfilesError(
+				`Saved profile '${profile.name}' contains duplicate agent entry '${savedAgent.fileName}'.`,
+				"DUPLICATE_PROFILE_AGENT",
+			);
+		}
+		seenFiles.add(sourceKey);
+
+		const target =
+			targetByFileName.get(normalizeCompareKey(savedAgent.fileName)) ??
+			targetByAgentName.get(normalizeCompareKey(savedAgent.agentName));
+		if (!target) {
+			missingAgents.push(savedAgent.fileName);
+			warnings.push(`Skipped missing agent file '${savedAgent.fileName}' while resolving '${targetDescription}'.`);
+			continue;
+		}
+
+		const markdown = readFileSync(target.path, "utf-8");
+		const normalizedFields = normalizeProfileFields(savedAgent.fields);
+		const updatedMarkdown = updateMarkdownProfileFields(markdown, normalizedFields);
+		const currentAgentName = readAgentNameFromMarkdown(markdown);
+		pendingWrites.push({
+			target: {
+				path: target.path,
+				fileName: target.fileName,
+				agentName: currentAgentName,
+				fields: normalizedFields,
+			},
+			updatedMarkdown,
+			fields: normalizedFields,
+		});
+	}
+
+	if (pendingWrites.length === 0) {
+		throw new ModelProfilesError(
+			`Saved profile '${profile.name}' does not match any existing agent markdown files in '${targetDescription}'.`,
+			"NO_MATCHING_AGENT_FILES",
+		);
+	}
+
+	for (const pending of pendingWrites) {
+		writeFileAtomic(pending.target.path, pending.updatedMarkdown);
+	}
+
+	return {
+		appliedAgents: pendingWrites.map((pending) => ({
+			updatedPath: pending.target.path,
+			fileName: pending.target.fileName,
+			agentName: pending.target.agentName,
+			appliedKeys: listAppliedKeys(pending.fields),
+			removedKeys: listRemovedKeys(pending.fields),
+		})),
+		missingAgents,
+		warnings,
+	};
+}

package/src/atomic-write.ts

@@ -0,0 +1,28 @@
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+function buildTempPath(targetPath: string): string {
+	const nonce = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+	return join(dirname(targetPath), `.${basename(targetPath)}.${nonce}.tmp`);
+}
+
+export function writeFileAtomic(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+
+	const tempPath = buildTempPath(path);
+	let renamed = false;
+
+	try {
+		writeFileSync(tempPath, content, "utf-8");
+		renameSync(tempPath, path);
+		renamed = true;
+	} finally {
+		if (!renamed) {
+			try {
+				unlinkSync(tempPath);
+			} catch {
+				// Ignore temp cleanup failures after a write error.
+			}
+		}
+	}
+}