pi-patch-keeper 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-plugins contributors
+
+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.en.md

@@ -0,0 +1,43 @@
+# pi-patch-keeper — extension load-order guard (pi extension)
+
+Stops "force-type" extensions from silently dropping every later section.
+
+## Features
+
+- Checks `packages` order in `~/.pi/agent/settings.json` at startup.
+- Statically scans npm extension sources for unconditional `return { systemPrompt }` / `forceSystemPrompt`.
+- Moves known force-type packages to the end of `packages` (settings backed up first).
+- Speaks only when something is wrong; `/patch-keeper` reports, `/patch-keeper fix` repairs.
+- This release contains no machine-specific patch healing (source patches, PiDeck asar, etc.).
+
+## Defaults
+
+| Item | Default | Note |
+| --- | --- | --- |
+| Force-type packages | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | override via `forceTail` |
+| Auto repair | on | backup `settings.json.bak-force-order-*` |
+| Startup notice | only on issue | silent when clean |
+| Scope | `npm:` packages | local path packages are skipped |
+
+## Install
+
+```bash
+pi install npm:pi-patch-keeper@1.0.0
+pi install ./pi-patch-keeper
+```
+
+## Config
+
+```json
+{ "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
+```
+
+## How it works
+
+- Reads each npm package's `pi.extensions` entry and compares where sections and force appear: sections first means a compatibility fallback, not an unconditional force.
+- Reports when any package still follows a force-type package.
+
+## Limits
+
+- Only npm packages can be inspected.
+- Reorders loading; never edits package code.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# pi-patch-keeper — 扩展加载顺序守护（pi 扩展）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+防止「force 型扩展」静默吞掉其后所有 section 的 system 注入。
+
+## 来源与借鉴
+
+原创，无上游实现。设计灵感来自本机长期维护 PiDeck / pi 补丁的实践：补丁会被升级覆盖，故需要启动时自检与自愈。
+
+## 功能
+
+- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序。
+- 静态扫描 npm 扩展源码，识别无条件 `return { systemPrompt }` / `forceSystemPrompt` 的包。
+- 已知 force 型包自动移到 `packages` 末尾（先备份 settings）。
+- 启动时只在发现问题时提示；`/patch-keeper` 随时查看状态，`/patch-keeper fix` 手动修复。
+- 发布版不含任何本机补丁自愈逻辑（源码补丁、PiDeck asar 等已剥离）。
+
+## 默认配置
+
+| 项 | 默认 | 说明 |
+| --- | --- | --- |
+| force 型包 | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | `~/.pi/patch-keeper.json` 的 `forceTail` 可覆盖 |
+| 自动修复顺序 | 开 | 写前备份 `settings.json.bak-force-order-*` |
+| 启动提示 | 仅异常时 | 无问题不打扰 |
+| 检测范围 | `npm:` 包 | 本地路径包跳过 |
+
+## 安装
+
+```bash
+pi install npm:pi-patch-keeper@1.0.0
+pi install ./pi-patch-keeper
+```
+
+## 配置示例
+
+```json
+{ "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
+```
+
+## 机制
+
+- 读取每个 npm 包的 `pi.extensions` 入口，检查 `before_agent_start` 中 section 写入与 force 出现的先后：先 sections 后 force 视为兼容兜底，不计入疑似。
+- 判定「force 型包之后仍有其他包」即报问题。
+
+## 限制
+
+- 只能读 `npm:` 包；读不到源码的包跳过。
+- 不修包内代码，只调整加载顺序。

package/index.ts

@@ -0,0 +1,161 @@
+/** 
+ * pi-patch-keeper — extension load-order guard for the pi coding agent.
+ *
+ * Force-type extensions (those returning { systemPrompt } / forceSystemPrompt)
+ * replace the whole system prompt, silently dropping every section written by
+ * handlers that run after them. This extension keeps known force-type packages
+ * at the tail of settings.json "packages" and reports packages that still follow
+ * one of them.
+ *
+ * Release edition: no machine-specific patch healing (source patches, PiDeck
+ * asar, memory fixes) is included.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const HOME = os.homedir();
+const SETTINGS = path.join(HOME, ".pi", "agent", "settings.json");
+const CONFIG = path.join(HOME, ".pi", "patch-keeper.json");
+const NPM_DIR = path.join(HOME, ".pi", "agent", "npm", "node_modules");
+const DEFAULT_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+
+function safeRead(p: string): string | null {
+	try { return readFileSync(p, "utf8"); } catch { return null; }
+}
+
+function readJson(p: string): Record<string, unknown> | null {
+	const t = safeRead(p);
+	if (t === null) return null;
+	try { return JSON.parse(t) as Record<string, unknown>; } catch { return null; }
+}
+
+function forceTail(): string[] {
+	const c = readJson(CONFIG);
+	const t = c?.forceTail;
+	const list = Array.isArray(t) ? t.filter((x): x is string => typeof x === "string") : DEFAULT_TAIL;
+	return list.length ? list : DEFAULT_TAIL;
+}
+
+function packagesOf(): string[] | null {
+	const s = readJson(SETTINGS);
+	const p = s?.packages;
+	return Array.isArray(p) ? p.filter((x): x is string => typeof x === "string") : null;
+}
+
+/** Problems in the current load order (empty = OK). */
+export function forceOrderIssues(packages: string[]): string[] {
+	const out: string[] = [];
+	const tail = forceTail();
+	const present = tail.filter((n) => packages.includes(n));
+	if (!present.length) return out;
+	const minForce = Math.min(...present.map((n) => packages.indexOf(n)));
+	const later = packages.slice(minForce + 1).filter((n) => !tail.includes(n));
+	if (later.length) out.push(
+		"force-type package is followed by " + later.length + " package(s) (" + later.slice(0, 2).join(" / ") +
+		") — their sections are dropped; move " + tail.join(" / ") + " to the end");
+	if (tail.every((n) => packages.includes(n)) && packages.indexOf(tail[0]) > packages.indexOf(tail[1]))
+		out.push("force order should be " + tail.join(" -> ") + " (the most likely trigger goes last)");
+	return out;
+}
+
+/** Reordered packages, or null when already correct. */
+export function normalizeForceOrder(packages: string[]): string[] | null {
+	const tail = forceTail();
+	const present = tail.filter((n) => packages.includes(n));
+	if (!present.length) return null;
+	const next = [...packages.filter((n) => !tail.includes(n)), ...present];
+	return next.join("\n") === packages.join("\n") ? null : next;
+}
+
+/** Repair settings.json order; backs up first. Returns a message or null. */
+function fixForceOrder(): string | null {
+	const s = readJson(SETTINGS);
+	if (!s) return null;
+	const packages = Array.isArray(s.packages) ? (s.packages as string[]) : [];
+	const next = normalizeForceOrder(packages);
+	if (!next) return null;
+	try {
+		copyFileSync(SETTINGS, SETTINGS + ".bak-force-order-" + Date.now());
+		s.packages = next;
+		writeFileSync(SETTINGS, JSON.stringify(s, null, 2), "utf8");
+	} catch (e) { return "force order repair failed: " + (e as Error).message; }
+	return "force order repaired: " + forceTail().filter((n) => next.includes(n)).join(" / ") + " moved to the end";
+}
+
+const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
+const SECTION_RE = /sections\s*(\[|\.)/;
+
+/** Classify static force candidates: sections-first means a legacy-host fallback. */
+function classify(packages: string[]): { force: string[]; fallback: string[] } {
+	const force: string[] = [];
+	const fallback: string[] = [];
+	const tail = forceTail();
+	for (const name of packages) {
+		if (!name.startsWith("npm:") || tail.includes(name)) continue;
+		const dir = path.join(NPM_DIR, name.slice(4));
+		if (!existsSync(dir)) continue;
+		let entries: string[] = [];
+		const pj = readJson(path.join(dir, "package.json")) as { pi?: { extensions?: unknown } } | null;
+		const ex = pj?.pi?.extensions;
+		entries = Array.isArray(ex) ? ex.filter((x): x is string => typeof x === "string") : [];
+		for (const rel of entries.slice(0, 3)) {
+			const src = safeRead(path.join(dir, rel));
+			if (src === null) continue;
+			const i = src.indexOf("before_agent_start");
+			if (i < 0) continue;
+			const body = src.slice(i, i + 4000);
+			const fi = body.search(FORCE_RE);
+			if (fi < 0) continue;
+			const si = body.search(SECTION_RE);
+			if (si >= 0 && si < fi) fallback.push(name); else force.push(name);
+			break;
+		}
+	}
+	return { force, fallback };
+}
+
+function report(): string[] {
+	const lines: string[] = [];
+	const pk = packagesOf();
+	if (!pk) { lines.push("settings: cannot read " + SETTINGS); return lines; }
+	const issues = forceOrderIssues(pk);
+	lines.push("force order: " + (issues.length ? issues[0] : "OK"));
+	const tail = forceTail();
+	lines.push("force packages: " + tail.filter((n) => pk.includes(n)).join(" / ") + (tail.some((n) => !pk.includes(n)) ? " (partial)" : ""));
+	const { force, fallback } = classify(pk);
+	lines.push("static scan: " + (force.length ? "force-like " + force.join(" / ") : "none"));
+	lines.push("fallbacks: " + (fallback.length ? fallback.join(" / ") : "none"));
+	return lines;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("patch-keeper", {
+		description: "Show / repair extension load order (force-type packages must load last)",
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const arg = (args || "").trim().toLowerCase();
+			if (arg === "fix") {
+				const r = fixForceOrder();
+				ctx.ui.notify(r ?? "patch-keeper: load order already correct", "info");
+				return;
+			}
+			ctx.ui.notify("patch-keeper\n" + report().join("\n"), "info");
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+		try {
+			const pk = packagesOf();
+			if (!pk) return;
+			const msgs: string[] = [];
+			for (const x of forceOrderIssues(pk)) msgs.push("patch-keeper: " + x);
+			const fixed = fixForceOrder();
+			if (fixed) msgs.push("patch-keeper: " + fixed);
+			const { force } = classify(pk);
+			const tail = forceTail();
+			const mid = force.filter((n) => pk.indexOf(n) < pk.length - 1 && !tail.includes(n));
+			if (mid.length) msgs.push("patch-keeper: force-like package not last: " + mid.join(" / ") + " — move it to the end of packages");
+			for (const m of msgs) ctx.ui.notify(m, "warning");
+		} catch { /* detection must never break the session */ }
+	});
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "pi-patch-keeper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Guards extension load order so later sections are not silently dropped.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}