@contentrain/mcp 1.2.0 → 1.3.0

package/dist/paths-C3xNyc7z.mjs

@@ -0,0 +1,52 @@
+//#region src/providers/shared/errors.ts
+/**
+* Unified "is this a 404?" helper for API-backed providers.
+*
+* Two common error shapes in the provider SDKs we use:
+*
+* - **Octokit** (`@octokit/rest`) — rejects with an `Error` that has a
+*   top-level `.status` number set to the HTTP status code.
+* - **Gitbeaker** (`@gitbeaker/rest`) — rejects with a plain `Error` whose
+*   `.cause` includes `{ response: { status } }`.
+*
+* Both forms converge on `404` meaning "resource missing", so we check
+* both shapes strictly. We deliberately do NOT fall back to substring
+* matching on the error message — that leniency can silently mask other
+* 404-like errors (forbidden repo, deleted project, rate limits) and
+* produce the wrong answer. If either SDK ever stops populating the
+* status field on a legitimate 404, the regression will surface in tests
+* rather than being papered over at the reader layer.
+*/
+function isNotFoundError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (error.status === 404) return true;
+	return error.cause?.response?.status === 404;
+}
+//#endregion
+//#region src/providers/shared/paths.ts
+/**
+* Normalise an optional contentRoot — strip leading/trailing slashes,
+* treat `''`, `/` and `undefined` as "no prefix". Used by API-backed
+* providers (GitHub, GitLab, future Bitbucket) to anchor content-relative
+* paths against a repo subdirectory when Contentrain lives under a
+* monorepo path like `apps/web/.contentrain/`.
+*/
+function normaliseContentRoot(raw) {
+	if (!raw || raw === "/" || raw === "") return "";
+	return raw.replace(/^\/+|\/+$/g, "");
+}
+/**
+* Resolve a content-root-relative path to a repo-relative path. The result
+* always uses forward slashes and has no leading slash — the form every
+* REST git API consumes for `file_path` / `path` query parameters and the
+* Git Data API tree entries.
+*/
+function resolveRepoPath(contentRoot, relativePath) {
+	const prefix = normaliseContentRoot(contentRoot);
+	const cleanPath = relativePath.replace(/^\/+/, "");
+	return prefix ? `${prefix}/${cleanPath}` : cleanPath;
+}
+//#endregion
+export { isNotFoundError as n, resolveRepoPath as t };
+
+//# sourceMappingURL=paths-C3xNyc7z.mjs.map

package/dist/paths-C3xNyc7z.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths-C3xNyc7z.mjs","names":[],"sources":["../src/providers/shared/errors.ts","../src/providers/shared/paths.ts"],"sourcesContent":["/**\n * Unified \"is this a 404?\" helper for API-backed providers.\n *\n * Two common error shapes in the provider SDKs we use:\n *\n * - **Octokit** (`@octokit/rest`) — rejects with an `Error` that has a\n *   top-level `.status` number set to the HTTP status code.\n * - **Gitbeaker** (`@gitbeaker/rest`) — rejects with a plain `Error` whose\n *   `.cause` includes `{ response: { status } }`.\n *\n * Both forms converge on `404` meaning \"resource missing\", so we check\n * both shapes strictly. We deliberately do NOT fall back to substring\n * matching on the error message — that leniency can silently mask other\n * 404-like errors (forbidden repo, deleted project, rate limits) and\n * produce the wrong answer. If either SDK ever stops populating the\n * status field on a legitimate 404, the regression will surface in tests\n * rather than being papered over at the reader layer.\n */\nexport function isNotFoundError(error: unknown): boolean {\n  if (typeof error !== 'object' || error === null) return false\n  const direct = (error as { status?: number }).status\n  if (direct === 404) return true\n  const nested = (error as { cause?: { response?: { status?: number } } }).cause?.response?.status\n  return nested === 404\n}\n","/**\n * Normalise an optional contentRoot — strip leading/trailing slashes,\n * treat `''`, `/` and `undefined` as \"no prefix\". Used by API-backed\n * providers (GitHub, GitLab, future Bitbucket) to anchor content-relative\n * paths against a repo subdirectory when Contentrain lives under a\n * monorepo path like `apps/web/.contentrain/`.\n */\nexport function normaliseContentRoot(raw?: string): string {\n  if (!raw || raw === '/' || raw === '') return ''\n  return raw.replace(/^\\/+|\\/+$/g, '')\n}\n\n/**\n * Resolve a content-root-relative path to a repo-relative path. The result\n * always uses forward slashes and has no leading slash — the form every\n * REST git API consumes for `file_path` / `path` query parameters and the\n * Git Data API tree entries.\n */\nexport function resolveRepoPath(contentRoot: string | undefined, relativePath: string): string {\n  const prefix = normaliseContentRoot(contentRoot)\n  const cleanPath = relativePath.replace(/^\\/+/, '')\n  return prefix ? `${prefix}/${cleanPath}` : cleanPath\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,gBAAgB,OAAyB;AACvD,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AAExD,KADgB,MAA8B,WAC/B,IAAK,QAAO;AAE3B,QADgB,MAAyD,OAAO,UAAU,WACxE;;;;;;;;;;;AChBpB,SAAgB,qBAAqB,KAAsB;AACzD,KAAI,CAAC,OAAO,QAAQ,OAAO,QAAQ,GAAI,QAAO;AAC9C,QAAO,IAAI,QAAQ,cAAc,GAAG;;;;;;;;AAStC,SAAgB,gBAAgB,aAAiC,cAA8B;CAC7F,MAAM,SAAS,qBAAqB,YAAY;CAChD,MAAM,YAAY,aAAa,QAAQ,QAAQ,GAAG;AAClD,QAAO,SAAS,GAAG,OAAO,GAAG,cAAc"}

package/dist/paths-CYl5vCBD.mjs

@@ -0,0 +1,54 @@
+//#region src/core/ops/paths.ts
+/**
+* Content-root-relative path helpers for plan-API consumers.
+*
+* These mirror the logic inside `core/content-manager.ts:resolveJsonFilePath`
+* but return forward-slash relative strings suitable for `FileChange.path`.
+* Providers are responsible for resolving these against their backing store
+* (worktree on disk for LocalProvider, git tree path for GitHubProvider, ...).
+*
+* Kept inline to `core/ops/` for now; when Faz 2 finishes migrating every op
+* the legacy absolute-path helpers in `core/content-manager.ts` and
+* `core/meta-manager.ts` will call into these (or be replaced entirely).
+*/
+/**
+* Content-root-relative content directory for a model (forward-slash paths).
+* Mirrors `resolveContentDir` with an empty `projectRoot`, so reader-backed
+* callers and plan-API consumers share the same path resolution.
+*/
+function contentDirPath(model) {
+	if (model.content_path) return model.content_path;
+	return `.contentrain/content/${model.domain}/${model.id}`;
+}
+function contentDir(model) {
+	return contentDirPath(model);
+}
+function contentFilePath(model, locale) {
+	const dir = contentDir(model);
+	if (!model.i18n) return `${dir}/data.json`;
+	switch (model.locale_strategy ?? "file") {
+		case "suffix": return `${dir}/${model.id}.${locale}.json`;
+		case "directory": return `${dir}/${locale}/${model.id}.json`;
+		case "none": return `${dir}/${model.id}.json`;
+		default: return `${dir}/${locale}.json`;
+	}
+}
+function documentFilePath(model, locale, slug) {
+	const dir = contentDir(model);
+	if (!model.i18n) return `${dir}/${slug}.md`;
+	switch (model.locale_strategy ?? "file") {
+		case "suffix": return `${dir}/${slug}.${locale}.md`;
+		case "directory": return `${dir}/${locale}/${slug}.md`;
+		case "none": return `${dir}/${slug}.md`;
+		default: return `${dir}/${slug}/${locale}.md`;
+	}
+}
+function metaFilePath(model, locale, slug) {
+	const base = `.contentrain/meta/${model.id}`;
+	if (model.kind === "document" && slug) return `${base}/${slug}/${locale}.json`;
+	return `${base}/${locale}.json`;
+}
+//#endregion
+export { metaFilePath as i, contentFilePath as n, documentFilePath as r, contentDirPath as t };
+
+//# sourceMappingURL=paths-CYl5vCBD.mjs.map

package/dist/paths-CYl5vCBD.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths-CYl5vCBD.mjs","names":[],"sources":["../src/core/ops/paths.ts"],"sourcesContent":["import type { ModelDefinition } from '@contentrain/types'\n\n/**\n * Content-root-relative path helpers for plan-API consumers.\n *\n * These mirror the logic inside `core/content-manager.ts:resolveJsonFilePath`\n * but return forward-slash relative strings suitable for `FileChange.path`.\n * Providers are responsible for resolving these against their backing store\n * (worktree on disk for LocalProvider, git tree path for GitHubProvider, ...).\n *\n * Kept inline to `core/ops/` for now; when Faz 2 finishes migrating every op\n * the legacy absolute-path helpers in `core/content-manager.ts` and\n * `core/meta-manager.ts` will call into these (or be replaced entirely).\n */\n\n/**\n * Content-root-relative content directory for a model (forward-slash paths).\n * Mirrors `resolveContentDir` with an empty `projectRoot`, so reader-backed\n * callers and plan-API consumers share the same path resolution.\n */\nexport function contentDirPath(\n  model: Pick<ModelDefinition, 'domain' | 'id' | 'content_path'>,\n): string {\n  if (model.content_path) return model.content_path\n  return `.contentrain/content/${model.domain}/${model.id}`\n}\n\nfunction contentDir(model: Pick<ModelDefinition, 'domain' | 'id' | 'content_path'>): string {\n  return contentDirPath(model)\n}\n\nexport function contentFilePath(\n  model: Pick<ModelDefinition, 'id' | 'kind' | 'domain' | 'i18n' | 'content_path' | 'locale_strategy'>,\n  locale: string,\n): string {\n  const dir = contentDir(model)\n  if (!model.i18n) return `${dir}/data.json`\n  const strategy = model.locale_strategy ?? 'file'\n  switch (strategy) {\n    case 'suffix': return `${dir}/${model.id}.${locale}.json`\n    case 'directory': return `${dir}/${locale}/${model.id}.json`\n    case 'none': return `${dir}/${model.id}.json`\n    default: return `${dir}/${locale}.json`\n  }\n}\n\nexport function documentFilePath(\n  model: Pick<ModelDefinition, 'id' | 'domain' | 'i18n' | 'content_path' | 'locale_strategy'>,\n  locale: string,\n  slug: string,\n): string {\n  const dir = contentDir(model)\n  if (!model.i18n) return `${dir}/${slug}.md`\n  const strategy = model.locale_strategy ?? 'file'\n  switch (strategy) {\n    case 'suffix': return `${dir}/${slug}.${locale}.md`\n    case 'directory': return `${dir}/${locale}/${slug}.md`\n    case 'none': return `${dir}/${slug}.md`\n    default: return `${dir}/${slug}/${locale}.md`\n  }\n}\n\nexport function metaFilePath(\n  model: Pick<ModelDefinition, 'id' | 'kind'>,\n  locale: string,\n  slug?: string,\n): string {\n  const base = `.contentrain/meta/${model.id}`\n  if (model.kind === 'document' && slug) {\n    return `${base}/${slug}/${locale}.json`\n  }\n  return `${base}/${locale}.json`\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAoBA,SAAgB,eACd,OACQ;AACR,KAAI,MAAM,aAAc,QAAO,MAAM;AACrC,QAAO,wBAAwB,MAAM,OAAO,GAAG,MAAM;;AAGvD,SAAS,WAAW,OAAwE;AAC1F,QAAO,eAAe,MAAM;;AAG9B,SAAgB,gBACd,OACA,QACQ;CACR,MAAM,MAAM,WAAW,MAAM;AAC7B,KAAI,CAAC,MAAM,KAAM,QAAO,GAAG,IAAI;AAE/B,SADiB,MAAM,mBAAmB,QAC1C;EACE,KAAK,SAAU,QAAO,GAAG,IAAI,GAAG,MAAM,GAAG,GAAG,OAAO;EACnD,KAAK,YAAa,QAAO,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG;EACtD,KAAK,OAAQ,QAAO,GAAG,IAAI,GAAG,MAAM,GAAG;EACvC,QAAS,QAAO,GAAG,IAAI,GAAG,OAAO;;;AAIrC,SAAgB,iBACd,OACA,QACA,MACQ;CACR,MAAM,MAAM,WAAW,MAAM;AAC7B,KAAI,CAAC,MAAM,KAAM,QAAO,GAAG,IAAI,GAAG,KAAK;AAEvC,SADiB,MAAM,mBAAmB,QAC1C;EACE,KAAK,SAAU,QAAO,GAAG,IAAI,GAAG,KAAK,GAAG,OAAO;EAC/C,KAAK,YAAa,QAAO,GAAG,IAAI,GAAG,OAAO,GAAG,KAAK;EAClD,KAAK,OAAQ,QAAO,GAAG,IAAI,GAAG,KAAK;EACnC,QAAS,QAAO,GAAG,IAAI,GAAG,KAAK,GAAG,OAAO;;;AAI7C,SAAgB,aACd,OACA,QACA,MACQ;CACR,MAAM,OAAO,qBAAqB,MAAM;AACxC,KAAI,MAAM,SAAS,cAAc,KAC/B,QAAO,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO;AAEnC,QAAO,GAAG,KAAK,GAAG,OAAO"}

package/dist/providers/github/index.d.mts

@@ -0,0 +1,144 @@
+import { c as MergeResult, d as RepoReader, i as CommitAuthor, l as ProviderCapabilities, n as Branch, o as FileDiff, r as Commit, t as ApplyPlanInput, u as RepoProvider } from "../../index-D0wQJSgs.mjs";
+import { Octokit } from "@octokit/rest";
+
+//#region src/providers/github/capabilities.d.ts
+/**
+ * Capability set for GitHubProvider.
+ *
+ * GitHub over the Git Data API has no working tree, so local worktree
+ * features, source-file access and AST scans are unavailable. Push /
+ * PR operations are free because every commit goes straight to the
+ * remote. Branch protection detection uses the Repos API.
+ *
+ * Tools that require `astScan`, `sourceRead` or `sourceWrite` must
+ * gracefully reject (with `capability_required`) when running against
+ * a GitHubProvider — this is the mechanism behind phase 6's normalize
+ * capability-gate.
+ */
+declare const GITHUB_CAPABILITIES: ProviderCapabilities;
+//#endregion
+//#region src/providers/github/client.d.ts
+/**
+ * GitHubClient — a typed alias for an `@octokit/rest` instance.
+ *
+ * We rely on the peer-installed `@octokit/rest` for its types only; the
+ * provider code never imports Octokit eagerly. Consumers install it
+ * themselves via the optional peer dependency; the factory in
+ * `factory.ts` `await import()`s Octokit at runtime so the rest of MCP
+ * stays usable without it.
+ */
+type GitHubClient = Octokit;
+//#endregion
+//#region src/providers/github/types.d.ts
+/**
+ * A reference to a GitHub repository.
+ *
+ * `contentRoot` is the repo-relative directory prefix where Contentrain
+ * content lives. For a flat content repo it stays `''`; for a monorepo
+ * where Contentrain is embedded (e.g. `apps/web/.contentrain/`) it holds
+ * that prefix. All reader/writer paths are joined against it.
+ */
+interface RepoRef {
+  owner: string;
+  name: string;
+  contentRoot?: string;
+}
+/**
+ * Authentication options for the GitHub provider.
+ *
+ * - `pat` — a personal access token or fine-grained PAT. Simplest for
+ *   self-hosted MCP or CI runners. Phase 5.1 ships with this mode only.
+ * - `app` — GitHub App installation auth (JWT + installation token
+ *   exchange). Planned for Phase 5.2; see `.internal/refactor/
+ *   02-studio-handoff.md` S6 for how Studio's hosted MCP plugs in.
+ */
+type GitHubAuth = {
+  type: 'pat';
+  token: string;
+} | {
+  type: 'app';
+  appId: number;
+  privateKey: string;
+  installationId: number;
+};
+/** Default author used when a call does not provide one. */
+declare const DEFAULT_GITHUB_AUTHOR: CommitAuthor;
+//#endregion
+//#region src/providers/github/provider.d.ts
+/**
+ * GitHubProvider — `RepoProvider` backed by the Octokit-driven GitHub
+ * REST + Git Data APIs.
+ *
+ * The provider is transport-agnostic; it only talks to an `Octokit`
+ * instance passed into the constructor. The `createGitHubProvider`
+ * helper in `factory.ts` wraps the dynamic import so consumers never
+ * have to touch Octokit directly.
+ */
+declare class GitHubProvider implements RepoProvider {
+  private readonly client;
+  readonly repo: RepoRef;
+  readonly capabilities: ProviderCapabilities;
+  private readonly reader;
+  constructor(client: GitHubClient, repo: RepoRef);
+  readFile(path: string, ref?: string): Promise<string>;
+  listDirectory(path: string, ref?: string): Promise<string[]>;
+  fileExists(path: string, ref?: string): Promise<boolean>;
+  applyPlan(input: ApplyPlanInput): Promise<Commit>;
+  listBranches(prefix?: string): Promise<Branch[]>;
+  createBranch(name: string, fromRef?: string): Promise<void>;
+  deleteBranch(name: string): Promise<void>;
+  getBranchDiff(branch: string, base?: string): Promise<FileDiff[]>;
+  mergeBranch(branch: string, into: string): Promise<MergeResult>;
+  isMerged(branch: string, into?: string): Promise<boolean>;
+  getDefaultBranch(): Promise<string>;
+}
+//#endregion
+//#region src/providers/github/factory.d.ts
+/**
+ * Create an Octokit-backed `GitHubClient` from an auth configuration.
+ *
+ * The `@octokit/rest` module is imported dynamically so it stays a pure
+ * optional peer dependency — self-hosted MCP on stdio can run without
+ * it. If the module is not installed, the import throws with a helpful
+ * hint pointing the operator at the peer dependency.
+ *
+ * Phase 5.1 ships with PAT auth only. App-based auth (JWT + installation
+ * token) lands in phase 5.2 together with the HTTP transport.
+ */
+declare function createGitHubClient(auth: GitHubAuth): Promise<GitHubClient>;
+/**
+ * Factory for the full provider — instantiates an Octokit client and
+ * wraps it in a `GitHubProvider`. Consumers who already hold an Octokit
+ * instance (HTTP server injecting shared clients, tests, etc.) should
+ * instantiate `GitHubProvider` directly instead.
+ */
+declare function createGitHubProvider(opts: {
+  auth: GitHubAuth;
+  repo: RepoRef;
+}): Promise<GitHubProvider>;
+//#endregion
+//#region src/providers/github/reader.d.ts
+/**
+ * GitHubReader — `RepoReader` backed by the GitHub Repos + Git Data APIs.
+ *
+ * Reads pass through `repos.getContent`; directories return a list of
+ * names, files return decoded UTF-8 text. Files larger than ~1 MB are
+ * fetched by blob SHA through `git.getBlob` because `getContent` omits
+ * the body in that case.
+ *
+ * `ref` is forwarded verbatim and may be a branch name, tag name or
+ * commit SHA. When omitted, GitHub resolves to the repository's default
+ * branch — which is usually wrong for Contentrain flows, so callers
+ * should always pass the explicit `contentrain` tracking branch.
+ */
+declare class GitHubReader implements RepoReader {
+  private readonly client;
+  private readonly repo;
+  constructor(client: GitHubClient, repo: RepoRef);
+  readFile(path: string, ref?: string): Promise<string>;
+  listDirectory(path: string, ref?: string): Promise<string[]>;
+  fileExists(path: string, ref?: string): Promise<boolean>;
+}
+//#endregion
+export { DEFAULT_GITHUB_AUTHOR, GITHUB_CAPABILITIES, type GitHubAuth, type GitHubClient, GitHubProvider, GitHubReader, type RepoRef, createGitHubClient, createGitHubProvider };
+//# sourceMappingURL=index.d.mts.map

package/dist/providers/github/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../src/providers/github/capabilities.ts","../../../src/providers/github/client.ts","../../../src/providers/github/types.ts","../../../src/providers/github/provider.ts","../../../src/providers/github/factory.ts","../../../src/providers/github/reader.ts"],"mappings":";;;;;;;AAeA;;;;;;;;ACJA;;cDIa,mBAAA,EAAqB,oBAAA;;;;;;AAAlC;;;;;;KCJY,YAAA,GAAe,OAAA;;;;;;ADI3B;;;;;UELiB,OAAA;EACf,KAAA;EACA,IAAA;EACA,WAAA;AAAA;;;;;;;AAHF;;;KAeY,UAAA;EACN,IAAA;EAAa,KAAA;AAAA;EAEb,IAAA;EACA,KAAA;EACA,UAAA;EACA,cAAA;AAAA;;cAIO,qBAAA,EAAuB,YAAA;;;;AFpBpC;;;;;;;;cGkBa,cAAA,YAA0B,YAAA;EAAA,iBAKlB,MAAA;EAAA,SACD,IAAA,EAAM,OAAA;EAAA,SALf,YAAA,EAAc,oBAAA;EAAA,iBACN,MAAA;cAGE,MAAA,EAAQ,YAAA,EACT,IAAA,EAAM,OAAA;EAKxB,QAAA,CAAS,IAAA,UAAc,GAAA,YAAe,OAAA;EAGtC,aAAA,CAAc,IAAA,UAAc,GAAA,YAAe,OAAA;EAG3C,UAAA,CAAW,IAAA,UAAc,GAAA,YAAe,OAAA;EAIxC,SAAA,CAAU,KAAA,EAAO,cAAA,GAAiB,OAAA,CAAQ,MAAA;EAI1C,YAAA,CAAa,MAAA,YAAkB,OAAA,CAAQ,MAAA;EAGvC,YAAA,CAAa,IAAA,UAAc,OAAA,YAAmB,OAAA;EAI9C,YAAA,CAAa,IAAA,WAAe,OAAA;EAG5B,aAAA,CAAc,MAAA,UAAgB,IAAA,YAAgB,OAAA,CAAQ,QAAA;EAItD,WAAA,CAAY,MAAA,UAAgB,IAAA,WAAe,OAAA,CAAQ,WAAA;EAGnD,QAAA,CAAS,MAAA,UAAgB,IAAA,YAAgB,OAAA;EAIzC,gBAAA,CAAA,GAAoB,OAAA;AAAA;;;;AHhEtB;;;;;;;;ACJA;;iBGIsB,kBAAA,CAAmB,IAAA,EAAM,UAAA,GAAa,OAAA,CAAQ,YAAA;;;;;;AFLpE;iBEiCsB,oBAAA,CAAqB,IAAA;EAAQ,IAAA,EAAM,UAAA;EAAY,IAAA,EAAM,OAAA;AAAA,IAAY,OAAA,CAAQ,cAAA;;;;AJ5B/F;;;;;;;;ACJA;;;;cIOa,YAAA,YAAwB,UAAA;EAAA,iBAEhB,MAAA;EAAA,iBACA,IAAA;cADA,MAAA,EAAQ,YAAA,EACR,IAAA,EAAM,OAAA;EAGnB,QAAA,CAAS,IAAA,UAAc,GAAA,YAAe,OAAA;EAmCtC,aAAA,CAAc,IAAA,UAAc,GAAA,YAAe,OAAA;EAkB3C,UAAA,CAAW,IAAA,UAAc,GAAA,YAAe,OAAA;AAAA"}

package/dist/providers/github/index.mjs

@@ -0,0 +1,414 @@
+import { n as isNotFoundError, t as resolveRepoPath } from "../../paths-C3xNyc7z.mjs";
+import { CONTENTRAIN_BRANCH } from "@contentrain/types";
+//#region src/providers/github/capabilities.ts
+/**
+* Capability set for GitHubProvider.
+*
+* GitHub over the Git Data API has no working tree, so local worktree
+* features, source-file access and AST scans are unavailable. Push /
+* PR operations are free because every commit goes straight to the
+* remote. Branch protection detection uses the Repos API.
+*
+* Tools that require `astScan`, `sourceRead` or `sourceWrite` must
+* gracefully reject (with `capability_required`) when running against
+* a GitHubProvider — this is the mechanism behind phase 6's normalize
+* capability-gate.
+*/
+const GITHUB_CAPABILITIES = {
+	localWorktree: false,
+	sourceRead: false,
+	sourceWrite: false,
+	pushRemote: true,
+	branchProtection: true,
+	pullRequestFallback: true,
+	astScan: false
+};
+//#endregion
+//#region src/providers/github/apply-plan.ts
+/**
+* Apply a plan to a GitHub repository as a single atomic commit via the
+* Git Data API. High-level flow:
+*
+* 1. Resolve the base commit SHA — either the current HEAD of the target
+*    branch, or the HEAD of `input.base` (or the repo's default branch)
+*    when the target branch does not yet exist.
+* 2. Read the base tree SHA from that commit.
+* 3. Walk `input.changes` in parallel — create a blob per non-null
+*    content, emit a tree entry with `sha: null` for each deletion.
+* 4. Create a new tree layered on top of the base tree with the collected
+*    entries.
+* 5. Create the commit (tree, parents, author).
+* 6. Update an existing branch ref or create a new one pointing at the
+*    commit.
+*
+* No working tree, no transaction — the commit is durable as soon as the
+* final ref update returns.
+*/
+async function applyPlanToGitHub(client, repo, input) {
+	const { baseSha, branchExists } = await resolveBaseSha(client, repo, input.branch, input.base);
+	const baseTreeSha = (await client.rest.git.getCommit({
+		owner: repo.owner,
+		repo: repo.name,
+		commit_sha: baseSha
+	})).data.tree.sha;
+	const treeEntries = await Promise.all(input.changes.map((change) => buildTreeEntry(client, repo, change)));
+	const tree = await client.rest.git.createTree({
+		owner: repo.owner,
+		repo: repo.name,
+		base_tree: baseTreeSha,
+		tree: treeEntries
+	});
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const commit = await client.rest.git.createCommit({
+		owner: repo.owner,
+		repo: repo.name,
+		message: input.message,
+		tree: tree.data.sha,
+		parents: [baseSha],
+		author: {
+			name: input.author.name,
+			email: input.author.email,
+			date: timestamp
+		}
+	});
+	if (branchExists) await client.rest.git.updateRef({
+		owner: repo.owner,
+		repo: repo.name,
+		ref: `heads/${input.branch}`,
+		sha: commit.data.sha
+	});
+	else await client.rest.git.createRef({
+		owner: repo.owner,
+		repo: repo.name,
+		ref: `refs/heads/${input.branch}`,
+		sha: commit.data.sha
+	});
+	return {
+		sha: commit.data.sha,
+		message: commit.data.message,
+		author: {
+			name: commit.data.author?.name ?? input.author.name,
+			email: commit.data.author?.email ?? input.author.email
+		},
+		timestamp: commit.data.author?.date ?? timestamp
+	};
+}
+async function buildTreeEntry(client, repo, change) {
+	const path = resolveRepoPath(repo.contentRoot, change.path);
+	if (change.content === null) return {
+		path,
+		mode: "100644",
+		type: "blob",
+		sha: null
+	};
+	return {
+		path,
+		mode: "100644",
+		type: "blob",
+		sha: (await client.rest.git.createBlob({
+			owner: repo.owner,
+			repo: repo.name,
+			content: change.content,
+			encoding: "utf-8"
+		})).data.sha
+	};
+}
+async function resolveBaseSha(client, repo, branch, base) {
+	try {
+		return {
+			baseSha: (await client.rest.git.getRef({
+				owner: repo.owner,
+				repo: repo.name,
+				ref: `heads/${branch}`
+			})).data.object.sha,
+			branchExists: true
+		};
+	} catch (error) {
+		if (!isNotFoundError(error)) throw error;
+	}
+	const baseRefName = base ?? CONTENTRAIN_BRANCH;
+	return {
+		baseSha: (await client.rest.git.getRef({
+			owner: repo.owner,
+			repo: repo.name,
+			ref: `heads/${baseRefName}`
+		})).data.object.sha,
+		branchExists: false
+	};
+}
+//#endregion
+//#region src/providers/github/branch-ops.ts
+/**
+* Branch/merge/diff helpers backed by the Repos and Git Data APIs.
+*
+* Pure functions so they can be composed into `GitHubProvider` or used
+* standalone. All throw on non-404 errors; 404s collapse to empty-ish
+* results where that matches the `RepoProvider` contract (e.g. a
+* missing branch prefix yields `[]` rather than raising).
+*/
+async function getDefaultBranch(client, repo) {
+	return (await client.rest.repos.get({
+		owner: repo.owner,
+		repo: repo.name
+	})).data.default_branch;
+}
+async function listBranches(client, repo, prefix) {
+	const branches = [];
+	const iterator = client.paginate.iterator(client.rest.repos.listBranches, {
+		owner: repo.owner,
+		repo: repo.name,
+		per_page: 100
+	});
+	for await (const page of iterator) for (const b of page.data) {
+		if (prefix && !b.name.startsWith(prefix)) continue;
+		branches.push({
+			name: b.name,
+			sha: b.commit.sha,
+			protected: b.protected
+		});
+	}
+	return branches;
+}
+async function createBranch(client, repo, name, fromRef) {
+	const base = await client.rest.git.getRef({
+		owner: repo.owner,
+		repo: repo.name,
+		ref: `heads/${fromRef}`
+	});
+	await client.rest.git.createRef({
+		owner: repo.owner,
+		repo: repo.name,
+		ref: `refs/heads/${name}`,
+		sha: base.data.object.sha
+	});
+}
+async function deleteBranch(client, repo, name) {
+	await client.rest.git.deleteRef({
+		owner: repo.owner,
+		repo: repo.name,
+		ref: `heads/${name}`
+	});
+}
+async function getBranchDiff(client, repo, branch, base) {
+	return ((await client.rest.repos.compareCommits({
+		owner: repo.owner,
+		repo: repo.name,
+		base,
+		head: branch
+	})).data.files ?? []).map((f) => ({
+		path: f.filename,
+		status: normaliseStatus(f.status),
+		before: null,
+		after: null
+	}));
+}
+async function mergeBranch(client, repo, branch, into) {
+	try {
+		return {
+			merged: true,
+			sha: (await client.rest.repos.merge({
+				owner: repo.owner,
+				repo: repo.name,
+				base: into,
+				head: branch
+			})).data.sha,
+			pullRequestUrl: null
+		};
+	} catch (error) {
+		if (isNotModified(error)) return {
+			merged: true,
+			sha: null,
+			pullRequestUrl: null
+		};
+		throw error;
+	}
+}
+async function isMerged(client, repo, branch, into) {
+	return (await client.rest.repos.compareCommits({
+		owner: repo.owner,
+		repo: repo.name,
+		base: into,
+		head: branch
+	})).data.ahead_by === 0;
+}
+function normaliseStatus(status) {
+	if (status === "added") return "added";
+	if (status === "removed") return "removed";
+	return "modified";
+}
+function isNotModified(error) {
+	return typeof error === "object" && error !== null && error.status === 204;
+}
+//#endregion
+//#region src/providers/github/reader.ts
+/**
+* GitHubReader — `RepoReader` backed by the GitHub Repos + Git Data APIs.
+*
+* Reads pass through `repos.getContent`; directories return a list of
+* names, files return decoded UTF-8 text. Files larger than ~1 MB are
+* fetched by blob SHA through `git.getBlob` because `getContent` omits
+* the body in that case.
+*
+* `ref` is forwarded verbatim and may be a branch name, tag name or
+* commit SHA. When omitted, GitHub resolves to the repository's default
+* branch — which is usually wrong for Contentrain flows, so callers
+* should always pass the explicit `contentrain` tracking branch.
+*/
+var GitHubReader = class {
+	constructor(client, repo) {
+		this.client = client;
+		this.repo = repo;
+	}
+	async readFile(path, ref) {
+		const repoPath = resolveRepoPath(this.repo.contentRoot, path);
+		const data = (await this.client.rest.repos.getContent({
+			owner: this.repo.owner,
+			repo: this.repo.name,
+			path: repoPath,
+			ref
+		})).data;
+		if (Array.isArray(data)) throw new Error(`GitHubReader: path "${path}" is a directory, not a file`);
+		if (data.type !== "file") throw new Error(`GitHubReader: path "${path}" is a ${data.type}, not a file`);
+		if (data.content === "" && data.size > 0) {
+			const blob = await this.client.rest.git.getBlob({
+				owner: this.repo.owner,
+				repo: this.repo.name,
+				file_sha: data.sha
+			});
+			if (blob.data.encoding !== "base64") throw new Error(`GitHubReader: unexpected blob encoding "${blob.data.encoding}" for ${path}`);
+			return Buffer.from(blob.data.content, "base64").toString("utf-8");
+		}
+		if (data.encoding !== "base64") throw new Error(`GitHubReader: unexpected encoding "${data.encoding}" for ${path}`);
+		return Buffer.from(data.content, "base64").toString("utf-8");
+	}
+	async listDirectory(path, ref) {
+		const repoPath = resolveRepoPath(this.repo.contentRoot, path);
+		try {
+			const data = (await this.client.rest.repos.getContent({
+				owner: this.repo.owner,
+				repo: this.repo.name,
+				path: repoPath,
+				ref
+			})).data;
+			if (!Array.isArray(data)) return [];
+			return data.map((entry) => entry.name);
+		} catch (error) {
+			if (isNotFoundError(error)) return [];
+			throw error;
+		}
+	}
+	async fileExists(path, ref) {
+		const repoPath = resolveRepoPath(this.repo.contentRoot, path);
+		try {
+			await this.client.rest.repos.getContent({
+				owner: this.repo.owner,
+				repo: this.repo.name,
+				path: repoPath,
+				ref
+			});
+			return true;
+		} catch (error) {
+			if (isNotFoundError(error)) return false;
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/providers/github/provider.ts
+/**
+* GitHubProvider — `RepoProvider` backed by the Octokit-driven GitHub
+* REST + Git Data APIs.
+*
+* The provider is transport-agnostic; it only talks to an `Octokit`
+* instance passed into the constructor. The `createGitHubProvider`
+* helper in `factory.ts` wraps the dynamic import so consumers never
+* have to touch Octokit directly.
+*/
+var GitHubProvider = class {
+	capabilities = GITHUB_CAPABILITIES;
+	reader;
+	constructor(client, repo) {
+		this.client = client;
+		this.repo = repo;
+		this.reader = new GitHubReader(client, repo);
+	}
+	readFile(path, ref) {
+		return this.reader.readFile(path, ref);
+	}
+	listDirectory(path, ref) {
+		return this.reader.listDirectory(path, ref);
+	}
+	fileExists(path, ref) {
+		return this.reader.fileExists(path, ref);
+	}
+	applyPlan(input) {
+		return applyPlanToGitHub(this.client, this.repo, input);
+	}
+	listBranches(prefix) {
+		return listBranches(this.client, this.repo, prefix);
+	}
+	createBranch(name, fromRef) {
+		const resolved = fromRef ?? "main";
+		return createBranch(this.client, this.repo, name, resolved);
+	}
+	deleteBranch(name) {
+		return deleteBranch(this.client, this.repo, name);
+	}
+	getBranchDiff(branch, base) {
+		const resolved = base ?? "main";
+		return getBranchDiff(this.client, this.repo, branch, resolved);
+	}
+	mergeBranch(branch, into) {
+		return mergeBranch(this.client, this.repo, branch, into);
+	}
+	isMerged(branch, into) {
+		const resolved = into ?? "main";
+		return isMerged(this.client, this.repo, branch, resolved);
+	}
+	getDefaultBranch() {
+		return getDefaultBranch(this.client, this.repo);
+	}
+};
+//#endregion
+//#region src/providers/github/factory.ts
+/**
+* Create an Octokit-backed `GitHubClient` from an auth configuration.
+*
+* The `@octokit/rest` module is imported dynamically so it stays a pure
+* optional peer dependency — self-hosted MCP on stdio can run without
+* it. If the module is not installed, the import throws with a helpful
+* hint pointing the operator at the peer dependency.
+*
+* Phase 5.1 ships with PAT auth only. App-based auth (JWT + installation
+* token) lands in phase 5.2 together with the HTTP transport.
+*/
+async function createGitHubClient(auth) {
+	if (auth.type !== "pat") throw new Error(`GitHub auth type "${auth.type}" is not yet supported. Phase 5.1 ships with "pat" only; "app" installation auth arrives in phase 5.2.`);
+	let OctokitCtor;
+	try {
+		({Octokit: OctokitCtor} = await import("@octokit/rest"));
+	} catch (error) {
+		throw new Error("@octokit/rest is required for the GitHubProvider but could not be loaded. Install it as a peer dependency: pnpm add @octokit/rest.", { cause: error });
+	}
+	return new OctokitCtor({ auth: auth.token });
+}
+/**
+* Factory for the full provider — instantiates an Octokit client and
+* wraps it in a `GitHubProvider`. Consumers who already hold an Octokit
+* instance (HTTP server injecting shared clients, tests, etc.) should
+* instantiate `GitHubProvider` directly instead.
+*/
+async function createGitHubProvider(opts) {
+	return new GitHubProvider(await createGitHubClient(opts.auth), opts.repo);
+}
+//#endregion
+//#region src/providers/github/types.ts
+/** Default author used when a call does not provide one. */
+const DEFAULT_GITHUB_AUTHOR = {
+	name: "Contentrain",
+	email: "mcp@contentrain.io"
+};
+//#endregion
+export { DEFAULT_GITHUB_AUTHOR, GITHUB_CAPABILITIES, GitHubProvider, GitHubReader, createGitHubClient, createGitHubProvider };
+
+//# sourceMappingURL=index.mjs.map