@geenius/release-toolkit 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,1401 @@
+import { z } from 'zod';
+
+/**
+ * Public report shapes. Stable across versions — schema changes require a minor
+ * bump and an explicit CHANGELOG entry. Downstream consumers (CI integrations,
+ * coverage aggregators, gauntlet runners) parse these reports directly.
+ */
+type StepStatus = "passed" | "failed" | "skipped" | "missing" | "unauthenticated";
+type CommandStatus = "passed" | "failed" | "skipped";
+interface StepReport {
+    /** Human-readable step name, e.g. `"pnpm audit"`, `"osv-scanner"`, `"smoke @geenius/ai-magic/react"`. */
+    name: string;
+    status: StepStatus;
+    /** Short reason for non-passed states. */
+    reason?: string;
+    durationMs: number;
+    /** Last 4 KB of combined stdout/stderr; useful for triage without re-running. */
+    output?: string;
+}
+interface CommandReport {
+    /** Canonical command name (e.g. `"supply-chain"`, `"license"`). */
+    command: string;
+    status: CommandStatus;
+    /** ISO 8601 timestamp when the command started. */
+    startedAt: string;
+    durationMs: number;
+    steps: StepReport[];
+    /** Free-form metadata: package name, fixture id, version, etc. */
+    meta?: Record<string, unknown>;
+}
+/** Per-scanner runtime state. Distinct from `StepStatus` because a `missing`
+ *  scanner is data, not failure, and the same `missing` value can map to
+ *  different downstream behavior (`passed`/`skipped`/`failed`) depending on
+ *  the scanner's `required` configuration.
+ */
+type ScannerState = {
+    kind: "passed";
+    output?: string;
+} | {
+    kind: "failed";
+    reason: string;
+    output?: string;
+} | {
+    kind: "missing";
+    reason: string;
+} | {
+    kind: "unauthenticated";
+    reason: string;
+};
+
+/**
+ * `geenius-release a11y-report` — aggregate axe-core results that the package's
+ * a11y test run produced. Replaces 28 copies of `a11y-report.mjs`.
+ *
+ * Looks for a single JSON file at `.eval/a11y/results.json` (or the path
+ * passed via `--results`) containing the axe output. Reports the count of
+ * violations by severity. Fails when any violation at or above
+ * `failThreshold` exists (default: `serious`).
+ */
+
+type A11ySeverity = "minor" | "moderate" | "serious" | "critical";
+interface RunA11yReportOptions {
+    cwd?: string;
+    /** Path to the axe results JSON. Default: `.eval/a11y/results.json`. */
+    resultsPath?: string;
+    /** Lowest severity that fails the report. Default: `serious`. */
+    failThreshold?: A11ySeverity;
+    /** Whether absent results is `failed` or `skipped`. */
+    optional?: boolean;
+    quiet?: boolean;
+}
+declare function runA11yReport(opts?: RunA11yReportOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release attw` — run @arethetypeswrong/cli against the packed tarball.
+ * Replaces ~13 scripts across 3 filename variations (`run-attw.mjs`,
+ * `attw-packed.mjs`, `attw-check.mjs`).
+ */
+
+interface RunAttwOptions {
+    cwd?: string;
+    /** Allow attw to be missing without failing. */
+    optional?: boolean;
+    /** Comma list of attw `--ignore-rules` (e.g. `cjs-resolves-to-esm`). */
+    ignoreRules?: readonly string[];
+    /** Reuse a stable directory (relative to packageRoot) for the tarball
+     *  instead of `mkdtempSync(os.tmpdir())`. Useful when concurrent pnpm
+     *  installs in the global cache thrash mkdtemp creations. Default:
+     *  undefined (use os.tmpdir). Common value: `.eval/attw-pack`. */
+    safePackDir?: string;
+    quiet?: boolean;
+}
+declare function runAttw(opts?: RunAttwOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release bundle-budgets` — variants.json-native gzip bundle budgets.
+ *
+ * Replaces `scripts/check-bundle-budgets.mjs` (currently 1 copy in perf, but
+ * 8 packages declare `bundleBudget` in their variants.json: perf, agent,
+ * ai-magic, devtools, errors, onboarding, ui, tools-legacy — so the pattern
+ * is genuinely shared).
+ *
+ * For every implemented variant declaring `bundleBudget: "<n><unit>"`:
+ *   1. Gzip-sum every declared runtime asset (default: index.js + index.css)
+ *      in <packageDir>/dist.
+ *   2. Compare against the parsed budget (b / kb / mb units).
+ *   3. Fail with a per-variant overshoot list on any violation.
+ *
+ * Distinct from `size-check` (which uses the external `size-limit` tool with
+ * its own config) and from `size-limit-config` (which generates a size-limit
+ * config from variants.json). This command is the lightweight, zero-extra-
+ * dependency path that just reads the manifest and the dist tree.
+ */
+interface RunBundleBudgetsOptions {
+    cwd?: string;
+    /** Runtime asset basenames to gzip-sum per variant (default: index.js, index.css). */
+    assets?: string[];
+    /** Only include variants flagged `implemented: true` (default: true). */
+    implementedOnly?: boolean;
+    /** Skip silently when no variant declares a budget. */
+    optional?: boolean;
+}
+interface BundleBudgetsResult {
+    status: "passed" | "failed" | "skipped";
+    exitCode: number;
+    rows: BudgetRow[];
+    failures: string[];
+}
+interface BudgetRow {
+    name: string;
+    packageDir: string;
+    budgetBytes: number;
+    gzipBytes: number;
+    uncompressedBytes: number;
+    assets: string[];
+}
+declare function runBundleBudgets(opts?: RunBundleBudgetsOptions): Promise<BundleBudgetsResult>;
+
+/**
+ * `geenius-release convex-build` — build a Convex sub-package.
+ *
+ * Replaces the per-package `build: "node ../../scripts/geenius-convex-codegen.mjs --src src && tsup"`
+ * pattern (repeated across the 16 Convex-bearing packages).
+ *
+ * Equivalent to:
+ *   geenius-release convex-codegen --src <src>   # default: src/
+ *   tsup
+ *
+ * Flags:
+ *   --src <dir>     Convex source dir (default: src)
+ *   --no-codegen    Skip codegen, just run tsup
+ *   --no-build      Run codegen only
+ *   --clean         Clean _generated/ instead of building
+ */
+interface RunConvexBuildOptions {
+    cwd?: string;
+    src?: string;
+    noCodegen?: boolean;
+    noBuild?: boolean;
+    clean?: boolean;
+    /** Builder to invoke (default: "tsup"). */
+    builder?: "tsup" | "tsc";
+    /** Extra args forwarded to the builder. */
+    passthrough?: string[];
+}
+interface ConvexBuildResult {
+    status: "passed" | "failed";
+    exitCode: number;
+    steps: {
+        name: string;
+        exitCode: number;
+    }[];
+}
+declare function runConvexBuild(opts?: RunConvexBuildOptions): Promise<ConvexBuildResult>;
+
+/**
+ * `geenius-release convex-codegen` — generate `_generated/` shims for Convex
+ * variants.
+ *
+ * Promotes the standalone `geenius-convex-codegen` script (vendored in
+ * geenius-payments and shipped as a bin from geenius-db's convex subpackage)
+ * into a first-class toolkit command. All Convex-bearing packages can drop
+ * their per-package copy and call this instead.
+ *
+ * Behaviour:
+ *   - Discovers the convex source dir by trying (in order):
+ *       opts.src → packages/convex/src → src → cwd
+ *   - Generates: server.js, server.d.ts, dataModel.d.ts, api.js, api.d.ts
+ *   - `--check` mode: verify files are up to date; exit 1 if not.
+ *   - `--clean` mode: delete `_generated/` and exit.
+ */
+interface RunConvexCodegenOptions {
+    cwd?: string;
+    /** Override source directory. */
+    src?: string;
+    /** Check-only — exit 1 if any file would be written/changed. */
+    check?: boolean;
+    /** Delete the _generated/ directory. */
+    clean?: boolean;
+}
+interface ConvexCodegenResult {
+    status: "passed" | "failed" | "skipped";
+    exitCode: number;
+    srcDir: string;
+    files: {
+        name: string;
+        status: "new" | "changed" | "unchanged";
+    }[];
+    modules: string[];
+    warnings: string[];
+}
+declare function runConvexCodegen(opts?: RunConvexCodegenOptions): Promise<ConvexCodegenResult>;
+
+/**
+ * `geenius-release coverage` — canonical vitest --coverage runner.
+ *
+ * Collapses run-coverage.mjs (5) and the various ad-hoc vitest invocations.
+ *
+ * Behaviour:
+ *   1. Clean root + per-variant coverage/ directories.
+ *   2. Run `vitest run --coverage` at the root, excluding tests from any
+ *      variant packages flagged as `separateCoverage: true` (or matching
+ *      `--separate-coverage <framework>`).
+ *   3. For each separate-coverage package, run vitest inside that package
+ *      directory so its own coverage report is emitted.
+ *
+ * Emits the same JSON shape downstream `coverage-report` expects.
+ */
+interface RunCoverageOptions {
+    cwd?: string;
+    /** Run separate vitest passes for variants whose framework matches. */
+    separateFrameworks?: string[];
+    /** Explicit list of packageDirs to run separately (overrides framework match). */
+    separatePackageDirs?: string[];
+    /** Skip the cleanup phase. */
+    noClean?: boolean;
+    /** Strict mode flag forwarded to tests via GEENIUS_COVERAGE_STRICT. */
+    strict?: boolean;
+    /** Extra args appended to every vitest call. */
+    passthrough?: string[];
+}
+interface CoverageResult {
+    status: "passed" | "failed" | "skipped";
+    exitCode: number;
+    passes: {
+        label: string;
+        cwd: string;
+        exitCode: number;
+    }[];
+}
+declare function runCoverage(opts?: RunCoverageOptions): Promise<CoverageResult>;
+
+/**
+ * `geenius-release coverage-report` — aggregate the coverage summary that
+ * vitest (or any tool writing coverage-summary.json / coverage-final.json)
+ * produced. Replaces 36 copies of `coverage-report.mjs`.
+ *
+ * Reads `coverage/coverage-summary.json` (default v8/istanbul output path).
+ * Optional thresholds: minimum % lines / branches / functions / statements.
+ */
+
+interface CoverageThresholds {
+    lines?: number;
+    branches?: number;
+    functions?: number;
+    statements?: number;
+}
+interface RunCoverageReportOptions {
+    cwd?: string;
+    /** Path to coverage-summary.json. Default: `coverage/coverage-summary.json`. */
+    summaryPath?: string;
+    /** Minimum percentages. Default: pull from `coverage-thresholds.json` if present
+     *  (legacy flat shape). When `thresholdFile` is set, the per-subpackage shape
+     *  there takes precedence. */
+    thresholds?: CoverageThresholds;
+    /** Path to a richer per-subpackage threshold JSON (shape:
+     *  `{ subpackages: { <name>: { thresholds: { lines, statements, branches, functions }, required?, kind? } } }`).
+     *  When set, the toolkit emits per-subpackage results in addition to the
+     *  totals row. Subpackages keyed by name look for `coverage/coverage-summary.json`
+     *  files at `packages/<name>/coverage/`, `<name>/coverage/`, or matching prefix
+     *  inside the root summary. */
+    thresholdFile?: string;
+    /** Write a Markdown report to this path. */
+    output?: string;
+    /** Write a structured JSON report to this path. */
+    json?: string;
+    /** Treat any subpackage below threshold as a failure (default: true when
+     *  `thresholdFile` is set, false otherwise — matches legacy --fail-on-gaps
+     *  flag in per-package scripts). */
+    failOnGaps?: boolean;
+    /** Whether absent coverage is `failed` (default) or `skipped`. */
+    optional?: boolean;
+    quiet?: boolean;
+}
+declare function runCoverageReport(opts?: RunCoverageReportOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release db-migrations` — run migration tests across db-provider
+ * variants.
+ *
+ * Collapses db-migrations-check.mjs (4 packages). For every variant with
+ * kind `db-provider` and `tests.migrations: true`, runs:
+ *   pnpm --filter ./<packageDir> test -- -t migration
+ *
+ * Fails fast on the first non-zero status by default.
+ */
+interface RunDbMigrationsOptions {
+    cwd?: string;
+    /** Only run providers whose name matches one of these. */
+    only?: string[];
+    /** Don't bail on first failure. */
+    continueOnFailure?: boolean;
+    /** Test-name pattern passed to vitest (default: "migration"). */
+    pattern?: string;
+}
+interface DbMigrationsResult {
+    status: "passed" | "failed" | "skipped";
+    exitCode: number;
+    ran: {
+        name: string;
+        packageDir: string;
+        exitCode: number;
+    }[];
+}
+declare function runDbMigrations(opts?: RunDbMigrationsOptions): Promise<DbMigrationsResult>;
+
+/**
+ * `geenius-release diff-coverage` — changed-line coverage diff against a base
+ * git ref. Replaces 22 copies of `diff-coverage.mjs`.
+ *
+ * Computes which source lines were added or modified between `--base` (default
+ * `origin/main`) and `HEAD`, then walks the latest `coverage-final.json` to
+ * check whether every such line was hit. Fails if the changed-line coverage
+ * percentage falls below `--min`.
+ */
+
+interface RunDiffCoverageOptions {
+    cwd?: string;
+    /** Git ref to diff against. Default: `origin/main`. */
+    base?: string;
+    /** Path to vitest's coverage-final.json. Default: `coverage/coverage-final.json`. */
+    coveragePath?: string;
+    /** Minimum changed-line coverage % required to pass. Default: 80. */
+    min?: number;
+    /** When `process.env.CI === "true"`, use this threshold instead of `min`. */
+    minCi?: number;
+    /** When `process.env.CI` is unset/falsy, use this threshold. Overrides `min`
+     *  for local runs. Common pattern: 0 locally + strict in CI. */
+    minLocal?: number;
+    /** Skip if coverage hasn't been run. Default: false. */
+    optional?: boolean;
+    quiet?: boolean;
+}
+declare function runDiffCoverage(opts?: RunDiffCoverageOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release e2e` — canonical Playwright runner.
+ *
+ * Collapses e2e-runner.mjs (5) + playwright-projects.mjs (2).
+ *
+ * Responsibilities:
+ *   1. Reserve ephemeral ports per UI harness variant and inject them as
+ *      `<PACKAGE>_E2E_<VARIANT>_PORT` env vars (mirroring the existing
+ *      per-package e2e-runner pattern).
+ *   2. Derive `--project=<variantName>-<browser>` filters from variants.json
+ *      when callers pass `--projects` or `--all-browsers`.
+ *   3. Forward all other args to `pnpm exec playwright test`.
+ */
+interface RunE2EOptions {
+    cwd?: string;
+    /** Emit `--project=<variant>-<browser>` projects for every e2e variant. */
+    projects?: boolean;
+    /** When true with projects, include every browser declared on each variant. */
+    allBrowsers?: boolean;
+    /** Specific browser to use (default: chromium) when --projects. */
+    browser?: string;
+    /** Env prefix for port vars. Default: derived from package.json name. */
+    envPrefix?: string;
+    /** Extra args forwarded to `playwright test`. */
+    passthrough?: string[];
+    /** Print resolved env + command and exit. */
+    print?: boolean;
+}
+interface E2EResult {
+    status: "passed" | "failed" | "skipped";
+    exitCode: number;
+    ports: Record<string, string>;
+    projects: string[];
+}
+declare function runE2E(opts?: RunE2EOptions): Promise<E2EResult>;
+
+/**
+ * Configuration: schema, defaults, loader.
+ *
+ * The single Zod schema below is the source of truth for `release-toolkit.config.json`.
+ * Defaults are applied per-field so that an absent config file is equivalent to
+ * an empty `{}` — every consumer gets sensible behaviour out of the box.
+ */
+
+declare const ConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    variants: z.ZodDefault<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    supplyChain: z.ZodDefault<z.ZodObject<{
+        scanners: z.ZodDefault<z.ZodObject<{
+            pnpmAudit: z.ZodDefault<z.ZodObject<{
+                required: z.ZodDefault<z.ZodBoolean>;
+                auditLevel: z.ZodDefault<z.ZodEnum<{
+                    low: "low";
+                    moderate: "moderate";
+                    high: "high";
+                    critical: "critical";
+                }>>;
+                scope: z.ZodDefault<z.ZodEnum<{
+                    prod: "prod";
+                    all: "all";
+                }>>;
+                skipIfMissing: z.ZodOptional<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+                skipIfUnauthenticated: z.ZodOptional<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+            }, z.core.$strict>>;
+            osvScanner: z.ZodDefault<z.ZodObject<{
+                required: z.ZodDefault<z.ZodBoolean>;
+                skipIfMissing: z.ZodDefault<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+                skipIfUnauthenticated: z.ZodOptional<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+            }, z.core.$strict>>;
+            socket: z.ZodDefault<z.ZodObject<{
+                required: z.ZodDefault<z.ZodBoolean>;
+                skipIfMissing: z.ZodDefault<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+                skipIfUnauthenticated: z.ZodDefault<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+            }, z.core.$strict>>;
+            license: z.ZodDefault<z.ZodObject<{
+                required: z.ZodDefault<z.ZodBoolean>;
+                skipIfMissing: z.ZodOptional<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+                skipIfUnauthenticated: z.ZodOptional<z.ZodEnum<{
+                    silent: "silent";
+                    info: "info";
+                    warn: "warn";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    license: z.ZodDefault<z.ZodObject<{
+        scope: z.ZodDefault<z.ZodEnum<{
+            prod: "prod";
+            all: "all";
+        }>>;
+        forbidden: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        unknownPolicy: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            pass: "pass";
+            fail: "fail";
+        }>>;
+    }, z.core.$strict>>;
+    sbom: z.ZodDefault<z.ZodObject<{
+        format: z.ZodDefault<z.ZodEnum<{
+            "cyclonedx-json": "cyclonedx-json";
+            "spdx-json": "spdx-json";
+        }>>;
+        out: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    smokePacked: z.ZodDefault<z.ZodObject<{
+        subpathsFromExports: z.ZodDefault<z.ZodBoolean>;
+        extraSubpaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        checkExportsOnDisk: z.ZodDefault<z.ZodBoolean>;
+        checkTarballPurity: z.ZodDefault<z.ZodString>;
+        checkStylesheets: z.ZodDefault<z.ZodBoolean>;
+        browserConditions: z.ZodDefault<z.ZodBoolean>;
+        domStubs: z.ZodDefault<z.ZodBoolean>;
+        injectDeps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    publint: z.ZodDefault<z.ZodObject<{
+        allowSourceTimeLinks: z.ZodDefault<z.ZodBoolean>;
+        sourceLinkScope: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    rewriteImports: z.ZodDefault<z.ZodObject<{
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            match: z.ZodString;
+            replaceWith: z.ZodString;
+            literal: z.ZodOptional<z.ZodBoolean>;
+            quoted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        frameworkDetect: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deriveFromExports: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    gauntlet: z.ZodDefault<z.ZodObject<{
+        steps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        continueOnFailure: z.ZodDefault<z.ZodBoolean>;
+        siblingDistFreshness: z.ZodDefault<z.ZodEnum<{
+            check: "check";
+            off: "off";
+            build: "build";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type Config = z.infer<typeof ConfigSchema>;
+interface LoadedConfig {
+    config: Config;
+    /** Absolute path to the config file that was read, or `null` if defaults were used. */
+    filePath: string | null;
+}
+/**
+ * Read `release-toolkit.config.json` if present; merge with defaults via Zod's
+ * `default()` mechanism. Missing config file is not an error.
+ */
+declare function loadConfig(packageRoot: string): LoadedConfig;
+
+/**
+ * `geenius-release gauntlet` — compose the configured step sequence.
+ *
+ * External steps (`lint`, `type-check`, `test:unit`, anything else) shell out
+ * to `pnpm <step>` so existing per-package scripts continue to work.
+ *
+ * Internal steps (`supply-chain`, `license`, `sbom`, `smoke-packed`) call the
+ * toolkit's `runX` functions directly — no `pnpm` overhead, full structured
+ * report aggregation.
+ */
+
+interface RunGauntletOptions {
+    cwd?: string;
+    config?: Config;
+    /** Override the step list. */
+    steps?: readonly string[];
+    /** Continue running remaining steps after a failure. */
+    continueOnFailure?: boolean;
+    quiet?: boolean;
+}
+declare function runGauntlet(opts?: RunGauntletOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release license` — forbidden-license scan over installed dependencies.
+ * Replaces the 36 copies of `license-check.mjs` across the ecosystem.
+ */
+
+interface RunLicenseOptions {
+    /** Defaults to `process.cwd()` if omitted. */
+    cwd?: string;
+    /** Override loaded config. */
+    config?: Config["license"];
+    /** Override the dependency scope. */
+    scope?: "prod" | "all";
+    /** Suppress console output (for gauntlet composition). */
+    quiet?: boolean;
+}
+declare function runLicense(opts?: RunLicenseOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release lint` — single canonical lint entry point.
+ *
+ * Collapses run-lint.mjs (9 pkgs) + lint-apps.mjs (4) + lint-scope.mjs (3) +
+ * biome-scope.mjs (5) + lint-pub.mjs (7) etc.
+ *
+ * Modes:
+ *   default (root): root files + every in-scope variant's packageDir, plus
+ *                   discovered apps/ directories if any exist.
+ *   --scope package: root files + variant packageDirs only.
+ *   --scope apps:    apps/* dirs derived from ui+storybook+e2e variants only.
+ *   --scope all:     everything (default behaviour, kept explicit).
+ *   --apps:          shortcut for --scope apps.
+ *
+ * Always invokes `biome check` (or `biome lint`/`biome format` via --command).
+ * Extra args after `--` (collected into passthrough) are forwarded.
+ */
+type LintScope = "package" | "apps" | "all";
+interface RunLintOptions {
+    cwd?: string;
+    scope?: LintScope;
+    /** Biome subcommand (default "check"). */
+    command?: "check" | "lint" | "format" | "ci";
+    /** Apply autofixes (`--write`). */
+    fix?: boolean;
+    /** Extra args forwarded to biome after the path list. */
+    passthrough?: string[];
+    /** Print the resolved command and exit. */
+    print?: boolean;
+    /** Limit variant collection to `implemented: true` variants. */
+    implementedOnly?: boolean;
+}
+interface LintResult {
+    status: "passed" | "failed" | "skipped";
+    command: string;
+    paths: string[];
+    exitCode: number;
+}
+declare function runLint(opts?: RunLintOptions): Promise<LintResult>;
+
+/**
+ * `geenius-release manifest-contract` — verify that every `package.json:exports`
+ * target file exists on disk, that `files` patterns cover every export target,
+ * and that `bin` entries exist + are executable.
+ *
+ * Absorbs the inline `test -f dist/index.js && test -f dist/index.d.ts` checks
+ * scattered across packages (e.g. tools/devtools' `test:dist-contract`).
+ */
+
+interface RunManifestContractOptions {
+    cwd?: string;
+    quiet?: boolean;
+}
+declare function runManifestContract(opts?: RunManifestContractOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release mutation-report` — Stryker driver. Replaces 36 copies of
+ * `mutation-report.mjs`. Optional by default: if Stryker isn't installed or
+ * configured, the command skips cleanly.
+ */
+
+interface RunMutationReportOptions {
+    cwd?: string;
+    /** When true (default), missing Stryker config → skipped (not failed). */
+    optional?: boolean;
+    /** Minimum mutation score required to pass (0-100). */
+    minScore?: number;
+    /** Just verify a Stryker config exists; do not invoke Stryker. */
+    checkConfigOnly?: boolean;
+    /** Fall back to `pnpm dlx --package <spec> -c "stryker run"` when the
+     *  package's local @stryker-mutator/core isn't installed. Common form:
+     *  `@stryker-mutator/core@9.5.0`. */
+    dlxSpec?: string;
+    /** Write a Markdown summary to this path. */
+    markdownOut?: string;
+    /** Write a structured JSON summary to this path. */
+    jsonOut?: string;
+    /** Where Stryker writes its raw report. Used to compute a fallback score
+     *  if the run didn't print "Final mutation testing score" on stdout.
+     *  Default: `.eval/mutation/mutation.json`. */
+    reportJsonPath?: string;
+    quiet?: boolean;
+}
+declare function runMutationReport(opts?: RunMutationReportOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release pack-contract` — run `pnpm pack --json`, capture the
+ * resulting manifest into a temp directory, expose the path via
+ * `PACK_CONTRACT_JSON`, then run a consumer-supplied vitest config that
+ * asserts on the packed contents (files included, exports targets, README
+ * present, etc.).
+ *
+ * Generic harness — the actual contract tests are package-specific. The
+ * caller passes `--test-config <vitest.pack-contract.config.ts>`.
+ *
+ * Replaces local `scripts/pack-contract.mjs` shims.
+ */
+interface RunPackContractOptions {
+    cwd?: string;
+    /** Vitest config that runs the contract assertions. Required. */
+    testConfig: string;
+    /** Pass an existing pack JSON instead of running `pnpm pack` first. */
+    packJson?: string;
+    /** Tests to run (passed to vitest as positional args). */
+    testFiles?: readonly string[];
+}
+interface PackContractResult {
+    status: number;
+    packJsonPath: string;
+}
+declare function runPackContract(opts: RunPackContractOptions): PackContractResult;
+
+/**
+ * `geenius-release patch-dts` — post-build patcher for dist outputs.
+ *
+ * Collapses patch-dts-imports.mjs (4) + patch-solid-web-import.mjs (2) +
+ * the `--fix-solid-jsx-runtime` flag previously embedded in sanitize-dist.
+ *
+ * Operations (composable; pass any combination):
+ *   --rewrite <from=to>  Plain string replaceAll in .d.ts files (repeatable).
+ *   --solid              Rewrite solid-js/web → solid-js/web/dist/web.js and
+ *                        gate delegateEvents() on a window check, in .js files.
+ *   --solid-jsx          Rewrite solid-js/jsx-runtime → solid-js/h/jsx-runtime
+ *                        in .js files.
+ *   --files <list>       Operate on an explicit file list instead of walking
+ *                        a directory.
+ *
+ * Default directory is `dist/`. Walks recursively; only touches `.d.ts` for
+ * --rewrite, only `.js`/`.mjs`/`.cjs` for the --solid* flags.
+ */
+interface DtsRewriteRule {
+    from: string;
+    to: string;
+}
+interface RunPatchDtsOptions {
+    cwd?: string;
+    /** Directory to walk (default: "dist"). Ignored when `files` is provided. */
+    dir?: string;
+    /** Explicit file list (absolute or relative to cwd). */
+    files?: string[];
+    /** Plain string replacements applied to .d.ts files. */
+    rewrites?: DtsRewriteRule[];
+    /** Apply Solid web import + delegateEvents patch to .js files. */
+    solid?: boolean;
+    /** Rewrite solid-js/jsx-runtime → solid-js/h/jsx-runtime in .js files. */
+    solidJsx?: boolean;
+}
+interface PatchDtsResult {
+    status: "passed" | "skipped";
+    filesChanged: number;
+    filesScanned: number;
+}
+declare function runPatchDts(opts?: RunPatchDtsOptions): Promise<PatchDtsResult>;
+
+/**
+ * `geenius-release perf-smoke` — perf-budget harness wrapper.
+ * Absorbs 7 copies of `perf-smoke.mjs`.
+ *
+ * Reads `.eval/perf/results.json` produced by the package's perf harness
+ * (Storybook perf stories, vitest perf suite, custom Playwright harness — the
+ * toolkit doesn't care how the file got there) and enforces budgets from
+ * `release-toolkit.config.json:perf` or `perf-budgets.json` at the package
+ * root.
+ */
+
+interface PerfBudget {
+    /** Symbolic metric name; matches the result file's `metric` field. */
+    metric: string;
+    /** Numerical maximum (e.g. 250 for "max 250 ms"). */
+    max: number;
+    /** Optional unit label for the report, e.g. "ms", "ops/s". */
+    unit?: string;
+    /** When set, this metric is a minimum (e.g. ops/sec) rather than a maximum. */
+    isMinimum?: boolean;
+}
+interface RunPerfSmokeOptions {
+    cwd?: string;
+    /** Path to the perf results JSON. Default: `.eval/perf/results.json`. */
+    resultsPath?: string;
+    /** Budget list. If absent, the toolkit reads `perf-budgets.json` at the
+     *  package root, then falls back to "no enforced budgets". */
+    budgets?: readonly PerfBudget[];
+    /** Whether absent results is `failed` or `skipped`. */
+    optional?: boolean;
+    quiet?: boolean;
+}
+declare function runPerfSmoke(opts?: RunPerfSmokeOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release pnpm-filters` — run a per-package script across the variant
+ * matrix.
+ *
+ * **The name is historical.** Earlier versions shelled out to
+ * `pnpm -r --filter ... <task>`. This version skips pnpm entirely and spawns
+ * each variant's `scripts.<task>` directly via `/bin/sh -c <cmd>`, which:
+ *
+ *   - eliminates the ~100-300ms pnpm bootstrap per package (critical when
+ *     fanning out 16 variants × 20 parallel agents);
+ *   - keeps `package.json` script semantics intact (shell pipes, &&, env
+ *     substitution all work because we hand the raw command to sh);
+ *   - augments PATH with each variant's `node_modules/.bin` and every
+ *     ancestor `node_modules/.bin` so locally-installed tools resolve the
+ *     same way pnpm exec would have resolved them.
+ *
+ * Execution modes (CLI surface is unchanged from the pnpm-era):
+ *   - **parallel** (default): launch all variants concurrently, optionally
+ *     capped by `--workspace-concurrency=N`. Stdout/stderr prefixed per pkg.
+ *   - **sequential**: one variant at a time, optional shared-first + kind
+ *     tiering + heartbeat.
+ *   - **shared-then-parallel**: shared first sequentially, then everything
+ *     else in parallel.
+ *
+ * `--prebuild <dir>` runs `<dir>`'s `build` script (always `build`, not the
+ * requested task) before the main fan-out, and removes `<dir>` from the main
+ * fan-out when task is also build.
+ */
+interface RunPnpmFiltersOptions {
+    cwd?: string;
+    task: string;
+    includeMissing?: boolean;
+    /** Limit fan-out to variants flagged `implemented: true`. */
+    implementedOnly?: boolean;
+    /** Skip variants whose package.json has no entry for `task` (default: true). */
+    ifPresent?: boolean;
+    /** Force unbounded parallelism (alias for `workspaceConcurrency: undefined`). */
+    parallel?: boolean;
+    /** Cap concurrent in-flight spawns in parallel mode (string for CLI parity). */
+    workspaceConcurrency?: string;
+    /** Print the resolved per-variant invocations and exit (no spawns). */
+    print?: boolean;
+    kinds?: readonly string[];
+    /** Forward extra arguments after the script body. Joined with space and
+     *  appended; the package script receives them via `$@`-like shell expansion. */
+    passthrough?: readonly string[];
+    /** Filter variants to those declaring `variant.tests.<key> === true`. */
+    requires?: readonly string[];
+    /** Sequential mode (one variant at a time). Overrides --parallel. */
+    sequential?: boolean;
+    /** Execution mode (takes precedence over `sequential`/`parallel`). */
+    mode?: "parallel" | "sequential" | "shared-then-parallel";
+    /** When sequential or shared-then-parallel, run this packageDir first. */
+    sharedFirst?: string;
+    /** Heartbeat interval (ms) when sequential, so CI doesn't kill a quiet job. */
+    heartbeatMs?: number;
+    /** Order variant kinds into tiers (sequential mode only). */
+    sequentialKindOrder?: readonly (readonly string[])[];
+    /** Build `<dir>` (always `build`, not the requested task) before main fan-out.
+     *  When `task === "build"`, the main fan-out excludes `<dir>`. */
+    prebuild?: string;
+}
+interface PnpmFiltersResult {
+    status: number;
+    /** Per-variant resolved invocations. Each entry: `[label, command]`. */
+    invocations: {
+        label: string;
+        cwd: string;
+        command: string;
+    }[];
+}
+declare function runPnpmFilters(opts: RunPnpmFiltersOptions): Promise<PnpmFiltersResult>;
+
+/**
+ * `geenius-release publint` — run publint against the package's packed tarball.
+ * Replaces ~17 scripts across 4 filename variations in the legacy tree
+ * (`publint-package.mjs`, `publint-packed.mjs`, `publint-check.mjs`, `publint.mjs`).
+ *
+ * publint is resolved from the package's local `node_modules/.bin` and spawned
+ * directly (skipping `pnpm exec`'s ~300ms bootstrap). If the binary isn't
+ * reachable, we report `missing` and let the config decide whether that's an
+ * optional skip.
+ */
+
+interface RunPublintOptions {
+    cwd?: string;
+    /** Allow publint to be missing without failing. Default: false (publint should always pass). */
+    optional?: boolean;
+    /** Tolerance config for source-time `link:` deps. */
+    config?: Config["publint"];
+    quiet?: boolean;
+}
+declare function runPublint(opts?: RunPublintOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release rewrite-imports` — post-build codemod that rewrites
+ * private subpath imports in a variant's built `dist/` so packed tarballs
+ * don't need to advertise internal `./shared` (or similar) exports.
+ *
+ * Replaces ~36 copies of `rewrite-private-imports.mjs`. Rules are
+ * config-driven and token-aware (`${packageName}`, `${framework}`,
+ * `${variant}`) so the same toolkit serves every Geenius package that
+ * keeps shared code under `packages/shared/` and per-framework variants
+ * under `packages/<variant>/`.
+ */
+
+interface RewriteRule {
+    /** Literal specifier to find. Token-expanded before matching. */
+    match: string;
+    /** Replacement. Token-expanded. When `literal` is false (default), treated
+     *  as a path relative to packageRoot and converted into a module specifier
+     *  relative to the variant's `dist/`. When `literal` is true, used as-is —
+     *  useful for JSDoc / comment cleanup ("internal-name → public-name"). */
+    replaceWith: string;
+    /** If true, `replaceWith` is used as literal text (no path resolution). */
+    literal?: boolean;
+    /** If true, only quoted occurrences are matched (both `"<match>"` and
+     *  `'<match>'`). Use this for import-specifier rewrites that must not
+     *  touch identical strings in JSDoc / comments. */
+    quoted?: boolean;
+}
+interface RunRewriteImportsOptions {
+    cwd?: string;
+    /** Variant directory, relative to packageRoot (e.g. `packages/react`). */
+    variantDir: string;
+    /** Override config rules. */
+    rules?: readonly RewriteRule[];
+    /** Override framework detection. Map of framework name → variant-basename regex. */
+    frameworkDetect?: Record<string, string>;
+    /** Explicit framework name (skips detection). */
+    framework?: string;
+    /** File extensions to rewrite. Default: `[".js", ".d.ts"]`. */
+    extensions?: readonly string[];
+    /** If true, generate additional literal rules from the root manifest's
+     *  `exports` map: for every `packages/<name>` referenced from an exports
+     *  target, map the private workspace name (read from `packages/<name>/
+     *  package.json`) to the public root-subpath specifier. Useful when
+     *  consumers must not see internal workspace package names in published
+     *  declaration files. Added after any explicitly configured rules. */
+    deriveFromExports?: boolean;
+    /** Built-in preset names to layer on. Currently: `solid-web` (rewrite
+     *  `solid-js/web` to `solid-js/web/dist/web.js` so Node ESM consumers can
+     *  resolve it without subpath redirects). Presets append to the rule list. */
+    presets?: readonly "solid-web"[];
+    config?: Config["rewriteImports"];
+    quiet?: boolean;
+}
+declare function runRewriteImports(opts: RunRewriteImportsOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release run-scripts <s1> <s2> …` — run multiple top-level
+ * `package.json` scripts sequentially in the package root, with PATH
+ * augmented to include `node_modules/.bin`. Stops on the first failure
+ * and propagates the failing exit code.
+ *
+ * Replaces local `_run-root-scripts.mjs` shims that exist in adapters and
+ * similar packages, where a single command needs to chain build → tests
+ * → exports → dist-contract in the same shell context.
+ */
+interface RunScriptsOptions {
+    cwd?: string;
+    scripts: readonly string[];
+    /** Stop on first failure (default: true). */
+    stopOnFailure?: boolean;
+    /** Don't actually spawn; print the command list. */
+    print?: boolean;
+}
+interface RunScriptsResult {
+    status: number;
+    /** Names of scripts that ran (including the failing one if applicable). */
+    ran: string[];
+    /** Name of the failing script, if any. */
+    failedAt?: string;
+}
+declare function runScripts(opts: RunScriptsOptions): Promise<RunScriptsResult>;
+
+/**
+ * `geenius-release sanitize-dist` — strip leaky tsup artifacts from built JS.
+ *
+ * Collapses sanitize-dist-comments.mjs (3) + sanitize-dist.mjs (2).
+ *
+ * Operations (composable):
+ *   --comments (default on)  Strip `// src/...` / `// .../src/...` comments tsup leaves at
+ *                            the top of bundled chunks (they expose workspace
+ *                            source paths).
+ *   --maps                   Strip `//# sourceMappingURL=` comments.
+ *   --fix-solid-jsx-runtime  Rewrite solid-js/jsx-runtime → solid-js/h/jsx-runtime.
+ *
+ * Walks `dist/` (override with `dir`) and only touches `.js`, `.cjs`, `.mjs`.
+ */
+interface RunSanitizeDistOptions {
+    cwd?: string;
+    dir?: string;
+    /** Default true. Strip `// .../src/...` source-path comments. */
+    comments?: boolean;
+    /** Default false. Strip sourceMappingURL comments. */
+    maps?: boolean;
+    /** Default false. Rewrite solid-js/jsx-runtime to runtime/h variant. */
+    fixSolidJsxRuntime?: boolean;
+}
+interface SanitizeDistResult {
+    status: "passed" | "skipped";
+    filesScanned: number;
+    filesChanged: number;
+}
+declare function runSanitizeDist(opts?: RunSanitizeDistOptions): Promise<SanitizeDistResult>;
+
+/**
+ * `geenius-release sbom` — emit a CycloneDX 1.5 JSON SBOM from pnpm-lock.yaml.
+ * Replaces the 36 copies of `sbom.mjs`.
+ *
+ * Implementation strategy: parse the lockfile YAML by line (no dependency on a
+ * full YAML parser — pnpm-lock.yaml has a stable, simple shape since v9).
+ * For SPDX format we shell out to `syft` if available; otherwise we report
+ * SPDX as `missing` per the optional-scanner policy.
+ */
+
+interface RunSbomOptions {
+    cwd?: string;
+    config?: Config["sbom"];
+    /** Override output path. */
+    out?: string;
+    /** Override format. */
+    format?: "cyclonedx-json" | "spdx-json";
+    quiet?: boolean;
+}
+declare function runSbom(opts?: RunSbomOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release size-check` — size-limit driver. Replaces 13 copies of
+ * `size-check.mjs`. Reads the package's `size-limit` config (either from
+ * `package.json:size-limit` or `size-limit.config.{js,mjs,ts}`) and runs the
+ * `size-limit` binary; passing means every entry is under its budget.
+ */
+
+interface RunSizeCheckOptions {
+    cwd?: string;
+    /** When the size-limit binary or config is absent: `false` → step is `missing`
+     *  and command fails. `true` (default) → step is `skipped` and command passes.
+     *  This mirrors `mutation-report` — size-limit is opt-in tooling, not every
+     *  package adopts it. */
+    optional?: boolean;
+    /** Additional flags to pass to size-limit (e.g. `--why`). */
+    extraArgs?: readonly string[];
+    quiet?: boolean;
+}
+declare function runSizeCheck(opts?: RunSizeCheckOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release size-limit-config` — generate size-limit entries from
+ * `variants.json` and the root manifest's `exports` map.
+ *
+ * For every variant whose `packageDir` is referenced in `root.exports` (i.e.
+ * actually shipped) and that declares `budget.gzip`, emit a size-limit entry:
+ *   { name, path: "<packageDir>/dist/index.js", ignore: [...peerDeps], limit }
+ *
+ * Variants without `budget.gzip` cause an error when they're in the exported
+ * set — this is the same invariant adapters' local `size-limit-config.mjs`
+ * enforces. Replaces ~5 copies across the ecosystem.
+ *
+ * Emits JSON to stdout; consumers pipe it into their `.size-limit.cjs` /
+ * `size-limit.config.mjs` (typically `module.exports = JSON.parse(read(...))`).
+ */
+interface RunSizeLimitConfigOptions {
+    cwd?: string;
+    /** Pretty-print JSON. Default: true. */
+    pretty?: boolean;
+    /** Match variants by exact `packageDir`. Default: derive from root exports. */
+    packageDirs?: readonly string[];
+}
+interface SizeLimitEntry {
+    name: string;
+    path: string;
+    ignore: string[];
+    limit: string;
+}
+declare function runSizeLimitConfig(opts?: RunSizeLimitConfigOptions): {
+    ok: boolean;
+    entries: SizeLimitEntry[];
+    output: string;
+};
+
+/**
+ * `geenius-release smoke-packed` — pack the package, install the tarball into
+ * an ephemeral tmpdir, and dynamic-import every subpath in `package.json:exports`.
+ *
+ * Replaces the 36 copies of `smoke-packed-imports.mjs` (the heaviest legacy
+ * script at ~286 LOC/copy = 10,318 total LOC absorbed).
+ */
+
+interface RunSmokePackedOptions {
+    cwd?: string;
+    config?: Config["smokePacked"];
+    /** Limit to a subset of subpaths. */
+    subpaths?: readonly string[];
+    quiet?: boolean;
+    /** CLI-only overrides (mirror config fields). */
+    checkExportsOnDisk?: boolean;
+    checkTarballPurity?: string;
+    checkStylesheets?: boolean;
+    browserConditions?: boolean;
+    domStubs?: boolean;
+    injectDeps?: readonly string[];
+}
+declare function runSmokePacked(opts?: RunSmokePackedOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release storybook` — build + test-runner orchestration for every
+ * Storybook app declared in `release-toolkit.config.json:storybook.apps`.
+ *
+ * Absorbs ~28 scripts across 5 filename variations (`storybook-runner.mjs`,
+ * `storybook-test-runner.mjs`, `test-storybook-static.mjs`, `storybook-build.mjs`,
+ * `storybook-apps.mjs`).
+ *
+ * Each app is identified by a relative path to its directory; the toolkit
+ * invokes `pnpm --dir <path> <action>` for each. Actions are configurable
+ * (default: build then test:storybook).
+ */
+
+interface RunStorybookOptions {
+    cwd?: string;
+    /** Relative paths to Storybook app directories. If omitted, falls back to
+     *  globbing `apps/storybook-*` at the package root. */
+    apps?: readonly string[];
+    /** Lifecycle action to run per app. Default: `["build", "test:storybook"]`. */
+    actions?: readonly string[];
+    /** Limit to a subset of apps via a substring filter. */
+    filter?: string;
+    /** Soft-skip apps that don't have the requested script. Default: true. */
+    skipIfMissingScript?: boolean;
+    /** Continue with the next app after a failure. */
+    continueOnFailure?: boolean;
+    /** When set, run the toolkit's built-in static smoke (Playwright + http
+     *  server) instead of (or after) shelling out to `pnpm test:storybook`.
+     *  `replace` skips per-app `test:storybook`, `after` runs it then smoke,
+     *  `only` skips `build` too. Default: undefined (legacy behavior). */
+    staticSmoke?: "replace" | "after" | "only";
+    /** Per-app runner. `static-smoke` is the toolkit's built-in Playwright +
+     *  http-server smoke (equivalent to `staticSmoke: "replace"`).
+     *  `test-runner` invokes `@storybook/test-runner` against a served
+     *  built Storybook. `vitest` runs the app's `test:storybook` script
+     *  (which typically points at a Vitest browser-mode config).
+     *  When set, `staticSmoke` is ignored and a single build step runs
+     *  before the chosen runner. */
+    runner?: "static-smoke" | "test-runner" | "vitest";
+    /** Story ids every Storybook must include during static smoke. */
+    requiredStoryIds?: readonly string[];
+    /** Discover apps from variants.json instead of auto-globbing apps/storybook-*.
+     *  Reads variants where `storybook` field is set; respects `published` if
+     *  `fromVariantsScope: "published"` is also set. */
+    fromVariants?: boolean;
+    /** When `fromVariants` is true: `all` (default) includes every variant
+     *  with a `storybook` field; `published` includes only variants with
+     *  `published: true`. */
+    fromVariantsScope?: "all" | "published";
+    /** When set, assert per-app structural shape (required + forbidden files,
+     *  required story titles in the built index.json). Same intent as the
+     *  per-package `scripts/storybook-app-smoke.mjs` shim. */
+    checkShape?: StorybookShapeSpec;
+    quiet?: boolean;
+}
+interface StorybookShapeSpec {
+    /** Paths (relative to the app dir) that must exist. */
+    requiredFiles?: readonly string[];
+    /** Paths (relative to the app dir) that must NOT exist. */
+    forbiddenFiles?: readonly string[];
+    /** Story titles (from index.json `entries[].title`) that must be present. */
+    requiredTitles?: readonly string[];
+}
+declare function runStorybook(opts?: RunStorybookOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release supply-chain` — pnpm audit + osv-scanner + Socket + license,
+ * all configurable required/optional. Replaces the 26 scripts across 7
+ * filename variations in the legacy tree.
+ */
+
+interface RunSupplyChainOptions {
+    cwd?: string;
+    config?: Config["supplyChain"];
+    /** Inherited from the parent License command settings, when invoked from gauntlet. */
+    licenseConfig?: Config["license"];
+    quiet?: boolean;
+}
+declare function runSupplyChain(opts?: RunSupplyChainOptions): Promise<CommandReport>;
+
+/**
+ * `geenius-release type-check` — run a per-variant type-check command,
+ * with a fallback chain. For each variant declaring a `packageDir`:
+ *
+ *   1. If the variant's `package.json` has a `type-check` script, run it.
+ *   2. Otherwise, if it has a `lint` script, run that.
+ *   3. Otherwise, run `tsc --noEmit` from the variant directory.
+ *
+ * PATH is augmented to include both the variant's and root's `node_modules/.bin`
+ * so locally-installed `tsc` resolves correctly. Replaces
+ * `scripts/type-check-packages.mjs` (78 LOC × several packages).
+ */
+interface RunTypeCheckOptions {
+    cwd?: string;
+    /** Continue with the next variant after a failure (default: false). */
+    continueOnFailure?: boolean;
+    /** Include variants marked inScope:false (default: true — type-checking
+     *  out-of-scope code surfaces drift early). */
+    includeOutOfScope?: boolean;
+    /** Run this packageDir first (typical: packages/shared). Default: undefined. */
+    sharedFirst?: string;
+    /** Don't spawn; print the resolved command list. */
+    print?: boolean;
+}
+interface TypeCheckResult {
+    status: number;
+    results: {
+        packageDir: string;
+        command: string;
+        status: number;
+    }[];
+}
+declare function runTypeCheck(opts?: RunTypeCheckOptions): Promise<TypeCheckResult>;
+
+/**
+ * `geenius-release variants` — print the package's variant matrix.
+ *
+ * Subcommands:
+ *   - list (default)      Emit `manifest.variants` as JSON.
+ *   - missing             Emit only required variants whose `packageDir` is absent.
+ *   - published-subpaths  Emit `{variant,subpath}[]` for every published subpath.
+ *   - ui                  Emit only UI-kind variants.
+ *   - db                  Emit only db-provider variants.
+ *   - storybook-apps      Emit `{variant,app,appDir}[]` for every Storybook host.
+ *
+ * Replaces 43 copies of `scripts/_variants.mjs`.
+ */
+interface RunVariantsOptions {
+    cwd?: string;
+    subcommand?: "list" | "missing" | "published-subpaths" | "ui" | "db" | "storybook-apps" | "check";
+    includeOutOfScope?: boolean;
+    /** Pretty-print JSON. Default: true. */
+    pretty?: boolean;
+    /** `check` subcommand: require every entry with `required: true` (or
+     *  unspecified `required`) to have a `packageDir` that exists on disk. */
+    requireAll?: boolean;
+}
+declare function runVariants(opts?: RunVariantsOptions): {
+    ok: boolean;
+    output: string;
+};
+
+/**
+ * `geenius-release vitest-browser-prepare` — vitest browser-mode prepare plugin.
+ *
+ * Collapses vitest-browser-prepare-retry.ts copies across 4 packages.
+ *
+ * Exposed both as a programmatic plugin factory (for `vitest.config.ts`) and as
+ * a CLI command that prints the plugin source for ad-hoc copy/integration. In
+ * practice every package should import the factory, not the CLI; the CLI is
+ * just an inspection escape hatch.
+ */
+interface VitestBrowserPreparePlugin {
+    name: string;
+    transformIndexHtml: {
+        order: "pre";
+        handler: () => {
+            tag: string;
+            injectTo: "head-prepend";
+            children: string;
+        }[];
+    };
+}
+/**
+ * Returns a Vitest browser-mode plugin that proxies `BroadcastChannel`
+ * construction inside the harness iframe so prepare/execute/cleanup messages
+ * emitted before the iframe's listener is attached are still delivered.
+ *
+ * Mirrors the per-package `vitestBrowserPrepareRetry()` factory verbatim so
+ * existing vitest configs can swap `from "./scripts/..."` for `from
+ * "@geenius/release-toolkit/vitest"` without behavioural drift.
+ */
+declare function vitestBrowserPrepareRetry(): VitestBrowserPreparePlugin;
+interface RunVitestBrowserPrepareOptions {
+    /** Print the injected script body to stdout (CLI inspection). */
+    print?: boolean;
+}
+declare function runVitestBrowserPrepare(opts?: RunVitestBrowserPrepareOptions): {
+    status: "passed";
+    source: string;
+};
+
+/**
+ * Centralized environment detection. Every subcommand reads its strictness
+ * dials from here instead of inspecting `process.env` ad-hoc.
+ */
+interface EnvSnapshot {
+    /** True if `CI` is set to a truthy value (`"1"`, `"true"`, `"yes"`). */
+    ci: boolean;
+    /** True when `SOCKET_API_TOKEN` is set; informs the supply-chain scanner. */
+    socketTokenPresent: boolean;
+    /** Coarse strictness override, parsed from `GEENIUS_RELEASE_STRICTNESS`.
+     *  - `"strict"`: every optional/skipIfX policy escalates one level.
+     *  - `"lenient"`: every optional/skipIfX policy de-escalates one level.
+     *  - `undefined`: use configured defaults. */
+    strictness: "strict" | "lenient" | undefined;
+    /** Per-scanner override: `GEENIUS_SUPPLY_CHAIN_<NAME>=off|optional|required`. */
+    supplyChainOverrides: Record<string, "off" | "optional" | "required">;
+}
+/**
+ * Read the environment once. Pure with respect to `env`; callers in tests can
+ * pass a custom object instead of `process.env`.
+ */
+declare function readEnv(env?: NodeJS.ProcessEnv): EnvSnapshot;
+
+/**
+ * Canonical exit codes. Stable across versions — adding a new code is a major
+ * bump. CI integrations rely on these.
+ */
+declare const ExitCode: {
+    readonly OK: 0;
+    readonly REQUIRED_FAILURE: 1;
+    readonly CONFIG_ERROR: 2;
+    readonly ENV_ERROR: 3;
+    readonly INTERNAL_BUG: 4;
+};
+type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * Errors the CLI knows how to translate into a non-zero exit code. Any other
+ * thrown value is an unexpected failure (exit code 4).
+ */
+declare class ReleaseToolkitError extends Error {
+    readonly code: ExitCode;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: ExitCode, hint?: string | undefined);
+}
+
+/**
+ * Canonical path resolution. Every command and lib reads paths through here so
+ * relocating the report directory or the lockfile name is a one-line edit.
+ */
+interface ResolvedPaths {
+    /** Absolute path to the package root (the directory containing package.json). */
+    packageRoot: string;
+    /** Absolute path to the package's pnpm-lock.yaml. */
+    lockfile: string;
+    /** Absolute path to the package's package.json. */
+    packageJson: string;
+    /** Absolute path to the package's node_modules root. */
+    nodeModules: string;
+    /** Absolute path to `.eval/release-toolkit/`. Reports go here. */
+    reportDir: string;
+}
+/**
+ * Resolve filesystem paths relative to a starting cwd. Walks up to find the
+ * first directory containing both `package.json` and `pnpm-lock.yaml`. This
+ * matches how `pnpm` itself locates package roots and lets the CLI be invoked
+ * from a sub-directory.
+ */
+declare function resolvePaths(startCwd?: string): ResolvedPaths;
+
+/**
+ * Rich variants loader — replaces the per-package `_variants.mjs` helper
+ * (43 copies across the workspace).
+ *
+ * Reads `variants.json` at the package root and returns typed variant
+ * objects with derived `packagePath`/`exists`/`subpaths` fields, plus
+ * helper queries (`packageVariants`, `uiVariants`, `dbProviderVariants`,
+ * `storybookApps`, `publishedSubpaths`, …). Honors the
+ * OMEGA_INCLUDE_OUT_OF_SCOPE env flag the legacy scripts depend on.
+ */
+interface RichVariantTestsConfig {
+    unit?: boolean;
+    coverage?: Record<string, number>;
+    [key: string]: unknown;
+}
+interface RichVariant {
+    name: string;
+    kind: string;
+    framework?: string;
+    packageDir?: string;
+    workspace?: string;
+    driver?: string;
+    subpath?: string;
+    aliases?: string[];
+    published?: boolean;
+    storybook?: string;
+    tests?: RichVariantTestsConfig;
+    inScope?: boolean;
+    /** Derived: absolute path to the variant directory. */
+    packagePath: string | null;
+    /** Derived: whether `packagePath` exists on disk. */
+    exists: boolean;
+    /** Derived: subpath + aliases concatenated. */
+    subpaths: string[];
+    [key: string]: unknown;
+}
+interface RichVariantsManifest {
+    package: string;
+    rootDir: string;
+    variants: RichVariant[];
+    coverage?: {
+        reference?: Record<string, number>;
+        library?: Record<string, number>;
+        provider?: Record<string, number>;
+    };
+    [key: string]: unknown;
+}
+interface LoadRichVariantsOptions {
+    /** Override the package root (otherwise the caller's cwd is used). */
+    rootDir?: string;
+    /** Force-include out-of-scope variants regardless of env. */
+    includeOutOfScope?: boolean;
+}
+declare function loadRichVariants(opts?: LoadRichVariantsOptions): RichVariantsManifest;
+interface VariantQueryOptions extends LoadRichVariantsOptions {
+    includeMissing?: boolean;
+    publishedOnly?: boolean;
+    kinds?: readonly string[];
+    /** Only include variants flagged `implemented: true`. */
+    implementedOnly?: boolean;
+}
+declare function packageVariants(opts?: VariantQueryOptions): RichVariant[];
+declare function variantsByKind(kind: string, opts?: LoadRichVariantsOptions): RichVariant[];
+declare function uiVariants(opts?: VariantQueryOptions): RichVariant[];
+declare function dbProviderVariants(opts?: LoadRichVariantsOptions): RichVariant[];
+declare function publishedSubpaths(opts?: LoadRichVariantsOptions): {
+    variant: RichVariant;
+    subpath: string;
+}[];
+declare function storybookVariants(opts?: LoadRichVariantsOptions): RichVariant[];
+declare function storybookApps(opts?: LoadRichVariantsOptions): {
+    variant: RichVariant;
+    app: string;
+    appDir: string;
+}[];
+declare function missingRequiredVariants(opts?: LoadRichVariantsOptions): RichVariant[];
+
+export { type BudgetRow, type BundleBudgetsResult, type CommandReport, type CommandStatus, type Config, ConfigSchema, type ConvexBuildResult, type ConvexCodegenResult, type CoverageResult, type DbMigrationsResult, type DtsRewriteRule, type E2EResult, type EnvSnapshot, ExitCode, type LintResult, type PackContractResult, type PatchDtsResult, type PnpmFiltersResult, ReleaseToolkitError, type ResolvedPaths, type RewriteRule, type RichVariant, type RichVariantsManifest, type RunA11yReportOptions, type RunAttwOptions, type RunBundleBudgetsOptions, type RunConvexBuildOptions, type RunConvexCodegenOptions, type RunCoverageOptions, type RunCoverageReportOptions, type RunDbMigrationsOptions, type RunDiffCoverageOptions, type RunE2EOptions, type RunGauntletOptions, type RunLicenseOptions, type RunLintOptions, type RunManifestContractOptions, type RunMutationReportOptions, type RunPackContractOptions, type RunPatchDtsOptions, type RunPerfSmokeOptions, type RunPnpmFiltersOptions, type RunPublintOptions, type RunRewriteImportsOptions, type RunSanitizeDistOptions, type RunSbomOptions, type RunScriptsOptions, type RunScriptsResult, type RunSizeCheckOptions, type RunSizeLimitConfigOptions, type RunSmokePackedOptions, type RunStorybookOptions, type RunSupplyChainOptions, type RunTypeCheckOptions, type RunVariantsOptions, type RunVitestBrowserPrepareOptions, type SanitizeDistResult, type ScannerState, type SizeLimitEntry, type StepReport, type StepStatus, type TypeCheckResult, type VitestBrowserPreparePlugin, dbProviderVariants, loadConfig, loadRichVariants, missingRequiredVariants, packageVariants, publishedSubpaths, readEnv, resolvePaths, runA11yReport, runAttw, runBundleBudgets, runConvexBuild, runConvexCodegen, runCoverage, runCoverageReport, runDbMigrations, runDiffCoverage, runE2E, runGauntlet, runLicense, runLint, runManifestContract, runMutationReport, runPackContract, runPatchDts, runPerfSmoke, runPnpmFilters, runPublint, runRewriteImports, runSanitizeDist, runSbom, runScripts, runSizeCheck, runSizeLimitConfig, runSmokePacked, runStorybook, runSupplyChain, runTypeCheck, runVariants, runVitestBrowserPrepare, storybookApps, storybookVariants, uiVariants, variantsByKind, vitestBrowserPrepareRetry };