toolfactory 0.1.1

package/dist/model.js

@@ -0,0 +1,214 @@
+/**
+ * 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 const CAPABILITIES = [
+    "net",
+    "fs",
+    "shell",
+    "secret",
+    "browser",
+    "model",
+    "user-input",
+    "channel",
+];
+export const PORTABLE_CAPABILITIES = new Set([
+    "net",
+    "fs",
+    "shell",
+    "secret",
+]);
+export const SURFACE_IDS = [
+    "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 const BINDINGS = ["typescript", "python"];
+/**
+ * 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 function defaultSurfaces(binding) {
+    return ["skill", "agent-plugins", "mcp", "cli", binding === "python" ? "pypi" : "npm"];
+}
+/** Package managers the generated workflows know how to drive; read from package.json `packageManager`. */
+export const PACKAGE_MANAGERS = ["npm", "pnpm"];
+/** Agent Plugins 1.0.0 name rule; the canonical name N every projection derives from. */
+export const NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+const jsonObject = z.record(z.string(), z.unknown());
+/** `dev.toolfactory/tool.json` — the one file toolfactory owns. */
+export const ToolConfigSchema = z
+    .object({
+    $schema: z.string().optional(),
+    schemaVersion: z.literal(1),
+    identity: z
+        .string()
+        .describe("Repo-relative path of the authored identity file (plugin.json, package.json, pyproject.toml, or a host manifest)."),
+    binding: z.enum(BINDINGS).describe("Language of the core logic and its kernel surfaces."),
+    runtime: z
+        .enum(["kernel", "none"])
+        .optional()
+        .describe("Whether this project has an executable kernel. `none` is for an instruction-only Codex skill/plugin and permits only the skill and codex surfaces."),
+    surfaces: z
+        .array(z.enum(SURFACE_IDS))
+        .min(1)
+        .describe("Selected surfaces. A file exists iff a selected surface owns it."),
+    kernel: z
+        .object({
+        command: z.string(),
+        args: z.array(z.string()).default([]),
+    })
+        .optional()
+        .describe("How to spawn the kernel MCP server for introspection; defaults from the binding."),
+    bundle: z
+        .object({ runtime: z.enum(["package", "bundled"]).default("package") })
+        .default({ runtime: "package" })
+        .describe("How mcp.json reaches the kernel: a published package (npx/uvx) or a committed single-file build."),
+    config: jsonObject
+        .optional()
+        .refine((schema) => Object.values((schema?.properties ?? {})).every((property) => !property["x-toolfactory"]?.sensitive ||
+        property.default === undefined), "A sensitive config property must not declare a default: it would be committed into every manifest.")
+        .describe("JSON Schema 2020-12 object for the tool's configuration; mark secrets with x-toolfactory.sensitive."),
+    tests: z
+        .object({ examples: z.record(z.string(), jsonObject).default({}) })
+        .default({ examples: {} })
+        .describe("Example arguments per operation, used by the generated surface-smoke tests."),
+    npm: z.object({ scope: z.string().optional() }).optional(),
+    codex: z.object({ interface: jsonObject.optional() }).optional(),
+    browserExtension: z
+        .object({
+        endpoint: z
+            .string()
+            .optional()
+            .describe("The kernel's mcp --http URL the extension pairs with; defaults to the kernel's own default port."),
+        authDomains: z
+            .array(z.string())
+            .optional()
+            .describe("Match patterns the extension may act in with the user's own session (host_permissions)."),
+        cookieExport: z
+            .boolean()
+            .optional()
+            .describe("Opt in to exporting the session cookies of authDomains to the kernel (needs the cookies permission; Chromium and Firefox only)."),
+        geckoId: z
+            .string()
+            .optional()
+            .describe("Firefox add-on id; defaults to <name>@<github owner>.github.io."),
+        icon: z
+            .string()
+            .optional()
+            .describe("Repo-relative source PNG or SVG the icon set is resized from; the placeholder set otherwise."),
+        sidePanel: z
+            .boolean()
+            .optional()
+            .describe("Also register a Chromium side panel (Chromium only)."),
+        safari: z
+            .boolean()
+            .optional()
+            .describe("Add the macOS Safari packaging leg to the release workflow."),
+    })
+        .optional(),
+    mcpb: z
+        .object({ privacyPolicies: z.array(z.string()).optional() })
+        .optional()
+        .describe("Privacy-policy URLs of the services this tool talks to; Anthropic's Connectors Directory submission requires them in the MCPB manifest."),
+    hermes: z.object({ toolset: z.string().optional() }).optional(),
+    openclaw: z
+        .object({
+        registers: z
+            .array(z.object({
+            api: z
+                .string()
+                .describe("OpenClawPluginApi method, e.g. registerRealtimeVoiceProvider"),
+            contract: z
+                .string()
+                .describe("openclaw.plugin.json contracts key, e.g. realtimeVoiceProviders"),
+            ids: z.array(z.string()).default([]).describe("Ids registered under that contract"),
+        }))
+            .optional()
+            .describe("Host registrations the plugin makes beyond tools; one declaration drives the manifest contracts, the plugin inspector's expectations and the generated test."),
+        activation: jsonObject
+            .optional()
+            .describe("openclaw.plugin.json activation; default onStartup."),
+        pluginApi: z
+            .string()
+            .optional()
+            .describe("Plugin API range for compat.pluginApi and the openclaw peer dependency."),
+        dependencies: z.record(z.string(), z.string()).optional(),
+        peerDependencies: z.record(z.string(), z.string()).optional(),
+        devDependencies: z.record(z.string(), z.string()).optional(),
+    })
+        .optional(),
+})
+    .superRefine((tool, context) => {
+    if (tool.runtime !== "none")
+        return;
+    const unsupported = tool.surfaces.filter((surface) => surface !== "skill" && surface !== "codex");
+    if (unsupported.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["surfaces"],
+            message: `runtime "none" supports only skill and codex surfaces; unsupported: ${unsupported.join(", ")}.`,
+        });
+    }
+})
+    .strict();
+/** An instruction-only plugin has author prose but no generated executable or MCP server. */
+export function isInstructionOnly(tool) {
+    return tool.runtime === "none";
+}
+export function isPortable(operation) {
+    return operation.requires.every((capability) => PORTABLE_CAPABILITIES.has(capability));
+}
+/**
+ * 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 function assertNoSensitiveArgument(config, operations) {
+    const properties = (config?.properties ?? {});
+    const sensitive = new Set(Object.entries(properties)
+        .filter(([, property]) => property["x-toolfactory"]?.sensitive)
+        .map(([key]) => key));
+    if (!sensitive.size)
+        return;
+    for (const operation of operations) {
+        const inputs = (operation.inputSchema.properties ?? {});
+        for (const name of Object.keys(inputs)) {
+            if (!sensitive.has(name))
+                continue;
+            throw new Error(`Operation "${operation.name}" declares an input named "${name}", which is a sensitive config key: a secret reaches the kernel through config (the environment the host injects), never through an argument every surface would prompt for. Read it from config in the handler and drop the property.`);
+        }
+    }
+}

package/dist/ops.d.ts

@@ -0,0 +1,255 @@
+/**
+ * toolfactory's own operations. toolfactory is a tool built with toolfactory: this file is
+ * the author-owned operation module, and `src/toolfactory/{cli,mcp}.ts` are generated from
+ * it by `toolfactory build`, exactly as for any other tool.
+ */
+import { z } from "zod";
+export declare const operations: (import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    name: z.ZodString;
+    binding: z.ZodEnum<{
+        typescript: "typescript";
+        python: "python";
+    }>;
+    runtime: z.ZodOptional<z.ZodEnum<{
+        kernel: "kernel";
+        none: "none";
+    }>>;
+    surfaces: z.ZodOptional<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";
+    }>>>;
+    description: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    git: z.ZodDefault<z.ZodBoolean>;
+    setup: z.ZodDefault<z.ZodBoolean>;
+    repo: z.ZodOptional<z.ZodString>;
+    public: z.ZodDefault<z.ZodBoolean>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    reviewers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    written: z.ZodArray<z.ZodString>;
+    agentConfig: z.ZodObject<{
+        setup: z.ZodBoolean;
+        harnesses: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    repository: z.ZodOptional<z.ZodObject<{
+        repository: z.ZodString;
+        visibility: z.ZodString;
+        topics: z.ZodArray<z.ZodString>;
+        secrets: z.ZodArray<z.ZodString>;
+        commands: z.ZodArray<z.ZodString>;
+        dryRun: z.ZodBoolean;
+    }, z.core.$strip>>;
+    nextSteps: z.ZodArray<z.ZodString>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    changed: z.ZodBoolean;
+    operations: z.ZodNumber;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    written: z.ZodArray<z.ZodString>;
+    deleted: z.ZodArray<z.ZodString>;
+    unchanged: z.ZodArray<z.ZodString>;
+    manual: z.ZodArray<z.ZodString>;
+    stripped: z.ZodArray<z.ZodString>;
+    nudge: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    surface: z.ZodOptional<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";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    outcomes: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        command: z.ZodString;
+        ok: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    surfaces: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodObject<{
+        operation: z.ZodString;
+        verdicts: z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    adopted: z.ZodString;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    regenerated: z.ZodString;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    surface: 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";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    adopted: z.ZodArray<z.ZodString>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    reviewers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    repository: z.ZodString;
+    environment: z.ZodString;
+    reviewers: z.ZodArray<z.ZodString>;
+    secrets: z.ZodArray<z.ZodString>;
+    missing: z.ZodArray<z.ZodString>;
+    commands: z.ZodArray<z.ZodString>;
+    manual: z.ZodArray<z.ZodString>;
+    dryRun: z.ZodBoolean;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    action: z.ZodDefault<z.ZodEnum<{
+        check: "check";
+        status: "status";
+    }>>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    secrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            config: "config";
+            release: "release";
+        }>;
+        required: z.ZodBoolean;
+        needs: z.ZodArray<z.ZodString>;
+        local: z.ZodBoolean;
+        github: z.ZodOptional<z.ZodBoolean>;
+        url: z.ZodOptional<z.ZodString>;
+        howTo: z.ZodArray<z.ZodString>;
+        check: z.ZodOptional<z.ZodObject<{
+            ok: z.ZodBoolean;
+            command: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    manual: z.ZodArray<z.ZodString>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+    ref: z.ZodDefault<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    hard: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    dropped: 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";
+    }>>;
+    steps: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        run: z.ZodString;
+    }, z.core.$strip>>;
+    ran: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ok: z.ZodBoolean;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    root: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ok: z.ZodBoolean;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    toolfactory: z.ZodString;
+    node: z.ZodString;
+    tools: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>>)[];