@theokit/sdk-tools 0.27.5 → 0.28.0

package/dist/github-link-preview.cjs

@@ -0,0 +1,227 @@
+'use strict';
+
+var sdk = require('@theokit/sdk');
+var zod = require('zod');
+
+// src/github-link-preview.ts
+var API_BASE = "https://api.github.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_SUMMARY_CHARS = 500;
+var MAX_BODY_BYTES = 1048576;
+var GITHUB_HOSTS = /* @__PURE__ */ new Set(["github.com", "www.github.com"]);
+var OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+var REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
+var NUMBER_PATTERN = /^[1-9][0-9]{0,9}$/;
+var PreviewFailure = class extends Error {
+  constructor(error, extra = {}) {
+    super(error);
+    this.error = error;
+    this.extra = extra;
+  }
+  error;
+  extra;
+};
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(
+      `createGithubLinkPreviewTool: ${name} must be a positive integer, got ${value}`
+    );
+  }
+  return value;
+}
+function hasControlCharacter(text) {
+  return Array.from(text).some((char) => {
+    const code = char.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+function requireValidToken(token) {
+  if (token.trim() === "" || hasControlCharacter(token)) {
+    throw new RangeError(
+      "createGithubLinkPreviewTool: token must be non-blank and free of control characters"
+    );
+  }
+  return token;
+}
+function buildHeaders(token) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "theokit-sdk-tools",
+    "x-github-api-version": "2022-11-28"
+  };
+  if (token !== void 0) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+function isGithubOrigin(parsed) {
+  return parsed.protocol === "https:" && GITHUB_HOSTS.has(parsed.hostname) && parsed.username === "" && parsed.password === "" && parsed.port === "";
+}
+var SECTION_KINDS = {
+  issues: "issue",
+  pull: "pull_request"
+};
+function isValidRepository(owner, repo) {
+  return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo) && repo !== "." && repo !== "..";
+}
+function numberedTarget(owner, repo, segments) {
+  const [, , section = "", number = ""] = segments;
+  const kind = Object.hasOwn(SECTION_KINDS, section) ? SECTION_KINDS[section] : void 0;
+  if (segments.length !== 4 || kind === void 0 || !NUMBER_PATTERN.test(number)) return void 0;
+  return { kind, owner, repo, number };
+}
+function targetFromSegments(segments) {
+  const [owner = "", repo = ""] = segments;
+  if (!isValidRepository(owner, repo)) return void 0;
+  if (segments.length === 2) return { kind: "repository", owner, repo };
+  return numberedTarget(owner, repo, segments);
+}
+function parseGithubUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return void 0;
+  }
+  if (!isGithubOrigin(parsed)) return void 0;
+  const segments = parsed.pathname.split("/").slice(1);
+  if (segments.at(-1) === "") segments.pop();
+  return targetFromSegments(segments);
+}
+function apiUrlFor(target) {
+  const base = `${API_BASE}/repos/${target.owner}/${target.repo}`;
+  if (target.kind === "issue") return `${base}/issues/${target.number}`;
+  if (target.kind === "pull_request") return `${base}/pulls/${target.number}`;
+  return base;
+}
+function canonicalUrlFor(target) {
+  const base = `https://github.com/${target.owner}/${target.repo}`;
+  if (target.kind === "issue") return `${base}/issues/${target.number}`;
+  if (target.kind === "pull_request") return `${base}/pull/${target.number}`;
+  return base;
+}
+function retryAfterSeconds(headers, nowMs) {
+  const retryAfter = Number(headers.get("retry-after") ?? Number.NaN);
+  if (Number.isFinite(retryAfter)) return Math.max(0, Math.ceil(retryAfter));
+  const reset = Number(headers.get("x-ratelimit-reset") ?? Number.NaN);
+  if (Number.isFinite(reset)) return Math.max(0, Math.ceil(reset - nowMs / 1e3));
+  return void 0;
+}
+function isRateLimited(response) {
+  if (response.status !== 403 && response.status !== 429) return false;
+  return response.headers.get("x-ratelimit-remaining") === "0" || response.headers.has("retry-after");
+}
+function checkStatus(response, nowMs) {
+  const { status } = response;
+  if (status >= 200 && status < 300) return;
+  if (status >= 300 && status < 400) throw new PreviewFailure("redirect_blocked", { status });
+  if (status === 404) throw new PreviewFailure("not_found", { status });
+  if (isRateLimited(response)) {
+    const retry = retryAfterSeconds(response.headers, nowMs);
+    throw new PreviewFailure("rate_limited", {
+      status,
+      ...retry === void 0 ? {} : { retry_after_seconds: retry }
+    });
+  }
+  throw new PreviewFailure("upstream_error", { status });
+}
+async function readCappedJson(response) {
+  if (Number(response.headers.get("content-length") ?? 0) > MAX_BODY_BYTES) {
+    throw new PreviewFailure("invalid_response");
+  }
+  const text = await response.text();
+  if (Buffer.byteLength(text, "utf8") > MAX_BODY_BYTES) {
+    throw new PreviewFailure("invalid_response");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new PreviewFailure("invalid_response");
+  }
+}
+function cutCodePoints(text, max) {
+  if (typeof text !== "string") return "";
+  return Array.from(text).slice(0, max).join("");
+}
+function stateOf(target, body) {
+  if (target.kind === "repository") return body.archived === true ? "archived" : "active";
+  if (target.kind === "pull_request" && body.merged === true) return "merged";
+  if (typeof body.state !== "string") throw new PreviewFailure("invalid_response");
+  return body.state;
+}
+function mapPreview(target, body, maxSummaryChars) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new PreviewFailure("invalid_response");
+  }
+  const record = body;
+  const isRepository = target.kind === "repository";
+  const title = isRepository ? record.full_name : record.title;
+  if (typeof title !== "string") throw new PreviewFailure("invalid_response");
+  return {
+    ok: true,
+    kind: target.kind,
+    url: canonicalUrlFor(target),
+    title,
+    state: stateOf(target, record),
+    summary: cutCodePoints(isRepository ? record.description : record.body, maxSummaryChars)
+  };
+}
+function failureFor(err, timeoutMs) {
+  if (err instanceof PreviewFailure) return err;
+  const name = err?.name;
+  if (name === "AbortError" || name === "TimeoutError") {
+    return new PreviewFailure("timeout", { timeout_ms: timeoutMs });
+  }
+  return new PreviewFailure("fetch_failed", {
+    error_name: typeof name === "string" ? name : "unknown"
+  });
+}
+async function fetchPreview(target, settings) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), settings.timeoutMs);
+  try {
+    const response = await settings.fetchImpl(apiUrlFor(target), {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: settings.headers
+    });
+    checkStatus(response, settings.now());
+    const body = await readCappedJson(response);
+    return mapPreview(target, body, settings.maxSummaryChars);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function preview(url, settings) {
+  const target = parseGithubUrl(url);
+  if (target === void 0) return { ok: false, error: "unsupported_url", url };
+  try {
+    return await fetchPreview(target, settings);
+  } catch (err) {
+    const failure = failureFor(err, settings.timeoutMs);
+    return { ok: false, error: failure.error, url, ...failure.extra };
+  }
+}
+function createGithubLinkPreviewTool(opts) {
+  const settings = {
+    fetchImpl: opts?.fetchImpl ?? fetch,
+    headers: buildHeaders(opts?.token === void 0 ? void 0 : requireValidToken(opts.token)),
+    timeoutMs: requirePositiveInteger("timeoutMs", opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    maxSummaryChars: requirePositiveInteger(
+      "maxSummaryChars",
+      opts?.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS
+    ),
+    now: opts?.now ?? Date.now
+  };
+  return sdk.Tool.create({
+    name: opts?.name ?? "github_link_preview",
+    description: opts?.description ?? "Preview a GitHub issue, pull request or repository from its github.com URL. Returns { ok, kind, url, title, state, summary } where state is open/closed/merged for issues and pull requests and active/archived for repositories, or { ok: false, error }. Only https://github.com/<owner>/<repo>, .../issues/<n> and .../pull/<n> are accepted.",
+    inputSchema: zod.z.object({
+      url: zod.z.string().min(1).describe("A github.com repository, issue or pull request URL.")
+    }),
+    handler: async ({ url }) => JSON.stringify(await preview(url, settings))
+  });
+}
+
+exports.createGithubLinkPreviewTool = createGithubLinkPreviewTool;
+//# sourceMappingURL=github-link-preview.cjs.map
+//# sourceMappingURL=github-link-preview.cjs.map

package/dist/github-link-preview.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/github-link-preview.ts"],"names":["Tool","z"],"mappings":"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","file":"github-link-preview.cjs","sourcesContent":["/**\n * `github_link_preview` — turn a github.com issue, pull request or repository URL into its title,\n * state and summary.\n *\n * The model's URL is parsed, never fetched: owner, repository and number are validated against\n * GitHub's own name charset and the request always goes to a fixed `https://api.github.com`\n * endpoint built from those parts (ADR D1). Redirects are refused, so a response can never choose\n * the next host or carry the bearer token elsewhere (ADR D2).\n *\n * Return shape (always a JSON string):\n *   - `{ ok: true, kind, url, title, state, summary }`\n *   - `{ ok: false, error: 'unsupported_url' | 'redirect_blocked' | 'not_found' | 'rate_limited' |\n *        'upstream_error' | 'timeout' | 'fetch_failed' | 'invalid_response', url, ... }`\n */\n\nimport type { CustomTool } from \"@theokit/sdk\";\n\nimport { Tool } from \"@theokit/sdk\";\nimport { z } from \"zod\";\n\nconst API_BASE = \"https://api.github.com\";\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_SUMMARY_CHARS = 500;\nconst MAX_BODY_BYTES = 1_048_576;\nconst GITHUB_HOSTS = new Set([\"github.com\", \"www.github.com\"]);\nconst OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;\nconst REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;\nconst NUMBER_PATTERN = /^[1-9][0-9]{0,9}$/;\n\n/** What a previewed GitHub URL points at, taken from its path. */\nexport type GithubLinkKind = \"repository\" | \"issue\" | \"pull_request\";\n\n/** Options for {@link createGithubLinkPreviewTool}; every one is optional. */\nexport interface CreateGithubLinkPreviewToolOptions {\n  /** Fetch implementation with the global `fetch` signature (injectable for tests). */\n  fetchImpl?: typeof fetch;\n  /** Optional GitHub token, sent as `Authorization: Bearer` to api.github.com only. */\n  token?: string;\n  /** Name exposed to the model. Default `github_link_preview`. */\n  name?: string;\n  /** Description exposed to the model. */\n  description?: string;\n  /** Timeout covering the request and the body read, in ms. Default 10000. */\n  timeoutMs?: number;\n  /** Longest summary returned, in code points. Default 500. */\n  maxSummaryChars?: number;\n  /** Clock for `retry_after_seconds` (injectable for tests). Default `Date.now`. */\n  now?: () => number;\n}\n\n/** The JSON the `github_link_preview` tool returns: a preview, or a typed failure. */\nexport type GithubLinkPreviewResult =\n  | {\n      ok: true;\n      kind: GithubLinkKind;\n      url: string;\n      title: string;\n      state: string;\n      summary: string;\n    }\n  | {\n      ok: false;\n      error:\n        | \"unsupported_url\"\n        | \"redirect_blocked\"\n        | \"not_found\"\n        | \"rate_limited\"\n        | \"upstream_error\"\n        | \"timeout\"\n        | \"fetch_failed\"\n        | \"invalid_response\";\n      url: string;\n      status?: number;\n      retry_after_seconds?: number;\n      timeout_ms?: number;\n      error_name?: string;\n    };\n\ninterface GithubTarget {\n  kind: GithubLinkKind;\n  owner: string;\n  repo: string;\n  number?: string;\n}\n\ninterface Settings {\n  fetchImpl: typeof fetch;\n  headers: Record<string, string>;\n  timeoutMs: number;\n  maxSummaryChars: number;\n  now: () => number;\n}\n\ntype Failure = Extract<GithubLinkPreviewResult, { ok: false }>;\ntype FailureError = Failure[\"error\"];\n\nclass PreviewFailure extends Error {\n  constructor(\n    readonly error: FailureError,\n    readonly extra: Omit<Failure, \"ok\" | \"error\" | \"url\"> = {},\n  ) {\n    super(error);\n  }\n}\n\nfunction requirePositiveInteger(name: string, value: number): number {\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new RangeError(\n      `createGithubLinkPreviewTool: ${name} must be a positive integer, got ${value}`,\n    );\n  }\n  return value;\n}\n\nfunction hasControlCharacter(text: string): boolean {\n  return Array.from(text).some((char) => {\n    const code = char.charCodeAt(0);\n    return code < 0x20 || code === 0x7f;\n  });\n}\n\nfunction requireValidToken(token: string): string {\n  if (token.trim() === \"\" || hasControlCharacter(token)) {\n    throw new RangeError(\n      \"createGithubLinkPreviewTool: token must be non-blank and free of control characters\",\n    );\n  }\n  return token;\n}\n\nfunction buildHeaders(token: string | undefined): Record<string, string> {\n  const headers: Record<string, string> = {\n    accept: \"application/vnd.github+json\",\n    \"user-agent\": \"theokit-sdk-tools\",\n    \"x-github-api-version\": \"2022-11-28\",\n  };\n  if (token !== undefined) headers.authorization = `Bearer ${token}`;\n  return headers;\n}\n\nfunction isGithubOrigin(parsed: URL): boolean {\n  return (\n    parsed.protocol === \"https:\" &&\n    GITHUB_HOSTS.has(parsed.hostname) &&\n    parsed.username === \"\" &&\n    parsed.password === \"\" &&\n    parsed.port === \"\"\n  );\n}\n\nconst SECTION_KINDS: Readonly<Record<string, GithubLinkKind>> = {\n  issues: \"issue\",\n  pull: \"pull_request\",\n};\n\nfunction isValidRepository(owner: string, repo: string): boolean {\n  return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo) && repo !== \".\" && repo !== \"..\";\n}\n\nfunction numberedTarget(owner: string, repo: string, segments: string[]): GithubTarget | undefined {\n  const [, , section = \"\", number = \"\"] = segments;\n  const kind = Object.hasOwn(SECTION_KINDS, section) ? SECTION_KINDS[section] : undefined;\n  if (segments.length !== 4 || kind === undefined || !NUMBER_PATTERN.test(number)) return undefined;\n  return { kind, owner, repo, number };\n}\n\nfunction targetFromSegments(segments: string[]): GithubTarget | undefined {\n  const [owner = \"\", repo = \"\"] = segments;\n  if (!isValidRepository(owner, repo)) return undefined;\n  if (segments.length === 2) return { kind: \"repository\", owner, repo };\n  return numberedTarget(owner, repo, segments);\n}\n\nfunction parseGithubUrl(url: string): GithubTarget | undefined {\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return undefined;\n  }\n  if (!isGithubOrigin(parsed)) return undefined;\n  const segments = parsed.pathname.split(\"/\").slice(1);\n  if (segments.at(-1) === \"\") segments.pop();\n  return targetFromSegments(segments);\n}\n\nfunction apiUrlFor(target: GithubTarget): string {\n  const base = `${API_BASE}/repos/${target.owner}/${target.repo}`;\n  if (target.kind === \"issue\") return `${base}/issues/${target.number}`;\n  if (target.kind === \"pull_request\") return `${base}/pulls/${target.number}`;\n  return base;\n}\n\nfunction canonicalUrlFor(target: GithubTarget): string {\n  const base = `https://github.com/${target.owner}/${target.repo}`;\n  if (target.kind === \"issue\") return `${base}/issues/${target.number}`;\n  if (target.kind === \"pull_request\") return `${base}/pull/${target.number}`;\n  return base;\n}\n\n// `retry-after` is read as delta-seconds only; an HTTP-date value falls through to the epoch reset.\nfunction retryAfterSeconds(headers: Headers, nowMs: number): number | undefined {\n  const retryAfter = Number(headers.get(\"retry-after\") ?? Number.NaN);\n  if (Number.isFinite(retryAfter)) return Math.max(0, Math.ceil(retryAfter));\n  const reset = Number(headers.get(\"x-ratelimit-reset\") ?? Number.NaN);\n  if (Number.isFinite(reset)) return Math.max(0, Math.ceil(reset - nowMs / 1000));\n  return undefined;\n}\n\nfunction isRateLimited(response: Response): boolean {\n  if (response.status !== 403 && response.status !== 429) return false;\n  return (\n    response.headers.get(\"x-ratelimit-remaining\") === \"0\" || response.headers.has(\"retry-after\")\n  );\n}\n\nfunction checkStatus(response: Response, nowMs: number): void {\n  const { status } = response;\n  if (status >= 200 && status < 300) return;\n  if (status >= 300 && status < 400) throw new PreviewFailure(\"redirect_blocked\", { status });\n  if (status === 404) throw new PreviewFailure(\"not_found\", { status });\n  if (isRateLimited(response)) {\n    const retry = retryAfterSeconds(response.headers, nowMs);\n    throw new PreviewFailure(\"rate_limited\", {\n      status,\n      ...(retry === undefined ? {} : { retry_after_seconds: retry }),\n    });\n  }\n  throw new PreviewFailure(\"upstream_error\", { status });\n}\n\nasync function readCappedJson(response: Response): Promise<unknown> {\n  if (Number(response.headers.get(\"content-length\") ?? 0) > MAX_BODY_BYTES) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  const text = await response.text();\n  if (Buffer.byteLength(text, \"utf8\") > MAX_BODY_BYTES) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n}\n\nfunction cutCodePoints(text: unknown, max: number): string {\n  if (typeof text !== \"string\") return \"\";\n  return Array.from(text).slice(0, max).join(\"\");\n}\n\nfunction stateOf(target: GithubTarget, body: Record<string, unknown>): string {\n  if (target.kind === \"repository\") return body.archived === true ? \"archived\" : \"active\";\n  if (target.kind === \"pull_request\" && body.merged === true) return \"merged\";\n  if (typeof body.state !== \"string\") throw new PreviewFailure(\"invalid_response\");\n  return body.state;\n}\n\nfunction mapPreview(\n  target: GithubTarget,\n  body: unknown,\n  maxSummaryChars: number,\n): GithubLinkPreviewResult {\n  if (typeof body !== \"object\" || body === null || Array.isArray(body)) {\n    throw new PreviewFailure(\"invalid_response\");\n  }\n  const record = body as Record<string, unknown>;\n  const isRepository = target.kind === \"repository\";\n  const title = isRepository ? record.full_name : record.title;\n  if (typeof title !== \"string\") throw new PreviewFailure(\"invalid_response\");\n  return {\n    ok: true,\n    kind: target.kind,\n    url: canonicalUrlFor(target),\n    title,\n    state: stateOf(target, record),\n    summary: cutCodePoints(isRepository ? record.description : record.body, maxSummaryChars),\n  };\n}\n\nfunction failureFor(err: unknown, timeoutMs: number): PreviewFailure {\n  if (err instanceof PreviewFailure) return err;\n  const name = (err as { name?: unknown } | null)?.name;\n  if (name === \"AbortError\" || name === \"TimeoutError\") {\n    return new PreviewFailure(\"timeout\", { timeout_ms: timeoutMs });\n  }\n  return new PreviewFailure(\"fetch_failed\", {\n    error_name: typeof name === \"string\" ? name : \"unknown\",\n  });\n}\n\nasync function fetchPreview(\n  target: GithubTarget,\n  settings: Settings,\n): Promise<GithubLinkPreviewResult> {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), settings.timeoutMs);\n  try {\n    const response = await settings.fetchImpl(apiUrlFor(target), {\n      method: \"GET\",\n      redirect: \"manual\",\n      signal: controller.signal,\n      headers: settings.headers,\n    });\n    checkStatus(response, settings.now());\n    const body = await readCappedJson(response);\n    return mapPreview(target, body, settings.maxSummaryChars);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\nasync function preview(url: string, settings: Settings): Promise<GithubLinkPreviewResult> {\n  const target = parseGithubUrl(url);\n  if (target === undefined) return { ok: false, error: \"unsupported_url\", url };\n  try {\n    return await fetchPreview(target, settings);\n  } catch (err) {\n    const failure = failureFor(err, settings.timeoutMs);\n    return { ok: false, error: failure.error, url, ...failure.extra };\n  }\n}\n\n/**\n * Build the `github_link_preview` tool. Every option is optional: `createGithubLinkPreviewTool()`\n * previews public objects anonymously with a 10-second timeout and a 500-character summary.\n *\n * Only three URL shapes are accepted: `https://github.com/<owner>/<repo>`,\n * `.../issues/<n>` and `.../pull/<n>` (also on `www.github.com`; a trailing slash, query or\n * fragment is ignored). Anything else is `unsupported_url` and makes no request.\n *\n * Throws `RangeError` at construction for a non-positive or fractional `timeoutMs` or\n * `maxSummaryChars`, and for a blank token or one with a control character. Every failure after\n * construction is a typed `{ ok: false, error }` result, never a throw. The token is never\n * echoed: error bodies are not returned, and `fetch_failed` carries only the error's name.\n */\nexport function createGithubLinkPreviewTool(opts?: CreateGithubLinkPreviewToolOptions): CustomTool {\n  const settings: Settings = {\n    fetchImpl: opts?.fetchImpl ?? fetch,\n    headers: buildHeaders(opts?.token === undefined ? undefined : requireValidToken(opts.token)),\n    timeoutMs: requirePositiveInteger(\"timeoutMs\", opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS),\n    maxSummaryChars: requirePositiveInteger(\n      \"maxSummaryChars\",\n      opts?.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS,\n    ),\n    now: opts?.now ?? Date.now,\n  };\n\n  return Tool.create({\n    name: opts?.name ?? \"github_link_preview\",\n    description:\n      opts?.description ??\n      \"Preview a GitHub issue, pull request or repository from its github.com URL. Returns \" +\n        \"{ ok, kind, url, title, state, summary } where state is open/closed/merged for issues and \" +\n        \"pull requests and active/archived for repositories, or { ok: false, error }. Only \" +\n        \"https://github.com/<owner>/<repo>, .../issues/<n> and .../pull/<n> are accepted.\",\n    inputSchema: z.object({\n      url: z.string().min(1).describe(\"A github.com repository, issue or pull request URL.\"),\n    }),\n    handler: async ({ url }) => JSON.stringify(await preview(url, settings)),\n  });\n}\n"]}

package/dist/github-link-preview.d.cts

@@ -0,0 +1,69 @@
+import { CustomTool } from '@theokit/sdk';
+
+/**
+ * `github_link_preview` — turn a github.com issue, pull request or repository URL into its title,
+ * state and summary.
+ *
+ * The model's URL is parsed, never fetched: owner, repository and number are validated against
+ * GitHub's own name charset and the request always goes to a fixed `https://api.github.com`
+ * endpoint built from those parts (ADR D1). Redirects are refused, so a response can never choose
+ * the next host or carry the bearer token elsewhere (ADR D2).
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, kind, url, title, state, summary }`
+ *   - `{ ok: false, error: 'unsupported_url' | 'redirect_blocked' | 'not_found' | 'rate_limited' |
+ *        'upstream_error' | 'timeout' | 'fetch_failed' | 'invalid_response', url, ... }`
+ */
+
+/** What a previewed GitHub URL points at, taken from its path. */
+type GithubLinkKind = "repository" | "issue" | "pull_request";
+/** Options for {@link createGithubLinkPreviewTool}; every one is optional. */
+interface CreateGithubLinkPreviewToolOptions {
+    /** Fetch implementation with the global `fetch` signature (injectable for tests). */
+    fetchImpl?: typeof fetch;
+    /** Optional GitHub token, sent as `Authorization: Bearer` to api.github.com only. */
+    token?: string;
+    /** Name exposed to the model. Default `github_link_preview`. */
+    name?: string;
+    /** Description exposed to the model. */
+    description?: string;
+    /** Timeout covering the request and the body read, in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Longest summary returned, in code points. Default 500. */
+    maxSummaryChars?: number;
+    /** Clock for `retry_after_seconds` (injectable for tests). Default `Date.now`. */
+    now?: () => number;
+}
+/** The JSON the `github_link_preview` tool returns: a preview, or a typed failure. */
+type GithubLinkPreviewResult = {
+    ok: true;
+    kind: GithubLinkKind;
+    url: string;
+    title: string;
+    state: string;
+    summary: string;
+} | {
+    ok: false;
+    error: "unsupported_url" | "redirect_blocked" | "not_found" | "rate_limited" | "upstream_error" | "timeout" | "fetch_failed" | "invalid_response";
+    url: string;
+    status?: number;
+    retry_after_seconds?: number;
+    timeout_ms?: number;
+    error_name?: string;
+};
+/**
+ * Build the `github_link_preview` tool. Every option is optional: `createGithubLinkPreviewTool()`
+ * previews public objects anonymously with a 10-second timeout and a 500-character summary.
+ *
+ * Only three URL shapes are accepted: `https://github.com/<owner>/<repo>`,
+ * `.../issues/<n>` and `.../pull/<n>` (also on `www.github.com`; a trailing slash, query or
+ * fragment is ignored). Anything else is `unsupported_url` and makes no request.
+ *
+ * Throws `RangeError` at construction for a non-positive or fractional `timeoutMs` or
+ * `maxSummaryChars`, and for a blank token or one with a control character. Every failure after
+ * construction is a typed `{ ok: false, error }` result, never a throw. The token is never
+ * echoed: error bodies are not returned, and `fetch_failed` carries only the error's name.
+ */
+declare function createGithubLinkPreviewTool(opts?: CreateGithubLinkPreviewToolOptions): CustomTool;
+
+export { type CreateGithubLinkPreviewToolOptions, type GithubLinkKind, type GithubLinkPreviewResult, createGithubLinkPreviewTool };

package/dist/github-link-preview.d.ts

@@ -0,0 +1,69 @@
+import { CustomTool } from '@theokit/sdk';
+
+/**
+ * `github_link_preview` — turn a github.com issue, pull request or repository URL into its title,
+ * state and summary.
+ *
+ * The model's URL is parsed, never fetched: owner, repository and number are validated against
+ * GitHub's own name charset and the request always goes to a fixed `https://api.github.com`
+ * endpoint built from those parts (ADR D1). Redirects are refused, so a response can never choose
+ * the next host or carry the bearer token elsewhere (ADR D2).
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, kind, url, title, state, summary }`
+ *   - `{ ok: false, error: 'unsupported_url' | 'redirect_blocked' | 'not_found' | 'rate_limited' |
+ *        'upstream_error' | 'timeout' | 'fetch_failed' | 'invalid_response', url, ... }`
+ */
+
+/** What a previewed GitHub URL points at, taken from its path. */
+type GithubLinkKind = "repository" | "issue" | "pull_request";
+/** Options for {@link createGithubLinkPreviewTool}; every one is optional. */
+interface CreateGithubLinkPreviewToolOptions {
+    /** Fetch implementation with the global `fetch` signature (injectable for tests). */
+    fetchImpl?: typeof fetch;
+    /** Optional GitHub token, sent as `Authorization: Bearer` to api.github.com only. */
+    token?: string;
+    /** Name exposed to the model. Default `github_link_preview`. */
+    name?: string;
+    /** Description exposed to the model. */
+    description?: string;
+    /** Timeout covering the request and the body read, in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Longest summary returned, in code points. Default 500. */
+    maxSummaryChars?: number;
+    /** Clock for `retry_after_seconds` (injectable for tests). Default `Date.now`. */
+    now?: () => number;
+}
+/** The JSON the `github_link_preview` tool returns: a preview, or a typed failure. */
+type GithubLinkPreviewResult = {
+    ok: true;
+    kind: GithubLinkKind;
+    url: string;
+    title: string;
+    state: string;
+    summary: string;
+} | {
+    ok: false;
+    error: "unsupported_url" | "redirect_blocked" | "not_found" | "rate_limited" | "upstream_error" | "timeout" | "fetch_failed" | "invalid_response";
+    url: string;
+    status?: number;
+    retry_after_seconds?: number;
+    timeout_ms?: number;
+    error_name?: string;
+};
+/**
+ * Build the `github_link_preview` tool. Every option is optional: `createGithubLinkPreviewTool()`
+ * previews public objects anonymously with a 10-second timeout and a 500-character summary.
+ *
+ * Only three URL shapes are accepted: `https://github.com/<owner>/<repo>`,
+ * `.../issues/<n>` and `.../pull/<n>` (also on `www.github.com`; a trailing slash, query or
+ * fragment is ignored). Anything else is `unsupported_url` and makes no request.
+ *
+ * Throws `RangeError` at construction for a non-positive or fractional `timeoutMs` or
+ * `maxSummaryChars`, and for a blank token or one with a control character. Every failure after
+ * construction is a typed `{ ok: false, error }` result, never a throw. The token is never
+ * echoed: error bodies are not returned, and `fetch_failed` carries only the error's name.
+ */
+declare function createGithubLinkPreviewTool(opts?: CreateGithubLinkPreviewToolOptions): CustomTool;
+
+export { type CreateGithubLinkPreviewToolOptions, type GithubLinkKind, type GithubLinkPreviewResult, createGithubLinkPreviewTool };

package/dist/github-link-preview.js

@@ -0,0 +1,225 @@
+import { Tool } from '@theokit/sdk';
+import { z } from 'zod';
+
+// src/github-link-preview.ts
+var API_BASE = "https://api.github.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_SUMMARY_CHARS = 500;
+var MAX_BODY_BYTES = 1048576;
+var GITHUB_HOSTS = /* @__PURE__ */ new Set(["github.com", "www.github.com"]);
+var OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+var REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
+var NUMBER_PATTERN = /^[1-9][0-9]{0,9}$/;
+var PreviewFailure = class extends Error {
+  constructor(error, extra = {}) {
+    super(error);
+    this.error = error;
+    this.extra = extra;
+  }
+  error;
+  extra;
+};
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(
+      `createGithubLinkPreviewTool: ${name} must be a positive integer, got ${value}`
+    );
+  }
+  return value;
+}
+function hasControlCharacter(text) {
+  return Array.from(text).some((char) => {
+    const code = char.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+function requireValidToken(token) {
+  if (token.trim() === "" || hasControlCharacter(token)) {
+    throw new RangeError(
+      "createGithubLinkPreviewTool: token must be non-blank and free of control characters"
+    );
+  }
+  return token;
+}
+function buildHeaders(token) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "theokit-sdk-tools",
+    "x-github-api-version": "2022-11-28"
+  };
+  if (token !== void 0) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+function isGithubOrigin(parsed) {
+  return parsed.protocol === "https:" && GITHUB_HOSTS.has(parsed.hostname) && parsed.username === "" && parsed.password === "" && parsed.port === "";
+}
+var SECTION_KINDS = {
+  issues: "issue",
+  pull: "pull_request"
+};
+function isValidRepository(owner, repo) {
+  return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo) && repo !== "." && repo !== "..";
+}
+function numberedTarget(owner, repo, segments) {
+  const [, , section = "", number = ""] = segments;
+  const kind = Object.hasOwn(SECTION_KINDS, section) ? SECTION_KINDS[section] : void 0;
+  if (segments.length !== 4 || kind === void 0 || !NUMBER_PATTERN.test(number)) return void 0;
+  return { kind, owner, repo, number };
+}
+function targetFromSegments(segments) {
+  const [owner = "", repo = ""] = segments;
+  if (!isValidRepository(owner, repo)) return void 0;
+  if (segments.length === 2) return { kind: "repository", owner, repo };
+  return numberedTarget(owner, repo, segments);
+}
+function parseGithubUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return void 0;
+  }
+  if (!isGithubOrigin(parsed)) return void 0;
+  const segments = parsed.pathname.split("/").slice(1);
+  if (segments.at(-1) === "") segments.pop();
+  return targetFromSegments(segments);
+}
+function apiUrlFor(target) {
+  const base = `${API_BASE}/repos/${target.owner}/${target.repo}`;
+  if (target.kind === "issue") return `${base}/issues/${target.number}`;
+  if (target.kind === "pull_request") return `${base}/pulls/${target.number}`;
+  return base;
+}
+function canonicalUrlFor(target) {
+  const base = `https://github.com/${target.owner}/${target.repo}`;
+  if (target.kind === "issue") return `${base}/issues/${target.number}`;
+  if (target.kind === "pull_request") return `${base}/pull/${target.number}`;
+  return base;
+}
+function retryAfterSeconds(headers, nowMs) {
+  const retryAfter = Number(headers.get("retry-after") ?? Number.NaN);
+  if (Number.isFinite(retryAfter)) return Math.max(0, Math.ceil(retryAfter));
+  const reset = Number(headers.get("x-ratelimit-reset") ?? Number.NaN);
+  if (Number.isFinite(reset)) return Math.max(0, Math.ceil(reset - nowMs / 1e3));
+  return void 0;
+}
+function isRateLimited(response) {
+  if (response.status !== 403 && response.status !== 429) return false;
+  return response.headers.get("x-ratelimit-remaining") === "0" || response.headers.has("retry-after");
+}
+function checkStatus(response, nowMs) {
+  const { status } = response;
+  if (status >= 200 && status < 300) return;
+  if (status >= 300 && status < 400) throw new PreviewFailure("redirect_blocked", { status });
+  if (status === 404) throw new PreviewFailure("not_found", { status });
+  if (isRateLimited(response)) {
+    const retry = retryAfterSeconds(response.headers, nowMs);
+    throw new PreviewFailure("rate_limited", {
+      status,
+      ...retry === void 0 ? {} : { retry_after_seconds: retry }
+    });
+  }
+  throw new PreviewFailure("upstream_error", { status });
+}
+async function readCappedJson(response) {
+  if (Number(response.headers.get("content-length") ?? 0) > MAX_BODY_BYTES) {
+    throw new PreviewFailure("invalid_response");
+  }
+  const text = await response.text();
+  if (Buffer.byteLength(text, "utf8") > MAX_BODY_BYTES) {
+    throw new PreviewFailure("invalid_response");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new PreviewFailure("invalid_response");
+  }
+}
+function cutCodePoints(text, max) {
+  if (typeof text !== "string") return "";
+  return Array.from(text).slice(0, max).join("");
+}
+function stateOf(target, body) {
+  if (target.kind === "repository") return body.archived === true ? "archived" : "active";
+  if (target.kind === "pull_request" && body.merged === true) return "merged";
+  if (typeof body.state !== "string") throw new PreviewFailure("invalid_response");
+  return body.state;
+}
+function mapPreview(target, body, maxSummaryChars) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new PreviewFailure("invalid_response");
+  }
+  const record = body;
+  const isRepository = target.kind === "repository";
+  const title = isRepository ? record.full_name : record.title;
+  if (typeof title !== "string") throw new PreviewFailure("invalid_response");
+  return {
+    ok: true,
+    kind: target.kind,
+    url: canonicalUrlFor(target),
+    title,
+    state: stateOf(target, record),
+    summary: cutCodePoints(isRepository ? record.description : record.body, maxSummaryChars)
+  };
+}
+function failureFor(err, timeoutMs) {
+  if (err instanceof PreviewFailure) return err;
+  const name = err?.name;
+  if (name === "AbortError" || name === "TimeoutError") {
+    return new PreviewFailure("timeout", { timeout_ms: timeoutMs });
+  }
+  return new PreviewFailure("fetch_failed", {
+    error_name: typeof name === "string" ? name : "unknown"
+  });
+}
+async function fetchPreview(target, settings) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), settings.timeoutMs);
+  try {
+    const response = await settings.fetchImpl(apiUrlFor(target), {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: settings.headers
+    });
+    checkStatus(response, settings.now());
+    const body = await readCappedJson(response);
+    return mapPreview(target, body, settings.maxSummaryChars);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function preview(url, settings) {
+  const target = parseGithubUrl(url);
+  if (target === void 0) return { ok: false, error: "unsupported_url", url };
+  try {
+    return await fetchPreview(target, settings);
+  } catch (err) {
+    const failure = failureFor(err, settings.timeoutMs);
+    return { ok: false, error: failure.error, url, ...failure.extra };
+  }
+}
+function createGithubLinkPreviewTool(opts) {
+  const settings = {
+    fetchImpl: opts?.fetchImpl ?? fetch,
+    headers: buildHeaders(opts?.token === void 0 ? void 0 : requireValidToken(opts.token)),
+    timeoutMs: requirePositiveInteger("timeoutMs", opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    maxSummaryChars: requirePositiveInteger(
+      "maxSummaryChars",
+      opts?.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS
+    ),
+    now: opts?.now ?? Date.now
+  };
+  return Tool.create({
+    name: opts?.name ?? "github_link_preview",
+    description: opts?.description ?? "Preview a GitHub issue, pull request or repository from its github.com URL. Returns { ok, kind, url, title, state, summary } where state is open/closed/merged for issues and pull requests and active/archived for repositories, or { ok: false, error }. Only https://github.com/<owner>/<repo>, .../issues/<n> and .../pull/<n> are accepted.",
+    inputSchema: z.object({
+      url: z.string().min(1).describe("A github.com repository, issue or pull request URL.")
+    }),
+    handler: async ({ url }) => JSON.stringify(await preview(url, settings))
+  });
+}
+
+export { createGithubLinkPreviewTool };
+//# sourceMappingURL=github-link-preview.js.map
+//# sourceMappingURL=github-link-preview.js.map