@josephyoung/pi-file-reference 0.1.1 → 0.1.3

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 + tag; CI triggers on package.json change
+```
+
+- GitHub Actions workflow: `.github/workflows/publish.yml`
+- Trigger: push to main when `package.json` changes, or `workflow_dispatch`
+- Uses Node 24 (npm 11) for OIDC support — Node 22's npm 10 OIDC is broken
+- Uses npm Trusted Publishing (OIDC) — no tokens or OTP needed
+- Runs on `refs/heads/main` — npm Trusted Publisher must accept branch `main`

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Joseph Cheng
+Copyright (c) 2026 @josephyoung/pi-file-reference
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

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

@@ -122,14 +122,41 @@ 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(`[pi-file-reference] @${ref} -> ${resolvedPath} not found, skipping`);
+      results.push({ ref: cleanRef, content: fs.readFileSync(resolvedPath, "utf-8") });
     }
   }
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@josephyoung/pi-file-reference",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
-  "description": "Pi extension that resolves @filepath references in AGENTS.md and injects file content into system prompt",
+  "description": "Pi extension: resolve @filepath (files & directories) in AGENTS.md, inject into system prompt",
   "type": "module",
   "keywords": [
     "pi-package",
     "pi",
-    "extension"
+    "extension",
+    "context",
+    "file-reference"
   ],
   "homepage": "https://github.com/josephyoung/pi-file-reference#readme",
   "bugs": {