@irogane/kaji 0.2.0-beta.11

package/registry/github/index.ts

@@ -0,0 +1,263 @@
+// This is YOUR GitHub integration. Edit it.
+
+import {
+  Integration,
+  type MetricsSink,
+  type ToolExecutionContext,
+  type ToolHandler,
+  type ToolSpec,
+  type TraceSink,
+} from "@irogane/kaji";
+import { createGitHubRequester } from "@irogane/kaji/integrations";
+
+import { GitHubClient } from "./client";
+
+export type SharedGitHubClient = Pick<
+  GitHubClient,
+  "addComment" | "createIssue" | "getFile" | "getIssue" | "listIssues" | "searchCode"
+>;
+
+const repository = {
+  type: "string",
+  pattern: "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$",
+} as const;
+const issueNumber = { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER } as const;
+
+function parameters(
+  properties: Readonly<Record<string, unknown>>,
+  required: readonly string[],
+): Record<string, unknown> {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties,
+    required: [...required],
+    additionalProperties: false,
+  };
+}
+
+function specs(): readonly ToolSpec[] {
+  return [
+    {
+      name: "add_comment",
+      description: "Add a comment to a GitHub issue.",
+      parameters: parameters(
+        {
+          repository,
+          issue_number: issueNumber,
+          body: { type: "string", minLength: 1, maxLength: 16_384 },
+        },
+        ["repository", "issue_number", "body"],
+      ),
+      risk: "external_effect",
+      parallel_safe: false,
+      timeout_ms: 15_000,
+    },
+    {
+      name: "create_issue",
+      description: "Create a GitHub issue.",
+      parameters: parameters(
+        {
+          repository,
+          title: { type: "string", minLength: 1, maxLength: 256 },
+          body: { type: "string", minLength: 0, maxLength: 16_384 },
+        },
+        ["repository", "title", "body"],
+      ),
+      risk: "external_effect",
+      parallel_safe: false,
+      timeout_ms: 15_000,
+    },
+    {
+      name: "get_file",
+      description: "Get a file from a GitHub repository.",
+      parameters: parameters(
+        {
+          repository,
+          path: { type: "string", minLength: 1, maxLength: 512 },
+          ref: { type: "string", minLength: 1, maxLength: 100 },
+        },
+        ["repository", "path"],
+      ),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+    {
+      name: "get_issue",
+      description: "Get a GitHub issue.",
+      parameters: parameters({ repository, issue_number: issueNumber }, [
+        "repository",
+        "issue_number",
+      ]),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+    {
+      name: "list_issues",
+      description: "List GitHub issues.",
+      parameters: parameters(
+        {
+          repository,
+          state: { type: "string", enum: ["open", "closed", "all"], default: "open" },
+          page: { type: "integer", minimum: 1, maximum: 1_000, default: 1 },
+          per_page: { type: "integer", minimum: 1, maximum: 20, default: 10 },
+        },
+        ["repository"],
+      ),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+    {
+      name: "search_code",
+      description: "Search code in a GitHub repository.",
+      parameters: parameters(
+        {
+          repository,
+          query: { type: "string", minLength: 1, maxLength: 256 },
+          page: { type: "integer", minimum: 1, maximum: 50, default: 1 },
+          per_page: { type: "integer", minimum: 1, maximum: 20, default: 10 },
+        },
+        ["repository", "query"],
+      ),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+  ];
+}
+
+function objectResult(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("GitHub client returned an invalid tool result");
+  }
+  return value as Record<string, unknown>;
+}
+
+function handler(client: SharedGitHubClient, name: string): ToolHandler {
+  return async (args, context) => {
+    switch (name) {
+      case "add_comment":
+        return objectResult(
+          await client.addComment(context, {
+            repository: args.repository as string,
+            issueNumber: args.issue_number as number,
+            body: args.body as string,
+          }),
+        );
+      case "create_issue":
+        return objectResult(
+          await client.createIssue(context, {
+            repository: args.repository as string,
+            title: args.title as string,
+            body: args.body as string,
+          }),
+        );
+      case "get_file":
+        return objectResult(
+          await client.getFile(context, {
+            repository: args.repository as string,
+            path: args.path as string,
+            ...(args.ref === undefined ? {} : { ref: args.ref as string }),
+          }),
+        );
+      case "get_issue":
+        return objectResult(
+          await client.getIssue(context, {
+            repository: args.repository as string,
+            issueNumber: args.issue_number as number,
+          }),
+        );
+      case "list_issues":
+        return objectResult(
+          await client.listIssues(context, {
+            repository: args.repository as string,
+            ...(args.state === undefined ? {} : { state: args.state as "open" | "closed" | "all" }),
+            ...(args.page === undefined ? {} : { page: args.page as number }),
+            ...(args.per_page === undefined ? {} : { perPage: args.per_page as number }),
+          }),
+        );
+      case "search_code":
+        return objectResult(
+          await client.searchCode(context, {
+            repository: args.repository as string,
+            query: args.query as string,
+            ...(args.page === undefined ? {} : { page: args.page as number }),
+            ...(args.per_page === undefined ? {} : { perPage: args.per_page as number }),
+          }),
+        );
+      default:
+        throw new Error("Unknown GitHub tool");
+    }
+  };
+}
+
+export function createSharedGitHubToolBindings(
+  client: SharedGitHubClient,
+): [ToolSpec, ToolHandler][] {
+  return specs().map((spec) => [spec, handler(client, spec.name)]);
+}
+
+export class GitHubIntegration extends Integration {
+  readonly namespace = "github";
+  private closeOwnedRequester: (() => void) | undefined;
+
+  constructor(
+    private readonly client: SharedGitHubClient,
+    closeOwnedRequester?: () => void,
+  ) {
+    super();
+    this.closeOwnedRequester = closeOwnedRequester;
+  }
+
+  override tools(): [ToolSpec, ToolHandler][] {
+    return createSharedGitHubToolBindings(this.client);
+  }
+
+  close(): void {
+    const close = this.closeOwnedRequester;
+    if (close === undefined) return;
+    close();
+    this.closeOwnedRequester = undefined;
+  }
+}
+
+export interface CreateGitHubIntegrationOptions {
+  readonly tokenFor: (context: ToolExecutionContext) => Promise<string>;
+  readonly repositories: readonly string[];
+  readonly metricsSink?: MetricsSink;
+  readonly traceSink?: TraceSink;
+}
+
+export function createGithubIntegration(
+  options: CreateGitHubIntegrationOptions,
+): GitHubIntegration {
+  const { metricsSink, traceSink, ...clientOptions } = options;
+  const http = createGitHubRequester({ metricsSink, traceSink });
+  return new GitHubIntegration(
+    new GitHubClient({
+      ...clientOptions,
+      http,
+    }),
+    () => http.close(),
+  );
+}
+
+function createGithubIntegrationForTest(client: SharedGitHubClient): GitHubIntegration {
+  return new GitHubIntegration(client);
+}
+
+const inspectionClient = new Proxy(
+  {},
+  {
+    get: () => async () => {
+      throw new Error("inspection dependencies must not execute");
+    },
+  },
+) as SharedGitHubClient;
+
+export function inspectIntegration(): GitHubIntegration {
+  return createGithubIntegrationForTest(inspectionClient);
+}

package/registry/github/manifest.json

@@ -0,0 +1,227 @@
+{
+  "name": "github",
+  "version": "0.1.0",
+  "namespace": "github",
+  "description": "Repository-scoped GitHub code, issue, and comment tools.",
+  "auth": {
+    "kind": "env",
+    "env": "GITHUB_TOKEN",
+    "docs": "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens"
+  },
+  "files": [
+    "index.ts",
+    "client.ts",
+    "tests/github.test.ts",
+    "owner-fixtures.json",
+    "LICENSE"
+  ],
+  "tools": [
+    {
+      "name": "add_comment",
+      "description": "Add a comment to a GitHub issue.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "issue_number": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384
+          }
+        },
+        "required": [
+          "repository",
+          "issue_number",
+          "body"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "external_effect",
+      "parallel_safe": false,
+      "timeout_ms": 15000
+    },
+    {
+      "name": "create_issue",
+      "description": "Create a GitHub issue.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "body": {
+            "type": "string",
+            "minLength": 0,
+            "maxLength": 16384
+          }
+        },
+        "required": [
+          "repository",
+          "title",
+          "body"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "external_effect",
+      "parallel_safe": false,
+      "timeout_ms": 15000
+    },
+    {
+      "name": "get_file",
+      "description": "Get a file from a GitHub repository.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "ref": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          }
+        },
+        "required": [
+          "repository",
+          "path"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    },
+    {
+      "name": "get_issue",
+      "description": "Get a GitHub issue.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "issue_number": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          }
+        },
+        "required": [
+          "repository",
+          "issue_number"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    },
+    {
+      "name": "list_issues",
+      "description": "List GitHub issues.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "open",
+              "closed",
+              "all"
+            ],
+            "default": "open"
+          },
+          "page": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "default": 1
+          },
+          "per_page": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20,
+            "default": 10
+          }
+        },
+        "required": [
+          "repository"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    },
+    {
+      "name": "search_code",
+      "description": "Search code in a GitHub repository.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "repository": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$"
+          },
+          "query": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "page": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50,
+            "default": 1
+          },
+          "per_page": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20,
+            "default": 10
+          }
+        },
+        "required": [
+          "repository",
+          "query"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    }
+  ],
+  "peerDeps": {}
+}

package/registry/github/owner-fixtures.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": "1.0.0",
+  "outcomes": [
+    { "name": "success", "expected": "success" },
+    { "name": "missing_auth", "expected": "INTEGRATION_AUTH_REQUIRED" },
+    { "name": "rate_limit", "expected": "INTEGRATION_RATE_LIMITED" },
+    { "name": "approval_rejected", "expected": "APPROVAL_REJECTED" },
+    { "name": "connection_lost_after_dispatch", "expected": "unknown" }
+  ]
+}

package/registry/github/tests/github.test.ts

@@ -0,0 +1,32 @@
+// This is YOUR no-network GitHub owner fixture test. Edit it.
+
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const closedOutcomes = new Set([
+  "success",
+  "missing_auth",
+  "rate_limit",
+  "approval_rejected",
+  "connection_lost_after_dispatch",
+]);
+
+export function scriptedOutcome(name: string): string {
+  if (!closedOutcomes.has(name)) throw new Error("unknown scripted GitHub outcome");
+  const fixture = JSON.parse(
+    readFileSync(new URL("../owner-fixtures.json", import.meta.url), "utf8"),
+  ) as { outcomes: Array<{ name: string; expected: string }> };
+  return fixture.outcomes.find((row) => row.name === name)!.expected;
+}
+
+describe("GitHub owner fixtures", () => {
+  it("keeps scripted outcomes closed and network-free", () => {
+    expect([...closedOutcomes].map((name) => [name, scriptedOutcome(name)])).toEqual([
+      ["success", "success"],
+      ["missing_auth", "INTEGRATION_AUTH_REQUIRED"],
+      ["rate_limit", "INTEGRATION_RATE_LIMITED"],
+      ["approval_rejected", "APPROVAL_REJECTED"],
+      ["connection_lost_after_dispatch", "unknown"],
+    ]);
+  });
+});

package/registry/gmail/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Enkang Yuan
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.