@vectorasystems/cli 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorasystems/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Vectora CLI — AI-powered project orchestration",
   "type": "module",
   "bin": {

package/src/lib/constants.js

@@ -1,7 +1,7 @@
 // @vectora/cli — constants
 // Inlined from @vectora/engine to avoid dependency in API-connected mode.
 
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.3';
 
 export const BRAND = {
   name: 'VECTORA',

package/src/tui/App.js

@@ -1,9 +1,13 @@
-// TUI root — Ink application
+// TUI root — full interactive Ink application
 import React, { useState, useEffect } from 'react';
 import { Box, Text, useApp, useInput } from 'ink';
 import { Header } from './components/Header.js';
 import { ProjectList } from './components/ProjectList.js';
-import { PhaseTimeline } from './components/PhaseTimeline.js';
+import { ActionMenu } from './components/ActionMenu.js';
+import { ChatWindow } from './components/ChatWindow.js';
+import { PhaseRunner } from './components/PhaseRunner.js';
+import { ArtifactBrowser } from './components/ArtifactBrowser.js';
+import { CreateProjectForm } from './components/CreateProjectForm.js';
 import { StatusBar } from './components/StatusBar.js';
 import { useProject } from './hooks/useProject.js';
 import { checkHealth, getMe } from '../lib/api-client.js';
@@ -13,10 +17,12 @@ export default function App() {
   const { exit } = useApp();
   const [connected, setConnected] = useState(true);
   const [orgName, setOrgName] = useState(null);
-  const [view, setView] = useState('projects'); // 'projects' | 'detail'
-  const { project, phases, artifacts, loading, refresh, projectId } = useProject();
+  const [view, setView] = useState('projects'); // projects|create|detail|chat|run|artifacts
+  const { project, phases, loading, refresh, projectId } = useProject();
+
+  // Augment project with phases array for PhaseRunner filtering
+  const projectWithPhases = project ? { ...project, phases } : null;
 
-  // Check connectivity and auth on mount
   useEffect(() => {
     checkHealth().then((h) => setConnected(h.status !== 'unreachable'));
     getCredentials().then(async (creds) => {
@@ -29,45 +35,99 @@ export default function App() {
     });
   }, []);
 
-  // Keyboard shortcuts
+  // Global keyboard shortcuts
   useInput((input, key) => {
     if (input === 'q' || (key.ctrl && input === 'c')) {
       exit();
+      return;
     }
-    if (input === 'r') {
-      refresh();
-    }
-    if (input === 'p') {
-      setView('projects');
+
+    if (view === 'projects') {
+      if (input === 'n') setView('create');
+      if (input === 'r') refresh();
     }
-    if (key.escape) {
-      setView('projects');
+
+    if (view === 'detail') {
+      if (input === 'c') setView('chat');
+      if (input === 'r') setView('run');
+      if (input === 'a') setView('artifacts');
+      if (key.escape) setView('projects');
     }
   });
 
+  function handleProjectSelect() {
+    refresh();
+    setView('detail');
+  }
+
+  function handleActionSelect(action) {
+    if (action === 'chat') setView('chat');
+    else if (action === 'run') setView('run');
+    else if (action === 'artifacts') setView('artifacts');
+    else if (action === 'back') setView('projects');
+  }
+
+  function handleProjectCreated() {
+    refresh();
+    setView('detail');
+  }
+
+  function renderView() {
+    if (loading && view !== 'create') {
+      return React.createElement(Text, { dimColor: true }, 'Loading…');
+    }
+
+    switch (view) {
+      case 'projects':
+        return React.createElement(ProjectList, { onSelect: handleProjectSelect });
+
+      case 'create':
+        return React.createElement(CreateProjectForm, {
+          onCreated: handleProjectCreated,
+          onCancel: () => setView('projects'),
+        });
+
+      case 'detail':
+        return React.createElement(ActionMenu, {
+          project: projectWithPhases,
+          onSelect: handleActionSelect,
+        });
+
+      case 'chat':
+        return projectId
+          ? React.createElement(ChatWindow, {
+              projectId,
+              onBack: () => setView('detail'),
+            })
+          : React.createElement(Text, { color: 'red' }, 'No project selected');
+
+      case 'run':
+        return projectId
+          ? React.createElement(PhaseRunner, {
+              project: projectWithPhases,
+              onBack: () => setView('detail'),
+              onArtifacts: () => setView('artifacts'),
+            })
+          : React.createElement(Text, { color: 'red' }, 'No project selected');
+
+      case 'artifacts':
+        return projectId
+          ? React.createElement(ArtifactBrowser, {
+              projectId,
+              onBack: () => setView('detail'),
+            })
+          : React.createElement(Text, { color: 'red' }, 'No project selected');
+
+      default:
+        return null;
+    }
+  }
+
   return React.createElement(Box, { flexDirection: 'column', padding: 1 },
     React.createElement(Header, { connected }),
-
-    loading
-      ? React.createElement(Text, { dimColor: true }, 'Loading...')
-      : view === 'projects'
-        ? React.createElement(ProjectList, {
-            onSelect: (id) => {
-              setView('detail');
-              refresh();
-            },
-          })
-        : React.createElement(Box, { flexDirection: 'column', gap: 1 },
-            project && React.createElement(Box, { flexDirection: 'column' },
-              React.createElement(Text, { bold: true, color: 'cyan' }, project.name),
-              React.createElement(Text, { dimColor: true }, `${project.orchestratorId} · ${project.status}`),
-            ),
-            React.createElement(PhaseTimeline, { phases }),
-            artifacts.length > 0 && React.createElement(Text, { dimColor: true },
-              `${artifacts.length} artifact(s)`
-            ),
-          ),
-
-    React.createElement(StatusBar, { project, orgName, connected }),
+    React.createElement(Box, { marginTop: 1 },
+      renderView(),
+    ),
+    React.createElement(StatusBar, { project, orgName, connected, view }),
   );
 }

package/src/tui/components/ActionMenu.js

@@ -0,0 +1,30 @@
+// TUI component — project action menu (detail view)
+import React from 'react';
+import { Box, Text } from 'ink';
+import SelectInput from 'ink-select-input';
+
+const ITEMS = [
+  { label: '💬  Idea Chat', value: 'chat', hint: 'Refine your idea with AI' },
+  { label: '▶   Run Phase', value: 'run', hint: 'Execute a phase' },
+  { label: '📦  Artifacts', value: 'artifacts', hint: 'Browse & download outputs' },
+  { label: '←   Back', value: 'back', hint: 'Return to project list' },
+];
+
+export function ActionMenu({ project, onSelect }) {
+  if (!project) return null;
+
+  return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+    React.createElement(Box, { flexDirection: 'column' },
+      React.createElement(Text, { bold: true, color: 'cyan' }, project.name),
+      React.createElement(Text, { dimColor: true },
+        `${project.orchestratorId?.toUpperCase() ?? 'FORGE'} · ${project.status}`
+      ),
+    ),
+    React.createElement(Box, { borderStyle: 'single', borderColor: 'gray', paddingX: 1, flexDirection: 'column' },
+      React.createElement(SelectInput, {
+        items: ITEMS,
+        onSelect: (item) => onSelect(item.value),
+      }),
+    ),
+  );
+}

package/src/tui/components/ArtifactBrowser.js

@@ -0,0 +1,96 @@
+// TUI component — artifact browser with download
+import React, { useState, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import SelectInput from 'ink-select-input';
+import Spinner from 'ink-spinner';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { getProjectArtifacts, getArtifactDownloadUrl } from '../../lib/api-client.js';
+
+const TYPE_FILENAME = {
+  handoff: 'VECTORA.md',
+  prd: 'PRD.md',
+  scope: 'SCOPE.md',
+  roadmap: 'ROADMAP.md',
+  analysis: 'ANALYSIS.json',
+  validation: 'VALIDATION.json',
+  feedback: 'FEEDBACK.json',
+};
+
+function formatDate(iso) {
+  return new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
+}
+
+export function ArtifactBrowser({ projectId, onBack }) {
+  const [artifacts, setArtifacts] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [downloading, setDownloading] = useState(false);
+  const [savedPath, setSavedPath] = useState(null);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    getProjectArtifacts(projectId)
+      .then((list) => { setArtifacts(list); setLoading(false); })
+      .catch((err) => { setError(err.message); setLoading(false); });
+  }, [projectId]);
+
+  useInput((_ch, key) => {
+    if (key.escape && !downloading) onBack();
+  });
+
+  async function handleSelect(item) {
+    setDownloading(true);
+    setSavedPath(null);
+    setError(null);
+    try {
+      const { url, filename } = await getArtifactDownloadUrl(item.value);
+      const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+      if (!res.ok) throw new Error(`Download failed: HTTP ${res.status}`);
+      const buffer = Buffer.from(await res.arrayBuffer());
+      const outPath = resolve(filename);
+      await writeFile(outPath, buffer);
+      setSavedPath(outPath);
+    } catch (err) {
+      setError(err.message ?? 'Download failed');
+    } finally {
+      setDownloading(false);
+    }
+  }
+
+  if (loading) {
+    return React.createElement(Box, { gap: 1 },
+      React.createElement(Spinner, { type: 'dots' }),
+      React.createElement(Text, null, ' Loading artifacts…'),
+    );
+  }
+
+  if (downloading) {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'cyan' }, '📦  Artifacts'),
+      React.createElement(Box, { gap: 1 },
+        React.createElement(Spinner, { type: 'dots' }),
+        React.createElement(Text, null, ' Downloading…'),
+      ),
+    );
+  }
+
+  const items = artifacts.map((a) => ({
+    label: `${a.type.padEnd(16)} ${formatDate(a.createdAt)}`,
+    value: a.id,
+  }));
+
+  return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+    React.createElement(Text, { bold: true, color: 'cyan' }, '📦  Artifacts'),
+
+    savedPath && React.createElement(Text, { color: 'green' }, `✓ Saved → ${savedPath}`),
+    error && React.createElement(Text, { color: 'red' }, `✗ ${error}`),
+
+    artifacts.length === 0
+      ? React.createElement(Text, { dimColor: true }, 'No artifacts yet. Run a phase first.')
+      : React.createElement(Box, { borderStyle: 'single', borderColor: 'gray', paddingX: 1 },
+          React.createElement(SelectInput, { items, onSelect: handleSelect }),
+        ),
+
+    React.createElement(Text, { dimColor: true }, 'Enter to download · Esc to go back'),
+  );
+}

package/src/tui/components/ChatWindow.js

@@ -0,0 +1,84 @@
+// TUI component — idea chat view with streaming AI responses
+import React, { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import TextInput from 'ink-text-input';
+import Spinner from 'ink-spinner';
+import { useChat } from '../hooks/useChat.js';
+
+function ReadinessBar({ value }) {
+  if (value == null) return null;
+  const pct = Math.min(100, Math.max(0, value));
+  const filled = Math.round(pct / 10);
+  const bar = '▓'.repeat(filled) + '░'.repeat(10 - filled);
+  const color = pct >= 80 ? 'green' : pct >= 50 ? 'yellow' : 'gray';
+  return React.createElement(Box, { gap: 1 },
+    React.createElement(Text, { dimColor: true }, 'Readiness'),
+    React.createElement(Text, { color }, bar),
+    React.createElement(Text, { dimColor: true }, `${pct}%`),
+  );
+}
+
+export function ChatWindow({ projectId, onBack }) {
+  const { messages, streaming, readiness, error, sendMessage } = useChat(projectId);
+  const [input, setInput] = useState('');
+
+  useInput((ch, key) => {
+    if (key.escape && !streaming) onBack();
+  });
+
+  const visibleMessages = messages.slice(-8); // show last 8 messages
+
+  return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+    React.createElement(Text, { bold: true, color: 'cyan' }, '💬  Idea Chat'),
+
+    // Message history
+    React.createElement(Box, {
+      flexDirection: 'column',
+      borderStyle: 'single',
+      borderColor: 'gray',
+      paddingX: 1,
+      minHeight: 10,
+    },
+      visibleMessages.length === 0
+        ? React.createElement(Text, { dimColor: true }, 'Start typing to chat with your AI product consultant…')
+        : visibleMessages.map((msg, i) =>
+            React.createElement(Box, { key: i, flexDirection: 'column', marginBottom: 0 },
+              React.createElement(Text, { color: msg.role === 'user' ? 'cyan' : 'white', bold: msg.role === 'user' },
+                msg.role === 'user' ? '› ' : '  ',
+                msg.text || (streaming && i === visibleMessages.length - 1
+                  ? React.createElement(Spinner, { type: 'dots' })
+                  : '…')
+              ),
+            )
+          ),
+    ),
+
+    // Readiness bar
+    React.createElement(ReadinessBar, { value: readiness }),
+
+    // Error
+    error && React.createElement(Text, { color: 'red' }, `Error: ${error}`),
+
+    // Input
+    React.createElement(Box, { borderStyle: 'single', borderColor: streaming ? 'gray' : 'cyan', paddingX: 1 },
+      React.createElement(Box, null,
+        React.createElement(Text, { color: streaming ? 'gray' : 'cyan' }, '› '),
+        streaming
+          ? React.createElement(Text, { dimColor: true }, 'AI is responding…')
+          : React.createElement(TextInput, {
+              value: input,
+              onChange: setInput,
+              placeholder: 'Describe your idea…',
+              onSubmit: (val) => {
+                if (val.trim()) {
+                  sendMessage(val.trim());
+                  setInput('');
+                }
+              },
+            }),
+      ),
+    ),
+
+    React.createElement(Text, { dimColor: true }, streaming ? 'Wait for response…' : 'Enter to send · Esc to go back'),
+  );
+}

package/src/tui/components/CreateProjectForm.js

@@ -0,0 +1,81 @@
+// TUI component — create project form (name → orchestrator → submit)
+import React, { useState } from 'react';
+import { Box, Text } from 'ink';
+import TextInput from 'ink-text-input';
+import SelectInput from 'ink-select-input';
+import { createProject, getWorkspaces } from '../../lib/api-client.js';
+import { getConfigValue, setConfigValue } from '../../lib/config-store.js';
+
+const ORCHESTRATORS = [
+  { label: 'Forge  — Idea → MVP pipeline', value: 'forge' },
+  { label: 'Temper — Post-MVP → Scale pipeline', value: 'temper' },
+];
+
+export function CreateProjectForm({ onCreated, onCancel }) {
+  const [stage, setStage] = useState('name'); // 'name' | 'orchestrator' | 'creating'
+  const [name, setName] = useState('');
+  const [error, setError] = useState(null);
+
+  async function handleOrchestratorSelect(item) {
+    setStage('creating');
+    setError(null);
+    try {
+      let workspaceId = getConfigValue('defaultWorkspace');
+      if (!workspaceId) {
+        const workspaces = await getWorkspaces();
+        if (!workspaces.length) {
+          setError('No workspaces found.');
+          setStage('orchestrator');
+          return;
+        }
+        workspaceId = workspaces[0].id;
+        setConfigValue('defaultWorkspace', workspaceId);
+      }
+      const project = await createProject({ name: name.trim(), workspaceId, orchestratorId: item.value });
+      setConfigValue('defaultProject', project.id);
+      onCreated(project);
+    } catch (err) {
+      setError(err.message ?? 'Failed to create project');
+      setStage('orchestrator');
+    }
+  }
+
+  if (stage === 'name') {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'cyan' }, 'New Project'),
+      React.createElement(Box, { borderStyle: 'single', borderColor: 'gray', paddingX: 1 },
+        React.createElement(Box, null,
+          React.createElement(Text, { dimColor: true }, 'Name: '),
+          React.createElement(TextInput, {
+            value: name,
+            onChange: setName,
+            placeholder: 'My App…',
+            onSubmit: (val) => {
+              if (val.trim()) setStage('orchestrator');
+            },
+          }),
+        ),
+      ),
+      React.createElement(Text, { dimColor: true }, 'Enter to continue · Esc to cancel'),
+    );
+  }
+
+  if (stage === 'orchestrator') {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'cyan' }, `New Project: ${name}`),
+      error && React.createElement(Text, { color: 'red' }, error),
+      React.createElement(Box, { borderStyle: 'single', borderColor: 'gray', paddingX: 1 },
+        React.createElement(SelectInput, {
+          items: ORCHESTRATORS,
+          onSelect: handleOrchestratorSelect,
+        }),
+      ),
+    );
+  }
+
+  // creating
+  return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+    React.createElement(Text, { color: 'cyan' }, `Creating "${name}"…`),
+    error && React.createElement(Text, { color: 'red' }, error),
+  );
+}

package/src/tui/components/PhaseRunner.js

@@ -0,0 +1,103 @@
+// TUI component — phase selection + live execution progress
+import React, { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import SelectInput from 'ink-select-input';
+import Spinner from 'ink-spinner';
+import { usePhaseRun } from '../hooks/usePhaseRun.js';
+import { FORGE_PHASES, TEMPER_PHASES } from '../../lib/constants.js';
+
+function ProgressBar({ pct }) {
+  const filled = Math.round(pct / 5); // 20 chars wide
+  const bar = '█'.repeat(filled) + '░'.repeat(20 - filled);
+  return React.createElement(Box, { gap: 1 },
+    React.createElement(Text, { color: 'cyan' }, bar),
+    React.createElement(Text, { dimColor: true }, `${pct}%`),
+  );
+}
+
+export function PhaseRunner({ project, onBack, onArtifacts }) {
+  const [selected, setSelected] = useState(null);
+  const { status, step, pct, artifactCount, error, run, reset } = usePhaseRun(project?.id);
+
+  const orchestratorId = project?.orchestratorId ?? 'forge';
+  const phaseList = orchestratorId === 'temper' ? TEMPER_PHASES : FORGE_PHASES;
+
+  // Build completed phase set for filtering
+  const completedPhases = new Set(
+    (project?.phases ?? [])
+      .filter((p) => p.status === 'completed')
+      .map((p) => p.phaseType)
+  );
+
+  const items = phaseList.map((p) => ({
+    label: completedPhases.has(p) ? `✓ ${p}` : `  ${p}`,
+    value: p,
+  }));
+
+  useInput((_ch, key) => {
+    if (key.escape) {
+      if (status === 'idle' || status === 'completed' || status === 'failed') {
+        reset();
+        setSelected(null);
+        onBack();
+      }
+    }
+    if (key.escape && status === 'completed' || status === 'failed') {
+      reset();
+      setSelected(null);
+    }
+  });
+
+  // Selecting state
+  if (!selected || status === 'idle') {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'cyan' }, '▶  Run Phase'),
+      React.createElement(Text, { dimColor: true }, `Orchestrator: ${orchestratorId.toUpperCase()}`),
+      React.createElement(Box, { borderStyle: 'single', borderColor: 'gray', paddingX: 1 },
+        React.createElement(SelectInput, {
+          items,
+          onSelect: (item) => {
+            setSelected(item.value);
+            run(item.value);
+          },
+        }),
+      ),
+      React.createElement(Text, { dimColor: true }, 'Enter to run · Esc to go back'),
+    );
+  }
+
+  // Running state
+  if (status === 'running') {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'cyan' }, `▶  ${selected}`),
+      React.createElement(Box, { gap: 1 },
+        React.createElement(Spinner, { type: 'dots' }),
+        React.createElement(Text, null, ` ${step}`),
+      ),
+      React.createElement(ProgressBar, { pct }),
+      React.createElement(Text, { dimColor: true }, 'Running… please wait'),
+    );
+  }
+
+  // Completed state
+  if (status === 'completed') {
+    return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+      React.createElement(Text, { bold: true, color: 'green' }, `✓  ${selected} complete`),
+      React.createElement(ProgressBar, { pct: 100 }),
+      artifactCount > 0 && React.createElement(Text, null,
+        `${artifactCount} artifact(s) generated`,
+      ),
+      React.createElement(Box, { gap: 2, marginTop: 1 },
+        artifactCount > 0 && React.createElement(Text, { color: 'cyan' }, `'a' → browse artifacts`),
+        React.createElement(Text, { dimColor: true }, `Esc → back`),
+      ),
+    );
+  }
+
+  // Failed state
+  return React.createElement(Box, { flexDirection: 'column', gap: 1 },
+    React.createElement(Text, { bold: true, color: 'red' }, `✗  ${selected} failed`),
+    React.createElement(Text, { color: 'red' }, error ?? 'Unknown error'),
+    React.createElement(Text, { dimColor: true }, 'Esc to go back'),
+  );
+}

package/src/tui/components/StatusBar.js

@@ -1,19 +1,30 @@
-// TUI component — bottom status bar
+// TUI component — bottom status bar with context-aware shortcuts
 import React from 'react';
 import { Box, Text } from 'ink';
 
-export function StatusBar({ project, orgName, connected }) {
-  return React.createElement(Box, { marginTop: 1 },
+const HINTS = {
+  projects: 'n: new project  q: quit',
+  create:   'Esc: cancel',
+  detail:   'c: chat  r: run  a: artifacts  Esc: back',
+  chat:     'Enter: send  Esc: back',
+  run:      'Enter: select  Esc: back',
+  artifacts:'Enter: download  Esc: back',
+};
+
+export function StatusBar({ project, orgName, connected, view }) {
+  const hint = HINTS[view] ?? 'q: quit';
+
+  return React.createElement(Box, { flexDirection: 'column', marginTop: 1 },
     React.createElement(Text, { dimColor: true }, '─'.repeat(60)),
     React.createElement(Box, { gap: 2 },
       project
-        ? React.createElement(Text, { dimColor: true }, `Project: ${project.name}`)
-        : React.createElement(Text, { dimColor: true }, 'No project selected'),
-      orgName && React.createElement(Text, { dimColor: true }, `Org: ${orgName}`),
+        ? React.createElement(Text, { dimColor: true }, `${project.name}`)
+        : React.createElement(Text, { dimColor: true }, 'No project'),
+      orgName && React.createElement(Text, { dimColor: true }, `· ${orgName}`),
       React.createElement(Text, { color: connected ? 'green' : 'red' },
-        connected ? '● Online' : '● Offline'
+        connected ? '● ' : '● '
       ),
-      React.createElement(Text, { dimColor: true }, 'q: quit'),
+      React.createElement(Text, { dimColor: true }, hint),
     ),
   );
 }

package/src/tui/hooks/useChat.js

@@ -0,0 +1,52 @@
+// TUI hook — idea chat state + SSE streaming
+import { useState, useCallback } from 'react';
+import { streamIdeaChat } from '../../lib/sse-client.js';
+import { getConfig } from '../../lib/config-store.js';
+import { requireToken } from '../../lib/auth-store.js';
+
+export function useChat(projectId) {
+  const [messages, setMessages] = useState([]);
+  const [streaming, setStreaming] = useState(false);
+  const [readiness, setReadiness] = useState(null);
+  const [error, setError] = useState(null);
+
+  const sendMessage = useCallback(async (text) => {
+    if (streaming || !projectId) return;
+    setError(null);
+    setStreaming(true);
+
+    // Append user message + empty assistant placeholder
+    setMessages((prev) => [
+      ...prev,
+      { role: 'user', text },
+      { role: 'assistant', text: '' },
+    ]);
+
+    try {
+      const { apiUrl } = getConfig();
+      const token = await requireToken();
+
+      for await (const { event, data } of streamIdeaChat(apiUrl, token, projectId, text)) {
+        if (event === 'chat:delta') {
+          setMessages((prev) => {
+            const copy = [...prev];
+            const last = copy[copy.length - 1];
+            copy[copy.length - 1] = { ...last, text: last.text + (data.text ?? '') };
+            return copy;
+          });
+        } else if (event === 'chat:complete') {
+          if (data.readiness != null) setReadiness(data.readiness);
+          setStreaming(false);
+        } else if (event === 'chat:error') {
+          setError(data.error ?? 'AI error');
+          setStreaming(false);
+        }
+      }
+    } catch (err) {
+      setError(err.message ?? 'Connection error');
+      setStreaming(false);
+    }
+  }, [projectId, streaming]);
+
+  return { messages, streaming, readiness, error, sendMessage };
+}

package/src/tui/hooks/usePhaseRun.js

@@ -0,0 +1,79 @@
+// TUI hook — phase execution + SSE progress streaming
+import { useState, useCallback } from 'react';
+import { runPhase } from '../../lib/api-client.js';
+import { streamPhaseProgress } from '../../lib/sse-client.js';
+import { getConfig } from '../../lib/config-store.js';
+import { requireToken } from '../../lib/auth-store.js';
+import { collectWorkspaceSnapshot } from '../../lib/workspace-scanner.js';
+
+export function usePhaseRun(projectId) {
+  const [status, setStatus] = useState('idle'); // idle | running | completed | failed
+  const [step, setStep] = useState('');
+  const [pct, setPct] = useState(0);
+  const [artifactCount, setArtifactCount] = useState(0);
+  const [error, setError] = useState(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setStep('');
+    setPct(0);
+    setArtifactCount(0);
+    setError(null);
+  }, []);
+
+  const run = useCallback(async (phase) => {
+    if (!projectId) return;
+    setStatus('running');
+    setStep('Starting…');
+    setPct(0);
+    setError(null);
+
+    try {
+      const { apiUrl } = getConfig();
+      const token = await requireToken();
+      const options = {};
+
+      if (phase === 'analyze-codebase') {
+        setStep('Scanning workspace…');
+        const snapshot = await collectWorkspaceSnapshot(process.cwd());
+        options.snapshot = snapshot;
+      }
+
+      const result = await runPhase(projectId, phase, options);
+      const { jobId } = result;
+
+      setStep('Queued');
+
+      for await (const { event, data } of streamPhaseProgress(apiUrl, jobId, token)) {
+        if (event === 'job:status') {
+          setStep(data.status ?? 'processing');
+        } else if (event === 'job:progress') {
+          setStep(data.step ?? data.message ?? '');
+          if (data.pct != null) setPct(data.pct);
+        } else if (event === 'job:completed') {
+          setArtifactCount(data.output?.artifacts?.length ?? 0);
+          setPct(100);
+          setStatus('completed');
+          return;
+        } else if (event === 'job:failed') {
+          setError(data.error ?? 'Phase failed');
+          setStatus('failed');
+          return;
+        } else if (event === 'job:timeout') {
+          setError('Timed out — phase may still be running on server');
+          setStatus('failed');
+          return;
+        }
+      }
+
+      // Stream ended without terminal event
+      setError('Stream ended unexpectedly — check status with vectora status');
+      setStatus('failed');
+    } catch (err) {
+      setError(err.message ?? 'Unknown error');
+      setStatus('failed');
+    }
+  }, [projectId]);
+
+  return { status, step, pct, artifactCount, error, run, reset };
+}