feat(cli): cdk explore, a web explorer for your CDK app

.projenrc.ts

@@ -1226,15 +1226,33 @@ const cdkExplorer = configureProject(
     ],
     devDeps: [
       'vscode-languageserver-protocol@^3',
+      'react@^18',
+      'react-dom@^18',
+      '@types/react@^18',
+      '@types/react-dom@^18',
+      '@cloudscape-design/components',
+      '@cloudscape-design/global-styles',
+      '@cloudscape-design/design-tokens',
+      'esbuild',
+      'tsx',
+      'supertest@^6',
+      '@types/supertest@^6',
       '@types/convert-source-map@^2',
+      'prismjs@^1',
+      '@types/prismjs@^1',
+      'yaml@^2',
     ],
     tsconfig: {
       compilerOptions: {
         ...defaultTsOptions,
       },
+      exclude: ['frontend'],
     },
     jestOptions: jestOptionsForProject({
       jestConfig: {
+        testMatch: [
+          '<rootDir>/**/test/**/?(*.)+(test).ts?(x)',
+        ],
         coverageThreshold: {
           statements: 80,
           branches: 80,
@@ -1246,6 +1264,22 @@ const cdkExplorer = configureProject(
   }),
 );
 fixupTestTask(cdkExplorer);
+// esbuild only transpiles, so the SPA gets its own `tsc --noEmit` pass before
+// being bundled (the package's main tsc build excludes `frontend/`).
+cdkExplorer.postCompileTask.exec('tsc --noEmit -p frontend/src/tsconfig.json');
+cdkExplorer.preCompileTask.exec('tsx build-tools/bundle-frontend.ts');
+cdkExplorer.eslint?.allowDefaultProjectFiles('build-tools/bundle-frontend.ts');
+cdkExplorer.gitignore.addPatterns('lib/web/static/', 'lib/web/web-assets.generated.ts', '.DS_Store', 'frontend/**/*.d.ts', 'frontend/**/*.js');
+cdkExplorer.npmignore?.addPatterns('frontend');
+cdkExplorer.eslint?.addOverride({
+  files: [
+    'frontend/**',
+  ],
+  rules: {
+    // Allow importing devdependencies (everything is bundled)
+    'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
+  },
+});
 cdkExplorer.eslint?.addOverride({
   files: [
     'lib/**',

packages/@aws-cdk/cdk-explorer/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Developing on the CDK Explorer
+
+## Quick iteration
+
+```sh
+$ project=/path/to/aws-cdk-cli
+$ $project/node_modules/.bin/tsx $project/packages/aws-cdk/bin/cdk explore
+```

packages/@aws-cdk/cdk-explorer/build-tools/bundle-frontend.ts

@@ -0,0 +1,91 @@
+/* eslint-disable no-console */
+/**
+ * Builds the web explorer SPA into lib/web/static, then writes the same assets
+ * to lib/web/web-assets.generated.ts so they ride the require() graph into
+ * the published CLI bundle (static file paths are not bundled).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as esbuild from 'esbuild';
+
+const packageRoot = path.resolve(__dirname, '..');
+const frontendDir = path.join(packageRoot, 'frontend', 'src');
+const outDir = path.join(packageRoot, 'lib', 'web', 'static');
+const embeddedAssetsFile = path.join(packageRoot, 'lib', 'web', 'web-assets.generated.ts');
+
+async function main(): Promise<void> {
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const isWatch = process.argv[2] === '--watch';
+
+  const context = await esbuild.context({
+    entryPoints: [path.join(frontendDir, 'index.tsx')],
+    bundle: true,
+    outfile: path.join(outDir, 'bundle.js'),
+    format: 'iife',
+    platform: 'browser',
+    target: 'es2020',
+    jsx: 'automatic',
+    loader: { '.css': 'css', '.svg': 'dataurl', '.png': 'dataurl' },
+    sourcemap: 'external', // does not load map automatically, have to attach manually
+    logLevel: 'warning',
+    minify: !isWatch,
+    logStyle: 'default',
+  });
+
+  try {
+    await buildAndPostProcess();
+
+    if (isWatch) {
+      const watcher = fs.watch(path.resolve(__dirname, '..', 'frontend'), { recursive: true }, async (eventType, filename) => {
+        console.log(`File changed: ${filename} (${eventType})`);
+        await buildAndPostProcess();
+      });
+
+      await new Promise<void>((resolve) => {
+        process.on('SIGINT', resolve);
+        process.on('SIGTERM', resolve);
+      });
+
+      watcher.close();
+    }
+  } finally {
+    await context.dispose();
+  }
+
+  async function buildAndPostProcess() {
+    try {
+      await context.rebuild();
+      writeEmbeddedAssets();
+      console.log('Built');
+    } catch (e) {
+      console.error(e);
+    }
+  }
+}
+
+const BUNDLE_FILES = ['bundle.js', 'bundle.css'];
+const ASSET_FILES = ['index.html', 'icon.png'];
+
+function writeEmbeddedAssets(): void {
+  const assets = [
+    ...ASSET_FILES.map(f => [f, fs.readFileSync(path.join(frontendDir, f))] as const),
+    ...BUNDLE_FILES.map(f => [f, fs.readFileSync(path.join(outDir, f))] as const),
+  ];
+  fs.writeFileSync(embeddedAssetsFile, [
+    'export const EMBEDDED_ASSETS = {',
+    ...assets.map(([fname, buf]) => {
+      const containsBinary = buf.indexOf('\x00') !== -1;
+      const encoding = containsBinary ? 'base64' : 'utf-8';
+
+      return `  "${fname}": Buffer.from(${JSON.stringify(buf.toString(encoding))}, "${encoding}"),`;
+    }),
+    '};',
+  ].join('\n'), 'utf-8');
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});

packages/@aws-cdk/cdk-explorer/build-tools/watch-explore.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# A bash script to watch the frontend source files and run the CDK explorer in a live mode where
+# it refreshes frontend assets from the filesystem.
+set -eu
+scriptdir=$(cd $(dirname "$0") && pwd)
+root=$(cd $scriptdir/../../../.. && pwd)
+
+env CDK_LIVE=1 $root/node_modules/.bin/tsx $root/packages/aws-cdk/bin/cdk explore &
+trap "pkill -P $$" EXIT
+
+(cd $scriptdir/.. && $root/node_modules/.bin/tsx build-tools/bundle-frontend.ts --watch)

packages/@aws-cdk/cdk-explorer/frontend/prismjs.d.ts

@@ -0,0 +1,9 @@
+declare module 'prismjs/components/prism-core' {
+  import Prism from 'prismjs';
+  export default Prism;
+}
+declare module 'prismjs/components/prism-json' {}
+declare module 'prismjs/components/prism-yaml' {}
+declare module 'prismjs/components/prism-clike' {}
+declare module 'prismjs/components/prism-javascript' {}
+declare module 'prismjs/components/prism-typescript' {}