@josephyoung/pi-file-reference 0.1.1 → 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

@@ -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,6 +1,6 @@
 {
   "name": "@josephyoung/pi-file-reference",
-  "version": "0.1.1",
+  "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",