toolfactory 0.1.1

package/dist/bindings/python.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bindings/python.test.js

@@ -0,0 +1,316 @@
+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 { 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, overrides = {}) {
+    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) {
+    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) => files.map((file) => file.path);
+const text = (files, path) => files.find((file) => file.path === path).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) => pypi.plan(p)[0].patch.project;
+        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].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.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.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 = [];
+        child.stderr?.on("data", (chunk) => 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.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.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 = [];
+        paired.stdout?.on("data", (chunk) => 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() {
+    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, body, protocolVersion, token) {
+    const headers = {
+        "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, deadlineMs, token) {
+    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));
+        }
+    }
+}

package/dist/bindings/typescript.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TypeScript binding: the six language-specific things, as templates against upstream
+ * SDKs only. The kernel files under `src/toolfactory/` are regenerated on every build; the
+ * author's `src/ops.ts` is scaffolded once and then owned.
+ */
+import type { PlannedFile, Project } from "../model.js";
+export declare const KERNEL_DIR = "src/toolfactory";
+export declare const OPS_PATH = "src/ops.ts";
+export declare const LIVE_TEST_PATH = "tests/live.test.ts";
+/**
+ * The scaffold script the `live` CI job and the author both run (§6 T4). Node's own
+ * `--env-file`, so no dotenv dependency (vitest does not put `.env` into `process.env`);
+ * `-if-exists` so CI, which injects the same names from the `live-tests` environment rather
+ * than a file, runs the same script; vitest's own entry file rather than `node_modules/.bin`,
+ * which is a shell shim under pnpm and cannot be handed to `node`.
+ */
+export declare const LIVE_TEST_SCRIPT = "node --env-file-if-exists=.env node_modules/vitest/vitest.mjs run tests/live.test.ts";
+export declare function kernelCommand(): {
+    command: string;
+    args: string[];
+};
+export declare function cliCommand(): {
+    command: string;
+    args: string[];
+};
+/**
+ * The T4 live tier: real calls against the real service, kept out of the default `vitest run`
+ * by a generated guard over the credentials `tool.json` declares as required and sensitive.
+ * The markers hold only the guard; the example test around them is the author's.
+ */
+export declare function liveTest(project: Project): PlannedFile[];
+/** The kernel, generated on every build for every tool: the contract, config, and the MCP server toolfactory introspects. */
+export declare function kernel(project: Project): PlannedFile[];
+/** The CLI surface's file. */
+export declare function cli(project: Project): PlannedFile[];
+/** The Node floor every generated TypeScript project declares (vite 8 and the MCP SDK need it). */
+export declare const NODE_ENGINES = ">=22.12";
+/** Written by `init` only when absent; owned by the author afterwards. */
+export declare function scaffold(project: Project): PlannedFile[];