@b-apm/integration-copilot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sdju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -0,0 +1,66 @@
+# @b-apm/integration-copilot
+
+> **UNSTABLE:** Early public release. APIs and on-disk layouts may change without a major bump. Not production-ready.
+
+GitHub Copilot **runtime** host for bapm (project-scope file primitives + home MCP translate).
+
+## Opt-in load
+
+```bash
+npm i -D @b-apm/integration-copilot
+```
+
+```yaml
+targets:
+  copilot: "@b-apm/integration-copilot"
+active:
+  - copilot
+```
+
+```bash
+bapm install --target copilot
+bapm compile --target copilot
+```
+
+## Detection vs forced target
+
+| Mode                            | When active                                                                                                 | Creates roots?                                      |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **Auto-detect**                 | Any whitelist signal under `.github/` (`copilot-instructions.md` or instructions/agents/prompts/hooks dirs) | Only when materialize / configure runs after detect |
+| **Forced** (`--target copilot`) | Explicit forced target id, even if detect is false                                                          | MAY `mkdir` `.github/` / `.agents/` as needed       |
+
+Auto-detect without a whitelist signal MUST NOT create roots solely for detection.
+
+## Deploy roots
+
+- `.github` — instructions, prompts, agents, hooks, compile output, ownership sidecar
+- `.agents` — portable skills under `.agents/skills/<name>/`
+
+Home MCP (`~/.copilot/mcp-config.json`, override with `COPILOT_HOME`) is outside project deploy roots.
+
+## Materialize routing
+
+| Primitive type   | Destination                                                                                         |
+| ---------------- | --------------------------------------------------------------------------------------------------- |
+| instruction      | `.github/instructions/<name>.instructions.md` (preserve `applyTo` / Copilot FM)                     |
+| command / prompt | `.github/prompts/<name>.prompt.md` (never `.github/commands/`)                                      |
+| agent            | `.github/agents/<name>.agent.md`                                                                    |
+| skill            | `.agents/skills/<name>/` (never `.github/skills/`)                                                  |
+| hook             | per-file `.github/hooks/<pkg>-<stem>.json` + scripts under `.github/hooks/scripts/<pkg>/` + sidecar |
+
+MCP is **not** written by materialize — only via `configureMcp`.
+
+## MCP (translate)
+
+- Config: `~/.copilot/mcp-config.json` (`mcpServers`)
+- `mcpEnvMode: "translate"` — APM `${VAR}` / `${env:VAR}` / `<VAR>` stay as runtime `${VAR}` placeholders
+- Install skips bake for this host; unrelated servers and top-level keys are preserved
+- Never writes project `.vscode/mcp.json`
+
+## Compile
+
+Thin emitter → `.github/copilot-instructions.md`. Instruction primitives already deployed under `.github/instructions/` are omitted from the compile body. Honors `write` vs validate/preview.
+
+## Exports
+
+- `createCopilotIntegration` / `createIntegration` — runtime factory (`id: "copilot"`)

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import { BapmIntegration } from "@b-apm/integration-api";
+//#region src/createCopilotIntegration.d.ts
+/**
+ * Create the GitHub Copilot runtime target.
+ * Detect: APM SIGNAL_WHITELIST under `.github/` (any one signal; no mkdir).
+ * Materialize: instructions/prompts/agents/hooks under `.github/`, skills under `.agents/skills/`.
+ * MCP: home `~/.copilot/mcp-config.json` (`COPILOT_HOME`) with translate placeholders.
+ * Compile: thin `.github/copilot-instructions.md`, omitting instruction primitives.
+ */
+declare function createCopilotIntegration(options?: {
+  id?: string;
+  deployRoots?: string[];
+}): BapmIntegration;
+/** Normalize hook event names to camelCase (`session_start` / `SessionStart` → `sessionStart`). */
+declare function toCamelCaseEvent(event: string): string;
+//#endregion
+export { createCopilotIntegration, createCopilotIntegration as createIntegration, toCamelCaseEvent };

package/dist/index.mjs

@@ -0,0 +1,368 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { assertUnderDeployRoots, compileMarkdownReport, copyHookScript, materializeSkill, primitivesList, primitivesMaterialize, readHookOwnershipSidecar, readPrimitiveContent, removeOwnedHookArtifacts, renderPrimitivesMarkdown, sanitizeName, writeDeployedFile, writeHookOwnershipSidecar } from "@b-apm/integration-api";
+//#region src/createCopilotIntegration.ts
+const DEFAULT_DEPLOY_ROOTS = [".github", ".agents"];
+const HOOKS_OWNERSHIP_REL = ".github/bapm-hooks.json";
+const COMPILE_DEFAULT = ".github/copilot-instructions.md";
+const DETECT_DIRS = [
+	".github/instructions",
+	".github/agents",
+	".github/prompts",
+	".github/hooks"
+];
+/**
+* Create the GitHub Copilot runtime target.
+* Detect: APM SIGNAL_WHITELIST under `.github/` (any one signal; no mkdir).
+* Materialize: instructions/prompts/agents/hooks under `.github/`, skills under `.agents/skills/`.
+* MCP: home `~/.copilot/mcp-config.json` (`COPILOT_HOME`) with translate placeholders.
+* Compile: thin `.github/copilot-instructions.md`, omitting instruction primitives.
+*/
+function createCopilotIntegration(options) {
+	const id = options?.id ?? "copilot";
+	const deployRoots = [...options?.deployRoots ?? DEFAULT_DEPLOY_ROOTS];
+	return {
+		id,
+		deployRoots,
+		mcpEnvMode: "translate",
+		detect: ({ cwd }) => detectCopilot(cwd),
+		getDeployRoots: () => [...deployRoots],
+		async compile(primitives, context) {
+			const content = renderPrimitivesMarkdown({
+				primitives: primitivesList(primitives),
+				title: "# GitHub Copilot instructions",
+				filter: (p) => !/instruction/i.test(String(p.type ?? ""))
+			});
+			return compileMarkdownReport({
+				cwd: context.cwd,
+				outputFile: context.outputFile ?? COMPILE_DEFAULT,
+				write: context.write,
+				content,
+				outsideCwdMessage: "Copilot compile output must be a cwd-relative file path"
+			});
+		},
+		async materialize(primitives, ctx) {
+			const cwd = resolve(ctx?.cwd ?? process.cwd());
+			const roots = ctx?.deployRoots?.length ? [...ctx.deployRoots] : deployRoots;
+			const deployedFiles = [];
+			const diagnostics = [];
+			const hookPrimitives = [];
+			await primitivesMaterialize(primitives, {
+				skill(p, { name }) {
+					deployedFiles.push(...materializeSkill({
+						primitive: p,
+						cwd,
+						deployRoots: roots,
+						destDir: join(".agents", "skills", name)
+					}));
+				},
+				instruction(p, { name }) {
+					deployedFiles.push(writeDeployedFile({
+						cwd,
+						deployRoots: roots,
+						destRel: join(".github", "instructions", `${name}.instructions.md`),
+						content: readPrimitiveContent(p),
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					}));
+				},
+				agent(p, { name }) {
+					deployedFiles.push(writeDeployedFile({
+						cwd,
+						deployRoots: roots,
+						destRel: join(".github", "agents", `${name}.agent.md`),
+						content: readPrimitiveContent(p),
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					}));
+				},
+				command(p, { name }) {
+					materializePromptLike(p, name, cwd, roots, deployedFiles);
+				},
+				hook(p) {
+					hookPrimitives.push(p);
+				},
+				unknown(p, { name, type }) {
+					if (/prompt/.test(type)) materializePromptLike(p, name, cwd, roots, deployedFiles);
+				}
+			});
+			if (hookPrimitives.length > 0) {
+				const hookDeployed = materializeCopilotHooks({
+					cwd,
+					roots,
+					hooks: hookPrimitives
+				});
+				deployedFiles.push(...hookDeployed.deployedFiles);
+				diagnostics.push(...hookDeployed.diagnostics);
+			}
+			return {
+				targetId: id,
+				deployedFiles,
+				...diagnostics.length > 0 ? { diagnostics } : {}
+			};
+		},
+		async configureMcp(servers, ctx) {
+			return writeCopilotMcpConfig(servers, {
+				cwd: resolve(ctx?.cwd ?? process.cwd()),
+				deployRoots: ctx?.deployRoots?.length ? [...ctx.deployRoots] : deployRoots,
+				targetId: ctx?.targetId ?? id
+			});
+		}
+	};
+}
+function detectCopilot(cwd) {
+	const instructions = join(cwd, ".github", "copilot-instructions.md");
+	if (existsSync(instructions) && statSync(instructions).isFile()) return true;
+	for (const rel of DETECT_DIRS) {
+		const abs = join(cwd, rel);
+		if (existsSync(abs) && statSync(abs).isDirectory()) return true;
+	}
+	return false;
+}
+function materializePromptLike(p, name, cwd, roots, deployedFiles) {
+	deployedFiles.push(writeDeployedFile({
+		cwd,
+		deployRoots: roots,
+		destRel: join(".github", "prompts", `${name}.prompt.md`),
+		content: readPrimitiveContent(p),
+		primitive: {
+			name: String(p.name),
+			packageName: p.packageName
+		}
+	}));
+}
+function resolveCopilotHome() {
+	const override = process.env.COPILOT_HOME?.trim();
+	if (override) return resolve(override);
+	return join(homedir(), ".copilot");
+}
+function writeCopilotMcpConfig(servers, ctx) {
+	const home = resolveCopilotHome();
+	mkdirSync(home, { recursive: true });
+	const destFile = join(home, "mcp-config.json");
+	const existingDoc = readExistingMcpDoc(destFile);
+	const existingServers = existingDoc.mcpServers && typeof existingDoc.mcpServers === "object" ? { ...existingDoc.mcpServers } : {};
+	const { entries: incoming, diagnostics } = normalizeServerEntries(servers);
+	const nextServers = { ...existingServers };
+	const writtenNames = [];
+	for (const [name, entry] of Object.entries(incoming)) {
+		const prior = existingServers[name];
+		const merged = prior && typeof prior === "object" ? {
+			...prior,
+			...entry
+		} : { ...entry };
+		delete merged.format;
+		delete merged.packageName;
+		delete merged.registry;
+		nextServers[name] = merged;
+		writtenNames.push(name);
+	}
+	const doc = {
+		...existingDoc,
+		mcpServers: nextServers
+	};
+	writeFileSync(destFile, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+	return {
+		targetId: ctx.targetId,
+		configPath: destFile,
+		servers: writtenNames,
+		deployedFiles: [],
+		diagnostics
+	};
+}
+function readExistingMcpDoc(path) {
+	if (!existsSync(path)) return {};
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		return raw && typeof raw === "object" && !Array.isArray(raw) ? { ...raw } : {};
+	} catch {
+		return {};
+	}
+}
+function normalizeServerEntries(servers) {
+	const out = {};
+	const diagnostics = [];
+	const list = Array.isArray(servers) ? servers : Object.entries(servers).map(([name, value]) => ({
+		...value,
+		name: value.name ?? name
+	}));
+	for (const server of list) {
+		const name = String(server.name ?? "").trim();
+		if (!name) continue;
+		out[name] = toCopilotServerEntry(server);
+	}
+	return {
+		entries: out,
+		diagnostics
+	};
+}
+function translateEnvPlaceholders(env) {
+	const out = {};
+	for (const [key, raw] of Object.entries(env)) {
+		if (typeof raw !== "string") {
+			out[key] = String(raw);
+			continue;
+		}
+		out[key] = raw.replace(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, "${$1}").replace(/<([A-Z_][A-Z0-9_]*)>/g, "${$1}");
+	}
+	return out;
+}
+function toCopilotServerEntry(server) {
+	const transport = String(server.transport ?? server.type ?? "").toLowerCase();
+	const entry = {};
+	if (transport === "http" || transport === "sse" || typeof server.url === "string") {
+		if (server.url) entry.url = server.url;
+		if (transport) entry.type = transport === "sse" ? "sse" : "http";
+	} else {
+		if (server.command) entry.command = String(server.command);
+		if (Array.isArray(server.args)) entry.args = server.args;
+		entry.type = "stdio";
+	}
+	if (server.env && typeof server.env === "object") entry.env = translateEnvPlaceholders(server.env);
+	for (const [key, value] of Object.entries(server)) {
+		if ([
+			"name",
+			"transport",
+			"type",
+			"command",
+			"args",
+			"url",
+			"env",
+			"packageName",
+			"registry",
+			"format",
+			"cwd"
+		].includes(key)) continue;
+		if (value !== void 0) entry[key] = value;
+	}
+	return entry;
+}
+/** Normalize hook event names to camelCase (`session_start` / `SessionStart` → `sessionStart`). */
+function toCamelCaseEvent(event) {
+	const trimmed = String(event ?? "").trim();
+	if (!trimmed) return trimmed;
+	if (trimmed.includes("_") || trimmed.includes("-")) return trimmed.split(/[_-]+/).filter(Boolean).map((part, index) => {
+		const lower = part.toLowerCase();
+		if (index === 0) return lower;
+		return lower.charAt(0).toUpperCase() + lower.slice(1);
+	}).join("");
+	return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
+}
+function packageKey(p) {
+	if (typeof p.packageName === "string" && p.packageName.trim()) return sanitizeName(p.packageName);
+	const source = String(p.source ?? "");
+	if (source.startsWith("dependency:")) return sanitizeName(source.slice(11));
+	return "local";
+}
+function materializeCopilotHooks(args) {
+	const { cwd, roots, hooks } = args;
+	const deployedFiles = [];
+	const diagnostics = [];
+	const ownershipPath = join(cwd, HOOKS_OWNERSHIP_REL);
+	assertUnderDeployRoots(cwd, ownershipPath, roots);
+	mkdirSync(join(cwd, ".github", "hooks"), { recursive: true });
+	const ownership = readHookOwnershipSidecar(ownershipPath);
+	removeOwnedHookArtifacts(cwd, ownership);
+	const nextOwned = {};
+	for (const p of hooks) {
+		const stem = sanitizeName(String(p.name));
+		const pkg = packageKey(p);
+		const hookRel = `.github/hooks/${pkg}-${stem}.json`;
+		const hookAbs = join(cwd, hookRel);
+		assertUnderDeployRoots(cwd, hookAbs, roots);
+		const srcPath = p.path ? resolve(p.path) : void 0;
+		if (!srcPath || !existsSync(srcPath) || !statSync(srcPath).isFile()) {
+			diagnostics.push({
+				code: "COPILOT_HOOK_SOURCE_MISSING",
+				message: `Hook primitive "${p.name}" has no readable source JSON`,
+				primitive: String(p.name)
+			});
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(srcPath, "utf8"));
+		} catch (cause) {
+			diagnostics.push({
+				code: "COPILOT_HOOK_JSON_INVALID",
+				message: `Hook "${p.name}" JSON is invalid: ${cause instanceof Error ? cause.message : String(cause)}`,
+				primitive: String(p.name)
+			});
+			continue;
+		}
+		const sourceHooks = parsed.hooks && typeof parsed.hooks === "object" ? parsed.hooks : {};
+		const outHooks = {};
+		const scripts = [];
+		for (const [event, entries] of Object.entries(sourceHooks)) {
+			if (!Array.isArray(entries)) continue;
+			const camel = toCamelCaseEvent(event);
+			const destList = [];
+			for (const entry of entries) {
+				if (!entry || typeof entry !== "object") continue;
+				const command = typeof entry.command === "string" ? entry.command.trim() : "";
+				const { _apm_source: _drop, ...clean } = entry;
+				if (!command) {
+					destList.push({ ...clean });
+					continue;
+				}
+				const rewritten = copyHookScript({
+					cwd,
+					deployRoots: roots,
+					hookFile: srcPath,
+					command,
+					alreadyDeployedNeedle: ".github/hooks/",
+					destRel: `.github/hooks/scripts/${pkg}/${basename(command.replace(/^\.\//, ""))}`,
+					commandAsDotSlash: true
+				});
+				destList.push({
+					...clean,
+					command: rewritten.commandRel
+				});
+				if (rewritten.scriptRel) {
+					scripts.push(rewritten.scriptRel);
+					deployedFiles.push({
+						path: rewritten.scriptRel,
+						primitive: {
+							name: String(p.name),
+							packageName: p.packageName
+						}
+					});
+				}
+			}
+			outHooks[camel] = destList;
+		}
+		writeFileSync(hookAbs, `${JSON.stringify({ hooks: outHooks }, null, 2)}\n`, "utf8");
+		deployedFiles.push({
+			path: hookRel,
+			primitive: {
+				name: String(p.name),
+				packageName: p.packageName
+			}
+		});
+		const ownedKey = `${pkg}-${stem}`;
+		nextOwned[ownedKey] = {
+			...p.packageName ? { packageName: p.packageName } : {},
+			hookFile: hookRel,
+			scripts
+		};
+	}
+	writeHookOwnershipSidecar(ownershipPath, { owned: nextOwned });
+	deployedFiles.push({
+		path: HOOKS_OWNERSHIP_REL,
+		...hooks[0] ? { primitive: {
+			name: String(hooks[0].name),
+			packageName: hooks[0].packageName
+		} } : {}
+	});
+	return {
+		deployedFiles,
+		diagnostics
+	};
+}
+//#endregion
+export { createCopilotIntegration, createCopilotIntegration as createIntegration, toCamelCaseEvent };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@b-apm/integration-copilot",
+  "version": "0.1.0",
+  "description": "GitHub Copilot runtime integration for bapm",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@b-apm/integration-api": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sdju/bapm.git",
+    "directory": "packages/integration-copilot"
+  },
+  "homepage": "https://github.com/Sdju/bapm#readme",
+  "bugs": {
+    "url": "https://github.com/Sdju/bapm/issues"
+  },
+  "keywords": [
+    "unstable",
+    "bapm",
+    "b-apm"
+  ],
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}