toolfactory 0.1.1

package/schemas/agent-plugins/plugin.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "title": "Agent Plugins Manifest",
+  "description": "Machine-readable schema for plugin.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+      "description": "Canonical identifier of the plugin manifest schema for the Agent Plugins version targeted by this document."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$",
+      "description": "Human-readable plugin name."
+    },
+    "version": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "homepage": {
+      "type": "string"
+    },
+    "repository": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Client-specific manifest data keyed by reverse-domain extension namespace. Agent Plugins assigns no semantics to namespace object contents.",
+      "additionalProperties": {
+        "type": "object"
+      }
+    }
+  },
+  "required": ["$schema", "name"],
+  "additionalProperties": false
+}

package/src/bindings/index.ts

@@ -0,0 +1,47 @@
+import type { Binding, PlannedFile, Project } from "../model.js";
+import * as python from "./python.js";
+import * as typescript from "./typescript.js";
+
+export interface BindingModule {
+  /** Files generated on every build for every tool: the contract, config, and the MCP server toolfactory introspects. */
+  kernel(project: Project): PlannedFile[];
+  /** The `cli` surface's files. */
+  cli(project: Project): PlannedFile[];
+  /** The T4 live test; empty when no config key is both required and sensitive. */
+  liveTest(project: Project): PlannedFile[];
+  /** Files written once by `init` when absent, then owned by the author. */
+  scaffold(project: Project): PlannedFile[];
+  /** How to launch the kernel MCP server from the repo root without a build step. */
+  kernelCommand(project: Project): { command: string; args: string[] };
+  /** The kernel CLI counterpart of `kernelCommand`, for the `cli` surface's smoke check. */
+  cliCommand(project: Project): { command: string; args: string[] };
+}
+
+const bindings: Partial<Record<Binding, BindingModule>> = {
+  typescript: {
+    kernel: typescript.kernel,
+    cli: typescript.cli,
+    liveTest: typescript.liveTest,
+    scaffold: typescript.scaffold,
+    kernelCommand: () => typescript.kernelCommand(),
+    cliCommand: () => typescript.cliCommand(),
+  },
+  python: {
+    kernel: python.kernel,
+    cli: python.cli,
+    liveTest: python.liveTest,
+    scaffold: python.scaffold,
+    kernelCommand: python.kernelCommand,
+    cliCommand: python.cliCommand,
+  },
+};
+
+export function registerBinding(id: Binding, module: BindingModule): void {
+  bindings[id] = module;
+}
+
+export function getBinding(id: Binding): BindingModule {
+  const binding = bindings[id];
+  if (!binding) throw new Error(`Binding "${id}" is not implemented in this toolfactory version.`);
+  return binding;
+}

package/src/bindings/python.test.ts

@@ -0,0 +1,374 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer as createNetServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { listTools } from "../introspect/index.js";
+import type { FullFile, MergeFile, PlannedFile, Project, SurfaceId } from "../model.js";
+import { ToolConfigSchema } from "../model.js";
+import { surface as pypi } from "../surfaces/pypi.js";
+import {
+  cliCommand,
+  cli as cliFiles,
+  kernel,
+  kernelCommand,
+  liveTest,
+  scaffold,
+} from "./python.js";
+
+function project(surfaces: SurfaceId[], overrides: Partial<Project> = {}): Project {
+  return {
+    root: "/tmp/none",
+    tool: ToolConfigSchema.parse({
+      schemaVersion: 1,
+      identity: "plugin.json",
+      binding: "python",
+      surfaces,
+      config: { type: "object", properties: { apiKey: { type: "string" } } },
+    }),
+    identity: {
+      name: "hello.py",
+      version: "0.2.0",
+      description: "Say hello.",
+      license: "MIT",
+      repository: "https://github.com/acme/hello",
+      author: { name: "Ada", email: "ada@example.com" },
+    },
+    identityExtra: {},
+    operations: [],
+    toolfactoryVersion: "0.1.0",
+    ...overrides,
+  };
+}
+
+/** A project whose config declares one required, sensitive credential: what gates the T4 tier. */
+function withCredential(surfaces: SurfaceId[]): Project {
+  const base = project(surfaces);
+  base.tool.config = {
+    type: "object",
+    properties: { passkey: { type: "string", "x-toolfactory": { sensitive: true } } },
+    required: ["passkey"],
+  };
+  base.tool.tests = { examples: { echo: { text: "hi" } } };
+  base.operations = [{ name: "echo", inputSchema: { type: "object" }, requires: [] }];
+  return base;
+}
+
+const paths = (files: PlannedFile[]) => files.map((file) => file.path);
+const text = (files: PlannedFile[], path: string) =>
+  (files.find((file) => file.path === path) as FullFile).content;
+
+describe("python binding", () => {
+  it("names every artifact from the canonical name", () => {
+    const both = project(["mcp", "cli"]);
+    expect(kernelCommand(both).args).toEqual([
+      "run",
+      "--quiet",
+      "python",
+      "-m",
+      "hello_py.toolfactory.mcp",
+    ]);
+    expect(cliCommand(both).args.at(-1)).toBe("hello_py.toolfactory.cli");
+    expect(paths([...kernel(both), ...cliFiles(both)])).toEqual([
+      "src/hello_py/toolfactory/__init__.py",
+      "src/hello_py/toolfactory/types.py",
+      "src/hello_py/toolfactory/config.py",
+      "src/hello_py/toolfactory/mcp.py",
+      "src/hello_py/toolfactory/cli.py",
+    ]);
+    // A file exists iff a selected surface owns it, and config keys become environment reads.
+    expect(paths(kernel(project(["mcp"])))).not.toContain("src/hello_py/toolfactory/cli.py");
+    expect(text(kernel(both), "src/hello_py/toolfactory/config.py")).toContain(
+      '"apiKey": os.environ.get("APIKEY")',
+    );
+    expect(text(scaffold(both), "pyproject.toml")).toContain(
+      '"hello.py" = "hello_py.toolfactory.cli:main"',
+    );
+  });
+
+  it("reads the data directory from <N>_DATA_DIR, else the platform default", () => {
+    const files = kernel(project(["mcp"]));
+    expect(text(files, "src/hello_py/toolfactory/types.py")).toContain("data_dir: Path");
+    const config = text(files, "src/hello_py/toolfactory/config.py");
+    expect(config).toContain('os.environ.get("HELLO_PY_DATA_DIR")');
+    expect(config).toContain('os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share"');
+    expect(config).toContain('os.environ.get("LOCALAPPDATA")');
+    expect(config).toContain('return base / "hello.py"');
+    expect(config).toContain("data_dir=data_dir()");
+  });
+
+  it("emits the T4 live test only for a required sensitive credential", () => {
+    expect(liveTest(project(["cli"]))).toEqual([]);
+
+    const live = liveTest(withCredential(["cli"]))[0];
+    if (live?.kind !== "region") throw new Error("expected a region file");
+    expect(live.path).toBe("tests/test_live.py");
+    expect(live.regions[0]?.content).toContain('CREDENTIALS = ("PASSKEY",)');
+    expect(live.regions[0]?.content).toContain("LIVE = all(os.environ.get(name)");
+    expect(live.template).toContain("@pytest.mark.skipif(not LIVE");
+    // pydantic's own JSON entry point, so tool.json's example arguments need no translation.
+    expect(live.template).toContain('operation.input.model_validate_json("{\\"text\\":\\"hi\\"}")');
+    // The header documents the local command; CI runs the same one without --env-file.
+    expect(live.template).toContain(
+      "uv run --env-file .env --with pytest pytest -q tests/test_live.py",
+    );
+  });
+
+  it("emits opt-in --http and --pair flags, defaulting to stdio, on the mcp module and the cli", () => {
+    const files = [...kernel(project(["mcp", "cli"])), ...cliFiles(project(["mcp", "cli"]))];
+    const mcp = text(files, "src/hello_py/toolfactory/mcp.py");
+    expect(mcp).toContain("def serve_http(");
+    // One ASGI app on both paths: the SDK's own streamable-HTTP app, run by uvicorn over a
+    // socket bound first, so `--http 0` can report the port it actually got.
+    expect(mcp).toContain("app = server.streamable_http_app(");
+    expect(mcp).toContain("sock = config.bind_socket()");
+    expect(mcp).toContain("uvicorn.Server(config).run(sockets=[sock])");
+    expect(mcp).toContain("Serving MCP streamable HTTP on {base}{path}{suffix}");
+    expect(mcp).toContain("stateless_http=True");
+    // Stdio is still the default: the standalone entrypoint only switches transport when --http is present.
+    expect(mcp).toContain("if args.http is None and not args.pair:");
+
+    // The pairing token: `<N>_MCP_TOKEN` or a `relay-token` file under the data directory, and
+    // `--pair` to mint one. Neither present means no token and no behaviour change.
+    expect(mcp).toContain('os.environ.get("HELLO_PY_MCP_TOKEN")');
+    expect(mcp).toContain("data_dir() / TOKEN_FILE");
+    expect(mcp).toContain("hmac.compare_digest(hashlib.sha256(presented).digest(), expected)");
+
+    const cli = text(files, "src/hello_py/toolfactory/cli.py");
+    expect(cli).toContain('"--http"');
+    expect(cli).toContain("from .mcp import serve_http");
+    expect(cli).toContain("if options.http is not None or options.pair:");
+    expect(cli).toContain('"--pair"');
+    // Without the `web` surface there is no page to serve, open or write secrets for.
+    expect(mcp).not.toContain("web_route()");
+    expect(mcp).not.toContain("SECRETS");
+    expect(paths(kernel(project(["mcp", "cli"])))).not.toContain("src/hello_py/toolfactory/web.py");
+  });
+
+  it("serves the page, opens it and takes a secret when the web surface is selected", () => {
+    const target = withCredential(["mcp", "cli", "web"]);
+    const files = [...kernel(target), ...cliFiles(target)];
+    const mcp = text(files, "src/hello_py/toolfactory/mcp.py");
+    // The static half: the wheel's own copy first, then this checkout's build output.
+    expect(mcp).toContain(
+      'for candidate in (package / "web", package.parent.parent / "web" / "dist")',
+    );
+    expect(mcp).toContain('Mount("/", app=StaticFiles(directory=directory, html=True))');
+    expect(mcp).toContain("run `npm -C web run build`");
+    // The token guards the API paths only — a browser cannot put a header on its own document.
+    expect(mcp).toContain('app = guard(app, token, {path, "/env"})');
+    expect(mcp).toContain('SECRETS = ["PASSKEY"]');
+    expect(mcp).toContain('return JSONResponse({"declared": SECRETS, "present": env_present()})');
+    expect(mcp).toContain("env_path().chmod(0o600)");
+    expect(mcp).toContain('print(f".env: set {name}", file=sys.stderr, flush=True)');
+    expect(mcp).toContain('webbrowser.open(f"{base}/#{token}")');
+    expect(mcp).toContain("mint_token() if open_browser else None");
+
+    // The `web` operation: a detached child holds the socket, never this process.
+    const web = text(files, "src/hello_py/toolfactory/web.py");
+    expect(web).toContain('[sys.executable, "-m", f"{__package__}.mcp", "--http", "0", "--open"]');
+    expect(web).toContain("start_new_session=True");
+    expect(web).toContain('SERVING = re.compile(r"Serving MCP streamable HTTP on (\\S+)")');
+    expect(mcp).toContain("OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]");
+    expect(text(files, "src/hello_py/toolfactory/cli.py")).toContain(
+      "OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]",
+    );
+  });
+
+  it("projects identity into pyproject.toml only when it is not the identity file", () => {
+    const patch = (p: Project) =>
+      (pypi.plan(p)[0] as MergeFile).patch.project as Record<string, unknown>;
+    expect(patch(project(["pypi", "cli"]))).toMatchObject({
+      name: "hello-py",
+      version: "0.2.0",
+      authors: [{ name: "Ada", email: "ada@example.com" }],
+      urls: { Repository: "https://github.com/acme/hello" },
+      scripts: { "hello.py": "hello_py.toolfactory.cli:main" },
+    });
+    const authored = project(["pypi", "cli"]);
+    authored.tool.identity = "pyproject.toml";
+    expect(patch(authored)).toEqual({ scripts: { "hello.py": "hello_py.toolfactory.cli:main" } });
+  });
+
+  it("carries the MCP Registry ownership marker in the README", () => {
+    const files = pypi.plan(project(["pypi", "mcp-registry"]));
+    expect((files[0] as MergeFile).patch).toMatchObject({ project: { readme: "README.md" } });
+    const readme = files[1];
+    if (readme.kind !== "region") throw new Error("expected a region file");
+    expect(readme.regions[0]?.content).toContain("<!-- mcp-name: io.github.acme/hello.py -->");
+  });
+});
+
+const uv = spawnSync("uv", ["--version"], { encoding: "utf8" }).status === 0;
+
+describe.skipIf(!uv)("python kernel, really run", () => {
+  it("serves tools/list and answers the CLI", { timeout: 300_000 }, async () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-python-"));
+    const real = project(["mcp", "cli"], { root, identity: { name: "probe", version: "0.1.0" } });
+    for (const file of [...scaffold(real), ...kernel(real), ...cliFiles(real)]) {
+      const path = join(root, file.path);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, (file as FullFile).content);
+    }
+    const sync = spawnSync("uv", ["sync", "--quiet"], { cwd: root, encoding: "utf8" });
+    expect(sync.status, sync.stderr).toBe(0);
+
+    const { command, args } = kernelCommand(real);
+    const ops = await listTools(root, command, args);
+    expect(ops.tools[0]).toMatchObject({
+      name: "echo",
+      inputSchema: { required: ["text"] },
+      outputSchema: { required: ["text"] },
+      _meta: { "dev.toolfactory": { requires: [] } },
+    });
+
+    const cli = cliCommand(real);
+    const ran = spawnSync(cli.command, [...cli.args, "echo", "--text", "hi"], {
+      cwd: root,
+      encoding: "utf8",
+    });
+    expect(JSON.parse(ran.stdout)).toEqual({ text: "hi" });
+  });
+
+  it("serves tools/list over --http, and requires the token minted by --pair", {
+    timeout: 300_000,
+  }, async () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-python-http-"));
+    const real = project(["mcp", "cli"], { root, identity: { name: "probe", version: "0.1.0" } });
+    for (const file of [...scaffold(real), ...kernel(real), ...cliFiles(real)]) {
+      const path = join(root, file.path);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, (file as FullFile).content);
+    }
+    const sync = spawnSync("uv", ["sync", "--quiet"], { cwd: root, encoding: "utf8" });
+    expect(sync.status, sync.stderr).toBe(0);
+
+    const dataDir = join(root, "data");
+    const env = { ...process.env, PROBE_DATA_DIR: dataDir };
+    const port = await freePort();
+    const cli = cliCommand(real);
+    const child = spawn(cli.command, [...cli.args, "mcp", "--http", String(port)], {
+      cwd: root,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stderr: string[] = [];
+    child.stderr?.on("data", (chunk: Buffer) => stderr.push(String(chunk)));
+
+    try {
+      const url = `http://127.0.0.1:${port}/mcp`;
+      const init = await waitForInitialize(url, 30_000).catch((error) => {
+        throw new Error(`${error instanceof Error ? error.message : error}\n${stderr.join("")}`);
+      });
+      expect(init.status).toBe(200);
+      const negotiated = (init.json as { result: { protocolVersion: string } }).result
+        .protocolVersion;
+
+      const list = await postRpc(url, { jsonrpc: "2.0", id: 2, method: "tools/list" }, negotiated);
+      expect(list.status).toBe(200);
+      const tools = (list.json as { result: { tools: { name: string }[] } }).result.tools;
+      expect(tools.map((tool) => tool.name)).toEqual(["echo"]);
+    } finally {
+      child.kill();
+    }
+
+    // The same server started with `--pair`: it prints the pairing string the extension's options
+    // page takes, keeps the token under the data directory, and refuses a request without it.
+    const pairPort = await freePort();
+    const paired = spawn(cli.command, [...cli.args, "mcp", "--http", String(pairPort), "--pair"], {
+      cwd: root,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout: string[] = [];
+    paired.stdout?.on("data", (chunk: Buffer) => stdout.push(String(chunk)));
+
+    try {
+      const url = `http://127.0.0.1:${pairPort}/mcp`;
+      const anonymous = await waitForInitialize(url, 30_000);
+      expect(anonymous.status).toBe(401);
+
+      const [printed, token] = stdout.join("").trim().split("\n")[0]?.split("#") ?? [];
+      expect(printed).toBe(url);
+      expect(readFileSync(join(dataDir, "relay-token"), "utf8").trim()).toBe(token);
+
+      const init = await waitForInitialize(url, 30_000, token);
+      expect(init.status).toBe(200);
+    } finally {
+      paired.kill();
+    }
+  });
+});
+
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer();
+    probe.on("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const address = probe.address();
+      const port = typeof address === "object" && address ? address.port : 0;
+      probe.close((error) => (error ? reject(error) : resolve(port)));
+    });
+  });
+}
+
+// The streamable HTTP transport requires `Accept: application/json, text/event-stream` on every
+// POST, and `MCP-Protocol-Version` on every request *after* the one that negotiates it in `initialize`.
+async function postRpc(
+  url: string,
+  body: unknown,
+  protocolVersion?: string,
+  token?: string,
+): Promise<{ status: number; json: unknown }> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+  };
+  if (protocolVersion) headers["MCP-Protocol-Version"] = protocolVersion;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+  const raw = await response.text();
+  const isEventStream =
+    response.headers.get("content-type")?.includes("text/event-stream") ?? false;
+  const payload = isEventStream
+    ? JSON.parse(
+        raw
+          .split("\n")
+          .find((line) => line.startsWith("data: "))
+          ?.slice("data: ".length) ?? "{}",
+      )
+    : JSON.parse(raw || "{}");
+  return { status: response.status, json: payload };
+}
+
+/** Retries `initialize` until the freshly-spawned server starts accepting connections. */
+async function waitForInitialize(
+  url: string,
+  deadlineMs: number,
+  token?: string,
+): Promise<{ status: number; json: unknown }> {
+  const deadline = Date.now() + deadlineMs;
+  for (;;) {
+    try {
+      return await postRpc(
+        url,
+        {
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2026-07-28",
+            capabilities: {},
+            clientInfo: { name: "toolfactory-test", version: "0.0.0" },
+          },
+        },
+        undefined,
+        token,
+      );
+    } catch (error) {
+      if (Date.now() >= deadline) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+}