toolfactory 0.1.1

package/dist/identity/name.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { assertValidName, githubOwner, projectName } from "./name.js";
+describe("projectName", () => {
+    it("projects the canonical name N onto every wire-visible identifier", () => {
+        expect(projectName.npm("hello")).toBe("hello");
+        expect(projectName.npm("hello", "acme")).toBe("@acme/hello");
+        expect(projectName.npm("hello", "@acme")).toBe("@acme/hello");
+        expect(projectName.pypi("hello.tool")).toBe("hello-tool");
+        expect(projectName.pythonPackage("hello.tool-kit")).toBe("hello_tool_kit");
+        expect(projectName.cursor("hello.tool")).toBe("hello-tool");
+        expect(projectName.openclawPackage("hello")).toBe("openclaw-plugin-hello");
+        expect(projectName.mcpRegistry("hello", "acme")).toBe("io.github.acme/hello");
+        expect(projectName.hermesToolset("hello.tool-kit")).toBe("hello_tool_kit");
+    });
+});
+describe("githubOwner", () => {
+    it("reads the owner out of a github repository URL", () => {
+        expect(githubOwner("https://github.com/acme/hello")).toBe("acme");
+        expect(githubOwner("git@github.com:acme/hello.git")).toBe("acme");
+        expect(githubOwner(undefined)).toBeUndefined();
+        expect(githubOwner("https://example.com/acme/hello")).toBeUndefined();
+    });
+});
+describe("assertValidName", () => {
+    it("accepts a lowercase, hyphen/dot-separated name", () => {
+        expect(() => assertValidName("hello-tool.kit")).not.toThrow();
+    });
+    it("rejects a double hyphen", () => {
+        expect(() => assertValidName("Bad--Name")).toThrow(/Invalid tool name/);
+    });
+    it("rejects a leading hyphen", () => {
+        expect(() => assertValidName("-abc")).toThrow(/Invalid tool name/);
+    });
+    it("rejects uppercase", () => {
+        expect(() => assertValidName("ABC")).toThrow(/Invalid tool name/);
+    });
+});

package/dist/identity/read.d.ts

@@ -0,0 +1,9 @@
+import type { Identity } from "../model.js";
+export interface IdentityFile {
+    identity: Identity;
+    extra: Record<string, unknown>;
+    /** Object → text serializer matching the source format, used when projecting back. */
+    format: "json" | "toml" | "yaml";
+}
+/** Read the identity file named by `tool.json.identity`. */
+export declare function readIdentityFile(path: string): IdentityFile;

package/dist/identity/read.js

@@ -0,0 +1,106 @@
+/**
+ * Identity readers. These are shallow structural reads that pull the eight identity
+ * fields out of a file the ecosystem defines and keep every other top-level key as an
+ * opaque bag, so a rewrite never deletes what toolfactory does not understand.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+import { assertValidName } from "./name.js";
+const IDENTITY_KEYS = [
+    "name",
+    "version",
+    "description",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+];
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asAuthor(value) {
+    if (typeof value === "string") {
+        const match = value.match(/^([^<(]+?)\s*(?:<([^>]+)>)?\s*(?:\(([^)]+)\))?\s*$/);
+        return match ? { name: match[1]?.trim(), email: match[2], url: match[3] } : { name: value };
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return {
+            name: asString(record.name),
+            email: asString(record.email),
+            url: asString(record.url),
+        };
+    }
+    return undefined;
+}
+function asRepository(value) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object")
+        return asString(value.url);
+    return undefined;
+}
+function split(record, keys) {
+    return Object.fromEntries(Object.entries(record).filter(([key]) => !keys.includes(key)));
+}
+function fromGeneric(record, nameKey = "name") {
+    const rawName = asString(record[nameKey]) ?? "";
+    const name = rawName.replace(/^@[^/]+\//, "");
+    assertValidName(name);
+    const identity = {
+        name,
+        version: asString(record.version),
+        description: asString(record.description),
+        author: asAuthor(record.author),
+        homepage: asString(record.homepage),
+        repository: asRepository(record.repository),
+        license: asString(record.license),
+        keywords: Array.isArray(record.keywords)
+            ? record.keywords.filter((k) => typeof k === "string")
+            : undefined,
+    };
+    const owned = [...IDENTITY_KEYS.filter((key) => key !== "name"), nameKey];
+    return { identity, extra: split(record, owned), format: "json" };
+}
+function fromPyproject(text) {
+    const document = parseToml(text);
+    const project = (document.project ?? {});
+    const urls = (project.urls ?? {});
+    const authors = Array.isArray(project.authors)
+        ? project.authors
+        : [];
+    const name = asString(project.name) ?? "";
+    assertValidName(name);
+    const license = project.license;
+    const identity = {
+        name,
+        version: asString(project.version),
+        description: asString(project.description),
+        author: authors[0] ? asAuthor(authors[0]) : undefined,
+        homepage: asString(urls.Homepage ?? urls.homepage),
+        repository: asString(urls.Repository ?? urls.repository ?? urls.Source),
+        license: typeof license === "string"
+            ? license
+            : asString(license?.text),
+        keywords: Array.isArray(project.keywords) ? project.keywords : undefined,
+    };
+    return { identity, extra: document, format: "toml" };
+}
+/** Read the identity file named by `tool.json.identity`. */
+export function readIdentityFile(path) {
+    const text = readFileSync(path, "utf8");
+    const file = basename(path);
+    if (file === "pyproject.toml")
+        return fromPyproject(text);
+    if (file === "plugin.yaml" || file === "plugin.yml") {
+        const document = (parseYaml(text) ?? {});
+        return { ...fromGeneric(document), format: "yaml" };
+    }
+    const document = JSON.parse(text);
+    if (file === "openclaw.plugin.json")
+        return fromGeneric(document, "id");
+    return fromGeneric(document);
+}

package/dist/identity/read.test.d.ts

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

package/dist/identity/read.test.js

@@ -0,0 +1,76 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readIdentityFile } from "./read.js";
+let dir;
+function file(name, content) {
+    const path = join(dir, name);
+    writeFileSync(path, content);
+    return path;
+}
+describe("readIdentityFile", () => {
+    afterEach(() => {
+        dir = "";
+    });
+    it("reads plugin.json, preserving unknown top-level keys as extra", () => {
+        dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+        const path = file("plugin.json", JSON.stringify({
+            name: "hello",
+            version: "0.1.0",
+            description: "Say hello.",
+            author: { name: "Ada", email: "ada@example.com" },
+            license: "MIT",
+            extensions: { toolfactory: {} },
+        }));
+        const result = readIdentityFile(path);
+        expect(result.format).toBe("json");
+        expect(result.identity).toMatchObject({
+            name: "hello",
+            version: "0.1.0",
+            description: "Say hello.",
+            author: { name: "Ada", email: "ada@example.com" },
+            license: "MIT",
+        });
+        expect(result.extra).toEqual({ extensions: { toolfactory: {} } });
+    });
+    it("reads package.json, stripping the npm scope off a scoped name", () => {
+        dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+        const path = file("package.json", JSON.stringify({ name: "@acme/hello", version: "0.2.0" }));
+        const result = readIdentityFile(path);
+        expect(result.identity.name).toBe("hello");
+        expect(result.identity.version).toBe("0.2.0");
+    });
+    it("reads pyproject.toml", () => {
+        dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+        const path = file("pyproject.toml", [
+            "[project]",
+            'name = "hello-py"',
+            'version = "0.3.0"',
+            'description = "Say hello."',
+            'authors = [{ name = "Ada", email = "ada@example.com" }]',
+            "",
+            "[project.urls]",
+            'Repository = "https://github.com/acme/hello-py"',
+            "",
+        ].join("\n"));
+        const result = readIdentityFile(path);
+        expect(result.format).toBe("toml");
+        expect(result.identity).toMatchObject({
+            name: "hello-py",
+            version: "0.3.0",
+            description: "Say hello.",
+            author: { name: "Ada", email: "ada@example.com" },
+            repository: "https://github.com/acme/hello-py",
+        });
+    });
+    it("reads openclaw.plugin.json off the `id` field", () => {
+        dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+        const path = file("openclaw.plugin.json", JSON.stringify({ id: "hello", version: "0.1.0", commands: ["run"] }));
+        const result = readIdentityFile(path);
+        expect(result.identity.name).toBe("hello");
+        expect(result.identity.version).toBe("0.1.0");
+        // Unknown keys other than the generic identity set round-trip as extra.
+        expect(result.extra).toEqual({ commands: ["run"] });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * as commands from "./commands.js";
+export * from "./model.js";
+export { loadProject, TOOLFACTORY_VERSION } from "./project/load.js";
+export { buildPlan } from "./project/plan.js";
+export { computeCoverage } from "./report/coverage.js";
+export { assertSurfaceRequirements, getSurface, registerSurface, selectedSurfaces, } from "./surfaces/registry.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * as commands from "./commands.js";
+export * from "./model.js";
+export { loadProject, TOOLFACTORY_VERSION } from "./project/load.js";
+export { buildPlan } from "./project/plan.js";
+export { computeCoverage } from "./report/coverage.js";
+export { assertSurfaceRequirements, getSurface, registerSurface, selectedSurfaces, } from "./surfaces/registry.js";

package/dist/introspect/index.d.ts

@@ -0,0 +1,15 @@
+import type { Project } from "../model.js";
+import { type Ops } from "../project/load.js";
+export declare function listTools(root: string, command: string, args: string[]): Promise<Ops>;
+export declare function serializeOps(ops: Ops): string;
+/** Spawn the kernel and compare its `tools/list` with the committed snapshot; writes nothing. */
+export declare function snapshot(project: Project): Promise<{
+    ops: Ops;
+    next: string;
+    changed: boolean;
+}>;
+export declare function introspect(project: Project): Promise<{
+    path: string;
+    changed: boolean;
+    ops: Ops;
+}>;

package/dist/introspect/index.js

@@ -0,0 +1,63 @@
+/**
+ * Operations come from the code: spawn the kernel MCP server, list its tools, and
+ * snapshot the result verbatim to ops.json so every generator runs offline.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { getBinding } from "../bindings/index.js";
+import { OPS_PATH, TOOLFACTORY_VERSION, toOperation } from "../project/load.js";
+export async function listTools(root, command, args) {
+    const transport = new StdioClientTransport({
+        command,
+        args,
+        cwd: root,
+        stderr: "pipe",
+        env: { ...process.env, TOOLFACTORY_INTROSPECT: "1" },
+    });
+    const stderr = [];
+    transport.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+    const client = new Client({ name: "toolfactory", version: TOOLFACTORY_VERSION });
+    try {
+        await client.connect(transport).catch((error) => {
+            const detail = stderr.join("").trim();
+            throw new Error(`Could not start the kernel MCP server (${[command, ...args].join(" ")}): ${error instanceof Error ? error.message : String(error)}${detail ? `\n${detail}` : ""}`);
+        });
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : undefined);
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor);
+        tools.sort((a, b) => a.name.localeCompare(b.name));
+        return { tools };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export function serializeOps(ops) {
+    return `${JSON.stringify(ops, null, 2)}\n`;
+}
+/** Spawn the kernel and compare its `tools/list` with the committed snapshot; writes nothing. */
+export async function snapshot(project) {
+    const kernel = project.tool.kernel ?? getBinding(project.tool.binding).kernelCommand(project);
+    const ops = await listTools(project.root, kernel.command, kernel.args);
+    for (const tool of ops.tools)
+        toOperation(tool); // rejects a capability outside the closed set
+    const next = serializeOps(ops);
+    const path = join(project.root, OPS_PATH);
+    const changed = !existsSync(path) || readFileSync(path, "utf8") !== next;
+    return { ops, next, changed };
+}
+export async function introspect(project) {
+    const { ops, next, changed } = await snapshot(project);
+    if (changed) {
+        const path = join(project.root, OPS_PATH);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, next);
+    }
+    return { path: OPS_PATH, changed, ops };
+}

package/dist/model.d.ts

@@ -0,0 +1,236 @@
+/**
+ * The shared plane. Every generator and command works only with these types.
+ *
+ * Identity is authored in one file the ecosystem already defines (plugin.json,
+ * package.json, pyproject.toml, or a host manifest). Operations come from the
+ * author's code, snapshotted from the kernel MCP server's `tools/list`. The
+ * rest is derived and written in-tree, tracked by a lock file.
+ */
+import { z } from "zod";
+export declare const CAPABILITIES: readonly ["net", "fs", "shell", "secret", "browser", "model", "user-input", "channel"];
+export type Capability = (typeof CAPABILITIES)[number];
+export declare const PORTABLE_CAPABILITIES: ReadonlySet<Capability>;
+export declare const SURFACE_IDS: 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"];
+export type SurfaceId = (typeof SURFACE_IDS)[number];
+export declare const BINDINGS: readonly ["typescript", "python"];
+export type Binding = (typeof BINDINGS)[number];
+/**
+ * What `init` selects when asked for nothing: the skills-first minimum that already serves every
+ * harness — a skill (installed anywhere by `npx skills add`), the Agent Plugins bundle, the
+ * kernel as an MCP server and a CLI, and the binding's package registry to distribute them. Every
+ * host-specific plugin is opt-in: add one only when that host needs what a skill and an MCP
+ * server cannot give it (a gateway tab, browser capability, a store listing).
+ */
+export declare function defaultSurfaces(binding: Binding): SurfaceId[];
+/** Package managers the generated workflows know how to drive; read from package.json `packageManager`. */
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+/** Agent Plugins 1.0.0 name rule; the canonical name N every projection derives from. */
+export declare const NAME_PATTERN: RegExp;
+/** `dev.toolfactory/tool.json` — the one file toolfactory owns. */
+export declare const ToolConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<1>;
+    identity: z.ZodString;
+    binding: z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        kernel: "kernel";
+        none: "none";
+    }>>;
+    surfaces: z.ZodArray<z.ZodEnum<{
+        skill: "skill";
+        "agent-plugins": "agent-plugins";
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+        mcp: "mcp";
+        "mcp-registry": "mcp-registry";
+        cli: "cli";
+        npm: "npm";
+        pypi: "pypi";
+        "openclaw-native": "openclaw-native";
+        "hermes-native": "hermes-native";
+        clawhub: "clawhub";
+        web: "web";
+        dsh: "dsh";
+        workflows: "workflows";
+        agents: "agents";
+        readme: "readme";
+        gemini: "gemini";
+        mcpb: "mcpb";
+        "browser-extension": "browser-extension";
+    }>>;
+    kernel: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    bundle: z.ZodDefault<z.ZodObject<{
+        runtime: z.ZodDefault<z.ZodEnum<{
+            package: "package";
+            bundled: "bundled";
+        }>>;
+    }, z.core.$strip>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    tests: z.ZodDefault<z.ZodObject<{
+        examples: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    npm: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    codex: z.ZodOptional<z.ZodObject<{
+        interface: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    browserExtension: z.ZodOptional<z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodString>;
+        authDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cookieExport: z.ZodOptional<z.ZodBoolean>;
+        geckoId: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        sidePanel: z.ZodOptional<z.ZodBoolean>;
+        safari: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    mcpb: z.ZodOptional<z.ZodObject<{
+        privacyPolicies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    hermes: z.ZodOptional<z.ZodObject<{
+        toolset: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    openclaw: z.ZodOptional<z.ZodObject<{
+        registers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            api: z.ZodString;
+            contract: z.ZodString;
+            ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        activation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        pluginApi: z.ZodOptional<z.ZodString>;
+        dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type ToolConfig = z.infer<typeof ToolConfigSchema>;
+/** An instruction-only plugin has author prose but no generated executable or MCP server. */
+export declare function isInstructionOnly(tool: ToolConfig): boolean;
+export interface Author {
+    name?: string;
+    email?: string;
+    url?: string;
+}
+/** Authored once, in the identity file; projected everywhere else. */
+export interface Identity {
+    name: string;
+    version?: string;
+    description?: string;
+    author?: Author;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+}
+/** One MCP tool definition as returned by `tools/list`, plus the requirements it declares. */
+export interface Operation {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    requires: Capability[];
+}
+export type VerdictKind = "native" | "bridged" | "degraded" | "excluded";
+export interface Verdict {
+    kind: VerdictKind;
+    /** Machine-readable reason, e.g. `excluded:mcp-no-host-capabilities`. Empty for `native`. */
+    reason?: string;
+}
+/** A whole generated file. */
+export interface FullFile {
+    kind: "file";
+    path: string;
+    content: string;
+    mode?: number;
+    /**
+     * A build output: generated and locked like any other file, but not expected to exist.
+     * `check` does not report it missing (it is gitignored and rebuilt), only stale when present.
+     */
+    output?: true;
+    /** `content` is a link target, not file bytes: the file is a symbolic link (`.agents/skills/<N>`). */
+    symlink?: true;
+}
+export interface Region {
+    begin: string;
+    end: string;
+    content: string;
+}
+/**
+ * A file the author owns, in which toolfactory maintains one or more delimited regions.
+ * `template` is written when the file does not exist and must contain every marker.
+ */
+export interface RegionFile {
+    kind: "region";
+    path: string;
+    regions: Region[];
+    template: string;
+}
+/**
+ * A structured file shared with the author (package.json, pyproject.toml): toolfactory
+ * owns exactly the keys in `patch` (deep-merged) and leaves every other key alone.
+ */
+export interface MergeFile {
+    kind: "merge";
+    path: string;
+    format: "json" | "toml";
+    patch: Record<string, unknown>;
+    /** Dotted paths inside `patch` whose object toolfactory owns whole: replaced, never merged. */
+    owned?: string[];
+}
+export type PlannedFile = FullFile | RegionFile | MergeFile;
+export interface Command {
+    /** Human label used in reports. */
+    label: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface Project {
+    root: string;
+    tool: ToolConfig;
+    identity: Identity;
+    /** Unknown top-level keys of the identity file, preserved on rewrite. */
+    identityExtra: Record<string, unknown>;
+    operations: Operation[];
+    toolfactoryVersion: string;
+    /** From the root package.json `packageManager` field; npm when absent. */
+    packageManager?: PackageManager;
+}
+export interface Surface {
+    id: SurfaceId;
+    /** Pure: no I/O. Everything this surface writes for the project. */
+    plan(project: Project): PlannedFile[];
+    /** Upstream validators to run for this surface (tier 1). */
+    validate?(project: Project): Command[];
+    /** Per-operation verdict on this surface. Default: portable ⇒ native, else excluded. */
+    verdict?(operation: Operation, project: Project): Verdict;
+    /**
+     * Surfaces this one reads the output of. A selection that omits one is refused by name at
+     * plan time instead of emitting an artifact that points at a file nobody writes.
+     */
+    requires?: SurfaceId[];
+}
+export declare function isPortable(operation: Operation): boolean;
+/**
+ * The other half of the sensitive-config law above: a sensitive key must not declare a default
+ * (it would be committed into every manifest), and **no operation may take one as an argument**.
+ *
+ * An operation's `inputSchema` is projected onto MCP `tools/call`, the CLI flags, the skill's
+ * operations block, the web form and every host manifest at once, so a property named like a
+ * secret is a paste-into-chat path on every surface simultaneously. A secret reaches the kernel
+ * through config — the environment a host injects from its own masked store — and never through
+ * an argument. Enforced wherever a project is loaded, so `introspect`, `build` and `check` all
+ * refuse it.
+ */
+export declare function assertNoSensitiveArgument(config: Record<string, unknown> | undefined, operations: readonly Operation[]): void;