@shepai/cli 1.72.7 → 1.72.8-pr216.5a2ec32

package/web/.next/standalone/src/presentation/web/CLAUDE.md

@@ -0,0 +1,128 @@
+# Web UI Development Notes
+
+## Running the UI
+
+There are two distinct ways to run the web UI. **Always test in BOTH modes.**
+
+### 1. Dev Mode (local development)
+
+```bash
+pnpm dev:web
+```
+
+- Uses `dev-server.ts` which initializes the DI container and starts Next.js in dev mode
+- Turbopack HMR enabled
+- Runs on port 3000 by default
+
+### 2. Production Mode (how users run it)
+
+```bash
+shep ui
+# or
+pnpm dev:cli ui
+```
+
+- The CLI bootstraps the DI container (`src/presentation/cli/index.ts`), then starts Next.js via `WebServerService`
+- Runs on port 4050 by default
+- This is how real users experience the UI
+- **IMPORTANT**: Always test real-time features in this mode, not just dev mode
+
+### Key Differences Between Modes
+
+| Aspect             | Dev Mode (`pnpm dev:web`)                               | Production Mode (`shep ui`)                             |
+| ------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
+| Entry point        | `dev-server.ts`                                         | `cli/index.ts` -> `ui.command.ts` -> `WebServerService` |
+| Port               | 3000                                                    | 4050                                                    |
+| DI container       | Set on `globalThis.__shepContainer` in dev-server.ts:73 | Set in cli/index.ts:76                                  |
+| WebSocket upgrades | Forwarded (HMR works)                                   | NOT forwarded in `WebServerService`                     |
+| Next.js mode       | Always dev                                              | dev when run from source, prod when installed           |
+
+## SSE / Real-Time Update Architecture
+
+```
+DB polling (500ms) -> /api/agent-events (SSE route)
+    -> Service Worker (public/agent-events-sw.js, single connection)
+        -> postMessage to all browser tabs
+            -> useAgentEvents hook (hooks/use-agent-events.ts)
+                -> AgentEventsProvider context (hooks/agent-events-provider.tsx)
+                    -> useControlCenterState (optimistic node updates via setNodes)
+                        -> React state updates -> sidebar + React Flow canvas
+```
+
+### SSE Key Files
+
+| File                                                             | Purpose                                                |
+| ---------------------------------------------------------------- | ------------------------------------------------------ |
+| `app/api/agent-events/route.ts`                                  | SSE endpoint, polls DB every 500ms, emits delta events |
+| `app/api/agent-events/health/route.ts`                           | Health check: `/api/agent-events/health`               |
+| `public/agent-events-sw.js`                                      | Service Worker: multiplexes single SSE to all tabs     |
+| `hooks/use-agent-events.ts`                                      | Client hook: registers with SW, receives events        |
+| `hooks/agent-events-provider.tsx`                                | React context wrapping `useAgentEvents`                |
+| `components/features/control-center/use-control-center-state.ts` | Processes SSE events into React Flow node updates      |
+| `components/common/feature-node/derive-feature-state.ts`         | Maps event types/phases to UI state/lifecycle          |
+
+### SSE Event Flow Details
+
+1. **SSE route** seeds a per-connection cache on first poll (no events emitted for initial state)
+2. Subsequent polls compare DB state against cache, emit only deltas
+3. **Service Worker** connects to `/api/agent-events` via EventSource on first subscriber
+4. SW broadcasts `{ type: 'notification', data }` to all tabs via `clients.matchAll()`
+5. **useControlCenterState** effect processes new events, calls `setNodes()` to update node state/lifecycle
+6. **Polling fallback** (5s interval) fetches via `fetchGraphData()` server action for active features
+
+### SSE Lifecycle Mappings
+
+The SSE route maps `SdlcLifecycle` enum -> agent graph node names -> client `FeatureLifecyclePhase`:
+
+```
+SdlcLifecycle.Started     -> 'requirements'  -> 'requirements'
+SdlcLifecycle.Analyze     -> 'analyze'       -> 'requirements'
+SdlcLifecycle.Requirements-> 'requirements'  -> 'requirements'
+SdlcLifecycle.Research    -> 'research'      -> 'research'
+SdlcLifecycle.Planning    -> 'plan'          -> 'implementation'
+SdlcLifecycle.Implementation -> 'implement'  -> 'implementation'
+SdlcLifecycle.Review      -> 'merge'         -> 'review'
+SdlcLifecycle.Maintain    -> 'maintain'      -> 'maintain'
+SdlcLifecycle.Blocked     -> 'blocked'       -> 'requirements'
+```
+
+## React Flow Rendering (CRITICAL)
+
+React Flow v12 (`@xyflow/react` ^12.10.0) has specific behaviors that affect real-time updates:
+
+- **Controlled mode**: `<ReactFlow nodes={nodes}>` passes nodes as props
+- **Internal Zustand store**: React Flow syncs props to an internal `nodeLookup` Map via `StoreUpdater`
+- **Memoized NodeWrapper**: Each node is wrapped in `memo(NodeWrapper)` which subscribes to store via `useStore(selector, shallow)`
+- **NodeWrapper gets node from store**, NOT from props directly. It does `s.nodeLookup.get(id)` with `shallow` comparison
+- **Single ReactFlowProvider**: There must be exactly ONE `ReactFlowProvider` ancestor. Multiple nested providers create separate stores, causing the outer one's `StoreUpdater` to sync nodes to a store that the inner components don't read from
+
+### Circular Update Loop (FIXED — do not reintroduce)
+
+In controlled mode, `enrichedNodes` (useMemo in FeaturesCanvas) creates new node objects every render
+(adding callbacks to `data`). StoreUpdater sees different references and emits `replace` changes via
+`onNodesChange`. If `onNodesChange` applies these 'replace' changes back to state via `applyNodeChanges`,
+it overwrites SSE-driven state updates with stale data from the previous render, AND triggers another
+`enrichedNodes` recalculation → infinite loop (110+ renders on page load).
+
+**Fix**: `onNodesChange` in `use-control-center-state.ts` filters out `replace` changes. Only `dimensions`,
+`position`, `select`, etc. are applied. StoreUpdater still syncs props to its internal store regardless —
+our state remains the source of truth.
+
+**NEVER** remove the `c.type !== 'replace'` filter from `onNodesChange`.
+
+## Testing Real-Time Updates
+
+1. Start the UI in the mode you want to test
+2. Check SSE health: `curl http://localhost:<port>/api/agent-events/health`
+3. Check SW status in browser: `navigator.serviceWorker.controller?.state` should be "activated"
+4. Trigger state changes: `pnpm dev:cli feat approve <id>` or start a new feature run
+5. Watch both **sidebar** and **canvas nodes** - they should both update
+6. Check browser console for errors
+7. Check server logs for `[SSE] emit:` messages confirming events are sent
+
+## Common Pitfalls
+
+- **No events when nothing changes**: SSE only emits deltas. If no feature state changes, no events are sent. This is correct behavior.
+- **Polling fallback dependency**: The 5s polling `useEffect` depends on a derived `hasActiveFeature` boolean (not `nodes` directly). Using `[nodes]` as a dependency would reset the interval on every node change, potentially preventing it from ever firing.
+- **Storybook mocks**: New server actions need mocks in `.storybook/mocks/app/actions/` or Storybook build breaks.
+- **`output: 'standalone'`** in next.config.ts: Production builds use standalone mode. Route handlers are bundled differently.

package/web/.next/standalone/src/presentation/web/app/actions/get-graph-data.ts

@@ -0,0 +1,12 @@
+'use server';
+
+import { getGraphData } from '@/app/(dashboard)/get-graph-data';
+
+/**
+ * Server action that fetches fresh graph nodes and edges.
+ * Used as a lightweight polling fallback for active features,
+ * avoiding full router.refresh() page re-renders.
+ */
+export async function fetchGraphData() {
+  return getGraphData();
+}

package/web/.next/standalone/src/presentation/web/app/api/agent-events/route.ts

@@ -44,13 +44,16 @@ interface CachedFeatureState {
  * Maps SdlcLifecycle values to agent graph node names so the client
  * can derive the correct FeatureLifecyclePhase via mapPhaseNameToLifecycle().
  */
-const LIFECYCLE_TO_NODE: Partial<Record<SdlcLifecycle, string>> = {
+const LIFECYCLE_TO_NODE: Record<SdlcLifecycle, string> = {
+  [SdlcLifecycle.Started]: 'requirements',
   [SdlcLifecycle.Analyze]: 'analyze',
   [SdlcLifecycle.Requirements]: 'requirements',
   [SdlcLifecycle.Research]: 'research',
   [SdlcLifecycle.Planning]: 'plan',
   [SdlcLifecycle.Implementation]: 'implement',
   [SdlcLifecycle.Review]: 'merge',
+  [SdlcLifecycle.Maintain]: 'maintain',
+  [SdlcLifecycle.Blocked]: 'blocked',
 };
 
 const STATUS_TO_EVENT: Partial<

package/web/.next/standalone/src/presentation/web/app/api/tools/[id]/install/route.ts

@@ -1,7 +1,14 @@
 import { NextResponse } from 'next/server';
 import { resolve } from '@/lib/server-container';
 import type { InstallToolUseCase } from '@shepai/core/application/use-cases/tools/install-tool.use-case';
-import { TOOL_METADATA } from '@shepai/core/infrastructure/services/tool-installer/tool-metadata';
+import type { ToolInstallationStatus } from '@shepai/core/domain/generated/output';
+
+// NOTE: Do NOT import TOOL_METADATA directly in API routes.
+// The module uses import.meta.url + fs.readdirSync to load JSON files,
+// which breaks when Turbopack bundles it (import.meta.url resolves to
+// the bundled chunk location where the tools/ directory doesn't exist).
+// Tool validation is delegated to the use case via the DI container,
+// where the module loads correctly in the Node.js CLI bootstrap context.
 
 export async function POST(
   _request: Request,
@@ -9,13 +16,14 @@ export async function POST(
 ): Promise<NextResponse> {
   const { id } = await params;
 
-  if (!TOOL_METADATA[id]) {
-    return NextResponse.json({ error: 'Tool not found' }, { status: 404 });
-  }
-
   try {
     const useCase = resolve<InstallToolUseCase>('InstallToolUseCase');
-    const status = await useCase.execute(id);
+    const status: ToolInstallationStatus = await useCase.execute(id);
+
+    if (status.status === 'error') {
+      return NextResponse.json({ error: status.errorMessage }, { status: 500 });
+    }
+
     return NextResponse.json({ status });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : 'Failed to install tool';

package/web/.next/standalone/src/presentation/web/app/api/tools/[id]/install/stream/route.ts

@@ -0,0 +1,42 @@
+import { resolve } from '@/lib/server-container';
+import type { InstallToolUseCase } from '@shepai/core/application/use-cases/tools/install-tool.use-case';
+
+// Force dynamic — SSE streams must never be statically optimized or cached
+export const dynamic = 'force-dynamic';
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<Response> {
+  const { id } = await params;
+  const useCase = resolve<InstallToolUseCase>('InstallToolUseCase');
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        const status = await useCase.execute(id, (chunk: string) => {
+          controller.enqueue(encoder.encode(`data: ${chunk.replace(/\n/g, '\ndata: ')}\n\n`));
+        });
+        controller.enqueue(encoder.encode(`event: done\ndata: ${JSON.stringify(status)}\n\n`));
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Installation failed';
+        controller.enqueue(
+          encoder.encode(
+            `event: done\ndata: ${JSON.stringify({ status: 'error', toolName: id, errorMessage: message })}\n\n`
+          )
+        );
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}

package/web/.next/standalone/src/presentation/web/components/common/base-drawer/base-drawer.tsx

@@ -12,6 +12,8 @@ import {
   DrawerHeader,
   DrawerFooter,
   DrawerOverlay,
+  DrawerTitle,
+  DrawerDescription,
 } from '@/components/ui/drawer';
 import { Separator } from '@/components/ui/separator';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
@@ -36,6 +38,7 @@ export interface BaseDrawerProps extends VariantProps<typeof drawerVariants> {
   modal?: boolean;
   /** When true, clicking anywhere outside the drawer closes it, ignoring `data-no-drawer-close` guards. */
   dismissOnOutsideClick?: boolean;
+  title?: string;
   header?: React.ReactNode;
   children: React.ReactNode;
   footer?: React.ReactNode;
@@ -49,6 +52,7 @@ export function BaseDrawer({
   onClose,
   modal = false,
   dismissOnOutsideClick = false,
+  title = 'Drawer',
   size,
   header,
   children,
@@ -101,8 +105,16 @@ export function BaseDrawer({
         showCloseButton={false}
         className={cn(drawerVariants({ size }), className)}
         data-testid={testId}
-        onInteractOutside={(e) => e.preventDefault()}
+        onInteractOutside={modal ? undefined : (e) => e.preventDefault()}
       >
+        {/* Visually hidden title & description required by Radix Dialog for accessibility */}
+        <DrawerTitle asChild>
+          <span className="sr-only">{title}</span>
+        </DrawerTitle>
+        <DrawerDescription asChild>
+          <span className="sr-only">{title}</span>
+        </DrawerDescription>
+
         {/* Close button */}
         <button
           type="button"

package/web/.next/standalone/src/presentation/web/components/common/feature-node/derive-feature-state.ts

@@ -120,6 +120,8 @@ const phaseNameToLifecycle: Record<string, FeatureLifecyclePhase> = {
   plan: 'implementation',
   implement: 'implementation',
   merge: 'review',
+  maintain: 'maintain',
+  blocked: 'requirements',
 };
 
 export function mapPhaseNameToLifecycle(

package/web/.next/standalone/src/presentation/web/components/features/control-center/use-control-center-state.ts

@@ -15,6 +15,7 @@ import {
 import { deleteFeature } from '@/app/actions/delete-feature';
 import { addRepository } from '@/app/actions/add-repository';
 import { deleteRepository } from '@/app/actions/delete-repository';
+import { fetchGraphData } from '@/app/actions/get-graph-data';
 import { useAgentEventsContext } from '@/hooks/agent-events-provider';
 import { useSoundAction } from '@/hooks/use-sound-action';
 import {
@@ -206,6 +207,7 @@ export function useControlCenterState(
           if (node.type !== 'featureNode') return node;
           const data = node.data as FeatureNodeData;
           if (data.featureId !== event.featureId) return node;
+
           return {
             ...node,
             data: {
@@ -219,8 +221,87 @@ export function useControlCenterState(
     }
   }, [events]);
 
+  // Lightweight server-action polling fallback: fetches fresh graph data every 5s
+  // when any feature is in an active state. This avoids full router.refresh() while
+  // ensuring the UI stays in sync even if SSE events are missed.
+  //
+  // We derive a stable boolean so the interval isn't torn down on every node change.
+  const hasActiveFeature = nodes.some((n) => {
+    if (n.type !== 'featureNode') return false;
+    const data = n.data as FeatureNodeData;
+    return (
+      data.state === 'running' || data.state === 'action-required' || data.state === 'creating'
+    );
+  });
+
+  useEffect(() => {
+    if (!hasActiveFeature) return;
+
+    const interval = setInterval(async () => {
+      try {
+        const { nodes: serverNodes } = await fetchGraphData();
+        setNodes((currentNodes) => {
+          const serverById = new Map(serverNodes.map((n) => [n.id, n]));
+          let changed = false;
+
+          const merged = currentNodes.map((node) => {
+            const serverNode = serverById.get(node.id);
+            if (!serverNode || node.type !== 'featureNode') return node;
+            const currentData = node.data as FeatureNodeData;
+            const serverData = serverNode.data as FeatureNodeData;
+
+            // Only update if server data has different state or lifecycle
+            if (
+              currentData.state === serverData.state &&
+              currentData.lifecycle === serverData.lifecycle
+            ) {
+              return node;
+            }
+
+            changed = true;
+            return {
+              ...node,
+              data: {
+                ...currentData,
+                state: serverData.state,
+                lifecycle: serverData.lifecycle,
+                progress: serverData.progress,
+                ...(serverData.errorMessage && { errorMessage: serverData.errorMessage }),
+                ...(serverData.runtime && { runtime: serverData.runtime }),
+                ...(serverData.agentType && { agentType: serverData.agentType }),
+                ...(serverData.pr && { pr: serverData.pr }),
+                ...(serverData.blockedBy && { blockedBy: serverData.blockedBy }),
+              },
+            };
+          });
+
+          // Add any new server nodes that don't exist on client
+          const clientIds = new Set(currentNodes.map((n) => n.id));
+          const newNodes = serverNodes.filter((n) => !clientIds.has(n.id));
+          if (newNodes.length > 0) {
+            changed = true;
+          }
+
+          return changed || newNodes.length > 0 ? [...merged, ...newNodes] : currentNodes;
+        });
+      } catch {
+        // Silently ignore polling errors — SSE is the primary mechanism
+      }
+    }, 5_000);
+
+    return () => clearInterval(interval);
+  }, [hasActiveFeature]);
+
   const onNodesChange = useCallback((changes: NodeChange<CanvasNodeType>[]) => {
-    setNodes((ns) => applyNodeChanges(changes, ns));
+    // Filter out 'replace' changes — in controlled mode these come from
+    // React Flow's StoreUpdater syncing the nodes prop back into state.
+    // Applying them creates a circular update loop (nodes → enrichedNodes →
+    // StoreUpdater → onNodesChange → setNodes → nodes → …) that both causes
+    // excessive re-renders and overwrites SSE-driven state changes with stale data.
+    const applicable = changes.filter((c) => c.type !== 'replace');
+    if (applicable.length > 0) {
+      setNodes((ns) => applyNodeChanges(applicable, ns));
+    }
   }, []);
 
   const handleConnect = useCallback(

package/web/.next/standalone/src/presentation/web/components/features/features-canvas/features-canvas.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useCallback, useMemo } from 'react';
-import { ReactFlow, Background, Controls, ReactFlowProvider } from '@xyflow/react';
+import { ReactFlow, Background, Controls } from '@xyflow/react';
 import type { Connection, Edge, NodeChange } from '@xyflow/react';
 import { Plus } from 'lucide-react';
 import { Button } from '@/components/ui/button';
@@ -163,28 +163,26 @@ export function FeaturesCanvas({
       data-no-drawer-close
       className="pointer-events-auto h-full w-full"
     >
-      <ReactFlowProvider>
-        <ReactFlow
-          nodes={enrichedNodes}
-          edges={edges}
-          nodeTypes={nodeTypes}
-          edgeTypes={edgeTypes}
-          isValidConnection={isValidConnection}
-          onConnect={onConnect}
-          onNodesChange={onNodesChange}
-          onNodeClick={onNodeClick}
-          onPaneClick={onPaneClick}
-          onMoveStart={onCanvasDrag}
-          defaultViewport={{ x: 30, y: 30, zoom: 0.85 }}
-          nodesDraggable={false}
-          nodesConnectable={false}
-          elementsSelectable={false}
-        >
-          <Background />
-          <Controls />
-          {toolbar}
-        </ReactFlow>
-      </ReactFlowProvider>
+      <ReactFlow
+        nodes={enrichedNodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
+        isValidConnection={isValidConnection}
+        onConnect={onConnect}
+        onNodesChange={onNodesChange}
+        onNodeClick={onNodeClick}
+        onPaneClick={onPaneClick}
+        onMoveStart={onCanvasDrag}
+        defaultViewport={{ x: 30, y: 30, zoom: 0.85 }}
+        nodesDraggable={false}
+        nodesConnectable={false}
+        elementsSelectable={false}
+      >
+        <Background />
+        <Controls />
+        {toolbar}
+      </ReactFlow>
     </div>
   );
 }

package/web/.next/standalone/src/presentation/web/components/features/index.ts

@@ -1,4 +1,4 @@
 export { FeaturesCanvas, type FeaturesCanvasProps } from './features-canvas';
 export { ToolsPageClient, type ToolsPageClientProps } from './tools';
 export { ToolCard, type ToolCardProps } from './tools';
-export { InstallInstructions, type InstallInstructionsProps } from './tools';
+export { ToolDetailDrawer, type ToolDetailDrawerProps } from './tools';

package/web/.next/standalone/src/presentation/web/components/features/tools/index.ts

@@ -1,3 +1,3 @@
 export { ToolsPageClient, type ToolsPageClientProps } from './tools-page-client';
 export { ToolCard, type ToolCardProps } from './tool-card';
-export { InstallInstructions, type InstallInstructionsProps } from './install-instructions';
+export { ToolDetailDrawer, type ToolDetailDrawerProps } from './tool-detail-drawer';

package/web/.next/standalone/src/presentation/web/components/features/tools/tool-card.stories.tsx

@@ -16,6 +16,9 @@ const installedIdeTool: ToolItem = {
   documentationUrl: 'https://cursor.sh',
   installCommand: 'brew install --cask cursor',
   status: { status: 'available', toolName: 'cursor' },
+  author: 'Anysphere',
+  website: 'https://cursor.com',
+  platforms: ['linux', 'darwin', 'win32'],
 };
 
 const installedNoLaunchTool: ToolItem = {
@@ -32,6 +35,9 @@ const installedNoLaunchTool: ToolItem = {
   documentationUrl: 'https://claude.ai',
   installCommand: 'npm install -g @anthropic-ai/claude-code',
   status: { status: 'available', toolName: 'claude-code' },
+  author: 'Anthropic',
+  website: 'https://claude.ai/code',
+  platforms: ['linux', 'darwin'],
 };
 
 const missingAutoInstallTool: ToolItem = {
@@ -48,6 +54,9 @@ const missingAutoInstallTool: ToolItem = {
   documentationUrl: 'https://aider.chat',
   installCommand: 'pip install aider-chat',
   status: { status: 'missing', toolName: 'aider' },
+  author: 'Paul Gauthier',
+  website: 'https://aider.chat',
+  platforms: ['linux', 'darwin', 'win32'],
 };
 
 const missingManualTool: ToolItem = {
@@ -64,6 +73,9 @@ const missingManualTool: ToolItem = {
   documentationUrl: 'https://code.visualstudio.com',
   installCommand: 'brew install --cask visual-studio-code',
   status: { status: 'missing', toolName: 'vscode' },
+  author: 'Microsoft',
+  website: 'https://code.visualstudio.com',
+  platforms: ['linux', 'darwin', 'win32'],
 };
 
 const cliAgentTool: ToolItem = {
@@ -80,6 +92,9 @@ const cliAgentTool: ToolItem = {
   documentationUrl: 'https://cursor.sh',
   installCommand: 'curl https://cursor.com/install -fsS | bash',
   status: { status: 'available', toolName: 'cursor-cli' },
+  author: 'Anysphere',
+  website: 'https://cursor.com',
+  platforms: ['linux', 'darwin', 'win32'],
 };
 
 const vcsTool: ToolItem = {
@@ -96,6 +111,9 @@ const vcsTool: ToolItem = {
   documentationUrl: 'https://cli.github.com/manual/',
   installCommand: 'brew install gh',
   status: { status: 'available', toolName: 'gh' },
+  author: 'GitHub',
+  website: 'https://cli.github.com',
+  platforms: ['linux', 'darwin', 'win32'],
 };
 
 const meta: Meta<typeof ToolCard> = {