serverless-ircd 0.9.0 → 0.11.0

package/scripts/deploy-web-aws.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * `scripts/deploy-web-aws.mjs` — the AWS web-client deploy pipeline helper.
+ *
+ * Two-phase deploy that runs AFTER `cdk deploy` applies the `IrcAwsStack`
+ * CloudFormation stack:
+ *
+ *   1. `aws cloudformation describe-stacks --stack-name IrcAwsStack` reads
+ *      the stack's outputs (`ConnectUrl`, `WebsiteBucketName`,
+ *      `WebsiteDistributionId`).
+ *   2. `pnpm --filter @serverless-ircd/web run build:prod-aws -- --api-url <url>`
+ *      bakes the SPA with the real API Gateway WebSocket URL (read from
+ *      `ConnectUrl` in step 1). The build script overrides the templated
+ *      `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}` `server` value in
+ *      `apps/web/static/config.prod-aws.json` and rejects any leftover
+ *      `{{...}}` placeholders, so no hardcoded URLs ship.
+ *   3. `aws s3 sync apps/web/dist s3://<bucket> --delete` uploads the
+ *      build. The CLI's `sync` compares etags and SKIPS unchanged objects,
+ *      so a re-deploy with no SPA changes uploads nothing (the
+ *      invalidation in step 4 still fires — CloudFront has no
+ *      unchanged-skip equivalent).
+ *   4. `aws cloudfront create-invalidation --distribution-id <id> --paths /*`
+ *      busts the edge cache so the new build is served immediately.
+ *
+ * Why a script instead of CDK `BucketDeployment`: `BucketDeployment`
+ * re-synths on every deploy (slower), cannot bake the post-deploy API URL
+ * into the baked config (it runs before the stack outputs exist), and
+ * pulls in a custom-resource Lambda for a one-shot copy. A stand-alone
+ * script reads the deployed outputs directly.
+ *
+ * Why the AWS CLI instead of `@aws-sdk/client-*`: `aws s3 sync`'s etag
+ * comparison and unchanged-skip are non-trivial to reimplement on top of
+ * the SDK; the CLI is already a deploy-time dependency (the workflow uses
+ * it for `describe-stacks`). One-off SDK calls would multiply surface
+ * area without buying anything.
+ *
+ * @see docs/AWS-Deployment.md for the full deploy runbook.
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+/**
+ * Fixed CloudFormation stack name (post-staging/prod-collapse: a single
+ * target per platform, no env suffix). Mirrors the value the deploy
+ * workflow's `describe-stacks` query already uses.
+ */
+export const STACK_NAME = 'IrcAwsStack';
+
+/**
+ * Outputs the script consumes. Each MUST be present on the deployed
+ * stack — a missing output aborts the deploy with a clear message so
+ * the operator knows to `cdk deploy` (or check the `webSite` prop) before
+ * re-running.
+ */
+export const REQUIRED_OUTPUTS = ['ConnectUrl', 'WebsiteBucketName', 'WebsiteDistributionId'];
+
+/**
+ * Pattern matching the `{{...}}` placeholders baked into
+ * `apps/web/static/config.prod-aws.json`. The stack output's `ConnectUrl`
+ * should be a fully-resolved wss URL; if it isn't, the build script would
+ * bake a broken SPA. This guard fails the deploy at the script layer
+ * (defence in depth) instead of relying on `build.mjs` alone.
+ */
+const PLACEHOLDER_PATTERN = /\{\{[^}]+\}\}/u;
+
+/**
+ * Builds the default runner that shells out to the `aws` CLI and `pnpm`
+ * via `spawnSync`. IO is captured (pipe) on the AWS path so the script can
+ * surface stderr in its own error messages; stdio for the `pnpm build`
+ * call is inherited so the (verbose) Kiwi build log streams live to the
+ * operator.
+ *
+ * @param {{ cwd?: string }} [opts]
+ * @returns {{ aws: (args: string[]) => CliResult; pnpm: (args: string[]) => CliResult }}
+ */
+export function makeDefaultRunner({ cwd = process.cwd() } = {}) {
+  return {
+    /* v8 ignore next -- 1-line wrapper over the tested runCli(); the literal binary name is the only thing that differs and it cannot be exercised without `aws` on the test PATH. */
+    aws(args) {
+      return runCli('aws', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    },
+    /* v8 ignore next -- 1-line wrapper over the tested runCli(); same reason as aws() above. */
+    pnpm(args) {
+      // Inherit stdio for pnpm so the build log streams live.
+      return runCli('pnpm', args, { cwd, stdio: 'inherit' });
+    },
+  };
+}
+
+/**
+ * Spawns a child process and returns the captured IO + exit status. Pure
+ * plumbing — no throwing on non-zero exits (the caller decides whether a
+ * non-zero status is an error). Exported so the test-suite can exercise
+ * the spawnSync shape with `node` as the binary instead of `aws`/`pnpm`
+ * (neither of which is guaranteed to be on PATH in the test environment).
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ cwd: string; stdio: 'inherit' | Array<'ignore' | 'pipe' | 'inherit'> }} opts
+ * @returns {CliResult}
+ */
+export function runCli(command, args, opts) {
+  const result = spawnSync(command, args, {
+    cwd: opts.cwd,
+    stdio: opts.stdio,
+    encoding: 'utf8',
+  });
+  const status = result.status ?? -1;
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+  return { status, stdout, stderr };
+}
+
+/**
+ * Parses the JSON body returned by
+ * `aws cloudformation describe-stacks --query 'Stacks[0].Outputs' --output json`
+ * into a plain `OutputKey → OutputValue` lookup. Empty / malformed bodies
+ * surface as thrown Errors so the caller (the deploy function) can fail
+ * loudly with context.
+ *
+ * @param {string} jsonBody
+ * @returns {Record<string, string>}
+ */
+export function parseStackOutputs(jsonBody) {
+  const parsed = JSON.parse(jsonBody);
+  if (!Array.isArray(parsed)) {
+    return {};
+  }
+  const map = {};
+  for (const entry of parsed) {
+    if (
+      typeof entry === 'object' &&
+      entry !== null &&
+      typeof entry.OutputKey === 'string' &&
+      typeof entry.OutputValue === 'string'
+    ) {
+      map[entry.OutputKey] = entry.OutputValue;
+    }
+  }
+  return map;
+}
+
+/**
+ * Runs the two-phase AWS web deploy. Throws on any failure (missing
+ * output, CLI non-zero exit, leftover placeholder) — the CLI entrypoint
+ * catches and exits non-zero.
+ *
+ * Implemented as an `async` function so the entrypoint and tests can
+ * consume it uniformly via `.catch()` / `rejects.toThrowError`; the
+ * underlying `spawnSync` calls are themselves synchronous, but wrapping
+ * the orchestration in a Promise keeps the contract stable if a future
+ * revision swaps in the AWS SDK or a streaming upload.
+ *
+ * @param {Object} [opts]
+ * @param {{ aws: (args: string[]) => CliResult; pnpm: (args: string[]) => CliResult }} [opts.runner]
+ * @param {string} [opts.stackName]
+ * @param {string} [opts.distDir]
+ * @param {(message: string) => void} [opts.log]
+ * @returns {Promise<{ connectUrl: string; bucket: string; distributionId: string }>}
+ */
+export async function deployWebAws({
+  runner = makeDefaultRunner(),
+  stackName = STACK_NAME,
+  distDir = path.join('apps', 'web', 'dist'),
+  log = (m) => console.log(m),
+} = {}) {
+  // 1. Read the deployed stack's outputs.
+  const describeResult = runner.aws([
+    'cloudformation',
+    'describe-stacks',
+    '--stack-name',
+    stackName,
+    '--query',
+    'Stacks[0].Outputs',
+    '--output',
+    'json',
+  ]);
+  if (describeResult.status !== 0) {
+    throw new Error(
+      `aws cloudformation describe-stacks --stack-name ${stackName} exited with ${describeResult.status}: ${describeResult.stderr}`,
+    );
+  }
+  const outputs = parseStackOutputs(describeResult.stdout);
+
+  // 2. Guard: every required output MUST be present. A missing output means
+  //    the stack hasn't been deployed (or the `webSite` prop was omitted on
+  //    the last synth), and proceeding would either bake a broken config
+  //    or sync to the wrong bucket.
+  const connectUrl = outputs.ConnectUrl;
+  const bucket = outputs.WebsiteBucketName;
+  const distributionId = outputs.WebsiteDistributionId;
+  for (const key of REQUIRED_OUTPUTS) {
+    const value = outputs[key];
+    if (value === undefined || value.length === 0) {
+      throw new Error(
+        `Missing required CloudFormation output '${key}' on stack '${stackName}'. ` +
+          `Has the stack been deployed (cdk deploy --all)? The web deploy pipeline requires: ${REQUIRED_OUTPUTS.join(', ')}.`,
+      );
+    }
+  }
+
+  // Defence in depth: the stack output itself should never carry an
+  // unsubstituted placeholder, but if it did the build would bake a
+  // broken SPA. Fail loudly here so the operator sees the script's
+  // diagnostic before the build's.
+  if (PLACEHOLDER_PATTERN.test(connectUrl)) {
+    throw new Error(
+      `Stack output ConnectUrl carries an unsubstituted placeholder: '${connectUrl}'. The deployed stage URL must be a fully-resolved wss:// URL, not a template.`,
+    );
+  }
+
+  // 3. Bake the SPA with the real API URL. The build script overrides the
+  //    templated `server` field in config.prod-aws.json with this value
+  //    and rejects any remaining `{{...}}` placeholders.
+  log(`Baking SPA with API URL ${connectUrl}`);
+  const buildResult = runner.pnpm([
+    '--filter',
+    '@serverless-ircd/web',
+    'run',
+    'build:prod-aws',
+    '--',
+    '--env',
+    'prod-aws',
+    '--api-url',
+    connectUrl,
+  ]);
+  if (buildResult.status !== 0) {
+    throw new Error(
+      `pnpm build:prod-aws exited with ${buildResult.status}. The web SPA build failed; see the build log above.`,
+    );
+  }
+
+  // 4. s3 sync. The CLI's `sync` skips unchanged objects via etag
+  //    comparison, so a re-deploy with no SPA changes uploads nothing.
+  //    `--delete` removes objects that no longer exist in the dist tree
+  //    (e.g. hashed assets from the previous build) so the bucket does
+  //    not accumulate stale entries.
+  log(`Syncing ${distDir} → s3://${bucket}`);
+  const syncResult = runner.aws(['s3', 'sync', distDir, `s3://${bucket}`, '--delete']);
+  if (syncResult.status !== 0) {
+    throw new Error(`aws s3 sync exited with ${syncResult.status}: ${syncResult.stderr}`);
+  }
+
+  // 5. CloudFront invalidation. Always fires — CloudFront has no
+  //    unchanged-skip equivalent, so even a no-op sync requires this to
+  //    guarantee the edge serves the latest origin state.
+  log(`Invalidating CloudFront distribution ${distributionId}`);
+  const invalidationResult = runner.aws([
+    'cloudfront',
+    'create-invalidation',
+    '--distribution-id',
+    distributionId,
+    '--paths',
+    '/*',
+  ]);
+  if (invalidationResult.status !== 0) {
+    throw new Error(
+      `aws cloudfront create-invalidation exited with ${invalidationResult.status}: ${invalidationResult.stderr}`,
+    );
+  }
+
+  log(`Deployed web client → s3://${bucket} (CloudFront ${distributionId}, invalidated /*)`);
+  return { connectUrl, bucket, distributionId };
+}
+
+// --- CLI entrypoint --------------------------------------------------------
+//
+// Excluded from coverage: the entrypoint is exercised by the deploy
+// pipeline / a human operator, not by the unit tests (which call
+// `deployWebAws` directly with an injected runner). The branch under test
+// is the `if (invokedDirectly)` body, which only fires when this file is
+// the process entry point — exactly the case vitest's import does NOT
+// produce. v8's ignore markers keep the coverage threshold meaningful
+// for the testable surface.
+
+/* v8 ignore start */
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  path.resolve(process.argv[1]) ===
+    path.resolve(new URL('./deploy-web-aws.mjs', import.meta.url).pathname);
+
+if (invokedDirectly) {
+  deployWebAws().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`deploy-web-aws: ${message}`);
+    process.exit(1);
+  });
+}
+/* v8 ignore stop */

package/scripts/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@serverless-ircd/deploy-scripts",
+  "version": "0.11.0",
+  "private": true,
+  "description": "Repo-level deploy helpers (AWS web client s3 sync + CloudFront invalidation pipeline).",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "scripts": {
+    "deploy:web-aws": "node ./deploy-web-aws.mjs",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf coverage .turbo"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}

package/scripts/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "composite": false,
+    "types": ["node"],
+    "allowJs": true,
+    "checkJs": false
+  },
+  "include": ["**/*.ts", "**/*.mjs", "**/*.d.mts"],
+  "exclude": ["node_modules", "coverage"]
+}

package/scripts/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['deploy-web-aws.mjs'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 90,
+        functions: 90,
+        branches: 90,
+        statements: 90,
+      },
+    },
+  },
+});

package/tools/ci-hardening/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": true,
-  "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
+  "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core + deploy hostname placeholder guard",
   "license": "BSD-3-Clause",
   "type": "module",
   "main": "./dist/index.js",

package/tools/ci-hardening/src/cf-deploy-cli.ts

@@ -0,0 +1,3 @@
+import { runDeploy } from './cf-deploy.js';
+
+process.exit(runDeploy(process.argv.slice(2), process.env));

package/tools/ci-hardening/src/cf-deploy.ts

@@ -0,0 +1,118 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { checkDeployHostname, readServerNameFromWranglerToml } from './deploy-hostname.js';
+
+/**
+ * Guarded `wrangler deploy` wrapper for the Cloudflare apps.
+ *
+ * Runs the deploy-time hostname guard and injects the resolved
+ * SERVER_NAME into the wrangler invocation itself, so an operator
+ * setting ONE override (`SERVER_NAME=irc.example.org pnpm deploy:cf`)
+ * satisfies both the guard and the deployed var. Without the wrapper
+ * the guard reads the env var but wrangler ignores it (vars come from
+ * wrangler.toml / --var flags), forcing the value to be specified
+ * twice.
+ *
+ * Usage (from an app's npm script, cwd = the app dir):
+ *
+ *   node ../../tools/ci-hardening/dist/cf-deploy-cli.js wrangler.toml -- <wrangler args...>
+ *
+ * Resolution order: a non-blank `SERVER_NAME` env override wins; else
+ * the `[vars]` SERVER_NAME in the config. The resolved value is always
+ * passed to wrangler as `--var SERVER_NAME:<hostname>` (identical to
+ * the config value in the fallback case, an override otherwise) and
+ * validated by the same placeholder guard as the deploy workflows.
+ */
+
+export interface WrapperArgv {
+  readonly configPath: string;
+  readonly passthrough: readonly string[];
+}
+
+/**
+ * Parses the wrapper argv: first positional is the wrangler.toml path;
+ * everything after it (with leading `--` separators stripped, which
+ * pnpm appends for `pnpm deploy:cf -- <args>`) is passed through to
+ * `wrangler deploy`.
+ */
+export function parseWrapperArgv(argv: readonly string[]): WrapperArgv {
+  const configPath = argv[0] ?? '';
+  const rest = argv.slice(1);
+  // Strip every leading `--` separator — pnpm forwarding can produce
+  // more than one (`pnpm deploy:cf -- --flag` on a script that itself
+  // ends in `--`); wrangler would treat them as positionals.
+  let i = 0;
+  while (i < rest.length && rest[i] === '--') i++;
+  return { configPath, passthrough: rest.slice(i) };
+}
+
+export type GuardedHostname = { ok: true; hostname: string } | { ok: false; message: string };
+
+/**
+ * Resolves the deploy-time hostname (env override → config `[vars]`
+ * SERVER_NAME) and runs it through the placeholder guard.
+ */
+export function resolveGuardedHostname(
+  configPath: string,
+  env: Record<string, string | undefined>,
+): GuardedHostname {
+  const override = env.SERVER_NAME;
+  const hostname =
+    typeof override === 'string' && override.trim() !== ''
+      ? override
+      : readServerNameFromWranglerToml(readFileSync(configPath, 'utf8'));
+  if (hostname === undefined) {
+    return {
+      ok: false,
+      message: `::error::SERVER_NAME is not set: no SERVER_NAME var found in ${configPath} and no SERVER_NAME environment override is set`,
+    };
+  }
+  const check = checkDeployHostname(hostname);
+  return check.ok
+    ? { ok: true, hostname: check.hostname }
+    : { ok: false, message: `::error::${check.error}` };
+}
+
+/**
+ * Builds the wrangler argument vector: `deploy` with the resolved
+ * hostname injected as a `--var` override, followed by any passthrough
+ * flags (`--dry-run`, `--keep-vars`, …). Uses the documented
+ * `KEY:value` pair syntax.
+ */
+export function buildWranglerDeployArgs(
+  hostname: string,
+  passthrough: readonly string[],
+): string[] {
+  return ['deploy', '--var', `SERVER_NAME:${hostname}`, ...passthrough];
+}
+
+const USAGE =
+  'usage: cf-deploy <wrangler.toml> [-- <wrangler deploy args...>] (SERVER_NAME env var optionally overrides the config value)';
+
+/**
+ * Resolves + guards, then execs `wrangler` (resolved from PATH — the
+ * npm script context puts node_modules/.bin there) with the resolved
+ * hostname injected. Returns the process exit code to propagate.
+ */
+export function runDeploy(
+  argv: readonly string[],
+  env: Record<string, string | undefined>,
+): number {
+  const { configPath, passthrough } = parseWrapperArgv(argv);
+  if (configPath === '') {
+    console.error(USAGE);
+    return 2;
+  }
+  const resolved = resolveGuardedHostname(configPath, env);
+  if (!resolved.ok) {
+    console.error(resolved.message);
+    return 1;
+  }
+  const args = buildWranglerDeployArgs(resolved.hostname, passthrough);
+  const result = spawnSync('wrangler', args, { stdio: 'inherit' });
+  if (result.error !== undefined) {
+    console.error(`::error::failed to run wrangler: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}

package/tools/ci-hardening/src/deploy-hostname.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Hostnames the repo ships as defaults in its deploy configs
+ * (`SERVER_NAME = "irc.your-domain.invalid"` in both wrangler.toml
+ * files, `irc.example.com` in the Spectrum apply docs/defaults).
+ *
+ * A deploy whose public hostname is still one of these values is a
+ * misconfiguration, not a deploy: the wss Worker would advertise the
+ * placeholder in its numerics and the Spectrum cert/handshake would
+ * target a domain the operator does not own. Deploy paths refuse to
+ * ship while the deploy-time hostname is on this list.
+ */
+export const PLACEHOLDER_HOSTNAMES: ReadonlySet<string> = new Set([
+  'irc.example.com',
+  'irc.your-domain.invalid',
+]);
+
+/**
+ * Whether a hostname is one of the repo's shipping placeholders.
+ * Hostnames are case-insensitive and tolerant of surrounding
+ * whitespace (workflow inputs / env vars).
+ */
+export function isPlaceholderHostname(hostname: string): boolean {
+  return PLACEHOLDER_HOSTNAMES.has(hostname.trim().toLowerCase());
+}
+
+export type HostnameCheck = { ok: true; hostname: string } | { ok: false; error: string };
+
+/**
+ * Validate a deploy-time hostname. Returns the trimmed, lowercased
+ * hostname on success; on failure returns an `error` explaining how
+ * to set a real one (workflow `hostname` input, or `SERVER_NAME` in
+ * the app's wrangler.toml `[vars]` block).
+ */
+export function checkDeployHostname(raw: string | undefined | null): HostnameCheck {
+  const hostname = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  if (hostname === '') {
+    return {
+      ok: false,
+      error:
+        'deploy hostname is required: pass the public IRC hostname via the workflow `hostname` input (deploy-cf / deploy-cf-tcp) or set SERVER_NAME in the app wrangler.toml [vars] block',
+    };
+  }
+  if (isPlaceholderHostname(hostname)) {
+    return {
+      ok: false,
+      error: `${hostname} is a placeholder hostname shipped with the repo defaults, not a real deploy target: set the public IRC hostname (workflow \`hostname\` input or SERVER_NAME in wrangler.toml [vars]) and redeploy`,
+    };
+  }
+  return { ok: true, hostname };
+}
+
+const SERVER_NAME_RE = /^\s*SERVER_NAME\s*=\s*["']([^"'\r\n]+)["']\s*$/m;
+
+/**
+ * Extract the `SERVER_NAME` var from wrangler.toml text. Anchored at
+ * line starts so commented-out (`# SERVER_NAME = ...`) assignments
+ * do not match; accepts both TOML quote styles.
+ */
+export function readServerNameFromWranglerToml(tomlText: string): string | undefined {
+  return tomlText.match(SERVER_NAME_RE)?.[1];
+}
+
+export interface HostnameGuardResult {
+  /** 0 = deployable, 1 = rejected (unset or placeholder), 2 = usage error. */
+  exitCode: number;
+  message: string;
+}
+
+const USAGE = 'usage: hostname-guard <hostname> | hostname-guard --from-config <wrangler.toml>';
+
+function report(check: HostnameCheck): HostnameGuardResult {
+  return check.ok
+    ? { exitCode: 0, message: `deploy hostname OK: ${check.hostname}` }
+    : { exitCode: 1, message: `::error::${check.error}` };
+}
+
+/**
+ * The deploy-time hostname guard. Two modes:
+ *
+ * - `hostname-guard <hostname>` — validate an explicit value (the
+ *   deploy workflows pass their `hostname` input through this).
+ * - `hostname-guard --from-config <wrangler.toml>` — validate the
+ *   deploy-time SERVER_NAME: the `SERVER_NAME` env override if set
+ *   and non-blank, else the `[vars]` SERVER_NAME in the config (the
+ *   guarded `wrangler deploy` npm scripts use this).
+ *
+ * Pure with respect to the process: `main` wires `process.argv` /
+ * `process.env` / stdio / `process.exit`.
+ */
+export function runHostnameGuard(
+  argv: readonly string[],
+  env: Record<string, string | undefined>,
+): HostnameGuardResult {
+  if (argv[0] === '--from-config') {
+    const configPath = argv[1];
+    if (configPath === undefined || configPath === '') {
+      return { exitCode: 2, message: USAGE };
+    }
+    const override = env.SERVER_NAME;
+    const hostname =
+      typeof override === 'string' && override.trim() !== ''
+        ? override
+        : readServerNameFromWranglerToml(readFileSync(configPath, 'utf8'));
+    if (hostname === undefined) {
+      return {
+        exitCode: 1,
+        message: `::error::SERVER_NAME is not set: no SERVER_NAME var found in ${configPath} and no SERVER_NAME environment override is set`,
+      };
+    }
+    return report(checkDeployHostname(hostname));
+  }
+  if (argv.length === 1) {
+    return report(checkDeployHostname(argv[0]));
+  }
+  return { exitCode: 2, message: USAGE };
+}