pi-profile-switch 0.3.0 → 0.4.0

package/README.md

@@ -2,16 +2,14 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile selects what the model sees and which capabilities the session uses — skills, MCP servers, tools, a model preset, and extra instructions — switchable in the same Pi process.
+Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile references a set of existing skills, extensions, MCP servers, and tools — switch between them in the same Pi process, without restarting.
 
-A shipped `read-only` preset covers the read-and-report workflow; other workflows you write yourself — a profile can narrow the tool set, hide skills, pin a model, or add instructions.
-
-`pi-profile-switch` is a plain Pi package (ADR-0007). It installs like any other extension, leaves Pi's configuration directory untouched, and keeps sessions, packages, project trust, and every other installed extension native.
+Use a lean read-only profile for code review, a full-powered one for implementation, a minimal one for a quick question — all against the same installed resources.
 
 ## Install
 
 ```bash
-pi install npm:pi-profile-switch
+npm install -g pi-profile-switch
 ```
 
 Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (installed automatically as a peer dependency).
@@ -19,33 +17,36 @@ Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (in
 ## Quick start
 
 ```bash
-# Use the saved profile (or the built-in default)
-pi
+# Launch with the built-in default profile (all resources, plain Pi behavior)
+pi-profile
 
-# Use a profile for this run only (not saved)
-pi --profile read-only
+# Launch with a named profile
+pi-profile review
 
-# The explicit native baseline
-pi --profile default
+# Anything after -- is passed to pi verbatim
+pi-profile review -- --model openai/gpt-5.4
 ```
 
-Create profiles with `/profile create`, which writes `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only). The wizard offers the shipped `read-only` preset — Pi's built-in tools only, no skills, MCP servers, or model assumed — or a blank definition.
-
-A preset is a one-time copy into your catalog: it is not tracked, so a package update never changes a profile you already created. Profiles **reference** resources by name — they never copy them. [`examples/profiles.example.json`](examples/profiles.example.json) is a complete catalog with several profiles covering every field; replace its resource names with ones you own.
-
-`schemaVersion` is 1 and is the only accepted value. A profile cannot select extensions: they load natively in every profile, so manage them with `pi install`.
-
-## What a profile controls
+Define profiles in `~/.pi-profile-switch/profiles.json` (global, fallback to `~/.pi/agent/profiles.json` for migration; custom root via `PI_PROFILE_SWITCH_DIR`) or `<project>/.pi/profiles.json` (project, trusted projects only):
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "review": {
+      "label": "Code review",
+      "skills": ["code-review"],
+      "mcp": ["github"],
+      "tools": ["read", "grep", "find", "bash"],
+      "instructions": "Review only; do not modify files."
+    }
+  }
+}
+```
 
-| Field | Effect |
-| --- | --- |
-| `instructions` | Text appended to the system prompt every turn |
-| `model` | Session-start model preset; an explicit `--model`/`--thinking` or a model recorded in the session wins |
-| `skills` | What the model sees in the prompt's skills list. Every installed skill stays loaded and callable by the user through `/skill:name` |
-| `mcp` | Which MCP servers the session exposes: the profile's allowlist is written into the adapter's own config (`~/.pi/agent/mcp.json`), disabling every other server. Servers you keep in that file move to `mcp.user.json`; connection details stay in your config, never in the profile |
-| `tools` | Active tool set: declared names/globs become the active set; names that register later (MCP, extensions) are applied when they appear |
+Profiles **reference** resources by name — they never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed. Full schema with more examples: [`examples/profiles.json`](examples/profiles.json).
 
-Anything a profile does not declare keeps Pi's native behavior, and `default` declares nothing.
+On install, pi-profile-switch seeds `~/.pi-profile-switch/profiles.json` with a starter **`ask`** profile — read-only Q&A and code exploration (`read`/`grep`/`find`/`ls`, no skills, extensions, or MCP). It assumes nothing about your setup; edit or delete it freely.
 
 ## Commands
 
@@ -55,25 +56,24 @@ In the TUI, the `/profile` command family manages everything in-session:
 | --- | --- |
 | `/profile` | Interactive profile picker |
 | `/profile list` / `/profile status` | Show profiles / active profile details |
-| `/profile use <name>` | Switch in place — same session; when the MCP selection changes, the runtime reloads automatically to re-apply it |
+| `/profile use <name>` / `/profile reload` | Switch / reload without restarting (rollback on failure) |
 | `/profile create\|edit\|delete\|duplicate` | Guided profile CRUD (TUI only) |
+| `/profile resource create\|edit\|delete` | Guided resource overrides |
 | `/profile customize` / `/profile reset` | Narrow the active profile for this session only |
 | `/mcp enable\|disable <server>` | Toggle MCP servers in the active profile |
 
-While a non-`default` profile is active, the footer shows `profile: <name>`, with `*` appended when a session-only overlay is in effect. `default` shows no badge, so an unprofiled session keeps Pi's native footer.
-
 All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizards are TUI-only.
 
 ## Guarantees
 
 - **Reference, never copy** — profiles point at resources you already own and maintain.
-- **Pi-native** — the configuration directory is Pi's own, so sessions, extension config, packages, context files, and trust behave exactly as they do in plain Pi.
-- **Fail safe** — untrusted project directories are never read; a failed activation applies nothing and reports the cause.
-- **No manual reload** — switching re-applies runtime state in place and the next turn's prompt carries the new selection. Only a change to the MCP selection rebuilds the runtime, automatically, in the same session.
+- **Pi-native** — anything a profile doesn't explicitly control keeps plain Pi behavior.
+- **Fail safe** — untrusted project directories are never read; a failed switch rolls back to the last working configuration.
 
 ## Docs
 
 - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
+- JSON Schemas: [`schemas/`](schemas/)
 
 ## License
 

package/README.zh-CN.md

@@ -2,16 +2,14 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 选择模型看到什么、会话使用哪些能力——skills、MCP server、tools、预制模型和附加指令——并在同一 Pi 进程内即时切换。
+[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 引用一组已存在的 skills、extensions、MCP server 和 tools，并在同一 Pi 进程内切换，无需重启。
 
-随包提供一个 `read-only` 预设覆盖「读代码 + 报告」的工作流；其余工作流由你自己定义——profile 可以收窄工具集、隐藏 skill、固定模型或附加指令。
-
-`pi-profile-switch` 是普通 Pi package（ADR-0007）：像其他扩展一样安装，不改动 Pi 的配置目录，session、packages、项目信任和其他扩展全部保持原生。
+代码评审用精简的只读 profile，实现需求用全量 profile，临时提问用最小 profile——全部基于同一套已安装的资源。
 
 ## 安装
 
 ```bash
-pi install npm:pi-profile-switch
+npm install -g pi-profile-switch
 ```
 
 依赖 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)（作为 peer dependency 自动安装）。
@@ -19,33 +17,36 @@ pi install npm:pi-profile-switch
 ## 快速上手
 
 ```bash
-# 使用已保存的 profile（不存在时用内建 default）
-pi
+# 使用内建 default profile 启动（全量资源，等同原生 Pi）
+pi-profile
 
-# 仅本次启动使用指定 profile（不保存）
-pi --profile read-only
+# 使用指定 profile 启动
+pi-profile review
 
-# 显式的原生基线
-pi --profile default
+# -- 后面的参数原样传给 pi
+pi-profile review -- --model openai/gpt-5.4
 ```
 
-用 `/profile create` 创建 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始。
-
-预设只被复制一次：它不被跟踪，包升级不会改动你已经创建的 profile。Profile 只**引用**资源，从不复制资源。[`examples/profiles.example.json`](examples/profiles.example.json) 是覆盖全部字段的完整 catalog，示例中的资源名请替换成你本机已有的名字。
-
-`schemaVersion` 为 1，也是唯一接受的值。Profile 不选择 extension：extensions 在所有 profile 中原生加载，请用 `pi install` 管理。
-
-## Profile 控制的范围
+在 `~/.pi-profile-switch/profiles.json`（全局，支持 `PI_PROFILE_SWITCH_DIR` 环境变量自定义，向下兼容 `~/.pi/agent/profiles.json`）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）中定义 profile：
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "review": {
+      "label": "Code review",
+      "skills": ["code-review"],
+      "mcp": ["github"],
+      "tools": ["read", "grep", "find", "bash"],
+      "instructions": "Review only; do not modify files."
+    }
+  }
+}
+```
 
-| 字段 | 效果 |
-| --- | --- |
-| `instructions` | 每个 turn 追加到 system prompt 末尾 |
-| `model` | 会话启动的模型预设；显式 `--model`/`--thinking` 或 session 历史中记录的模型优先 |
-| `skills` | 模型在 prompt skills 列表中看到的内容；所有已安装 skill 仍保持加载，用户可用 `/skill:name` 手动调用 |
-| `mcp` | 本次会话暴露哪些 MCP server：白名单写入 adapter 自己的配置（`~/.pi/agent/mcp.json`），其余 server 一律标为 disabled。你原本放在该文件里的 server 会迁移到 `mcp.user.json`；连接参数只在你自己的配置里，从不进入 profile |
-| `tools` | 活动工具集：声明的名字/glob 成为活动集合；之后才注册的工具（MCP、扩展）在出现时补上 |
+Profile 只**引用**资源，从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。完整示例见 [`examples/profiles.json`](examples/profiles.json)。
 
-未声明的字段保持 Pi 原生行为，`default` 什么都不声明。
+安装时，pi-profile-switch 会向 `~/.pi-profile-switch/profiles.json` 写入一个初始 **`ask`** profile——只读的问答与代码走读模式（仅 `read`/`grep`/`find`/`ls`，无 skill、extension 和 MCP）。它不假设你安装过任何插件，可随意修改或删除。
 
 ## 命令
 
@@ -55,25 +56,24 @@ pi --profile default
 | --- | --- |
 | `/profile` | 交互式选择 profile |
 | `/profile list` / `/profile status` | 列出 profile / 查看活动 profile 详情 |
-| `/profile use <name>` | 原位切换——同一 session；当 MCP 选择发生变化时会自动 reload 以重新应用 |
+| `/profile use <name>` / `/profile reload` | 会话内切换 / 重载（失败自动回滚） |
 | `/profile create\|edit\|delete\|duplicate` | 向导式 profile 增删改（仅 TUI） |
+| `/profile resource create\|edit\|delete` | 向导式资源覆盖管理 |
 | `/profile customize` / `/profile reset` | 仅本次会话收窄活动 profile |
 | `/mcp enable\|disable <server>` | 在活动 profile 中开关 MCP server |
 
-活动 profile 不是 `default` 时，footer 显示 `profile: <name>`；本次会话的 overlay 生效时追加 `*`。`default` 不显示 badge，未使用 profile 的会话保持 Pi 原生 footer。
-
 非交互模式（`--mode rpc|print|json`）下命令同样生效；CRUD 向导仅 TUI 可用。
 
 ## 保证
 
 - **引用而非复制**——profile 指向你自己拥有和维护的资源。
-- **Pi 原生**——配置目录就是 Pi 自己的目录，session、扩展配置、packages、context 文件和信任行为与原生 Pi 完全一致。
-- **失败安全**——未信任的项目目录从不读取；激活失败时不应用任何设置并报出原因。
-- **无需手动 reload**——切换在原位重新应用运行时状态，下一个 turn 的 prompt 直接带上新选择；只有 MCP 选择变化时才会自动重建运行时（同一 session）
+- **Pi 原生**——profile 未显式控制的一切保持原生 Pi 行为。
+- **失败安全**——未信任的项目目录从不读取；切换失败回滚到上一份可用配置。
 
 ## 文档
 
 - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
+- JSON Schema：[`schemas/`](schemas/)
 
 ## 许可证
 

package/bin/pi-profile.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Installed entry point. Node refuses type-stripping under node_modules, so
+ * the shipped package loads the TypeScript launcher through jiti (the same
+ * loader Pi uses for extensions). Development can run bin/pi-profile.ts
+ * directly; both paths share the one TS graph.
+ */
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url);
+await jiti.import("./pi-profile.ts");

package/bin/pi-profile.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * pi-profile launcher (ADR-0005).
+ *
+ * Resolves the initial profile, materializes it as a generated runtime
+ * directory (settings + symlinks + env + flags), and spawns the real `pi`
+ * binary with user arguments passed through verbatim.
+ *
+ * Usage:
+ *   pi-profile                          # default profile
+ *   pi-profile review                   # named profile (once catalogs land)
+ *   pi-profile review -- --mode rpc --model openai/gpt-5.4
+ */
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { ExtensionError } from "../src/extension-discovery.ts";
+import { parseLauncherArgs } from "../src/launcher/args.ts";
+import { UnknownProfileError, resolveInitialProfile } from "../src/launcher/initial-profile.ts";
+import { sweepStaleRuntimeDirs } from "../src/launcher/runtime-cleanup.ts";
+import { spawnPi } from "../src/launcher/spawn.ts";
+import { McpConfigError } from "../src/mcp-config.ts";
+import { MissingMcpAdapterError } from "../src/mcp-coordination.ts";
+import { CatalogError } from "../src/profile-catalog.ts";
+import { ActivationError } from "../src/profile-resolver.ts";
+import { generateRuntimeDir } from "../src/settings-generator.ts";
+
+try {
+	const args = parseLauncherArgs(process.argv.slice(2));
+	const agentDir = getAgentDir();
+	// Fails before spawning when the profile is unknown or cannot activate.
+	// --approve/--no-approve are consumed here as a one-run trust input.
+	const { plan, discovery, projectSettings, warnings } = await resolveInitialProfile(args.profile, {
+		agentDir,
+		cwd: process.cwd(),
+		trustOverride: args.trustOverride,
+	});
+	for (const warning of warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
+	// Stale per-launch runtime dirs (dead pid, or no pid past the grace
+	// window) are swept before this launch materializes its own. Best-effort:
+	// sweep errors never block the launch.
+	await sweepStaleRuntimeDirs(agentDir);
+	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectSettings });
+	process.exitCode = await spawnPi({
+		generated,
+		piArgs: args.piArgs,
+		// Only the default profile keeps trust behavior native (flag re-applied);
+		// named profiles never forward it — the resolver is the trust gatekeeper.
+		trustOverride: plan.filter === "none" ? args.trustOverride : undefined,
+	});
+} catch (error) {
+	// Launcher input/selection failures (unknown profile, unresolvable
+	// references, missing adapter, malformed catalogs) are usage errors:
+	// exit 2. Unexpected failures: exit 1.
+	const isUsageError =
+		error instanceof UnknownProfileError ||
+		error instanceof ActivationError ||
+		error instanceof ExtensionError ||
+		error instanceof MissingMcpAdapterError ||
+		error instanceof McpConfigError ||
+		error instanceof CatalogError;
+	console.error(error instanceof Error ? `pi-profile: ${error.message}` : error);
+	process.exitCode = isUsageError ? 2 : 1;
+}

package/bin/postinstall.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Types for the plain-JS install-time seeder (bin/postinstall.js), which
+ * stays dependency-free and cannot ship TypeScript.
+ */
+
+export interface InstallResult {
+	path: string;
+	written: boolean;
+	/** Present when skipped to avoid shadowing a legacy catalog. */
+	skipped?: "legacy-catalog-present";
+}
+
+export function installDefaultProfiles(options?: { env?: NodeJS.ProcessEnv }): Promise<InstallResult>;

package/bin/postinstall.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * postinstall: seed the global catalog with the default profiles file.
+ *
+ * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
+ * Idempotent and conservative:
+ * - Writes `defaults/profiles.json` to the profile-switch dir ONLY when no
+ *   catalog exists there yet (COPYFILE_EXCL; an existing file — including
+ *   one written concurrently — is never touched).
+ * - Skips entirely when a legacy `~/.pi/agent/profiles.json` exists, because
+ *   the resolver still falls back to it and a new preferred-path file would
+ *   silently shadow it (see src/workspace.ts resolveGlobalProfilesPath).
+ * - Never fails the install: errors are downgraded to a warning.
+ *
+ * This module is plain Node ESM (no jiti/TS): npm may run postinstall in a
+ * context where only plain JS is safe. The path rules intentionally mirror
+ * src/workspace.ts — keep them in sync.
+ */
+import { access, copyFile, mkdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DEFAULT_TEMPLATE = fileURLToPath(new URL("../defaults/profiles.json", import.meta.url));
+
+/** Mirrors getProfileSwitchDir() in src/workspace.ts.
+ *  @param {NodeJS.ProcessEnv} env */
+function profileSwitchDir(env) {
+	const override = env.PI_PROFILE_SWITCH_DIR;
+	if (override && override.trim()) return path.resolve(override.trim());
+	return path.join(homedir(), ".pi-profile-switch");
+}
+
+/** The legacy migration fallback the resolver still reads (~/.pi/agent).
+ *  @param {NodeJS.ProcessEnv} env */
+function legacyCatalogPath(env) {
+	const agentDir = env.PI_CODING_AGENT_DIR ?? path.join(homedir(), ".pi", "agent");
+	return path.join(agentDir, "profiles.json");
+}
+
+/** @param {string} filePath */
+async function exists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** @typedef {{ path: string, written: boolean, skipped?: string }} InstallResult */
+
+/**
+ * Seeds the default catalog. Safe to call repeatedly; only the first call
+ * writes.
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<InstallResult>}
+ */
+export async function installDefaultProfiles({ env = process.env } = {}) {
+	const target = path.join(profileSwitchDir(env), "profiles.json");
+	if (await exists(target)) return { path: target, written: false };
+	if (await exists(legacyCatalogPath(env))) {
+		return { path: target, written: false, skipped: "legacy-catalog-present" };
+	}
+	await mkdir(path.dirname(target), { recursive: true });
+	try {
+		await copyFile(DEFAULT_TEMPLATE, target, constants.COPYFILE_EXCL);
+	} catch (error) {
+		// Lost a create race (e.g. two installs in parallel): the winner's
+		// file stands; still not ours to overwrite.
+		if (error.code === "EEXIST") return { path: target, written: false };
+		throw error;
+	}
+	return { path: target, written: true };
+}
+
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+	installDefaultProfiles().then(
+		(result) => {
+			if (result.written) console.log(`pi-profile: seeded default profiles at ${result.path}`);
+		},
+		(error) => {
+			console.warn(`pi-profile: could not seed default profiles: ${error instanceof Error ? error.message : error}`);
+		},
+	);
+}

package/defaults/profiles.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "ask": {
+      "label": "Ask & Discuss",
+      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+      "skills": [],
+      "extensions": [],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
+    }
+  }
+}

package/examples/profiles.json

@@ -1,16 +1,42 @@
 {
   "schemaVersion": 1,
   "profiles": {
-    "read-only": {
-      "label": "Read-only",
-      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
+    "review": {
+      "label": "Code review",
+      "description": "Read-heavy review workflow",
+      "skills": [
+        "code-review",
+        "diagnosing-bugs"
+      ],
+      "extensions": [
+        "pi-mcp-adapter"
+      ],
+      "mcps": [
+        "github"
+      ],
       "tools": [
         "read",
         "grep",
         "find",
-        "ls"
+        "bash"
+      ],
+      "instructions": "Review only; do not modify files."
+    },
+    "impl": {
+      "label": "Implementation",
+      "skills": [
+        "tdd"
+      ],
+      "extensions": [
+        "pi-mcp-adapter"
+      ],
+      "mcps": [
+        "github",
+        "linear"
       ],
-      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
+      "defaultProvider": "deepseek",
+      "defaultModel": "deepseek-v4-pro",
+      "defaultThinkingLevel": "high"
     }
   }
 }