@kispace-io/extension-howto-system 0.8.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@kispace-io/extension-howto-system",
+  "version": "0.8.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@kispace-io/core": "*",
+    "@kispace-io/extension-ai-system": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/README.md

@@ -0,0 +1,249 @@
+# HowTo System Extension
+
+The HowTo System provides a framework for creating step-by-step workflows that guide users through specific processes. It features a floating, draggable UI panel that displays workflows with pre and post condition checks.
+
+## Features
+
+- **Register HowToContributions**: Extensions can register workflows with multiple steps
+- **Floating UI Panel**: Always-on-top, draggable panel that hosts the workflow steps
+- **Sequential Step Execution**: Steps are executed one at a time in order
+- **Pre and Post Conditions**: Each step can have conditions that check requirements and outcomes
+- **Step Status Tracking**: Visual indicators show step status (pending, active, completed, failed, skipped)
+
+## Usage
+
+### Registering a HowTo Contribution
+
+From any extension, you can register a HowTo contribution via the contribution registry:
+
+```typescript
+import { contributionRegistry } from '../../core/contributionregistry';
+import { HOWTO_CONTRIBUTION_TARGET } from '../../extensions/howto-system/howto-extension';
+import type { HowToContribution } from '../../extensions/howto-system/howto-extension';
+
+export default function myExtension({ contributionRegistry }: any) {
+    // Register a HowTo contribution
+    contributionRegistry.registerContribution<HowToContribution>(HOWTO_CONTRIBUTION_TARGET, {
+        id: 'my-extension.setup-workspace',
+        title: 'Setup Workspace',
+        description: 'Guide to set up your workspace for the first time',
+        icon: 'folder-open',
+        label: 'Setup Workspace', // Required by Contribution interface
+        steps: [
+            {
+                id: 'step-1',
+                title: 'Create Project Folder',
+                description: 'Create a new folder for your project',
+                preCondition: async () => {
+                    // Check if workspace is selected
+                    const workspace = await workspaceService.getWorkspace();
+                    return workspace !== undefined;
+                },
+                postCondition: async () => {
+                    // Check if project folder exists
+                    const workspace = await workspaceService.getWorkspace();
+                    if (!workspace) return false;
+                    const projectFolder = await workspace.getChild('my-project');
+                    return projectFolder !== undefined;
+                },
+                command: 'workspace.create-folder',
+                commandParams: { name: 'my-project' }
+            },
+            {
+                id: 'step-2',
+                title: 'Initialize Configuration',
+                description: 'Create a configuration file',
+                preCondition: async () => {
+                    // Previous step must be completed
+                    return true; // This will be checked automatically
+                },
+                postCondition: async () => {
+                    const workspace = await workspaceService.getWorkspace();
+                    if (!workspace) return false;
+                    const configFile = await workspace.getChild('config.json');
+                    return configFile !== undefined;
+                },
+                command: 'workspace.create-file',
+                commandParams: { name: 'config.json', content: '{}' }
+            }
+        ]
+    });
+}
+```
+
+### Using Conditions
+
+Conditions are functions that return a boolean or Promise<boolean>:
+
+```typescript
+// Simple synchronous condition
+preCondition: () => {
+    return someVariable === true;
+}
+
+// Async condition
+preCondition: async () => {
+    const result = await someAsyncCheck();
+    return result.isValid;
+}
+
+// Condition with error handling
+postCondition: async () => {
+    try {
+        const file = await workspaceService.getFile('path/to/file');
+        return file !== undefined;
+    } catch {
+        return false;
+    }
+}
+```
+
+### Step Commands
+
+Steps can optionally execute commands when activated:
+
+```typescript
+{
+    id: 'step-1',
+    title: 'Open Editor',
+    description: 'Open the code editor',
+    command: 'editor.open',
+    commandParams: {
+        file: 'src/main.ts'
+    }
+}
+```
+
+### Optional Steps
+
+Steps can be marked as optional, allowing users to skip them:
+
+```typescript
+{
+    id: 'step-3',
+    title: 'Install Dependencies (Optional)',
+    description: 'Install optional dependencies',
+    optional: true,
+    // ...
+}
+```
+
+## HowTo Panel UI
+
+The floating panel provides:
+
+- **Workflow List**: Shows all registered workflows
+- **Step List**: Displays all steps in the active workflow
+- **Status Indicators**: Visual feedback for each step's status
+- **Condition Checks**: Shows whether pre/post conditions are met
+- **Action Buttons**: Execute or skip steps
+- **Drag to Move**: Click and drag the header to reposition
+
+### Showing the Panel
+
+The panel is hidden by default. You can show it using:
+
+1. **Toolbar Button**: Click the "HowTo" button in the bottom right toolbar
+2. **Keyboard Shortcut**: Press `Ctrl+Shift+H` to toggle the panel
+3. **Command**: Execute the `howto.show-panel` or `howto.toggle-panel` command
+4. **Command Palette**: Search for "Show HowTo Panel" or "Toggle HowTo Panel"
+
+The panel visibility state is persisted in localStorage, so it will remember whether it was visible when you reload the page.
+
+## API Reference
+
+### HowToService
+
+The HowToService manages HowTo contributions by reading from the contribution registry:
+
+```typescript
+class HowToService {
+    // Get a contribution by ID
+    getContribution(contributionId: string): HowToContribution | undefined;
+    
+    // Get all contributions
+    getAllContributions(): HowToContribution[];
+    
+    // Get contributions by category
+    getContributionsByCategory(category: string): HowToContribution[];
+    
+    // Check if a contribution exists
+    hasContribution(contributionId: string): boolean;
+}
+```
+
+The service is registered in the dependency injection context and can be accessed via:
+
+```typescript
+export default function myExtension({ howToService }: any) {
+    const contributions = howToService.getAllContributions();
+}
+```
+
+Or imported directly:
+
+```typescript
+import { howToService } from '../../extensions/howto-system/howto-extension';
+```
+
+### HowToContribution
+
+```typescript
+interface HowToContribution {
+    id: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+    steps: HowToStep[];
+}
+```
+
+### HowToStep
+
+```typescript
+interface HowToStep {
+    id: string;
+    title: string;
+    description: string;
+    preCondition?: ConditionFunction;
+    postCondition?: ConditionFunction;
+    command?: string;
+    commandParams?: Record<string, any>;
+    optional?: boolean;
+}
+```
+
+### ConditionFunction
+
+```typescript
+type ConditionFunction = () => Promise<boolean> | boolean;
+```
+
+## Events
+
+The system uses the contribution registry's events. Subscribe to contribution changes:
+
+```typescript
+import { TOPIC_CONTRIBUTEIONS_CHANGED } from '../../core/contributionregistry';
+import { HOWTO_CONTRIBUTION_TARGET } from '../../extensions/howto-system/howto-extension';
+import { subscribe } from '../../core/events';
+
+subscribe(TOPIC_CONTRIBUTEIONS_CHANGED, (event) => {
+    if (event.target === HOWTO_CONTRIBUTION_TARGET) {
+        console.log('HowTo contributions changed:', event.contributions);
+    }
+});
+```
+
+## Contribution Target
+
+All HowTo contributions must be registered to the target:
+
+```typescript
+import { HOWTO_CONTRIBUTION_TARGET } from '../../extensions/howto-system/howto-extension';
+
+// Use this constant when registering contributions
+contributionRegistry.registerContribution(HOWTO_CONTRIBUTION_TARGET, contribution);
+```
+

package/src/contributions/ai-setup-howto-contributions.ts

@@ -0,0 +1,205 @@
+import { contributionRegistry, activeEditorSignal, partDirtySignal, subscribe, appLoaderService, appSettings } from '@kispace-io/core';
+import type { EditorContentProvider } from '@kispace-io/core';
+import { watchSignal } from '@kispace-io/core';
+import { HOWTO_CONTRIBUTION_TARGET } from '../howto-service';
+import type { HowToContribution, HowToContext } from '../howto-contribution';
+import { KEY_AI_CONFIG, TOPIC_AICONFIG_CHANGED } from '@kispace-io/extension-ai-system';
+import type { AIConfig } from '@kispace-io/extension-ai-system';
+
+const AI_CONFIG_EDITOR_KEY = '.system.ai-config';
+
+/**
+ * Type guard to check if an editor implements EditorContentProvider
+ */
+function isEditorContentProvider(editor: any): editor is EditorContentProvider {
+    return editor &&
+        typeof editor.getFilePath === 'function';
+}
+
+/**
+ * Checks if the AI config editor is open
+ */
+function isAIConfigEditorOpen(): boolean {
+    const activeEditor = activeEditorSignal.get();
+    if (!activeEditor || !isEditorContentProvider(activeEditor)) {
+        return false;
+    }
+    
+    const filePath = activeEditor.getFilePath();
+    return filePath === AI_CONFIG_EDITOR_KEY;
+}
+
+/**
+ * Checks if an LLM provider is configured (has default provider with API key)
+ */
+async function isLLMProviderConfigured(): Promise<boolean> {
+    try {
+        const config = await appSettings.get(KEY_AI_CONFIG) as AIConfig | undefined;
+        if (!config || !config.defaultProvider) {
+            return false;
+        }
+        
+        const defaultProvider = config.providers?.find(p => p.name === config.defaultProvider);
+        if (!defaultProvider) {
+            return false;
+        }
+        
+        // Check if API key is set (not empty)
+        return !!defaultProvider.apiKey && defaultProvider.apiKey.trim() !== '';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Checks if the AI config editor has unsaved changes
+ */
+function isAIConfigEditorDirty(): boolean {
+    const activeEditor = activeEditorSignal.get();
+    if (!activeEditor || !isEditorContentProvider(activeEditor)) {
+        return false;
+    }
+    
+    const filePath = activeEditor.getFilePath();
+    if (filePath !== AI_CONFIG_EDITOR_KEY) {
+        return false;
+    }
+    
+    return activeEditor.isDirty() === true;
+}
+
+/**
+ * Checks if the AI config editor is saved (not dirty)
+ */
+function isAIConfigEditorSaved(): boolean {
+    if (!isAIConfigEditorOpen()) {
+        return false;
+    }
+    
+    return !isAIConfigEditorDirty();
+}
+
+/**
+ * Checks if the AI config editor is closed
+ */
+function isAIConfigEditorClosed(): boolean {
+    return !isAIConfigEditorOpen();
+}
+
+/**
+ * Checks if user has typed something in the AI chat
+ * This checks if there are any chat sessions with messages
+ */
+async function hasTypedInChat(): Promise<boolean> {
+    try {
+        const sessions = await appSettings.get('aiChatSessions') as any;
+        if (!sessions || typeof sessions !== 'object') {
+            return false;
+        }
+        
+        // Check if any session has messages
+        for (const sessionId in sessions) {
+            const session = sessions[sessionId];
+            if (session?.history && Array.isArray(session.history)) {
+                // Check if there's at least one user message
+                const hasUserMessage = session.history.some((msg: any) => 
+                    msg.role === 'user' && msg.content && msg.content.trim() !== ''
+                );
+                if (hasUserMessage) {
+                    return true;
+                }
+            }
+        }
+        
+        return false;
+    } catch {
+        return false;
+    }
+}
+
+// Get current app name for the title
+function getAppName(): string {
+    const currentApp = appLoaderService.getCurrentApp();
+    return currentApp?.name || 'AppSpace';
+}
+
+// Create the AI setup HowTo contribution
+const aiSetupContribution: HowToContribution = {
+    id: 'appspace.ai-setup',
+    title: () => `Set up AI in ${getAppName()}`,
+    description: () => `Configure an LLM provider to enable AI chat features in ${getAppName()}`,
+    icon: 'robot',
+    label: '',
+    category: 'Getting Started',
+    initialize: (context: HowToContext) => {
+        // Set up subscriptions for editor and AI config changes
+        const cleanups: (() => void)[] = [];
+
+        // Watch editor changes
+        cleanups.push(
+            watchSignal(activeEditorSignal, () => {
+                context.requestUpdate();
+            })
+        );
+
+        // Watch dirty state changes
+        cleanups.push(
+            watchSignal(partDirtySignal, () => {
+                context.requestUpdate();
+            })
+        );
+
+        // Subscribe to AI config changes
+        subscribe(TOPIC_AICONFIG_CHANGED, () => {
+            context.requestUpdate();
+        });
+
+        // Return cleanup function
+        return () => {
+            cleanups.forEach(cleanup => cleanup());
+        };
+    },
+    steps: [
+        {
+            id: 'open-ai-settings',
+            title: 'Open AI Settings',
+            description: 'Open the AI settings editor by clicking the robot icon in the toolbar or using the command palette.',
+            preCondition: () => true, // Always available
+            postCondition: () => isAIConfigEditorOpen(),
+            command: 'open_ai_config',
+        },
+        {
+            id: 'configure-llm-provider',
+            title: 'Configure LLM Provider',
+            description: 'Select a provider as default and enter an API key. Make sure to save your changes using Ctrl+S or the save button.',
+            preCondition: () => isAIConfigEditorOpen(),
+            postCondition: async () => {
+                // Check if provider is configured AND settings are saved
+                const configured = await isLLMProviderConfigured();
+                const saved = isAIConfigEditorSaved();
+                return configured && saved;
+            },
+            // No command - user manually configures in the editor
+        },
+        {
+            id: 'save-and-close',
+            title: 'Save and Close',
+            description: 'Save your changes (if not already saved) and close the AI settings editor tab.',
+            preCondition: () => isAIConfigEditorOpen(),
+            postCondition: () => isAIConfigEditorClosed(),
+            // No command - user manually saves and closes the tab
+        },
+        {
+            id: 'type-in-chat',
+            title: 'Type in Chat',
+            description: 'Open the AI chat view (if not already open) and type a message to test your AI configuration.',
+            preCondition: async () => await isLLMProviderConfigured(),
+            postCondition: async () => await hasTypedInChat(),
+            // No command - user manually types in chat
+        }
+    ]
+};
+
+// Register the contribution
+contributionRegistry.registerContribution<HowToContribution>(HOWTO_CONTRIBUTION_TARGET, aiSetupContribution);
+

package/src/contributions/onboarding-howto-contributions.ts

@@ -0,0 +1,196 @@
+import { contributionRegistry, workspaceService, File, TOPIC_WORKSPACE_CHANGED, TOPIC_WORKSPACE_CONNECTED, activeEditorSignal, partDirtySignal, subscribe, appLoaderService } from '@kispace-io/core';
+import type { EditorContentProvider } from '@kispace-io/core';
+import { watchSignal } from '@kispace-io/core';
+import { HOWTO_CONTRIBUTION_TARGET } from '../howto-service';
+import type { HowToContribution, HowToContext } from '../howto-contribution';
+
+const ONBOARDING_FILE_PATH = 'welcome.txt';
+
+/**
+ * Type guard to check if an editor implements EditorContentProvider
+ */
+function isEditorContentProvider(editor: any): editor is EditorContentProvider {
+    return editor &&
+        typeof editor.getFilePath === 'function';
+}
+
+/**
+ * Checks if a workspace is selected
+ */
+async function isWorkspaceSelected(): Promise<boolean> {
+    return workspaceService.isConnected();
+}
+
+/**
+ * Checks if the onboarding file exists
+ */
+async function onboardingFileExists(): Promise<boolean> {
+    const workspace = await workspaceService.getWorkspace();
+    if (!workspace) return false;
+    
+    try {
+        const resource = await workspace.getResource(ONBOARDING_FILE_PATH);
+        return resource instanceof File;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Checks if the onboarding file is open in an editor
+ */
+function isOnboardingFileOpen(): boolean {
+    const activeEditor = activeEditorSignal.get();
+    if (!activeEditor || !isEditorContentProvider(activeEditor)) {
+        return false;
+    }
+    
+    const filePath = activeEditor.getFilePath();
+    return filePath === ONBOARDING_FILE_PATH;
+}
+
+/**
+ * Checks if the active editor is dirty (has unsaved changes)
+ * Returns true only if the onboarding file is open AND dirty
+ */
+function isActiveEditorDirty(): boolean {
+    if (!isOnboardingFileOpen()) return false;
+    
+    const activeEditor = activeEditorSignal.get();
+    if (!activeEditor) return false;
+    
+    return activeEditor.isDirty() === true;
+}
+
+/**
+ * Checks if the active editor is clean (no unsaved changes)
+ * Returns true only if the onboarding file is open AND not dirty
+ */
+function isActiveEditorClean(): boolean {
+    if (!isOnboardingFileOpen()) return false;
+    
+    const activeEditor = activeEditorSignal.get();
+    if (!activeEditor) return false;
+    
+    return activeEditor.isDirty() === false;
+}
+
+/**
+ * Checks if the onboarding file is closed (not open in any editor)
+ */
+function isOnboardingFileClosed(): boolean {
+    return !isOnboardingFileOpen();
+}
+
+// Get current app name for the title
+function getAppName(): string {
+    const currentApp = appLoaderService.getCurrentApp();
+    return currentApp?.name || 'AppSpace';
+}
+
+// Create the onboarding HowTo contribution
+// Using callback functions so the app name is read when the HowTo is displayed
+const onboardingContribution: HowToContribution = {
+    id: 'appspace.onboarding',
+    title: () => `Welcome to ${getAppName()}`,
+    description: () => `Get started with ${getAppName()} by learning the basics of workspace and file management`,
+    icon: 'graduation-cap',
+    // label will be set from title in howto-service.ts
+    label: '',
+    category: 'Getting Started',
+    initialize: (context: HowToContext) => {
+        // Set up subscriptions for workspace and editor changes
+        const cleanups: (() => void)[] = [];
+
+        // Subscribe to workspace events
+        subscribe(TOPIC_WORKSPACE_CHANGED, () => {
+            context.requestUpdate();
+        });
+
+        subscribe(TOPIC_WORKSPACE_CONNECTED, () => {
+            context.requestUpdate();
+        });
+
+        // Watch editor signals
+        cleanups.push(
+            watchSignal(activeEditorSignal, () => {
+                context.requestUpdate();
+            })
+        );
+
+        cleanups.push(
+            watchSignal(partDirtySignal, () => {
+                context.requestUpdate();
+            })
+        );
+
+        // Return cleanup function
+        return () => {
+            cleanups.forEach(cleanup => cleanup());
+        };
+    },
+    steps: [
+        {
+            id: 'create-text-file',
+            title: 'Create welcome.txt',
+            description: 'Create a new text file called "welcome.txt" in your workspace. If you don\'t have a workspace selected, choose one first.',
+            preCondition: async () => {
+                // Workspace must be selected
+                return await isWorkspaceSelected();
+            },
+            postCondition: async () => {
+                return await onboardingFileExists();
+            },
+            command: 'create_file',
+            commandParams: {
+                path: ONBOARDING_FILE_PATH,
+                contents: 'Welcome to AppSpace!\n\nThis is your first file. You can edit it and save your changes.'
+            }
+        },
+        {
+            id: 'open-text-file',
+            title: 'Open welcome.txt',
+            description: 'Open the "welcome.txt" file in the editor.',
+            preCondition: async () => {
+                return await onboardingFileExists();
+            },
+            postCondition: () => {
+                return isOnboardingFileOpen();
+            },
+            command: 'open_editor',
+            commandParams: {
+                path: ONBOARDING_FILE_PATH
+            }
+        },
+        {
+            id: 'edit-and-save',
+            title: 'Type something and save',
+            description: 'Type some text in the editor to modify the file, then save it using Ctrl+S or the save button.',
+            preCondition: () => {
+                return isOnboardingFileOpen();
+            },
+            postCondition: () => {
+                // File must be open, was dirty (edited), and is now clean (saved)
+                // Check that file is open and clean (saved)
+                return isActiveEditorClean();
+            },
+            // No command - user manually edits and saves
+        },
+        {
+            id: 'close-text-file',
+            title: 'Close the file',
+            description: 'Close the editor tab by clicking the X button on the tab.',
+            preCondition: () => {
+                return isOnboardingFileOpen();
+            },
+            postCondition: () => {
+                return isOnboardingFileClosed();
+            },
+            // No command - user manually closes the tab
+        }
+    ]
+};
+
+// Register the contribution
+contributionRegistry.registerContribution<HowToContribution>(HOWTO_CONTRIBUTION_TARGET, onboardingContribution);
+