add jsdoc comments for infra core and terraform functions (#436)

infra/cdktf/src/lib/app-stack.ts

@@ -8,6 +8,9 @@ import { withBackend } from './backend';
 import { CloudGovSpace } from './cloud.gov/space';
 import { DataAwsSsmParameter } from '../../.gen/providers/aws/data-aws-ssm-parameter';
 
+/**
+ * Register an application stack and translates the IaC to a template format via the `synth` function.
+ */
 export const registerAppStack = (
   stackPrefix: string,
   gitCommitHash: string
@@ -18,6 +21,15 @@ export const registerAppStack = (
   app.synth();
 };
 
+/**
+ * Represents a Terraform stack designed to deploy and manage resources for the application using AWS and Cloud Foundry providers.
+ * This sets up necessary providers and resources specific to the application's deployment needs and handles configuration for the following:
+ *
+ * - AWS as a provider with a specific region.
+ * - Retrieves Cloud Foundry credentials from AWS SSM Parameter Store.
+ * - Sets up the Cloud Foundry provider for integration with the Cloud.gov environment.
+ * - Instantiates a CloudGovSpace resource with the provided git commit hash identifier.
+ */
 class AppStack extends TerraformStack {
   constructor(scope: Construct, id: string, gitCommitHash: string) {
     super(scope, id);

infra/cdktf/src/lib/backend.ts

@@ -1,5 +1,9 @@
 import { S3Backend, TerraformStack } from 'cdktf';
 
+/**
+ * Configures an S3 backend for a given Terraform stack to store the Terraform
+ * state in an S3 bucket with a specific key and region.
+ */
 export const withBackend = (stack: TerraformStack, stackPrefix: string) =>
   new S3Backend(stack, {
     bucket: '10x-atj-tfstate',

infra/cdktf/src/lib/cloud.gov/node-astro.ts

@@ -1,6 +1,17 @@
 import { Construct } from 'constructs';
 import * as cloudfoundry from '../../../.gen/providers/cloudfoundry';
 
+/**
+ * Represents a service configuration for deploying an application on a Cloud Foundry platform.
+ * The `AstroService` class sets up the required resources, routes, services, and configurations
+ * needed to deploy, run, and maintain the application.
+ *
+ * ### Important Notes:
+ * - The RDS instance is configured to prevent destruction to ensure database persistence.
+ * - Timeout settings for the database instance allow for extended creation, update, and deletion times.
+ * - Routes and services are bound together to enable communication with the database and login service
+ *
+ */
 export class AstroService extends Construct {
   constructor(
     scope: Construct,

infra/cdktf/src/lib/cloud.gov/space.ts

@@ -5,6 +5,10 @@ import { CLOUD_GOV_ORG_NAME } from './config';
 import { AstroService } from './node-astro';
 import { getSecret } from '../secrets';
 
+/**
+ * Initializes a [Cloud.gov space](https://cloud.gov/docs/getting-started/concepts/#spaces) within a specified organization
+ * and deploys AstroService instance(s)
+ */
 export class CloudGovSpace extends Construct {
   constructor(scope: Construct, id: string, gitCommitHash: string) {
     super(scope, id);

infra/cdktf/src/lib/rest-api.ts

@@ -4,6 +4,10 @@ import { AssetType, TerraformAsset, TerraformOutput } from 'cdktf';
 import { Construct } from 'constructs';
 import * as aws from '../../.gen/providers/aws';
 
+/**
+ * Creates and deploys infrastructure that includes an AWS Lambda function and API Gateway using Terraform.
+ * It also manages the creation of necessary roles, permissions, and assets required for these components.
+ */
 export class FormService extends Construct {
   readonly url: string;
 

infra/cdktf/src/lib/secrets.ts

@@ -1,6 +1,9 @@
 import { Construct } from 'constructs';
 import { DataAwsSsmParameter } from '../../.gen/providers/aws/data-aws-ssm-parameter';
 
+/**
+ * Retrieves the value of an AWS SSM Parameter Store secret.
+ */
 export const getSecret = (scope: Construct, name: string) => {
   const parameter = new DataAwsSsmParameter(scope, name, {
     name,

infra/core/src/commands/delete-secret.ts

@@ -1,5 +1,8 @@
 import type { SecretKey, SecretsVault } from '../lib/types.js';
 
+/**
+ * Deletes a secret from the provided secrets vault.
+ */
 export const deleteSecret = async (vault: SecretsVault, key: SecretKey) => {
   return await vault.deleteSecret(key);
 };

infra/core/src/commands/get-secret-key-list.ts

@@ -1,5 +1,8 @@
 import { type SecretsVault } from '../lib/types.js';
 
+/**
+ * Retrieves a list of secret keys from the provided secrets vault.
+ */
 export const getSecretKeyList = async (vault: SecretsVault) => {
   return await vault.getSecretKeys();
 };

infra/core/src/commands/get-secret.ts

@@ -1,5 +1,8 @@
 import { type SecretsVault } from '../lib/types.js';
 
+/**
+ * Retrieves a secret value from the provided secrets vault.
+ */
 export const getSecret = async (vault: SecretsVault, key: string) => {
   return await vault.getSecret(key);
 };

infra/core/src/commands/get-secrets.ts

@@ -1,5 +1,8 @@
 import { type SecretsVault } from '../lib/types.js';
 
+/**
+ * Retrieves all secrets from the provided secrets vault.
+ */
 export const getSecrets = async (vault: SecretsVault) => {
   const allKeys = await vault.getSecretKeys();
   return await vault.getSecrets(allKeys);

infra/core/src/commands/set-login-gov-secrets.ts

@@ -21,6 +21,10 @@ type Context = {
   generateLoginGovKey?: GenerateLoginGovKey;
 };
 
+/**
+ * Sets or retrieves Login.gov secrets for the given application key. It retrieves and returns the
+ * existing key pair or generates, stores, and returns new key pair if one didn't exist previously.
+ */
 export const setLoginGovSecrets = async (
   ctx: Context,
   env: DeployEnv,
@@ -54,12 +58,21 @@ export const setLoginGovSecrets = async (
   };
 };
 
+/**
+ * Gets the file path for the Login.gov public key (`.pem`) file.
+ */
 const loginGovPublicKeyPath = (secretsDir: string, appKey: string) =>
   `${secretsDir}/login-gov-${appKey}-key.pem`;
 
+/**
+ * Gets the file path for the Login.gov private key certificate (`.pem`) file.
+ */
 const loginGovPrivateKeyPath = (secretsDir: string, appKey: string) =>
   `${secretsDir}/login-gov-${appKey}-cert.pem`;
 
+/**
+ * Generates a public-private key pair for Login.gov using OpenSSL.
+ */
 const generateLoginGovKey: GenerateLoginGovKey = async (
   privateKeyPath: string,
   publicKeyPath: string

infra/core/src/commands/set-secret.ts

@@ -1,5 +1,8 @@
 import { type SecretsVault } from '../lib/types.js';
 
+/**
+ * Sets a secret in a specified secrets vault.
+ */
 export const setSecret = async (
   vault: SecretsVault,
   key: string,

infra/core/src/lib/adapters/aws-param-store.ts

@@ -16,6 +16,10 @@ import type {
   SecretsVault,
 } from '../types.js';
 
+/**
+ * Provides an implementation of the SecretsVault interface leveraging
+ * AWS Systems Manager Parameter Store to manage secrets securely.
+ */
 export class AWSParameterStoreSecretsVault implements SecretsVault {
   client: SSMClient;
 

infra/core/src/lib/adapters/in-memory.ts

@@ -1,5 +1,8 @@
 import type { SecretMap, SecretsVault } from '../types.js';
 
+/**
+ * Provides an in-memory implementation of the SecretsVault interface
+ */
 export class InMemorySecretsVault implements SecretsVault {
   constructor(private secretMap: SecretMap) {}
 

infra/core/src/values.ts

@@ -2,6 +2,11 @@ export type DeployEnv = 'dev' | 'staging';
 
 const getPathPrefix = (env: DeployEnv) => `/tts-10x-atj-${env}`;
 
+/**
+ * Generates an object containing the paths for private/public keys pairs
+ * associated with login.gov for an application in the specified
+ * deployment environment.
+ */
 export const getAppLoginGovKeys = (env: DeployEnv, appKey: string) => {
   const prefix = getPathPrefix(env);
   return {