feat: cloudscape frontend

.projenrc.ts

@@ -1692,12 +1692,23 @@ const cdkExplorer = configureProject(
     devDeps: [
       'vscode-languageserver-protocol@^3',
       '@types/express@^4',
+      'react@^18',
+      'react-dom@^18',
+      '@types/react@^18',
+      '@types/react-dom@^18',
+      '@cloudscape-design/components@^3',
+      '@cloudscape-design/global-styles@^1',
+      'esbuild',
+      'tsx',
+      'supertest@^6',
+      '@types/supertest@^6',
       '@types/convert-source-map@^2',
     ],
     tsconfig: {
       compilerOptions: {
         ...defaultTsOptions,
       },
+      exclude: ['frontend'],
     },
     jestOptions: jestOptionsForProject({
       jestConfig: {
@@ -1712,6 +1723,10 @@ const cdkExplorer = configureProject(
   }),
 );
 fixupTestTask(cdkExplorer);
+cdkExplorer.postCompileTask.exec('tsx build-tools/bundle-frontend.ts');
+cdkExplorer.tsconfigDev.addInclude('build-tools/**/*.ts');
+cdkExplorer.gitignore.addPatterns('lib/web/static/', 'lib/web/web-assets.generated.json');
+cdkExplorer.npmignore?.addPatterns('frontend', 'tsconfig.frontend.json');
 cli.deps.addDependency('@aws-cdk/cdk-explorer', pj.DependencyType.RUNTIME);
 
 // #endregion

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

@@ -0,0 +1,59 @@
+/**
+ * Builds the web explorer SPA into lib/web/static (typechecked via
+ * tsconfig.frontend.json, since esbuild only transpiles), then writes the same
+ * assets to lib/web/web-assets.generated.json so they ride the require() graph
+ * into the published CLI bundle (express.static paths are not bundled).
+ */
+import { execFileSync } from 'child_process';
+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');
+const outDir = path.join(packageRoot, 'lib', 'web', 'static');
+const embeddedAssetsFile = path.join(packageRoot, 'lib', 'web', 'web-assets.generated.json');
+
+async function main(): Promise<void> {
+  typecheck();
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  await esbuild.build({
+    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: true,
+    logLevel: 'info',
+  });
+
+  fs.copyFileSync(path.join(frontendDir, 'index.html'), path.join(outDir, 'index.html'));
+  writeEmbeddedAssets();
+}
+
+function writeEmbeddedAssets(): void {
+  const assets: Record<string, string> = {
+    'index.html': fs.readFileSync(path.join(frontendDir, 'index.html'), 'utf-8'),
+    'bundle.js': fs.readFileSync(path.join(outDir, 'bundle.js'), 'utf-8'),
+    'bundle.css': fs.readFileSync(path.join(outDir, 'bundle.css'), 'utf-8'),
+  };
+  fs.writeFileSync(embeddedAssetsFile, JSON.stringify(assets));
+}
+
+function typecheck(): void {
+  execFileSync('tsc', ['--noEmit', '-p', path.join(packageRoot, 'tsconfig.frontend.json')], {
+    cwd: packageRoot,
+    stdio: 'inherit',
+  });
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});

packages/@aws-cdk/cdk-explorer/frontend/App.tsx

@@ -0,0 +1,40 @@
+import Box from '@cloudscape-design/components/box';
+import Container from '@cloudscape-design/components/container';
+import ContentLayout from '@cloudscape-design/components/content-layout';
+import Grid from '@cloudscape-design/components/grid';
+import Header from '@cloudscape-design/components/header';
+import SpaceBetween from '@cloudscape-design/components/space-between';
+import * as React from 'react';
+import { FilePane } from './components/FilePane';
+
+/** Web explorer shell: Resource Tree (left), two file panes, Violations (bottom). Tree/violations are placeholders until the cloud-assembly reader is wired in. */
+export function App(): JSX.Element {
+  return (
+    <ContentLayout
+      header={
+        <Header variant="h1" description="last updated: —">
+          CDK Web Explorer
+        </Header>
+      }
+    >
+      <SpaceBetween size="l">
+        <Grid gridDefinition={[{ colspan: 3 }, { colspan: 9 }]}>
+          <Container header={<Header variant="h2">Resource Tree</Header>}>
+            <Box color="text-status-inactive">
+              Construct tree appears here once the cloud-assembly reader is wired in.
+            </Box>
+          </Container>
+          <Grid gridDefinition={[{ colspan: 6 }, { colspan: 6 }]}>
+            <FilePane title="file 1" />
+            <FilePane title="file 2" />
+          </Grid>
+        </Grid>
+        <Container header={<Header variant="h2">Violations</Header>}>
+          <Box color="text-status-inactive">
+            Policy-validation violations appear here once the cloud-assembly reader is wired in.
+          </Box>
+        </Container>
+      </SpaceBetween>
+    </ContentLayout>
+  );
+}

packages/@aws-cdk/cdk-explorer/frontend/api.ts

@@ -0,0 +1,17 @@
+import type { DirEntry, FilesResponse, FileResponse } from '../lib/web/protocol';
+
+export type { DirEntry, FilesResponse, FileResponse };
+
+async function getJson<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error((body as { error?: string }).error ?? `request failed: ${res.status}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+export const api = {
+  listFiles: (dir = ''): Promise<FilesResponse> => getJson(`/api/files?dir=${encodeURIComponent(dir)}`),
+  readFile: (filePath: string): Promise<FileResponse> => getJson(`/api/file?path=${encodeURIComponent(filePath)}`),
+};

packages/@aws-cdk/cdk-explorer/frontend/components/FilePane.tsx

@@ -0,0 +1,115 @@
+import Box from '@cloudscape-design/components/box';
+import Button from '@cloudscape-design/components/button';
+import Container from '@cloudscape-design/components/container';
+import Header from '@cloudscape-design/components/header';
+import SpaceBetween from '@cloudscape-design/components/space-between';
+import * as React from 'react';
+import { api, type DirEntry } from '../api';
+
+interface FilePaneProps {
+  /** Heading shown in the pane header (e.g. "file 1"). */
+  readonly title: string;
+}
+
+/**
+ * A self-contained code pane with a server-backed file picker. Browses
+ * directories under the app root via /api/files and shows file contents via
+ * /api/file. Rendered once per code pane (center and right).
+ */
+export function FilePane({ title }: FilePaneProps): JSX.Element {
+  const [picking, setPicking] = React.useState(false);
+  const [dir, setDir] = React.useState('');
+  const [entries, setEntries] = React.useState<readonly DirEntry[]>([]);
+  const [filePath, setFilePath] = React.useState<string | undefined>();
+  const [content, setContent] = React.useState('');
+  const [error, setError] = React.useState<string | undefined>();
+
+  const browse = React.useCallback(async (nextDir: string) => {
+    try {
+      const res = await api.listFiles(nextDir);
+      setDir(res.dir);
+      setEntries(res.entries);
+      setError(undefined);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, []);
+
+  const openPicker = React.useCallback(() => {
+    setPicking(true);
+    void browse('');
+  }, [browse]);
+
+  const choose = React.useCallback(async (entry: DirEntry) => {
+    if (entry.type === 'dir') {
+      void browse(entry.path);
+      return;
+    }
+    try {
+      const res = await api.readFile(entry.path);
+      setFilePath(res.path);
+      setContent(res.content);
+      setPicking(false);
+      setError(undefined);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, [browse]);
+
+  return (
+    <Container
+      header={
+        <Header variant="h2" actions={<Button iconName="folder-open" onClick={openPicker}>Open file…</Button>}>
+          {filePath ?? title}
+        </Header>
+      }
+    >
+      <SpaceBetween size="s">
+        {error && <Box color="text-status-error">{error}</Box>}
+        {picking ? (
+          <FileBrowser dir={dir} entries={entries} onChoose={choose} onUp={() => browse(parentOf(dir))} />
+        ) : (
+          <pre style={CODE_STYLE}>{content || 'No file selected.'}</pre>
+        )}
+      </SpaceBetween>
+    </Container>
+  );
+}
+
+const CODE_STYLE: React.CSSProperties = {
+  margin: 0,
+  maxHeight: '60vh',
+  overflow: 'auto',
+  fontFamily: 'Monaco, Menlo, "Courier New", monospace',
+  fontSize: '12px',
+  whiteSpace: 'pre',
+};
+
+function FileBrowser(props: {
+  readonly dir: string;
+  readonly entries: readonly DirEntry[];
+  readonly onChoose: (entry: DirEntry) => void;
+  readonly onUp: () => void;
+}): JSX.Element {
+  return (
+    <SpaceBetween size="xxs">
+      <Box variant="code">/{props.dir}</Box>
+      {props.dir !== '' && <Button variant="inline-link" iconName="folder" onClick={props.onUp}>../</Button>}
+      {props.entries.map((entry) => (
+        <Button
+          key={entry.path}
+          variant="inline-link"
+          iconName={entry.type === 'dir' ? 'folder' : 'file'}
+          onClick={() => props.onChoose(entry)}
+        >
+          {entry.type === 'dir' ? `${entry.name}/` : entry.name}
+        </Button>
+      ))}
+    </SpaceBetween>
+  );
+}
+
+function parentOf(dir: string): string {
+  const idx = dir.lastIndexOf('/');
+  return idx === -1 ? '' : dir.slice(0, idx);
+}

packages/@aws-cdk/cdk-explorer/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CDK Web Explorer</title>
+    <link rel="stylesheet" href="./bundle.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="./bundle.js"></script>
+  </body>
+</html>