rastack 0.0.62 → 0.0.64

package/src/rastack-init.ts

@@ -12,14 +12,17 @@
  *   1. writes `.rastack/deploy.json` + `.github/workflows/{ci,deploy-backend}.yml`
  *      (GitHub coordinates default from the `origin` remote; missing fields are
  *      prompted for on a TTY);
- *   2. resolves the tier-0 bootstrap stack's artifacts bucket — erroring with a
- *      pointer to `rastack bootstrap` when that account+region stack is missing
- *      (init is per-app and never creates account-level infrastructure);
+ *   2. verifies the AWS CLI is logged in, then ensures the tier-0 bootstrap stack
+ *      exists — creating it (the S3 template/placeholder buckets + GitHub OIDC
+ *      provider) when missing, reconciling it when it already does;
  *   3. uploads the Lambda placeholder bundle to that bucket;
  *   4. deploys the per-app backend (app.yaml) with the resolved ArtifactsBucket;
  *   5. reads the stack Outputs back into the config and prints the two GitHub repo
  *      Variables CI needs.
  *
+ * The CloudFormation templates ship inside the `rastack` package; a partial
+ * install falls back to downloading them from reactapistack.com.
+ *
  * Thereafter the recurring code deploy is CI's job — `rastack ci deploy`, which
  * `rastack deploy` also runs. `--no-deploy` scaffolds only; `--print` shows the
  * exact single-line `aws cloudformation deploy` commands without running them.
@@ -30,32 +33,46 @@ import * as path from "path";
 import {
   APP_STACK_OUTPUTS,
   BOOTSTRAP_ARTIFACTS_OUTPUT,
-  BOOTSTRAP_TEMPLATES_OUTPUT,
   DeployConfig,
   DeployOutputs,
+  EnvName,
+  ENV_NAMES,
   PartialDeployConfig,
+  bootstrapStackCommand,
   bootstrapStackName,
-  deployStackArgs,
-  deployStackCommand,
+  deployStackCommandForEnv,
+  deployStackArgsForEnv,
+  ghEnvironmentCreateArgs,
   ghVariableSetArgs,
   mergeConfig,
   normalizeConfig,
   parseGitHubRemote,
-  repoVariables,
+  repoVariablesForEnv,
+  resolveEnvironment,
   validateConfig,
 } from "./deploy/config";
-import { scaffoldFiles } from "./deploy/workflows";
+import {
+  ENV_PATH,
+  GITIGNORE_PATH,
+  applyEnvValues,
+  gitignoreWith,
+  scaffoldFiles,
+} from "./deploy/workflows";
 import {
   ask,
   awsAvailable,
+  awsIdentity,
   awsRun,
   canPrompt,
+  ensureBootstrapStack,
   ghAuthLogin,
   ghAuthenticated,
   ghAvailable,
+  ghEnvironmentCreate,
   gitRemoteUrl,
   loadConfig,
   resolveDeployAsset,
+  resolveTemplateFile,
   saveConfig,
   setRepoVariable,
   stackOutput,
@@ -65,18 +82,30 @@ import {
 
 interface Flags {
   patch: PartialDeployConfig;
+  /** Which environments to stand up (default: both). */
+  envs: EnvName[];
   force: boolean;
   noWorkflows: boolean;
   noDeploy: boolean;
   print: boolean;
 }
 
+function parseEnvFlag(value: string): EnvName[] {
+  const v = value.trim().toLowerCase();
+  if (v === "all" || v === "") return [...ENV_NAMES];
+  if ((ENV_NAMES as readonly string[]).includes(v)) return [v as EnvName];
+  console.error(`Unknown --env: expected dev | prod | all.`);
+  process.exit(1);
+}
+
 function parseFlags(argv: string[]): Flags {
-  const patch: PartialDeployConfig = { github: {} };
+  const patch: PartialDeployConfig = { github: {}, environments: {} };
+  let envs: EnvName[] = [...ENV_NAMES];
   let force = false;
   let noWorkflows = false;
   let noDeploy = false;
   let print = false;
+  const devPatch = () => (patch.environments!.dev ??= {});
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const next = () => argv[++i] ?? "";
@@ -93,6 +122,17 @@ function parseFlags(argv: string[]): Flags {
       case "--branch":
         patch.github!.branch = next();
         break;
+      case "--dev-branch":
+        devPatch().branch = next();
+        break;
+      case "--dev-proxy":
+      case "--dev-proxy-upstream":
+        // The dev external-API proxy upstream (a UAT/prod backend URL).
+        devPatch().proxyUpstream = next();
+        break;
+      case "--env":
+        envs = parseEnvFlag(next());
+        break;
       case "--region":
         patch.region = next();
         break;
@@ -122,7 +162,9 @@ function parseFlags(argv: string[]): Flags {
         }
     }
   }
-  return { patch, force, noWorkflows, noDeploy, print };
+  // Drop the scratch environments container when nothing was set on it.
+  if (patch.environments && !patch.environments.dev) delete patch.environments;
+  return { patch, envs, force, noWorkflows, noDeploy, print };
 }
 
 /** Seed a config: existing file → flags → git remote → defaults. */
@@ -166,6 +208,38 @@ async function promptMissing(cfg: DeployConfig): Promise<DeployConfig> {
   });
 }
 
+/**
+ * Ensure `.env` is git-ignored and (re)write the generated `.env` with the
+ * current config, preserving any secrets a developer already added. Returns the
+ * repo-relative paths touched, for the written/skipped summary.
+ */
+function writeEnvAndGitignore(cfg: DeployConfig): string[] {
+  const touched: string[] = [];
+
+  // 1. git-ignore `.env` (append-merge; never duplicate or clobber).
+  const giAbs = path.join(process.cwd(), GITIGNORE_PATH);
+  const existingGi = fs.existsSync(giAbs)
+    ? fs.readFileSync(giAbs, "utf-8")
+    : "";
+  const nextGi = gitignoreWith(existingGi, ENV_PATH);
+  if (nextGi !== existingGi) {
+    fs.writeFileSync(giAbs, nextGi);
+    touched.push(GITIGNORE_PATH);
+  }
+
+  // 2. Upsert the generated RASTACK_* values into `.env` (secrets preserved).
+  const envAbs = path.join(process.cwd(), ENV_PATH);
+  const existingEnv = fs.existsSync(envAbs)
+    ? fs.readFileSync(envAbs, "utf-8")
+    : "";
+  const nextEnv = applyEnvValues(existingEnv, cfg);
+  if (nextEnv !== existingEnv) {
+    fs.writeFileSync(envAbs, nextEnv);
+    touched.push(ENV_PATH);
+  }
+  return touched;
+}
+
 /** Yes/no confirmation with a default of "no" — gates the cloud-mutating steps. */
 async function confirm(question: string): Promise<boolean> {
   return withPrompt(async (rl) => {
@@ -181,24 +255,44 @@ function table(rows: { key: string; value: string }[]): string {
 }
 
 /**
- * Read the app.yaml stack Outputs into a `DeployOutputs`, skipping any that are
- * not resolvable yet (best-effort — a freshly created stack has them all).
+ * Read one environment's app.yaml stack Outputs into a `DeployOutputs`, skipping
+ * any not resolvable yet (best-effort — a freshly created stack has them all).
  */
-function readAppOutputs(cfg: DeployConfig): DeployOutputs {
+function readEnvOutputs(cfg: DeployConfig, env: EnvName): DeployOutputs {
+  const stackName = resolveEnvironment(cfg, env).stackName;
   const outputs: DeployOutputs = {};
   for (const { key, field } of APP_STACK_OUTPUTS) {
-    const value = stackOutput(cfg.stackName, key, cfg.region);
+    const value = stackOutput(stackName, key, cfg.region);
     if (value) outputs[field] = value;
   }
   return outputs;
 }
 
+/** Merge an environment's resolved outputs back into the config in the right slot. */
+function withEnvOutputs(
+  cfg: DeployConfig,
+  env: EnvName,
+  outputs: DeployOutputs,
+): DeployConfig {
+  return env === "prod"
+    ? mergeConfig(cfg, { outputs })
+    : mergeConfig(cfg, { environments: { dev: { outputs } } });
+}
+
+/** Human label for an environment ("dev" / "prod") plus its branch. */
+function envLabel(cfg: DeployConfig, env: EnvName): string {
+  const e = resolveEnvironment(cfg, env);
+  return `${env} (${e.branch} → ${e.ghEnvironment})`;
+}
+
 /**
  * Print the exact commands `init` would run, without touching the cloud
- * (`--print`). The artifacts bucket is read from the bootstrap stack when the
- * AWS CLI is available, else shown as a placeholder.
+ * (`--print`). init stands up *both* stacks, so both `aws cloudformation deploy`
+ * commands are shown: the tier-0 bootstrap stack (created only when missing) and
+ * the per-app backend. The artifacts bucket is read from an existing bootstrap
+ * stack when the AWS CLI is available, else shown as a placeholder.
  */
-function printPlan(cfg: DeployConfig): void {
+function printPlan(cfg: DeployConfig, envs: EnvName[]): void {
   const bucket = awsAvailable()
     ? stackOutput(
         bootstrapStackName(cfg),
@@ -209,36 +303,50 @@ function printPlan(cfg: DeployConfig): void {
   const withBucket = mergeConfig(cfg, {
     artifactsBucket: bucket ?? "<ArtifactsBucketName from bootstrap stack>",
   });
+  const bootstrapTemplate = resolveDeployAsset("bootstrap.yaml") ?? undefined;
   const appTemplate = resolveDeployAsset("app.yaml") ?? undefined;
-  console.log(`\n  Deployment plan (${cfg.stackName} @ ${cfg.region})\n`);
-  console.log(
-    `  ── Prerequisite: the tier-0 bootstrap stack (${bootstrapStackName(cfg)}) must exist ──`,
-  );
+  console.log(`\n  Deployment plan (${envs.join(" + ")} @ ${cfg.region})\n`);
   console.log(
-    `  Create it once per account+region (init does not):  rastack bootstrap --region ${cfg.region}\n`,
+    `  ── 1. Tier-0 bootstrap stack (${bootstrapStackName(cfg)}) — created only when missing ──`,
   );
-  console.log("  ── 1. Per-app backend (app.yaml) — what init deploys ──");
-  console.log("\n  " + deployStackCommand(withBucket, appTemplate) + "\n");
+  console.log("\n  " + bootstrapStackCommand(cfg, false, bootstrapTemplate) + "\n");
   console.log(
-    "  ── 2. Wire these GitHub repo Variables from the stack Outputs ──",
+    "  ── 2. Per-app backend (app.yaml) — one stack per environment ──",
   );
+  for (const env of envs) {
+    const e = resolveEnvironment(withBucket, env);
+    console.log(`\n  # ${envLabel(withBucket, env)} — stack ${e.stackName}`);
+    console.log("  " + deployStackCommandForEnv(withBucket, env, appTemplate));
+  }
   console.log(
-    table(
-      repoVariables(cfg).map((v) => ({
-        key: v.name,
-        value: v.value || `<${v.from}>`,
-      })),
-    ) + "\n",
+    "\n  ── 2. Wire each GitHub Environment's Variables from its stack Outputs ──",
   );
+  for (const env of envs) {
+    const e = resolveEnvironment(cfg, env);
+    console.log(`\n  # GitHub Environment: ${e.ghEnvironment}`);
+    console.log(
+      table(
+        repoVariablesForEnv(cfg, env).map((v) => ({
+          key: v.name,
+          value: v.value || `<${v.from}>`,
+        })),
+      ),
+    );
+  }
+  console.log("");
 }
 
 /**
- * Stand the infrastructure up: ensure the bootstrap stack + artifacts bucket,
- * upload the Lambda placeholder, deploy app.yaml, and read the Outputs back into
- * the config. Returns the config enriched with the resolved buckets + outputs.
+ * Stand the infrastructure up: verify the AWS CLI is logged in, ensure the
+ * tier-0 bootstrap stack (creating it when missing), upload the Lambda
+ * placeholder, deploy app.yaml, and read the Outputs back into the config.
+ * `init` is the single command that stands up *everything* — there is no
+ * separate manual bootstrap step. Returns the config enriched with the resolved
+ * buckets + outputs.
  */
 async function standUp(
   cfg: DeployConfig,
+  envs: EnvName[],
   interactive: boolean,
 ): Promise<DeployConfig> {
   if (!awsAvailable()) {
@@ -249,36 +357,35 @@ async function standUp(
     process.exit(1);
   }
 
-  // 1. Resolve the artifacts bucket from the tier-0 bootstrap stack. That stack
-  //    is an account+region once-off — the S3 buckets that host the templates +
-  //    Lambda placeholder, and the GitHub OIDC provider. `init` is a per-app
-  //    command and deliberately does NOT create it: standing up account-level
-  //    infrastructure is `rastack bootstrap`'s job (run once by an account admin),
-  //    so a missing bootstrap stack is a clear, actionable error, not an implicit
-  //    account mutation buried inside an app deploy.
-  const artifactsBucket = stackOutput(
-    bootstrapStackName(cfg),
-    BOOTSTRAP_ARTIFACTS_OUTPUT,
-    cfg.region,
-  );
-  const templatesBucket = stackOutput(
-    bootstrapStackName(cfg),
-    BOOTSTRAP_TEMPLATES_OUTPUT,
-    cfg.region,
-  );
-  if (!artifactsBucket) {
+  // Verify the AWS CLI is actually logged in before creating any stacks, so a
+  // missing/expired credential fails fast with an actionable message rather than
+  // a cryptic `cloudformation deploy` error partway through.
+  const account = awsIdentity(cfg.region);
+  if (!account) {
     console.error(
-      `\n  ✗ Bootstrap stack ${bootstrapStackName(cfg)} not found in ${cfg.region}.\n` +
-        "    It is the once-per-account+region step that hosts the CloudFormation\n" +
-        "    templates and the Lambda placeholder every app deploy reads. Create it\n" +
-        "    first (an account admin does this once), then re-run `rastack init`:\n\n" +
-        `      rastack bootstrap --region ${cfg.region}\n`,
+      "  ✗ the AWS CLI has no usable credentials — it is not logged in.\n" +
+        "    Configure credentials, then re-run `rastack init`:\n" +
+        "      aws configure            # static access key / secret\n" +
+        "      aws sso login            # or an existing SSO session\n" +
+        "    Or re-run with --print to see the commands, or --no-deploy to skip.",
     );
     process.exit(1);
   }
+  console.log(`  ✓ AWS account ${account} (${cfg.region})`);
+
+  // 1. Ensure the tier-0 bootstrap stack exists — the S3 buckets that host the
+  //    templates + Lambda placeholder and the GitHub OIDC provider. init creates
+  //    it when missing (idempotent for an existing one), so a single command
+  //    takes an account+repo from nothing to a deployed backend.
+  const { artifactsBucket, templatesBucket } = await ensureBootstrapStack(
+    cfg,
+  ).catch((err: Error) => {
+    console.error(`\n  ✗ ${err.message}`);
+    process.exit(1);
+  });
   console.log(`  ✓ artifacts bucket: ${artifactsBucket}`);
 
-  // 2. Upload the placeholder the function is created from.
+  // 2. Upload the placeholder the function is created from (shared by all envs).
   console.log("\n▸ Uploading the Lambda placeholder bundle");
   if (!uploadPlaceholder(artifactsBucket, cfg.region)) {
     console.error(
@@ -287,38 +394,40 @@ async function standUp(
     process.exit(1);
   }
 
-  // 3. Deploy the per-app backend with the resolved bucket wired in.
   cfg = mergeConfig(cfg, {
     artifactsBucket,
     templatesBucket: templatesBucket ?? undefined,
   });
-  const appTemplate = resolveDeployAsset("app.yaml");
+  const appTemplate = await resolveTemplateFile("app.yaml");
   if (!appTemplate) {
     console.error(
-      "  ✗ app.yaml template not found in the rastack package. Reinstall rastack\n" +
-        "    (`npm i -g rastack`) or run from the framework repo.",
-    );
-    process.exit(1);
-  }
-  console.log(`\n▸ Deploying ${cfg.stackName}`);
-  try {
-    awsRun(deployStackArgs(cfg, appTemplate));
-  } catch (err) {
-    console.error(
-      `\n  ✗ aws cloudformation deploy failed for ${cfg.stackName}.\n    ${(err as Error).message}`,
+      "  ✗ app.yaml template not found in the rastack package and could not be\n" +
+        "    downloaded from reactapistack.com. Reinstall rastack (`npm i -g rastack`).",
     );
     process.exit(1);
   }
 
-  // 4. Read the Outputs back into the config so CI has them without a live lookup.
-  const outputs = readAppOutputs(cfg);
-  cfg = mergeConfig(cfg, { outputs });
-  saveConfig(cfg);
+  // 3. Deploy one stack per environment — each with its own Cognito pool,
+  //    warehouse, Lambda and API — reading the Outputs back into the config.
+  for (const env of envs) {
+    const stackName = resolveEnvironment(cfg, env).stackName;
+    console.log(`\n▸ Deploying ${envLabel(cfg, env)} — ${stackName}`);
+    try {
+      awsRun(deployStackArgsForEnv(cfg, env, appTemplate));
+    } catch (err) {
+      console.error(
+        `\n  ✗ aws cloudformation deploy failed for ${stackName}.\n    ${(err as Error).message}`,
+      );
+      process.exit(1);
+    }
+    cfg = withEnvOutputs(cfg, env, readEnvOutputs(cfg, env));
+    saveConfig(cfg);
+  }
 
-  // 5. Connect the GitHub CLI and wire the repo Variables CI reads, so the FIRST
-  //    push actually ships. Without this the deploy-backend workflow's `if:
-  //    vars.AWS_DEPLOY_ROLE_ARN != ''` guard silently skips every run.
-  wireRepoVariables(cfg, interactive);
+  // 4. Connect the GitHub CLI and wire each environment's scoped Variables, so
+  //    the FIRST push actually ships. Without this the deploy-backend workflow's
+  //    `if: vars.AWS_DEPLOY_ROLE_ARN != ''` guard silently skips every run.
+  wireEnvironments(cfg, envs, interactive);
   return cfg;
 }
 
@@ -333,20 +442,37 @@ async function standUp(
  * (and isn't) done.
  */
 const wiredVariables = new Set<string>();
-function wireRepoVariables(cfg: DeployConfig, interactive: boolean): void {
-  const vars = repoVariables(cfg).filter((v) => v.value);
-  if (!vars.length) return;
+
+/** Key a wired Variable by its GitHub Environment so dev/prod don't collide. */
+function wiredKey(ghEnvironment: string | undefined, name: string): string {
+  return `${ghEnvironment ?? ""}:${name}`;
+}
+
+/**
+ * Create each environment's GitHub Actions Environment and wire its scoped
+ * `AWS_DEPLOY_ROLE_ARN` / `AWS_REGION` Variables via `gh`, so the GitHub →
+ * Lambda pipeline is live for both dev and prod the moment `init` finishes.
+ */
+function wireEnvironments(
+  cfg: DeployConfig,
+  envs: EnvName[],
+  interactive: boolean,
+): void {
+  const anyValue = envs.some((env) =>
+    repoVariablesForEnv(cfg, env).some((v) => v.value),
+  );
+  if (!anyValue) return;
 
   if (!ghAvailable()) {
     console.log(
-      "\n▸ GitHub CLI (`gh`) not found — skipping repo Variable wiring.\n" +
+      "\n▸ GitHub CLI (`gh`) not found — skipping environment + Variable wiring.\n" +
         "  Install `gh` (https://cli.github.com) and re-run, or wire the\n" +
         "  Variables below by hand so pushes deploy.",
     );
     return;
   }
 
-  // Connect `gh` to GitHub if it isn't already, so it can set the Variables.
+  // Connect `gh` to GitHub if it isn't already, so it can create environments.
   if (!ghAuthenticated()) {
     if (interactive) {
       console.log(
@@ -356,53 +482,86 @@ function wireRepoVariables(cfg: DeployConfig, interactive: boolean): void {
     }
     if (!ghAuthenticated()) {
       console.log(
-        "\n▸ GitHub CLI is not connected — skipping repo Variable wiring.\n" +
+        "\n▸ GitHub CLI is not connected — skipping environment wiring.\n" +
           "  Run `gh auth login`, then wire the Variables below by hand.",
       );
       return;
     }
   }
 
-  console.log("\n▸ Wiring the GitHub repo Variables CI reads (via `gh`)");
-  for (const v of vars) {
-    const ok = setRepoVariable(ghVariableSetArgs(cfg, v.name, v.value));
-    if (ok) {
-      wiredVariables.add(v.name);
-      console.log(`  ✓ set ${v.name}`);
-    } else {
-      console.log(`  • could not set ${v.name} — wire it by hand (below)`);
+  console.log(
+    "\n▸ Creating GitHub Environments + wiring their Variables (via `gh`)",
+  );
+  for (const env of envs) {
+    const e = resolveEnvironment(cfg, env);
+    // Create the Environment first — a Variable can only be scoped to one that
+    // already exists. Idempotent (PUT), so re-running init is safe.
+    if (!ghEnvironmentCreate(ghEnvironmentCreateArgs(cfg, e.ghEnvironment))) {
+      console.log(
+        `  • could not create GitHub Environment ${e.ghEnvironment} — create it by hand`,
+      );
+      continue;
+    }
+    for (const v of repoVariablesForEnv(cfg, env).filter((x) => x.value)) {
+      const ok = setRepoVariable(
+        ghVariableSetArgs(cfg, v.name, v.value, v.ghEnvironment),
+      );
+      if (ok) {
+        wiredVariables.add(wiredKey(v.ghEnvironment, v.name));
+        console.log(`  ✓ set ${e.ghEnvironment}/${v.name}`);
+      } else {
+        console.log(
+          `  • could not set ${e.ghEnvironment}/${v.name} — wire it by hand (below)`,
+        );
+      }
     }
   }
 }
 
-function printSummary(cfg: DeployConfig): void {
-  console.log(
-    `\n  ✓ ${cfg.app} is deployed (${cfg.stackName} @ ${cfg.region})`,
-  );
-  if (cfg.outputs?.apiUrl) console.log(`    API:  ${cfg.outputs.apiUrl}`);
+function printSummary(cfg: DeployConfig, envs: EnvName[]): void {
+  console.log(`\n  ✓ ${cfg.app} is deployed @ ${cfg.region}`);
+  for (const env of envs) {
+    const e = resolveEnvironment(cfg, env);
+    console.log(`\n  ${env} — ${e.stackName}`);
+    if (e.outputs?.apiUrl) console.log(`    API:        ${e.outputs.apiUrl}`);
+    if (e.outputs?.hostedUiUrl)
+      console.log(`    Hosted UI:  ${e.outputs.hostedUiUrl}`);
+    if (e.outputs?.userPoolId)
+      console.log(`    User Pool:  ${e.outputs.userPoolId}`);
+    if (e.outputs?.proxyUrl)
+      console.log(`    Proxy:      ${e.outputs.proxyUrl}`);
+  }
 
   // Only the Variables `init` could NOT wire itself remain a manual step.
-  const pending = repoVariables(cfg).filter((v) => !wiredVariables.has(v.name));
+  const pending: { key: string; value: string }[] = [];
+  for (const env of envs) {
+    const e = resolveEnvironment(cfg, env);
+    for (const v of repoVariablesForEnv(cfg, env)) {
+      if (!wiredVariables.has(wiredKey(v.ghEnvironment, v.name)))
+        pending.push({
+          key: `${e.ghEnvironment}/${v.name}`,
+          value: v.value || `<${v.from}>`,
+        });
+    }
+  }
   if (pending.length) {
     console.log(
-      "\n  Wire these GitHub repo Variables so CI can ship code (Settings → Variables):",
-    );
-    console.log(
-      table(
-        pending.map((v) => ({
-          key: v.name,
-          value: v.value || `<${v.from}>`,
-        })),
-      ),
+      "\n  Wire these per-environment GitHub Variables so CI can ship code\n" +
+        "  (Settings → Environments → <env> → Variables):",
     );
+    console.log(table(pending));
   } else {
     console.log(
-      "\n  ✓ wired the GitHub repo Variables CI reads (AWS_DEPLOY_ROLE_ARN, AWS_REGION).",
+      "\n  ✓ wired every GitHub Environment's Variables (AWS_DEPLOY_ROLE_ARN, AWS_REGION).",
     );
   }
+
+  const dev = resolveEnvironment(cfg, "dev");
+  const prod = resolveEnvironment(cfg, "prod");
   console.log(
-    `\n  Every push to ${cfg.github.branch} now ships code via \`rastack ci deploy\`` +
-      ` (also runnable locally as \`rastack deploy\`).\n`,
+    `\n  Pushes now ship code via \`rastack ci deploy\`:\n` +
+      `    ${prod.branch} → prod (${prod.ghEnvironment})   ${dev.branch} → dev (${dev.ghEnvironment})\n` +
+      `  Run one locally with \`rastack deploy --env dev\` / \`--env prod\`.\n`,
   );
 }
 
@@ -446,6 +605,10 @@ async function main(argv: string[]): Promise<void> {
     fs.writeFileSync(abs, f.content);
     written.push(f.path);
   }
+  // The `.env` (local app environment) + its `.gitignore` entry are standard —
+  // generated on every init, secrets preserved, refreshed with Outputs post-deploy.
+  for (const p of writeEnvAndGitignore(cfg)) written.push(p);
+
   console.log("");
   for (const w of written) console.log(`  ✓ wrote ${w}`);
   for (const s of skipped)
@@ -453,7 +616,7 @@ async function main(argv: string[]): Promise<void> {
 
   // 2. Deploy (unless opted out).
   if (flags.print) {
-    printPlan(cfg);
+    printPlan(cfg, flags.envs);
     return;
   }
   if (flags.noDeploy) {
@@ -465,8 +628,11 @@ async function main(argv: string[]): Promise<void> {
   }
 
   if (canPrompt()) {
+    const stacks = flags.envs
+      .map((env) => resolveEnvironment(cfg, env).stackName)
+      .join(" + ");
     const ok = await confirm(
-      `Deploy ${cfg.stackName} to AWS ${cfg.region} now? (requires the bootstrap stack to exist) [y/N]`,
+      `Deploy ${stacks} to AWS ${cfg.region} now? (creates the bootstrap stack if missing) [y/N]`,
     );
     if (!ok) {
       console.log(
@@ -476,8 +642,10 @@ async function main(argv: string[]): Promise<void> {
     }
   }
 
-  cfg = await standUp(cfg, canPrompt());
-  printSummary(cfg);
+  cfg = await standUp(cfg, flags.envs, canPrompt());
+  // Refresh `.env` with the resolved stack Outputs (API URLs, pool/client ids).
+  for (const p of writeEnvAndGitignore(cfg)) console.log(`  ✓ updated ${p}`);
+  printSummary(cfg, flags.envs);
 }
 
 if (require.main === module) {

package/src/rastack.ts

@@ -137,6 +137,7 @@ switch (command) {
   case "deploy":
     // Ship code to the Lambda — an alias for the CI code deploy. Infrastructure
     // is stood up once by `rastack init`; `deploy` only ever ships code.
+    // `--env dev|prod` picks which environment's function to update.
     run("rastack-ci.js", ["deploy", ...rest]);
     break;
   case "ci":