@reventlessdev/reventless-aws 3.0.0-alpha.367 → 3.0.0-alpha.369

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.369 (2026-10-01)
+
+### Features
+
+* **spec, aws, core, local:** an app declares its environments, and every deployment records its commit ([c7cc925](https://github.com/ReventlessDev/reventless-core/commit/c7cc92573e97742b681a9000cea0bdfd6e9a33fc))
+
+
+# 3.0.0-alpha.368 (2026-09-29)
+
+**Note:** Version bump only for package @reventlessdev/reventless-aws
+
+
+
+
+
 # 3.0.0-alpha.367 (2026-09-28)
 
 **Note:** Version bump only for package @reventlessdev/reventless-aws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.367",
+  "version": "3.0.0-alpha.369",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -8,7 +8,8 @@
     "provision-admin": "./run-provision-admin.mjs",
     "provision-accounts": "./run-provision-accounts.mjs",
     "bake-manifest": "./run-bake-manifest.mjs",
-    "deploy-app": "./run-deploy-app.mjs"
+    "deploy-app": "./run-deploy-app.mjs",
+    "resolve-environment": "./run-resolve-environment.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-appsync": "3.970.0",
@@ -20,19 +21,19 @@
     "sury": "11.0.0",
     "uuid": "^13.0.0",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.26",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.34",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.27",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.11",
-    "@reventlessdev/rescript-pulumi-aws": "3.0.0-alpha.21",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.19",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.20",
+    "@reventlessdev/rescript-pulumi-aws": "3.0.0-alpha.22",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.34",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.22",
-    "@reventlessdev/rescript-web": "1.0.0-alpha.6",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.1",
+    "@reventlessdev/rescript-web": "1.0.0-alpha.7",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.183",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.285",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.149",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.38",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.283",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.181",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.147",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.153"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.155"
   },
   "devDependencies": {
     "rescript": "12.3.1",

package/run-resolve-environment.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./scripts/ResolveEnvironment.res.mjs"
+await main()

package/scripts/ResolveEnvironment.res

@@ -0,0 +1,135 @@
+/***
+Which environment a push, a tag or a pull request deploys to, from the app's
+`environments.yaml`.
+
+```
+pnpm exec resolve-environment --ref refs/heads/test
+pnpm exec resolve-environment --pull-request 7 --base dev
+```
+
+Prints `key=value` lines, so the deploy workflow appends them to
+`$GITHUB_OUTPUT` as they are:
+
+```
+matched=true
+environment=test
+stack=test
+purpose=test
+```
+
+Nothing matched is an answer, not a failure: `matched=false` and exit 0, so a push
+to a branch no environment names deploys nowhere and says so. The workflow asks
+only when the file exists; without it the stack is the branch, as it always was.
+*/
+
+type request =
+  | Push(string)
+  | PullRequest({number: int, base: string, draft: bool})
+
+type args = {
+  file: option<string>,
+  manifest: option<string>,
+  request: request,
+}
+
+let parseArgs = (argv: array<string>): result<args, string> =>
+  Reventless.CliArgs.parse(
+    ~strings=["file", "manifest", "ref", "pull-request", "base"],
+    ~bools=["draft"],
+    argv,
+  )
+  ->Result.flatMap(Reventless.CliArgs.noPositionals)
+  ->Result.flatMap(a => {
+    let string = name => a->Reventless.CliArgs.string(name)
+    let request = switch (string("ref"), string("pull-request"), string("base")) {
+    | (Some(ref), None, None) => Ok(Push(ref))
+    | (None, Some(number), Some(base)) =>
+      switch Int.fromString(number) {
+      | Some(number) => Ok(PullRequest({number, base, draft: a->Reventless.CliArgs.bool("draft")}))
+      | None => Error(`--pull-request takes a number, not "${number}"`)
+      }
+    | (None, Some(_), None) => Error("--pull-request needs --base, the branch it targets")
+    | (None, None, None) => Error("say what deploys: --ref, or --pull-request with --base")
+    | _ => Error("--ref and --pull-request are two different questions; ask one")
+    }
+    request->Result.map(request => {file: string("file"), manifest: string("manifest"), request})
+  })
+
+let usage = `
+Usage: resolve-environment (--ref <ref> | --pull-request <n> --base <branch> [--draft])
+                           [--file <path>] [--manifest <path>]
+
+Which environment of the app's environments.yaml a deploy goes to.
+
+  --ref <ref>            A push or a tag: refs/heads/<branch> or refs/tags/<tag>.
+  --pull-request <n>     A pull request, by number ...
+  --base <branch>        ... and the branch it targets.
+  --draft                The pull request is a draft.
+  --file <path>          The environments file. Defaults to ${Reventless.Environments.fileName}
+                         beside the deploy manifest.
+  --manifest <path>      The deploy manifest. Defaults to ${DeployManifest.defaultFile}
+                         in the working directory.
+
+Prints matched, environment, stack and purpose as key=value lines; a deploy that
+matches nothing prints matched=false and exits 0.
+`
+
+/** The lines printed for a request, from the environments already read. */
+let answer = (environments: Reventless.Environments.t, request: request): array<string> => {
+  let resolved = switch request {
+  | Push(ref) =>
+    ref
+    ->Reventless.Environments.refOf
+    ->Option.flatMap(ref => environments->Reventless.Environments.resolve(ref))
+  | PullRequest({number, base, draft}) =>
+    environments->Reventless.Environments.resolvePullRequest(~base, ~number, ~draft)
+  }
+  switch resolved {
+  | Some({name, stack, purpose}) => [
+      "matched=true",
+      `environment=${name}`,
+      `stack=${stack}`,
+      `purpose=${purpose->Reventless.Environments.purposeName}`,
+    ]
+  | None => ["matched=false"]
+  }
+}
+
+let run = (args: args): result<array<string>, string> => {
+  let file = switch args.file {
+  | Some(file) => file
+  | None =>
+    Reventless.Environments.pathBeside(
+      ~manifest=args.manifest->Option.getOr(
+        NodePath.join([NodeProcess.cwd(), DeployManifest.defaultFile]),
+      ),
+    )
+  }
+  if !NodeFs.existsSync(file) {
+    Error(
+      `no environments file at ${file}. Without one every branch deploys to the stack of its own name, and there is nothing to resolve; --file names another path.`,
+    )
+  } else {
+    file
+    ->Reventless.Environments.parseFile
+    ->Result.map(environments => answer(environments, args.request))
+    ->Result.mapError(message =>
+      `${file}: ${message}. The deploy reads any file of this name beside the deploy manifest as its environments; a file kept there for something else needs another name, or the workflow's environments input pointed elsewhere.`
+    )
+  }
+}
+
+let cli: Reventless.CliArgs.cli<args> = {bin: "resolve-environment", usage, parse: parseArgs}
+
+let main = () =>
+  Reventless.CliArgs.run(cli, async args =>
+    switch run(args) {
+    | Ok(lines) => lines->Array.forEach(line => Console.log(line))
+    | Error(message) =>
+      Console.error(`resolve-environment: ${message}`)
+      NodeProcess.exit(1)
+    }
+  )
+
+// No top-level call: `../run-resolve-environment.mjs` invokes [main], so a test can
+// import this module.

package/scripts/ResolveEnvironment.res.mjs

@@ -0,0 +1,148 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as CliArgs$Reventless from "@reventlessdev/reventless-spec/src/CliArgs.res.mjs";
+import * as Environments$Reventless from "@reventlessdev/reventless-spec/src/types/Environments.res.mjs";
+import * as DeployManifest$ReventlessAws from "./DeployManifest.res.mjs";
+
+function parseArgs(argv) {
+  return Stdlib_Result.flatMap(Stdlib_Result.flatMap(CliArgs$Reventless.parse([
+    "file",
+    "manifest",
+    "ref",
+    "pull-request",
+    "base"
+  ], ["draft"], undefined, undefined, argv), CliArgs$Reventless.noPositionals), a => {
+    let match = CliArgs$Reventless.string(a, "ref");
+    let match$1 = CliArgs$Reventless.string(a, "pull-request");
+    let match$2 = CliArgs$Reventless.string(a, "base");
+    let request;
+    if (match !== undefined) {
+      request = match$1 !== undefined || match$2 !== undefined ? ({
+          TAG: "Error",
+          _0: "--ref and --pull-request are two different questions; ask one"
+        }) : ({
+          TAG: "Ok",
+          _0: {
+            TAG: "Push",
+            _0: match
+          }
+        });
+    } else if (match$1 !== undefined) {
+      if (match$2 !== undefined) {
+        let number = Stdlib_Int.fromString(match$1, undefined);
+        request = number !== undefined ? ({
+            TAG: "Ok",
+            _0: {
+              TAG: "PullRequest",
+              number: number,
+              base: match$2,
+              draft: CliArgs$Reventless.bool(a, "draft")
+            }
+          }) : ({
+            TAG: "Error",
+            _0: `--pull-request takes a number, not "` + match$1 + `"`
+          });
+      } else {
+        request = {
+          TAG: "Error",
+          _0: "--pull-request needs --base, the branch it targets"
+        };
+      }
+    } else {
+      request = match$2 !== undefined ? ({
+          TAG: "Error",
+          _0: "--ref and --pull-request are two different questions; ask one"
+        }) : ({
+          TAG: "Error",
+          _0: "say what deploys: --ref, or --pull-request with --base"
+        });
+    }
+    return Stdlib_Result.map(request, request => ({
+      file: CliArgs$Reventless.string(a, "file"),
+      manifest: CliArgs$Reventless.string(a, "manifest"),
+      request: request
+    }));
+  });
+}
+
+let usage = `
+Usage: resolve-environment (--ref <ref> | --pull-request <n> --base <branch> [--draft])
+                           [--file <path>] [--manifest <path>]
+
+Which environment of the app's environments.yaml a deploy goes to.
+
+  --ref <ref>            A push or a tag: refs/heads/<branch> or refs/tags/<tag>.
+  --pull-request <n>     A pull request, by number ...
+  --base <branch>        ... and the branch it targets.
+  --draft                The pull request is a draft.
+  --file <path>          The environments file. Defaults to ` + Environments$Reventless.fileName + `
+                         beside the deploy manifest.
+  --manifest <path>      The deploy manifest. Defaults to ` + DeployManifest$ReventlessAws.defaultFile + `
+                         in the working directory.
+
+Prints matched, environment, stack and purpose as key=value lines; a deploy that
+matches nothing prints matched=false and exits 0.
+`;
+
+function answer(environments, request) {
+  let resolved;
+  resolved = request.TAG === "Push" ? Stdlib_Option.flatMap(Environments$Reventless.refOf(request._0), ref => Environments$Reventless.resolve(environments, ref)) : Environments$Reventless.resolvePullRequest(environments, request.base, request.number, request.draft);
+  if (resolved !== undefined) {
+    return [
+      "matched=true",
+      `environment=` + resolved.name,
+      `stack=` + resolved.stack,
+      `purpose=` + Environments$Reventless.purposeName(resolved.purpose)
+    ];
+  } else {
+    return ["matched=false"];
+  }
+}
+
+function run(args) {
+  let file = args.file;
+  let file$1 = file !== undefined ? file : Environments$Reventless.pathBeside(Stdlib_Option.getOr(args.manifest, Nodepath.join(process.cwd(), DeployManifest$ReventlessAws.defaultFile)));
+  if (Nodefs.existsSync(file$1)) {
+    return Stdlib_Result.mapError(Stdlib_Result.map(Environments$Reventless.parseFile(file$1), environments => answer(environments, args.request)), message => file$1 + `: ` + message + `. The deploy reads any file of this name beside the deploy manifest as its environments; a file kept there for something else needs another name, or the workflow's environments input pointed elsewhere.`);
+  } else {
+    return {
+      TAG: "Error",
+      _0: `no environments file at ` + file$1 + `. Without one every branch deploys to the stack of its own name, and there is nothing to resolve; --file names another path.`
+    };
+  }
+}
+
+let cli = {
+  bin: "resolve-environment",
+  usage: usage,
+  parse: parseArgs
+};
+
+function main() {
+  return CliArgs$Reventless.run(cli, undefined, undefined, async args => {
+    let lines = run(args);
+    if (lines.TAG === "Ok") {
+      lines._0.forEach(line => {
+        console.log(line);
+      });
+      return;
+    }
+    console.error(`resolve-environment: ` + lines._0);
+    process.exit(1);
+  });
+}
+
+export {
+  parseArgs,
+  usage,
+  answer,
+  run,
+  cli,
+  main,
+}
+/* node:fs Not a pure module */

package/tests/ResolveEnvironmentTest.res

@@ -0,0 +1,91 @@
+open JestGlobals
+
+// What the deploy workflow appends to $GITHUB_OUTPUT. The resolving itself, and
+// the file's rules, are tested with the format in `spec`'s `EnvironmentsTest`;
+// what is tested here is the command line and the lines it prints, because the
+// workflow reads those as they are.
+
+module Resolve = ResolveEnvironment
+
+let environments = switch Reventless.Environments.parseString(`environments:
+  - { name: review,     purpose: review,     pullRequestsInto: dev }
+  - { name: dev,        purpose: dev,        branch: dev }
+  - { name: production, purpose: production, branch: main, tags: "v*", stack: prod }
+`) {
+| Ok(environments) => environments
+| Error(message) => JsError.throwWithMessage(message)
+}
+
+describe("ResolveEnvironment.parseArgs", () => {
+  testSync("a ref asks about a push", () =>
+    expect(Resolve.parseArgs(["--ref", "refs/heads/dev"])->Result.map(a => a.request))->toEqual(
+      Ok(Resolve.Push("refs/heads/dev")),
+    )
+  )
+
+  testSync("a pull request needs the branch it targets", () =>
+    expect(Resolve.parseArgs(["--pull-request", "7"])->Result.isError)->toBe(true)
+  )
+
+  testSync("a pull request with its base and draft state", () =>
+    expect(
+      Resolve.parseArgs(["--pull-request", "7", "--base", "dev", "--draft"])->Result.map(
+        a => a.request,
+      ),
+    )->toEqual(Ok(Resolve.PullRequest({number: 7, base: "dev", draft: true})))
+  )
+
+  testSync("a pull request number that is not a number is refused", () =>
+    expect(Resolve.parseArgs(["--pull-request", "seven", "--base", "dev"])->Result.isError)->toBe(
+      true,
+    )
+  )
+
+  testSync("both questions at once are refused", () =>
+    expect(
+      Resolve.parseArgs([
+        "--ref",
+        "refs/heads/dev",
+        "--pull-request",
+        "7",
+        "--base",
+        "dev",
+      ])->Result.isError,
+    )->toBe(true)
+  )
+
+  testSync("no question is refused", () =>
+    expect(Resolve.parseArgs([])->Result.isError)->toBe(true)
+  )
+})
+
+describe("ResolveEnvironment.answer", () => {
+  testSync("a push to a branch prints its environment, stack and purpose", () =>
+    expect(Resolve.answer(environments, Push("refs/heads/main")))->toEqual([
+      "matched=true",
+      "environment=production",
+      "stack=prod",
+      "purpose=production",
+    ])
+  )
+
+  testSync("a tag deploys where its pattern says", () =>
+    expect(Resolve.answer(environments, Push("refs/tags/v1.2.0"))->Array.get(2))->toEqual(
+      Some("stack=prod"),
+    )
+  )
+
+  testSync("a pull request into dev gets its review stack", () =>
+    expect(
+      Resolve.answer(environments, PullRequest({number: 7, base: "dev", draft: false})),
+    )->toEqual(["matched=true", "environment=review", "stack=review-pr-7", "purpose=review"])
+  )
+
+  testSync("nothing matched is an answer, not an error", () =>
+    expect(Resolve.answer(environments, Push("refs/heads/feature/x")))->toEqual(["matched=false"])
+  )
+
+  testSync("a ref that is neither a branch nor a tag matches nothing", () =>
+    expect(Resolve.answer(environments, Push("refs/pull/7/merge")))->toEqual(["matched=false"])
+  )
+})

package/tests/ResolveEnvironmentTest.res.mjs

@@ -0,0 +1,128 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Environments$Reventless from "@reventlessdev/reventless-spec/src/types/Environments.res.mjs";
+import * as ResolveEnvironment$ReventlessAws from "../scripts/ResolveEnvironment.res.mjs";
+
+let environments = Environments$Reventless.parseString(`environments:
+  - { name: review,     purpose: review,     pullRequestsInto: dev }
+  - { name: dev,        purpose: dev,        branch: dev }
+  - { name: production, purpose: production, branch: main, tags: "v*", stack: prod }
+`);
+
+let environments$1;
+
+environments$1 = environments.TAG === "Ok" ? environments._0 : Stdlib_JsError.throwWithMessage(environments._0);
+
+globalThis.describe("ResolveEnvironment.parseArgs", () => {
+  globalThis.test("a ref asks about a push", () => {
+    globalThis.expect(Stdlib_Result.map(ResolveEnvironment$ReventlessAws.parseArgs([
+      "--ref",
+      "refs/heads/dev"
+    ]), a => a.request)).toEqual({
+      TAG: "Ok",
+      _0: {
+        TAG: "Push",
+        _0: "refs/heads/dev"
+      }
+    });
+  });
+  globalThis.test("a pull request needs the branch it targets", () => {
+    globalThis.expect(Stdlib_Result.isError(ResolveEnvironment$ReventlessAws.parseArgs([
+      "--pull-request",
+      "7"
+    ]))).toBe(true);
+  });
+  globalThis.test("a pull request with its base and draft state", () => {
+    globalThis.expect(Stdlib_Result.map(ResolveEnvironment$ReventlessAws.parseArgs([
+      "--pull-request",
+      "7",
+      "--base",
+      "dev",
+      "--draft"
+    ]), a => a.request)).toEqual({
+      TAG: "Ok",
+      _0: {
+        TAG: "PullRequest",
+        number: 7,
+        base: "dev",
+        draft: true
+      }
+    });
+  });
+  globalThis.test("a pull request number that is not a number is refused", () => {
+    globalThis.expect(Stdlib_Result.isError(ResolveEnvironment$ReventlessAws.parseArgs([
+      "--pull-request",
+      "seven",
+      "--base",
+      "dev"
+    ]))).toBe(true);
+  });
+  globalThis.test("both questions at once are refused", () => {
+    globalThis.expect(Stdlib_Result.isError(ResolveEnvironment$ReventlessAws.parseArgs([
+      "--ref",
+      "refs/heads/dev",
+      "--pull-request",
+      "7",
+      "--base",
+      "dev"
+    ]))).toBe(true);
+  });
+  globalThis.test("no question is refused", () => {
+    globalThis.expect(Stdlib_Result.isError(ResolveEnvironment$ReventlessAws.parseArgs([]))).toBe(true);
+  });
+});
+
+globalThis.describe("ResolveEnvironment.answer", () => {
+  globalThis.test("a push to a branch prints its environment, stack and purpose", () => {
+    globalThis.expect(ResolveEnvironment$ReventlessAws.answer(environments$1, {
+      TAG: "Push",
+      _0: "refs/heads/main"
+    })).toEqual([
+      "matched=true",
+      "environment=production",
+      "stack=prod",
+      "purpose=production"
+    ]);
+  });
+  globalThis.test("a tag deploys where its pattern says", () => {
+    globalThis.expect(ResolveEnvironment$ReventlessAws.answer(environments$1, {
+        TAG: "Push",
+        _0: "refs/tags/v1.2.0"
+      })[2]).toEqual("stack=prod");
+  });
+  globalThis.test("a pull request into dev gets its review stack", () => {
+    globalThis.expect(ResolveEnvironment$ReventlessAws.answer(environments$1, {
+      TAG: "PullRequest",
+      number: 7,
+      base: "dev",
+      draft: false
+    })).toEqual([
+      "matched=true",
+      "environment=review",
+      "stack=review-pr-7",
+      "purpose=review"
+    ]);
+  });
+  globalThis.test("nothing matched is an answer, not an error", () => {
+    globalThis.expect(ResolveEnvironment$ReventlessAws.answer(environments$1, {
+      TAG: "Push",
+      _0: "refs/heads/feature/x"
+    })).toEqual(["matched=false"]);
+  });
+  globalThis.test("a ref that is neither a branch nor a tag matches nothing", () => {
+    globalThis.expect(ResolveEnvironment$ReventlessAws.answer(environments$1, {
+      TAG: "Push",
+      _0: "refs/pull/7/merge"
+    })).toEqual(["matched=false"]);
+  });
+});
+
+let Resolve;
+
+export {
+  Resolve,
+  environments$1 as environments,
+}
+/* environments Not a pure module */