insforge 0.3.1

package/frontend/src/features/onboard/components/OnboardButton.tsx

@@ -0,0 +1,84 @@
+import { Link, useLocation } from 'react-router-dom';
+import { cn } from '@/lib/utils/utils';
+import { Button } from '@/components/radix/Button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/radix/Tooltip';
+import { CircularStepper } from '@/components/Stepper';
+import { useOnboardStep, STEP_DESCRIPTIONS } from '@/lib/contexts/OnboardStepContext';
+
+interface OnboardButtonProps {
+  isCollapsed: boolean;
+}
+
+export function OnboardButton({ isCollapsed }: OnboardButtonProps) {
+  const location = useLocation();
+  const { currentStep, totalSteps } = useOnboardStep();
+
+  const isActive = location.pathname === '/dashboard/onboard';
+
+  // Limit displayed step to totalSteps for the sidebar
+  const displayStep = Math.min(currentStep, totalSteps);
+  const currentDescription = STEP_DESCRIPTIONS[displayStep - 1];
+
+  return (
+    <TooltipProvider delayDuration={300}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Link to="/dashboard/onboard" className="block">
+            <Button
+              variant="ghost"
+              className={cn(
+                'w-full h-16 relative transition-all duration-200 ease-in-out border-2 rounded-lg justify-start',
+                isCollapsed ? 'pl-[11px] pr-2.5' : 'px-3.5',
+                isActive
+                  ? 'border-zinc-900 dark:bg-emerald-300 dark:hover:bg-emerald-200 bg-zinc-900 hover:bg-zinc-900 '
+                  : 'border-zinc-200 dark:border-neutral-700 hover:bg-zinc-50 dark:hover:bg-neutral-600 hover:border-zinc-300 dark:text-white'
+              )}
+            >
+              <CircularStepper
+                currentStep={displayStep}
+                totalSteps={totalSteps}
+                size={40}
+                isActive={isActive}
+              />
+              {!isCollapsed && (
+                <div className="absolute left-16.5 flex flex-col items-start">
+                  <span
+                    className={cn(
+                      'font-semibold text-sm transition-colors duration-200',
+                      isActive ? 'text-zinc-50 dark:text-black' : 'text-zinc-950 dark:text-white'
+                    )}
+                  >
+                    Get Started
+                  </span>
+                  <span
+                    className={cn(
+                      'text-xs transition-colors duration-200',
+                      isActive
+                        ? 'text-text-gray dark:text-zinc-800'
+                        : 'text-zinc-500 dark:text-white'
+                    )}
+                  >
+                    {currentDescription}
+                  </span>
+                </div>
+              )}
+            </Button>
+          </Link>
+        </TooltipTrigger>
+        {isCollapsed && (
+          <TooltipContent side="right">
+            <div className="text-center">
+              <p className="font-semibold">Get Started</p>
+              <p className="text-xs text-text-gray dark:text-neutural-600">{currentDescription}</p>
+            </div>
+          </TooltipContent>
+        )}
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/frontend/src/features/onboard/components/StepContent.tsx

@@ -0,0 +1,91 @@
+import { OnboardStep } from '../types';
+import { CodeBlock } from '@/components/CodeBlock';
+import { McpInstallation } from '@/features/onboard/components/mcp';
+import { TestConnectionStep } from './TestConnectionStep';
+
+interface StepContentProps {
+  step: OnboardStep;
+}
+
+export function StepContent({ step }: StepContentProps) {
+  switch (step) {
+    case OnboardStep.INSTALL_NODEJS:
+      return (
+        <div className="border border-transparent dark:border-neutral-800 rounded-xl bg-white dark:bg-neutral-800 py-8 px-6 space-y-4">
+          <div>
+            <p className="text-zinc-950 dark:text-white text-sm mb-4">
+              Install{' '}
+              <a
+                href="https://nodejs.org"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-link-blue underline inline-flex items-center gap-1"
+              >
+                Node.js
+              </a>
+              . Visit the official Node.js website at{' '}
+              <a
+                href="https://nodejs.org/"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-link-blue underline"
+              >
+                https://nodejs.org/
+              </a>
+            </p>
+            <p className="text-zinc-950 dark:text-white text-sm">
+              Verify installation by opening a terminal and running:
+            </p>
+          </div>
+
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <CodeBlock
+              code="node --version"
+              className="dark:bg-neutral-700 dark:text-white"
+              buttonClassName="dark:bg-neutral-800 dark:hover:bg-neutral-800"
+            />
+            <CodeBlock
+              code="npm --version"
+              className="dark:bg-neutral-700 dark:text-white"
+              buttonClassName="dark:bg-neutral-800 dark:hover:bg-neutral-800"
+            />
+          </div>
+        </div>
+      );
+
+    case OnboardStep.INSTALL_MCP:
+      return <McpInstallation TabListClassName="dark:bg-neutral-800" />;
+
+    case OnboardStep.TEST_CONNECTION:
+      return <TestConnectionStep />;
+
+    case OnboardStep.FINAL_SETUP:
+      return (
+        <div className="space-y-6 border border-transparent dark:border-neutral-700 rounded-xl bg-white dark:bg-neutral-800 py-8 px-6">
+          <div>
+            <p className="text-zinc-950 dark:text-white text-sm mb-4">
+              Whenever you start a new chat session, init your AI agents with the InsForge init
+              prompt:
+            </p>
+          </div>
+
+          <CodeBlock
+            code="Learn how to use InsForge"
+            className="bg-slate-50 dark:bg-neutral-700 dark:text-white"
+            buttonClassName="dark:bg-neutral-800 dark:hover:bg-neutral-800"
+          />
+
+          <div>
+            <p className="text-zinc-950 dark:text-white text-sm">Then you can start building!</p>
+          </div>
+        </div>
+      );
+
+    default:
+      return (
+        <div className="text-center text-zinc-500">
+          <p>Step content not found</p>
+        </div>
+      );
+  }
+}

package/frontend/src/features/onboard/components/TestConnectionStep.tsx

@@ -0,0 +1,53 @@
+import { CodeBlock } from '@/components/CodeBlock';
+import { ServerEvents, useSocket } from '@/lib/contexts/SocketContext';
+import { ClockIcon } from 'lucide-react';
+import CheckedIcon from '@/assets/icons/checked.svg';
+import { useEffect, useState } from 'react';
+
+export function TestConnectionStep() {
+  const [showSuccess, setShowSuccess] = useState(false);
+
+  // Use the Socket hook - it will auto-connect
+  const { socket } = useSocket();
+
+  // Show success message when mcp connects
+  useEffect(() => {
+    const handleMcpConnected = () => setShowSuccess(true);
+
+    socket?.on(ServerEvents.MCP_CONNECTED, handleMcpConnected);
+
+    return () => {
+      socket?.off(ServerEvents.MCP_CONNECTED, handleMcpConnected);
+    };
+  }, [socket]);
+
+  return (
+    <div className="space-y-6 border border-transparent dark:border-neutral-700 rounded-xl bg-white dark:bg-neutral-800 py-8 px-6">
+      <div>
+        <p className="text-zinc-950 dark:text-white text-sm mb-4">
+          Open your agent&apos;s chat interface, copy and send this:
+        </p>
+      </div>
+
+      <CodeBlock
+        code="I'm using InsForge as my backend platform, what is my current backend structure?"
+        className="bg-slate-50 dark:bg-neutral-700 dark:text-white"
+        buttonClassName="dark:bg-neutral-800 dark:hover:bg-neutral-800"
+      />
+
+      {!showSuccess && (
+        <div className="flex items-center gap-2 text-zinc-500 dark:text-neutral-400">
+          <ClockIcon className="w-5 h-5" />
+          <p className="text-sm">Waiting for connection</p>
+        </div>
+      )}
+
+      {showSuccess && (
+        <div className="flex items-center gap-2 text-green-600 dark:text-green-400">
+          <img src={CheckedIcon} alt="Checked" className="w-5 h-5" />
+          <p className="text-sm">API Call Detected, Connection Succeeded</p>
+        </div>
+      )}
+    </div>
+  );
+}

package/frontend/src/features/onboard/components/mcp/CursorDeeplinkGenerator.tsx

@@ -0,0 +1,35 @@
+import { useMemo } from 'react';
+import { createMCPServerConfig, type PlatformType } from './mcp-helper';
+import CursorLogo from '@/assets/logos/cursor.svg?react';
+import { getBackendUrl } from '@/lib/utils/utils';
+
+interface CursorDeeplinkGeneratorProps {
+  apiKey?: string;
+  os?: PlatformType;
+}
+
+export function CursorDeeplinkGenerator({
+  apiKey,
+  os = 'macos-linux',
+}: CursorDeeplinkGeneratorProps) {
+  const deeplink = useMemo(() => {
+    const config = createMCPServerConfig(apiKey || '', os, getBackendUrl());
+    const configString = JSON.stringify(config);
+    const base64Config = btoa(configString);
+    return `cursor://anysphere.cursor-deeplink/mcp/install?name=insforge&config=${encodeURIComponent(base64Config)}`;
+  }, [apiKey, os]);
+
+  const handleOpenInCursor = () => {
+    window.open(deeplink, '_blank');
+  };
+
+  return (
+    <button
+      onClick={handleOpenInCursor}
+      className="bg-black py-2 px-4 flex items-center justify-center gap-2.5 rounded-md text-white text-sm font-medium"
+    >
+      <CursorLogo className="h-6 w-6" />
+      <span>Add to Cursor</span>
+    </button>
+  );
+}

package/frontend/src/features/onboard/components/mcp/McpInstallation.tsx

@@ -0,0 +1,144 @@
+import { useState, useMemo } from 'react';
+import { cn, getBackendUrl } from '@/lib/utils/utils';
+import { CodeBlock } from '@/components/CodeBlock';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/radix/Tabs';
+import { Alert, AlertDescription } from '@/components/radix/Alert';
+import { JsonHighlight } from '@/components/JsonHighlight';
+import { CursorDeeplinkGenerator } from './CursorDeeplinkGenerator';
+import {
+  MCP_AGENTS,
+  createMCPConfig,
+  GenerateInstallCommand,
+  type MCPAgent,
+  type PlatformType,
+} from './mcp-helper';
+import { useApiKey } from '@/features/metadata/hooks/useMetadata';
+
+interface McpInstallerProps {
+  className?: string;
+  defaultAgent?: string;
+  TabListClassName?: string;
+}
+
+export function McpInstallation({
+  className,
+  defaultAgent = 'cursor',
+  TabListClassName,
+}: McpInstallerProps) {
+  const [selectedAgent, setSelectedAgent] = useState<MCPAgent>(() => {
+    return MCP_AGENTS.find((agent) => agent.id === defaultAgent) || MCP_AGENTS[0];
+  });
+  const [activeTab, setActiveTab] = useState<PlatformType>('macos-linux');
+
+  const { apiKey } = useApiKey();
+
+  const handleTabChange = (value: string) => {
+    setActiveTab(value as PlatformType);
+  };
+
+  const mcpConfig = useMemo(() => {
+    return createMCPConfig(apiKey || '', activeTab, getBackendUrl());
+  }, [apiKey, activeTab]);
+
+  return (
+    <div className={cn('w-full flex flex-col gap-2 overflow-hidden', className)}>
+      {/* Agent Tabs */}
+      <Tabs
+        value={selectedAgent.id}
+        onValueChange={(value) => {
+          const agent = MCP_AGENTS.find((a) => a.id === value);
+          if (agent) {
+            setSelectedAgent(agent);
+          }
+        }}
+      >
+        <TabsList
+          className={cn(
+            'grid w-full grid-cols-7 bg-neutral-200 dark:bg-neutral-900 p-1 rounded-lg h-fit mb-2',
+            TabListClassName
+          )}
+        >
+          {MCP_AGENTS.map((agent) => (
+            <TabsTrigger
+              key={agent.id}
+              value={agent.id}
+              className="rounded-sm px-4 py-2 text-sm font-normal transition-all duration-200 flex flex-row items-center justify-start gap-1
+                data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-700 dark:data-[state=active]:text-white data-[state=active]:text-gray-900 data-[state=active]:shadow-sm
+                data-[state=inactive]:text-gray-600 dark:data-[state=inactive]:text-neutral-400 data-[state=inactive]:hover:text-gray-900"
+            >
+              {agent.logo}
+              {agent.displayName}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+
+        {/* Content for each agent */}
+        {MCP_AGENTS.map((agent) => (
+          <TabsContent key={agent.id} value={agent.id} className="mt-0">
+            {agent.id !== 'mcp' ? (
+              <div className="bg-white dark:bg-neutral-700 px-6 py-8 flex flex-col items-start justify-start gap-4 rounded-xl border border-border-gray dark:border-neutral-700">
+                {agent.id === 'cursor' && (
+                  <CursorDeeplinkGenerator apiKey={apiKey} os={activeTab} />
+                )}
+                {/* Alternative Installation */}
+                <p className="text-zinc-950 dark:text-neutral-300 text-sm">
+                  {agent.id === 'cursor' ? 'or copy' : 'Copy'} the command below and paste it to
+                  terminal
+                </p>
+                {/* Command Block */}
+                <CodeBlock
+                  code={GenerateInstallCommand(agent, apiKey || '')}
+                  className="bg-slate-50 dark:bg-neutral-800 w-full font-normal text-blue-800 dark:text-blue-400"
+                />
+              </div>
+            ) : (
+              <div className="px-6 py-8 bg-white dark:bg-neutral-800 overflow-hidden rounded-xl border border-border-gray dark:border-neutral-700">
+                <p className="text-zinc-950 dark:text-white text-sm mb-3">
+                  Copy the configuration below and add it to your AI assistant.
+                </p>
+
+                {/* OS Tabs */}
+                <div className="flex items-center justify-between">
+                  <Tabs value={activeTab} onValueChange={handleTabChange} className="w-full">
+                    <TabsList className="grid w-60 grid-cols-2 bg-gray-100 dark:bg-neutral-900 p-1.5 rounded-lg h-fit">
+                      <TabsTrigger
+                        value="macos-linux"
+                        className="h-7 rounded-sm px-3 py-1 text-sm font-medium transition-all duration-200
+                          data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-700 dark:data-[state=active]:text-white data-[state=active]:text-gray-900 data-[state=active]:shadow-sm
+                          data-[state=inactive]:text-gray-600 dark:data-[state=inactive]:text-neutral-400 data-[state=inactive]:hover:text-gray-900"
+                      >
+                        MacOS/Linux
+                      </TabsTrigger>
+                      <TabsTrigger
+                        value="windows"
+                        className="h-7 rounded-sm px-3 py-1 text-sm font-medium transition-all duration-200
+                          data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-700 dark:data-[state=active]:text-white data-[state=active]:text-gray-900 data-[state=active]:shadow-sm
+                          data-[state=inactive]:text-gray-600 dark:data-[state=inactive]:text-neutral-400 data-[state=inactive]:hover:text-gray-900"
+                      >
+                        Windows
+                      </TabsTrigger>
+                    </TabsList>
+                  </Tabs>
+                </div>
+
+                {/* Configuration content */}
+                <div className="mt-1">
+                  {!apiKey && (
+                    <Alert className="border-yellow-200 bg-yellow-50 mb-4">
+                      <AlertDescription className="text-yellow-800">
+                        No API key found. Please ensure the backend is running and you&apos;re
+                        logged in as an admin.
+                      </AlertDescription>
+                    </Alert>
+                  )}
+
+                  <JsonHighlight json={JSON.stringify(mcpConfig, null, 2)} />
+                </div>
+              </div>
+            )}
+          </TabsContent>
+        ))}
+      </Tabs>
+    </div>
+  );
+}

package/frontend/src/features/onboard/components/mcp/index.ts

@@ -0,0 +1,4 @@
+export { McpInstallation } from './McpInstallation';
+export { CursorDeeplinkGenerator } from './CursorDeeplinkGenerator';
+export type { MCPAgent, PlatformType } from './mcp-helper';
+export { MCP_AGENTS, createMCPConfig, createMCPServerConfig } from './mcp-helper';

package/frontend/src/features/onboard/components/mcp/mcp-helper.tsx

@@ -0,0 +1,98 @@
+import { ReactElement } from 'react';
+export interface MCPAgent {
+  id: string;
+  displayName: string;
+  logo?: ReactElement;
+}
+
+import TraeLogo from '@/assets/logos/trae.svg?react';
+import CursorLogo from '@/assets/logos/cursor.svg?react';
+import ClaudeLogo from '@/assets/logos/claude_code.svg?react';
+import WindsurfLogo from '@/assets/logos/windsurf.svg?react';
+import ClineLogo from '@/assets/logos/cline.svg?react';
+import RooCodeLogo from '@/assets/logos/roo_code.svg';
+import { getBackendUrl } from '@/lib/utils/utils';
+// import CodexLogo from '@/assets/logos/openai.svg?react';
+
+export type PlatformType = 'macos-linux' | 'windows';
+
+export const GenerateInstallCommand = (agent: MCPAgent, apiKey: string) => {
+  return `npx @insforge/install --client ${agent.id} --env API_KEY=${apiKey} --env API_BASE_URL=${getBackendUrl()}`;
+};
+
+export const MCP_AGENTS: MCPAgent[] = [
+  {
+    id: 'trae',
+    displayName: 'Trae',
+    logo: <TraeLogo className="w-6 h-6" />,
+  },
+  {
+    id: 'cursor',
+    displayName: 'Cursor',
+    logo: <CursorLogo className="w-6 h-6" />,
+  },
+  {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    logo: <ClaudeLogo className="w-6 h-6" />,
+  },
+  {
+    id: 'windsurf',
+    displayName: 'Windsurf',
+    logo: <WindsurfLogo className="w-6 h-6 dark:text-white" />,
+  },
+  {
+    id: 'cline',
+    displayName: 'Cline',
+    logo: <ClineLogo className="w-6 h-6 dark:text-white" />,
+  },
+  {
+    id: 'roocode',
+    displayName: 'Roo Code',
+    logo: <img src={RooCodeLogo} alt="" className="dark:invert" />,
+  },
+  // {
+  //   id: 'codex',
+  //   displayName: 'Codex',
+  //   logo: <CodexLogo className="w-5 h-5 dark:text-white" />,
+  // },
+  {
+    id: 'mcp',
+    displayName: 'MCP JSON',
+  },
+];
+
+// Core MCP server configuration builder
+export const createMCPServerConfig = (
+  apiKey: string,
+  platform: PlatformType,
+  apiBaseUrl?: string
+) => {
+  const env = {
+    API_KEY: apiKey,
+    API_BASE_URL: apiBaseUrl || window.location.origin,
+  };
+
+  if (platform === 'windows') {
+    return {
+      command: 'cmd',
+      args: ['/c', 'npx', '-y', '@insforge/mcp@latest'],
+      env,
+    };
+  } else {
+    return {
+      command: 'npx',
+      args: ['-y', '@insforge/mcp@latest'],
+      env,
+    };
+  }
+};
+
+// Full MCP configuration for AI assistants
+export const createMCPConfig = (apiKey: string, platform: PlatformType, apiBaseUrl?: string) => {
+  return {
+    mcpServers: {
+      insforge: createMCPServerConfig(apiKey, platform, apiBaseUrl),
+    },
+  };
+};

package/frontend/src/features/onboard/index.ts

@@ -0,0 +1,3 @@
+export { OnboardStep } from './types';
+export { StepContent } from './components/StepContent';
+export { TestConnectionStep } from './components/TestConnectionStep';

package/frontend/src/features/onboard/page/OnBoardPage.tsx

@@ -0,0 +1,104 @@
+import { useState, useEffect } from 'react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { Button } from '@/components/radix/Button';
+import { useOnboardStep, STEP_DESCRIPTIONS } from '@/lib/contexts/OnboardStepContext';
+import { type OnboardStep } from '../types';
+import { LinearStepper } from '@/components/Stepper';
+import { StepContent } from '../components/StepContent';
+import { CompletionCard } from '../components/CompletionCard';
+
+export default function OnBoardPage() {
+  const navigate = useNavigate();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { currentStep, updateStep, totalSteps } = useOnboardStep();
+  const [isCompleted, setIsCompleted] = useState(false);
+
+  // Handle reinstall with step parameter
+  useEffect(() => {
+    const stepParam = searchParams.get('step');
+    if (stepParam === '1') {
+      updateStep(1);
+      setIsCompleted(false);
+      setSearchParams({});
+    }
+  }, [searchParams, setSearchParams, updateStep]);
+
+  const handleDismiss = async () => {
+    await navigate('/dashboard');
+  };
+
+  const handleNext = () => {
+    if (currentStep < totalSteps) {
+      updateStep((currentStep + 1) as OnboardStep);
+    } else if (currentStep === totalSteps) {
+      setIsCompleted(true);
+    }
+  };
+
+  const handleBack = () => {
+    if (currentStep > 1) {
+      updateStep((currentStep - 1) as OnboardStep);
+    }
+  };
+
+  return (
+    <div className="min-h-screen bg-bg-gray dark:bg-neutral-900">
+      <div className="container max-w-[1080px] mx-auto px-6 py-12">
+        {/* Header with Linear Stepper */}
+        <div className="mb-12 space-y-3">
+          <h1 className="text-2xl font-bold text-black dark:text-white">Get Started</h1>
+          <LinearStepper
+            currentStep={currentStep}
+            totalSteps={totalSteps}
+            stepLabels={STEP_DESCRIPTIONS}
+            isCompleted={isCompleted}
+          />
+        </div>
+
+        {/* Main Content Card */}
+        {isCompleted ? (
+          <CompletionCard />
+        ) : (
+          <div className="space-y-3">
+            <p className="text-black dark:text-white text-lg font-semibold">
+              {STEP_DESCRIPTIONS[currentStep - 1]}
+            </p>
+            <StepContent step={currentStep} />
+
+            {/* Action Buttons */}
+            <div className="flex justify-between items-center">
+              {/* Dismiss Button - Left */}
+              <Button
+                variant="outline"
+                onClick={() => void handleDismiss()}
+                className="h-10 w-30 py-2 text-zinc-950 dark:text-white dark:border-neutral-700 dark:bg-neutral-700"
+              >
+                Dismiss
+              </Button>
+
+              {/* Navigation Buttons - Right */}
+              <div className="flex space-x-4">
+                {currentStep > 1 && (
+                  <Button
+                    variant="outline"
+                    onClick={() => void handleBack()}
+                    className="h-10 w-30 text-zinc-950 dark:text-white dark:border-neutral-700 dark:bg-neutral-700"
+                  >
+                    Back
+                  </Button>
+                )}
+                <Button
+                  variant="default"
+                  onClick={() => void handleNext()}
+                  className="h-10 w-30 dark:bg-emerald-300 dark:text-black dark:hover:bg-emerald-200 disabled:opacity-50 disabled:cursor-not-allowed"
+                >
+                  {currentStep === totalSteps ? 'Complete' : 'Next'}
+                </Button>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/frontend/src/features/onboard/types.ts

@@ -0,0 +1,8 @@
+export enum OnboardStep {
+  INSTALL_NODEJS = 1,
+  INSTALL_MCP = 2,
+  TEST_CONNECTION = 3,
+  FINAL_SETUP = 4,
+}
+
+export const TOTAL_STEPS = Object.keys(OnboardStep).filter((key) => !isNaN(Number(key))).length;