@b-apm/integration-api 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,76 @@
+# @b-apm/integration-api
+
+> **UNSTABLE:** Early public release. APIs and on-disk layouts may change without a major bump. Not production-ready.
+
+Shared **contracts, registry, and materialize helpers** for bapm integrations.
+
+## Boundary
+
+| Package                                             | May depend on                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------------- |
+| `@b-apm/core`                                        | `@b-apm/integration-api` only (no concrete `@b-apm/integration-*`) |
+| `@b-apm/integration-cursor` (and other integrations) | `@b-apm/integration-api`                                          |
+| CLI / tests                                         | Register concrete integrations into a registry created here      |
+
+Core Install discovers primitives and calls `materialize` on registered integrations through this package. Integration packages implement detection, deploy roots, and disk writes — core never imports them.
+
+## Loadable package export contract (object-map)
+
+When a project manifest uses object-map `target` / `targets`, the CLI loads each map value as an npm package from the project cwd and registers a runtime `BapmIntegration`. A loadable package MUST expose (first match wins):
+
+1. Named **`createIntegration`** — zero-arg factory returning `BapmIntegration` (preferred for third parties); or
+2. Named **`createCursorIntegration`** (or an equivalent documented factory) returning `BapmIntegration`; or
+3. **Default export** that is either a `BapmIntegration` object or a factory returning one.
+
+The loaded instance MUST have non-empty `id`, `deployRoots` array, `detect`, and `materialize` (`configureMcp` / `compile` optional). Optional `mcpEnvMode: "bake" | "translate"` tells install whether to bake APM `${VAR}` placeholders before `configureMcp` (omitted ⇒ bake-compatible, Cursor default). `id` MUST equal the map key. Marketplace-output-only packages (no runtime hooks) are rejected. A successful `configureMcp` report MUST include a non-empty `configPath` (project-relative, absolute, or home-tilde form for home-scoped hosts).
+
+See `@b-apm/integration-cursor` for a built-in reference and the VitePress architecture guide for the author how-to.
+
+## Helpers
+
+Optional fs/path helpers for host `materialize` (exported from the package root):
+
+| Symbol                            | Role                                                               |
+| --------------------------------- | ------------------------------------------------------------------ |
+| `primitivesList`                  | Normalize array / `{ primitives }` sets                            |
+| `primitivesMaterialize`           | Dispatch primitives to `skill` / `instruction` / … handlers        |
+| `sanitizeName`                    | Path-safe single segment from a primitive name                     |
+| `isUnderRoot`                     | Containment check under a deploy root                              |
+| `assertUnderDeployRoots`          | Refuse writes outside registered roots                             |
+| `writeDeployedFile`               | Assert roots + mkdir + write + `DeployedFile` inventory row        |
+| `readPrimitiveContent`            | Inline content / source file / stub frontmatter                    |
+| `toPosixRel`                      | Absolute → cwd-relative path with `/` separators                   |
+| `findPackageRoot`                 | Nearest `apm.yml` / `bapm.yml` / `plugin.json` ancestor            |
+| `isWithin`                        | Path containment (`candidate` under `root`)                        |
+| `listFiles`                       | Recursive file listing (absolute paths)                            |
+| `copyPortableSkillDirectory`      | Safe Agent Plugin skill tree copy (no symlink escape)              |
+| `materializeSkill`                | Shared skill deploy (portable tree / SKILL.md / stub + inventory)  |
+| `renderPrimitivesMarkdown`        | Deterministic compile markdown (AGENTS.md family)                  |
+| `compileMarkdownReport`           | Preview/write `CompileReport` for host compile hooks               |
+| `filterFrontmatterKeys`           | Drop non-allowlisted YAML frontmatter keys                         |
+| `SHARED_COMMAND_FRONTMATTER_KEYS` | Shared command FM allowlist (description/tools/model/…)            |
+| `HookOwnershipSidecar`            | Type for `.*/bapm-hooks.json` owned map (flexible optional fields) |
+| `readHookOwnershipSidecar`        | Read ownership sidecar; missing/malformed → `{ owned: {} }`        |
+| `writeHookOwnershipSidecar`       | Write `{ owned }` as pretty JSON + trailing newline                |
+| `stripOwnedHookCommands`          | Filter event arrays by owned entry commands (no disk deletes)      |
+| `removeOwnedHookArtifacts`        | Best-effort rm of owned `scripts` / `hookFile` / `hookFiles`       |
+| `copyHookScript`                  | Simple script copy + command rewrite (needle + caller `destRel`)   |
+
+Prefer `primitivesMaterialize({ skill() {…}, … })` over a manual `primitivesList` loop.
+Use `materializeSkill({ destDir })` inside the `skill` handler — hosts only pick the path.
+Use `writeDeployedFile` for single-file markdown/json deploys; use `renderPrimitivesMarkdown` + `compileMarkdownReport` inside `compile`.
+Integrations keep host-specific detect + destinations; shared path/content plumbing lives here.
+
+## Materialize report
+
+`materialize` MAY return a `MaterializeReport`:
+
+```ts
+type DeployedFile = { path: string; hash?: string };
+type MaterializeReport = { deployedFiles: DeployedFile[] };
+```
+
+- `path` — project-/cwd-relative harness path (e.g. `.agents/skills/hello/SKILL.md`)
+- `hash` — optional; when omitted, core computes a stable content hash for lock inventory
+
+Core uses this report only via `@b-apm/integration-api` to write `deployed_file_hashes` and drive orphan cleanup / frozen re-verify. There is no adapter catalog or MCP configure surface in this package.

package/dist/index.d.mts

@@ -0,0 +1,378 @@
+//#region src/types.d.ts
+/**
+ * Shared target contracts for core ↔ host packages.
+ */
+/** Target identifier (built-in like `cursor`, or vendor `x-<vendor>-<name>`). */
+type TargetId = string;
+/** Source attribution for a discovered primitive (OpenAPM pr-001). */
+type PrimitiveSource = "local" | `dependency:${string}`;
+/** Primitive kinds in the M4 discovery floor (skill | agent | instruction | …). */
+type PrimitiveType = string;
+/** Attributed primitive unit passed to materialize. */
+type AttributedPrimitive = {
+  name: string;
+  type: PrimitiveType;
+  source: PrimitiveSource;
+  /** Absolute or project-relative path to the source file/dir. */
+  path: string;
+  /** Package name when source is dependency:<name>. */
+  packageName?: string;
+  /** Optional raw content hint; hosts may re-read from path. */
+  content?: string;
+  /** Complete portable Agent Plugin skill directory, when applicable. */
+  skillDirectory?: string;
+  /** Resolved portable plugin root for containment-aware targets. */
+  pluginRoot?: string;
+  /** Identifies the portable Agent Plugins skill format. */
+  format?: "agent-plugin";
+  [key: string]: unknown;
+};
+/** Conflict-resolved set (or array) accepted by materialize. */
+type AttributedPrimitiveSet = AttributedPrimitive[] | {
+  primitives: AttributedPrimitive[];
+  diagnostics?: unknown[];
+};
+/** Context supplied when invoking materialize. */
+type MaterializeContext = {
+  cwd: string;
+  /** Active target id for this invocation. */
+  targetId: TargetId;
+  /** Deploy roots declared by the target (relative to cwd). */
+  deployRoots: string[];
+  [key: string]: unknown;
+};
+/** One harness file written by materialize (cwd-relative path). */
+type DeployedFile = {
+  /** Project-/cwd-relative path using `/` separators. */
+  path: string;
+  /** Optional content hash (host may omit; core can compute). */
+  hash?: string;
+  /**
+   * Target-supplied primitive ownership for this deployment. Core uses this
+   * metadata for lock attribution and never infers it from a host file layout.
+   */
+  primitive?: {
+    name: string;
+    packageName?: string;
+  };
+};
+/**
+ * Report returned by `materialize` so core can record lock inventory
+ * (`deployed_file_hashes`) without importing concrete host packages.
+ */
+type MaterializeReport = {
+  /** Registered target that owns these deployment entries when any are reported. */
+  targetId?: TargetId;
+  deployedFiles: DeployedFile[];
+  /** Non-fatal adapter notes (frontmatter drops, unsupported primitive skips, …). */
+  diagnostics?: Array<{
+    code?: string;
+    message: string;
+    [key: string]: unknown;
+  }>;
+};
+/** Detection predicate hook — true when this host should activate for the project. */
+type TargetDetectFn = (ctx: {
+  cwd: string;
+}) => boolean | Promise<boolean>;
+/** A non-sensitive reason why a registered target was not detected. */
+type TargetDetectionDiagnostic = {
+  targetId: TargetId;
+  message: string;
+};
+/** Result of evaluating every registered target exactly once. */
+type DetectedTargetsResult = {
+  detectedIds: TargetId[];
+  diagnostics: TargetDetectionDiagnostic[];
+};
+/** Context owned by core while a target emits its compile output. */
+type CompileContext = {
+  cwd: string;
+  outputFile?: string;
+  /** Core-owned write intent; false for validation and preview requests. */
+  write: boolean;
+};
+/** Target-owned compile emission result. Paths are project-relative. */
+type CompileReport = {
+  path: string;
+  content: string;
+  wrote: boolean;
+};
+type CompileFn = (primitives: AttributedPrimitiveSet, context: CompileContext) => CompileReport | Promise<CompileReport>;
+/**
+ * Host-agnostic MCP server definition passed to optional `configureMcp`.
+ * Concrete targets map transport, command, or URL into their native config shape.
+ */
+type McpServerConfig = {
+  name: string;
+  transport?: string;
+  type?: string;
+  command?: string;
+  args?: unknown[];
+  url?: string;
+  env?: Record<string, string>;
+  /** Package provenance (dependency name or local). */
+  packageName?: string;
+  [key: string]: unknown;
+};
+/** Context for optional MCP configure. */
+type ConfigureMcpContext = {
+  cwd: string;
+  /** Active target id for this invocation. */
+  targetId?: TargetId;
+  /** Deploy roots declared by the target (relative to cwd). */
+  deployRoots?: string[];
+  [key: string]: unknown;
+};
+/**
+ * Report returned by `configureMcp` so core can record lock `mcp_*` inventory
+ * without importing concrete host packages.
+ */
+type ConfigureMcpReport = {
+  /** Registered target that owns the reported MCP deployment. */
+  targetId?: TargetId;
+  /**
+   * Path to the written target MCP config: project-/cwd-relative for project hosts,
+   * or absolute / `~/…` for home-scoped hosts.
+   */
+  configPath: string;
+  /** Server names written/updated. */
+  servers?: string[];
+  deployedFiles?: DeployedFile[];
+  /** Explicit adapter decisions or unsupported-server diagnostics. */
+  diagnostics?: Array<{
+    code: string;
+    message: string;
+    server?: string;
+  }>;
+};
+/** Optional MCP configure hook — targets that lack it are skipped for MCP. */
+type ConfigureMcpFn = (servers: McpServerConfig[] | Record<string, McpServerConfig>, ctx?: ConfigureMcpContext) => ConfigureMcpReport | Promise<ConfigureMcpReport>;
+/**
+ * Install-time MCP env policy for a host.
+ * - `bake` (default when omitted): resolve APM `${VAR}` / `${env:VAR}` / `<VAR>` to literals before configure
+ * - `translate`: pass APM placeholders through; host writes runtime `${VAR}` forms
+ * Bapm `{bake:NAME}` directives are still resolved (fail-closed) for both modes.
+ */
+type McpEnvMode = "bake" | "translate";
+/** Concrete target contract consumed by core only through `@b-apm/integration-api`. */
+type BapmIntegration = {
+  id: TargetId;
+  /** Registered deploy root(s) relative to project cwd (tg-002). */
+  deployRoots: string[];
+  detect: TargetDetectFn;
+  materialize: (primitives: AttributedPrimitiveSet, ctx?: MaterializeContext) => void | MaterializeReport | Promise<void | MaterializeReport>;
+  getDeployRoots?: () => string[];
+  /** Optional host-agnostic MCP configure; targets without it are skipped for MCP. */
+  configureMcp?: ConfigureMcpFn;
+  /** Optional host-owned compile rendering and output placement. */
+  compile?: CompileFn;
+  /**
+   * Optional MCP env handling mode. Omitted ⇒ bake-compatible (Cursor default).
+   * Install reads this through the api contract — no host-id allowlists in core.
+   */
+  mcpEnvMode?: McpEnvMode;
+  [key: string]: unknown;
+};
+type IntegrationRegistry = {
+  register(target: BapmIntegration): void;
+  list(): BapmIntegration[];
+  get(id: TargetId): BapmIntegration | undefined;
+  getAll(): BapmIntegration[];
+  /** Evaluate each registered detector once, treating failures as non-matches. */
+  detect(cwd: string): Promise<DetectedTargetsResult>;
+};
+/**
+ * Host-owned marketplace output. The neutral payload types deliberately avoid
+ * describing any host document schema; integrations own that representation.
+ */
+type MarketplaceOutputCapability = {
+  format: string;
+  defaultOutput: string;
+  map: (config: unknown, resolved: unknown[]) => Record<string, unknown>;
+};
+/** Marketplace-only integrations need no runtime detect or deployment hooks. */
+type MarketplaceOutputIntegration = {
+  id: string;
+  marketplaceOutput: MarketplaceOutputCapability;
+};
+type MarketplaceOutputRegistry = {
+  register(integration: MarketplaceOutputIntegration): void;
+  list(): MarketplaceOutputIntegration[];
+  get(format: string): MarketplaceOutputIntegration | undefined;
+};
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Create an empty in-memory target registry for core Install and tests.
+ * No concrete host imports — callers register doubles or host packages.
+ */
+declare function createIntegrationRegistry(): IntegrationRegistry;
+/** Create a registry for marketplace-output-only or combined integrations. */
+declare function createMarketplaceOutputRegistry(): MarketplaceOutputRegistry;
+//#endregion
+//#region src/helpers.d.ts
+/** Shared command frontmatter allowlist (Cursor / Claude Code / Grok-style prompts). */
+declare const SHARED_COMMAND_FRONTMATTER_KEYS: ReadonlySet<string>;
+/** Normalize `AttributedPrimitiveSet` (array or `{ primitives }`) to a list. */
+declare function primitivesList(set: AttributedPrimitiveSet): AttributedPrimitive[];
+/** Known primitive kinds dispatched by `primitivesMaterialize`. */
+type PrimitiveMaterializeKind = "skill" | "instruction" | "agent" | "command" | "hook";
+/** Context passed to each materialize handler. */
+type PrimitiveMaterializeContext = {
+  /** Path-safe single segment from `primitive.name`. */
+  name: string;
+  /** Lowercased `primitive.type` (default `"skill"`). */
+  type: string;
+};
+type PrimitiveMaterializeHandler = (primitive: AttributedPrimitive, ctx: PrimitiveMaterializeContext) => void | Promise<void>;
+/**
+ * Host handlers keyed by primitive kind. Missing keys are skipped.
+ * `unknown` runs only when the type matches no known kind.
+ */
+type PrimitiveMaterializeHandlers = Partial<Record<PrimitiveMaterializeKind, PrimitiveMaterializeHandler>> & {
+  unknown?: PrimitiveMaterializeHandler;
+};
+/**
+ * Dispatch each primitive to a typed handler (`skill`, `instruction`, …).
+ * Prefer this over a manual `primitivesList` + `if (/skill/)` loop in hosts.
+ * Known kinds without a handler are skipped; `unknown` covers unmatched types.
+ */
+declare function primitivesMaterialize(set: AttributedPrimitiveSet, handlers: PrimitiveMaterializeHandlers): Promise<void>;
+/** Replace path separators so a primitive name is safe as a single path segment. */
+declare function sanitizeName(name: string): string;
+/** True when `absPath` is `rootRel` or a descendant under `cwd`. */
+declare function isUnderRoot(cwd: string, absPath: string, rootRel: string): boolean;
+/** Throw if `absPath` is outside every registered deploy root. */
+declare function assertUnderDeployRoots(cwd: string, absPath: string, deployRoots: string[]): void;
+/**
+ * Resolve primitive body: inline `content`, preferred nested file, source file,
+ * or minimal frontmatter stub.
+ */
+declare function readPrimitiveContent(p: AttributedPrimitive, preferredFile?: string): string;
+/** Absolute path → cwd-relative path with `/` separators. */
+declare function toPosixRel(cwd: string, absPath: string): string;
+/**
+ * Walk up from `startPath` (file or directory) to the nearest package root
+ * marked by `apm.yml`, `bapm.yml`, or `plugin.json`.
+ * Falls back to `dirname(startPath)` when no marker is found.
+ */
+declare function findPackageRoot(startPath: string): string;
+/** True when `candidate` is `root` or a descendant (path containment). */
+declare function isWithin(root: string, candidate: string): boolean;
+/** Recursively list files under `dir` (absolute paths). */
+declare function listFiles(dir: string): string[];
+/**
+ * Copy a validated portable Agent Plugin skill directory without retaining symlinks.
+ * Throws when the skill escapes `pluginRoot`.
+ */
+declare function copyPortableSkillDirectory(sourceDir: string, pluginRoot: unknown, destDir: string): void;
+/**
+ * Host-agnostic skill materialize: Agent Plugin tree / SKILL.md copy / content stub.
+ * Hosts only choose `destDir` (cwd-relative or absolute under deploy roots).
+ */
+declare function materializeSkill(args: {
+  primitive: AttributedPrimitive;
+  cwd: string;
+  deployRoots: string[];
+  /** Destination skill directory (e.g. `.agents/skills/hello` or absolute). */
+  destDir: string;
+}): DeployedFile[];
+/** True when the target exposes an MCP configure hook (any documented alias). */
+declare function hasConfigureMcp(target: BapmIntegration | Record<string, unknown>): boolean;
+/**
+ * Resolve optional MCP configure from a registered target.
+ * Accepts `configureMcp` and documented aliases without requiring every host to
+ * use the same method name.
+ */
+declare function getConfigureMcp(target: BapmIntegration | Record<string, unknown>): ConfigureMcpFn | undefined;
+/**
+ * Assert deploy-root containment, mkdir parents, write content, return inventory row.
+ */
+declare function writeDeployedFile(args: {
+  cwd: string;
+  deployRoots: string[];
+  /** Destination path relative to `cwd` (or absolute under cwd). */
+  destRel: string;
+  content: string | Buffer;
+  primitive?: {
+    name: string;
+    packageName?: string;
+  };
+}): DeployedFile;
+/**
+ * Deterministic markdown document from attributed primitives (AGENTS.md family).
+ */
+declare function renderPrimitivesMarkdown(args: {
+  primitives: AttributedPrimitive[];
+  title: string;
+  filter?: (p: AttributedPrimitive) => boolean;
+  emptyMessage?: string;
+  sectionHeading?: (p: AttributedPrimitive) => string;
+  preferredFile?: string;
+}): string;
+/**
+ * Build a `CompileReport` from markdown content; optionally write under cwd.
+ */
+declare function compileMarkdownReport(args: {
+  cwd: string;
+  outputFile: string;
+  write: boolean;
+  content: string;
+  requireBasename?: string;
+  outsideCwdMessage?: string;
+}): CompileReport;
+/**
+ * Drop YAML frontmatter keys not in `preserved`; preserve body and non-key lines.
+ */
+declare function filterFrontmatterKeys(source: string, preserved: ReadonlySet<string>): {
+  content: string;
+  droppedKeys: string[];
+};
+/** Owned-hook sidecar document (hosts write only the fields they need). */
+type HookOwnershipSidecar = {
+  owned: Record<string, {
+    packageName?: string;
+    entries?: Array<{
+      event: string;
+      command: string;
+    }>;
+    scripts?: string[];
+    hookFile?: string;
+    hookFiles?: string[];
+  }>;
+};
+/** Read ownership sidecar; missing/malformed → `{ owned: {} }`. */
+declare function readHookOwnershipSidecar(path: string): HookOwnershipSidecar;
+/** Write `{ owned }` as pretty JSON with trailing newline (caller asserts deploy roots). */
+declare function writeHookOwnershipSidecar(path: string, doc: HookOwnershipSidecar): void;
+/**
+ * Remove entries whose `command` appears in any owned `entries`.
+ * Mutates `hooks` in place; does not delete files from disk.
+ */
+declare function stripOwnedHookCommands(hooks: Record<string, unknown>, ownership: HookOwnershipSidecar): void;
+/**
+ * Best-effort delete of owned `scripts`, `hookFile`, and `hookFiles` under `cwd`.
+ * Missing paths are ignored; does not mutate hooks JSON.
+ */
+declare function removeOwnedHookArtifacts(cwd: string, ownership: HookOwnershipSidecar): void;
+type CopyHookScriptArgs = {
+  cwd: string;
+  deployRoots: string[];
+  hookFile: string;
+  command: string;
+  alreadyDeployedNeedle: string;
+  destRel: string;
+  commandAsDotSlash?: boolean;
+};
+type CopyHookScriptResult = {
+  commandRel: string;
+  scriptRel?: string;
+};
+/**
+ * Simple hook-script copy for hosts that resolve next to the hook file or under
+ * `findPackageRoot`, then write a caller-supplied `destRel` under deploy roots.
+ */
+declare function copyHookScript(args: CopyHookScriptArgs): CopyHookScriptResult;
+//#endregion
+export { type AttributedPrimitive, type AttributedPrimitiveSet, type BapmIntegration, type CompileContext, type CompileFn, type CompileReport, type ConfigureMcpContext, type ConfigureMcpFn, type ConfigureMcpReport, type CopyHookScriptArgs, type CopyHookScriptResult, type DeployedFile, type DetectedTargetsResult, type HookOwnershipSidecar, type IntegrationRegistry, type MarketplaceOutputCapability, type MarketplaceOutputIntegration, type MarketplaceOutputRegistry, type MaterializeContext, type MaterializeReport, type McpEnvMode, type McpServerConfig, type PrimitiveMaterializeContext, type PrimitiveMaterializeHandler, type PrimitiveMaterializeHandlers, type PrimitiveMaterializeKind, type PrimitiveSource, type PrimitiveType, SHARED_COMMAND_FRONTMATTER_KEYS, type TargetDetectFn, type TargetDetectionDiagnostic, type TargetId, assertUnderDeployRoots, compileMarkdownReport, copyHookScript, copyPortableSkillDirectory, createIntegrationRegistry, createMarketplaceOutputRegistry, filterFrontmatterKeys, findPackageRoot, getConfigureMcp, hasConfigureMcp, isUnderRoot, isWithin, listFiles, materializeSkill, primitivesList, primitivesMaterialize, readHookOwnershipSidecar, readPrimitiveContent, removeOwnedHookArtifacts, renderPrimitivesMarkdown, sanitizeName, stripOwnedHookCommands, toPosixRel, writeDeployedFile, writeHookOwnershipSidecar };

package/dist/index.mjs

@@ -0,0 +1,452 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+//#region src/registry.ts
+/**
+* Create an empty in-memory target registry for core Install and tests.
+* No concrete host imports — callers register doubles or host packages.
+*/
+function createIntegrationRegistry() {
+	const byId = /* @__PURE__ */ new Map();
+	return {
+		register(target) {
+			if (!target || typeof target !== "object") throw new TypeError("register requires a BapmIntegration object");
+			const id = String(target.id ?? "").trim();
+			if (!id) throw new TypeError("BapmIntegration.id is required");
+			if (!Array.isArray(target.deployRoots)) throw new TypeError(`BapmIntegration ${id} requires deployRoots array`);
+			if (typeof target.detect !== "function") throw new TypeError(`BapmIntegration ${id} requires detect()`);
+			if (typeof target.materialize !== "function") throw new TypeError(`BapmIntegration ${id} requires materialize()`);
+			byId.set(id, target.id === id ? target : {
+				...target,
+				id
+			});
+		},
+		list() {
+			return [...byId.values()];
+		},
+		get(id) {
+			return byId.get(id);
+		},
+		getAll() {
+			return [...byId.values()];
+		},
+		async detect(cwd) {
+			const detectedIds = [];
+			const diagnostics = [];
+			for (const target of byId.values()) try {
+				if (await target.detect({ cwd })) detectedIds.push(target.id);
+			} catch {
+				diagnostics.push({
+					targetId: target.id,
+					message: `Target "${target.id}" detection did not match`
+				});
+			}
+			return {
+				detectedIds,
+				diagnostics
+			};
+		}
+	};
+}
+/** Create a registry for marketplace-output-only or combined integrations. */
+function createMarketplaceOutputRegistry() {
+	const byFormat = /* @__PURE__ */ new Map();
+	return {
+		register(integration) {
+			const format = integration?.marketplaceOutput?.format?.trim();
+			if (!integration?.id?.trim() || !format || !integration.marketplaceOutput.defaultOutput) throw new TypeError("Marketplace output integration requires id, format, and defaultOutput");
+			if (typeof integration.marketplaceOutput.map !== "function") throw new TypeError(`Marketplace output integration ${integration.id} requires map()`);
+			byFormat.set(format, {
+				...integration,
+				id: integration.id.trim(),
+				marketplaceOutput: {
+					...integration.marketplaceOutput,
+					format
+				}
+			});
+		},
+		list() {
+			return [...byFormat.values()];
+		},
+		get(format) {
+			return byFormat.get(format);
+		}
+	};
+}
+//#endregion
+//#region src/helpers.ts
+/**
+* Shared materialize helpers for host targets (fs/path, primitive content).
+*/
+/** Shared command frontmatter allowlist (Cursor / Claude Code / Grok-style prompts). */
+const SHARED_COMMAND_FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+	"description",
+	"allowed-tools",
+	"model",
+	"argument-hint",
+	"input"
+]);
+/** Normalize `AttributedPrimitiveSet` (array or `{ primitives }`) to a list. */
+function primitivesList(set) {
+	if (Array.isArray(set)) return set;
+	if (set && typeof set === "object" && Array.isArray(set.primitives)) return set.primitives;
+	return [];
+}
+const KIND_MATCHERS = [
+	{
+		kind: "skill",
+		test: /skill/
+	},
+	{
+		kind: "instruction",
+		test: /instruction/
+	},
+	{
+		kind: "agent",
+		test: /agent/
+	},
+	{
+		kind: "command",
+		test: /command/
+	},
+	{
+		kind: "hook",
+		test: /hook/
+	}
+];
+function resolvePrimitiveKind(type) {
+	for (const { kind, test } of KIND_MATCHERS) if (test.test(type)) return kind;
+}
+/**
+* Dispatch each primitive to a typed handler (`skill`, `instruction`, …).
+* Prefer this over a manual `primitivesList` + `if (/skill/)` loop in hosts.
+* Known kinds without a handler are skipped; `unknown` covers unmatched types.
+*/
+async function primitivesMaterialize(set, handlers) {
+	for (const primitive of primitivesList(set)) {
+		const type = String(primitive.type ?? "skill").toLowerCase();
+		const ctx = {
+			name: sanitizeName(String(primitive.name)),
+			type
+		};
+		const kind = resolvePrimitiveKind(type);
+		const handler = kind ? handlers[kind] : handlers.unknown;
+		if (handler) await handler(primitive, ctx);
+	}
+}
+/** Replace path separators so a primitive name is safe as a single path segment. */
+function sanitizeName(name) {
+	return String(name || "unnamed").replace(/[/\\]/g, "-");
+}
+/** True when `absPath` is `rootRel` or a descendant under `cwd`. */
+function isUnderRoot(cwd, absPath, rootRel) {
+	const rootAbs = resolve(cwd, rootRel);
+	const rel = relative(rootAbs, absPath);
+	return rel === "" || !rel.startsWith("..") && !rel.startsWith(`..${sep}`);
+}
+/** Throw if `absPath` is outside every registered deploy root. */
+function assertUnderDeployRoots(cwd, absPath, deployRoots) {
+	if (!deployRoots.some((r) => isUnderRoot(cwd, absPath, r))) throw new Error(`materialize refuses path outside deploy roots: ${absPath}`);
+}
+/**
+* Resolve primitive body: inline `content`, preferred nested file, source file,
+* or minimal frontmatter stub.
+*/
+function readPrimitiveContent(p, preferredFile) {
+	if (typeof p.content === "string") return p.content;
+	const src = p.path ? resolve(p.path) : void 0;
+	if (src && existsSync(src)) {
+		if (preferredFile) {
+			const nested = src.endsWith(preferredFile) ? src : join(src, preferredFile);
+			if (existsSync(nested) && statSync(nested).isFile()) return readFileSync(nested, "utf8");
+		}
+		if (statSync(src).isFile()) return readFileSync(src, "utf8");
+	}
+	const name = sanitizeName(String(p.name));
+	return `---\nname: ${name}\n---\n# ${name}\n`;
+}
+/** Absolute path → cwd-relative path with `/` separators. */
+function toPosixRel(cwd, absPath) {
+	return relative(cwd, absPath).split(sep).join("/");
+}
+/**
+* Walk up from `startPath` (file or directory) to the nearest package root
+* marked by `apm.yml`, `bapm.yml`, or `plugin.json`.
+* Falls back to `dirname(startPath)` when no marker is found.
+*/
+function findPackageRoot(startPath) {
+	let dir = existsSync(startPath) && statSync(startPath).isDirectory() ? startPath : dirname(startPath);
+	for (;;) {
+		if (existsSync(join(dir, "apm.yml")) || existsSync(join(dir, "bapm.yml")) || existsSync(join(dir, "plugin.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return existsSync(startPath) && statSync(startPath).isDirectory() ? startPath : dirname(startPath);
+}
+/** True when `candidate` is `root` or a descendant (path containment). */
+function isWithin(root, candidate) {
+	const rel = relative(root, candidate);
+	return rel === "" || !rel.startsWith("..") && !rel.startsWith("/") && rel !== "..";
+}
+/** Recursively list files under `dir` (absolute paths). */
+function listFiles(dir) {
+	const files = [];
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) files.push(...listFiles(path));
+		else files.push(path);
+	}
+	return files;
+}
+function treeIsContained(directory, root, visited) {
+	if (visited.has(directory)) return true;
+	visited.add(directory);
+	for (const entry of readdirSync(directory)) {
+		const resolved = realpathSync(join(directory, entry));
+		if (!isWithin(root, resolved)) return false;
+		if (statSync(resolved).isDirectory() && !treeIsContained(resolved, root, visited)) return false;
+	}
+	return true;
+}
+/**
+* Copy a validated portable Agent Plugin skill directory without retaining symlinks.
+* Throws when the skill escapes `pluginRoot`.
+*/
+function copyPortableSkillDirectory(sourceDir, pluginRoot, destDir) {
+	const source = realpathSync(sourceDir);
+	const root = typeof pluginRoot === "string" ? realpathSync(pluginRoot) : void 0;
+	if (!root || !isWithin(root, source) || !statSync(source).isDirectory()) throw new Error("Agent Plugin skill directory is outside its plugin root");
+	const skillFile = realpathSync(join(source, "SKILL.md"));
+	if (!isWithin(root, skillFile) || !statSync(skillFile).isFile() || !treeIsContained(source, root, /* @__PURE__ */ new Set())) throw new Error("Agent Plugin skill contains a path outside its plugin root");
+	mkdirSync(destDir, { recursive: true });
+	cpSync(source, destDir, {
+		recursive: true,
+		dereference: true,
+		force: true
+	});
+}
+/**
+* Host-agnostic skill materialize: Agent Plugin tree / SKILL.md copy / content stub.
+* Hosts only choose `destDir` (cwd-relative or absolute under deploy roots).
+*/
+function materializeSkill(args) {
+	const { primitive: p, cwd, deployRoots } = args;
+	const destDir = resolve(cwd, args.destDir);
+	const destFile = join(destDir, "SKILL.md");
+	assertUnderDeployRoots(cwd, destFile, deployRoots);
+	mkdirSync(destDir, { recursive: true });
+	const src = p.path ? resolve(p.path) : void 0;
+	if (p.format === "agent-plugin" && typeof p.skillDirectory === "string") copyPortableSkillDirectory(p.skillDirectory, p.pluginRoot, destDir);
+	else if (src && existsSync(src)) {
+		const skillMd = src.endsWith("SKILL.md") ? src : join(src, "SKILL.md");
+		if (existsSync(skillMd) && statSync(skillMd).isFile()) cpSync(skillMd, destFile);
+		else writeFileSync(destFile, readPrimitiveContent(p, "SKILL.md"), "utf8");
+	} else writeFileSync(destFile, readPrimitiveContent(p, "SKILL.md"), "utf8");
+	return listFiles(destDir).map((path) => ({
+		path: toPosixRel(cwd, path),
+		primitive: {
+			name: String(p.name),
+			packageName: p.packageName
+		}
+	}));
+}
+const MCP_CONFIGURE_ALIASES = [
+	"configureMcp",
+	"writeMcpConfig",
+	"deployMcp",
+	"configureMcpServers"
+];
+/** True when the target exposes an MCP configure hook (any documented alias). */
+function hasConfigureMcp(target) {
+	return getConfigureMcp(target) !== void 0;
+}
+/**
+* Resolve optional MCP configure from a registered target.
+* Accepts `configureMcp` and documented aliases without requiring every host to
+* use the same method name.
+*/
+function getConfigureMcp(target) {
+	const rec = target;
+	for (const key of MCP_CONFIGURE_ALIASES) {
+		const fn = rec[key];
+		if (typeof fn === "function") return fn.bind(target);
+	}
+}
+/**
+* Assert deploy-root containment, mkdir parents, write content, return inventory row.
+*/
+function writeDeployedFile(args) {
+	const cwd = resolve(args.cwd);
+	const destFile = resolve(cwd, args.destRel);
+	assertUnderDeployRoots(cwd, destFile, args.deployRoots);
+	mkdirSync(dirname(destFile), { recursive: true });
+	writeFileSync(destFile, args.content);
+	const row = { path: toPosixRel(cwd, destFile) };
+	if (args.primitive) row.primitive = args.primitive;
+	return row;
+}
+function defaultSectionHeading(p) {
+	return `${p.name} (${p.type})`;
+}
+/**
+* Deterministic markdown document from attributed primitives (AGENTS.md family).
+*/
+function renderPrimitivesMarkdown(args) {
+	const sorted = [...args.filter ? args.primitives.filter(args.filter) : args.primitives].sort((a, b) => {
+		const type = String(a.type ?? "").localeCompare(String(b.type ?? ""));
+		if (type !== 0) return type;
+		const name = String(a.name ?? "").localeCompare(String(b.name ?? ""));
+		return name !== 0 ? name : String(a.path ?? "").localeCompare(String(b.path ?? ""));
+	});
+	const emptyMessage = args.emptyMessage ?? "_No discoverable primitives._";
+	const heading = args.sectionHeading ?? defaultSectionHeading;
+	const sections = [
+		args.title,
+		"",
+		"<!-- Generated by bapm compile. Do not edit by hand. -->",
+		""
+	];
+	if (sorted.length === 0) return [
+		...sections,
+		emptyMessage,
+		""
+	].join("\n");
+	for (const primitive of sorted) {
+		sections.push(`## ${heading(primitive)}`, "");
+		sections.push(readPrimitiveContent(primitive, args.preferredFile ?? `# ${primitive.name}\n`).trimEnd(), "");
+	}
+	return sections.join("\n");
+}
+/**
+* Build a `CompileReport` from markdown content; optionally write under cwd.
+*/
+function compileMarkdownReport(args) {
+	const cwd = resolve(args.cwd);
+	const outputPath = resolve(cwd, args.outputFile);
+	const rel = relative(cwd, outputPath);
+	const sepChar = process.platform === "win32" ? "\\" : "/";
+	if (!rel || rel === ".." || rel.startsWith(`..${sepChar}`)) throw new Error(args.outsideCwdMessage ?? "Compile output must be a cwd-relative file path");
+	if (args.requireBasename && basename(outputPath) !== args.requireBasename) throw new Error(`Compile output basename must be ${args.requireBasename}`);
+	const path = rel.split(sep).join("/");
+	const wrote = args.write;
+	if (wrote) {
+		mkdirSync(dirname(outputPath), { recursive: true });
+		writeFileSync(outputPath, args.content, "utf8");
+	}
+	return {
+		path,
+		content: args.content,
+		wrote
+	};
+}
+/**
+* Drop YAML frontmatter keys not in `preserved`; preserve body and non-key lines.
+*/
+function filterFrontmatterKeys(source, preserved) {
+	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	if (!match) return {
+		content: source,
+		droppedKeys: []
+	};
+	const rawFm = match[1] ?? "";
+	const body = match[2] ?? "";
+	const kept = [];
+	const droppedKeys = [];
+	for (const line of rawFm.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		const keyMatch = line.match(/^([A-Za-z0-9_-]+)\s*:/);
+		if (!keyMatch) {
+			kept.push(line);
+			continue;
+		}
+		const key = keyMatch[1];
+		if (preserved.has(key)) kept.push(line);
+		else droppedKeys.push(key);
+	}
+	return {
+		content: `${kept.length > 0 ? `---\n${kept.join("\n")}\n---\n` : ""}${body}`.replace(/\s+$/, "\n"),
+		droppedKeys
+	};
+}
+/** Read ownership sidecar; missing/malformed → `{ owned: {} }`. */
+function readHookOwnershipSidecar(path) {
+	if (!existsSync(path)) return { owned: {} };
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { owned: {} };
+		const owned = raw.owned;
+		if (!owned || typeof owned !== "object" || Array.isArray(owned)) return { owned: {} };
+		return { owned };
+	} catch {
+		return { owned: {} };
+	}
+}
+/** Write `{ owned }` as pretty JSON with trailing newline (caller asserts deploy roots). */
+function writeHookOwnershipSidecar(path, doc) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ owned: doc.owned ?? {} }, null, 2)}\n`, "utf8");
+}
+/**
+* Remove entries whose `command` appears in any owned `entries`.
+* Mutates `hooks` in place; does not delete files from disk.
+*/
+function stripOwnedHookCommands(hooks, ownership) {
+	const ownedCommands = /* @__PURE__ */ new Set();
+	for (const record of Object.values(ownership.owned ?? {})) for (const entry of record.entries ?? []) if (entry.command) ownedCommands.add(entry.command);
+	if (ownedCommands.size === 0) return;
+	for (const [event, entries] of Object.entries(hooks)) {
+		if (!Array.isArray(entries)) continue;
+		hooks[event] = entries.filter((e) => {
+			const cmd = e && typeof e === "object" && typeof e.command === "string" ? e.command : "";
+			return !ownedCommands.has(cmd);
+		});
+	}
+}
+/**
+* Best-effort delete of owned `scripts`, `hookFile`, and `hookFiles` under `cwd`.
+* Missing paths are ignored; does not mutate hooks JSON.
+*/
+function removeOwnedHookArtifacts(cwd, ownership) {
+	for (const record of Object.values(ownership.owned ?? {})) {
+		const rels = [];
+		if (typeof record.hookFile === "string" && record.hookFile) rels.push(record.hookFile);
+		if (Array.isArray(record.hookFiles)) {
+			for (const f of record.hookFiles) if (typeof f === "string" && f) rels.push(f);
+		}
+		if (Array.isArray(record.scripts)) {
+			for (const s of record.scripts) if (typeof s === "string" && s) rels.push(s);
+		}
+		for (const rel of rels) try {
+			const abs = join(cwd, rel);
+			if (existsSync(abs)) rmSync(abs, { force: true });
+		} catch {}
+	}
+}
+/**
+* Simple hook-script copy for hosts that resolve next to the hook file or under
+* `findPackageRoot`, then write a caller-supplied `destRel` under deploy roots.
+*/
+function copyHookScript(args) {
+	const { cwd, deployRoots, hookFile, command, alreadyDeployedNeedle, destRel, commandAsDotSlash } = args;
+	if (command.includes(alreadyDeployedNeedle)) return { commandRel: commandAsDotSlash ? command.startsWith("./") ? command : `./${command.replace(/^\//, "")}` : command };
+	const cleaned = command.replace(/^\.\//, "");
+	const packageRoot = findPackageRoot(hookFile);
+	const source = [resolve(dirname(hookFile), cleaned), resolve(packageRoot, cleaned)].find((p) => {
+		try {
+			return existsSync(p) && statSync(p).isFile();
+		} catch {
+			return false;
+		}
+	});
+	if (!source) return { commandRel: command };
+	const destAbs = join(cwd, destRel);
+	assertUnderDeployRoots(cwd, destAbs, deployRoots);
+	mkdirSync(dirname(destAbs), { recursive: true });
+	cpSync(source, destAbs);
+	return {
+		commandRel: commandAsDotSlash ? `./${destRel}` : destRel,
+		scriptRel: destRel
+	};
+}
+//#endregion
+export { SHARED_COMMAND_FRONTMATTER_KEYS, assertUnderDeployRoots, compileMarkdownReport, copyHookScript, copyPortableSkillDirectory, createIntegrationRegistry, createMarketplaceOutputRegistry, filterFrontmatterKeys, findPackageRoot, getConfigureMcp, hasConfigureMcp, isUnderRoot, isWithin, listFiles, materializeSkill, primitivesList, primitivesMaterialize, readHookOwnershipSidecar, readPrimitiveContent, removeOwnedHookArtifacts, renderPrimitivesMarkdown, sanitizeName, stripOwnedHookCommands, toPosixRel, writeDeployedFile, writeHookOwnershipSidecar };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@b-apm/integration-api",
+  "version": "0.1.0",
+  "description": "Shared contracts and registry for bapm host integrations",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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-api"
+  },
+  "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"
+  }
+}