[RFC] feat(cli): Interactive TUI prototype

cdk/src/constructs/task-api.ts

@@ -73,6 +73,23 @@ export interface TaskApiProps {
    */
   readonly nudgeRateLimitPerMinute?: number;
 
+  /**
+   * Per-user per-minute `GET /v1/pending` rate limit.
+   *
+   * The default of 10 was sized for the original CLI-only `bgagent pending`
+   * workflow where users polled by hand. The TUI's adaptive ladder polls
+   * `/v1/pending` on a 2-30s cadence and a fast first poll naturally lands
+   * 20-30 calls in the first minute — comfortably above 10. The handler's
+   * default (`get-pending.ts::PENDING_RATE_LIMIT_PER_MINUTE`) is also 10,
+   * so omitting this prop preserves the historical behaviour.
+   *
+   * Sized for: a single TUI session at 2s sustained cadence (30/min) plus
+   * room for concurrent CLI `bgagent pending` checks during testing.
+   *
+   * @default 60
+   */
+  readonly pendingRateLimitPerMinute?: number;
+
   /**
    * The DynamoDB repo config table. When provided, task creation checks
    * that the target repository is onboarded before accepting the task.
@@ -652,12 +669,21 @@ export class TaskApi extends Construct {
       props.taskEventsTable.grantReadWriteData(denyTaskFn);
 
       // GetPendingFn — GET /pending
+      // Adds `PENDING_RATE_LIMIT_PER_MINUTE` on top of the shared
+      // approval env so the per-user rate limit is configurable from
+      // the construct prop (default 60/min — sized to support a
+      // single TUI session at 2s sustained cadence with headroom for
+      // concurrent CLI `bgagent pending` calls). Approve/deny don't
+      // need this var so it stays out of `approvalEnv`.
       const getPendingFn = new lambda.NodejsFunction(this, 'GetPendingFn', {
         entry: path.join(handlersDir, 'get-pending.ts'),
         handler: 'handler',
         runtime: Runtime.NODEJS_24_X,
         architecture: Architecture.ARM_64,
-        environment: approvalEnv,
+        environment: {
+          ...approvalEnv,
+          PENDING_RATE_LIMIT_PER_MINUTE: String(props.pendingRateLimitPerMinute ?? 60),
+        },
         bundling: commonBundling,
         timeout: Duration.seconds(10),
         memorySize: 256,

cli/docs/recordings/demo-approvals.tape

@@ -0,0 +1,47 @@
+# Approval flow — list → detail → approve/deny
+# Run: vhs demo-approvals.tape
+
+Output demo-approvals.gif
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Padding 20
+
+Type "npm run tui"
+Enter
+Sleep 3s
+Type " "
+Sleep 1s
+
+# Go to Approvals
+Type "3"
+Sleep 1.5s
+
+# Browse approvals
+Down
+Sleep 0.5s
+Up
+Sleep 1s
+
+# Drill into detail
+Enter
+Sleep 3s
+
+# Deny with confirmation
+Type "d"
+Sleep 1s
+# See the confirm dialog
+Sleep 1.5s
+# Cancel
+Type "n"
+Sleep 1s
+
+# Approve instead
+Type "a"
+Sleep 1.5s
+
+# Back to list
+Escape
+Sleep 1s
+
+Type "q"

cli/docs/recordings/demo-full.tape

@@ -0,0 +1,115 @@
+# Full TUI Demo — splash → all panels
+# Run: vhs demo-full.tape
+
+Output demo-full.gif
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Padding 20
+
+# Start the TUI
+Type "npm run tui"
+Enter
+Sleep 3s
+
+# Splash screen visible — press key to dismiss
+Type " "
+Sleep 1.5s
+
+# Tasks panel — navigate list
+Sleep 1s
+Down
+Sleep 0.5s
+Down
+Sleep 0.5s
+Up
+Sleep 1s
+
+# Select first task → Watch
+Enter
+Sleep 3s
+
+# Watch events streaming in...
+Sleep 3s
+
+# Scroll up through events
+Up
+Up
+Up
+Sleep 1s
+# Scroll back down
+Down
+Down
+Down
+Sleep 1s
+
+# Nudge the agent
+Type "n"
+Sleep 0.5s
+Type "focus on the unit tests first"
+Sleep 0.5s
+Enter
+Sleep 1.5s
+
+# Switch to Approvals
+Type "3"
+Sleep 1.5s
+
+# Drill into detail
+Enter
+Sleep 2s
+
+# Approve
+Type "a"
+Sleep 1s
+
+# Back to list
+Escape
+Sleep 1s
+
+# Switch to Policies
+Type "4"
+Sleep 1s
+
+# View a policy detail
+Down
+Down
+Enter
+Sleep 2s
+
+# Navigate while detail stays open
+Down
+Sleep 1s
+Down
+Sleep 1s
+
+# Close detail
+Escape
+Sleep 1s
+
+# Switch to Submit (New Task)
+Type "5"
+Sleep 1s
+
+# Select repo
+Down
+Sleep 0.5s
+Enter
+Sleep 0.5s
+
+# Type instructions
+Enter
+Type "Add integration tests for the payment service"
+Enter
+Sleep 1s
+
+# Submit
+Down
+Down
+Down
+Enter
+Sleep 2s
+
+# Quit
+Type "q"
+Sleep 0.5s

cli/docs/recordings/demo-splash.tape

@@ -0,0 +1,20 @@
+# Splash screen — just the Peccy animation
+# Run: vhs demo-splash.tape
+
+Output demo-splash.gif
+Set FontSize 16
+Set Width 800
+Set Height 500
+Set Padding 20
+
+Type "npm run tui"
+Enter
+
+# Let the splash play for the full Peccy animation cycle
+Sleep 5s
+
+# Dismiss
+Type " "
+Sleep 2s
+
+Type "q"

cli/docs/recordings/demo-watch.tape

@@ -0,0 +1,52 @@
+# Watch panel — event streaming + inline approval + nudge
+# Run: vhs demo-watch.tape
+
+Output demo-watch.gif
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Padding 20
+
+Type "npm run tui"
+Enter
+Sleep 3s
+Type " "
+Sleep 1s
+
+# Select a task
+Enter
+Sleep 5s
+
+# Events streaming in...
+Sleep 5s
+
+# Scroll up through history
+Up
+Up
+Up
+Up
+Sleep 2s
+
+# Back to live
+Down
+Down
+Down
+Down
+Sleep 2s
+
+# Approve inline
+Type "a"
+Sleep 1.5s
+
+# Nudge
+Type "n"
+Sleep 0.5s
+Type "please add error handling"
+Enter
+Sleep 2s
+
+# Back to tasks
+Escape
+Sleep 1s
+
+Type "q"

cli/jest.tui.config.cjs

@@ -0,0 +1,49 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * Separate Jest config for the TUI panel tests. These need the real
+ * Ink runtime (which is pure ESM), so we opt them into Jest's
+ * experimental VM-modules ESM path. Run with:
+ *
+ *   NODE_OPTIONS=--experimental-vm-modules npx jest --config jest.tui.config.cjs
+ *
+ * The main Jest config keeps CommonJS + `moduleNameMapper` for the
+ * bulk of the test suite; only panel tests that actually mount Ink
+ * components go through this config.
+ */
+module.exports = {
+  rootDir: '.',
+  testMatch: ['<rootDir>/test/tui-panels/**/*.test.@(ts|tsx)'],
+  testPathIgnorePatterns: ['/node_modules/'],
+  // Strip the `.js` suffix TUI sources use (Node16 ESM style) so
+  // Jest's resolver finds the `.ts` / `.tsx` sources.
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  extensionsToTreatAsEsm: ['.ts', '.tsx'],
+  transform: {
+    '^.+\\.[jt]sx?$': [
+      'ts-jest',
+      {
+        tsconfig: 'tsconfig.dev.json',
+        useESM: true,
+      },
+    ],
+  },
+  // Ink + ink-testing-library are ESM; Jest's default transformIgnorePatterns
+  // skips node_modules, so we whitelist the ones we need compiled.
+  transformIgnorePatterns: [
+    'node_modules/(?!(ink|ink-testing-library|chalk|cli-truncate|slice-ansi|string-width|strip-ansi|ansi-regex|ansi-styles|figures|is-fullwidth-code-point|emoji-regex|code-excerpt|indent-string|cli-cursor|cli-boxes|restore-cursor|widest-line|wrap-ansi|type-fest|auto-bind|yoga-layout|@alcalzone/ansi-tokenize|is-unicode-supported|is-in-ci|signal-exit|terminal-size|tagged-tag|xml-naming|uuid)/)',
+  ],
+  testEnvironment: 'node',
+  clearMocks: true,
+  // Coverage off for panel smokes — the coverage gate in the main config
+  // already covers the pure logic; panels are about interaction, not
+  // line-coverage gain.
+  collectCoverage: false,
+  // Ink keeps terminal-size polling + raw-mode listeners alive after
+  // unmount in ways that leak into Jest's worker. We `forceExit` so the
+  // suite doesn't hang for the 5 s default. Tests themselves assert all
+  // behaviour before that point; `forceExit` only affects post-pass
+  // teardown.
+  forceExit: true,
+};