toolfactory 0.1.1

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

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

package/dist/bindings/typescript.test.js

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
+import { createServer as createNetServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { ToolConfigSchema } from "../model.js";
+import { cliCommand, cli as cliFiles, kernel, kernelCommand, liveTest, scaffold, } from "./typescript.js";
+function project(surfaces, overrides = {}) {
+    return {
+        root: "/tmp/none",
+        tool: ToolConfigSchema.parse({
+            schemaVersion: 1,
+            identity: "plugin.json",
+            binding: "typescript",
+            surfaces,
+            config: { type: "object", properties: { apiKey: { type: "string" } } },
+        }),
+        identity: {
+            name: "hello.ts",
+            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("typescript binding", () => {
+    it("names every artifact from the canonical name", () => {
+        const both = project(["mcp", "cli"]);
+        expect(kernelCommand().args).toEqual(["--import", "tsx", "src/toolfactory/mcp.ts"]);
+        expect(cliCommand().args.at(-1)).toBe("src/toolfactory/cli.ts");
+        expect(paths([...kernel(both), ...cliFiles(both)])).toEqual([
+            "src/toolfactory/types.ts",
+            "src/toolfactory/config.ts",
+            "src/toolfactory/mcp.ts",
+            "src/toolfactory/cli.ts",
+        ]);
+        // A file exists iff a selected surface owns it, and config keys become environment reads.
+        // The kernel is the same for every surface set; only the cli surface adds cli.ts.
+        expect(paths(kernel(project(["mcp"])))).not.toContain("src/toolfactory/cli.ts");
+        expect(text(kernel(both), "src/toolfactory/config.ts")).toContain('"apiKey": process.env["APIKEY"]');
+    });
+    it("reads the data directory from <N>_DATA_DIR, else the platform default", () => {
+        const files = kernel(project(["mcp"]));
+        expect(text(files, "src/toolfactory/types.ts")).toContain("dataDir: string;");
+        const config = text(files, "src/toolfactory/config.ts");
+        expect(config).toContain('process.env["HELLO_TS_DATA_DIR"]');
+        expect(config).toContain('process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share")');
+        expect(config).toContain('process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local")');
+        expect(config).toContain('return join(base, "hello.ts");');
+        expect(config).toContain("dataDir: dataDir(),");
+    });
+    it("emits the T4 live test, and its scaffold script, only for a required sensitive credential", () => {
+        // No config key is both required and sensitive: nothing gates a live run, so no live tier.
+        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/live.test.ts");
+        // The generated region is the guard; the example test around it is the author's.
+        expect(live.regions[0]?.content).toContain('const CREDENTIALS = ["PASSKEY"];');
+        expect(live.regions[0]?.content).toContain("CREDENTIALS.every((name) => process.env[name])");
+        expect(live.template).toContain("describe.skipIf(!live)");
+        // The example arguments come from tool.json tests.examples, so the stub is a real call.
+        expect(live.template).toContain('operation.handler({"text":"hi"} as never, context())');
+        const scripts = JSON.parse(text(scaffold(project(["cli"])), "package.json")).scripts;
+        expect(scripts["test:live"]).toBe("node --env-file-if-exists=.env node_modules/vitest/vitest.mjs run tests/live.test.ts");
+    });
+    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/toolfactory/mcp.ts");
+        expect(mcp).toContain('import { createMcpHandler, McpServer } from "@modelcontextprotocol/server"');
+        expect(mcp).toContain("export async function serveHttp(");
+        expect(mcp).toContain('port = 3000, host = "127.0.0.1", path = "/mcp"');
+        expect(mcp).toContain("toNodeHandler(createMcpHandler(createServer))");
+        // The CLI's mcp subcommand exists only when the mcp surface does (the file it imports).
+        expect(text(cliFiles(project(["cli"])), "src/toolfactory/cli.ts")).not.toContain('command("mcp")');
+        // Stdio is still the default: the standalone entrypoint only switches transport when --http is present.
+        expect(mcp).toContain("const port = httpPortArg(process.argv.slice(2));");
+        expect(mcp).toContain("port === undefined && !pair ? serve() : serveHttp({ port: port ?? 3000");
+        // 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('process.env["HELLO_TS_MCP_TOKEN"]');
+        expect(mcp).toContain("join(context().dataDir, TOKEN_FILE)");
+        expect(mcp).toContain('timingSafeEqual(digest(header?.replace(/^Bearer /, "") ?? "")');
+        const cli = text(files, "src/toolfactory/cli.ts");
+        expect(cli).toContain('"--http [port]"');
+        expect(cli).toContain("serve, serveHttp");
+        expect(cli).toContain("if (options.http === undefined && !options.pair) await serve();");
+        expect(cli).toContain('"--pair"');
+        // Without the `web` surface there is no page to serve, open or write secrets for.
+        expect(mcp).not.toContain("WEB_DIST");
+        expect(mcp).not.toContain("SECRETS");
+        expect(paths(kernel(project(["mcp", "cli"])))).not.toContain("src/toolfactory/web.ts");
+    });
+    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/toolfactory/mcp.ts");
+        // One router, exported, so a host with its own listener mounts the same function.
+        expect(mcp).toContain("export function handler(options: HandlerOptions = {})");
+        expect(mcp).toContain('const { path = "/mcp", prefix = "", token, hostGuard, env = true }');
+        expect(mcp).toContain('fileURLToPath(new URL("../../web/dist/", import.meta.url))');
+        expect(mcp).toContain("run \\`npm -C web run build\\`");
+        // The token guards the API routes only — a browser cannot put a header on its own document.
+        expect(mcp).toContain("serveWeb(pathname.slice(prefix.length), response);");
+        expect(mcp).toContain('const SECRETS = ["PASSKEY"];');
+        expect(mcp).toContain("json(200, { declared: SECRETS, present: envPresent() })");
+        expect(mcp).toContain("chmodSync(envPath(), 0o600)");
+        expect(mcp).toContain("console.error(`.env: set ${name}`)");
+        expect(mcp).toContain("openBrowser(`${base}/#${token}`)");
+        expect(mcp).toContain("pairedToken() ?? (open ? mintToken() : undefined)");
+        // The `web` operation: a detached child holds the socket, never this process.
+        const web = text(files, "src/toolfactory/web.ts");
+        expect(web).toContain('[...process.execArgv, KERNEL, "--http", "0", "--open"]');
+        expect(web).toContain("detached: true");
+        expect(web).toContain("const SERVING = /Serving MCP streamable HTTP on (\\S+)/;");
+        expect(mcp).toContain("const operations = [...authored, web];");
+        expect(text(files, "src/toolfactory/cli.ts")).toContain("const operations = [...authored, web];");
+    });
+});
+const repoRoot = join(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+const repoNodeModules = join(repoRoot, "node_modules");
+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));
+        }
+    }
+}
+describe.skipIf(!existsSync(repoNodeModules))("typescript kernel, really run over http", () => {
+    it("serves tools/list over --http, and requires the token minted by --pair", {
+        timeout: 60_000,
+    }, async () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-typescript-"));
+        symlinkSync(repoNodeModules, join(root, "node_modules"), "dir");
+        const real = project(["mcp", "cli"], { root, identity: { name: "probe", version: "0.1.0" } });
+        for (const file of [...scaffold(real), ...kernel(real), ...cliFiles(real)]) {
+            const filePath = join(root, file.path);
+            mkdirSync(dirname(filePath), { recursive: true });
+            writeFileSync(filePath, file.content);
+        }
+        const dataDir = join(root, "data");
+        const env = { ...process.env, PROBE_DATA_DIR: dataDir };
+        const port = await freePort();
+        const { command, args } = cliCommand();
+        const child = spawn(command, [...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, 20_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(command, [...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, 20_000);
+            expect(anonymous.status).toBe(401);
+            const [printed, token] = stdout.join("").trim().split("#");
+            expect(printed).toBe(url);
+            expect(readFileSync(join(dataDir, "relay-token"), "utf8").trim()).toBe(token);
+            const init = await waitForInitialize(url, 20_000, token);
+            expect(init.status).toBe(200);
+        }
+        finally {
+            paired.kill();
+        }
+    });
+});

package/dist/commands.d.ts

@@ -0,0 +1,188 @@
+import { type BootstrapResult, type CreateRepoResult } from "./hosts/github.js";
+import type { Binding, Command, Project, SurfaceId } from "./model.js";
+import { type Drift } from "./project/apply.js";
+import { type GateStep } from "./project/gate.js";
+import { type Coverage } from "./report/coverage.js";
+export interface InitOptions {
+    root: string;
+    name: string;
+    description?: string;
+    binding: Binding;
+    /** `none` creates an instruction-only skill/Codex plugin with no executable payload. */
+    runtime?: "kernel" | "none";
+    /** Default: `defaultSurfaces(binding)`, the skills-first minimum. */
+    surfaces?: SurfaceId[];
+    license?: string;
+    repository?: string;
+    author?: string;
+    /**
+     * Activation triggers for hosts that key off them (Kiro Powers, Agent Plugins); defaults to
+     * `[name]`.
+     */
+    keywords?: string[];
+    /** `git init` when the directory is not a repository yet. `.agents/setup` needs one. */
+    git?: boolean;
+    /** Run `.agents/setup`: harness adapters, the git hooks, the dependency install. */
+    setup?: boolean;
+    /** `owner/name` of a GitHub repository to create with `gh` and push to. */
+    repo?: string;
+    /** Create that repository public; the default is private. */
+    public?: boolean;
+    /** Print the `gh` invocations instead of running them. */
+    dryRun?: boolean;
+    /** GitHub logins that must approve a live run, when the repository gets a live tier. */
+    reviewers?: string[];
+}
+export interface InitResult {
+    written: string[];
+    /** What `.agents/setup` did here: whether it succeeded, and the harnesses it rendered for. */
+    agentConfig: {
+        setup: boolean;
+        harnesses: string[];
+    };
+    repository?: CreateRepoResult & {
+        secrets: string[];
+    };
+    /** What the caller — a human or the agent that ran `init` — has to do next, in order. */
+    nextSteps: string[];
+}
+/**
+ * Create dev.toolfactory/tool.json, the identity file and the binding's scaffold, build every
+ * selected surface, and leave a project that is already live in the harness it was run from:
+ * a git repository, the first-party skills, the rendered agent config, and — only when asked —
+ * a GitHub repository holding it.
+ */
+export declare function init(options: InitOptions): InitResult;
+export declare function build(root?: string): {
+    project: Project;
+    result: {
+        nudge: string | undefined;
+        written: string[];
+        deleted: string[];
+        unchanged: string[];
+        manual: string[];
+        stripped: string[];
+    };
+};
+/** Throws when any generated file drifted, so CLI and MCP callers see a failure. */
+/** The drift gate: the operation snapshot and every generated file must match the code. */
+export declare function check(root?: string): Promise<{
+    project: Project;
+    drift: Drift[];
+}>;
+/** Regenerate the kernel first so the snapshot always reflects the current templates. */
+export declare function introspect(root?: string): Promise<{
+    path: string;
+    changed: boolean;
+    ops: import("./project/load.js").Ops;
+}>;
+export declare function coverage(root?: string): Coverage;
+export interface ValidationOutcome {
+    label: string;
+    command: string;
+    ok: boolean;
+    output: string;
+}
+/** Run every selected surface's upstream validator (tier 1 and the kernel smoke); throws if any fails. */
+export declare function validate(root?: string, only?: SurfaceId): ValidationOutcome[];
+export declare function run(command: Command): ValidationOutcome;
+export interface StepResult {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+}
+/**
+ * Run a step list from `project/gate.ts` in order, stopping at the first failure. `when: "ci"`
+ * steps are runner provisioning — a global install no checkout may perform on the author's
+ * machine — and are skipped here exactly as `renderShell` skips them. Every step's output goes to
+ * this process's stderr, never its stdout, so running the gate over the MCP surface cannot
+ * corrupt the protocol stream.
+ */
+export declare function runSteps(root: string, steps: GateStep[]): {
+    steps: StepResult[];
+};
+/**
+ * The gate: what "green" means for this project, run here instead of on a runner. `ci.yml`
+ * renders the same list, so a project with no CI at all — no GitHub, plain git or none — has the
+ * identical gate one command away.
+ */
+export declare function gate(root?: string): {
+    steps: StepResult[];
+};
+/** Every release asset into `dist/release/`, by the same steps the release workflow's job runs. */
+export declare function packageRelease(root?: string): {
+    steps: StepResult[];
+};
+export interface SecretRow {
+    /** The environment variable name, on every surface and in every environment. */
+    name: string;
+    kind: "config" | "release";
+    required: boolean;
+    /** Selected surfaces (a config key) or registry ids (a release token) that consume it. */
+    needs: string[];
+    /** Present in `<root>/.env` or this process's environment. Presence only, never the value. */
+    local: boolean;
+    /** Named by `gh secret list`; absent when `gh` is not on PATH or no repository is declared. */
+    github?: boolean;
+    url?: string;
+    /** The exact next action, per selected host and per registry. */
+    howTo: string[];
+    /** `check`: what the registry's own CLI said about the credential in the environment. */
+    check?: {
+        ok: boolean;
+        command: string;
+    };
+}
+export interface SecretsReport {
+    secrets: SecretRow[];
+    /** The one-time human steps with no API; the same list `bootstrap-repo` prints. */
+    manual: string[];
+}
+export declare function secretsReport(project: Project, action?: "status" | "check", key?: string): SecretsReport;
+/** The whole inventory: what each credential is for, where it is set, and (check) whether it works. */
+export declare function secrets(args: {
+    root?: string;
+    action?: "status" | "check";
+    key?: string;
+}): SecretsReport;
+export interface UnpublishResult {
+    /** The tag the previous selection came from; absent when there is no earlier tag to diff against. */
+    from?: string;
+    /** Surfaces selected at that tag, no longer selected, and published somewhere. */
+    dropped: SurfaceId[];
+    steps: {
+        name: string;
+        run: string;
+    }[];
+    /**
+     * What each step did (omitted by `dryRun`). Best-effort on purpose: a registry that refuses a
+     * retraction must never stop the release it is riding along with from being cut.
+     */
+    ran?: StepResult[];
+}
+export declare function unpublish(root?: string, options?: {
+    ref?: string;
+    dryRun?: boolean;
+    hard?: boolean;
+}): UnpublishResult;
+export declare function adopt(root: string, path: string): void;
+export declare function unadopt(root: string, path: string): void;
+export declare function eject(root: string, surface: SurfaceId): string[];
+export interface DoctorReport {
+    toolfactory: string;
+    node: string;
+    tools: Record<string, string>;
+}
+/** Report the upstream CLIs this machine can delegate to. */
+/**
+ * Prepare the GitHub repository: the `live-tests` environment and its secrets, the release
+ * registries' repository secrets, Pages, and npm's trusted publisher — everything GitHub only
+ * exposes over its API, from the one table and the one `.env`.
+ */
+export declare function bootstrapRepo(args: {
+    root: string;
+    reviewers?: string[];
+    dryRun?: boolean;
+}): BootstrapResult;
+export declare function doctor(): DoctorReport;
+export declare const SURFACES: readonly ["skill", "agent-plugins", "claude", "codex", "cursor", "mcp", "mcp-registry", "cli", "npm", "pypi", "openclaw-native", "hermes-native", "clawhub", "web", "dsh", "workflows", "agents", "readme", "gemini", "mcpb", "browser-extension"];