rastack 0.0.62 → 0.0.64

package/src/deploy/config.ts

@@ -33,6 +33,12 @@ export interface DeployOutputs {
   jwksUrl?: string;
   /** S3 Iceberg warehouse bucket — the system of record. */
   warehouseBucket?: string;
+  /** Cognito Hosted UI domain (scheme-less), for browser sign-in. */
+  userPoolDomain?: string;
+  /** Full Cognito Hosted UI base URL (`https://…`). */
+  hostedUiUrl?: string;
+  /** Base URL of the external-API proxy route, when the env provisions one. */
+  proxyUrl?: string;
 }
 
 export interface LambdaBuild {
@@ -44,6 +50,36 @@ export interface LambdaBuild {
   features: string;
 }
 
+/**
+ * Per-environment overrides. The **prod** environment defaults its values from
+ * the top-level config (its branch is `github.branch`, its stack is `stackName`,
+ * its outputs are the top-level `outputs`); the **dev** environment defaults to
+ * the `development` branch and a `-dev` stack. Anything set here wins over those
+ * defaults. Only the fields that actually differ per environment live here —
+ * `app`/`namePrefix`/`region`/`github.owner`/`github.repo` are shared.
+ */
+export interface EnvOverride {
+  /** GitHub branch whose push deploys this environment. */
+  branch?: string;
+  /** GitHub Actions **Environment** name (scoped Variables + protection rules). */
+  ghEnvironment?: string;
+  /** CloudFormation stack name for this environment. */
+  stackName?: string;
+  /** Iceberg namespace this environment's warehouse writes under. */
+  namespace?: string;
+  /**
+   * Base URL of the upstream this environment's **external-API proxy** forwards
+   * to (typically a UAT or prod backend). When set, the stack provisions a
+   * Cognito-authorized `ANY /proxy/{proxy+}` route on the HTTP API that forwards
+   * to `${proxyUpstream}/{proxy}` — so a locally-running app (signed in against
+   * this environment's Cognito pool) reaches external APIs *only* through the
+   * proxy, never directly, and credentials stay server-side. Empty = no proxy.
+   */
+  proxyUpstream?: string;
+  /** Values resolved from this environment's stack after it is created. */
+  outputs?: DeployOutputs;
+}
+
 export interface DeployConfig {
   /** App slug — namespaces buckets/roles/SSM. Cognito-safe: `^[a-z0-9]{1,20}$`. */
   app: string;
@@ -51,9 +87,16 @@ export interface DeployConfig {
   namePrefix: string;
   /** AWS region the stack (and CI) target. */
   region: string;
-  /** CloudFormation stack name — defaults to `${namePrefix}-${app}`. */
+  /**
+   * CloudFormation stack name of the **prod** environment — defaults to
+   * `${namePrefix}-${app}`. Dev's stack defaults to this + `-dev`.
+   */
   stackName: string;
-  /** The GitHub repo whose CI is trusted to ship the Lambda code. */
+  /**
+   * The GitHub repo whose CI is trusted to ship the Lambda code. `branch` is the
+   * **prod** deploy branch (default `master`); the dev branch defaults to
+   * `development` and is overridable under `environments.dev.branch`.
+   */
   github: { owner: string; repo: string; branch: string };
   /** Iceberg namespace the warehouse writes under. */
   namespace: string;
@@ -69,10 +112,130 @@ export interface DeployConfig {
   artifactsBucket?: string;
   /** Whether the function verifies the `access` or `id` token. */
   tokenUse: "access" | "id";
-  /** Values resolved from the stack after it is created (optional). */
+  /** Values resolved from the (prod) stack after it is created (optional). */
+  outputs?: DeployOutputs;
+  /**
+   * Per-environment overrides. A `dev` + `prod` split is the default even with
+   * this omitted (see `resolveEnvironment`); this only records what a user
+   * changed (a custom dev branch, dev stack outputs, …).
+   */
+  environments?: Partial<Record<EnvName, EnvOverride>>;
+}
+
+/** The two deployment environments — dev (development branch) and prod (master). */
+export type EnvName = "prod" | "dev";
+export const ENV_NAMES: readonly EnvName[] = ["prod", "dev"] as const;
+
+/** The fully-resolved shape of one environment (top-level + defaults + overrides). */
+export interface EnvDef {
+  /** Which environment this is. */
+  name: EnvName;
+  /** Branch whose push deploys it (`master` for prod, `development` for dev). */
+  branch: string;
+  /** GitHub Actions Environment name (`production` / `development`). */
+  ghEnvironment: string;
+  /**
+   * The app.yaml `AppName` parameter — the infra namespace. Prod uses the app
+   * slug; dev uses `${app}dev` so its buckets/roles/pools/SSM never collide with
+   * prod's (AppName is Cognito-safe `^[a-z0-9]{1,20}$`, so the suffix is glued,
+   * not hyphenated).
+   */
+  appName: string;
+  /** CloudFormation stack name for this environment. */
+  stackName: string;
+  /** Iceberg namespace this environment writes under. */
+  namespace: string;
+  /** Upstream the external-API proxy forwards to (empty when no proxy). */
+  proxyUpstream: string;
+  /** Values resolved from this environment's stack, when known. */
   outputs?: DeployOutputs;
 }
 
+/** Defaults for the dev environment when `environments.dev` is unset. */
+export const DEV_DEFAULTS = {
+  branch: "development",
+  ghEnvironment: "development",
+  namespace: "development",
+} as const;
+
+/** The GitHub Actions Environment name the prod deploy uses. */
+export const PROD_GH_ENVIRONMENT = "production";
+
+/**
+ * The app.yaml `AppName` for an environment — the infra namespace. Dev glues a
+ * `dev` suffix on so its stack's buckets/roles/pools/SSM are physically distinct
+ * from prod's without a hyphen (Cognito `AppName`/`IdentityPoolName` forbid one).
+ */
+export function envAppName(cfg: DeployConfig, env: EnvName): string {
+  return env === "dev" ? `${cfg.app}dev` : cfg.app;
+}
+
+/**
+ * Resolve one environment to its full definition: the prod environment inherits
+ * the top-level branch/stack/namespace/outputs, the dev environment defaults to
+ * the `development` branch and a `-dev` stack, and anything under
+ * `cfg.environments[env]` overrides those.
+ */
+export function resolveEnvironment(cfg: DeployConfig, env: EnvName): EnvDef {
+  const o = cfg.environments?.[env] ?? {};
+  if (env === "prod") {
+    return {
+      name: "prod",
+      branch: o.branch ?? cfg.github.branch,
+      ghEnvironment: o.ghEnvironment ?? PROD_GH_ENVIRONMENT,
+      appName: cfg.app,
+      stackName: o.stackName ?? cfg.stackName,
+      namespace: o.namespace ?? cfg.namespace,
+      proxyUpstream: o.proxyUpstream ?? "",
+      outputs: o.outputs ?? cfg.outputs,
+    };
+  }
+  return {
+    name: "dev",
+    branch: o.branch ?? DEV_DEFAULTS.branch,
+    ghEnvironment: o.ghEnvironment ?? DEV_DEFAULTS.ghEnvironment,
+    appName: envAppName(cfg, "dev"),
+    stackName: o.stackName ?? (cfg.stackName ? `${cfg.stackName}-dev` : ""),
+    namespace: o.namespace ?? DEV_DEFAULTS.namespace,
+    proxyUpstream: o.proxyUpstream ?? "",
+    outputs: o.outputs,
+  };
+}
+
+/** Both environments, prod first, fully resolved. */
+export function resolveEnvironments(cfg: DeployConfig): EnvDef[] {
+  return ENV_NAMES.map((e) => resolveEnvironment(cfg, e));
+}
+
+/**
+ * The browser-facing Cognito config for one environment — what `rastack dev`
+ * serves at `/__rastack/cognito.json` so a locally-running app can sign in
+ * against the real (dev) Cognito pool via the Hosted UI. Shaped to feed
+ * `cognitoRuntimeToConfig` in `rastack/auth`. Returns null until the
+ * environment's stack Outputs (client id + Hosted UI url) are known.
+ */
+export interface CognitoRuntimeConfig {
+  userPoolId?: string;
+  clientId: string;
+  /** Hosted UI base URL (`https://…amazoncognito.com`). */
+  hostedUiUrl: string;
+  region: string;
+}
+
+export function cognitoRuntimeConfig(
+  cfg: DeployConfig,
+  env: EnvName,
+): CognitoRuntimeConfig | null {
+  const o = resolveEnvironment(cfg, env).outputs;
+  if (!o?.userPoolClientId || !o?.hostedUiUrl) return null;
+  return {
+    userPoolId: o.userPoolId,
+    clientId: o.userPoolClientId,
+    hostedUiUrl: o.hostedUiUrl,
+    region: cfg.region,
+  };
+}
+
 export const DEFAULT_LAMBDA: LambdaBuild = {
   bin: "bootstrap",
   arch: "arm64",
@@ -132,9 +295,31 @@ export function normalizeConfig(
     artifactsBucket: partial.artifactsBucket?.trim() || undefined,
     tokenUse: partial.tokenUse ?? DEFAULTS.tokenUse,
     outputs: partial.outputs ? { ...partial.outputs } : undefined,
+    environments: normalizeEnvironments(partial.environments),
   };
 }
 
+/** Copy through per-environment overrides, dropping an empty map to undefined. */
+function normalizeEnvironments(
+  envs: PartialDeployConfig["environments"],
+): DeployConfig["environments"] {
+  if (!envs) return undefined;
+  const out: Partial<Record<EnvName, EnvOverride>> = {};
+  for (const name of ENV_NAMES) {
+    const o = envs[name];
+    if (!o) continue;
+    const entry: EnvOverride = {};
+    if (o.branch?.trim()) entry.branch = o.branch.trim();
+    if (o.ghEnvironment?.trim()) entry.ghEnvironment = o.ghEnvironment.trim();
+    if (o.stackName?.trim()) entry.stackName = o.stackName.trim();
+    if (o.namespace?.trim()) entry.namespace = o.namespace.trim();
+    if (o.proxyUpstream?.trim()) entry.proxyUpstream = o.proxyUpstream.trim();
+    if (o.outputs) entry.outputs = { ...o.outputs };
+    if (Object.keys(entry).length) out[name] = entry;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 const SLUG = /^[a-z0-9]{1,20}$/;
 const REGION = /^[a-z]{2}-[a-z]+-\d+$/;
 const GH_NAME = /^[A-Za-z0-9_.-]+$/;
@@ -152,6 +337,14 @@ export function validateConfig(cfg: DeployConfig): string[] {
     errors.push(
       `app "${cfg.app}" must match ${SLUG} (lowercase letters/digits, 1–20).`,
     );
+  // The dev environment appends "dev" to the app slug for its infra namespace
+  // (buckets/roles/pools/SSM). That derived name must still be a valid slug, so
+  // the app slug is effectively capped at 17 chars once a dev env is in play.
+  else if (!SLUG.test(envAppName(cfg, "dev")))
+    errors.push(
+      `app "${cfg.app}" is too long: the dev environment uses "${envAppName(cfg, "dev")}" ` +
+        `for its infra names, which must still match ${SLUG} (so app ≤ 17 chars).`,
+    );
 
   if (!SLUG.test(cfg.namePrefix))
     errors.push(`namePrefix "${cfg.namePrefix}" must match ${SLUG}.`);
@@ -226,9 +419,31 @@ export function mergeConfig(
     github: { ...base.github, ...patch.github },
     lambda: { ...base.lambda, ...patch.lambda },
     outputs: { ...base.outputs, ...patch.outputs },
+    environments: mergeEnvironments(base.environments, patch.environments),
   });
 }
 
+/** Deep-merge per-environment overrides (per env, and per env's outputs). */
+function mergeEnvironments(
+  base: DeployConfig["environments"],
+  patch: PartialDeployConfig["environments"],
+): DeployConfig["environments"] {
+  if (!base && !patch) return undefined;
+  const out: Partial<Record<EnvName, EnvOverride>> = {};
+  for (const name of ENV_NAMES) {
+    const b = base?.[name];
+    const p = patch?.[name];
+    if (!b && !p) continue;
+    out[name] = {
+      ...b,
+      ...p,
+      outputs:
+        b?.outputs || p?.outputs ? { ...b?.outputs, ...p?.outputs } : undefined,
+    };
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 /**
  * Recover `{ owner, repo }` from a GitHub remote URL — both the SSH
  * (`git@github.com:owner/repo.git`) and HTTPS
@@ -314,6 +529,40 @@ export function stackParameters(cfg: DeployConfig): StackParameter[] {
   return params;
 }
 
+/**
+ * The app.yaml `--parameter-overrides` for a **specific environment** (dev or
+ * prod). Same as `stackParameters` but the AppName/branch/namespace come from the
+ * resolved environment, and it also passes `GitHubEnvironment` so the stack's
+ * deploy-role trust is scoped to the GitHub Actions Environment (the OIDC subject
+ * for an environment-gated job is `…:environment:<env>`, not `…:ref:…`). Prod's
+ * AppName is the bare slug, so prod's resource names are byte-for-byte what the
+ * pre-environment template produced.
+ */
+export function stackParametersForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+): StackParameter[] {
+  const e = resolveEnvironment(cfg, env);
+  const params: StackParameter[] = [
+    { key: "AppName", value: e.appName },
+    { key: "NamePrefix", value: cfg.namePrefix },
+    { key: "GitHubOwner", value: cfg.github.owner },
+    { key: "GitHubRepo", value: cfg.github.repo },
+    { key: "GitHubBranch", value: e.branch },
+    { key: "GitHubEnvironment", value: e.ghEnvironment },
+    { key: "IcebergNamespace", value: e.namespace },
+  ];
+  if (cfg.artifactsBucket)
+    params.push({ key: "ArtifactsBucket", value: cfg.artifactsBucket });
+  // The external-API proxy is provisioned only when an upstream is configured
+  // (typically dev → a UAT/prod backend). Empty leaves the route/authorizer out.
+  if (e.proxyUpstream)
+    params.push({ key: "ExternalApiUpstream", value: e.proxyUpstream });
+  if (!cognitoAdvancedSecuritySupported(cfg.region))
+    params.push({ key: "AdvancedSecurity", value: "OFF" });
+  return params;
+}
+
 /**
  * The canonical repo-relative CloudFormation template paths. These are the paths
  * in the *framework* repo (theserverkid/reactapistack) and the default the argv
@@ -399,6 +648,29 @@ export function deployStackCommand(
   return awsCommand(deployStackArgs(cfg, templateFile));
 }
 
+/** The `aws cloudformation deploy` argv for one environment's stack (dev/prod). */
+export function deployStackArgsForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string[] {
+  return cfnDeployArgs(
+    templateFile,
+    resolveEnvironment(cfg, env).stackName,
+    cfg.region,
+    stackParametersForEnv(cfg, env),
+  );
+}
+
+/** The single-line `aws cloudformation deploy` command for one environment. */
+export function deployStackCommandForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string {
+  return awsCommand(deployStackArgsForEnv(cfg, env, templateFile));
+}
+
 /**
  * The tier-0 bootstrap stack (bootstrap.yaml) — the S3 buckets that hold the
  * Lambda placeholder + hosted templates, and the GitHub OIDC provider. One per
@@ -470,6 +742,9 @@ export const APP_STACK_OUTPUTS: { key: string; field: keyof DeployOutputs }[] =
     { key: "UserPoolClientId", field: "userPoolClientId" },
     { key: "JwksUrl", field: "jwksUrl" },
     { key: "WarehouseBucketName", field: "warehouseBucket" },
+    { key: "UserPoolDomain", field: "userPoolDomain" },
+    { key: "HostedUiUrl", field: "hostedUiUrl" },
+    { key: "ProxyUrl", field: "proxyUrl" },
   ];
 
 /** GitHub repo Variable to wire (name + resolved value, if known from outputs). */
@@ -477,13 +752,20 @@ export interface RepoVariable {
   name: string;
   value: string;
   from: string;
+  /**
+   * The GitHub Actions **Environment** this Variable is scoped to (`development`
+   * / `production`). When set, `init` wires it under that environment so the
+   * dev and prod deploys each read their own role/region.
+   */
+  ghEnvironment?: string;
 }
 
 /**
  * The GitHub repo **Variables** CI reads — `AWS_DEPLOY_ROLE_ARN` and
  * `AWS_REGION` (see docs/serverless-deploy.md §3). Values come from the stack
  * Outputs when already resolved, else an empty string to fill in from the
- * Console.
+ * Console. This is the legacy single-environment view (the prod stack); the
+ * dev/prod split wires them per GitHub Environment via `repoVariablesForEnv`.
  */
 export function repoVariables(cfg: DeployConfig): RepoVariable[] {
   return [
@@ -496,6 +778,33 @@ export function repoVariables(cfg: DeployConfig): RepoVariable[] {
   ];
 }
 
+/**
+ * The same two Variables, scoped to one environment's GitHub Actions
+ * Environment. The dev deploy reads `development`'s copies, the prod deploy
+ * `production`'s — so the two never cross-assume each other's role. Values come
+ * from the environment's own stack Outputs.
+ */
+export function repoVariablesForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+): RepoVariable[] {
+  const e = resolveEnvironment(cfg, env);
+  return [
+    {
+      name: "AWS_DEPLOY_ROLE_ARN",
+      value: e.outputs?.deployRoleArn ?? "",
+      from: "DeployRoleArn stack output",
+      ghEnvironment: e.ghEnvironment,
+    },
+    {
+      name: "AWS_REGION",
+      value: cfg.region,
+      from: "Region stack output",
+      ghEnvironment: e.ghEnvironment,
+    },
+  ];
+}
+
 /**
  * The argv (after `gh`) that sets one GitHub repo **Variable** on the config's
  * repo. `init` runs this for each resolved `repoVariables` entry so the
@@ -509,15 +818,39 @@ export function ghVariableSetArgs(
   cfg: DeployConfig,
   name: string,
   value: string,
+  ghEnvironment?: string,
 ): string[] {
-  return [
+  const args = [
     "variable",
     "set",
     name,
     "--repo",
     `${cfg.github.owner}/${cfg.github.repo}`,
-    "--body",
-    value,
+  ];
+  // Scope the Variable to a GitHub Actions Environment when one is given, so the
+  // dev and prod deploys each read their own role/region.
+  if (ghEnvironment) args.push("--env", ghEnvironment);
+  args.push("--body", value);
+  return args;
+}
+
+/**
+ * The argv (after `gh`) that creates (idempotently) a GitHub Actions
+ * **Environment** on the config's repo — `gh api --method PUT
+ * repos/{owner}/{repo}/environments/{env}`. `init` runs this for `development`
+ * and `production` before wiring their scoped Variables, since a Variable can
+ * only be set on an environment that already exists. PUT is idempotent, so
+ * re-running `init` is safe.
+ */
+export function ghEnvironmentCreateArgs(
+  cfg: DeployConfig,
+  ghEnvironment: string,
+): string[] {
+  return [
+    "api",
+    "--method",
+    "PUT",
+    `repos/${cfg.github.owner}/${cfg.github.repo}/environments/${ghEnvironment}`,
   ];
 }
 

package/src/deploy/io.ts

@@ -6,11 +6,20 @@
 
 import { execFileSync, execSync } from "child_process";
 import * as fs from "fs";
+import * as https from "https";
 import * as os from "os";
 import * as path from "path";
 import * as readline from "readline";
 import { CONFIG_PATH } from "./workflows";
-import { DeployConfig, PartialDeployConfig, normalizeConfig } from "./config";
+import {
+  BOOTSTRAP_ARTIFACTS_OUTPUT,
+  BOOTSTRAP_TEMPLATES_OUTPUT,
+  DeployConfig,
+  PartialDeployConfig,
+  bootstrapStackArgs,
+  bootstrapStackName,
+  normalizeConfig,
+} from "./config";
 import { zipStore } from "./zip";
 
 /** Absolute path to the deploy config for a project root. */
@@ -50,6 +59,65 @@ export function resolveDeployAsset(
   return null;
 }
 
+/**
+ * Base URL the framework's CloudFormation templates are published at. The same
+ * site that hosts the installer (`reactapistack.com/setup.sh`) serves the base
+ * templates, so a CLI whose bundled copy is missing (a partial install, or a
+ * globally-linked dev build) can still fetch them.
+ */
+export const TEMPLATE_BASE_URL = "https://reactapistack.com/cloudformation";
+
+/**
+ * Download a published CloudFormation template to a temp file, returning its
+ * path — or null on any failure (offline, 404, write error). Used as the
+ * fallback when the template is not bundled with the install.
+ */
+export function downloadTemplate(
+  name: string,
+  base = TEMPLATE_BASE_URL,
+): Promise<string | null> {
+  const url = `${base}/${name}`;
+  return new Promise((resolve) => {
+    https
+      .get(url, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            const dest = path.join(
+              os.tmpdir(),
+              `rastack-${path.basename(name)}`,
+            );
+            fs.writeFileSync(dest, Buffer.concat(chunks));
+            resolve(dest);
+          } catch {
+            resolve(null);
+          }
+        });
+      })
+      .on("error", () => resolve(null));
+  });
+}
+
+/**
+ * Resolve a CloudFormation template to a local file path for `aws cloudformation
+ * deploy` (which accepts only `--template-file`). Prefers the copy bundled with
+ * the `rastack` install; when that is missing, downloads it from the React API
+ * Stack website. Returns null only when the template is neither bundled nor
+ * fetchable.
+ */
+export async function resolveTemplateFile(
+  name: string,
+  cwd = process.cwd(),
+): Promise<string | null> {
+  return resolveDeployAsset(name, cwd) ?? (await downloadTemplate(name));
+}
+
 /** Read + normalize the deploy config, or null when it does not exist yet. */
 export function loadConfig(cwd = process.cwd()): DeployConfig | null {
   const file = configPath(cwd);
@@ -121,6 +189,26 @@ export function awsAvailable(): boolean {
   return awsCapture(["--version"]) !== null;
 }
 
+/**
+ * The AWS account id the CLI's active credentials resolve to, or null when the
+ * CLI has no usable credentials (not logged in, an expired SSO session, or no
+ * configured profile). `init`/`bootstrap` call this to fail fast with an
+ * actionable "log in" message before attempting a stack deploy, instead of
+ * letting the first `cloudformation deploy` fail with a cryptic AWS error.
+ */
+export function awsIdentity(region?: string): string | null {
+  const args = [
+    "sts",
+    "get-caller-identity",
+    "--query",
+    "Account",
+    "--output",
+    "text",
+  ];
+  if (region) args.push("--region", region);
+  return awsCapture(args);
+}
+
 /**
  * A single Output value of a CloudFormation stack, or null when the stack does
  * not exist or the key is unset. `describe-stacks` prints `None` for a missing
@@ -176,6 +264,79 @@ export function uploadPlaceholder(
   return true;
 }
 
+/**
+ * Deploy the tier-0 bootstrap stack, retrying once against an account that
+ * already has a GitHub OIDC provider — AWS allows only one provider per URL, so
+ * a second create is rejected and the retry tells the template to reuse the
+ * existing one. Throws on failure (after the retry). Shared by `rastack init`
+ * and `rastack bootstrap` so both stand the stack up identically.
+ */
+export function deployBootstrap(
+  cfg: DeployConfig,
+  reuseOidc: boolean,
+  template: string,
+): void {
+  try {
+    awsRun(bootstrapStackArgs(cfg, reuseOidc, template));
+  } catch (err) {
+    if (reuseOidc) throw err;
+    console.log(
+      "  • retrying bootstrap, reusing the account's existing GitHub OIDC provider",
+    );
+    awsRun(bootstrapStackArgs(cfg, true, template));
+  }
+}
+
+/**
+ * Ensure the tier-0 bootstrap stack exists for this account+region, **creating
+ * it when missing**, and return its artifacts/templates buckets. This is why
+ * `rastack init` is a single command that stands up *everything* — the
+ * account-level bootstrap stack and the per-app backend — with no separate
+ * `rastack bootstrap` step. Idempotent: an existing stack is reconciled in
+ * place. Throws with an actionable message when the template cannot be resolved,
+ * the deploy fails, or the buckets can't be read back.
+ */
+export async function ensureBootstrapStack(
+  cfg: DeployConfig,
+  reuseOidc = false,
+): Promise<{ artifactsBucket: string; templatesBucket: string | null }> {
+  const stack = bootstrapStackName(cfg);
+  const existing = stackOutput(stack, BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+  if (existing) {
+    console.log(`  ✓ bootstrap stack ${stack} already exists — reconciling`);
+  } else {
+    console.log(
+      `\n▸ Creating the tier-0 bootstrap stack ${stack} (@ ${cfg.region})`,
+    );
+  }
+
+  const template = await resolveTemplateFile("bootstrap.yaml");
+  if (!template) {
+    throw new Error(
+      "bootstrap.yaml template not found in the rastack package and could not be\n" +
+        "    downloaded from reactapistack.com. Reinstall rastack (`npm i -g rastack`).",
+    );
+  }
+  deployBootstrap(cfg, reuseOidc, template);
+
+  const artifactsBucket = stackOutput(
+    stack,
+    BOOTSTRAP_ARTIFACTS_OUTPUT,
+    cfg.region,
+  );
+  const templatesBucket = stackOutput(
+    stack,
+    BOOTSTRAP_TEMPLATES_OUTPUT,
+    cfg.region,
+  );
+  if (!artifactsBucket) {
+    throw new Error(
+      `bootstrap stack ${stack} deployed but its ArtifactsBucket output could not be read.`,
+    );
+  }
+  return { artifactsBucket, templatesBucket };
+}
+
 // ── GitHub CLI boundary ──────────────────────────────────────────────────────
 // After the stack is up `init` wires the two repo Variables CI reads
 // (AWS_DEPLOY_ROLE_ARN / AWS_REGION) through the developer's own `gh` — already
@@ -236,7 +397,23 @@ export function ghAuthLogin(cwd = process.cwd()): boolean {
  * `execFileSync` (no shell) so the ARN/region values are never interpolated
  * into a command line.
  */
-export function setRepoVariable(
+export function setRepoVariable(args: string[], cwd = process.cwd()): boolean {
+  try {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    execFileSync("gh", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create (idempotently, via `gh api --method PUT`) a GitHub Actions Environment
+ * so its scoped Variables can be set. Returns true on success. Best-effort — a
+ * missing/unauthenticated `gh` or an API error degrades to the printed
+ * instructions, exactly like `setRepoVariable`.
+ */
+export function ghEnvironmentCreate(
   args: string[],
   cwd = process.cwd(),
 ): boolean {