rastack 0.0.41 → 0.0.43

package/dist/templates/cloudformation/bootstrap.yaml

@@ -0,0 +1,342 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >-
+  React API Stack bootstrap (tier-0). Creates the account+region S3 buckets that
+  host the framework CloudFormation templates and the Lambda placeholder, plus a
+  least-privilege GitHub OIDC publisher role. Run once per account and region.
+
+# ---------------------------------------------------------------------------
+# Parameters — everything that varies between accounts / forks lives here, so
+# the same template bootstraps any account without edits.
+# ---------------------------------------------------------------------------
+Parameters:
+  NamePrefix:
+    Type: String
+    Default: rastack
+    Description: Prefix for the bucket names and the publisher role.
+    # No hyphens, matching app.yaml (its NamePrefix feeds a Cognito name).
+    AllowedPattern: "^[a-z0-9]{1,20}$"
+
+  GitHubOwner:
+    Type: String
+    Default: theserverkid
+    Description: GitHub org/user that owns the framework repo allowed to publish.
+
+  PublisherRepo:
+    Type: String
+    Default: reactapistack
+    Description: >
+      The single repository whose CI (via OIDC) may publish templates/artifacts
+      into these buckets. Only this repo's workflows can assume the publisher
+      role — nothing else, and no long-lived keys.
+
+  PublisherBranch:
+    Type: String
+    Default: master
+    Description: Branch of PublisherRepo whose workflow may assume the publisher role.
+
+  CreateOIDCProvider:
+    Type: String
+    Default: "true"
+    AllowedValues: ["true", "false"]
+    Description: >
+      Create the GitHub Actions OIDC provider. Set "false" if the account
+      already has one (an account may have only a single provider per URL) and
+      pass its ARN in ExistingOIDCProviderArn.
+
+  ExistingOIDCProviderArn:
+    Type: String
+    Default: ""
+    Description: ARN of a pre-existing GitHub OIDC provider (when CreateOIDCProvider=false).
+
+  ReadableByAccount:
+    Type: String
+    Default: "true"
+    AllowedValues: ["true", "false"]
+    Description: >
+      Grant s3:GetObject on both buckets to the account root, so any IAM
+      principal in THIS account can launch a hosted template / read the
+      placeholder artifact from the Console without an extra identity policy.
+      Public (internet) access stays blocked regardless — account-root is not
+      public.
+
+Conditions:
+  ShouldCreateOIDCProvider: !Equals [!Ref CreateOIDCProvider, "true"]
+  GrantAccountRead: !Equals [!Ref ReadableByAccount, "true"]
+  HasExistingOIDCArn: !Not [!Equals [!Ref ExistingOIDCProviderArn, ""]]
+
+Resources:
+
+  # -- GitHub OIDC provider ----------------------------------------------------
+  # Short-lived OIDC tokens instead of stored AWS keys. Reused by the per-app
+  # deploy role (app.yaml) too; created here once so tier-0 owns the trust root.
+  GitHubOIDCProvider:
+    Type: AWS::IAM::OIDCProvider
+    Condition: ShouldCreateOIDCProvider
+    Properties:
+      Url: https://token.actions.githubusercontent.com
+      ClientIdList:
+        - sts.amazonaws.com
+      # AWS no longer validates these thumbprints for the GitHub host, but the
+      # property is still required; both historically-published values are listed.
+      ThumbprintList:
+        - 6938fd4d98bab03faadb97b34396831e3780aea1
+        - 1c58a3a8518e8759bf075b76b750d4f2df264fca
+
+  # -- Templates bucket --------------------------------------------------------
+  # Hosts the *.yaml CloudFormation templates (app.yaml + future ones). Private,
+  # versioned, encrypted, TLS-only, public access fully blocked. CloudFormation
+  # reads a template referenced by S3 URL using the *deployer's* credentials, so
+  # no public read is needed for a Console "Launch Stack" within the account.
+  TemplatesBucket:
+    Type: AWS::S3::Bucket
+    # The template store is durable and shared across every consumer stack —
+    # never let a `delete-stack` of the bootstrap take it (and its version
+    # history) down with it.
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      BucketName: !Sub "${NamePrefix}-cloudformation-${AWS::AccountId}-${AWS::Region}"
+      VersioningConfiguration:
+        Status: Enabled
+      BucketEncryption:
+        ServerSideEncryptionConfiguration:
+          - ServerSideEncryptionByDefault:
+              SSEAlgorithm: AES256
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+      OwnershipControls:
+        Rules:
+          - ObjectOwnership: BucketOwnerEnforced
+      LifecycleConfiguration:
+        Rules:
+          - Id: expire-noncurrent-template-versions
+            Status: Enabled
+            NoncurrentVersionExpiration:
+              NoncurrentDays: 30
+            AbortIncompleteMultipartUpload:
+              DaysAfterInitiation: 7
+
+  TemplatesBucketPolicy:
+    Type: AWS::S3::BucketPolicy
+    Properties:
+      Bucket: !Ref TemplatesBucket
+      PolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: DenyInsecureTransport
+            Effect: Deny
+            Principal: "*"
+            Action: "s3:*"
+            Resource:
+              - !GetAtt TemplatesBucket.Arn
+              - !Sub "${TemplatesBucket.Arn}/*"
+            Condition:
+              Bool:
+                aws:SecureTransport: "false"
+          - !If
+            - GrantAccountRead
+            - Sid: AccountReadTemplates
+              Effect: Allow
+              Principal:
+                AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
+              Action:
+                - s3:GetObject
+                - s3:ListBucket
+              Resource:
+                - !GetAtt TemplatesBucket.Arn
+                - !Sub "${TemplatesBucket.Arn}/*"
+            - !Ref "AWS::NoValue"
+
+  # -- Artifacts bucket --------------------------------------------------------
+  # Hosts the Lambda placeholder bundle (placeholders/bootstrap.zip) that the
+  # per-app template's function is created from, plus any build artifacts CI
+  # stages. Same hardening as the templates bucket.
+  ArtifactsBucket:
+    Type: AWS::S3::Bucket
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      BucketName: !Sub "${NamePrefix}-artifacts-${AWS::AccountId}-${AWS::Region}"
+      VersioningConfiguration:
+        Status: Enabled
+      BucketEncryption:
+        ServerSideEncryptionConfiguration:
+          - ServerSideEncryptionByDefault:
+              SSEAlgorithm: AES256
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+      OwnershipControls:
+        Rules:
+          - ObjectOwnership: BucketOwnerEnforced
+      LifecycleConfiguration:
+        Rules:
+          - Id: expire-noncurrent-artifact-versions
+            Status: Enabled
+            NoncurrentVersionExpiration:
+              NoncurrentDays: 30
+            AbortIncompleteMultipartUpload:
+              DaysAfterInitiation: 7
+
+  ArtifactsBucketPolicy:
+    Type: AWS::S3::BucketPolicy
+    Properties:
+      Bucket: !Ref ArtifactsBucket
+      PolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: DenyInsecureTransport
+            Effect: Deny
+            Principal: "*"
+            Action: "s3:*"
+            Resource:
+              - !GetAtt ArtifactsBucket.Arn
+              - !Sub "${ArtifactsBucket.Arn}/*"
+            Condition:
+              Bool:
+                aws:SecureTransport: "false"
+          - !If
+            - GrantAccountRead
+            - Sid: AccountReadArtifacts
+              Effect: Allow
+              Principal:
+                AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
+              Action:
+                - s3:GetObject
+                - s3:ListBucket
+              Resource:
+                - !GetAtt ArtifactsBucket.Arn
+                - !Sub "${ArtifactsBucket.Arn}/*"
+            - !Ref "AWS::NoValue"
+
+  # -- Publisher role (GitHub OIDC) --------------------------------------------
+  # The framework's CI assumes THIS role (no stored keys) to sync the templates
+  # and the placeholder artifact into the two buckets. Its trust is pinned to a
+  # single repo+branch, and its permission grant is scoped to exactly these two
+  # buckets — plus an explicit deny that stops it re-governing them or escalating.
+  TemplatePublisherRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub "${NamePrefix}-template-publisher"
+      Description: CI role that publishes React API Stack templates + artifacts.
+      MaxSessionDuration: 3600
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              # When reusing an existing provider but no ARN was passed, derive
+              # the account's single standard GitHub provider ARN — never an
+              # empty principal (which IAM rejects as MalformedPolicyDocument).
+              Federated: !If
+                - ShouldCreateOIDCProvider
+                - !Ref GitHubOIDCProvider
+                - !If
+                  - HasExistingOIDCArn
+                  - !Ref ExistingOIDCProviderArn
+                  - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:oidc-provider/token.actions.githubusercontent.com"
+            Action: sts:AssumeRoleWithWebIdentity
+            Condition:
+              StringEquals:
+                token.actions.githubusercontent.com:aud: sts.amazonaws.com
+              StringLike:
+                token.actions.githubusercontent.com:sub: !Sub "repo:${GitHubOwner}/${PublisherRepo}:ref:refs/heads/${PublisherBranch}"
+      Policies:
+        - PolicyName: publish-to-template-buckets
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Sid: WriteObjects
+                Effect: Allow
+                Action:
+                  - s3:PutObject
+                  - s3:GetObject
+                  - s3:DeleteObject
+                Resource:
+                  - !Sub "${TemplatesBucket.Arn}/*"
+                  - !Sub "${ArtifactsBucket.Arn}/*"
+              - Sid: ListBuckets
+                Effect: Allow
+                Action:
+                  - s3:ListBucket
+                  - s3:GetBucketLocation
+                Resource:
+                  - !GetAtt TemplatesBucket.Arn
+                  - !GetAtt ArtifactsBucket.Arn
+        - PolicyName: deny-privilege-escalation
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              # Defense-in-depth: a compromised publish workflow can only write
+              # template/artifact objects. It can never re-govern the buckets,
+              # touch identity, or grant itself anything more.
+              - Sid: DenyPrivilegeEscalation
+                Effect: Deny
+                Action:
+                  - iam:*
+                  - sts:AssumeRole
+                  - organizations:*
+                  - account:*
+                  - s3:PutBucketPolicy
+                  - s3:DeleteBucketPolicy
+                  - s3:PutBucketPublicAccessBlock
+                  - s3:PutBucketAcl
+                  - s3:PutObjectAcl
+                  - s3:DeleteBucket
+                Resource: "*"
+
+Outputs:
+  TemplatesBucketName:
+    Description: S3 bucket hosting the CloudFormation templates.
+    Value: !Ref TemplatesBucket
+    Export:
+      Name: !Sub "${AWS::StackName}-TemplatesBucket"
+
+  TemplatesBaseUrl:
+    Description: Base HTTPS URL of the templates bucket (append the object key).
+    Value: !Sub "https://${TemplatesBucket}.s3.${AWS::Region}.amazonaws.com"
+
+  AppTemplateUrl:
+    Description: >
+      URL the per-app backend template will live at once published
+      (deploy/cloudformation/app.yaml → app.yaml). Consumer repos launch from this.
+    Value: !Sub "https://${TemplatesBucket}.s3.${AWS::Region}.amazonaws.com/app.yaml"
+
+  LaunchAppStackUrl:
+    Description: >
+      One-click Console "Launch Stack" (quick-create) link for the hosted app
+      template. Fill in GitHubRepo/AppName parameters on the review screen.
+    Value: !Sub "https://${AWS::Region}.console.aws.amazon.com/cloudformation/home?region=${AWS::Region}#/stacks/create/review?templateURL=https://${TemplatesBucket}.s3.${AWS::Region}.amazonaws.com/app.yaml&stackName=rastack-app"
+
+  ArtifactsBucketName:
+    Description: S3 bucket hosting the Lambda placeholder + build artifacts.
+    Value: !Ref ArtifactsBucket
+    Export:
+      Name: !Sub "${AWS::StackName}-ArtifactsBucket"
+
+  ArtifactsBaseUrl:
+    Description: Base HTTPS URL of the artifacts bucket.
+    Value: !Sub "https://${ArtifactsBucket}.s3.${AWS::Region}.amazonaws.com"
+
+  PublisherRoleArn:
+    Description: >
+      Role ARN the framework CI assumes via OIDC to publish templates/artifacts.
+      Wire as the AWS_PUBLISH_ROLE_ARN repo Variable in the framework repo.
+    Value: !GetAtt TemplatePublisherRole.Arn
+    Export:
+      Name: !Sub "${AWS::StackName}-PublisherRoleArn"
+
+  OIDCProviderArn:
+    Description: GitHub OIDC provider ARN (created or reused) — reuse in app.yaml.
+    Value: !If
+      - ShouldCreateOIDCProvider
+      - !Ref GitHubOIDCProvider
+      - !If
+        - HasExistingOIDCArn
+        - !Ref ExistingOIDCProviderArn
+        - !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:oidc-provider/token.actions.githubusercontent.com"

package/dist/templates/cloudformation/placeholder/bootstrap

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Placeholder React API Stack Lambda bootstrap (provided.al2023 custom runtime).
+#
+# Its one guaranteed job: be a valid code bundle so app.yaml can CREATE the
+# function with no Rust toolchain (Lambda does not execute this at create time).
+# CI then replaces it out of band with the compiled rastack-server via
+# `aws lambda update-function-code`; app.yaml pins a fixed Code.S3Key, so stack
+# updates never revert what CI shipped.
+#
+# Best-effort until real code lands: if the (minimal) runtime has curl, every
+# invocation returns a clear 503 rather than an opaque error. The placeholder is
+# never meant to serve real traffic — deploy the backend before pointing at it.
+set -eu
+
+while true; do
+  HEADERS="$(mktemp)"
+  # Long-poll for the next invocation.
+  curl -sS -LD "$HEADERS" -o /dev/null \
+    "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"
+  REQUEST_ID="$(grep -Fi 'Lambda-Runtime-Aws-Request-Id' "$HEADERS" \
+    | tr -d '[:space:]' | cut -d: -f2)"
+  [ -n "${REQUEST_ID}" ] || continue
+
+  RESPONSE='{"statusCode":503,"headers":{"content-type":"application/json"},"body":"{\"detail\":\"React API Stack backend not yet deployed — CI has not shipped the rastack-server bundle to this function.\"}"}'
+  curl -sS -o /dev/null \
+    "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/${REQUEST_ID}/response" \
+    -d "${RESPONSE}"
+done

package/dist/update.d.ts

@@ -52,6 +52,17 @@ export declare function npmBinary(platform?: string): string;
  * shell means no injection surface).
  */
 export declare function npmSpawnShell(platform?: string): boolean;
+/**
+ * The single command string used to launch npm on platforms that must go through
+ * a shell (Windows — see `npmSpawnShell`). Node 22+ deprecates passing an args
+ * *array* together with `shell: true` (DEP0190: the args are concatenated, not
+ * escaped), so the shell path builds one string and runs it via `execSync`
+ * instead. Joining with spaces is safe here because every token is a fixed
+ * literal except the version, which `sanitizeVersion` constrains to
+ * `[A-Za-z0-9._-]` (no shell metacharacters). POSIX never uses this — it keeps
+ * the shell-free, array-based `execFile`, which has no concatenation at all.
+ */
+export declare function npmShellCommand(binary: string, args: string[]): string;
 /** The npm package spec to install for a target version. */
 export declare function installSpec(version: string): string;
 /** The `npm <args>` (after the `npm` binary) that installs the target globally. */

package/dist/update.js

@@ -15,6 +15,7 @@ exports.parseUpdateFlags = parseUpdateFlags;
 exports.sanitizeVersion = sanitizeVersion;
 exports.npmBinary = npmBinary;
 exports.npmSpawnShell = npmSpawnShell;
+exports.npmShellCommand = npmShellCommand;
 exports.installSpec = installSpec;
 exports.npmInstallArgs = npmInstallArgs;
 exports.globalPrefixFromPackageDir = globalPrefixFromPackageDir;
@@ -88,6 +89,19 @@ function npmBinary(platform = process.platform) {
 function npmSpawnShell(platform = process.platform) {
     return platform === "win32";
 }
+/**
+ * The single command string used to launch npm on platforms that must go through
+ * a shell (Windows — see `npmSpawnShell`). Node 22+ deprecates passing an args
+ * *array* together with `shell: true` (DEP0190: the args are concatenated, not
+ * escaped), so the shell path builds one string and runs it via `execSync`
+ * instead. Joining with spaces is safe here because every token is a fixed
+ * literal except the version, which `sanitizeVersion` constrains to
+ * `[A-Za-z0-9._-]` (no shell metacharacters). POSIX never uses this — it keeps
+ * the shell-free, array-based `execFile`, which has no concatenation at all.
+ */
+function npmShellCommand(binary, args) {
+    return [binary, ...args].join(" ");
+}
 /** The npm package spec to install for a target version. */
 function installSpec(version) {
     return !version || version === "latest" ? "rastack" : `rastack@${version}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",
@@ -13,7 +13,7 @@
   },
   "scripts": {
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
-    "build": "tsc && cp src/.prettierrc dist/.prettierrc",
+    "build": "tsc && cp src/.prettierrc dist/.prettierrc && node scripts/copy-templates.js",
     "start": "node dist/index.js",
     "test": "jest"
   },

package/scripts/copy-templates.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Copy the canonical CloudFormation templates (deploy/cloudformation/*.yaml + the
+ * Lambda placeholder bundle) into the built package so `rastack init` /
+ * `rastack bootstrap` can deploy them from ANY repo.
+ *
+ * A consumer repo (the demo, any app) deliberately does not carry a copy of the
+ * framework IaC (deploy/cloudformation/README.md), so the CLI ships the templates
+ * itself. `resolveDeployAsset` (src/deploy/io.ts) reads them from
+ * `dist/templates/cloudformation/`, which this script populates from the single
+ * source of truth at repo-root `deploy/cloudformation/`.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const srcDir = path.join(repoRoot, "deploy", "cloudformation");
+const destDir = path.join(__dirname, "..", "dist", "templates", "cloudformation");
+
+const assets = [
+  "app.yaml",
+  "bootstrap.yaml",
+  path.join("placeholder", "bootstrap"),
+];
+
+fs.mkdirSync(path.join(destDir, "placeholder"), { recursive: true });
+
+for (const rel of assets) {
+  const src = path.join(srcDir, rel);
+  const dest = path.join(destDir, rel);
+  if (!fs.existsSync(src)) {
+    console.error(`copy-templates: missing source ${src}`);
+    process.exit(1);
+  }
+  fs.copyFileSync(src, dest);
+  // Preserve the executable bit on the Lambda placeholder binary.
+  if (rel.endsWith("bootstrap")) fs.chmodSync(dest, 0o755);
+}
+
+console.log(
+  `copy-templates: bundled ${assets.length} CloudFormation asset(s) into dist/templates/cloudformation`,
+);

package/src/deploy/config.ts

@@ -314,7 +314,14 @@ export function stackParameters(cfg: DeployConfig): StackParameter[] {
   return params;
 }
 
-/** The in-repo CloudFormation templates `rastack init` deploys from. */
+/**
+ * The canonical repo-relative CloudFormation template paths. These are the paths
+ * in the *framework* repo (theserverkid/reactapistack) and the default the argv
+ * builders below embed. A **consumer** repo (the demo, any app) deliberately does
+ * NOT carry a copy of the framework IaC — the templates ship inside the `rastack`
+ * package instead — so `init`/`bootstrap` resolve the real on-disk path via
+ * `resolveDeployAsset` (io.ts) and pass it in as the `templateFile` override.
+ */
 export const APP_TEMPLATE_FILE = "deploy/cloudformation/app.yaml";
 export const BOOTSTRAP_TEMPLATE_FILE = "deploy/cloudformation/bootstrap.yaml";
 
@@ -327,7 +334,8 @@ export const BOOTSTRAP_TEMPLATE_FILE = "deploy/cloudformation/bootstrap.yaml";
  * accepts *only* a local template file. `--template-url` is exclusive to the
  * low-level `create-stack`/`update-stack`/`create-change-set` commands, so
  * pairing it with `deploy` fails with `the following arguments are required:
- * --template-file`. `init` runs in the repo, where both templates are present.
+ * --template-file`. The file is resolved from the `rastack` package (see
+ * `resolveDeployAsset`), so a consumer repo need not carry the framework IaC.
  */
 function cfnDeployArgs(
   templateFile: string,
@@ -362,10 +370,17 @@ function awsCommand(args: string[]): string {
   return `aws ${args.join(" ")}`;
 }
 
-/** The argv that creates the app's infrastructure (app.yaml). */
-export function deployStackArgs(cfg: DeployConfig): string[] {
+/**
+ * The argv that creates the app's infrastructure (app.yaml). `templateFile`
+ * defaults to the canonical repo-relative path; `init` passes the resolved
+ * package-bundled path so it works from a consumer repo that carries no IaC.
+ */
+export function deployStackArgs(
+  cfg: DeployConfig,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string[] {
   return cfnDeployArgs(
-    APP_TEMPLATE_FILE,
+    templateFile,
     cfg.stackName,
     cfg.region,
     stackParameters(cfg),
@@ -377,8 +392,11 @@ export function deployStackArgs(cfg: DeployConfig): string[] {
  * infrastructure (app.yaml), from the in-repo template. `rastack init` runs this
  * for you; it is also printed by `--print` so it can be run by hand.
  */
-export function deployStackCommand(cfg: DeployConfig): string {
-  return awsCommand(deployStackArgs(cfg));
+export function deployStackCommand(
+  cfg: DeployConfig,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string {
+  return awsCommand(deployStackArgs(cfg, templateFile));
 }
 
 /**
@@ -410,13 +428,19 @@ export function bootstrapStackParameters(
   return params;
 }
 
-/** The argv that creates the bootstrap stack (bootstrap.yaml). */
+/**
+ * The argv that creates the bootstrap stack (bootstrap.yaml). `templateFile`
+ * defaults to the canonical repo-relative path; `init`/`bootstrap` pass the
+ * resolved package-bundled path so it works from a consumer repo that carries no
+ * IaC.
+ */
 export function bootstrapStackArgs(
   cfg: DeployConfig,
   reuseOidc = false,
+  templateFile: string = BOOTSTRAP_TEMPLATE_FILE,
 ): string[] {
   return cfnDeployArgs(
-    BOOTSTRAP_TEMPLATE_FILE,
+    templateFile,
     bootstrapStackName(cfg),
     cfg.region,
     bootstrapStackParameters(cfg, reuseOidc),
@@ -427,8 +451,9 @@ export function bootstrapStackArgs(
 export function bootstrapStackCommand(
   cfg: DeployConfig,
   reuseOidc = false,
+  templateFile: string = BOOTSTRAP_TEMPLATE_FILE,
 ): string {
-  return awsCommand(bootstrapStackArgs(cfg, reuseOidc));
+  return awsCommand(bootstrapStackArgs(cfg, reuseOidc, templateFile));
 }
 
 /** Stack Output keys `init` reads back off the bootstrap stack. */

package/src/deploy/io.ts

@@ -18,6 +18,38 @@ export function configPath(cwd = process.cwd()): string {
   return path.join(cwd, CONFIG_PATH);
 }
 
+/**
+ * Resolve a CloudFormation asset (`app.yaml`, `bootstrap.yaml`, or the
+ * `placeholder/bootstrap` Lambda bundle) to an absolute on-disk path.
+ *
+ * The templates are the **framework's** IaC, not the consumer's — the demo repo
+ * and every future app repo deliberately do not carry a copy (see
+ * deploy/cloudformation/README.md). So `init`/`bootstrap`, which run in those
+ * repos, cannot assume `deploy/cloudformation/<asset>` exists relative to the
+ * cwd — that is exactly the `Invalid template path deploy/cloudformation/…`
+ * failure. Instead the assets ship *inside* the `rastack` package (copied into
+ * `dist/templates/cloudformation/` at build time) and are resolved from the
+ * install location, with fallbacks so running from source or from the framework
+ * repo itself still works. Returns null when no candidate exists.
+ */
+export function resolveDeployAsset(
+  relPath: string,
+  cwd = process.cwd(),
+): string | null {
+  const candidates = [
+    // Installed package: dist/deploy/io.js → dist/templates/cloudformation/…
+    path.join(__dirname, "..", "templates", "cloudformation", relPath),
+    // Running from TS source: tools/src/deploy/io.ts → repo-root deploy/…
+    path.join(__dirname, "..", "..", "..", "deploy", "cloudformation", relPath),
+    // Invoked inside the framework repo itself (cwd is the repo root).
+    path.join(cwd, "deploy", "cloudformation", relPath),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 /** Read + normalize the deploy config, or null when it does not exist yet. */
 export function loadConfig(cwd = process.cwd()): DeployConfig | null {
   const file = configPath(cwd);
@@ -126,8 +158,8 @@ export function uploadPlaceholder(
   region: string,
   cwd = process.cwd(),
 ): boolean {
-  const src = path.join(cwd, "deploy/cloudformation/placeholder/bootstrap");
-  if (!fs.existsSync(src)) return false;
+  const src = resolveDeployAsset("placeholder/bootstrap", cwd);
+  if (!src) return false;
   const zip = zipStore([
     { name: "bootstrap", data: fs.readFileSync(src), mode: 0o755 },
   ]);