@dlacaille/opencode-copilot-instructions 0.1.0 → 0.3.0

package/README.md

@@ -35,9 +35,9 @@ Always use explicit return types.
 
 When the `read`, `edit`, or `write` tools touch a matching file, the instructions are appended to the tool result. Each file is added once per session, and again after the session is compacted.
 
-`applyTo` accepts a comma-separated string or a YAML list of [picomatch](https://github.com/micromatch/picomatch) globs, relative to the project directory.
+`applyTo` accepts a comma-separated string or a YAML list of [picomatch](https://github.com/micromatch/picomatch) globs, relative to the git root.
 
-Instructions are loaded when the plugin starts. Restart OpenCode after changing them.
+Instructions are read from the `.github` folder at the git root of each session's directory (or the directory itself outside a git repository). They are reloaded on every use, so edits apply without restarting OpenCode.
 
 ## Development
 

package/index.ts

@@ -1 +1 @@
-export { default } from "./src/index"
+export { default } from "./src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dlacaille/opencode-copilot-instructions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "OpenCode plugin that loads GitHub Copilot custom instruction files",
   "type": "module",
   "license": "MIT",
@@ -22,7 +22,9 @@
   ],
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write"
   },
   "dependencies": {
     "front-matter": "^4.0.2",
@@ -32,6 +34,7 @@
     "@opencode/plugin": ">=2.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.5.14",
     "@opencode/plugin": "^2.0.15",
     "@types/node": "^22.0.0",
     "@types/picomatch": "^4.0.0",

package/src/frontmatter.ts

@@ -1,38 +1,38 @@
-import * as frontMatterModule from "front-matter"
-
-const fm = (frontMatterModule as any).default ?? frontMatterModule
+import fm from "front-matter";
 
 export interface Frontmatter {
-  applyTo?: string | string[]
+  applyTo?: string | string[];
 }
 
 export interface ParsedFrontmatter {
-  frontmatter: Frontmatter
-  body: string
+  frontmatter: Frontmatter;
+  body: string;
 }
 
 export function parseFrontmatter(content: string): ParsedFrontmatter {
-  const normalized = content.replace(/\r\n/g, "\n")
+  const normalized = content.replace(/\r\n/g, "\n");
 
   if (!fm.test(normalized)) {
-    return { frontmatter: {}, body: content }
+    return { frontmatter: {}, body: content };
   }
 
   try {
-    const parsed = fm(normalized)
-    const attrs = parsed.attributes as Record<string, unknown>
-    const result: Frontmatter = {}
+    const parsed = fm(normalized);
+    const attrs = parsed.attributes as Record<string, unknown>;
+    const result: Frontmatter = {};
 
     if (attrs.applyTo !== undefined) {
       if (typeof attrs.applyTo === "string") {
-        result.applyTo = attrs.applyTo
+        result.applyTo = attrs.applyTo;
       } else if (Array.isArray(attrs.applyTo)) {
-        result.applyTo = attrs.applyTo.filter((item): item is string => typeof item === "string")
+        result.applyTo = attrs.applyTo.filter(
+          (item): item is string => typeof item === "string",
+        );
       }
     }
 
-    return { frontmatter: result, body: parsed.body }
+    return { frontmatter: result, body: parsed.body };
   } catch {
-    return { frontmatter: {}, body: content }
+    return { frontmatter: {}, body: content };
   }
 }

package/src/index.ts

@@ -1,95 +1,141 @@
-import * as path from "node:path"
-import { Plugin } from "@opencode/plugin"
-import { loadRepoInstructions, loadPathInstructions } from "./loader"
-import { SessionState } from "./session-state"
-
-const FILE_TOOLS = new Set(["read", "edit", "write"])
+import * as path from "node:path";
+import { Plugin } from "@opencode/plugin";
+import {
+  findRepoRoot,
+  loadPathInstructions,
+  loadRepoInstructions,
+} from "./loader";
+import { SessionState } from "./session-state";
+
+const FILE_TOOLS = new Set(["read", "edit", "write"]);
+
+/** Path relative to the repo root, or null when the file is outside it. */
+function getRepoRelativePath(
+  repoRoot: string,
+  sessionDirectory: string,
+  filePath: string,
+): string | null {
+  const relative = path.relative(
+    repoRoot,
+    path.resolve(sessionDirectory, filePath),
+  );
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  )
+    return null;
+  return relative;
+}
 
-function getRelativePath(directory: string, filePath: string): string {
-  const normalizedDir = directory.endsWith("/") ? directory.slice(0, -1) : directory
-  if (!path.isAbsolute(filePath)) return filePath
-  return path.relative(normalizedDir, filePath)
+function appendInstructions<Content>(
+  result: { content?: string | ReadonlyArray<Content>; output?: unknown },
+  text: string,
+): string | ReadonlyArray<Content | { type: "text"; text: string }> {
+  const { content, output } = result;
+  if (Array.isArray(content)) return [...content, { type: "text", text }];
+  // Without content, the model would otherwise see only the output, so keep it in the text.
+  const existing =
+    typeof content === "string"
+      ? content
+      : output === undefined
+        ? ""
+        : typeof output === "string"
+          ? output
+          : JSON.stringify(output, null, 2);
+  return existing ? `${existing}\n\n${text}` : text;
 }
 
 export default Plugin.define({
   id: "copilot-instructions",
   async setup(ctx) {
-    const directory = ctx.location.directory
-    const repoInstructions = loadRepoInstructions(directory)
-    const pathInstructions = loadPathInstructions(directory)
-
-    if (repoInstructions) {
-      console.log("[copilot-instructions] Loaded repo instructions from .github/copilot-instructions.md")
-    }
-    for (const instruction of pathInstructions) {
-      console.log(`[copilot-instructions] Loaded path instructions from ${path.basename(instruction.file)}`)
-    }
-    if (!repoInstructions && pathInstructions.length === 0) {
-      console.log("[copilot-instructions] No Copilot instructions found")
-    }
-
-    const state = new SessionState()
-
-    const injectRepoInstructions = (event: { system: Array<{ type: string; text: string }> }) => {
-      if (!repoInstructions) return
+    const state = new SessionState();
+
+    const getSessionDirectory = async (
+      sessionID: string,
+    ): Promise<string | null> => {
+      try {
+        const session = await ctx.session.get({ sessionID });
+        return session.location.directory;
+      } catch {
+        return null;
+      }
+    };
+
+    const injectRepoInstructions = async (event: {
+      sessionID: string;
+      system: Array<{ type: string; text: string }>;
+    }) => {
+      const directory = await getSessionDirectory(event.sessionID);
+      if (!directory) return;
+      const repoInstructions = loadRepoInstructions(findRepoRoot(directory));
+      if (!repoInstructions) return;
       event.system.push({
         type: "text",
         text: `<copilot-instruction:copilot-instructions.md>\n${repoInstructions.trimEnd()}\n</copilot-instruction:copilot-instructions.md>`,
-      })
-    }
+      });
+    };
 
     // Inject repo-wide instructions into every model call so they survive compaction.
-    await ctx.session.hook("context", injectRepoInstructions)
-    await ctx.session.hook("compaction", injectRepoInstructions)
+    await ctx.session.hook("context", injectRepoInstructions);
+    await ctx.session.hook("compaction", injectRepoInstructions);
 
-    await ctx.tool.hook("execute.before", (event) => {
-      if (!FILE_TOOLS.has(event.tool)) return
+    await ctx.tool.hook("execute.before", async (event) => {
+      if (!FILE_TOOLS.has(event.tool)) return;
 
-      const input = event.input as { path?: unknown }
-      const filePath = input?.path
-      if (!filePath || typeof filePath !== "string") return
+      const input = event.input as { path?: unknown };
+      const filePath = input?.path;
+      if (!filePath || typeof filePath !== "string") return;
 
-      const relativePath = getRelativePath(directory, filePath)
-      const matching = pathInstructions.filter((instruction) => {
-        if (state.isFileInjected(event.sessionID, instruction.file)) return false
-        return instruction.matcher(relativePath)
-      })
-      if (matching.length === 0) return
+      const directory = await getSessionDirectory(event.sessionID);
+      if (!directory) return;
+      const repoRoot = findRepoRoot(directory);
+      const relativePath = getRepoRelativePath(repoRoot, directory, filePath);
+      if (relativePath === null) return;
 
-      for (const instruction of matching) state.markFileInjected(event.sessionID, instruction.file)
+      const matching = loadPathInstructions(repoRoot).filter((instruction) => {
+        if (state.isFileInjected(event.sessionID, instruction.file))
+          return false;
+        return instruction.matcher(relativePath);
+      });
+      if (matching.length === 0) return;
+
+      for (const instruction of matching)
+        state.markFileInjected(event.sessionID, instruction.file);
 
       const text = matching
         .map((instruction) => {
-          const filename = path.basename(instruction.file)
-          const patterns = instruction.applyTo.join(", ")
-          return `<copilot-instruction:${filename}>\n## Path-Specific Instructions (applies to: ${patterns})\n\n${instruction.content.trimEnd()}\n</copilot-instruction:${filename}>`
+          const filename = path.basename(instruction.file);
+          const patterns = instruction.applyTo.join(", ");
+          return `<copilot-instruction:${filename}>\n## Path-Specific Instructions (applies to: ${patterns})\n\n${instruction.content.trimEnd()}\n</copilot-instruction:${filename}>`;
         })
-        .join("\n\n")
+        .join("\n\n");
 
-      state.setPending(event.id, text)
-    })
+      state.setPending(event.id, text);
+    });
 
     await ctx.tool.hook("execute.after", (event) => {
-      const text = state.consumePending(event.id)
-      if (!text) return
-      if (event.status !== "completed") return
+      const text = state.consumePending(event.id);
+      if (!text) return;
+      if (event.status !== "completed") return;
 
-      const existing = typeof event.result.content === "string" ? event.result.content : ""
       event.result = {
         ...event.result,
-        content: existing ? `${existing}\n\n${text}` : text,
-      }
-    })
+        content: appendInstructions(event.result, text),
+      };
+    });
 
-    const controller = new AbortController()
+    const controller = new AbortController();
     void (async () => {
-      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+      for await (const event of ctx.event.subscribe({
+        signal: controller.signal,
+      })) {
         if (event.type === "session.compaction.ended") {
-          state.clearSession(event.data.sessionID)
+          state.clearSession(event.data.sessionID);
         }
       }
-    })()
+    })();
 
-    return () => controller.abort()
+    return () => controller.abort();
   },
-})
+});

package/src/loader.ts

@@ -1,57 +1,68 @@
-import * as fs from "node:fs"
-import * as path from "node:path"
-import { parseFrontmatter } from "./frontmatter"
-import { createMatcher, normalizePatterns, type Matcher } from "./matcher"
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseFrontmatter } from "./frontmatter";
+import { createMatcher, type Matcher, normalizePatterns } from "./matcher";
 
 export interface PathInstruction {
-  file: string
-  applyTo: string[]
-  content: string
-  matcher: Matcher
+  file: string;
+  applyTo: string[];
+  content: string;
+  matcher: Matcher;
+}
+
+/** Find the nearest ancestor containing `.git`, or return the directory itself. */
+export function findRepoRoot(directory: string): string {
+  let current = path.resolve(directory);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(directory);
+    current = parent;
+  }
 }
 
 /** Load repo-wide instructions from .github/copilot-instructions.md */
 export function loadRepoInstructions(directory: string): string | null {
-  const filePath = path.join(directory, ".github", "copilot-instructions.md")
+  const filePath = path.join(directory, ".github", "copilot-instructions.md");
   try {
-    return fs.readFileSync(filePath, "utf-8")
+    return fs.readFileSync(filePath, "utf-8");
   } catch {
-    return null
+    return null;
   }
 }
 
 /** Load path-specific instructions from .github/instructions/*.instructions.md */
 export function loadPathInstructions(directory: string): PathInstruction[] {
-  const instructionsDir = path.join(directory, ".github", "instructions")
-  let files: string[]
+  const instructionsDir = path.join(directory, ".github", "instructions");
+  let files: string[];
   try {
-    files = fs.readdirSync(instructionsDir)
+    files = fs.readdirSync(instructionsDir);
   } catch {
-    return []
+    return [];
   }
 
-  const result: PathInstruction[] = []
+  const result: PathInstruction[] = [];
   for (const filename of files) {
-    if (!filename.endsWith(".instructions.md")) continue
+    if (!filename.endsWith(".instructions.md")) continue;
 
-    const filePath = path.join(instructionsDir, filename)
-    let content: string
+    const filePath = path.join(instructionsDir, filename);
+    let content: string;
     try {
-      content = fs.readFileSync(filePath, "utf-8")
+      content = fs.readFileSync(filePath, "utf-8");
     } catch {
-      continue
+      continue;
     }
 
-    const parsed = parseFrontmatter(content)
-    const patterns = normalizePatterns(parsed.frontmatter.applyTo)
-    if (patterns.length === 0) continue
+    const parsed = parseFrontmatter(content);
+    const patterns = normalizePatterns(parsed.frontmatter.applyTo);
+    if (patterns.length === 0) continue;
 
     result.push({
       file: filePath,
       applyTo: patterns,
       content: parsed.body,
       matcher: createMatcher(patterns),
-    })
+    });
   }
-  return result
+  return result;
 }

package/src/matcher.ts

@@ -1,18 +1,20 @@
-import picomatch from "picomatch"
+import picomatch from "picomatch";
 
-export type Matcher = (path: string) => boolean
+export type Matcher = (path: string) => boolean;
 
 export function createMatcher(patterns: string[]): Matcher {
-  if (patterns.length === 0) return () => false
-  const isMatch = picomatch(patterns)
-  return (path) => isMatch(path)
+  if (patterns.length === 0) return () => false;
+  const isMatch = picomatch(patterns);
+  return (path) => isMatch(path);
 }
 
-export function normalizePatterns(applyTo: string | string[] | undefined): string[] {
-  if (applyTo === undefined) return []
-  if (Array.isArray(applyTo)) return applyTo
+export function normalizePatterns(
+  applyTo: string | string[] | undefined,
+): string[] {
+  if (applyTo === undefined) return [];
+  if (Array.isArray(applyTo)) return applyTo;
   return applyTo
     .split(",")
     .map((pattern) => pattern.trim())
-    .filter((pattern) => pattern.length > 0)
+    .filter((pattern) => pattern.length > 0);
 }

package/src/session-state.ts

@@ -5,33 +5,33 @@
  * pending instructions keyed by tool call ID.
  */
 export class SessionState {
-  private injectedPerSession = new Map<string, Set<string>>()
-  private pendingInstructions = new Map<string, string>()
+  private injectedPerSession = new Map<string, Set<string>>();
+  private pendingInstructions = new Map<string, string>();
 
   isFileInjected(sessionId: string, file: string): boolean {
-    return this.injectedPerSession.get(sessionId)?.has(file) ?? false
+    return this.injectedPerSession.get(sessionId)?.has(file) ?? false;
   }
 
   markFileInjected(sessionId: string, file: string): void {
-    let files = this.injectedPerSession.get(sessionId)
+    let files = this.injectedPerSession.get(sessionId);
     if (!files) {
-      files = new Set()
-      this.injectedPerSession.set(sessionId, files)
+      files = new Set();
+      this.injectedPerSession.set(sessionId, files);
     }
-    files.add(file)
+    files.add(file);
   }
 
   clearSession(sessionId: string): void {
-    this.injectedPerSession.delete(sessionId)
+    this.injectedPerSession.delete(sessionId);
   }
 
   setPending(callId: string, text: string): void {
-    this.pendingInstructions.set(callId, text)
+    this.pendingInstructions.set(callId, text);
   }
 
   consumePending(callId: string): string | undefined {
-    const text = this.pendingInstructions.get(callId)
-    this.pendingInstructions.delete(callId)
-    return text
+    const text = this.pendingInstructions.get(callId);
+    this.pendingInstructions.delete(callId);
+    return text;
   }
 }