rastack 0.0.62 → 0.0.63

package/dist/deploy/ci.d.ts

@@ -15,7 +15,7 @@
  * or emitted as a live `$(aws cloudformation describe-stacks …)` substitution so
  * the same plan works before and after they are wired into the config.
  */
-import { DeployConfig } from "./config";
+import { DeployConfig, EnvName } from "./config";
 export type CiPhase = "check" | "build" | "deploy";
 export interface CiStep {
     /** Human label, echoed before the step runs. */
@@ -37,10 +37,17 @@ export interface CiPlanOptions {
     bin?: string;
     /** Skip the build steps in `deploy` (code already built this job). */
     skipBuild?: boolean;
-    /** Override the function name (else from cfg.outputs, else resolved live). */
+    /** Override the function name (else from the env's outputs, else resolved live). */
     functionName?: string;
-    /** Override the JWKS URL (else from cfg.outputs, else resolved live). */
+    /** Override the JWKS URL (else from the env's outputs, else resolved live). */
     jwksUrl?: string;
+    /**
+     * Which environment (dev/prod) to build+ship. When set, the stack name,
+     * outputs, and app label come from that environment — so `rastack ci deploy
+     * --env dev` targets the dev stack (dev's Cognito JWKS, dev's function). When
+     * unset the legacy single-stack fields (`cfg.stackName` / `cfg.outputs`) apply.
+     */
+    env?: EnvName;
 }
 /** `check` — validate the resource graph and compile the manifest. A CI gate. */
 export declare function checkSteps(cfg: DeployConfig, bin: string): CiStep[];

package/dist/deploy/ci.js

@@ -21,6 +21,7 @@ exports.checkSteps = checkSteps;
 exports.buildSteps = buildSteps;
 exports.deploySteps = deploySteps;
 exports.ciPlan = ciPlan;
+const config_1 = require("./config");
 /**
  * The in-process compile step shared by `check` and `build`: it produces
  * `schema.rastack.json` + `openapi.json` in `cfg.outDir` without a subprocess,
@@ -34,17 +35,25 @@ function compileStep(cfg) {
         action: "compile",
     };
 }
+/** The stack name + outputs + app label the plan targets, honouring `opts.env`. */
+function ciTarget(cfg, opts) {
+    if (opts.env) {
+        const e = (0, config_1.resolveEnvironment)(cfg, opts.env);
+        return { stackName: e.stackName, outputs: e.outputs, app: e.appName };
+    }
+    return { stackName: cfg.stackName, outputs: cfg.outputs, app: cfg.app };
+}
 /**
- * A stack Output value: the literal from `cfg.outputs` if wired, else a shell
- * command substitution that resolves it live from CloudFormation. Keeping the
- * fallback inline (rather than a separate step) means the plan is a flat list of
- * self-contained commands that read correctly in any order.
+ * A stack Output value: the literal if wired, else a shell command substitution
+ * that resolves it live from CloudFormation. Keeping the fallback inline (rather
+ * than a separate step) means the plan is a flat list of self-contained commands
+ * that read correctly in any order.
  */
-function stackOutput(cfg, outputKey, literal) {
+function stackOutput(stackName, region, outputKey, literal) {
     if (literal)
         return literal;
-    return (`$(aws cloudformation describe-stacks --stack-name ${cfg.stackName} ` +
-        `--region ${cfg.region} ` +
+    return (`$(aws cloudformation describe-stacks --stack-name ${stackName} ` +
+        `--region ${region} ` +
         `--query "Stacks[0].Outputs[?OutputKey=='${outputKey}'].OutputValue" ` +
         `--output text)`);
 }
@@ -69,8 +78,9 @@ function checkSteps(cfg, bin) {
  */
 function buildSteps(cfg, opts = {}) {
     const stage = stageDir(cfg);
+    const target = ciTarget(cfg, opts);
     const archFlag = cfg.lambda.arch === "arm64" ? "--arm64" : "--x86-64";
-    const jwks = stackOutput(cfg, "JwksUrl", opts.jwksUrl ?? cfg.outputs?.jwksUrl);
+    const jwks = stackOutput(target.stackName, cfg.region, "JwksUrl", opts.jwksUrl ?? target.outputs?.jwksUrl);
     return [
         compileStep(cfg),
         {
@@ -100,8 +110,9 @@ function buildSteps(cfg, opts = {}) {
 function deploySteps(cfg, opts = {}) {
     const stage = stageDir(cfg);
     const zip = `${stage}/bootstrap.zip`;
-    const fn = stackOutput(cfg, "FunctionName", opts.functionName ?? cfg.outputs?.functionName);
-    const apiUrl = stackOutput(cfg, "ApiUrl", cfg.outputs?.apiUrl);
+    const target = ciTarget(cfg, opts);
+    const fn = stackOutput(target.stackName, cfg.region, "FunctionName", opts.functionName ?? target.outputs?.functionName);
+    const apiUrl = stackOutput(target.stackName, cfg.region, "ApiUrl", target.outputs?.apiUrl);
     const steps = opts.skipBuild ? [] : buildSteps(cfg, opts);
     steps.push({
         name: "Ship the code (update-function-code)",
@@ -113,7 +124,7 @@ function deploySteps(cfg, opts = {}) {
         run: `aws lambda wait function-updated --function-name ${fn} --region ${cfg.region}`,
     }, {
         name: "Report the API URL",
-        run: `echo "Deployed ${cfg.app} → ${apiUrl}"`,
+        run: `echo "Deployed ${target.app} → ${apiUrl}"`,
     });
     return steps;
 }

package/dist/deploy/config.d.ts

@@ -32,6 +32,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 {
     /** Cargo bin built for the custom runtime (`provided.al2023`). */
@@ -41,6 +47,35 @@ export interface LambdaBuild {
     /** Cargo features the Lambda build enables. */
     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;
@@ -48,9 +83,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;
@@ -70,9 +112,80 @@ 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 declare const ENV_NAMES: readonly EnvName[];
+/** 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 declare const DEV_DEFAULTS: {
+    readonly branch: "development";
+    readonly ghEnvironment: "development";
+    readonly namespace: "development";
+};
+/** The GitHub Actions Environment name the prod deploy uses. */
+export declare 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 declare function envAppName(cfg: DeployConfig, env: EnvName): string;
+/**
+ * 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 declare function resolveEnvironment(cfg: DeployConfig, env: EnvName): EnvDef;
+/** Both environments, prod first, fully resolved. */
+export declare function resolveEnvironments(cfg: DeployConfig): EnvDef[];
+/**
+ * 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 declare function cognitoRuntimeConfig(cfg: DeployConfig, env: EnvName): CognitoRuntimeConfig | null;
 export declare const DEFAULT_LAMBDA: LambdaBuild;
 /** The out-of-the-box config — everything a fresh repo can default sensibly. */
 export declare const DEFAULTS: Omit<DeployConfig, "app" | "github">;
@@ -136,6 +249,16 @@ export declare function cognitoAdvancedSecuritySupported(region: string): boolea
  * the template's ENFORCED default stands).
  */
 export declare function stackParameters(cfg: DeployConfig): StackParameter[];
+/**
+ * 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 declare function stackParametersForEnv(cfg: DeployConfig, env: EnvName): StackParameter[];
 /**
  * The canonical repo-relative CloudFormation template paths. These are the paths
  * in the *framework* repo (theserverkid/reactapistack) and the default the argv
@@ -158,6 +281,10 @@ export declare function deployStackArgs(cfg: DeployConfig, templateFile?: string
  * for you; it is also printed by `--print` so it can be run by hand.
  */
 export declare function deployStackCommand(cfg: DeployConfig, templateFile?: string): string;
+/** The `aws cloudformation deploy` argv for one environment's stack (dev/prod). */
+export declare function deployStackArgsForEnv(cfg: DeployConfig, env: EnvName, templateFile?: string): string[];
+/** The single-line `aws cloudformation deploy` command for one environment. */
+export declare function deployStackCommandForEnv(cfg: DeployConfig, env: EnvName, templateFile?: string): string;
 /**
  * The tier-0 bootstrap stack (bootstrap.yaml) — the S3 buckets that hold the
  * Lambda placeholder + hosted templates, and the GitHub OIDC provider. One per
@@ -193,14 +320,28 @@ 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 declare 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 declare function repoVariablesForEnv(cfg: DeployConfig, env: EnvName): RepoVariable[];
 /**
  * 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
@@ -210,7 +351,16 @@ export declare function repoVariables(cfg: DeployConfig): RepoVariable[];
  * user's GitHub) rather than an API token; a pure argv so it is inspectable and
  * shell-free (`execFileSync`).
  */
-export declare function ghVariableSetArgs(cfg: DeployConfig, name: string, value: string): string[];
+export declare function ghVariableSetArgs(cfg: DeployConfig, name: string, value: string, ghEnvironment?: string): string[];
+/**
+ * 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 declare function ghEnvironmentCreateArgs(cfg: DeployConfig, ghEnvironment: string): string[];
 /**
  * The `RASTACK_*` environment the Lambda reads (docs/serverless-deploy.md §1).
  * The IaC sets these on the function; surfaced here for `rastack deploy` to

package/dist/deploy/config.js

@@ -18,7 +18,11 @@
  * thin IO wrappers that read/write the file and shell out.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APP_STACK_OUTPUTS = exports.BOOTSTRAP_TEMPLATES_OUTPUT = exports.BOOTSTRAP_ARTIFACTS_OUTPUT = exports.BOOTSTRAP_TEMPLATE_FILE = exports.APP_TEMPLATE_FILE = exports.REGIONS_WITHOUT_COGNITO_ASF = exports.DEFAULTS = exports.DEFAULT_LAMBDA = void 0;
+exports.APP_STACK_OUTPUTS = exports.BOOTSTRAP_TEMPLATES_OUTPUT = exports.BOOTSTRAP_ARTIFACTS_OUTPUT = exports.BOOTSTRAP_TEMPLATE_FILE = exports.APP_TEMPLATE_FILE = exports.REGIONS_WITHOUT_COGNITO_ASF = exports.DEFAULTS = exports.DEFAULT_LAMBDA = exports.PROD_GH_ENVIRONMENT = exports.DEV_DEFAULTS = exports.ENV_NAMES = void 0;
+exports.envAppName = envAppName;
+exports.resolveEnvironment = resolveEnvironment;
+exports.resolveEnvironments = resolveEnvironments;
+exports.cognitoRuntimeConfig = cognitoRuntimeConfig;
 exports.normalizeConfig = normalizeConfig;
 exports.validateConfig = validateConfig;
 exports.validateBootstrapConfig = validateBootstrapConfig;
@@ -26,15 +30,83 @@ exports.mergeConfig = mergeConfig;
 exports.parseGitHubRemote = parseGitHubRemote;
 exports.cognitoAdvancedSecuritySupported = cognitoAdvancedSecuritySupported;
 exports.stackParameters = stackParameters;
+exports.stackParametersForEnv = stackParametersForEnv;
 exports.deployStackArgs = deployStackArgs;
 exports.deployStackCommand = deployStackCommand;
+exports.deployStackArgsForEnv = deployStackArgsForEnv;
+exports.deployStackCommandForEnv = deployStackCommandForEnv;
 exports.bootstrapStackName = bootstrapStackName;
 exports.bootstrapStackParameters = bootstrapStackParameters;
 exports.bootstrapStackArgs = bootstrapStackArgs;
 exports.bootstrapStackCommand = bootstrapStackCommand;
 exports.repoVariables = repoVariables;
+exports.repoVariablesForEnv = repoVariablesForEnv;
 exports.ghVariableSetArgs = ghVariableSetArgs;
+exports.ghEnvironmentCreateArgs = ghEnvironmentCreateArgs;
 exports.lambdaEnv = lambdaEnv;
+exports.ENV_NAMES = ["prod", "dev"];
+/** Defaults for the dev environment when `environments.dev` is unset. */
+exports.DEV_DEFAULTS = {
+    branch: "development",
+    ghEnvironment: "development",
+    namespace: "development",
+};
+/** The GitHub Actions Environment name the prod deploy uses. */
+exports.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).
+ */
+function envAppName(cfg, env) {
+    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.
+ */
+function resolveEnvironment(cfg, env) {
+    const o = cfg.environments?.[env] ?? {};
+    if (env === "prod") {
+        return {
+            name: "prod",
+            branch: o.branch ?? cfg.github.branch,
+            ghEnvironment: o.ghEnvironment ?? exports.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 ?? exports.DEV_DEFAULTS.branch,
+        ghEnvironment: o.ghEnvironment ?? exports.DEV_DEFAULTS.ghEnvironment,
+        appName: envAppName(cfg, "dev"),
+        stackName: o.stackName ?? (cfg.stackName ? `${cfg.stackName}-dev` : ""),
+        namespace: o.namespace ?? exports.DEV_DEFAULTS.namespace,
+        proxyUpstream: o.proxyUpstream ?? "",
+        outputs: o.outputs,
+    };
+}
+/** Both environments, prod first, fully resolved. */
+function resolveEnvironments(cfg) {
+    return exports.ENV_NAMES.map((e) => resolveEnvironment(cfg, e));
+}
+function cognitoRuntimeConfig(cfg, env) {
+    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,
+    };
+}
 exports.DEFAULT_LAMBDA = {
     bin: "bootstrap",
     arch: "arm64",
@@ -82,8 +154,36 @@ function normalizeConfig(partial = {}) {
         artifactsBucket: partial.artifactsBucket?.trim() || undefined,
         tokenUse: partial.tokenUse ?? exports.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) {
+    if (!envs)
+        return undefined;
+    const out = {};
+    for (const name of exports.ENV_NAMES) {
+        const o = envs[name];
+        if (!o)
+            continue;
+        const entry = {};
+        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_.-]+$/;
@@ -99,6 +199,12 @@ function validateConfig(cfg) {
         errors.push("app is required (a short slug, e.g. `airline`).");
     else if (!SLUG.test(cfg.app))
         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}.`);
     if (!cfg.region)
@@ -158,8 +264,27 @@ function mergeConfig(base, patch) {
         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, patch) {
+    if (!base && !patch)
+        return undefined;
+    const out = {};
+    for (const name of exports.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
@@ -232,6 +357,36 @@ function stackParameters(cfg) {
         params.push({ key: "AdvancedSecurity", value: "OFF" });
     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.
+ */
+function stackParametersForEnv(cfg, env) {
+    const e = resolveEnvironment(cfg, env);
+    const params = [
+        { 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
@@ -296,6 +451,14 @@ function deployStackArgs(cfg, templateFile = exports.APP_TEMPLATE_FILE) {
 function deployStackCommand(cfg, templateFile = exports.APP_TEMPLATE_FILE) {
     return awsCommand(deployStackArgs(cfg, templateFile));
 }
+/** The `aws cloudformation deploy` argv for one environment's stack (dev/prod). */
+function deployStackArgsForEnv(cfg, env, templateFile = exports.APP_TEMPLATE_FILE) {
+    return cfnDeployArgs(templateFile, resolveEnvironment(cfg, env).stackName, cfg.region, stackParametersForEnv(cfg, env));
+}
+/** The single-line `aws cloudformation deploy` command for one environment. */
+function deployStackCommandForEnv(cfg, env, templateFile = exports.APP_TEMPLATE_FILE) {
+    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
@@ -346,12 +509,16 @@ exports.APP_STACK_OUTPUTS = [
     { key: "UserPoolClientId", field: "userPoolClientId" },
     { key: "JwksUrl", field: "jwksUrl" },
     { key: "WarehouseBucketName", field: "warehouseBucket" },
+    { key: "UserPoolDomain", field: "userPoolDomain" },
+    { key: "HostedUiUrl", field: "hostedUiUrl" },
+    { key: "ProxyUrl", field: "proxyUrl" },
 ];
 /**
  * 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`.
  */
 function repoVariables(cfg) {
     return [
@@ -363,6 +530,29 @@ function repoVariables(cfg) {
         { name: "AWS_REGION", value: cfg.region, from: "Region stack output" },
     ];
 }
+/**
+ * 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.
+ */
+function repoVariablesForEnv(cfg, env) {
+    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
@@ -372,15 +562,35 @@ function repoVariables(cfg) {
  * user's GitHub) rather than an API token; a pure argv so it is inspectable and
  * shell-free (`execFileSync`).
  */
-function ghVariableSetArgs(cfg, name, value) {
-    return [
+function ghVariableSetArgs(cfg, name, value, ghEnvironment) {
+    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.
+ */
+function ghEnvironmentCreateArgs(cfg, ghEnvironment) {
+    return [
+        "api",
+        "--method",
+        "PUT",
+        `repos/${cfg.github.owner}/${cfg.github.repo}/environments/${ghEnvironment}`,
     ];
 }
 /**

package/dist/deploy/io.d.ts

@@ -75,6 +75,13 @@ export declare function ghAuthLogin(cwd?: string): boolean;
  * into a command line.
  */
 export declare function setRepoVariable(args: string[], cwd?: string): boolean;
+/**
+ * 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 declare function ghEnvironmentCreate(args: string[], cwd?: string): boolean;
 /**
  * Ask a single question with a default, echoed as `label [default]: `. Returns
  * the trimmed answer, or the default on an empty line.