rastack 0.0.38 → 0.0.40

package/dist/rastack-init.js

@@ -6,7 +6,7 @@
  *
  *   rastack init [--app <slug>] [--owner <o>] [--repo <r>] [--branch <b>]
  *                [--region <r>] [--prefix <p>] [--namespace <n>]
- *                [--force] [--no-workflows] [--no-deploy] [--print] [--yes]
+ *                [--force] [--no-workflows] [--no-deploy] [--print]
  *
  * This is the one command that takes you from nothing to deployed. It:
  *   1. writes `.rastack/deploy.json` + `.github/workflows/{ci,deploy-backend}.yml`
@@ -68,7 +68,6 @@ function parseFlags(argv) {
     let noWorkflows = false;
     let noDeploy = false;
     let print = false;
-    let nonInteractive = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         const next = () => argv[++i] ?? "";
@@ -107,11 +106,6 @@ function parseFlags(argv) {
             case "--dry-run":
                 print = true;
                 break;
-            case "--yes":
-            case "-y":
-            case "--non-interactive":
-                nonInteractive = true;
-                break;
             default:
                 if (a.startsWith("-")) {
                     console.error(`Unknown flag: ${a}`);
@@ -119,7 +113,7 @@ function parseFlags(argv) {
                 }
         }
     }
-    return { patch, force, noWorkflows, noDeploy, print, nonInteractive };
+    return { patch, force, noWorkflows, noDeploy, print };
 }
 /** Seed a config: existing file → flags → git remote → defaults. */
 function seedConfig(flags) {
@@ -209,7 +203,7 @@ function printPlan(cfg) {
  * upload the Lambda placeholder, deploy app.yaml, and read the Outputs back into
  * the config. Returns the config enriched with the resolved buckets + outputs.
  */
-async function standUp(cfg) {
+async function standUp(cfg, interactive) {
     if (!(0, io_1.awsAvailable)()) {
         console.error("  ✗ the AWS CLI is not on PATH. Install it and configure credentials,\n" +
             "    or re-run with --print to see the commands, or --no-deploy to skip.");
@@ -252,8 +246,57 @@ async function standUp(cfg) {
     const outputs = readAppOutputs(cfg);
     cfg = (0, config_1.mergeConfig)(cfg, { outputs });
     (0, io_1.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);
     return cfg;
 }
+/**
+ * Set the `AWS_DEPLOY_ROLE_ARN` / `AWS_REGION` repo Variables via `gh` so the
+ * GitHub → Lambda pipeline is live the moment `init` finishes. Connects `gh` to
+ * GitHub first — running `gh auth login` when it is installed but not yet
+ * authenticated (on a TTY) — so a fresh machine goes from nothing to a working
+ * pipeline in one command. Best-effort throughout: no `gh`, a declined login, or
+ * a value the stack Outputs did not yield falls back to the printed instructions
+ * in `printSummary`. Records the names it wired so the summary reports what is
+ * (and isn't) done.
+ */
+const wiredVariables = new Set();
+function wireRepoVariables(cfg, interactive) {
+    const vars = (0, config_1.repoVariables)(cfg).filter((v) => v.value);
+    if (!vars.length)
+        return;
+    if (!(0, io_1.ghAvailable)()) {
+        console.log("\n▸ GitHub CLI (`gh`) not found — skipping repo 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.
+    if (!(0, io_1.ghAuthenticated)()) {
+        if (interactive) {
+            console.log("\n▸ Connecting the GitHub CLI to your account (`gh auth login`)");
+            (0, io_1.ghAuthLogin)();
+        }
+        if (!(0, io_1.ghAuthenticated)()) {
+            console.log("\n▸ GitHub CLI is not connected — skipping repo Variable 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 = (0, io_1.setRepoVariable)((0, config_1.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)`);
+        }
+    }
+}
 /** Deploy the bootstrap stack, retrying once against an existing OIDC provider. */
 function deployBootstrap(cfg) {
     try {
@@ -277,26 +320,33 @@ function printSummary(cfg) {
     console.log(`\n  ✓ ${cfg.app} is deployed (${cfg.stackName} @ ${cfg.region})`);
     if (cfg.outputs?.apiUrl)
         console.log(`    API:  ${cfg.outputs.apiUrl}`);
-    console.log("\n  Wire these GitHub repo Variables so CI can ship code (Settings → Variables):");
-    console.log(table((0, config_1.repoVariables)(cfg).map((v) => ({
-        key: v.name,
-        value: v.value || `<${v.from}>`,
-    }))));
-    console.log(`\n  Then every push to ${cfg.github.branch} ships code via \`rastack ci deploy\`` +
+    // Only the Variables `init` could NOT wire itself remain a manual step.
+    const pending = (0, config_1.repoVariables)(cfg).filter((v) => !wiredVariables.has(v.name));
+    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}>`,
+        }))));
+    }
+    else {
+        console.log("\n  ✓ wired the GitHub repo Variables CI reads (AWS_DEPLOY_ROLE_ARN, AWS_REGION).");
+    }
+    console.log(`\n  Every push to ${cfg.github.branch} now ships code via \`rastack ci deploy\`` +
         ` (also runnable locally as \`rastack deploy\`).\n`);
 }
 async function main(argv) {
     const flags = parseFlags(argv);
     let cfg = seedConfig(flags);
-    if ((0, io_1.canPrompt)(flags.nonInteractive)) {
+    if ((0, io_1.canPrompt)()) {
         console.log("\n  rastack init — scaffold the deploy config + stand the backend up\n");
         cfg = await promptMissing(cfg);
     }
     const errors = (0, config_1.validateConfig)(cfg);
     // Any deploy needs a complete config; a still-incomplete one is fatal unless we
-    // are only scaffolding files.
+    // are only scaffolding files, and always fatal off a TTY (no prompt to fix it).
     if (errors.length) {
-        const fatal = !flags.noDeploy || flags.nonInteractive;
+        const fatal = !flags.noDeploy || !(0, io_1.canPrompt)();
         const label = fatal ? "✗" : "⚠";
         for (const e of errors)
             console.error(`  ${label} ${e}`);
@@ -334,14 +384,14 @@ async function main(argv) {
             `  or \`rastack init --print\` to see the exact commands.\n`);
         return;
     }
-    if ((0, io_1.canPrompt)(flags.nonInteractive)) {
+    if ((0, io_1.canPrompt)()) {
         const ok = await confirm(`Deploy ${cfg.stackName} to AWS ${cfg.region} now? (creates the bootstrap stack if needed) [y/N]`);
         if (!ok) {
             console.log("\n  Skipped the deploy. Re-run to deploy, or `rastack init --print` for the commands.\n");
             return;
         }
     }
-    cfg = await standUp(cfg);
+    cfg = await standUp(cfg, (0, io_1.canPrompt)());
     printSummary(cfg);
 }
 if (require.main === module) {

package/dist/rastack.d.ts

@@ -15,6 +15,7 @@
  *   rastack wasm                                Compile the API to WebAssembly (in-browser local dev)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
  *   rastack seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
+ *   rastack bootstrap [--owner o] [--repo r]    Stand the tier-0 AWS account stack up (once per account+region)
  *   rastack init   [--app slug] [--force]       Scaffold config + GitHub Actions AND stand the backend up
  *   rastack deploy [--plan]                     Ship code to the Lambda (alias for `rastack ci deploy`)
  *   rastack ci     <check|build|deploy> [--plan] Run the CI pipeline (keeps Actions a one-liner)

package/dist/rastack.js

@@ -16,6 +16,7 @@
  *   rastack wasm                                Compile the API to WebAssembly (in-browser local dev)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
  *   rastack seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
+ *   rastack bootstrap [--owner o] [--repo r]    Stand the tier-0 AWS account stack up (once per account+region)
  *   rastack init   [--app slug] [--force]       Scaffold config + GitHub Actions AND stand the backend up
  *   rastack deploy [--plan]                     Ship code to the Lambda (alias for `rastack ci deploy`)
  *   rastack ci     <check|build|deploy> [--plan] Run the CI pipeline (keeps Actions a one-liner)
@@ -113,6 +114,11 @@ switch (command) {
     case "seed":
         run("seed.js");
         break;
+    case "bootstrap":
+        // Stand the tier-0 bootstrap stack up (buckets + GitHub OIDC) for an AWS
+        // account — the once-per-account+region step, decoupled from any app.
+        run("rastack-bootstrap.js", rest);
+        break;
     case "init":
         // Scaffold config + GitHub Actions and stand the serverless backend up.
         run("rastack-init.js", rest);
@@ -148,6 +154,7 @@ switch (command) {
             `  rastack wasm                                Compile the API to WebAssembly (browser local dev)\n` +
             `  rastack scan   [files...] [--fail-on-pii]\n` +
             `  rastack seed   [--env dev|staging] [--source gs://bucket/ | ./myapp-dev/]\n` +
+            `  rastack bootstrap [--owner o] [--repo r] [--region r] [--prefix p] [--reuse-oidc] [--print]  Stand the AWS account stack up\n` +
             `  rastack init   [--app slug] [--owner o] [--repo r] [--print] [--no-deploy]  Scaffold + stand the backend up\n` +
             `  rastack deploy [--plan]                                       Ship code to the Lambda (alias for ci deploy)\n` +
             `  rastack ci     <check|build|deploy> [--plan]                  Run the CI pipeline (cleaner Actions)\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",

package/src/deploy/config.ts

@@ -184,6 +184,37 @@ export function validateConfig(cfg: DeployConfig): string[] {
   return errors;
 }
 
+/**
+ * Return the subset of problems that block standing the **tier-0 bootstrap
+ * stack** up. The bootstrap stack (bootstrap.yaml) is account+region scoped — it
+ * only needs the name prefix, the region, and the GitHub coordinates that anchor
+ * the OIDC trust — so `rastack bootstrap` validates just those, not the per-app
+ * fields (`app`, namespace, Lambda build) that `validateConfig` also requires.
+ */
+export function validateBootstrapConfig(cfg: DeployConfig): string[] {
+  const errors: string[] = [];
+  if (!SLUG.test(cfg.namePrefix))
+    errors.push(`namePrefix "${cfg.namePrefix}" must match ${SLUG}.`);
+
+  if (!cfg.region) errors.push("region is required (e.g. `af-south-1`).");
+  else if (!REGION.test(cfg.region))
+    errors.push(
+      `region "${cfg.region}" does not look like an AWS region (e.g. af-south-1).`,
+    );
+
+  if (!cfg.github.owner) errors.push("github.owner is required.");
+  else if (!GH_NAME.test(cfg.github.owner))
+    errors.push(
+      `github.owner "${cfg.github.owner}" is not a valid GitHub name.`,
+    );
+  if (!cfg.github.repo) errors.push("github.repo is required.");
+  else if (!GH_NAME.test(cfg.github.repo))
+    errors.push(`github.repo "${cfg.github.repo}" is not a valid GitHub name.`);
+  if (!cfg.github.branch) errors.push("github.branch is required.");
+
+  return errors;
+}
+
 /** Deep-merge a patch over a base config (used by `deploy`/`init` reconfigure). */
 export function mergeConfig(
   base: DeployConfig,
@@ -440,6 +471,31 @@ export function repoVariables(cfg: DeployConfig): 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
+ * `deploy-backend.yml` guard (`if: vars.AWS_DEPLOY_ROLE_ARN != ''`) passes and
+ * the very first push actually ships — instead of the variables being a manual
+ * Console step the user has to remember. Uses `gh` (already authenticated to the
+ * user's GitHub) rather than an API token; a pure argv so it is inspectable and
+ * shell-free (`execFileSync`).
+ */
+export function ghVariableSetArgs(
+  cfg: DeployConfig,
+  name: string,
+  value: string,
+): string[] {
+  return [
+    "variable",
+    "set",
+    name,
+    "--repo",
+    `${cfg.github.owner}/${cfg.github.repo}`,
+    "--body",
+    value,
+  ];
+}
+
 /**
  * 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/src/deploy/io.ts

@@ -55,7 +55,7 @@ export function gitRemoteUrl(cwd = process.cwd()): string | null {
 }
 
 /** True when we can prompt the user (a TTY, and not explicitly opted out). */
-export function canPrompt(nonInteractive: boolean): boolean {
+export function canPrompt(nonInteractive = false): boolean {
   return !nonInteractive && Boolean(process.stdin.isTTY);
 }
 
@@ -144,6 +144,79 @@ export function uploadPlaceholder(
   return true;
 }
 
+// ── 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
+// authenticated to their GitHub — so the pipeline fires on the first push
+// instead of leaving the wiring as a manual Console step. Best-effort: absent or
+// unauthenticated `gh` degrades to the printed instructions.
+
+/** True when the GitHub CLI is on PATH. */
+export function ghAvailable(): boolean {
+  try {
+    execFileSync("gh", ["--version"], { stdio: ["ignore", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when `gh` already holds valid credentials for github.com. `gh auth
+ * status` exits non-zero when logged out, so a thrown call means "not connected".
+ */
+export function ghAuthenticated(cwd = process.cwd()): boolean {
+  try {
+    execFileSync("gh", ["auth", "status", "--hostname", "github.com"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Connect `gh` to GitHub interactively (`gh auth login`) as part of `init`, so
+ * the repo Variables can be set right after. Streamed to the terminal — the
+ * browser/device-code flow needs the TTY — and left to `gh`'s own prompts so the
+ * user picks how to authenticate (browser or a pasted token). Returns true when
+ * the login exits 0.
+ */
+export function ghAuthLogin(cwd = process.cwd()): boolean {
+  try {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    execFileSync("gh", ["auth", "login", "--hostname", "github.com"], {
+      cwd,
+      stdio: "inherit",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Set one GitHub repo Variable via `gh variable set`. Returns true on success,
+ * false when `gh` is missing, unauthenticated, or the call otherwise fails —
+ * the caller falls back to printing the value for the user to wire by hand.
+ * `execFileSync` (no shell) so the ARN/region values are never interpolated
+ * into a command line.
+ */
+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;
+  }
+}
+
 /**
  * Ask a single question with a default, echoed as `label [default]: `. Returns
  * the trimmed answer, or the default on an empty line.

package/src/rastack-bootstrap.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+/**
+ * `rastack bootstrap` — stand the **tier-0 bootstrap stack** up for an AWS
+ * account. This is the once-per-account+region step that prepares an account to
+ * host React API Stack backends, decoupled from any single app.
+ *
+ *   rastack bootstrap [--owner <o>] [--repo <r>] [--branch <b>]
+ *                     [--region <r>] [--prefix <p>]
+ *                     [--reuse-oidc] [--print] [--yes]
+ *
+ * It deploys `deploy/cloudformation/bootstrap.yaml`, which creates:
+ *   • the S3 buckets that hold the Lambda placeholder + hosted templates, and
+ *   • the GitHub OIDC provider + trust that lets CI assume a deploy role.
+ * It then uploads the Lambda placeholder bundle to the artifacts bucket, so the
+ * account is immediately ready for per-app deploys (`rastack init`).
+ *
+ * `rastack init` still creates this stack on demand if it is missing, so
+ * `bootstrap` is the explicit, app-independent way to do the same thing up front
+ * (e.g. an account admin preparing an account before app teams run `init`).
+ * `--reuse-oidc` skips creating the GitHub OIDC provider (AWS allows only one per
+ * URL per account); `--print` shows the exact single-line `aws cloudformation
+ * deploy` command without touching the cloud.
+ */
+
+import {
+  BOOTSTRAP_ARTIFACTS_OUTPUT,
+  BOOTSTRAP_TEMPLATES_OUTPUT,
+  DeployConfig,
+  PartialDeployConfig,
+  bootstrapStackArgs,
+  bootstrapStackCommand,
+  bootstrapStackName,
+  mergeConfig,
+  normalizeConfig,
+  parseGitHubRemote,
+  validateBootstrapConfig,
+} from "./deploy/config";
+import {
+  ask,
+  awsAvailable,
+  awsRun,
+  canPrompt,
+  gitRemoteUrl,
+  loadConfig,
+  stackOutput,
+  uploadPlaceholder,
+  withPrompt,
+} from "./deploy/io";
+
+interface Flags {
+  patch: PartialDeployConfig;
+  reuseOidc: boolean;
+  print: boolean;
+  nonInteractive: boolean;
+}
+
+function parseFlags(argv: string[]): Flags {
+  const patch: PartialDeployConfig = { github: {} };
+  let reuseOidc = false;
+  let print = false;
+  let nonInteractive = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i] ?? "";
+    switch (a) {
+      case "--owner":
+        patch.github!.owner = next();
+        break;
+      case "--repo":
+        patch.github!.repo = next();
+        break;
+      case "--branch":
+        patch.github!.branch = next();
+        break;
+      case "--region":
+        patch.region = next();
+        break;
+      case "--prefix":
+        patch.namePrefix = next();
+        break;
+      case "--reuse-oidc":
+        reuseOidc = true;
+        break;
+      case "--print":
+      case "--dry-run":
+        print = true;
+        break;
+      case "--yes":
+      case "-y":
+      case "--non-interactive":
+        nonInteractive = true;
+        break;
+      default:
+        if (a.startsWith("-")) {
+          console.error(`Unknown flag: ${a}`);
+          process.exit(1);
+        }
+    }
+  }
+  return { patch, reuseOidc, print, nonInteractive };
+}
+
+/** Seed a config: existing file → flags → git remote → defaults. */
+function seedConfig(flags: Flags): DeployConfig {
+  const existing = loadConfig();
+  let cfg = existing
+    ? mergeConfig(existing, flags.patch)
+    : normalizeConfig(flags.patch);
+  // Default the GitHub coordinates from `origin` when not already known — they
+  // anchor the OIDC trust the bootstrap stack sets up.
+  if (!cfg.github.owner || !cfg.github.repo) {
+    const url = gitRemoteUrl();
+    const remote = url ? parseGitHubRemote(url) : null;
+    if (remote) {
+      cfg = mergeConfig(cfg, {
+        github: {
+          owner: cfg.github.owner || remote.owner,
+          repo: cfg.github.repo || remote.repo,
+        },
+      });
+    }
+  }
+  return cfg;
+}
+
+async function promptMissing(cfg: DeployConfig): Promise<DeployConfig> {
+  return withPrompt(async (rl) => {
+    const owner = await ask(rl, "GitHub owner", cfg.github.owner);
+    const repo = await ask(rl, "GitHub repo", cfg.github.repo);
+    const branch = await ask(rl, "Deploy branch", cfg.github.branch);
+    const region = await ask(rl, "AWS region", cfg.region);
+    const prefix = await ask(rl, "Name prefix", cfg.namePrefix);
+    return mergeConfig(cfg, {
+      region,
+      namePrefix: prefix,
+      github: { owner, repo, branch },
+    });
+  });
+}
+
+/** Yes/no confirmation with a default of "no" — gates the cloud-mutating step. */
+async function confirm(question: string): Promise<boolean> {
+  return withPrompt(async (rl) => {
+    const answer = await ask(rl, question, "no");
+    return /^y(es)?$/i.test(answer.trim());
+  });
+}
+
+/** Print the exact command `bootstrap` would run, without touching the cloud. */
+function printPlan(cfg: DeployConfig, reuseOidc: boolean): void {
+  console.log(
+    `\n  Bootstrap plan (${bootstrapStackName(cfg)} @ ${cfg.region})\n`,
+  );
+  console.log("  ── Tier-0 bootstrap stack (bootstrap.yaml) ──");
+  console.log("\n  " + bootstrapStackCommand(cfg, reuseOidc) + "\n");
+  console.log(
+    "  Then `rastack init` (or `rastack bootstrap` again) resolves this stack's\n" +
+      "  ArtifactsBucket to create app backends. Nothing here is app-specific.\n",
+  );
+}
+
+/**
+ * Deploy the bootstrap stack, retrying once against an account that already has
+ * a GitHub OIDC provider (AWS allows only one per URL) when the caller did not
+ * already ask to reuse it.
+ */
+function deployBootstrap(cfg: DeployConfig, reuseOidc: boolean): void {
+  try {
+    awsRun(bootstrapStackArgs(cfg, reuseOidc));
+  } catch (err) {
+    if (reuseOidc) {
+      console.error(
+        `\n  ✗ bootstrap stack deploy failed.\n    ${(err as Error).message}`,
+      );
+      process.exit(1);
+    }
+    // The most common cause is an account that already has a GitHub OIDC
+    // provider. Retry telling the template to reuse it instead of creating a
+    // second (which CloudFormation rejects).
+    console.log(
+      "  • retrying bootstrap, reusing the account's existing GitHub OIDC provider",
+    );
+    try {
+      awsRun(bootstrapStackArgs(cfg, true));
+    } catch (retryErr) {
+      console.error(
+        `\n  ✗ bootstrap stack deploy failed.\n    ${(retryErr as Error).message}`,
+      );
+      process.exit(1);
+    }
+  }
+}
+
+/** Stand the tier-0 bootstrap stack up and upload the Lambda placeholder. */
+function standUp(cfg: DeployConfig, reuseOidc: boolean): void {
+  if (!awsAvailable()) {
+    console.error(
+      "  ✗ the AWS CLI is not on PATH. Install it and configure credentials,\n" +
+        "    or re-run with --print to see the command.",
+    );
+    process.exit(1);
+  }
+
+  const stack = bootstrapStackName(cfg);
+  const existing = stackOutput(stack, BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+  if (existing) {
+    console.log(
+      `\n▸ Bootstrap stack ${stack} already exists — reconciling (idempotent).`,
+    );
+  } else {
+    console.log(`\n▸ Creating bootstrap stack ${stack} (@ ${cfg.region})`);
+  }
+  deployBootstrap(cfg, reuseOidc);
+
+  const artifactsBucket = stackOutput(
+    stack,
+    BOOTSTRAP_ARTIFACTS_OUTPUT,
+    cfg.region,
+  );
+  const templatesBucket = stackOutput(
+    stack,
+    BOOTSTRAP_TEMPLATES_OUTPUT,
+    cfg.region,
+  );
+  if (!artifactsBucket) {
+    console.error(
+      "  ✗ bootstrap stack deployed but its ArtifactsBucket output could not be read.",
+    );
+    process.exit(1);
+  }
+  console.log(`  ✓ artifacts bucket:  ${artifactsBucket}`);
+  if (templatesBucket) console.log(`  ✓ templates bucket:  ${templatesBucket}`);
+
+  // Upload the placeholder the app.yaml function is later created from, so the
+  // account is ready for `rastack init` without a second manual step.
+  console.log("\n▸ Uploading the Lambda placeholder bundle");
+  if (!uploadPlaceholder(artifactsBucket, cfg.region)) {
+    console.error(
+      "  ✗ deploy/cloudformation/placeholder/bootstrap not found — the placeholder\n" +
+        "    was not uploaded. `rastack init` will upload it on the first app deploy.",
+    );
+  } else {
+    console.log("  ✓ placeholder uploaded");
+  }
+
+  console.log(
+    `\n  ✓ account bootstrapped (${stack} @ ${cfg.region}).\n` +
+      `    Run \`rastack init\` in an app repo to deploy a backend against it.\n`,
+  );
+}
+
+async function main(argv: string[]): Promise<void> {
+  const flags = parseFlags(argv);
+  let cfg = seedConfig(flags);
+
+  if (canPrompt(flags.nonInteractive) && !flags.print) {
+    console.log(
+      "\n  rastack bootstrap — stand the tier-0 AWS account stack up\n",
+    );
+    cfg = await promptMissing(cfg);
+  }
+
+  const errors = validateBootstrapConfig(cfg);
+  if (errors.length) {
+    for (const e of errors) console.error(`  ✗ ${e}`);
+    console.error(
+      `\n  ${errors.length} problem(s). Pass the missing values as flags` +
+        ` (--owner, --repo, --branch, --region, --prefix).`,
+    );
+    process.exit(1);
+  }
+
+  if (flags.print) {
+    printPlan(cfg, flags.reuseOidc);
+    return;
+  }
+
+  if (canPrompt(flags.nonInteractive)) {
+    const ok = await confirm(
+      `Create/update bootstrap stack ${bootstrapStackName(cfg)} in AWS ${cfg.region} now? [y/N]`,
+    );
+    if (!ok) {
+      console.log(
+        "\n  Skipped. Re-run to deploy, or `rastack bootstrap --print` for the command.\n",
+      );
+      return;
+    }
+  }
+
+  standUp(cfg, flags.reuseOidc);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(`  ✗ ${(err as Error).message}`);
+    process.exit(1);
+  });
+}