pi-profile-switch 0.9.0 → 0.9.1

package/README.md

@@ -36,9 +36,9 @@ Profiles live in two directories, with one JSON file per profile:
 
 Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` on install) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
+You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` — best-effort on install, and guaranteed in place at every launcher startup) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
 
-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:
+pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — best-effort on install, and guaranteed in place at every launcher startup — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {

package/README.zh-CN.md

@@ -18,7 +18,7 @@ npm install -g pi-profile-switch
 # 使用内建 default profile 启动（全量资源，等同原生 Pi）
 pi-profile
 
-# 使用安装时播种的只读 ask profile 启动
+# 使用 starter 只读 ask profile 启动
 pi-profile ask
 
 # -- 后面的参数原样传给 pi
@@ -36,9 +36,9 @@ profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件
 
 直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时分发至 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
+你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时 best-effort 分发、launcher 启动时保证就位，位于 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
 
-安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——安装时 best-effort、launcher 启动时保证就位——它是只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {

package/bin/pi-profile.ts

@@ -21,11 +21,20 @@ import { spawnPi } from "../src/launcher/spawn.ts";
 import { McpConfigError, MissingMcpAdapterError } from "../src/mcp-config.ts";
 import { CatalogError } from "../src/profile-catalog.ts";
 import { ActivationError } from "../src/profile-resolver.ts";
+import { ensureStarterAssets } from "../src/starter-assets.ts";
 import { generateRuntimeDir } from "../src/settings-generator.ts";
 
 try {
 	const args = parseLauncherArgs(process.argv.slice(2));
 	const agentDir = getAgentDir();
+	// Starter assets (seed profile + profile-config skill) are ensured before
+	// initial profile resolution so the seed is visible to this launch's
+	// resolution and /profile list. Best-effort: ensure failures never block
+	// the launch (same pattern as the sweep below).
+	const starterAssets = await ensureStarterAssets({ agentDir });
+	for (const warning of starterAssets.warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	// 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, projectDir, warnings } = await resolveInitialProfile(args.profile, {

package/bin/postinstall.js

@@ -1,9 +1,21 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default starter profile,
- * and distribute the profile-config skill to the agent skills directory.
+ * postinstall: best-effort early seeding of the global catalog with the
+ * default starter profile, and distribution of the profile-config skill to
+ * the agent skills directory.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
+ *
+ * Role: this hook is an early optimization, NOT the sole distribution
+ * channel. npm v12+ blocks dependency lifecycle scripts by default
+ * (allowScripts), so installs that skip this hook are covered by the
+ * launcher instead: `bin/pi-profile.ts` calls the runtime ensure
+ * (src/starter-assets.ts) on every launch, before resolving the initial
+ * profile. The authoritative behavior contract for both assets lives in
+ * openspec/specs/profile-catalog/spec.md ("播种 starter profile" and
+ * "分发 profile-config skill"); keep this script's rules in sync with
+ * src/starter-assets.ts, which is the single TS implementation.
+ *
  * Idempotent and conservative:
  * - Writes the shipped `examples/ask.json` starter profile to the
  *   profiles dir ONLY when no .json profile exists there yet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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/src/starter-assets.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime ensure of starter assets: seeds the starter profile into global
+ * profiles/ if no profile exists yet, and distributes/syncs the profile-config
+ * skill into the user's agent skills directory.
+ *
+ * Idempotent, safe against concurrent launches, and downgrades IO errors
+ * to warnings without throwing.
+ */
+
+import { constants } from "node:fs";
+import { copyFile, mkdir, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { getGlobalProfilesDir } from "./workspace.ts";
+
+export interface StarterAssetFileResult {
+	/** 目标文件绝对路径 */
+	path: string;
+	/** 本次调用是否发生了写入 */
+	written: boolean;
+}
+
+export interface StarterAssetsResult {
+	profile: StarterAssetFileResult;
+	skill: StarterAssetFileResult;
+	/** 人类可读的降级警告；为空表示全部成功或无操作 */
+	warnings: string[];
+}
+
+export interface EnsureStarterAssetsOptions {
+	/** 默认 getGlobalProfilesDir()；测试注入 */
+	globalProfilesDir?: string;
+	/** 默认 Pi 的 getAgentDir()；测试注入 */
+	agentDir?: string;
+	/** 默认由 import.meta.url 定位包根；测试注入 */
+	packageRoot?: string;
+}
+
+async function hasAnyJsonProfiles(dir: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
+	} catch (error: unknown) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") {
+			return false;
+		}
+		throw error;
+	}
+}
+
+export async function ensureStarterAssets(options?: EnsureStarterAssetsOptions): Promise<StarterAssetsResult> {
+	const defaultPackageRoot = fileURLToPath(new URL("..", import.meta.url));
+	const packageRoot = options?.packageRoot ? path.resolve(options.packageRoot) : defaultPackageRoot;
+	const globalProfiles = options?.globalProfilesDir ? path.resolve(options.globalProfilesDir) : getGlobalProfilesDir();
+	const agent = options?.agentDir ? path.resolve(options.agentDir) : getAgentDir();
+
+	const profileTemplate = path.join(packageRoot, "examples", "ask.json");
+	const targetProfilePath = path.join(globalProfiles, "ask.json");
+
+	const skillTemplate = path.join(packageRoot, "skills", "profile-config", "SKILL.md");
+	const targetSkillDir = path.join(agent, "skills", "profile-config");
+	const targetSkillPath = path.join(targetSkillDir, "SKILL.md");
+
+	const warnings: string[] = [];
+	const profileResult: StarterAssetFileResult = {
+		path: targetProfilePath,
+		written: false,
+	};
+	const skillResult: StarterAssetFileResult = {
+		path: targetSkillPath,
+		written: false,
+	};
+
+	// 1. Starter profile seeding
+	try {
+		const hasJson = await hasAnyJsonProfiles(globalProfiles);
+		if (!hasJson) {
+			await mkdir(globalProfiles, { recursive: true });
+			try {
+				await copyFile(profileTemplate, targetProfilePath, constants.COPYFILE_EXCL);
+				profileResult.written = true;
+			} catch (error: unknown) {
+				const err = error as NodeJS.ErrnoException;
+				if (err.code === "EEXIST") {
+					// Lost a create race (concurrent launch); winner stands
+					profileResult.written = false;
+				} else {
+					throw error;
+				}
+			}
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not seed starter profile: ${message}`);
+	}
+
+	// 2. Profile-config skill distribution & sync
+	try {
+		const templateContent = await readFile(skillTemplate, "utf8");
+		let needsWrite = true;
+		try {
+			const existingContent = await readFile(targetSkillPath, "utf8");
+			if (existingContent === templateContent) {
+				needsWrite = false;
+			}
+		} catch (error: unknown) {
+			const err = error as NodeJS.ErrnoException;
+			if (err.code !== "ENOENT") {
+				throw error;
+			}
+		}
+
+		if (needsWrite) {
+			await mkdir(targetSkillDir, { recursive: true });
+			await copyFile(skillTemplate, targetSkillPath);
+			skillResult.written = true;
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not distribute profile-config skill: ${message}`);
+	}
+
+	return {
+		profile: profileResult,
+		skill: skillResult,
+		warnings,
+	};
+}