toolfactory 0.1.1

package/src/surfaces/dsh.ts

@@ -0,0 +1,159 @@
+/**
+ * DSH (DeepSeek Harness), experimental: a zero-code Cordis bundle that attaches the tool's own
+ * MCP server through DSH's first-party `@deepseek-ai/dsh-mcp-client`.
+ *
+ * `hosts/dsh/` is two files and no code — a `package.json` whose only load-bearing key is
+ * `dsh.bundle.patch` (that one expression is DSH's whole acceptance test for a bundle) and the
+ * Cordis patch it names, one `insert` row. Nothing else is emitted, on purpose: a bundle that
+ * shipped a Cordis plugin would have to track the `ToolDefinition`/`inject` API — the fastest
+ * moving part of an alpha harness — and would put its package name and version into the
+ * `dsh_plugin_packages` inventory DSH sends to the model endpoint on every request. The row keys
+ * this file writes are byte-identical across every published DSH version; the parts that did
+ * move (profile templates, `patchReload`) are DSH-owned state written by `dsh plugin`.
+ *
+ * The bundle declares no dependency: `@deepseek-ai/dsh-mcp-client` is a direct dependency of
+ * `@deepseek-ai/dsh` itself, symlinked into `$DSH_HOME/profiles/node_modules/` as every
+ * profile's resolution fallback, so declaring it would only invite a version mismatch on a
+ * package the user cannot independently satisfy.
+ *
+ * Every DSH-specific string lives here and nowhere else.
+ */
+import { Scalar, stringify as yamlStringify } from "yaml";
+import { getBinding } from "../bindings/index.js";
+import { projectName } from "../identity/name.js";
+import type { Project, Surface } from "../model.js";
+import { compact, configProperties, envName, json, kernelLaunch, mcpVerdict } from "./shared.js";
+
+/**
+ * The `@deepseek-ai/dsh` release `validate()` boots. Pinned, not `@alpha`: npm's `latest` tag
+ * lags the alpha line by weeks, so an unpinned install is neither current nor reproducible.
+ * Renovate bumps this constant (`renovate.json` `customManagers`).
+ */
+export const DSH_PIN = "0.1.2-alpha.5";
+
+export const HOST_DIR = "hosts/dsh";
+/** The patch file name `dsh.bundle.patch` points at; DSH's own convention for a Cordis overlay. */
+export const PATCH_FILE = "cordis.patch.yml";
+/**
+ * The same row against this checkout instead of the published package. Kept out of `files`, so
+ * `npm pack ./hosts/dsh` never ships it: it is what `validate()` boots and what a developer
+ * passes to `dsh --patch` to drive the working tree.
+ */
+export const LOCAL_PATCH_FILE = "cordis.local.patch.yml";
+
+/** DSH's first-party MCP bridge; the only plugin the bundle names. */
+const MCP_CLIENT = "@deepseek-ai/dsh-mcp-client";
+/** `headless` is one-shot and ships an app bundle; a profile without one blocks forever. */
+export const PROFILE = "headless";
+/**
+ * The pass signature of the keyless boot probe. Reaching it proves, in order: the patch parsed,
+ * the row is a valid loader entry, the mcp-client resolved, its config passed the plugin schema,
+ * the MCP server spawned, and `initialize` + `tools/list` succeeded — `failOnStartupError` makes
+ * every one of those a hard failure before the model is ever consulted. The run then dies on the
+ * DeepSeek credential nobody has in CI, which is the exit this validator asserts.
+ */
+const MISSING_CREDENTIAL = "MISSING_CREDENTIAL: llm-deepseek";
+
+/** `!!js <expr>` — the `tag:yaml.org,2002:js` scalar DSH evaluates when it loads a patch. */
+function jsExpression(source: string): Scalar {
+  const scalar = new Scalar(source);
+  scalar.tag = "!!js";
+  return scalar;
+}
+
+/**
+ * One `insert` row for the mcp-client. `env` restates every config variable as a `!!js` lookup
+ * because DSH scrubs any parent name matching /KEY|PASSWORD|SECRET|TOKEN/i (and every `DSH_*`)
+ * before spawning an MCP server: an unrestated credential simply never arrives.
+ */
+function patch(project: Project, launch: { command: string; args: string[] }): string {
+  const serverName = projectName.dshServer(project.identity.name);
+  const env = Object.fromEntries(
+    Object.keys(configProperties(project)).map((key) => [
+      envName(key),
+      jsExpression(`process.env.${envName(key)}`),
+    ]),
+  );
+  const row = {
+    id: rowId(project),
+    name: MCP_CLIENT,
+    config: compact({
+      serverName,
+      transport: "stdio",
+      ...launch,
+      env: Object.keys(env).length ? env : undefined,
+      failOnStartupError: true,
+    }),
+  };
+  return yamlStringify([{ insert: [row] }], { lineWidth: 0 });
+}
+
+/** The public name a bridged MCP tool takes in DSH; `mcp__<serverName>__<rawName>` is its contract. */
+export function toolName(project: Project, operation: string): string {
+  return `mcp__${projectName.dshServer(project.identity.name)}__${operation}`;
+}
+
+/** The row id and, with it, the `# == <bundle>` layer `--dump-config` prints. */
+export function rowId(project: Project): string {
+  return `mcp-${projectName.dshServer(project.identity.name)}`;
+}
+
+/** The tarball `npm pack ./hosts/dsh` writes into the release assets, by name. */
+export function dshTarball(project: Project): string {
+  const name = projectName.dshPackage(project.identity.name);
+  return `${name}-${project.identity.version ?? "0.0.0"}.tgz`;
+}
+
+export const surface: Surface = {
+  id: "dsh",
+  plan(project) {
+    const { identity } = project;
+    const manifest = compact({
+      name: projectName.dshPackage(identity.name),
+      version: identity.version,
+      description: `DSH bundle for ${identity.name}: attaches its MCP server through ${MCP_CLIENT}.`,
+      license: identity.license,
+      files: [PATCH_FILE],
+      dsh: { bundle: { patch: `./${PATCH_FILE}` } },
+    });
+    return [
+      { kind: "file", path: `${HOST_DIR}/package.json`, content: json(manifest) },
+      {
+        kind: "file",
+        path: `${HOST_DIR}/${PATCH_FILE}`,
+        // `cwd` is deliberately absent: an installed bundle has no path to point at, and the
+        // published launch resolves through the registry from wherever DSH is running.
+        content: patch(project, kernelLaunch(project, ".")),
+      },
+      {
+        kind: "file",
+        path: `${HOST_DIR}/${LOCAL_PATCH_FILE}`,
+        // The kernel as `introspect` and `inspector.json` spawn it: repo-relative, so it resolves
+        // against the directory DSH itself was started in.
+        content: patch(project, getBinding(project.tool.binding).kernelCommand(project)),
+      },
+    ];
+  },
+  validate(project) {
+    // A fresh DSH_HOME per run: an id already present from an installed bundle would collide
+    // (`duplicate loader entry id`), and the profile is initialised on first use anyway.
+    const script = [
+      'DSH_HOME="$(mktemp -d)"; export DSH_HOME DSH_TELEMETRY_DISABLED=1',
+      `out="$(env -u DEEPSEEK_API_KEY -u DEEPSEEK_BASE_URL npx -y @deepseek-ai/dsh@${DSH_PIN} --profile ${PROFILE} --patch ${HOST_DIR}/${LOCAL_PATCH_FILE} 'toolfactory dsh surface probe' 2>&1)"`,
+      'rm -rf "$DSH_HOME"',
+      'printf "%s\\n" "$out"',
+      `printf "%s" "$out" | grep -qF '${MISSING_CREDENTIAL}'`,
+    ].join("\n");
+    return [
+      {
+        label: "dsh headless boot (keyless)",
+        command: "sh",
+        args: ["-c", script],
+        cwd: project.root,
+      },
+    ];
+  },
+  // The tools reach the model as `mcp__<serverName>__<operation>`: DSH's MCP client carries tool
+  // calls and nothing else, so the rule is the `mcp` surface's own.
+  verdict: mcpVerdict,
+};

package/src/surfaces/external.ts

@@ -0,0 +1,13 @@
+/**
+ * Surfaces that write nothing of their own and exist for their coverage row and their
+ * effect on other surfaces:
+ *
+ * - `clawhub` publishes the OpenClaw-native package; its only artifact is the release leg
+ *   `workflows` emits when it is selected together with `openclaw-native`.
+ */
+import type { Surface } from "../model.js";
+
+export const clawhub: Surface = {
+  id: "clawhub",
+  plan: () => [],
+};

package/src/surfaces/gemini.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import type { Operation, Project } from "../model.js";
+import { GEMINI_PIN, surface as gemini } from "./gemini.js";
+
+const echo: Operation = { name: "echo", inputSchema: { type: "object" }, requires: [] };
+const browse: Operation = {
+  name: "browse",
+  inputSchema: { type: "object" },
+  requires: ["browser"],
+};
+
+const project: Project = {
+  root: "/repo",
+  tool: {
+    schemaVersion: 1,
+    identity: "plugin.json",
+    binding: "typescript",
+    surfaces: ["mcp", "npm", "skill", "gemini"],
+    bundle: { runtime: "package" },
+    tests: { examples: {} },
+    config: {
+      properties: {
+        apiKey: { type: "string", title: "API key", "x-toolfactory": { sensitive: true } },
+        region: { type: "string", description: "Service region." },
+      },
+      required: ["apiKey"],
+    },
+  },
+  identity: { name: "hello.tool", version: "0.1.0", description: "Says hello.", license: "MIT" },
+  identityExtra: {},
+  operations: [echo, browse],
+  toolfactoryVersion: "0.1.0",
+  packageManager: "npm",
+};
+
+const [manifestFile, ...rest] = gemini.plan(project);
+if (manifestFile?.kind !== "file") throw new Error("expected one whole file");
+const manifest = JSON.parse(manifestFile.content) as Record<string, unknown>;
+
+describe("gemini", () => {
+  it("is one root manifest: a dashed name, the kernel launch, AGENTS.md as the context file", () => {
+    expect(rest).toEqual([]);
+    expect(manifestFile.path).toBe("gemini-extension.json");
+    expect(manifest).toEqual({
+      // Gemini rejects anything outside [A-Za-z0-9-], so the dot in N becomes a dash.
+      name: "hello-tool",
+      version: "0.1.0",
+      description: "Says hello.",
+      mcpServers: { "hello.tool": { command: "npx", args: ["-y", "hello.tool@0.1.0", "mcp"] } },
+      // Not GEMINI.md: the always-on `agents` surface writes AGENTS.md, and Gemini's own
+      // validator fails when the named context file is missing.
+      contextFileName: "AGENTS.md",
+      // Gemini passes an extension no shell environment beyond what `settings[].envVar`
+      // allowlists, so every config key is declared here and none in an `env` map.
+      settings: [
+        { name: "API key", description: "apiKey", envVar: "APIKEY", sensitive: true },
+        { name: "region", description: "Service region.", envVar: "REGION" },
+      ],
+    });
+    // `skills/` and `commands/` are auto-discovered from the extension root; no key names them.
+    expect(manifestFile.content).not.toContain('"skills"');
+  });
+
+  it("validates through Gemini's own manifest validator, and carries only MCP tool calls", () => {
+    expect(gemini.validate?.(project)).toEqual([
+      {
+        label: "gemini extensions validate",
+        command: "npx",
+        args: ["-y", `@google/gemini-cli@${GEMINI_PIN}`, "extensions", "validate", "."],
+        cwd: "/repo",
+      },
+    ]);
+
+    expect(gemini.verdict?.(echo, project)).toEqual({ kind: "native" });
+    expect(gemini.verdict?.(browse, project)).toEqual({
+      kind: "excluded",
+      reason: "excluded:mcp-no-host-capabilities",
+    });
+  });
+});

package/src/surfaces/gemini.ts

@@ -0,0 +1,84 @@
+/**
+ * Gemini CLI extension: one `gemini-extension.json` at the repository root, which is the entire
+ * install channel. `gemini extensions install https://github.com/<owner>/<repo>` takes any public
+ * repository carrying that file — no submission, no catalog PR — and geminicli.com/extensions
+ * lists it from the same manifest.
+ *
+ * Three things it deliberately does not emit:
+ *
+ * - No `skills` or `commands` key. Gemini auto-discovers `skills/` and `commands/` from the
+ *   extension root, and the extension root is the repository root, so the `skill` surface's
+ *   directory already is the extension's skills.
+ * - No `GEMINI.md`. `contextFileName` points at `AGENTS.md`, which the always-on `agents` surface
+ *   writes and every other harness reads; `.agents/sync.py` renders `GEMINI.md` as the one line
+ *   `@AGENTS.md` for interactive use, and the extension needs no second copy of it.
+ * - No `env` on the MCP server row. Gemini does not pass the user's shell environment to an
+ *   extension: only standard-safe variables and those declared in `settings[].envVar` are
+ *   allowlisted through to its MCP servers, so the config schema projects onto `settings` and an
+ *   `env` map would name variables that never arrive.
+ */
+
+import { projectName } from "../identity/name.js";
+import type { Surface } from "../model.js";
+import { AGENTS_PATH } from "./agents.js";
+import {
+  compact,
+  configProperties,
+  envName,
+  isSensitive,
+  json,
+  kernelLaunch,
+  mcpVerdict,
+} from "./shared.js";
+
+export const MANIFEST_PATH = "gemini-extension.json";
+
+/**
+ * The `@google/gemini-cli` release `validate()` runs. Pinned so the gate is reproducible;
+ * Renovate bumps this constant (`renovate.json` `customManagers`).
+ */
+export const GEMINI_PIN = "0.58.0";
+
+/** Gemini rejects any extension name outside `[A-Za-z0-9-]`; the projection lives in `projectName`. */
+export const extensionName = projectName.gemini;
+
+export const surface: Surface = {
+  id: "gemini",
+  plan(project) {
+    const { identity } = project;
+    const settings = Object.entries(configProperties(project)).map(([key, property]) =>
+      compact({
+        name: (property.title as string | undefined) ?? key,
+        description: (property.description as string | undefined) ?? key,
+        envVar: envName(key),
+        sensitive: isSensitive(property) || undefined,
+      }),
+    );
+    const manifest = compact({
+      name: extensionName(identity.name),
+      version: identity.version,
+      description: identity.description,
+      // `${extensionPath}` is the installed copy's own directory: an install is a copy, not a
+      // checkout, so a bundled kernel is only reachable through it.
+      mcpServers: { [identity.name]: kernelLaunch(project, "${extensionPath}") },
+      contextFileName: AGENTS_PATH,
+      settings: settings.length ? settings : undefined,
+    });
+    return [{ kind: "file", path: MANIFEST_PATH, content: json(manifest) }];
+  },
+  validate(project) {
+    // Gemini's own manifest validator: it parses the manifest, enforces the name and version
+    // rules, and fails when `contextFileName` names a file that is not there. Keyless — it never
+    // reaches the model — so it is the gate rather than a schema of our own.
+    return [
+      {
+        label: "gemini extensions validate",
+        command: "npx",
+        args: ["-y", `@google/gemini-cli@${GEMINI_PIN}`, "extensions", "validate", "."],
+        cwd: project.root,
+      },
+    ];
+  },
+  // The extension carries MCP tool calls and nothing else: the rule is the `mcp` surface's own.
+  verdict: mcpVerdict,
+};

package/src/surfaces/hermes-native.test.ts

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { describe, expect, it } from "vitest";
+import { parse as parseYaml } from "yaml";
+import type { Operation, Project } from "../model.js";
+import { HOST_DIR, pluginDir, surface } from "./hermes-native.js";
+
+const echo: Operation = {
+  name: "echo",
+  description: "Return the text you pass in.",
+  inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"],
+  },
+  outputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
+  requires: [],
+};
+const shoot: Operation = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+
+function project(overrides: Partial<Project> = {}): Project {
+  return {
+    root: "/repo",
+    tool: {
+      schemaVersion: 1,
+      identity: "package.json",
+      binding: "typescript",
+      surfaces: ["hermes-native", "cli"],
+      bundle: { runtime: "package" },
+      tests: { examples: { echo: { text: "hi" } } },
+      config: {
+        type: "object",
+        properties: {
+          apiKey: {
+            description: "Acme key",
+            "x-toolfactory": { sensitive: true, url: "https://a" },
+          },
+          region: { description: "Acme region" },
+        },
+        required: ["apiKey"],
+      },
+      ...overrides.tool,
+    },
+    identity: { name: "hello", version: "1.2.0", description: "Say hello" },
+    identityExtra: {},
+    operations: [echo, shoot],
+    toolfactoryVersion: "0.1.0",
+    ...overrides,
+  };
+}
+
+function emitted(target: Project): Record<string, string> {
+  return Object.fromEntries(
+    surface.plan(target).map((file) => [file.path, file.kind === "file" ? file.content : ""]),
+  );
+}
+
+const python = project({ tool: { ...project().tool, binding: "python" } });
+
+describe("hermes-native", () => {
+  it("projects the manifest Hermes parses and the credentials it prompts for", () => {
+    const files = emitted(project());
+    const manifest = parseYaml(files[`${pluginDir(project())}/plugin.yaml`] ?? "") as Record<
+      string,
+      // biome-ignore lint/suspicious/noExplicitAny: manifest is untyped upstream YAML
+      any
+    >;
+    // 1, not the loader's newer-supported 2: `hermes plugins install`'s own cap is still stuck
+    // at 1 and rejects a v2 manifest outright, even though the loader and `doctor` accept it.
+    expect(manifest.manifest_version).toBe(1);
+    expect(manifest.name).toBe("hello");
+    // Only what the surface can actually run: `shoot` is excluded, so it is never advertised.
+    expect(manifest.provides_tools).toEqual(["echo"]);
+    expect(surface.verdict?.(shoot, project())).toEqual({
+      kind: "excluded",
+      reason: "excluded:implement-in-hosts",
+    });
+    // One credential declaration becomes the rich env form Hermes' config UI prompts from.
+    expect(manifest.requires_env).toEqual([
+      {
+        name: "APIKEY",
+        description: "Acme key",
+        secret: true,
+        url: "https://a",
+      },
+    ]);
+    expect(manifest.optional_env.map((entry: { name: string }) => entry.name)).toEqual([
+      "REGION",
+      "HELLO_ROOT",
+    ]);
+
+    const pyproject = parseToml(files[`${HOST_DIR}/pyproject.toml`] ?? "") as Record<
+      string,
+      // biome-ignore lint/suspicious/noExplicitAny: TOML is untyped
+      any
+    >;
+    expect(pyproject.project["entry-points"]["hermes_agent.plugins"]).toEqual({
+      hello: "hello_hermes:register",
+    });
+  });
+
+  it("shims a TypeScript core out of process and calls a Python core in it", () => {
+    const shim = emitted(project())[`${pluginDir(project())}/__init__.py`] ?? "";
+    expect(surface.verdict?.(echo, project())).toEqual({
+      kind: "degraded",
+      reason: "degraded:out-of-process",
+    });
+    expect(shim).toContain('KERNEL = ["node", "--import", "tsx", "src/toolfactory/cli.ts"]');
+    expect(shim).toContain('_ROOT = os.environ.get("HELLO_ROOT")');
+    // Hermes' own per-plugin data directory reaches the kernel through the shared variable.
+    expect(shim).toContain('os.environ.setdefault("HELLO_DATA_DIR", str(ctx.state.data_dir))');
+
+    const native = emitted(python)[`${pluginDir(python)}/__init__.py`] ?? "";
+    expect(surface.verdict?.(echo, python)).toEqual({ kind: "native" });
+    expect(native).toContain("from hello.ops import OPERATIONS");
+    expect(native).not.toContain("subprocess");
+    // The published wheel resolves the pin; the checkout resolves the uv path source.
+    const pyproject = parseToml(emitted(python)[`${HOST_DIR}/pyproject.toml`] ?? "") as Record<
+      string,
+      // biome-ignore lint/suspicious/noExplicitAny: TOML is untyped
+      any
+    >;
+    expect(pyproject.project.dependencies).toEqual(["hello>=1.2.0,<2"]);
+    expect(pyproject.tool.uv.sources.hello).toEqual({ path: "../..", editable: true });
+  });
+
+  it("emits a fake-ctx test that registers and calls a real handler, no Hermes import", () => {
+    const shim = emitted(project())[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
+    expect(shim).not.toMatch(/^\s*(import|from) hermes/m);
+    expect(shim).toContain("from hello_hermes import register");
+    expect(shim).toContain("def register_tool(self, **kwargs: Any) -> None:");
+    expect(shim).toContain("self.state = _State(data_dir)");
+    // `shoot` is excluded (browser), so only `echo` is registered and only `echo` is callable.
+    expect(shim).toContain('assert [r["name"] for r in ctx.registrations] == ["echo"]');
+    expect(shim).toContain('r["name"] == "echo"');
+    expect(shim).toContain('handler({"text":"hi"})');
+    // The marker comes from `echo`'s own output schema, not a hardcoded assumption.
+    expect(shim).toContain('assert "text" in result');
+    expect(shim).toContain("checkout and Node, which the shim handler spawns");
+
+    const native = emitted(python)[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
+    expect(native).toContain("from hello_hermes import register");
+    expect(native).not.toContain("and Node");
+  });
+});
+
+function hasHermes(): boolean {
+  try {
+    execFileSync("hermes", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The only claim that matters: Hermes' own runtime discovers, imports and registers this. */
+describe.skipIf(!hasHermes())("hermes plugins doctor", () => {
+  it("loads and registers the generated plugin", () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-hermes-"));
+    try {
+      for (const file of surface.plan(project())) {
+        if (file.kind !== "file") continue;
+        mkdirSync(dirname(join(root, file.path)), { recursive: true });
+        writeFileSync(join(root, file.path), file.content);
+      }
+      const commands = surface.validate?.({ ...project(), root }) ?? [];
+      const command = commands.find((c) => c.label === "hermes plugins doctor");
+      if (!command) throw new Error("the hermes surface no longer declares a doctor validator");
+      const output = execFileSync(command.command, command.args, { cwd: root, encoding: "utf8" });
+      expect(output).toContain("registrations: 1 tool(s)");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});