@josephyoung/pi-file-reference 0.1.0 → 0.1.2

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - package.json
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          PUBLISHED_VERSION=$(npm view @josephyoung/pi-file-reference version 2>/dev/null || echo "0.0.0")
+          if [ "$PACKAGE_VERSION" != "$PUBLISHED_VERSION" ]; then
+            npm publish --provenance --access public
+          else
+            echo "Version $PACKAGE_VERSION already published, skipping"
+          fi

package/AGENTS.md

@@ -0,0 +1,47 @@
+# pi-file-reference
+
+Pi extension that resolves `@filepath` references in AGENTS.md and injects file content into system prompt.
+
+## Structure
+
+- `extensions/index.ts` — extension entry point
+  - `session_start`: scan AGENTS.md for @refs, read files, cache in memory
+  - `before_agent_start`: inject cached file content into system prompt
+- `package.json` — pi package metadata
+
+## How it works
+
+When a user writes `@./docs/style-guide.md` in their AGENTS.md:
+
+1. The extension finds all `@` references in AGENTS.md (cwd or ~/.pi/agent/)
+2. Resolves paths (relative, absolute, ~/ expansion)
+3. If the path is a file: reads it
+   If the path is a directory: reads all immediate files (depth 1, sorted alphabetically)
+4. Injects them into the system prompt under `# Context References`
+
+## Conventions
+
+- All code and comments in English
+- AGENTS.md drives the project-level AI context
+- Match Pi's internal style for context file injection (`## @path\n\n{content}`)
+
+## Publishing
+
+After functional changes are committed and pushed, update the GitHub repo description if the feature set changed:
+
+```bash
+gh repo edit --description "Pi extension: ..."
+```
+
+Then bump version and push:
+
+```bash
+npm version patch   # bump version, creates commit + tag
+git push origin main --tags   # push to main triggers CI (package.json change)
+```
+
+- GitHub Actions workflow: `.github/workflows/publish.yml`
+- Trigger: push to main when `package.json` changes, or `workflow_dispatch`
+- CI checks if version > npm latest before publishing (idempotent)
+- Uses npm Trusted Publishing (OIDC) — no tokens or OTP needed
+- OIDC runs on `refs/heads/main` — ensure npm Trusted Publisher is configured for branch `main`

package/README.md

@@ -21,6 +21,16 @@ A [pi](https://github.com/earendil-works/pi-coding-agent) extension that resolve
 
 The `@` must be at the start of a line or preceded by whitespace.
 
+### Directory references
+
+When `@path` resolves to a directory, all immediate files (depth 1) are injected:
+
+```
+@./docs
+```
+
+Injects `@docs/style-guide.md`, `@docs/patterns.md`, etc. (sorted alphabetically). Subdirectories are skipped. Trailing `/` is stripped (`@./docs/` works the same).
+
 ## Installation
 
 ```bash

package/extensions/index.ts

@@ -1,10 +1,9 @@
-import type { ExtensionAPI, CustomEntry } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 
 const AGENTS_FILE = "AGENTS.md";
-const STORE_KEY = "agents-at-context";
 
 /**
  * Parse @filepath references from a line.
@@ -123,52 +122,65 @@ function loadRefs(cwd: string): RefContent[] {
     return true;
   });
 
-  // Read each referenced file
+  // Read each referenced file or directory
   const results: RefContent[] = [];
   for (const ref of uniqueRefs) {
-    const resolvedPath = resolveRef(ref, baseDir);
-    if (fs.existsSync(resolvedPath)) {
-      results.push({ ref, content: fs.readFileSync(resolvedPath, "utf-8") });
+    // Strip trailing slashes for consistent handling
+    const cleanRef = ref.endsWith("/") ? ref.slice(0, -1) : ref;
+    const resolvedPath = resolveRef(cleanRef, baseDir);
+
+    if (!fs.existsSync(resolvedPath)) {
+      console.warn(`[pi-file-reference] @${cleanRef} -> ${resolvedPath} not found, skipping`);
+      continue;
+    }
+
+    const stat = fs.statSync(resolvedPath);
+    if (stat.isDirectory()) {
+      // Read all files at depth 1, skip subdirectories
+      const entries = fs.readdirSync(resolvedPath, { withFileTypes: true });
+      const files = entries
+        .filter((e) => e.isFile())
+        .map((e) => e.name)
+        .sort(); // deterministic order
+
+      if (files.length === 0) {
+        console.warn(`[pi-file-reference] @${cleanRef} is an empty directory, skipping`);
+        continue;
+      }
+
+      for (const fileName of files) {
+        const filePath = path.join(resolvedPath, fileName);
+        results.push({
+          ref: `${cleanRef}/${fileName}`,
+          content: fs.readFileSync(filePath, "utf-8"),
+        });
+      }
     } else {
-      console.warn(`[agents-at-reader] @${ref} -> ${resolvedPath} not found, skipping`);
+      results.push({ ref: cleanRef, content: fs.readFileSync(resolvedPath, "utf-8") });
     }
   }
 
   return results;
 }
 
+let cachedRefs: RefContent[] = [];
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
-    // Check if custom entry already exists (e.g., after reload)
-    const entries = ctx.sessionManager.getEntries();
-    const existing = entries.find(
-      (e): e is CustomEntry<{ refs: RefContent[] }> =>
-        e.type === "custom" && e.customType === STORE_KEY,
-    );
-    if (existing) return;
-
-    const refs = loadRefs(ctx.cwd);
-    if (refs.length === 0) return;
-
-    pi.appendEntry(STORE_KEY, { refs });
+    cachedRefs = loadRefs(ctx.cwd);
   });
 
-  pi.on("before_agent_start", (event, ctx) => {
-    const entries = ctx.sessionManager.getEntries();
-    const entry = entries.find(
-      (e): e is CustomEntry<{ refs: RefContent[] }> =>
-        e.type === "custom" && e.customType === STORE_KEY,
-    );
-    if (!entry?.data?.refs?.length) return;
+  pi.on("before_agent_start", (event, _ctx) => {
+    if (!cachedRefs.length) return;
 
-    const injected = entry.data.refs
-      .map((r) => `// @${r.ref}\n${r.content}`)
+    const injected = cachedRefs
+      .map((r) => `## @${r.ref}\n\n${r.content}`)
       .join("\n\n");
 
     return {
       systemPrompt:
         event.systemPrompt +
-        `\n\n---\n// @AGENTS.md 引用文件 — 注入以下文件内容供参考\n${injected}\n---`,
+        `\n\n# Context References\n\n${injected}`,
     };
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyoung/pi-file-reference",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Pi extension that resolves @filepath references in AGENTS.md and injects file content into system prompt",
   "type": "module",

package/tsconfig.json

@@ -7,5 +7,5 @@
     "noEmit": true,
     "skipLibCheck": true
   },
-  "include": ["agents-at-reader.ts"]
+  "include": ["extensions/**/*.ts"]
 }