toolfactory 0.1.1

package/dist/surfaces/workflows.test.d.ts

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

package/dist/surfaces/workflows.test.js

@@ -0,0 +1,563 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parse as yamlParse } from "yaml";
+import { bootstrapRepo } from "../hosts/github.js";
+import { gateSteps, packageSteps, registries } from "../project/gate.js";
+import { sourcesZipName, zipName } from "./browser-extension.js";
+import { surface } from "./workflows.js";
+const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
+const shoot = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+function project(surfaces, overrides = {}) {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "package.json",
+            binding: "typescript",
+            surfaces,
+            bundle: { runtime: "package" },
+            tests: { examples: {} },
+            config: {
+                properties: {
+                    api_key: {
+                        type: "string",
+                        description: "Provider API key",
+                        "x-toolfactory": { sensitive: true, tier: 4, url: "https://example.com/keys" },
+                    },
+                    region: { type: "string", description: "Deployment region" },
+                },
+                required: ["api_key"],
+            },
+        },
+        identity: { name: "hello", version: "0.1.0", description: "Say hello" },
+        identityExtra: {},
+        operations: [echo],
+        toolfactoryVersion: "0.1.0",
+        ...overrides,
+    };
+}
+function emitted(target) {
+    return Object.fromEntries(surface
+        .plan(target)
+        .map((file) => [
+        file.path,
+        file.kind === "file"
+            ? file.content
+            : file.kind === "merge"
+                ? JSON.stringify(file.patch)
+                : "",
+    ]));
+}
+/** Every generated file is a parseable document in its format — the one invariant that must never break. */
+function expectAllYamlAndJsonParse(files) {
+    for (const [path, content] of Object.entries(files)) {
+        if (path.endsWith(".yml") || path.endsWith(".yaml")) {
+            expect(() => yamlParse(content), path).not.toThrow();
+        }
+        else if (path.endsWith(".json")) {
+            expect(() => JSON.parse(content), path).not.toThrow();
+        }
+    }
+}
+describe("workflows", () => {
+    it("sets up Node without a package-manager cache for an instruction-only plugin", () => {
+        const target = project(["skill", "codex"]);
+        target.tool.runtime = "none";
+        const ci = yamlParse(emitted(target)[".github/workflows/ci.yml"] ?? "");
+        const setupNode = ci.jobs.test.steps.find((step) => step.uses === "actions/setup-node@v7");
+        expect(setupNode?.with).toEqual({ "node-version": "${{ matrix.node-version }}" });
+        expect(ci.jobs.test.steps.some((step) => step.uses === "pnpm/action-setup@v4")).toBe(false);
+    });
+    it("always emits ci.yml, release.yml, .env.example and renovate.json, never compose without a trigger", () => {
+        const files = emitted(project(["cli", "mcp"]));
+        expect(Object.keys(files).sort()).toEqual([
+            ".env.example",
+            ".github/workflows/ci.yml",
+            ".github/workflows/release.yml",
+            "renovate.json",
+        ]);
+        // No registry surface: the tag still gets its gate, its assets and its Release, no legs.
+        const bare = yamlParse(files[".github/workflows/release.yml"]);
+        expect(Object.keys(bare.jobs)).toEqual(["gate", "package", "release"]);
+        expect(bare.jobs.gate.outputs).toEqual({ sha: "${{ steps.tag.outputs.sha }}" });
+        expectAllYamlAndJsonParse(files);
+        const ci = yamlParse(files[".github/workflows/ci.yml"]);
+        expect(ci.jobs.test.strategy.matrix["node-version"]).toEqual(["22", "24"]);
+        // No skill/claude/openclaw-native selected: no extra validator installs, no matrix guard.
+        const steps = ci.jobs.test.steps;
+        expect(steps.some((s) => s.run?.includes("agentskills"))).toBe(false);
+        expect(steps.filter((s) => s.uses).map((s) => s.uses)).toEqual(["actions/checkout@v7", "actions/setup-node@v7"]);
+        expect(steps.some((s) => s.run?.includes("claude-code"))).toBe(false);
+        expect(steps.find((s) => s.run === "npx toolfactory validate")?.if).toBeUndefined();
+        const renovate = JSON.parse(files["renovate.json"]);
+        expect(renovate.extends).toEqual(["config:recommended", "group:all"]);
+        expect(renovate.minimumReleaseAge).toBe("7 days");
+        // The generated workflows are SHA-locked projections: a Renovate PR editing one would make
+        // `toolfactory check` fail and the next `toolfactory build` revert it.
+        expect(renovate.ignorePaths).toContain(".github/workflows/**");
+    });
+    it("ci.yml installs each selected surface's validator and guards the openclaw leg on the matrix", () => {
+        const files = emitted(project(["skill", "claude", "openclaw-native", "mcp"]));
+        const ci = yamlParse(files[".github/workflows/ci.yml"]);
+        const steps = ci.jobs.test.steps;
+        expect(steps.some((s) => s.uses === "astral-sh/setup-uv@v6")).toBe(true);
+        expect(steps.some((s) => s.run?.includes("npm i -g @anthropic-ai/claude-code"))).toBe(true);
+        // openclaw-native needs Node >=24; skip that one step on the 22 leg rather than fail it.
+        expect(steps.find((s) => s.run === "npx toolfactory validate")?.if).toBe("matrix.node-version == '24'");
+    });
+    it("python binding uses a single uv + Python 3.12 toolchain, no node matrix", () => {
+        const python = project(["cli", "mcp"], {
+            tool: { ...project(["cli"]).tool, binding: "python" },
+        });
+        const ci = yamlParse(emitted(python)[".github/workflows/ci.yml"]);
+        expect(ci.jobs.test.strategy).toBeUndefined();
+        const steps = ci.jobs.test.steps;
+        expect(steps.find((s) => s.uses === "astral-sh/setup-uv@v6")?.with).toEqual({
+            "python-version": "3.12",
+        });
+        expect(steps.some((s) => s.run === "uv run --with pytest pytest -q")).toBe(true);
+    });
+    it("release.yml runs the legs in the forced order npm -> oci -> mcp-registry -> clawhub, each gated on what the gate decided", () => {
+        const files = emitted(project(["npm", "mcp-registry", "clawhub", "openclaw-native", "skill", "claude", "web", "mcp"], {
+            identity: {
+                name: "hello",
+                version: "0.1.0",
+                repository: "https://github.com/acme/hello.git",
+            },
+        }));
+        expectAllYamlAndJsonParse(files);
+        const release = yamlParse(files[".github/workflows/release.yml"]);
+        expect(release.on.push).toEqual({ tags: ["v*"] });
+        // The re-run after adding a secret: a fresh run reads current secrets, `gh run rerun` does not.
+        expect(release.on.workflow_dispatch.inputs.tag).toMatchObject({
+            required: true,
+            type: "string",
+        });
+        // Presence is decided once, in the gate, and every leg obeys it at job level.
+        expect(Object.keys(release.jobs.gate.outputs)).toEqual([
+            "sha",
+            "npm",
+            "oci",
+            "mcp_registry",
+            "clawhub_package",
+            "clawhub_skill",
+            "pages",
+        ]);
+        expect(release.jobs["publish-npm"].if).toBe("needs.gate.outputs.npm == 'true'");
+        expect(release.jobs["publish-mcp-registry"].if).toBe("needs.gate.outputs.mcp_registry == 'true'");
+        expect(release.jobs["publish-clawhub"].if).toBe("${{ !cancelled() && needs.package.result == 'success' && !contains(needs.*.result, 'failure') && needs.gate.outputs.clawhub_package == 'true' }}");
+        expect(release.jobs["pages-build"].if).toBe("needs.gate.outputs.pages == 'true'");
+        const presence = release.jobs.gate.steps.find((s) => s.id === "presence");
+        expect(presence?.env?.NPM_TOKEN).toBe("${{ secrets.NPM_TOKEN }}");
+        expect(presence?.env?.NPM_TRUSTED_PUBLISHER).toBe("${{ vars.NPM_TRUSTED_PUBLISHER }}");
+        expect(presence?.run).toContain('echo "npm=$npm" >> "$GITHUB_OUTPUT"');
+        expect(presence?.run).toContain('[ "$npm" = true ] && [ "$oci" = true ]');
+        // Skipped legs never skip the Release; failed ones do. It retracts dropped registries first.
+        expect(release.jobs.release.if).toBe("${{ !cancelled() && needs.package.result == 'success' && !contains(needs.*.result, 'failure') }}");
+        expect(release.jobs.release.needs).toContain("gate");
+        expect(release.jobs.release.env).not.toHaveProperty("NPM_TOKEN");
+        const releaseSteps = release.jobs.release.steps;
+        expect(releaseSteps[0].with).toEqual({
+            ref: "${{ needs.gate.outputs.sha }}",
+            "fetch-depth": 0,
+        });
+        expect(releaseSteps.some((s) => s.run === "npx toolfactory unpublish")).toBe(true);
+        expect(releaseSteps.at(-1)?.with).toMatchObject({
+            tag_name: "${{ inputs.tag || github.ref_name }}",
+            target_commitish: "${{ needs.gate.outputs.sha }}",
+        });
+        // Cutting a tag from the Actions UI: gate resolves the commit, the Release creates the tag.
+        const gateSteps_ = release.jobs.gate.steps;
+        expect(gateSteps_[0].with).toEqual({ "fetch-depth": 0 });
+        expect(gateSteps_.find((s) => s.id === "tag")?.run).toContain('git rev-parse -q --verify "refs/tags/$RELEASE_TAG^{commit}"');
+        expect(Object.keys(release.jobs)).toEqual([
+            "gate",
+            "package",
+            "publish-npm",
+            "publish-oci",
+            "publish-mcp-registry",
+            "publish-clawhub",
+            "publish-clawhub-skill",
+            "release",
+            "pages-build",
+            "pages-deploy",
+        ]);
+        expect(release.jobs["publish-npm"].needs).toEqual(["gate", "package"]);
+        expect(release.jobs["publish-npm"].steps).toContainEqual({
+            uses: "actions/download-artifact@v8",
+            with: { name: "release-assets", path: "release-assets" },
+        });
+        expect(release.jobs["publish-npm"].env).not.toHaveProperty("NPM_TOKEN");
+        for (const step of release.jobs["publish-npm"].steps) {
+            if (step.name === "npm publish") {
+                expect(step.env.NPM_TOKEN).toBe("${{ vars.NPM_TRUSTED_PUBLISHER != 'true' && secrets.NPM_TOKEN || '' }}");
+            }
+            else {
+                expect(step.env ?? {}).not.toHaveProperty("NPM_TOKEN");
+            }
+        }
+        expect(release.jobs["publish-oci"].needs).toBe("gate");
+        expect(release.jobs["publish-mcp-registry"].needs).toEqual([
+            "gate",
+            "publish-npm",
+            "publish-oci",
+        ]);
+        // The ClawHub leg publishes the tarball `package` built, not the repository subdirectory:
+        // the reusable workflow has no build step of its own.
+        expect(release.jobs["publish-clawhub"].needs).toEqual([
+            "gate",
+            "package",
+            "publish-npm",
+            "publish-oci",
+            "publish-mcp-registry",
+        ]);
+        expect(release.jobs["publish-clawhub"].with).toMatchObject({
+            package_artifact_name: "release-assets",
+            package_artifact_path: "openclaw-plugin-hello-0.1.0.tgz",
+        });
+        expect(release.jobs["publish-clawhub"].secrets.clawhub_token).toContain("CLAWHUB_TOKEN");
+        // ClawHub's skill catalog is a separate track: it needs only `gate` (no built tarball), and
+        // reuses ClawHub's own skill-publish.yml, which derives slug/version from SKILL.md itself.
+        expect(release.jobs["publish-clawhub-skill"]).toMatchObject({
+            needs: "gate",
+            uses: "openclaw/clawhub/.github/workflows/skill-publish.yml@main",
+            with: { skill_path: "skills/hello", dry_run: false },
+        });
+        expect(release.jobs["publish-clawhub-skill"].secrets.clawhub_token).toContain("CLAWHUB_TOKEN");
+        expect(release.jobs.release.needs.at(-1)).toBe("publish-clawhub-skill");
+        // Every job that runs steps declares its own permissions; the workflow-call leg inherits the
+        // file's `contents: read`.
+        const withoutPermissions = Object.entries(release.jobs)
+            .filter(([, job]) => job.permissions === undefined)
+            .map(([name]) => name);
+        expect(withoutPermissions).toEqual(["publish-clawhub", "publish-clawhub-skill"]);
+        expect(release.permissions).toEqual({ contents: "read" });
+        expect(release.jobs["publish-oci"].permissions).toEqual({
+            contents: "read",
+            packages: "write",
+            attestations: "write",
+            "id-token": "write",
+        });
+        expect(release.jobs.release.permissions).toEqual({
+            contents: "write",
+            packages: "write",
+            pages: "write",
+            "id-token": "write",
+        });
+        expect(release.jobs["pages-deploy"].permissions).toEqual({
+            pages: "write",
+            "id-token": "write",
+        });
+        // The gate asserts the tag against the identity file's version and never writes it (§2.2).
+        const gateRuns = release.jobs.gate.steps
+            .map((s) => s.run)
+            .filter(Boolean);
+        // After the commit is resolved (a dispatched tag may not exist yet), before anything else.
+        expect(gateRuns[1]).toBe('test "v$(node -p "require(\'./package.json\').version")" = "$RELEASE_TAG"');
+        // The gate is the same check sequence as ci.yml: build precedes `toolfactory validate`,
+        // which runs every selected surface's own validator (no transcribed commands to drift).
+        expect(gateRuns.indexOf("npm run --if-present build")).toBeLessThan(gateRuns.indexOf("npx toolfactory validate"));
+        expect(gateRuns.some((r) => r?.includes("openclaw plugins build"))).toBe(false);
+        // npm generates provenance itself under trusted publishing; --provenance is redundant. A
+        // configured publisher selects OIDC; otherwise the stored token is a fallback. A re-dispatch
+        // after adding either credential must not attempt to republish an immutable version.
+        expect(release.jobs["publish-npm"].steps.some((s) => s.run?.includes("npm view hello@0.1.0 version") &&
+            s.run?.includes('elif [ "$NPM_TRUSTED_PUBLISHER" = true ]; then npm publish release-assets/hello-0.1.0.tgz --access public') &&
+            s.run?.includes('NODE_AUTH_TOKEN="$NPM_TOKEN" npm publish release-assets/hello-0.1.0.tgz --access public'))).toBe(true);
+        // The oci leg pushes the very image server.json's oci entry names.
+        const meta = release.jobs["publish-oci"].steps.find((s) => s.id === "meta");
+        expect(meta?.with?.images).toBe("ghcr.io/acme/hello");
+        expect(meta?.with?.labels).toBe("io.modelcontextprotocol.server.name=io.github.acme/hello");
+        expect(files[".github/workflows/release.yml"]).toContain("git is the ledger");
+        expect(files[".github/workflows/release.yml"]).toContain("CLAWHUB_TOKEN");
+    });
+    it("clawhub without openclaw-native publishes nothing (there is no host package to publish)", () => {
+        const release = emitted(project(["clawhub", "npm"]))[".github/workflows/release.yml"];
+        expect(yamlParse(release).jobs["publish-clawhub"]).toBeUndefined();
+    });
+    it("clawhub + skill without openclaw-native still publishes the skill catalog leg", () => {
+        const release = yamlParse(emitted(project(["clawhub", "skill"]))[".github/workflows/release.yml"]);
+        expect(release.jobs["publish-clawhub"]).toBeUndefined();
+        expect(release.jobs["publish-clawhub-skill"].needs).toBe("gate");
+    });
+    it("compose.toolfactory.yaml appears only for a host-native surface and picks the browser image variant", () => {
+        expect(emitted(project(["cli"]))["compose.toolfactory.yaml"]).toBeUndefined();
+        const withBrowser = project(["openclaw-native"], { operations: [echo, shoot] });
+        const compose = yamlParse(emitted(withBrowser)["compose.toolfactory.yaml"]);
+        expect(compose.services.openclaw.image).toBe("ghcr.io/openclaw/openclaw:latest-browser");
+        // `--link` (a copy trips the install-time symlink scan) and a non-interactive accept.
+        expect(compose.services.openclaw.command[2]).toContain("openclaw plugins install --link /work/hosts/openclaw --force --accept-capabilities");
+        expect(compose.services.openclaw.env_file).toEqual([".env"]);
+        expect(compose.services.hermes).toBeUndefined();
+        expect(compose.volumes.PLUGIN_DATA).toEqual({});
+        const noBrowser = project(["hermes-native"]);
+        const composeHermes = yamlParse(emitted(noBrowser)["compose.toolfactory.yaml"]);
+        expect(composeHermes.services.hermes.command[2]).toContain("hermes plugins doctor /work/hosts/hermes/hello_hermes --ci");
+        expect(composeHermes.services.openclaw).toBeUndefined();
+    });
+    it("adds the T4 live job, and workflow_dispatch, iff a config key is required and sensitive", () => {
+        const ci = yamlParse(emitted(project(["cli"]))[".github/workflows/ci.yml"]);
+        expect(ci.on.workflow_dispatch).toEqual({});
+        const live = ci.jobs.live;
+        expect(live.needs).toBe("test");
+        expect(live.environment).toBe("live-tests");
+        // A fork's pull request must never see the live-tests secrets.
+        expect(live.if).toBe("github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository");
+        // Every sensitive key, not only the required ones: an optional credential is still a secret.
+        expect(live.env).toEqual({ API_KEY: "${{ secrets.API_KEY }}" });
+        expect(live.steps.at(-1)?.run).toBe("npm run --if-present test:live");
+        const python = project(["cli"], { tool: { ...project(["cli"]).tool, binding: "python" } });
+        expect(yamlParse(emitted(python)[".github/workflows/ci.yml"]).jobs.live.steps.at(-1)?.run).toBe("uv run --with pytest pytest -q tests/test_live.py");
+        // api_key optional: nothing gates a live run, so no live job and no workflow_dispatch.
+        const noCredential = project(["cli"]);
+        noCredential.tool.config = { ...noCredential.tool.config, required: [] };
+        const plain = yamlParse(emitted(noCredential)[".github/workflows/ci.yml"]);
+        expect(plain.jobs.live).toBeUndefined();
+        expect(plain.on.workflow_dispatch).toBeUndefined();
+    });
+    it(".env.example lists every config key uppercased, secrets and required marked", () => {
+        const env = emitted(project(["cli"]))[".env.example"];
+        expect(env).toContain("API_KEY=");
+        expect(env).toContain("(required, secret) — get one: https://example.com/keys");
+        expect(env).toContain("REGION=");
+        expect(env).toContain("(optional)");
+    });
+});
+/** Real invocation: an offline GitHub Actions linter, when one happens to be on PATH. */
+describe("npm release authentication", () => {
+    it("executes token, OIDC, disabled, and already-published branches without registry writes", () => {
+        const target = project(["npm"]);
+        const release = yamlParse(emitted(target)[".github/workflows/release.yml"]);
+        const publish = release.jobs["publish-npm"].steps.find((step) => step.name === "npm publish")?.run;
+        const gate = registries(target).find((registry) => registry.id === "npm")?.gate;
+        expect(publish).toBeDefined();
+        expect(gate).toBeDefined();
+        for (const scenario of [
+            { trust: "", token: "", exists: false, enabled: false, output: "" },
+            { trust: "false", token: "", exists: false, enabled: false, output: "" },
+            {
+                trust: "false",
+                token: "test-token",
+                exists: false,
+                enabled: true,
+                output: "publish:test-token",
+            },
+            { trust: "true", token: "test-token", exists: false, enabled: true, output: "publish:oidc" },
+            { trust: "true", token: "", exists: true, enabled: true, output: "already published" },
+        ]) {
+            const env = {
+                ...process.env,
+                NPM_TRUSTED_PUBLISHER: scenario.trust,
+                NPM_TOKEN: scenario.token,
+                NODE_AUTH_TOKEN: "",
+            };
+            const gated = spawnSync("bash", ["-c", gate], { env });
+            expect(gated.status === 0).toBe(scenario.enabled);
+            if (!scenario.enabled)
+                continue;
+            // Stub the upstream CLI at the shell boundary; never contact or write to npm.
+            const stub = `npm() { if [ "$1" = view ]; then return ${scenario.exists ? 0 : 1}; fi; printf 'publish:%s\\n' "\${NODE_AUTH_TOKEN:-oidc}"; };`;
+            const output = execFileSync("bash", ["-c", `${stub}\n${publish}`], {
+                env,
+                encoding: "utf8",
+            });
+            expect(output).toContain(scenario.output);
+            if (scenario.exists)
+                expect(output).not.toContain("publish:");
+        }
+    });
+});
+function actionlintAvailable() {
+    try {
+        execFileSync("actionlint", ["-version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+describe.skipIf(!actionlintAvailable())("actionlint", () => {
+    it("accepts the generated ci.yml and release.yml", () => {
+        const dir = mkdtempSync(join(tmpdir(), "tf-workflows-"));
+        const files = emitted(project([
+            "npm",
+            "mcp-registry",
+            "clawhub",
+            "openclaw-native",
+            "hermes-native",
+            "skill",
+            "claude",
+            "web",
+            "mcp",
+        ], {
+            identity: {
+                name: "hello",
+                version: "0.1.0",
+                repository: "https://github.com/acme/hello.git",
+            },
+        }));
+        const workflowPaths = [];
+        for (const [path, content] of Object.entries(files)) {
+            if (!path.startsWith(".github/workflows/"))
+                continue;
+            mkdirSync(dirname(join(dir, path)), { recursive: true });
+            writeFileSync(join(dir, path), content);
+            workflowPaths.push(path);
+        }
+        // actionlint otherwise walks up looking for a git repo to find `.github/workflows`;
+        // point it straight at the files instead.
+        execFileSync("actionlint", workflowPaths, { cwd: dir });
+    });
+});
+/**
+ * `bootstrap-repo`: the one-time I/O the live job depends on. It shells to the official `gh`
+ * CLI, so the unit under test is the invocation list — which `--dry-run` returns without
+ * touching the network — and the fact that no secret value appears in it.
+ */
+describe("bootstrap-repo", () => {
+    it("prepares the live-tests environment through gh, with values only ever on stdin", () => {
+        const target = project(["cli"], {
+            root: "/repo",
+            identity: { name: "hello", repository: "https://github.com/acme/hello.git" },
+        });
+        const result = bootstrapRepo(target, { reviewers: ["ada"], dryRun: true });
+        expect(result.repository).toBe("acme/hello");
+        expect(result.secrets).toEqual(["API_KEY"]);
+        expect(result.commands).toEqual([
+            "gh api users/ada --jq .id",
+            'gh api --method PUT repos/acme/hello/environments/live-tests --input - <<< \'{"reviewers":[{"type":"User","id":"<id of ada>"}]}\'',
+            "gh secret set API_KEY --env live-tests --repo acme/hello  # value from /repo/.env, on stdin",
+        ]);
+        const anonymous = project(["cli"], { identity: { name: "hello" } });
+        expect(() => bootstrapRepo(anonymous, { dryRun: true })).toThrow(/GitHub repository URL/);
+        // No live credential is not "nothing to do": the release tokens still land, at repository scope.
+        const noCredential = project(["cli"], { identity: target.identity });
+        noCredential.tool.config = { ...noCredential.tool.config, required: [] };
+        const release = bootstrapRepo(noCredential, {
+            dryRun: true,
+            releaseSecrets: ["NPM_TOKEN"],
+            manual: ["npm: generic instructions replaced by the bootstrap outcome"],
+        });
+        expect(release.secrets).toEqual(["NPM_TOKEN"]);
+        expect(release.commands).toContain("gh secret set NPM_TOKEN --repo acme/hello  # value from /repo/.env, on stdin");
+        expect(release.manual.join(" ")).toContain("granular access tokens with bypass 2FA are unsupported");
+        expect(release.manual.join(" ")).toContain("NPM_TRUSTED_PUBLISHER");
+        expect(release.manual.filter((step) => step.startsWith("npm:"))).toHaveLength(1);
+    });
+});
+/**
+ * The gate is a command and the workflows are its projection: one list, two renderings. The
+ * local runner skips the runner-only provisioning, so what it skips and what it keeps is pinned.
+ */
+describe("gate", () => {
+    it("lists the same steps CI runs, marking the runner-only ones", () => {
+        const target = project(["npm", "claude", "openclaw-native", "mcp"]);
+        const steps = gateSteps(target);
+        expect(steps.map((step) => step.name)).toEqual([
+            "install",
+            "build",
+            "toolfactory check",
+            "toolfactory build (output files)",
+            "Install Claude Code CLI",
+            "toolfactory validate",
+            "author checks",
+            "author tests",
+            "openclaw end-to-end (scripted model, no LLM key)",
+        ]);
+        // `npm ci` and a global CLI install are the runner's job, not a checkout's: `toolfactory gate`
+        // skips every `when: "ci"` step and runs the rest here, in order.
+        expect(steps.filter((step) => step.when === "ci").map((step) => step.name)).toEqual([
+            "install",
+            "Install Claude Code CLI",
+        ]);
+        expect(steps.filter((step) => step.when === "node24").map((step) => step.name)).toEqual([
+            "toolfactory validate",
+            "openclaw end-to-end (scripted model, no LLM key)",
+        ]);
+    });
+    it("packages one asset per selected distribution surface into dist/release", () => {
+        const target = project([
+            "npm",
+            "pypi",
+            "openclaw-native",
+            "skill",
+            "claude",
+            "web",
+            "browser-extension",
+            "mcp",
+        ]);
+        const runs = packageSteps(target).map((step) => step.run);
+        expect(runs).toContain("npm pack --pack-destination dist/release");
+        expect(runs).toContain("uv build --out-dir dist/release");
+        expect(runs.some((run) => run.includes("npm pack ./hosts/openclaw"))).toBe(true);
+        expect(runs).toContain('set -- skills .claude-plugin; for path in LICENSE LICENSE.md LICENSE.txt NOTICE NOTICE.md NOTICE.txt; do if [ -f "$path" ]; then set -- "$@" "$path"; fi; done; zip -qr dist/release/hello-plugin.zip "$@"');
+        const webBuild = runs.findIndex((run) => run.includes("npm -C web run build"));
+        const npmPack = runs.indexOf("npm pack --pack-destination dist/release");
+        const webArchive = runs.findIndex((run) => run.includes("hello-web.tar.gz"));
+        expect(webBuild).toBeGreaterThan(-1);
+        expect(webBuild).toBeLessThan(npmPack);
+        // Keep the release archive out of the npm tarball's dist directory.
+        expect(webArchive).toBeGreaterThan(npmPack);
+        // wxt zip -b <browser> per store, copied into dist/release under zipName()'s own names, plus
+        // the Firefox sources zip `wxt zip -b firefox` writes alongside it.
+        const zipStep = runs.find((run) => run.includes("wxt zip hosts/browser -b chrome"));
+        expect(zipStep).toContain("wxt zip hosts/browser -b firefox");
+        expect(zipStep).toContain("wxt zip hosts/browser -b edge");
+        for (const asset of [
+            zipName(target, "chrome"),
+            zipName(target, "firefox"),
+            zipName(target, "edge"),
+            sourcesZipName(target),
+        ]) {
+            expect(zipStep).toContain(asset);
+        }
+        // The signed Firefox xpi is opt-in on the JWT pair, never a hard failure when absent.
+        expect(runs.some((run) => run.includes("web-ext sign") && run.includes("FIREFOX_JWT_ISSUER"))).toBe(true);
+        expect(runs.at(-1)).toBe("cp COVERAGE.md dist/release/ && npx toolfactory coverage > dist/release/coverage.json");
+    });
+});
+/**
+ * The publish-browser-ext leg (store submission) and its opt-in Safari sibling: the leg appears
+ * only with the surface, Safari only with the surface *and* `tool.json` `browserExtension.safari`.
+ */
+describe("browser-extension release legs", () => {
+    it("release.yml carries publish-browser-ext only with the surface, Safari only with the flag", () => {
+        const withIdentity = {
+            identity: {
+                name: "hello",
+                repository: "https://github.com/acme/hello.git",
+                version: "0.1.0",
+            },
+        };
+        const noExtension = project(["npm"], withIdentity);
+        expect(yamlParse(emitted(noExtension)[".github/workflows/release.yml"]).jobs["publish-browser-ext"]).toBeUndefined();
+        const withExtension = project(["browser-extension", "mcp"], withIdentity);
+        const release = yamlParse(emitted(withExtension)[".github/workflows/release.yml"]);
+        // browser-extension alone (no npm/pypi/mcp-registry/clawhub) still gets a release.yml.
+        expect(release.jobs["publish-browser-ext"]).toBeDefined();
+        expect(release.jobs["publish-browser-ext"].needs).toEqual(["gate", "package"]);
+        expect(release.jobs["publish-browser-ext"].permissions).toEqual({ contents: "read" });
+        const steps = release.jobs["publish-browser-ext"].steps;
+        expect(steps.some((s) => s.run?.includes("wxt submit --dry-run"))).toBe(true);
+        const realSubmit = steps.find((s) => s.run?.includes("wxt submit") && !s.run.includes("--dry-run"));
+        expect(realSubmit).toBeDefined();
+        // release.yml runs only on a tag or a dispatched tag, so the job-level store gate is the whole condition.
+        expect(release.jobs["publish-browser-ext"].if).toContain("needs.gate.outputs.chrome == 'true'");
+        expect(release.jobs.release.needs).toContain("publish-browser-ext");
+        expect(release.jobs["publish-browser-ext-safari"]).toBeUndefined();
+        const withSafari = project(["browser-extension", "mcp"], {
+            ...withIdentity,
+            tool: { ...project(["browser-extension"]).tool, browserExtension: { safari: true } },
+        });
+        const safariRelease = yamlParse(emitted(withSafari)[".github/workflows/release.yml"]);
+        expect(safariRelease.jobs["publish-browser-ext-safari"]).toMatchObject({
+            needs: "gate",
+            "runs-on": "macos-latest",
+        });
+        // The Safari leg submits to App Store Connect, not dist/release/: it never gates the release.
+        expect(safariRelease.jobs.release.needs).not.toContain("publish-browser-ext-safari");
+    });
+});

package/dist/toolfactory/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/toolfactory/cli.js

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

package/dist/toolfactory/config.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "./types.js";
+/** Configuration is read from the environment; hosts inject it from their own settings UI. */
+export declare function context(): Context;