toolfactory 0.1.1

package/dist/surfaces/workflows.js

@@ -0,0 +1,809 @@
+/**
+ * Surface "workflows": the CI/release/test-harness/credential/dependency-update files, always
+ * generated (never in `tool.json.surfaces`; `project/plan.ts` adds this surface unconditionally).
+ *
+ * Every command these workflows run comes from `src/project/gate.ts` — the gate is a command and
+ * this file is its GitHub projection, so a project with no GitHub at all still has the same
+ * definition of green. Only the `uses:` steps (checkout, toolchains, caches, publishers) are this
+ * file's own.
+ *
+ * - `.github/workflows/ci.yml` — T0/T1 always: toolchain per binding, then `gateSteps`.
+ * - `.github/workflows/release.yml` — always: the gate (which also decides, once, which registries
+ *   this tag can actually publish to), `packageSteps` uploaded as one artifact, one publish job
+ *   per registry in the forced order §7 requires, the GitHub Release, and the Pages pair. A
+ *   project with no registry surface still gets the tag's Release carrying those assets.
+ * - `compose.toolfactory.yaml` — only when a host-native surface (openclaw-native /
+ *   hermes-native) is selected: the T3 container harness, one service per selected host.
+ * - `.env.example` — always: every `tool.json.config` property, uppercased, secrets marked.
+ * - `renovate.json` — always: `config:recommended`, minus the paths toolfactory itself owns.
+ */
+import { stringify as yamlStringify } from "yaml";
+import { LIVE_TEST_COMMAND } from "../bindings/python.js";
+import { githubOwner } from "../identity/name.js";
+import { isInstructionOnly, } from "../model.js";
+import { bootstrapSteps, gateSteps, gateVariable, MCP_PUBLISHER_FETCH, npmTarball, openclawTarball, outputsStep, PACKAGE_MANAGER_COMMANDS, packageSteps, RELEASE_DIR, RELEASE_SECRET_NAMES, registries, tagVersionAssert, toolfactoryCli, unpublishStep, WEB_BUILD, } from "../project/gate.js";
+import { HOST_DIR as BROWSER_HOST_DIR, sourcesZipName, zipName } from "./browser-extension.js";
+import { HERMES_PIN, hermesInstall, pluginDir as hermesPluginDir } from "./hermes-native.js";
+import { ociImage, registryName } from "./mcp-registry.js";
+import { HOST_DIR as OPENCLAW_HOST_DIR } from "./openclaw-native.js";
+import { compact, configProperties, envName, has, isSensitive, liveCredentials, npmName, requiredConfig, } from "./shared.js";
+import { skillPath } from "./skill.js";
+const YAML_HEADER = "# Generated by toolfactory. Do not edit; run `toolfactory build` to regenerate.\n\n";
+/** The one artifact the `package` job uploads and every later job reads. */
+const RELEASE_ARTIFACT = "release-assets";
+function yml(document) {
+    // lineWidth: 0 disables folding — a long `run:` one-liner stays one line instead of being
+    // wrapped mid-command, which would still parse but reads (and diffs) badly.
+    // aliasDuplicateObjects: false — shared step objects must not become YAML anchors.
+    return yamlStringify(document, { lineWidth: 0, aliasDuplicateObjects: false });
+}
+/**
+ * The tag `release.yml` is releasing. On `push: tags` it is the pushed tag; on `workflow_dispatch`
+ * it is the `tag` input — either an existing tag (the operator's re-run after minting a missing
+ * secret, which `gh run rerun` cannot be because a re-run replays the original run's secret
+ * snapshot) or a new one, cut at the dispatched branch's head by the Release itself. `gate`
+ * resolves the commit once (`outputs.sha`); every other checkout, the assert, the image tag and
+ * the Release read it, so a dispatched run releases that commit and never the branch's later head.
+ */
+const TAG_NAME = "${{ inputs.tag || github.ref_name }}";
+const RELEASE_SHA = "${{ needs.gate.outputs.sha }}";
+/** `actions/checkout`, pinned to the released tag inside `release.yml` and to the event elsewhere. */
+function checkoutStep(ref, extra) {
+    const options = compact({ ref, ...extra });
+    return compact({
+        uses: "actions/checkout@v7",
+        with: Object.keys(options).length ? options : undefined,
+    });
+}
+/** A single job dependency as GitHub Actions spells it: a bare string for one, an array for many. */
+function needsOf(jobs) {
+    if (jobs.length === 0)
+        return undefined;
+    // A copy: callers keep pushing onto the leg list after reading it.
+    return jobs.length === 1 ? jobs[0] : [...jobs];
+}
+// ---------------------------------------------------------------------------------------------
+// Provisioning: the `uses:` half, which only CI has. Everything else is a gate.ts command.
+// ---------------------------------------------------------------------------------------------
+/** The package-manager action each row needs before `setup-node`'s cache can see it. */
+const SETUP_ACTIONS = {
+    npm: [],
+    pnpm: [{ uses: "pnpm/action-setup@v4" }],
+};
+/** Checkout plus the language toolchain: everything a job needs before it can run a command. */
+function toolchainSteps(project, node, ref) {
+    const pmName = project.packageManager ?? "npm";
+    const steps = [checkoutStep(ref)];
+    if (project.tool.binding === "typescript") {
+        // uv runs the agentskills validator; the python toolchain has it anyway.
+        if (!isInstructionOnly(project.tool))
+            steps.push(...SETUP_ACTIONS[pmName]);
+        steps.push({
+            uses: "actions/setup-node@v7",
+            with: {
+                "node-version": node,
+                ...(isInstructionOnly(project.tool) ? {} : { cache: pmName }),
+            },
+        });
+        if (has(project, "skill") || has(project, "hermes-native"))
+            steps.push({ uses: "astral-sh/setup-uv@v6" });
+    }
+    else {
+        // Node only runs `npx toolfactory`; 24 also covers the openclaw CLI when selected.
+        steps.push({ uses: "actions/setup-node@v7", with: { "node-version": node } }, { uses: "astral-sh/setup-uv@v6", with: { "python-version": "3.12" } });
+    }
+    return steps;
+}
+/**
+ * Hermes has no published wheel carrying `plugins doctor`, so `toolfactory validate` needs its
+ * installer. One install per pin: the checkout, its venv and the launcher come back from the
+ * cache, so the installer only runs when the pin moves. GitHub throttles anonymous clones from
+ * shared runner addresses (the failure mode the installer's own fallbacks exist for), so that one
+ * run clones with the job's token.
+ */
+function hermesSteps(project) {
+    if (!has(project, "hermes-native"))
+        return [];
+    return [
+        {
+            name: "Restore Hermes",
+            id: "hermes",
+            uses: "actions/cache@v4",
+            with: {
+                path: ["~/.hermes", "~/.local/bin/hermes*", "~/.local/share/uv/python"].join("\n"),
+                key: `hermes-\${{ runner.os }}-${HERMES_PIN.commit}`,
+            },
+        },
+        {
+            name: "Install Hermes",
+            if: "steps.hermes.outputs.cache-hit != 'true'",
+            env: {
+                GIT_CONFIG_COUNT: "1",
+                GIT_CONFIG_KEY_0: "url.https://x-access-token:${{ github.token }}@github.com/.insteadOf",
+                GIT_CONFIG_VALUE_0: "https://github.com/",
+            },
+            run: hermesInstall(),
+        },
+        { name: "Hermes on PATH", run: 'echo "$HOME/.local/bin" >> "$GITHUB_PATH"' },
+    ];
+}
+/** One gate.ts step as a GitHub step; `node24` becomes the matrix guard where a matrix exists. */
+function actionStep(step, matrix) {
+    return compact({
+        name: step.name,
+        run: step.run,
+        env: step.env,
+        if: matrix && step.when === "node24" ? "matrix.node-version == '24'" : undefined,
+    });
+}
+// ---------------------------------------------------------------------------------------------
+// ci.yml — always.
+// ---------------------------------------------------------------------------------------------
+/**
+ * T4: the live tier runs the binding's live test with the real credentials, so it exists iff
+ * the generated live test does — when `config` declares a key that is both required and
+ * sensitive. Its secrets come from the `live-tests` environment, whose required reviewers
+ * `toolfactory bootstrap-repo` sets, and the `if` keeps a fork's pull request away from them
+ * (an environment gates deployments, not the checkout an untrusted PR ships).
+ */
+function liveJob(project) {
+    if (liveCredentials(project).length === 0)
+        return undefined;
+    const properties = configProperties(project);
+    const secrets = Object.keys(properties).filter((key) => isSensitive(properties[key]));
+    const pmName = project.packageManager ?? "npm";
+    const pm = PACKAGE_MANAGER_COMMANDS[pmName];
+    const steps = project.tool.binding === "typescript"
+        ? [
+            { uses: "actions/checkout@v7" },
+            ...SETUP_ACTIONS[pmName],
+            { uses: "actions/setup-node@v7", with: { "node-version": "24", cache: pmName } },
+            { run: pm.install },
+            { run: pm.run("build") },
+            { name: "live tests", run: pm.run("test:live") },
+        ]
+        : [
+            { uses: "actions/checkout@v7" },
+            { uses: "astral-sh/setup-uv@v6", with: { "python-version": "3.12" } },
+            { run: "uv sync" },
+            { name: "live tests", run: LIVE_TEST_COMMAND },
+        ];
+    return {
+        needs: "test",
+        if: "github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository",
+        "runs-on": "ubuntu-latest",
+        environment: "live-tests",
+        env: Object.fromEntries(secrets.map((key) => [envName(key), `\${{ secrets.${envName(key)} }}`])),
+        steps,
+    };
+}
+function ciDocument(project) {
+    const typescript = project.tool.binding === "typescript";
+    const node = typescript ? "${{ matrix.node-version }}" : "24";
+    const job = compact({
+        "runs-on": "ubuntu-latest",
+        strategy: typescript ? { matrix: { "node-version": ["22", "24"] } } : undefined,
+        steps: [
+            ...toolchainSteps(project, node),
+            ...hermesSteps(project),
+            ...gateSteps(project).map((step) => actionStep(step, typescript)),
+        ],
+    });
+    const live = liveJob(project);
+    return {
+        name: "CI",
+        on: compact({
+            push: { branches: ["main"] },
+            pull_request: {},
+            // The live tier is also the one job a maintainer wants to fire by hand.
+            workflow_dispatch: live ? {} : undefined,
+        }),
+        permissions: { contents: "read" },
+        jobs: compact({ test: job, live }),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// The browser extension's publish-* legs: store submission (stored secrets, no OIDC — none of
+// the three stores support it) and the opt-in Safari host-native leg. Every store's secret names
+// come from `registries(project)` (§1), the same table `secrets` and `unpublish` read. `wxt
+// submit` reads each credential from the environment itself under the CLI's UPPER_SNAKE_CASE
+// convention (verified live, `publish-browser-extension@6.1.1`'s resolveConfig): the shell only
+// has to decide which store's `--<store>-zip` flag to pass, so an unconfigured store is a no-op,
+// never a validation error.
+// ---------------------------------------------------------------------------------------------
+/** The three store rows, in submit order; absent from `rows` when the store is not applicable. */
+const STORES = ["chrome", "firefox", "edge"];
+function storeRows(rows) {
+    return STORES.map((id) => rows.find((row) => row.id === id)).filter((row) => row !== undefined);
+}
+/** `wxt submit --dry-run` (zip + payload check) or the real submission, gated per store. */
+function browserExtSubmitScript(project, rows, dryRun) {
+    const zip = (browser) => `${RELEASE_ARTIFACT}/${zipName(project, browser)}`;
+    const present = (names) => names.map((name) => `[ -n "$${name}" ]`).join(" && ");
+    const flags = {
+        chrome: `--chrome-zip ${zip("chrome")}`,
+        firefox: `--firefox-zip ${zip("firefox")} --firefox-sources-zip ${RELEASE_ARTIFACT}/${sourcesZipName(project)}`,
+        edge: `--edge-zip ${zip("edge")}`,
+    };
+    return [
+        'flags=""',
+        ...storeRows(rows).map((row) => `if ${present(row.secrets)}; then flags="$flags ${flags[row.id]}"; fi`),
+        'if [ -z "$flags" ]; then echo "No browser store credentials configured; skipping wxt submit."; exit 0; fi',
+        `npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt submit ${dryRun ? "--dry-run " : ""}$flags`,
+    ].join("\n");
+}
+function browserExtPublishJob(project, rows) {
+    const stores = storeRows(rows);
+    return {
+        needs: needsOf(["gate", "package"]),
+        if: stores.map((row) => `needs.gate.outputs.${gateVariable(row)} == 'true'`).join(" || "),
+        "runs-on": "ubuntu-latest",
+        permissions: { contents: "read" },
+        env: {
+            // Constant, not a secret: Chrome Web Store API v2 (mandatory — v1.1 shuts off 15 Oct 2026)
+            // authenticates with a service account, not v1.1's client-id/secret/refresh-token triple,
+            // and `publish-browser-extension` switches its whole config shape on this value.
+            CHROME_API_VERSION: "v2",
+            ...Object.fromEntries(stores.flatMap((row) => row.secrets).map((name) => [name, `\${{ secrets.${name} }}`])),
+        },
+        steps: [
+            ...toolchainSteps(project, "24", RELEASE_SHA),
+            // Only the `wxt`/`publish-browser-extension` binary is needed — the zips it submits are the
+            // `package` job's own, downloaded below, not rebuilt.
+            { run: `npm --prefix ${BROWSER_HOST_DIR} install` },
+            {
+                uses: "actions/download-artifact@v8",
+                with: { name: RELEASE_ARTIFACT, path: RELEASE_ARTIFACT },
+            },
+            {
+                // Not a credential check for every store: the dry run reaches the network only for
+                // Chrome (API v2's `fetchStatus`) and Firefox (`GET /api/v5/addons/addon/{id}`). Edge's
+                // dry run makes no request at all, so what this proves there is the zip, not the token.
+                name: "wxt submit --dry-run (zips, plus a live credential read for Chrome and Firefox)",
+                run: browserExtSubmitScript(project, rows, true),
+            },
+            { name: "wxt submit", run: browserExtSubmitScript(project, rows, false) },
+        ],
+    };
+}
+/**
+ * Safari has no headless publish path (§6): `xcrun safari-web-extension-converter` is macOS-only
+ * and Apple's own Xcode archive/export is the only route to App Store Connect. Opt-in
+ * (`tool.json` `browserExtension.safari`) and never in the default matrix — a `macos-latest`
+ * runner and a paid Apple Developer account are real costs the surface must not impose by
+ * default. Documented as the host-native leg: toolfactory scaffolds the payload
+ * (`wxt build -b safari`, any OS) and converts + signs it here; the archive/export invocation is
+ * Apple's own and unverifiable without macOS, so an author adjusting scheme/entitlements for
+ * their own app id is expected.
+ */
+function browserExtSafariJob(project, safari) {
+    return {
+        needs: "gate",
+        if: `needs.gate.outputs.${gateVariable(safari)} == 'true'`,
+        "runs-on": "macos-latest",
+        permissions: { contents: "read" },
+        env: Object.fromEntries(safari.secrets.map((name) => [name, `\${{ secrets.${name} }}`])),
+        steps: [
+            ...toolchainSteps(project, "24", RELEASE_SHA),
+            { run: `npm --prefix ${BROWSER_HOST_DIR} install` },
+            // `npm exec` never changes the working directory, so `wxt` needs its root passed
+            // explicitly (verified live against `wxt zip`, the same CLI).
+            {
+                run: `npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build ${BROWSER_HOST_DIR} -b safari`,
+            },
+            {
+                name: "Convert to an Xcode project",
+                run: `xcrun safari-web-extension-converter ${BROWSER_HOST_DIR}/.output/safari-mv2 --project-location dist/safari --no-open --no-prompt`,
+            },
+            {
+                name: "Archive and export (App Store Connect API key)",
+                run: [
+                    `key="dist/safari/AuthKey_$ASC_KEY_ID.p8" && printf '%s' "$ASC_PRIVATE_KEY" > "$key"`,
+                    `project="$(ls dist/safari/*.xcodeproj)" && scheme="$(basename "$project" .xcodeproj)"`,
+                    `xcodebuild archive -project "$project" -scheme "$scheme" -archivePath dist/safari/build.xcarchive`,
+                    `xcodebuild -exportArchive -archivePath dist/safari/build.xcarchive -exportPath dist/safari/export -authenticationKeyPath "$key" -authenticationKeyID "$ASC_KEY_ID" -authenticationKeyIssuerID "$ASC_ISSUER_ID"`,
+                ].join(" && "),
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// release.yml — always: the Release carries the assets; each registry leg runs iff `gate` says it can.
+// ---------------------------------------------------------------------------------------------
+/**
+ * Which registries this tag can publish to, decided once. Each gated row's `gate` runs with that
+ * row's secrets and confirm variable in its environment and the answer becomes a job output,
+ * because `secrets` and `env` are unreadable in a job-level `if` and the reusable-workflow legs
+ * cannot be gated inside a `run:`. A row that cannot publish prints one notice pointing at its page.
+ */
+function presenceStep(rows) {
+    const gated = rows.filter((row) => row.gate);
+    const env = { GH_TOKEN: "${{ github.token }}" };
+    for (const row of gated) {
+        for (const name of row.secrets)
+            env[name] = `\${{ secrets.${name} }}`;
+        if (row.confirmVariable)
+            env[row.confirmVariable] = `\${{ vars.${row.confirmVariable} }}`;
+    }
+    const script = gated.map((row) => {
+        const v = gateVariable(row);
+        return `${v}=false; if ${row.gate}; then ${v}=true; else echo "::notice::${row.id}: not published at this tag — ${row.url}"; fi; echo "${v}=$${v}" >> "$GITHUB_OUTPUT"`;
+    });
+    return {
+        id: "presence",
+        name: "which registries this tag can publish to",
+        env,
+        run: script.join("\n"),
+    };
+}
+function presenceOutputs(rows) {
+    const gated = rows.filter((row) => row.gate);
+    return gated.length
+        ? Object.fromEntries(gated.map((row) => [
+            gateVariable(row),
+            `\${{ steps.presence.outputs.${gateVariable(row)} }}`,
+        ]))
+        : undefined;
+}
+function releaseDocument(project) {
+    const npmSelected = has(project, "npm");
+    const pypiSelected = has(project, "pypi");
+    const mcpRegistrySelected = has(project, "mcp-registry");
+    // ClawHub publishes the openclaw-native package; without that host there is nothing to publish.
+    const clawhubSelected = has(project, "clawhub") && has(project, "openclaw-native");
+    // ClawHub's skill catalog is a separate track from its plugin catalog above: it publishes
+    // straight from the checkout (no openclaw-native package needed), so `skill` is all it takes.
+    const clawhubSkillSelected = has(project, "clawhub") && has(project, "skill");
+    const browserExtSelected = has(project, "browser-extension");
+    const rows = registries(project);
+    const gated = (id) => {
+        const row = rows.find((entry) => entry.id === id);
+        return row?.gate ? `needs.gate.outputs.${gateVariable(row)} == 'true'` : undefined;
+    };
+    const cli = toolfactoryCli(project);
+    const assert = tagVersionAssert(project);
+    const jobs = {
+        gate: compact({
+            "runs-on": "ubuntu-latest",
+            permissions: compact({ contents: "read", pages: has(project, "web") ? "read" : undefined }),
+            env: { RELEASE_TAG: TAG_NAME },
+            outputs: { sha: "${{ steps.tag.outputs.sha }}", ...presenceOutputs(rows) },
+            steps: [
+                // The whole history: the tag may exist (a re-run) or not yet (a dispatch cuts it), and
+                // `unpublish` reads tool.json at the previous tag.
+                checkoutStep(undefined, { "fetch-depth": 0 }),
+                ...toolchainSteps(project, "24").slice(1),
+                {
+                    id: "tag",
+                    name: "the commit this tag releases",
+                    run: 'sha=$(git rev-parse -q --verify "refs/tags/$RELEASE_TAG^{commit}" 2>/dev/null || git rev-parse HEAD) && git checkout -q "$sha" && echo "sha=$sha" >> "$GITHUB_OUTPUT"',
+                },
+                ...(assert ? [actionStep(assert, false)] : []),
+                ...hermesSteps(project),
+                ...gateSteps(project).map((step) => actionStep(step, false)),
+                presenceStep(rows),
+            ],
+        }),
+        package: compact({
+            needs: "gate",
+            "runs-on": "ubuntu-latest",
+            permissions: { contents: "read" },
+            // The Firefox self-hosted xpi packageSteps emits (gate.ts) is opt-in on this pair: present,
+            // it signs; absent, that one step no-ops and the job still packages the unsigned zips.
+            env: has(project, "browser-extension")
+                ? {
+                    FIREFOX_JWT_ISSUER: "${{ secrets.FIREFOX_JWT_ISSUER }}",
+                    FIREFOX_JWT_SECRET: "${{ secrets.FIREFOX_JWT_SECRET }}",
+                }
+                : undefined,
+            steps: [
+                ...toolchainSteps(project, "24", RELEASE_SHA),
+                ...packageSteps(project).map((step) => actionStep(step, false)),
+                {
+                    uses: "actions/upload-artifact@v7",
+                    with: { name: RELEASE_ARTIFACT, path: `${RELEASE_DIR}/` },
+                },
+            ],
+        }),
+    };
+    const priorLegs = [];
+    if (npmSelected) {
+        const tarball = `${RELEASE_ARTIFACT}/${npmTarball(project)}`;
+        jobs["publish-npm"] = compact({
+            needs: ["gate", "package"],
+            if: gated("npm"),
+            "runs-on": "ubuntu-latest",
+            permissions: { "id-token": "write", contents: "read" },
+            env: { NPM_TRUSTED_PUBLISHER: "${{ vars.NPM_TRUSTED_PUBLISHER }}" },
+            steps: [
+                checkoutStep(RELEASE_SHA),
+                {
+                    uses: "actions/setup-node@v7",
+                    with: { "node-version": "24", "registry-url": "https://registry.npmjs.org" },
+                },
+                {
+                    uses: "actions/download-artifact@v8",
+                    with: { name: RELEASE_ARTIFACT, path: RELEASE_ARTIFACT },
+                },
+                // OIDC is selected only after bootstrap-repo verified `npm trust` and set the repository
+                // variable. A token remains the fallback for a new package and for an existing package
+                // whose publisher was not configured. npm versions are immutable, so a dispatch retry
+                // after adding credentials leaves an already-published version alone.
+                {
+                    name: "npm publish",
+                    env: {
+                        NPM_TOKEN: "${{ vars.NPM_TRUSTED_PUBLISHER != 'true' && secrets.NPM_TOKEN || '' }}",
+                    },
+                    run: `if npm view ${npmName(project)}@${project.identity.version ?? "0.0.0"} version >/dev/null 2>&1; then echo "::notice::npm: ${npmName(project)}@${project.identity.version ?? "0.0.0"} already published; skipping immutable version."; elif [ "$NPM_TRUSTED_PUBLISHER" = true ]; then npm publish ${tarball} --access public; else NODE_AUTH_TOKEN="$NPM_TOKEN" npm publish ${tarball} --access public; fi`,
+                },
+            ],
+        });
+        priorLegs.push("publish-npm");
+    }
+    if (pypiSelected) {
+        jobs["publish-pypi"] = compact({
+            needs: "gate",
+            if: gated("pypi"),
+            "runs-on": "ubuntu-latest",
+            environment: "pypi",
+            permissions: { "id-token": "write" },
+            steps: [
+                checkoutStep(RELEASE_SHA),
+                { uses: "astral-sh/setup-uv@v6" },
+                { run: "uv build" },
+                {
+                    name: "Publish package distributions to PyPI",
+                    uses: "pypa/gh-action-pypi-publish@release/v1",
+                },
+            ],
+        });
+        priorLegs.push("publish-pypi");
+    }
+    const owner = githubOwner(project.identity.repository);
+    if (mcpRegistrySelected && owner) {
+        // The image the `mcp-registry` surface already named in `server.json`'s oci entry, and the
+        // root Dockerfile it emitted alongside it. `type=semver` turns the v-prefixed tag into the
+        // bare version the entry carries — the gate has already asserted they agree.
+        const image = ociImage(project, owner).replace(/:[^:]*$/, "");
+        jobs["publish-oci"] = compact({
+            needs: "gate",
+            if: gated("oci"),
+            "runs-on": "ubuntu-latest",
+            permissions: {
+                contents: "read",
+                packages: "write",
+                attestations: "write",
+                "id-token": "write",
+            },
+            steps: [
+                checkoutStep(RELEASE_SHA),
+                {
+                    uses: "docker/login-action@v4",
+                    with: {
+                        registry: "ghcr.io",
+                        username: "${{ github.actor }}",
+                        password: "${{ secrets.GITHUB_TOKEN }}",
+                    },
+                },
+                {
+                    id: "meta",
+                    uses: "docker/metadata-action@v6",
+                    with: {
+                        images: image,
+                        tags: `type=semver,pattern={{version}},value=${TAG_NAME}`,
+                        // The registry's OCI ownership check reads this label back out of the image config.
+                        labels: `io.modelcontextprotocol.server.name=${registryName(project)}`,
+                    },
+                },
+                {
+                    uses: "docker/build-push-action@v7",
+                    with: {
+                        context: ".",
+                        push: true,
+                        tags: "${{ steps.meta.outputs.tags }}",
+                        labels: "${{ steps.meta.outputs.labels }}",
+                    },
+                },
+            ],
+        });
+        priorLegs.push("publish-oci");
+    }
+    if (mcpRegistrySelected) {
+        jobs["publish-mcp-registry"] = compact({
+            // After every package leg (§7): mcp-publisher validates that each `packages[]` entry
+            // already exists in its own registry, the oci image included — so the gate lets it run only
+            // when every package leg does.
+            needs: needsOf(["gate", ...priorLegs]),
+            if: gated("mcp-registry"),
+            "runs-on": "ubuntu-latest",
+            permissions: { "id-token": "write", contents: "read" },
+            steps: [
+                checkoutStep(RELEASE_SHA),
+                { run: MCP_PUBLISHER_FETCH },
+                { run: "./mcp-publisher login github-oidc && ./mcp-publisher publish" },
+            ],
+        });
+        priorLegs.push("publish-mcp-registry");
+    }
+    const comments = [
+        "`gate` decides once which registries this tag can publish to (a job-level `if` cannot read",
+        "secrets) and every leg obeys its output, so a tag with no secrets is still green: gate,",
+        "package, the Release, and whatever else applies. After adding a secret, re-run with",
+        "`gh workflow run release.yml -f tag=vX.Y.Z` — never `gh run rerun`, which replays the",
+        "original run's secret snapshot. `release` first retracts every registry a surface dropped",
+        "since the previous tag published to (git is the ledger; `toolfactory unpublish`), and",
+        "`toolfactory secrets status` / `bootstrap-repo` cover the one-time steps that are left.",
+    ];
+    if (clawhubSelected) {
+        jobs["publish-clawhub"] = compact({
+            if: "${{ !cancelled() && needs.package.result == 'success' && !contains(needs.*.result, 'failure') && needs.gate.outputs.clawhub_package == 'true' }}",
+            // Last (§7): content-fingerprint deduped by ClawHub, therefore safe to retry. The reusable
+            // workflow has no build step, so it publishes the tarball the `package` job already built
+            // rather than the repository subdirectory. It is a workflow call, so it has no `permissions`
+            // block of its own and inherits the file's `contents: read`.
+            needs: needsOf(["gate", "package", ...priorLegs]),
+            uses: "openclaw/clawhub/.github/workflows/package-publish.yml@main",
+            with: {
+                package_artifact_name: RELEASE_ARTIFACT,
+                package_artifact_path: openclawTarball(project),
+                dry_run: false,
+                wait_for_publication: true,
+            },
+            secrets: { clawhub_token: "${{ secrets.CLAWHUB_TOKEN }}" },
+        });
+        priorLegs.push("publish-clawhub");
+        comments.push("", "ClawHub's GitHub-OIDC trusted publishing covers `workflow_dispatch` only, not", "`push: tags` — this leg is the one that is not secretless (§7): it needs a stored", "CLAWHUB_TOKEN repo secret, and `clawhub package trusted-publisher set` does not help here.");
+    }
+    if (clawhubSkillSelected) {
+        // A separate ClawHub track from the package leg above: publishes skills/<N> to ClawHub's
+        // skill catalog straight from the checkout, so it only needs `gate`, not the built tarball.
+        // ClawHub's own reusable workflow derives slug/name/version from SKILL.md and dedupes by
+        // content fingerprint, same as `clawhub package publish` above — safe to retry.
+        jobs["publish-clawhub-skill"] = compact({
+            if: gated("clawhub-skill"),
+            needs: "gate",
+            uses: "openclaw/clawhub/.github/workflows/skill-publish.yml@main",
+            with: { skill_path: skillPath(project).replace(/\/SKILL\.md$/, ""), dry_run: false },
+            secrets: { clawhub_token: "${{ secrets.CLAWHUB_TOKEN }}" },
+        });
+        priorLegs.push("publish-clawhub-skill");
+        comments.push("", "ClawHub skill publishing has no OIDC trusted-publishing path yet (V1 is token-only,", "per its own docs) — this leg reuses the same stored CLAWHUB_TOKEN as publish-clawhub.");
+    }
+    if (browserExtSelected) {
+        jobs["publish-browser-ext"] = browserExtPublishJob(project, rows);
+        priorLegs.push("publish-browser-ext");
+        comments.push("", "None of Chrome Web Store, Firefox Add-ons or Edge Add-ons supports GitHub OIDC — like", "CLAWHUB_TOKEN above, publish-browser-ext is a stored-secrets leg, gated per store on that", "store's own secrets (nine names across the three stores); a store left unconfigured is", "skipped, never a failure, and the leg's own dry run runs on every push and pull request.");
+        const safari = rows.find((row) => row.id === "safari");
+        if (safari) {
+            // Opt-in and outside the release graph on purpose: it submits to App Store Connect, not
+            // dist/release/, so nothing downstream needs to wait on it.
+            jobs["publish-browser-ext-safari"] = browserExtSafariJob(project, safari);
+            comments.push("", "publish-browser-ext-safari (opt-in, tool.json browserExtension.safari) is the macOS", "host-native leg: xcrun safari-web-extension-converter, then an Xcode archive/export", "signed with an App Store Connect API key. Runs on macos-latest, needs only `gate`, and", "does not gate the release — it submits to App Store Connect, not dist/release/.");
+        }
+    }
+    jobs.release = {
+        // The tag's own release, after every leg: the assets are the same ones the registries got.
+        // Skipped legs must not skip it, only failed ones; hence the explicit condition.
+        needs: needsOf(["gate", "package", ...priorLegs]),
+        if: "${{ !cancelled() && needs.package.result == 'success' && !contains(needs.*.result, 'failure') }}",
+        "runs-on": "ubuntu-latest",
+        // Retraction needs what publishing needed: packages and pages to delete, OIDC for the MCP
+        // registry, and the stored tokens the dropped registries' rows name.
+        permissions: { contents: "write", packages: "write", pages: "write", "id-token": "write" },
+        env: {
+            RELEASE_TAG: TAG_NAME,
+        },
+        steps: [
+            // The whole history: `unpublish` reads tool.json at the previous tag.
+            checkoutStep(RELEASE_SHA, { "fetch-depth": 0 }),
+            ...toolchainSteps(project, "24", RELEASE_SHA).slice(1),
+            ...bootstrapSteps(project).map((step) => actionStep(step, false)),
+            {
+                ...actionStep(unpublishStep(project), false),
+                env: {
+                    GH_TOKEN: "${{ github.token }}",
+                    ...Object.fromEntries(RELEASE_SECRET_NAMES.map((name) => [name, `\${{ secrets.${name} }}`])),
+                },
+            },
+            {
+                uses: "actions/download-artifact@v8",
+                with: { name: RELEASE_ARTIFACT, path: RELEASE_ARTIFACT },
+            },
+            {
+                uses: "softprops/action-gh-release@v3",
+                with: {
+                    tag_name: TAG_NAME,
+                    // A tag the dispatch is cutting does not exist yet: the Release creates it here.
+                    target_commitish: RELEASE_SHA,
+                    generate_release_notes: true,
+                    files: `${RELEASE_ARTIFACT}/*`,
+                    fail_on_unmatched_files: true,
+                },
+            },
+        ],
+    };
+    if (has(project, "web")) {
+        jobs["pages-build"] = compact({
+            needs: "gate",
+            if: gated("pages"),
+            "runs-on": "ubuntu-latest",
+            permissions: { contents: "read" },
+            steps: [
+                ...toolchainSteps(project, "24", RELEASE_SHA),
+                ...[...bootstrapSteps(project), outputsStep(project)].map((step) => actionStep(step, false)),
+                { uses: "actions/configure-pages@v5" },
+                {
+                    name: "web build",
+                    // A project page is served from /<repo>/, so Vite's base has to say so or every asset
+                    // 404s. `web/vite.config.ts` reads PAGES_BASE and defaults to "/" for `npm run dev`.
+                    env: { PAGES_BASE: "/${{ github.event.repository.name }}/" },
+                    run: WEB_BUILD,
+                },
+                {
+                    name: "publish the schema and the coverage report alongside the app",
+                    run: `cp dev.toolfactory/tool.schema.json COVERAGE.md web/dist/ && ${cli} coverage > web/dist/coverage.json`,
+                },
+                { uses: "actions/upload-pages-artifact@v3", with: { path: "web/dist" } },
+            ],
+        });
+        jobs["pages-deploy"] = {
+            needs: "pages-build",
+            "runs-on": "ubuntu-latest",
+            permissions: { pages: "write", "id-token": "write" },
+            environment: { name: "github-pages", url: "${{ steps.deployment.outputs.page_url }}" },
+            steps: [{ id: "deployment", uses: "actions/deploy-pages@v5" }],
+        };
+        comments.push("", "Pages must be enabled with Source = GitHub Actions once (`toolfactory bootstrap-repo` does", "it through gh); until then the gate skips the Pages pair with a notice.");
+    }
+    const doc = {
+        name: "Release",
+        on: {
+            push: { tags: ["v*"] },
+            workflow_dispatch: {
+                inputs: {
+                    tag: {
+                        description: "The v* tag to release: an existing one to publish again (e.g. after adding a secret), or a new one to cut at this branch's head",
+                        required: true,
+                        type: "string",
+                    },
+                },
+            },
+        },
+        permissions: { contents: "read" },
+        jobs,
+    };
+    return { doc, comments };
+}
+// ---------------------------------------------------------------------------------------------
+// compose.toolfactory.yaml — when openclaw-native or hermes-native is selected.
+// ---------------------------------------------------------------------------------------------
+function composeDocument(project) {
+    const openclawSelected = has(project, "openclaw-native");
+    const hermesSelected = has(project, "hermes-native");
+    if (!openclawSelected && !hermesSelected)
+        return undefined;
+    const requiresBrowser = project.operations.some((op) => op.requires.includes("browser"));
+    const services = {};
+    if (openclawSelected) {
+        services.openclaw = {
+            image: `ghcr.io/openclaw/openclaw:latest${requiresBrowser ? "-browser" : ""}`,
+            volumes: [".:/work", "PLUGIN_DATA:/data"],
+            env_file: [".env"],
+            // `--link` registers the mounted checkout in place: a plain install copies the whole tree,
+            // node_modules/openclaw included, and trips the install-time symlink scan on the `file:`
+            // core dependency. `--accept-capabilities` is what makes the install non-interactive.
+            command: [
+                "sh",
+                "-c",
+                `openclaw plugins install --link /work/${OPENCLAW_HOST_DIR} --force --accept-capabilities && openclaw plugins inspect ${project.identity.name} --runtime --json`,
+            ],
+        };
+    }
+    if (hermesSelected) {
+        services.hermes = {
+            // No published Hermes image exists; its own installer, pinned, in a stock image is the host.
+            image: "buildpack-deps:bookworm",
+            volumes: [".:/work", "PLUGIN_DATA:/data"],
+            environment: { HERMES_HOME: "/data" },
+            env_file: [".env"],
+            command: [
+                "bash",
+                "-c",
+                `${hermesInstall()} && hermes plugins doctor /work/${hermesPluginDir(project)} --ci`,
+            ],
+        };
+    }
+    return { services, volumes: { PLUGIN_DATA: {} } };
+}
+// ---------------------------------------------------------------------------------------------
+// .env.example — always: every config key, from the one credential declaration (§6).
+// ---------------------------------------------------------------------------------------------
+function envExample(project) {
+    const properties = configProperties(project);
+    const required = new Set(requiredConfig(project));
+    const keys = Object.keys(properties);
+    const lines = [
+        "# Generated by toolfactory from dev.toolfactory/tool.json `config`. Copy to `.env` and fill in.",
+    ];
+    if (keys.length === 0)
+        lines.push("# No configuration keys are declared yet.");
+    for (const key of keys) {
+        const property = properties[key];
+        const sensitive = isSensitive(property);
+        const meta = (property["x-toolfactory"] ?? {});
+        const description = typeof property.description === "string" ? property.description : key;
+        const tags = [required.has(key) ? "required" : "optional", sensitive ? "secret" : undefined]
+            .filter(Boolean)
+            .join(", ");
+        lines.push("", `# ${description} (${tags})${meta.url ? ` — get one: ${meta.url}` : ""}`, `${envName(key)}=`);
+    }
+    const release = registries(project).filter((row) => row.secrets.length);
+    if (release.length) {
+        lines.push("", "# Release credentials (repository secrets; `toolfactory bootstrap-repo` pushes them from .env,", "# `toolfactory secrets status` explains each). Leave one empty to skip that registry.");
+        for (const row of release) {
+            lines.push("", `# ${row.id}: ${row.url}`, ...row.secrets.map((name) => `${name}=`));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+// ---------------------------------------------------------------------------------------------
+// renovate.json — always: config:recommended already spans npm/PyPI/Actions/Docker (C9).
+// ---------------------------------------------------------------------------------------------
+function renovatePatch() {
+    return {
+        $schema: "https://docs.renovatebot.com/renovate-schema.json",
+        // `group:all` is Renovate's own preset for one PR per run rather than one per dependency;
+        // writing the rule out by hand would only own a key the author needs for their own pins.
+        extends: ["config:recommended", "group:all"],
+        // Mirrors OpenClaw's own minimumReleaseAge.
+        minimumReleaseAge: "7 days",
+        // These files are projections of dev.toolfactory/tool.json and are SHA-locked: a Renovate PR
+        // editing one makes `toolfactory check` fail and the next `toolfactory build` reverts it.
+        // Upgrading what they pin is a toolfactory version bump (§8 C6).
+        ignorePaths: [".github/workflows/**", "hosts/*/package.json", "web/package.json"],
+    };
+}
+export const surface = {
+    id: "workflows",
+    plan(project) {
+        const files = [
+            {
+                kind: "file",
+                path: ".github/workflows/ci.yml",
+                content: YAML_HEADER + yml(ciDocument(project)),
+            },
+        ];
+        const release = releaseDocument(project);
+        if (release) {
+            const header = [
+                YAML_HEADER.trimEnd(),
+                ...release.comments.map((line) => (line ? `# ${line}` : "#")),
+                "",
+                "",
+            ].join("\n");
+            files.push({
+                kind: "file",
+                path: ".github/workflows/release.yml",
+                content: header + yml(release.doc),
+            });
+        }
+        const compose = composeDocument(project);
+        if (compose) {
+            files.push({
+                kind: "file",
+                path: "compose.toolfactory.yaml",
+                content: YAML_HEADER + yml(compose),
+            });
+        }
+        files.push({ kind: "file", path: ".env.example", content: envExample(project) });
+        // A merge file: an author's own keys (a `customManagers` for pins in their source) survive.
+        files.push({
+            kind: "merge",
+            path: "renovate.json",
+            format: "json",
+            patch: renovatePatch(),
+            owned: ["extends", "ignorePaths"],
+        });
+        return files;
+    },
+};