infraweaver 0.1.0

package/src/agents/writeGateSource.ts

@@ -0,0 +1,148 @@
+/**
+ * The path-decision half of the write-time gates, emitted as source text that
+ * both agent runtimes embed into the standalone scripts they drop in the run
+ * tmpdir (see action/agents/claudePretoolGate.ts and
+ * action/agents/opencodePlugin.ts).
+ *
+ * It lives in one place because the two runtimes previously derived their base
+ * directory differently (the hook payload's `cwd` vs `process.cwd()`), which
+ * would silently misalign every glob the moment one of them changed. Sharing
+ * the source keeps a single definition of "is this write allowed", and keeps it
+ * aligned with the push-time gates in action/mcp/guardrails.ts that re-check
+ * the same globs.
+ *
+ * The emitted code is dependency-free (node builtins only) because the scripts
+ * run outside the bundle, with no module resolution available to them.
+ */
+
+import { globToRegex } from "#app/mcp/guardrails";
+
+/**
+ * Shared helper source. Defines `refuseWrite(policy, rawPath, root)` returning
+ * a refusal string or null, plus the primitives it needs. Callers supply their
+ * own `targetPathOf` because the two runtimes name tool arguments differently.
+ */
+export const WRITE_GATE_HELPERS_SOURCE = `
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+// embedded verbatim from globToRegex in action/mcp/guardrails.ts via
+// Function.prototype.toString, so these gates and the push-time guardrails
+// share one definition of glob membership rather than a copy that can drift.
+// The function is a self-contained named declaration, which is what keeps this
+// valid through esbuild bundling and minification.
+const globToRegex = ${globToRegex.toString()};
+
+function matchesAny(path, globs) {
+  if (!Array.isArray(globs)) return false;
+  return globs.some((g) => globToRegex(g).test(path));
+}
+
+/**
+ * Deny-list membership. Matches case-insensitively IN ADDITION to exactly:
+ * macOS and Windows resolve \`PROD/main.tf\` and \`prod/main.tf\` to the same
+ * file, so a case variant must not slip past protected_paths. The allow-list
+ * deliberately stays case-sensitive — failing closed there is an inconvenience,
+ * whereas failing open on a deny-list is a security hole.
+ */
+function denyMatches(path, globs) {
+  if (matchesAny(path, globs)) return true;
+  if (!Array.isArray(globs)) return false;
+  const lower = path.toLowerCase();
+  return globs.some((g) => globToRegex(String(g).toLowerCase()).test(lower));
+}
+
+/**
+ * Resolve to a real path, following symlinks on the deepest EXISTING ancestor.
+ * resolve() alone is purely lexical, so a symlink planted inside the checkout
+ * ("link" -> "../outside") would produce a repo-relative path that passes every
+ * glob while the write itself lands outside the work tree — where the push-time
+ * guardrails can never see it, because \`git diff\` does not report it.
+ */
+function realDeepest(p) {
+  let current = resolve(p);
+  const trailing = [];
+  for (;;) {
+    try {
+      const real = realpathSync(current);
+      return trailing.length === 0 ? real : join(real, ...trailing.slice().reverse());
+    } catch {
+      const parent = dirname(current);
+      // reached the filesystem root without finding anything that exists —
+      // fall back to the lexical resolution rather than looping forever.
+      if (parent === current) return resolve(p);
+      trailing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Repo-root-relative POSIX path, matching what \`git diff --name-only\` yields
+ * for the push-time gates, or null when the write escapes the workspace.
+ *
+ * The base is the REPO ROOT, never the process cwd: main.ts chdir()s into the
+ * \`cwd\` input for monorepo subdirectories, and the push-time globs are always
+ * repo-root-relative, so resolving against cwd would misalign every glob in
+ * exactly the runs that configure one.
+ */
+function repoRelativePath(rawPath, root) {
+  const realRoot = realDeepest(root);
+  const absolute = isAbsolute(rawPath) ? rawPath : resolve(realRoot, rawPath);
+  const rel = relative(realRoot, realDeepest(absolute)).replace(/\\\\/g, "/");
+  if (rel === "" || rel === ".." || rel.startsWith("../")) return null;
+  // on Windows, path.relative returns an ABSOLUTE path when the two roots
+  // differ (another drive letter, or a UNC share). Such a path must be a
+  // refusal, not something that happens to match \`**/*.tf\`.
+  if (isAbsolute(rel) || rel.startsWith("//")) return null;
+  return rel;
+}
+
+/**
+ * Refusal string when the write must be blocked, or null to allow. Deny-lists
+ * are checked BEFORE the allow-list: a .tf file inside protected_paths matches
+ * the allow-list too, and must still be refused. A policy whose arrays are
+ * missing or malformed fails CLOSED — an unusable policy must not silently
+ * become a pass.
+ */
+function refuseWrite(policy, rawPath, root) {
+  const rel = repoRelativePath(rawPath, root);
+  if (rel === null) {
+    return "write blocked (protected-paths guardrail): '" + rawPath +
+      "' resolves outside the repository workspace. Write only inside the checkout.";
+  }
+  if (denyMatches(rel, policy.protected)) {
+    return "write blocked (protected-paths guardrail): '" + rel +
+      "' matches the protected_paths globs [" + (policy.protected || []).join(", ") +
+      "], which are marked never-auto-modify. Leave this file for a human and fix the concern elsewhere.";
+  }
+  if (denyMatches(rel, policy.vendored)) {
+    return "write blocked (read-only module guardrail): '" + rel +
+      "' is FETCHED module code under the local module cache, which is read-only. " +
+      "Fix a module-internal concern at the CALL SITE via the module's inputs, never by editing the vendored copy.";
+  }
+  if (!Array.isArray(policy.allowed) || !matchesAny(rel, policy.allowed)) {
+    return "write blocked (Terraform-only guardrail): '" + rel +
+      "' is outside the allowed paths [" + (policy.allowed || []).join(", ") +
+      "]. " + policy.mode + " must only touch Terraform files — keep the change to those.";
+  }
+  return null;
+}
+
+function readWritePolicy(policyPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(policyPath, "utf8"));
+    // an absent/empty mode is the "no guarded mode selected" signal — the
+    // policy file exists for the whole run but only restricts once a guarded
+    // mode is chosen, mirroring the push-time gates' isGuardedMode() no-op.
+    if (!parsed || typeof parsed.mode !== "string" || parsed.mode === "") return null;
+    if (typeof parsed.root !== "string" || parsed.root === "") return null;
+    return parsed;
+  } catch {
+    // no policy published yet (or unreadable). the push-time guardrails remain
+    // the fail-closed backstop, so allowing here cannot let a bad change reach
+    // a PR — it only defers the refusal to push time.
+    return null;
+  }
+}
+`;

package/src/agents/writePolicy.ts

@@ -0,0 +1,132 @@
+/**
+ * The write-time counterpart to the push-time path guardrails in
+ * `action/mcp/guardrails.ts`.
+ *
+ * Those gates (`enforceRemediationPaths`, `enforceProtectedPaths`,
+ * `assertNoVendoredModuleEdits`) all read `git diff <run-start> HEAD` — so they
+ * only fire once a change is already committed and heading for a push. That is
+ * fail-safe but LATE: between the write and the push the modified tree is what
+ * every subsequent subprocess sees, so a `terraform plan` or a re-scan can run
+ * against a file the guardrails would ultimately refuse. This module moves the
+ * same allow/deny decision to the moment of the write itself.
+ *
+ * SCOPE — this covers the agent's file-writing TOOLS, not every possible write.
+ * It deliberately does not cover:
+ *   - the MCP `shell` tool (`cat > f`, `tee`, `sed -i`), which is bounded by
+ *     the OS sandbox in `action/mcp/shell.ts` rather than by these globs;
+ *   - the file-emitting MCP tools (`terraform_emit_sarif`, `_emit_evidence`,
+ *     `_emit_oscal`, `_emit_vex`, `terraform_module_docs`), whose output paths
+ *     are confined to the workspace by `resolveWithinCwd` but not to
+ *     `allowed_paths`.
+ * Both remain covered by the push-time gates, which still fail closed, so
+ * neither is a route to a merged PR — but neither is stopped at write time.
+ *
+ * The policy is published as a small JSON file in the run's tmpdir rather than
+ * baked into the agent's gate script, because `select_mode` sets
+ * `toolState.selectedMode` DURING the run (see action/mcp/selectMode.ts) while
+ * the gate script is written before the agent launches. The gate re-reads this
+ * file on every tool call, so an auto-selected mode is picked up without
+ * restarting the agent. No file (or a non-guarded mode) means no restriction —
+ * exactly matching the push-time gates, which no-op outside a guarded mode.
+ *
+ * Both agent runtimes consume it: action/agents/claudePretoolGate.ts (Claude
+ * Code `PreToolUse`) and action/agents/opencodePlugin.ts
+ * (`tool.execute.before`).
+ */
+
+import { renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type GuardrailContext,
+  isGuardedModeName,
+  resolveAllowedPaths,
+  resolveProtectedPaths,
+  VENDORED_MODULE_PATHS,
+} from "#app/mcp/guardrails";
+import { resolveRepoRoot } from "#app/mcp/shell";
+import { log } from "#app/utils/cli";
+
+export const WRITE_POLICY_FILENAME = "infraweaver-write-policy.json" as const;
+
+/**
+ * What the gate scripts read. Deliberately a flat, dependency-free shape: the
+ * gates are plain `.mjs` with no imports, so anything richer would have to be
+ * re-modelled on the other side.
+ */
+export interface WritePolicy {
+  /** the guarded mode in force — surfaced in the refusal so the model can reason about it. */
+  mode: string;
+  /**
+   * The repo root every glob is resolved against. Carried in the policy rather
+   * than derived inside the gates because `main.ts` chdir()s into the `cwd`
+   * input for monorepo subdirectories, so neither gate's own process cwd is a
+   * safe base — and the push-time globs are always repo-root-relative.
+   */
+  root: string;
+  /** globs a write MUST match (the `allowed_paths` allow-list). */
+  allowed: string[];
+  /** globs a write must NOT match (the `protected_paths` deny-list). */
+  protected: string[];
+  /** fetched/vendored module code, which is read-only by the refactor contract. */
+  vendored: string[];
+}
+
+/**
+ * Derive the policy for the current run, or `null` when no restriction applies
+ * (no mode selected yet, or a mode outside the guarded set — Review, Plan,
+ * Assess and friends legitimately write files the Terraform-only allow-list
+ * would reject, so gating them would break them).
+ */
+export function buildWritePolicy(ctx: GuardrailContext): WritePolicy | null {
+  const mode = ctx.toolState.selectedMode;
+  if (!mode || !isGuardedModeName(mode)) return null;
+  return {
+    mode,
+    root: resolveRepoRoot(),
+    allowed: resolveAllowedPaths(ctx),
+    protected: resolveProtectedPaths(ctx),
+    vendored: [...VENDORED_MODULE_PATHS],
+  };
+}
+
+export function writePolicyPath(tmpdir: string): string {
+  return join(tmpdir, WRITE_POLICY_FILENAME);
+}
+
+/**
+ * Publish (or clear) the policy for the gates to read.
+ *
+ * Written via a temp file + `rename` so a gate that reads concurrently sees
+ * either the old policy or the new one, never a half-written file — `rename` is
+ * atomic within a filesystem, and the temp file is created in the same tmpdir.
+ *
+ * Best-effort by design: the push-time guardrails remain the authoritative,
+ * fail-closed backstop, so a failure to publish must not abort a run that would
+ * otherwise be blocked correctly a few steps later. It is logged, not thrown.
+ */
+export function refreshWritePolicy(ctx: GuardrailContext): void {
+  // everything, including resolving the path, sits inside the try: this is
+  // called from the select_mode hot path and must never be able to fail a run.
+  // A context without a tmpdir (or an unwritable one) degrades to "no policy
+  // published", which the gates read as "no restriction" — the same posture as
+  // before this gate existed, with the push-time guardrails still fail-closed.
+  try {
+    const policy = buildWritePolicy(ctx);
+    const target = writePolicyPath(ctx.tmpdir);
+    const staging = `${target}.${process.pid}.tmp`;
+    // an absent `mode` is the "no restriction" signal the gates already handle,
+    // so clearing is just publishing a policy with no mode rather than deleting
+    // the file (which would race with a concurrent read).
+    writeFileSync(staging, JSON.stringify(policy ?? { mode: "" }), "utf8");
+    renameSync(staging, target);
+  } catch (err) {
+    // warning, not debug: this silently disables write-time enforcement for the
+    // whole run, and the only remaining signal would be a push-time refusal
+    // much later. The run is still safe (push-time gates fail closed) but the
+    // operator should see that a layer went missing.
+    log.warning(
+      `could not publish the write policy — write-time path enforcement is disabled for this run ` +
+        `(push-time guardrails still apply): ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/brand.ts

@@ -0,0 +1,84 @@
+/**
+ * Single source of truth for the product brand on the engine side.
+ *
+ * Every user-visible product name, slug, prefix, and brand-derived filename
+ * must come from this module — a rebrand (or a white-label build) is then a
+ * handful of one-line edits here. The one permitted exception is `action.yml`,
+ * which is static YAML and cannot import; src/brand.test.ts asserts it stays
+ * in sync with these values.
+ *
+ * The reviewer subagent name is NOT defined here — it is a separate sub-brand
+ * owned by `REVIEWER_AGENT_NAME` in src/agents/reviewer.ts.
+ */
+
+/** Display name — PR bodies, review comments, run summaries, agent labels. */
+export const PRODUCT_NAME = "Infraweaver";
+
+/** Lowercase wordmark — package/dir names, CLI usage strings, slugs. */
+export const PRODUCT_SLUG = "infraweaver";
+
+/** PR comment trigger, e.g. `@infraweaver fix`. */
+export const COMMENT_COMMAND = `@${PRODUCT_SLUG}`;
+
+/** SARIF `driver.name`, CycloneDX VEX tool component, evidence `tool.name` —
+ * the emitted artifacts all use the lowercase wordmark. */
+export const TOOL_NAME = PRODUCT_SLUG;
+
+/** Cloud API token prefix — must match the Cloud UI's `TOKEN_PREFIX`. */
+export const TOKEN_PREFIX = "tmnd_";
+
+/** Prefix for all brand-scoped environment variables. */
+export const ENV_PREFIX = "INFRAWEAVER_";
+
+/** Primary domain — the Cloud API's default host and bearer-credential allowlist root. */
+export const PRIMARY_DOMAIN = "infraweaver.dev";
+/** Default Cloud API base URL. */
+export const DEFAULT_API_URL = `https://${PRIMARY_DOMAIN}`;
+/** Docs subdomain, used in in-product setup links. */
+export const DOCS_URL = `https://docs.${PRIMARY_DOMAIN}`;
+/** Status-page subdomain, linked from transient-error messages. */
+export const STATUS_URL = `https://status.${PRIMARY_DOMAIN}`;
+/** Asset-hosting subdomain, used for static images embedded in PR/issue markdown. */
+export const UPLOADS_URL = `https://uploads.${PRIMARY_DOMAIN}`;
+
+// ---------------------------------------------------------------------------
+// Brand-derived filenames (repo config, state, and emitted artifacts).
+// ---------------------------------------------------------------------------
+
+/** Repo config file (YAML). */
+export const CONFIG_FILE = `.${PRODUCT_SLUG}.yml`;
+/** Repo config file (`.yaml` spelling variant). */
+export const CONFIG_FILE_YAML = `.${PRODUCT_SLUG}.yaml`;
+/** Repo config file (JSON variant). */
+export const CONFIG_FILE_JSON = `.${PRODUCT_SLUG}.json`;
+/** Committed baseline of accepted pre-existing findings. */
+export const BASELINE_FILE = `.${PRODUCT_SLUG}.baseline.json`;
+/** Committed fix-memory (proven-fix recall) file. */
+export const FIX_MEMORY_FILE = `.${PRODUCT_SLUG}.fix-memory.json`;
+/** Repo-committed reviewer learnings file seeded by the server. */
+export const LEARNINGS_FILE = `${PRODUCT_SLUG}-learnings.md`;
+/** Rolling PR summary snapshot file. */
+export const SUMMARY_FILE = `${PRODUCT_SLUG}-summary.md`;
+/** Signed evidence bundle. */
+export const EVIDENCE_FILE = `${PRODUCT_SLUG}-evidence.json`;
+/** Detached signature for the evidence bundle. */
+export const EVIDENCE_SIG_FILE = `${EVIDENCE_FILE}.sig`;
+/** SARIF report. */
+export const SARIF_FILE = `${PRODUCT_SLUG}.sarif`;
+/** CycloneDX VEX document. */
+export const VEX_FILE = `${PRODUCT_SLUG}-vex.cdx.json`;
+/** OSCAL Assessment Results document. */
+export const OSCAL_FILE = `${PRODUCT_SLUG}-oscal.json`;
+/** Credential-free cost-analysis artifact committed to the PR (§5.19). */
+export const COST_FILE = "cost.md";
+
+// ---------------------------------------------------------------------------
+// Brand-derived identities.
+// ---------------------------------------------------------------------------
+
+/** The product's GitHub App bot login. */
+export const BOT_LOGIN = `${PRODUCT_SLUG}[bot]`;
+/** The bot's GitHub noreply commit-author email. */
+export const BOT_EMAIL = `${BOT_LOGIN}@users.noreply.github.com`;
+/** Default GitHub Actions OIDC audience for the product API. */
+export const OIDC_AUDIENCE = `${PRODUCT_SLUG}-api`;

package/src/cli.ts

@@ -0,0 +1,117 @@
+import { basename } from "node:path";
+import arg from "arg";
+import pc from "picocolors";
+import { PRODUCT_SLUG } from "#app/brand";
+import { runCli as runGhaCli } from "#app/commands/gha";
+import { runMcpCli } from "#app/commands/mcp";
+import { runVerifyEvidenceCli } from "#app/commands/verifyEvidence";
+
+const VERSION = process.env.CLI_VERSION ?? "0.0.0";
+const bin = basename(process.argv[1] || "");
+const PROG = bin === "pf" || bin === PRODUCT_SLUG ? bin : PRODUCT_SLUG;
+const rawArgs = process.argv.slice(2);
+
+function printMainUsage(stream: typeof console.log): void {
+  stream(`usage: ${PROG} <command>\n`);
+  stream("commands:");
+  stream("  gha              run the github action runtime flow (used by action.yml)");
+  stream("  mcp              start the local MCP server (stdio) with read-only terraform tools");
+  stream("  verify-evidence  verify a signed evidence bundle's detached Ed25519 signature");
+  stream("");
+  stream("global options:");
+  stream("  -h, --help      show help");
+  stream("  -v, --version   show version");
+}
+
+function parseGlobalArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--version": Boolean,
+      "-h": "--help",
+      "-v": "--version",
+    },
+    {
+      argv: args,
+      stopAtPositional: true,
+    },
+  );
+}
+
+function exitWithUsageError(message: string): never {
+  console.error(`${message}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+async function run(): Promise<void> {
+  let globalParsed: ReturnType<typeof parseGlobalArgs>;
+  try {
+    globalParsed = parseGlobalArgs(rawArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithUsageError(message);
+  }
+
+  if (globalParsed["--version"]) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  const command = globalParsed._[0];
+  const commandArgs = globalParsed._.slice(1);
+
+  if (!command) {
+    if (globalParsed["--help"]) {
+      console.log(`${pc.bold(PRODUCT_SLUG)} v${VERSION}\n`);
+      printMainUsage(console.log);
+      process.exit(0);
+    }
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  if (command === "gha") {
+    await runGhaCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (command === "mcp") {
+    await runMcpCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (command === "verify-evidence") {
+    await runVerifyEvidenceCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (globalParsed["--help"]) {
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  console.error(`unknown command: ${pc.bold(command)}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+try {
+  await run();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(pc.red(message));
+  process.exit(1);
+}

package/src/commands/gha.ts

@@ -0,0 +1,188 @@
+import { dirname } from "node:path";
+import * as core from "@actions/core";
+import arg from "arg";
+import { main } from "#app/main";
+import { acquireInstallationToken, revokeInstallationToken } from "#app/utils/token";
+
+// GitHub Actions runs the action entry point with the node24 binary specified
+// in action.yml, but doesn't add that binary's directory to PATH. Without this,
+// spawned processes (pnpm, npm, etc.) resolve to the runner's default node (v20).
+process.env.PATH = `${dirname(process.execPath)}:${process.env.PATH}`;
+
+const STATE_TOKEN = "token";
+
+interface GhaCliParams {
+  args: string[];
+  prog: string;
+  showHelp?: boolean;
+}
+
+async function runMain(): Promise<void> {
+  try {
+    const result = await main();
+    if (!result.success) {
+      throw new Error(result.error || "agent execution failed");
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "unknown error occurred";
+    core.setFailed(`action failed: ${errorMessage}`);
+  }
+}
+
+async function tokenMain(): Promise<void> {
+  const reposInput = core.getInput("repos");
+  const additionalRepos = reposInput
+    ? reposInput
+        .split(",")
+        .map((r) => r.trim())
+        .filter(Boolean)
+    : [];
+
+  const token = await acquireInstallationToken({ repos: additionalRepos });
+
+  core.setSecret(token);
+  core.saveState(STATE_TOKEN, token);
+  core.setOutput("token", token);
+
+  const scope = additionalRepos.length
+    ? `current repo + ${additionalRepos.join(", ")}`
+    : "current repo only";
+  core.info(`» installation token acquired (${scope})`);
+}
+
+async function tokenPost(): Promise<void> {
+  const token = core.getState(STATE_TOKEN);
+  if (!token) {
+    core.debug("no token found in state, skipping revocation");
+    return;
+  }
+  await revokeInstallationToken(token);
+  core.info("» installation token revoked");
+}
+
+function printGhaUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} gha [subcommand]\n`);
+  params.stream("run the github action runtime flow.");
+  params.stream("");
+  params.stream("subcommands:");
+  params.stream("  token        acquire a github app installation token");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+}
+
+function printGhaTokenUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} gha token [--post]\n`);
+  params.stream("acquire a github app installation token, or revoke it in the post step.");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+  params.stream("  --post       revoke the previously-acquired token (post-step usage only)");
+}
+
+function parseGhaArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+      stopAtPositional: true,
+    },
+  );
+}
+
+function parseGhaTokenArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--post": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+    },
+  );
+}
+
+export async function runCli(params: GhaCliParams): Promise<void> {
+  if (params.showHelp) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  let parsed: ReturnType<typeof parseGhaArgs>;
+  try {
+    parsed = parseGhaArgs(params.args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--help"]) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  const positional = parsed._;
+  const subcommand = positional[0];
+
+  if (!subcommand) {
+    await run(["gha"]);
+    return;
+  }
+
+  if (subcommand !== "token") {
+    console.error(`unknown gha subcommand: ${subcommand}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  // gha token [--post]
+  let tokenParsed: ReturnType<typeof parseGhaTokenArgs>;
+  try {
+    tokenParsed = parseGhaTokenArgs(positional.slice(1));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printGhaTokenUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (tokenParsed["--help"]) {
+    printGhaTokenUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  if (tokenParsed._.length > 0) {
+    console.error(`unexpected positional arguments for gha token: ${tokenParsed._.join(" ")}\n`);
+    printGhaTokenUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  const normalizedArgs = ["gha", "token"];
+  if (tokenParsed["--post"]) {
+    normalizedArgs.push("--post");
+  }
+  await run(normalizedArgs);
+}
+
+export async function run(args: string[]) {
+  try {
+    if (args.includes("token")) {
+      if (args.includes("--post")) {
+        await tokenPost();
+      } else {
+        await tokenMain();
+      }
+    } else {
+      await runMain();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    core.setFailed(message);
+  }
+}