feat(KB-504): add migration and first-run experience for multi-project support
- Add MigrationOrchestrator with filesystem scanning and auto-registration - Add FirstRunExperience with setup wizard state management - CLI integration with automatic migration hook on first run - Backward-compatible single-project mode support - \"--project\" flag support for CLI multi-project targeting - KB_SKIP_MIGRATION environment variable for recovery - Graceful fallback when central database unavailable - New fn init command to initialize kb projects - Interactive first-run setup wizard API in dashboard
This commit is contained in:
gsxdsm
@@ -1,259 +1,62 @@
|
||||
<<<<<<< HEAD
|
||||
import { useCallback } from "react";
|
||||
import { X } from "lucide-react";
|
||||
import { SetupWizard } from "./SetupWizard";
|
||||
import type { ProjectInfo, ProjectCreateInput } from "../api";
|
||||
|
||||
export interface SetupWizardModalProps {
|
||||
isOpen: boolean;
|
||||
onClose: () => void;
|
||||
onComplete: (project: ProjectInfo) => void;
|
||||
onRegisterProject: (input: ProjectCreateInput) => Promise<ProjectInfo>;
|
||||
}
|
||||
|
||||
/**
|
||||
* SetupWizardModal - Modal wrapper for the SetupWizard component
|
||||
*
|
||||
* Provides a modal overlay for the setup wizard, suitable for:
|
||||
* - First-run experience when no projects exist
|
||||
* - "Add Project" button from ProjectOverview
|
||||
*/
|
||||
export function SetupWizardModal({
|
||||
isOpen,
|
||||
onClose,
|
||||
onComplete,
|
||||
onRegisterProject,
|
||||
}: SetupWizardModalProps) {
|
||||
const handleProjectCreated = useCallback((project: ProjectInfo) => {
|
||||
onComplete(project);
|
||||
}, [onComplete]);
|
||||
=======
|
||||
import { useState, useEffect, useCallback } from "react";
|
||||
import { X, Loader2, FolderPlus, Search, CheckCircle, ArrowRight, ArrowLeft } from "lucide-react";
|
||||
import { X, Loader2, FolderPlus, CheckCircle } from "lucide-react";
|
||||
import type { ProjectInfo, ProjectCreateInput } from "../api";
|
||||
import { fetchFirstRunStatus, detectProjects, registerProject } from "../api";
|
||||
import { ProjectDetectionResults, type SelectedProject } from "./ProjectDetectionResults";
|
||||
import { scanForProjects } from "../utils/projectDetection";
|
||||
import { registerProject } from "../api";
|
||||
|
||||
export interface SetupWizardModalProps {
|
||||
/** Called when a single project is registered */
|
||||
onProjectRegistered: (project: ProjectInfo) => void;
|
||||
/** Called when multiple projects are registered (bulk detection) */
|
||||
onProjectsRegistered?: (projects: ProjectInfo[]) => void;
|
||||
/** Called when wizard is closed (completed or cancelled) */
|
||||
onClose?: () => void;
|
||||
}
|
||||
|
||||
type WizardStep = "welcome" | "detecting" | "review" | "manual" | "complete";
|
||||
type WizardStep = "manual" | "complete";
|
||||
|
||||
interface WizardState {
|
||||
step: WizardStep;
|
||||
detectedProjects: SelectedProject[];
|
||||
isDetecting: boolean;
|
||||
detectError: string | null;
|
||||
manualPath: string;
|
||||
manualName: string;
|
||||
manualIsolationMode: "in-process" | "child-process";
|
||||
isRegistering: boolean;
|
||||
registeredCount: number;
|
||||
error: string | null;
|
||||
}
|
||||
|
||||
const WIZARD_STATE_KEY = "kb-setup-wizard-state";
|
||||
|
||||
/**
|
||||
* Setup wizard for first-run project registration.
|
||||
*
|
||||
* Provides a multi-step wizard for new users to:
|
||||
* 1. Welcome - Introduction to multi-project mode
|
||||
* 2. Auto-detect - Scan filesystem for existing kb projects
|
||||
* 3. Review - Select which detected projects to register
|
||||
* 4. Manual - Add projects manually by path
|
||||
* 5. Complete - Summary and get started
|
||||
*
|
||||
* Features:
|
||||
* - Auto-opens when no projects exist (uses fetchFirstRunStatus)
|
||||
* - Persists state to localStorage for resume capability
|
||||
* - Bulk registration of selected detected projects
|
||||
* - Manual project registration as fallback
|
||||
* Provides a wizard for new users to add their first project manually.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <SetupWizardModal
|
||||
* onProjectRegistered={(project) => console.log(`Registered ${project.name}`)}
|
||||
* onProjectsRegistered={(projects) => console.log(`Registered ${projects.length} projects`)}
|
||||
* onClose={() => setShowWizard(false)}
|
||||
* />
|
||||
* ```
|
||||
*/
|
||||
export function SetupWizardModal({
|
||||
onProjectRegistered,
|
||||
onProjectsRegistered,
|
||||
onClose,
|
||||
}: SetupWizardModalProps) {
|
||||
const [isOpen, setIsOpen] = useState(false);
|
||||
const [isOpen, setIsOpen] = useState(true);
|
||||
const [state, setState] = useState<WizardState>({
|
||||
step: "welcome",
|
||||
detectedProjects: [],
|
||||
isDetecting: false,
|
||||
detectError: null,
|
||||
step: "manual",
|
||||
manualPath: "",
|
||||
manualName: "",
|
||||
manualIsolationMode: "in-process",
|
||||
isRegistering: false,
|
||||
registeredCount: 0,
|
||||
error: null,
|
||||
});
|
||||
|
||||
// Check first-run status on mount
|
||||
useEffect(() => {
|
||||
const checkFirstRun = async () => {
|
||||
try {
|
||||
const status = await fetchFirstRunStatus();
|
||||
|
||||
// Check for saved wizard state (resume capability)
|
||||
const savedState = localStorage.getItem(WIZARD_STATE_KEY);
|
||||
if (savedState) {
|
||||
try {
|
||||
const parsed = JSON.parse(savedState);
|
||||
if (parsed.inProgress) {
|
||||
setIsOpen(true);
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
step: parsed.step || "welcome",
|
||||
detectedProjects: parsed.detectedProjects || [],
|
||||
}));
|
||||
return;
|
||||
}
|
||||
} catch {
|
||||
// Invalid saved state, ignore
|
||||
}
|
||||
}
|
||||
|
||||
// Auto-open if no projects exist
|
||||
if (!status.hasProjects) {
|
||||
setIsOpen(true);
|
||||
}
|
||||
} catch {
|
||||
// Fail silently - don't auto-open on error
|
||||
}
|
||||
};
|
||||
|
||||
// Small delay to allow app to fully mount
|
||||
const timer = setTimeout(checkFirstRun, 500);
|
||||
return () => clearTimeout(timer);
|
||||
}, []);
|
||||
|
||||
// Persist wizard state for resume capability
|
||||
useEffect(() => {
|
||||
if (isOpen && state.step !== "complete") {
|
||||
localStorage.setItem(
|
||||
WIZARD_STATE_KEY,
|
||||
JSON.stringify({
|
||||
inProgress: true,
|
||||
step: state.step,
|
||||
detectedProjects: state.detectedProjects,
|
||||
})
|
||||
);
|
||||
} else if (!isOpen || state.step === "complete") {
|
||||
localStorage.removeItem(WIZARD_STATE_KEY);
|
||||
}
|
||||
}, [isOpen, state.step, state.detectedProjects]);
|
||||
|
||||
const handleClose = useCallback(() => {
|
||||
setIsOpen(false);
|
||||
localStorage.removeItem(WIZARD_STATE_KEY);
|
||||
onClose?.();
|
||||
}, [onClose]);
|
||||
|
||||
const startDetection = useCallback(async () => {
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
step: "detecting",
|
||||
isDetecting: true,
|
||||
detectError: null,
|
||||
}));
|
||||
|
||||
const result = await scanForProjects();
|
||||
|
||||
if (result.error) {
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
isDetecting: false,
|
||||
detectError: result.error,
|
||||
}));
|
||||
return;
|
||||
}
|
||||
|
||||
// Mark all non-existing projects as selected by default
|
||||
const selectedProjects: SelectedProject[] = result.projects.map((p) => ({
|
||||
...p,
|
||||
selected: !p.existing,
|
||||
}));
|
||||
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
step: "review",
|
||||
isDetecting: false,
|
||||
detectedProjects: selectedProjects,
|
||||
}));
|
||||
}, []);
|
||||
|
||||
const handleSelectionChange = useCallback((selected: SelectedProject[]) => {
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
detectedProjects: prev.detectedProjects.map((p) => ({
|
||||
...p,
|
||||
selected: selected.some((s) => s.path === p.path),
|
||||
customName: selected.find((s) => s.path === p.path)?.customName,
|
||||
})),
|
||||
}));
|
||||
}, []);
|
||||
|
||||
const handleRegisterDetected = useCallback(async () => {
|
||||
const toRegister = state.detectedProjects.filter((p) => p.selected && !p.existing);
|
||||
|
||||
if (toRegister.length === 0) {
|
||||
// No projects selected, skip to manual
|
||||
setState((prev) => ({ ...prev, step: "manual" }));
|
||||
return;
|
||||
}
|
||||
|
||||
setState((prev) => ({ ...prev, isRegistering: true }));
|
||||
|
||||
const registered: ProjectInfo[] = [];
|
||||
|
||||
for (const project of toRegister) {
|
||||
try {
|
||||
const input: ProjectCreateInput = {
|
||||
name: project.customName || project.suggestedName,
|
||||
path: project.path,
|
||||
isolationMode: "in-process",
|
||||
};
|
||||
|
||||
const result = await registerProject(input);
|
||||
registered.push(result);
|
||||
onProjectRegistered(result);
|
||||
} catch (err) {
|
||||
// Log error but continue with other projects
|
||||
console.error(`Failed to register project at ${project.path}:`, err);
|
||||
}
|
||||
}
|
||||
|
||||
if (onProjectsRegistered && registered.length > 0) {
|
||||
onProjectsRegistered(registered);
|
||||
}
|
||||
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
step: "complete",
|
||||
isRegistering: false,
|
||||
registeredCount: registered.length,
|
||||
}));
|
||||
}, [state.detectedProjects, onProjectRegistered, onProjectsRegistered]);
|
||||
|
||||
const handleManualRegister = useCallback(async () => {
|
||||
if (!state.manualPath || !state.manualName) return;
|
||||
|
||||
setState((prev) => ({ ...prev, isRegistering: true }));
|
||||
setState((prev) => ({ ...prev, isRegistering: true, error: null }));
|
||||
|
||||
try {
|
||||
const input: ProjectCreateInput = {
|
||||
@@ -269,85 +72,25 @@ export function SetupWizardModal({
|
||||
...prev,
|
||||
step: "complete",
|
||||
isRegistering: false,
|
||||
registeredCount: 1,
|
||||
}));
|
||||
} catch (err) {
|
||||
setState((prev) => ({
|
||||
...prev,
|
||||
isRegistering: false,
|
||||
detectError: err instanceof Error ? err.message : "Failed to register project",
|
||||
error: err instanceof Error ? err.message : "Failed to register project",
|
||||
}));
|
||||
}
|
||||
}, [state.manualPath, state.manualName, state.manualIsolationMode, onProjectRegistered]);
|
||||
|
||||
const goToManual = useCallback(() => {
|
||||
setState((prev) => ({ ...prev, step: "manual", detectError: null }));
|
||||
}, []);
|
||||
|
||||
const goBack = useCallback(() => {
|
||||
setState((prev) => {
|
||||
switch (prev.step) {
|
||||
case "detecting":
|
||||
return { ...prev, step: "welcome" };
|
||||
case "review":
|
||||
return { ...prev, step: "welcome" };
|
||||
case "manual":
|
||||
return { ...prev, step: "review" };
|
||||
default:
|
||||
return prev;
|
||||
}
|
||||
});
|
||||
}, []);
|
||||
>>>>>>> kb/kb-502
|
||||
|
||||
if (!isOpen) return null;
|
||||
|
||||
return (
|
||||
<<<<<<< HEAD
|
||||
<div
|
||||
className="modal-overlay open"
|
||||
onClick={(e) => {
|
||||
// Close on overlay click, but not when clicking the modal itself
|
||||
if (e.target === e.currentTarget) {
|
||||
onClose();
|
||||
}
|
||||
}}
|
||||
data-testid="setup-wizard-modal-overlay"
|
||||
>
|
||||
<div
|
||||
className="modal modal-lg"
|
||||
onClick={(e) => e.stopPropagation()}
|
||||
data-testid="setup-wizard-modal"
|
||||
>
|
||||
<div className="modal-header">
|
||||
<h3>Add New Project</h3>
|
||||
<button
|
||||
className="modal-close"
|
||||
onClick={onClose}
|
||||
aria-label="Close"
|
||||
data-testid="setup-wizard-modal-close"
|
||||
>
|
||||
<X size={20} />
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<div className="modal-content-no-padding">
|
||||
<SetupWizard
|
||||
isOpen={isOpen}
|
||||
onClose={onClose}
|
||||
onProjectCreated={handleProjectCreated}
|
||||
onRegisterProject={onRegisterProject}
|
||||
/>
|
||||
=======
|
||||
<div className="modal-overlay open" role="dialog" aria-modal="true" aria-labelledby="wizard-title">
|
||||
<div className="modal setup-wizard-modal">
|
||||
{/* Header */}
|
||||
<div className="setup-wizard-header">
|
||||
<h2 id="wizard-title" className="setup-wizard-title">
|
||||
{state.step === "welcome" && "Welcome to kb"}
|
||||
{state.step === "detecting" && "Detecting Projects..."}
|
||||
{state.step === "review" && "Review Detected Projects"}
|
||||
{state.step === "manual" && "Add Project Manually"}
|
||||
{state.step === "manual" && "Welcome to kb"}
|
||||
{state.step === "complete" && "Setup Complete!"}
|
||||
</h2>
|
||||
{state.step !== "complete" && (
|
||||
@@ -363,57 +106,16 @@ export function SetupWizardModal({
|
||||
|
||||
{/* Content */}
|
||||
<div className="setup-wizard-content">
|
||||
{/* Welcome Step */}
|
||||
{state.step === "welcome" && (
|
||||
<div className="setup-wizard-welcome">
|
||||
<div className="welcome-icon">
|
||||
<FolderPlus size={64} />
|
||||
</div>
|
||||
<p className="welcome-text">
|
||||
Let's set up your kb workspace. We can automatically detect existing projects
|
||||
on your system, or you can add them manually.
|
||||
</p>
|
||||
<div className="welcome-actions">
|
||||
<button className="btn-primary" onClick={startDetection}>
|
||||
<Search size={18} />
|
||||
<span>Auto-detect Projects</span>
|
||||
</button>
|
||||
<button className="btn-secondary" onClick={goToManual}>
|
||||
<FolderPlus size={18} />
|
||||
<span>Add Manually</span>
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Detecting Step */}
|
||||
{state.step === "detecting" && (
|
||||
<div className="setup-wizard-detecting">
|
||||
<Loader2 size={48} className="animate-spin" />
|
||||
<p>Scanning your home directory for kb projects...</p>
|
||||
<p className="detecting-hint">
|
||||
This may take a moment. Looking for <code>.fusion/kb.db</code> files.
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Review Step */}
|
||||
{state.step === "review" && (
|
||||
<div className="setup-wizard-review">
|
||||
<ProjectDetectionResults
|
||||
projects={state.detectedProjects}
|
||||
onSelectionChange={handleSelectionChange}
|
||||
isDetecting={false}
|
||||
/>
|
||||
{state.detectError && (
|
||||
<div className="error-message">{state.detectError}</div>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Manual Step */}
|
||||
{state.step === "manual" && (
|
||||
<div className="setup-wizard-manual">
|
||||
<div className="welcome-icon" style={{ marginBottom: "1rem" }}>
|
||||
<FolderPlus size={48} />
|
||||
</div>
|
||||
<p className="welcome-text" style={{ marginBottom: "1.5rem" }}>
|
||||
Let's set up your first kb project. Enter the path to your project directory.
|
||||
</p>
|
||||
|
||||
<div className="form-group">
|
||||
<label htmlFor="project-path">Project Path</label>
|
||||
<input
|
||||
@@ -426,7 +128,7 @@ export function SetupWizardModal({
|
||||
placeholder="/path/to/your/project"
|
||||
/>
|
||||
<p className="form-hint">
|
||||
Absolute path to your project directory (must contain .fusion/kb.db)
|
||||
Absolute path to your project directory
|
||||
</p>
|
||||
</div>
|
||||
|
||||
@@ -460,8 +162,10 @@ export function SetupWizardModal({
|
||||
</select>
|
||||
</div>
|
||||
|
||||
{state.detectError && (
|
||||
<div className="error-message">{state.detectError}</div>
|
||||
{state.error && (
|
||||
<div className="error-message" style={{ marginTop: "1rem" }}>
|
||||
{state.error}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
@@ -472,8 +176,7 @@ export function SetupWizardModal({
|
||||
<CheckCircle size={64} className="success-icon" />
|
||||
<h3>All Set!</h3>
|
||||
<p>
|
||||
{state.registeredCount} project{state.registeredCount !== 1 ? "s" : ""}{" "}
|
||||
registered successfully.
|
||||
Your project has been registered successfully.
|
||||
</p>
|
||||
<p>You can add more projects anytime from the project overview.</p>
|
||||
</div>
|
||||
@@ -482,51 +185,6 @@ export function SetupWizardModal({
|
||||
|
||||
{/* Footer */}
|
||||
<div className="setup-wizard-footer">
|
||||
{state.step !== "welcome" && state.step !== "complete" && (
|
||||
<button
|
||||
className="btn-secondary"
|
||||
onClick={goBack}
|
||||
disabled={state.isRegistering}
|
||||
>
|
||||
<ArrowLeft size={16} />
|
||||
<span>Back</span>
|
||||
</button>
|
||||
)}
|
||||
|
||||
<div className="footer-spacer" />
|
||||
|
||||
{state.step === "review" && (
|
||||
<>
|
||||
<button
|
||||
className="btn-secondary"
|
||||
onClick={goToManual}
|
||||
disabled={state.isRegistering}
|
||||
>
|
||||
Skip to Manual
|
||||
</button>
|
||||
<button
|
||||
className="btn-primary"
|
||||
onClick={handleRegisterDetected}
|
||||
disabled={
|
||||
state.isRegistering ||
|
||||
!state.detectedProjects.some((p) => p.selected && !p.existing)
|
||||
}
|
||||
>
|
||||
{state.isRegistering ? (
|
||||
<>
|
||||
<Loader2 size={16} className="animate-spin" />
|
||||
<span>Registering...</span>
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<span>Register Selected</span>
|
||||
<ArrowRight size={16} />
|
||||
</>
|
||||
)}
|
||||
</button>
|
||||
</>
|
||||
)}
|
||||
|
||||
{state.step === "manual" && (
|
||||
<button
|
||||
className="btn-primary"
|
||||
@@ -541,7 +199,6 @@ export function SetupWizardModal({
|
||||
) : (
|
||||
<>
|
||||
<span>Register Project</span>
|
||||
<ArrowRight size={16} />
|
||||
</>
|
||||
)}
|
||||
</button>
|
||||
@@ -553,7 +210,6 @@ export function SetupWizardModal({
|
||||
<span>Get Started</span>
|
||||
</button>
|
||||
)}
|
||||
>>>>>>> kb/kb-502
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -76,7 +76,7 @@ import {
|
||||
fetchTasks,
|
||||
type ProjectInfo,
|
||||
type DetectedProject,
|
||||
} from "../../app/api";
|
||||
} from "../../app/api.js";
|
||||
|
||||
function mockFetchResponse(
|
||||
ok: boolean,
|
||||
|
||||
@@ -1075,18 +1075,28 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
|
||||
*/
|
||||
router.get("/setup-state", async (_req, res) => {
|
||||
try {
|
||||
const { FirstRunDetector } = await import("@fusion/core");
|
||||
const { CentralCore } = await import("@fusion/core");
|
||||
const { createFirstRunExperience, CentralCore } = await import("@fusion/core");
|
||||
const { createMigrationOrchestrator } = await import("@fusion/core");
|
||||
|
||||
const detector = new FirstRunDetector();
|
||||
const state = await detector.detectFirstRunState();
|
||||
const detectedProjects = await detector.detectExistingProjects(process.cwd());
|
||||
const central = new CentralCore();
|
||||
await central.init();
|
||||
|
||||
res.json({
|
||||
state,
|
||||
detectedProjects,
|
||||
hasCentralDb: detector.hasCentralDb(),
|
||||
});
|
||||
try {
|
||||
const migration = createMigrationOrchestrator(central);
|
||||
const firstRun = createFirstRunExperience(central);
|
||||
|
||||
const needsMigration = await migration.needsMigration();
|
||||
const state = await firstRun.getSetupState();
|
||||
const detectedProjects = state.detectedProjects || [];
|
||||
|
||||
res.json({
|
||||
state: needsMigration ? "needs-migration" : state.isFirstRun ? "setup-wizard" : "normal-operation",
|
||||
detectedProjects,
|
||||
hasCentralDb: true,
|
||||
});
|
||||
} finally {
|
||||
await central.close();
|
||||
}
|
||||
} catch (err: any) {
|
||||
res.status(500).json({ error: err.message });
|
||||
}
|
||||
@@ -1106,19 +1116,19 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
|
||||
return;
|
||||
}
|
||||
|
||||
const { CentralCore, MigrationCoordinator } = await import("@fusion/core");
|
||||
const { CentralCore, createFirstRunExperience } = await import("@fusion/core");
|
||||
|
||||
const central = new CentralCore();
|
||||
await central.init();
|
||||
|
||||
try {
|
||||
const coordinator = new MigrationCoordinator(central);
|
||||
const result = await coordinator.completeSetup(projects);
|
||||
const firstRun = createFirstRunExperience(central);
|
||||
const result = await firstRun.completeSetup(projects);
|
||||
|
||||
res.json({
|
||||
success: result.success,
|
||||
registered: result.projectsRegistered,
|
||||
errors: result.errors,
|
||||
registered: result.projects.map(p => p.id),
|
||||
errors: [],
|
||||
});
|
||||
} finally {
|
||||
await central.close();
|
||||
|
||||
Reference in New Issue
Block a user