rastack 0.0.62 → 0.0.64

package/dist/compile/analyze.js

@@ -172,7 +172,17 @@ function analyzeField(name, initializer, checker) {
         const app = literalTypeProp(fieldType, "__app", checker, initializer);
         const model = literalTypeProp(fieldType, "__model", checker, initializer);
         if (app && model) {
-            return { name, type: "fk", relation: { app, model } };
+            const fk = { name, type: "fk", relation: { app, model } };
+            // `s.ref(() => X, { null: true })` — a nullable relation (a shared secret
+            // with no project, an unassigned task). The options object is the ref
+            // call's second argument, read the same way scalar constraints are.
+            if (ts.isCallExpression(initializer)) {
+                const opts = literalToValue(initializer.arguments[1]);
+                if (opts && typeof opts === "object" && opts.null === true) {
+                    fk.null = true;
+                }
+            }
+            return fk;
         }
         return undefined;
     }

package/dist/define/index.d.ts

@@ -64,6 +64,11 @@ export interface Ref<App extends string, Model extends string> {
     readonly __model: Model;
     /** The authored `() => Resource` thunk — carried at runtime. */
     readonly target?: () => ResourceType<App, Model, any>;
+    /** Optional FK constraints — `null: true` makes the relation nullable
+     * (e.g. a shared secret with no project, or an unassigned task). */
+    readonly options?: {
+        null?: boolean;
+    };
 }
 export interface StringOptions {
     maxLength?: number;
@@ -105,7 +110,9 @@ export declare const s: {
      * the relation from the *type* `Ref<App, Model>` this returns, and the
      * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
      */
-    ref<A extends string, M extends string>(thunk: () => ResourceType<A, M, any>): Ref<A, M>;
+    ref<A extends string, M extends string>(thunk: () => ResourceType<A, M, any>, options?: {
+        null?: boolean;
+    }): Ref<A, M>;
 };
 export type AnyField = Scalar<string> | Ref<string, string>;
 /** Local-first sync configuration (mirrors the old Python `class Sync:`). */

package/dist/define/index.js

@@ -56,8 +56,8 @@ exports.s = {
      * the relation from the *type* `Ref<App, Model>` this returns, and the
      * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
      */
-    ref(thunk) {
-        return { __rastackRef: true, target: thunk };
+    ref(thunk, options) {
+        return { __rastackRef: true, target: thunk, options };
     },
 };
 /** Define a resource. Capture app/model (and options) as literal types. */

package/dist/define/manifest.js

@@ -89,11 +89,17 @@ function runtimeField(res, name, value) {
         if (!isResourceValue(target)) {
             throw new Error(`manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`);
         }
-        return {
+        const fk = {
             name,
             type: "fk",
             relation: { app: target.app, model: target.model },
         };
+        // A nullable FK (`s.ref(() => X, { null: true })`) — e.g. a shared secret
+        // with no project — so the engine allows and stores a null relation.
+        if (field.options?.null === true) {
+            fk.null = true;
+        }
+        return fk;
     }
     if (typeof field.__rastackScalar !== "string")
         return undefined;

package/dist/deploy/ci.d.ts

@@ -15,7 +15,7 @@
  * 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";
+import { DeployConfig, EnvName } from "./config";
 export type CiPhase = "check" | "build" | "deploy";
 export interface CiStep {
     /** Human label, echoed before the step runs. */
@@ -37,10 +37,17 @@ export interface CiPlanOptions {
     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). */
+    /** Override the function name (else from the env's outputs, else resolved live). */
     functionName?: string;
-    /** Override the JWKS URL (else from cfg.outputs, else resolved live). */
+    /** Override the JWKS URL (else from the env's outputs, else resolved live). */
     jwksUrl?: string;
+    /**
+     * Which environment (dev/prod) to build+ship. When set, the stack name,
+     * outputs, and app label come from that environment — so `rastack ci deploy
+     * --env dev` targets the dev stack (dev's Cognito JWKS, dev's function). When
+     * unset the legacy single-stack fields (`cfg.stackName` / `cfg.outputs`) apply.
+     */
+    env?: EnvName;
 }
 /** `check` — validate the resource graph and compile the manifest. A CI gate. */
 export declare function checkSteps(cfg: DeployConfig, bin: string): CiStep[];

package/dist/deploy/ci.js

@@ -21,6 +21,7 @@ exports.checkSteps = checkSteps;
 exports.buildSteps = buildSteps;
 exports.deploySteps = deploySteps;
 exports.ciPlan = ciPlan;
+const config_1 = require("./config");
 /**
  * The in-process compile step shared by `check` and `build`: it produces
  * `schema.rastack.json` + `openapi.json` in `cfg.outDir` without a subprocess,
@@ -34,17 +35,25 @@ function compileStep(cfg) {
         action: "compile",
     };
 }
+/** The stack name + outputs + app label the plan targets, honouring `opts.env`. */
+function ciTarget(cfg, opts) {
+    if (opts.env) {
+        const e = (0, config_1.resolveEnvironment)(cfg, opts.env);
+        return { stackName: e.stackName, outputs: e.outputs, app: e.appName };
+    }
+    return { stackName: cfg.stackName, outputs: cfg.outputs, app: cfg.app };
+}
 /**
- * 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.
+ * A stack Output value: the literal 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) {
+function stackOutput(stackName, region, outputKey, literal) {
     if (literal)
         return literal;
-    return (`$(aws cloudformation describe-stacks --stack-name ${cfg.stackName} ` +
-        `--region ${cfg.region} ` +
+    return (`$(aws cloudformation describe-stacks --stack-name ${stackName} ` +
+        `--region ${region} ` +
         `--query "Stacks[0].Outputs[?OutputKey=='${outputKey}'].OutputValue" ` +
         `--output text)`);
 }
@@ -69,8 +78,9 @@ function checkSteps(cfg, bin) {
  */
 function buildSteps(cfg, opts = {}) {
     const stage = stageDir(cfg);
+    const target = ciTarget(cfg, opts);
     const archFlag = cfg.lambda.arch === "arm64" ? "--arm64" : "--x86-64";
-    const jwks = stackOutput(cfg, "JwksUrl", opts.jwksUrl ?? cfg.outputs?.jwksUrl);
+    const jwks = stackOutput(target.stackName, cfg.region, "JwksUrl", opts.jwksUrl ?? target.outputs?.jwksUrl);
     return [
         compileStep(cfg),
         {
@@ -100,8 +110,9 @@ function buildSteps(cfg, opts = {}) {
 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 target = ciTarget(cfg, opts);
+    const fn = stackOutput(target.stackName, cfg.region, "FunctionName", opts.functionName ?? target.outputs?.functionName);
+    const apiUrl = stackOutput(target.stackName, cfg.region, "ApiUrl", target.outputs?.apiUrl);
     const steps = opts.skipBuild ? [] : buildSteps(cfg, opts);
     steps.push({
         name: "Ship the code (update-function-code)",
@@ -113,7 +124,7 @@ function deploySteps(cfg, opts = {}) {
         run: `aws lambda wait function-updated --function-name ${fn} --region ${cfg.region}`,
     }, {
         name: "Report the API URL",
-        run: `echo "Deployed ${cfg.app} → ${apiUrl}"`,
+        run: `echo "Deployed ${target.app} → ${apiUrl}"`,
     });
     return steps;
 }

package/dist/deploy/config.d.ts

@@ -32,6 +32,12 @@ export interface DeployOutputs {
     jwksUrl?: string;
     /** S3 Iceberg warehouse bucket — the system of record. */
     warehouseBucket?: string;
+    /** Cognito Hosted UI domain (scheme-less), for browser sign-in. */
+    userPoolDomain?: string;
+    /** Full Cognito Hosted UI base URL (`https://…`). */
+    hostedUiUrl?: string;
+    /** Base URL of the external-API proxy route, when the env provisions one. */
+    proxyUrl?: string;
 }
 export interface LambdaBuild {
     /** Cargo bin built for the custom runtime (`provided.al2023`). */
@@ -41,6 +47,35 @@ export interface LambdaBuild {
     /** Cargo features the Lambda build enables. */
     features: string;
 }
+/**
+ * Per-environment overrides. The **prod** environment defaults its values from
+ * the top-level config (its branch is `github.branch`, its stack is `stackName`,
+ * its outputs are the top-level `outputs`); the **dev** environment defaults to
+ * the `development` branch and a `-dev` stack. Anything set here wins over those
+ * defaults. Only the fields that actually differ per environment live here —
+ * `app`/`namePrefix`/`region`/`github.owner`/`github.repo` are shared.
+ */
+export interface EnvOverride {
+    /** GitHub branch whose push deploys this environment. */
+    branch?: string;
+    /** GitHub Actions **Environment** name (scoped Variables + protection rules). */
+    ghEnvironment?: string;
+    /** CloudFormation stack name for this environment. */
+    stackName?: string;
+    /** Iceberg namespace this environment's warehouse writes under. */
+    namespace?: string;
+    /**
+     * Base URL of the upstream this environment's **external-API proxy** forwards
+     * to (typically a UAT or prod backend). When set, the stack provisions a
+     * Cognito-authorized `ANY /proxy/{proxy+}` route on the HTTP API that forwards
+     * to `${proxyUpstream}/{proxy}` — so a locally-running app (signed in against
+     * this environment's Cognito pool) reaches external APIs *only* through the
+     * proxy, never directly, and credentials stay server-side. Empty = no proxy.
+     */
+    proxyUpstream?: string;
+    /** Values resolved from this environment's stack after it is created. */
+    outputs?: DeployOutputs;
+}
 export interface DeployConfig {
     /** App slug — namespaces buckets/roles/SSM. Cognito-safe: `^[a-z0-9]{1,20}$`. */
     app: string;
@@ -48,9 +83,16 @@ export interface DeployConfig {
     namePrefix: string;
     /** AWS region the stack (and CI) target. */
     region: string;
-    /** CloudFormation stack name — defaults to `${namePrefix}-${app}`. */
+    /**
+     * CloudFormation stack name of the **prod** environment — defaults to
+     * `${namePrefix}-${app}`. Dev's stack defaults to this + `-dev`.
+     */
     stackName: string;
-    /** The GitHub repo whose CI is trusted to ship the Lambda code. */
+    /**
+     * The GitHub repo whose CI is trusted to ship the Lambda code. `branch` is the
+     * **prod** deploy branch (default `master`); the dev branch defaults to
+     * `development` and is overridable under `environments.dev.branch`.
+     */
     github: {
         owner: string;
         repo: string;
@@ -70,9 +112,80 @@ export interface DeployConfig {
     artifactsBucket?: string;
     /** Whether the function verifies the `access` or `id` token. */
     tokenUse: "access" | "id";
-    /** Values resolved from the stack after it is created (optional). */
+    /** Values resolved from the (prod) stack after it is created (optional). */
+    outputs?: DeployOutputs;
+    /**
+     * Per-environment overrides. A `dev` + `prod` split is the default even with
+     * this omitted (see `resolveEnvironment`); this only records what a user
+     * changed (a custom dev branch, dev stack outputs, …).
+     */
+    environments?: Partial<Record<EnvName, EnvOverride>>;
+}
+/** The two deployment environments — dev (development branch) and prod (master). */
+export type EnvName = "prod" | "dev";
+export declare const ENV_NAMES: readonly EnvName[];
+/** The fully-resolved shape of one environment (top-level + defaults + overrides). */
+export interface EnvDef {
+    /** Which environment this is. */
+    name: EnvName;
+    /** Branch whose push deploys it (`master` for prod, `development` for dev). */
+    branch: string;
+    /** GitHub Actions Environment name (`production` / `development`). */
+    ghEnvironment: string;
+    /**
+     * The app.yaml `AppName` parameter — the infra namespace. Prod uses the app
+     * slug; dev uses `${app}dev` so its buckets/roles/pools/SSM never collide with
+     * prod's (AppName is Cognito-safe `^[a-z0-9]{1,20}$`, so the suffix is glued,
+     * not hyphenated).
+     */
+    appName: string;
+    /** CloudFormation stack name for this environment. */
+    stackName: string;
+    /** Iceberg namespace this environment writes under. */
+    namespace: string;
+    /** Upstream the external-API proxy forwards to (empty when no proxy). */
+    proxyUpstream: string;
+    /** Values resolved from this environment's stack, when known. */
     outputs?: DeployOutputs;
 }
+/** Defaults for the dev environment when `environments.dev` is unset. */
+export declare const DEV_DEFAULTS: {
+    readonly branch: "development";
+    readonly ghEnvironment: "development";
+    readonly namespace: "development";
+};
+/** The GitHub Actions Environment name the prod deploy uses. */
+export declare const PROD_GH_ENVIRONMENT = "production";
+/**
+ * The app.yaml `AppName` for an environment — the infra namespace. Dev glues a
+ * `dev` suffix on so its stack's buckets/roles/pools/SSM are physically distinct
+ * from prod's without a hyphen (Cognito `AppName`/`IdentityPoolName` forbid one).
+ */
+export declare function envAppName(cfg: DeployConfig, env: EnvName): string;
+/**
+ * Resolve one environment to its full definition: the prod environment inherits
+ * the top-level branch/stack/namespace/outputs, the dev environment defaults to
+ * the `development` branch and a `-dev` stack, and anything under
+ * `cfg.environments[env]` overrides those.
+ */
+export declare function resolveEnvironment(cfg: DeployConfig, env: EnvName): EnvDef;
+/** Both environments, prod first, fully resolved. */
+export declare function resolveEnvironments(cfg: DeployConfig): EnvDef[];
+/**
+ * The browser-facing Cognito config for one environment — what `rastack dev`
+ * serves at `/__rastack/cognito.json` so a locally-running app can sign in
+ * against the real (dev) Cognito pool via the Hosted UI. Shaped to feed
+ * `cognitoRuntimeToConfig` in `rastack/auth`. Returns null until the
+ * environment's stack Outputs (client id + Hosted UI url) are known.
+ */
+export interface CognitoRuntimeConfig {
+    userPoolId?: string;
+    clientId: string;
+    /** Hosted UI base URL (`https://…amazoncognito.com`). */
+    hostedUiUrl: string;
+    region: string;
+}
+export declare function cognitoRuntimeConfig(cfg: DeployConfig, env: EnvName): CognitoRuntimeConfig | null;
 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">;
@@ -136,6 +249,16 @@ export declare function cognitoAdvancedSecuritySupported(region: string): boolea
  * the template's ENFORCED default stands).
  */
 export declare function stackParameters(cfg: DeployConfig): StackParameter[];
+/**
+ * The app.yaml `--parameter-overrides` for a **specific environment** (dev or
+ * prod). Same as `stackParameters` but the AppName/branch/namespace come from the
+ * resolved environment, and it also passes `GitHubEnvironment` so the stack's
+ * deploy-role trust is scoped to the GitHub Actions Environment (the OIDC subject
+ * for an environment-gated job is `…:environment:<env>`, not `…:ref:…`). Prod's
+ * AppName is the bare slug, so prod's resource names are byte-for-byte what the
+ * pre-environment template produced.
+ */
+export declare function stackParametersForEnv(cfg: DeployConfig, env: EnvName): StackParameter[];
 /**
  * The canonical repo-relative CloudFormation template paths. These are the paths
  * in the *framework* repo (theserverkid/reactapistack) and the default the argv
@@ -158,6 +281,10 @@ export declare function deployStackArgs(cfg: DeployConfig, templateFile?: string
  * for you; it is also printed by `--print` so it can be run by hand.
  */
 export declare function deployStackCommand(cfg: DeployConfig, templateFile?: string): string;
+/** The `aws cloudformation deploy` argv for one environment's stack (dev/prod). */
+export declare function deployStackArgsForEnv(cfg: DeployConfig, env: EnvName, templateFile?: string): string[];
+/** The single-line `aws cloudformation deploy` command for one environment. */
+export declare function deployStackCommandForEnv(cfg: DeployConfig, env: EnvName, templateFile?: string): 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
@@ -193,14 +320,28 @@ export interface RepoVariable {
     name: string;
     value: string;
     from: string;
+    /**
+     * The GitHub Actions **Environment** this Variable is scoped to (`development`
+     * / `production`). When set, `init` wires it under that environment so the
+     * dev and prod deploys each read their own role/region.
+     */
+    ghEnvironment?: 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.
+ * Console. This is the legacy single-environment view (the prod stack); the
+ * dev/prod split wires them per GitHub Environment via `repoVariablesForEnv`.
  */
 export declare function repoVariables(cfg: DeployConfig): RepoVariable[];
+/**
+ * The same two Variables, scoped to one environment's GitHub Actions
+ * Environment. The dev deploy reads `development`'s copies, the prod deploy
+ * `production`'s — so the two never cross-assume each other's role. Values come
+ * from the environment's own stack Outputs.
+ */
+export declare function repoVariablesForEnv(cfg: DeployConfig, env: EnvName): RepoVariable[];
 /**
  * The argv (after `gh`) that sets one GitHub repo **Variable** on the config's
  * repo. `init` runs this for each resolved `repoVariables` entry so the
@@ -210,7 +351,16 @@ export declare function repoVariables(cfg: DeployConfig): RepoVariable[];
  * user's GitHub) rather than an API token; a pure argv so it is inspectable and
  * shell-free (`execFileSync`).
  */
-export declare function ghVariableSetArgs(cfg: DeployConfig, name: string, value: string): string[];
+export declare function ghVariableSetArgs(cfg: DeployConfig, name: string, value: string, ghEnvironment?: string): string[];
+/**
+ * The argv (after `gh`) that creates (idempotently) a GitHub Actions
+ * **Environment** on the config's repo — `gh api --method PUT
+ * repos/{owner}/{repo}/environments/{env}`. `init` runs this for `development`
+ * and `production` before wiring their scoped Variables, since a Variable can
+ * only be set on an environment that already exists. PUT is idempotent, so
+ * re-running `init` is safe.
+ */
+export declare function ghEnvironmentCreateArgs(cfg: DeployConfig, ghEnvironment: string): string[];
 /**
  * The `RASTACK_*` environment the Lambda reads (docs/serverless-deploy.md §1).
  * The IaC sets these on the function; surfaced here for `rastack deploy` to