toolfactory 0.1.1

package/src/toolfactory/cli.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.
+import { Command } from "commander";
+import { z } from "zod";
+import { operations as authored } from "../ops.js";
+import { context } from "./config.js";
+import { serves } from "./types.js";
+import { web } from "./web.js";
+
+/** The authored operations plus the generated `web` one, exactly as the MCP kernel lists them. */
+const operations = [...authored, web];
+
+const program = new Command()
+  .name("toolfactory")
+  .description("Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.")
+  .version("0.1.1");
+
+for (const op of operations) {
+  if (!serves(op, "cli")) continue;
+  const command = program.command(op.name).description(op.description);
+  command.option("--json <arguments>", "all arguments as one JSON object");
+  const schema = z.toJSONSchema(op.input, { io: "input" }) as {
+    properties?: Record<string, { description?: string; type?: string; default?: unknown }>;
+  };
+  for (const [key, property] of Object.entries(schema.properties ?? {})) {
+    const flag = property.type === "boolean" ? `--${key}` : `--${key} <value>`;
+    const hint = property.type === "array" ? " (comma-separated)" : property.type === "object" ? " (JSON)" : "";
+    command.option(flag, `${property.description ?? key}${hint}`);
+  }
+  command.action(async (options: Record<string, string | boolean | undefined>) => {
+    const fromJson = options.json ? (JSON.parse(String(options.json)) as Record<string, unknown>) : {};
+    const fromFlags = Object.fromEntries(
+      Object.entries(options)
+        .filter(([key, value]) => key !== "json" && value !== undefined)
+        .map(([key, value]) => {
+          const type = schema.properties?.[key]?.type;
+          if (type === "number" || type === "integer") return [key, Number(value)];
+          if (type === "boolean") return [key, value === true || value === "true"];
+          if (type === "array") return [key, String(value).split(",").map((item) => item.trim()).filter(Boolean)];
+          if (type === "object") return [key, JSON.parse(String(value))];
+          return [key, value];
+        }),
+    );
+    const args = op.input.parse({ ...fromJson, ...fromFlags });
+    const result = await op.handler(args as never, context());
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  });
+}
+
+program
+  .command("mcp")
+  .description("Serve the operations as an MCP server over stdio, or over streamable HTTP with --http")
+  .option(
+    "--http [port]",
+    "serve over MCP streamable HTTP instead of stdio (default port 3000, host 127.0.0.1, path /mcp)",
+  )
+  .option(
+    "--pair",
+    "serve over HTTP with a fresh pairing token: prints <url>#<token> and requires it as a bearer token",
+  )
+  .option("--open", "serve over HTTP and open the web app in this machine's browser")
+  .action(async (options: { http?: string | boolean; pair?: boolean; open?: boolean }) => {
+    const { serve, serveHttp } = await import("./mcp.js");
+    if (options.http === undefined && !options.pair && !options.open) await serve();
+    else {
+      const port = options.http === undefined || options.http === true ? 3000 : Number(options.http);
+      await serveHttp({ port, pair: options.pair, open: options.open });
+    }
+  });
+
+program.parseAsync(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/src/toolfactory/config.ts

@@ -0,0 +1,33 @@
+// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Context } from "./types.js";
+
+/**
+ * Where this tool may keep its own state: TOOLFACTORY_DATA_DIR when a host sets it, else the
+ * platform's own data location (XDG on POSIX, %LOCALAPPDATA% on Windows).
+ */
+function dataDir(): string {
+  // Hosts that launch the kernel export their own name for it: Agent Plugins clients and
+  // OpenClaw set PLUGIN_DATA, Claude Code sets CLAUDE_PLUGIN_DATA.
+  const configured =
+    process.env["TOOLFACTORY_DATA_DIR"] ??
+    process.env.PLUGIN_DATA ??
+    process.env.CLAUDE_PLUGIN_DATA;
+  if (configured) return configured;
+  const base =
+    process.platform === "win32"
+      ? (process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"))
+      : (process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"));
+  return join(base, "toolfactory");
+}
+
+/** Configuration is read from the environment; hosts inject it from their own settings UI. */
+export function context(): Context {
+  return {
+    config: {
+
+    },
+    dataDir: dataDir(),
+  };
+}

package/src/toolfactory/mcp.ts

@@ -0,0 +1,311 @@
+// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.
+/**
+ * The kernel MCP server: stdio by default; `--http [port]` (or `serveHttp()`) serves the
+ * same operations over MCP streamable HTTP instead, stateless per MCP 2026-07-28 (a fresh
+ * server instance per request, from `createMcpHandler`).
+ *
+ * The same listener serves the built web app: `/mcp` is the endpoint, everything else is a
+ * file under `web/dist`, so the page POSTs same-origin and `--open` is the whole launch.
+ * `handler()` is that router, exported so a host with its own listener (the OpenClaw plugin's
+ * gateway route) can mount it instead of binding a port.
+ */
+import { localhostHostValidation, toNodeHandler } from "@modelcontextprotocol/node";
+import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { execFile } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createServer as createHttpServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { dirname, join, extname, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { operations as authored } from "../ops.js";
+import { context } from "./config.js";
+import { serves } from "./types.js";
+import { web } from "./web.js";
+
+/** The authored operations plus the generated `web` one; `introspect` snapshots this list. */
+const operations = [...authored, web];
+
+/** toolfactory introspects with every operation visible; a served instance lists only what MCP can run. */
+const introspecting = Boolean(process.env.TOOLFACTORY_INTROSPECT);
+
+/** Builds one server instance with every servable operation registered; called once for stdio, once per HTTP request. */
+function createServer(): McpServer {
+  const server = new McpServer({ name: "toolfactory", version: "0.1.1" });
+  for (const op of operations) {
+    if (!introspecting && !serves(op, "mcp")) continue;
+    server.registerTool(
+      op.name,
+      {
+        description: op.description,
+        inputSchema: op.input as z.ZodObject,
+        outputSchema: (op.output ?? z.unknown()) as z.ZodType,
+        annotations: op.annotations,
+        _meta: { "dev.toolfactory": { requires: op.requires ?? [] } },
+      },
+      async (args: Record<string, unknown>) => {
+        const result = await op.handler(args as never, context());
+        return {
+          resultType: "complete" as const,
+          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+          structuredContent: result as Record<string, unknown>,
+        };
+      },
+    );
+  }
+  return server;
+}
+
+export const server = createServer();
+
+export async function serve(): Promise<void> {
+  await server.connect(new StdioServerTransport());
+}
+
+/**
+ * The pairing token, so a browser extension (or anything else on loopback) can prove it is the
+ * client the user paired: the endpoint requires `Authorization: Bearer <token>` when
+ * `TOOLFACTORY_MCP_TOKEN` is set or `mcp --http --pair` has written one under the data directory. With
+ * neither, nothing changes and the endpoint stays open on loopback.
+ */
+const TOKEN_FILE = "relay-token";
+
+function tokenPath(): string {
+  return join(context().dataDir, TOKEN_FILE);
+}
+
+function pairedToken(): string | undefined {
+  const configured = process.env["TOOLFACTORY_MCP_TOKEN"];
+  if (configured) return configured;
+  try {
+    return readFileSync(tokenPath(), "utf8").trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Mint a token and keep it 0600 under the data directory. Never rotates an existing one. */
+function mintToken(): string {
+  const token = randomBytes(32).toString("base64url");
+  mkdirSync(dirname(tokenPath()), { recursive: true });
+  writeFileSync(tokenPath(), `${token}\n`, { mode: 0o600 });
+  return token;
+}
+
+/** Constant-time comparison over digests, so neither the token nor its length leaks. */
+function authorized(header: string | undefined, token: string): boolean {
+  const digest = (value: string) => createHash("sha256").update(value).digest();
+  return timingSafeEqual(digest(header?.replace(/^Bearer /, "") ?? ""), digest(token));
+}
+
+/** The built page: `npm -C web run build` writes it beside the kernel, and the package ships it. */
+const WEB_DIST = fileURLToPath(new URL("../../web/dist/", import.meta.url));
+const TYPES: Record<string, string> = {
+  ".html": "text/html",
+  ".js": "text/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".woff2": "font/woff2",
+};
+
+/** One file under `web/dist`; a pathname with no extension is a client route, so the page answers. */
+function serveWeb(pathname: string, response: ServerResponse): void {
+  const relative = normalize(pathname.replace(/^\//, "")).replace(/^(\.\.[/\\])+/, "");
+  const file = join(WEB_DIST, extname(relative) ? relative : "index.html");
+  readFile(file).then(
+    (body) => {
+      response.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+      response.end(body);
+    },
+    () => {
+      response.writeHead(404, { "content-type": "text/plain" });
+      response.end(`no ${file}; run \`npm -C web run build\`\n`);
+    },
+  );
+}
+
+/**
+ * Best effort, by platform, because neither Node nor any single CLI opens a URL everywhere:
+ * a container, a CI runner and an SSH session have no opener and that must not fail the command.
+ */
+function openBrowser(url: string): void {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  execFile(command, args as string[], () => {});
+}
+
+/** The names this project declares; `/env` writes no other. */
+const SECRETS = ["NPM_TOKEN"];
+const ENV_LINE = (name: string) => new RegExp(`^\\s*(export\\s+)?${name}\\s*=`);
+
+function envPath(): string {
+  return join(process.cwd(), ".env");
+}
+
+/** Which declared names `.env` already carries a value for. Names only — never a value. */
+function envPresent(): string[] {
+  let text = "";
+  try {
+    text = readFileSync(envPath(), "utf8");
+  } catch {
+    return [];
+  }
+  return SECRETS.filter((name) =>
+    text.split("\n").some((line) => ENV_LINE(name).test(line) && line.split("=").slice(1).join("=").trim()),
+  );
+}
+
+/** Rewrite one line of `.env`, keeping every other line, and keep the file private. */
+function envWrite(name: string, value: string): void {
+  let lines: string[] = [];
+  try {
+    lines = readFileSync(envPath(), "utf8").replace(/\n$/, "").split("\n");
+  } catch {
+    lines = [];
+  }
+  const index = lines.findIndex((line) => ENV_LINE(name).test(line));
+  if (index === -1) lines.push(`${name}=${value}`);
+  else lines[index] = `${name}=${value}`;
+  writeFileSync(envPath(), `${lines.join("\n")}\n`, { mode: 0o600 });
+  chmodSync(envPath(), 0o600);
+  // The name, never the value: this log is the one place a secret could leak by accident.
+  console.error(`.env: set ${name}`);
+}
+
+/** `GET` the names present, `POST {name, value}` one of them. Writing needs the bearer token. */
+function serveEnv(request: IncomingMessage, response: ServerResponse, token: string | undefined): void {
+  const json = (status: number, body: unknown): void => {
+    response.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+  };
+  // Names, never values: what this project declares and which of them `.env` already carries.
+  if (request.method === "GET") return json(200, { declared: SECRETS, present: envPresent() });
+  if (request.method !== "POST") return json(405, { error: "GET or POST" });
+  // Even on loopback: without a token in force there is no client to trust with a write.
+  if (!token) return json(403, { error: "unpaired: restart with `mcp --http --open`" });
+  let body = "";
+  request.on("data", (chunk: Buffer) => {
+    body += chunk;
+  });
+  request.on("end", () => {
+    let name = "";
+    let value = "";
+    try {
+      ({ name, value } = JSON.parse(body) as { name: string; value: string });
+    } catch {
+      return json(400, { error: "expected {name, value}" });
+    }
+    if (!SECRETS.includes(name)) return json(400, { error: "not a declared secret" });
+    if (typeof value !== "string" || !value) return json(400, { error: "empty value" });
+    envWrite(name, value);
+    json(200, { declared: SECRETS, present: envPresent() });
+  });
+}
+
+export interface HandlerOptions {
+  /** Pathname the MCP endpoint answers on. */
+  path?: string;
+  /** Pathname the page is mounted under, when a host owns the listener (OpenClaw's plugin route). */
+  prefix?: string;
+  /** Bearer token the API routes require, when one is in force. */
+  token?: string;
+  /** Host-header guard, for a listener of our own on loopback. */
+  hostGuard?: (request: IncomingMessage, response: ServerResponse) => boolean;
+  /**
+   * Answer `/env`; off where the working directory is not the developer's own checkout (the
+   * OpenClaw route). Always declared, so a host mounting this handler needs no build-time
+   * knowledge of whether the project happens to declare a secret.
+   */
+  env?: boolean;
+}
+
+export interface HttpOptions {
+  port?: number;
+  host?: string;
+  path?: string;
+  /** Mint a fresh pairing token, print `<url>#<token>`, and require it from every client. */
+  pair?: boolean;
+  /** Ensure a token, then open the page in the machine's browser. */
+  open?: boolean;
+}
+
+/**
+ * The whole router, so a host that owns the listener mounts the same function: `path` answers
+ * MCP, `<prefix>/env` the Secrets panel, everything else is a file under `web/dist`. The token guards the
+ * two API routes, never the page — a browser cannot put a header on its own document request.
+ */
+export function handler(options: HandlerOptions = {}): (request: IncomingMessage, response: ServerResponse) => void {
+  const { path = "/mcp", prefix = "", token, hostGuard, env = true } = options;
+  const handle = toNodeHandler(createMcpHandler(createServer));
+  const unauthorized = (response: ServerResponse): void => {
+    response.writeHead(401, { "WWW-Authenticate": "Bearer" }).end();
+  };
+  return (request, response) => {
+    const { pathname } = new URL(request.url ?? "/", "http://localhost");
+    if (hostGuard && !hostGuard(request, response)) return;
+    if (pathname === path) {
+      if (token && !authorized(request.headers.authorization, token)) return unauthorized(response);
+      handle(request, response).catch((error: unknown) => {
+        console.error(error);
+        if (!response.headersSent) response.writeHead(500);
+        response.end();
+      });
+      return;
+    }
+    if (env && pathname === `${prefix}/env`) {
+      if (token && !authorized(request.headers.authorization, token)) return unauthorized(response);
+      serveEnv(request, response, token);
+      return;
+    }
+    serveWeb(pathname.slice(prefix.length), response);
+  };
+}
+
+/** Serve over MCP streamable HTTP instead of stdio. Opt-in; stdio stays the default transport. */
+export async function serveHttp(options: HttpOptions = {}): Promise<void> {
+  const { port = 3000, host = "127.0.0.1", path = "/mcp", pair = false, open = false } = options;
+  const loopback = host === "127.0.0.1" || host === "localhost" || host === "::1";
+  const hostGuard = loopback ? localhostHostValidation() : undefined;
+  // `--open` needs a token for the page to call back with; an existing one is never rotated,
+  // because the browser extension holds it.
+  const token = pair ? mintToken() : (pairedToken() ?? (open ? mintToken() : undefined));
+  const httpServer = createHttpServer(handler({ path, token, hostGuard }));
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, host, resolve);
+  });
+  // `--http 0` asks the OS for a free port; the URL is only known once it is bound.
+  const base = `http://${host}:${(httpServer.address() as { port: number }).port}`;
+  if (pair) process.stdout.write(`${base}${path}#${token}\n`);
+  console.error(
+    `Serving MCP streamable HTTP on ${base}${path}${token ? " (bearer token required)" : ""}`,
+  );
+  if (open) openBrowser(`${base}/#${token}`);
+}
+
+/** Parses a manually-run `node mcp.ts [--http [port]]` invocation; the CLI's `mcp` subcommand parses its own. */
+function httpPortArg(argv: string[]): number | undefined {
+  const index = argv.indexOf("--http");
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  return value && !value.startsWith("-") ? Number(value) : 3000;
+}
+
+if (process.argv[1] && /toolfactory[\\/]mcp\.[cm]?[jt]s$/.test(process.argv[1])) {
+  const port = httpPortArg(process.argv.slice(2));
+  const pair = process.argv.includes("--pair");
+  const open = process.argv.includes("--open");
+  (port === undefined && !pair && !open
+    ? serve()
+    : serveHttp({ port: port ?? 3000, pair, open })
+  ).catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

package/src/toolfactory/types.ts

@@ -0,0 +1,52 @@
+// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.
+import type { z } from "zod";
+
+/** Host capabilities an operation may declare. Portable: net, fs, shell, secret. */
+export type Capability =
+  | "net"
+  | "fs"
+  | "shell"
+  | "secret"
+  | "browser"
+  | "model"
+  | "user-input"
+  | "channel";
+
+export interface Context {
+  /** Configuration values read from the environment, keyed as declared in dev.toolfactory/tool.json. */
+  config: Record<string, string | undefined>;
+  /** Directory this tool may keep its own state in. Created by the tool, not by the kernel. */
+  dataDir: string;
+}
+
+export interface Operation<Input extends z.ZodObject = z.ZodObject, Output extends z.ZodType = z.ZodType> {
+  name: string;
+  description: string;
+  input: Input;
+  output?: Output;
+  requires?: Capability[];
+  annotations?: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+  handler: (args: z.infer<Input>, context: Context) => Promise<z.infer<Output>> | z.infer<Output>;
+}
+
+/** Identity function that pins the generic parameters so handlers are typed. */
+export function operation<Input extends z.ZodObject, Output extends z.ZodType>(
+  definition: Operation<Input, Output>,
+): Operation<Input, Output> {
+  return definition;
+}
+
+/** Capabilities every surface can satisfy on its own. */
+export const PORTABLE: ReadonlySet<Capability> = new Set(["net", "fs", "shell", "secret"]);
+
+/** Whether a surface can run an operation: MCP needs a portable one; a CLI also has a human for user-input. */
+export function serves(operation: { requires?: Capability[] }, surface: "mcp" | "cli"): boolean {
+  return (operation.requires ?? []).every(
+    (capability) => PORTABLE.has(capability) || (surface === "cli" && capability === "user-input"),
+  );
+}

package/src/toolfactory/web.ts

@@ -0,0 +1,45 @@
+// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.
+import { spawn } from "node:child_process";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { operation } from "./types.js";
+
+/** The kernel beside this file, in the form that is running: `.ts` under tsx, `.js` from dist. */
+const KERNEL = fileURLToPath(
+  new URL(`./mcp${extname(fileURLToPath(import.meta.url))}`, import.meta.url),
+);
+const SERVING = /Serving MCP streamable HTTP on (\S+)/;
+
+export const web = operation({
+  name: "web",
+  description:
+    "Open this tool's web app: serves the operations page and the MCP endpoint on a free local port, opens a browser there, and returns the URL.",
+  input: z.object({}),
+  output: z.object({ url: z.string() }),
+  requires: ["shell", "net"],
+  annotations: { openWorldHint: false },
+  handler: () =>
+    new Promise<{ url: string }>((resolve, reject) => {
+      const child = spawn(process.execPath, [...process.execArgv, KERNEL, "--http", "0", "--open"], {
+        detached: true,
+        stdio: ["ignore", "ignore", "pipe"],
+      });
+      let output = "";
+      child.on("error", reject);
+      child.on("exit", (code) => reject(new Error(`the kernel exited with ${code}: ${output}`)));
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk: string) => {
+        output += chunk;
+        const serving = SERVING.exec(output);
+        if (!serving) return;
+        // The child outlives this process; unref both handles so neither keeps it alive, and
+        // leave the pipe open so the kernel's own stderr never writes to a closed one.
+        child.unref();
+        (child.stderr as unknown as { unref: () => void }).unref();
+        // The page, not the endpoint, and without the token the child already handed the browser:
+        // an operation's result travels through an agent, and a token is a credential.
+        resolve({ url: new URL("/", serving[1]).href });
+      });
+    }),
+});

package/src/validate/agent-plugins.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent Plugins has no CLI validator; the spec forbids fetching schemas at load time, so
+ * the two official 1.0.0 schemas are vendored and checked here with Ajv (draft 2020-12).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv2020 } from "ajv/dist/2020.js";
+
+const SCHEMA_DIR = fileURLToPath(new URL("../../schemas/agent-plugins/", import.meta.url));
+
+export interface SchemaProblem {
+  file: string;
+  message: string;
+}
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMA_DIR, name), "utf8")) as Record<string, unknown>;
+}
+
+export function validateAgentPlugin(root: string): SchemaProblem[] {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const problems: SchemaProblem[] = [];
+  const targets: Array<[string, string]> = [
+    ["plugin.json", "plugin.schema.json"],
+    ["mcp.json", "mcp.schema.json"],
+  ];
+  for (const [file, schemaName] of targets) {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+      if (file === "plugin.json")
+        problems.push({ file, message: "missing (required for an Agent Plugins bundle)" });
+      continue;
+    }
+    let document: unknown;
+    try {
+      document = JSON.parse(readFileSync(path, "utf8"));
+    } catch (error) {
+      problems.push({ file, message: `not valid JSON: ${(error as Error).message}` });
+      continue;
+    }
+    const validate = ajv.compile(loadSchema(schemaName));
+    if (!validate(document)) {
+      for (const error of validate.errors ?? []) {
+        problems.push({
+          file,
+          message: `${error.instancePath || "/"} ${error.message ?? "invalid"}`,
+        });
+      }
+    }
+  }
+  return problems;
+}