@agilecustoms/envctl 0.1.0

package/.github/workflows/build-and-release.yml

@@ -0,0 +1,46 @@
+name: Client Build and Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  Build:
+    uses: ./.github/workflows/build.yml
+    with:
+      artifacts: true
+    secrets: inherit
+    permissions:
+      id-token: write
+      contents: read
+
+
+  Release:
+    needs:
+      - Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: client
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_ACTIONS_TOKEN }} # Admin PAT to bypass push protection on 'main' branch
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+
+      - name: Release
+        id: release
+        uses: agilecustoms/gha-release@main
+        with:
+          aws-account: ${{ vars.AWS_ACCOUNT_DIST }}
+          npmjs-token: ${{ secrets.NPMJS_TOKEN }}
+
+      - name: Summary
+        run: echo "### Released ${{ steps.release.outputs.version }} :pushpin:" >> $GITHUB_STEP_SUMMARY

package/.github/workflows/build.yml

@@ -0,0 +1,46 @@
+name: Client Build
+
+on:
+  push:
+    branches-ignore:
+      - main
+  workflow_call:
+    inputs:
+      artifacts:
+        required: false
+        type: boolean
+        default: false
+        description: upload artifacts or not
+
+jobs:
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 23
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifacts
+        if: inputs.artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          path: dist # take everything from dist/ folder
+          name: dist #  and create artifact named dist (so later on the download action will create <repo-root>/dist/ folder)
+          # if not specify name - it will be available as 'artifact' dir

package/Makefile

@@ -0,0 +1,28 @@
+_aws-login:
+	@aws sso login
+
+# npm list --all - show dependency tree
+app0-install-deps:
+	@npm install
+
+app0-update-deps:
+	@npm update; npm outdated
+
+app1-lint:
+	@npm run lint
+
+app1-lint-fix:
+	@npm run lint:fix
+
+app2-test:
+	@npm run test
+
+app3-build:
+	@npm run build
+
+# npm cache clean --force
+# cd ~/.npm; open .
+app4-dry-run:
+	@set -e; \
+	echo "cd in other directory, otherwise npx picks up local package :("; cd ..; \
+	npx -y --force @agilecustoms/envctl --version

package/README.md

@@ -0,0 +1,35 @@
+# envctl
+- npm [@agilecustoms/envctl](https://www.npmjs.com/package/@agilecustoms/envctl)
+- npm [agilecustoms/packages](https://www.npmjs.com/settings/agilecustoms/packages) (admin view)
+
+## npmjs setup
+1. Login in npmjs.com
+2. Create organization `agilecustoms` this will create scope `@agilecustoms` (one org => exactly one scope, also scope can be created w/o org)
+3. Go to your user > Access Tokens > Generate New Token > New Granular Access Token
+   1. Token name: `agilecustoms-ci`
+   2. Packages and scopes
+      1. Permissions: Read and write
+      2. Only select packages and scopes: `@agilecustoms`
+   3. Organizations (keep as is)
+4. Save token in GitHub > org > Settings > Secrets and variables > Actions > Secrets > New organization secret
+   1. Name `NPMJS_TOKEN`
+   2. Repository access: `envctl` only
+
+dev-env is a microservice hosted in 'maintenance' account and working as garbage collector: every environment first
+created in dev-env and then 'managed' by dev-env: it deletes env when it is not in use anymore OR can extend lifetime.
+Creation API yields unique ID, so you can safely manage env (delete, extend lifetime) via this ID. But creation API
+need to be secured. There are two main use cases:
+1. create environment from CI (mainly ephemeral envs)
+2. create env from dev machine
+
+I (Alex C) chosen IAM authorization as common denominator:
+1. on CI - use OIDC to assume role `/ci/deployer`                     
+2. on dev machine - use SSO and profile chaining to assume role `/ci/deployer`
+
+Then as `/ci/deployer` --call--> dev-env HTTP API (exposed with API Gateway with IAM authorizer)
+
+Now problem is: any request needs to be signed with AWS signature v4. Originally I planned to use bash scripts, but it
+quickly became bulky and hard to maintain. Then I thought about Node.js - it is available on dev machines and
+in GitHub actions (namely in Ubuntu runners). How to distribute it? First I thought about using `ncc` to bundle in one
+big .js file (as I do for `gha-upload-3` and `gha-healthcheck`) but it will be hard to use on dev machine...
+So I ended up with publishing this client as npm package in CodeArtifact and then running from anywhere with `npx`!

package/dist/commands/createEphemeral.js

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import { envCtl } from '../container.js';
+import { wrap } from '../exceptions.js';
+export function ephemeral(program) {
+    program
+        .command('ephemeral')
+        .description('Create new ephemeral environment')
+        .requiredOption('-k, --key <key>', 'Key used to store env state (s3 key in case of AWS). Can be git hash, feature-a or {project-code}-{env-name}')
+        .action(wrap(handler));
+}
+async function handler(options) {
+    const { key } = options;
+    return await envCtl.createEphemeralEnv(key);
+}

package/dist/commands/delete.js

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { envCtl } from '../container.js';
+import { wrap } from '../exceptions.js';
+export function deleteIt(program) {
+    program
+        .command('delete')
+        .description('Delete a development environment')
+        .argument('<string>', 'key used to create/register the environment')
+        .action(wrap(handler));
+}
+async function handler(key) {
+    await envCtl.delete(key);
+}

package/dist/commands/index.js

@@ -0,0 +1,3 @@
+export { ephemeral } from './createEphemeral.js';
+export { register } from './register.js';
+export { deleteIt } from './delete.js';

package/dist/commands/register.js

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { envCtl } from '../container.js';
+import { wrap } from '../exceptions.js';
+export function register(program) {
+    program
+        .command('register')
+        .description('Create new or update existing dev environment')
+        .requiredOption('-k, --key <key>', 'Key used to store env state (s3 key in case of AWS). Can be git hash, feature-a or {project-code}-{env-name}')
+        .requiredOption('-o, --owner <owner>', 'Environment owner (GH username)')
+        .action(wrap(handler));
+}
+async function handler(options) {
+    const { key, owner } = options;
+    return await envCtl.registerEnv(key, owner);
+}

package/dist/container.js

@@ -0,0 +1,7 @@
+import { STSClient } from '@aws-sdk/client-sts';
+import { DevEnvClient, EnvCtl, HttpClient } from './service/index.js';
+const stsClient = new STSClient();
+const httpClient = new HttpClient();
+const devEnvClient = new DevEnvClient(httpClient);
+const envCtl = new EnvCtl(stsClient, devEnvClient);
+export { envCtl };

package/dist/exceptions.js

@@ -0,0 +1,26 @@
+export class KnownException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KnownException';
+    }
+}
+export function wrap(callable) {
+    return async (...args) => {
+        let result;
+        try {
+            result = await callable(...args);
+        }
+        catch (error) {
+            if (error instanceof KnownException) {
+                console.error(error.message);
+            }
+            else {
+                console.error('Unknown error:', error);
+            }
+            process.exit(1);
+        }
+        if (result !== undefined) {
+            console.log(result);
+        }
+    };
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { createRequire } from 'module';
+import { Command } from 'commander';
+import { deleteIt, ephemeral, register } from './commands/index.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+const program = new Command();
+program
+    .name('envctl')
+    .description('CLI to manage environments')
+    .version(version);
+register(program);
+ephemeral(program);
+deleteIt(program);
+program.parse(process.argv);

package/dist/model/Environment.js

@@ -0,0 +1 @@
+export {};

package/dist/model/PersonalEnvironment.js

@@ -0,0 +1 @@
+export {};

package/dist/model/index.js

@@ -0,0 +1 @@
+export {};

package/dist/service/DevEnvClient.js

@@ -0,0 +1,27 @@
+import { HttpClient } from './HttpClient.js';
+export class DevEnvClient {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async registerEnv(env) {
+        return await this.send('PUT', '/ci/env', env);
+    }
+    async createEphemeralEnv(env) {
+        return await this.send('POST', '/ci/env', env);
+    }
+    async delete(envId) {
+        await this.httpClient.fetch(`/ci/env/${envId}`, {
+            method: 'DELETE'
+        });
+    }
+    async send(method, path, env) {
+        return this.httpClient.fetch(path, {
+            method,
+            body: JSON.stringify(env),
+            headers: {
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+}

package/dist/service/EnvCtl.js

@@ -0,0 +1,43 @@
+import { GetCallerIdentityCommand, STSClient } from '@aws-sdk/client-sts';
+import { KnownException } from '../exceptions.js';
+import { DevEnvClient } from './DevEnvClient.js';
+export class EnvCtl {
+    stsClient;
+    devEnvClient;
+    constructor(stsClient, devEnvClient) {
+        this.stsClient = stsClient;
+        this.devEnvClient = devEnvClient;
+    }
+    async getAccount() {
+        const command = new GetCallerIdentityCommand({});
+        let response;
+        try {
+            response = await this.stsClient.send(command);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                const message = error.message;
+                if (message.startsWith('The SSO session token') || message.startsWith('Token is expired')) {
+                    throw new KnownException(error.message);
+                }
+            }
+            throw new Error('Error fetching account', { cause: error });
+        }
+        return response.Account;
+    }
+    async registerEnv(key, owner) {
+        const account = await this.getAccount();
+        const env = { account, key, owner };
+        return await this.devEnvClient.registerEnv(env);
+    }
+    async createEphemeralEnv(key) {
+        const account = await this.getAccount();
+        const env = { account, key };
+        return await this.devEnvClient.createEphemeralEnv(env);
+    }
+    async delete(key) {
+        const account = await this.getAccount();
+        const envId = `${account}-${key}`;
+        return this.devEnvClient.delete(envId);
+    }
+}

package/dist/service/HttpClient.js

@@ -0,0 +1,51 @@
+import { fromEnv, fromSSO } from '@aws-sdk/credential-providers';
+import aws4 from 'aws4';
+import { KnownException } from '../exceptions.js';
+const HOST = 'dev-env.maintenance.agilecustoms.com';
+export class HttpClient {
+    async fetch(path, options) {
+        const creds = await this.getCredentials();
+        const requestOptions = {
+            method: options.method,
+            body: options.body,
+            headers: options.headers,
+            host: HOST,
+            service: 'execute-api',
+            path,
+        };
+        const signedOptions = aws4.sign(requestOptions, creds);
+        const signedHeaders = signedOptions.headers;
+        const url = `https://${HOST}${path}`;
+        options.headers = signedHeaders;
+        let response;
+        try {
+            response = await fetch(url, options);
+        }
+        catch (error) {
+            throw new Error('Error (network?) making the request:', { cause: error });
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            if (response.status === 422) {
+                throw new KnownException(`Validation error: ${text}`);
+            }
+            throw new Error(`Received ${response.status} response: ${text}`);
+        }
+        return text;
+    }
+    async getCredentials() {
+        let identityProvider;
+        if (process.env.CI) {
+            identityProvider = fromEnv();
+        }
+        else {
+            identityProvider = fromSSO();
+        }
+        try {
+            return await identityProvider();
+        }
+        catch (error) {
+            throw new Error('Error fetching credentials:', { cause: error });
+        }
+    }
+}

package/dist/service/index.js

@@ -0,0 +1,3 @@
+export { DevEnvClient } from './DevEnvClient.js';
+export { EnvCtl } from './EnvCtl.js';
+export { HttpClient } from './HttpClient.js';

package/eslint.config.mjs

@@ -0,0 +1,34 @@
+import tseslint from 'typescript-eslint'
+import plugin from '@stylistic/eslint-plugin'
+import importPlugin from 'eslint-plugin-import';
+
+export default [
+    ...tseslint.configs.recommended,
+    plugin.configs['recommended-flat'],
+    {
+        plugins: {
+            import: importPlugin,
+        },
+        rules: {
+            '@stylistic/brace-style': ['error', '1tbs'], // 'else' keyword on the same line as closing brace
+            '@stylistic/comma-dangle': 'off', // there are cases when trailing comma desired, and sometimes not
+            '@typescript-eslint/no-unused-vars': ['error', { // unused var starting from _ is ok
+                'argsIgnorePattern': '^_',
+                'destructuredArrayIgnorePattern': '^_'
+            }],
+
+            // Enforce Alphabetical Import Order and Merge Duplicate Imports
+            'import/order': ['error', {
+                'alphabetize': {'order': 'asc', 'caseInsensitive': true}
+            }],
+            'import/no-duplicates': 'error',
+        }
+    },
+    // Test-specific configuration (glob-based override)
+    {
+        files: ['**/*.test.ts', '**/*.test.tsx'],
+        rules: {
+            '@typescript-eslint/no-extra-non-null-assertion': 'off', // allow using !! initially to use with .mock.calls[0]!!
+        },
+    },
+];

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@agilecustoms/envctl",
+  "description": "node.js CLI client for manage environments",
+  "version": "0.1.0",
+  "author": "Alex Chekulaev",
+  "type": "module",
+  "bin": {
+    "envctl": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agilecustoms/envctl.git"
+  },
+  "license": "UNLICENSED",
+  "_comment0": "to run via `npx` you must use `name` (with scope) and have at least one entry in `bin`. Key does not matter when run via `npx`",
+  "_comment1": "keys become CLI apps (symlinks) when install globally. ex: npm install -g @agilecustoms/envctl; ls $(which alexc-blah) >> lrwxr-xr-x  1 alexc  admin  62 Dec 30 14:29 /opt/homebrew/bin/alexc-blah -> ../lib/node_modules/@agilecustoms/envctl-client/dist/index.js",
+  "scripts": {
+    "lint": "eslint src/*.ts src/**/*.ts test/**/*.ts",
+    "lint:fix": "npm run lint -- --fix",
+    "test": "vitest run --coverage",
+    "build": "tsc",
+    "run": "node dist/index.js",
+    "run-version": "tsc --sourceMap true; npm run run -- --version",
+    "run-register": "tsc --sourceMap true; npm run run -- register --project tt --env alexc --owner laxa1986",
+    "run-ephemeral": "tsc --sourceMap true; npm run run -- ephemeral -p tt -e tempenv",
+    "run-delete": "tsc --sourceMap true; npm run run -- delete tt-alexc"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sts": "^3.716.0",
+    "@aws-sdk/credential-providers": "^3.716.0",
+    "aws4": "^1.13.2",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^4.2.0",
+    "@types/aws4": "^1.11.6",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^3.0.2",
+    "eslint": "^9.22.0",
+    "eslint-plugin-import": "^2.31.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.8.1",
+    "vitest": "^3.0.2"
+  }
+}

package/src/commands/createEphemeral.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander'
+import { envCtl } from '../container.js'
+import { wrap } from '../exceptions.js'
+
+export function ephemeral(program: Command) {
+  program
+    .command('ephemeral')
+    .description('Create new ephemeral environment')
+    .requiredOption('-k, --key <key>', 'Key used to store env state (s3 key in case of AWS). Can be git hash, feature-a or {project-code}-{env-name}')
+    .action(wrap(handler))
+}
+
+type Options = {
+  key: string
+}
+
+async function handler(options: object): Promise<string> {
+  const { key } = options as Options
+
+  return await envCtl.createEphemeralEnv(key)
+}

package/src/commands/delete.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander'
+import { envCtl } from '../container.js'
+import { wrap } from '../exceptions.js'
+
+export function deleteIt(program: Command) {
+  program
+    .command('delete')
+    .description('Delete a development environment')
+    .argument('<string>', 'key used to create/register the environment')
+    .action(wrap(handler))
+}
+
+async function handler(key: string): Promise<void> {
+  await envCtl.delete(key)
+}

package/src/commands/index.ts

@@ -0,0 +1,3 @@
+export { ephemeral } from './createEphemeral.js'
+export { register } from './register.js'
+export { deleteIt } from './delete.js'

package/src/commands/register.ts

@@ -0,0 +1,23 @@
+import { Command } from 'commander'
+import { envCtl } from '../container.js'
+import { wrap } from '../exceptions.js'
+
+export function register(program: Command) {
+  program
+    .command('register')
+    .description('Create new or update existing dev environment')
+    .requiredOption('-k, --key <key>', 'Key used to store env state (s3 key in case of AWS). Can be git hash, feature-a or {project-code}-{env-name}')
+    .requiredOption('-o, --owner <owner>', 'Environment owner (GH username)')
+    .action(wrap(handler))
+}
+
+type Options = {
+  key: string
+  owner: string
+}
+
+async function handler(options: object): Promise<string> {
+  const { key, owner } = options as Options
+
+  return await envCtl.registerEnv(key, owner)
+}

package/src/container.ts

@@ -0,0 +1,9 @@
+import { STSClient } from '@aws-sdk/client-sts'
+import { DevEnvClient, EnvCtl, HttpClient } from './service/index.js'
+
+const stsClient = new STSClient()
+const httpClient = new HttpClient()
+const devEnvClient = new DevEnvClient(httpClient)
+const envCtl = new EnvCtl(stsClient, devEnvClient)
+
+export { envCtl }

package/src/exceptions.ts

@@ -0,0 +1,29 @@
+export class KnownException extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'KnownException'
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function wrap(callable: (...args: any[]) => Promise<string | void>): (...args: any[]) => void | Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return async (...args: any[]): Promise<void> => {
+    let result: string | void
+    try {
+      result = await callable(...args)
+    } catch (error) {
+      if (error instanceof KnownException) {
+        console.error(error.message)
+      } else {
+        // print stack trace
+        console.error('Unknown error:', error)
+      }
+      process.exit(1)
+    }
+    // this is how result is returned back so it can be accessed by calling shell script
+    if (result !== undefined) {
+      console.log(result)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { createRequire } from 'module'
+import { Command } from 'commander'
+import { deleteIt, ephemeral, register } from './commands/index.js'
+
+// it is possible to use 'import' to load JSON files, but package.json is level higher, so such trick copies 'src' in /dist :(
+const require = createRequire(import.meta.url) // custom 'require' relative to current module’s file URL
+const { version } = require('../package.json')
+
+const program = new Command()
+program
+  .name('envctl') // shown when running --help: Usage: envctl [options] [command]
+  .description('CLI to manage environments')
+  .version(version)
+register(program)
+ephemeral(program)
+deleteIt(program)
+
+program.parse(process.argv)

package/src/model/Environment.ts

@@ -0,0 +1,4 @@
+export type Environment = {
+  account: string
+  key: string
+}

package/src/model/PersonalEnvironment.ts

@@ -0,0 +1,5 @@
+import type { Environment } from './Environment.js'
+
+export type PersonalEnvironment = Environment & {
+  owner: string
+}

package/src/model/index.ts

@@ -0,0 +1,2 @@
+export type { Environment } from './Environment.js'
+export type { PersonalEnvironment } from './PersonalEnvironment.js'

package/src/service/DevEnvClient.ts

@@ -0,0 +1,34 @@
+import type { Environment, PersonalEnvironment } from '../model/index.js'
+import { HttpClient } from './HttpClient.js'
+
+export class DevEnvClient {
+  private httpClient: HttpClient
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient
+  }
+
+  public async registerEnv(env: PersonalEnvironment): Promise<string> {
+    return await this.send('PUT', '/ci/env', env)
+  }
+
+  public async createEphemeralEnv(env: Environment): Promise<string> {
+    return await this.send('POST', '/ci/env', env)
+  }
+
+  public async delete(envId: string): Promise<void> {
+    await this.httpClient.fetch(`/ci/env/${envId}`, {
+      method: 'DELETE'
+    })
+  }
+
+  private async send(method: string, path: string, env: Environment): Promise<string> {
+    return this.httpClient.fetch(path, {
+      method,
+      body: JSON.stringify(env),
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    })
+  }
+}

package/src/service/EnvCtl.ts

@@ -0,0 +1,57 @@
+import { GetCallerIdentityCommand, STSClient } from '@aws-sdk/client-sts'
+import type { GetCallerIdentityResponse } from '@aws-sdk/client-sts'
+import { KnownException } from '../exceptions.js'
+import { DevEnvClient } from './DevEnvClient.js'
+
+export class EnvCtl {
+  private stsClient: STSClient
+  private devEnvClient: DevEnvClient
+
+  constructor(
+    stsClient: STSClient,
+    devEnvClient: DevEnvClient
+  ) {
+    this.stsClient = stsClient
+    this.devEnvClient = devEnvClient
+  }
+
+  private async getAccount(): Promise<string> {
+    const command = new GetCallerIdentityCommand({})
+    let response: GetCallerIdentityResponse
+    try {
+      response = await this.stsClient.send(command)
+    } catch (error) {
+      // there is no type to check with instanceof, and also different errors have same .name  == 'CredentialsProviderError'
+      if (error instanceof Error) {
+        const message = error.message
+        if (message.startsWith('The SSO session token') || message.startsWith('Token is expired')) {
+          throw new KnownException(error.message)
+        }
+      }
+      throw new Error('Error fetching account', { cause: error })
+    }
+    return response.Account!
+  }
+
+  public async registerEnv(key: string, owner: string): Promise<string> {
+    const account = await this.getAccount()
+    const env = { account, key, owner }
+    return await this.devEnvClient.registerEnv(env)
+  }
+
+  public async createEphemeralEnv(key: string): Promise<string> {
+    const account = await this.getAccount()
+    const env = { account, key }
+    return await this.devEnvClient.createEphemeralEnv(env)
+  }
+
+  /**
+   * Here client uses secret knowledge on how id is constructed from account and key
+   * Probably it is OK because client and server are tightly coupled
+   */
+  public async delete(key: string): Promise<void> {
+    const account = await this.getAccount()
+    const envId = `${account}-${key}`
+    return this.devEnvClient.delete(envId)
+  }
+}

package/src/service/HttpClient.ts

@@ -0,0 +1,58 @@
+import { fromEnv, fromSSO } from '@aws-sdk/credential-providers'
+import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@smithy/types'
+import aws4 from 'aws4'
+import type { Credentials, Request as Aws4Request } from 'aws4'
+import { KnownException } from '../exceptions.js'
+
+const HOST = 'dev-env.maintenance.agilecustoms.com'
+
+export class HttpClient {
+  public async fetch(path: string, options: RequestInit): Promise<string> {
+    const creds: Credentials = await this.getCredentials()
+
+    const requestOptions: Aws4Request = {
+      method: options.method,
+      body: options.body as string | undefined,
+      headers: options.headers as Record<string, string>,
+      host: HOST,
+      service: 'execute-api',
+      path,
+    }
+    const signedOptions: Aws4Request = aws4.sign(requestOptions, creds)
+    const signedHeaders = signedOptions.headers as Record<string, string>
+
+    const url = `https://${HOST}${path}`
+    options.headers = signedHeaders
+
+    let response: Response
+    try {
+      response = await fetch(url, options)
+    } catch (error) {
+      throw new Error('Error (network?) making the request:', { cause: error })
+    }
+
+    const text = await response.text()
+    if (!response.ok) {
+      if (response.status === 422) {
+        throw new KnownException(`Validation error: ${text}`)
+      }
+      throw new Error(`Received ${response.status} response: ${text}`)
+    }
+
+    return text
+  }
+
+  private async getCredentials(): Promise<AwsCredentialIdentity> {
+    let identityProvider: AwsCredentialIdentityProvider
+    if (process.env.CI) {
+      identityProvider = fromEnv()
+    } else {
+      identityProvider = fromSSO()
+    }
+    try {
+      return await identityProvider()
+    } catch (error) {
+      throw new Error('Error fetching credentials:', { cause: error })
+    }
+  }
+}

package/src/service/index.ts

@@ -0,0 +1,3 @@
+export { DevEnvClient } from './DevEnvClient.js'
+export { EnvCtl } from './EnvCtl.js'
+export { HttpClient } from './HttpClient.js'

package/test/service/EnvCtl.test.ts

@@ -0,0 +1,34 @@
+import { STSClient } from '@aws-sdk/client-sts'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DevEnvClient, EnvCtl } from '../../src/service'
+
+const stsClient = {
+  send: vi.fn(),
+}
+
+const devEnvClient = {
+  registerEnv: vi.fn(),
+}
+
+describe('EnvCtl', () => {
+  let envCtl: EnvCtl
+  beforeEach(() => {
+    envCtl = new EnvCtl(
+      stsClient as unknown as STSClient,
+      devEnvClient as unknown as DevEnvClient
+    )
+  })
+
+  describe('registerEnv', () => {
+    it('should call stsClient to get account and then call devEnvClient to register env', async () => {
+      stsClient.send.mockResolvedValue({ Account: 'testAccount' })
+      devEnvClient.registerEnv.mockResolvedValue('testEnvId')
+
+      const result = await envCtl.registerEnv('env', 'owner')
+
+      expect(result).toBe('testEnvId')
+      expect(stsClient.send).toHaveBeenCalled()
+      expect(devEnvClient.registerEnv).toHaveBeenCalled()
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,23 @@
+// https://www.typescriptlang.org/tsconfig
+{
+  "include": [
+    "src"
+  ],
+  // Runtime is Node 23 (latest as Jan 2025), to be run in CI (action/setup-node) and local machines
+  "compilerOptions": {
+    // MAIN SETTINGS (based on runtime)
+    "target": "es2023",   // highest available, fully supported by Node 23
+    "module": "nodenext", // preferred for modern Node projects
+    "outDir": "dist",     // standard output folder for all emitted files
+
+    // DEFAULTS that are always "good to have" - expect to be the same for all projects
+    "allowJs": false,             // no need to compile JS, all is TS
+    "noUncheckedIndexedAccess": true,
+    "removeComments": true,
+    "skipLibCheck": true,         // skip type checking of declaration files (.d.ts) - allows quick hot reload
+    "strict": true,               // enable all strict type-checking options
+    "verbatimModuleSyntax": true, // force using 'import type' for types
+
+    // ADDITIONAL SETTINGS (vary per project)
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { coverageConfigDefaults, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      exclude: [
+        '**/index.ts',
+        'src/container.ts',
+        'src/model/**',
+        ...coverageConfigDefaults.exclude
+      ],
+      reporter: ['text'], // other: 'html', 'clover', 'json'
+      thresholds: {
+        lines: 26,
+        branches: 44,
+      }
+    }
+  }
+})