semantic markup update

frontend/src/routes/+page.svelte

@@ -14,6 +14,11 @@
         pluginsStore.set(data.plugins);
     }
 
+    // [DEF:selectPlugin:Function]
+    /* @PURPOSE: Handles plugin selection and navigation.
+       @PRE: plugin object must be provided.
+       @POST: Navigates to migration or sets selectedPlugin store.
+    */
     function selectPlugin(plugin) {
         console.log(`[Dashboard][Action] Selecting plugin: ${plugin.id}`);
         if (plugin.id === 'superset-migration') {
@@ -22,7 +27,13 @@
             selectedPlugin.set(plugin);
         }
     }
+    // [/DEF:selectPlugin:Function]
 
+    // [DEF:handleFormSubmit:Function]
+    /* @PURPOSE: Handles task creation from dynamic form submission.
+       @PRE: event.detail must contain task parameters.
+       @POST: Task is created via API and selectedTask store is updated.
+    */
     async function handleFormSubmit(event) {
         console.log("[App.handleFormSubmit][Action] Handling form submission for task creation.");
         const params = event.detail;
@@ -36,6 +47,7 @@
             console.error(`[App.handleFormSubmit][Coherence:Failed] Task creation failed error=${error}`);
         }
     }
+    // [/DEF:handleFormSubmit:Function]
 </script>
 
 <div class="container mx-auto p-4">

frontend/src/routes/+page.ts

@@ -1,5 +1,10 @@
 import { api } from '../lib/api';
 
+// [DEF:load:Function]
+/* @PURPOSE: Loads initial plugin data for the dashboard.
+   @PRE: None.
+   @POST: Returns an object with plugins or an error message.
+*/
 /** @type {import('./$types').PageLoad} */
 export async function load() {
     try {
@@ -15,3 +20,4 @@ export async function load() {
         };
     }
 }
+// [/DEF:load:Function]

frontend/src/routes/migration/+page.svelte

@@ -51,6 +51,7 @@
   // [DEF:fetchEnvironments:Function]
   /**
    * @purpose Fetches the list of environments from the API.
+   * @pre     None.
    * @post    environments state is updated.
    */
   async function fetchEnvironments() {
@@ -69,6 +70,7 @@
   // [DEF:fetchDashboards:Function]
   /**
    * @purpose Fetches dashboards for the selected source environment.
+   * @pre     envId is a valid environment ID.
    * @param envId The environment ID.
    * @post    dashboards state is updated.
    */
@@ -93,6 +95,8 @@
   // [DEF:fetchDatabases:Function]
   /**
    * @purpose Fetches databases from both environments and gets suggestions.
+   * @pre     sourceEnvId and targetEnvId must be set.
+   * @post    sourceDatabases, targetDatabases, mappings, and suggestions are updated.
    */
   async function fetchDatabases() {
     if (!sourceEnvId || !targetEnvId) return;
@@ -128,6 +132,8 @@
   // [DEF:handleMappingUpdate:Function]
   /**
    * @purpose Saves a mapping to the backend.
+   * @pre     event.detail contains sourceUuid and targetUuid.
+   * @post    Mapping is saved and local mappings list is updated.
    */
   async function handleMappingUpdate(event: CustomEvent) {
     const { sourceUuid, targetUuid } = event.detail;
@@ -162,6 +168,8 @@
 
   // [DEF:handleViewLogs:Function]
   // @PURPOSE: Opens the log viewer for a specific task.
+  // @PRE: event.detail contains task object.
+  // @POST: logViewer state updated and showLogViewer set to true.
   function handleViewLogs(event: CustomEvent) {
       const task = event.detail;
       logViewerTaskId = task.id;
@@ -172,6 +180,8 @@
 
   // [DEF:handlePasswordPrompt:Function]
   // @PURPOSE: Reactive logic to show password prompt when a task is awaiting input.
+  // @PRE: selectedTask status is AWAITING_INPUT.
+  // @POST: showPasswordPrompt set to true with request data.
   // This is triggered by TaskRunner or TaskHistory when a task needs input
   // For now, we rely on the WebSocket or manual check.
   // Ideally, TaskHistory or TaskRunner emits an event when input is needed.
@@ -194,6 +204,8 @@
 
   // [DEF:handleResumeMigration:Function]
   // @PURPOSE: Resumes a migration task with provided passwords.
+  // @PRE: event.detail contains passwords.
+  // @POST: resumeTask is called and showPasswordPrompt is hidden on success.
   async function handleResumeMigration(event: CustomEvent) {
       if (!$selectedTask) return;
       
@@ -214,6 +226,7 @@
   /**
    * @purpose Starts the migration process.
    * @pre     sourceEnvId and targetEnvId must be set and different.
+   * @post    Migration task is started and selectedTask is updated.
    */
   async function startMigration() {
     if (!sourceEnvId || !targetEnvId) {

frontend/src/routes/migration/mappings/+page.svelte

@@ -32,6 +32,8 @@
 
   // [DEF:fetchEnvironments:Function]
   // @PURPOSE: Fetches the list of environments.
+  // @PRE: None.
+  // @POST: environments array is populated.
   async function fetchEnvironments() {
     try {
       const response = await fetch('/api/environments');
@@ -50,6 +52,8 @@
   // [DEF:fetchDatabases:Function]
   /**
    * @purpose Fetches databases from both environments and gets suggestions.
+   * @pre sourceEnvId and targetEnvId must be set.
+   * @post sourceDatabases, targetDatabases, mappings, and suggestions are updated.
    */
   async function fetchDatabases() {
     if (!sourceEnvId || !targetEnvId) return;
@@ -86,6 +90,8 @@
   // [DEF:handleUpdate:Function]
   /**
    * @purpose Saves a mapping to the backend.
+   * @pre event.detail contains sourceUuid and targetUuid.
+   * @post Mapping is saved and local mappings list is updated.
    */
   async function handleUpdate(event: CustomEvent) {
     const { sourceUuid, targetUuid } = event.detail;

frontend/src/routes/settings/+page.svelte

@@ -21,6 +21,11 @@
 
     let editingEnvId = null;
 
+    // [DEF:handleSaveGlobal:Function]
+    /* @PURPOSE: Saves global application settings.
+       @PRE: settings.settings must contain valid configuration.
+       @POST: Global settings are updated via API.
+    */
     async function handleSaveGlobal() {
         try {
             console.log("[Settings.handleSaveGlobal][Action] Saving global settings.");
@@ -32,7 +37,13 @@
             addToast('Failed to save global settings', 'error');
         }
     }
+    // [/DEF:handleSaveGlobal:Function]
 
+    // [DEF:handleAddOrUpdateEnv:Function]
+    /* @PURPOSE: Adds a new environment or updates an existing one.
+       @PRE: newEnv must contain valid environment details.
+       @POST: Environment is saved and page is reloaded to reflect changes.
+    */
     async function handleAddOrUpdateEnv() {
         try {
             console.log(`[Settings.handleAddOrUpdateEnv][Action] ${editingEnvId ? 'Updating' : 'Adding'} environment.`);
@@ -54,7 +65,13 @@
             addToast('Failed to save environment', 'error');
         }
     }
+    // [/DEF:handleAddOrUpdateEnv:Function]
 
+    // [DEF:handleDeleteEnv:Function]
+    /* @PURPOSE: Deletes a Superset environment.
+       @PRE: id must be a valid environment ID.
+       @POST: Environment is removed and page is reloaded.
+    */
     async function handleDeleteEnv(id) {
         if (confirm('Are you sure you want to delete this environment?')) {
             try {
@@ -69,7 +86,13 @@
             }
         }
     }
+    // [/DEF:handleDeleteEnv:Function]
 
+    // [DEF:handleTestEnv:Function]
+    /* @PURPOSE: Tests the connection to a Superset environment.
+       @PRE: id must be a valid environment ID.
+       @POST: Displays success or error toast based on connection result.
+    */
     async function handleTestEnv(id) {
         try {
             console.log(`[Settings.handleTestEnv][Action] Testing environment: ${id}`);
@@ -86,12 +109,24 @@
             addToast('Failed to test connection', 'error');
         }
     }
+    // [/DEF:handleTestEnv:Function]
 
+    // [DEF:editEnv:Function]
+    /* @PURPOSE: Populates the environment form for editing.
+       @PRE: env object must be provided.
+       @POST: newEnv and editingEnvId are updated.
+    */
     function editEnv(env) {
         newEnv = { ...env };
         editingEnvId = env.id;
     }
+    // [/DEF:editEnv:Function]
 
+    // [DEF:resetEnvForm:Function]
+    /* @PURPOSE: Resets the environment creation/edit form to default state.
+       @PRE: None.
+       @POST: newEnv is cleared and editingEnvId is set to null.
+    */
     function resetEnvForm() {
         newEnv = {
             id: '',
@@ -103,6 +138,7 @@
         };
         editingEnvId = null;
     }
+    // [/DEF:resetEnvForm:Function]
 </script>
 
 <div class="container mx-auto p-4">

frontend/src/routes/settings/+page.ts

@@ -1,5 +1,10 @@
 import { api } from '../../lib/api';
 
+// [DEF:load:Function]
+/* @PURPOSE: Loads application settings and environment list.
+   @PRE: API must be reachable.
+   @POST: Returns settings object or default values on error.
+*/
 /** @type {import('./$types').PageLoad} */
 export async function load() {
     try {
@@ -21,3 +26,4 @@ export async function load() {
         };
     }
 }
+// [/DEF:load:Function]

frontend/src/routes/settings/connections/+page.svelte

@@ -10,11 +10,17 @@
 
     let listComponent;
 
+    // [DEF:handleSuccess:Function]
+    /* @PURPOSE: Refreshes the connection list after a successful creation.
+       @PRE: listComponent must be bound.
+       @POST: Triggers the fetchConnections method on the list component.
+    */
     function handleSuccess() {
         if (listComponent) {
             listComponent.fetchConnections();
         }
     }
+    // [/DEF:handleSuccess:Function]
 </script>
 
 <div class="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">

frontend/src/routes/tasks/+page.svelte

@@ -13,6 +13,11 @@
   let showBackupModal = false;
   let selectedEnvId = '';
 
+  // [DEF:loadInitialData:Function]
+  /* @PURPOSE: Loads tasks and environments on page initialization.
+     @PRE: API must be reachable.
+     @POST: tasks and environments variables are populated.
+  */
   async function loadInitialData() {
     try {
       loading = true;
@@ -28,7 +33,13 @@
       loading = false;
     }
   }
+  // [/DEF:loadInitialData:Function]
 
+  // [DEF:refreshTasks:Function]
+  /* @PURPOSE: Periodically refreshes the task list.
+     @PRE: API must be reachable.
+     @POST: tasks variable is updated if data is valid.
+  */
   async function refreshTasks() {
     try {
       const data = await getTasks();
@@ -40,11 +51,23 @@
       console.error('Failed to refresh tasks:', error);
     }
   }
+  // [/DEF:refreshTasks:Function]
 
+  // [DEF:handleSelectTask:Function]
+  /* @PURPOSE: Updates the selected task ID when a task is clicked.
+     @PRE: event.detail.id must be provided.
+     @POST: selectedTaskId is updated.
+  */
   function handleSelectTask(event) {
     selectedTaskId = event.detail.id;
   }
+  // [/DEF:handleSelectTask:Function]
 
+  // [DEF:handleRunBackup:Function]
+  /* @PURPOSE: Triggers a manual backup task for the selected environment.
+     @PRE: selectedEnvId must not be empty.
+     @POST: Backup task is created and task list is refreshed.
+  */
   async function handleRunBackup() {
     if (!selectedEnvId) {
       addToast('Please select an environment', 'error');
@@ -61,6 +84,7 @@
       console.error('Failed to start backup:', error);
     }
   }
+  // [/DEF:handleRunBackup:Function]
 
   onMount(() => {
     loadInitialData();