add shared CLI for terminal and browser based on ink/web-ink; fix E2E tests; fix VirtualPod type

Author: devalbo

docs/CODING_GUIDELINES.md

@@ -2,6 +2,13 @@
 
 Keep the codebase maintainable: strict types, small units of work, and simple React components.
 
+## React
+
+- **Use the latest stable React** and follow current React best practices. Prefer modern APIs (e.g. hooks, concurrent features where applicable) over legacy patterns.
+- **Effects and event logic:** When a `useEffect` needs to call a callback (e.g. a prop like `onOutputLines`) that should not be in the dependency array—to avoid re-running the effect when the parent passes a new function reference—use **`useEffectEvent`** (React 19+) to wrap that callback. The Effect Event always sees the latest props/state when it runs but does not trigger the effect to re-run when it changes. This keeps the effect’s dependencies minimal and avoids stale closures.
+- **Custom hooks for stateful logic.** If a component has non-trivial state or effects, move that logic into a `useSomething` hook and keep the component mostly presentational.
+- **Composition over complexity.** Prefer many small components and clear data flow over large components with many branches.
+
 ## TypeScript
 
 - **Strict types only.** The project uses `strict: true` in `tsconfig.json`. Do not relax it.
@@ -20,7 +27,6 @@ Keep the codebase maintainable: strict types, small units of work, and simple Re
 
 - **Keep components small.** If a component is long or has many branches, extract subcomponents or custom hooks.
 - **Avoid overly complex components.** Prefer many small components over one large one. Use composition.
-- **Custom hooks for stateful logic.** If a component has non-trivial state or effects, move that logic into a `useSomething` hook and keep the component mostly presentational.
 - **Props: typed and minimal.** Define a clear props interface; avoid spreading large objects “just in case.”
 
 ## General

docs/testing/bdd-tests.md

@@ -4,8 +4,9 @@ E2E tests are written in Gherkin (`.feature` files) and run with [Playwright](ht
 
 ## Commands
 
-- **Generate specs and run:** `npx bddgen && npx playwright test` (or `npm run test:e2e` / `npm run test:bdd`)
+- **Generate specs and run (browser only):** `npx bddgen && npx playwright test` (or `npm run test:e2e` / `npm run test:bdd`) — runs only **browser** CLI scenarios (Example #1); no browser is launched for terminal scenarios.
 - **With browser visible:** `npm run test:e2e:headed`
+- **Terminal CLI only (no browser):** `npm run test:e2e:terminal` — runs terminal CLI E2E via Vitest (spawns Node CLI, no Playwright, no browser).
 - **View last report:** `npx playwright show-report`
 
 After changing `.feature` files or step definitions, run `npx bddgen` before `npx playwright test`.
@@ -60,7 +61,12 @@ These are implemented in `tests/features/*.feature` and run with Playwright.
 
 ### CLI in browser vs terminal (Scenario Outline)
 
-The same CLI scenarios run **in the browser** (Terminal tab) and **in the terminal** (Node CLI spawned with piped stdin). One feature file per area (e.g. `cli-contacts.feature`) uses a **Scenario Outline** with `Examples: | context | browser | terminal |`. The step "Given I have the CLI in the <context>" either opens the Terminal tab (browser) or spawns `npx tsx src/cli/run-node.tsx` with a unique temp store path (terminal). "When I run the command" and "Then I should see ... in the output" branch on context. Run with the same command as other E2E: `npm run test:e2e` (dev server must be running for browser; terminal runs without it). In Node, `exit` quits the process; `export` prints JSON (or `--download` writes a file). See README and [INTEGRATION_GUIDE.md](../INTEGRATION_GUIDE.md) for full CLI usage.
+The same CLI scenarios are defined **for both browser and terminal** in the feature files (e.g. `cli-contacts.feature` uses `Examples: | context | browser | terminal |`). In practice they run in two ways so that a browser is never opened for terminal scenarios:
+
+- **Browser (Example #1):** Run with `npm run test:e2e`. Playwright is configured to run only tests named "Example #1" (browser context). The dev server must be running; the test opens the Terminal tab and asserts via the in-page CLI output mirror.
+- **Terminal (no browser):** Run with `npm run test:e2e:terminal`. Vitest runs `tests/e2e-cli-terminal.spec.ts`, which spawns the Node CLI with piped stdin and asserts on stdout. No Playwright, no browser.
+
+The step "Given I have the CLI in the <context>" either opens the Terminal tab (browser) or spawns `npx tsx src/cli/run-node.tsx` (terminal). See README and [INTEGRATION_GUIDE.md](../INTEGRATION_GUIDE.md) for full CLI usage.
 
 ### Not yet automated (manual verification)
 

eslint.config.js

@@ -1,29 +1,66 @@
 // For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
 import storybook from "eslint-plugin-storybook";
+import tseslint from 'typescript-eslint';
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import { defineConfig, globalIgnores } from 'eslint/config';
 
-import js from '@eslint/js'
-import globals from 'globals'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import { defineConfig, globalIgnores } from 'eslint/config'
-
-export default defineConfig([globalIgnores(['dist']), {
-  files: ['**/*.{js,jsx}'],
-  extends: [
-    js.configs.recommended,
-    reactHooks.configs.flat.recommended,
-    reactRefresh.configs.vite,
-  ],
-  languageOptions: {
-    ecmaVersion: 2020,
-    globals: globals.browser,
-    parserOptions: {
-      ecmaVersion: 'latest',
-      ecmaFeatures: { jsx: true },
-      sourceType: 'module',
+export default defineConfig([
+  globalIgnores(['dist', '.features-gen']),
+  // Node/Config files: process etc.
+  {
+    files: ['vite.config.js', 'vitest.config.ts', 'playwright.config.ts'],
+    languageOptions: { globals: { ...globals.node } },
+  },
+  // JS/JSX
+  {
+    files: ['**/*.{js,jsx}'],
+    extends: [
+      js.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
     },
   },
-  rules: {
-    'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+  // TypeScript/TSX: parser so .stories.tsx and .storybook parse correctly
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: { ...globals.browser },
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^[A-Z_]' }],
+      'no-empty-pattern': 'off',
+      '@typescript-eslint/no-require-imports': 'off',
+      'react-refresh/only-export-components': 'off',
+      'react-hooks/set-state-in-effect': 'off',
+    },
   },
-}, ...storybook.configs["flat/recommended"]])
+  ...storybook.configs['flat/recommended'],
+]);

package-lock.json

@@ -42,6 +42,7 @@
     "build-storybook": "storybook build",
     "test:e2e": "npx bddgen && playwright test",
     "test:e2e:headed": "npx bddgen && playwright test --headed",
+    "test:e2e:terminal": "vitest run --config vitest.terminal-e2e.config.ts",
     "test:bdd": "npx bddgen && playwright test",
     "cli": "tsx src/cli/run-node.tsx"
   },
@@ -84,6 +85,7 @@
     "storybook": "^10.2.3",
     "tsx": "^4.19.2",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
     "vite": "npm:rolldown-vite@7.2.5",
     "vitest": "^4.0.18"
   },

package.json

@@ -22,7 +22,8 @@ export default defineConfig({
     navigationTimeout: 15_000,
   },
   projects: [
-    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    // Browser scenarios only (Example #1 in each outline). Terminal scenarios run via test:e2e:terminal (no browser).
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, grep: /Example #1/ },
   ],
   // No webServer: start the dev server yourself (e.g. npm run dev) before running BDD/E2E tests.
 });

playwright.config.ts

@@ -1001,7 +1001,7 @@ const styles: Record<string, CSSProperties> = {
   navGitHubLink: { display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '6px 12px', borderRadius: 4, border: '1px solid #444', background: '#2a2a2a', color: '#ccc', textDecoration: 'none', marginLeft: 4, fontSize: 12, fontWeight: 500 },
   topNavTab: { padding: '14px 24px', border: 'none', background: 'transparent', color: '#888', cursor: 'pointer', fontSize: 14, fontWeight: 500, borderBottom: '2px solid transparent', transition: 'all 0.2s' },
   topNavTabActive: { color: '#4ecdc4', borderBottom: '2px solid #4ecdc4' },
-  terminalView: { padding: 0, height: 'calc(100vh - 49px)', background: '#1e1e1e' },
+  terminalView: { padding: 0, height: 'calc(100vh - 49px)', minHeight: 320, width: '100%', background: '#1e1e1e', display: 'flex', flexDirection: 'column' },
   personasViewContainer: { padding: 24, flex: 1, maxWidth: 800, margin: '0 auto', width: '100%', boxSizing: 'border-box' },
   contactsViewContainer: { padding: 24, flex: 1, maxWidth: 800, margin: '0 auto', width: '100%', boxSizing: 'border-box' },
   groupsViewContainer: { padding: 24, flex: 1, maxWidth: 800, margin: '0 auto', width: '100%', boxSizing: 'border-box' },