useful-pi-extensions 0.1.0 → 1.0.0

package/README.md

@@ -2,17 +2,18 @@
 
 English | [中文](README_CN.md)
 
-A small collection of [pi](https://pi.dev) extensions, installed with one command.
+A small collection of [pi](https://pi.dev) extensions, installed with one command. Every extension
+in it is also published on its own, so you can take the collection or just the piece you want.
 
 ```sh
-pi install git:github.com/reedchan7/useful-pi-extensions
+pi install npm:useful-pi-extensions
 ```
 
 ## What is in here
 
-| Extension                                       | What it does                                                                                                                                                                                            |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`statusline`](extensions/statusline/README.md) | Replaces pi's footer with a labelled two-row one: context pressure as a fixed-size meter, cache and cost, the model and effort level, and the latest turn's TTFT and decode throughput in tokens/second |
+| Extension                                               | What it does                                                                                                                                                                                            |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@reedchan/statusline`](packages/statusline/README.md) | Replaces pi's footer with a labelled two-row one: context pressure as a fixed-size meter, cache and cost, the model and effort level, and the latest turn's TTFT and decode throughput in tokens/second |
 
 Only one extension owns the footer, so `statusline` is a complete replacement rather than an
 addition. If you want pi's stock footer back, remove this package and `/reload`.
@@ -26,11 +27,14 @@ addition. If you want pi's stock footer back, remove this package and `/reload`.
 ## Install
 
 ```sh
-# from the repository
-pi install git:github.com/reedchan7/useful-pi-extensions
+# the collection: every extension in this repository
+pi install npm:useful-pi-extensions
 
-# pinned to a tag
-pi install git:github.com/reedchan7/useful-pi-extensions@v0.1.0
+# one extension on its own
+pi install npm:@reedchan/statusline
+
+# from the repository, pinned to a tag
+pi install git:github.com/reedchan7/useful-pi-extensions@v1.0.0
 
 # from a local checkout (development)
 pi install /absolute/path/to/useful-pi-extensions
@@ -38,6 +42,10 @@ pi install /absolute/path/to/useful-pi-extensions
 
 Then reload pi in the running session with `/reload`, or start a new one.
 
+> **Install one surface, not both.** The collection and the individual package ship the same
+> extension file, so installing `useful-pi-extensions` _and_ `@reedchan/statusline` loads it twice.
+> Nothing breaks, but there is nothing to gain either.
+
 > **Removing a loose copy first.** If you were running the extension as a single file in
 > `~/.pi/agent/extensions/`, delete that file before installing this package. Both would load, and
 > two footers race for the same slot — the later one wins, which decides nothing useful.
@@ -50,17 +58,26 @@ Then reload pi in the running session with `/reload`, or start a new one.
 
 ## Layout
 
+Two things are published from this repository: the collection, which is the repository root, and
+each extension under `packages/`, on its own.
+
 ```
-extensions/            # each subdirectory is one extension; pi discovers <name>/index.ts
-  statusline/
-    index.ts           # pi entry point: events and footer wiring
-    render.ts          # pure helpers: number formatting, the meter, row layout
-    render.test.ts     # unit tests for render.ts
+package.json                     # the collection package, published as useful-pi-extensions
+packages/
+  statusline/                    # published as @reedchan/statusline
+    package.json
+    extensions/statusline/
+      index.ts                   # pi entry point: events and footer wiring
+      render.ts                  # pure helpers: number formatting, the meter, row layout
+      render.test.ts             # unit tests for render.ts
+tools/                           # repository tooling: docs pairing, commit lint, publishing
 ```
 
-`package.json` declares `"pi": { "extensions": ["./extensions"] }` and carries the `pi-package`
-keyword so the package is discoverable. pi resolves the manifest, finds every
-`extensions/*/index.ts`, and loads it — no build step, no bundling.
+The collection declares `"pi": { "extensions": ["packages/*/extensions"] }` and the individual
+package declares `"./extensions"`. pi resolves the glob, finds every `extensions/<name>/index.ts`
+and loads it — no build step, no bundling. Adding an extension is therefore adding a directory under
+`packages/`: no manifest needs editing, because the collection's glob picks the new package up on
+its own, and `make publish` discovers it the same way.
 
 ## Development
 
@@ -79,7 +96,7 @@ make help         # list every target
 | Lint   | `bun run lint`       | oxlint in type-aware mode with `--deny-warnings`, so a warning fails the run                                                                                           |
 | Types  | `bun run typecheck`  | `--strict` plus `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` and `verbatimModuleSyntax`, which is what keeps every file loadable by pi without a transform |
 | Docs   | `bun run docs:check` | every `README.md` has a `README_CN.md` with the same heading sequence and a working language switcher                                                                  |
-| Tests  | `bun test`           | the unit tests under `extensions/*/`                                                                                                                                   |
+| Tests  | `bun test`           | the unit tests under `packages/*/`                                                                                                                                     |
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/): the `commit-msg` hook
 rejects a subject that is not `type(scope): summary`, and the pre-commit hook formats and lints only

package/README_CN.md

@@ -2,17 +2,18 @@
 
 [English](README.md) | 中文
 
-一组 [pi](https://pi.dev) 扩展，一行命令即可安装。
+一组 [pi](https://pi.dev) 扩展，一行命令即可安装。其中的每个扩展也会单独发布，
+所以你要么整套装，要么只取其中一件。
 
 ```sh
-pi install git:github.com/reedchan7/useful-pi-extensions
+pi install npm:useful-pi-extensions
 ```
 
 ## 包含什么
 
-| 扩展                                               | 作用                                                                                                                                           |
-| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`statusline`](extensions/statusline/README_CN.md) | 替换 pi 的 footer，改成带文字标签的两行：上下文压力用固定宽度仪表显示，外加缓存与花费、模型与思考等级，以及最近一轮的 TTFT 和解码速度（tok/s） |
+| 扩展                                                       | 作用                                                                                                                                           |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@reedchan/statusline`](packages/statusline/README_CN.md) | 替换 pi 的 footer，改成带文字标签的两行：上下文压力用固定宽度仪表显示，外加缓存与花费、模型与思考等级，以及最近一轮的 TTFT 和解码速度（tok/s） |
 
 footer 只能有一个扩展占用，所以 `statusline` 是**替换**而不是叠加。想回到 pi 原生 footer，移除本包再 `/reload`。
 
@@ -25,11 +26,14 @@ footer 只能有一个扩展占用，所以 `statusline` 是**替换**而不是
 ## 安装
 
 ```sh
-# 从仓库安装
-pi install git:github.com/reedchan7/useful-pi-extensions
+# 合集：本仓库的全部扩展
+pi install npm:useful-pi-extensions
 
-# 锁定标签
-pi install git:github.com/reedchan7/useful-pi-extensions@v0.1.0
+# 只要其中一个扩展
+pi install npm:@reedchan/statusline
+
+# 从仓库安装并锁定标签
+pi install git:github.com/reedchan7/useful-pi-extensions@v1.0.0
 
 # 从本地检出安装（开发用）
 pi install /absolute/path/to/useful-pi-extensions
@@ -37,6 +41,10 @@ pi install /absolute/path/to/useful-pi-extensions
 
 然后在运行中的会话里执行 `/reload`，或直接新开一个会话。
 
+> **只装一个入口，不要两个都装。** 合集与单独包包含的是同一个扩展文件，
+> 同时安装 `useful-pi-extensions` 与 `@reedchan/statusline` 会让它被加载两次。
+> 这不会出错，但也没有任何好处。
+
 > **先删掉散装的那份。** 如果你之前把扩展作为单文件放在 `~/.pi/agent/extensions/`，
 > 安装本包之前请先删掉那个文件。两份会同时加载，两个 footer 抢同一个位置——
 > 后加载的赢，而谁后加载没有意义。
@@ -49,16 +57,24 @@ pi install /absolute/path/to/useful-pi-extensions
 
 ## 目录结构
 
+本仓库发布两样东西：合集，即仓库根目录；以及 `packages/` 下每个扩展各自成包。
+
 ```
-extensions/            # 每个子目录是一个扩展；pi 发现 <name>/index.ts
-  statusline/
-    index.ts           # pi 入口：事件与 footer 接线
-    render.ts          # 纯函数：数字格式化、仪表、行布局
-    render.test.ts     # render.ts 的单元测试
+package.json                     # 合集包，发布为 useful-pi-extensions
+packages/
+  statusline/                    # 发布为 @reedchan/statusline
+    package.json
+    extensions/statusline/
+      index.ts                   # pi 入口：事件与 footer 接线
+      render.ts                  # 纯函数：数字格式化、仪表、行布局
+      render.test.ts             # render.ts 的单元测试
+tools/                           # 仓库工具：文档配对、提交信息校验、发布
 ```
 
-`package.json` 声明 `"pi": { "extensions": ["./extensions"] }`，并带 `pi-package` 关键字以便被发现。
-pi 读取该清单，找到每个 `extensions/*/index.ts` 并加载——无构建、无打包。
+合集声明 `"pi": { "extensions": ["packages/*/extensions"] }`，单独包声明 `"./extensions"`。
+pi 解析该 glob，找到每个 `extensions/<name>/index.ts` 并加载——无构建、无打包。
+因此新增一个扩展就是新增一个 `packages/` 下的目录：**两个清单都不用改**，
+合集的 glob 会自动发现新包，`make publish` 也用同一套发现逻辑。
 
 ## 开发
 
@@ -77,7 +93,7 @@ make help         # 列出所有目标
 | Lint | `bun run lint`       | oxlint 类型感知模式 + `--deny-warnings`，即 **warning 也判失败**                                                                                     |
 | 类型 | `bun run typecheck`  | `--strict` 以及 `noUncheckedIndexedAccess`、`exactOptionalPropertyTypes`、`verbatimModuleSyntax`，这正是保证每个文件无需转译就能被 pi 直接加载的原因 |
 | 文档 | `bun run docs:check` | 每个 `README.md` 都有 `README_CN.md`，标题层级序列一致且语言切换链接可用                                                                             |
-| 单测 | `bun test`           | `extensions/*/` 下的单元测试                                                                                                                         |
+| 单测 | `bun test`           | `packages/*/` 下的单元测试                                                                                                                           |
 
 提交遵循 [Conventional Commits](https://www.conventionalcommits.org/)：`commit-msg` 钩子会拒绝不符合
 `type(scope): summary` 的标题，pre-commit 钩子只对暂存文件做格式化与 lint。工具链在 `package.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "A small collection of pi extensions, installed with one command — a labelled status line with context pressure, cache, cost, effort, TTFT and tokens/sec.",
   "keywords": [
     "bun",
@@ -23,9 +23,12 @@
     "type": "git",
     "url": "git+https://github.com/reedchan7/useful-pi-extensions.git"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "files": [
-    "extensions",
-    "!extensions/**/*.test.ts",
+    "packages/*/extensions/**",
+    "!packages/*/extensions/**/*.test.ts",
     "README.md",
     "README_CN.md",
     "LICENSE"
@@ -38,7 +41,7 @@
     "fmt:check": "oxfmt --check .",
     "lint": "oxlint --deny-warnings .",
     "lint:fix": "oxlint --fix .",
-    "prepublishOnly": "bun run check",
+    "publish:changed": "bun tools/publish-changed/src/index.ts",
     "test": "bun test",
     "test:changed": "git rev-parse --verify --quiet origin/main >/dev/null && bun test --changed=origin/main || bun test",
     "typecheck": "tsc -p tsconfig.json"
@@ -53,16 +56,12 @@
     "oxlint-tsgolint": "7.0.2002",
     "typescript": "7.0.2"
   },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  },
   "engines": {
     "bun": ">=1.4.0"
   },
   "pi": {
     "extensions": [
-      "./extensions"
+      "packages/*/extensions"
     ],
     "image": "https://github.com/user-attachments/assets/7ae64213-cb05-4440-835e-a633796a87f9"
   }

package/packages/statusline/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reedchan7
+
+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/{extensions → packages}/statusline/README.md

@@ -81,7 +81,11 @@ So the rate excludes prefill and time-to-first-token, which is the industry-stan
 ## Install
 
 ```sh
-pi install git:github.com/reedchan7/useful-pi-extensions
+# on its own
+pi install npm:@reedchan/statusline
+
+# or as part of the collection, which installs every extension in the repository
+pi install npm:useful-pi-extensions
 ```
 
 Then `/reload`.

package/{extensions → packages}/statusline/README_CN.md

@@ -71,7 +71,11 @@ tok/s    = usage.output / (decodeMs / 1000)
 ## 安装
 
 ```sh
-pi install git:github.com/reedchan7/useful-pi-extensions
+# 单独安装
+pi install npm:@reedchan/statusline
+
+# 或作为合集的一部分安装，会装上本仓库的全部扩展
+pi install npm:useful-pi-extensions
 ```
 
 然后 `/reload`。