pi-directory-context 0.1.0

package/.docs/first-npm-release.md

@@ -0,0 +1,133 @@
+# 首个 npm 发布说明
+
+本文档描述 `pi-directory-context` 第一次发布到 npm 时的最小步骤。
+
+## 发布前检查
+
+在仓库根目录执行：
+
+```bash
+npm run prepublishOnly
+```
+
+当前会执行：
+- `npm run check:import`
+- `npm run pack:check`
+
+通过标准：
+- 扩展入口 `extensions/directory-context.ts` 可以被直接导入
+- `npm pack --dry-run` 输出中包含预期发布文件
+
+## 发布前需要你确认的事项
+
+### 1. npm 登录状态
+
+确认本机已经登录 npm：
+
+```bash
+npm whoami
+```
+
+如果未登录：
+
+```bash
+npm login
+```
+
+### 2. 包名可用性
+
+确认 `pi-directory-context` 尚未被占用：
+
+```bash
+npm view pi-directory-context name
+```
+
+如果返回 `E404`，通常表示这个包名还没有被发布。
+
+### 3. 仓库内容
+
+建议在发布前至少确认这些文件已经存在且内容正确：
+- `package.json`
+- `README.md`
+- `CHANGELOG.md`
+- `extensions/directory-context.ts`
+- `src/directory-context/index.ts`
+- `src/directory-context/context.ts`
+
+## 首次发布步骤
+
+### 1. 确认版本号
+
+当前版本是：
+
+```json
+"version": "0.1.0"
+```
+
+如果准备首次发布 `0.1.0`，保持不变即可。
+
+如果要调整版本，可修改 `package.json` 后再执行发布前检查。
+
+### 2. 本地打包预览
+
+```bash
+npm pack --dry-run
+```
+
+确认 tarball 中没有意外文件，例如：
+- `.git/`
+- `node_modules/`
+- 本地缓存文件
+- 临时测试文件
+
+### 3. 正式发布
+
+```bash
+npm publish
+```
+
+如果后续改为 scoped package，通常需要：
+
+```bash
+npm publish --access public
+```
+
+## 发布后验证
+
+### 1. npm 安装验证
+
+等待 npm 同步完成后，可以执行：
+
+```bash
+pi install npm:pi-directory-context
+```
+
+### 2. Pi 加载验证
+
+安装后重启 Pi，或执行：
+
+```text
+/reload
+```
+
+验证点：
+- Pi 能成功加载扩展
+- system prompt 中出现 `<environment_context>` 注入片段
+
+## 常见问题
+
+### 包名已被占用
+
+如果 `pi-directory-context` 已被占用，你需要：
+- 改 `package.json` 里的 `name`
+- 同步更新 `README.md` 中的安装示例
+
+### peer dependency 提示
+
+当前包把 `@earendil-works/pi-coding-agent` 放在 `peerDependencies`，这是符合 Pi package 文档约定的。只要安装环境中有 Pi，一般不需要额外处理。
+
+### 是否需要编译
+
+当前不需要。
+
+这个包采用 TypeScript 直载方案，Pi 可直接加载 `.ts` 扩展入口。只有在你后续需要额外导出普通 Node 库接口、类型产物、或更复杂的构建流程时，才建议引入 `tsc` 或其他构建链。

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-06-20
+
+### Added
+- 初始化 Git 仓库并推送到 GitHub。
+- 将单文件扩展整理为可安装的 Pi package 骨架。
+- 新增 `extensions/` 入口层与 `src/directory-context/` 实现层。
+- 新增 `package.json`、`.gitignore`、`README.md`。
+- 新增发布前校验脚本：`check:import`、`pack:check`、`prepublishOnly`。
+- 新增首个 npm 发布说明文档。
+
+### Changed
+- 根 `index.ts` 调整为兼容转发入口，实际扩展实现迁移到 `src/directory-context/index.ts`。

package/README.md

@@ -0,0 +1,152 @@
+# pi-directory-context
+
+`pi-directory-context` 是一个 Pi extension package。
+
+它会在 `before_agent_start` 阶段，把当前工作目录相关的环境上下文注入到 system prompt，帮助模型更快理解自己所处的执行环境。
+
+## 当前能力
+
+注入的信息包括：
+- `cwd`
+- `workspaceRoot`（向上查找 `.git` 时可用）
+- `currentDate`
+- `timezone`
+- `shell`
+- `operating_system`
+- `runtime`
+
+注入格式示例：
+
+```xml
+<environment_context>
+  <cwd>/path/to/project</cwd>
+  <workspace>
+    <root>/path/to/project</root>
+  </workspace>
+  <shell type="zsh">/bin/zsh</shell>
+  <current_date>2026-06-20</current_date>
+  <timezone>Asia/Shanghai</timezone>
+  <operating_system>
+    <platform>darwin</platform>
+    <arch>arm64</arch>
+    <type>Darwin</type>
+    <release>24.3.0</release>
+  </operating_system>
+  <runtime>
+    <name>Node.js</name>
+    <version>v25.0.0</version>
+  </runtime>
+</environment_context>
+```
+
+## 安装
+
+### 本地路径安装
+
+```bash
+pi install /absolute/path/to/pi-directory-context
+```
+
+或在当前目录附近：
+
+```bash
+pi install ./pi-directory-context
+```
+
+### npm 安装
+
+等你正式发布到 npm 后可用：
+
+```bash
+pi install npm:pi-directory-context
+```
+
+### 临时试用
+
+只在当前运行中加载：
+
+```bash
+pi -e ./pi-directory-context
+```
+
+## 使用
+
+安装后重新启动 Pi，或执行：
+
+```text
+/reload
+```
+
+这个包通过 `package.json` 里的 `pi.extensions` 声明扩展入口：
+
+- `extensions/directory-context.ts`
+
+Pi 会加载该入口，并注册环境上下文注入逻辑。
+
+## 开发
+
+当前采用 TypeScript 直载方案，不引入编译产物，便于快速迭代：
+
+```bash
+npm run check:import
+npm run pack:check
+```
+
+这两个命令分别用于：
+- 验证扩展入口可以被 Node 的 TypeScript 直载能力导入
+- 预览 npm 打包时会包含哪些文件
+
+## 首次发布
+
+如果这是你第一次把它发布到 npm，建议按下面顺序执行：
+
+```bash
+npm whoami
+npm run prepublishOnly
+npm publish
+```
+
+如果你后续改用 scoped package，例如 `@your-scope/pi-directory-context`，通常需要：
+
+```bash
+npm publish --access public
+```
+
+更完整的首次发布步骤见：
+- `.docs/first-npm-release.md`
+
+## 目录结构
+
+```text
+pi-directory-context/
+├── extensions/
+│   └── directory-context.ts
+├── src/
+│   └── directory-context/
+│       ├── context.ts
+│       └── index.ts
+├── index.ts
+├── package.json
+└── README.md
+```
+
+说明：
+- `extensions/` 是 Pi 发现和加载的扩展入口层
+- `src/` 是内部实现层
+- 根 `index.ts` 当前保留为兼容入口，便于平滑过渡
+
+## 面向后续扩展库演进
+
+你当前目标是先做成“可安装的单扩展包”，后续再演进为“多扩展库”。
+
+为了减少后续搬迁成本，这个仓库已经按“入口层 + 实现层”拆开。后面如果要增加新的扩展，建议继续按下面模式扩展：
+
+```text
+extensions/
+  another-extension.ts
+src/
+  another-extension/
+    index.ts
+```
+
+这样未来只需要在 `package.json` 的 `pi.extensions` 中继续追加入口即可。

package/extensions/directory-context.ts

@@ -0,0 +1 @@
+export { default } from "../src/directory-context/index.ts";

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/directory-context/index.ts";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pi-directory-context",
+  "version": "0.1.0",
+  "description": "Pi extension package that injects working-directory environment context into the system prompt.",
+  "author": "rao",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MuJianxuan/pi-directory-context.git"
+  },
+  "homepage": "https://github.com/MuJianxuan/pi-directory-context#readme",
+  "bugs": {
+    "url": "https://github.com/MuJianxuan/pi-directory-context/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "context",
+    "directory"
+  ],
+  "files": [
+    "extensions/",
+    "src/",
+    "index.ts",
+    "README.md",
+    "CHANGELOG.md",
+    ".docs/"
+  ],
+  "scripts": {
+    "check:import": "node --experimental-strip-types --input-type=module -e \"import('./extensions/directory-context.ts')\"",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run check:import && npm run pack:check"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/directory-context.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.79.8"
+  }
+}

package/src/directory-context/context.ts

@@ -0,0 +1,143 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface EnvironmentContext {
+  cwd: string;
+  workspaceRoot?: string;
+  currentDate: string;
+  timezone: string;
+  shell: {
+    type: string;
+    path: string;
+  };
+  os: {
+    platform: string;
+    arch: string;
+    release: string;
+    type: string;
+  };
+  runtime: {
+    name: string;
+    version: string;
+  };
+}
+
+export async function collectEnvironmentContext(
+  cwd: string,
+): Promise<EnvironmentContext> {
+  const context: EnvironmentContext = {
+    cwd,
+    currentDate: new Date().toISOString().split("T")[0],
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    shell: detectShell(),
+    os: collectOsInfo(),
+    runtime: detectRuntime(),
+  };
+
+  context.workspaceRoot = findWorkspaceRoot(cwd);
+
+  return context;
+}
+
+function detectShell(): { type: string; path: string } {
+  const shellPath = process.env.SHELL || "";
+  const shellType = path.basename(shellPath) || "unknown";
+
+  return {
+    type: shellType,
+    path: shellPath,
+  };
+}
+
+function collectOsInfo() {
+  return {
+    platform: os.platform(),
+    arch: os.arch(),
+    release: os.release(),
+    type: os.type(),
+  };
+}
+
+function detectRuntime(): { name: string; version: string } {
+  if (typeof Bun !== "undefined") {
+    return {
+      name: "Bun",
+      version: Bun.version || "unknown",
+    };
+  }
+
+  return {
+    name: "Node.js",
+    version: process.version,
+  };
+}
+
+function findWorkspaceRoot(startDir: string): string | undefined {
+  let currentDir = startDir;
+
+  while (true) {
+    const gitPath = path.join(currentDir, ".git");
+
+    try {
+      if (fs.existsSync(gitPath)) {
+        return currentDir;
+      }
+    } catch {
+      // Ignore permission errors and continue scanning upward.
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+
+    currentDir = parentDir;
+  }
+
+  return undefined;
+}
+
+export function buildContextXml(context: EnvironmentContext): string {
+  const lines: string[] = [];
+
+  lines.push("<environment_context>");
+  lines.push(`  <cwd>${escapeXml(context.cwd)}</cwd>`);
+
+  if (context.workspaceRoot) {
+    lines.push("  <workspace>");
+    lines.push(`    <root>${escapeXml(context.workspaceRoot)}</root>`);
+    lines.push("  </workspace>");
+  }
+
+  lines.push(
+    `  <shell type="${escapeXml(context.shell.type)}">${escapeXml(context.shell.path)}</shell>`,
+  );
+  lines.push(`  <current_date>${context.currentDate}</current_date>`);
+  lines.push(`  <timezone>${context.timezone}</timezone>`);
+
+  lines.push("  <operating_system>");
+  lines.push(`    <platform>${context.os.platform}</platform>`);
+  lines.push(`    <arch>${context.os.arch}</arch>`);
+  lines.push(`    <type>${escapeXml(context.os.type)}</type>`);
+  lines.push(`    <release>${escapeXml(context.os.release)}</release>`);
+  lines.push("  </operating_system>");
+
+  lines.push("  <runtime>");
+  lines.push(`    <name>${context.runtime.name}</name>`);
+  lines.push(`    <version>${context.runtime.version}</version>`);
+  lines.push("  </runtime>");
+
+  lines.push("</environment_context>");
+
+  return lines.join("\n");
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/directory-context/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  buildContextXml,
+  collectEnvironmentContext,
+} from "./context.ts";
+
+export default function directoryContextExtension(pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (event, ctx) => {
+    const context = await collectEnvironmentContext(ctx.cwd);
+    const contextXml = buildContextXml(context);
+    const enhancedPrompt = `${event.systemPrompt}\n\n${contextXml}`;
+
+    return {
+      systemPrompt: enhancedPrompt,
+    };
+  });
+}