@thallylabs/mcp 0.10.21 → 0.10.23

package/dist/track.d.ts

@@ -1,10 +1,16 @@
+/** The legacy docs-agent branch namespace. Retained for API compatibility. */
+declare const AGENT_BRANCH_PREFIX = "thally/agent-";
 /**
- * The branch prefix the docs agent stamps on its own PRs (`run.ts` creates
- * `thally/agent-<base36>`). Track's loop guard ignores PRs from these branches so a
- * self-tracking repo never chases its own agent PRs. Single source of truth for
- * the webhook relay, the scaffolded Actions workflow, and the producer.
+ * Every branch namespace authored by a Track-controlled writer.
+ *
+ * Intake must ignore all of these namespaces. Otherwise a self-tracking docs
+ * repository can treat Track's own documentation pull request as a new product
+ * change and recursively create another run. Keep this list shared by Cloud,
+ * generated sender workflows, and any future Track producer.
  */
-declare const AGENT_BRANCH_PREFIX = "thally/agent-";
+declare const TRACK_OWNED_BRANCH_PREFIXES: readonly ["thally/agent-", "thally/track-vnext/"];
+/** Return whether a branch or full `refs/heads/` ref belongs to Track. */
+declare function isTrackOwnedBranch(ref: string | null | undefined): boolean;
 /** Label that turns an OPEN PR into a preview-docs request (shared by the
  * webhook relay and the scaffolded sender workflow). */
 declare const DOCS_PREVIEW_LABEL = "docs-preview";
@@ -123,11 +129,11 @@ declare const TRACK_CONTEXT_CHAR_CAP = 20000;
  * The instruction frames the agent's actual job: judge what user-facing
  * behavior the merged PR changed and update the docs that describe it.
  */
-declare function buildTrackInstruction(repo: TrackedRepoLike, pr: Pick<PullRequestInfo, 'number'>, options?: {
+declare function buildTrackInstruction(repo: TrackedRepoLike, pr: Pick<PullRequestInfo, "number">, options?: {
     preview?: boolean;
 }): string;
 /** The capped markdown context for a merged tracked PR (title, body, file diffs). */
-declare function buildTrackContext(repo: Pick<TrackedRepoLike, 'owner' | 'repo'>, pr: PullRequestInfo, files: Array<PrFile>): string;
+declare function buildTrackContext(repo: Pick<TrackedRepoLike, "owner" | "repo">, pr: PullRequestInfo, files: Array<PrFile>): string;
 /**
  * Distill a merged PR into the docs task the agent runs: a one-line instruction
  * (output routing) and a capped markdown context (PR description + diff).
@@ -137,4 +143,4 @@ declare function buildTrackTask(repo: TrackedRepoLike, pr: PullRequestInfo, file
     context: string;
 };
 
-export { AGENT_BRANCH_PREFIX, DOCS_PREVIEW_LABEL, type GithubAppCreds, type GithubFetchOptions, type OwnerRepoRef, type PrFile, type PullRequestInfo, TRACK_CONTEXT_CHAR_CAP, type TrackedRepoLike, buildTrackContext, buildTrackInstruction, buildTrackTask, createAppJwt, fetchLatestMergedPr, fetchPullRequest, fetchPullRequestFiles, filterFilesByGlobs, matchesGlob, mintInstallationToken, parseOwnerRepo, resolveGithubToken, verifyInstallationBelongsToApp };
+export { AGENT_BRANCH_PREFIX, DOCS_PREVIEW_LABEL, type GithubAppCreds, type GithubFetchOptions, type OwnerRepoRef, type PrFile, type PullRequestInfo, TRACK_CONTEXT_CHAR_CAP, TRACK_OWNED_BRANCH_PREFIXES, type TrackedRepoLike, buildTrackContext, buildTrackInstruction, buildTrackTask, createAppJwt, fetchLatestMergedPr, fetchPullRequest, fetchPullRequestFiles, filterFilesByGlobs, isTrackOwnedBranch, matchesGlob, mintInstallationToken, parseOwnerRepo, resolveGithubToken, verifyInstallationBelongsToApp };

package/dist/track.js

@@ -1,16 +1,38 @@
 // src/lib/track.ts
 import { createSign, createHash } from "crypto";
 var AGENT_BRANCH_PREFIX = "thally/agent-";
+var TRACK_OWNED_BRANCH_PREFIXES = [
+  AGENT_BRANCH_PREFIX,
+  "thally/track-vnext/"
+];
+function isTrackOwnedBranch(ref) {
+  if (typeof ref !== "string") return false;
+  const branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+  return TRACK_OWNED_BRANCH_PREFIXES.some(
+    (prefix) => branch.startsWith(prefix)
+  );
+}
 var DOCS_PREVIEW_LABEL = "docs-preview";
 function parseOwnerRepo(spec) {
   const trimmed = spec.trim();
   const url = trimmed.match(
     /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:\/pull\/(\d+))?(?:[/#?].*)?$/i
   );
-  if (url) return { owner: url[1], repo: url[2], ...url[3] ? { pr: Number(url[3]) } : {} };
-  const plain = trimmed.match(/^([A-Za-z0-9-_.]+)\/([A-Za-z0-9-_.]+?)(?:#(\d+))?$/);
+  if (url)
+    return {
+      owner: url[1],
+      repo: url[2],
+      ...url[3] ? { pr: Number(url[3]) } : {}
+    };
+  const plain = trimmed.match(
+    /^([A-Za-z0-9-_.]+)\/([A-Za-z0-9-_.]+?)(?:#(\d+))?$/
+  );
   if (!plain) return null;
-  return { owner: plain[1], repo: plain[2], ...plain[3] ? { pr: Number(plain[3]) } : {} };
+  return {
+    owner: plain[1],
+    repo: plain[2],
+    ...plain[3] ? { pr: Number(plain[3]) } : {}
+  };
 }
 function base64url(input) {
   return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -19,8 +41,12 @@ var installationTokenCache = /* @__PURE__ */ new Map();
 function createAppJwt(appId, privateKey) {
   const now = Math.floor(Date.now() / 1e3);
   const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
-  const payload = base64url(JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: String(appId) }));
-  const signature = base64url(createSign("RSA-SHA256").update(`${header}.${payload}`).sign(privateKey));
+  const payload = base64url(
+    JSON.stringify({ iat: now - 60, exp: now + 9 * 60, iss: String(appId) })
+  );
+  const signature = base64url(
+    createSign("RSA-SHA256").update(`${header}.${payload}`).sign(privateKey)
+  );
   return `${header}.${payload}.${signature}`;
 }
 async function mintInstallationToken(creds, fetchImpl = fetch) {
@@ -29,12 +55,20 @@ async function mintInstallationToken(creds, fetchImpl = fetch) {
   const cached = installationTokenCache.get(cacheKey);
   if (cached && cached.expiresAtMs - 6e4 > Date.now()) return cached.token;
   const jwt = createAppJwt(creds.appId, creds.privateKey);
-  const res = await fetchImpl(`https://api.github.com/app/installations/${creds.installationId}/access_tokens`, {
-    method: "POST",
-    headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${jwt}` }
-  });
+  const res = await fetchImpl(
+    `https://api.github.com/app/installations/${creds.installationId}/access_tokens`,
+    {
+      method: "POST",
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${jwt}`
+      }
+    }
+  );
   if (!res.ok) {
-    throw new Error(`GitHub App token exchange failed (${res.status}) \u2014 check the app id, installation id, and private key.`);
+    throw new Error(
+      `GitHub App token exchange failed (${res.status}) \u2014 check the app id, installation id, and private key.`
+    );
   }
   const body = await res.json();
   const parsed = Date.parse(body.expires_at);
@@ -44,9 +78,15 @@ async function mintInstallationToken(creds, fetchImpl = fetch) {
 }
 async function verifyInstallationBelongsToApp(appId, privateKey, installationId, fetchImpl = fetch) {
   const jwt = createAppJwt(appId, privateKey);
-  const res = await fetchImpl(`https://api.github.com/app/installations/${installationId}`, {
-    headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${jwt}` }
-  });
+  const res = await fetchImpl(
+    `https://api.github.com/app/installations/${installationId}`,
+    {
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${jwt}`
+      }
+    }
+  );
   if (!res.ok) return false;
   const body = await res.json();
   return String(body.app_id) === String(appId);
@@ -55,7 +95,8 @@ function envAppCreds() {
   const appId = (process.env.THALLY_GITHUB_APP_ID ?? process.env.DOX_GITHUB_APP_ID)?.trim();
   const installationId = (process.env.THALLY_GITHUB_APP_INSTALLATION_ID ?? process.env.DOX_GITHUB_APP_INSTALLATION_ID)?.trim();
   const privateKey = process.env.THALLY_GITHUB_APP_PRIVATE_KEY ?? process.env.DOX_GITHUB_APP_PRIVATE_KEY;
-  if (appId && installationId && privateKey) return { appId, installationId, privateKey };
+  if (appId && installationId && privateKey)
+    return { appId, installationId, privateKey };
   return void 0;
 }
 async function resolveGithubToken(options) {
@@ -66,7 +107,9 @@ async function resolveGithubToken(options) {
     try {
       return await mintInstallationToken(appCreds, options?.fetchImpl ?? fetch);
     } catch (err) {
-      console.warn(`[thally-track] GitHub App token mint failed, falling back to PAT: ${err instanceof Error ? err.message : String(err)}`);
+      console.warn(
+        `[thally-track] GitHub App token mint failed, falling back to PAT: ${err instanceof Error ? err.message : String(err)}`
+      );
       return pat;
     }
   }
@@ -75,9 +118,13 @@ async function resolveGithubToken(options) {
 async function githubJson(path, options) {
   const fetchImpl = options?.fetchImpl ?? fetch;
   const token = await resolveGithubToken(options);
-  const headers = { Accept: "application/vnd.github+json" };
+  const headers = {
+    Accept: "application/vnd.github+json"
+  };
   if (token) headers.Authorization = `Bearer ${token}`;
-  const response = await fetchImpl(`https://api.github.com${path}`, { headers });
+  const response = await fetchImpl(`https://api.github.com${path}`, {
+    headers
+  });
   if (!response.ok) {
     const hint = response.status === 404 || response.status === 403 ? " (private repo or rate limit? set THALLY_GITHUB_TOKEN or connect a GitHub App)" : "";
     throw new Error(`GitHub API ${response.status} for ${path}${hint}`);
@@ -96,7 +143,10 @@ function toPullRequestInfo(raw) {
   };
 }
 async function fetchPullRequest(owner, repo, number, options) {
-  const raw = await githubJson(`/repos/${owner}/${repo}/pulls/${number}`, options);
+  const raw = await githubJson(
+    `/repos/${owner}/${repo}/pulls/${number}`,
+    options
+  );
   return toPullRequestInfo(raw);
 }
 async function fetchPullRequestFiles(owner, repo, number, options) {
@@ -104,7 +154,10 @@ async function fetchPullRequestFiles(owner, repo, number, options) {
   const maxPages = 30;
   const raw = [];
   for (let page = 1; page <= maxPages; page++) {
-    const chunk = await githubJson(`/repos/${owner}/${repo}/pulls/${number}/files?per_page=${perPage}&page=${page}`, options);
+    const chunk = await githubJson(
+      `/repos/${owner}/${repo}/pulls/${number}/files?per_page=${perPage}&page=${page}`,
+      options
+    );
     raw.push(...chunk);
     if (chunk.length < perPage) break;
   }
@@ -121,7 +174,9 @@ async function fetchLatestMergedPr(owner, repo, base, options) {
     `/repos/${owner}/${repo}/pulls?state=closed&base=${encodeURIComponent(base)}&sort=updated&direction=desc&per_page=30`,
     options
   );
-  const merged = raw.filter((pr) => Boolean(pr.merged_at)).sort((a, b) => Date.parse(b.merged_at ?? "") - Date.parse(a.merged_at ?? ""))[0];
+  const merged = raw.filter((pr) => Boolean(pr.merged_at)).sort(
+    (a, b) => Date.parse(b.merged_at ?? "") - Date.parse(a.merged_at ?? "")
+  )[0];
   return merged ? toPullRequestInfo(merged) : null;
 }
 function compileGlob(pattern) {
@@ -197,12 +252,16 @@ _(diff truncated \u2014 ${files.length} file(s) total)_
   return context.slice(0, TRACK_CONTEXT_CHAR_CAP);
 }
 function buildTrackTask(repo, pr, files) {
-  return { instruction: buildTrackInstruction(repo, pr), context: buildTrackContext(repo, pr, files) };
+  return {
+    instruction: buildTrackInstruction(repo, pr),
+    context: buildTrackContext(repo, pr, files)
+  };
 }
 export {
   AGENT_BRANCH_PREFIX,
   DOCS_PREVIEW_LABEL,
   TRACK_CONTEXT_CHAR_CAP,
+  TRACK_OWNED_BRANCH_PREFIXES,
   buildTrackContext,
   buildTrackInstruction,
   buildTrackTask,
@@ -211,6 +270,7 @@ export {
   fetchPullRequest,
   fetchPullRequestFiles,
   filterFilesByGlobs,
+  isTrackOwnedBranch,
   matchesGlob,
   mintInstallationToken,
   parseOwnerRepo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thallylabs/mcp",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "description": "MCP server for managing Thally knowledge surfaces and tracing product changes into documentation work.",
   "type": "module",
   "engines": {
@@ -38,7 +38,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.36.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
-    "create-thally-docs": "0.10.20",
+    "create-thally-docs": "0.10.21",
     "gray-matter": "^4.0.3",
     "p-limit": "^6.1.0",
     "yaml": "^2.8.2",