rastack 0.0.62 → 0.0.63

package/src/deploy/ci.ts

@@ -16,7 +16,12 @@
  * the same plan works before and after they are wired into the config.
  */
 
-import { DeployConfig } from "./config";
+import {
+  DeployConfig,
+  DeployOutputs,
+  EnvName,
+  resolveEnvironment,
+} from "./config";
 
 export type CiPhase = "check" | "build" | "deploy";
 
@@ -55,27 +60,47 @@ 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;
+}
+
+/** The stack name + outputs + app label the plan targets, honouring `opts.env`. */
+function ciTarget(
+  cfg: DeployConfig,
+  opts: CiPlanOptions,
+): { stackName: string; outputs?: DeployOutputs; app: string } {
+  if (opts.env) {
+    const e = 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: DeployConfig,
+  stackName: string,
+  region: string,
   outputKey: string,
   literal?: string,
 ): string {
   if (literal) return literal;
   return (
-    `$(aws cloudformation describe-stacks --stack-name ${cfg.stackName} ` +
-    `--region ${cfg.region} ` +
+    `$(aws cloudformation describe-stacks --stack-name ${stackName} ` +
+    `--region ${region} ` +
     `--query "Stacks[0].Outputs[?OutputKey=='${outputKey}'].OutputValue" ` +
     `--output text)`
   );
@@ -107,11 +132,13 @@ export function buildSteps(
   opts: CiPlanOptions = {},
 ): CiStep[] {
   const stage = stageDir(cfg);
+  const target = ciTarget(cfg, opts);
   const archFlag = cfg.lambda.arch === "arm64" ? "--arm64" : "--x86-64";
   const jwks = stackOutput(
-    cfg,
+    target.stackName,
+    cfg.region,
     "JwksUrl",
-    opts.jwksUrl ?? cfg.outputs?.jwksUrl,
+    opts.jwksUrl ?? target.outputs?.jwksUrl,
   );
   return [
     compileStep(cfg),
@@ -146,12 +173,19 @@ export function deploySteps(
 ): CiStep[] {
   const stage = stageDir(cfg);
   const zip = `${stage}/bootstrap.zip`;
+  const target = ciTarget(cfg, opts);
   const fn = stackOutput(
-    cfg,
+    target.stackName,
+    cfg.region,
     "FunctionName",
-    opts.functionName ?? cfg.outputs?.functionName,
+    opts.functionName ?? target.outputs?.functionName,
+  );
+  const apiUrl = stackOutput(
+    target.stackName,
+    cfg.region,
+    "ApiUrl",
+    target.outputs?.apiUrl,
   );
-  const apiUrl = stackOutput(cfg, "ApiUrl", cfg.outputs?.apiUrl);
   const steps: CiStep[] = opts.skipBuild ? [] : buildSteps(cfg, opts);
   steps.push(
     {
@@ -167,7 +201,7 @@ export function deploySteps(
     },
     {
       name: "Report the API URL",
-      run: `echo "Deployed ${cfg.app} → ${apiUrl}"`,
+      run: `echo "Deployed ${target.app} → ${apiUrl}"`,
     },
   );
   return steps;

package/src/deploy/config.ts

@@ -33,6 +33,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 {
@@ -44,6 +50,36 @@ export interface LambdaBuild {
   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;
@@ -51,9 +87,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; branch: string };
   /** Iceberg namespace the warehouse writes under. */
   namespace: string;
@@ -69,10 +112,130 @@ 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 const ENV_NAMES: readonly EnvName[] = ["prod", "dev"] as const;
+
+/** 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 const DEV_DEFAULTS = {
+  branch: "development",
+  ghEnvironment: "development",
+  namespace: "development",
+} as const;
+
+/** The GitHub Actions Environment name the prod deploy uses. */
+export 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 function envAppName(cfg: DeployConfig, env: EnvName): string {
+  return env === "dev" ? `${cfg.app}dev` : cfg.app;
+}
+
+/**
+ * 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 function resolveEnvironment(cfg: DeployConfig, env: EnvName): EnvDef {
+  const o = cfg.environments?.[env] ?? {};
+  if (env === "prod") {
+    return {
+      name: "prod",
+      branch: o.branch ?? cfg.github.branch,
+      ghEnvironment: o.ghEnvironment ?? PROD_GH_ENVIRONMENT,
+      appName: cfg.app,
+      stackName: o.stackName ?? cfg.stackName,
+      namespace: o.namespace ?? cfg.namespace,
+      proxyUpstream: o.proxyUpstream ?? "",
+      outputs: o.outputs ?? cfg.outputs,
+    };
+  }
+  return {
+    name: "dev",
+    branch: o.branch ?? DEV_DEFAULTS.branch,
+    ghEnvironment: o.ghEnvironment ?? DEV_DEFAULTS.ghEnvironment,
+    appName: envAppName(cfg, "dev"),
+    stackName: o.stackName ?? (cfg.stackName ? `${cfg.stackName}-dev` : ""),
+    namespace: o.namespace ?? DEV_DEFAULTS.namespace,
+    proxyUpstream: o.proxyUpstream ?? "",
+    outputs: o.outputs,
+  };
+}
+
+/** Both environments, prod first, fully resolved. */
+export function resolveEnvironments(cfg: DeployConfig): EnvDef[] {
+  return ENV_NAMES.map((e) => resolveEnvironment(cfg, e));
+}
+
+/**
+ * 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 function cognitoRuntimeConfig(
+  cfg: DeployConfig,
+  env: EnvName,
+): CognitoRuntimeConfig | null {
+  const o = resolveEnvironment(cfg, env).outputs;
+  if (!o?.userPoolClientId || !o?.hostedUiUrl) return null;
+  return {
+    userPoolId: o.userPoolId,
+    clientId: o.userPoolClientId,
+    hostedUiUrl: o.hostedUiUrl,
+    region: cfg.region,
+  };
+}
+
 export const DEFAULT_LAMBDA: LambdaBuild = {
   bin: "bootstrap",
   arch: "arm64",
@@ -132,9 +295,31 @@ export function normalizeConfig(
     artifactsBucket: partial.artifactsBucket?.trim() || undefined,
     tokenUse: partial.tokenUse ?? DEFAULTS.tokenUse,
     outputs: partial.outputs ? { ...partial.outputs } : undefined,
+    environments: normalizeEnvironments(partial.environments),
   };
 }
 
+/** Copy through per-environment overrides, dropping an empty map to undefined. */
+function normalizeEnvironments(
+  envs: PartialDeployConfig["environments"],
+): DeployConfig["environments"] {
+  if (!envs) return undefined;
+  const out: Partial<Record<EnvName, EnvOverride>> = {};
+  for (const name of ENV_NAMES) {
+    const o = envs[name];
+    if (!o) continue;
+    const entry: EnvOverride = {};
+    if (o.branch?.trim()) entry.branch = o.branch.trim();
+    if (o.ghEnvironment?.trim()) entry.ghEnvironment = o.ghEnvironment.trim();
+    if (o.stackName?.trim()) entry.stackName = o.stackName.trim();
+    if (o.namespace?.trim()) entry.namespace = o.namespace.trim();
+    if (o.proxyUpstream?.trim()) entry.proxyUpstream = o.proxyUpstream.trim();
+    if (o.outputs) entry.outputs = { ...o.outputs };
+    if (Object.keys(entry).length) out[name] = entry;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 const SLUG = /^[a-z0-9]{1,20}$/;
 const REGION = /^[a-z]{2}-[a-z]+-\d+$/;
 const GH_NAME = /^[A-Za-z0-9_.-]+$/;
@@ -152,6 +337,14 @@ export function validateConfig(cfg: DeployConfig): string[] {
     errors.push(
       `app "${cfg.app}" must match ${SLUG} (lowercase letters/digits, 1–20).`,
     );
+  // The dev environment appends "dev" to the app slug for its infra namespace
+  // (buckets/roles/pools/SSM). That derived name must still be a valid slug, so
+  // the app slug is effectively capped at 17 chars once a dev env is in play.
+  else if (!SLUG.test(envAppName(cfg, "dev")))
+    errors.push(
+      `app "${cfg.app}" is too long: the dev environment uses "${envAppName(cfg, "dev")}" ` +
+        `for its infra names, which must still match ${SLUG} (so app ≤ 17 chars).`,
+    );
 
   if (!SLUG.test(cfg.namePrefix))
     errors.push(`namePrefix "${cfg.namePrefix}" must match ${SLUG}.`);
@@ -226,9 +419,31 @@ export function mergeConfig(
     github: { ...base.github, ...patch.github },
     lambda: { ...base.lambda, ...patch.lambda },
     outputs: { ...base.outputs, ...patch.outputs },
+    environments: mergeEnvironments(base.environments, patch.environments),
   });
 }
 
+/** Deep-merge per-environment overrides (per env, and per env's outputs). */
+function mergeEnvironments(
+  base: DeployConfig["environments"],
+  patch: PartialDeployConfig["environments"],
+): DeployConfig["environments"] {
+  if (!base && !patch) return undefined;
+  const out: Partial<Record<EnvName, EnvOverride>> = {};
+  for (const name of ENV_NAMES) {
+    const b = base?.[name];
+    const p = patch?.[name];
+    if (!b && !p) continue;
+    out[name] = {
+      ...b,
+      ...p,
+      outputs:
+        b?.outputs || p?.outputs ? { ...b?.outputs, ...p?.outputs } : undefined,
+    };
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 /**
  * Recover `{ owner, repo }` from a GitHub remote URL — both the SSH
  * (`git@github.com:owner/repo.git`) and HTTPS
@@ -314,6 +529,40 @@ export function stackParameters(cfg: DeployConfig): StackParameter[] {
   return params;
 }
 
+/**
+ * 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 function stackParametersForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+): StackParameter[] {
+  const e = resolveEnvironment(cfg, env);
+  const params: StackParameter[] = [
+    { key: "AppName", value: e.appName },
+    { key: "NamePrefix", value: cfg.namePrefix },
+    { key: "GitHubOwner", value: cfg.github.owner },
+    { key: "GitHubRepo", value: cfg.github.repo },
+    { key: "GitHubBranch", value: e.branch },
+    { key: "GitHubEnvironment", value: e.ghEnvironment },
+    { key: "IcebergNamespace", value: e.namespace },
+  ];
+  if (cfg.artifactsBucket)
+    params.push({ key: "ArtifactsBucket", value: cfg.artifactsBucket });
+  // The external-API proxy is provisioned only when an upstream is configured
+  // (typically dev → a UAT/prod backend). Empty leaves the route/authorizer out.
+  if (e.proxyUpstream)
+    params.push({ key: "ExternalApiUpstream", value: e.proxyUpstream });
+  if (!cognitoAdvancedSecuritySupported(cfg.region))
+    params.push({ key: "AdvancedSecurity", value: "OFF" });
+  return params;
+}
+
 /**
  * The canonical repo-relative CloudFormation template paths. These are the paths
  * in the *framework* repo (theserverkid/reactapistack) and the default the argv
@@ -399,6 +648,29 @@ export function deployStackCommand(
   return awsCommand(deployStackArgs(cfg, templateFile));
 }
 
+/** The `aws cloudformation deploy` argv for one environment's stack (dev/prod). */
+export function deployStackArgsForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string[] {
+  return cfnDeployArgs(
+    templateFile,
+    resolveEnvironment(cfg, env).stackName,
+    cfg.region,
+    stackParametersForEnv(cfg, env),
+  );
+}
+
+/** The single-line `aws cloudformation deploy` command for one environment. */
+export function deployStackCommandForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+  templateFile: string = APP_TEMPLATE_FILE,
+): string {
+  return awsCommand(deployStackArgsForEnv(cfg, env, templateFile));
+}
+
 /**
  * The tier-0 bootstrap stack (bootstrap.yaml) — the S3 buckets that hold the
  * Lambda placeholder + hosted templates, and the GitHub OIDC provider. One per
@@ -470,6 +742,9 @@ export const APP_STACK_OUTPUTS: { key: string; field: keyof DeployOutputs }[] =
     { key: "UserPoolClientId", field: "userPoolClientId" },
     { key: "JwksUrl", field: "jwksUrl" },
     { key: "WarehouseBucketName", field: "warehouseBucket" },
+    { key: "UserPoolDomain", field: "userPoolDomain" },
+    { key: "HostedUiUrl", field: "hostedUiUrl" },
+    { key: "ProxyUrl", field: "proxyUrl" },
   ];
 
 /** GitHub repo Variable to wire (name + resolved value, if known from outputs). */
@@ -477,13 +752,20 @@ 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 function repoVariables(cfg: DeployConfig): RepoVariable[] {
   return [
@@ -496,6 +778,33 @@ export 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 function repoVariablesForEnv(
+  cfg: DeployConfig,
+  env: EnvName,
+): RepoVariable[] {
+  const e = resolveEnvironment(cfg, env);
+  return [
+    {
+      name: "AWS_DEPLOY_ROLE_ARN",
+      value: e.outputs?.deployRoleArn ?? "",
+      from: "DeployRoleArn stack output",
+      ghEnvironment: e.ghEnvironment,
+    },
+    {
+      name: "AWS_REGION",
+      value: cfg.region,
+      from: "Region stack output",
+      ghEnvironment: e.ghEnvironment,
+    },
+  ];
+}
+
 /**
  * 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
@@ -509,15 +818,39 @@ export function ghVariableSetArgs(
   cfg: DeployConfig,
   name: string,
   value: string,
+  ghEnvironment?: string,
 ): string[] {
-  return [
+  const args = [
     "variable",
     "set",
     name,
     "--repo",
     `${cfg.github.owner}/${cfg.github.repo}`,
-    "--body",
-    value,
+  ];
+  // Scope the Variable to a GitHub Actions Environment when one is given, so the
+  // dev and prod deploys each read their own role/region.
+  if (ghEnvironment) args.push("--env", ghEnvironment);
+  args.push("--body", value);
+  return args;
+}
+
+/**
+ * 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 function ghEnvironmentCreateArgs(
+  cfg: DeployConfig,
+  ghEnvironment: string,
+): string[] {
+  return [
+    "api",
+    "--method",
+    "PUT",
+    `repos/${cfg.github.owner}/${cfg.github.repo}/environments/${ghEnvironment}`,
   ];
 }
 

package/src/deploy/io.ts

@@ -236,7 +236,23 @@ export function ghAuthLogin(cwd = process.cwd()): boolean {
  * `execFileSync` (no shell) so the ARN/region values are never interpolated
  * into a command line.
  */
-export function setRepoVariable(
+export function setRepoVariable(args: string[], cwd = process.cwd()): boolean {
+  try {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    execFileSync("gh", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create (idempotently, via `gh api --method PUT`) a GitHub Actions Environment
+ * so its scoped Variables can be set. Returns true on success. Best-effort — a
+ * missing/unauthenticated `gh` or an API error degrades to the printed
+ * instructions, exactly like `setRepoVariable`.
+ */
+export function ghEnvironmentCreate(
   args: string[],
   cwd = process.cwd(),
 ): boolean {