Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

19.7 KB
Raw Blame
import type { CommandDefinition } from "./command-definition.js";
import { assertPositionals, bodySource, option } from "./command-input.js";
import {
  choice,
  pageInput,
  pageSchema,
  schema,
  stringSchema,
  text,
  usage,
} from "./connector-input.js";
import {
  connectorDefinition,
  cursor,
  nextCursor,
  optionalFields,
  record,
  requiredString,
  value,
  type ConnectorRuntime,
  type Json,
} from "./connector-runtime.js";
import { CliError, ConnectorError } from "./errors.js";
import { displayText } from "./display-text.js";
const descriptions = {
  me: "Read the profile of the connected GitHub account.",
  repos:
    "List repositories the connected account owns, collaborates on, or belongs to through an organization.",
  repo: "Read one repository and its README.",
  search: "Search issues and pull requests with GitHub search syntax.",
  read: "Read an issue or pull request with all its comments; a pull request also lists its changed files.",
  comment: "Comment on an issue or pull request.",
  "create-issue": "Create an issue in a repository.",
};
type Action = keyof typeof descriptions;
const repoSorts = ["updated", "pushed", "created", "full_name"];
// GitHub rejects longer comment and issue bodies.
const maxBody = 65536;
// Comments and changed files are read 100 at a time, up to this many pages.
const maxPages = 10;
// A README longer than this is cut, and reported as incomplete.
const maxReadme = 100000;
const issueTarget = {
  owner: stringSchema,
  repo: stringSchema,
  number: { type: "integer", minimum: 1 },
};
const bodies = {
  "--content": value("Markdown body; exclusive with --file."),
  "--file": value("UTF-8 Markdown body file; - reads stdin."),
};
export const githubCommandDefinitions: CommandDefinition[] = (
  Object.keys(descriptions) as Action[]
).map((action) =>
  connectorDefinition({
    command: ["github", action],
    description: descriptions[action],
    readOnly: !["comment", "create-issue"].includes(action),
    options:
      action === "repos"
        ? {
            "--sort": value(
              "updated / pushed / created / full_name; default updated.",
            ),
            "--limit": value("1–100 items per page; default 20."),
            "--cursor": value("Cursor from the previous page."),
          }
        : action === "search"
          ? {
              "--limit": value("1–100 items per page; default 20."),
              "--cursor": value("Cursor from the previous page."),
            }
          : action === "comment"
            ? bodies
            : action === "create-issue"
              ? {
                  "--repo": value("Repository as owner/name or its link."),
                  "--title": value("Issue title."),
                  ...bodies,
                }
              : {},
    usage: [
      action === "repo"
        ? "teamhub github repo <owner/name|url> [flags]"
        : action === "search"
          ? "teamhub github search <query> [flags]"
          : action === "read"
            ? "teamhub github read <owner/name#number|url> [flags]"
            : action === "comment"
              ? "teamhub github comment <owner/name#number|url> (--content <text> | --file <path|->) [flags]"
              : action === "create-issue"
                ? "teamhub github create-issue --repo <owner/name|url> --title <text> [--content <text> | --file <path|->] [flags]"
                : `teamhub github ${action} [flags]`,
    ],
    examples:
      action === "repos"
        ? ["teamhub github repos --sort pushed --limit 50"]
        : action === "repo"
          ? ["teamhub github repo octo-org/api"]
          : action === "search"
            ? [
                "teamhub github search 'author:@me is:pr updated:>2026-08-01'",
                "teamhub github search 'repo:octo-org/api is:issue is:open label:bug'",
              ]
            : action === "read"
              ? [
                  "teamhub github read 'https://github.com/octo-org/api/pull/42'",
                ]
              : action === "comment"
                ? [
                    "teamhub github comment octo-org/api#42 --content 'Verified the fix on staging.'",
                  ]
                : action === "create-issue"
                  ? [
                      "teamhub github create-issue --repo octo-org/api --title 'Login fails after reset' --file ./issue.md",
                    ]
                  : ["teamhub github me"],
    notes:
      action === "search"
        ? [
            "GitHub returns at most the first 1,000 matches of a search; @me means the connected account.",
          ]
        : action === "read"
          ? [
              "Reads up to 1,000 comments and 1,000 changed files and reports whether each list is complete; review comments and diffs are out of scope.",
            ]
          : [],
    inputSchema:
      action === "repos"
        ? schema({ ...pageSchema, sort: { enum: repoSorts } })
        : action === "search"
          ? schema({ ...pageSchema, query: stringSchema }, ["query"])
          : action === "repo"
            ? schema({ owner: stringSchema, repo: stringSchema }, [
                "owner",
                "repo",
              ])
            : action === "read"
              ? schema(issueTarget, ["owner", "repo", "number"])
              : action === "comment"
                ? schema(
                    {
                      ...issueTarget,
                      content: { type: "string", maxLength: maxBody },
                    },
                    ["owner", "repo", "number", "content"],
                  )
                : action === "create-issue"
                  ? schema(
                      {
                        owner: stringSchema,
                        repo: stringSchema,
                        title: stringSchema,
                        content: { type: "string", maxLength: maxBody },
                      },
                      ["owner", "repo", "title"],
                    )
                  : schema({}),
    normalize: async (args, reader) => {
      const input: Json = {};
      if (action === "me") assertPositionals(args, 0);
      if (action === "repos") {
        assertPositionals(args, 0);
        Object.assign(input, pageInput(args));
        input.sort = choice(
          option(args, "--sort"),
          repoSorts,
          "--sort",
          "updated",
        );
      }
      if (action === "search") {
        assertPositionals(args, 1);
        Object.assign(input, pageInput(args));
        input.query = text(args.positionals[0], "query", 256);
      }
      if (action === "repo") {
        assertPositionals(args, 1);
        const found = githubTarget(
          text(args.positionals[0], "repository", 4096),
        );
        if (found.number !== undefined)
          usage("Use a repository, not an issue or pull request.");
        Object.assign(input, found);
      }
      if (action === "read" || action === "comment") {
        assertPositionals(args, 1);
        const found = githubTarget(
          text(args.positionals[0], "issue or pull request", 4096),
        );
        if (found.number === undefined)
          usage("Use an issue or pull request, such as owner/name#42.");
        Object.assign(input, found);
      }
      if (action === "create-issue") {
        assertPositionals(args, 0);
        const found = githubTarget(
          text(option(args, "--repo"), "--repo", 4096),
        );
        if (found.number !== undefined)
          usage("--repo takes a repository, not an issue or pull request.");
        Object.assign(input, found);
        input.title = text(option(args, "--title"), "--title", 256);
      }
      if (action === "comment" || action === "create-issue") {
        const body = await bodySource(args, reader, action === "comment");
        if (body !== undefined) {
          if ([...body].length > maxBody || body.includes("\u0000"))
            usage(
              `The body must be UTF-8 text of at most ${maxBody} characters.`,
            );
          if (action === "comment" && !body.trim())
            usage("Provide a nonblank comment.");
          input.content = body;
        }
      }
      return { input };
    },
    bindings: () =>
      ({
        me: ["GITHUB_GET_THE_AUTHENTICATED_USER"],
        repos: ["GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER"],
        repo: ["GITHUB_GET_A_REPOSITORY", "GITHUB_GET_A_REPOSITORY_README"],
        search: ["GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS"],
        read: [
          "GITHUB_GET_AN_ISSUE",
          "GITHUB_LIST_ISSUE_COMMENTS",
          "GITHUB_GET_A_PULL_REQUEST",
          "GITHUB_LIST_PULL_REQUESTS_FILES",
        ],
        comment: ["GITHUB_GET_AN_ISSUE", "GITHUB_CREATE_AN_ISSUE_COMMENT"],
        "create-issue": ["GITHUB_GET_A_REPOSITORY", "GITHUB_CREATE_AN_ISSUE"],
      })[action],
    execute: (input, runtime) => executeGitHub(action, input, runtime),
  }),
);
const ownerPattern = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/u;
const repoPattern = /^[A-Za-z0-9._-]{1,100}$/u;
/** Parses owner/name, owner/name#number, or a github.com link to either. */
function githubTarget(value: string): {
  owner: string;
  repo: string;
  number?: number;
} {
  let owner: string | undefined,
    repo: string | undefined,
    number: string | undefined;
  if (value.startsWith("https://")) {
    let url: URL;
    try {
      url = new URL(value);
    } catch {
      usage("Use a github.com link.");
    }
    if (
      !["github.com", "www.github.com"].includes(url!.hostname) ||
      url!.username ||
      url!.password ||
      url!.port
    )
      usage("Use a github.com repository, issue, or pull request link.");
    const parts = url!.pathname.split("/").filter(Boolean);
    [owner, repo] = parts;
    repo = repo?.replace(/\.git$/u, "");
    if (parts.length > 2) {
      if (!["issues", "pull"].includes(parts[2]!) || !parts[3])
        usage("Use a repository, issue, or pull request link.");
      number = parts[3];
    }
  } else {
    const match = /^([^/#]+)\/([^/#]+)(?:#(.+))?$/u.exec(value);
    if (!match)
      usage("Use owner/name, owner/name#number, or a github.com link.");
    [, owner, repo, number] = match!;
  }
  if (
    !owner ||
    !repo ||
    !ownerPattern.test(owner) ||
    !repoPattern.test(repo) ||
    repo === "." ||
    repo === ".."
  )
    usage("The repository owner or name is invalid.");
  if (number !== undefined && !/^[1-9]\d{0,9}$/u.test(number))
    usage("The issue or pull request number is invalid.");
  return {
    owner: owner!,
    repo: repo!,
    ...(number === undefined ? {} : { number: Number(number) }),
  };
}
function login(value: unknown): string | undefined {
  return value && typeof value === "object"
    ? (record(value).login as string | undefined)
    : undefined;
}
/** Composio wraps each GitHub list in an object under a tool-specific key. */
function rows(raw: Json, key: string): Json[] {
  const list = raw[key];
  if (!Array.isArray(list))
    throw new ConnectorError(
      "incomplete_response",
      `The GitHub response has no ${key} list.`,
    );
  return list.map((item) => record(item));
}
function githubUser(raw: Json): Json {
  return optionalFields({
    login: requiredString(raw.login, "GitHub login"),
    name: raw.name,
    bio: raw.bio,
    company: raw.company,
    blog: raw.blog || undefined,
    location: raw.location,
    email: raw.email,
    url: raw.html_url,
    publicRepos: raw.public_repos,
    followers: raw.followers,
    following: raw.following,
    createdAt: raw.created_at,
  });
}
function githubRepository(raw: Json): Json {
  return optionalFields({
    fullName: requiredString(raw.full_name, "repository name"),
    description: raw.description,
    url: raw.html_url,
    private: raw.private,
    fork: raw.fork,
    archived: raw.archived,
    language: raw.language,
    topics:
      Array.isArray(raw.topics) && raw.topics.length ? raw.topics : undefined,
    stars: raw.stargazers_count,
    forks: raw.forks_count,
    openIssues: raw.open_issues_count,
    defaultBranch: raw.default_branch,
    homepage: raw.homepage || undefined,
    pushedAt: raw.pushed_at,
    updatedAt: raw.updated_at,
  });
}
function repositoryOf(raw: Json): string {
  // Search results name their repository only by its API URL.
  const match = /\/repos\/([^/]+\/[^/]+)$/u.exec(String(raw.repository_url));
  return requiredString(match?.[1], "repository");
}
function githubIssue(raw: Json): Json {
  return optionalFields({
    repository: repositoryOf(raw),
    number: raw.number,
    kind: raw.pull_request ? "pull_request" : "issue",
    title: requiredString(raw.title, "title"),
    state: raw.state,
    stateReason: raw.state_reason,
    author: login(raw.user),
    url: raw.html_url,
    labels: Array.isArray(raw.labels)
      ? raw.labels
          .map((label) =>
            typeof label === "string" ? label : record(label).name,
          )
          .filter((name) => typeof name === "string")
      : undefined,
    assignees: Array.isArray(raw.assignees)
      ? raw.assignees.map(login).filter((name) => typeof name === "string")
      : undefined,
    commentCount: raw.comments,
    createdAt: raw.created_at,
    updatedAt: raw.updated_at,
    closedAt: raw.closed_at,
  });
}
function githubComment(raw: Json): Json {
  return optionalFields({
    commentId: String(raw.id),
    author: login(raw.user),
    body: raw.body ?? "",
    url: raw.html_url,
    createdAt: raw.created_at,
    updatedAt: raw.updated_at,
  });
}
/** Reads 100 rows a page until a short page or the page cap. */
async function allPages(
  load: (page: number) => Promise<Json>,
  key: string,
): Promise<{ rows: Json[]; complete: boolean }> {
  const result: Json[] = [];
  for (let page = 1; page <= maxPages; page++) {
    const found = rows(await load(page), key);
    result.push(...found);
    if (found.length < 100) return { rows: result, complete: true };
  }
  return { rows: result, complete: false };
}
async function executeGitHub(
  action: Action,
  input: Json,
  runtime: ConnectorRuntime,
): Promise<Json> {
  const where = { owner: input.owner, repo: input.repo };
  if (action === "me")
    return {
      user: githubUser(
        await runtime.call("GITHUB_GET_THE_AUTHENTICATED_USER", {}),
      ),
    };
  if (action === "repos" || action === "search") {
    const fp = {
      account: runtime.account.connection_id,
      action,
      query: input.query ?? "",
      sort: input.sort ?? "",
      limit: input.limit,
    };
    const page = cursor(input.cursor, fp).page ?? 1;
    if (!Number.isSafeInteger(page) || Number(page) < 1)
      throw new ConnectorError(
        "cursor_mismatch",
        "Use the returned cursor with the same account and filters.",
      );
    const limit = Number(input.limit);
    if (action === "repos") {
      const found = rows(
        await runtime.call(
          "GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER",
          {
            sort: input.sort,
            per_page: limit,
            page,
          },
        ),
        "repositories",
      );
      // The list reports no total; a full page may be followed by more.
      const hasMore = found.length === limit;
      return {
        repositories: found.map(githubRepository),
        hasMore,
        ...(hasMore
          ? { nextCursor: nextCursor({ page: Number(page) + 1 }, fp) }
          : {}),
      };
    }
    const raw = await runtime.call("GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS", {
      q: input.query,
      per_page: limit,
      page,
      response_detail: "full",
    });
    if (typeof raw.total_count !== "number")
      throw new ConnectorError(
        "incomplete_response",
        "The search result is incomplete.",
      );
    const hasMore = Number(page) * limit < Math.min(raw.total_count, 1000);
    return optionalFields({
      totalCount: raw.total_count,
      // GitHub stops a slow search early and says so.
      incomplete: raw.incomplete_results === true || undefined,
      items: rows(raw, "items").map(githubIssue),
      hasMore,
      ...(hasMore
        ? { nextCursor: nextCursor({ page: Number(page) + 1 }, fp) }
        : {}),
    });
  }
  if (action === "repo") {
    const repository = githubRepository(
      await runtime.call("GITHUB_GET_A_REPOSITORY", where),
    );
    let readme: Json;
    try {
      readme = githubReadme(
        await runtime.call("GITHUB_GET_A_REPOSITORY_README", where),
      );
    } catch (error) {
      // GitHub answers a repository without a README with Not Found, which
      // TeamHub reports as a failed provider call; anything else is real.
      if (
        !(error instanceof CliError) ||
        error.code !== "tool_execution_failed"
      )
        throw error;
      readme = { available: false };
    }
    return { repository: { ...repository, readme } };
  }
  if (action === "create-issue") {
    const repository = await runtime.call("GITHUB_GET_A_REPOSITORY", where);
    if (repository.has_issues === false)
      throw new ConnectorError(
        "unsupported_combination",
        "Issues are disabled in this repository.",
        { operation_rejected: true },
      );
    const created = await runtime.call(
      "GITHUB_CREATE_AN_ISSUE",
      optionalFields({ ...where, title: input.title, body: input.content }),
      true,
    );
    return {
      result: optionalFields({
        action: "issue_created",
        acknowledged: true,
        repository: `${String(input.owner)}/${String(input.repo)}`,
        number: created.number,
        url: created.html_url,
      }),
    };
  }
  const numbered = { ...where, issue_number: input.number };
  const issue = await runtime.call("GITHUB_GET_AN_ISSUE", numbered);
  if (action === "comment") {
    const created = await runtime.call(
      "GITHUB_CREATE_AN_ISSUE_COMMENT",
      { ...numbered, body: input.content },
      true,
    );
    return {
      result: optionalFields({
        action: "commented",
        acknowledged: true,
        repository: repositoryOf(issue),
        number: input.number,
        commentId:
          created.id === undefined ? undefined : displayText(created.id),
        url: created.html_url,
      }),
    };
  }
  const comments = await allPages(
    (page) =>
      runtime.call("GITHUB_LIST_ISSUE_COMMENTS", {
        ...numbered,
        per_page: 100,
        page,
      }),
    "comments",
  );
  const item: Json = {
    ...githubIssue(issue),
    body: issue.body ?? "",
    comments: comments.rows.map(githubComment),
    commentsComplete: comments.complete,
  };
  if (issue.pull_request) {
    const pullNumber = { ...where, pull_number: input.number };
    const pull = await runtime.call("GITHUB_GET_A_PULL_REQUEST", pullNumber);
    const files = await allPages(
      (page) =>
        runtime.call("GITHUB_LIST_PULL_REQUESTS_FILES", {
          ...pullNumber,
          per_page: 100,
          page,
        }),
      "details",
    );
    Object.assign(
      item,
      optionalFields({
        draft: pull.draft,
        merged: pull.merged,
        mergedAt: pull.merged_at,
        head: record(pull.head ?? {}).ref,
        base: record(pull.base ?? {}).ref,
        additions: pull.additions,
        deletions: pull.deletions,
        files: files.rows.map((file) =>
          optionalFields({
            path: requiredString(file.filename, "file path"),
            status: file.status,
            additions: file.additions,
            deletions: file.deletions,
            previousPath: file.previous_filename,
          }),
        ),
        filesComplete: files.complete,
      }),
    );
  }
  return { item };
}
function githubReadme(raw: Json): Json {
  if (raw.encoding !== "base64" || typeof raw.content !== "string")
    throw new ConnectorError(
      "incomplete_response",
      "The README content is unavailable.",
    );
  const content = Buffer.from(raw.content, "base64").toString("utf8");
  const complete = content.length <= maxReadme;
  return optionalFields({
    available: true,
    path: raw.path,
    text: complete ? content : content.slice(0, maxReadme),
    complete,
  });
}