@timurci/pi-profiles 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Timur Çakmakoğlu
+
+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,116 @@
+# pi-profiles
+
+Reusable pi configuration profiles — list, load, and capture from any project.
+
+This package lets you save and reuse your `.pi/` setup (extensions, skills, settings, prompts) as a named profile and switch between profiles per-project via slash commands.
+
+## Install
+
+**From npm** (recommended):
+
+```bash
+pi install npm:@timurci/pi-profiles
+```
+
+**From GitHub**:
+
+```bash
+pi install git:github.com/timurci/pi-profiles
+```
+
+Pin a specific version:
+
+```bash
+pi install npm:@timurci/pi-profiles@0.1.0
+pi install git:github.com/timurci/pi-profiles@v0.1.0
+```
+
+## Usage
+
+Three slash commands are registered when the extension is loaded:
+
+| Command | Description |
+| --- | --- |
+| `/profiles` | List all available profiles |
+| `/profile <name>` | Load a profile (prompts to choose if name omitted) |
+| `/profile-from-project` | Capture the current `./.pi` as a new profile |
+
+### `/profile <name>`
+
+Creates a symlink at `./.pi` pointing to `~/.pi/profiles/<name>`, then
+triggers a `/reload` so the profile's extensions, skills, etc. take
+effect immediately.
+
+If `./.pi` already exists:
+
+- **Symlink to another profile** — asked to confirm before replacement
+- **Real file or directory** — asked to confirm before being removed and replaced
+- **Already pointing to the requested profile** — no-op
+
+Tab completion is available for the profile argument.
+
+### `/profile-from-project`
+
+Copies `./.pi` into `~/.pi/profiles/<new-id>/`. If a profile with the
+same id already exists, you'll be warned and asked to confirm the
+overwrite.
+
+If `./.pi` has a `PROFILE.md`, its `name` and `description` are reused
+and no prompts are shown.
+
+If `./.pi` does **not** have a `PROFILE.md`, the command prompts for:
+
+1. **Name** — empty input falls back to the cwd basename.
+2. **Description** — required; the prompt re-asks if you submit an empty value.
+
+A `PROFILE.md` is then generated in the new profile directory using
+the values you provided.
+
+## Config
+
+Optional: `~/.pi/agent/extensions/profiles.json`
+
+```json
+{
+  "profilesDir": "/custom/path/to/profiles"
+}
+```
+
+If `profilesDir` is omitted, defaults to `~/.pi/profiles`. Run
+`/reload` after editing.
+
+## Profile format
+
+Each profile is a directory under `profilesDir` containing a `PROFILE.md`
+file with YAML frontmatter (same convention as `SKILL.md`):
+
+```
+~/.pi/profiles/
+└── python-dev/
+    ├── PROFILE.md
+    ├── skills/
+    │   └── ...
+    └── extensions/
+        └── ...
+```
+
+`PROFILE.md`:
+
+```markdown
+---
+name: python-dev
+description: Python development environment with ML/data tooling.
+---
+
+# Python Profile
+
+Add profile documentation here.
+```
+
+Only `name` and `description` are read by this extension. The rest of
+the file is freeform.
+
+## Security
+
+This extension runs with your full user permissions, creates symlinks in your current working directory, and copies files from `./.pi` to your home directory. The [pi security model](https://github.com/earendil-works/pi-mono/blob/main/docs/security.md) is explicit that extensions and third-party packages are full-trust — do not install profiles from sources you have not reviewed.
+

package/extensions/profiles.ts

@@ -0,0 +1,412 @@
+/**
+ * Profiles extension for pi.
+ *
+ * Manages reusable "profiles" - bundles of pi configuration (extensions,
+ * skills, settings, prompts) stored under `~/.pi/profiles/<name>/`.
+ *
+ * Each profile is a directory containing a `PROFILE.md` file with YAML
+ * frontmatter (same convention as `SKILL.md`):
+ *
+ *     ---
+ *     name: my-profile
+ *     description: What this profile does and when to use it.
+ *     ---
+ *
+ * Loading a profile creates a symlink from the project's `./.pi` to the
+ * profile directory, then reloads pi so the new resources take effect
+ * immediately (no need to run `/reload` manually).
+ *
+ * Commands:
+ *   /profiles              - list all available profiles
+ *   /profile [name]        - load a profile (prompts to choose if name omitted)
+ *   /profile-from-project  - capture ./pi as a new profile in the profiles dir
+ *
+ * Config:
+ *   ~/.pi/agent/extensions/profiles.json
+ *
+ *   Example:
+ *   ```json
+ *   {
+ *     "profilesDir": "/custom/path/to/profiles"
+ *   }
+ *   ```
+ *
+ *   If `profilesDir` is omitted, defaults to `~/.pi/profiles`.
+ */
+
+import { homedir } from "node:os";
+import {
+	cpSync,
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	readlinkSync,
+	rmSync,
+	symlinkSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import {
+	getAgentDir,
+	parseFrontmatter,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+const PROFILE_FILE = "PROFILE.md";
+const CONFIG_DIR_NAME = ".pi";
+const YES = "Yes";
+const NO = "No";
+
+interface ProfilesConfig {
+	/** Override the default profiles directory (~/.pi/profiles). */
+	profilesDir?: string;
+}
+
+interface Profile {
+	/** Directory name; used as the lookup key. */
+	id: string;
+	/** Display name from frontmatter `name`, or `id` as fallback. */
+	name: string;
+	/** Description from frontmatter `description`, possibly empty. */
+	description: string;
+	/** Absolute path to the profile directory. */
+	dir: string;
+}
+
+function lstatSafe(path: string) {
+	return lstatSync(path, { throwIfNoEntry: false });
+}
+
+function loadConfig(): ProfilesConfig {
+	const configPath = join(getAgentDir(), "extensions", "profiles.json");
+	if (!existsSync(configPath)) return {};
+	try {
+		return JSON.parse(readFileSync(configPath, "utf-8")) as ProfilesConfig;
+	} catch (err) {
+		console.error(`profiles extension: failed to parse ${configPath}:`, err);
+		return {};
+	}
+}
+
+function listProfiles(profilesDir: string): Profile[] {
+	if (!lstatSafe(profilesDir)) return [];
+
+	const profiles: Profile[] = [];
+	for (const entry of readdirSync(profilesDir, { withFileTypes: true })) {
+		if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+
+		const dir = join(profilesDir, entry.name);
+		const file = join(dir, PROFILE_FILE);
+		if (!lstatSafe(file)) continue;
+
+		let name = entry.name;
+		let description = "";
+
+		try {
+			const content = readFileSync(file, "utf8");
+			const { frontmatter } = parseFrontmatter<{ name?: string; description?: string }>(content);
+			if (typeof frontmatter.name === "string" && frontmatter.name.trim()) {
+				name = frontmatter.name.trim();
+			}
+			if (typeof frontmatter.description === "string") {
+				description = frontmatter.description.trim();
+			}
+		} catch {
+			// Invalid/missing frontmatter is not fatal; fall back to defaults.
+		}
+
+		profiles.push({ id: entry.name, name, description, dir });
+	}
+
+	profiles.sort((a, b) => a.name.localeCompare(b.name));
+	return profiles;
+}
+
+function findProfile(query: string, profilesDir: string): Profile | undefined {
+	const q = query.trim();
+	const profiles = listProfiles(profilesDir);
+	return (
+		profiles.find((p) => p.id === q) ??
+		profiles.find((p) => p.name === q) ??
+		profiles.find((p) => p.name.toLowerCase() === q.toLowerCase())
+	);
+}
+
+function formatLine(p: Profile): string {
+	return p.description ? `${p.name} — ${p.description}` : p.name;
+}
+
+function slugify(input: string): string {
+	return input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+async function doCreateFromProject(
+	profilesDir: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const sourceDir = join(ctx.cwd, CONFIG_DIR_NAME);
+	const sourceStat = lstatSafe(sourceDir);
+
+	if (!sourceStat) {
+		ctx.ui.notify(
+			`No ./${CONFIG_DIR_NAME} directory in this project. Nothing to capture.`,
+			"error",
+		);
+		return;
+	}
+	if (sourceStat.isSymbolicLink()) {
+		ctx.ui.notify(
+			`./${CONFIG_DIR_NAME} is a symlink (likely pointing to an existing profile).\n` +
+				`Remove the symlink first to capture a standalone profile.`,
+			"error",
+		);
+		return;
+	}
+	if (!sourceStat.isDirectory()) {
+		ctx.ui.notify(`./${CONFIG_DIR_NAME} is not a directory.`, "error");
+		return;
+	}
+
+	const sourceProfileFile = join(sourceDir, PROFILE_FILE);
+	const cwdName = basename(ctx.cwd);
+	let name: string;
+	let description: string;
+	let needWriteProfile = false;
+
+	if (lstatSafe(sourceProfileFile)) {
+		// Reuse the existing PROFILE.md from the project.
+		try {
+			const content = readFileSync(sourceProfileFile, "utf8");
+			const { frontmatter } = parseFrontmatter<{ name?: string; description?: string }>(content);
+			name =
+				typeof frontmatter.name === "string" && frontmatter.name.trim()
+					? frontmatter.name.trim()
+					: cwdName;
+			description =
+				typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
+		} catch {
+			name = cwdName;
+			description = "";
+		}
+	} else {
+		// No PROFILE.md in the project; prompt the user.
+		const nameInput = await ctx.ui.input(
+			`Profile name (default: ${slugify(cwdName) || "<name>"})`,
+			cwdName,
+		);
+		if (nameInput === undefined) {
+			ctx.ui.notify("Cancelled.", "info");
+			return;
+		}
+		// Empty name falls back to the default (cwd basename).
+		const nameTrimmed = nameInput.trim();
+		name = nameTrimmed || cwdName;
+
+		// Description is required; re-prompt on empty until the user provides
+		// one or cancels the whole command.
+		while (true) {
+			const descInput = await ctx.ui.input(
+				"Profile description (what is this profile for and when to use it)",
+				"What this profile is for.",
+			);
+			if (descInput === undefined) {
+				ctx.ui.notify("Cancelled.", "info");
+				return;
+			}
+			const descTrimmed = descInput.trim();
+			if (descTrimmed) {
+				description = descTrimmed;
+				break;
+			}
+			ctx.ui.notify("Description cannot be empty. Please describe the profile.", "warning");
+		}
+		needWriteProfile = true;
+	}
+
+	const id = slugify(name);
+	if (!id) {
+		ctx.ui.notify(
+			`Profile name "${name}" doesn't yield a valid directory name. Use letters, numbers, or hyphens.`,
+			"error",
+		);
+		return;
+	}
+	const targetDir = join(profilesDir, id);
+
+	if (lstatSafe(targetDir)) {
+		ctx.ui.notify(
+			`Profile "${id}" already exists at ${targetDir}.`,
+			"warning",
+		);
+		const choice = await ctx.ui.select(
+			`Overwrite the existing profile "${id}" with the contents of ./${CONFIG_DIR_NAME}?`,
+			[YES, NO],
+		);
+		if (choice !== YES) {
+			ctx.ui.notify("Cancelled.", "info");
+			return;
+		}
+		rmSync(targetDir, { recursive: true, force: true });
+	}
+
+	mkdirSync(profilesDir, { recursive: true });
+	cpSync(sourceDir, targetDir, { recursive: true });
+
+	if (needWriteProfile) {
+		const profileContent =
+			`---\n` +
+			`name: ${name}\n` +
+			`description: ${description}\n` +
+			`---\n\n` +
+			`# ${name}\n\n` +
+			`Add profile documentation here.\n`;
+		writeFileSync(join(targetDir, PROFILE_FILE), profileContent);
+	}
+
+	ctx.ui.notify(
+		`Created profile "${id}" at ${targetDir}.\n\n` +
+			`Use \`/profile ${id}\` to load it.`,
+		"info",
+	);
+}
+
+async function doLoad(profile: Profile, profilesDir: string, ctx: ExtensionCommandContext): Promise<void> {
+	const linkPath = join(ctx.cwd, CONFIG_DIR_NAME);
+	const existing = lstatSafe(linkPath);
+
+	if (existing) {
+		if (existing.isSymbolicLink()) {
+			const target = readlinkSync(linkPath);
+			if (target === profile.dir) {
+				ctx.ui.notify(`Profile "${profile.name}" is already loaded.`, "info");
+				return;
+			}
+			const choice = await ctx.ui.select(
+				`./${CONFIG_DIR_NAME} currently points to:\n  ${target}\n\nReplace it with profile "${profile.name}"?`,
+				[YES, NO],
+			);
+			if (choice !== YES) {
+				ctx.ui.notify("Cancelled.", "info");
+				return;
+			}
+			unlinkSync(linkPath);
+		} else {
+			// Real file or directory - never touch without explicit consent.
+			const choice = await ctx.ui.select(
+				`./${CONFIG_DIR_NAME} already exists in this directory and is not a symlink.\n\n` +
+					`Replace it with a symlink to profile "${profile.name}"?\n` +
+					`(The existing ./${CONFIG_DIR_NAME} will be removed.)`,
+				[YES, NO],
+			);
+			if (choice !== YES) {
+				ctx.ui.notify(
+					`Cancelled. Move or rename ./${CONFIG_DIR_NAME} first if you want to switch profiles.`,
+					"info",
+				);
+				return;
+			}
+			rmSync(linkPath, { recursive: true, force: true });
+		}
+	}
+
+	try {
+		symlinkSync(profile.dir, linkPath, "dir");
+	} catch (err) {
+		ctx.ui.notify(`Failed to create symlink: ${(err as Error).message}`, "error");
+		return;
+	}
+
+	ctx.ui.notify(
+		`Loaded profile "${profile.name}".\n  ./${CONFIG_DIR_NAME} -> ${profile.dir}\nReloading pi...`,
+		"info",
+	);
+
+	// Reload so the profile's extensions/skills/etc. take effect immediately.
+	// The reload re-discovers resources; the symlink makes the profile's
+	// contents appear at ./pi, so they get picked up on this reload.
+	await ctx.reload();
+}
+
+export default function profilesExtension(pi: ExtensionAPI) {
+	const config = loadConfig();
+	const profilesDir = config.profilesDir || join(homedir(), ".pi", "profiles");
+
+	pi.registerCommand("profiles", {
+		description: "List available profiles from ~/.pi/profiles",
+		handler: async (_args, ctx) => {
+			const profiles = listProfiles(profilesDir);
+
+			if (profiles.length === 0) {
+				ctx.ui.notify(
+					`No profiles found in ${profilesDir}.\n` +
+						`Create a subdirectory containing a ${PROFILE_FILE} file ` +
+						`(YAML frontmatter: name, description).`,
+					"warning",
+				);
+				return;
+			}
+
+			const lines = profiles.map(formatLine);
+			const choice = await ctx.ui.select(
+				`Profiles (${profiles.length}) — select to load`,
+				lines,
+			);
+			if (!choice) return;
+
+			const idx = lines.indexOf(choice);
+			const profile = profiles[idx];
+			if (profile) await doLoad(profile, profilesDir, ctx);
+		},
+	});
+
+	pi.registerCommand("profile", {
+		description: "Load a profile: /profile <name> — symlinks ./.pi to ~/.pi/profiles/<name>",
+		getArgumentCompletions: (prefix) => {
+			const matches = listProfiles(profilesDir).filter(
+				(p) => p.id.startsWith(prefix) || p.name.toLowerCase().startsWith(prefix.toLowerCase()),
+			);
+			return matches.length > 0 ? matches.map((p) => ({ value: p.id, label: p.name })) : null;
+		},
+		handler: async (args, ctx) => {
+			const query = args.trim();
+
+			if (!query) {
+				const profiles = listProfiles(profilesDir);
+				if (profiles.length === 0) {
+					ctx.ui.notify(`No profiles found in ${profilesDir}.`, "warning");
+					return;
+				}
+				const lines = profiles.map(formatLine);
+				const choice = await ctx.ui.select("Load which profile?", lines);
+				if (!choice) return;
+				const idx = lines.indexOf(choice);
+				const profile = profiles[idx];
+				if (profile) await doLoad(profile, profilesDir, ctx);
+				return;
+			}
+
+			const profile = findProfile(query, profilesDir);
+			if (!profile) {
+				ctx.ui.notify(`Profile not found: ${query}`, "error");
+				return;
+			}
+
+			await doLoad(profile, profilesDir, ctx);
+		},
+	});
+
+	pi.registerCommand("profile-from-project", {
+		description:
+			"Capture ./pi as a new profile: /profile-from-project — copies the project's .pi to the profiles directory",
+		handler: async (_args, ctx) => {
+			await doCreateFromProject(profilesDir, ctx);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@timurci/pi-profiles",
+  "version": "0.1.0",
+  "description": "Reusable pi configuration profiles for projects",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "author": {
+    "name": "Timur Çakmakoğlu",
+    "email": "timurcakmakoglu@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timurci/pi-profiles"
+  },
+  "homepage": "https://github.com/timurci/pi-profiles",
+  "bugs": {
+    "url": "https://github.com/timurci/pi-profiles/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions"]
+  }
+}