rastack 0.0.35 → 0.0.37

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.37](https://github.com/theserverkid/reactapistack/compare/v0.0.36...v0.0.37) (2026-07-11)
+
+### [0.0.36](https://github.com/theserverkid/reactapistack/compare/v0.0.35...v0.0.36) (2026-07-11)
+
 ### [0.0.35](https://github.com/theserverkid/reactapistack/compare/v0.0.34...v0.0.35) (2026-07-11)
 
 ### [0.0.34](https://github.com/theserverkid/reactapistack/compare/v0.0.33...v0.0.34) (2026-07-11)

package/dist/deploy/config.d.ts

@@ -64,7 +64,7 @@ export interface DeployConfig {
     resourcesDir: string;
     /** Where `rastack compile` writes the manifest + OpenAPI. */
     outDir: string;
-    /** Bootstrap templates bucket that hosts `app.yaml` (for the launch command). */
+    /** Bootstrap templates bucket that hosts `app.yaml` (recorded for reference). */
     templatesBucket?: string;
     /** Bootstrap artifacts bucket holding the Lambda placeholder bundle. */
     artifactsBucket?: string;
@@ -115,14 +115,42 @@ export interface StackParameter {
  * `ArtifactsBucket` (which has no template default) is included only when set.
  */
 export declare function stackParameters(cfg: DeployConfig): StackParameter[];
-/** The S3 URL app.yaml is launched from, when the templates bucket is known. */
-export declare function templateUrl(cfg: DeployConfig): string | null;
+/** The in-repo CloudFormation templates `rastack init` deploys from. */
+export declare const APP_TEMPLATE_FILE = "deploy/cloudformation/app.yaml";
+export declare const BOOTSTRAP_TEMPLATE_FILE = "deploy/cloudformation/bootstrap.yaml";
+/** The argv that creates the app's infrastructure (app.yaml). */
+export declare function deployStackArgs(cfg: DeployConfig): string[];
 /**
  * The one-time `aws cloudformation deploy` command that creates the app's
- * infrastructure. Launched from the hosted template URL when the templates
- * bucket is known, else from the in-repo `deploy/cloudformation/app.yaml`.
+ * 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 declare function deployStackCommand(cfg: DeployConfig): string;
+/**
+ * The tier-0 bootstrap stack (bootstrap.yaml) — the S3 buckets that hold the
+ * Lambda placeholder + hosted templates, and the GitHub OIDC provider. One per
+ * account **and region**; its name is derived from the prefix so `init` can find
+ * it (and its `ArtifactsBucket`) without extra config.
+ */
+export declare function bootstrapStackName(cfg: DeployConfig): string;
+/**
+ * `--parameter-overrides` for bootstrap.yaml. `reuseOidc` re-runs against an
+ * account that already has a GitHub OIDC provider (AWS allows only one per URL):
+ * the template then derives the existing provider's ARN itself.
+ */
+export declare function bootstrapStackParameters(cfg: DeployConfig, reuseOidc?: boolean): StackParameter[];
+/** The argv that creates the bootstrap stack (bootstrap.yaml). */
+export declare function bootstrapStackArgs(cfg: DeployConfig, reuseOidc?: boolean): string[];
+/** The one-time `aws cloudformation deploy` command that creates the bootstrap stack. */
+export declare function bootstrapStackCommand(cfg: DeployConfig, reuseOidc?: boolean): string;
+/** Stack Output keys `init` reads back off the bootstrap stack. */
+export declare const BOOTSTRAP_ARTIFACTS_OUTPUT = "ArtifactsBucketName";
+export declare const BOOTSTRAP_TEMPLATES_OUTPUT = "TemplatesBucketName";
+/** app.yaml stack Output key → the `DeployOutputs` field it populates. */
+export declare const APP_STACK_OUTPUTS: {
+    key: string;
+    field: keyof DeployOutputs;
+}[];
 /** GitHub repo Variable to wire (name + resolved value, if known from outputs). */
 export interface RepoVariable {
     name: string;

package/dist/deploy/config.js

@@ -18,14 +18,18 @@
  * thin IO wrappers that read/write the file and shell out.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.DEFAULTS = exports.DEFAULT_LAMBDA = void 0;
 exports.normalizeConfig = normalizeConfig;
 exports.validateConfig = validateConfig;
 exports.mergeConfig = mergeConfig;
 exports.parseGitHubRemote = parseGitHubRemote;
 exports.stackParameters = stackParameters;
-exports.templateUrl = templateUrl;
+exports.deployStackArgs = deployStackArgs;
 exports.deployStackCommand = deployStackCommand;
+exports.bootstrapStackName = bootstrapStackName;
+exports.bootstrapStackParameters = bootstrapStackParameters;
+exports.bootstrapStackArgs = bootstrapStackArgs;
+exports.bootstrapStackCommand = bootstrapStackCommand;
 exports.repoVariables = repoVariables;
 exports.lambdaEnv = lambdaEnv;
 exports.DEFAULT_LAMBDA = {
@@ -163,34 +167,104 @@ function stackParameters(cfg) {
         params.push({ key: "ArtifactsBucket", value: cfg.artifactsBucket });
     return params;
 }
-/** The S3 URL app.yaml is launched from, when the templates bucket is known. */
-function templateUrl(cfg) {
-    if (!cfg.templatesBucket)
-        return null;
-    return `https://${cfg.templatesBucket}.s3.${cfg.region}.amazonaws.com/app.yaml`;
+/** The in-repo CloudFormation templates `rastack init` deploys from. */
+exports.APP_TEMPLATE_FILE = "deploy/cloudformation/app.yaml";
+exports.BOOTSTRAP_TEMPLATE_FILE = "deploy/cloudformation/bootstrap.yaml";
+/**
+ * The argv (after `aws`) for an `aws cloudformation deploy`. `init` feeds this to
+ * `execFileSync` (no shell), and the printed command string is just this joined
+ * with spaces — so what is shown is exactly what runs.
+ *
+ * Always `--template-file`: the high-level `aws cloudformation deploy` command
+ * 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.
+ */
+function cfnDeployArgs(templateFile, stackName, region, params) {
+    return [
+        "cloudformation",
+        "deploy",
+        "--template-file",
+        templateFile,
+        "--stack-name",
+        stackName,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--region",
+        region,
+        "--parameter-overrides",
+        ...params.map((p) => `${p.key}=${p.value}`),
+    ];
+}
+/**
+ * Render an argv as a single-line command string. Deliberately ONE line: a
+ * backslash-continued command pasted into Windows PowerShell breaks — there `\`
+ * is not a line-continuation, so every `--flag` is parsed as its own statement
+ * (`Missing expression after unary operator '--'`). A single line pastes cleanly
+ * into bash, zsh and PowerShell alike.
+ */
+function awsCommand(args) {
+    return `aws ${args.join(" ")}`;
+}
+/** The argv that creates the app's infrastructure (app.yaml). */
+function deployStackArgs(cfg) {
+    return cfnDeployArgs(exports.APP_TEMPLATE_FILE, cfg.stackName, cfg.region, stackParameters(cfg));
 }
 /**
  * The one-time `aws cloudformation deploy` command that creates the app's
- * infrastructure. Launched from the hosted template URL when the templates
- * bucket is known, else from the in-repo `deploy/cloudformation/app.yaml`.
+ * 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.
  */
 function deployStackCommand(cfg) {
-    const src = templateUrl(cfg);
-    const templateArg = src
-        ? `--template-url ${src}`
-        : "--template-file deploy/cloudformation/app.yaml";
-    const overrides = stackParameters(cfg)
-        .map((p) => `${p.key}=${p.value}`)
-        .join(" ");
-    return [
-        "aws cloudformation deploy",
-        templateArg,
-        `--stack-name ${cfg.stackName}`,
-        "--capabilities CAPABILITY_NAMED_IAM",
-        `--region ${cfg.region}`,
-        `--parameter-overrides ${overrides}`,
-    ].join(" \\\n  ");
+    return awsCommand(deployStackArgs(cfg));
+}
+/**
+ * The tier-0 bootstrap stack (bootstrap.yaml) — the S3 buckets that hold the
+ * Lambda placeholder + hosted templates, and the GitHub OIDC provider. One per
+ * account **and region**; its name is derived from the prefix so `init` can find
+ * it (and its `ArtifactsBucket`) without extra config.
+ */
+function bootstrapStackName(cfg) {
+    return `${cfg.namePrefix}-bootstrap`;
+}
+/**
+ * `--parameter-overrides` for bootstrap.yaml. `reuseOidc` re-runs against an
+ * account that already has a GitHub OIDC provider (AWS allows only one per URL):
+ * the template then derives the existing provider's ARN itself.
+ */
+function bootstrapStackParameters(cfg, reuseOidc = false) {
+    const params = [
+        { key: "NamePrefix", value: cfg.namePrefix },
+        { key: "GitHubOwner", value: cfg.github.owner },
+        { key: "PublisherRepo", value: cfg.github.repo },
+        { key: "PublisherBranch", value: cfg.github.branch },
+    ];
+    if (reuseOidc)
+        params.push({ key: "CreateOIDCProvider", value: "false" });
+    return params;
+}
+/** The argv that creates the bootstrap stack (bootstrap.yaml). */
+function bootstrapStackArgs(cfg, reuseOidc = false) {
+    return cfnDeployArgs(exports.BOOTSTRAP_TEMPLATE_FILE, bootstrapStackName(cfg), cfg.region, bootstrapStackParameters(cfg, reuseOidc));
+}
+/** The one-time `aws cloudformation deploy` command that creates the bootstrap stack. */
+function bootstrapStackCommand(cfg, reuseOidc = false) {
+    return awsCommand(bootstrapStackArgs(cfg, reuseOidc));
 }
+/** Stack Output keys `init` reads back off the bootstrap stack. */
+exports.BOOTSTRAP_ARTIFACTS_OUTPUT = "ArtifactsBucketName";
+exports.BOOTSTRAP_TEMPLATES_OUTPUT = "TemplatesBucketName";
+/** app.yaml stack Output key → the `DeployOutputs` field it populates. */
+exports.APP_STACK_OUTPUTS = [
+    { key: "FunctionName", field: "functionName" },
+    { key: "ApiUrl", field: "apiUrl" },
+    { key: "DeployRoleArn", field: "deployRoleArn" },
+    { key: "UserPoolId", field: "userPoolId" },
+    { key: "UserPoolClientId", field: "userPoolClientId" },
+    { key: "JwksUrl", field: "jwksUrl" },
+    { key: "WarehouseBucketName", field: "warehouseBucket" },
+];
 /**
  * The GitHub repo **Variables** CI reads — `AWS_DEPLOY_ROLE_ARN` and
  * `AWS_REGION` (see docs/serverless-deploy.md §3). Values come from the stack

package/dist/deploy/index.d.ts

@@ -7,3 +7,4 @@
 export * from "./config";
 export * from "./ci";
 export * from "./workflows";
+export * from "./zip";

package/dist/deploy/index.js

@@ -23,3 +23,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./config"), exports);
 __exportStar(require("./ci"), exports);
 __exportStar(require("./workflows"), exports);
+__exportStar(require("./zip"), exports);

package/dist/deploy/io.d.ts

@@ -18,6 +18,25 @@ export declare function saveConfig(cfg: DeployConfig, cwd?: string): string;
 export declare function gitRemoteUrl(cwd?: string): string | null;
 /** True when we can prompt the user (a TTY, and not explicitly opted out). */
 export declare function canPrompt(nonInteractive: boolean): boolean;
+/** Capture `aws <args>` stdout, or null when the CLI is absent / the call fails. */
+export declare function awsCapture(args: string[], cwd?: string): string | null;
+/** Run `aws <args>` streaming output; throws on a non-zero exit. */
+export declare function awsRun(args: string[], cwd?: string): void;
+/** True when the AWS CLI is on PATH. */
+export declare function awsAvailable(): boolean;
+/**
+ * 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
+ * key with `--output text`, which we normalize to null.
+ */
+export declare function stackOutput(stackName: string, key: string, region: string): string | null;
+/**
+ * Package the in-repo Lambda placeholder and upload it to the bootstrap
+ * artifacts bucket at `placeholders/bootstrap.zip` — the object app.yaml's
+ * function is *created from*. Idempotent (the zip is deterministic); safe to run
+ * on every `init`. Returns false when the placeholder file is missing.
+ */
+export declare function uploadPlaceholder(artifactsBucket: string, region: 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

@@ -43,14 +43,21 @@ exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
 exports.gitRemoteUrl = gitRemoteUrl;
 exports.canPrompt = canPrompt;
+exports.awsCapture = awsCapture;
+exports.awsRun = awsRun;
+exports.awsAvailable = awsAvailable;
+exports.stackOutput = stackOutput;
+exports.uploadPlaceholder = uploadPlaceholder;
 exports.ask = ask;
 exports.withPrompt = withPrompt;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
 const workflows_1 = require("./workflows");
 const config_1 = require("./config");
+const zip_1 = require("./zip");
 /** Absolute path to the deploy config for a project root. */
 function configPath(cwd = process.cwd()) {
     return path.join(cwd, workflows_1.CONFIG_PATH);
@@ -94,6 +101,80 @@ function gitRemoteUrl(cwd = process.cwd()) {
 function canPrompt(nonInteractive) {
     return !nonInteractive && Boolean(process.stdin.isTTY);
 }
+// ── AWS CLI boundary ─────────────────────────────────────────────────────────
+// `init` shells out to the developer's own AWS CLI (execFileSync — no shell, so
+// no injection surface) to stand the infrastructure up. Read helpers capture
+// output and return null on failure; mutating helpers stream to the console and
+// throw so the caller can report which step failed.
+/** Capture `aws <args>` stdout, or null when the CLI is absent / the call fails. */
+function awsCapture(args, cwd = process.cwd()) {
+    try {
+        const out = (0, child_process_1.execFileSync)("aws", args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return out.toString().trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Run `aws <args>` streaming output; throws on a non-zero exit. */
+function awsRun(args, cwd = process.cwd()) {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    (0, child_process_1.execFileSync)("aws", args, { cwd, stdio: "inherit" });
+}
+/** True when the AWS CLI is on PATH. */
+function awsAvailable() {
+    return awsCapture(["--version"]) !== 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
+ * key with `--output text`, which we normalize to null.
+ */
+function stackOutput(stackName, key, region) {
+    const val = awsCapture([
+        "cloudformation",
+        "describe-stacks",
+        "--stack-name",
+        stackName,
+        "--region",
+        region,
+        "--query",
+        `Stacks[0].Outputs[?OutputKey=='${key}'].OutputValue`,
+        "--output",
+        "text",
+    ]);
+    if (!val || val === "None")
+        return null;
+    return val;
+}
+/**
+ * Package the in-repo Lambda placeholder and upload it to the bootstrap
+ * artifacts bucket at `placeholders/bootstrap.zip` — the object app.yaml's
+ * function is *created from*. Idempotent (the zip is deterministic); safe to run
+ * on every `init`. Returns false when the placeholder file is missing.
+ */
+function uploadPlaceholder(artifactsBucket, region, cwd = process.cwd()) {
+    const src = path.join(cwd, "deploy/cloudformation/placeholder/bootstrap");
+    if (!fs.existsSync(src))
+        return false;
+    const zip = (0, zip_1.zipStore)([
+        { name: "bootstrap", data: fs.readFileSync(src), mode: 0o755 },
+    ]);
+    const tmp = path.join(os.tmpdir(), "rastack-placeholder-bootstrap.zip");
+    fs.writeFileSync(tmp, zip);
+    awsRun([
+        "s3",
+        "cp",
+        tmp,
+        `s3://${artifactsBucket}/placeholders/bootstrap.zip`,
+        "--region",
+        region,
+    ]);
+    return true;
+}
 /**
  * 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/zip.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A tiny, dependency-free ZIP writer used by `rastack init` to package the Lambda
+ * placeholder bundle (`placeholders/bootstrap.zip`) before uploading it to the
+ * bootstrap artifacts bucket.
+ *
+ * Why hand-roll it: `init` runs on the developer's machine — including Windows
+ * PowerShell, which has no `zip` binary — so shelling out to `zip` is not
+ * portable. Entries are STORED (no compression); the placeholder is ~1 KB, so
+ * compression buys nothing and STORE keeps this pure and trivial to verify. The
+ * one detail that matters for Lambda is the Unix executable bit on `bootstrap`,
+ * which is carried in the central-directory external attributes.
+ */
+/** A file to place in the archive. `mode` defaults to `0o644` (or `0o755` via helper). */
+export interface ZipEntry {
+    name: string;
+    data: Buffer;
+    mode?: number;
+}
+/**
+ * Build a ZIP archive from `entries` and return its bytes. Deterministic: the
+ * same inputs always produce the same buffer (a fixed DOS timestamp, no
+ * compression), so the placeholder upload is idempotent.
+ */
+export declare function zipStore(entries: ZipEntry[]): Buffer;

package/dist/deploy/zip.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * A tiny, dependency-free ZIP writer used by `rastack init` to package the Lambda
+ * placeholder bundle (`placeholders/bootstrap.zip`) before uploading it to the
+ * bootstrap artifacts bucket.
+ *
+ * Why hand-roll it: `init` runs on the developer's machine — including Windows
+ * PowerShell, which has no `zip` binary — so shelling out to `zip` is not
+ * portable. Entries are STORED (no compression); the placeholder is ~1 KB, so
+ * compression buys nothing and STORE keeps this pure and trivial to verify. The
+ * one detail that matters for Lambda is the Unix executable bit on `bootstrap`,
+ * which is carried in the central-directory external attributes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zipStore = zipStore;
+const CRC_TABLE = (() => {
+    const table = new Int32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c;
+    }
+    return table;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+// Fixed 1980-01-01 00:00 DOS timestamp — deterministic output (no wall-clock).
+const DOS_TIME = 0;
+const DOS_DATE = 0x0021;
+/**
+ * Build a ZIP archive from `entries` and return its bytes. Deterministic: the
+ * same inputs always produce the same buffer (a fixed DOS timestamp, no
+ * compression), so the placeholder upload is idempotent.
+ */
+function zipStore(entries) {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name, "utf-8");
+        const crc = crc32(entry.data);
+        const size = entry.data.length;
+        const mode = entry.mode ?? 0o644;
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0); // local file header signature
+        local.writeUInt16LE(20, 4); // version needed
+        local.writeUInt16LE(0, 6); // flags
+        local.writeUInt16LE(0, 8); // method: STORE
+        local.writeUInt16LE(DOS_TIME, 10);
+        local.writeUInt16LE(DOS_DATE, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(size, 18); // compressed size
+        local.writeUInt32LE(size, 22); // uncompressed size
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28); // extra length
+        locals.push(local, name, entry.data);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0); // central directory signature
+        central.writeUInt16LE((3 << 8) | 20, 4); // version made by: Unix host
+        central.writeUInt16LE(20, 6); // version needed
+        central.writeUInt16LE(0, 8); // flags
+        central.writeUInt16LE(0, 10); // method: STORE
+        central.writeUInt16LE(DOS_TIME, 12);
+        central.writeUInt16LE(DOS_DATE, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(size, 20);
+        central.writeUInt32LE(size, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt16LE(0, 30); // extra length
+        central.writeUInt16LE(0, 32); // comment length
+        central.writeUInt16LE(0, 34); // disk number
+        central.writeUInt16LE(0, 36); // internal attributes
+        central.writeUInt32LE((mode & 0xffff) << 16, 38); // external attrs: Unix mode
+        central.writeUInt32LE(offset, 42); // local header offset
+        centrals.push(central, name);
+        offset += local.length + name.length + entry.data.length;
+    }
+    const localBytes = Buffer.concat(locals);
+    const centralBytes = Buffer.concat(centrals);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0); // end of central directory signature
+    eocd.writeUInt16LE(0, 4); // disk number
+    eocd.writeUInt16LE(0, 6); // central dir start disk
+    eocd.writeUInt16LE(entries.length, 8); // entries on this disk
+    eocd.writeUInt16LE(entries.length, 10); // total entries
+    eocd.writeUInt32LE(centralBytes.length, 12); // central dir size
+    eocd.writeUInt32LE(localBytes.length, 16); // central dir offset
+    eocd.writeUInt16LE(0, 20); // comment length
+    return Buffer.concat([localBytes, centralBytes, eocd]);
+}

package/dist/rastack-ci.js

@@ -103,7 +103,7 @@ function main(argv) {
     const { phase, plan, opts } = parseFlags(argv);
     const cfg = (0, io_1.loadConfig)();
     if (!cfg) {
-        console.error("  ✗ no .rastack/deploy.json found. Run `rastack init` (or `rastack deploy`) first.");
+        console.error("  ✗ no .rastack/deploy.json found. Run `rastack init` first.");
         process.exit(1);
         return;
     }

package/dist/rastack-init.d.ts

@@ -1,14 +1,25 @@
 #!/usr/bin/env node
 /**
- * `rastack init` — template the base GitHub Actions + deploy config into a repo.
+ * `rastack init` — scaffold a repo's deploy config + GitHub Actions AND stand the
+ * serverless backend up.
  *
  *   rastack init [--app <slug>] [--owner <o>] [--repo <r>] [--branch <b>]
- *                [--region <r>] [--force] [--no-workflows] [--yes]
+ *                [--region <r>] [--prefix <p>] [--namespace <n>]
+ *                [--force] [--no-workflows] [--no-deploy] [--print] [--yes]
  *
- * Scaffolds a new project (or reconfigures an existing one) so it is ready to
- * deploy: `.rastack/deploy.json` plus `.github/workflows/{ci,deploy-backend}.yml`,
- * both of which run `rastack ci`. GitHub coordinates default from the repo's
- * `origin` remote; missing fields are prompted for on a TTY. Existing files are
- * left untouched unless `--force`.
+ * This is the one command that takes you from nothing to deployed. It:
+ *   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 — and CREATES the
+ *      bootstrap stack if it does not exist yet;
+ *   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.
+ *
+ * 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.
  */
 export {};