rastack 0.0.33 → 0.0.35

package/src/deploy/config.ts

@@ -0,0 +1,329 @@
+/**
+ * `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 const DEFAULT_LAMBDA: LambdaBuild = {
+  bin: "bootstrap",
+  arch: "arm64",
+  features: "lambda",
+};
+
+/** The out-of-the-box config — everything a fresh repo can default sensibly. */
+export const DEFAULTS: Omit<DeployConfig, "app" | "github"> = {
+  namePrefix: "rastack",
+  region: "af-south-1",
+  stackName: "",
+  namespace: "production",
+  lambda: DEFAULT_LAMBDA,
+  resourcesDir: "resources",
+  outDir: ".rastack",
+  tokenUse: "access",
+};
+
+/** 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 function normalizeConfig(
+  partial: PartialDeployConfig = {},
+): DeployConfig {
+  const app = (partial.app ?? "").trim();
+  const namePrefix = (partial.namePrefix ?? 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 ?? DEFAULTS.region).trim(),
+    stackName,
+    github,
+    namespace: (partial.namespace ?? DEFAULTS.namespace).trim(),
+    lambda: {
+      bin: (partial.lambda?.bin ?? DEFAULT_LAMBDA.bin).trim(),
+      arch: partial.lambda?.arch ?? DEFAULT_LAMBDA.arch,
+      features: (partial.lambda?.features ?? DEFAULT_LAMBDA.features).trim(),
+    },
+    resourcesDir: (partial.resourcesDir ?? DEFAULTS.resourcesDir).trim(),
+    outDir: (partial.outDir ?? DEFAULTS.outDir).trim(),
+    templatesBucket: partial.templatesBucket?.trim() || undefined,
+    artifactsBucket: partial.artifactsBucket?.trim() || undefined,
+    tokenUse: partial.tokenUse ?? 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.
+ */
+export function validateConfig(cfg: DeployConfig): string[] {
+  const errors: string[] = [];
+  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). */
+export function mergeConfig(
+  base: DeployConfig,
+  patch: PartialDeployConfig,
+): DeployConfig {
+  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.
+ */
+export function parseGitHubRemote(
+  url: string,
+): { owner: string; repo: string } | null {
+  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 };
+}
+
+/** 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 function stackParameters(cfg: DeployConfig): StackParameter[] {
+  const params: StackParameter[] = [
+    { 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. */
+export function templateUrl(cfg: DeployConfig): string | null {
+  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`.
+ */
+export function deployStackCommand(cfg: DeployConfig): string {
+  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  ");
+}
+
+/** 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 function repoVariables(cfg: DeployConfig): RepoVariable[] {
+  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.
+ */
+export function lambdaEnv(cfg: DeployConfig): StackParameter[] {
+  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/src/deploy/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/src/deploy/io.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as readline from "readline";
+import { CONFIG_PATH } from "./workflows";
+import { DeployConfig, PartialDeployConfig, normalizeConfig } from "./config";
+
+/** Absolute path to the deploy config for a project root. */
+export function configPath(cwd = process.cwd()): string {
+  return path.join(cwd, CONFIG_PATH);
+}
+
+/** 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);
+  if (!fs.existsSync(file)) return null;
+  const raw = JSON.parse(fs.readFileSync(file, "utf-8")) as PartialDeployConfig;
+  return normalizeConfig(raw);
+}
+
+/** Write the deploy config, creating `.rastack/` if needed. */
+export function saveConfig(cfg: DeployConfig, cwd = process.cwd()): string {
+  const file = configPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+  return file;
+}
+
+/**
+ * Best-effort GitHub `origin` remote URL, for defaulting the repo coordinates.
+ * Returns null when not a git repo or no origin.
+ */
+export function gitRemoteUrl(cwd = process.cwd()): string | null {
+  try {
+    // Reads the developer's own git config with a fixed command; no untrusted
+    // input, so there is no command-injection surface.
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    const out = execSync("git remote get-url origin", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const url = out.toString().trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when we can prompt the user (a TTY, and not explicitly opted out). */
+export function canPrompt(nonInteractive: boolean): boolean {
+  return !nonInteractive && Boolean(process.stdin.isTTY);
+}
+
+/**
+ * Ask a single question with a default, echoed as `label [default]: `. Returns
+ * the trimmed answer, or the default on an empty line.
+ */
+export function ask(
+  rl: readline.Interface,
+  label: string,
+  def: string,
+): Promise<string> {
+  const suffix = def ? ` [${def}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`  ${label}${suffix}: `, (answer) => {
+      resolve(answer.trim() || def);
+    });
+  });
+}
+
+/** Run a callback with a readline interface, always closing it. */
+export async function withPrompt<T>(
+  fn: (rl: readline.Interface) => Promise<T>,
+): Promise<T> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await fn(rl);
+  } finally {
+    rl.close();
+  }
+}

package/src/deploy/workflows.ts

@@ -0,0 +1,163 @@
+/**
+ * The files `rastack init` templates into a repo — the base GitHub Actions and
+ * the deploy config — so starting (or reconfiguring) a project is one command.
+ *
+ * The generated workflows lean on `rastack ci`: rather than inlining the build
+ * and deploy shell, each job runs one `rastack ci …` line, and the CLI owns the
+ * steps (tools/src/deploy/ci.ts). That keeps the YAML short and keeps the
+ * pipeline logic versioned with the CLI, testable, and inspectable with
+ * `rastack ci --plan`.
+ *
+ * Pure string builders — `rastack-init.ts` is the thin wrapper that writes them.
+ */
+
+import { DeployConfig } from "./config";
+
+/** A templated file: repo-relative path + its contents. */
+export interface ScaffoldFile {
+  path: string;
+  content: string;
+}
+
+/** Node version the templated workflows pin (LTS — safe for a fresh repo). */
+const NODE_VERSION = "22";
+
+/**
+ * `.github/workflows/ci.yml` — validate resources and compile the manifest on
+ * every push/PR. The clean replacement for hand-written compile/check steps.
+ */
+export function renderCiWorkflow(cfg: DeployConfig): string {
+  return `name: CI
+
+# Validate the resource graph and compile the manifest on every change.
+# The heavy lifting lives in \`rastack ci check\` (see tools/src/deploy/ci.ts),
+# so this workflow stays a single command.
+
+on:
+  push:
+    branches: [${cfg.github.branch}]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '${NODE_VERSION}'
+      - name: Install rastack
+        run: npm install -g rastack
+      - name: Validate resources & compile manifest
+        run: rastack ci check
+`;
+}
+
+/**
+ * `.github/workflows/deploy-backend.yml` — ship the Rust Lambda on every push to
+ * the deploy branch. Authenticates with GitHub OIDC (no stored keys) and then
+ * runs one line, `rastack ci deploy`, which cross-builds the bundle, bakes the
+ * JWKS, and calls `update-function-code`. That single privileged call is the
+ * whole of CI's blast radius (docs/serverless-deploy.md §2).
+ */
+export function renderDeployWorkflow(cfg: DeployConfig): string {
+  const arch = cfg.lambda.arch === "arm64" ? "arm64" : "x86_64";
+  return `name: Deploy backend
+
+# Ship the Rust API (rastack-server) to AWS Lambda. Infrastructure is created
+# once by a human via CloudFormation (docs/serverless-deploy.md); this workflow
+# only ever runs \`aws lambda update-function-code\`, wrapped by \`rastack ci\`.
+#
+# Wire these from the CloudFormation stack Outputs as GitHub repo Variables:
+#   AWS_DEPLOY_ROLE_ARN   DeployRoleArn   (the OIDC role this job assumes)
+#   AWS_REGION            Region          (${cfg.region})
+
+on:
+  push:
+    branches: [${cfg.github.branch}]
+
+# Least privilege: read the repo + mint an OIDC token to assume the deploy role.
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: deploy-backend
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Build & deploy the Lambda (${arch})
+    runs-on: ubuntu-latest
+    # Skip on forks / repos that never wired the deploy role, so the job does
+    # not fail red for contributors who cannot (and should not) deploy.
+    if: vars.AWS_DEPLOY_ROLE_ARN != ''
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '${NODE_VERSION}'
+      - name: Install rastack
+        run: npm install -g rastack
+
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust
+      # cargo-lambda cross-builds the custom-runtime binary; it auto-installs
+      # zig (via pip) for the cross-compile when needed.
+      - name: Install cargo-lambda
+        run: pip3 install cargo-lambda
+
+      - name: Configure AWS credentials (OIDC — no stored keys)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: \${{ vars.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: \${{ vars.AWS_REGION }}
+
+      # One line: compile the manifest, cross-build the bundle, bake the JWKS,
+      # and update-function-code. See \`rastack ci --plan deploy\`.
+      - name: Build & deploy
+        run: rastack ci deploy
+`;
+}
+
+/** The deploy config written to `.rastack/deploy.json`, pretty-printed. */
+export function renderConfigFile(cfg: DeployConfig): string {
+  return JSON.stringify(cfg, null, 2) + "\n";
+}
+
+export const CONFIG_PATH = ".rastack/deploy.json";
+export const CI_WORKFLOW_PATH = ".github/workflows/ci.yml";
+export const DEPLOY_WORKFLOW_PATH = ".github/workflows/deploy-backend.yml";
+
+export interface ScaffoldOptions {
+  /** Omit the GitHub Actions workflows (config only). */
+  noWorkflows?: boolean;
+}
+
+/**
+ * The full set of files `rastack init` templates: the deploy config plus the two
+ * base workflows. Returned as data so the caller decides what to write, skip, or
+ * overwrite.
+ */
+export function scaffoldFiles(
+  cfg: DeployConfig,
+  opts: ScaffoldOptions = {},
+): ScaffoldFile[] {
+  const files: ScaffoldFile[] = [
+    { path: CONFIG_PATH, content: renderConfigFile(cfg) },
+  ];
+  if (!opts.noWorkflows) {
+    files.push(
+      { path: CI_WORKFLOW_PATH, content: renderCiWorkflow(cfg) },
+      { path: DEPLOY_WORKFLOW_PATH, content: renderDeployWorkflow(cfg) },
+    );
+  }
+  return files;
+}