rastack 0.0.63 → 0.0.64

package/src/compile/analyze.ts

@@ -179,7 +179,17 @@ function analyzeField(
     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: FieldModel = { 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/src/define/index.ts

@@ -66,6 +66,9 @@ 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 {
@@ -153,8 +156,9 @@ export const s = {
    */
   ref<A extends string, M extends string>(
     thunk: () => ResourceType<A, M, any>,
+    options?: { null?: boolean },
   ): Ref<A, M> {
-    return { __rastackRef: true, target: thunk } as Ref<A, M>;
+    return { __rastackRef: true, target: thunk, options } as Ref<A, M>;
   },
 };
 

package/src/define/manifest.ts

@@ -121,11 +121,17 @@ function runtimeField(
         `manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`,
       );
     }
-    return {
+    const fk: FieldModel = {
       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 as { null?: boolean } | undefined)?.null === true) {
+      fk.null = true;
+    }
+    return fk;
   }
 
   if (typeof field.__rastackScalar !== "string") return undefined;

package/src/deploy/io.ts

@@ -6,11 +6,20 @@
 
 import { execFileSync, execSync } from "child_process";
 import * as fs from "fs";
+import * as https from "https";
 import * as os from "os";
 import * as path from "path";
 import * as readline from "readline";
 import { CONFIG_PATH } from "./workflows";
-import { DeployConfig, PartialDeployConfig, normalizeConfig } from "./config";
+import {
+  BOOTSTRAP_ARTIFACTS_OUTPUT,
+  BOOTSTRAP_TEMPLATES_OUTPUT,
+  DeployConfig,
+  PartialDeployConfig,
+  bootstrapStackArgs,
+  bootstrapStackName,
+  normalizeConfig,
+} from "./config";
 import { zipStore } from "./zip";
 
 /** Absolute path to the deploy config for a project root. */
@@ -50,6 +59,65 @@ export function resolveDeployAsset(
   return null;
 }
 
+/**
+ * Base URL the framework's CloudFormation templates are published at. The same
+ * site that hosts the installer (`reactapistack.com/setup.sh`) serves the base
+ * templates, so a CLI whose bundled copy is missing (a partial install, or a
+ * globally-linked dev build) can still fetch them.
+ */
+export const TEMPLATE_BASE_URL = "https://reactapistack.com/cloudformation";
+
+/**
+ * Download a published CloudFormation template to a temp file, returning its
+ * path — or null on any failure (offline, 404, write error). Used as the
+ * fallback when the template is not bundled with the install.
+ */
+export function downloadTemplate(
+  name: string,
+  base = TEMPLATE_BASE_URL,
+): Promise<string | null> {
+  const url = `${base}/${name}`;
+  return new Promise((resolve) => {
+    https
+      .get(url, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            const dest = path.join(
+              os.tmpdir(),
+              `rastack-${path.basename(name)}`,
+            );
+            fs.writeFileSync(dest, Buffer.concat(chunks));
+            resolve(dest);
+          } catch {
+            resolve(null);
+          }
+        });
+      })
+      .on("error", () => resolve(null));
+  });
+}
+
+/**
+ * Resolve a CloudFormation template to a local file path for `aws cloudformation
+ * deploy` (which accepts only `--template-file`). Prefers the copy bundled with
+ * the `rastack` install; when that is missing, downloads it from the React API
+ * Stack website. Returns null only when the template is neither bundled nor
+ * fetchable.
+ */
+export async function resolveTemplateFile(
+  name: string,
+  cwd = process.cwd(),
+): Promise<string | null> {
+  return resolveDeployAsset(name, cwd) ?? (await downloadTemplate(name));
+}
+
 /** 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);
@@ -121,6 +189,26 @@ export function awsAvailable(): boolean {
   return awsCapture(["--version"]) !== null;
 }
 
+/**
+ * The AWS account id the CLI's active credentials resolve to, or null when the
+ * CLI has no usable credentials (not logged in, an expired SSO session, or no
+ * configured profile). `init`/`bootstrap` call this to fail fast with an
+ * actionable "log in" message before attempting a stack deploy, instead of
+ * letting the first `cloudformation deploy` fail with a cryptic AWS error.
+ */
+export function awsIdentity(region?: string): string | null {
+  const args = [
+    "sts",
+    "get-caller-identity",
+    "--query",
+    "Account",
+    "--output",
+    "text",
+  ];
+  if (region) args.push("--region", region);
+  return awsCapture(args);
+}
+
 /**
  * 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
@@ -176,6 +264,79 @@ export function uploadPlaceholder(
   return true;
 }
 
+/**
+ * Deploy the tier-0 bootstrap stack, retrying once against an account that
+ * already has a GitHub OIDC provider — AWS allows only one provider per URL, so
+ * a second create is rejected and the retry tells the template to reuse the
+ * existing one. Throws on failure (after the retry). Shared by `rastack init`
+ * and `rastack bootstrap` so both stand the stack up identically.
+ */
+export function deployBootstrap(
+  cfg: DeployConfig,
+  reuseOidc: boolean,
+  template: string,
+): void {
+  try {
+    awsRun(bootstrapStackArgs(cfg, reuseOidc, template));
+  } catch (err) {
+    if (reuseOidc) throw err;
+    console.log(
+      "  • retrying bootstrap, reusing the account's existing GitHub OIDC provider",
+    );
+    awsRun(bootstrapStackArgs(cfg, true, template));
+  }
+}
+
+/**
+ * Ensure the tier-0 bootstrap stack exists for this account+region, **creating
+ * it when missing**, and return its artifacts/templates buckets. This is why
+ * `rastack init` is a single command that stands up *everything* — the
+ * account-level bootstrap stack and the per-app backend — with no separate
+ * `rastack bootstrap` step. Idempotent: an existing stack is reconciled in
+ * place. Throws with an actionable message when the template cannot be resolved,
+ * the deploy fails, or the buckets can't be read back.
+ */
+export async function ensureBootstrapStack(
+  cfg: DeployConfig,
+  reuseOidc = false,
+): Promise<{ artifactsBucket: string; templatesBucket: string | null }> {
+  const stack = bootstrapStackName(cfg);
+  const existing = stackOutput(stack, BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
+  if (existing) {
+    console.log(`  ✓ bootstrap stack ${stack} already exists — reconciling`);
+  } else {
+    console.log(
+      `\n▸ Creating the tier-0 bootstrap stack ${stack} (@ ${cfg.region})`,
+    );
+  }
+
+  const template = await resolveTemplateFile("bootstrap.yaml");
+  if (!template) {
+    throw new Error(
+      "bootstrap.yaml template not found in the rastack package and could not be\n" +
+        "    downloaded from reactapistack.com. Reinstall rastack (`npm i -g rastack`).",
+    );
+  }
+  deployBootstrap(cfg, reuseOidc, template);
+
+  const artifactsBucket = stackOutput(
+    stack,
+    BOOTSTRAP_ARTIFACTS_OUTPUT,
+    cfg.region,
+  );
+  const templatesBucket = stackOutput(
+    stack,
+    BOOTSTRAP_TEMPLATES_OUTPUT,
+    cfg.region,
+  );
+  if (!artifactsBucket) {
+    throw new Error(
+      `bootstrap stack ${stack} deployed but its ArtifactsBucket output could not be read.`,
+    );
+  }
+  return { artifactsBucket, templatesBucket };
+}
+
 // ── GitHub CLI boundary ──────────────────────────────────────────────────────
 // After the stack is up `init` wires the two repo Variables CI reads
 // (AWS_DEPLOY_ROLE_ARN / AWS_REGION) through the developer's own `gh` — already

package/src/rastack-bootstrap.ts

@@ -25,11 +25,8 @@
  */
 
 import {
-  BOOTSTRAP_ARTIFACTS_OUTPUT,
-  BOOTSTRAP_TEMPLATES_OUTPUT,
   DeployConfig,
   PartialDeployConfig,
-  bootstrapStackArgs,
   bootstrapStackCommand,
   bootstrapStackName,
   mergeConfig,
@@ -40,12 +37,12 @@ import {
 import {
   ask,
   awsAvailable,
-  awsRun,
+  awsIdentity,
   canPrompt,
+  ensureBootstrapStack,
   gitRemoteUrl,
   loadConfig,
   resolveDeployAsset,
-  stackOutput,
   uploadPlaceholder,
   withPrompt,
 } from "./deploy/io";
@@ -164,47 +161,12 @@ function printPlan(cfg: DeployConfig, reuseOidc: boolean): void {
 }
 
 /**
- * Deploy the bootstrap stack, retrying once against an account that already has
- * a GitHub OIDC provider (AWS allows only one per URL) when the caller did not
- * already ask to reuse it.
+ * Stand the tier-0 bootstrap stack up and upload the Lambda placeholder. The
+ * deploy (with the GitHub-OIDC-reuse retry) and template resolution are shared
+ * with `rastack init` via `ensureBootstrapStack`, so both stand the stack up
+ * identically.
  */
-function deployBootstrap(cfg: DeployConfig, reuseOidc: boolean): void {
-  const template = resolveDeployAsset("bootstrap.yaml");
-  if (!template) {
-    console.error(
-      "  ✗ bootstrap.yaml template not found in the rastack package. Reinstall\n" +
-        "    rastack (`npm i -g rastack`) or run from the framework repo.",
-    );
-    process.exit(1);
-  }
-  try {
-    awsRun(bootstrapStackArgs(cfg, reuseOidc, template));
-  } catch (err) {
-    if (reuseOidc) {
-      console.error(
-        `\n  ✗ bootstrap stack deploy failed.\n    ${(err as Error).message}`,
-      );
-      process.exit(1);
-    }
-    // The most common cause is an account that already has a GitHub OIDC
-    // provider. Retry telling the template to reuse it instead of creating a
-    // second (which CloudFormation rejects).
-    console.log(
-      "  • retrying bootstrap, reusing the account's existing GitHub OIDC provider",
-    );
-    try {
-      awsRun(bootstrapStackArgs(cfg, true, template));
-    } catch (retryErr) {
-      console.error(
-        `\n  ✗ bootstrap stack deploy failed.\n    ${(retryErr as Error).message}`,
-      );
-      process.exit(1);
-    }
-  }
-}
-
-/** Stand the tier-0 bootstrap stack up and upload the Lambda placeholder. */
-function standUp(cfg: DeployConfig, reuseOidc: boolean): void {
+async function standUp(cfg: DeployConfig, reuseOidc: boolean): Promise<void> {
   if (!awsAvailable()) {
     console.error(
       "  ✗ the AWS CLI is not on PATH. Install it and configure credentials,\n" +
@@ -213,33 +175,26 @@ function standUp(cfg: DeployConfig, reuseOidc: boolean): void {
     process.exit(1);
   }
 
-  const stack = bootstrapStackName(cfg);
-  const existing = stackOutput(stack, BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region);
-  if (existing) {
-    console.log(
-      `\n▸ Bootstrap stack ${stack} already exists — reconciling (idempotent).`,
-    );
-  } else {
-    console.log(`\n▸ Creating bootstrap stack ${stack} (@ ${cfg.region})`);
-  }
-  deployBootstrap(cfg, reuseOidc);
-
-  const artifactsBucket = stackOutput(
-    stack,
-    BOOTSTRAP_ARTIFACTS_OUTPUT,
-    cfg.region,
-  );
-  const templatesBucket = stackOutput(
-    stack,
-    BOOTSTRAP_TEMPLATES_OUTPUT,
-    cfg.region,
-  );
-  if (!artifactsBucket) {
+  // Verify the AWS CLI is logged in before attempting a stack deploy.
+  const account = awsIdentity(cfg.region);
+  if (!account) {
     console.error(
-      "  ✗ bootstrap stack deployed but its ArtifactsBucket output could not be read.",
+      "  ✗ the AWS CLI has no usable credentials — it is not logged in.\n" +
+        "    Run `aws configure` (or `aws sso login`), then re-run `rastack bootstrap`.\n" +
+        "    Or re-run with --print to see the command.",
     );
     process.exit(1);
   }
+  console.log(`  ✓ AWS account ${account} (${cfg.region})`);
+
+  const stack = bootstrapStackName(cfg);
+  const { artifactsBucket, templatesBucket } = await ensureBootstrapStack(
+    cfg,
+    reuseOidc,
+  ).catch((err: Error) => {
+    console.error(`\n  ✗ ${err.message}`);
+    process.exit(1);
+  });
   console.log(`  ✓ artifacts bucket:  ${artifactsBucket}`);
   if (templatesBucket) console.log(`  ✓ templates bucket:  ${templatesBucket}`);
 
@@ -299,7 +254,7 @@ async function main(argv: string[]): Promise<void> {
     }
   }
 
-  standUp(cfg, flags.reuseOidc);
+  await standUp(cfg, flags.reuseOidc);
 }
 
 if (require.main === module) {

package/src/rastack-init.ts

@@ -12,14 +12,17 @@
  *   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 — erroring with a
- *      pointer to `rastack bootstrap` when that account+region stack is missing
- *      (init is per-app and never creates account-level infrastructure);
+ *   2. verifies the AWS CLI is logged in, then ensures the tier-0 bootstrap stack
+ *      exists — creating it (the S3 template/placeholder buckets + GitHub OIDC
+ *      provider) when missing, reconciling it when it already does;
  *   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.
  *
+ * The CloudFormation templates ship inside the `rastack` package; a partial
+ * install falls back to downloading them from reactapistack.com.
+ *
  * 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.
@@ -30,12 +33,12 @@ import * as path from "path";
 import {
   APP_STACK_OUTPUTS,
   BOOTSTRAP_ARTIFACTS_OUTPUT,
-  BOOTSTRAP_TEMPLATES_OUTPUT,
   DeployConfig,
   DeployOutputs,
   EnvName,
   ENV_NAMES,
   PartialDeployConfig,
+  bootstrapStackCommand,
   bootstrapStackName,
   deployStackCommandForEnv,
   deployStackArgsForEnv,
@@ -58,8 +61,10 @@ import {
 import {
   ask,
   awsAvailable,
+  awsIdentity,
   awsRun,
   canPrompt,
+  ensureBootstrapStack,
   ghAuthLogin,
   ghAuthenticated,
   ghAvailable,
@@ -67,6 +72,7 @@ import {
   gitRemoteUrl,
   loadConfig,
   resolveDeployAsset,
+  resolveTemplateFile,
   saveConfig,
   setRepoVariable,
   stackOutput,
@@ -281,8 +287,10 @@ function envLabel(cfg: DeployConfig, env: EnvName): string {
 
 /**
  * Print the exact commands `init` would run, without touching the cloud
- * (`--print`). The artifacts bucket is read from the bootstrap stack when the
- * AWS CLI is available, else shown as a placeholder.
+ * (`--print`). init stands up *both* stacks, so both `aws cloudformation deploy`
+ * commands are shown: the tier-0 bootstrap stack (created only when missing) and
+ * the per-app backend. The artifacts bucket is read from an existing bootstrap
+ * stack when the AWS CLI is available, else shown as a placeholder.
  */
 function printPlan(cfg: DeployConfig, envs: EnvName[]): void {
   const bucket = awsAvailable()
@@ -295,16 +303,15 @@ function printPlan(cfg: DeployConfig, envs: EnvName[]): void {
   const withBucket = mergeConfig(cfg, {
     artifactsBucket: bucket ?? "<ArtifactsBucketName from bootstrap stack>",
   });
+  const bootstrapTemplate = resolveDeployAsset("bootstrap.yaml") ?? undefined;
   const appTemplate = resolveDeployAsset("app.yaml") ?? undefined;
   console.log(`\n  Deployment plan (${envs.join(" + ")} @ ${cfg.region})\n`);
   console.log(
-    `  ── Prerequisite: the tier-0 bootstrap stack (${bootstrapStackName(cfg)}) must exist ──`,
-  );
-  console.log(
-    `  Create it once per account+region (init does not):  rastack bootstrap --region ${cfg.region}\n`,
+    `  ── 1. Tier-0 bootstrap stack (${bootstrapStackName(cfg)}) — created only when missing ──`,
   );
+  console.log("\n  " + bootstrapStackCommand(cfg, false, bootstrapTemplate) + "\n");
   console.log(
-    "  ── 1. Per-app backend (app.yaml) — one stack per environment ──",
+    "  ── 2. Per-app backend (app.yaml) — one stack per environment ──",
   );
   for (const env of envs) {
     const e = resolveEnvironment(withBucket, env);
@@ -330,9 +337,12 @@ function printPlan(cfg: DeployConfig, envs: EnvName[]): void {
 }
 
 /**
- * Stand the infrastructure up: ensure the bootstrap stack + artifacts bucket,
- * upload the Lambda placeholder, deploy app.yaml, and read the Outputs back into
- * the config. Returns the config enriched with the resolved buckets + outputs.
+ * Stand the infrastructure up: verify the AWS CLI is logged in, ensure the
+ * tier-0 bootstrap stack (creating it when missing), upload the Lambda
+ * placeholder, deploy app.yaml, and read the Outputs back into the config.
+ * `init` is the single command that stands up *everything* — there is no
+ * separate manual bootstrap step. Returns the config enriched with the resolved
+ * buckets + outputs.
  */
 async function standUp(
   cfg: DeployConfig,
@@ -347,33 +357,32 @@ async function standUp(
     process.exit(1);
   }
 
-  // 1. Resolve the artifacts bucket from the tier-0 bootstrap stack. That stack
-  //    is an account+region once-off — the S3 buckets that host the templates +
-  //    Lambda placeholder, and the GitHub OIDC provider. `init` is a per-app
-  //    command and deliberately does NOT create it: standing up account-level
-  //    infrastructure is `rastack bootstrap`'s job (run once by an account admin),
-  //    so a missing bootstrap stack is a clear, actionable error, not an implicit
-  //    account mutation buried inside an app deploy.
-  const artifactsBucket = stackOutput(
-    bootstrapStackName(cfg),
-    BOOTSTRAP_ARTIFACTS_OUTPUT,
-    cfg.region,
-  );
-  const templatesBucket = stackOutput(
-    bootstrapStackName(cfg),
-    BOOTSTRAP_TEMPLATES_OUTPUT,
-    cfg.region,
-  );
-  if (!artifactsBucket) {
+  // Verify the AWS CLI is actually logged in before creating any stacks, so a
+  // missing/expired credential fails fast with an actionable message rather than
+  // a cryptic `cloudformation deploy` error partway through.
+  const account = awsIdentity(cfg.region);
+  if (!account) {
     console.error(
-      `\n  ✗ Bootstrap stack ${bootstrapStackName(cfg)} not found in ${cfg.region}.\n` +
-        "    It is the once-per-account+region step that hosts the CloudFormation\n" +
-        "    templates and the Lambda placeholder every app deploy reads. Create it\n" +
-        "    first (an account admin does this once), then re-run `rastack init`:\n\n" +
-        `      rastack bootstrap --region ${cfg.region}\n`,
+      "  ✗ the AWS CLI has no usable credentials — it is not logged in.\n" +
+        "    Configure credentials, then re-run `rastack init`:\n" +
+        "      aws configure            # static access key / secret\n" +
+        "      aws sso login            # or an existing SSO session\n" +
+        "    Or re-run with --print to see the commands, or --no-deploy to skip.",
     );
     process.exit(1);
   }
+  console.log(`  ✓ AWS account ${account} (${cfg.region})`);
+
+  // 1. Ensure the tier-0 bootstrap stack exists — the S3 buckets that host the
+  //    templates + Lambda placeholder and the GitHub OIDC provider. init creates
+  //    it when missing (idempotent for an existing one), so a single command
+  //    takes an account+repo from nothing to a deployed backend.
+  const { artifactsBucket, templatesBucket } = await ensureBootstrapStack(
+    cfg,
+  ).catch((err: Error) => {
+    console.error(`\n  ✗ ${err.message}`);
+    process.exit(1);
+  });
   console.log(`  ✓ artifacts bucket: ${artifactsBucket}`);
 
   // 2. Upload the placeholder the function is created from (shared by all envs).
@@ -389,11 +398,11 @@ async function standUp(
     artifactsBucket,
     templatesBucket: templatesBucket ?? undefined,
   });
-  const appTemplate = resolveDeployAsset("app.yaml");
+  const appTemplate = await resolveTemplateFile("app.yaml");
   if (!appTemplate) {
     console.error(
-      "  ✗ app.yaml template not found in the rastack package. Reinstall rastack\n" +
-        "    (`npm i -g rastack`) or run from the framework repo.",
+      "  ✗ app.yaml template not found in the rastack package and could not be\n" +
+        "    downloaded from reactapistack.com. Reinstall rastack (`npm i -g rastack`).",
     );
     process.exit(1);
   }
@@ -623,7 +632,7 @@ async function main(argv: string[]): Promise<void> {
       .map((env) => resolveEnvironment(cfg, env).stackName)
       .join(" + ");
     const ok = await confirm(
-      `Deploy ${stacks} to AWS ${cfg.region} now? (requires the bootstrap stack to exist) [y/N]`,
+      `Deploy ${stacks} to AWS ${cfg.region} now? (creates the bootstrap stack if missing) [y/N]`,
     );
     if (!ok) {
       console.log(