@mavogel/cdk-vscode-server 0.0.62 → 0.0.64

package/CLAUDE.md

@@ -4,18 +4,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository Overview
 
-This is a JSII-enabled CDK construct library published to npm, PyPI, and Go that deploys VS Code Server on AWS. It's designed for workshop/development purposes and creates infrastructure for running a cloud-based VS Code instance accessible through CloudFront.
+A JSII-enabled CDK construct library that deploys VS Code Server on AWS. Published to npm and PyPI. Designed for workshop/development environments with intentionally permissive security for ease of use.
 
-**Key Characteristics**:
-- **Projen-managed**: All project configuration is in `.projenrc.ts` - run `npx projen` after modifying it
-- **Multi-language**: TypeScript source published to Python and Go via JSII
-- **Not production-ready**: Intentionally permissive for workshop scenarios
+**Key Characteristic**: This is **NOT production-ready** by design - it's optimized for quick workshop setup and learning environments.
+
+## Projen-Managed Project
+
+**Critical**: ALL project configuration is in `.projenrc.ts`. After modifying it, run `npx projen` to regenerate managed files.
+
+**Never manually edit**:
+- `package.json`
+- Task definitions
+- GitHub workflows
+- Any file with "~~ Generated by projen" header
 
 ## Development Commands
 
 ### Build and Test
 ```bash
-# Build project (compiles TS, bundles Lambdas, generates API docs)
+# Full build (compiles TS, bundles Lambdas, generates API docs)
 npx projen build
 
 # Run unit tests
@@ -24,10 +31,10 @@ npx projen test
 # Run single test file
 npx jest test/vscode-server.test.ts
 
-# Run tests in watch mode
+# Watch mode for tests
 npx projen test:watch
 
-# Integration tests (deploys to eu-west-1, eu-west-2, eu-north-1)
+# Integration tests (deploys to eu-west-1, eu-west-2, eu-north-1, eu-west-3)
 npm run integ-test
 ```
 
@@ -44,82 +51,305 @@ npm run awslint
 ```bash
 # Bundle specific Lambda
 npx projen bundle:installer/installer.lambda
+npx projen bundle:idle-monitor/idle-monitor.lambda
+npx projen bundle:idle-monitor-enabler/idle-monitor-enabler.lambda
 npx projen bundle:secret-retriever/secret-retriever.lambda
 
-# Watch mode for development
+# Watch mode for Lambda development
 npx projen bundle:installer/installer.lambda:watch
 ```
 
 ### Publishing
 ```bash
-# Package for all targets (JS, Python, Go)
+# Package for all targets (npm, Python)
 npx projen package-all
 
 # Package specific target
 npx projen package:js
 npx projen package:python
-npx projen package:go
 ```
 
-## Architecture
+## Architecture Overview
 
-### Main Construct (`VSCodeServer`)
-Located in `src/vscode-server.ts`, orchestrates:
+### Main Construct: `VSCodeServer` (src/vscode-server.ts)
+
+Orchestrates the entire infrastructure:
 - VPC with single public subnet
 - EC2 instance (default: m7g.xlarge Graviton3 ARM)
-- CloudFront distribution with custom cache policies for VS Code Server
+- CloudFront distribution with custom cache policies
 - Security groups (CloudFront prefix list restriction only)
-- IAM role with CDK permissions for workshop use
-- Optional Route53 + ACM certificate integration via `domainName` prop
+- IAM role with broad CDK permissions (workshop-friendly)
+- Optional: Route53 + ACM certificate integration
+- Optional: Auto-stop feature with idle monitoring
+
+### Custom Resource Pattern
 
-### Custom Resources Pattern
 Uses Lambda-backed custom resources via CDK Provider construct:
-- **Installer** (`src/installer/`): OS-specific VS Code Server installation via SSM documents
-- **SecretRetriever** (`src/secret-retriever/`): Extracts generated password from Secrets Manager
-- **PrefixListRetriever** (`src/prefixlist-retriever/`): Fetches AWS-managed CloudFront prefix lists
 
-### AMI Selection
-`src/mappings.ts` contains SSM parameter paths for:
-- Ubuntu 22/24 (ARM + x86_64)
+1. **Installer** (`src/installer/`)
+   - Runs SSM documents to install VS Code Server
+   - OS-specific installation for Ubuntu 22/24/25 and Amazon Linux 2023
+   - Returns SUCCESS when installation completes
+   - Custom resource name: `SSMInstallerCustomResource`
+   - **Critical**: Must pass `linuxFlavorType` parameter to ensure correct OS-specific SSM document is used
+
+2. **SecretRetriever** (`src/secret-retriever/`)
+   - Extracts generated password from Secrets Manager
+   - Returns password as CloudFormation output
+
+3. **PrefixListRetriever** (`src/prefixlist-retriever/`)
+   - Fetches AWS-managed CloudFront prefix lists
+   - Used to restrict security group ingress
+
+4. **IdleMonitorEnabler** (`src/idle-monitor-enabler/`)
+   - Enables EventBridge rule ONLY after installation completes
+   - Prevents race condition where IdleMonitor stops instance mid-installation
+   - Critical dependency chain: `Installer → IdleMonitorEnabler → IdleMonitor active`
+
+### Auto-Stop Feature Architecture
+
+**Problem Solved**: Race condition where IdleMonitor could stop instance during installation.
+
+**Solution Flow**:
+1. EventBridge rule created in **DISABLED** state (`src/idle-monitor/idle-monitor.ts:118`)
+2. Installer runs and completes VS Code Server setup
+3. IdleMonitorEnabler custom resource **enables** the rule after installation succeeds
+4. IdleMonitor now safely monitors CloudFront metrics for idle detection
+
+**Key Files**:
+- `src/idle-monitor/idle-monitor.ts` - EventBridge rule + Lambda for monitoring
+- `src/idle-monitor/idle-monitor.lambda.ts` - Checks CloudWatch metrics, stops instance if idle
+- `src/idle-monitor-enabler/idle-monitor-enabler.ts` - Custom resource construct
+- `src/idle-monitor-enabler/idle-monitor-enabler.lambda.ts` - Enables EventBridge rule via AWS SDK
+
+**Dependency Wiring** (`src/vscode-server.ts:984`):
+```typescript
+const installerCustomResource = this.node.findChild('SSMInstallerCustomResource');
+enabler.node.addDependency(installerCustomResource);
+```
+
+### AMI Selection (`src/mappings.ts`)
+
+Contains SSM parameter paths for:
+- Ubuntu 22/24/25 (ARM + x86_64)
 - Amazon Linux 2023 (ARM + x86_64)
 
+**Ubuntu Codenames**:
+- Ubuntu 22 = "jammy" (uses ebs-gp2)
+- Ubuntu 24 = "noble" (uses ebs-gp3)
+- Ubuntu 25 = "plucky" (uses ebs-gp3)
+
 Function `getAmiSSMParameterForLinuxArchitectureAndFlavor()` returns region-specific SSM parameter for latest AMI.
 
-### Key Props
-`VSCodeServerProps` in `src/vscode-server.ts:27-155`:
-- **Instance**: `instanceClass`, `instanceSize`, `instanceVolumeSize`
-- **OS**: `instanceOperatingSystem` (LinuxFlavorType enum), `instanceCpuArchitecture` (LinuxArchitectureType enum)
-- **VS Code**: `vscodeUser`, `vscodePassword`, `homeFolder`, `devServerPort`, `devServerBasePath`
-- **Domain**: `domainName`, `hostedZoneId`, `certificateArn`, `autoCreateCertificate`
-- **Extensions**: `additionalInstanceRolePolicies`, `additionalTags`
+**Verify SSM Parameters** (when adding new OS versions):
+```bash
+# List available Ubuntu versions
+aws ssm get-parameters-by-path --path "/aws/service/canonical/ubuntu/server/" --recursive --query "Parameters[*].Name" --region us-east-1
+
+# Verify specific AMI paths exist
+aws ssm get-parameters --names \
+  "/aws/service/canonical/ubuntu/server/plucky/stable/current/amd64/hvm/ebs-gp3/ami-id" \
+  "/aws/service/canonical/ubuntu/server/plucky/stable/current/arm64/hvm/ebs-gp3/ami-id" \
+  --region us-east-1
+```
+
+### Key Props (`src/vscode-server.ts:27-200`)
+
+**Instance Configuration**:
+- `instanceClass`, `instanceSize`, `instanceVolumeSize`
+- `instanceOperatingSystem` (LinuxFlavorType enum)
+- `instanceCpuArchitecture` (LinuxArchitectureType enum)
+
+**VS Code Configuration**:
+- `vscodeUser`, `vscodePassword`, `homeFolder`
+- `devServerPort`, `devServerBasePath`
+
+**Domain/Certificate**:
+- `domainName`, `hostedZoneId`, `certificateArn`, `autoCreateCertificate`
 
-## Important Patterns
+**Auto-Stop**:
+- `enableAutoStop` - Enable automatic instance stop when idle
+- `idleTimeoutMinutes` - Minutes of inactivity before stopping (default: 30)
+- `idleCheckIntervalMinutes` - How often to check (default: 5)
+- `skipStatusChecks` - Skip EC2 status checks before stopping (for testing only)
 
-### Projen Workflow
-1. Edit `.projenrc.ts` for project changes (dependencies, build config, etc.)
-2. Run `npx projen` to regenerate managed files
-3. Never manually edit `package.json`, task definitions, or GitHub workflows
+**Extensions**:
+- `additionalInstanceRolePolicies`, `additionalTags`
 
-### JSII Constraints
+## JSII Constraints
+
+**Critical for JSII compatibility**:
 - All public APIs must be JSII-compatible (no TS-specific types)
-- Bundled dependencies (like `node-html-parser`) in Lambda code must be listed in `.projenrc.ts` `bundledDeps`
-- Lambda functions use esbuild bundling configured via Projen
-
-### CDK-nag Integration
-- `src/suppress-nags.ts` contains suppression patterns
-- Suppressions are applied via `NagSuppressions.addResourceSuppressions()` throughout construct code
-- Necessary because workshop design intentionally violates production best practices (e.g., broad IAM permissions)
-
-### Integration Tests
-- Located in `integ-tests/`
-- Use `@aws-cdk/integ-tests-alpha` framework
-- Deploy actual stacks to 3 regions in parallel
-- Include assertion tests (e.g., login test via Lambda in `integ-tests/functions/`)
-- Run with `npm run integ-test` (requires AWS credentials)
-
-## Domain/Certificate Feature (feat/route53-domain branch)
-When `domainName` prop is provided:
-- Creates Route53 A record pointing to CloudFront distribution
-- Supports `autoCreateCertificate` flag to create ACM cert in us-east-1 with DNS validation
-- Alternatively accepts existing `certificateArn`
-- Auto-discovers hosted zone if `hostedZoneId` not provided
+- Bundled dependencies (like `node-html-parser`) must be in `.projenrc.ts` `bundledDeps`
+- Lambda functions use esbuild bundling configured via Projen (auto-discovered in `src/**/*.lambda.ts`)
+
+## CDK-nag Integration
+
+Suppressions defined in `src/suppress-nags.ts` and applied throughout construct code.
+
+**Why suppressions are needed**: Workshop design intentionally violates production best practices:
+- Broad IAM permissions for ease of use
+- Permissive security groups
+- Public subnet deployment
+- No VPC endpoints
+
+Apply suppressions via `NagSuppressions.addResourceSuppressions()`.
+
+## Integration Tests
+
+Located in `integ-tests/`, using `@aws-cdk/integ-tests-alpha` framework.
+
+**Test Files**:
+- `integ.ubuntu.ts` - Basic Ubuntu 22 deployment + login test
+- `integ.ubuntu24.ts` - Ubuntu 24 deployment + login test
+- `integ.ubuntu25.ts` - Ubuntu 25 deployment + login test
+- `integ.al2023.ts` - Amazon Linux 2023 deployment
+- `integ.custom-domain.ts` - Custom domain + ACM certificate
+- `integ.stop-on-idle.ts` - **4-phase auto-stop workflow test**
+
+**Stop-on-Idle Test Phases** (`integ-tests/integ.stop-on-idle.ts`):
+1. `verify-auto-stop` - Wait for instance to stop after idle timeout
+2. `disable-idle-monitor` - Disable EventBridge rule to prevent re-stopping
+3. `start-instance` - Start instance and wait for running state
+4. `verify-login` - Check VS Code Server accessibility via CloudFront
+
+**Run Integration Tests**:
+```bash
+npm run integ-test  # Deploys to 4 regions in parallel
+```
+
+**Important**: Integration tests deploy actual stacks and incur AWS costs.
+
+## Lambda Bundling
+
+Projen automatically discovers Lambda functions matching `src/**/*.lambda.ts` pattern.
+
+**Auto-generated tasks** for each Lambda:
+- `bundle:<path>/name.lambda` - Bundle Lambda code
+- `bundle:<path>/name.lambda:watch` - Watch mode for development
+
+**Bundled output**: `assets/<path>/name.lambda/index.js`
+
+## Common Workflows
+
+### Adding a New Lambda Function
+
+1. Create `src/my-feature/my-feature.lambda.ts`
+2. Create `src/my-feature/my-feature-function.ts` (CDK construct wrapper)
+3. Run `npx projen` - auto-discovers and creates bundle task
+4. Import in construct: `import { MyFeatureFunction } from './my-feature/my-feature-function'`
+
+### Modifying VSCodeServer Props
+
+1. Edit `src/vscode-server.ts` - update `VSCodeServerProps` interface
+2. Run `npx projen build` - regenerates JSII artifacts + API docs
+3. Update README.md with usage examples
+
+### Testing Changes
+
+1. Unit tests: `npx jest test/vscode-server.test.ts`
+2. Build validation: `npx projen build` (includes awslint checks)
+3. Integration test: `npm run integ-test` (full deployment test)
+
+### Adding Support for a New Ubuntu Version
+
+When Ubuntu releases a new version (e.g., Ubuntu 26):
+
+1. **Add AMI mappings** in `src/mappings.ts`:
+   ```typescript
+   [
+     'arm-ubuntu26',
+     '/aws/service/canonical/ubuntu/server/CODENAME/stable/current/arm64/hvm/ebs-gp3/ami-id',
+   ],
+   [
+     'amd64-ubuntu26',
+     '/aws/service/canonical/ubuntu/server/CODENAME/stable/current/amd64/hvm/ebs-gp3/ami-id',
+   ],
+   ```
+   Replace `CODENAME` with Ubuntu's codename (verify via AWS SSM Parameter Store)
+
+2. **Add enum value** in `src/vscode-server.ts`:
+   ```typescript
+   export enum LinuxFlavorType {
+     // ...
+     UBUNTU_26 = 'ubuntu26',
+   }
+   ```
+
+3. **Update Installer** in `src/installer/installer.ts`:
+   - Add `LinuxFlavorType.UBUNTU_26` to the Ubuntu switch case in `createSSMDocument()` (line ~657)
+   - Update installer calls in `src/vscode-server.ts` to include new case (line ~930)
+
+4. **Pass linuxFlavorType** in `src/vscode-server.ts`:
+   ```typescript
+   installer = Installer.ubuntu({
+     // ... other options
+     linuxFlavorType: instanceOperatingSystem, // Critical!
+   })._bind(this);
+   ```
+
+5. **Create integration test**: Copy `integ-tests/integ.ubuntu25.ts` to `integ.ubuntu26.ts` and update OS version
+
+6. **Update documentation**:
+   - Update README.md examples with inline comments showing all supported versions
+   - Examples in `examples/` directory (optional - can keep as Ubuntu 24)
+
+7. **Verify and build**:
+   ```bash
+   # Verify SSM parameters exist
+   aws ssm get-parameters-by-path --path "/aws/service/canonical/ubuntu/server/CODENAME/" --recursive --region us-east-1
+
+   # Build and test
+   npx projen build
+   npm run integ-test
+   ```
+
+## Race Condition Prevention (Auto-Stop)
+
+**Issue**: IdleMonitor EventBridge rule triggers immediately on stack creation, potentially stopping instance during installation (observed: instance stopped 72 seconds after installer started).
+
+**Fix**: Three-stage dependency chain ensures safe operation:
+
+```
+EC2 Instance
+    ↓
+Installer Custom Resource (waits for VS Code Server installation)
+    ↓
+IdleMonitorEnabler Custom Resource (enables EventBridge rule)
+    ↓
+IdleMonitor Active (now safe to monitor)
+```
+
+**Implementation Details**:
+- EventBridge rule created with `enabled: false` (`src/idle-monitor/idle-monitor.ts:118`)
+- IdleMonitorEnabler depends on `SSMInstallerCustomResource` via `node.addDependency()`
+- CloudFormation enforces ordering automatically
+
+This pattern can be applied to any future features requiring post-installation activation.
+
+## Multi-Language Publishing
+
+Project publishes to:
+- **npm**: `@mavogel/cdk-vscode-server`
+- **PyPI**: `cdk-vscode-server`
+
+JSII compiles TypeScript to:
+- JavaScript (npm)
+- Python (PyPI)
+
+**Publishing** (requires credentials):
+```bash
+npx projen release
+```
+
+## Workshop-Specific Considerations
+
+**Remember**: This construct is intentionally designed for workshops, NOT production:
+
+- IAM roles have broad permissions (all CDK operations)
+- Security groups allow CloudFront only (but permissive within that constraint)
+- No private subnets or VPC endpoints (cost optimization for workshops)
+- Single public subnet (simplicity over high availability)
+- Password-based authentication (ease of use over MFA/SSO)
+
+When reviewing changes, prioritize **ease of use** and **quick setup** over security hardening.

package/README.md

@@ -21,7 +21,9 @@ we implement new features. Therefore make sure you use an exact version in your
 - [Features](#features)
 - [Usage](#usage)
   - [Standard](#Standard)
+  - [Pre-populate with Git Repository](#pre-populate-with-git-repository)
   - [Custom Domain Configuration](#custom-domain-configuration)
+  - [Auto-Stop Configuration](#auto-stop-configuration)
 - [Solution Design](#solution-design)
 - [Inspiration](#inspiration)
 
@@ -31,7 +33,7 @@ we implement new features. Therefore make sure you use an exact version in your
 - 📏 **Best Practice Setup**: Set up with [projen](https://projen.io/) and a [single configuration file](./.projenrc.ts) to keep your changes centralized.
 - 🤹‍♂️ **Pre-installed packages**: Besides the [vscode](https://code.visualstudio.com/) server, other tools and software packages such as `git`, `docker`, `awscli` `nodejs` and `python` are pre-installed on the EC2 instance.
 - 🌐 **Custom Domain Support**: Use your own domain name with automatic ACM certificate creation and Route53 DNS configuration, or bring your existing certificate.
-- 💰 **Auto-Stop**: Automatically stop EC2 instances after inactivity with Elastic IP retention - save up to 75% on costs for development environments
+- 💰 **Auto-Stop**: Automatically stop EC2 instances after inactivity with Elastic IP retention - save up to 75% on costs for development environments.
 - 🏗️ **Extensibility**: Pass in properties to the construct, which start with `additional*`. They allow you to extend the configuration to your needs. There are more to come...
 
 ## Usage
@@ -67,7 +69,7 @@ export class MyStack extends Stack {
       instanceVolumeSize: 8,
       instanceClass: ec2.InstanceClass.M7G,
       instanceSize: ec2.InstanceSize.LARGE,
-      instanceOperatingSystem: LinuxFlavorType.UBUNTU_22,
+      instanceOperatingSystem: LinuxFlavorType.UBUNTU_24,
       instanceCpuArchitecture: LinuxArchitectureType.ARM,
       
       // 👇🏽 or if you want to give the InstanceRole more permissions
@@ -115,6 +117,41 @@ dev.vscodepassword64FBCA12 = foobarbaz
 
 See the [examples](./examples) folder for more inspiration.
 
+### Pre-populate with Git Repository
+
+Clone a git repository into the VS Code Server's home folder during instance setup - perfect for workshops or development environments with starter code:
+
+```ts
+new VSCodeServer(this, 'vscode', {
+  // Clone a git repository into the home folder
+  repoUrl: 'https://github.com/aws-samples/my-workshop-repo.git',
+
+  // Optional: customize the home folder path (default: /Workshop)
+  homeFolder: '/MyWorkshop',
+
+  // Optional: specify VS Code user (default: vscode-user)
+  vscodeUser: 'workshop-user',
+});
+```
+
+**What happens:**
+1. During instance setup, the specified git repository is cloned into the user's home folder
+2. VS Code Server opens with the repository already loaded and ready to use
+3. Participants can start coding immediately without manual git clone steps
+
+**Use cases:**
+- Workshop environments with pre-configured starter code
+- Development environments with boilerplate projects
+- Training sessions with example applications
+- Code review sessions with pre-loaded repositories
+
+**Repository requirements:**
+- Must be publicly accessible (no authentication required)
+- HTTPS URLs only (SSH git URLs are not supported)
+- Repository will be cloned using `git clone` during instance initialization
+
+For complete examples, see [examples/](./examples).
+
 ### Custom Domain Configuration
 
 You can configure your VS Code Server with a custom domain name instead of using the default CloudFront domain. The construct supports three different configuration options:
@@ -200,6 +237,7 @@ new VSCodeServer(this, 'vscode', {
 - Elastic IP for consistent public addressing
 - EventBridge rule triggering idle monitoring at configured intervals
 - IdleMonitor Lambda function checking CloudWatch metrics for request activity
+- IdleMonitorEnabler custom resource ensuring monitoring only starts after installation completes
 - CloudWatch metrics from CloudFront distribution
 
 **Integration Testing:**

package/assets/idle-monitor-enabler/idle-monitor-enabler.lambda/index.js

@@ -0,0 +1,67 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/idle-monitor-enabler/idle-monitor-enabler.lambda.ts
+var idle_monitor_enabler_lambda_exports = {};
+__export(idle_monitor_enabler_lambda_exports, {
+  handler: () => handler
+});
+module.exports = __toCommonJS(idle_monitor_enabler_lambda_exports);
+var import_client_eventbridge = require("@aws-sdk/client-eventbridge");
+var eventBridge = new import_client_eventbridge.EventBridge();
+var handler = async (event) => {
+  console.log("Event: %j", { ...event, ResponseURL: "..." });
+  const ruleName = event.ResourceProperties.RuleName;
+  if (!ruleName) {
+    throw new Error("RuleName is required in ResourceProperties");
+  }
+  switch (event.RequestType) {
+    case "Create":
+    case "Update":
+      console.log(`Enabling EventBridge rule: ${ruleName}`);
+      await eventBridge.send(
+        new import_client_eventbridge.EnableRuleCommand({
+          Name: ruleName
+        })
+      );
+      console.log(`Successfully enabled rule: ${ruleName}`);
+      return {
+        PhysicalResourceId: `idle-monitor-enabler-${ruleName}`
+      };
+    case "Delete":
+      console.log(`Disabling EventBridge rule on deletion: ${ruleName}`);
+      try {
+        await eventBridge.send(
+          new import_client_eventbridge.DisableRuleCommand({
+            Name: ruleName
+          })
+        );
+        console.log(`Successfully disabled rule: ${ruleName}`);
+      } catch (error) {
+        console.log(`Error disabling rule (ignoring): ${error.message}`);
+      }
+      return {};
+    default:
+      throw new Error(`Unsupported RequestType: ${event.RequestType}`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handler
+});