diff --git a/specs/project_map.md b/.ai/PROJECT_MAP.md similarity index 95% rename from specs/project_map.md rename to .ai/PROJECT_MAP.md index 9d69a4c..460b6cc 100644 --- a/specs/project_map.md +++ b/.ai/PROJECT_MAP.md @@ -145,6 +145,8 @@ - 🏗️ Layer: Unknown - ƒ **openDrawerForTask** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) + - ƒ **openDrawer** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - ƒ **closeDrawer** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) - ƒ **updateResourceTask** (`Function`) `[TRIVIAL]` @@ -172,6 +174,31 @@ - 📝 Track active task count for navbar indicator - 🏗️ Layer: UI - 🔗 DEPENDS_ON -> `WebSocket connection, taskDrawer store` +- 📦 **frontend.src.lib.stores.__tests__.test_sidebar** (`Module`) + - 📝 Unit tests for sidebar store + - 🏗️ Layer: UI +- 📦 **frontend.src.lib.stores.__tests__.sidebar** (`Module`) + - 📝 Unit tests for sidebar store + - 🏗️ Layer: Domain (Tests) + - ƒ **test_sidebar_initial_state** (`Function`) + - ƒ **test_toggleSidebar** (`Function`) + - ƒ **test_setActiveItem** (`Function`) +- 📦 **frontend.src.lib.stores.__tests__.test_activity** (`Module`) + - 📝 Unit tests for activity store + - 🏗️ Layer: UI + - 🔗 DEPENDS_ON -> `frontend.src.lib.stores.taskDrawer` +- 📦 **setupTests** (`Module`) + - 📝 Global test setup with mocks for SvelteKit modules + - 🏗️ Layer: UI +- 📦 **frontend.src.lib.stores.__tests__.test_taskDrawer** (`Module`) `[CRITICAL]` + - 📝 Unit tests for task drawer store + - 🏗️ Layer: UI +- 📦 **navigation** (`Mock`) + - 📝 Mock for $app/navigation in tests +- 📦 **stores** (`Mock`) + - 📝 Mock for $app/stores in tests +- 📦 **environment** (`Mock`) + - 📝 Mock for $app/environment in tests - 🧩 **Select** (`Component`) `[TRIVIAL]` - 📝 Standardized dropdown selection component. - 🏗️ Layer: Atom @@ -284,6 +311,12 @@ - ⬅️ READS_FROM `lib` - ⬅️ READS_FROM `taskDrawerStore` - ➡️ WRITES_TO `taskDrawerStore` + - ƒ **loadRecentTasks** (`Function`) + - 📝 Load recent tasks for list mode display + - ƒ **selectTask** (`Function`) + - 📝 Select a task from list to view details + - ƒ **goBackToList** (`Function`) + - 📝 Return to task list view from task details - 📦 **TaskDrawer** (`Module`) `[TRIVIAL]` - 📝 Auto-generated module for frontend/src/lib/components/layout/TaskDrawer.svelte - 🏗️ Layer: Unknown @@ -674,24 +707,24 @@ - 📝 Updates a mapping for a specific source database. - ƒ **getSuggestion** (`Function`) - 📝 Finds a suggestion for a source database. -- 🧩 **TaskLogViewer** (`Component`) - - 📝 Displays detailed logs for a specific task in a modal or inline using TaskLogPanel. +- 🧩 **TaskLogViewer** (`Component`) `[CRITICAL]` + - 📝 Displays detailed logs for a specific task inline or in a modal using TaskLogPanel. - 🏗️ Layer: UI - - 📥 Props: show: any, inline: any, taskId: any, taskStatus: any + - 🔒 Invariant: Real-time logs are always appended without duplicates. + - 📥 Props: show: any, inline: any, taskId: any, taskStatus: any, realTimeLogs: any - ⚡ Events: close - ⬅️ READS_FROM `t` - - ➡️ WRITES_TO `t` + - 📦 **handleRealTimeLogs** (`Action`) + - 📝 Append real-time logs as they arrive from WebSocket, preventing duplicates */ - ƒ **fetchLogs** (`Function`) - - 📝 Fetches logs for the current task. - - ƒ **close** (`Function`) - - 📝 Closes the log viewer modal. - - ƒ **onDestroy** (`Function`) - - 📝 Cleans up the polling interval. + - 📝 Fetches logs for the current task from API (polling fallback). - 📦 **TaskLogViewer** (`Module`) `[TRIVIAL]` - 📝 Auto-generated module for frontend/src/components/TaskLogViewer.svelte - 🏗️ Layer: Unknown - ƒ **handleFilterChange** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) + - ƒ **handleRefresh** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - 🧩 **Footer** (`Component`) `[TRIVIAL]` - 📝 Displays the application footer with copyright information. - 🏗️ Layer: UI @@ -817,21 +850,25 @@ - ⬅️ READS_FROM `app` - ⬅️ READS_FROM `auth` - 🧩 **TaskLogPanel** (`Component`) - - 📝 Scrolls the log container to the bottom. + - 📝 Component properties and state. - 🏗️ Layer: UI - 🔒 Invariant: Must always display logs in chronological order and respect auto-scroll preference. - - 📥 Props: taskId: any, logs: any, autoScroll: any + - 📥 Props: logs: any, autoScroll: any - ⚡ Events: filterChange - 📦 **TaskLogPanel** (`Module`) `[TRIVIAL]` - 📝 Auto-generated module for frontend/src/components/tasks/TaskLogPanel.svelte - 🏗️ Layer: Unknown + - ƒ **filterLogs** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - ƒ **handleFilterChange** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) - ƒ **scrollToBottom** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) + - ƒ **toggleAutoScroll** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - 🧩 **LogFilterBar** (`Component`) - - 📝 UI component for filtering logs by level, source, and text search. --> - - 🏗️ Layer: UI --> + - 📝 Compact filter toolbar for logs — level, source, and text search in a single dense row. + - 🏗️ Layer: UI - 📥 Props: availableSources: any, selectedLevel: any, selectedSource: any, searchText: any - 📦 **LogFilterBar** (`Module`) `[TRIVIAL]` - 📝 Auto-generated module for frontend/src/components/tasks/LogFilterBar.svelte @@ -845,14 +882,14 @@ - ƒ **clearFilters** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) - 🧩 **LogEntryRow** (`Component`) - - 📝 Optimized row rendering for a single log entry with color coding and progress bar support. --> - - 🏗️ Layer: UI --> + - 📝 Renders a single log entry with stacked layout optimized for narrow drawer panels. + - 🏗️ Layer: UI - 📥 Props: log: any, showSource: any + - ƒ **formatTime** (`Function`) + - 📝 Format ISO timestamp to HH:MM:SS */ - 📦 **LogEntryRow** (`Module`) `[TRIVIAL]` - 📝 Auto-generated module for frontend/src/components/tasks/LogEntryRow.svelte - 🏗️ Layer: Unknown - - ƒ **formatTime** (`Function`) `[TRIVIAL]` - - 📝 Auto-detected function (orphan) - ƒ **getLevelClass** (`Function`) `[TRIVIAL]` - 📝 Auto-detected function (orphan) - ƒ **getSourceClass** (`Function`) `[TRIVIAL]` @@ -1455,6 +1492,27 @@ - 📝 Retrieves a permission by resource and action. - ƒ **list_permissions** (`Function`) - 📝 Lists all available permissions. +- 📦 **test_auth** (`Module`) + - 📝 Unit tests for authentication module + - 🏗️ Layer: Domain + - ƒ **db_session** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **auth_service** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **auth_repo** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_create_user** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_authenticate_user** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_create_session** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_role_permission_association** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_user_role_association** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **test_ad_group_mapping** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - 📦 **backend.core.utils.fileio** (`Module`) - 📝 Предоставляет набор утилит для управления файловыми операциями, включая работу с временными файлами, архивами ZIP, файлами YAML и очистку директорий. - 🏗️ Layer: Infra @@ -1573,6 +1631,25 @@ - 🔗 CALLS -> `self.load_excel_mappings` - 🔗 CALLS -> `superset_client.get_dataset` - 🔗 CALLS -> `superset_client.update_dataset` +- 📦 **test_logger** (`Module`) + - 📝 Unit tests for logger module + - 🏗️ Layer: Infra + - ƒ **test_belief_scope_logs_entry_action_exit_at_debug** (`Function`) + - 📝 Test that belief_scope generates [ID][Entry], [ID][Action], and [ID][Exit] logs at DEBUG level. + - ƒ **test_belief_scope_error_handling** (`Function`) + - 📝 Test that belief_scope logs Coherence:Failed on exception. + - ƒ **test_belief_scope_success_coherence** (`Function`) + - 📝 Test that belief_scope logs Coherence:OK on success. + - ƒ **test_belief_scope_not_visible_at_info** (`Function`) + - 📝 Test that belief_scope Entry/Exit/Coherence logs are NOT visible at INFO level. + - ƒ **test_task_log_level_default** (`Function`) + - 📝 Test that default task log level is INFO. + - ƒ **test_should_log_task_level** (`Function`) + - 📝 Test that should_log_task_level correctly filters log levels. + - ƒ **test_configure_logger_task_log_level** (`Function`) + - 📝 Test that configure_logger updates task_log_level. + - ƒ **test_enable_belief_state_flag** (`Function`) + - 📝 Test that enable_belief_state flag controls belief_scope logging. - 📦 **TaskLoggerModule** (`Module`) `[CRITICAL]` - 📝 Provides a dedicated logger for tasks with automatic source attribution. - 🏗️ Layer: Core @@ -2022,6 +2099,11 @@ - ƒ **download_file** (`Function`) - 📝 Retrieve a file for download. - 🔗 CALLS -> `StoragePlugin.get_file_path` +- 📦 **__init__** (`Module`) `[TRIVIAL]` + - 📝 Auto-generated module for backend/src/api/routes/__init__.py + - 🏗️ Layer: Unknown + - ƒ **__getattr__** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - 📦 **TasksRouter** (`Module`) - 📝 Defines the FastAPI router for task-related endpoints, allowing clients to create, list, and get the status of tasks. - 🏗️ Layer: UI (API) @@ -2073,6 +2155,30 @@ - ƒ **get_database_mappings** (`Function`) - 📝 Get database mapping suggestions between source and target environments - 🔗 CALLS -> `MappingService.get_suggestions` +- 📦 **backend.src.api.routes.__tests__.test_dashboards** (`Module`) + - 📝 Unit tests for Dashboards API endpoints + - 🏗️ Layer: API + - ƒ **test_get_dashboards_success** (`Function`) + - ƒ **test_get_dashboards_with_search** (`Function`) + - ƒ **test_get_dashboards_env_not_found** (`Function`) + - ƒ **test_get_dashboards_invalid_pagination** (`Function`) + - ƒ **test_migrate_dashboards_success** (`Function`) + - ƒ **test_migrate_dashboards_no_ids** (`Function`) + - ƒ **test_backup_dashboards_success** (`Function`) + - ƒ **test_get_database_mappings_success** (`Function`) + - ƒ **mock_get_dashboards** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) + - ƒ **mock_get_dashboards** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) +- 📦 **backend.src.api.routes.__tests__.test_datasets** (`Module`) + - 📝 Unit tests for Datasets API endpoints + - 🏗️ Layer: API + - ƒ **test_get_datasets_success** (`Function`) + - ƒ **test_get_datasets_env_not_found** (`Function`) + - ƒ **test_get_datasets_invalid_pagination** (`Function`) + - ƒ **test_map_columns_success** (`Function`) + - ƒ **test_map_columns_invalid_source_type** (`Function`) + - ƒ **test_generate_docs_success** (`Function`) - 📦 **backend.src.models.llm** (`Module`) - 📝 SQLAlchemy models for LLM provider configuration and validation results. - 🏗️ Layer: Domain @@ -2157,6 +2263,11 @@ - ℂ **ADGroupMapping** (`Class`) - 📝 Maps an Active Directory group to a local System Role. - 🔗 DEPENDS_ON -> `Role` +- 📦 **test_models** (`Module`) `[TRIVIAL]` + - 📝 Unit tests for data models + - 🏗️ Layer: Domain + - ƒ **test_environment_model** (`Function`) + - 📝 Tests that Environment model correctly stores values. - 📦 **backend.src.services.resource_service** (`Module`) - 📝 Shared service for fetching resource data with Git status and task status - 🏗️ Layer: Service @@ -2229,6 +2340,8 @@ - 📦 **backend.src.services** (`Module`) - 📝 Package initialization for services module - 🏗️ Layer: Core + - ƒ **__getattr__** (`Function`) `[TRIVIAL]` + - 📝 Auto-detected function (orphan) - 📦 **backend.src.services.auth_service** (`Module`) - 📝 Orchestrates authentication business logic. - 🏗️ Layer: Service @@ -2291,6 +2404,15 @@ - 📝 Helper to get an initialized SupersetClient for an environment. - ƒ **get_suggestions** (`Function`) - 📝 Fetches databases from both environments and returns fuzzy matching suggestions. +- 📦 **backend.src.services.__tests__.test_resource_service** (`Module`) + - 📝 Unit tests for ResourceService + - 🏗️ Layer: Service + - ƒ **test_get_dashboards_with_status** (`Function`) + - ƒ **test_get_datasets_with_status** (`Function`) + - ƒ **test_get_activity_summary** (`Function`) + - ƒ **test_get_git_status_for_dashboard_no_repo** (`Function`) + - ƒ **test_get_last_task_for_resource** (`Function`) + - ƒ **test_extract_resource_name_from_task** (`Function`) - 📦 **BackupPlugin** (`Module`) - 📝 A plugin that provides functionality to back up Superset dashboards. - 🏗️ Layer: App @@ -2652,11 +2774,6 @@ - 📝 Test sub-context logger uses new source. - ƒ **test_multiple_sub_contexts** (`Function`) - 📝 Test creating multiple sub-contexts. -- 📦 **backend.tests.test_resource_service** (`Module`) - - 📝 Contract-driven tests for ResourceService - - ƒ **test_get_dashboards_with_status** (`Function`) - - ƒ **test_get_dashboards_with_status** (`Function`) `[TRIVIAL]` - - 📝 Auto-detected function (orphan) - ƒ **test_belief_scope_logs_entry_action_exit_at_debug** (`Function`) - 📝 Test that belief_scope generates [ID][Entry], [ID][Action], and [ID][Exit] logs at DEBUG level. - ƒ **test_belief_scope_error_handling** (`Function`) diff --git a/.ai/ROOT.md b/.ai/ROOT.md new file mode 100644 index 0000000..9c4c29b --- /dev/null +++ b/.ai/ROOT.md @@ -0,0 +1,37 @@ +# [DEF:Project_Knowledge_Map:Root] +# @TIER: CRITICAL +# @PURPOSE: Global navigation map for AI-Agent (GRACE Knowledge Graph). +# @LAST_UPDATE: 2026-02-19 + +## 1. SYSTEM STANDARDS (Rules of the Game) +Strict policies and formatting rules. +* **Constitution:** High-level architectural and business invariants. + * Ref: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution]` +* **Architecture:** Service boundaries and tech stack decisions. + * Ref: `.ai/standards/architecture.md` -> `[DEF:Std:Architecture]` +* **Plugin Design:** Rules for building and integrating Plugins. + * Ref: `.ai/standards/plugin_design.md` -> `[DEF:Std:Plugin]` +* **API Design:** Rules for FastAPI endpoints and Pydantic models. + * Ref: `.ai/standards/api_design.md` -> `[DEF:Std:API_FastAPI]` +* **UI Design:** SvelteKit and Tailwind CSS component standards. + * Ref: `.ai/standards/ui_design.md` -> `[DEF:Std:UI_Svelte]` +* **Semantic Mapping:** Using `[DEF:]` and belief scopes. + * Ref: `.ai/standards/semantics.md` -> `[DEF:Std:Semantics]` + +## 2. FEW-SHOT EXAMPLES (Patterns) +Use these for code generation (Style Transfer). +* **FastAPI Route:** Reference implementation of a task-based route. + * Ref: `.ai/shots/backend_route.py` -> `[DEF:Shot:FastAPI_Route]` +* **Svelte Component:** Reference implementation of a sidebar/navigation component. + * Ref: `.ai/shots/frontend_component.svelte` -> `[DEF:Shot:Svelte_Component]` +* **Plugin Module:** Reference implementation of a task plugin. + * Ref: `.ai/shots/plugin_example.py` -> `[DEF:Shot:Plugin_Example]` + +## 3. DOMAIN MAP (Modules) +* **Project Map:** `.ai/PROJECT_MAP.md` -> `[DEF:Project_Map]` +* **Backend Core:** `backend/src/core` -> `[DEF:Module:Backend_Core]` +* **Backend API:** `backend/src/api` -> `[DEF:Module:Backend_API]` +* **Frontend Lib:** `frontend/src/lib` -> `[DEF:Module:Frontend_Lib]` +* **Specifications:** `specs/` -> `[DEF:Module:Specs]` + +# [/DEF:Project_Knowledge_Map] diff --git a/.ai/shots/backend_route.py b/.ai/shots/backend_route.py new file mode 100644 index 0000000..76d829d --- /dev/null +++ b/.ai/shots/backend_route.py @@ -0,0 +1,57 @@ +# [DEF:Shot:FastAPI_Route:Example] +# @PURPOSE: Reference implementation of a task-based route using GRACE-Poly. +# @RELATION: IMPLEMENTS -> [DEF:Std:API_FastAPI] + +from typing import List, Dict, Any, Optional +from fastapi import APIRouter, Depends, HTTPException, status +from pydantic import BaseModel +from ...core.logger import belief_scope +from ...core.task_manager import TaskManager, Task +from ...core.config_manager import ConfigManager +from ...dependencies import get_task_manager, get_config_manager, has_permission, get_current_user + +router = APIRouter() + +class CreateTaskRequest(BaseModel): + plugin_id: str + params: Dict[str, Any] + +@router.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED) +# [DEF:create_task:Function] +# @PURPOSE: Create and start a new task using TaskManager. Non-blocking. +# @PARAM: request (CreateTaskRequest) - Plugin and params. +# @PARAM: task_manager (TaskManager) - Async task executor. +# @PARAM: config (ConfigManager) - Centralized configuration. +# @PRE: plugin_id must exist; config must be initialized. +# @POST: A new task is spawned; Task ID returned immediately. +async def create_task( + request: CreateTaskRequest, + task_manager: TaskManager = Depends(get_task_manager), + config: ConfigManager = Depends(get_config_manager), + current_user = Depends(get_current_user) +): + # RBAC: Dynamic permission check + has_permission(f"plugin:{request.plugin_id}", "EXECUTE")(current_user) + + with belief_scope("create_task"): + try: + # 1. Action: Resolve setting using ConfigManager (Example) + timeout = config.get("TASKS_DEFAULT_TIMEOUT", 3600) + + # 2. Action: Spawn async task via TaskManager + # @RELATION: CALLS -> task_manager.create_task + task = await task_manager.create_task( + plugin_id=request.plugin_id, + params={**request.params, "timeout": timeout} + ) + return task + except Exception as e: + # Evaluation: Proper error mapping and logging + # @UX_STATE: Error feedback to frontend + raise HTTPException( + status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, + detail=f"Task creation failed: {str(e)}" + ) +# [/DEF:create_task:Function] + +# [/DEF:Shot:FastAPI_Route] diff --git a/.ai/shots/frontend_component.svelte b/.ai/shots/frontend_component.svelte new file mode 100644 index 0000000..05bd165 --- /dev/null +++ b/.ai/shots/frontend_component.svelte @@ -0,0 +1,63 @@ + +# @PURPOSE: Reference implementation of a task-spawning component using Constitution rules. +# @RELATION: IMPLEMENTS -> [DEF:Std:UI_Svelte] + + + + + + + diff --git a/.ai/shots/plugin_example.py b/.ai/shots/plugin_example.py new file mode 100644 index 0000000..8c10d8e --- /dev/null +++ b/.ai/shots/plugin_example.py @@ -0,0 +1,67 @@ +# [DEF:Shot:Plugin_Example:Example] +# @PURPOSE: Reference implementation of a plugin following GRACE standards. +# @RELATION: IMPLEMENTS -> [DEF:Std:Plugin] + +from typing import Dict, Any, Optional +from ..core.plugin_base import PluginBase +from ..core.task_manager.context import TaskContext + +class ExamplePlugin(PluginBase): + @property + def id(self) -> str: + return "example-plugin" + + @property + def name(self) -> str: + return "Example Plugin" + + @property + def description(self) -> str: + return "A simple plugin that demonstrates structured logging and progress tracking." + + @property + def version(self) -> str: + return "1.0.0" + + # [DEF:get_schema:Function] + # @PURPOSE: Defines input validation schema. + def get_schema(self) -> Dict[str, Any]: + return { + "type": "object", + "properties": { + "message": { + "type": "string", + "title": "Message", + "description": "A message to log.", + "default": "Hello, GRACE!", + } + }, + "required": ["message"], + } + # [/DEF:get_schema:Function] + + # [DEF:execute:Function] + # @PURPOSE: Core plugin logic with structured logging and progress reporting. + # @PARAM: params (Dict) - Validated input parameters. + # @PARAM: context (TaskContext) - Execution context with logging and progress tools. + async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None): + message = params["message"] + + # 1. Action: Structured Logging with Source Attribution + if context: + log = context.logger.with_source("example_plugin") + log.info(f"Starting execution with message: {message}") + + # 2. Action: Progress Reporting + log.progress("Processing step 1...", percent=25) + # Simulating some async work... + # await some_async_op() + + log.progress("Processing step 2...", percent=75) + log.info("Execution completed successfully.") + else: + # Fallback for manual/standalone execution + print(f"Standalone execution: {message}") + # [/DEF:execute:Function] + +# [/DEF:Shot:Plugin_Example] diff --git a/.ai/standards/api_design.md b/.ai/standards/api_design.md new file mode 100644 index 0000000..19eeb4e --- /dev/null +++ b/.ai/standards/api_design.md @@ -0,0 +1,47 @@ +# [DEF:Std:API_FastAPI:Standard] +# @TIER: CRITICAL +# @PURPOSE: Unification of all FastAPI endpoints following GRACE-Poly. +# @LAYER: UI (API) +# @INVARIANT: All non-trivial route logic must be wrapped in `belief_scope`. +# @INVARIANT: Every module and function MUST have `[DEF:]` anchors and metadata. + +## 1. ROUTE MODULE DEFINITION +Every API route file must start with a module definition header: +```python +# [DEF:ModuleName:Module] +# @TIER: [CRITICAL | STANDARD | TRIVIAL] +# @SEMANTICS: list, of, keywords +# @PURPOSE: High-level purpose of the module. +# @LAYER: UI (API) +# @RELATION: DEPENDS_ON -> [OtherModule] +``` + +## 2. FUNCTION DEFINITION & CONTRACT +Every endpoint handler must be decorated with `[DEF:]` and explicit metadata before the implementation: +```python +@router.post("/endpoint", response_model=ModelOut) +# [DEF:function_name:Function] +# @PURPOSE: What it does (brief, high-entropy). +# @PARAM: param_name (Type) - Description. +# @PRE: Conditions before execution (e.g., auth, existence). +# @POST: Expected state after execution. +# @RETURN: What it returns. +async def function_name(...): + with belief_scope("function_name"): + # Implementation + pass +# [/DEF:function_name:Function] +``` + +## 3. DEPENDENCY INJECTION & CORE SERVICES +* **Auth:** `Depends(get_current_user)` for authentication. +* **Perms:** `Depends(has_permission("resource", "ACTION"))` for RBAC. +* **Config:** Use `Depends(get_config_manager)` for settings. Hardcoding is FORBIDDEN. +* **Tasks:** Long-running operations must be executed via `TaskManager`. API routes should return Task ID and be non-blocking. + +## 4. ERROR HANDLING +* Raise `HTTPException` from the router layer. +* Use `try-except` blocks within `belief_scope` to ensure proper error logging and classification. +* Do not leak internal implementation details in error responses. + +# [/DEF:Std:API_FastAPI] diff --git a/.ai/standards/architecture.md b/.ai/standards/architecture.md new file mode 100644 index 0000000..684f36c --- /dev/null +++ b/.ai/standards/architecture.md @@ -0,0 +1,25 @@ +# [DEF:Std:Architecture:Standard] +# @TIER: CRITICAL +# @PURPOSE: Core architectural decisions and service boundaries. +# @LAYER: Infra +# @INVARIANT: ss-tools MUST remain a standalone service (Orchestrator). +# @INVARIANT: Backend: FastAPI, Frontend: SvelteKit. + +## 1. ORCHESTRATOR VS INSTANCE +* **Role:** ss-tools is a "Manager of Managers". It sits ABOVE Superset environments. +* **Isolation:** Do not integrate directly into Superset as a plugin to maintain multi-environment management capability. +* **Tech Stack:** + * Backend: Python 3.9+ with FastAPI (Asynchronous logic). + * Frontend: SvelteKit + Tailwind CSS (Reactive UX). + +## 2. COMPONENT BOUNDARIES +* **Plugins:** All business logic must be encapsulated in Plugins (`backend/src/plugins/`). +* **TaskManager:** All long-running operations MUST be handled by the TaskManager. +* **Security:** Independent RBAC system managed in `auth.db`. + +## 3. INTEGRATION STRATEGY +* **Superset API:** Communication via REST API. +* **Database:** Local SQLite for metadata (`tasks.db`, `auth.db`, `migrations.db`). +* **Filesystem:** Local storage for backups and git repositories. + +# [/DEF:Std:Architecture] diff --git a/.ai/standards/constitution.md b/.ai/standards/constitution.md new file mode 100644 index 0000000..ace66c8 --- /dev/null +++ b/.ai/standards/constitution.md @@ -0,0 +1,36 @@ +# [DEF:Std:Constitution:Standard] +# @TIER: CRITICAL +# @PURPOSE: Supreme Law of the Repository. High-level architectural and business invariants. +# @VERSION: 2.3.0 +# @LAST_UPDATE: 2026-02-19 +# @INVARIANT: Any deviation from this Constitution constitutes a build failure. + +## 1. CORE PRINCIPLES + +### I. Semantic Protocol Compliance +* **Ref:** `[DEF:Std:Semantics]` (formerly `semantic_protocol.md`) +* **Law:** All code must adhere to the Axioms (Meaning First, Contract First, etc.). +* **Compliance:** Strict matching of Anchors (`[DEF]`), Tags (`@KEY`), and structures is mandatory. + +### II. Modular Plugin Architecture +* **Pattern:** Everything is a Plugin inheriting from `PluginBase`. +* **Centralized Config:** Use `ConfigManager` via `get_config_manager()`. Hardcoding is FORBIDDEN. + +### III. Unified Frontend Experience +* **Styling:** Tailwind CSS First. Minimize scoped ` + +``` + +## 2. STATE MANAGEMENT & STORES +* **Subscription:** Use `$` prefix for reactive store access (e.g., `$sidebarStore`). +* **Data Flow:** Mark store interactions in `[DEF:]` metadata: + * `# @RELATION: BINDS_TO -> store_id` + +## 3. UI/UX BEST PRACTICES +* **Transitions:** Use Svelte built-in transitions for UI state changes. +* **Feedback:** Always provide visual feedback for async actions (Loading spinners, skeleton loaders). +* **Modularity:** Break down components into "Atoms" (Trivial) and "Orchestrators" (Critical). + +## 4. ACCESSIBILITY (A11Y) +* Ensure proper ARIA roles and keyboard navigation for interactive elements. +* Use semantic HTML tags (`