@openparachute/agent 0.1.0

package/web/ui/src/routes/SetupWizard.tsx

@@ -0,0 +1,219 @@
+/**
+ * Setup wizard orchestrator (paraclaw#27 phase 1).
+ *
+ * Mounts at /setup. Renders the active step and a step indicator. State
+ * lives in localStorage under SETUP_STORAGE_KEY so a tab close mid-install
+ * survives — the bot token is the one thing we never persist (handled in
+ * the credentials step itself).
+ *
+ * Step navigation:
+ *   - The step indicator shows all 9 steps; the user can click any step at
+ *     or before `furthestStep` to revisit it.
+ *   - `next()` advances and stamps furthestStep monotonically.
+ *   - `goto()` lets a step jump (e.g. credentials → install).
+ *   - `back()` is purely visual — no state mutation.
+ *
+ * The orchestrator does NOT do smart-resume on its own. Each step renders
+ * its current state from the server (PrereqStep polls /setup/status,
+ * AdapterInstallStep polls the in-flight task, etc.) so the UI is always
+ * faithful to the actual filesystem rather than what we think happened.
+ */
+import { useCallback, useEffect, useMemo, useState, type ReactElement } from 'react';
+import { Link } from 'react-router-dom';
+import { AdapterInstallStep } from '../components/setup/AdapterInstallStep.tsx';
+import { AgentGroupStep } from '../components/setup/AgentGroupStep.tsx';
+import { ChannelPickStep } from '../components/setup/ChannelPickStep.tsx';
+import { DoneStep } from '../components/setup/DoneStep.tsx';
+import { PrereqStep } from '../components/setup/PrereqStep.tsx';
+import { TestConnectionStep } from '../components/setup/TestConnectionStep.tsx';
+import { TestMessageStep } from '../components/setup/TestMessageStep.tsx';
+import { WireChannelStep } from '../components/setup/WireChannelStep.tsx';
+import {
+  ADAPTER_LABELS,
+  DEFAULT_SETUP_STATE,
+  SETUP_STEPS,
+  SETUP_STORAGE_KEY,
+  type SetupState,
+  type SetupStepKey,
+  type StepProps,
+} from '../components/setup/types.ts';
+
+function loadState(): SetupState {
+  try {
+    const raw = localStorage.getItem(SETUP_STORAGE_KEY);
+    if (!raw) return { ...DEFAULT_SETUP_STATE };
+    const parsed = JSON.parse(raw) as Partial<SetupState>;
+    return { ...DEFAULT_SETUP_STATE, ...parsed };
+  } catch {
+    return { ...DEFAULT_SETUP_STATE };
+  }
+}
+
+function saveState(state: SetupState): void {
+  try {
+    localStorage.setItem(SETUP_STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    // Quota exceeded / private browsing; non-fatal.
+  }
+}
+
+const STEP_INDEX: Record<SetupStepKey, number> = SETUP_STEPS.reduce(
+  (acc, s, i) => {
+    acc[s.key] = i;
+    return acc;
+  },
+  {} as Record<SetupStepKey, number>,
+);
+
+export function SetupWizard() {
+  const [state, setState] = useState<SetupState>(() => loadState());
+
+  useEffect(() => {
+    saveState(state);
+  }, [state]);
+
+  const patchState = useCallback((patch: Partial<SetupState>) => {
+    setState((prev) => ({ ...prev, ...patch }));
+  }, []);
+
+  const goto = useCallback((step: SetupStepKey) => {
+    setState((prev) => {
+      const stepIdx = STEP_INDEX[step];
+      const furthestIdx = STEP_INDEX[prev.furthestStep];
+      return {
+        ...prev,
+        currentStep: step,
+        furthestStep: stepIdx > furthestIdx ? step : prev.furthestStep,
+      };
+    });
+  }, []);
+
+  const next = useCallback(() => {
+    setState((prev) => {
+      const idx = STEP_INDEX[prev.currentStep];
+      const nextIdx = Math.min(idx + 1, SETUP_STEPS.length - 1);
+      const nextStep = SETUP_STEPS[nextIdx].key;
+      const furthestIdx = STEP_INDEX[prev.furthestStep];
+      return {
+        ...prev,
+        currentStep: nextStep,
+        furthestStep: nextIdx > furthestIdx ? nextStep : prev.furthestStep,
+      };
+    });
+  }, []);
+
+  const back = useCallback(() => {
+    setState((prev) => {
+      const idx = STEP_INDEX[prev.currentStep];
+      const prevStep = SETUP_STEPS[Math.max(idx - 1, 0)].key;
+      return { ...prev, currentStep: prevStep };
+    });
+  }, []);
+
+  const stepProps: StepProps = useMemo(
+    () => ({ state, patchState, next, back, goto }),
+    [state, patchState, next, back, goto],
+  );
+
+  const onReset = () => {
+    if (
+      !confirm(
+        'Reset wizard state? This clears local progress (bot user id, agent group folder, etc.) but does NOT undo backend changes (installed adapters, agent groups, saved secrets).',
+      )
+    )
+      return;
+    localStorage.removeItem(SETUP_STORAGE_KEY);
+    setState({ ...DEFAULT_SETUP_STATE });
+  };
+
+  return (
+    <div>
+      <Link to="/" className="muted">
+        ← Skip setup, view groups
+      </Link>
+      <h2 style={{ marginTop: '0.5rem' }}>
+        Set up parachute-agent
+        {state.adapter && (
+          <span className="dim" style={{ fontSize: '0.7em', marginLeft: '0.5rem' }}>
+            · {ADAPTER_LABELS[state.adapter]}
+          </span>
+        )}
+      </h2>
+      <p className="muted" style={{ marginTop: '-0.5rem' }}>
+        Fresh install? Walk these steps to land your first agent. You can re-open this wizard any time at <code>/agent/setup</code>.
+      </p>
+      <SetupStepIndicator current={state.currentStep} furthest={state.furthestStep} onJump={goto} />
+
+      <div className="section">{renderStep(state.currentStep, stepProps)}</div>
+
+      <div className="actions" style={{ marginTop: '1rem' }}>
+        <button className="secondary" onClick={onReset}>
+          Reset wizard
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function renderStep(step: SetupStepKey, props: StepProps): ReactElement {
+  switch (step) {
+    case 'prereqs':
+      return <PrereqStep {...props} />;
+    case 'channel-pick':
+      return <ChannelPickStep {...props} />;
+    case 'install':
+      return <AdapterInstallStep {...props} />;
+    case 'test-connection':
+      return <TestConnectionStep {...props} />;
+    case 'agent-group':
+      return <AgentGroupStep {...props} />;
+    case 'wire-channel':
+      return <WireChannelStep {...props} />;
+    case 'test-message':
+      return <TestMessageStep {...props} />;
+    case 'done':
+      return <DoneStep {...props} />;
+  }
+}
+
+function SetupStepIndicator({
+  current,
+  furthest,
+  onJump,
+}: {
+  current: SetupStepKey;
+  furthest: SetupStepKey;
+  onJump: (step: SetupStepKey) => void;
+}) {
+  const furthestIdx = STEP_INDEX[furthest];
+  return (
+    <ol className="wizard-steps">
+      {SETUP_STEPS.map((s, i) => {
+        const reachable = i <= furthestIdx;
+        const isCurrent = s.key === current;
+        return (
+          <li key={s.key} className={`wizard-step${isCurrent ? ' active' : ''}`}>
+            {reachable ? (
+              <button
+                type="button"
+                onClick={() => onJump(s.key)}
+                style={{
+                  background: 'transparent',
+                  border: 0,
+                  padding: 0,
+                  color: 'inherit',
+                  font: 'inherit',
+                  cursor: 'pointer',
+                }}
+              >
+                {s.label}
+              </button>
+            ) : (
+              <span style={{ opacity: 0.6 }}>{s.label}</span>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/web/ui/src/routes/VaultDetail.test.tsx

@@ -0,0 +1,361 @@
+/**
+ * VaultDetail tests cover the four behavior contracts the design doc calls
+ * out as inviolable:
+ *   1. Mint flow: form submit → mintVaultToken called with form values →
+ *      plaintext shown once in the copy-card → "Copy" button writes to
+ *      clipboard.
+ *   2. Revoke: confirm-modal copy says "one-way", DELETE only fires on
+ *      explicit confirm.
+ *   3. Detach modal: two-button shape (Keep / Detach + revoke), and the
+ *      "Detach + revoke" button passes `revokeToken: true`.
+ *   4. Auth fallback: a 401/403 from listVaultTokens renders the
+ *      auth-gate "Grant access" button, and clicking it triggers
+ *      beginLogin with the narrow per-vault admin scope appended.
+ *
+ * Tests stub the api module so we don't need a live server or real
+ * localStorage-seeded auth state. The auth module is mocked too, so we
+ * can assert beginLogin was called with the right scopes without the
+ * real implementation trying to navigate the jsdom window.
+ */
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import * as api from '../lib/api.ts';
+import * as auth from '../lib/auth.ts';
+import { VaultDetail } from './VaultDetail.tsx';
+
+vi.mock('../lib/api.ts', async () => {
+  const actual = await vi.importActual<typeof api>('../lib/api.ts');
+  return {
+    ...actual,
+    getVaultDetail: vi.fn(),
+    listVaultTokens: vi.fn(),
+    mintVaultToken: vi.fn(),
+    revokeVaultToken: vi.fn(),
+    detachVault: vi.fn(),
+  };
+});
+
+vi.mock('../lib/auth.ts', async () => {
+  const actual = await vi.importActual<typeof auth>('../lib/auth.ts');
+  return {
+    ...actual,
+    beginLogin: vi.fn(),
+  };
+});
+
+function renderAt(path: string) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route path="/vaults/:name" element={<VaultDetail />} />
+      </Routes>
+    </MemoryRouter>,
+  );
+}
+
+const sampleDetail: api.VaultDetail = {
+  vault: { name: 'work', url: 'https://hub.example/vault/work', version: '0.4.7' },
+  attachedGroups: [
+    {
+      folder: 'research',
+      mcpName: 'parachute-vault',
+      scope: 'vault:read',
+      tokenLabel: 'claw-research',
+      attachedAt: '2026-04-20T10:00:00Z',
+    },
+  ],
+};
+
+const sampleTokens: api.VaultToken[] = [
+  {
+    id: 't_abc',
+    label: 'claw-research',
+    scopes: ['vault:read'],
+    created_at: '2026-04-20T10:00:00Z',
+    last_used_at: '2026-04-28T10:00:00Z',
+    attachedTo: [{ folder: 'research', scope: 'vault:read' }],
+  },
+];
+
+beforeEach(() => {
+  vi.mocked(api.getVaultDetail).mockResolvedValue(sampleDetail);
+  vi.mocked(api.listVaultTokens).mockResolvedValue(sampleTokens);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('VaultDetail — mint flow', () => {
+  it('mints a token, renders plaintext once, copies on click', async () => {
+    const minted: api.MintedVaultToken = {
+      token: 'pvt_super_secret_plaintext',
+      id: 't_new',
+      label: 'claw-new',
+      scopes: ['vault:read'],
+      created_at: '2026-04-29T10:00:00Z',
+    };
+    vi.mocked(api.mintVaultToken).mockResolvedValue(minted);
+
+    // userEvent.setup() installs its own navigator.clipboard mock; reading
+    // back via readText() is the canonical way to assert what got copied.
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText('Mint new token')).toBeInTheDocument();
+    });
+
+    const labelInput = screen.getByLabelText('Label') as HTMLInputElement;
+    await user.clear(labelInput);
+    await user.type(labelInput, 'claw-new');
+
+    await user.click(screen.getByRole('button', { name: 'Mint token' }));
+
+    await waitFor(() => {
+      expect(api.mintVaultToken).toHaveBeenCalledWith('work', {
+        label: 'claw-new',
+        scopes: ['vault:read'],
+        expires_at: null,
+      });
+    });
+
+    // Plaintext appears once in the copy-card
+    await waitFor(() => {
+      expect(screen.getByDisplayValue('pvt_super_secret_plaintext')).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Copy to clipboard' }));
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: 'Copied ✓' })).toBeInTheDocument();
+    });
+    expect(await navigator.clipboard.readText()).toBe('pvt_super_secret_plaintext');
+  });
+});
+
+describe('VaultDetail — dismiss without copying', () => {
+  it('renders the warn-banner when the operator closes the card without copying', async () => {
+    const minted: api.MintedVaultToken = {
+      token: 'pvt_uncopied_secret',
+      id: 't_unc',
+      label: 'claw-uncopied',
+      scopes: ['vault:read'],
+      created_at: '2026-04-29T10:00:00Z',
+    };
+    vi.mocked(api.mintVaultToken).mockResolvedValue(minted);
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText('Mint new token')).toBeInTheDocument();
+    });
+
+    const labelInput = screen.getByLabelText('Label') as HTMLInputElement;
+    await user.clear(labelInput);
+    await user.type(labelInput, 'claw-uncopied');
+    await user.click(screen.getByRole('button', { name: 'Mint token' }));
+
+    // Plaintext appears in the copy-card
+    await waitFor(() => {
+      expect(screen.getByDisplayValue('pvt_uncopied_secret')).toBeInTheDocument();
+    });
+
+    // Operator closes the card WITHOUT clicking Copy.
+    await user.click(screen.getByRole('button', { name: 'Close without copying' }));
+
+    // Warn-banner appears, naming the token by label, with both inline
+    // Revoke and Dismiss CTAs.
+    await waitFor(() => {
+      expect(
+        screen.getByText(/was minted but you didn't copy the plaintext/),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByRole('button', { name: 'Revoke claw-uncopied' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Dismiss' })).toBeInTheDocument();
+
+    // Plaintext is gone from the DOM — vault stored only a hash.
+    expect(screen.queryByDisplayValue('pvt_uncopied_secret')).not.toBeInTheDocument();
+  });
+
+  it('disables the inline Revoke button when the token is not in the live list (paraclaw#62)', async () => {
+    // Race / id-mismatch path: operator dismisses without copying, but the
+    // post-mint reload returns a tokens list that doesn't include the new
+    // id (vault hiccup, server-side rename, etc.). The CTA must visibly
+    // disable rather than silently no-op on click.
+    const minted: api.MintedVaultToken = {
+      token: 'pvt_lost_secret',
+      id: 't_lost',
+      label: 'claw-lost',
+      scopes: ['vault:read'],
+      created_at: '2026-04-30T10:00:00Z',
+    };
+    vi.mocked(api.mintVaultToken).mockResolvedValue(minted);
+    // First call (initial render) returns the seeded sampleTokens; every
+    // subsequent call (the post-mint reload) returns an empty list, so the
+    // banner's `live` lookup misses.
+    vi.mocked(api.listVaultTokens)
+      .mockReset()
+      .mockResolvedValueOnce(sampleTokens)
+      .mockResolvedValue([]);
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText('Mint new token')).toBeInTheDocument();
+    });
+
+    const labelInput = screen.getByLabelText('Label') as HTMLInputElement;
+    await user.clear(labelInput);
+    await user.type(labelInput, 'claw-lost');
+    await user.click(screen.getByRole('button', { name: 'Mint token' }));
+
+    await waitFor(() => {
+      expect(screen.getByDisplayValue('pvt_lost_secret')).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole('button', { name: 'Close without copying' }));
+
+    // Wait for the post-dismiss reload to settle so the empty tokens list
+    // is reflected in `state.tokens`.
+    await waitFor(() => {
+      expect(screen.queryByText(/Tokens \(1\)/)).not.toBeInTheDocument();
+    });
+
+    const revokeBtn = screen.getByRole('button', { name: 'Revoke claw-lost' });
+    expect(revokeBtn).toBeDisabled();
+    expect(revokeBtn).toHaveAttribute(
+      'title',
+      'Token no longer in current list — see tokens table below',
+    );
+  });
+});
+
+describe('VaultDetail — revoke modal', () => {
+  it('opens confirm modal with one-way copy and only revokes on explicit click', async () => {
+    vi.mocked(api.revokeVaultToken).mockResolvedValue(undefined);
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText(/Tokens \(1\)/)).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Revoke' }));
+    expect(screen.getByText(/one-way/i)).toBeInTheDocument();
+    expect(api.revokeVaultToken).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('button', { name: 'Revoke token' }));
+    await waitFor(() => {
+      expect(api.revokeVaultToken).toHaveBeenCalledWith('work', 't_abc');
+    });
+  });
+});
+
+describe('VaultDetail — detach modal', () => {
+  it('exposes Keep + Detach+revoke buttons; Detach+revoke passes revokeToken=true', async () => {
+    vi.mocked(api.detachVault).mockResolvedValue({
+      group: {
+        id: 'g1',
+        name: 'research',
+        folder: 'research',
+        agent_provider: null,
+        created_at: '2026-04-20T10:00:00Z',
+        vault: null,
+        status: null,
+      },
+      revokedTokenId: 't_abc',
+      revokeError: null,
+    });
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText(/Attached groups \(1\)/)).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Detach…' }));
+
+    expect(screen.getByRole('button', { name: 'Keep token' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Detach + revoke' })).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: 'Detach + revoke' }));
+
+    await waitFor(() => {
+      expect(api.detachVault).toHaveBeenCalledWith('research', {
+        mcpName: 'parachute-vault',
+        revokeToken: true,
+        authExtraScopes: ['vault:work:admin'],
+      });
+    });
+  });
+
+  it('Keep token detaches without revoke', async () => {
+    vi.mocked(api.detachVault).mockResolvedValue({
+      group: {
+        id: 'g1',
+        name: 'research',
+        folder: 'research',
+        agent_provider: null,
+        created_at: '2026-04-20T10:00:00Z',
+        vault: null,
+        status: null,
+      },
+      revokedTokenId: null,
+      revokeError: null,
+    });
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText(/Attached groups \(1\)/)).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole('button', { name: 'Detach…' }));
+    await user.click(screen.getByRole('button', { name: 'Keep token' }));
+
+    await waitFor(() => {
+      expect(api.detachVault).toHaveBeenCalledWith('research', {
+        mcpName: 'parachute-vault',
+        revokeToken: false,
+        authExtraScopes: undefined,
+      });
+    });
+  });
+});
+
+describe('VaultDetail — auth fallback', () => {
+  it('renders Grant access on 403 and triggers beginLogin with narrow scope', async () => {
+    vi.mocked(api.listVaultTokens).mockRejectedValue(
+      new api.HttpError(403, 'missing vault:work:admin'),
+    );
+
+    const user = userEvent.setup();
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText('Additional consent required')).toBeInTheDocument();
+    });
+    expect(screen.getByText(/missing vault:work:admin/)).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: 'Grant access' }));
+    expect(auth.beginLogin).toHaveBeenCalledWith(['vault:work:admin']);
+  });
+
+  it('renders Grant access on 401 too', async () => {
+    vi.mocked(api.listVaultTokens).mockRejectedValue(
+      new api.HttpError(401, 'unauthorized'),
+    );
+
+    renderAt('/vaults/work');
+
+    await waitFor(() => {
+      expect(screen.getByText('Additional consent required')).toBeInTheDocument();
+    });
+  });
+});