toolfactory 0.1.1

package/dist/bindings/typescript.js

@@ -0,0 +1,758 @@
+import { secretsOf } from "../project/gate.js";
+import { configProperties, dataDirEnvName, envName, has, liveCredentials, liveExample, npmName, } from "../surfaces/shared.js";
+import { WEB_DIR } from "../surfaces/web.js";
+export const KERNEL_DIR = "src/toolfactory";
+export const OPS_PATH = "src/ops.ts";
+export 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 const LIVE_TEST_SCRIPT = `node --env-file-if-exists=.env node_modules/vitest/vitest.mjs run ${LIVE_TEST_PATH}`;
+const LIVE_GUARD_BEGIN = "// tf:live-guard";
+const LIVE_GUARD_END = "// /tf:live-guard";
+export function kernelCommand() {
+    return { command: "node", args: ["--import", "tsx", `${KERNEL_DIR}/mcp.ts`] };
+}
+export function cliCommand() {
+    return { command: "node", args: ["--import", "tsx", `${KERNEL_DIR}/cli.ts`] };
+}
+const HEADER = "// Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n";
+function typesTemplate() {
+    return `${HEADER}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"),
+  );
+}
+`;
+}
+function configTemplate(project) {
+    const keys = Object.keys(configProperties(project));
+    const entries = keys.map((key) => `  ${JSON.stringify(key)}: process.env[${JSON.stringify(envName(key))}],`);
+    const name = project.identity.name;
+    const dataDirEnv = dataDirEnvName(project);
+    return `${HEADER}import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Context } from "./types.js";
+
+/**
+ * Where this tool may keep its own state: ${dataDirEnv} 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[${JSON.stringify(dataDirEnv)}] ??
+    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, ${JSON.stringify(name)});
+}
+
+/** Configuration is read from the environment; hosts inject it from their own settings UI. */
+export function context(): Context {
+  return {
+    config: {
+${entries.join("\n")}
+    },
+    dataDir: dataDir(),
+  };
+}
+`;
+}
+/**
+ * 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 function liveTest(project) {
+    const credentials = liveCredentials(project).map(envName);
+    const example = liveExample(project);
+    if (credentials.length === 0 || !example)
+        return [];
+    const guard = `
+const CREDENTIALS = ${JSON.stringify(credentials)};
+const live = CREDENTIALS.every((name) => process.env[name]);
+`;
+    const template = `/**
+ * Live tests: real calls against the real service, so they run only when the credentials
+ * (${credentials.join(", ")}) are in the environment — \`npm test\` skips them.
+ *
+ * Locally: copy .env.example to .env, fill it in, then \`npm run test:live\`.
+ * In CI:   the \`live\` job of .github/workflows/ci.yml, from the \`live-tests\` environment.
+ */
+import { describe, expect, it } from "vitest";
+import { operations } from "../src/ops.js";
+import { context } from "../src/toolfactory/config.js";
+
+${LIVE_GUARD_BEGIN}${LIVE_GUARD_END}
+
+describe.skipIf(!live)(${JSON.stringify(`${project.identity.name} against the real service`)}, () => {
+  it(${JSON.stringify(`${example.name} answers`)}, async () => {
+    const operation = operations.find((candidate) => candidate.name === ${JSON.stringify(example.name)});
+    if (!operation) throw new Error(${JSON.stringify(`no operation named ${example.name}; point this test at another one`)});
+    const result = await operation.handler(${JSON.stringify(example.args)} as never, context());
+    // Replace this with the assertion that proves the real service answered correctly.
+    expect(result).toBeDefined();
+  });
+});
+`;
+    return [
+        {
+            kind: "region",
+            path: LIVE_TEST_PATH,
+            regions: [{ begin: LIVE_GUARD_BEGIN, end: LIVE_GUARD_END, content: guard }],
+            template,
+        },
+    ];
+}
+/**
+ * What the kernel adds when the `web` surface is selected: the static half of the router (the
+ * built page under `web/dist`), the OS opener `--open` shells out to, and — only when the
+ * project declares a secret — the `/env` route the page's Secrets panel reads and writes.
+ * `.env` is the developer's own file, resolved from the working directory: names out, one
+ * name in, never a value in a log or a response.
+ */
+function webRoutes(secrets) {
+    const env = !secrets.length
+        ? ""
+        : `
+/** The names this project declares; \`/env\` writes no other. */
+const SECRETS = ${JSON.stringify(secrets)};
+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() });
+  });
+}
+`;
+    return `
+/** The built page: \`npm -C ${WEB_DIR} run build\` writes it beside the kernel, and the package ships it. */
+const WEB_DIST = fileURLToPath(new URL("../../${WEB_DIR}/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_DIR} 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[], () => {});
+}
+${env}
+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;
+}
+`;
+}
+function mcpTemplate(project) {
+    const tokenEnv = `${envName(project.identity.name)}_MCP_TOKEN`;
+    const web = has(project, "web");
+    const secrets = web ? secretsOf(project) : [];
+    return `${HEADER}/**
+ * 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\`).${web
+        ? `
+ *
+ * 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";${web
+        ? `
+import { execFile } from "node:child_process";`
+        : ""}
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { ${secrets.length ? "chmodSync, " : ""}mkdirSync, readFileSync, writeFileSync } from "node:fs";${web
+        ? `
+import { readFile } from "node:fs/promises";`
+        : ""}
+import { createServer as createHttpServer${web ? ", type IncomingMessage, type ServerResponse" : ""} } from "node:http";
+import { dirname, join${web ? ", extname, normalize" : ""} } from "node:path";${web
+        ? `
+import { fileURLToPath } from "node:url";`
+        : ""}
+import { z } from "zod";
+import { operations${web ? " as authored" : ""} } from "../ops.js";
+import { context } from "./config.js";
+import { serves } from "./types.js";${web
+        ? `
+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: ${JSON.stringify(project.identity.name)}, version: ${JSON.stringify(project.identity.version ?? "0.0.0")} });
+  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
+ * \`${tokenEnv}\` 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[${JSON.stringify(tokenEnv)}];
+  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));
+}
+${web ? webRoutes(secrets) : ""}
+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;${web
+        ? `
+  /** Ensure a token, then open the page in the machine's browser. */
+  open?: boolean;`
+        : ""}
+}
+${web
+        ? `
+/**
+ * The whole router, so a host that owns the listener mounts the same function: \`path\` answers
+ * MCP, ${secrets.length ? "`<prefix>/env` the Secrets panel, " : ""}everything else is a file under \`web/dist\`. The token guards the
+ * ${secrets.length ? "two API routes" : "endpoint"}, 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${secrets.length ? ", 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;
+    }${secrets.length
+            ? `
+    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${web ? ", 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() : ${web ? "(pairedToken() ?? (open ? mintToken() : undefined))" : "pairedToken()"};
+${web
+        ? "  const httpServer = createHttpServer(handler({ path, token, hostGuard }));"
+        : `  const handle = toNodeHandler(createMcpHandler(createServer));
+  const httpServer = createHttpServer((request, response) => {
+    if (new URL(request.url ?? "/", "http://localhost").pathname !== path) {
+      response.writeHead(404).end();
+      return;
+    }
+    if (hostGuard && !hostGuard(request, response)) return;
+    if (token && !authorized(request.headers.authorization, token)) {
+      response.writeHead(401, { "WWW-Authenticate": "Bearer" }).end();
+      return;
+    }
+    handle(request, response).catch((error: unknown) => {
+      console.error(error);
+      if (!response.headersSent) response.writeHead(500);
+      response.end();
+    });
+  });`}
+  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)" : ""}\`,
+  );${web
+        ? `
+  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");${web
+        ? `
+  const open = process.argv.includes("--open");
+  (port === undefined && !pair && !open
+    ? serve()
+    : serveHttp({ port: port ?? 3000, pair, open })
+  ).catch((error) => {`
+        : `
+  (port === undefined && !pair ? serve() : serveHttp({ port: port ?? 3000, pair })).catch((error) => {`}
+    console.error(error);
+    process.exit(1);
+  });
+}
+`;
+}
+/**
+ * The `web` operation, generated with the `web` surface: it reaches every surface at once
+ * (MCP `tools/call`, the skill, the CLI, the page itself) without a socket inside the stdio
+ * server — the kernel's own HTTP listener runs in a detached child, which is also what opens
+ * the browser, so the page appears on the machine running the tool and no host has to open a
+ * URL a tool returns.
+ */
+function webTemplate() {
+    return `${HEADER}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 });
+      });
+    }),
+});
+`;
+}
+function cliTemplate(project) {
+    const web = has(project, "web");
+    return `#!/usr/bin/env node
+${HEADER}import { Command } from "commander";
+import { z } from "zod";
+import { operations${web ? " as authored" : ""} } from "../ops.js";
+import { context } from "./config.js";
+import { serves } from "./types.js";${web
+        ? `
+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(${JSON.stringify(project.identity.name)})
+  .description(${JSON.stringify(project.identity.description ?? project.identity.name)})
+  .version(${JSON.stringify(project.identity.version ?? "0.0.0")});
+
+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\`);
+  });
+}
+
+${has(project, "mcp")
+        ? `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",
+  )${web
+            ? `
+  .option("--open", "serve over HTTP and open the web app in this machine's browser")`
+            : ""}
+  .action(async (options: { http?: string | boolean; pair?: boolean${web ? "; open?: boolean" : ""} }) => {
+    const { serve, serveHttp } = await import("./mcp.js");
+    if (options.http === undefined && !options.pair${web ? " && !options.open" : ""}) await serve();
+    else {
+      const port = options.http === undefined || options.http === true ? 3000 : Number(options.http);
+      await serveHttp({ port, pair: options.pair${web ? ", open: options.open" : ""} });
+    }
+  });
+
+`
+        : ""}program.parseAsync(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});
+`;
+}
+function opsScaffold() {
+    return `import { z } from "zod";
+import { operation } from "./toolfactory/types.js";
+
+/**
+ * Your tool's operations: pure functions of (arguments, context.config, filesystem).
+ * Declare \`requires\` for anything a host must provide; toolfactory decides per surface
+ * whether that operation is native, bridged, degraded, or excluded.
+ */
+export const operations = [
+  operation({
+    name: "echo",
+    description: "Return the text you pass in.",
+    input: z.object({ text: z.string().describe("Text to echo back") }),
+    output: z.object({ text: z.string() }),
+    annotations: { readOnlyHint: true },
+    handler: async ({ text }) => ({ text }),
+  }),
+];
+`;
+}
+/** The kernel, generated on every build for every tool: the contract, config, and the MCP server toolfactory introspects. */
+export function kernel(project) {
+    return [
+        { kind: "file", path: `${KERNEL_DIR}/types.ts`, content: typesTemplate() },
+        { kind: "file", path: `${KERNEL_DIR}/config.ts`, content: configTemplate(project) },
+        { kind: "file", path: `${KERNEL_DIR}/mcp.ts`, content: mcpTemplate(project) },
+        // The `web` surface's own operation: generated here because it is the kernel's listener it
+        // starts, and appended to `operations` by the two templates above, so `introspect` sees it.
+        ...(has(project, "web")
+            ? [{ kind: "file", path: `${KERNEL_DIR}/web.ts`, content: webTemplate() }]
+            : []),
+    ];
+}
+/** The CLI surface's file. */
+export function cli(project) {
+    return [{ kind: "file", path: `${KERNEL_DIR}/cli.ts`, content: cliTemplate(project) }];
+}
+/** The Node floor every generated TypeScript project declares (vite 8 and the MCP SDK need it). */
+export const NODE_ENGINES = ">=22.12";
+/** Written by `init` only when absent; owned by the author afterwards. */
+export function scaffold(project) {
+    const packageJson = {
+        name: npmName(project),
+        version: project.identity.version ?? "0.1.0",
+        description: project.identity.description,
+        license: project.identity.license,
+        repository: project.identity.repository,
+        homepage: project.identity.homepage,
+        keywords: project.identity.keywords,
+        type: "module",
+        engines: { node: NODE_ENGINES },
+        scripts: {
+            build: "tsc -p tsconfig.json",
+            test: "vitest run --passWithNoTests",
+            "test:live": LIVE_TEST_SCRIPT,
+        },
+        dependencies: {
+            "@modelcontextprotocol/node": "^2.0.0",
+            "@modelcontextprotocol/server": "^2.0.0",
+            commander: "^15.0.0",
+            zod: "^4.0.0",
+        },
+        devDependencies: {
+            "@types/node": "^22.0.0",
+            toolfactory: `^${project.toolfactoryVersion}`,
+            tsx: "^4.0.0",
+            typescript: "^6.0.0",
+            vitest: "^4.0.0",
+        },
+    };
+    const tsconfig = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            declaration: true,
+            outDir: "dist",
+            rootDir: "src",
+            skipLibCheck: true,
+            types: ["node"],
+        },
+        include: ["src/**/*.ts"],
+    };
+    return [
+        { kind: "file", path: OPS_PATH, content: opsScaffold() },
+        { kind: "file", path: "package.json", content: `${JSON.stringify(packageJson, null, 2)}\n` },
+        { kind: "file", path: "tsconfig.json", content: `${JSON.stringify(tsconfig, null, 2)}\n` },
+    ];
+}