rastack 0.0.33 → 0.0.35

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.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)
+
 ### [0.0.33](https://github.com/theserverkid/reactapistack/compare/v0.0.32...v0.0.33) (2026-07-11)
 
 ### [0.0.32](https://github.com/theserverkid/reactapistack/compare/v0.0.31...v0.0.32) (2026-07-10)

package/dist/deploy/ci.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `rastack ci` — the CI pipeline as a *plan of shell steps*, derived purely from
+ * the deploy config.
+ *
+ * The whole point is to make GitHub Actions cleaner: instead of thirty lines of
+ * inline bash (compile the manifest, cross-build the arm64 Lambda, bake the
+ * Cognito JWKS, assemble the zip, `update-function-code`, wait, print the URL),
+ * a workflow runs one line — `rastack ci deploy` — and this module owns the
+ * steps. Because the plan is a pure function of the config, it is fully testable
+ * without AWS or a Rust toolchain, and `rastack ci --plan` prints exactly what
+ * will run.
+ *
+ * Values that only exist after the stack is created (the function name, the API
+ * URL, the JWKS URL) are either taken from `cfg.outputs` when already resolved,
+ * or emitted as a live `$(aws cloudformation describe-stacks …)` substitution so
+ * the same plan works before and after they are wired into the config.
+ */
+import { DeployConfig } from "./config";
+export type CiPhase = "check" | "build" | "deploy";
+export interface CiStep {
+    /** Human label, echoed before the step runs. */
+    name: string;
+    /** The shell command to execute. */
+    run: string;
+    /** Working directory relative to the repo root (default: repo root). */
+    cwd?: string;
+}
+export interface CiPlanOptions {
+    /** How to invoke the rastack CLI for nested steps (default: `rastack`). */
+    bin?: string;
+    /** Skip the build steps in `deploy` (code already built this job). */
+    skipBuild?: boolean;
+    /** Override the function name (else from cfg.outputs, else resolved live). */
+    functionName?: string;
+    /** Override the JWKS URL (else from cfg.outputs, else resolved live). */
+    jwksUrl?: string;
+}
+/** `check` — validate the resource graph and compile the manifest. A CI gate. */
+export declare function checkSteps(cfg: DeployConfig, bin: string): CiStep[];
+/**
+ * `build` — produce the deployable Lambda bundle: compile the manifest,
+ * cross-build the custom-runtime binary, bake the Cognito JWKS in, and zip the
+ * binary together with the files it reads at `/var/task`.
+ */
+export declare function buildSteps(cfg: DeployConfig, opts?: CiPlanOptions): CiStep[];
+/**
+ * `deploy` — the whole CI job: build (unless already built), then ship the code
+ * with the single privileged call CI is allowed, `update-function-code`, wait
+ * for it to settle, and print the API URL.
+ */
+export declare function deploySteps(cfg: DeployConfig, opts?: CiPlanOptions): CiStep[];
+/** Build the ordered step list for a phase. */
+export declare function ciPlan(phase: CiPhase, cfg: DeployConfig, opts?: CiPlanOptions): CiStep[];

package/dist/deploy/ci.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * `rastack ci` — the CI pipeline as a *plan of shell steps*, derived purely from
+ * the deploy config.
+ *
+ * The whole point is to make GitHub Actions cleaner: instead of thirty lines of
+ * inline bash (compile the manifest, cross-build the arm64 Lambda, bake the
+ * Cognito JWKS, assemble the zip, `update-function-code`, wait, print the URL),
+ * a workflow runs one line — `rastack ci deploy` — and this module owns the
+ * steps. Because the plan is a pure function of the config, it is fully testable
+ * without AWS or a Rust toolchain, and `rastack ci --plan` prints exactly what
+ * will run.
+ *
+ * Values that only exist after the stack is created (the function name, the API
+ * URL, the JWKS URL) are either taken from `cfg.outputs` when already resolved,
+ * or emitted as a live `$(aws cloudformation describe-stacks …)` substitution so
+ * the same plan works before and after they are wired into the config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSteps = checkSteps;
+exports.buildSteps = buildSteps;
+exports.deploySteps = deploySteps;
+exports.ciPlan = ciPlan;
+/**
+ * A stack Output value: the literal from `cfg.outputs` if wired, else a shell
+ * command substitution that resolves it live from CloudFormation. Keeping the
+ * fallback inline (rather than a separate step) means the plan is a flat list of
+ * self-contained commands that read correctly in any order.
+ */
+function stackOutput(cfg, outputKey, literal) {
+    if (literal)
+        return literal;
+    return (`$(aws cloudformation describe-stacks --stack-name ${cfg.stackName} ` +
+        `--region ${cfg.region} ` +
+        `--query "Stacks[0].Outputs[?OutputKey=='${outputKey}'].OutputValue" ` +
+        `--output text)`);
+}
+/** The Lambda staging directory `cargo lambda build` writes the binary into. */
+function stageDir(cfg) {
+    return `rust/target/lambda/${cfg.lambda.bin}`;
+}
+/** `check` — validate the resource graph and compile the manifest. A CI gate. */
+function checkSteps(cfg, bin) {
+    return [
+        {
+            name: "Validate resource graph",
+            run: `${bin} check ${cfg.resourcesDir}`,
+        },
+        {
+            name: "Compile manifest + OpenAPI",
+            run: `${bin} compile ${cfg.resourcesDir} ${cfg.outDir}`,
+        },
+    ];
+}
+/**
+ * `build` — produce the deployable Lambda bundle: compile the manifest,
+ * cross-build the custom-runtime binary, bake the Cognito JWKS in, and zip the
+ * binary together with the files it reads at `/var/task`.
+ */
+function buildSteps(cfg, opts = {}) {
+    const bin = opts.bin ?? "rastack";
+    const stage = stageDir(cfg);
+    const archFlag = cfg.lambda.arch === "arm64" ? "--arm64" : "--x86-64";
+    const jwks = stackOutput(cfg, "JwksUrl", opts.jwksUrl ?? cfg.outputs?.jwksUrl);
+    return [
+        {
+            name: "Compile manifest + OpenAPI",
+            run: `${bin} compile ${cfg.resourcesDir} ${cfg.outDir}`,
+        },
+        {
+            name: "Cross-build the Lambda binary",
+            run: `cargo lambda build --release ${archFlag} --bin ${cfg.lambda.bin} --features ${cfg.lambda.features}`,
+            cwd: "rust",
+        },
+        {
+            name: "Bake the Cognito JWKS into the bundle",
+            run: `curl -fsSL "${jwks}" -o ${stage}/jwks.json`,
+        },
+        {
+            name: "Stage the manifest + OpenAPI",
+            run: `cp ${cfg.outDir}/schema.rastack.json ${cfg.outDir}/openapi.json ${stage}/`,
+        },
+        {
+            name: "Assemble the deployment bundle",
+            run: `zip -j ${stage}/bootstrap.zip ${stage}/${cfg.lambda.bin} ${stage}/schema.rastack.json ${stage}/openapi.json ${stage}/jwks.json`,
+        },
+    ];
+}
+/**
+ * `deploy` — the whole CI job: build (unless already built), then ship the code
+ * with the single privileged call CI is allowed, `update-function-code`, wait
+ * for it to settle, and print the API URL.
+ */
+function deploySteps(cfg, opts = {}) {
+    const stage = stageDir(cfg);
+    const zip = `${stage}/bootstrap.zip`;
+    const fn = stackOutput(cfg, "FunctionName", opts.functionName ?? cfg.outputs?.functionName);
+    const apiUrl = stackOutput(cfg, "ApiUrl", cfg.outputs?.apiUrl);
+    const steps = opts.skipBuild ? [] : buildSteps(cfg, opts);
+    steps.push({
+        name: "Ship the code (update-function-code)",
+        run: `aws lambda update-function-code --function-name ${fn} ` +
+            `--zip-file fileb://${zip} --region ${cfg.region} --publish ` +
+            `--output text --query LastModified`,
+    }, {
+        name: "Wait for the function to update",
+        run: `aws lambda wait function-updated --function-name ${fn} --region ${cfg.region}`,
+    }, {
+        name: "Report the API URL",
+        run: `echo "Deployed ${cfg.app} → ${apiUrl}"`,
+    });
+    return steps;
+}
+/** Build the ordered step list for a phase. */
+function ciPlan(phase, cfg, opts = {}) {
+    const bin = opts.bin ?? "rastack";
+    switch (phase) {
+        case "check":
+            return checkSteps(cfg, bin);
+        case "build":
+            return buildSteps(cfg, opts);
+        case "deploy":
+            return deploySteps(cfg, opts);
+    }
+}

package/dist/deploy/config.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `rastack deploy` config — the single source of truth for a repo's serverless
+ * deployment, written to `.rastack/deploy.json`.
+ *
+ * The deploy is split by *what changes* (see docs/serverless-deploy.md): the
+ * CloudFormation stack owns all durable infrastructure and is created once by a
+ * human, while CI does exactly one thing on every push —
+ * `aws lambda update-function-code`. This module models the small set of
+ * *authoring inputs* a human decides up front (app slug, region, the GitHub repo
+ * whose CI ships the code, the Lambda build shape) plus the *stack outputs* that
+ * only exist after the stack is created (function name, API URL, JWKS URL, …).
+ * CI resolves any missing output live from the stack, so the config stays a
+ * short, human-owned file.
+ *
+ * Everything here is pure and side-effect-free — the same discipline as the
+ * resource compiler and the token compiler. `rastack-{init,deploy,ci}.ts` are the
+ * thin IO wrappers that read/write the file and shell out.
+ */
+/** Values CI resolves from the CloudFormation stack Outputs (see app.yaml). */
+export interface DeployOutputs {
+    /** Lambda function name — CI targets this with `update-function-code`. */
+    functionName?: string;
+    /** Base URL of the deployed HTTP API. */
+    apiUrl?: string;
+    /** OIDC role CI assumes — wire as the `AWS_DEPLOY_ROLE_ARN` repo Variable. */
+    deployRoleArn?: string;
+    /** Cognito User Pool id (identity / JWTs). */
+    userPoolId?: string;
+    /** App client id — the token audience `rastack-server` pins. */
+    userPoolClientId?: string;
+    /** JWKS URL baked into the Lambda bundle at build time. */
+    jwksUrl?: string;
+    /** S3 Iceberg warehouse bucket — the system of record. */
+    warehouseBucket?: string;
+}
+export interface LambdaBuild {
+    /** Cargo bin built for the custom runtime (`provided.al2023`). */
+    bin: string;
+    /** Target architecture — arm64 (Graviton, the default) or x86_64. */
+    arch: "arm64" | "x86_64";
+    /** Cargo features the Lambda build enables. */
+    features: string;
+}
+export interface DeployConfig {
+    /** App slug — namespaces buckets/roles/SSM. Cognito-safe: `^[a-z0-9]{1,20}$`. */
+    app: string;
+    /** Resource-name prefix shared across a deployment. `^[a-z0-9]{1,20}$`. */
+    namePrefix: string;
+    /** AWS region the stack (and CI) target. */
+    region: string;
+    /** CloudFormation stack name — defaults to `${namePrefix}-${app}`. */
+    stackName: string;
+    /** The GitHub repo whose CI is trusted to ship the Lambda code. */
+    github: {
+        owner: string;
+        repo: string;
+        branch: string;
+    };
+    /** Iceberg namespace the warehouse writes under. */
+    namespace: string;
+    /** How the Rust Lambda bundle is built. */
+    lambda: LambdaBuild;
+    /** Where the TypeScript resource definitions live. */
+    resourcesDir: string;
+    /** Where `rastack compile` writes the manifest + OpenAPI. */
+    outDir: string;
+    /** Bootstrap templates bucket that hosts `app.yaml` (for the launch command). */
+    templatesBucket?: string;
+    /** Bootstrap artifacts bucket holding the Lambda placeholder bundle. */
+    artifactsBucket?: string;
+    /** Whether the function verifies the `access` or `id` token. */
+    tokenUse: "access" | "id";
+    /** Values resolved from the stack after it is created (optional). */
+    outputs?: DeployOutputs;
+}
+export declare const DEFAULT_LAMBDA: LambdaBuild;
+/** The out-of-the-box config — everything a fresh repo can default sensibly. */
+export declare const DEFAULTS: Omit<DeployConfig, "app" | "github">;
+/** A recursively-optional view of the config, as read from disk or CLI flags. */
+export type PartialDeployConfig = {
+    [K in keyof DeployConfig]?: DeployConfig[K] extends object ? Partial<DeployConfig[K]> : DeployConfig[K];
+};
+/**
+ * Fill a partial config with defaults into a complete `DeployConfig`. Never
+ * throws — `validateConfig` reports what is still missing or malformed.
+ */
+export declare function normalizeConfig(partial?: PartialDeployConfig): DeployConfig;
+/**
+ * Return a list of human-readable problems, empty when the config is deployable.
+ * The slug/prefix patterns mirror app.yaml's `AllowedPattern`s exactly, so a
+ * config that passes here also passes CloudFormation's own validation.
+ */
+export declare function validateConfig(cfg: DeployConfig): string[];
+/** Deep-merge a patch over a base config (used by `deploy`/`init` reconfigure). */
+export declare function mergeConfig(base: DeployConfig, patch: PartialDeployConfig): DeployConfig;
+/**
+ * Recover `{ owner, repo }` from a GitHub remote URL — both the SSH
+ * (`git@github.com:owner/repo.git`) and HTTPS
+ * (`https://github.com/owner/repo(.git)`) forms — so `init` can default the
+ * GitHub coordinates from `git remote get-url origin`. Returns null for any
+ * non-GitHub or unparseable URL.
+ */
+export declare function parseGitHubRemote(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+/** A `Key=Value` CloudFormation parameter override. */
+export interface StackParameter {
+    key: string;
+    value: string;
+}
+/**
+ * The `--parameter-overrides` for `aws cloudformation deploy` of app.yaml,
+ * derived from the config. Order and keys match the template's `Parameters`.
+ * `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 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`.
+ */
+export declare function deployStackCommand(cfg: DeployConfig): string;
+/** GitHub repo Variable to wire (name + resolved value, if known from outputs). */
+export interface RepoVariable {
+    name: string;
+    value: string;
+    from: string;
+}
+/**
+ * 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.
+ */
+export declare function repoVariables(cfg: DeployConfig): RepoVariable[];
+/**
+ * The `RASTACK_*` environment the Lambda reads (docs/serverless-deploy.md §1).
+ * The IaC sets these on the function; surfaced here for `rastack deploy` to
+ * print so the mapping between config and runtime env is inspectable.
+ */
+export declare function lambdaEnv(cfg: DeployConfig): StackParameter[];

package/dist/deploy/config.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * `rastack deploy` config — the single source of truth for a repo's serverless
+ * deployment, written to `.rastack/deploy.json`.
+ *
+ * The deploy is split by *what changes* (see docs/serverless-deploy.md): the
+ * CloudFormation stack owns all durable infrastructure and is created once by a
+ * human, while CI does exactly one thing on every push —
+ * `aws lambda update-function-code`. This module models the small set of
+ * *authoring inputs* a human decides up front (app slug, region, the GitHub repo
+ * whose CI ships the code, the Lambda build shape) plus the *stack outputs* that
+ * only exist after the stack is created (function name, API URL, JWKS URL, …).
+ * CI resolves any missing output live from the stack, so the config stays a
+ * short, human-owned file.
+ *
+ * Everything here is pure and side-effect-free — the same discipline as the
+ * resource compiler and the token compiler. `rastack-{init,deploy,ci}.ts` are the
+ * 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.normalizeConfig = normalizeConfig;
+exports.validateConfig = validateConfig;
+exports.mergeConfig = mergeConfig;
+exports.parseGitHubRemote = parseGitHubRemote;
+exports.stackParameters = stackParameters;
+exports.templateUrl = templateUrl;
+exports.deployStackCommand = deployStackCommand;
+exports.repoVariables = repoVariables;
+exports.lambdaEnv = lambdaEnv;
+exports.DEFAULT_LAMBDA = {
+    bin: "bootstrap",
+    arch: "arm64",
+    features: "lambda",
+};
+/** The out-of-the-box config — everything a fresh repo can default sensibly. */
+exports.DEFAULTS = {
+    namePrefix: "rastack",
+    region: "af-south-1",
+    stackName: "",
+    namespace: "production",
+    lambda: exports.DEFAULT_LAMBDA,
+    resourcesDir: "resources",
+    outDir: ".rastack",
+    tokenUse: "access",
+};
+/**
+ * Fill a partial config with defaults into a complete `DeployConfig`. Never
+ * throws — `validateConfig` reports what is still missing or malformed.
+ */
+function normalizeConfig(partial = {}) {
+    const app = (partial.app ?? "").trim();
+    const namePrefix = (partial.namePrefix ?? exports.DEFAULTS.namePrefix).trim();
+    const github = {
+        owner: (partial.github?.owner ?? "").trim(),
+        repo: (partial.github?.repo ?? "").trim(),
+        branch: (partial.github?.branch ?? "master").trim(),
+    };
+    const stackName = (partial.stackName ?? "").trim() || (app ? `${namePrefix}-${app}` : "");
+    return {
+        app,
+        namePrefix,
+        region: (partial.region ?? exports.DEFAULTS.region).trim(),
+        stackName,
+        github,
+        namespace: (partial.namespace ?? exports.DEFAULTS.namespace).trim(),
+        lambda: {
+            bin: (partial.lambda?.bin ?? exports.DEFAULT_LAMBDA.bin).trim(),
+            arch: partial.lambda?.arch ?? exports.DEFAULT_LAMBDA.arch,
+            features: (partial.lambda?.features ?? exports.DEFAULT_LAMBDA.features).trim(),
+        },
+        resourcesDir: (partial.resourcesDir ?? exports.DEFAULTS.resourcesDir).trim(),
+        outDir: (partial.outDir ?? exports.DEFAULTS.outDir).trim(),
+        templatesBucket: partial.templatesBucket?.trim() || undefined,
+        artifactsBucket: partial.artifactsBucket?.trim() || undefined,
+        tokenUse: partial.tokenUse ?? exports.DEFAULTS.tokenUse,
+        outputs: partial.outputs ? { ...partial.outputs } : undefined,
+    };
+}
+const SLUG = /^[a-z0-9]{1,20}$/;
+const REGION = /^[a-z]{2}-[a-z]+-\d+$/;
+const GH_NAME = /^[A-Za-z0-9_.-]+$/;
+const NAMESPACE = /^[a-z0-9_]+$/;
+/**
+ * Return a list of human-readable problems, empty when the config is deployable.
+ * The slug/prefix patterns mirror app.yaml's `AllowedPattern`s exactly, so a
+ * config that passes here also passes CloudFormation's own validation.
+ */
+function validateConfig(cfg) {
+    const errors = [];
+    if (!cfg.app)
+        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).`);
+    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.");
+    if (!NAMESPACE.test(cfg.namespace))
+        errors.push(`namespace "${cfg.namespace}" must match ${NAMESPACE}.`);
+    if (cfg.lambda.arch !== "arm64" && cfg.lambda.arch !== "x86_64")
+        errors.push(`lambda.arch must be "arm64" or "x86_64" (got "${cfg.lambda.arch}").`);
+    if (!cfg.lambda.bin)
+        errors.push("lambda.bin is required.");
+    return errors;
+}
+/** Deep-merge a patch over a base config (used by `deploy`/`init` reconfigure). */
+function mergeConfig(base, patch) {
+    return normalizeConfig({
+        ...base,
+        ...patch,
+        github: { ...base.github, ...patch.github },
+        lambda: { ...base.lambda, ...patch.lambda },
+        outputs: { ...base.outputs, ...patch.outputs },
+    });
+}
+/**
+ * Recover `{ owner, repo }` from a GitHub remote URL — both the SSH
+ * (`git@github.com:owner/repo.git`) and HTTPS
+ * (`https://github.com/owner/repo(.git)`) forms — so `init` can default the
+ * GitHub coordinates from `git remote get-url origin`. Returns null for any
+ * non-GitHub or unparseable URL.
+ */
+function parseGitHubRemote(url) {
+    const trimmed = url.trim();
+    const m = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/.exec(trimmed) ||
+        /^(?:https?:\/\/|ssh:\/\/git@)github\.com\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(trimmed);
+    if (!m)
+        return null;
+    const owner = m[1];
+    const repo = m[2];
+    if (!GH_NAME.test(owner) || !GH_NAME.test(repo))
+        return null;
+    return { owner, repo };
+}
+/**
+ * The `--parameter-overrides` for `aws cloudformation deploy` of app.yaml,
+ * derived from the config. Order and keys match the template's `Parameters`.
+ * `ArtifactsBucket` (which has no template default) is included only when set.
+ */
+function stackParameters(cfg) {
+    const params = [
+        { key: "AppName", value: cfg.app },
+        { key: "NamePrefix", value: cfg.namePrefix },
+        { key: "GitHubOwner", value: cfg.github.owner },
+        { key: "GitHubRepo", value: cfg.github.repo },
+        { key: "GitHubBranch", value: cfg.github.branch },
+        { key: "IcebergNamespace", value: cfg.namespace },
+    ];
+    if (cfg.artifactsBucket)
+        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 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`.
+ */
+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  ");
+}
+/**
+ * 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.
+ */
+function repoVariables(cfg) {
+    return [
+        {
+            name: "AWS_DEPLOY_ROLE_ARN",
+            value: cfg.outputs?.deployRoleArn ?? "",
+            from: "DeployRoleArn stack output",
+        },
+        { name: "AWS_REGION", value: cfg.region, from: "Region stack output" },
+    ];
+}
+/**
+ * The `RASTACK_*` environment the Lambda reads (docs/serverless-deploy.md §1).
+ * The IaC sets these on the function; surfaced here for `rastack deploy` to
+ * print so the mapping between config and runtime env is inspectable.
+ */
+function lambdaEnv(cfg) {
+    const warehouse = cfg.outputs?.warehouseBucket
+        ? `s3://${cfg.outputs.warehouseBucket}/warehouse`
+        : "s3://{warehouse-bucket}/warehouse";
+    const manifest = `/var/task/schema.rastack.json`;
+    return [
+        { key: "RASTACK_WAREHOUSE", value: warehouse },
+        { key: "RASTACK_MANIFEST", value: manifest },
+        { key: "RASTACK_OPENAPI", value: "/var/task/openapi.json" },
+        { key: "RASTACK_JWKS", value: "/var/task/jwks.json" },
+        {
+            key: "RASTACK_ISSUER",
+            value: cfg.outputs?.userPoolId
+                ? `https://cognito-idp.${cfg.region}.amazonaws.com/${cfg.outputs.userPoolId}`
+                : `https://cognito-idp.${cfg.region}.amazonaws.com/{userPoolId}`,
+        },
+        {
+            key: "RASTACK_AUDIENCE",
+            value: cfg.outputs?.userPoolClientId ?? "{appClientId}",
+        },
+        { key: "RASTACK_TOKEN_USE", value: cfg.tokenUse },
+    ];
+}

package/dist/deploy/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `rastack deploy | ci | init` core — the DevOps surface of React API Stack.
+ *
+ * Pure, testable building blocks (config, CI plan, workflow templates); the
+ * `rastack-{deploy,ci,init}.ts` entrypoints are the thin IO wrappers over them.
+ */
+export * from "./config";
+export * from "./ci";
+export * from "./workflows";

package/dist/deploy/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * The `rastack deploy | ci | init` core — the DevOps surface of React API Stack.
+ *
+ * Pure, testable building blocks (config, CI plan, workflow templates); the
+ * `rastack-{deploy,ci,init}.ts` entrypoints are the thin IO wrappers over them.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config"), exports);
+__exportStar(require("./ci"), exports);
+__exportStar(require("./workflows"), exports);

package/dist/deploy/io.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Filesystem + prompt helpers shared by the `rastack deploy | ci | init`
+ * entrypoints. Everything pure lives in the sibling modules; this is the small
+ * IO boundary they wrap.
+ */
+import * as readline from "readline";
+import { DeployConfig } from "./config";
+/** Absolute path to the deploy config for a project root. */
+export declare function configPath(cwd?: string): string;
+/** 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. */
+export declare function saveConfig(cfg: DeployConfig, cwd?: string): string;
+/**
+ * Best-effort GitHub `origin` remote URL, for defaulting the repo coordinates.
+ * Returns null when not a git repo or no origin.
+ */
+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;
+/**
+ * Ask a single question with a default, echoed as `label [default]: `. Returns
+ * the trimmed answer, or the default on an empty line.
+ */
+export declare function ask(rl: readline.Interface, label: string, def: string): Promise<string>;
+/** Run a callback with a readline interface, always closing it. */
+export declare function withPrompt<T>(fn: (rl: readline.Interface) => Promise<T>): Promise<T>;