create-ekka-desktop-app 0.2.2

package/template/src/demo/DemoApp.tsx

@@ -0,0 +1,260 @@
+/**
+ * EKKA Demo App
+ *
+ * Flow:
+ * 1. Check setup status (pre-login) - only node credentials
+ * 2. If setup incomplete (no node credentials), show SetupWizard
+ * 3. Connect to engine
+ * 4. Check auth - if not logged in, show LoginPage
+ * 5. After login, check home.status for HOME grant
+ * 6. If not HOME_GRANTED, show HomeSetupPage (requests grant from engine)
+ * 7. Show main app when HOME_GRANTED
+ */
+
+import { useState, useEffect, type ReactElement, type CSSProperties } from 'react';
+import { ekka, advanced, EkkaError, addAuditEvent, type HomeStatus, type SetupStatus } from '../ekka';
+import { Shell } from './layout/Shell';
+import { type Page } from './layout/Sidebar';
+import { SystemPage } from './pages/SystemPage';
+import { AuditLogPage } from './pages/AuditLogPage';
+import { PathPermissionsPage } from './pages/PathPermissionsPage';
+import { VaultPage } from './pages/VaultPage';
+import { DocGenPage } from './pages/DocGenPage';
+import { RunnerPage } from './pages/RunnerPage';
+import { LoginPage } from './pages/LoginPage';
+import { HomeSetupPage } from './pages/HomeSetupPage';
+import { SetupWizard } from './components/SetupWizard';
+
+type AppState = 'loading' | 'setup' | 'login' | 'home-setup' | 'ready';
+
+interface DemoState {
+  appState: AppState;
+  setupStatus: SetupStatus | null;
+  homeStatus: HomeStatus | null;
+  connected: boolean;
+  error: string | null;
+}
+
+export function DemoApp(): ReactElement {
+  const [selectedPage, setSelectedPage] = useState<Page>('path-permissions');
+  const [darkMode, setDarkMode] = useState<boolean>(() => {
+    if (typeof window !== 'undefined') {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches;
+    }
+    return false;
+  });
+  const [state, setState] = useState<DemoState>({
+    appState: 'loading',
+    setupStatus: null,
+    homeStatus: null,
+    connected: false,
+    error: null,
+  });
+
+  useEffect(() => {
+    void initializeApp();
+  }, []);
+
+  async function initializeApp(): Promise<void> {
+    try {
+      // Step 1: Check setup status BEFORE connect (pre-login)
+      const setupStatus = await ekka.setup.status();
+      setState((s) => ({ ...s, setupStatus }));
+
+      // Log setup gate status
+      console.log(`[ekka] op=desktop.setup.gate setupComplete=${setupStatus.setupComplete}`);
+
+      // HARD GATE: If setup is incomplete, show wizard - NO exceptions
+      if (!setupStatus.setupComplete) {
+        setState((s) => ({ ...s, appState: 'setup' }));
+        return;
+      }
+
+      // Step 2: Connect to engine (REQUIRED before login)
+      await ekka.connect();
+      setState((s) => ({ ...s, connected: true }));
+
+      console.log('[ekka] op=desktop.connect.success');
+
+      addAuditEvent({
+        type: 'connection.established',
+        description: 'Connected to EKKA backend',
+        technical: { mode: advanced.internal.mode() },
+      });
+
+      // Step 3: Check auth
+      if (!ekka.auth.isLoggedIn()) {
+        setState((s) => ({ ...s, appState: 'login' }));
+        return;
+      }
+
+      const user = ekka.auth.user();
+      if (user) {
+        const tenantId = user.company?.id || 'default';
+        await advanced.auth.setContext({ tenantId, sub: user.id, jwt: '' });
+      }
+
+      await checkHomeStatus();
+    } catch (err: unknown) {
+      const message = err instanceof EkkaError ? err.message : 'Connection failed';
+
+      // Check if setup is incomplete - if so, stay in setup mode
+      try {
+        const setupStatus = await ekka.setup.status();
+        if (!setupStatus.setupComplete) {
+          setState((s) => ({ ...s, setupStatus, appState: 'setup', error: message }));
+          return;
+        }
+      } catch {
+        // If we can't check setup status, stay in loading with error
+        setState((s) => ({ ...s, error: message }));
+        return;
+      }
+
+      // Only go to login if setup IS complete but connection failed
+      setState((s) => ({ ...s, error: message, appState: 'login' }));
+
+      addAuditEvent({
+        type: 'connection.failed',
+        description: 'Failed to connect to EKKA backend',
+        technical: { error: message },
+      });
+    }
+  }
+
+  async function checkHomeStatus(): Promise<void> {
+    try {
+      const status = await advanced.home.status();
+      setState((s) => ({ ...s, homeStatus: status }));
+
+      if (status.state === 'HOME_GRANTED') {
+        setState((s) => ({ ...s, appState: 'ready' }));
+      } else if (status.state === 'AUTHENTICATED_NO_HOME_GRANT') {
+        setState((s) => ({ ...s, appState: 'home-setup' }));
+      } else {
+        setState((s) => ({ ...s, appState: 'login' }));
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to check home status';
+      setState((s) => ({ ...s, error: message }));
+    }
+  }
+
+  async function handleSetupComplete(): Promise<void> {
+    // After setup wizard completes:
+    // Wizard already verified credentials saved - proceed directly to login
+    // (Don't re-verify via setup.status - keychain read-after-write has race condition)
+    setState((s) => ({ ...s, appState: 'loading' }));
+
+    try {
+      // Ensure connected (wizard should have called connect, but verify)
+      if (!ekka.isConnected()) {
+        await ekka.connect();
+        console.log('[ekka] op=desktop.connect.success (post-setup)');
+      }
+      setState((s) => ({ ...s, connected: true }));
+
+      // Now proceed to login
+      if (!ekka.auth.isLoggedIn()) {
+        setState((s) => ({ ...s, appState: 'login' }));
+        return;
+      }
+
+      // Already logged in - check home status
+      await checkHomeStatus();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Setup verification failed';
+      setState((s) => ({ ...s, error: message, appState: 'setup' }));
+    }
+  }
+
+  async function handleLoginSuccess(): Promise<void> {
+    // Belt + suspenders: ensure connected before any engine ops
+    if (!state.connected) {
+      try {
+        await ekka.connect();
+        setState((s) => ({ ...s, connected: true }));
+        console.log('[ekka] op=desktop.connect.success (post-login)');
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Failed to connect';
+        setState((s) => ({ ...s, error: message }));
+        return;
+      }
+    }
+    await checkHomeStatus();
+  }
+
+  function handleHomeGranted(): void {
+    setState((s) => ({ ...s, appState: 'ready' }));
+  }
+
+  // Loading
+  if (state.appState === 'loading') {
+    const style: CSSProperties = {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      minHeight: '100vh',
+      background: darkMode ? '#1c1c1e' : '#ffffff',
+      fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif',
+      color: darkMode ? '#98989d' : '#86868b',
+      fontSize: '14px',
+    };
+    return <div style={style}>Connecting...</div>;
+  }
+
+  // Setup wizard (pre-login)
+  if (state.appState === 'setup' && state.setupStatus) {
+    return (
+      <SetupWizard
+        initialStatus={state.setupStatus}
+        onComplete={handleSetupComplete}
+        darkMode={darkMode}
+      />
+    );
+  }
+
+  // Login
+  if (state.appState === 'login') {
+    return <LoginPage onLoginSuccess={handleLoginSuccess} darkMode={darkMode} />;
+  }
+
+  // Home setup
+  if (state.appState === 'home-setup' && state.homeStatus) {
+    return (
+      <HomeSetupPage
+        homeStatus={state.homeStatus}
+        onGranted={handleHomeGranted}
+        darkMode={darkMode}
+      />
+    );
+  }
+
+  // Main app
+  const errorStyle: CSSProperties = {
+    marginBottom: '20px',
+    padding: '12px 14px',
+    background: darkMode ? '#3c1618' : '#fef2f2',
+    border: `1px solid ${darkMode ? '#7f1d1d' : '#fecaca'}`,
+    borderRadius: '6px',
+    fontSize: '13px',
+    color: darkMode ? '#fca5a5' : '#991b1b',
+  };
+
+  return (
+    <Shell
+      selectedPage={selectedPage}
+      onNavigate={setSelectedPage}
+      darkMode={darkMode}
+      onToggleDarkMode={() => setDarkMode((prev) => !prev)}
+    >
+      {state.error && <div style={errorStyle}>{state.error}</div>}
+      {selectedPage === 'path-permissions' && <PathPermissionsPage darkMode={darkMode} />}
+      {selectedPage === 'vault' && <VaultPage darkMode={darkMode} />}
+      {selectedPage === 'doc-gen' && <DocGenPage darkMode={darkMode} />}
+      {selectedPage === 'runner' && <RunnerPage darkMode={darkMode} />}
+      {selectedPage === 'audit-log' && <AuditLogPage darkMode={darkMode} />}
+      {selectedPage === 'system' && <SystemPage darkMode={darkMode} />}
+    </Shell>
+  );
+}

package/template/src/demo/components/Banner.tsx

@@ -0,0 +1,82 @@
+/**
+ * Banner Component
+ * Informational banner for warnings, info, and errors.
+ */
+
+import { type CSSProperties, type ReactElement } from 'react';
+
+type BannerType = 'warning' | 'info' | 'error';
+
+interface BannerProps {
+  type: BannerType;
+  message: string;
+  darkMode?: boolean;
+}
+
+export function Banner({ type, message, darkMode = false }: BannerProps): ReactElement {
+  const colorMap: Record<BannerType, { bg: string; border: string; text: string; icon: string }> = {
+    warning: {
+      bg: darkMode ? '#422006' : '#fffbeb',
+      border: darkMode ? '#854d0e' : '#fcd34d',
+      text: darkMode ? '#fcd34d' : '#92400e',
+      icon: darkMode ? '#fbbf24' : '#f59e0b',
+    },
+    info: {
+      bg: darkMode ? '#1e3a5f' : '#eff6ff',
+      border: darkMode ? '#1d4ed8' : '#93c5fd',
+      text: darkMode ? '#93c5fd' : '#1e40af',
+      icon: darkMode ? '#60a5fa' : '#3b82f6',
+    },
+    error: {
+      bg: darkMode ? '#3c1618' : '#fef2f2',
+      border: darkMode ? '#7f1d1d' : '#fecaca',
+      text: darkMode ? '#fca5a5' : '#991b1b',
+      icon: darkMode ? '#f87171' : '#ef4444',
+    },
+  };
+
+  const colors = colorMap[type];
+
+  const styles: Record<string, CSSProperties> = {
+    banner: {
+      display: 'flex',
+      alignItems: 'flex-start',
+      gap: '12px',
+      padding: '12px 14px',
+      background: colors.bg,
+      border: `1px solid ${colors.border}`,
+      borderRadius: '6px',
+      fontSize: '13px',
+      lineHeight: 1.5,
+      color: colors.text,
+    },
+    icon: {
+      width: '16px',
+      height: '16px',
+      flexShrink: 0,
+      marginTop: '1px',
+      color: colors.icon,
+    },
+    message: {
+      flex: 1,
+      margin: 0,
+    },
+  };
+
+  const iconPaths: Record<BannerType, string> = {
+    warning:
+      'M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5zm.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2z',
+    info: 'M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z',
+    error:
+      'M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zM5.354 4.646a.5.5 0 1 0-.708.708L7.293 8l-2.647 2.646a.5.5 0 0 0 .708.708L8 8.707l2.646 2.647a.5.5 0 0 0 .708-.708L8.707 8l2.647-2.646a.5.5 0 0 0-.708-.708L8 7.293 5.354 4.646z',
+  };
+
+  return (
+    <div style={styles.banner}>
+      <svg style={styles.icon} viewBox="0 0 16 16" fill="currentColor">
+        <path d={iconPaths[type]} />
+      </svg>
+      <p style={styles.message}>{message}</p>
+    </div>
+  );
+}

package/template/src/demo/components/EmptyState.tsx

@@ -0,0 +1,61 @@
+/**
+ * Empty State Component
+ * Placeholder UI for empty lists or sections.
+ */
+
+import { type CSSProperties, type ReactElement, type ReactNode } from 'react';
+
+interface EmptyStateProps {
+  icon: ReactNode;
+  message: string;
+  hint?: string;
+  darkMode?: boolean;
+}
+
+export function EmptyState({
+  icon,
+  message,
+  hint,
+  darkMode = false,
+}: EmptyStateProps): ReactElement {
+  const colors = {
+    text: darkMode ? '#ffffff' : '#1d1d1f',
+    textMuted: darkMode ? '#98989d' : '#6e6e73',
+    iconColor: darkMode ? '#48484a' : '#d2d2d7',
+  };
+
+  const styles: Record<string, CSSProperties> = {
+    container: {
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: '48px 24px',
+      textAlign: 'center',
+    },
+    iconWrapper: {
+      marginBottom: '16px',
+      color: colors.iconColor,
+    },
+    message: {
+      fontSize: '14px',
+      fontWeight: 500,
+      color: colors.text,
+      marginBottom: hint ? '8px' : '0',
+    },
+    hint: {
+      fontSize: '13px',
+      color: colors.textMuted,
+      maxWidth: '280px',
+      lineHeight: 1.5,
+    },
+  };
+
+  return (
+    <div style={styles.container}>
+      <div style={styles.iconWrapper}>{icon}</div>
+      <p style={styles.message}>{message}</p>
+      {hint && <p style={styles.hint}>{hint}</p>}
+    </div>
+  );
+}

package/template/src/demo/components/InfoPopover.tsx

@@ -0,0 +1,171 @@
+/**
+ * Info Popover Component
+ * Shows an info icon that displays detailed info on click.
+ * Uses position: fixed to avoid being clipped by parent overflow.
+ */
+
+import { useState, useRef, useEffect, type CSSProperties, type ReactElement, type ReactNode } from 'react';
+
+interface InfoItem {
+  label: string;
+  value: string | ReactNode;
+  mono?: boolean;
+}
+
+interface InfoPopoverProps {
+  items: InfoItem[];
+  darkMode?: boolean;
+}
+
+export function InfoPopover({ items, darkMode = false }: InfoPopoverProps): ReactElement {
+  const [isOpen, setIsOpen] = useState(false);
+  const [position, setPosition] = useState({ top: 0, right: 0 });
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  const colors = {
+    icon: darkMode ? '#98989d' : '#86868b',
+    iconHover: darkMode ? '#0a84ff' : '#007aff',
+    bg: darkMode ? '#2c2c2e' : '#ffffff',
+    border: darkMode ? '#3a3a3c' : '#e5e5e5',
+    text: darkMode ? '#ffffff' : '#1d1d1f',
+    textMuted: darkMode ? '#98989d' : '#86868b',
+  };
+
+  const styles: Record<string, CSSProperties> = {
+    container: {
+      position: 'relative',
+      display: 'inline-flex',
+      alignItems: 'center',
+    },
+    button: {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: '24px',
+      height: '24px',
+      padding: 0,
+      background: 'transparent',
+      border: 'none',
+      borderRadius: '4px',
+      cursor: 'pointer',
+      color: isOpen ? colors.iconHover : colors.icon,
+      transition: 'color 0.15s ease',
+    },
+    popover: {
+      position: 'fixed',
+      top: position.top,
+      right: position.right,
+      padding: '12px',
+      background: colors.bg,
+      border: `1px solid ${colors.border}`,
+      borderRadius: '8px',
+      boxShadow: darkMode
+        ? '0 4px 16px rgba(0, 0, 0, 0.4)'
+        : '0 4px 16px rgba(0, 0, 0, 0.12)',
+      zIndex: 9999,
+      minWidth: '260px',
+      maxWidth: '360px',
+      maxHeight: '400px',
+      overflowY: 'auto',
+    },
+    row: {
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '2px',
+      padding: '6px 0',
+      borderBottom: `1px solid ${colors.border}`,
+    },
+    rowLast: {
+      borderBottom: 'none',
+    },
+    label: {
+      fontSize: '10px',
+      fontWeight: 600,
+      color: colors.textMuted,
+      textTransform: 'uppercase',
+      letterSpacing: '0.04em',
+    },
+    value: {
+      fontSize: '12px',
+      color: colors.text,
+      wordBreak: 'break-all',
+    },
+    valueMono: {
+      fontFamily: 'SF Mono, Monaco, Consolas, monospace',
+    },
+  };
+
+  // Update position when opening
+  useEffect(() => {
+    if (isOpen && buttonRef.current) {
+      const rect = buttonRef.current.getBoundingClientRect();
+      setPosition({
+        top: rect.bottom + 8,
+        right: window.innerWidth - rect.right,
+      });
+    }
+  }, [isOpen]);
+
+  // Close on click outside or scroll
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleClickOutside = (e: MouseEvent) => {
+      if (buttonRef.current && !buttonRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    const handleScroll = () => setIsOpen(false);
+
+    document.addEventListener('click', handleClickOutside);
+    document.addEventListener('scroll', handleScroll, true);
+
+    return () => {
+      document.removeEventListener('click', handleClickOutside);
+      document.removeEventListener('scroll', handleScroll, true);
+    };
+  }, [isOpen]);
+
+  return (
+    <div style={styles.container}>
+      <button
+        ref={buttonRef}
+        style={styles.button}
+        onClick={(e) => {
+          e.stopPropagation();
+          setIsOpen(!isOpen);
+        }}
+        title="View details"
+      >
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+          <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="1.5" />
+          <path
+            d="M8 7v4M8 5.5v.01"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeLinecap="round"
+          />
+        </svg>
+      </button>
+      {isOpen && (
+        <div style={styles.popover} onClick={(e) => e.stopPropagation()}>
+          {items.map((item, idx) => (
+            <div
+              key={item.label}
+              style={{
+                ...styles.row,
+                ...(idx === items.length - 1 ? styles.rowLast : {}),
+              }}
+            >
+              <span style={styles.label}>{item.label}</span>
+              <span style={{ ...styles.value, ...(item.mono ? styles.valueMono : {}) }}>
+                {item.value}
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/template/src/demo/components/InfoTooltip.tsx

@@ -0,0 +1,76 @@
+/**
+ * Info Tooltip Component
+ * Shows an info icon that displays tooltip text on hover.
+ */
+
+import { useState, type CSSProperties, type ReactElement } from 'react';
+
+interface InfoTooltipProps {
+  text: string;
+  darkMode?: boolean;
+}
+
+export function InfoTooltip({ text, darkMode = false }: InfoTooltipProps): ReactElement {
+  const [isVisible, setIsVisible] = useState(false);
+
+  const colors = {
+    icon: darkMode ? '#98989d' : '#86868b',
+    iconHover: darkMode ? '#ffffff' : '#1d1d1f',
+    tooltipBg: darkMode ? '#3a3a3c' : '#1d1d1f',
+    tooltipText: '#ffffff',
+  };
+
+  const styles: Record<string, CSSProperties> = {
+    container: {
+      position: 'relative',
+      display: 'inline-flex',
+      alignItems: 'center',
+    },
+    icon: {
+      width: '14px',
+      height: '14px',
+      cursor: 'help',
+      color: isVisible ? colors.iconHover : colors.icon,
+      transition: 'color 0.15s ease',
+    },
+    tooltip: {
+      position: 'absolute',
+      bottom: '100%',
+      left: '50%',
+      transform: 'translateX(-50%)',
+      marginBottom: '8px',
+      padding: '8px 12px',
+      background: colors.tooltipBg,
+      color: colors.tooltipText,
+      fontSize: '12px',
+      lineHeight: 1.4,
+      borderRadius: '6px',
+      whiteSpace: 'nowrap',
+      maxWidth: '280px',
+      zIndex: 1000,
+      opacity: isVisible ? 1 : 0,
+      visibility: isVisible ? 'visible' : 'hidden',
+      transition: 'opacity 0.15s ease, visibility 0.15s ease',
+      pointerEvents: 'none',
+    },
+  };
+
+  return (
+    <span
+      style={styles.container}
+      onMouseEnter={() => setIsVisible(true)}
+      onMouseLeave={() => setIsVisible(false)}
+    >
+      <svg style={styles.icon} viewBox="0 0 16 16" fill="none">
+        <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="1.5" />
+        <path
+          d="M8 7v4M8 5.5v.01"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        />
+      </svg>
+      <span style={styles.tooltip}>{text}</span>
+    </span>
+  );
+}