toolfactory 0.1.1

package/dist/project/gate.d.ts

@@ -0,0 +1,129 @@
+import { type PackageManager, type Project, type SurfaceId } from "../model.js";
+export interface GateStep {
+    /** Step label: the CI step name, and the banner the shell script echoes. */
+    name: string;
+    run: string;
+    /**
+     * `"ci"` — runner provisioning no checkout may perform on the author's machine (a global or
+     * system-wide install); the local runner skips it. `"node24"` — needs Node >= 24, which the
+     * `openclaw` CLI does; the matrix guard in `ci.yml`.
+     */
+    when?: "ci" | "node24";
+    env?: Record<string, string>;
+}
+/** Where `toolfactory package` and the release `package` job leave every asset. */
+export declare const RELEASE_DIR = "dist/release";
+/** The web app's build, shared by the release tarball and the Pages job (which sets `PAGES_BASE`). */
+export declare const WEB_BUILD = "npm -C web ci && npm -C web run build";
+/** The commands each supported package manager spells; `package.json` `packageManager` picks the row. */
+export declare const PACKAGE_MANAGER_COMMANDS: Record<PackageManager, {
+    install: string;
+    run: (script: string) => string;
+    test: string;
+}>;
+/** How the project invokes toolfactory: the devDependency in a TypeScript project, a pinned fetch otherwise. */
+export declare function toolfactoryCli(project: Project): string;
+/**
+ * Dependencies and, for TypeScript, the build — everything both the gate and the packaging run
+ * need before any command that imports the project's own code.
+ */
+/**
+ * Output files (§2.2 S4) are build products, not tracked: a fresh checkout has none, and the
+ * validators and the web build read them. On a tree `check` has just proved current, `build`
+ * writes exactly those.
+ */
+export declare function outputsStep(project: Project): GateStep;
+export declare function bootstrapSteps(project: Project): GateStep[];
+/**
+ * The gate: bootstrap, the drift check, the validator CLIs the selected surfaces need on PATH,
+ * `toolfactory validate` (every surface's own upstream validator), the author's `check` and
+ * tests, and the credential-free OpenClaw turn. Nothing is transcribed from a surface — the
+ * commands a surface owns are reached through `toolfactory validate`, so this list cannot drift
+ * away from what `validate` actually runs.
+ */
+export declare function gateSteps(project: Project): GateStep[];
+/**
+ * §2.2: one version, in the identity file, projected everywhere by `build`. A release therefore
+ * asserts the tag against it and never writes it — rewriting a SHA-locked file from the tag would
+ * be a change `build` did not make and `check` would fail on the next run.
+ */
+export declare function tagVersionAssert(project: Project): GateStep | undefined;
+/**
+ * The release assets, into `dist/release/`: the same list locally (`toolfactory package`) and in
+ * the release workflow's `package` job, which uploads the directory as one artifact. Publishing
+ * to a registry stays a CI concern; producing the artifacts never is.
+ */
+export declare function packageSteps(project: Project): GateStep[];
+/** npm's filename for the root package, including its flattened scope. */
+export declare function npmTarball(project: Project): string;
+/** The ClawHub tarball `npm pack ./hosts/openclaw` writes, by name, inside the release artifact. */
+export declare function openclawTarball(project: Project): string;
+/**
+ * One row per (surface, registry): what publishing needs, what proves it, how to retract.
+ * DESIGN.md §1 (research3). `secrets status`/`check`, the release legs' presence gating and the
+ * unpublish step all read this table and nothing else.
+ */
+export interface Registry {
+    /** Stable id: the release job suffix, the `secrets status` row, the unpublish step name. */
+    id: "npm" | "pypi" | "mcp-registry" | "oci" | "clawhub-package" | "clawhub-skill" | "pages" | "chrome" | "firefox" | "edge" | "safari";
+    /** The surfaces whose selection publishes here; all must be selected. */
+    surfaces: SurfaceId[];
+    /** Environment names the publish leg consumes (repository scope); [] for OIDC/GITHUB_TOKEN legs. */
+    secrets: string[];
+    /** Environment names retraction consumes when they differ from `secrets`. */
+    retractSecrets?: string[];
+    /** Where a human mints the credential or does the one-time web step. */
+    url: string;
+    /** Where a human retracts by hand, when that differs from `url`; the notices point at it. */
+    retractUrl?: string;
+    /** Shell: exit 0 iff the credential in the environment is accepted (`secrets check`). Absent = no probe exists. */
+    probe?: string;
+    /** Shell: exit 0 iff the current version is published (anonymous; idempotency for publish and unpublish). */
+    exists?: string;
+    /**
+     * Shell: exit 0 iff this leg can publish at this tag — the release `gate` job's
+     * `outputs.<id>`, which every leg's job-level `if` reads. Absent = the leg is never gated.
+     */
+    gate?: string;
+    /** Shell: the retraction, one upstream CLI; absent = manual. */
+    retract?: string;
+    /** With `--hard`: the destructive form. */
+    retractHard?: string;
+    /** A one-time human step with no API, gated by a repository variable the human sets when done. */
+    confirmVariable?: string;
+}
+/** ClawHub's CLI, pinned: no runner carries `clawhub` on PATH and every ClawHub row shells to it. */
+export declare const CLAWHUB_PIN = "0.23.3";
+/** The `mcp-publisher` binary: the publish leg and the MCP Registry retraction fetch the same one. */
+export declare const MCP_PUBLISHER_FETCH = "curl -sL \"https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz\" | tar xz mcp-publisher";
+/**
+ * Every name any row can consume, selected or not: the release's retraction step runs against
+ * the previous tag's selection, so its environment carries them all (an unset one is empty).
+ */
+export declare const RELEASE_SECRET_NAMES: string[];
+/**
+ * Every registry row whose surfaces are all selected, with the exact upstream command for each
+ * column. Four consumers read this and nothing else: `secrets status`, `secrets check`, the
+ * release legs' presence gating, and the unpublish step.
+ */
+export declare function registries(project: Project): Registry[];
+/** The shell variable the release gate holds a row's presence in; the job output takes the same name. */
+export declare function gateVariable(row: Registry): string;
+/** Every environment name a secret can be set under: sensitive config keys, then the release registries' tokens. */
+export declare function secretsOf(project: Project): string[];
+/**
+ * The one-time human steps the table cannot automate — no API at all, or one no token in CI can
+ * reach. `secrets status` and `bootstrap-repo` print the same list.
+ */
+export declare function manualSteps(project: Project): string[];
+/**
+ * The retraction of every registry a dropped surface used to publish to, one step per row:
+ * `exists` → the secret guard → `retract`, so re-running the same tag is a no-op and a registry
+ * with no machine retraction prints the exact page instead of failing the release.
+ *
+ * `previous` is the project as the previous tag left it — its surfaces and its version — so the
+ * existence probes ask about what that tag actually published, not about the tag being cut now.
+ */
+export declare function unpublishSteps(previous: Project, dropped: readonly SurfaceId[], hard?: boolean): GateStep[];
+/** The one line CI runs, exactly as `toolfactory validate` is one gate step: the whole diff-and-retract. */
+export declare function unpublishStep(project: Project): GateStep;