rastack 0.0.62 → 0.0.64

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

@@ -22,6 +22,27 @@ export declare function configPath(cwd?: string): string;
  * repo itself still works. Returns null when no candidate exists.
  */
 export declare function resolveDeployAsset(relPath: string, cwd?: string): string | 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 declare 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 declare function downloadTemplate(name: string, base?: string): Promise<string | 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 declare function resolveTemplateFile(name: string, cwd?: string): Promise<string | null>;
 /** Read + normalize the deploy config, or null when it does not exist yet. */
 export declare function loadConfig(cwd?: string): DeployConfig | null;
 /** Write the deploy config, creating `.rastack/` if needed. */
@@ -39,6 +60,14 @@ export declare function awsCapture(args: string[], cwd?: string): string | null;
 export declare function awsRun(args: string[], cwd?: string): void;
 /** True when the AWS CLI is on PATH. */
 export declare function awsAvailable(): boolean;
+/**
+ * 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 declare function awsIdentity(region?: string): string | null;
 /**
  * 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
@@ -52,6 +81,27 @@ export declare function stackOutput(stackName: string, key: string, region: stri
  * on every `init`. Returns false when the placeholder file is missing.
  */
 export declare function uploadPlaceholder(artifactsBucket: string, region: string, cwd?: string): boolean;
+/**
+ * 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 declare function deployBootstrap(cfg: DeployConfig, reuseOidc: boolean, template: string): void;
+/**
+ * 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 declare function ensureBootstrapStack(cfg: DeployConfig, reuseOidc?: boolean): Promise<{
+    artifactsBucket: string;
+    templatesBucket: string | null;
+}>;
 /** True when the GitHub CLI is on PATH. */
 export declare function ghAvailable(): boolean;
 /**
@@ -75,6 +125,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.

package/dist/deploy/io.js

@@ -38,8 +38,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATE_BASE_URL = void 0;
 exports.configPath = configPath;
 exports.resolveDeployAsset = resolveDeployAsset;
+exports.downloadTemplate = downloadTemplate;
+exports.resolveTemplateFile = resolveTemplateFile;
 exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
 exports.gitRemoteUrl = gitRemoteUrl;
@@ -47,16 +50,21 @@ exports.canPrompt = canPrompt;
 exports.awsCapture = awsCapture;
 exports.awsRun = awsRun;
 exports.awsAvailable = awsAvailable;
+exports.awsIdentity = awsIdentity;
 exports.stackOutput = stackOutput;
 exports.uploadPlaceholder = uploadPlaceholder;
+exports.deployBootstrap = deployBootstrap;
+exports.ensureBootstrapStack = ensureBootstrapStack;
 exports.ghAvailable = ghAvailable;
 exports.ghAuthenticated = ghAuthenticated;
 exports.ghAuthLogin = ghAuthLogin;
 exports.setRepoVariable = setRepoVariable;
+exports.ghEnvironmentCreate = ghEnvironmentCreate;
 exports.ask = ask;
 exports.withPrompt = withPrompt;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const https = __importStar(require("https"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
@@ -96,6 +104,54 @@ function resolveDeployAsset(relPath, cwd = process.cwd()) {
     }
     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.
+ */
+exports.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.
+ */
+function downloadTemplate(name, base = exports.TEMPLATE_BASE_URL) {
+    const url = `${base}/${name}`;
+    return new Promise((resolve) => {
+        https
+            .get(url, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            const chunks = [];
+            res.on("data", (c) => 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.
+ */
+async function resolveTemplateFile(name, cwd = process.cwd()) {
+    return resolveDeployAsset(name, cwd) ?? (await downloadTemplate(name));
+}
 /** Read + normalize the deploy config, or null when it does not exist yet. */
 function loadConfig(cwd = process.cwd()) {
     const file = configPath(cwd);
@@ -162,6 +218,26 @@ function awsRun(args, cwd = process.cwd()) {
 function awsAvailable() {
     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.
+ */
+function awsIdentity(region) {
+    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
@@ -209,6 +285,55 @@ function uploadPlaceholder(artifactsBucket, region, cwd = process.cwd()) {
     ]);
     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.
+ */
+function deployBootstrap(cfg, reuseOidc, template) {
+    try {
+        awsRun((0, config_1.bootstrapStackArgs)(cfg, reuseOidc, template));
+    }
+    catch (err) {
+        if (reuseOidc)
+            throw err;
+        console.log("  • retrying bootstrap, reusing the account's existing GitHub OIDC provider");
+        awsRun((0, config_1.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.
+ */
+async function ensureBootstrapStack(cfg, reuseOidc = false) {
+    const stack = (0, config_1.bootstrapStackName)(cfg);
+    const existing = stackOutput(stack, config_1.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, config_1.BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+    const templatesBucket = stackOutput(stack, config_1.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
@@ -278,6 +403,22 @@ function setRepoVariable(args, cwd = process.cwd()) {
         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`.
+ */
+function ghEnvironmentCreate(args, cwd = process.cwd()) {
+    try {
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        (0, child_process_1.execFileSync)("gh", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Ask a single question with a default, echoed as `label [default]: `. Returns
  * the trimmed answer, or the default on an empty line.

package/dist/deploy/workflows.d.ts

@@ -34,6 +34,36 @@ export declare function renderConfigFile(cfg: DeployConfig): string;
 export declare const CONFIG_PATH = ".rastack/deploy.json";
 export declare const CI_WORKFLOW_PATH = ".github/workflows/ci.yml";
 export declare const DEPLOY_WORKFLOW_PATH = ".github/workflows/deploy-backend.yml";
+export declare const ENV_PATH = ".env";
+export declare const GITIGNORE_PATH = ".gitignore";
+/**
+ * The generated `.env` — the app's **local** environment. Every value is
+ * non-secret (client ids, pool ids, public URLs from the stack Outputs), but the
+ * file is git-ignored by convention (`gitignoreWith`) so a developer can add
+ * their own secrets beside these without ever committing them. Values are blank
+ * until the matching stack is deployed; `rastack init` rewrites the file with the
+ * resolved Outputs after standing the backends up.
+ *
+ * Keys are `RASTACK_<ENV>_*` (a neutral prefix). For a browser bundle, re-export
+ * the ones you need under your bundler's public prefix (EXPO_PUBLIC_/VITE_/…);
+ * `rastack dev` also serves the dev pool config live at `/__rastack/cognito.json`.
+ */
+export declare function renderEnvFile(cfg: DeployConfig): string;
+/**
+ * Upsert the generated `RASTACK_*` keys from `renderEnvFile(cfg)` into an
+ * existing `.env`, preserving every other line (a developer's own secrets,
+ * comments, extra keys). A matching `RASTACK_*=` line is updated in place;
+ * generated keys not yet present are appended. When there is no existing file,
+ * this is exactly `renderEnvFile(cfg)`. Pure — the IO wrapper reads/writes.
+ */
+export declare function applyEnvValues(existing: string, cfg: DeployConfig): string;
+/**
+ * Return `.gitignore` content with a `.env` entry present (idempotent). Appends
+ * under a labelled block when missing, leaves the file untouched when `.env` is
+ * already ignored — so `rastack init` never duplicates the entry or clobbers a
+ * developer's existing ignore rules.
+ */
+export declare function gitignoreWith(existing: string, entry?: string): string;
 export interface ScaffoldOptions {
     /** Omit the GitHub Actions workflows (config only). */
     noWorkflows?: boolean;