pi-profile-switch 0.6.0 → 0.8.0

package/README.md

@@ -27,72 +27,62 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## Define your own profiles
 
-Profiles live in two JSON files, both optional:
+Profiles live in two directories, with one JSON file per profile:
 
-| File | Scope |
+| Path | Scope |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root; `~/.pi/agent/profiles.json` is read as a legacy fallback for migration. |
-| `<project>/.pi/profiles.json` | Project-level, trusted projects only. |
+| `~/.pi-profile-switch/profiles/<name>.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the workspace root. |
+| `<project>/.pi/profiles/<name>.json` | Project-level, trusted projects only. |
 
-Create or change a profile by editing the JSON directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-On install, pi-profile-switch seeds the global file with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
+On install, pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {
-  "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."
-    }
-  }
+  "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."
 }
 ```
 
-One profile can use every field at once. This example `impl` profile loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
+One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +93,15 @@ How fields resolve:
 - `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
 - Any field you omit keeps plain Pi behavior.
 
-The files in [`examples/`](examples/) mirror the two profiles above: `profiles.json` is the seeded starter, `example.json` the full-field demo.
+The files in [`examples/`](examples/) mirror the two profiles above: `ask.json` is the seeded starter, `example.json` the full-field demo.
+
+### Migrating from earlier versions
+
+If you used an earlier version that stored all profiles in a single `profiles.json` (`schemaVersion: 1`), migrate manually by creating a file for each profile under the `profiles/` directory:
+
+1. Create directory `~/.pi-profile-switch/profiles/` (or `<project>/.pi/profiles/`).
+2. For each key `<name>` in your old `profiles.json`'s `profiles` object, save its value directly as `<name>.json`.
+3. Drop the outer `schemaVersion` and `profiles` envelope.
 
 ## Commands
 

package/README.zh-CN.md

@@ -27,72 +27,62 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## 自定义 profile
 
-profile 定义在两个 JSON 文件中，均可选：
+profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件：
 
-| 文件 | 作用域 |
+| 路径 | 作用域 |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录；`~/.pi/agent/profiles.json` 作为遗留路径向下兼容，用于迁移。 |
-| `<项目>/.pi/profiles.json` | 项目级，仅对已信任项目生效。 |
+| `~/.pi-profile-switch/profiles/<name>.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录。 |
+| `<项目>/.pi/profiles/<name>.json` | 项目级，仅对已信任项目生效。 |
 
-直接编辑 JSON 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-安装时，pi-profile-switch 会向全局文件播种一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {
-  "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."
-    }
-  }
+  "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."
 }
 ```
 
-一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
+一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +93,15 @@ profile 定义在两个 JSON 文件中，均可选：
 - `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
 - 未写的字段保持原生 Pi 行为。
 
-[`examples/`](examples/) 中的两个文件与上面一一对应：`profiles.json` 是播种的初始 profile，`example.json` 是全字段演示。
+[`examples/`](examples/) 中的两个文件与上面一一对应：`ask.json` 是播种的初始 profile，`example.json` 是全字段演示。
+
+### 从旧版本迁移
+
+如果你之前使用了把全部 profile 存在单个 `profiles.json`（含 `schemaVersion: 1`）的旧版本，请手动把每个 profile 拆分到 `profiles/` 目录：
+
+1. 创建 `~/.pi-profile-switch/profiles/`（或 `<项目>/.pi/profiles/`）目录。
+2. 将旧 `profiles.json` 中 `profiles` 下的每个 `<name>` 键值提取为独立的 `<name>.json` 文件。
+3. 去除外层的 `schemaVersion` 与 `profiles` 信封，文件顶层即为裸 profile 定义。
 
 ## 命令
 

package/bin/pi-profile.ts

@@ -37,10 +37,16 @@ try {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	// Stale per-launch instance dirs (dead pid, or no pid past the grace
-	// window) are swept before this launch materializes its own. Directories
-	// holding state pi-profile did not generate are kept and reported instead of
-	// deleted (ADR-0010). Best-effort: sweep errors never block the launch.
-	for (const warning of await sweepStaleInstances()) {
+	// window) are swept before this launch materializes its own. Unrecognized
+	// entries are dispositioned per content scan: kept + reported when they
+	// reference the instance path or cannot be cleared, adopted into the real
+	// agent dir, or deleted on a name conflict (real wins) — all with a stderr
+	// notice (ADR-0012). Best-effort: sweep errors never block the launch.
+	const sweep = await sweepStaleInstances(agentDir);
+	for (const notice of sweep.notices) {
+		console.error(`pi-profile: notice: ${notice}`);
+	}
+	for (const warning of sweep.warnings) {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectDir });

package/bin/postinstall.js

@@ -1,29 +1,25 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default profiles file.
+ * postinstall: seed the global catalog with the default starter profile.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
  * Idempotent and conservative:
- * - Writes the shipped `examples/profiles.json` starter catalog 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).
+ * - Writes the shipped `examples/ask.json` starter profile to the
+ *   profiles dir ONLY when no .json profile exists there yet
+ *   (COPYFILE_EXCL; an existing file — including one written concurrently — is never touched).
  * - 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 { copyFile, mkdir, readdir } 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("../examples/profiles.json", import.meta.url));
+const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/ask.json", import.meta.url));
 
 /** Mirrors getProfileSwitchDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
@@ -33,38 +29,40 @@ function profileSwitchDir(env) {
 	return path.join(homedir(), ".pi-profile-switch");
 }
 
-/** The legacy migration fallback the resolver still reads (~/.pi/agent).
+/** Mirrors getGlobalProfilesDir() in src/workspace.ts.
  *  @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");
+function globalProfilesDir(env) {
+	return path.join(profileSwitchDir(env), "profiles");
 }
 
-/** @param {string} filePath */
-async function exists(filePath) {
+/** Checks whether the directory exists and contains any .json files.
+ *  @param {string} dir */
+async function hasAnyJsonProfiles(dir) {
 	try {
-		await access(filePath);
-		return true;
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
 	} catch {
 		return false;
 	}
 }
 
-/** @typedef {{ path: string, written: boolean, skipped?: string }} InstallResult */
+/** @typedef {{ path: string, written: boolean }} InstallResult */
 
 /**
- * Seeds the default catalog. Safe to call repeatedly; only the first call
- * writes.
+ * Seeds the default starter profile. Safe to call repeatedly; only writes
+ * if no .json files exist in the global profiles directory.
  * @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" };
+	const dir = globalProfilesDir(env);
+	const target = path.join(dir, "ask.json");
+
+	if (await hasAnyJsonProfiles(dir)) {
+		return { path: target, written: false };
 	}
-	await mkdir(path.dirname(target), { recursive: true });
+
+	await mkdir(dir, { recursive: true });
 	try {
 		await copyFile(DEFAULT_TEMPLATE, target, constants.COPYFILE_EXCL);
 	} catch (error) {
@@ -80,10 +78,10 @@ const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pat
 if (invokedDirectly) {
 	installDefaultProfiles().then(
 		(result) => {
-			if (result.written) console.log(`pi-profile: seeded default profiles at ${result.path}`);
+			if (result.written) console.log(`pi-profile: seeded starter profile at ${result.path}`);
 		},
 		(error) => {
-			console.warn(`pi-profile: could not seed default profiles: ${error instanceof Error ? error.message : error}`);
+			console.warn(`pi-profile: could not seed starter profile: ${error instanceof Error ? error.message : error}`);
 		},
 	);
 }

package/examples/ask.json

@@ -0,0 +1,13 @@
+{
+  "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/example.json

@@ -1,37 +1,32 @@
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [

package/schemas/profiles.schema.json

@@ -1,86 +1,60 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "pi-profile-switch profile catalog",
-  "description": "Named profile definitions (global ~/.pi-profile-switch/profiles.json, legacy fallback ~/.pi/agent/profiles.json; or project .pi/profiles.json). Definitions are complete and self-contained: there is no inheritance field, and resource references are names/globs, never copies. The built-in \"default\" profile must not be defined here.",
+  "title": "pi-profile-switch profile definition",
+  "description": "A named profile definition stored in ~/.pi-profile-switch/profiles/<name>.json or <project>/.pi/profiles/<name>.json. Definitions are complete and self-contained: there is no inheritance field, and resource references are names/globs, never copies.",
   "type": "object",
-  "required": [
-    "schemaVersion",
-    "profiles"
-  ],
   "additionalProperties": false,
   "properties": {
-    "schemaVersion": {
-      "const": 1
+    "label": {
+      "type": "string",
+      "description": "Display label in the selector and /profile list."
     },
-    "profiles": {
-      "type": "object",
-      "propertyNames": {
-        "not": {
-          "const": "default"
-        }
+    "description": {
+      "type": "string"
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "string"
       },
-      "additionalProperties": {
-        "$ref": "#/$defs/profile"
-      }
-    }
-  },
-  "$defs": {
-    "profile": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "label": {
-          "type": "string",
-          "description": "Display label in the selector and /profile list."
-        },
-        "description": {
-          "type": "string"
-        },
-        "skills": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Skill names or globs (e.g. \"review\", \"internal-*\") referencing discovered skills."
-        },
-        "extensions": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Extension names or globs. Package names, source aliases, loose-file stems, glob patterns, or direct file paths, resolved against discovered extensions."
-        },
-        "mcps": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "MCP server names or globs, discovered by pi-mcp-adapter configuration. Connection details stay in adapter-managed config."
-        },
-        "tools": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Tool names or globs expanded against Pi's live registry (including extension tools)."
-        },
-        "defaultProvider": {
-          "type": "string",
-          "description": "Startup provider for this profile (e.g. \"anthropic\", \"openai\"). Mirrors Pi's settings.defaultProvider."
-        },
-        "defaultModel": {
-          "type": "string",
-          "description": "Startup model ID for this profile. Mirrors Pi's settings.defaultModel."
-        },
-        "defaultThinkingLevel": {
-          "type": "string",
-          "description": "Startup thinking level for this profile. Mirrors Pi's settings.defaultThinkingLevel."
-        },
-        "instructions": {
-          "type": "string",
-          "description": "Appended to Pi's fully built system prompt on every turn."
-        }
-      }
+      "description": "Skill names or globs (e.g. \"review\", \"internal-*\") referencing discovered skills."
+    },
+    "extensions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Extension names or globs. Package names, source aliases, loose-file stems, glob patterns, or direct file paths, resolved against discovered extensions."
+    },
+    "mcps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "MCP server names or globs, discovered by pi-mcp-adapter configuration. Connection details stay in adapter-managed config."
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Tool names or globs expanded against Pi's live registry (including extension tools)."
+    },
+    "defaultProvider": {
+      "type": "string",
+      "description": "Startup provider for this profile (e.g. \"anthropic\", \"openai\"). Mirrors Pi's settings.defaultProvider."
+    },
+    "defaultModel": {
+      "type": "string",
+      "description": "Startup model ID for this profile. Mirrors Pi's settings.defaultModel."
+    },
+    "defaultThinkingLevel": {
+      "type": "string",
+      "description": "Startup thinking level for this profile. Mirrors Pi's settings.defaultThinkingLevel."
+    },
+    "instructions": {
+      "type": "string",
+      "description": "Appended to Pi's fully built system prompt on every turn."
     }
   }
 }