diff --git a/.claude/.pi-map.index.md b/.claude/.pi-map.index.md index 1ec30c5..f5f1d53 100644 --- a/.claude/.pi-map.index.md +++ b/.claude/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .claude ## role -Configuration and instruction files for the Claude AI assistant integration. +Configuration directory for Claude AI assistant integration and custom instructions. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/.claude/.pi-map.md b/.claude/.pi-map.md index 5e53043..4476958 100644 --- a/.claude/.pi-map.md +++ b/.claude/.pi-map.md @@ -4,10 +4,10 @@ dir: .claude index: .claude/.pi-map.index.md ## role -Configuration and instruction files for the Claude AI assistant integration. +Configuration directory for Claude AI assistant integration and custom instructions. ## files ## arch -Simple flat-file configuration storage with no complex architecture; contains prompt templates, system instructions, or context files used to guide Claude's behavior in this project. +Project-specific AI tooling configuration using convention-based file organization for assistant context and behavior customization. ## tags - ## symbols diff --git a/.claude/skills/.pi-map.index.md b/.claude/skills/.pi-map.index.md index 1a0e0c6..f31c258 100644 --- a/.claude/skills/.pi-map.index.md +++ b/.claude/skills/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .claude/skills ## role -Empty directory placeholder for future Claude Code skill definitions or custom AI-assisted workflows. +Contains reusable AI skill definitions and prompt templates that configure Claude's specialized capabilities for specific development tasks. ## parent index: .claude/.pi-map.index.md map: .claude/.pi-map.md diff --git a/.claude/skills/.pi-map.md b/.claude/skills/.pi-map.md index 33285cb..e83c69e 100644 --- a/.claude/skills/.pi-map.md +++ b/.claude/skills/.pi-map.md @@ -4,10 +4,10 @@ dir: .claude/skills index: .claude/skills/.pi-map.index.md ## role -Empty directory placeholder for future Claude Code skill definitions or custom AI-assisted workflows. +Contains reusable AI skill definitions and prompt templates that configure Claude's specialized capabilities for specific development tasks. ## files ## arch -None (no files present); likely intended for declarative skill modules using Claude's skill system pattern. +Modular skill-based architecture using declarative configuration files (likely YAML/JSON) to define context-specific behaviors, tool access patterns, and system prompts for different operational modes. ## tags - ## symbols diff --git a/.claude/skills/sift-backlog/.pi-map.md b/.claude/skills/sift-backlog/.pi-map.md index cacaad9..977bd16 100644 --- a/.claude/skills/sift-backlog/.pi-map.md +++ b/.claude/skills/sift-backlog/.pi-map.md @@ -8,7 +8,7 @@ Defines a workflow skill for triaging, organizing, and activating backlog tasks ## files - SKILL.md | Defines a workflow skill for triaging, organizing, and activating backlog tasks into actionable plans using a custom CLI tool. | dep: sf (custom CLI tool), task management system, plan management system ## arch -Skill-based workflow automation following a structured triage pipeline (scan → filter → prioritize → activate) with CLI tool integration for backlog management. +Documentation-driven skill definition using structured markdown with command specifications, workflow stages, and integration patterns for Claude CLI tooling. ## tags skill, defines, workflow, triaging, organizing, activating, backlog, tasks ## symbols diff --git a/.opencode/.pi-map.index.md b/.opencode/.pi-map.index.md index d6511f0..a452937 100644 --- a/.opencode/.pi-map.index.md +++ b/.opencode/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode ## role -Configuration directory for the OpenCode AI coding assistant tool +Hidden directory for OpenCode IDE/editor configuration and workspace metadata ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/.opencode/.pi-map.md b/.opencode/.pi-map.md index 21eac4f..40ae67c 100644 --- a/.opencode/.pi-map.md +++ b/.opencode/.pi-map.md @@ -4,10 +4,10 @@ dir: .opencode index: .opencode/.pi-map.index.md ## role -Configuration directory for the OpenCode AI coding assistant tool +Hidden directory for OpenCode IDE/editor configuration and workspace metadata ## files ## arch -Tool-specific configuration storage using standard dot-directory convention with likely JSON/YAML config files and optional workspace state/logs +IDE-specific dot-directory pattern, no active code architecture; stores tool preferences and ephemeral state ## tags - ## symbols diff --git a/.opencode/commands/.pi-map.index.md b/.opencode/commands/.pi-map.index.md index 482ce1e..7bcca04 100644 --- a/.opencode/commands/.pi-map.index.md +++ b/.opencode/commands/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/commands ## role -Defines structured workflow commands and AI assistant stances for an experimental OpenSpec-based development system that guides changes through exploration, proposal, implementation, and archival phases. +Defines experimental workflow skills and AI assistant stances for an OpenSpec-based development system with structured change management. ## parent index: .opencode/.pi-map.index.md map: .opencode/.pi-map.md diff --git a/.opencode/commands/.pi-map.md b/.opencode/commands/.pi-map.md index 5de9054..e4099c1 100644 --- a/.opencode/commands/.pi-map.md +++ b/.opencode/commands/.pi-map.md @@ -4,14 +4,14 @@ dir: .opencode/commands index: .opencode/commands/.pi-map.index.md ## role -Defines structured workflow commands and AI assistant stances for an experimental OpenSpec-based development system that guides changes through exploration, proposal, implementation, and archival phases. +Defines experimental workflow skills and AI assistant stances for an OpenSpec-based development system with structured change management. ## files - opsx-apply.md | Defines an experimental workflow skill for implementing tasks from an OpenSpec change through a structured, interactive process with CLI integration and progress tracking. | dep: openspec CLI, AskUserQuestion tool, filesystem (for reading context files) - opsx-archive.md | Defines a workflow for archiving completed changes in an experimental openspec-based development system | dep: openspec CLI, AskUserQuestion tool, Task tool, Skill tool, filesystem (mkdir, mv), JSON parsing - opsx-explore.md | Defines the "explore mode" stance for an AI assistant - a thinking/discovery mode for investigating problems and clarifying requirements without implementing code | dep: OpenSpec system - opsx-propose.md | Defines a workflow for proposing new changes in the openspec system by creating a change directory and generating all required artifacts (proposal.md, design.md, tasks.md) in dependency order | dep: openspec CLI, AskUserQuestion tool, TodoWrite tool, JSON parsing ## arch -Markdown-based declarative workflow definitions using a command pattern where each `.md` file specifies a distinct operational stance or phase (explore/propose/apply/archive) with embedded metadata, structured steps, and CLI integration points for progressive change lifecycle management. +Markdown-based command definitions using a workflow pattern with interactive CLI integration, progress tracking, and dependency-ordered artifact generation across explore/propose/apply/archive lifecycle phases. ## tags opsx, defines, workflow, openspec, openspec cli, askuserquestion tool, explore, experimental ## symbols diff --git a/.opencode/skills/.pi-map.index.md b/.opencode/skills/.pi-map.index.md index c1a37e4..f11167a 100644 --- a/.opencode/skills/.pi-map.index.md +++ b/.opencode/skills/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/skills ## role -Contains reusable skill modules that provide specific capabilities or integrations for the OpenCode agent framework. +Contains reusable AI skill modules that provide specialized capabilities for the OpenCode assistant. ## parent index: .opencode/.pi-map.index.md map: .opencode/.pi-map.md diff --git a/.opencode/skills/.pi-map.md b/.opencode/skills/.pi-map.md index 0efac59..77e0a1e 100644 --- a/.opencode/skills/.pi-map.md +++ b/.opencode/skills/.pi-map.md @@ -4,10 +4,10 @@ dir: .opencode/skills index: .opencode/skills/.pi-map.index.md ## role -Contains reusable skill modules that provide specific capabilities or integrations for the OpenCode agent framework. +Contains reusable AI skill modules that provide specialized capabilities for the OpenCode assistant. ## files ## arch -Modular plugin-based architecture where each skill is a self-contained unit implementing standardized interfaces for dynamic discovery and loading by the agent core. +Modular plugin-based architecture where each skill is a self-contained module with defined interfaces, enabling dynamic loading and composition of AI capabilities. ## tags - ## symbols diff --git a/.opencode/skills/openspec-apply-change/.pi-map.index.md b/.opencode/skills/openspec-apply-change/.pi-map.index.md index c2b3bf5..bcef100 100644 --- a/.opencode/skills/openspec-apply-change/.pi-map.index.md +++ b/.opencode/skills/openspec-apply-change/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/skills/openspec-apply-change ## role -Provides a spec-driven AI skill that implements tasks from OpenSpec changes by applying structured modifications to a codebase. +Defines an AI assistant skill that implements OpenSpec changes through a spec-driven workflow with structured planning, validation, and execution phases. ## parent index: .opencode/skills/.pi-map.index.md map: .opencode/skills/.pi-map.md diff --git a/.opencode/skills/openspec-apply-change/.pi-map.md b/.opencode/skills/openspec-apply-change/.pi-map.md index ac0c4e6..0043787 100644 --- a/.opencode/skills/openspec-apply-change/.pi-map.md +++ b/.opencode/skills/openspec-apply-change/.pi-map.md @@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-apply-change index: .opencode/skills/openspec-apply-change/.pi-map.index.md ## role -Provides a spec-driven AI skill that implements tasks from OpenSpec changes by applying structured modifications to a codebase. +Defines an AI assistant skill that implements OpenSpec changes through a spec-driven workflow with structured planning, validation, and execution phases. ## files - SKILL.md | Defines an AI assistant skill for implementing tasks from an OpenSpec change using a spec-driven workflow | dep: openspec CLI, AskUserQuestion tool, filesystem access ## arch -Skill-based modular architecture using markdown-defined capabilities with a workflow-driven pattern that separates specification parsing from implementation execution. +Template-based skill definition using markdown documentation with structured workflow phases (planning, validation, execution) and integration points for external tools (OpenSpec CLI, OpenCode agent). ## tags skill, defines, assistant, implementing, tasks, openspec, change, spec ## symbols diff --git a/.opencode/skills/openspec-archive-change/.pi-map.index.md b/.opencode/skills/openspec-archive-change/.pi-map.index.md index dcc1fbe..1ce1dc8 100644 --- a/.opencode/skills/openspec-archive-change/.pi-map.index.md +++ b/.opencode/skills/openspec-archive-change/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/skills/openspec-archive-change ## role -Provides a skill definition for archiving completed changes in an experimental workflow using the openspec CLI. +Provides a reusable automation skill for archiving completed experimental changes via the openspec CLI ## parent index: .opencode/skills/.pi-map.index.md map: .opencode/skills/.pi-map.md diff --git a/.opencode/skills/openspec-archive-change/.pi-map.md b/.opencode/skills/openspec-archive-change/.pi-map.md index 3de49d1..8b3e61d 100644 --- a/.opencode/skills/openspec-archive-change/.pi-map.md +++ b/.opencode/skills/openspec-archive-change/.pi-map.md @@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-archive-change index: .opencode/skills/openspec-archive-change/.pi-map.index.md ## role -Provides a skill definition for archiving completed changes in an experimental workflow using the openspec CLI. +Provides a reusable automation skill for archiving completed experimental changes via the openspec CLI ## files - SKILL.md | Defines a skill for archiving completed changes in an experimental workflow using the openspec CLI. | dep: openspec CLI, AskUserQuestion tool, Task tool, file system (mkdir, mv, read), JSON parsing ## arch -Single-file skill definition using markdown-based skill documentation pattern with CLI tool integration. +Skill-based modular automation pattern using markdown-defined CLI operations with structured metadata and command templates ## tags skill, defines, archiving, completed, changes, experimental, workflow, openspec ## symbols diff --git a/.opencode/skills/openspec-explore/.pi-map.index.md b/.opencode/skills/openspec-explore/.pi-map.index.md index 720e4a2..0d53c8b 100644 --- a/.opencode/skills/openspec-explore/.pi-map.index.md +++ b/.opencode/skills/openspec-explore/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/skills/openspec-explore ## role -Defines a conversational AI skill that acts as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. +Defines a conversational AI skill/persona for "explore mode" that serves as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. ## parent index: .opencode/skills/.pi-map.index.md map: .opencode/skills/.pi-map.md diff --git a/.opencode/skills/openspec-explore/.pi-map.md b/.opencode/skills/openspec-explore/.pi-map.md index 5c0c982..d6f65b6 100644 --- a/.opencode/skills/openspec-explore/.pi-map.md +++ b/.opencode/skills/openspec-explore/.pi-map.md @@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-explore index: .opencode/skills/openspec-explore/.pi-map.index.md ## role -Defines a conversational AI skill that acts as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. +Defines a conversational AI skill/persona for "explore mode" that serves as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. ## files - SKILL.md | Defines a conversational AI skill/persona for "explore mode" - a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. | dep: openspec CLI ## arch -Markdown-based skill definition using persona/role-prompting pattern with structured behavioral guidelines for non-implementation exploratory conversations. +Single-file skill definition using markdown-based persona specification with structured sections for description, usage guidelines, and behavioral constraints. ## tags skill, defines, conversational, persona, explore, mode, thinking, partner ## symbols diff --git a/.opencode/skills/openspec-propose/.pi-map.index.md b/.opencode/skills/openspec-propose/.pi-map.index.md index fb7e65c..18c22e0 100644 --- a/.opencode/skills/openspec-propose/.pi-map.index.md +++ b/.opencode/skills/openspec-propose/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .opencode/skills/openspec-propose ## role -Defines a structured workflow skill for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order. +Provides a structured workflow skill for proposing new changes using the openspec CLI with artifact generation in dependency order. ## parent index: .opencode/skills/.pi-map.index.md map: .opencode/skills/.pi-map.md diff --git a/.opencode/skills/openspec-propose/.pi-map.md b/.opencode/skills/openspec-propose/.pi-map.md index f208bea..dd237d4 100644 --- a/.opencode/skills/openspec-propose/.pi-map.md +++ b/.opencode/skills/openspec-propose/.pi-map.md @@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-propose index: .opencode/skills/openspec-propose/.pi-map.index.md ## role -Defines a structured workflow skill for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order. +Provides a structured workflow skill for proposing new changes using the openspec CLI with artifact generation in dependency order. ## files - SKILL.md | Defines a structured workflow for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order. | dep: openspec CLI, AskUserQuestion tool, TodoWrite tool ## arch -Template-based skill definition using markdown documentation with structured workflow patterns for CLI-driven artifact generation and dependency-ordered execution. +Template-based skill definition using markdown documentation with sequential artifact generation (proposal → design → tasks) following dependency ordering. ## tags skill, defines, structured, workflow, proposing, new, changes, openspec ## symbols diff --git a/.pi-map.index.md b/.pi-map.index.md index ea22442..b1fd771 100644 --- a/.pi-map.index.md +++ b/.pi-map.index.md @@ -16,7 +16,7 @@ dir: . Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. +Infrastructure and deployment configuration package for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. ## parent - ## children diff --git a/.pi-map.md b/.pi-map.md index 1823708..bb1c193 100644 --- a/.pi-map.md +++ b/.pi-map.md @@ -18,7 +18,7 @@ index: ./.pi-map.index.md Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. +Infrastructure and deployment configuration package for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. ## files - .env.example | Provides a template of environment variables for configuring a Headquarter application with PostgreSQL, Redis, Authentik SSO, and Docker/Traefik deployment - .gitignore | Specifies files and directories for Git to ignore across a multi-language project with Python, Node, and custom tooling | dep: Git @@ -31,7 +31,7 @@ Infrastructure and deployment configuration for a self-hosted project management - progress.md | Tracks completed and remaining tasks for a backend-frontend code refactoring project organized in 7 phases - swap-pane | Empty file with no functionality ## arch -Containerized microservices architecture using Docker Compose with PostgreSQL/Redis data layer, Traefik reverse proxy for TLS termination, environment-based configuration pattern, and Makefile-driven development workflow. +Containerized microservices architecture using Docker Compose with PostgreSQL and Redis backing services, Traefik reverse proxy for TLS termination, environment-driven configuration pattern, and Makefile-based development workflow automation. ## tags docker, redis, git, application, postgresql, compose, traefik, project ## symbols diff --git a/.stoneforge/.pi-map.index.md b/.stoneforge/.pi-map.index.md index b5ef699..12c31e6 100644 --- a/.stoneforge/.pi-map.index.md +++ b/.stoneforge/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .stoneforge ## role -Hidden system directory storing runtime state, configuration, and version-control metadata for the Stoneforge application. +Internal configuration and state tracking directory for the Stoneforge application ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/.stoneforge/.pi-map.md b/.stoneforge/.pi-map.md index 7aed4a8..1ac8d34 100644 --- a/.stoneforge/.pi-map.md +++ b/.stoneforge/.pi-map.md @@ -4,13 +4,13 @@ dir: .stoneforge index: .stoneforge/.pi-map.index.md ## role -Hidden system directory storing runtime state, configuration, and version-control metadata for the Stoneforge application. +Internal configuration and state tracking directory for the Stoneforge application ## files - .dashboard-opened | Stores timestamp and identifier data for tracking when a dashboard was opened - .gitignore | Specifies files and patterns for Git to ignore in version control - config.yaml | Configuration file for the Stoneforge application defining database, sync, playbook, identity, merge, workflow, and agent settings. ## arch -Simple flat-file storage with YAML-based configuration, dotfile-based state tracking, and standard Git ignore patterns. +Simple dot-directory pattern storing metadata (.dashboard-opened), version control exclusions (.gitignore), and hierarchical YAML configuration (config.yaml) with domain-separated settings ## tags config, stores, timestamp, identifier, data, tracking, dashboard, was ## symbols diff --git a/.stoneforge/sync/.pi-map.index.md b/.stoneforge/sync/.pi-map.index.md index f83bbb7..dcfbcdb 100644 --- a/.stoneforge/sync/.pi-map.index.md +++ b/.stoneforge/sync/.pi-map.index.md @@ -2,7 +2,7 @@ dir: .stoneforge/sync ## role -Distributed task coordination and ephemeral worker agent management for a multi-agent execution system. +Persists distributed task execution state by storing dependency graphs and ephemeral worker agent records for a collaborative workflow system. ## parent index: .stoneforge/.pi-map.index.md map: .stoneforge/.pi-map.md diff --git a/.stoneforge/sync/.pi-map.md b/.stoneforge/sync/.pi-map.md index 97f8014..7782f0c 100644 --- a/.stoneforge/sync/.pi-map.md +++ b/.stoneforge/sync/.pi-map.md @@ -4,12 +4,12 @@ dir: .stoneforge/sync index: .stoneforge/sync/.pi-map.index.md ## role -Distributed task coordination and ephemeral worker agent management for a multi-agent execution system. +Persists distributed task execution state by storing dependency graphs and ephemeral worker agent records for a collaborative workflow system. ## files - dependencies.jsonl | Stores a sequence of dependency relationships between entities in JSON Lines format, tracking parent-child, blocking, and reply relationships with timestamps and creators. - elements.jsonl | Stores JSONL records of ephemeral worker agents with their session history, worktree assignments, and lifecycle metadata for a distributed task execution system. ## arch -Event-sourced JSONL append-only logs with entity-relationship graph tracking, session-based worker lifecycle management, and decentralized worktree assignment. +Event-sourced JSONL append-only logs with entity-relationship modeling (parent-child, blocking, reply) and session-based worker lifecycle tracking. ## tags stores, relationships, dependencies, elements, sequence, dependency, entities, json ## symbols diff --git a/apps/.pi-map.index.md b/apps/.pi-map.index.md index fe888c5..0486d98 100644 --- a/apps/.pi-map.index.md +++ b/apps/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps ## role -Contains the main application entry points and executable modules for the project. +Contains the main deployable application entry points and executable components of the project. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/apps/.pi-map.md b/apps/.pi-map.md index 327acd1..a2781cf 100644 --- a/apps/.pi-map.md +++ b/apps/.pi-map.md @@ -4,10 +4,10 @@ dir: apps index: apps/.pi-map.index.md ## role -Contains the main application entry points and executable modules for the project. +Contains the main deployable application entry points and executable components of the project. ## files ## arch -Follows a modular application structure with separate directories for each deployable application, typically using framework-specific patterns (e.g., MVC, MVVM, or component-based architecture depending on the stack). +Typically follows a multi-app monorepo structure where each subdirectory is an independent application sharing common libraries/modules. ## tags - ## symbols diff --git a/apps/api/.pi-map.index.md b/apps/api/.pi-map.index.md index 35477e3..88b8481 100644 --- a/apps/api/.pi-map.index.md +++ b/apps/api/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api ## role -Backend API service that provides a self-hosted FastAPI server for managing development projects, git repositories, and containerized tools via Docker. +Self-hosted FastAPI backend API that manages projects, git repositories, and development tools through Docker container orchestration. ## parent index: apps/.pi-map.index.md map: apps/.pi-map.md diff --git a/apps/api/.pi-map.md b/apps/api/.pi-map.md index f3e1437..8c6df4a 100644 --- a/apps/api/.pi-map.md +++ b/apps/api/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api index: apps/api/.pi-map.index.md ## role -Backend API service that provides a self-hosted FastAPI server for managing development projects, git repositories, and containerized tools via Docker. +Self-hosted FastAPI backend API that manages projects, git repositories, and development tools through Docker container orchestration. ## files - .dockerignore | Specifies files and directories to exclude from Docker build context to reduce image size and avoid copying unnecessary files into containers. | dep: Docker - Dockerfile | Multi-stage Docker build for a Python application with Docker socket access, Cloudflare tunneling, and database dependency waiting | dep: python:3.11-slim, gcc, libpq-dev, docker-ce-cli, docker-compose-plugin, cloudflared, uvicorn, pyproject.toml dependencies @@ -14,7 +14,7 @@ Backend API service that provides a self-hosted FastAPI server for managing deve - uv.lock | Lock file for the uv Python package manager that pins exact dependency versions and their artifact hashes for reproducible installations | dep: uv, Python 3.11+, aiosqlite, alembic, annotated-doc, annotated-types, anyio, ast-serialize, asyncpg, and many other PyPI packages - wait-for-db.sh | Wait for a PostgreSQL database to become available before executing a command, with configurable retry logic. | dep: nc (netcat), sh (POSIX shell), sleep ## arch -Modern Python async architecture using FastAPI with SQLAlchemy/alembic for PostgreSQL, uv for dependency management, multi-stage Docker builds with Cloudflare tunneling, and health-check orchestration for database readiness. +Async Python backend using FastAPI with PostgreSQL (asyncpg), Alembic migrations, multi-stage Docker deployment with Cloudflare tunneling, uv package management, and containerized service coordination with database dependency waiting. ## tags docker, alembic, python, database, fastapi, postgresql, asyncpg, uvicorn ## symbols diff --git a/apps/api/alembic/.pi-map.index.md b/apps/api/alembic/.pi-map.index.md index 140c5c8..4cfb9d5 100644 --- a/apps/api/alembic/.pi-map.index.md +++ b/apps/api/alembic/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/alembic ## role -Database migration tooling that manages schema versioning and changes for the API's PostgreSQL database using Alembic with async SQLAlchemy. +Database migration infrastructure for managing schema evolution with async SQLAlchemy support. ## parent index: apps/api/.pi-map.index.md map: apps/api/.pi-map.md diff --git a/apps/api/alembic/.pi-map.md b/apps/api/alembic/.pi-map.md index 0994834..3a75883 100644 --- a/apps/api/alembic/.pi-map.md +++ b/apps/api/alembic/.pi-map.md @@ -4,16 +4,23 @@ dir: apps/api/alembic index: apps/api/alembic/.pi-map.index.md ## role -Database migration tooling that manages schema versioning and changes for the API's PostgreSQL database using Alembic with async SQLAlchemy. +Database migration infrastructure for managing schema evolution with async SQLAlchemy support. ## files -- env.py | Configures Alembic database migration environment with async SQLAlchemy support for a project. | dep: alembic, sqlalchemy, sqlalchemy.ext.asyncio, logging.config, asyncio, src.config, src.models +- env.py | Configures Alembic database migration environment with async SQLAlchemy support for a project. | exp: func:run_migrations_offline() → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:do_run_migrations(connection: Connection) → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:run_async_migrations() → None, call:async_engine_from_config, call:config.get_section, call:connectable.connect, call:connection.run_sync, call:connectable.dispose, func:run_migrations_online() → None, call:asyncio.run, call:run_async_migrations | dep: logging.config, alembic, sqlalchemy, sqlalchemy.engine, sqlalchemy.ext.asyncio, src.config, src.models, asyncio - script.py.mako | Alembic database migration script template that generates upgrade/downgrade functions for SQLAlchemy schema migrations | dep: alembic, sqlalchemy ## arch -Template-driven migration pattern using Alembic's declarative configuration with async engine setup, environment context management, and auto-generated revision scripts with upgrade/downgrade function pairs. +Alembic migration framework with async SQLAlchemy engine configuration and templated revision scripts. ## tags -sqlalchemy, alembic, database, migration, asyncio, config, src, env +migrations, run, sqlalchemy, async, alembic, call:context.configure, call:context.begin, transaction ## symbols -- +- run_migrations_offline +- do_run_migrations +- run_async_migrations +- run_migrations_online +- call:context.configure +- call:context.begin_transaction +- call:context.run_migrations +- call:async_engine_from_config ## workflows - change alembic behavior read: env.py, script.py.mako diff --git a/apps/api/alembic/versions/.pi-map.index.md b/apps/api/alembic/versions/.pi-map.index.md index 8bfeb6c..effdb4a 100644 --- a/apps/api/alembic/versions/.pi-map.index.md +++ b/apps/api/alembic/versions/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/alembic/versions ## role -Database schema evolution management for the API application, tracking incremental changes to tables supporting users, authentication, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, and notifications. +Database schema versioning and incremental migration management for the API application's relational database, tracking evolutionary changes to tables, columns, relationships, and data transformations across the project lifecycle. ## parent index: apps/api/alembic/.pi-map.index.md map: apps/api/alembic/.pi-map.md diff --git a/apps/api/alembic/versions/.pi-map.md b/apps/api/alembic/versions/.pi-map.md index 7ec55b0..f93e30e 100644 --- a/apps/api/alembic/versions/.pi-map.md +++ b/apps/api/alembic/versions/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/alembic/versions index: apps/api/alembic/versions/.pi-map.index.md ## role -Database schema evolution management for the API application, tracking incremental changes to tables supporting users, authentication, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, and notifications. +Database schema versioning and incremental migration management for the API application's relational database, tracking evolutionary changes to tables, columns, relationships, and data transformations across the project lifecycle. ## files - 0001_initial_schema.py | Defines the initial database schema migration creating five tables (users, ssh_keys, projects, git_repositories, user_configs) with relationships, indexes, and constraints using Alembic. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.String, call:postgresql.UUID, call:sa.DateTime, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:op.f, call:sa.Text, call:sa.ForeignKeyConstraint, call:sa.Boolean, call:postgresql.JSONB, func:downgrade() → None, call:op.drop_table, call:op.drop_index, call:op.f | dep: alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect - 0002_refresh_tokens.py | Alembic database migration that creates a refresh_tokens table with indexes for user authentication token management | exp: func:upgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:inspector.get_indexes, call:op.f, call:op.create_index, func:downgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:inspector.get_indexes, call:op.f, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql @@ -51,7 +51,7 @@ Database schema evolution management for the API application, tracking increment - af8512103d67_add_tool_type_fields.py | Alembic database migration that adds new columns (definition_type, dockerfile_template, build_context, readiness_probe) to the tool_types table with a CHECK constraint on definition_type. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql - f3d2dc90ba3a_merge_single_interface_and_clone_mode.py | Alembic database migration that merges two prior revisions (single_interface and clone_mode) into a single migration path | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic ## arch -Linear and branched Alembic migration pattern with merge migrations to reconcile divergent branches, using incremental revision files with upgrade/downgrade functions, idempotent operations, and occasional data migrations for schema transformations. +Linear and branched migration history using Alembic (SQLAlchemy's migration tool) with sequential numeric revisions, merge heads to reconcile divergent branches, idempotent data migrations, dialect-specific SQL (PostgreSQL/SQLite), JSON/JSONB columns for flexible schemas, and defensive checks for conditional schema changes; follows additive-only evolution with occasional table drops and column restructures, embedding both schema and data migration logic in revision files. ## tags column, table, call:op.drop, key, alembic, downgrade, upgrade, constraint ## symbols diff --git a/apps/api/src/.pi-map.index.md b/apps/api/src/.pi-map.index.md index fc19fea..766531d 100644 --- a/apps/api/src/.pi-map.index.md +++ b/apps/api/src/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src ## role -Core application package that bootstraps and configures the Headquarter API FastAPI service with its infrastructure concerns. +Core application package for the Headquarter API, handling configuration, database connectivity, structured logging, and FastAPI application initialization. ## parent index: apps/api/.pi-map.index.md map: apps/api/.pi-map.md diff --git a/apps/api/src/.pi-map.md b/apps/api/src/.pi-map.md index 6fd375f..582bffa 100644 --- a/apps/api/src/.pi-map.md +++ b/apps/api/src/.pi-map.md @@ -4,15 +4,15 @@ dir: apps/api/src index: apps/api/src/.pi-map.index.md ## role -Core application package that bootstraps and configures the Headquarter API FastAPI service with its infrastructure concerns. +Core application package for the Headquarter API, handling configuration, database connectivity, structured logging, and FastAPI application initialization. ## files - __init__.py | Marks the directory as a Python package for the Headquarter API. -- config.py | Defines application configuration settings using Pydantic with environment variable loading, database URL construction, and computed properties for service URLs and OAuth endpoints. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings -- database.py | Configures async SQLAlchemy database engine and session factory, and provides retry logic for database initialization with Alembic migrations via subprocess. | exp: func:init_database(max_retries, retry_delay) → bool, call:range, call:engine.connect, call:test_conn.execute, call:text, call:test_conn.close, call:logger.info, call:asyncio.get_event_loop().run_in_executor, call:subprocess.run, call:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy +- config.py | Defines application configuration settings with environment-based overrides using Pydantic, including database URLs, service domains, OAuth/Authentik integration, JWT/session settings, and computed properties for environment-specific behavior. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings +- database.py | Sets up async SQLAlchemy database engine and session factory, with retry logic for database connectivity testing and Alembic migration execution via subprocess. | exp: func:init_database(max_retries, retry_delay) → bool, call:range, call:engine.connect, call:test_conn.execute, call:text, call:test_conn.close, call:logger.info, call:asyncio.get_event_loop().run_in_executor, call:subprocess.run, call:os.path.dirname, call:os.path.abspath, call:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, os, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy - logging_config.py | Configures structured JSON logging with correlation ID injection, custom formatters, and HTTP request/exception middleware for a FastAPI application. | exp: class:CorrelationIdFilter, method:filter(self, record: logging.LogRecord) → bool, call:get_correlation_id, class:JSONFormatter, method:format(self, record: logging.LogRecord) → str, call:self.formatTime, call:record.getMessage, call:getattr, call:self.formatException, call:json.dumps, method:formatTime(self, record: logging.LogRecord, datefmt) → str, call:time.strftime, call:time.gmtime, class:RequestLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:time.time, call:logger.info, call:call_next, call:int, call:logger.error, call:type, call:traceback.format_exc, class:ExceptionLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:call_next, call:logger.critical, call:traceback.format_exc, func:configure_logging(level) → None, call:JSONFormatter, call:logging.StreamHandler, call:console_handler.setFormatter, call:console_handler.addFilter, call:CorrelationIdFilter, call:root_logger.setLevel, call:logging.getLogger("uvicorn").setLevel, call:logging.getLogger("uvicorn.access").setLevel, call:logging.getLogger("sqlalchemy.engine").setLevel, call:logger.info, call:logging.getLevelName | dep: json, logging, sys, time, traceback, collections.abc, fastapi, starlette.middleware.base, src.services.shared.correlation - main.py | Initializes and configures a FastAPI application for the "Headquarter API" with database setup, middleware, routing, and background services. | exp: func:_sanitize_validation_errors(errors), call:error.get, call:str, call:ctx.items, call:isinstance, call:type, call:sanitized.append, func:validation_exception_handler(request: Request, exc: RequestValidationError), call:exc.errors, call:logger.warning, call:_sanitize_validation_errors, call:JSONResponse, func:on_startup(), call:logger.info, call:init_database, call:logger.error, call:sys.exit, call:_health_monitor.start, call:seed_builtin_tool_types, func:on_shutdown(), call:logger.info, call:_health_monitor.stop | dep: logging, os, fastapi, fastapi.exceptions, fastapi.middleware.cors, fastapi.responses, fastapi.staticfiles, src.api.config, src.api.project, src.api.system, src.api.tool, src.api.user, src.api.workspace, src.config, src.models, src.database, src.logging_config, src.seeds.builtin_tool_types, src.services.instance, src.services.shared, sys, src.api.* ## arch -Layered configuration with Pydantic settings, async SQLAlchemy with Alembic migration integration, structured JSON logging with correlation ID tracking, and FastAPI middleware/routing setup. +Layered architecture with environment-based Pydantic config, async SQLAlchemy with retry patterns, structured JSON logging with correlation IDs, and modular FastAPI setup with middleware and background services. ## tags src, database, logging, call:logger.info, api, middleware, fastapi, filter ## symbols diff --git a/apps/api/src/api/.pi-map.index.md b/apps/api/src/api/.pi-map.index.md index 1ed61c7..3796d2d 100644 --- a/apps/api/src/api/.pi-map.index.md +++ b/apps/api/src/api/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api ## role -Defines reusable API validation utilities and package structure for FastAPI router organization. +Defines shared API infrastructure and reusable validation utilities for the API layer. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/api/.pi-map.md b/apps/api/src/api/.pi-map.md index 66417ff..fd22e5d 100644 --- a/apps/api/src/api/.pi-map.md +++ b/apps/api/src/api/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/api index: apps/api/src/api/.pi-map.index.md ## role -Defines reusable API validation utilities and package structure for FastAPI router organization. +Defines shared API infrastructure and reusable validation utilities for the API layer. ## files - __init__.py | Marks the directory as a Python package for API routers. - shared_validators.py | Provides reusable Pydantic validator functions for API schema validation including mount paths, files, environment variables, and volume mounts. | exp: func:validate_mount_path(v: str | None) → str | None, call:v.startswith, raise:ValueError, func:validate_files(v: dict | None, max_size_bytes) → dict | None, call:v.items, call:path.startswith, call:len, call:content.encode, raise:ValueError, func:validate_env_vars(v: dict | None) → dict | None, call:isinstance, raise:ValueError, func:validate_volumes(v: list | None) → list | None, call:isinstance, call:enumerate, raise:ValueError ## arch -Modular utility package with shared Pydantic validators for cross-cutting API schema concerns, following separation of validation logic from route handlers. +Modular package structure with shared Pydantic validators for cross-cutting schema validation concerns. ## tags validate, raise:value, error, call:isinstance, mount, api, init, path ## symbols diff --git a/apps/api/src/api/config/.pi-map.index.md b/apps/api/src/api/config/.pi-map.index.md index 11c36b7..780c15a 100644 --- a/apps/api/src/api/config/.pi-map.index.md +++ b/apps/api/src/api/config/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/config ## role -Exposes REST API endpoints for managing user configuration profiles and settings. +Provides FastAPI API endpoints for managing user configuration settings and configuration profiles. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/config/.pi-map.md b/apps/api/src/api/config/.pi-map.md index 852f2ef..44666cf 100644 --- a/apps/api/src/api/config/.pi-map.md +++ b/apps/api/src/api/config/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/src/api/config index: apps/api/src/api/config/.pi-map.index.md ## role -Exposes REST API endpoints for managing user configuration profiles and settings. +Provides FastAPI API endpoints for managing user configuration settings and configuration profiles. ## files - __init__.py | Aggregates and exports configuration-related API routers for the config module. | dep: src.api.config.config_profiles, src.api.config.user_config - config_profiles.py | FastAPI router providing CRUD endpoints for user config profiles with includes, resolution, defaults, and git URL validation | exp: func:list_config_profiles(project_id, tool_type_id, current_user_id, session), call:select(ConfigProfile) .where(ConfigProfile.user_id == user_uuid) .options, call:selectinload, call:uuid.UUID, call:conditions.append, call:ConfigProfile.project_id.is_, call:ConfigProfile.tool_type_id.is_, call:query.where, call:or_, call:session.execute, call:result.scalars().all, call:profile_to_response, func:create_config_profile(data: ConfigProfileCreate, current_user_id, session), call:create_profile, call:logger.debug, call:profile_to_response, func:get_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:profile_to_response, raise:HTTPException, func:update_config_profile(profile_id: str, data: ConfigProfileUpdate, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:update_profile, call:logger.debug, call:profile_to_response, raise:HTTPException, func:delete_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:session.delete, call:session.commit, call:logger.debug, raise:HTTPException, func:update_profile_includes_endpoint(profile_id: str, data: ConfigProfileIncludeUpdate, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:update_includes, call:session.execute, call:select(ConfigProfileInclude).where, call:inc_result.scalars().all, call:logger.debug, call:profile_to_response, call:list, raise:HTTPException, func:preview_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:resolve_profile, call:resolved_profile_to_dict, raise:HTTPException, func:resolve_default_profile_endpoint(project_id, tool_type_id, current_user_id, session), call:resolve_default_profile, call:uuid.UUID, func:get_default_profiles_endpoint(user_id, session) → dict, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, func:set_default_profiles_endpoint(data: DefaultProfilesUpdate, user_id, session) → dict, call:validate_default_profiles, call:get_or_create_user_config, call:session.commit, call:session.refresh, func:get_default_profile_for_tool_type_endpoint(tool_type_id: str, user_id, session) → dict, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:user_config.default_profiles.get, func:validate_git_url_endpoint(data: ValidateGitUrlRequest, current_user_id, session) → ValidateGitUrlResponse, call:validate_git_url | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.auth.dependencies, src.models, src.schemas.config, src.services.config.config_profile_resolver, src.services.config.crud_service, src.services.config.resolver_service - user_config.py | Provides FastAPI endpoints to get and update the current user's configuration settings, creating a default config if none exists. | exp: func:_get_or_create_config(session: AsyncSession, user_id: uuid.UUID) → UserConfig, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:UserConfig, call:session.add, call:session.commit, call:session.refresh, func:get_user_config(user_id, session) → UserConfigResponse, call:_get_user, call:_get_or_create_config, call:UserConfigResponse.model_validate, func:update_user_config(data: UserConfigUpdate, user_id, session) → UserConfigResponse, call:_get_user, call:_get_or_create_config, call:data.model_dump, call:logger.debug, call:session.commit, call:session.refresh, call:UserConfigResponse.model_validate | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.schemas.user ## arch -FastAPI router modules following domain-driven separation with CRUD patterns, validation logic, and automatic default initialization. +Modular FastAPI router pattern with separate route modules for distinct resource domains (user config vs config profiles), each implementing standard CRUD operations with validation and default initialization logic. ## tags config, profile, get, user, includes, call:uuid.uuid, or, default ## symbols diff --git a/apps/api/src/api/project/.pi-map.index.md b/apps/api/src/api/project/.pi-map.index.md index e5e2eda..55ccfa4 100644 --- a/apps/api/src/api/project/.pi-map.index.md +++ b/apps/api/src/api/project/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/project ## role -Provides REST API endpoints for project and Git repository management in the backend service. +Provides FastAPI REST API endpoints for project and Git repository management, serving as the HTTP interface layer for the project's core domain operations. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/project/.pi-map.md b/apps/api/src/api/project/.pi-map.md index e517ee7..7587fed 100644 --- a/apps/api/src/api/project/.pi-map.md +++ b/apps/api/src/api/project/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/src/api/project index: apps/api/src/api/project/.pi-map.index.md ## role -Provides REST API endpoints for project and Git repository management in the backend service. +Provides FastAPI REST API endpoints for project and Git repository management, serving as the HTTP interface layer for the project's core domain operations. ## files - __init__.py | Aggregates and exports project-related API routers from submodules. | dep: src.api.project.git_repositories, src.api.project.projects - git_repositories.py | Implements FastAPI REST endpoints for managing Git repositories, including CRUD operations, SSH key management, file browsing, branch operations, and git commands (clone, commit, push, pull, merge, etc.) for both project-scoped and external repositories. | exp: func:_get_repo(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID) → GitRepository, call:_get_user, call:_get_owned_project, call:session.get, raise:HTTPException, func:_get_repo_on_disk(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID) → GitRepository, call:_get_repo, call:os.path.exists, raise:HTTPException, func:_parse_remote_url(remote_url: str | None, force_original: bool) → str | None, call:parse_git_url, call:parse_result.get, raise:HTTPException, func:_commit_author(session: AsyncSession, user_id: uuid.UUID) → tuple[str, str], call:_get_user, func:list_user_repositories(user_id, session) → list[GitRepository], call:session.execute, call:select(GitRepository).where, call:list, call:result.scalars().all, func:parse_repository_url(data: URLParseRequest) → URLParseResponse, call:URLParseResponse, call:parse_git_url, func:create_external_repository(data: GitRepositoryCreate, user_id, session) → GitRepository, call:_get_user, call:session.execute, call:select(GitRepository).where, call:GitRepository.project_id.is_, call:existing.scalar_one_or_none, call:_parse_remote_url, call:uuid.UUID, call:session.get, call:preflight_remote_repository, call:session.add, call:session.flush, call:clone_working_repository, call:session.rollback, call:init_working_repository, call:session.commit, raise:HTTPException, func:list_repositories(project_id: uuid.UUID, user_id, session) → list[GitRepository], call:_get_user, call:_get_owned_project, call:session.execute, call:select(GitRepository).where, call:list, call:result.scalars().all, func:delete_repository(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → Response, call:_get_repo, call:os.path.exists, call:shutil.rmtree, call:session.delete, call:session.commit, call:Response, func:create_repository(project_id: uuid.UUID, data: GitRepositoryCreate, user_id, session) → GitRepository, call:_get_user, call:_get_owned_project, call:session.execute, call:select(GitRepository).where, call:existing.scalar_one_or_none, call:_parse_remote_url, call:uuid.UUID, call:session.get, call:preflight_remote_repository, call:get_repo_path, call:os.makedirs, call:os.path.dirname, call:clone_working_repository, call:init_working_repository, call:GitRepository, call:session.add, call:session.commit, call:session.refresh, raise:HTTPException, func:update_repository_ssh_key(project_id: uuid.UUID, repo_id: uuid.UUID, data: UpdateSSHKeyRequest, user_id, session) → GitRepository, call:_get_repo, call:uuid.UUID, call:session.get, call:session.commit, call:session.refresh, raise:HTTPException, func:get_repository_history(project_id: uuid.UUID, repo_id: uuid.UUID, view, branch, limit, offset, user_id, session) → dict, call:_get_repo_on_disk, call:get_commit_history, raise:HTTPException, func:get_repository_commit(project_id: uuid.UUID, repo_id: uuid.UUID, commit_hash: str, user_id, session) → dict, call:_get_repo_on_disk, call:get_commit_detail, raise:HTTPException, func:list_repository_files(project_id: uuid.UUID, repo_id: uuid.UUID, branch, path, user_id, session) → FileListResponse, call:_get_repo_on_disk, call:list_tree, call:FileListResponse, call:logger.error, call:str, raise:HTTPException, func:get_repository_file_content(project_id: uuid.UUID, repo_id: uuid.UUID, branch: str, path: str, user_id, session) → FileContentResponse, call:_get_repo_on_disk, call:get_file_content, call:FileContentResponse, raise:HTTPException, func:get_repository_branches(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → BranchesResponse, call:_get_repo, call:os.path.isdir, call:os.path.join, call:os.path.isfile, call:list_branches, call:BranchesResponse, call:logger.error, call:str, call:session.get, call:list_remote_branches, raise:HTTPException, func:update_repository_file(project_id: uuid.UUID, repo_id: uuid.UUID, data: FileUpdateRequest, user_id, session) → FileUpdateResponse, call:_get_repo_on_disk, call:_commit_author, call:commit_file, call:FileUpdateResponse, raise:HTTPException, func:get_repository_status(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → StatusResponse, call:_get_repo_on_disk, call:get_status, call:StatusResponse, raise:HTTPException, func:create_repository_branch(project_id: uuid.UUID, repo_id: uuid.UUID, data: BranchCreateRequest, user_id, session) → dict, call:_get_repo_on_disk, call:create_branch, raise:HTTPException, func:delete_repository_branch(project_id: uuid.UUID, repo_id: uuid.UUID, branch_name: str, force, user_id, session) → dict, call:_get_repo_on_disk, call:delete_branch, raise:HTTPException, func:checkout_repository_branch(project_id: uuid.UUID, repo_id: uuid.UUID, data: CheckoutRequest, user_id, session) → dict, call:_get_repo_on_disk, call:checkout_branch, raise:HTTPException, func:commit_repository_changes(project_id: uuid.UUID, repo_id: uuid.UUID, data: CommitRequest, user_id, session) → CommitResponse, call:_get_repo_on_disk, call:_commit_author, call:commit_changes, call:CommitResponse, raise:HTTPException, func:fetch_repository(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → FetchResponse, call:_get_repo_on_disk, call:fetch, call:FetchResponse, raise:HTTPException, func:pull_repository(project_id: uuid.UUID, repo_id: uuid.UUID, branch, user_id, session) → PullResponse, call:_get_repo_on_disk, call:pull, call:PullResponse, raise:HTTPException, func:push_repository(project_id: uuid.UUID, repo_id: uuid.UUID, branch, user_id, session) → PushResponse, call:_get_repo_on_disk, call:push, call:PushResponse, raise:HTTPException, func:merge_repository_branches(project_id: uuid.UUID, repo_id: uuid.UUID, data: MergeRequest, user_id, session) → MergeResponse, call:_get_repo_on_disk, call:merge, call:MergeResponse, raise:HTTPException | dep: logging, os, shutil, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.schemas.project.git_repository, src.services.git.operations, src.utils.git_control, src.utils.git_files, src.utils.git_history, src.utils.git_url_parser - projects.py | Implements FastAPI REST endpoints for CRUD operations on projects, including nested repository/workspace listing and filesystem cleanup on deletion. | exp: func:create_project(data: ProjectCreate, user_id, session) → Project, call:_get_user, call:Project, call:session.add, call:session.commit, call:session.refresh, func:list_projects(user_id, session) → list[dict], call:_get_user, call:session.execute, call:select(Project) .where(Project.owner_id == user.id) .order_by, call:Project.created_at.desc, call:result.scalars().all, call:select(GitRepository).where, call:repos_result.scalars().all, call:select(Workspace).where, call:ws_result.scalars().all, call:select(func.count()).where, call:func.count, call:inst_result.scalar, call:workspaces.append, call:str, call:repositories.append, call:enriched.append, call:project.created_at.isoformat, func:get_project(project_id: uuid.UUID, user_id, session) → Project, call:_get_user, call:_get_owned_project, func:update_project(project_id: uuid.UUID, data: ProjectUpdate, user_id, session) → Project, call:_get_user, call:_get_owned_project, call:session.commit, call:session.refresh, func:delete_project(project_id: uuid.UUID, user_id, session) → Response, call:_get_user, call:_get_owned_project, call:session.execute, call:select(GitRepository).where, call:result.scalars().all, call:os.path.exists, call:shutil.rmtree, call:session.delete, call:session.commit, call:Response, func:set_default_ssh_key(project_id: uuid.UUID, data: SetDefaultSSHKeyRequest, user_id, session) → Project, call:_get_user, call:_get_owned_project, call:session.get, call:session.commit, call:session.refresh, raise:HTTPException | dep: os, shutil, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models.project, src.schemas.project ## arch -Modular FastAPI router pattern with separate endpoint modules for distinct resource domains (projects vs. git repositories), using CRUD-based operations with filesystem integration and git CLI automation. +Modular router-based architecture using FastAPI with separate modules for distinct resource domains (projects vs. git repositories), each implementing full CRUD plus specialized operations, aggregated via __init__.py for centralized router registration. ## tags get, call:, repository, raise:httpexception, repo, on, disk, project ## symbols diff --git a/apps/api/src/api/system/.pi-map.index.md b/apps/api/src/api/system/.pi-map.index.md index 64757ef..f6e68ad 100644 --- a/apps/api/src/api/system/.pi-map.index.md +++ b/apps/api/src/api/system/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/system ## role -Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, events, notifications, and container terminal access. +Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, event streaming, notifications, and container terminal access. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/system/.pi-map.md b/apps/api/src/api/system/.pi-map.md index 893f584..e5f2fc5 100644 --- a/apps/api/src/api/system/.pi-map.md +++ b/apps/api/src/api/system/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/api/system index: apps/api/src/api/system/.pi-map.index.md ## role -Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, events, notifications, and container terminal access. +Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, event streaming, notifications, and container terminal access. ## files - __init__.py | Aggregates and re-exports system API router modules from submodules for centralized access. | dep: src.api.system.dashboard, src.api.system.events, src.api.system.health, src.api.system.instance_proxy, src.api.system.notifications, src.api.system.terminal - dashboard.py | Provides a FastAPI endpoint that returns a dashboard summary with aggregated counts of projects, repositories, SSH keys, and recent activity for the authenticated user. | exp: func:get_dashboard_summary(user_id, session) → dict, call:session.execute, call:select(func.count()).select_from(Project).where, call:func.count, call:projects_result.scalar, call:select(func.count()).select_from(GitRepository).where, call:repos_result.scalar, call:select(func.count()).select_from(SSHKey).where, call:ssh_keys_result.scalar, call:select(Project) .where(Project.owner_id == user_id) .order_by(Project.created_at.desc()) .limit, call:Project.created_at.desc, call:recent_projects.scalars().all | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models.project, src.models (GitRepository, Project, SSHKey) @@ -14,7 +14,7 @@ Provides system-level API endpoints for monitoring, administration, and infrastr - notifications.py | Defines FastAPI REST endpoints for managing user notifications (list, unread count, mark read, dismiss/clear) with support for muted categories from user config. | exp: class:NotificationItem, class:NotificationListResponse, class:UnreadCountResponse, class:MarkAllReadResponse, class:ClearAllResponse, func:_get_mute_categories(session: AsyncSession, user_id: uuid.UUID) → list[str], call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:config.config.get, call:isinstance, func:list_notifications(limit, offset, unread_only, user, session) → NotificationListResponse, call:_get_mute_categories, call:notification_service.list_notifications, call:NotificationListResponse, call:NotificationItem.model_validate, func:get_unread_count(user, session) → UnreadCountResponse, call:notification_service.get_unread_count, call:UnreadCountResponse, func:mark_notification_read(notification_id: uuid.UUID, user, session) → NotificationItem, call:notification_service.mark_read, call:NotificationItem.model_validate, raise:HTTPException, func:mark_all_read(user, session) → MarkAllReadResponse, call:notification_service.mark_all_read, call:MarkAllReadResponse, func:clear_all_notifications(user, session) → ClearAllResponse, call:notification_service.dismiss_all, call:ClearAllResponse, func:dismiss_notification(notification_id: uuid.UUID, user, session) → None, call:notification_service.dismiss, raise:HTTPException | dep: uuid, datetime, fastapi, pydantic, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.models, src.services.shared.notification_service, sqlalchemy - terminal.py | Provides WebSocket and HTTP endpoints for managing interactive terminal sessions attached to running Docker container tool instances, including session creation, attachment, input/output streaming, resize/reset control messages, and session listing. | exp: class:SessionRef, method:__init__(self, session, slot_session_id), func:terminal_websocket_default(websocket: WebSocket, instance_id: str, db_session) → None, call:_handle_terminal_websocket, func:terminal_websocket_specific(websocket: WebSocket, instance_id: str, session_id: str, db_session) → None, call:_handle_terminal_websocket, func:_handle_terminal_websocket(websocket: WebSocket, instance_id: str, target_session_id: str | None, db_session: AsyncSession) → None, call:logger.debug, call:websocket.accept, call:uuid.UUID, call:logger.error, call:websocket.close, call:_get_user_from_websocket, call:logger.warning, call:db_session.get, call:get_container_status, call:terminal_manager.get_or_create_session, call:terminal_manager.get_session, call:logger.info, call:terminal_manager.create_session, call:terminal_manager._find_key_by_internal_id, call:terminal_manager.attach_websocket, call:websocket.send_json, call:SessionRef, call:asyncio.create_task, call:_write_loop, call:_heartbeat_loop, call:asyncio.wait, call:len, call:task.cancel, call:str, call:suppress, call:terminal_manager.detach_websocket, func:_write_loop(session_ref: SessionRef, websocket, instance_id: str) → None, call:session.is_alive, call:asyncio.sleep, call:websocket.receive, call:session.write_input, call:text.startswith, call:json.loads, call:ctrl.get, call:logger.debug, call:session.resize, call:session.acknowledge_data, call:websocket.send_json, call:terminal_manager.reset_session, call:terminal_manager.attach_websocket, call:text.encode, func:_heartbeat_loop(websocket: WebSocket) → None, call:asyncio.sleep, call:websocket.send_json, func:_get_terminal_instance(instance_id: uuid.UUID, user_id: uuid.UUID, db_session: AsyncSession) → ToolInstance, call:db_session.get, raise:HTTPException, func:list_terminal_sessions(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.execute, call:select(TerminalSessionModel) .where(TerminalSessionModel.instance_id == instance_id) .where(TerminalSessionModel.status != "closed") .order_by, call:TerminalSessionModel.created_at.asc, call:result.scalars().all, call:terminal_manager.get_session, call:str, call:sessions.append, call:live_session.has_websockets, call:row.created_at.isoformat, call:row.last_activity_at.isoformat, func:create_terminal_session(instance_id: uuid.UUID, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:data.get, call:terminal_manager.create_session, raise:HTTPException, func:close_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:terminal_manager.close_session, raise:HTTPException, func:reset_specific_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:db_session.get, call:terminal_manager.reset_session, raise:HTTPException, func:rename_terminal_session(instance_id: uuid.UUID, session_id: str, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:data.get, call:isinstance, call:terminal_manager.get_session, call:str, call:db_session.get, call:uuid.UUID, call:db_session.commit, raise:HTTPException, func:reset_terminal_session(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:terminal_manager.reset_session, call:logger.info, call:str, call:logger.error, raise:HTTPException, func:_get_user_from_websocket(websocket: WebSocket, db_session: AsyncSession) → uuid.UUID | None, call:websocket.cookies.get, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str | dep: asyncio, json, logging, uuid, contextlib, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, starlette.websockets, src.auth.dependencies, src.models, src.services.terminal.terminal_manager, src.services.docker, src.auth.session, src.config, starlette ## arch -FastAPI modular router pattern with separate files per domain concern, combining REST endpoints, SSE streaming, WebSocket connections, and HTTP proxying; uses dependency injection for auth and integrates with Docker/container runtime for terminal and instance proxy features. +FastAPI router modules organized by domain concern with async/await patterns, SSE/WebSocket for real-time streaming, proxy pattern for container instance forwarding, and per-user authentication/authorization with connection limiting. ## tags session, terminal, call:terminal, call:, src, get, response, websocket ## symbols diff --git a/apps/api/src/api/tool/.pi-map.index.md b/apps/api/src/api/tool/.pi-map.index.md index da8b35e..dd14ddb 100644 --- a/apps/api/src/api/tool/.pi-map.index.md +++ b/apps/api/src/api/tool/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/tool ## role -Provides FastAPI REST API endpoints and routers for managing the complete lifecycle of Docker-based tools, including type definitions, instances, sessions, and lifecycle operations. +Provides FastAPI REST API endpoints for managing Docker-based tools, including their definitions, types, instances, lifecycle operations, and active sessions. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/tool/.pi-map.md b/apps/api/src/api/tool/.pi-map.md index 4192232..3b5f2cd 100644 --- a/apps/api/src/api/tool/.pi-map.md +++ b/apps/api/src/api/tool/.pi-map.md @@ -4,17 +4,17 @@ dir: apps/api/src/api/tool index: apps/api/src/api/tool/.pi-map.index.md ## role -Provides FastAPI REST API endpoints and routers for managing the complete lifecycle of Docker-based tools, including type definitions, instances, sessions, and lifecycle operations. +Provides FastAPI REST API endpoints for managing Docker-based tools, including their definitions, types, instances, lifecycle operations, and active sessions. ## files - __init__.py | Aggregates and exports all tool-related API routers from submodules as a unified module interface. | dep: src.api.tool.sessions, src.api.tool.tool_definitions, src.api.tool.tool_instances, src.api.tool.tool_lifecycle, src.api.tool.tool_types -- sessions.py | API endpoint that retrieves all active tool instances (sessions) for the currently authenticated user with related metadata | exp: func:get_user_sessions(user_id, session) → dict, call:_get_user, call:session.execute, call:select(ToolInstance) .where(ToolInstance.owner_id == user_id) .where( ToolInstance.status.in_( ["running", "building", "pending", "stopped", "error"] ) ) .order_by, call:ToolInstance.status.in_, call:ToolInstance.created_at.desc, call:result.scalars().all, call:session.get, call:sessions.append, call:str, call:instance.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models +- sessions.py | Provides a FastAPI endpoint to retrieve all active tool instances (sessions) for the currently authenticated user with related metadata. | exp: func:get_user_sessions(user_id, session) → dict, call:_get_user, call:session.execute, call:select(ToolInstance) .where(ToolInstance.owner_id == user_id) .where( ToolInstance.status.in_( ["running", "building", "pending", "stopped", "error"] ) ) .order_by, call:ToolInstance.status.in_, call:ToolInstance.created_at.desc, call:result.scalars().all, call:session.get, call:sessions.append, call:str, call:instance.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models (GitRepository, Project, ToolInstance, ToolType, Workspace) - tool_definitions.py | FastAPI router providing CRUD endpoints and manifest compilation for tool definition manifests stored in a database. | exp: class:CreateToolDefinitionRequest, class:UpdateToolDefinitionRequest, func:create_tool_definition(data: CreateToolDefinitionRequest, user_id, session) → dict, call:uuid.UUID, call:session.get, call:session.execute, call:select(ToolDefinitionManifest).where, call:existing.scalar_one_or_none, call:ToolDefinitionManifest, call:session.add, call:session.commit, call:session.refresh, call:logger.info, call:str, call:definition.created_at.isoformat, raise:HTTPException, func:list_tool_definitions(user_id, session, include_bases) → dict, call:select, call:query.where, call:ToolDefinitionManifest.is_base.is_, call:session.execute, call:query.order_by, call:ToolDefinitionManifest.created_at.desc, call:result.scalars().all, call:str, call:d.created_at.isoformat, func:get_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:str, call:definition.created_at.isoformat, call:definition.updated_at.isoformat, raise:HTTPException, func:update_tool_definition(definition_id: uuid.UUID, data: UpdateToolDefinitionRequest, user_id, session) → dict, call:session.get, call:session.commit, call:session.refresh, call:logger.info, call:str, call:definition.updated_at.isoformat, raise:HTTPException, func:delete_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:session.execute, call:select(ToolType).where, call:result.scalars().all, call:", ".join, call:session.delete, call:session.commit, call:logger.info, call:str, raise:HTTPException, func:compile_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:dict, call:resolve_base, call:deep_merge, call:compile_dockerfile, call:compile_entrypoint, call:compute_image_tag, call:compile_compose, call:session.commit, call:str, raise:HTTPException | dep: logging, uuid, fastapi, pydantic, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.build.manifest_compiler - tool_instances.py | Provides FastAPI REST endpoints for managing tool instances including CRUD operations, logs, health checks, tunnel recreation, event history, and HTTP proxying to running containers. | exp: func:create_instance(project_id: uuid.UUID, repo_id: uuid.UUID, data: CreateInstanceRequest, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:create_tool_instance, call:str, call:instance.created_at.isoformat, raise:HTTPException, func:list_instances(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → list[dict], call:_get_user, call:_get_owned_project, call:session.execute, call:select(ToolInstance) .where(ToolInstance.repository_id == repo_id) .where(ToolInstance.owner_id == user_id) .order_by, call:ToolInstance.created_at.desc, call:result.scalars().all, call:str, call:i.created_at.isoformat, func:get_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_status, call:str, call:instance.created_at.isoformat, call:instance.last_started_at.isoformat, raise:HTTPException, func:rename_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:data.get("display_name", "").strip, call:rename_tool_instance, call:str, raise:HTTPException, func:get_instance_logs(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, tail, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_logs, raise:HTTPException, func:recreate_tunnel_endpoint(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:recreate_instance_tunnel, raise:HTTPException, func:check_instance_tunnel_health(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_status, call:instance.probe_result.get, call:"\n".join, call:check_tunnel_health, call:tunnel_health.get, raise:HTTPException, func:get_instance_events(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, limit, user_id, session) → list[dict], call:_get_user, call:_get_owned_project, call:session.get, call:session.execute, call:select(InstanceEvent) .where(InstanceEvent.instance_id == instance_id) .order_by(InstanceEvent.created_at.desc()) .limit, call:InstanceEvent.created_at.desc, call:result.scalars().all, call:str, call:row.created_at.isoformat, raise:HTTPException, func:proxy_to_instance(request: Request, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, path, user_id, session) → Response, call:session.get, call:str, call:dict, call:headers.pop, call:httpx.AsyncClient, call:request.body, call:client.request, call:logger.error, call:response_headers.pop, call:Response, raise:HTTPException | dep: logging, uuid, httpx, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.docker, src.services.shared.tunnel, src.schemas.tool, src.services.tool.instance_service - tool_lifecycle.py | FastAPI router providing REST endpoints for managing Docker-based tool instance lifecycle operations (start, stop, restart, delete). | exp: func:start_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:start_tool_instance, raise:HTTPException, func:stop_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:stop_tool_instance, raise:HTTPException, func:restart_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:restart_tool_instance, raise:HTTPException, func:delete_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, force, user_id, session) → None, call:_get_user, call:_get_owned_project, call:delete_tool_instance, call:str, call:detail.lower, raise:HTTPException | dep: logging, uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.schemas.tool, src.services.tool.instance_service - tool_types.py | Defines FastAPI routes for CRUD operations and validation of Docker tool types with compose/dockerfile/manifest definitions. | exp: func:_require_admin(user: User) → None, func:create_tool_type(data: ToolTypeCreate, user_id, session) → ToolType, call:_get_user, call:_require_admin, call:session.scalar, call:select(ToolType).where, call:ToolType, call:session.add, call:session.commit, call:session.refresh, raise:HTTPException, func:list_tool_types(user_id, session) → list[ToolType], call:_get_user, call:session.execute, call:select(ToolType).order_by, call:list, call:result.scalars().all, func:get_tool_type(tool_type_id: uuid.UUID, user_id, session) → ToolType, call:_get_user, call:session.get, raise:HTTPException, func:update_tool_type(tool_type_id: uuid.UUID, data: ToolTypeUpdate, user_id, session) → ToolType, call:_get_user, call:_require_admin, call:session.get, call:data.model_dump, call:update_data.get, call:validate_compose_yaml, call:check_port_exposed, call:validate_required_variables, call:update_data.items, call:setattr, call:session.commit, call:session.refresh, raise:HTTPException, func:validate_tool_type_template(data: ToolTypeValidateRequest, user_id, session) → dict, call:_get_user, call:errors.append, call:validate_compose_yaml, call:str, call:data.dockerfile_template.strip().startswith, call:len, func:validate_tool_type(tool_type_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:session.get, call:errors.append, call:validate_compose_yaml, call:str, call:tool_type.dockerfile_template.strip().startswith, call:len, raise:HTTPException, func:delete_tool_type(tool_type_id: uuid.UUID, user_id, session) → None, call:_get_user, call:_require_admin, call:session.get, call:session.delete, call:session.commit, raise:HTTPException | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.api.tool.tool_types_validation, src.auth.dependencies, src.models, src.models.user, src.schemas.tool -- tool_types_validation.py | Validates Docker Compose YAML templates by sanitizing template variables, parsing YAML, checking required structure, verifying port exposure, and ensuring required variables are present. | exp: func:sanitize_template_vars(template: str) → str, call:re.sub, func:validate_compose_yaml(template: str) → dict, call:sanitize_template_vars, call:yaml.safe_load, call:isinstance, raise:ValueError, func:check_port_exposed(parsed: dict, port: int) → bool, call:str, call:isinstance, call:parsed["services"].values, func:validate_required_variables(template: str, variables: list[str]) → None, raise:HTTPException | dep: re, yaml, fastapi, fastapi.HTTPException, fastapi.status +- tool_types_validation.py | Validates Docker Compose YAML templates by sanitizing template variables, parsing YAML structure, checking port exposure, and verifying required variables exist. | exp: func:sanitize_template_vars(template: str) → str, call:re.sub, func:validate_compose_yaml(template: str) → dict, call:sanitize_template_vars, call:yaml.safe_load, call:isinstance, raise:ValueError, func:check_port_exposed(parsed: dict, port: int) → bool, call:str, call:isinstance, call:parsed["services"].values, call:port_mapping.split, call:mapping.split, func:validate_required_variables(template: str, variables: list[str]) → None, raise:HTTPException | dep: re, yaml, fastapi ## arch -Modular FastAPI router composition pattern with separated concerns across CRUD operations, validation, lifecycle management, and proxying, aggregated through `__init__.py` for unified module interface. +Modular FastAPI router organization with clear separation of concerns across CRUD operations, Docker lifecycle management, YAML/Compose validation, and container proxying/tunneling. ## tags get, call:, tool, raise:httpexception, user, instance, call:str, call:session.get ## symbols diff --git a/apps/api/src/api/user/.pi-map.index.md b/apps/api/src/api/user/.pi-map.index.md index c78ee20..325041d 100644 --- a/apps/api/src/api/user/.pi-map.index.md +++ b/apps/api/src/api/user/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/user ## role -Provides user-facing API endpoints for authentication, profile management, and SSH key operations in a FastAPI backend application. +Provides authentication, user profile management, and SSH key operations for the API backend. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/user/.pi-map.md b/apps/api/src/api/user/.pi-map.md index 71ce8dc..6bceb12 100644 --- a/apps/api/src/api/user/.pi-map.md +++ b/apps/api/src/api/user/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/api/user index: apps/api/src/api/user/.pi-map.index.md ## role -Provides user-facing API endpoints for authentication, profile management, and SSH key operations in a FastAPI backend application. +Provides authentication, user profile management, and SSH key operations for the API backend. ## files - __init__.py | Aggregates and exports user-related API routers from submodules for easy importing | dep: src.api.user.auth, src.api.user.ssh_keys, src.api.user.users - auth.py | Implements OAuth2/OIDC authentication endpoints for a FastAPI application using Authentik as the identity provider, including login initiation, callback handling, logout, and current user retrieval. | exp: func:get_db_session() → AsyncGenerator[AsyncSession, None], call:SessionLocal, func:login(next) → RedirectResponse, call:Settings, call:token_urlsafe, call:build_login_redirect_url, call:logger.debug, call:RedirectResponse, call:response.set_cookie, func:callback(code: str, state: str, auth_state, auth_next, session) → RedirectResponse, call:logger.debug, call:logger.warning, call:Settings, call:httpx.AsyncClient, call:exchange_code_for_tokens, call:logger.info, call:logger.error, call:fetch_user_info, call:str, call:user_info.get, call:session.scalar, call:select(User).where, call:User, call:session.add, call:session.commit, call:session.refresh, call:create_session_cookie, call:build_cookie_options, call:cast, call:bool, call:cookie_options.get, call:RedirectResponse, call:redirect_response.set_cookie, call:redirect_response.delete_cookie, raise:HTTPException, func:logout(response: Response) → dict[str, str], call:Settings, call:build_cookie_options, call:cast, call:bool, call:str, call:cookie_options.get, call:response.delete_cookie, func:me(session_cookie, session) → dict[str, Any], call:logger.debug, call:bool, call:logger.warning, call:Settings, call:decode_session_cookie, call:session.get, call:logger.info, call:str, raise:HTTPException | dep: logging, secrets, typing, httpx, fastapi, fastapi.responses, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.cookies, src.auth.oidc, src.auth.session, src.config, src.database, src.models.user - ssh_keys.py | Implements a FastAPI router for managing Ed25519 SSH key pairs, including generation, storage with encrypted private keys, listing, deletion, and cryptographic signing/verification operations. | exp: func:_get_fernet() → Fernet, call:Settings, call:hashlib.sha256(settings.session_secret.encode()).digest, call:settings.session_secret.encode, call:base64.urlsafe_b64encode, call:Fernet, func:generate_ssh_key_pair() → tuple[str, str], call:Ed25519PrivateKey.generate, call:private_key.public_key, call:private_key.private_bytes, call:serialization.NoEncryption, call:public_key.public_bytes, call:private_bytes.decode, call:public_bytes.decode, func:create_ssh_key(data: SSHKeyCreate, user_id, session) → SSHKey, call:_get_user, call:generate_ssh_key_pair, call:_get_fernet, call:fernet.encrypt(private_key.encode()).decode, call:private_key.encode, call:SSHKey, call:session.add, call:session.commit, call:session.refresh, func:list_ssh_keys(user_id, session) → list[SSHKey], call:_get_user, call:session.execute, call:select(SSHKey).where, call:list, call:result.scalars().all, func:delete_ssh_key(key_id: uuid.UUID, user_id, session) → None, call:_get_user, call:session.get, call:session.delete, call:session.commit, raise:HTTPException, func:sign_payload(key_id: uuid.UUID, data: SignPayloadRequest, user_id, session) → SignatureResponse, call:_get_user, call:session.get, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:serialization.load_ssh_private_key, call:private_key_pem.encode, call:private_key.sign, call:data.payload.encode, call:SignatureResponse, call:base64.b64encode(signature).decode, raise:HTTPException, func:verify_signature(key_id: uuid.UUID, data: VerifySignatureRequest, user_id, session) → VerifySignatureResponse, call:_get_user, call:session.get, call:serialization.load_ssh_public_key, call:ssh_key.public_key.encode, call:base64.b64decode, call:public_key.verify, call:data.payload.encode, call:VerifySignatureResponse, raise:HTTPException | dep: base64, uuid, cryptography.fernet, cryptography.hazmat.primitives, cryptography.hazmat.primitives.asymmetric.ed25519, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.config, src.models, src.schemas.project, hashlib, cryptography - users.py | Implements FastAPI endpoints for authenticated user profile management including retrieval, updates, and avatar uploads. | exp: func:get_profile(user_id, session) → User, call:_get_user, func:update_profile(data: UserProfileUpdate, user_id, session) → User, call:_get_user, call:len, call:data.name.strip, call:data.email.strip, call:session.commit, call:session.refresh, raise:HTTPException, func:upload_avatar(file: UploadFile, user_id, session) → User, call:_get_user, call:file.read, call:len, call:Path, call:old_path.exists, call:old_path.unlink, call:filename_part.split(".")[-1].lower, call:uuid.uuid4, call:file_path.write_bytes, call:session.commit, call:session.refresh, raise:HTTPException | dep: uuid, pathlib, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.schemas.user ## arch -Modular FastAPI router pattern with separate submodule files per domain concern (auth, SSH keys, users), aggregated via __init__.py, using OAuth2/OIDC external identity provider (Authentik) and encrypted key storage for cryptographic operations. +Modular FastAPI router pattern with OAuth2/OIDC external identity provider integration, encrypted key storage, and file-based avatar handling. ## tags user, get, call:, key, ssh, src, cookie, raise:httpexception ## symbols diff --git a/apps/api/src/api/workspace/.pi-map.index.md b/apps/api/src/api/workspace/.pi-map.index.md index 63edc7c..dd88480 100644 --- a/apps/api/src/api/workspace/.pi-map.index.md +++ b/apps/api/src/api/workspace/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/api/workspace ## role -Provides FastAPI REST endpoints for workspace management, file operations, and git integration in user-scoped development environments. +Provides FastAPI REST API endpoints for workspace management, including CRUD operations, file access, git version control, and tool instance management within user-scoped workspaces. ## parent index: apps/api/src/api/.pi-map.index.md map: apps/api/src/api/.pi-map.md diff --git a/apps/api/src/api/workspace/.pi-map.md b/apps/api/src/api/workspace/.pi-map.md index eb2c38a..ae8b18e 100644 --- a/apps/api/src/api/workspace/.pi-map.md +++ b/apps/api/src/api/workspace/.pi-map.md @@ -4,15 +4,15 @@ dir: apps/api/src/api/workspace index: apps/api/src/api/workspace/.pi-map.index.md ## role -Provides FastAPI REST endpoints for workspace management, file operations, and git integration in user-scoped development environments. +Provides FastAPI REST API endpoints for workspace management, including CRUD operations, file access, git version control, and tool instance management within user-scoped workspaces. ## files - __init__.py | Aggregates and re-exports workspace API router modules for centralized access | dep: src.api.workspace.workspace_files, src.api.workspace.workspace_git, src.api.workspace.workspace_instances, src.api.workspace.workspaces - workspace_files.py | Provides FastAPI endpoints for listing, reading, and writing files within user workspaces with optional git commit integration. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:list_files(workspace_id: uuid.UUID, path, user_id, session) → dict, call:_get_workspace, call:FileService, call:service.list_directory, raise:HTTPException, func:get_file_content(workspace_id: uuid.UUID, path: str, user_id, session) → dict, call:_get_workspace, call:FileService, call:service.read_file, raise:HTTPException, func:write_file(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:FileService, call:data.get("path", "").strip, call:data.get("message", "").strip, call:service.write_file, call:GitOperations, call:git.commit, raise:HTTPException | dep: uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.shared.file_service, sqlalchemy, src.services.git.git_operations - workspace_git.py | Provides FastAPI REST endpoints for git operations (status, branches, commit, push, pull, fetch, checkout, history) scoped to user workspaces. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:git_status(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.status, raise:HTTPException, func:git_branches(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.branches, raise:HTTPException, func:git_commit(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:data.get("message", "").strip, call:GitOperations, call:git.commit, raise:HTTPException, func:git_push(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.push, raise:HTTPException, func:git_pull(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.pull, raise:HTTPException, func:git_fetch(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.fetch, raise:HTTPException, func:git_checkout(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:data.get("branch", "").strip, call:GitOperations, call:git.checkout, call:session.commit, raise:HTTPException, func:git_history(workspace_id: uuid.UUID, path, limit, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.history, raise:HTTPException | dep: uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.git.git_operations, sqlalchemy -- workspace_instances.py | Defines API endpoints for listing tool instances associated with a specific workspace, verifying workspace ownership. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:list_workspace_instances(workspace_id: uuid.UUID, user_id, session) → list[dict], call:_get_workspace, call:session.execute, call:select(ToolInstance) .where(ToolInstance.workspace_id == workspace_id) .order_by, call:ToolInstance.created_at.desc, call:result.scalars().all, call:str, call:i.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models +- workspace_instances.py | FastAPI router providing endpoints to create and list tool instances associated with a specific workspace. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:create_workspace_instance(workspace_id: uuid.UUID, data: CreateWorkspaceInstanceRequest, user_id, session) → dict, call:_get_workspace, call:session.get, call:CreateInstanceRequest, call:str, call:create_tool_instance, call:instance.created_at.isoformat, raise:HTTPException, func:list_workspace_instances(workspace_id: uuid.UUID, user_id, session) → list[dict], call:_get_workspace, call:session.execute, call:select(ToolInstance) .where(ToolInstance.workspace_id == workspace_id) .order_by, call:ToolInstance.created_at.desc, call:result.scalars().all, call:str, call:i.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.schemas.tool, src.services.tool.instance_service - workspaces.py | Provides FastAPI CRUD endpoints for managing Git repository workspaces with nested and top-level URL structures, including listing, creating, updating, deleting, and syncing workspaces with instance count tracking. | exp: func:list_all_workspaces(user_id, session) → list[dict], call:select(func.count(ToolInstance.id)) .where(ToolInstance.workspace_id == Workspace.id) .correlate(Workspace) .scalar_subquery, call:func.count, call:session.execute, call:select( Workspace, GitRepository.name.label("repo_name"), GitRepository.project_id, GitRepository.ssh_key_id.label("repo_ssh_key_id"), instance_count.label("instance_count"), ) .join(GitRepository, Workspace.repo_id == GitRepository.id) .where(Workspace.user_id == user_id) .order_by, call:GitRepository.name.label, call:GitRepository.ssh_key_id.label, call:instance_count.label, call:Workspace.created_at.desc, call:result.all, call:str, call:ws.last_sync_at.isoformat, call:ws.created_at.isoformat, call:ws.updated_at.isoformat, func:delete_workspace_top_level(workspace_id: uuid.UUID, force, user_id, session) → dict, call:session.get, call:WorkspaceManager, call:manager.delete, call:session.commit, call:session.rollback, call:logger.error, raise:HTTPException, func:create_workspace_top_level(data: dict, user_id, session) → dict, call:data.get("repo_id", "").strip, call:uuid.UUID, call:session.get, call:data.get("name", "").strip, call:data.get("branch", "main").strip, call:WorkspaceManager, call:manager.create, call:session.add, call:session.commit, call:session.rollback, call:logger.error, call:session.refresh, call:str, call:workspace.created_at.isoformat, raise:HTTPException, func:list_workspaces(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → list[dict], call:_get_repo, call:select(func.count(ToolInstance.id)) .where(ToolInstance.workspace_id == Workspace.id) .correlate(Workspace) .scalar_subquery, call:func.count, call:session.execute, call:select( Workspace, instance_count.label("instance_count"), ) .where(Workspace.repo_id == repo_id) .order_by, call:instance_count.label, call:Workspace.created_at.desc, call:result.all, call:str, call:ws.last_sync_at.isoformat, call:ws.created_at.isoformat, call:ws.updated_at.isoformat, func:create_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_repo, call:data.get("name", "").strip, call:data.get("branch", "main").strip, call:WorkspaceManager, call:manager.create, call:session.add, call:session.commit, call:session.rollback, call:logger.error, call:session.refresh, call:str, call:workspace.created_at.isoformat, raise:HTTPException, func:get_workspace_detail(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:session.execute, call:select(func.count(ToolInstance.id)).where, call:func.count, call:result.scalar, call:str, call:workspace.last_sync_at.isoformat, call:workspace.created_at.isoformat, call:workspace.updated_at.isoformat, func:update_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:data.get("name", "").strip, call:data.get("branch", "").strip, call:session.commit, call:session.rollback, call:logger.error, call:str, raise:HTTPException, func:delete_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, force, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:WorkspaceManager, call:manager.delete, call:session.commit, call:session.rollback, call:logger.error, raise:HTTPException, func:sync_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:WorkspaceManager, call:manager.sync, call:session.commit, call:workspace.last_sync_at.isoformat, raise:HTTPException, func:_get_repo(session: AsyncSession, repo_id: uuid.UUID, project_id: uuid.UUID, user_id: uuid.UUID) → GitRepository, call:session.execute, call:select(GitRepository) .where( GitRepository.id == repo_id, GitRepository.project_id == project_id, ) .options, call:selectinload, call:result.scalar_one_or_none, raise:HTTPException, func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, repo_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.auth.dependencies, src.models, src.services.shared.workspace_manager ## arch -Modular router composition with domain-separated endpoint modules (files, git, instances, workspaces) using FastAPI dependency injection for workspace ownership verification and nested resource URL patterns. +Modular router-based architecture using FastAPI with domain-driven decomposition into separate modules (files, git, instances, workspaces), nested URL routing for hierarchical resources, and optional git integration for file operations. ## tags workspace, get, raise:httpexception, call:, at.isoformat, git, call:select, call:data.get ## symbols diff --git a/apps/api/src/auth/.pi-map.index.md b/apps/api/src/auth/.pi-map.index.md index b0a7874..72029cc 100644 --- a/apps/api/src/auth/.pi-map.index.md +++ b/apps/api/src/auth/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/auth ## role -Provides authentication and authorization infrastructure for the API, including OIDC/OAuth2 integration, session management, and FastAPI dependency injection. +Provides authentication and authorization infrastructure for the API using OIDC/OAuth2 with Authentik, session cookies, and FastAPI dependencies. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/auth/.pi-map.md b/apps/api/src/auth/.pi-map.md index cfd440d..6426813 100644 --- a/apps/api/src/auth/.pi-map.md +++ b/apps/api/src/auth/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/auth index: apps/api/src/auth/.pi-map.index.md ## role -Provides authentication and authorization infrastructure for the API, including OIDC/OAuth2 integration, session management, and FastAPI dependency injection. +Provides authentication and authorization infrastructure for the API using OIDC/OAuth2 with Authentik, session cookies, and FastAPI dependencies. ## files - __init__.py | Re-exports authentication utility functions from submodules to provide a unified public API for the auth package | dep: src.auth.cookies, src.auth.oidc, src.auth.session - cookies.py | Builds a dictionary of HTTP cookie options from application settings for secure cookie configuration. | exp: func:build_cookie_options(settings: Settings) → dict[str, str | bool | None] | dep: src.config, src.config.Settings @@ -12,7 +12,7 @@ Provides authentication and authorization infrastructure for the API, including - oidc.py | Implements OIDC/OAuth2 authentication flow with Authentik, including login URL construction, authorization code exchange for tokens, and user info retrieval. | exp: func:build_login_redirect_url(settings: Settings, redirect_uri: str, state: str) → str, call:urlencode, func:exchange_code_for_tokens(settings: Settings, code: str, redirect_uri: str, client: httpx.AsyncClient) → dict[str, str], call:client.post, call:response.raise_for_status, call:response.json, call:payload.get, func:fetch_user_info(settings: Settings, access_token: str, client: httpx.AsyncClient) → dict[str, Any], call:client.get, call:response.raise_for_status, call:response.json | dep: typing, urllib.parse, httpx, src.config - session.py | Implements creation and verification of signed session cookies using HMAC-SHA256 in a JWS-like format. | exp: func:_base64url_encode(data: bytes) → str, call:base64.urlsafe_b64encode(data).rstrip(b"=").decode, func:_base64url_decode(data: str) → bytes, call:len, call:base64.urlsafe_b64decode, func:create_session_cookie(settings: Settings, user_id: str) → str, call:int, call:(datetime.now(timezone.utc) + timedelta(hours=settings.session_ttl_hours)).timestamp, call:datetime.now, call:timedelta, call:_base64url_encode, call:json.dumps({"alg": "HS256", "typ": "session"}).encode, call:json.dumps(payload).encode, call:hmac.new( settings.session_secret.encode(), message.encode(), hashlib.sha256, ).digest, call:settings.session_secret.encode, call:message.encode, func:decode_session_cookie(settings: Settings, cookie_value: str) → dict[str, Any], call:cookie_value.split, call:len, call:hmac.new( settings.session_secret.encode(), message.encode(), hashlib.sha256, ).digest, call:settings.session_secret.encode, call:message.encode, call:_base64url_encode, call:hmac.compare_digest, call:_base64url_decode, call:json.loads, call:payload.get, call:int, call:datetime.now(timezone.utc).timestamp, raise:ValueError | dep: hmac, hashlib, json, base64, datetime, typing, src.config, src.config.Settings ## arch -Modular utility package with separation of concerns across cookies, sessions, OIDC flows, and FastAPI dependencies; uses HMAC-SHA256 JWS-like tokens and external Authentik identity provider. +Modular security layer with separation of concerns: protocol handling (OIDC), transport security (cookies/sessions), framework integration (dependencies), and clean public API (re-exports). ## tags session, src, cookie, user, get, base64url, raise:httpexception, call: ## symbols diff --git a/apps/api/src/models/.pi-map.index.md b/apps/api/src/models/.pi-map.index.md index eaa8c78..405e810 100644 --- a/apps/api/src/models/.pi-map.index.md +++ b/apps/api/src/models/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models ## role -Provides the core database model layer with a centralized public API, defining SQLAlchemy base classes and reusable mixins for consistent schema patterns across the API application. +Centralized database model definitions and shared infrastructure for the API's data layer. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/models/.pi-map.md b/apps/api/src/models/.pi-map.md index 321dc6a..91e73b5 100644 --- a/apps/api/src/models/.pi-map.md +++ b/apps/api/src/models/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/models index: apps/api/src/models/.pi-map.index.md ## role -Provides the core database model layer with a centralized public API, defining SQLAlchemy base classes and reusable mixins for consistent schema patterns across the API application. +Centralized database model definitions and shared infrastructure for the API's data layer. ## files - __init__.py | Re-exports model classes from submodules to provide a centralized public API for the src.models package | dep: src.models.base, src.models.config.config_profile, src.models.project.git_repository, src.models.project.project, src.models.project.workspace, src.models.system.health_check, src.models.system.instance_event, src.models.system.notification, src.models.system.terminal_session, src.models.tool.tool_definition_manifest, src.models.tool.tool_instance, src.models.tool.tool_type, src.models.user.ssh_key, src.models.user.user, src.models.user.user_config - base.py | Defines SQLAlchemy base model and reusable mixins for UUID primary keys and automatic timestamp tracking in database models. | exp: class:Base, class:UUIDPrimaryKeyMixin, class:TimestampMixin | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm ## arch -Uses the declarative base pattern with mixin composition for cross-cutting concerns (UUIDs, timestamps), and a facade/aggregate module pattern via __init__.py re-exports to simplify imports for consumers. +SQLAlchemy ORM with declarative base, mixin-based composition for cross-cutting concerns (UUIDs, timestamps), and explicit package-level re-exports for clean public API surface. ## tags models, src, base, project, system, user, mixin, tool ## symbols diff --git a/apps/api/src/models/config/.pi-map.index.md b/apps/api/src/models/config/.pi-map.index.md index 0f54717..b5ed8a5 100644 --- a/apps/api/src/models/config/.pi-map.index.md +++ b/apps/api/src/models/config/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models/config ## role -Provides SQLAlchemy ORM models for managing configuration profiles and their hierarchical includes in the API application. +Provides SQLAlchemy ORM models for configuration profiles that manage environment variables, mounts, files, and git mounts with support for profile inheritance and user/project/tool associations. ## parent index: apps/api/src/models/.pi-map.index.md map: apps/api/src/models/.pi-map.md diff --git a/apps/api/src/models/config/.pi-map.md b/apps/api/src/models/config/.pi-map.md index 71ed878..218cb07 100644 --- a/apps/api/src/models/config/.pi-map.md +++ b/apps/api/src/models/config/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/models/config index: apps/api/src/models/config/.pi-map.index.md ## role -Provides SQLAlchemy ORM models for managing configuration profiles and their hierarchical includes in the API application. +Provides SQLAlchemy ORM models for configuration profiles that manage environment variables, mounts, files, and git mounts with support for profile inheritance and user/project/tool associations. ## files - __init__.py | Exports config model classes from a subpackage for simplified importing | dep: src.models.config.config_profile - config_profile.py | Defines SQLAlchemy ORM models for configuration profiles and their includes, storing environment variables, runtime hints, mounts, files, and git mounts with user/project/tool associations and self-referential inclusion relationships. | exp: class:ConfigProfile, class:ConfigProfileInclude | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.user, src.models (ToolType) ## arch -Uses SQLAlchemy declarative ORM pattern with self-referential many-to-many relationships for profile inclusion, and associations to users, projects, and tools. +Uses SQLAlchemy ORM with declarative base pattern, implementing self-referential many-to-many relationships for profile inclusion, association tables for user/project/tool ownership, and polymorphic-like configuration through profile inheritance rather than class inheritance. ## tags config, src, models, profile, sqlalchemy, init, orm, mounts ## symbols diff --git a/apps/api/src/models/project/.pi-map.index.md b/apps/api/src/models/project/.pi-map.index.md index 1bb8e2a..36c606a 100644 --- a/apps/api/src/models/project/.pi-map.index.md +++ b/apps/api/src/models/project/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models/project ## role -Defines the core data models for project-related entities (GitRepository, Project, Workspace) using SQLAlchemy ORM. +Defines the core domain data models for project management, representing Git repositories, projects, and workspaces as SQLAlchemy ORM entities with their relationships. ## parent index: apps/api/src/models/.pi-map.index.md map: apps/api/src/models/.pi-map.md diff --git a/apps/api/src/models/project/.pi-map.md b/apps/api/src/models/project/.pi-map.md index dc69df7..c3dd4d3 100644 --- a/apps/api/src/models/project/.pi-map.md +++ b/apps/api/src/models/project/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/models/project index: apps/api/src/models/project/.pi-map.index.md ## role -Defines the core data models for project-related entities (GitRepository, Project, Workspace) using SQLAlchemy ORM. +Defines the core domain data models for project management, representing Git repositories, projects, and workspaces as SQLAlchemy ORM entities with their relationships. ## files - __init__.py | Exports the three main project model classes (GitRepository, Project, Workspace) as the public API for the models.project package. | dep: src.models.project.git_repository, src.models.project.project, src.models.project.workspace - git_repository.py | Defines a SQLAlchemy ORM model for Git repositories with relationships to projects, users, and SSH keys. | exp: class:GitRepository | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.user, src.models.ssh_key - project.py | Defines a SQLAlchemy ORM model for a Project entity with relationships to users, Git repositories, and SSH keys. | exp: class:Project | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.user, src.models.GitRepository, src.models.SSHKey, src.models.user.User - workspace.py | Defines a SQLAlchemy ORM model for persistent writable Git repository clones associated with users. | exp: class:Workspace | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.user, src.models.GitRepository, src.models.user.User ## arch -Standard SQLAlchemy ORM pattern with declarative models, package-level public API abstraction via __init__.py, and bidirectional relationships between entities. +Standard SQLAlchemy ORM model layer with declarative base pattern, using __init__.py as a public API facade to expose the three main entity classes while keeping implementation details in separate modules. ## tags models, src, project, sqlalchemy, git, user, workspace, orm ## symbols diff --git a/apps/api/src/models/system/.pi-map.index.md b/apps/api/src/models/system/.pi-map.index.md index 02160f0..d1619a2 100644 --- a/apps/api/src/models/system/.pi-map.index.md +++ b/apps/api/src/models/system/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models/system ## role -Provides SQLAlchemy ORM models for system-level operational and audit data including health checks, instance events, notifications, and terminal sessions. +Provides database persistence models for system-level operational concerns including health monitoring, audit logging, user notifications, and terminal session management. ## parent index: apps/api/src/models/.pi-map.index.md map: apps/api/src/models/.pi-map.md diff --git a/apps/api/src/models/system/.pi-map.md b/apps/api/src/models/system/.pi-map.md index dd4d427..de86374 100644 --- a/apps/api/src/models/system/.pi-map.md +++ b/apps/api/src/models/system/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/models/system index: apps/api/src/models/system/.pi-map.index.md ## role -Provides SQLAlchemy ORM models for system-level operational and audit data including health checks, instance events, notifications, and terminal sessions. +Provides database persistence models for system-level operational concerns including health monitoring, audit logging, user notifications, and terminal session management. ## files - __init__.py | Exports system-related model classes from a package for convenient importing. | dep: src.models.system.health_check, src.models.system.instance_event, src.models.system.notification, src.models.system.terminal_session - health_check.py | Defines a SQLAlchemy ORM model for storing health check snapshots of tool instances with various status and probe fields. | exp: class:HealthCheck | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm, src.models.base @@ -12,7 +12,7 @@ Provides SQLAlchemy ORM models for system-level operational and audit data inclu - notification.py | Defines a SQLAlchemy ORM model for storing user notifications with metadata, read/dismissed tracking, and polymorphic source references. | exp: class:Notification | dep: datetime, typing, uuid, sqlalchemy, sqlalchemy.orm, sqlalchemy.sql, src.models.base - terminal_session.py | Defines a SQLAlchemy database model for storing terminal session metadata with lifecycle tracking. | exp: class:TerminalSessionModel | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm, src.models.base ## arch -Standard SQLAlchemy declarative ORM pattern with timestamped base models, polymorphic relationships (notification sources), lifecycle state tracking, and audit fields (user attribution, status enums). +Uses SQLAlchemy ORM declarative models with consistent patterns including timestamp tracking, JSON metadata columns, enum-based status fields, and polymorphic relationships for extensible source attribution. ## tags sqlalchemy, src, models, model, orm, system, notification, health ## symbols diff --git a/apps/api/src/models/tool/.pi-map.index.md b/apps/api/src/models/tool/.pi-map.index.md index 30c76e0..59ac10f 100644 --- a/apps/api/src/models/tool/.pi-map.index.md +++ b/apps/api/src/models/tool/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models/tool ## role -Defines SQLAlchemy ORM models for managing tool definitions, instances, and types in a container-based deployment system. +Database models for containerized tool lifecycle management, covering tool definitions, deployment instances, and categorization types. ## parent index: apps/api/src/models/.pi-map.index.md map: apps/api/src/models/.pi-map.md diff --git a/apps/api/src/models/tool/.pi-map.md b/apps/api/src/models/tool/.pi-map.md index 9a4e3b4..0244275 100644 --- a/apps/api/src/models/tool/.pi-map.md +++ b/apps/api/src/models/tool/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/models/tool index: apps/api/src/models/tool/.pi-map.index.md ## role -Defines SQLAlchemy ORM models for managing tool definitions, instances, and types in a container-based deployment system. +Database models for containerized tool lifecycle management, covering tool definitions, deployment instances, and categorization types. ## files - __init__.py | Exports the public API for the tool models module by re-exporting three key classes. | dep: src.models.tool.tool_definition_manifest, src.models.tool.tool_instance, src.models.tool.tool_type - tool_definition_manifest.py | Defines a SQLAlchemy ORM model for storing tool definition manifests that compile to Dockerfiles and Compose files, supporting both base definitions and tool-specific definitions with inheritance. | exp: class:ToolDefinitionManifest | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.user -- tool_instance.py | Defines a SQLAlchemy ORM model for tool instances that represent deployed tools with container/runtime metadata and relationships to users, projects, repositories, and workspaces. | exp: class:ToolInstance | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.project, src.models.user, src.models (ConfigProfile, GitRepository, Project, ToolType, User, Workspace) +- tool_instance.py | Defines a SQLAlchemy ORM model for tool instances that represent deployed tools with container metadata, status tracking, and relationships to users, projects, workspaces, and other entities. | exp: class:ToolInstance | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.project, src.models.user, src.models (ConfigProfile, GitRepository, Project, ToolType, User, Workspace) - tool_type.py | Defines a SQLAlchemy ORM model for tool types that represent configurable categories of tools with deployment templates, manifest references, and metadata. | exp: class:ToolType | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.tool.tool_definition_manifest, src.models.user ## arch -Domain-driven SQLAlchemy ORM models with inheritance patterns (base/tool-specific manifests), rich relationships (users, projects, repositories, workspaces), and template-based deployment abstractions. +SQLAlchemy ORM with declarative models using inheritance hierarchies, relationship mappings, and polymorphic manifest compilation for Docker/Compose deployment. ## tags tool, models, src, sqlalchemy, orm, definition, manifest, base ## symbols diff --git a/apps/api/src/models/user/.pi-map.index.md b/apps/api/src/models/user/.pi-map.index.md index 5897971..04c39c8 100644 --- a/apps/api/src/models/user/.pi-map.index.md +++ b/apps/api/src/models/user/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/models/user ## role -Provides the core data models for user identity, authentication credentials, and personal configuration in the API's database layer. +Provides SQLAlchemy ORM data models for user authentication, SSH key storage, and per-user configuration management. ## parent index: apps/api/src/models/.pi-map.index.md map: apps/api/src/models/.pi-map.md diff --git a/apps/api/src/models/user/.pi-map.md b/apps/api/src/models/user/.pi-map.md index 5230384..0c0192e 100644 --- a/apps/api/src/models/user/.pi-map.md +++ b/apps/api/src/models/user/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/models/user index: apps/api/src/models/user/.pi-map.index.md ## role -Provides the core data models for user identity, authentication credentials, and personal configuration in the API's database layer. +Provides SQLAlchemy ORM data models for user authentication, SSH key storage, and per-user configuration management. ## files - __init__.py | Exports the user-related model classes (SSHKey, User, UserConfig) from a package for convenient importing. | dep: src.models.user.ssh_key, src.models.user.user, src.models.user.user_config - ssh_key.py | Defines an SSHKey SQLAlchemy ORM model for storing encrypted SSH key pairs with user and optional project associations. | exp: class:SSHKey | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models.user - user.py | Defines a SQLAlchemy ORM model for a User entity with authentication fields and relationships to projects, SSH keys, and user configuration. | exp: class:User | dep: typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.SSHKey, src.models.UserConfig - user_config.py | Defines a SQLAlchemy model for storing per-user JSON configuration with typed property accessors for default profile IDs. | exp: class:UserConfig | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.user ## arch -Follows SQLAlchemy ORM declarative model pattern with package-level aggregation via __init__.py, using explicit table relationships (foreign keys, one-to-many associations) and a JSON-backed configuration store with typed property accessors. +Classic SQLAlchemy ORM model package pattern with declarative models, explicit table relationships, and a package-level __init__.py facade for clean imports. ## tags user, src, models, sqlalchemy, sshkey, orm, model, ssh ## symbols diff --git a/apps/api/src/schemas/.pi-map.index.md b/apps/api/src/schemas/.pi-map.index.md index d23854a..651fe64 100644 --- a/apps/api/src/schemas/.pi-map.index.md +++ b/apps/api/src/schemas/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas ## role -Defines Pydantic schemas for data validation, serialization, and API request/response models in the FastAPI application. +Defines Pydantic schemas for data validation and serialization in the API layer. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/schemas/.pi-map.md b/apps/api/src/schemas/.pi-map.md index 6401026..218b19f 100644 --- a/apps/api/src/schemas/.pi-map.md +++ b/apps/api/src/schemas/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/api/src/schemas index: apps/api/src/schemas/.pi-map.index.md ## role -Defines Pydantic schemas for data validation, serialization, and API request/response models in the FastAPI application. +Defines Pydantic schemas for data validation and serialization in the API layer. ## files - __init__.py | Empty file with no functionality ## arch -Modular schema organization following FastAPI/Pydantic patterns, with empty __init__.py indicating package initialization for future schema modules. +Standard Python package structure using __init__.py to mark the directory as an importable package, likely intended for request/response models following FastAPI/Pydantic patterns. ## tags init, empty, functionality ## symbols diff --git a/apps/api/src/schemas/config/.pi-map.index.md b/apps/api/src/schemas/config/.pi-map.index.md index 22234ed..9ca4621 100644 --- a/apps/api/src/schemas/config/.pi-map.index.md +++ b/apps/api/src/schemas/config/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas/config ## role -Provides Pydantic validation schemas for configuration profile API endpoints, ensuring data integrity for mounts, git URLs, UUIDs, and file paths. +Defines Pydantic validation schemas for configuration profile API request/response models with strict input validation. ## parent index: apps/api/src/schemas/.pi-map.index.md map: apps/api/src/schemas/.pi-map.md diff --git a/apps/api/src/schemas/config/.pi-map.md b/apps/api/src/schemas/config/.pi-map.md index 8ac5849..e314813 100644 --- a/apps/api/src/schemas/config/.pi-map.md +++ b/apps/api/src/schemas/config/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/schemas/config index: apps/api/src/schemas/config/.pi-map.index.md ## role -Provides Pydantic validation schemas for configuration profile API endpoints, ensuring data integrity for mounts, git URLs, UUIDs, and file paths. +Defines Pydantic validation schemas for configuration profile API request/response models with strict input validation. ## files - __init__.py | Re-exports Pydantic schemas for configuration profile operations from a submodule to provide a clean public API. | dep: src.schemas.config.config_profile - config_profile.py | Defines Pydantic request/response schemas for config profile API operations with validation for mounts, git URLs, UUIDs, and file paths. | exp: class:GitMountMapping, class:GitMountItem, class:MountItem, class:ConfigProfileCreate, class:ConfigProfileUpdate, class:ConfigProfileIncludeUpdate, class:ConfigProfileResponse, class:DefaultProfilesUpdate, class:ValidateGitUrlRequest, class:ValidateGitUrlResponse, func:_validate_uuid(v: str | None) → str | None, call:uuid.UUID, raise:ValueError | dep: uuid, pydantic, src.api.shared_validators ## arch -Simple schema-as-code pattern using Pydantic models with field validators; clean public API via explicit re-exports in `__init__.py`. +Standard Python package pattern using `__init__.py` re-exports to expose a clean public API from internal modules, with Pydantic-based schema-per-resource organization. ## tags profile, config, git, mount, update, validate, response, item ## symbols diff --git a/apps/api/src/schemas/project/.pi-map.index.md b/apps/api/src/schemas/project/.pi-map.index.md index 3462393..0e235f8 100644 --- a/apps/api/src/schemas/project/.pi-map.index.md +++ b/apps/api/src/schemas/project/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas/project ## role -Provides Pydantic data validation schemas for project-related API endpoints including projects, Git repositories, and SSH keys. +Defines Pydantic data validation schemas for project-related API endpoints, serving as the contract layer between HTTP requests/responses and internal business logic. ## parent index: apps/api/src/schemas/.pi-map.index.md map: apps/api/src/schemas/.pi-map.md diff --git a/apps/api/src/schemas/project/.pi-map.md b/apps/api/src/schemas/project/.pi-map.md index 4f643b7..de36223 100644 --- a/apps/api/src/schemas/project/.pi-map.md +++ b/apps/api/src/schemas/project/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/schemas/project index: apps/api/src/schemas/project/.pi-map.index.md ## role -Provides Pydantic data validation schemas for project-related API endpoints including projects, Git repositories, and SSH keys. +Defines Pydantic data validation schemas for project-related API endpoints, serving as the contract layer between HTTP requests/responses and internal business logic. ## files - __init__.py | Re-exports Pydantic schema classes from submodules to provide a unified public API for the project schemas module | dep: src.schemas.project.git_repository, src.schemas.project.project, src.schemas.project.ssh_key - git_repository.py | Defines Pydantic request/response schemas for Git repository operations in an API. | exp: class:GitRepositoryCreate, class:URLParseRequest, class:URLParseResponse, class:GitRepositoryResponse, class:UpdateSSHKeyRequest, class:FileListResponse, class:FileContentResponse, class:BranchesResponse, class:FileUpdateRequest, class:FileUpdateResponse, class:StatusResponse, class:BranchCreateRequest, class:CheckoutRequest, class:CommitRequest, class:CommitResponse, class:FetchResponse, class:PullResponse, class:PushResponse, class:MergeRequest, class:MergeResponse | dep: uuid, datetime, pydantic - project.py | Defines Pydantic request/response schemas for project-related API operations. | exp: class:ProjectCreate, class:ProjectUpdate, class:ProjectResponse, class:SetDefaultSSHKeyRequest | dep: uuid, pydantic - ssh_key.py | Defines Pydantic schemas for SSH key creation, response, signing, and signature verification in an API. | exp: class:SSHKeyCreate, class:SSHKeyResponse, class:SignPayloadRequest, class:SignatureResponse, class:VerifySignatureRequest, class:VerifySignatureResponse | dep: uuid, datetime, pydantic ## arch -Modular schema-per-domain pattern with clean separation of concerns, using Pydantic models for request/response validation and an `__init__.py` facade for unified public API access. +Modular schema decomposition with submodule-per-domain pattern (project, git_repository, ssh_key) aggregated through __init__.py barrel exports, using Pydantic models for declarative validation and serialization. ## tags response, request, project, create, update, sshkey, pydantic, schemas ## symbols diff --git a/apps/api/src/schemas/system/.pi-map.index.md b/apps/api/src/schemas/system/.pi-map.index.md index d0dacb8..e17f4e7 100644 --- a/apps/api/src/schemas/system/.pi-map.index.md +++ b/apps/api/src/schemas/system/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas/system ## role -Provides Pydantic schemas for system health monitoring endpoints in the API. +Provides Pydantic schema definitions for system health monitoring API responses. ## parent index: apps/api/src/schemas/.pi-map.index.md map: apps/api/src/schemas/.pi-map.md diff --git a/apps/api/src/schemas/system/.pi-map.md b/apps/api/src/schemas/system/.pi-map.md index e0d568a..420d023 100644 --- a/apps/api/src/schemas/system/.pi-map.md +++ b/apps/api/src/schemas/system/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/schemas/system index: apps/api/src/schemas/system/.pi-map.index.md ## role -Provides Pydantic schemas for system health monitoring endpoints in the API. +Provides Pydantic schema definitions for system health monitoring API responses. ## files - __init__.py | Re-exports health check schema classes from a submodule to provide a unified interface for the system schemas module. | dep: src.schemas.system.health - health.py | Defines Pydantic data models for health check API responses including database, disk, and overall system health status. | exp: class:DatabaseHealth, class:DiskHealth, class:HealthChecks, class:HealthResponse, class:DatabaseHealthResponse | dep: pydantic ## arch -Simple submodule pattern with explicit re-exports in __init__.py, using Pydantic models for structured API response validation. +Simple modular schema layer with submodule organization and re-export pattern for clean API surface. ## tags health, database, response, system, disk, check, schemas, init ## symbols diff --git a/apps/api/src/schemas/tool/.pi-map.index.md b/apps/api/src/schemas/tool/.pi-map.index.md index 0b40ddb..7ab1288 100644 --- a/apps/api/src/schemas/tool/.pi-map.index.md +++ b/apps/api/src/schemas/tool/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas/tool ## role -Provides Pydantic data validation schemas for tool-related API operations including tool types and instances. +Defines Pydantic data validation schemas for tool instance and tool type API operations in the API layer. ## parent index: apps/api/src/schemas/.pi-map.index.md map: apps/api/src/schemas/.pi-map.md diff --git a/apps/api/src/schemas/tool/.pi-map.md b/apps/api/src/schemas/tool/.pi-map.md index 5ef63be..ccc8215 100644 --- a/apps/api/src/schemas/tool/.pi-map.md +++ b/apps/api/src/schemas/tool/.pi-map.md @@ -4,17 +4,18 @@ dir: apps/api/src/schemas/tool index: apps/api/src/schemas/tool/.pi-map.index.md ## role -Provides Pydantic data validation schemas for tool-related API operations including tool types and instances. +Defines Pydantic data validation schemas for tool instance and tool type API operations in the API layer. ## files -- __init__.py | Re-exports tool-related schema classes from submodules to provide a unified import interface for the tool schemas module. | dep: src.schemas.tool.tool_instance, src.schemas.tool.tool_type -- tool_instance.py | Defines Pydantic request/response schemas for tool instance lifecycle operations (create and start). | exp: class:CreateInstanceRequest, class:StartInstanceRequest | dep: pydantic -- tool_type.py | Defines Pydantic request/response schemas for creating, updating, and validating tool types with Docker compose/dockerfile/manifest definitions | exp: class:ToolTypeCreate, class:ToolTypeUpdate, class:ToolTypeResponse, class:ToolTypeValidateRequest | dep: uuid, datetime, pydantic, src.api.tool.tool_types_validation +- __init__.py | Package initialization file that exposes tool-related schema classes for import convenience. | dep: src.schemas.tool.tool_instance, src.schemas.tool.tool_type +- tool_instance.py | Defines Pydantic request/response schemas for tool instance lifecycle operations (create, create-on-workspace, start). | exp: class:CreateInstanceRequest, class:CreateWorkspaceInstanceRequest, class:StartInstanceRequest | dep: pydantic +- tool_type.py | Defines Pydantic request/response schemas for tool type CRUD operations with conditional validation logic based on definition type (compose/dockerfile/manifest). | exp: class:ToolTypeCreate, class:ToolTypeUpdate, class:ToolTypeResponse, class:ToolTypeValidateRequest | dep: uuid, datetime, pydantic, src.api.tool.tool_types_validation ## arch -Modular schema organization with submodule-per-entity pattern and unified re-export interface via `__init__.py`, following standard Python package structure for clean API imports. +Standard Pydantic schema package pattern with type-specific conditional validation using discriminated unions or field validators based on definition type. ## tags -tool, type, request, instance, schemas, create, pydantic, response +tool, type, request, instance, create, schemas, pydantic, response ## symbols - CreateInstanceRequest +- CreateWorkspaceInstanceRequest - StartInstanceRequest - ToolTypeCreate - ToolTypeUpdate diff --git a/apps/api/src/schemas/user/.pi-map.index.md b/apps/api/src/schemas/user/.pi-map.index.md index 7f4da33..51b208a 100644 --- a/apps/api/src/schemas/user/.pi-map.index.md +++ b/apps/api/src/schemas/user/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/schemas/user ## role -Provides centralized Pydantic data validation schemas for user-related API requests and responses. +Provides Pydantic data validation schemas for user-related API requests and responses. ## parent index: apps/api/src/schemas/.pi-map.index.md map: apps/api/src/schemas/.pi-map.md diff --git a/apps/api/src/schemas/user/.pi-map.md b/apps/api/src/schemas/user/.pi-map.md index e9d06e2..fff7adc 100644 --- a/apps/api/src/schemas/user/.pi-map.md +++ b/apps/api/src/schemas/user/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/src/schemas/user index: apps/api/src/schemas/user/.pi-map.index.md ## role -Provides centralized Pydantic data validation schemas for user-related API requests and responses. +Provides Pydantic data validation schemas for user-related API requests and responses. ## files - __init__.py | Re-exports user-related Pydantic schemas from submodules to provide a unified public API for the user schemas package. | dep: src.schemas.user.user, src.schemas.user.user_config - user.py | Defines Pydantic response and update schemas for user profile data | exp: class:UserProfileResponse, class:UserProfileUpdate | dep: uuid, pydantic - user_config.py | Defines Pydantic models for user configuration data transfer objects (response and update schemas). | exp: class:UserConfigResponse, class:UserConfigUpdate | dep: pydantic ## arch -Modular package pattern with submodule separation of concerns (user profile vs. user config) and unified public API via `__init__.py` re-exports. +Modular schema organization with submodule separation of concerns and unified package-level re-exports for clean imports. ## tags user, schemas, response, update, config, pydantic, profile, src ## symbols diff --git a/apps/api/src/scripts/.pi-map.index.md b/apps/api/src/scripts/.pi-map.index.md index 01cc6aa..a919a2f 100644 --- a/apps/api/src/scripts/.pi-map.index.md +++ b/apps/api/src/scripts/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/scripts ## role -Provides utility scripts for administrative and setup tasks for the API application. +Provides utility scripts for administrative and setup tasks for the API application, specifically database seeding. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/scripts/.pi-map.md b/apps/api/src/scripts/.pi-map.md index a8d7829..aa7d682 100644 --- a/apps/api/src/scripts/.pi-map.md +++ b/apps/api/src/scripts/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/scripts index: apps/api/src/scripts/.pi-map.index.md ## role -Provides utility scripts for administrative and setup tasks for the API application. +Provides utility scripts for administrative and setup tasks for the API application, specifically database seeding. ## files - __init__.py | Marks the directory as a Python package and provides a docstring describing it as utility scripts for the API package. - seed.py | Seeds a development user into the database using SQLAlchemy async operations, with idempotency check to avoid duplicates. | exp: func:build_seed_user() → Mapping[str, str | None], func:seed_database(session: AsyncSession) → User, call:build_seed_user, call:session.scalar, call:select(User).where, call:User, call:session.add, call:session.commit, call:session.refresh, func:run() → None, call:SessionLocal, call:seed_database, call:print, call:str, func:main() → None, call:asyncio.run, call:run | dep: collections.abc, sqlalchemy, sqlalchemy.ext.asyncio, src.database, src.models.user, asyncio ## arch -Simple procedural scripts using async SQLAlchemy for database operations, with idempotency guards for safe re-runs. +Simple procedural script architecture with async SQLAlchemy database operations and idempotent initialization patterns. ## tags seed, user, database, sqlalchemy, package, init, call:build, call:session.scalar ## symbols diff --git a/apps/api/src/seeds/.pi-map.index.md b/apps/api/src/seeds/.pi-map.index.md index d769bdc..927d734 100644 --- a/apps/api/src/seeds/.pi-map.index.md +++ b/apps/api/src/seeds/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/seeds ## role -Provides database seeding utilities for initializing built-in tool types in the API application. +Database seeding utilities for populating initial data, specifically built-in tool types. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/seeds/.pi-map.md b/apps/api/src/seeds/.pi-map.md index a21024a..55a4ad6 100644 --- a/apps/api/src/seeds/.pi-map.md +++ b/apps/api/src/seeds/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/api/src/seeds index: apps/api/src/seeds/.pi-map.index.md ## role -Provides database seeding utilities for initializing built-in tool types in the API application. +Database seeding utilities for populating initial data, specifically built-in tool types. ## files - __init__.py | Marks the directory as a Python package for database seeding utilities. - builtin_tool_types.py | Seeds built-in Docker Compose-based tool types (VS Code Server, Jupyter Notebook, OpenCode) into a database with idempotent create-or-update logic. | exp: func:_table_exists(session, table_name: str) → bool, call:session.execute, call:text, call:result.scalar, func:seed_builtin_tool_types(), call:SessionLocal, call:_table_exists, call:logger.warning, call:session.scalar, call:select(ToolType).where, call:ToolType, call:tool_data.get, call:session.add, call:logger.info, call:session.commit | dep: logging, sqlalchemy, src.database, src.models ## arch -Simple procedural seeding scripts with idempotent create-or-update logic using direct database operations, organized as a Python package with one seed module per entity type. +Simple procedural seeding scripts with idempotent create-or-update logic for Docker Compose-based tool definitions. ## tags tool, types, table, exists, builtin, call:tool, database, init ## symbols diff --git a/apps/api/src/services/.pi-map.index.md b/apps/api/src/services/.pi-map.index.md index 4dc40e6..0913da1 100644 --- a/apps/api/src/services/.pi-map.index.md +++ b/apps/api/src/services/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services ## role -Initializes the services directory as a Python package for business logic modules. +This directory is intended to contain service-layer business logic modules for the API application. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/services/.pi-map.md b/apps/api/src/services/.pi-map.md index b4a7c31..5091c10 100644 --- a/apps/api/src/services/.pi-map.md +++ b/apps/api/src/services/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/api/src/services index: apps/api/src/services/.pi-map.index.md ## role -Initializes the services directory as a Python package for business logic modules. +This directory is intended to contain service-layer business logic modules for the API application. ## files - __init__.py | Empty file with no functionality ## arch -Standard Python package structure using empty __init__.py for namespace declaration. +Empty package placeholder following standard Python package structure with no implemented architecture yet. ## tags init, empty, functionality ## symbols diff --git a/apps/api/src/services/config/.pi-map.index.md b/apps/api/src/services/config/.pi-map.index.md index 4964db9..36adb4e 100644 --- a/apps/api/src/services/config/.pi-map.index.md +++ b/apps/api/src/services/config/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/config ## role -Provides configuration profile resolution, validation, and CRUD operations for managing hierarchical, mergeable configuration with environment-aware overrides and Git integration. +Provides configuration profile resolution and management services for the API, handling hierarchical config merging, validation, and access control. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/config/.pi-map.md b/apps/api/src/services/config/.pi-map.md index d74ef5b..4d29721 100644 --- a/apps/api/src/services/config/.pi-map.md +++ b/apps/api/src/services/config/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/src/services/config index: apps/api/src/services/config/.pi-map.index.md ## role -Provides configuration profile resolution, validation, and CRUD operations for managing hierarchical, mergeable configuration with environment-aware overrides and Git integration. +Provides configuration profile resolution and management services for the API, handling hierarchical config merging, validation, and access control. ## files - __init__.py | Re-exports configuration profile resolution components from a subpackage to provide a unified public API. | dep: src.services.config.config_profile_resolver - config_profile_resolver.py | Resolves configuration profiles recursively with ordered include merging, cycle detection, and deterministic override rules for environment variables, runtime hints, files, mounts, and git mounts. | exp: class:ConfigProfileCycleError, class:ConfigProfileNotFoundError, class:ResolvedMount, class:ResolvedProfile, func:_detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → bool, func:_merge_env_vars(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_runtime_hints(base: dict[str, Any], overlay: dict[str, Any], overrides: dict[str, str], source_name: str) → dict[str, Any], call:dict, call:overlay.items, func:_merge_files(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_mounts(base: dict[str, ResolvedMount], overlay: list[dict[str, Any]], overrides: dict[str, str], source_name: str) → dict[str, ResolvedMount], call:dict, call:mount_data.get, call:files.items, call:ResolvedMount, func:_merge_git_mounts(base: list[dict[str, Any]], overlay: list[dict[str, Any]], source_name: str) → list[dict[str, Any]], call:list, call:enumerate, call:_normalize_git_mount_entry, call:dict, call:m.get, call:mount.get, call:existing.get, call:existing["mappings"].append, call:existing_sources.add, call:len, call:result.append, func:_normalize_git_mount_entry(entry: dict[str, Any]) → dict[str, Any], call:dict, call:entry.get, call:entry.pop, func:_resolve_profile_recursive(session: AsyncSession, profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → ResolvedProfile, call:_detect_cycle, call:" -> ".join, call:str, call:session.get, call:ResolvedProfile, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == profile_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_resolve_profile_recursive, call:result.included_profiles.append, call:_merge_env_vars, call:_merge_runtime_hints, call:_merge_files, call:_merge_mounts, call:included.mounts.values, call:_merge_git_mounts, raise:ConfigProfileCycleError, raise:ConfigProfileNotFoundError, func:resolve_profile(session: AsyncSession, profile_id: uuid.UUID) → ResolvedProfile, call:_resolve_profile_recursive, call:set, func:check_include_cycle(session: AsyncSession, profile_id: uuid.UUID, new_include_id) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, call:set, call:len, func:_check_from(current_id: uuid.UUID, target_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, func:apply_resolved_profile(instance_dir: str, resolved: ResolvedProfile, home_dir) → tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]], call:Path, call:dict, call:files.items, call:full_path.resolve().relative_to, call:instance_path.resolve, call:logger.warning, call:full_path.parent.mkdir, call:full_path.write_text, call:resolved.mounts.values, call:expand_container_path, call:expanded_target.lstrip("/").replace, call:mount_dir.mkdir, call:mount.files.items, call:mount_dir.resolve, call:os.path.join, call:volume_mounts.append, call:str, func:expand_container_path(path: str, home_dir: str) → str, call:path.startswith, call:os.path.join, func:resolved_profile_to_dict(resolved: ResolvedProfile) → dict[str, Any], call:str, call:resolved.mounts.values | dep: logging, os, uuid, dataclasses, typing, sqlalchemy, sqlalchemy.ext.asyncio, src.models, pathlib - crud_service.py | Provides CRUD operations for configuration profiles including validation, access control, size limits, and include cycle detection. | exp: func:calculate_profile_size(data: dict) → int, call:data.get("env_vars", {}).items, call:len, call:key.encode, call:str(value).encode, call:data.get("runtime_hints", {}).items, call:str(mount.get("target", "")).encode, call:str(mount.get("mode", "")).encode, call:mount.get("files", {}).items, call:path.encode, call:content.encode, call:data.get("files", {}).items, func:get_profile_with_includes(session: AsyncSession, profile_id: uuid.UUID) → ConfigProfile | None, call:session.execute, call:select(ConfigProfile) .where(ConfigProfile.id == profile_id) .options, call:selectinload, call:result.scalar_one_or_none, func:check_access(session: AsyncSession, user_id: uuid.UUID, project_id, tool_type_id) → None, call:session.get, raise:HTTPException, func:validate_git_mounts(session: AsyncSession, user_id: uuid.UUID, git_mounts: list[Any], project_id) → None, call:mount.get, call:remote_url.startswith, raise:HTTPException, func:profile_to_response(profile: ConfigProfile, includes) → dict, call:str, call:profile.created_at.isoformat, call:profile.updated_at.isoformat, func:get_or_create_user_config(session: AsyncSession, user_id: uuid.UUID) → UserConfig, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:UserConfig, call:session.add, func:validate_default_profiles(session: AsyncSession, user_id: uuid.UUID, default_profiles: dict[str, str]) → None, call:default_profiles.items, call:uuid.UUID, call:session.get, raise:HTTPException, func:create_profile(session: AsyncSession, user_id: uuid.UUID, data: Any) → ConfigProfile, call:session.execute, call:select(ConfigProfile) .where( ConfigProfile.user_id == user_id, ConfigProfile.name == data.name, ) .options, call:selectinload, call:existing.scalar_one_or_none, call:uuid.UUID, call:check_access, call:m.model_dump, call:hasattr, call:validate_git_mounts, call:calculate_profile_size, call:data.model_dump, call:ConfigProfile, call:session.add, call:session.commit, call:select(ConfigProfile) .where(ConfigProfile.id == profile.id) .options, call:result.scalar_one, raise:HTTPException, func:update_profile(session: AsyncSession, profile: ConfigProfile, data: Any) → ConfigProfile, call:data.model_dump, call:session.execute, call:select(ConfigProfile).where, call:existing.scalar_one_or_none, call:uuid.UUID, call:check_access, call:m.model_dump, call:hasattr, call:validate_git_mounts, call:profile_to_response, call:calculate_profile_size, call:update_data.items, call:isinstance, call:setattr, call:session.commit, call:select(ConfigProfile) .where(ConfigProfile.id == profile.id) .options, call:selectinload, call:result.scalar_one, raise:HTTPException, func:update_includes(session: AsyncSession, profile: ConfigProfile, included_ids: list[uuid.UUID], user_id: uuid.UUID) → ConfigProfile, call:session.get, call:check_include_cycle, call:" -> ".join, call:str, call:session.execute, call:select(ConfigProfileInclude).where, call:result.scalars().all, call:session.delete, call:session.flush, call:enumerate, call:ConfigProfileInclude, call:session.add, call:session.commit, call:select(ConfigProfile).where, call:result.scalar_one, raise:HTTPException | dep: uuid, typing, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.models, src.models.project, src.services.config.config_profile_resolver - resolver_service.py | Resolves default configuration profiles for users/projects/tools and validates Git URLs with SSH key support. | exp: func:resolve_default_profile(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, tool_type_id: uuid.UUID) → dict, call:select(ConfigProfile) .where(ConfigProfile.user_id == user_id) .where( (ConfigProfile.project_id.is_(None) & ConfigProfile.tool_type_id.is_(None)) | (ConfigProfile.project_id == project_id) | (ConfigProfile.tool_type_id == tool_type_id) | ( (ConfigProfile.project_id == project_id) & (ConfigProfile.tool_type_id == tool_type_id) ) ) .order_by, call:ConfigProfile.project_id.is_, call:ConfigProfile.tool_type_id.is_, call:session.execute, call:result.scalars().all, call:str, func:validate_git_url(session: AsyncSession, current_user_id: uuid.UUID, url: str, ssh_key_id: str | None) → ValidateGitUrlResponse, call:parse_git_url, call:url.strip, call:parse_result.get, call:ValidateGitUrlResponse, call:uuid.UUID, call:session.get, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:tempfile.mkstemp, call:os.write, call:private_key.encode, call:os.close, call:os.chmod, call:subprocess.run, call:os.path.exists, call:os.unlink, call:result.stderr.strip, call:stderr.lower, call:result.stdout.strip().split, call:line.strip, call:line.split, call:len, call:ref.startswith, call:branches.append | dep: logging, os, subprocess, uuid, typing, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.models, src.services.shared.ssh_keys, src.utils.git_url_parser, src.schemas.config, tempfile ## arch -Layered service architecture with separation between resolution logic (recursive merge with cycle detection), CRUD operations (validation, access control, limits), and default resolution (user/project/tool scoping, Git/SSH integration), exposing a unified public API through `__init__.py` facade pattern. +Service-layer pattern with separation of concerns: dedicated resolver (recursive merge with cycle detection), CRUD operations (validation/ACLs), and default resolution (user/project/tool scoping); supports multiple config sources with deterministic override precedence. ## tags profile, call:, call:select, git, merge, call:str, call:session.execute, mounts ## symbols diff --git a/apps/api/src/services/docker/.pi-map.index.md b/apps/api/src/services/docker/.pi-map.index.md index d30fbf7..4b6fdde 100644 --- a/apps/api/src/services/docker/.pi-map.index.md +++ b/apps/api/src/services/docker/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/docker ## role -Provides Docker-based infrastructure services for container orchestration, configuration management, runtime operations, and secure tunneling to expose internal services. +Provides Docker infrastructure services for container lifecycle management, compose orchestration, configuration deployment, and secure tunneling to expose internal services. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/docker/.pi-map.md b/apps/api/src/services/docker/.pi-map.md index 7a625bb..e9bf8f0 100644 --- a/apps/api/src/services/docker/.pi-map.md +++ b/apps/api/src/services/docker/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/services/docker index: apps/api/src/services/docker/.pi-map.index.md ## role -Provides Docker-based infrastructure services for container orchestration, configuration management, runtime operations, and secure tunneling to expose internal services. +Provides Docker infrastructure services for container lifecycle management, compose orchestration, configuration deployment, and secure tunneling to expose internal services. ## files - __init__.py | Package initialization file that exposes Docker-related service functions for container operations, compose management, configuration staging, and tunnel management. | dep: src.services.docker.compose, src.services.docker.config_staging, src.services.docker.container, src.services.docker.tunnel - compose.py | Generates, renders, and executes Docker Compose commands for container orchestration with volume sorting and template substitution. | exp: func:sort_volumes_by_specificity(volumes: list[str]) → list[str], call:vol.split, call:len, call:parts[1].rstrip, call:target.count, call:targets.append, call:Counter(targets).items, call:logger.warning, call:sorted, func:_target_depth(vol: str) → int, call:vol.split, call:len, call:parts[1].rstrip, call:target.count, func:render_compose_template(template: str, variables: dict[str, Any]) → str, call:variables.items, call:result.replace, call:str, func:write_compose_file(instance_dir: str, content: str) → str, call:Path, call:compose_path.write_text, call:str, func:execute_compose_command(compose_path: str, action: str, timeout, env_file) → tuple[int, str, str], call:Path, call:cmd.extend, call:cmd.append, call:subprocess.run, call:str, raise:ValueError | dep: logging, subprocess, collections, pathlib, typing, collections.Counter, pathlib.Path, typing.Any @@ -12,7 +12,7 @@ Provides Docker-based infrastructure services for container orchestration, confi - container.py | Provides Docker container runtime queries and network management utilities via subprocess calls to the Docker CLI. | exp: func:get_container_id(instance_name: str) → str | None, call:instance_name.lower, call:subprocess.run, call:result.stdout.strip, call:ps_result.stdout.strip().splitlines, call:line.split, call:len, call:name.lower, func:get_container_name(instance_name: str) → str | None, call:subprocess.run, call:instance_name.lower, call:result.stdout.strip().lstrip, func:get_backend_network_name() → str, call:subprocess.run, call:result.stdout.strip().split, call:net.lower, func:connect_container_to_network(container_name: str, network_name) → bool, call:get_backend_network_name, call:subprocess.run, func:get_container_ip_on_network(container_id: str, network_name) → str | None, call:get_backend_network_name, call:subprocess.run, call:result.stdout.strip, func:is_container_on_network(container_id: str, network_name) → bool, call:get_backend_network_name, call:subprocess.run, func:get_container_status(container_id: str) → dict[str, Any], call:subprocess.run, call:result.stdout.strip().split, call:int, call:len, call:parts[1].isdigit, func:wait_for_container_running(container_id: str, timeout, interval) → dict[str, Any], call:time.time, call:get_container_status, call:time.sleep, func:get_container_logs(container_id: str, tail) → str, call:subprocess.run, call:str, func:find_free_port(start, end) → int, call:range, call:socket.socket, call:s.connect_ex, raise:RuntimeError | dep: logging, subprocess, time, typing, socket - tunnel.py | Manages Cloudflare tunnels by orchestrating cloudflared Docker containers to expose internal services via temporary public URLs. | exp: func:_tunnel_container_name(instance_name: str) → str, call:instance_name.lower, func:_ensure_image() → None, call:subprocess.run, call:result.stdout.strip, call:logger.info, call:logger.warning, func:_cleanup_stale_tunnel(tunnel_name: str) → None, call:subprocess.run, func:_get_tunnel_logs(tunnel_name: str) → tuple[str, str], call:subprocess.run, func:_get_tunnel_exit_code(tunnel_name: str) → int | None, call:subprocess.run, call:int, call:result.stdout.strip, func:start_tunnel(instance_name: str, container_port: int, timeout, target_url) → dict[str, str], call:_ensure_image, call:_tunnel_container_name, call:_cleanup_stale_tunnel, call:instance_name.lower, call:get_backend_network_name, call:logger.debug, call:" ".join, call:subprocess.run, call:proc.stdout.strip, call:re.compile, call:__import__("time").time, call:_get_tunnel_logs, call:url_pattern.search, call:match.group, call:_get_tunnel_exit_code, call:__import__("time").sleep, call:logger.info, raise:RuntimeError, func:stop_tunnel(instance_name: str) → None, call:_tunnel_container_name, call:_cleanup_stale_tunnel, call:logger.debug, func:recreate_tunnel(instance_name: str, container_port: int, target_url) → dict[str, str], call:stop_tunnel, call:start_tunnel, func:check_tunnel_health(url: str, timeout) → dict[str, Any], call:subprocess.run, call:int, call:result.stdout.strip, call:str(exc).lower, call:any | dep: logging, re, subprocess, typing, src.services.docker.container ## arch -Modular service-oriented architecture with subprocess-based Docker CLI integration, Jinja2 templating for compose generation, path-traversal-safe file staging, and Cloudflare tunnel orchestration via containerized cloudflared. +Subprocess-based CLI wrapper architecture around Docker/cloudflared tools with template rendering, path-traversal-safe file staging, and functional decomposition into single-responsibility modules. ## tags tunnel, container, call:subprocess.run, get, name, call:, network, call:result.stdout.strip ## symbols diff --git a/apps/api/src/services/git/.pi-map.index.md b/apps/api/src/services/git/.pi-map.index.md index 11f3031..464c9da 100644 --- a/apps/api/src/services/git/.pi-map.index.md +++ b/apps/api/src/services/git/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/git ## role -Provides git repository operations for workspace management including cloning, authentication, and common git commands +Encapsulates all Git version control operations for workspace management, providing both synchronous and asynchronous interfaces for repository cloning, commit history, branch management, and remote operations with SSH authentication support. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/git/.pi-map.md b/apps/api/src/services/git/.pi-map.md index 22d2f8b..1e50426 100644 --- a/apps/api/src/services/git/.pi-map.md +++ b/apps/api/src/services/git/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/services/git index: apps/api/src/services/git/.pi-map.index.md ## role -Provides git repository operations for workspace management including cloning, authentication, and common git commands +Encapsulates all Git version control operations for workspace management, providing both synchronous and asynchronous interfaces for repository cloning, commit history, branch management, and remote operations with SSH authentication support. ## files - __init__.py | Exports the public API for the git services module by re-exporting key classes and functions from submodules. | dep: src.services.git.clone, src.services.git.git_operations, src.services.git.git_service - clone.py | Provides git repository cloning with optional SSH authentication, dirty state checking, and cleanup utilities | exp: func:clone_repository(remote_url: str, ssh_key_path: str | None, instance_dir: str, branch) → str, call:Path, call:clone_path.mkdir, call:os.environ.copy, call:str, call:logger.debug, call:subprocess.run, call:logger.error, raise:RuntimeError, func:check_dirty_state(clone_path: str) → tuple[bool, list[str]], call:subprocess.run, call:logger.warning, call:line.strip, call:result.stdout.split, call:len, func:remove_clone_directory(instance_dir: str) → None, call:Path, call:clone_path.exists, call:shutil.rmtree, call:logger.debug | dep: logging, os, subprocess, pathlib, shutil @@ -12,7 +12,7 @@ Provides git repository operations for workspace management including cloning, a - git_service.py | Provides asynchronous and synchronous git operations (clone, fetch, pull, branch check) with SSH key support for workspace management. | exp: class:GitService | dep: asyncio, logging, os, subprocess, tempfile - operations.py | Provides git repository operations including cloning, initialization, remote validation, and branch listing with SSH key authentication support. | exp: func:get_repo_path(user_id: uuid.UUID, project_id: uuid.UUID, name: str) → str, call:Settings, call:os.path.join, call:str, func:build_provider_clone_url(owner: str, repo: str) → str, func:prepare_ssh_env(ssh_key: SSHKey | None) → tuple[dict, str] | None, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:tempfile.mkstemp, call:os.write, call:private_key.encode, call:os.close, call:os.chmod, func:preflight_remote_repository(remote_url: str, ssh_key) → None, call:prepare_ssh_env, call:subprocess.run, call:os.path.exists, call:os.unlink, call:logger.error, raise:HTTPException, func:clone_working_repository(remote_url: str, repo_path: str, ssh_key) → None, call:prepare_ssh_env, call:subprocess.run, call:os.path.exists, call:os.unlink, call:logger.error, raise:HTTPException, func:init_working_repository(repo_path: str) → None, call:subprocess.run, raise:HTTPException, func:list_remote_branches(remote_url: str, ssh_key) → tuple[list[str], str], call:prepare_ssh_env, call:subprocess.run, call:logger.warning, call:result.stdout.strip().split, call:line.split, call:len, call:ref.startswith, call:branches.append, call:str, call:os.path.exists, call:os.unlink, raise:RuntimeError | dep: logging, os, subprocess, uuid, fastapi, src.config, src.models, src.services.shared.ssh_keys, tempfile ## arch -Layered service architecture with operation decomposition across specialized modules (clone, operations, git_operations, git_service), wrapping git CLI with async/sync variants and SSH key-based authentication +Layered abstraction pattern with three implementation tiers: low-level CLI wrappers (git_operations.py, operations.py), mid-level service coordinators (git_service.py), and high-level specialized utilities (clone.py), unified through __init__.py re-exports to present a single public API surface. ## tags git, raise:runtime, error, run, call:self., clone, call:subprocess.run, ssh ## symbols diff --git a/apps/api/src/services/instance/.pi-map.md b/apps/api/src/services/instance/.pi-map.md index 4aab369..c089b9f 100644 --- a/apps/api/src/services/instance/.pi-map.md +++ b/apps/api/src/services/instance/.pi-map.md @@ -11,7 +11,7 @@ Provides infrastructure for managing tool instance lifecycle events, health moni - health_monitor.py | Background health monitor that periodically polls Docker container and tunnel health for tool instances, publishing state change events and notifications. | exp: class:HealthSnapshot, class:HealthMonitor, method:__init__(self, event_bus: InstanceEventBus) → None, method:start(self) → None, call:self._task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._poll_loop, method:stop(self) → None, call:self._task.done, call:self._task.cancel, call:self._last_known_state.clear, method:_poll_loop(self) → None, call:asyncio.sleep, call:self._run_check_cycle, call:logger.exception, method:_run_check_cycle(self) → None, call:SessionLocal, call:session.execute, call:select(ToolInstance).where, call:ToolInstance.status.in_, call:result.scalars().all, call:self._check_instance, method:_check_instance(self, session: AsyncSession, instance: ToolInstance) → None, call:logger.debug, call:get_container_status, call:logger.exception, call:str, call:get_correlation_id, call:check_tunnel_health, call:tunnel_result.get, call:HealthSnapshot, call:self._last_known_state.get, call:self._derive_status, call:self._snapshots_equal, call:self._handle_state_change, method:_derive_status(self, snapshot: HealthSnapshot, previous: HealthSnapshot | None, current_status: str | None) → str, method:_snapshots_equal(self, a: HealthSnapshot, b: HealthSnapshot) → bool, method:_handle_state_change(self, session: AsyncSession, instance: ToolInstance, previous: HealthSnapshot | None, snapshot: HealthSnapshot, new_status: str) → None, call:HealthCheck, call:session.add, call:session.commit, call:get_correlation_id, call:str, call:datetime.now(timezone.utc).isoformat, call:self._event_bus.publish, call:notification_service.create_notification, call:logger.exception | dep: asyncio, logging, uuid, dataclasses, datetime, sqlalchemy, sqlalchemy.ext.asyncio, src.database, src.models, src.services.shared.correlation, src.services.docker, src.services.shared.tunnel, src.services.instance.event_bus, src.services.shared.notification_service - lifecycle_hooks.py | Provides helpers to publish tool instance lifecycle events, persist audit records, and conditionally send user notifications. | exp: func:_derive_title(event_type: str) → str, call:mapping.get, call:event_type.replace("instance.", "").replace("_", " ").title, func:_should_notify(event_type: str, status: str | None) → bool, func:_build_payload(event_type: str, instance: ToolInstance, status, message, metadata) → InstanceEventPayload, call:str, call:datetime.now(timezone.utc).isoformat, call:get_correlation_id, func:_write_audit_row(session: AsyncSession, instance: ToolInstance, event_type: str, created_by, status, message, metadata) → InstanceEvent, call:InstanceEvent, call:event_type.replace, call:session.add, call:session.commit, func:publish_lifecycle_event(event_bus: InstanceEventBus, session: AsyncSession, instance: ToolInstance, event_type: str, created_by, status, message, metadata) → None, call:_build_payload, call:_write_audit_row, call:event_bus.publish, call:_should_notify, call:_derive_title, call:notification_service.create_notification, call:logger.exception, call:payload.get | dep: logging, uuid, datetime, sqlalchemy.ext.asyncio, src.models, src.services.shared.correlation, src.services.instance.event_bus, src.services.shared.notification_service ## arch -Event-driven architecture using a singleton-typed in-memory pub/sub event bus with decoupled background health monitoring, lifecycle hook orchestration, and exception-isolated sync/async callback handling. +Event-driven architecture using a singleton in-memory pub/sub event bus with typed messages, background polling workers, and lifecycle hooks that bridge domain events to persistence and notifications with exception isolation between sync/async handlers. ## tags call:self., instance, src, services, event, health, call:logger.exception, check ## symbols diff --git a/apps/api/src/services/shared/.pi-map.index.md b/apps/api/src/services/shared/.pi-map.index.md index 4b963ab..ea63f7e 100644 --- a/apps/api/src/services/shared/.pi-map.index.md +++ b/apps/api/src/services/shared/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/shared ## role -Provides reusable, cross-cutting infrastructure services for the API including I/O safety, container operations, user notifications, request tracing, and workspace lifecycle management. +Provides reusable, cross-cutting infrastructure services for security, I/O, container operations, and workspace management used throughout the API layer. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/shared/.pi-map.md b/apps/api/src/services/shared/.pi-map.md index 26cdfe8..aae8550 100644 --- a/apps/api/src/services/shared/.pi-map.md +++ b/apps/api/src/services/shared/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/services/shared index: apps/api/src/services/shared/.pi-map.index.md ## role -Provides reusable, cross-cutting infrastructure services for the API including I/O safety, container operations, user notifications, request tracing, and workspace lifecycle management. +Provides reusable, cross-cutting infrastructure services for security, I/O, container operations, and workspace management used throughout the API layer. ## files - __init__.py | Re-exports shared service classes and functions from a services package to provide a unified public API | dep: src.services.shared.correlation, src.services.shared.file_service, src.services.shared.notification_service, src.services.shared.permission_fixer, src.services.shared.readiness_probe, src.services.shared.ssh_keys, src.services.shared.tunnel, src.services.shared.workspace_manager, correlation, file_service, notification_service, permission_fixer, readiness_probe, ssh_keys, tunnel, workspace_manager - correlation.py | Provides async correlation ID tracking via context variables and FastAPI middleware for request tracing. | exp: class:CorrelationIdMiddleware, method:dispatch(self, request: Request, call_next), call:request.headers.get, call:str, call:uuid.uuid4, call:CORRELATION_ID.set, call:call_next, call:CORRELATION_ID.reset, func:get_correlation_id() → str, call:CORRELATION_ID.get, call:str, call:uuid.uuid4 | dep: contextvars, uuid, fastapi, starlette.middleware.base, fastapi.Request, starlette.middleware.base.BaseHTTPMiddleware @@ -14,11 +14,11 @@ Provides reusable, cross-cutting infrastructure services for the API including I - readiness_probe.py | Executes a retryable readiness probe command inside a Docker container with configurable timeout and interval | exp: func:execute_probe(container_id: str, command: str, timeout, interval) → tuple[bool, list[str]], call:asyncio.get_event_loop().time, call:logs.append, call:logger.debug, call:subprocess.run, call:result.stdout.strip, call:result.stderr.strip, call:asyncio.sleep | dep: asyncio, logging, subprocess - ssh_keys.py | Decrypts and writes SSH key files to instance directories for container mounting, with optional ownership configuration and SSH config generation. | exp: func:_get_fernet() → Fernet, call:Settings, call:hashlib.sha256(settings.session_secret.encode()).digest, call:settings.session_secret.encode, call:base64.urlsafe_b64encode, call:Fernet, func:_sanitize_filename(name: str) → str, call:re.sub, call:sanitized.strip, func:prepare_ssh_key_files(instance_dir: str, ssh_key, subdir, uid, gid, key_filename, write_config) → str, call:Path, call:ssh_dir.mkdir, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:private_key_path.write_text, call:os.chmod, call:public_key_path.write_text, call:config_path.write_text, call:os.chown, call:logger.debug, call:logger.warning, call:os.getuid, call:str, func:write_ssh_config(ssh_dir: str, key_filenames: list[str], uid, gid) → None, call:Path, call:ssh_dir_path.mkdir, call:lines.append, call:"\n".join, call:config_path.write_text, call:os.chmod, call:os.chown, func:cleanup_ssh_key_files(instance_dir: str) → None, call:Path, call:ssh_dir.exists, call:ssh_dir.iterdir, call:file_path.unlink, call:ssh_dir.rmdir | dep: logging, os, re, pathlib, cryptography.fernet, src.config, base64, hashlib - tunnel.py | Re-exports Docker tunnel functions from a nested module for backward compatibility. | dep: src.services.docker.tunnel -- workspace_manager.py | Manages workspace lifecycle operations including creation, deletion, synchronization, and validation for git repository workspaces. | exp: class:SyncResult, class:WorkspaceHasInstancesError, method:__init__(self, instances: list[dict]) → None, call:super().__init__, call:len, class:WorkspaceManager, method:_workspace_path(self, repo_id: uuid.UUID, name: str) → str, call:os.path.join, call:str, method:create(self, repo: GitRepository, user_id: uuid.UUID, name: str, branch, session) → Workspace, call:self._workspace_path, call:os.path.dirname, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:logger.info, call:os.path.exists, call:logger.warning, call:shutil.rmtree, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.clone, call:self._make_world_writable, call:Workspace, call:datetime.now, raise:ValueError, method:delete(self, workspace: Workspace, force, session) → None, call:self._get_instances, call:self._stop_and_delete_instance, call:os.path.exists, call:shutil.rmtree, call:logger.info, call:session.delete, raise:ValueError, raise:WorkspaceHasInstancesError, method:sync(self, workspace: Workspace, session) → SyncResult, call:logger.info, call:session.get, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.fetch, call:GitService.branch_exists_remotely, call:SyncResult, call:GitService.pull, call:self._make_world_writable, call:datetime.now, method:_make_world_writable(self, path: str) → None, call:contextlib.suppress, call:os.chmod, call:os.walk, call:os.path.join, call:os.stat, method:_get_instances(self, workspace: Workspace, session: AsyncSession) → list[ToolInstance], call:session.execute, call:select(ToolInstance).where, call:list, call:result.scalars().all, method:_stop_and_delete_instance(self, instance: ToolInstance) → None, call:logger.warning | dep: contextlib, logging, os, shutil, stat, uuid, dataclasses, datetime, typing, sqlalchemy, src.models, src.services.git.git_service, src.services.shared.ssh_keys, sqlalchemy.ext.asyncio +- workspace_manager.py | Manages Git workspace lifecycle operations including creation, deletion, sync, and migration of legacy tool instances into workspace-bound repositories. | exp: class:SyncResult, class:WorkspaceHasInstancesError, method:__init__(self, instances: list[dict]) → None, call:super().__init__, call:len, class:WorkspaceManager, method:_workspace_path(self, repo_id: uuid.UUID, name: str) → str, call:os.path.join, call:str, method:create(self, repo: GitRepository, user_id: uuid.UUID, name: str, branch, session) → Workspace, call:self._workspace_path, call:os.path.dirname, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:logger.info, call:os.path.exists, call:logger.warning, call:shutil.rmtree, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.clone, call:self._make_world_writable, call:Workspace, call:datetime.now, raise:ValueError, method:delete(self, workspace: Workspace, force, session) → None, call:self._get_instances, call:self._stop_and_delete_instance, call:os.path.exists, call:shutil.rmtree, call:logger.info, call:session.delete, raise:ValueError, raise:WorkspaceHasInstancesError, method:sync(self, workspace: Workspace, session) → SyncResult, call:logger.info, call:session.get, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.fetch, call:GitService.branch_exists_remotely, call:SyncResult, call:GitService.pull, call:self._make_world_writable, call:datetime.now, method:_make_world_writable(self, path: str) → None, call:contextlib.suppress, call:os.chmod, call:os.walk, call:os.path.join, call:os.stat, method:_get_instances(self, workspace: Workspace, session: AsyncSession) → list[ToolInstance], call:session.execute, call:select(ToolInstance).where, call:list, call:result.scalars().all, method:_stop_and_delete_instance(self, instance: ToolInstance, session: AsyncSession) → None, call:delete_tool_instance, call:logger.info, call:logger.error, method:ensure_instance_workspace(self, instance: ToolInstance, session: AsyncSession) → Workspace, call:session.get, call:self._workspace_name_exists, call:self._migrate_clone_into_workspace, call:self.create, call:session.add, call:session.commit, call:session.refresh, call:logger.info, raise:RuntimeError, method:_workspace_name_exists(self, session: AsyncSession, repo_id: uuid.UUID, name: str) → bool, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, method:_migrate_clone_into_workspace(self, instance: ToolInstance, repo: "GitRepository", session: AsyncSession, name: str) → Workspace, call:os.path.dirname, call:os.path.join, call:os.path.exists, call:self._workspace_path, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:shutil.rmtree, call:shutil.move, call:self._make_world_writable, call:Workspace, call:datetime.now, call:session.add, call:session.flush, raise:RuntimeError | dep: contextlib, logging, os, shutil, stat, uuid, dataclasses, datetime, typing, sqlalchemy, src.models, src.services.git.git_service, src.services.shared.ssh_keys, sqlalchemy.ext.asyncio, src.services.tool.instance_service ## arch -Modular service-oriented architecture with async singletons, context variable-based state propagation, path traversal defense, Docker container exec abstraction, and strict ownership-based isolation boundaries. +Modular utility services pattern with async singletons, context variables for request tracing, defensive security (path traversal/ownership isolation), Docker exec abstraction, and Git-backed workspace lifecycle management. ## tags -error, get, key, call:self., src, call:ssh, at.is, call:session.execute +error, workspace, call:self., get, key, src, call:session.execute, call:ssh ## symbols - CorrelationIdMiddleware - FileEntry diff --git a/apps/api/src/services/terminal/.pi-map.index.md b/apps/api/src/services/terminal/.pi-map.index.md index d96081a..f48672a 100644 --- a/apps/api/src/services/terminal/.pi-map.index.md +++ b/apps/api/src/services/terminal/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/terminal ## role -Provides backend WebSocket terminal session management with PTY-based interactive shells, lifecycle control, and real-time I/O streaming for remote terminal access. +Provides WebSocket-connected terminal session management with PTY-based I/O for remote terminal access in the API server. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/terminal/.pi-map.md b/apps/api/src/services/terminal/.pi-map.md index 6d7069d..ae5a8d0 100644 --- a/apps/api/src/services/terminal/.pi-map.md +++ b/apps/api/src/services/terminal/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/src/services/terminal index: apps/api/src/services/terminal/.pi-map.index.md ## role -Provides backend WebSocket terminal session management with PTY-based interactive shells, lifecycle control, and real-time I/O streaming for remote terminal access. +Provides WebSocket-connected terminal session management with PTY-based I/O for remote terminal access in the API server. ## files - __init__.py | Package initialization file that exports the public API for a terminal services module | dep: src.services.terminal.terminal_manager, src.services.terminal.terminal_session - terminal_manager.py | Manages WebSocket-connected terminal sessions with lifecycle control, idle cleanup, database persistence, and per-instance session limits. | exp: class:MaxSessionsExceededError, method:__init__(self, instance_id: str, max_sessions) → None, call:super().__init__, class:TerminalManager, method:__init__(self) → None, call:self._start_idle_check, method:_start_idle_check(self) → None, call:self._idle_check_task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._idle_check_loop, method:_idle_check_loop(self) → None, call:asyncio.sleep, call:self._cleanup_idle_sessions, call:logger.error, method:_cleanup_idle_sessions(self) → None, call:list, call:self._sessions.items, call:session.is_idle, call:idle_keys.append, call:logger.info, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, method:_insert_db_session_row(self, session_id: str, instance_id: uuid.UUID, name: str) → None, call:SessionLocal, call:pg_insert(TerminalSessionModel) .values( id=uuid.UUID(session_id), instance_id=instance_id, name=name, status="active", created_at=datetime.now(timezone.utc), last_activity_at=datetime.now(timezone.utc), ) .on_conflict_do_nothing, call:uuid.UUID, call:datetime.now, call:db_session.execute, call:db_session.commit, call:logger.debug, call:logger.error, method:_mark_closed_in_db(self, session_id: str) → None, call:SessionLocal, call:db_session.get, call:uuid.UUID, call:datetime.now, call:db_session.commit, call:logger.debug, call:logger.error, method:_count_sessions_for_instance(self, instance_id_str: str) → int, call:sum, method:create_session(self, instance_id: uuid.UUID, container_id: str, startup_command, name, session_id) → TerminalSession, call:str, call:self._count_sessions_for_instance, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, call:logger.info, raise:MaxSessionsExceededError, method:get_or_create_session(self, instance_id: uuid.UUID, container_id: str, startup_command) → TerminalSession, call:self._start_idle_check, call:str, call:session.is_alive, call:logger.debug, call:session.close, call:logger.info, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, method:get_session(self, instance_id: str, session_id: str) → TerminalSession | None, call:self._sessions.get, call:self._sessions.items, method:_find_key_by_internal_id(self, instance_id: str, internal_session_id: str) → tuple[str, str] | None, call:self._sessions.items, method:get_sessions_for_instance(self, instance_id: str) → list[TerminalSession], call:self._sessions.items, method:close_session(self, instance_id: str, session_id: str) → None, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:logger.info, method:attach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.has_websockets, call:logger.debug, call:list, call:ws.close, call:session._websockets.clear, call:session.attach_websocket, call:session.get_buffer, call:websocket.send_bytes, method:detach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.detach_websocket, method:reset_session(self, instance_id: uuid.UUID, container_id: str, startup_command, session_id, name) → TerminalSession, call:str, call:logger.debug, call:self._sessions.pop, call:old_session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:uuid.uuid4, call:TerminalSession, call:new_session.start, call:self._insert_db_session_row, method:close_all(self) → None, call:list, call:self._sessions.values, call:self._sessions.clear, call:session.close, call:self._idle_check_task.done, call:self._idle_check_task.cancel | dep: asyncio, logging, uuid, datetime, fastapi, sqlalchemy.dialects.postgresql, src.database, src.models, src.services.terminal.terminal_session, fastapi.WebSocket - terminal_session.py | Manages a high-performance asyncio-native terminal session using PTY I/O with event-driven reads, output batching, and flow control for WebSocket delivery. | exp: class:TerminalSession, method:__init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command, name) → None, call:deque, call:set, call:time.time, call:self._generate_name, call:str, call:bytearray, call:asyncio.Lock, method:start(self, startup_command) → None, call:pty.openpty, call:self._set_terminal_size, call:logger.debug, call:asyncio.create_subprocess_exec, call:os.close, call:time.time, call:self._start_reading, method:_start_reading(self) → None, call:asyncio.get_event_loop, call:loop.add_reader, call:logger.debug, call:logger.error, method:_stop_reading(self) → None, call:asyncio.get_event_loop, call:loop.remove_reader, method:_on_fd_readable(self) → None, call:os.read, call:logger.debug, call:self._handle_eof, call:self._add_to_buffer, call:time.time, call:self._queue_output, method:_add_to_buffer(self, data: bytes) → None, call:self._output_buffer.append, call:len, call:self._output_buffer.popleft, method:_queue_output(self, data: bytes) → None, call:self._batch_buffer.extend, call:len, call:self._pause_output, call:asyncio.get_event_loop, call:loop.call_later, method:_flush_batch_sync(self) → None, call:self._batch_buffer.clear, call:bytes, call:set, call:list, call:asyncio.create_task, call:self._send_bytes, call:dead_sockets.add, method:_send_bytes(self, ws: Any, payload: bytes) → None, call:ws.send_bytes, call:self._websockets.discard, method:acknowledge_data(self, char_count: int) → None, call:max, call:self._resume_output, call:self._ack_timeout_handle.cancel, call:asyncio.get_event_loop, call:loop.call_later, method:_ack_timeout_fallback(self) → None, call:logger.warning, call:self._resume_output, method:_pause_output(self) → None, call:self._stop_reading, call:logger.debug, method:_resume_output(self) → None, call:self._start_reading, call:logger.debug, method:get_buffer(self) → bytes, call:b"".join, method:_handle_eof(self) → None, call:self._stop_reading, call:self.process._transport.close, call:set, call:self._websockets.clear, call:asyncio.create_task, call:ws.close, call:logger.info, method:write_input(self, data: bytes) → None, call:os.write, call:time.time, call:logger.debug, call:self._handle_eof, method:_set_terminal_size(self, cols: int, rows: int) → None, call:logger.warning, call:struct.pack, call:fcntl.ioctl, call:logger.debug, call:logger.error, method:resize(self, cols: int, rows: int) → None, call:logger.warning, call:logger.debug, call:self._set_terminal_size, call:os.kill, method:reset(self) → None, call:self.close, call:self._output_buffer.clear, call:self._websockets.clear, call:self._batch_buffer.clear, method:close(self) → None, call:self._stop_reading, call:self._batch_timer.cancel, call:self._ack_timeout_handle.cancel, call:os.close, call:self.process.kill, call:asyncio.wait_for, call:self.process.wait, method:is_alive(self) → bool, method:is_idle(self) → bool, call:time.time, method:attach_websocket(self, websocket: Any) → None, call:self._websockets.add, call:time.time, method:detach_websocket(self, websocket: Any) → None, call:self._websockets.discard, method:has_websockets(self) → bool, call:len, method:send_to_all(self, data: bytes) → None, call:set, call:ws.send_bytes, call:dead_sockets.add, call:self._websockets.discard, method:read_output(self) → bytes | dep: asyncio, logging, os, pty, signal, struct, fcntl, time, uuid, collections, typing, collections.deque ## arch -Asyncio-native event-driven architecture with PTY subprocess I/O, batched output with flow control, session lifecycle management (idle cleanup, persistence, limits), and WebSocket message passing. +Asyncio-native event-driven architecture with session lifecycle management, resource cleanup, output batching/flow control, and database persistence for scalable terminal multiplexing. ## tags call:self., session, call:logger.debug, idle, output, terminal, check, task ## symbols diff --git a/apps/api/src/services/tool/.pi-map.index.md b/apps/api/src/services/tool/.pi-map.index.md index 5a2b376..2453cf4 100644 --- a/apps/api/src/services/tool/.pi-map.index.md +++ b/apps/api/src/services/tool/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/services/tool ## role -Orchestrates Docker container lifecycle for tool instances with git repository mounting, configuration validation, and SSH tunnel management. +Provides Docker container lifecycle management for tool instances with git repository integration and configuration validation. ## parent index: apps/api/src/services/.pi-map.index.md map: apps/api/src/services/.pi-map.md diff --git a/apps/api/src/services/tool/.pi-map.md b/apps/api/src/services/tool/.pi-map.md index d4ba21f..a5dd64b 100644 --- a/apps/api/src/services/tool/.pi-map.md +++ b/apps/api/src/services/tool/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/src/services/tool index: apps/api/src/services/tool/.pi-map.index.md ## role -Orchestrates Docker container lifecycle for tool instances with git repository mounting, configuration validation, and SSH tunnel management. +Provides Docker container lifecycle management for tool instances with git repository integration and configuration validation. ## files -- instance_service.py | Manages Docker-based tool instance lifecycle operations including git repository mounting, config profile validation, compose file generation, container orchestration, and SSH tunnel management. | exp: func:resolve_git_mounts(session: AsyncSession, resolved: ResolvedProfile, instance_dir, working_directory, home_dir) → list[dict], call:tasks.append, call:resolve_single_git_mount, call:asyncio.gather, call:isinstance, call:logger.warning, call:volume_mounts.extend, func:normalize_git_mount(entry: dict) → dict, call:dict, call:entry.get, call:entry.pop, func:clone_git_repo(remote_url: str, branch: str | None, clone_parent: str) → str, call:hashlib.md5(remote_url.encode()).hexdigest, call:remote_url.encode, call:remote_url.split("/")[-1].replace, call:os.path.join, call:os.path.exists, call:os.makedirs, call:clone_repository, call:logger.debug, call:logger.warning, call:pull_repository_updates, call:checkout_branch, func:resolve_git_mount_mappings(repo_path: str, mappings: list[dict], working_directory: str | None, home_dir) → list[dict], call:mapping.get, call:logger.warning, call:expand_container_path, call:target_path.startswith, call:os.path.join, call:expand_glob_source, call:os.path.exists, call:len, call:os.path.relpath, call:volume_mounts.append, call:logger.debug, func:resolve_single_git_mount(session: AsyncSession, git_mount: dict, instance_dir, working_directory, home_dir) → list[dict], call:normalize_git_mount, call:git_mount.get, call:logger.warning, call:asyncio.to_thread, call:resolve_git_mount_mappings, func:checkout_branch(repo_path: str, branch: str) → bool, call:subprocess.run, call:logger.warning, call:result.stderr.strip, func:pull_repository_updates(repo_path: str, remote_url: str) → None, call:subprocess.run, raise:RuntimeError, func:expand_glob_source(source_path: str, repo_path: str) → list[str], call:any, call:os.path.exists, call:glob_module.glob, call:len, call:os.path.abspath, call:abs_path.startswith, call:results.append, call:logger.warning, func:validate_config_profile(session: AsyncSession, profile_id: str | None, user_id: uuid.UUID, project_id: uuid.UUID, tool_type_id: uuid.UUID) → uuid.UUID | None, call:uuid.UUID, call:session.get, raise:HTTPException, func:sanitize_compose_file(compose_path: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:isinstance, call:port_mapping.split, call:len, call:valid_ports.append, call:compose_file.write_text, call:yaml.dump, func:modify_compose_file(compose_path: str, port_override, start_command, working_directory, extra_volumes, home_dir) → None, call:Path, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:enumerate, call:isinstance, call:port_mapping.split, call:expand_container_path, call:vol.get, call:service_config["volumes"].append, call:service_config.get, call:sort_volumes_by_specificity, call:compose_file.write_text, call:yaml.dump, func:ensure_container_name_in_compose(compose_path: str, container_name: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:container_name.lower, call:compose_file.write_text, call:yaml.dump, call:logger.info, func:ensure_web_bind_address(compose_path: str, tool_type_name: str, default_port: int) → None, call:KNOWN_BIND_FIXES.get, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].values, call:service_config.get, call:compose_file.write_text, call:yaml.dump, call:logger.warning, call:logger.info, func:ensure_backend_network_in_compose(compose_path: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:get_backend_network_name, call:compose_data["services"].values, call:svc_config.get, call:compose_file.write_text, call:yaml.dump, call:logger.info, func:prepare_manifest_instance(session: AsyncSession, instance: ToolInstance, instance_dir: str, repo_path: str, env_vars: dict, extra_volumes: list, working_directory: str | None) → tuple[str, str, dict, str], call:session.get, call:dict, call:resolve_base, call:deep_merge, call:logger.warning, call:merge_with_config, call:manifest.pop, call:env_vars.update, call:extra_volumes.extend, call:compute_image_tag, call:subprocess.run, call:check.stdout.strip, call:compile_dockerfile, call:compile_entrypoint, call:logger.debug, call:len, call:asyncio.to_thread, call:logger.info, call:os.path.join, call:resolve_profile, call:gm.get, call:instance.name.lower, call:compile_compose, call:manifest.get, call:datetime.now, call:get_manifest_home_dir, raise:RuntimeError, func:create_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, data: "CreateInstanceRequest") → ToolInstance, call:session.get, call:uuid.UUID, call:validate_config_profile, call:uuid.uuid4, call:select(ToolInstance) .where(ToolInstance.workspace_id == workspace_id) .where(ToolInstance.tool_type_id == tool_type_id) .where, call:select(ToolInstance) .where(ToolInstance.repository_id == repo_id) .where(ToolInstance.tool_type_id == tool_type_id) .where, call:session.execute, call:len, call:result.scalars().all, call:ensure_instance_directory, call:os.path.join, call:find_free_port, call:prepare_ssh_key_files, call:clone_repository, call:logger.exception, call:cleanup_ssh_key_files, call:os.listdir, call:logger.error, call:logger.debug, call:subprocess.run, call:f"headquarter/{instance_name}:latest".lower, call:asyncio.to_thread, call:logger.info, call:instance_name.lower, call:write_compose_file, call:dict, call:resolve_base, call:deep_merge, call:compute_image_tag, call:compile_compose, call:str, call:render_compose_template, call:yaml.safe_load, call:compose_data["services"].values, call:svc.get, call:logger.warning, call:svc["volumes"].append, call:yaml.dump, call:ToolInstance, call:session.add, call:session.commit, call:session.refresh, call:publish_lifecycle_event, raise:ValueError, raise:RuntimeError, func:start_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data: "StartInstanceRequest | None") → dict, call:session.get, call:validate_config_profile, call:session.commit, call:os.path.exists, call:logger.info, call:dict, call:resolve_base, call:deep_merge, call:get_manifest_home_dir, call:manifest.get, call:user_cfg.get, call:logger.debug, call:os.path.dirname, call:resolve_profile, call:apply_resolved_profile, call:env_vars.update, call:config_files.update, call:extra_volumes.extend, call:resolve_git_mounts, call:profile_hints.get, call:len, call:logger.error, call:write_env_file, call:write_config_files, call:uuid.UUID, call:ssh_keys_to_mount.append, call:logger.warning, call:os.path.join, call:os.makedirs, call:_sanitize_filename, call:key_filenames.append, call:prepare_ssh_key_files, call:write_ssh_config, call:extra_volumes.append, call:prepare_manifest_instance, call:write_compose_file, call:logger.exception, call:modify_compose_file, call:sanitize_compose_file, call:ensure_web_bind_address, call:ensure_container_name_in_compose, call:ensure_backend_network_in_compose, call:execute_compose_command, call:instance.name.lower, call:get_container_id, call:publish_lifecycle_event, call:wait_for_container_running, call:get_container_logs, call:resolved_manifest.get, call:apply_mount_permissions, call:home_dir.startswith, call:apply_ssh_permissions, call:probe_config.get, call:execute_probe, call:datetime.now().isoformat, call:"\n".join, call:start_tunnel, call:str, call:traceback.format_exc, raise:ValueError, raise:RuntimeError, func:restart_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:stop_tunnel, call:logger.debug, call:logger.warning, call:os.path.exists, call:os.path.dirname, call:resolve_profile, call:apply_resolved_profile, call:write_env_file, call:logger.error, call:sanitize_compose_file, call:ensure_web_bind_address, call:ensure_container_name_in_compose, call:ensure_backend_network_in_compose, call:execute_compose_command, call:datetime.now, call:session.commit, call:start_tunnel, call:publish_lifecycle_event, raise:ValueError, raise:RuntimeError, func:delete_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, force) → None, call:session.get, call:os.path.dirname, call:os.path.join, call:os.path.exists, call:check_dirty_state, call:stop_tunnel, call:logger.debug, call:logger.warning, call:execute_compose_command, call:shutil.rmtree, call:publish_lifecycle_event, call:session.delete, call:session.commit, raise:ValueError, raise:RuntimeError, func:recreate_instance_tunnel(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:instance.name.lower, call:logger.info, call:get_container_id, call:logger.error, call:get_backend_network_name, call:is_container_on_network, call:connect_container_to_network, call:get_container_ip_on_network, call:logger.warning, call:recreate_tunnel, call:check_tunnel_health, call:health.get, call:subprocess.run, call:probe.stdout.strip, call:session.commit, call:logger.exception, raise:ValueError, raise:RuntimeError, func:stop_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:stop_tunnel, call:logger.warning, call:os.path.exists, call:execute_compose_command, call:datetime.now, call:session.commit, call:publish_lifecycle_event, raise:ValueError, func:rename_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, display_name: str) → ToolInstance, call:session.get, call:display_name.strip, call:session.commit, call:session.refresh, raise:ValueError | dep: asyncio, logging, os, subprocess, uuid, datetime, httpx, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.models, src.schemas.tool, src.services.git.clone, src.services.config.config_profile_resolver, src.services.docker, src.services.shared.tunnel, src.services.build.docker_build, src.services.build.manifest_compiler, src.services.shared.permission_fixer, src.services.shared.readiness_probe, src.services.shared.ssh_keys, src.services.instance.event_bus, src.services.instance.lifecycle_hooks, src.auth.dependencies, hashlib, yaml, pathlib, traceback, shutil +- instance_service.py | Manages Docker-based tool instances including git repository mounting, config profile validation, compose file generation, and container lifecycle operations. | exp: func:resolve_git_mounts(session: AsyncSession, resolved: ResolvedProfile, instance_dir, working_directory, home_dir) → list[dict], call:tasks.append, call:resolve_single_git_mount, call:asyncio.gather, call:isinstance, call:logger.warning, call:volume_mounts.extend, func:normalize_git_mount(entry: dict) → dict, call:dict, call:entry.get, call:entry.pop, func:clone_git_repo(remote_url: str, branch: str | None, clone_parent: str) → str, call:hashlib.md5(remote_url.encode()).hexdigest, call:remote_url.encode, call:remote_url.split("/")[-1].replace, call:os.path.join, call:os.path.exists, call:os.makedirs, call:clone_repository, call:logger.debug, call:logger.warning, call:pull_repository_updates, call:checkout_branch, func:resolve_git_mount_mappings(repo_path: str, mappings: list[dict], working_directory: str | None, home_dir) → list[dict], call:mapping.get, call:logger.warning, call:expand_container_path, call:target_path.startswith, call:os.path.join, call:expand_glob_source, call:os.path.exists, call:len, call:os.path.relpath, call:volume_mounts.append, call:logger.debug, func:resolve_single_git_mount(session: AsyncSession, git_mount: dict, instance_dir, working_directory, home_dir) → list[dict], call:normalize_git_mount, call:git_mount.get, call:logger.warning, call:asyncio.to_thread, call:resolve_git_mount_mappings, func:checkout_branch(repo_path: str, branch: str) → bool, call:subprocess.run, call:logger.warning, call:result.stderr.strip, func:pull_repository_updates(repo_path: str, remote_url: str) → None, call:subprocess.run, raise:RuntimeError, func:expand_glob_source(source_path: str, repo_path: str) → list[str], call:any, call:os.path.exists, call:glob_module.glob, call:len, call:os.path.abspath, call:abs_path.startswith, call:results.append, call:logger.warning, func:validate_config_profile(session: AsyncSession, profile_id: str | None, user_id: uuid.UUID, project_id: uuid.UUID, tool_type_id: uuid.UUID) → uuid.UUID | None, call:uuid.UUID, call:session.get, raise:HTTPException, func:sanitize_compose_file(compose_path: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:isinstance, call:port_mapping.split, call:len, call:valid_ports.append, call:compose_file.write_text, call:yaml.dump, func:modify_compose_file(compose_path: str, port_override, start_command, working_directory, extra_volumes, home_dir) → None, call:Path, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:enumerate, call:isinstance, call:port_mapping.split, call:expand_container_path, call:vol.get, call:service_config["volumes"].append, call:service_config.get, call:sort_volumes_by_specificity, call:compose_file.write_text, call:yaml.dump, func:ensure_container_name_in_compose(compose_path: str, container_name: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].items, call:container_name.lower, call:compose_file.write_text, call:yaml.dump, call:logger.info, func:ensure_web_bind_address(compose_path: str, tool_type_name: str, default_port: int) → None, call:KNOWN_BIND_FIXES.get, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:compose_data["services"].values, call:service_config.get, call:compose_file.write_text, call:yaml.dump, call:logger.warning, call:logger.info, func:ensure_backend_network_in_compose(compose_path: str) → None, call:Path, call:compose_file.exists, call:compose_file.read_text, call:yaml.safe_load, call:get_backend_network_name, call:compose_data["services"].values, call:svc_config.get, call:compose_file.write_text, call:yaml.dump, call:logger.info, func:prepare_manifest_instance(session: AsyncSession, instance: ToolInstance, instance_dir: str, repo_path: str, env_vars: dict, extra_volumes: list, working_directory: str | None) → tuple[str, str, dict, str], call:session.get, call:dict, call:resolve_base, call:deep_merge, call:logger.warning, call:merge_with_config, call:manifest.pop, call:env_vars.update, call:extra_volumes.extend, call:compute_image_tag, call:subprocess.run, call:check.stdout.strip, call:compile_dockerfile, call:compile_entrypoint, call:logger.debug, call:len, call:asyncio.to_thread, call:logger.info, call:resolve_profile, call:gm.get, call:instance.name.lower, call:compile_compose, call:manifest.get, call:datetime.now, call:get_manifest_home_dir, raise:RuntimeError, func:create_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, data: "CreateInstanceRequest") → ToolInstance, call:session.get, call:uuid.UUID, call:validate_config_profile, call:uuid.uuid4, call:select(ToolInstance) .where(ToolInstance.workspace_id == workspace_id) .where(ToolInstance.tool_type_id == tool_type_id) .where, call:select(ToolInstance) .where(ToolInstance.repository_id == repo_id) .where(ToolInstance.tool_type_id == tool_type_id) .where, call:session.execute, call:len, call:result.scalars().all, call:ensure_instance_directory, call:os.path.join, call:find_free_port, call:f"headquarter/{instance_name}:latest".lower, call:asyncio.to_thread, call:logger.error, call:logger.info, call:instance_name.lower, call:write_compose_file, call:dict, call:resolve_base, call:deep_merge, call:compute_image_tag, call:compile_compose, call:str, call:render_compose_template, call:ToolInstance, call:session.add, call:session.commit, call:session.refresh, call:publish_lifecycle_event, raise:ValueError, raise:RuntimeError, func:start_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data: "StartInstanceRequest | None") → dict, call:session.get, call:validate_config_profile, call:session.commit, call:os.path.exists, call:logger.info, call:dict, call:resolve_base, call:deep_merge, call:get_manifest_home_dir, call:manifest.get, call:user_cfg.get, call:logger.debug, call:os.path.dirname, call:resolve_profile, call:apply_resolved_profile, call:env_vars.update, call:config_files.update, call:extra_volumes.extend, call:resolve_git_mounts, call:profile_hints.get, call:len, call:logger.error, call:write_env_file, call:write_config_files, call:uuid.UUID, call:ssh_keys_to_mount.append, call:logger.warning, call:os.path.join, call:os.makedirs, call:_sanitize_filename, call:key_filenames.append, call:prepare_ssh_key_files, call:write_ssh_config, call:extra_volumes.append, call:prepare_manifest_instance, call:write_compose_file, call:logger.exception, call:modify_compose_file, call:sanitize_compose_file, call:ensure_web_bind_address, call:ensure_container_name_in_compose, call:ensure_backend_network_in_compose, call:execute_compose_command, call:instance.name.lower, call:get_container_id, call:publish_lifecycle_event, call:wait_for_container_running, call:get_container_logs, call:resolved_manifest.get, call:apply_mount_permissions, call:home_dir.startswith, call:apply_ssh_permissions, call:probe_config.get, call:execute_probe, call:datetime.now().isoformat, call:"\n".join, call:start_tunnel, call:str, call:traceback.format_exc, raise:ValueError, raise:RuntimeError, func:restart_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:stop_tunnel, call:logger.debug, call:logger.warning, call:os.path.exists, call:os.path.dirname, call:resolve_profile, call:apply_resolved_profile, call:write_env_file, call:logger.error, call:sanitize_compose_file, call:ensure_web_bind_address, call:ensure_container_name_in_compose, call:ensure_backend_network_in_compose, call:execute_compose_command, call:datetime.now, call:session.commit, call:start_tunnel, call:publish_lifecycle_event, raise:ValueError, raise:RuntimeError, func:delete_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, force) → None, call:session.get, call:os.path.dirname, call:os.path.join, call:os.path.exists, call:check_dirty_state, call:stop_tunnel, call:logger.debug, call:logger.warning, call:execute_compose_command, call:shutil.rmtree, call:publish_lifecycle_event, call:session.delete, call:session.commit, raise:ValueError, raise:RuntimeError, func:recreate_instance_tunnel(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:instance.name.lower, call:logger.info, call:get_container_id, call:logger.error, call:get_backend_network_name, call:is_container_on_network, call:connect_container_to_network, call:get_container_ip_on_network, call:logger.warning, call:recreate_tunnel, call:check_tunnel_health, call:health.get, call:subprocess.run, call:probe.stdout.strip, call:session.commit, call:logger.exception, raise:ValueError, raise:RuntimeError, func:stop_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID) → dict, call:session.get, call:stop_tunnel, call:logger.warning, call:os.path.exists, call:execute_compose_command, call:datetime.now, call:session.commit, call:publish_lifecycle_event, raise:ValueError, func:rename_tool_instance(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, display_name: str) → ToolInstance, call:session.get, call:display_name.strip, call:session.commit, call:session.refresh, raise:ValueError | dep: asyncio, logging, os, subprocess, uuid, datetime, httpx, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.models, src.schemas.tool, src.services.git.clone, src.services.config.config_profile_resolver, src.services.docker, src.services.shared.tunnel, src.services.build.docker_build, src.services.build.manifest_compiler, src.services.shared.permission_fixer, src.services.shared.readiness_probe, src.services.shared.ssh_keys, src.services.instance.event_bus, src.services.instance.lifecycle_hooks, src.auth.dependencies, hashlib, yaml, pathlib, traceback, shutil, glob ## arch -Service-oriented architecture with Docker Compose orchestration, git-based code mounting, config profile validation, and SSH tunnel proxying for isolated tool execution environments. +Service-oriented architecture with a single service class handling container orchestration, filesystem operations, and external tool integration through Docker Compose. ## tags -compose, call:compose, call:logger.warning, error, instance, container, git, text +compose, call:compose, error, call:logger.warning, instance, container, git, text ## symbols - resolve_git_mounts - normalize_git_mount diff --git a/apps/api/src/utils/.pi-map.index.md b/apps/api/src/utils/.pi-map.index.md index ae990ab..3e7a5c7 100644 --- a/apps/api/src/utils/.pi-map.index.md +++ b/apps/api/src/utils/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/src/utils ## role -Provides Git repository interaction utilities for the API layer, abstracting subprocess-based git operations into reusable Python modules. +Provides Git repository interaction utilities that wrap subprocess commands for URL parsing, file browsing, history extraction, and repository control operations. ## parent index: apps/api/src/.pi-map.index.md map: apps/api/src/.pi-map.md diff --git a/apps/api/src/utils/.pi-map.md b/apps/api/src/utils/.pi-map.md index 81502c8..f15d115 100644 --- a/apps/api/src/utils/.pi-map.md +++ b/apps/api/src/utils/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/api/src/utils index: apps/api/src/utils/.pi-map.index.md ## role -Provides Git repository interaction utilities for the API layer, abstracting subprocess-based git operations into reusable Python modules. +Provides Git repository interaction utilities that wrap subprocess commands for URL parsing, file browsing, history extraction, and repository control operations. ## files - __init__.py | Empty file with no functionality - git_control.py | Provides a Python wrapper for common Git repository operations using subprocess calls | exp: class:GitStatus, func:_run_git_command(repo_path: str, *args: str) → str, call:subprocess.run, raise:RuntimeError, func:get_status(repo_path: str) → GitStatus, call:_run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip, call:_run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip, call:GitStatus, call:output.strip().split, call:line.startswith, call:branch_info.split("[ahead ")[1].split, call:int, call:ahead_str.split, call:branch_info.split("[behind ")[1].split, call:behind_str.split, call:len, call:status.untracked.append, call:status.added.append, call:status.deleted.append, call:status.renamed.append, call:status.modified.append, func:create_branch(repo_path: str, name: str, base_branch) → None, call:_run_git_command, call:str(e).lower, func:delete_branch(repo_path: str, name: str, force) → None, call:_run_git_command, func:checkout_branch(repo_path: str, name: str) → None, call:_run_git_command, call:str(e).lower, func:commit_changes(repo_path: str, message: str, author_name: str, author_email: str, files) → str, call:_run_git_command(repo_path, "rev-parse", "HEAD").strip, func:fetch(repo_path: str) → None, call:_run_git_command, func:pull(repo_path: str, branch) → None, call:args.append, call:_run_git_command, func:push(repo_path: str, branch) → None, call:args.extend, call:_run_git_command, func:merge(repo_path: str, source_branch: str, target_branch, message) → str, call:checkout_branch, call:args.extend, call:_run_git_command(repo_path, "rev-parse", "HEAD").strip, func:get_current_branch(repo_path: str) → str, call:_run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip, call:_run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip | dep: subprocess, dataclasses @@ -12,7 +12,7 @@ Provides Git repository interaction utilities for the API layer, abstracting sub - git_history.py | Extracts and structures git commit history, metadata, diffs, and graph visualization data from bare/mirror repositories using subprocess git commands. | exp: class:Commit, class:FileChange, class:CommitDetail, func:_run_git_command(repo_path: str, args: list[str]) → str, call:subprocess.run, raise:RuntimeError, func:get_commit_history(repo_path: str, branch, limit, offset) → dict[str, Any], call:_run_git_command, call:b.strip, call:branches_output.strip().split, call:log_args.append, call:_get_branch_map, call:_get_tag_map, call:log_output.strip().split, call:line.strip, call:line.split, call:len, call:parts[1].split, call:commits.append, call:Commit, call:int, call:branch_map.get, call:tag_map.get, call:count_output.strip, call:_build_graph_data, call:enumerate, call:min, call:commit_dicts.append, call:_commit_to_dict, func:get_commit_detail(repo_path: str, commit_hash: str) → dict[str, Any], call:_run_git_command, call:log_output.strip().split, call:len, call:parts[1].split, call:int, call:_parse_stats, call:_parse_diff, call:_get_branch_map, call:_get_tag_map, call:datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat, call:branch_map.get, call:tag_map.get, call:_file_change_to_dict, raise:ValueError, func:_get_branch_map(repo_path: str) → dict[str, list[str]], call:_run_git_command, call:branch_output.strip().split, call:line.split, call:result[commit_hash].append, func:_get_tag_map(repo_path: str) → dict[str, list[str]], call:_run_git_command, call:tag_output.strip().split, call:line.split, call:result[commit_hash].append, func:_build_graph_data(commits: list[Commit]) → dict[str, Any], call:enumerate, call:hash, call:nodes.append, call:edges.append, func:_parse_stats(stat_output: str) → dict[str, int], call:stat_output.strip().split, call:line.strip, call:line.split, call:part.strip, call:int, call:part.split, func:_parse_diff(diff_output: str) → list[FileChange], call:diff_output.split, call:line.startswith, call:"\n".join, call:files.append, call:FileChange, call:current_diff.append, func:_commit_to_dict(commit: Commit, graph_symbol, graph_depth) → dict[str, Any], call:refs.extend, call:datetime.fromtimestamp(commit.timestamp, tz=timezone.utc).isoformat, func:_file_change_to_dict(file_change: FileChange) → dict[str, Any] | dep: subprocess, dataclasses, datetime, typing - git_url_parser.py | Parses various Git hosting service URLs (browser, SSH, HTTPS) to extract normalized base repository clone URLs with .git suffix. | exp: func:extract_base_repo_url(url: str) → str | None, call:url.startswith, call:url.endswith, call:urlparse, call:parsed.netloc.lower, call:parsed.path.split, call:_extract_github_url, call:_extract_gitlab_url, call:_extract_bitbucket_url, call:_extract_generic_url, func:_extract_github_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_gitlab_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_bitbucket_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, func:_extract_generic_url(url: str, path_parts: list[str]) → str | None, call:len, call:repo_name.endswith, call:urlparse, func:is_valid_clone_url(url: str) → bool, call:url.startswith, call:urlparse, call:path.endswith, func:parse_git_url(url: str) → dict, call:url.strip, call:urlparse, call:parsed.netloc.lower, call:url.startswith, call:url.split, call:len, call:parts[0].replace, call:is_valid_clone_url, call:extract_base_repo_url | dep: urllib.parse ## arch -Utility-layer architecture with functional decomposition into single-responsibility modules (operations, file browsing, history extraction, URL parsing), all relying on subprocess calls to external git binary rather than native git libraries. +Facade pattern with subprocess-based adapters, where each module encapsulates a distinct Git domain (control, files, history, URLs) behind Pythonic function interfaces. ## tags call:, git, run, command, get, url, commit, call:len ## symbols diff --git a/apps/api/tests/.pi-map.index.md b/apps/api/tests/.pi-map.index.md index 77f726f..f7349a3 100644 --- a/apps/api/tests/.pi-map.index.md +++ b/apps/api/tests/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests ## role -Provides shared test infrastructure and fixtures for the FastAPI API application. +Provides shared test infrastructure and fixtures for API integration testing. ## parent index: apps/api/.pi-map.index.md map: apps/api/.pi-map.md diff --git a/apps/api/tests/.pi-map.md b/apps/api/tests/.pi-map.md index 99ddf16..d81871e 100644 --- a/apps/api/tests/.pi-map.md +++ b/apps/api/tests/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/api/tests index: apps/api/tests/.pi-map.index.md ## role -Provides shared test infrastructure and fixtures for the FastAPI API application. +Provides shared test infrastructure and fixtures for API integration testing. ## files -- conftest.py | Provides shared pytest fixtures for FastAPI testing with async SQLite database, authenticated clients, and test data setup. | exp: func:test_client() → Generator[TestClient, None, None], call:create_async_engine, call:engine.begin, call:conn.run_sync, call:asyncio.run, call:init_db, call:async_sessionmaker, call:patch, call:TestClient, call:app.dependency_overrides.pop, call:engine.dispose, func:init_db(), call:engine.begin, call:conn.run_sync, func:override_get_db_session() → AsyncGenerator[AsyncSession, None], call:async_sessionmaker, func:db_session(test_client) → AsyncGenerator[AsyncSession, None], call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:gen.aclose, call:create_async_engine, call:engine.begin, call:conn.run_sync, call:async_sessionmaker, call:engine.dispose, func:authenticated_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_test_user, call:create_session_cookie, call:test_client.cookies.set, func:create_test_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, func:test_project_and_repo(authenticated_client) → tuple[str, str], call:uuid.uuid4, call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, call:asyncio.run, call:get_user_id, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, call:create_project_and_repo, call:str, raise:RuntimeError, func:get_user_id(), call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:create_project_and_repo(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, func:admin_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_admin_user, call:create_session_cookie, call:test_client.cookies.set, func:create_admin_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose | dep: asyncio, os, typing, unittest.mock, pytest, pytest_asyncio, fastapi.testclient, sqlalchemy.ext.asyncio, src.config, src.models.base, src.main, src.auth.dependencies, uuid, src.auth.session, src.models.user, src.models.project, src.models.git_repository, fastapi, sqlalchemy, src.models, src.auth +- conftest.py | Provides shared pytest fixtures for testing a FastAPI application with async SQLite database, authenticated clients, and test data setup. | exp: func:test_client() → Generator[TestClient, None, None], call:create_async_engine, call:engine.begin, call:conn.run_sync, call:asyncio.run, call:init_db, call:async_sessionmaker, call:patch, call:TestClient, call:app.dependency_overrides.pop, call:engine.dispose, func:init_db(), call:engine.begin, call:conn.run_sync, func:override_get_db_session() → AsyncGenerator[AsyncSession, None], call:async_sessionmaker, func:db_session(test_client) → AsyncGenerator[AsyncSession, None], call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:gen.aclose, call:create_async_engine, call:engine.begin, call:conn.run_sync, call:async_sessionmaker, call:engine.dispose, func:authenticated_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_test_user, call:create_session_cookie, call:test_client.cookies.set, func:create_test_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, func:test_project_and_repo(authenticated_client) → tuple[str, str], call:uuid.uuid4, call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, call:asyncio.run, call:get_user_id, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, call:create_project_and_repo, call:str, raise:RuntimeError, func:get_user_id(), call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:create_project_and_repo(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, func:admin_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_admin_user, call:create_session_cookie, call:test_client.cookies.set, func:create_admin_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose | dep: asyncio, os, typing, unittest.mock, pytest, pytest_asyncio, fastapi.testclient, sqlalchemy.ext.asyncio, src.config, src.models.base, src.main, src.auth.dependencies, uuid, src.auth.session, src.models.user.user, src.models.project.project, src.models.project.git_repository, fastapi, sqlalchemy, aiosqlite, src.models, src.auth ## arch -Pytest fixture-based testing architecture with async SQLite database setup, authenticated HTTP client factories, and test data seeding patterns. +Pytest fixture-based testing architecture with async SQLite database lifecycle management, FastAPI TestClient dependency injection, and authenticated client wrappers for role-based testing. ## tags -call:app.dependency, call:create, overrides.get, call:override, fn, call:gen.asend, call:gen.aclose, session +call:app.dependency, call:create, overrides.get, call:override, fn, call:gen.asend, call:gen.aclose, user ## symbols - test_client - init_db diff --git a/apps/api/tests/api/.pi-map.index.md b/apps/api/tests/api/.pi-map.index.md index 9c3be64..42b1e99 100644 --- a/apps/api/tests/api/.pi-map.index.md +++ b/apps/api/tests/api/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests/api ## role -Integration test suite for API authentication and multi-session WebSocket terminal functionality. +Integration tests for multi-session terminal WebSocket routes and authentication requirements on REST API endpoints ## parent index: apps/api/tests/.pi-map.index.md map: apps/api/tests/.pi-map.md diff --git a/apps/api/tests/api/.pi-map.md b/apps/api/tests/api/.pi-map.md index b271756..aeac02b 100644 --- a/apps/api/tests/api/.pi-map.md +++ b/apps/api/tests/api/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/api/tests/api index: apps/api/tests/api/.pi-map.index.md ## role -Integration test suite for API authentication and multi-session WebSocket terminal functionality. +Integration tests for multi-session terminal WebSocket routes and authentication requirements on REST API endpoints ## files - test_terminal_ws_multi.py | Integration tests verifying multi-session terminal WebSocket routes exist and REST API endpoints require authentication | exp: class:TestTerminalWebSocketMultiSession, method:test_specific_session_websocket_route_exists(self, client), call:client.get, method:test_default_session_alias_route_exists(self, client), call:client.get, class:TestTerminalRestApi, method:test_list_sessions_requires_auth(self, client), call:client.get, method:test_create_session_requires_auth(self, client), call:client.post, method:test_close_session_requires_auth(self, client), call:client.delete, method:test_reset_session_requires_auth(self, client), call:client.post, method:test_rename_session_requires_auth(self, client), call:client.post, method:test_legacy_reset_alias_requires_auth(self, client), call:client.post, func:client(), call:TestClient | dep: pytest, fastapi.testclient, src.main ## arch -pytest-based integration testing with FastAPI TestClient, WebSocket endpoint verification, and REST API authentication requirement validation. +Test-driven validation using pytest with WebSocket client testing and HTTP authentication assertion patterns ## tags test, session, requires, auth, call:client.post, terminal, call:client.get, multi ## symbols diff --git a/apps/api/tests/integration/.pi-map.index.md b/apps/api/tests/integration/.pi-map.index.md index a493fbd..220ef5e 100644 --- a/apps/api/tests/integration/.pi-map.index.md +++ b/apps/api/tests/integration/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests/integration ## role -Integration and unit test suite for the FastAPI backend API, covering authentication, CRUD APIs, workspace/git operations, and event/notification systems using real databases and external dependencies. +Integration test suite for the API backend, covering authentication, workspaces, projects, notifications, configuration, and database models with real PostgreSQL and git repositories. ## parent index: apps/api/tests/.pi-map.index.md map: apps/api/tests/.pi-map.md diff --git a/apps/api/tests/integration/.pi-map.md b/apps/api/tests/integration/.pi-map.md index 7385404..839421b 100644 --- a/apps/api/tests/integration/.pi-map.md +++ b/apps/api/tests/integration/.pi-map.md @@ -4,31 +4,31 @@ dir: apps/api/tests/integration index: apps/api/tests/integration/.pi-map.index.md ## role -Integration and unit test suite for the FastAPI backend API, covering authentication, CRUD APIs, workspace/git operations, and event/notification systems using real databases and external dependencies. +Integration test suite for the API backend, covering authentication, workspaces, projects, notifications, configuration, and database models with real PostgreSQL and git repositories. ## files - __init__.py | Empty file with no functionality -- test_auth_api.py | Integration tests for FastAPI authentication endpoints (login, me, logout) using a real database and session cookies. | exp: func:_prepare_auth_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:importlib.reload, func:_insert_test_user(user_id: str) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_login_redirects_to_authentik_authorize_endpoint() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.get, func:test_me_returns_401_without_session_cookie() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.get, func:test_me_returns_user_with_valid_session() → None, call:_prepare_auth_test_db, call:_insert_test_user, call:_load_app, call:Settings, call:create_session_cookie, call:TestClient, call:client.get, call:response.json, func:test_logout_clears_session_cookie() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.post, call:response.headers.get | dep: uuid, asyncio, importlib, fastapi.testclient, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.user, fastapi, src.database, src.api.auth, src.main +- test_auth_api.py | Integration tests for authentication API endpoints using a real PostgreSQL database | exp: func:_postgres_available() → bool, call:asyncpg.connect, call:conn.close, call:asyncio.run, call:_check, func:_check() → bool, call:asyncpg.connect, call:conn.close, func:_prepare_auth_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:importlib.reload, func:_insert_test_user(user_id: str) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_login_redirects_to_authentik_authorize_endpoint() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.get, func:test_me_returns_401_without_session_cookie() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.get, func:test_me_returns_user_with_valid_session() → None, call:_prepare_auth_test_db, call:_insert_test_user, call:_load_app, call:Settings, call:create_session_cookie, call:TestClient, call:client.get, call:response.json, func:test_logout_clears_session_cookie() → None, call:_prepare_auth_test_db, call:_load_app, call:TestClient, call:client.post, call:response.headers.get | dep: uuid, asyncio, importlib, fastapi.testclient, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.user.user, asyncpg, fastapi - test_auth_services.py | Integration tests for authentication services including cookie options, OIDC login URLs, and session cookie creation/decoding with security validations. | exp: func:test_cookie_options_follow_environment_defaults(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, call:build_cookie_options, func:test_login_redirect_url_contains_required_oidc_params() → None, call:Settings, call:build_login_redirect_url, func:test_create_and_decode_session_cookie_round_trip() → None, call:Settings, call:create_session_cookie, call:decode_session_cookie, func:test_decode_session_rejects_invalid_signature() → None, call:Settings, call:create_session_cookie, call:pytest.raises, call:decode_session_cookie, func:test_decode_session_rejects_expired_cookie(monkeypatch) → None, call:Settings, call:create_session_cookie, call:pytest.raises, call:decode_session_cookie | dep: pytest, src.auth.cookies, src.auth.oidc, src.auth.session, src.config - test_config_profiles_api.py | Integration tests for a FastAPI config profiles REST API covering CRUD operations, profile inheritance, default resolution, git mounts, and validation. | exp: class:TestConfigProfilesAPI, method:test_list_config_profiles_requires_authentication(self, test_client: TestClient) → None, call:test_client.get, method:test_list_config_profiles_returns_user_profiles(self, authenticated_client: TestClient) → None, call:authenticated_client.get, call:response.json, call:isinstance, method:test_create_config_profile_successfully(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_config_profile_duplicate_name(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_create_config_profile_exceeds_size_limit(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_create_config_profile_invalid_file_path(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_create_config_profile_invalid_mount_target(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_get_config_profile_by_id(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json, method:test_get_config_profile_not_found(self, authenticated_client: TestClient) → None, call:authenticated_client.get, call:uuid.uuid4, method:test_update_config_profile_successfully(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, method:test_delete_config_profile_successfully(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.delete, call:authenticated_client.get, method:test_update_profile_includes_successfully(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:base_response.json, call:child_response.json, call:authenticated_client.put, call:response.json, call:print, call:data.get, call:len, method:test_update_profile_includes_cycle_detection(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:a_response.json, call:b_response.json, call:authenticated_client.put, method:test_preview_config_profile_successfully(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:base_response.json, call:child_response.json, call:authenticated_client.put, call:authenticated_client.get, call:response.json, call:len, method:test_resolve_default_profile(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:str, call:uuid.uuid4, call:authenticated_client.get, call:response.json, method:test_resolve_default_profile_no_match(self, authenticated_client: TestClient) → None, call:str, call:uuid.uuid4, call:authenticated_client.get, call:response.json, method:test_create_config_profile_with_git_mounts(self, authenticated_client: TestClient, test_project_and_repo) → None, call:authenticated_client.post, call:response.json, call:len, method:test_update_config_profile_git_mounts(self, authenticated_client: TestClient, test_project_and_repo) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, call:len, method:test_create_config_profile_invalid_git_mount_source_path(self, authenticated_client: TestClient, test_project_and_repo) → None, call:authenticated_client.post, method:test_create_config_profile_invalid_git_mount_target_path_traversal(self, authenticated_client: TestClient, test_project_and_repo) → None, call:authenticated_client.post, method:test_preview_config_profile_with_git_mounts(self, authenticated_client: TestClient, test_project_and_repo) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json, call:len | dep: uuid, pytest, fastapi.testclient, fastapi.testclient.TestClient -- test_events.py | Integration tests for SSE endpoint authentication, connection limits, and lifecycle event publishing/persistence via pub/sub event bus. | exp: func:event_bus() → Generator[InstanceEventBus, None, None], call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:_get_user_id_from_client(client: TestClient) → uuid.UUID | None, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:test_sse_requires_auth(test_client: TestClient) → None, call:test_client.get, func:test_sse_enforces_connection_limit(authenticated_client: TestClient) → None, call:_get_user_id_from_client, call:authenticated_client.get, call:events_module._connection_counts.pop, func:test_sse_event_generator_format() → None, call:getattr, call:any, call:str, func:test_lifecycle_hook_publishes_event_and_persists(authenticated_client: TestClient, db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:_get_user_id_from_client, call:Project, call:uuid.uuid4, call:GitRepository, call:ToolType, call:db_session.add_all, call:db_session.commit, call:ToolInstance, call:db_session.add, call:received.append, call:event_bus.subscribe, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_lifecycle_event_persists_audit_row(authenticated_client: TestClient, db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:_get_user_id_from_client, call:Project, call:uuid.uuid4, call:GitRepository, call:ToolType, call:db_session.add_all, call:db_session.commit, call:ToolInstance, call:db_session.add, call:publish_lifecycle_event, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalars().all, call:len, func:test_event_bus_pubsub(event_bus: InstanceEventBus) → None, call:received.append, call:event_bus.subscribe, call:str, call:uuid.uuid4, call:asyncio.run, call:event_bus.publish, call:len, func:handler(payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, collections.abc, typing, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.api, src.auth.session, src.config, src.models.git_repository, src.models.instance_event, src.models.project, src.models.tool_instance, src.models.tool_type, src.services.event_bus, src.api.events, src.services.lifecycle_hooks, fastapi +- test_events.py | Integration tests for SSE endpoint authentication, connection limits, event bus pub/sub, and lifecycle event persistence to database | exp: func:event_bus() → Generator[InstanceEventBus, None, None], call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:_get_user_id_from_client(client: TestClient) → uuid.UUID | None, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:test_sse_requires_auth(test_client: TestClient) → None, call:test_client.get, func:test_sse_enforces_connection_limit(authenticated_client: TestClient) → None, call:_get_user_id_from_client, call:authenticated_client.get, call:events_module._connection_counts.pop, func:test_sse_event_generator_format() → None, call:getattr, call:any, call:str, func:test_lifecycle_hook_publishes_event_and_persists(authenticated_client: TestClient, db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:_get_user_id_from_client, call:Project, call:uuid.uuid4, call:GitRepository, call:ToolType, call:db_session.add_all, call:db_session.commit, call:ToolInstance, call:db_session.add, call:received.append, call:event_bus.subscribe, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_lifecycle_event_persists_audit_row(authenticated_client: TestClient, db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:_get_user_id_from_client, call:Project, call:uuid.uuid4, call:GitRepository, call:ToolType, call:db_session.add_all, call:db_session.commit, call:ToolInstance, call:db_session.add, call:publish_lifecycle_event, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalars().all, call:len, func:test_event_bus_pubsub(event_bus: InstanceEventBus) → None, call:received.append, call:event_bus.subscribe, call:str, call:uuid.uuid4, call:asyncio.run, call:event_bus.publish, call:len, func:handler(payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, collections.abc, typing, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.api.system, src.auth.session, src.config, src.models.project.git_repository, src.models.system.instance_event, src.models.project.project, src.models.tool.tool_instance, src.models.tool.tool_type, src.services.instance.event_bus, src.api.system.events, src.services.instance.lifecycle_hooks, fastapi - test_git_control.py | Unit tests for git utility functions including repository status, branch operations, and commit handling | exp: class:TestGitStatus, method:test_clean_repo(self, temp_repo), call:get_status, call:isinstance, call:len, method:test_modified_file(self, temp_repo), call:open, call:os.path.join, call:f.write, call:get_status, method:test_untracked_file(self, temp_repo), call:open, call:os.path.join, call:f.write, call:get_status, class:TestBranchOperations, method:test_create_branch(self, temp_repo), call:get_current_branch, call:create_branch, call:get_status, method:test_checkout_branch(self, temp_repo), call:get_current_branch, call:create_branch, call:checkout_branch, method:test_delete_branch(self, temp_repo), call:get_current_branch, call:create_branch, call:delete_branch, method:test_get_current_branch(self, temp_repo), call:get_current_branch, class:TestCommit, method:test_commit_changes(self, temp_repo), call:open, call:os.path.join, call:f.write, call:commit_changes, call:get_status, method:test_commit_all_changes(self, temp_repo), call:open, call:os.path.join, call:f.write, call:commit_changes, call:get_status, call:len, func:temp_repo(), call:tempfile.TemporaryDirectory, call:os.system, call:open, call:os.path.join, call:f.write, func:test_get_current_branch_handles_unborn_main() → None, call:tempfile.TemporaryDirectory, call:os.system, call:get_current_branch, func:test_create_branch_on_bare_repo_with_no_commits() → None, call:tempfile.TemporaryDirectory, call:os.system, call:create_branch, call:get_current_branch, func:test_checkout_branch_on_bare_repo_with_no_commits() → None, call:tempfile.TemporaryDirectory, call:os.system, call:checkout_branch, call:get_current_branch | dep: os, tempfile, pytest, src.utils.git_control -- test_models.py | Integration tests for SQLAlchemy model definitions, verifying table registration, column schemas, relationships, and database operations | exp: func:test_base_metadata_collects_declared_tables() → None, call:isinstance, func:test_shared_mixins_define_expected_columns() → None, func:test_expected_tables_are_registered() → None, call:set, func:test_user_table_has_required_columns() → None, call:set, call:columns.keys, func:test_project_relationships_point_to_owner_and_default_ssh_key() → None, call:next, call:iter, func:test_repository_and_user_config_relationships_are_registered() → None, call:next, call:iter, func:test_async_session_can_insert_and_load_user(db_session: AsyncSession) → None, call:User, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:db_session.get | dep: pytest, sqlalchemy.ext.asyncio, src.models, src.models.base, src.models.git_repository, src.models.project, src.models.ssh_key, src.models.user, src.models.user_config, src.models (Base, mixins, GitRepository, Project, SSHKey, User, UserConfig) -- test_notifications_api.py | Integration tests for a notifications REST API covering authentication, CRUD operations, pagination, and user-scoped access control. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:_mint_cookie_for_user(test_client: TestClient, user_id: uuid.UUID) → None, call:Settings, call:create_session_cookie, call:str, call:test_client.cookies.set, func:test_list_requires_auth(test_client: TestClient) → None, call:test_client.get, func:test_list_returns_only_own_notifications(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_notifications, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:create_notifications() → None, call:notification_service.create_notification, func:test_list_pagination(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:create_many, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:create_many() → None, call:range, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, func:test_unread_count_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:asyncio.run, call:create_unread, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, func:create_unread() → None, call:range, call:notification_service.create_notification, func:test_mark_read_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.patch, call:response.json, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mark_read_404_for_other_user(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.patch, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mark_all_read_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:asyncio.run, call:create_unread, call:_mint_cookie_for_user, call:authenticated_client.post, call:response.json, func:create_unread() → None, call:range, call:notification_service.create_notification, func:test_dismiss_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.delete, call:authenticated_client.get, call:response.json, call:len, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_dismiss_404_for_other_user(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.delete, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mute_categories_filter_in_list(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:UserConfig, call:db_session.add, call:db_session.commit, call:notification_service.create_notification, call:asyncio.run, call:setup, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:setup() → None, call:UserConfig, call:db_session.add, call:db_session.commit, call:notification_service.create_notification | dep: uuid, datetime, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models.user, src.models.user_config, src.services.notification_service, src.auth.session, src.config, asyncio, fastapi, sqlalchemy -- test_notifications_lifecycle.py | Integration tests verifying that tool instance lifecycle events and health monitor checks correctly create (or skip) notifications with proper ownership, severity, and error resilience. | exp: func:event_bus() → Generator[InstanceEventBus, None, None], call:InstanceEventBus, call:bus._reset_for_testing, func:test_instance(db_session: AsyncSession) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:Project, call:GitRepository, call:ToolType, call:db_session.add_all, call:ToolInstance, func:test_lifecycle_started_intermediate_skips_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:received.append, call:event_bus.subscribe, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_lifecycle_running_creates_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, call:len, func:test_health_monitor_error_creates_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:HealthMonitor, call:received.append, call:event_bus.subscribe, call:patch, call:monitor._check_instance, call:len, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_notification_failure_does_not_block_event_pipeline(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:received.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(Notification).where, call:result.scalar_one_or_none, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_notification_ownership_matches_instance_owner(db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:Project, call:GitRepository, call:ToolType, call:db_session.add_all, call:ToolInstance, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_lifecycle_error_creates_error_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_health_monitor_unhealthy_creates_warning_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:HealthMonitor, call:HealthSnapshot, call:patch, call:monitor._check_instance, call:db_session.execute, call:select(Notification).where, call:result.scalar_one | dep: uuid, collections.abc, unittest.mock, pytest, pytest_asyncio, sqlalchemy, sqlalchemy.ext.asyncio, src.models.git_repository, src.models.notification, src.models.project, src.models.tool_instance, src.models.tool_type, src.models.user, src.services.event_bus, src.services.health_monitor, src.services.lifecycle_hooks -- test_projects_api.py | Integration tests for a FastAPI projects API endpoint covering authentication, CRUD operations, and ownership-based access control. | exp: func:_prepare_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:hasattr, call:asyncio.run, call:database_module.engine.dispose, call:importlib.reload, func:_mint_token(user_id: str) → str, call:Settings, call:create_session_cookie, call:datetime.now, call:timedelta, func:_insert_user(user_id: str, email) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_insert_project(project_id: str, owner_id: str, name) → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:Project, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:Project, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_create_project_requires_authentication() → None, call:_prepare_test_db, call:_load_app, call:TestClient, call:client.post, func:test_create_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, call:response.json, func:test_list_projects_returns_only_owned_projects() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, call:len, func:test_update_project_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch, func:test_update_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch, call:response.json, func:test_delete_project_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, func:test_delete_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, func:test_set_default_ssh_key_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch | dep: uuid, datetime, asyncio, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.project, src.models.user, importlib, fastapi, src.database, src.api.auth, src.api.projects, src.main +- test_models.py | Integration tests verifying SQLAlchemy model definitions, table registration, column constraints, relationships, and async database operations. | exp: func:test_base_metadata_collects_declared_tables() → None, call:isinstance, func:test_shared_mixins_define_expected_columns() → None, func:test_expected_tables_are_registered() → None, call:set, func:test_user_table_has_required_columns() → None, call:set, call:columns.keys, func:test_project_relationships_point_to_owner_and_default_ssh_key() → None, call:next, call:iter, func:test_repository_and_user_config_relationships_are_registered() → None, call:next, call:iter, func:test_async_session_can_insert_and_load_user(db_session: AsyncSession) → None, call:User, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:db_session.get | dep: pytest, sqlalchemy.ext.asyncio, src.models, src.models.base, src.models.project.git_repository, src.models.project.project, src.models.user.ssh_key, src.models.user.user, src.models.user.user_config, src.models (Base, mixins, User, Project, GitRepository, SSHKey, UserConfig) +- test_notifications_api.py | Integration tests for a notifications REST API covering authentication, CRUD operations, pagination, and user isolation. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:_mint_cookie_for_user(test_client: TestClient, user_id: uuid.UUID) → None, call:Settings, call:create_session_cookie, call:str, call:test_client.cookies.set, func:test_list_requires_auth(test_client: TestClient) → None, call:test_client.get, func:test_list_returns_only_own_notifications(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_notifications, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:create_notifications() → None, call:notification_service.create_notification, func:test_list_pagination(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:create_many, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:create_many() → None, call:range, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, func:test_unread_count_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:asyncio.run, call:create_unread, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, func:create_unread() → None, call:range, call:notification_service.create_notification, func:test_mark_read_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.patch, call:response.json, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mark_read_404_for_other_user(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.patch, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mark_all_read_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:asyncio.run, call:create_unread, call:_mint_cookie_for_user, call:authenticated_client.post, call:response.json, func:create_unread() → None, call:range, call:notification_service.create_notification, func:test_dismiss_endpoint(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.delete, call:authenticated_client.get, call:response.json, call:len, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_dismiss_404_for_other_user(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:asyncio.run, call:create_and_get, call:_mint_cookie_for_user, call:authenticated_client.delete, func:create_and_get() → uuid.UUID, call:notification_service.create_notification, func:test_mute_categories_filter_in_list(authenticated_client: TestClient, db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:UserConfig, call:db_session.add, call:db_session.commit, call:notification_service.create_notification, call:asyncio.run, call:setup, call:_mint_cookie_for_user, call:authenticated_client.get, call:response.json, call:len, func:setup() → None, call:UserConfig, call:db_session.add, call:db_session.commit, call:notification_service.create_notification | dep: uuid, datetime, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models.user.user, src.models.user.user_config, src.services.shared.notification_service, src.auth.session, src.config, asyncio, fastapi, sqlalchemy +- test_notifications_lifecycle.py | Integration tests verifying that instance lifecycle events and health monitor state changes correctly create (or skip) notifications with proper ownership, severity, and error handling. | exp: func:event_bus() → Generator[InstanceEventBus, None, None], call:InstanceEventBus, call:bus._reset_for_testing, func:test_instance(db_session: AsyncSession) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:Project, call:GitRepository, call:ToolType, call:db_session.add_all, call:ToolInstance, func:test_lifecycle_started_intermediate_skips_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:received.append, call:event_bus.subscribe, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_lifecycle_running_creates_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, call:len, func:test_health_monitor_error_creates_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:HealthMonitor, call:HealthSnapshot, call:received.append, call:event_bus.subscribe, call:patch, call:monitor._check_instance, call:len, call:db_session.execute, call:select(Notification).where, call:list, call:result.scalars().all, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_notification_failure_does_not_block_event_pipeline(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:received.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:publish_lifecycle_event, call:len, call:db_session.execute, call:select(Notification).where, call:result.scalar_one_or_none, func:subscriber(payload: InstanceEventPayload) → None, call:received.append, func:test_notification_ownership_matches_instance_owner(db_session: AsyncSession, event_bus: InstanceEventBus) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:Project, call:GitRepository, call:ToolType, call:db_session.add_all, call:ToolInstance, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_lifecycle_error_creates_error_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:publish_lifecycle_event, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_health_monitor_unhealthy_creates_warning_notification(db_session: AsyncSession, event_bus: InstanceEventBus, test_instance: ToolInstance) → None, call:HealthMonitor, call:HealthSnapshot, call:patch, call:monitor._check_instance, call:db_session.execute, call:select(Notification).where, call:result.scalar_one | dep: uuid, collections.abc, unittest.mock, pytest, pytest_asyncio, sqlalchemy, sqlalchemy.ext.asyncio, src.models.project.git_repository, src.models.system.notification, src.models.project.project, src.models.tool.tool_instance, src.models.tool.tool_type, src.models.user.user, src.services.instance.event_bus, src.services.instance.health_monitor, src.services.instance.lifecycle_hooks +- test_projects_api.py | Integration tests for a FastAPI projects API endpoint, verifying authentication, CRUD operations, and ownership-based authorization against a real PostgreSQL database. | exp: func:_postgres_available() → bool, call:asyncpg.connect, call:conn.close, call:asyncio.run, call:_check, func:_check() → bool, call:asyncpg.connect, call:conn.close, func:_prepare_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:hasattr, call:asyncio.run, call:database_module.engine.dispose, call:importlib.reload, func:_mint_token(user_id: str) → str, call:Settings, call:create_session_cookie, func:_insert_user(user_id: str, email) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_insert_project(project_id: str, owner_id: str, name) → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:Project, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:Project, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_create_project_requires_authentication() → None, call:_prepare_test_db, call:_load_app, call:TestClient, call:client.post, func:test_create_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, call:response.json, func:test_list_projects_returns_only_owned_projects() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, call:len, func:test_update_project_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch, func:test_update_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch, call:response.json, func:test_delete_project_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, func:test_delete_project_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, func:test_set_default_ssh_key_requires_ownership() → None, call:_prepare_test_db, call:_insert_user, call:_insert_project, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.patch | dep: uuid, datetime, asyncio, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.project.project, src.models.user.user, asyncpg, importlib, fastapi, src.database, src.api.user.auth, src.api.project.projects, src.main - test_seed.py | Tests deterministic seed user generation and database seeding functionality for development environments. | exp: func:test_build_seed_user_returns_deterministic_payload() → None, call:build_seed_user, func:test_seed_database_creates_development_user(db_session: AsyncSession) → None, call:seed_database, call:db_session.scalar, call:select(User).where | dep: pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.models.user, src.scripts.seed -- test_ssh_keys_api.py | Integration tests for SSH keys API endpoints verifying authentication requirements | exp: func:async_client(), call:AsyncClient, func:test_create_ssh_key_requires_authentication(async_client: AsyncClient) → None, call:async_client.post, func:test_list_ssh_keys_requires_authentication(async_client: AsyncClient) → None, call:async_client.get | dep: pytest, httpx, src.main -- test_tool_types_api.py | Integration tests for a FastAPI tool types REST API endpoint covering CRUD operations, authentication, and validation rules | exp: func:_prepare_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:hasattr, call:asyncio.run, call:database_module.engine.dispose, call:importlib.reload, func:_mint_token(user_id: str) → str, call:Settings, call:create_session_cookie, call:datetime.now, call:timedelta, func:_insert_user(user_id: str, email) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_insert_tool_type(tool_type_id: str, name: str, display_name: str, compose_template: str, created_by_id) → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:ToolType, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:ToolType, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_list_tool_types_requires_authentication() → None, call:_prepare_test_db, call:_load_app, call:TestClient, call:client.get, func:test_list_tool_types_returns_all_types() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, call:len, call:next, func:test_get_tool_type_by_id() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, func:test_get_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, func:test_create_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, call:response.json, func:test_create_tool_type_duplicate_name() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_invalid_yaml() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_missing_services() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_missing_required_variable() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_update_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.put, call:response.json, func:test_update_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.put, func:test_delete_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, call:client.get, func:test_delete_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete | dep: uuid, datetime, asyncio, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.tool_type, src.models.user, importlib, fastapi, src.database, src.api.auth, src.api.tool_types, src.main -- test_tool_types_api_extended.py | Integration tests for a FastAPI tool types API endpoint covering CRUD operations with extended fields including dockerfile templates, compose templates, readiness probes, startup commands, and validation logic. | exp: class:TestToolTypesAPIExtended, method:test_create_tool_type_with_dockerfile(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_with_readiness_probe(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_invalid_definition_type(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_create_tool_type_dockerfile_without_template(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_update_tool_type_with_new_fields(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, method:test_validate_tool_type_compose(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_validate_tool_type_invalid_compose(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_validate_tool_type_dockerfile(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_get_tool_type_returns_new_fields(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json, method:test_create_tool_type_without_port_fails(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, call:str, method:test_create_tool_type_with_port_mismatch_fails(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_with_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_update_tool_type_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, method:test_get_tool_type_returns_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json, call:str | dep: pytest, fastapi.testclient, fastapi.testclient.TestClient -- test_users_api.py | Integration tests for user profile API endpoints including get, update, and avatar upload with authentication and validation | exp: func:_prepare_users_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:importlib.reload, func:_insert_test_user(user_id: str) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_create_auth_cookie(user_id: str) → str, call:Settings, call:create_session_cookie, call:datetime.now, call:timedelta, func:test_get_profile_returns_401_without_cookie() → None, call:_prepare_users_test_db, call:_load_app, call:TestClient, call:client.get, func:test_get_profile_returns_user_data() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.get, call:response.json, func:test_update_profile_changes_name_and_email() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, call:response.json, func:test_update_profile_rejects_empty_name() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, func:test_update_profile_rejects_invalid_email() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, func:test_upload_avatar_updates_avatar_url() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO, call:response.json, call:data["avatar_url"].startswith, func:test_upload_avatar_rejects_invalid_file_type() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO, func:test_upload_avatar_rejects_oversized_file() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO | dep: uuid, datetime, asyncio, io, fastapi.testclient, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.user, importlib, fastapi, src.database, src.api.users, src.main -- test_workspace_files.py | Integration tests for workspace file endpoints (list, read, write) with path traversal security checks | exp: class:TestListWorkspaceFiles, method:test_list_files(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:authenticated_client.get, call:response.json, method:test_list_files_path_escapes_workspace(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.get, class:TestGetFileContent, method:test_get_content(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.get, call:response.json, method:test_get_missing_file(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.get, class:TestWriteFileContent, method:test_write_file(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.post, call:os.path.exists, call:os.path.join, method:test_write_file_missing_path(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.post, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_repo_with_workspace(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:db_session.commit, call:db_session.refresh | dep: asyncio, os, tempfile, uuid, unittest.mock, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.services.shared.workspace_manager, src.auth.session, src.config, fastapi.testclient.TestClient, sqlalchemy.ext.asyncio.AsyncSession -- test_workspace_git.py | Integration tests for workspace Git endpoints (status, commit, history, checkout) using real git repositories and FastAPI test client. | exp: class:TestGitStatus, method:test_status_clean(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.get, call:response.json, method:test_status_modified(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.get, call:response.json, class:TestGitCommit, method:test_commit(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.post, call:response.json, method:test_commit_missing_message(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.post, class:TestGitHistory, method:test_history(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.get, call:response.json, call:len, class:TestGitCheckout, method:test_checkout(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:_run_git, call:authenticated_client.post, call:response.json, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_repo_with_git_workspace(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:_run_git, call:open, call:os.path.join, call:f.write, call:Workspace, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:_run_git, call:open, call:os.path.join, call:f.write, call:Workspace, call:db_session.commit, call:db_session.refresh | dep: asyncio, os, subprocess, tempfile, uuid, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.auth.session, src.config, fastapi.testclient.TestClient, sqlalchemy.ext.asyncio.AsyncSession -- test_workspace_instances.py | Integration tests for workspace instance REST API endpoints (listing and creating tool instances within workspaces) | exp: class:TestListWorkspaceInstances, method:test_list_empty(self, authenticated_client: TestClient, test_workspace_with_tool_type), call:authenticated_client.get, call:response.json, method:test_list_instances(self, authenticated_client: TestClient, db_session: AsyncSession, test_workspace_with_tool_type), call:ToolInstance, call:db_session.add, call:db_session.commit, call:asyncio.run, call:_create_instance, call:authenticated_client.get, call:response.json, call:len, class:TestCreateWorkspaceInstance, method:test_create_instance(self, authenticated_client: TestClient, test_workspace_with_tool_type), call:ToolInstance, call:uuid.uuid4, call:datetime.now, call:patch, call:authenticated_client.post, call:str, call:response.json, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_workspace_with_tool_type(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:ToolType, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:ToolType, call:db_session.commit, call:db_session.refresh | dep: asyncio, tempfile, uuid, datetime, unittest.mock, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.auth.session, src.config, src.api.workspace.workspace_instances +- test_ssh_keys_api.py | Integration tests verifying SSH key API endpoints require authentication | exp: func:test_create_ssh_key_requires_authentication(test_client: TestClient) → None, call:test_client.post, func:test_list_ssh_keys_requires_authentication(test_client: TestClient) → None, call:test_client.get | dep: pytest, fastapi.testclient +- test_tool_types_api.py | Integration tests for a FastAPI tool types REST API endpoint using a real PostgreSQL database. | exp: func:_postgres_available() → bool, call:asyncpg.connect, call:conn.close, call:asyncio.run, call:_check, func:_check() → bool, call:asyncpg.connect, call:conn.close, func:_prepare_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:hasattr, call:asyncio.run, call:database_module.engine.dispose, call:importlib.reload, func:_mint_token(user_id: str) → str, call:Settings, call:create_session_cookie, call:datetime.now, call:timedelta, func:_insert_user(user_id: str, email) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_insert_tool_type(tool_type_id: str, name: str, display_name: str, compose_template: str, created_by_id) → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:ToolType, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:async_sessionmaker, call:session_factory, call:ToolType, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:test_list_tool_types_requires_authentication() → None, call:_prepare_test_db, call:_load_app, call:TestClient, call:client.get, func:test_list_tool_types_returns_all_types() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, call:len, call:next, func:test_get_tool_type_by_id() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, call:response.json, func:test_get_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.get, func:test_create_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, call:response.json, func:test_create_tool_type_duplicate_name() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_invalid_yaml() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_missing_services() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_create_tool_type_missing_required_variable() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.post, func:test_update_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.put, call:response.json, func:test_update_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.put, func:test_delete_tool_type_successfully() → None, call:_prepare_test_db, call:_insert_user, call:_insert_tool_type, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete, call:client.get, func:test_delete_tool_type_not_found() → None, call:_prepare_test_db, call:_insert_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_mint_token, call:client.delete | dep: uuid, datetime, asyncio, pytest, fastapi.testclient, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.tool.tool_type, src.models.user.user, asyncpg, importlib, fastapi +- test_tool_types_api_extended.py | Integration tests for a FastAPI tool types API endpoint covering CRUD operations with extended fields like dockerfile templates, readiness probes, startup commands, and validation. | exp: class:TestToolTypesAPIExtended, method:test_create_tool_type_with_dockerfile(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_with_readiness_probe(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_invalid_definition_type(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_create_tool_type_dockerfile_without_template(self, authenticated_client: TestClient) → None, call:authenticated_client.post, method:test_update_tool_type_with_new_fields(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, method:test_validate_tool_type_compose(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_validate_tool_type_invalid_compose(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_validate_tool_type_dockerfile(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_get_tool_type_returns_new_fields(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json, method:test_create_tool_type_without_port_fails(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, call:str, method:test_create_tool_type_with_port_mismatch_fails(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_create_tool_type_with_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:response.json, method:test_update_tool_type_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.put, call:response.json, method:test_get_tool_type_returns_startup_command(self, authenticated_client: TestClient) → None, call:authenticated_client.post, call:create_response.json, call:authenticated_client.get, call:response.json | dep: pytest, fastapi.testclient, fastapi.testclient.TestClient +- test_users_api.py | Integration tests for user profile API endpoints using a real PostgreSQL database | exp: func:_postgres_available() → bool, call:asyncpg.connect, call:conn.close, call:asyncio.run, call:_check, func:_check() → bool, call:asyncpg.connect, call:conn.close, func:_prepare_users_test_db() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:connection.execute, call:text, call:engine.dispose, func:_load_app(), call:importlib.reload, func:_insert_test_user(user_id: str) → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, call:asyncio.run, call:_run, func:_run() → None, call:create_async_engine, call:build_database_url, call:engine.begin, call:connection.run_sync, call:async_sessionmaker, call:session_factory, call:User, call:uuid.UUID, call:session.merge, call:session.commit, call:engine.dispose, func:_create_auth_cookie(user_id: str) → str, call:Settings, call:create_session_cookie, func:test_get_profile_returns_401_without_cookie() → None, call:_prepare_users_test_db, call:_load_app, call:TestClient, call:client.get, func:test_get_profile_returns_user_data() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.get, call:response.json, func:test_update_profile_changes_name_and_email() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, call:response.json, func:test_update_profile_rejects_empty_name() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, func:test_update_profile_rejects_invalid_email() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.put, func:test_upload_avatar_updates_avatar_url() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO, call:response.json, call:data["avatar_url"].startswith, func:test_upload_avatar_rejects_invalid_file_type() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO, func:test_upload_avatar_rejects_oversized_file() → None, call:_prepare_users_test_db, call:_insert_test_user, call:_load_app, call:TestClient, call:client.cookies.set, call:_create_auth_cookie, call:client.post, call:io.BytesIO | dep: uuid, datetime, asyncio, io, fastapi.testclient, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.models, src.models.user.user, asyncpg, importlib, fastapi, src.database, src.api.user.users, src.main +- test_workspace_files.py | Integration tests for FastAPI endpoints that manage workspace file operations (list, read, write) | exp: class:TestListWorkspaceFiles, method:test_list_files(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:authenticated_client.get, call:response.json, method:test_list_files_path_escapes_workspace(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.get, class:TestGetFileContent, method:test_get_content(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.get, call:response.json, method:test_get_missing_file(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.get, class:TestWriteFileContent, method:test_write_file(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.post, call:os.path.exists, call:os.path.join, method:test_write_file_missing_path(self, authenticated_client: TestClient, test_repo_with_workspace: Workspace), call:authenticated_client.post, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_repo_with_workspace(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:db_session.commit, call:db_session.refresh | dep: asyncio, os, tempfile, uuid, unittest.mock, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.services.shared.workspace_manager, src.auth.session, src.config, fastapi, sqlalchemy +- test_workspace_git.py | Integration tests for FastAPI workspace git endpoints (status, commit, history, checkout) using real git repositories. | exp: class:TestGitStatus, method:test_status_clean(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.get, call:response.json, method:test_status_modified(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.get, call:response.json, class:TestGitCommit, method:test_commit(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:authenticated_client.post, call:response.json, method:test_commit_missing_message(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.post, class:TestGitHistory, method:test_history(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:authenticated_client.get, call:response.json, call:len, class:TestGitCheckout, method:test_checkout(self, authenticated_client: TestClient, test_repo_with_git_workspace: Workspace), call:_run_git, call:authenticated_client.post, call:response.json, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_repo_with_git_workspace(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:_run_git, call:open, call:os.path.join, call:f.write, call:Workspace, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:_run_git, call:open, call:os.path.join, call:f.write, call:Workspace, call:db_session.commit, call:db_session.refresh | dep: asyncio, os, subprocess, tempfile, uuid, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.auth.session, src.config, fastapi, sqlalchemy +- test_workspace_instances.py | Integration tests for FastAPI workspace instance endpoints (list and create) using an authenticated test client and mocked database fixtures. | exp: class:TestListWorkspaceInstances, method:test_list_empty(self, authenticated_client: TestClient, test_workspace_with_tool_type), call:authenticated_client.get, call:response.json, method:test_list_instances(self, authenticated_client: TestClient, db_session: AsyncSession, test_workspace_with_tool_type), call:ToolInstance, call:db_session.add, call:db_session.commit, call:asyncio.run, call:_create_instance, call:authenticated_client.get, call:response.json, call:len, class:TestCreateWorkspaceInstance, method:test_create_instance(self, authenticated_client: TestClient, test_workspace_with_tool_type), call:ToolInstance, call:uuid.uuid4, call:datetime.now, call:patch, call:authenticated_client.post, call:str, call:response.json, func:_get_user_id(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_workspace_with_tool_type(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:ToolType, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:tempfile.mkdtemp, call:Workspace, call:ToolType, call:db_session.commit, call:db_session.refresh | dep: asyncio, tempfile, uuid, datetime, unittest.mock, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.auth.session, src.config, src.api.workspace.workspace_instances - test_workspaces_api.py | Integration tests for workspace API endpoints including list, create, delete, and sync operations with repository/project scoping | exp: class:TestListWorkspaces, method:test_list_empty(self, authenticated_client: TestClient, test_repo: GitRepository), call:authenticated_client.get, call:response.json, method:test_list_with_workspaces(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:asyncio.run, call:_commit, call:authenticated_client.get, call:response.json, call:len, class:TestCreateWorkspace, method:test_create_success(self, authenticated_client: TestClient, test_repo: GitRepository), call:Workspace, call:uuid.uuid4, call:patch.object, call:authenticated_client.post, call:response.json, call:mock_create.assert_called_once, method:test_create_missing_name(self, authenticated_client: TestClient, test_repo: GitRepository), call:authenticated_client.post, call:response.json, method:test_create_duplicate_name(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:asyncio.run, call:_commit, call:patch.object, call:Exception, call:authenticated_client.post, class:TestDeleteWorkspace, method:test_delete_without_instances(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_commit_refresh, call:patch.object, call:authenticated_client.delete, call:response.json, method:test_delete_with_instances_force(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_commit_refresh, call:patch.object, call:authenticated_client.delete, class:TestSyncWorkspace, method:test_sync_success(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_commit_refresh, call:patch.object, call:MagicMock, call:authenticated_client.post, call:response.json, method:test_sync_branch_deleted(self, authenticated_client: TestClient, db_session: AsyncSession, test_repo: GitRepository), call:Workspace, call:db_session.add, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_commit_refresh, call:patch.object, call:MagicMock, call:authenticated_client.post, call:response.json, func:_get_user_id_from_client(client: TestClient) → uuid.UUID, call:Settings, call:client.cookies.get, call:decode_session_cookie, call:uuid.UUID, raise:RuntimeError, func:test_repo(db_session: AsyncSession, authenticated_client: TestClient), call:_get_user_id_from_client, call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:db_session.commit, call:db_session.refresh, call:asyncio.run, call:_create, func:_create(), call:Project, call:db_session.add, call:db_session.flush, call:GitRepository, call:db_session.commit, call:db_session.refresh | dep: asyncio, uuid, unittest.mock, pytest, fastapi.testclient, sqlalchemy.ext.asyncio, src.models, src.services.shared.workspace_manager, src.auth.session, src.config, fastapi, sqlalchemy ## arch -Test-driven pyramid with integration tests as primary layer using FastAPI TestClient, real SQLAlchemy databases, actual git repositories, and pub/sub event bus; unit tests limited to isolated git utilities; shared fixtures likely in conftest.py for dependency injection, database setup/teardown, and authenticated client sessions. +Pytest-based integration testing using real external dependencies (PostgreSQL, git repos), FastAPI TestClient with authenticated fixtures, mocked database fixtures for isolation, and security validation patterns (cookie/ OIDC/ SSE auth). ## tags -test, call:, call:db, call:authenticated, user, call:response.json, create, call:create +test, call:, call:db, call:authenticated, user, create, call:response.json, call:create ## symbols - TestConfigProfilesAPI - TestGitStatus diff --git a/apps/api/tests/services/.pi-map.index.md b/apps/api/tests/services/.pi-map.index.md index ab0912e..34d64e8 100644 --- a/apps/api/tests/services/.pi-map.index.md +++ b/apps/api/tests/services/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests/services ## role -Unit tests for verifying TerminalManager's multi-session terminal lifecycle and resource management capabilities. +Unit tests for TerminalManager's multi-session functionality and session lifecycle management. ## parent index: apps/api/tests/.pi-map.index.md map: apps/api/tests/.pi-map.md diff --git a/apps/api/tests/services/.pi-map.md b/apps/api/tests/services/.pi-map.md index 47e9d08..9d47c20 100644 --- a/apps/api/tests/services/.pi-map.md +++ b/apps/api/tests/services/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/api/tests/services index: apps/api/tests/services/.pi-map.index.md ## role -Unit tests for verifying TerminalManager's multi-session terminal lifecycle and resource management capabilities. +Unit tests for TerminalManager's multi-session functionality and session lifecycle management. ## files -- test_terminal_manager_multi.py | Unit tests for TerminalManager's multi-session support including session creation limits, instance filtering, websocket attachment behavior, default session handling, and idle cleanup. | exp: class:FakeWebSocket, method:__init__(self, name) → None, method:close(self, code, reason) → None, method:send_bytes(self, data: bytes) → None, call:self._sent.append, func:manager() → TerminalManager, call:TerminalManager, call:tm._idle_check_task.done, call:tm._idle_check_task.cancel, func:mock_terminal_session(monkeypatch) → None, call:__import__("time").time, call:monkeypatch.setattr, func:fake_start(self), call:__import__("time").time, func:instance_id() → uuid.UUID, call:uuid.uuid4, func:test_create_session_increases_count(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:len, call:manager.get_sessions_for_instance, call:str, call:manager.create_session, func:test_create_session_enforces_max_5(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:range, call:manager.create_session, call:len, call:manager.get_sessions_for_instance, call:str, call:pytest.raises, func:test_get_sessions_for_instance_filters_by_instance(manager: TerminalManager, mock_terminal_session) → None, call:uuid.uuid4, call:manager.create_session, call:len, call:manager.get_sessions_for_instance, call:str, func:test_close_session_removes_from_dict(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:manager.get_session, call:str, call:patch.object, call:AsyncMock, call:manager.close_session, call:asyncio.sleep, call:mock_mark.assert_called_once_with, func:test_attach_websocket_only_closes_same_session(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:FakeWebSocket, call:session_a.attach_websocket, call:session_b.attach_websocket, call:manager.attach_websocket, func:test_default_session_keyed_separately(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.get_or_create_session, call:manager.create_session, call:manager.get_session, call:str, func:test_idle_cleanup_updates_db_status(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:patch.object, call:AsyncMock, call:manager._cleanup_idle_sessions, call:manager.get_session, call:str, call:mock_mark.assert_called_once_with | dep: asyncio, uuid, unittest.mock, pytest, src.services.terminal_manager, src.services.terminal_session +- test_terminal_manager_multi.py | Unit tests for TerminalManager's multi-session support including session creation limits, instance filtering, WebSocket attachment behavior, default session handling, and idle cleanup. | exp: class:FakeWebSocket, method:__init__(self, name) → None, method:close(self, code, reason) → None, method:send_bytes(self, data: bytes) → None, call:self._sent.append, func:manager() → TerminalManager, call:TerminalManager, call:tm._idle_check_task.done, call:tm._idle_check_task.cancel, func:mock_terminal_session(monkeypatch) → None, call:__import__("time").time, call:monkeypatch.setattr, func:fake_start(self), call:__import__("time").time, func:instance_id() → uuid.UUID, call:uuid.uuid4, func:test_create_session_increases_count(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:len, call:manager.get_sessions_for_instance, call:str, call:manager.create_session, func:test_create_session_enforces_max_5(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:range, call:manager.create_session, call:len, call:manager.get_sessions_for_instance, call:str, call:pytest.raises, func:test_get_sessions_for_instance_filters_by_instance(manager: TerminalManager, mock_terminal_session) → None, call:uuid.uuid4, call:manager.create_session, call:len, call:manager.get_sessions_for_instance, call:str, func:test_close_session_removes_from_dict(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:manager.get_session, call:str, call:patch.object, call:AsyncMock, call:manager.close_session, call:asyncio.sleep, call:mock_mark.assert_called_once_with, func:test_attach_websocket_only_closes_same_session(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:FakeWebSocket, call:session_a.attach_websocket, call:session_b.attach_websocket, call:manager.attach_websocket, func:test_default_session_keyed_separately(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.get_or_create_session, call:manager.create_session, call:manager.get_session, call:str, func:test_idle_cleanup_updates_db_status(manager: TerminalManager, mock_terminal_session, instance_id: uuid.UUID) → None, call:manager.create_session, call:patch.object, call:AsyncMock, call:manager._cleanup_idle_sessions, call:manager.get_session, call:str, call:mock_mark.assert_called_once_with | dep: asyncio, uuid, unittest.mock, pytest, src.services.terminal.terminal_manager, src.services.terminal.terminal_session ## arch -Pytest-based test suite using fixture mocking for async service dependencies and parameterized scenarios for session limit boundary testing. +pytest-based test suite with mocked dependencies, testing session limits, filtering, WebSocket handling, and background cleanup tasks. ## tags session, test, call:manager.get, call:manager.create, instance, call:str, sessions, websocket ## symbols diff --git a/apps/api/tests/system/.pi-map.index.md b/apps/api/tests/system/.pi-map.index.md index 6bebdf7..9525eb9 100644 --- a/apps/api/tests/system/.pi-map.index.md +++ b/apps/api/tests/system/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests/system ## role -System-level integration test suite for the API application. +System-level integration tests for the API application ## parent index: apps/api/tests/.pi-map.index.md map: apps/api/tests/.pi-map.md diff --git a/apps/api/tests/system/.pi-map.md b/apps/api/tests/system/.pi-map.md index 2fb398d..5eb01eb 100644 --- a/apps/api/tests/system/.pi-map.md +++ b/apps/api/tests/system/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/api/tests/system index: apps/api/tests/system/.pi-map.index.md ## role -System-level integration test suite for the API application. +System-level integration tests for the API application ## files - __init__.py | Empty file with no functionality ## arch -Minimal test package structure with placeholder initialization, following Python package conventions for future test module organization. +Standard Python test package structure with empty initializer for module discovery ## tags init, empty, functionality ## symbols diff --git a/apps/api/tests/unit/.pi-map.index.md b/apps/api/tests/unit/.pi-map.index.md index de4a266..e46b1c4 100644 --- a/apps/api/tests/unit/.pi-map.index.md +++ b/apps/api/tests/unit/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/tests/unit ## role -Unit test suite for the API backend, covering configuration, Docker operations, Git services, file handling, health monitoring, notifications, and SSH key management. +Contains comprehensive unit tests for the API application's core services, utilities, and infrastructure components. ## parent index: apps/api/tests/.pi-map.index.md map: apps/api/tests/.pi-map.md @@ -16,11 +16,7 @@ map: apps/api/tests/.pi-map.md - test_docker_service.py - test_event_bus.py - test_file_service.py -- test_git_mount_resolution.py -- test_git_mounts.py - test_git_operations.py -- test_git_repository_clone_preflight.py -- test_git_repository_working_clones.py - test_git_service.py - test_git_url_parser.py - test_health_monitor.py diff --git a/apps/api/tests/unit/.pi-map.md b/apps/api/tests/unit/.pi-map.md index 31db71b..0b89657 100644 --- a/apps/api/tests/unit/.pi-map.md +++ b/apps/api/tests/unit/.pi-map.md @@ -4,37 +4,33 @@ dir: apps/api/tests/unit index: apps/api/tests/unit/.pi-map.index.md ## role -Unit test suite for the API backend, covering configuration, Docker operations, Git services, file handling, health monitoring, notifications, and SSH key management. +Contains comprehensive unit tests for the API application's core services, utilities, and infrastructure components. ## files - __init__.py | Empty file with no functionality -- test_config.py | Unit tests for application configuration settings, database URL construction, and environment-specific behavior | exp: func:test_settings_default_database_url_uses_asyncpg() → None, call:Settings, func:test_build_database_url_uses_explicit_values() → None, call:build_database_url, func:test_settings_prefers_explicit_database_url_env(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_auth_settings_have_secure_defaults() → None, call:Settings, call:settings.resolved_authentik_authorize_url.endswith, call:settings.resolved_authentik_token_url.endswith, call:settings.resolved_authentik_jwks_url.endswith, func:test_cookie_policy_is_strict_in_production(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_cookie_policy_is_relaxed_for_local_dev(monkeypatch) → None, call:monkeypatch.setenv, call:Settings | dep: pytest, src.config, src.database -- test_config_profile_resolver.py | Unit tests for configuration profile resolution, including merge functions, profile inheritance with includes, cycle detection, and git mount normalization. | exp: class:TestMergeFunctions, method:test_merge_env_vars_basic(self) → None, call:_merge_env_vars, method:test_merge_env_vars_tracks_overrides(self) → None, call:_merge_env_vars, method:test_merge_runtime_hints_basic(self) → None, call:_merge_runtime_hints, method:test_merge_files_basic(self) → None, call:_merge_files, method:test_merge_mounts_basic(self) → None, call:_merge_mounts, method:test_merge_mounts_file_override(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_mounts_mode_conflict(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_git_mounts_basic(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_concatenate_same_repo_branch(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_dedup_same_mapping(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_repos(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_branches(self) → None, call:_merge_git_mounts, call:len, call:m.get, class:TestResolveProfile, class:TestApplyResolvedProfile, method:test_mounts_individual_files_not_directory(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, method:test_file_mount_preserves_sibling_files(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0]["source"].endswith, method:test_empty_mount_produces_no_volumes(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, method:test_home_expansion_in_file_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, class:TestCheckIncludeCycle | dep: uuid, pytest, sqlalchemy.ext.asyncio, src.models.config_profile, src.services.config_profile_resolver -- test_docker_build.py | Unit tests for a Docker image build service that validates successful builds, failures, command structure, file writing, context handling, path traversal prevention, timeouts, and exceptions. | exp: class:TestBuildImage | dep: subprocess, tempfile, pathlib, unittest.mock, pytest, src.services.docker_build -- test_docker_service.py | Unit tests for Docker service utility functions including container ID/name retrieval and volume sorting by mount specificity. | exp: class:TestGetContainerId, class:TestGetContainerName, class:TestSortVolumesBySpecificity, method:test_parent_before_child(self) → None, call:sort_volumes_by_specificity, method:test_stable_sort_for_equal_depth(self) → None, call:sort_volumes_by_specificity, method:test_with_type_suffix(self) → None, call:sort_volumes_by_specificity, method:test_empty_list(self) → None, call:sort_volumes_by_specificity, method:test_single_volume(self) → None, call:sort_volumes_by_specificity, method:test_duplicate_target_warning(self, caplog) → None, call:caplog.at_level, call:sort_volumes_by_specificity | dep: unittest.mock, logging, src.services.docker, subprocess -- test_event_bus.py | Unit tests for InstanceEventBus verifying publish/subscribe behavior, exception isolation, unsubscribe functionality, and async callback support | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:test_publish_delivers_to_all_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, call:len, func:callback_1(payload: InstanceEventPayload) → None, call:received.append, func:callback_2(payload: InstanceEventPayload) → None, call:received.append, func:callback_3(payload: InstanceEventPayload) → None, call:received.append, func:test_subscriber_exception_isolation(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, raise:RuntimeError, func:bad_callback(_payload: InstanceEventPayload) → None, raise:RuntimeError, func:good_callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_unsubscribe_removes_callback(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:unsubscribe, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_publish_to_empty_subscriber_list(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:event_bus.publish, func:test_async_subscriber_supported(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, call:event_bus.subscribe, call:event_bus.publish, func:async_callback(_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, func:test_unsubscribe_all_clears_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.unsubscribe_all, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, typing, pytest, src.services.event_bus -- test_file_service.py | Unit tests for FileService validating directory listing, file read/write, binary rejection, and path traversal prevention. | exp: class:TestFileService, method:test_list_directory_empty(self, temp_workspace: Workspace), call:FileService, call:service.list_directory, method:test_list_directory_with_files(self, temp_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:FileService, call:service.list_directory, call:len, method:test_read_file(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:service.read_file, method:test_read_binary_file_rejected(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:pytest.raises, call:service.read_file, method:test_write_file(self, temp_workspace: Workspace), call:FileService, call:service.write_file, call:os.path.exists, call:os.path.join, call:open, call:f.read, method:test_path_escapes_workspace(self, temp_workspace: Workspace), call:FileService, call:pytest.raises, call:service.list_directory, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:Workspace | dep: os, tempfile, pytest, src.models, src.services.shared.file_service, src.models.Workspace, src.services.shared.file_service.FileService -- test_git_mount_resolution.py | Unit tests for git mount resolution functions including glob expansion, branch checkout, and mount validation in tool instances. | exp: class:TestExpandGlobSource, method:test_no_glob_single_file(self, tmp_path: Path) → None, call:test_file.write_text, call:_expand_glob_source, call:str, call:len, method:test_no_glob_missing_file(self, tmp_path: Path) → None, call:_expand_glob_source, call:str, call:len, method:test_glob_pattern(self, tmp_path: Path) → None, call:(tmp_path / "file1.txt").write_text, call:(tmp_path / "file2.txt").write_text, call:(tmp_path / "other.py").write_text, call:_expand_glob_source, call:str, call:len, call:all, call:f.endswith, method:test_glob_recursive(self, tmp_path: Path) → None, call:subdir.mkdir, call:(subdir / "nested.txt").write_text, call:_expand_glob_source, call:str, call:len, method:test_glob_limit_enforced(self, tmp_path: Path) → None, call:range, call:(tmp_path / f"file{i}.txt").write_text, call:_expand_glob_source, call:str, call:len, method:test_glob_escapes_repo(self, tmp_path: Path) → None, call:other_dir.mkdir, call:(other_dir / "outside.txt").write_text, call:_expand_glob_source, call:str, call:all, call:r.startswith, class:TestCheckoutBranch, method:test_checkout_existing_branch(self, tmp_path: Path) → None, call:os.system, call:(tmp_path / "file.txt").write_text, call:_checkout_branch, call:str, call:os.popen(f"cd {tmp_path} && git branch --show-current").read().strip, method:test_checkout_nonexistent_branch(self, tmp_path: Path) → None, call:os.system, call:(tmp_path / "file.txt").write_text, call:_checkout_branch, call:str, class:TestResolveSingleGitMount | dep: os, pathlib, pytest, src.api.tool_instances, pathlib.Path -- test_git_mounts.py | Unit tests for git mount resolution functions that handle multi-mapping support, normalization, glob expansion, and Docker volume bind mounting. | exp: class:TestNormalizeGitMount, method:test_legacy_to_mappings(self) → None, call:_normalize_git_mount, method:test_already_mappings(self) → None, call:_normalize_git_mount, method:test_missing_target_path_no_mappings(self) → None, call:_normalize_git_mount, class:TestResolveGitMountMappings, method:test_single_mapping(self) → None, call:tempfile.TemporaryDirectory, call:os.makedirs, call:os.path.join, call:_resolve_git_mount_mappings, call:len, method:test_multiple_mappings(self) → None, call:tempfile.TemporaryDirectory, call:os.makedirs, call:os.path.join, call:_resolve_git_mount_mappings, call:len, method:test_relative_target_path(self) → None, call:tempfile.TemporaryDirectory, call:os.makedirs, call:os.path.join, call:_resolve_git_mount_mappings, call:len, method:test_glob_expansion(self) → None, call:tempfile.TemporaryDirectory, call:os.makedirs, call:os.path.join, call:_resolve_git_mount_mappings, call:len, method:test_missing_target_path_skipped(self) → None, call:tempfile.TemporaryDirectory, call:_resolve_git_mount_mappings, call:len, method:test_no_working_directory_for_relative_target(self) → None, call:tempfile.TemporaryDirectory, call:os.makedirs, call:os.path.join, call:_resolve_git_mount_mappings, call:len, class:TestResolveSingleGitMount, class:TestExpandGlobSource, method:test_no_glob(self) → None, call:tempfile.TemporaryDirectory, call:os.path.join, call:open(path, "w").close, call:_expand_glob_source, method:test_no_glob_missing(self) → None, call:tempfile.TemporaryDirectory, call:os.path.join, call:_expand_glob_source, method:test_glob_pattern(self) → None, call:tempfile.TemporaryDirectory, call:open(os.path.join(tmp, "a.txt"), "w").close, call:os.path.join, call:open(os.path.join(tmp, "b.txt"), "w").close, call:_expand_glob_source, call:len | dep: os, tempfile, unittest.mock, pytest, src.api.tool_instances -- test_git_operations.py | Unit tests for GitOperations class covering git status, commit, history, and branch operations | exp: class:TestGitOperationsStatus, method:test_status_clean(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.status, method:test_status_modified(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, method:test_status_untracked(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, class:TestGitOperationsCommit, method:test_commit_stages_and_commits(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.status, call:git.history, method:test_commit_fails_without_changes(self, temp_workspace: Workspace), call:GitOperations, call:pytest.raises, call:asyncio.run, call:git.commit, class:TestGitOperationsHistory, method:test_history_returns_commits(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.history, call:len, method:test_history_filters_by_path(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.history, call:len, class:TestGitOperationsBranches, method:test_branches_lists_main(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.branches, method:test_checkout_switches_branch(self, temp_workspace: Workspace), call:_run_git, call:GitOperations, call:asyncio.run, call:git.checkout, call:git.status, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:_run_git, call:os.path.join, call:open, call:f.write, call:Workspace | dep: asyncio, os, subprocess, tempfile, pytest, src.models, src.services.git.git_operations, src.models.Workspace, src.services.git.git_operations.GitOperations -- test_git_repository_clone_preflight.py | Unit tests for git repository clone URL building and preflight accessibility checks | exp: func:test_build_provider_clone_url_uses_fixed_host() → None, call:_build_provider_clone_url, func:test_preflight_remote_repository_allows_accessible_repo() → None, call:Mock, call:patch, call:_preflight_remote_repository, call:run_mock.assert_called_once, func:test_preflight_remote_repository_rejects_missing_repo() → None, call:Mock, call:patch, call:pytest.raises, call:_preflight_remote_repository | dep: unittest.mock, pytest, fastapi, src.api.git_repositories, subprocess -- test_git_repository_working_clones.py | Tests git repository cloning and initialization utilities with fallback strategies for different git versions | exp: func:test_clone_working_repository_uses_normal_clone() → None, call:Mock, call:patch, call:_clone_working_repository, call:run_mock.assert_called_once, func:test_clone_working_repository_raises_on_failure() → None, call:Mock, call:patch, call:pytest.raises, call:_clone_working_repository, func:test_init_working_repository_prefers_init_b() → None, call:Mock, call:patch, call:_init_working_repository, func:test_init_working_repository_falls_back_to_symbolic_ref() → None, call:Mock, call:patch, call:_init_working_repository, func:test_create_branch_uses_orphan_checkout_when_head_is_unborn() → None, call:patch, call:create_branch, raise:RuntimeError, func:mock_run(repo_path: str, *args: str) → str, raise:RuntimeError | dep: unittest.mock, pytest, fastapi, src.api.git_repositories, src.utils.git_control, subprocess -- test_git_service.py | Unit tests for GitService class covering clone, fetch, pull, and branch_exists_remotely operations with mocked subprocess calls. | exp: class:TestGitServiceClone, class:TestGitServiceFetch, class:TestGitServicePull, class:TestGitServiceBranchExistsRemotely, method:test_branch_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, call:mock_run.assert_called_once_with, method:test_branch_not_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, method:test_ls_remote_fails(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely | dep: asyncio, unittest.mock, pytest, src.services.git_service +- test_config.py | Tests configuration settings and database URL building for an application, verifying defaults, environment variable overrides, and environment-specific behavior. | exp: func:test_settings_default_database_url_uses_asyncpg(monkeypatch) → None, call:monkeypatch.delenv, call:Settings, func:test_build_database_url_uses_explicit_values() → None, call:build_database_url, func:test_settings_prefers_explicit_database_url_env(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_auth_settings_have_secure_defaults() → None, call:Settings, call:settings.resolved_authentik_authorize_url.endswith, call:settings.resolved_authentik_token_url.endswith, call:settings.resolved_authentik_jwks_url.endswith, func:test_cookie_policy_is_strict_in_production(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_cookie_policy_is_relaxed_for_local_dev(monkeypatch) → None, call:monkeypatch.setenv, call:Settings | dep: pytest, src.config, src.database +- test_config_profile_resolver.py | Unit tests for config profile resolution including merge functions, profile inheritance with includes, cycle detection, and git mount normalization | exp: class:TestMergeFunctions, method:test_merge_env_vars_basic(self) → None, call:_merge_env_vars, method:test_merge_env_vars_tracks_overrides(self) → None, call:_merge_env_vars, method:test_merge_runtime_hints_basic(self) → None, call:_merge_runtime_hints, method:test_merge_files_basic(self) → None, call:_merge_files, method:test_merge_mounts_basic(self) → None, call:_merge_mounts, method:test_merge_mounts_file_override(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_mounts_mode_conflict(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_git_mounts_basic(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_concatenate_same_repo_branch(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_dedup_same_mapping(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_repos(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_branches(self) → None, call:_merge_git_mounts, call:len, call:m.get, class:TestResolveProfile, class:TestApplyResolvedProfile, method:test_mounts_individual_files_not_directory(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, method:test_file_mount_preserves_sibling_files(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0]["source"].endswith, method:test_empty_mount_produces_no_volumes(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, method:test_home_expansion_in_file_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, class:TestCheckIncludeCycle | dep: uuid, pytest, sqlalchemy.ext.asyncio, src.models.config.config_profile, src.services.config.config_profile_resolver +- test_docker_build.py | Unit tests for a Docker image build service that verifies Dockerfile creation, command structure, context file handling, path traversal prevention, and error handling. | exp: class:TestBuildImage | dep: subprocess, tempfile, pathlib, unittest.mock, pytest, src.services.build.docker_build +- test_docker_service.py | Unit tests for Docker service utilities including container ID/name retrieval and volume sorting by specificity. | exp: class:TestGetContainerId, class:TestGetContainerName, class:TestSortVolumesBySpecificity, method:test_parent_before_child(self) → None, call:sort_volumes_by_specificity, method:test_stable_sort_for_equal_depth(self) → None, call:sort_volumes_by_specificity, method:test_with_type_suffix(self) → None, call:sort_volumes_by_specificity, method:test_empty_list(self) → None, call:sort_volumes_by_specificity, method:test_single_volume(self) → None, call:sort_volumes_by_specificity, method:test_duplicate_target_warning(self, caplog) → None, call:caplog.at_level, call:sort_volumes_by_specificity | dep: unittest.mock, logging, src.services.docker.container, src.services.docker.compose, subprocess +- test_event_bus.py | Unit tests for InstanceEventBus verifying publish/subscribe, exception isolation, unsubscribe, and async callback support. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:test_publish_delivers_to_all_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, call:len, func:callback_1(payload: InstanceEventPayload) → None, call:received.append, func:callback_2(payload: InstanceEventPayload) → None, call:received.append, func:callback_3(payload: InstanceEventPayload) → None, call:received.append, func:test_subscriber_exception_isolation(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, raise:RuntimeError, func:bad_callback(_payload: InstanceEventPayload) → None, raise:RuntimeError, func:good_callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_unsubscribe_removes_callback(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:unsubscribe, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_publish_to_empty_subscriber_list(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:event_bus.publish, func:test_async_subscriber_supported(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, call:event_bus.subscribe, call:event_bus.publish, func:async_callback(_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, func:test_unsubscribe_all_clears_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.unsubscribe_all, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, typing, pytest, src.services.instance.event_bus +- test_file_service.py | Unit tests for FileService validating directory listing, file read/write, binary rejection, path traversal prevention, and workspace-based file operations. | exp: class:TestFileService, method:test_list_directory_empty(self, temp_workspace: Workspace), call:FileService, call:service.list_directory, method:test_list_directory_with_files(self, temp_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:FileService, call:service.list_directory, call:len, method:test_read_file(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:service.read_file, method:test_read_binary_file_rejected(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:pytest.raises, call:service.read_file, method:test_write_file(self, temp_workspace: Workspace), call:FileService, call:service.write_file, call:os.path.exists, call:os.path.join, call:open, call:f.read, method:test_path_escapes_workspace(self, temp_workspace: Workspace), call:FileService, call:pytest.raises, call:service.list_directory, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:Workspace | dep: os, tempfile, pytest, src.models, src.services.shared.file_service, src.models.Workspace, src.services.shared.file_service.FileService +- test_git_operations.py | Unit tests for GitOperations class covering status, commit, history, and branch operations | exp: class:TestGitOperationsStatus, method:test_status_clean(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.status, method:test_status_modified(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, method:test_status_untracked(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, class:TestGitOperationsCommit, method:test_commit_stages_and_commits(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.status, call:git.history, method:test_commit_fails_without_changes(self, temp_workspace: Workspace), call:GitOperations, call:pytest.raises, call:asyncio.run, call:git.commit, class:TestGitOperationsHistory, method:test_history_returns_commits(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.history, call:len, method:test_history_filters_by_path(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.history, call:len, class:TestGitOperationsBranches, method:test_branches_lists_main(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.branches, method:test_checkout_switches_branch(self, temp_workspace: Workspace), call:_run_git, call:GitOperations, call:asyncio.run, call:git.checkout, call:git.status, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:_run_git, call:os.path.join, call:open, call:f.write, call:Workspace | dep: asyncio, os, subprocess, tempfile, pytest, src.models, src.services.git.git_operations, src.models.Workspace, src.services.git.git_operations.GitOperations +- test_git_service.py | Unit tests for GitService class covering clone, fetch, pull, and branch_exists_remotely operations with mocked subprocess calls. | exp: class:TestGitServiceClone, class:TestGitServiceFetch, class:TestGitServicePull, class:TestGitServiceBranchExistsRemotely, method:test_branch_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, call:mock_run.assert_called_once_with, method:test_branch_not_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, method:test_ls_remote_fails(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely | dep: asyncio, unittest.mock, pytest, src.services.git.git_service - test_git_url_parser.py | Tests for git URL parsing utilities that extract base repository URLs, validate clone URLs, and parse various git URL formats across GitHub, GitLab, and Bitbucket. | exp: class:TestExtractBaseRepoUrl, method:test_github_tree_url(self), call:extract_base_repo_url, method:test_github_blob_url(self), call:extract_base_repo_url, method:test_github_pull_url(self), call:extract_base_repo_url, method:test_github_issues_url(self), call:extract_base_repo_url, method:test_github_valid_url(self), call:extract_base_repo_url, method:test_github_url_with_query_params(self), call:extract_base_repo_url, method:test_gitlab_tree_url(self), call:extract_base_repo_url, method:test_gitlab_blob_url(self), call:extract_base_repo_url, method:test_gitlab_merge_request_url(self), call:extract_base_repo_url, method:test_gitlab_valid_url(self), call:extract_base_repo_url, method:test_bitbucket_src_url(self), call:extract_base_repo_url, method:test_bitbucket_valid_url(self), call:extract_base_repo_url, method:test_ssh_url(self), call:extract_base_repo_url, method:test_ssh_url_without_git_suffix(self), call:extract_base_repo_url, method:test_invalid_url(self), call:extract_base_repo_url, method:test_empty_url(self), call:extract_base_repo_url, class:TestIsValidCloneUrl, method:test_valid_ssh_url(self), call:is_valid_clone_url, method:test_valid_https_url(self), call:is_valid_clone_url, method:test_browser_url(self), call:is_valid_clone_url, method:test_url_without_git_suffix(self), call:is_valid_clone_url, method:test_invalid_url(self), call:is_valid_clone_url, class:TestParseGitUrl, method:test_valid_git_url(self), call:parse_git_url, method:test_browser_url(self), call:parse_git_url, method:test_invalid_url(self), call:parse_git_url, method:test_empty_url(self), call:parse_git_url, method:test_ssh_url(self), call:parse_git_url | dep: src.utils.git_url_parser, pytest -- test_health_monitor.py | Unit tests for HealthMonitor's state-transition logic covering container crashes, tunnel failures, recovery detection, deduplication, exception resilience, and lifecycle management. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:health_monitor(event_bus: InstanceEventBus) → HealthMonitor, call:HealthMonitor, func:_create_running_instance(db_session) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, func:test_detects_container_crash(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_tunnel_failure(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_recovery(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:db_session.commit, call:HealthSnapshot, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_skips_writes_when_no_state_change(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:patch, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:len, call:result.scalars().all, func:test_docker_exception_resilience(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one_or_none, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_monitor_start_stop(health_monitor: HealthMonitor) → None, call:health_monitor.start, call:task.done, call:health_monitor.stop, call:suppress, call:task.cancelled | dep: asyncio, uuid, contextlib, unittest.mock, pytest, sqlalchemy, src.models.health_check, src.models.tool_instance, src.models.user, src.services.event_bus, src.services.health_monitor -- test_home_path_expansion.py | Unit tests for tilde and $HOME expansion in container paths across three helper functions. | exp: class:TestExpandContainerPath, method:test_tilde_slash_expands(self) → None, call:expand_container_path, method:test_tilde_alone_expands(self) → None, call:expand_container_path, method:test_dollar_home_slash_expands(self) → None, call:expand_container_path, method:test_dollar_home_alone_expands(self) → None, call:expand_container_path, method:test_absolute_path_unchanged(self) → None, call:expand_container_path, method:test_relative_path_unchanged(self) → None, call:expand_container_path, method:test_tilde_in_middle_unchanged(self) → None, call:expand_container_path, method:test_dollar_home_in_middle_unchanged(self) → None, call:expand_container_path, method:test_root_home(self) → None, call:expand_container_path, class:TestGetManifestHomeDir, method:test_with_user_block(self) → None, call:get_manifest_home_dir, method:test_without_user_block(self) → None, call:get_manifest_home_dir, method:test_with_empty_user_name(self) → None, call:get_manifest_home_dir, method:test_with_none_user_name(self) → None, call:get_manifest_home_dir, class:TestResolveGitMountMappingsExpansion, method:test_tilde_target_expansion(self, tmp_path) → None, call:(tmp_path / "src").mkdir, call:_resolve_git_mount_mappings, call:str, call:len, method:test_dollar_home_target_expansion(self, tmp_path) → None, call:(tmp_path / "src").mkdir, call:_resolve_git_mount_mappings, call:str, call:len, method:test_absolute_target_unchanged(self, tmp_path) → None, call:(tmp_path / "src").mkdir, call:_resolve_git_mount_mappings, call:str, call:len | dep: pytest, src.api.tool_instances, src.services.config_profile_resolver, src.services.manifest_compiler -- test_lifecycle_hooks.py | Unit tests for lifecycle hook helper functions that derive notification titles and determine whether events should trigger notifications based on event type and status. | exp: class:TestDeriveTitle, method:test_known_event_types(self) → None, call:_derive_title, method:test_unknown_event_type(self) → None, call:_derive_title, class:TestShouldNotify, method:test_error_events_are_notified(self) → None, call:_should_notify, method:test_health_changed_running_is_notified(self) → None, call:_should_notify, method:test_created_started_stopped_restarted_deleted_filtered(self) → None, call:_should_notify, method:test_health_changed_non_running_filtered(self) → None, call:_should_notify | dep: pytest, src.services.lifecycle_hooks +- test_health_monitor.py | Unit tests for HealthMonitor state-transition logic covering container crash detection, tunnel failure detection, recovery detection, write deduplication, exception resilience, and start/stop lifecycle. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:health_monitor(event_bus: InstanceEventBus) → HealthMonitor, call:HealthMonitor, func:_create_running_instance(db_session) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, func:test_detects_container_crash(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_tunnel_failure(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_recovery(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:db_session.commit, call:HealthSnapshot, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_skips_writes_when_no_state_change(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:HealthSnapshot, call:patch, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:len, call:result.scalars().all, func:test_docker_exception_resilience(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one_or_none, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_monitor_start_stop(health_monitor: HealthMonitor) → None, call:health_monitor.start, call:task.done, call:health_monitor.stop, call:suppress, call:task.cancelled | dep: asyncio, uuid, contextlib, unittest.mock, pytest, sqlalchemy, src.models.system.health_check, src.models.tool.tool_instance, src.models.user.user, src.services.instance.event_bus, src.services.instance.health_monitor +- test_home_path_expansion.py | Unit tests for home directory path expansion (~ and $HOME) in container paths and manifest home directory resolution. | exp: class:TestExpandContainerPath, method:test_tilde_slash_expands(self) → None, call:expand_container_path, method:test_tilde_alone_expands(self) → None, call:expand_container_path, method:test_dollar_home_slash_expands(self) → None, call:expand_container_path, method:test_dollar_home_alone_expands(self) → None, call:expand_container_path, method:test_absolute_path_unchanged(self) → None, call:expand_container_path, method:test_relative_path_unchanged(self) → None, call:expand_container_path, method:test_tilde_in_middle_unchanged(self) → None, call:expand_container_path, method:test_dollar_home_in_middle_unchanged(self) → None, call:expand_container_path, method:test_root_home(self) → None, call:expand_container_path, class:TestGetManifestHomeDir, method:test_with_user_block(self) → None, call:get_manifest_home_dir, method:test_without_user_block(self) → None, call:get_manifest_home_dir, method:test_with_empty_user_name(self) → None, call:get_manifest_home_dir, method:test_with_none_user_name(self) → None, call:get_manifest_home_dir | dep: pytest, src.services.config.config_profile_resolver, src.services.build.manifest_compiler +- test_lifecycle_hooks.py | Unit tests for lifecycle hook helper functions that derive notification titles and determine whether events should trigger notifications. | exp: class:TestDeriveTitle, method:test_known_event_types(self) → None, call:_derive_title, method:test_unknown_event_type(self) → None, call:_derive_title, class:TestShouldNotify, method:test_error_events_are_notified(self) → None, call:_should_notify, method:test_health_changed_running_is_notified(self) → None, call:_should_notify, method:test_created_started_stopped_restarted_deleted_filtered(self) → None, call:_should_notify, method:test_health_changed_non_running_filtered(self) → None, call:_should_notify | dep: pytest, src.services.instance.lifecycle_hooks - test_manifest_compiler.py | Unit tests for a manifest compiler that generates Dockerfiles with user configuration and home directory setup | exp: func:test_compile_dockerfile_creates_config_dirs_for_user() → None, call:compile_dockerfile, func:test_compile_dockerfile_no_user_does_not_create_home() → None, call:compile_dockerfile | dep: pytest, src.services.build.manifest_compiler - test_migration_metadata.py | Tests Alembic database migration files for correct table definitions and revision chain metadata | exp: func:test_initial_migration_defines_all_core_tables() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module, func:test_refresh_tokens_migration_has_expected_revision_chain() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module | dep: pytest, importlib.util, pathlib, pathlib.Path -- test_monitoring_models.py | Unit tests for monitoring models (InstanceEvent, HealthCheck) and their database persistence/querying. | exp: func:test_instance_event_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.refresh, call:isinstance, func:test_health_check_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:HealthCheck, call:db_session.refresh, call:isinstance, func:test_instance_event_query_by_instance(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalar_one | dep: uuid, datetime, pytest, sqlalchemy, src.models.health_check, src.models.instance_event, src.models.tool_instance, src.models.user -- test_notification_service.py | Unit tests for NotificationService covering CRUD operations, filtering, ownership validation, and bulk actions on user notifications. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:test_create_notification(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:uuid.uuid4, func:test_list_notifications_orders_by_created_at_desc(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:notification_service.list_notifications, func:test_list_notifications_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.list_notifications, func:test_list_notifications_unread_only(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.list_notifications, func:test_get_unread_count(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.get_unread_count, func:test_mark_read_sets_read_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, func:test_mark_all_read_affects_all_unread(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count, func:test_dismiss_sets_dismissed_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_mark_read_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.mark_read, func:test_dismiss_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.dismiss, func:test_list_notifications_mute_categories(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.list_notifications, func:test_get_unread_count_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.get_unread_count, func:test_dismiss_all_affects_all_non_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_dismiss_all_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_mark_all_read_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count | dep: uuid, datetime, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.models.notification, src.models.user, src.services.notification_service -- test_notifications_api_routes.py | Tests that FastAPI notification routes are declared in correct order so bulk DELETE /notifications matches before parameterized DELETE /notifications/{id} | exp: func:test_delete_notifications_route_order() → None, call:FastAPI, call:app.include_router, call:TestClient, call:client.delete | dep: fastapi, fastapi.testclient, src.api.notifications -- test_permission_fixer.py | Unit tests for a Docker container permission fixer service that applies chown/chmod/file_mode to mounts and SSH directories. | exp: class:TestApplyMountPermissions, class:TestRunInContainer, class:TestApplySshPermissions, class:TestCheckRootUserAvailable | dep: unittest.mock, pytest, src.services.permission_fixer, subprocess -- test_readiness_probe.py | Unit tests for a Docker container readiness probe service that executes commands via docker exec with retry logic and timeout handling. | exp: class:TestExecuteProbe, class:TestIntegrationScenarios | dep: unittest.mock, src.services.readiness_probe, subprocess -- test_ssh_keys.py | Unit tests for SSH key preparation functionality that decrypts encrypted private keys and writes SSH key files with proper permissions and optional ownership. | exp: class:TestPrepareSshKeyFiles | dep: os, pathlib, unittest.mock, pytest, src.services.ssh_keys +- test_monitoring_models.py | Unit tests verifying creation, persistence, and querying of monitoring models (InstanceEvent and HealthCheck) with database migration compatibility. | exp: func:test_instance_event_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.refresh, call:isinstance, func:test_health_check_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:HealthCheck, call:db_session.refresh, call:isinstance, func:test_instance_event_query_by_instance(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalar_one | dep: uuid, datetime, pytest, sqlalchemy, src.models.system.health_check, src.models.system.instance_event, src.models.tool.tool_instance, src.models.user.user +- test_notification_service.py | Unit tests for NotificationService covering CRUD operations, filtering, sorting, and ownership isolation. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:test_create_notification(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:uuid.uuid4, func:test_list_notifications_orders_by_created_at_desc(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:notification_service.list_notifications, func:test_list_notifications_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.list_notifications, func:test_list_notifications_unread_only(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.list_notifications, func:test_get_unread_count(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.get_unread_count, func:test_mark_read_sets_read_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, func:test_mark_all_read_affects_all_unread(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count, func:test_dismiss_sets_dismissed_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_mark_read_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.mark_read, func:test_dismiss_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.dismiss, func:test_list_notifications_mute_categories(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.list_notifications, func:test_get_unread_count_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.get_unread_count, func:test_dismiss_all_affects_all_non_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_dismiss_all_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_mark_all_read_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count | dep: uuid, datetime, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.models.system.notification, src.models.user.user, src.services.shared.notification_service, NotificationService, Notification, User, AsyncSession +- test_notifications_api_routes.py | Tests that FastAPI notification routes are declared in correct order so bulk DELETE doesn't get intercepted by parameterized route | exp: func:test_delete_notifications_route_order() → None, call:FastAPI, call:app.include_router, call:TestClient, call:client.delete | dep: fastapi, fastapi.testclient, src.api.system.notifications +- test_permission_fixer.py | Unit tests for a Docker container permission fixer that adjusts mount and SSH permissions via docker exec commands. | exp: class:TestApplyMountPermissions, class:TestRunInContainer, class:TestApplySshPermissions, class:TestCheckRootUserAvailable | dep: unittest.mock, pytest, src.services.shared.permission_fixer, subprocess +- test_readiness_probe.py | Unit tests for a Docker container readiness probe service that executes commands via docker exec with retry logic. | exp: class:TestExecuteProbe, class:TestIntegrationScenarios | dep: unittest.mock, src.services.shared.readiness_probe, subprocess +- test_ssh_keys.py | Unit tests for SSH key preparation functionality including file creation, permissions, ownership, and error handling | exp: class:TestPrepareSshKeyFiles | dep: os, pathlib, unittest.mock, pytest, src.services.shared.ssh_keys ## arch -pytest-based unit testing with heavy mocking of external dependencies (Docker, Git subprocesses, databases), organized by service/component under test, using parameterized tests and fixture-based setup for isolated component verification. +Standard Python unittest/pytest structure with heavy use of mocking for external dependencies (Docker, Git subprocess, database), testing business logic in isolation without integration requirements. ## tags -test, call:, url, git, call:notification, mount, call:len, call:db +test, url, call:notification, git, call:db, merge, call:, src ## symbols - TestMergeFunctions - TestResolveProfile diff --git a/apps/api/uploads/.pi-map.index.md b/apps/api/uploads/.pi-map.index.md index b90056b..1452095 100644 --- a/apps/api/uploads/.pi-map.index.md +++ b/apps/api/uploads/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/uploads ## role -Handles file upload processing, storage, and management for the API application. +Handles file upload processing, storage, and retrieval for the API application. ## parent index: apps/api/.pi-map.index.md map: apps/api/.pi-map.md diff --git a/apps/api/uploads/.pi-map.md b/apps/api/uploads/.pi-map.md index c309865..971e794 100644 --- a/apps/api/uploads/.pi-map.md +++ b/apps/api/uploads/.pi-map.md @@ -4,10 +4,10 @@ dir: apps/api/uploads index: apps/api/uploads/.pi-map.index.md ## role -Handles file upload processing, storage, and management for the API application. +Handles file upload processing, storage, and retrieval for the API application. ## files ## arch -Modular service-oriented architecture with dedicated modules for different upload types (avatars, documents, images), using NestJS controllers/services with S3/cloud storage integration, file validation, and database persistence for upload metadata. +Express.js middleware pattern with multipart form parsing, likely using Multer or similar for file handling, with storage abstraction for local/cloud backends. ## tags - ## symbols diff --git a/apps/api/uploads/avatars/.pi-map.index.md b/apps/api/uploads/avatars/.pi-map.index.md index c4c8912..4842e5c 100644 --- a/apps/api/uploads/avatars/.pi-map.index.md +++ b/apps/api/uploads/avatars/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/api/uploads/avatars ## role -Storage directory for user avatar image files uploaded through the API. +Storage directory for user avatar image files uploaded through the API application. ## parent index: apps/api/uploads/.pi-map.index.md map: apps/api/uploads/.pi-map.md diff --git a/apps/api/uploads/avatars/.pi-map.md b/apps/api/uploads/avatars/.pi-map.md index 9b0c6b7..98fbeac 100644 --- a/apps/api/uploads/avatars/.pi-map.md +++ b/apps/api/uploads/avatars/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/api/uploads/avatars index: apps/api/uploads/avatars/.pi-map.index.md ## role -Storage directory for user avatar image files uploaded through the API. +Storage directory for user avatar image files uploaded through the API application. ## files - 30d2810a-cb00-4065-8e5d-c7d32a0b55c9.png | Binary file - b342b640-d3c1-488d-bdba-0e2890d6c363.png | Binary file - da1c3121-20d7-400c-8c94-507a9d890810.png | Binary file - ee9fdd89-0dcc-4f46-9ad8-01f4ff93720d.png | Binary file ## arch -Simple flat file storage using UUID-named PNG files with no subdirectory organization or metadata indexing. +Simple static file storage using UUID-named PNG files in a flat directory structure, serving as a persistent blob store without database indexing or subdirectory organization. ## tags binary, 30d2810a, cb00, 4065, 8e5d, c7d32a0b55c9, b342b640, d3c1 ## symbols diff --git a/apps/web/.pi-map.md b/apps/web/.pi-map.md index ad33a7a..f81e3a7 100644 --- a/apps/web/.pi-map.md +++ b/apps/web/.pi-map.md @@ -16,7 +16,7 @@ Frontend web application providing a React-based UI with code editing, terminal, - tsconfig.json | TypeScript configuration file for a React project using Vite with modern ES2020 target and bundler module resolution | dep: typescript, react, vite - vite.config.ts | Configures Vite build tool for a React project with custom dev server port and Vitest test settings. | dep: vite, @vitejs/plugin-react ## arch -Modern React SPA built with Vite and TypeScript, served by nginx in a containerized multi-stage Docker build, using Vitest for testing and ESLint for code quality. +Modern React SPA built with Vite and TypeScript, containerized via multi-stage Docker with nginx serving, featuring client-side routing and optimized static asset delivery. ## tags react, eslint, vite, typescript, dom, application, nginx, web ## symbols diff --git a/apps/web/public/.pi-map.index.md b/apps/web/public/.pi-map.index.md index 0a9b1b8..d4bd623 100644 --- a/apps/web/public/.pi-map.index.md +++ b/apps/web/public/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/public ## role -Static HTML prototype for UI/UX validation and stakeholder review of the workspace dashboard design before React implementation. +Static frontend assets serving a standalone HTML preview/demo of the workspace dashboard UI without requiring the full application runtime. ## parent index: apps/web/.pi-map.index.md map: apps/web/.pi-map.md diff --git a/apps/web/public/.pi-map.md b/apps/web/public/.pi-map.md index c2f80d1..5d05c21 100644 --- a/apps/web/public/.pi-map.md +++ b/apps/web/public/.pi-map.md @@ -4,11 +4,11 @@ dir: apps/web/public index: apps/web/public/.pi-map.index.md ## role -Static HTML prototype for UI/UX validation and stakeholder review of the workspace dashboard design before React implementation. +Static frontend assets serving a standalone HTML preview/demo of the workspace dashboard UI without requiring the full application runtime. ## files - preview.html | Static HTML/CSS UI mockup for a "Headquarter" workspace dashboard with interactive page preview switching between Home, Projects, and Settings views. | dep: Google Fonts (Inter, IBM Plex Mono) ## arch -Vanilla HTML/CSS mockup with JavaScript-driven view switching, using CSS Grid/Flexbox layout and class-based DOM manipulation for interactive state transitions. +Self-contained static HTML prototype with vanilla CSS and JavaScript, using a simple view-switching pattern to simulate multi-page SPA navigation within a single file. ## tags preview, static, html, css, mockup, headquarter, workspace, dashboard ## symbols diff --git a/apps/web/src/.pi-map.index.md b/apps/web/src/.pi-map.index.md index 37825fa..c72f1a0 100644 --- a/apps/web/src/.pi-map.index.md +++ b/apps/web/src/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src ## role -Frontend web application entry point and core infrastructure for a React-based collaborative development platform. +Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions. ## parent index: apps/web/.pi-map.index.md map: apps/web/.pi-map.md diff --git a/apps/web/src/.pi-map.md b/apps/web/src/.pi-map.md index 4839234..704a13f 100644 --- a/apps/web/src/.pi-map.md +++ b/apps/web/src/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/web/src index: apps/web/src/.pi-map.index.md ## role -Frontend web application entry point and core infrastructure for a React-based collaborative development platform. +Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions. ## files - main.tsx | Bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom - router.tsx | Defines the React Router configuration for a web application with protected routes, nested layouts, and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage - types.ts | Defines TypeScript type definitions for user sessions, projects, repositories, and workspaces in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos ## arch -Modern React SPA with declarative routing (React Router), nested layout composition, protected route guards via authentication context, and centralized TypeScript domain modeling for multi-tenant workspace/project entities. +Provider pattern wrapping React Router with nested route layouts, protected route guards via authentication/session providers, and centralized TypeScript type definitions for domain models. ## tags pages, styles, css, router, react, session, dom, project ## symbols diff --git a/apps/web/src/api/.pi-map.index.md b/apps/web/src/api/.pi-map.index.md index 15e3b95..cba9650 100644 --- a/apps/web/src/api/.pi-map.index.md +++ b/apps/web/src/api/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/api ## role -Provides typed HTTP API client modules and interfaces for all backend communication in the web application, covering domains from authentication and user management to workspaces, tools, git, terminals, and real-time events. +Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/api/.pi-map.md b/apps/web/src/api/.pi-map.md index ec58c73..d58710d 100644 --- a/apps/web/src/api/.pi-map.md +++ b/apps/web/src/api/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/api index: apps/web/src/api/.pi-map.index.md ## role -Provides typed HTTP API client modules and interfaces for all backend communication in the web application, covering domains from authentication and user management to workspaces, tools, git, terminals, and real-time events. +Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity. ## files - client.ts | Configures an Axios HTTP client with automatic 401 redirect handling and exponential backoff retry logic for transient network/server errors. | exp: apiClient, shouldSkipAuthRedirect | dep: axios - config-profiles.ts | Defines TypeScript interfaces and API client functions for managing configuration profiles with environment variables, mounts, git mounts, file inclusions, and profile resolution. | exp: ConfigProfile, ConfigProfileMount, GitMountMapping, GitMount, ConfigProfileInclude, ResolvedProfile, ResolvedMount, CreateConfigProfileRequest, UpdateConfigProfileRequest, UpdateIncludesRequest, listConfigProfiles, getConfigProfile, createConfigProfile, updateConfigProfile, deleteConfigProfile, updateProfileIncludes, previewConfigProfile, resolveDefaultProfile, ValidateGitUrlResponse, validateGitUrl | dep: ./client, client @@ -14,7 +14,7 @@ Provides typed HTTP API client modules and interfaces for all backend communicat - notifications.ts | Defines TypeScript interfaces and API client functions for fetching, reading, dismissing, and clearing user notifications. | exp: NotificationItem, NotificationListResponse, UnreadCountResponse, MarkAllReadResponse, ClearAllResponse, getNotifications, getUnreadCount, markNotificationRead, markAllNotificationsRead, dismissNotification, clearAllNotifications | dep: ./client, apiClient - profile.ts | Provides API functions for fetching, updating, and uploading avatar for the current user's profile. | exp: UserProfile, ProfileUpdatePayload, getProfile, updateProfile, uploadAvatar | dep: ./client, ../types, apiClient, SessionUser - projects.ts | Provides typed API functions for CRUD operations on projects via HTTP endpoints. | exp: ProjectCreateInput, ProjectUpdateInput, SetDefaultSSHKeyInput, listProjects, createProject, updateProject, deleteProject, setDefaultSSHKey | dep: ./client, ../types -- sessions.ts | Provides API client functions for managing cloud development tool instances and user sessions via REST endpoints. | exp: ToolInstance, Session, InstanceHealth, func:listInstances(projectId: string, repoId: string) → Promise, call:apiClient.get, func:createInstance(projectId: string, repoId: string, toolTypeId: string, displayName: string, cloneMode: string, branch: string, newBranch: string, configProfileId: string, sshKeyIds: string[], workspaceId: string) → Promise, call:apiClient.post, func:startInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:startInstance, raise:error, func:stopInstance(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string }>, call:apiClient.post, func:restartInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:restartInstance, raise:error, func:deleteInstance(projectId: string, repoId: string, instanceId: string, force: boolean) → Promise, call:apiClient.delete, func:getInstance(projectId: string, repoId: string, instanceId: string) → Promise, call:apiClient.get, func:getUserSessions() → Promise, call:apiClient.get, func:checkInstanceHealth(projectId: string, repoId: string, instanceId: string) → Promise, call:apiClient.get, func:renameInstance(projectId: string, repoId: string, instanceId: string, displayName: string) → Promise<{ id: string; name: string; display_name: string }>, call:apiClient.patch, func:recreateInstanceTunnel(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string; url?: string }>, call:apiClient.post | dep: axios, ./client +- sessions.ts | Provides TypeScript API functions and interfaces for managing remote tool instances and sessions via HTTP requests. | exp: ToolInstance, Session, InstanceHealth, func:listInstances(projectId: string, repoId: string) → Promise, call:apiClient.get, func:createInstance(projectId: string, repoId: string, toolTypeId: string, displayName: string, workspaceId: string, configProfileId: string, sshKeyIds: string[]) → Promise, call:apiClient.post, func:startInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:startInstance, raise:error, func:stopInstance(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string }>, call:apiClient.post, func:restartInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:restartInstance, raise:error, func:deleteInstance(projectId: string, repoId: string, instanceId: string, force: boolean) → Promise, call:apiClient.delete, func:getInstance(projectId: string, repoId: string, instanceId: string) → Promise, call:apiClient.get, func:getUserSessions() → Promise, call:apiClient.get, func:checkInstanceHealth(projectId: string, repoId: string, instanceId: string) → Promise, call:apiClient.get, func:renameInstance(projectId: string, repoId: string, instanceId: string, displayName: string) → Promise<{ id: string; name: string; display_name: string }>, call:apiClient.patch, func:recreateInstanceTunnel(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string; url?: string }>, call:apiClient.post | dep: axios, ./client - settings.ts | Defines user configuration interfaces and API functions for fetching and updating user settings via HTTP requests. | exp: UserConfig, UserConfigUpdate, getUserConfig, updateUserConfig | dep: ./client, apiClient - ssh-keys.ts | Provides a TypeScript API client for SSH key management operations including listing, creating, deleting, and cryptographic signing/verification. | exp: SSHKey, SSHKeyCreate, SignPayloadRequest, SignatureResponse, VerifySignatureRequest, VerifySignatureResponse, func:listSSHKeys() → Promise, func:createSSHKey(data: SSHKeyCreate) → Promise, func:deleteSSHKey(keyId: string) → Promise, call:apiClient.delete, func:signPayload(keyId: string, data: SignPayloadRequest) → Promise, func:verifySignature(keyId: string, data: VerifySignatureRequest) → Promise | dep: ./client, apiClient - terminal.ts | Provides a TypeScript API client module for managing remote terminal sessions (CRUD operations) on cloud instances via REST endpoints. | exp: TerminalSession, TerminalSessionListResponse, TerminalSessionCreateRequest, TerminalSessionCreateResponse, func:listTerminalSessions(instanceId: string) → Promise, call:apiClient.get, func:createTerminalSession(instanceId: string, name: string) → Promise, call:apiClient.post, func:closeTerminalSession(instanceId: string, sessionId: string) → Promise<{ status: string; session_id: string }>, call:apiClient.delete, func:resetTerminalSession(instanceId: string, sessionId: string) → Promise<{ id: string; name: string; status: string }>, call:apiClient.post, func:renameTerminalSession(instanceId: string, sessionId: string, name: string) → Promise<{ id: string; name: string }>, call:apiClient.post | dep: ./client, client @@ -26,9 +26,9 @@ Provides typed HTTP API client modules and interfaces for all backend communicat - workspace-instances.ts | Provides API client functions to list and create workspace tool instances. | exp: func:listWorkspaceInstances(workspaceId: string) → Promise, func:createWorkspaceInstance(workspaceId: string, toolTypeId: string, displayName: string, configProfileId: string) → Promise | dep: ./client, ./sessions - workspaces.ts | Provides an API client wrapper for CRUD operations and sync functionality on workspaces via HTTP endpoints. | exp: func:listWorkspaces(projectId: string, repoId: string) → Promise, call:workspaceUrl, func:listAllWorkspaces() → Promise, func:createWorkspace(projectId: string, repoId: string, data: CreateWorkspaceRequest) → Promise, call:workspaceUrl, func:createWorkspaceTopLevel(data: CreateWorkspaceRequest & { repo_id: string }) → Promise, func:getWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise, call:workspaceUrl, func:updateWorkspace(projectId: string, repoId: string, workspaceId: string, data: Partial) → Promise, call:workspaceUrl, func:deleteWorkspace(workspaceId: string, force) → Promise<{ status: string }>, func:syncWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise, call:workspaceUrl | dep: ./client, ../types/workspace, apiClient, Workspace, CreateWorkspaceRequest, SyncResult ## arch -Modular facade pattern with a centralized Axios client instance (client.ts) featuring cross-cutting concerns (auth redirect, retry logic), with each domain exposing isolated typed API function modules that map to REST endpoints; includes SSE for real-time events and mirrors backend domain boundaries. +Modular facade pattern with a centralized Axios client (client.ts) featuring cross-cutting concerns (auth redirect, retry logic), consumed by domain-specific modules that export typed interfaces and thin API function wrappers. ## tags -call:api, tool, client.post, create, git, profile, client, get +call:api, tool, client.post, create, git, profile, get, client ## symbols - createEventSource - probeEventStreamStatus diff --git a/apps/web/src/components/.pi-map.index.md b/apps/web/src/components/.pi-map.index.md index bd3f56f..1ce81e5 100644 --- a/apps/web/src/components/.pi-map.index.md +++ b/apps/web/src/components/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components ## role -Provides reusable, shared React UI components and utilities for building the web application's interface, including layout shells, data display states, iconography, routing guards, and feedback mechanisms. +Reusable React UI components and authentication guards for the web application's frontend interface. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/components/.pi-map.md b/apps/web/src/components/.pi-map.md index 9bd5ebb..99346c1 100644 --- a/apps/web/src/components/.pi-map.md +++ b/apps/web/src/components/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components index: apps/web/src/components/.pi-map.index.md ## role -Provides reusable, shared React UI components and utilities for building the web application's interface, including layout shells, data display states, iconography, routing guards, and feedback mechanisms. +Reusable React UI components and authentication guards for the web application's frontend interface. ## files - app-shell.tsx | Renders the main application shell layout with navigation, session management, and responsive mobile/desktop views for a React Router-based app. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ../state/session-operations, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./features/session/session-progress-panel, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons - code-editor.tsx | A React component that renders a syntax-highlighted code editor with line numbers using react-simple-code-editor. | exp: CodeEditor | dep: react, react-simple-code-editor, ../utils/language @@ -16,7 +16,7 @@ Provides reusable, shared React UI components and utilities for building the web - toast-rules.test.ts | Unit tests for mapping instance events to toast notification categories and severities | dep: vitest, ./toast-rules, ../types/events - toast-rules.ts | Maps instance events to toast notifications with deduplication logic to prevent spam | exp: func:mapEventToCategory(event: InstanceEventPayload) → string, call:event.event.startsWith, func:mapEventToSeverity(event: InstanceEventPayload) → "info" | "warning" | "error" | "success", func:handleEventToast(event: InstanceEventPayload) → void, call:shouldShowToast, call:toast.info, call:toast.success, call:toast.warning, call:toast.error, func:clearToastDedup() → void, call:lastToastTime.clear | dep: ../state/toast, ../types/events, toast state module, InstanceEventPayload type ## arch -Component-based architecture with functional React patterns, emphasizing composability, type safety, and separation of concerns through presentational components, custom hooks integration, and utility modules for cross-cutting concerns like notifications and routing protection. +Component-based React architecture using functional components with hooks, centralized type-safe utilities (icons, data states), composition patterns for layout (app-shell), and higher-order route protection for auth gating. ## tags toast, state, react, icon, code, event, editor, protected ## symbols diff --git a/apps/web/src/components/features/.pi-map.index.md b/apps/web/src/components/features/.pi-map.index.md index dea3453..7fef5bd 100644 --- a/apps/web/src/components/features/.pi-map.index.md +++ b/apps/web/src/components/features/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features ## role -Reusable React components implementing specific business functionality and UI features for the web application. +Contains reusable UI components that implement specific business features and user-facing functionality across the web application. ## parent index: apps/web/src/components/.pi-map.index.md map: apps/web/src/components/.pi-map.md diff --git a/apps/web/src/components/features/.pi-map.md b/apps/web/src/components/features/.pi-map.md index 013d3a4..c024d0a 100644 --- a/apps/web/src/components/features/.pi-map.md +++ b/apps/web/src/components/features/.pi-map.md @@ -4,10 +4,10 @@ dir: apps/web/src/components/features index: apps/web/src/components/features/.pi-map.index.md ## role -Reusable React components implementing specific business functionality and UI features for the web application. +Contains reusable UI components that implement specific business features and user-facing functionality across the web application. ## files ## arch -Feature-based component organization with domain-specific subdirectories, likely combining presentational and container patterns with hooks for state management. +Feature-based component organization with domain-specific groupings, likely using composition patterns, container/presentational separation, and integration with hooks/state management for feature logic. ## tags - ## symbols diff --git a/apps/web/src/components/features/config-profiles/.pi-map.index.md b/apps/web/src/components/features/config-profiles/.pi-map.index.md index bfe6172..91cf2a9 100644 --- a/apps/web/src/components/features/config-profiles/.pi-map.index.md +++ b/apps/web/src/components/features/config-profiles/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/config-profiles ## role -Provides a complete UI subsystem for managing configuration profiles through list, edit, and mobile-responsive views with CRUD operations. +Provides a complete UI subsystem for managing configuration profiles with desktop and mobile views, supporting CRUD operations, profile relationships, and advanced configuration options. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/config-profiles/.pi-map.md b/apps/web/src/components/features/config-profiles/.pi-map.md index 900d9a2..ae0e606 100644 --- a/apps/web/src/components/features/config-profiles/.pi-map.md +++ b/apps/web/src/components/features/config-profiles/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/web/src/components/features/config-profiles index: apps/web/src/components/features/config-profiles/.pi-map.index.md ## role -Provides a complete UI subsystem for managing configuration profiles through list, edit, and mobile-responsive views with CRUD operations. +Provides a complete UI subsystem for managing configuration profiles with desktop and mobile views, supporting CRUD operations, profile relationships, and advanced configuration options. ## files - ConfigProfileEditorPanel.tsx | React component that renders a form-based editor panel for creating and editing configuration profiles with support for includes, environment variables, runtime hints, files, and mounts. | exp: ConfigProfileEditorPanel | dep: ../../icon, ../git/git-mount-editor, ../../../api/config-profiles, ../../../types, ../../../api/tool-types, React, Icon, GitMountEditor, ConfigProfile, CreateConfigProfileRequest, ResolvedProfile, ProjectWithRepos, ToolType - ConfigProfileListSidebar.tsx | Renders a sidebar component for listing, selecting, creating, and deleting configuration profiles with visual indicators for default status, scope, and includes. | exp: ConfigProfileListSidebar | dep: ../../icon, ../../../api/config-profiles, Icon, ConfigProfile - ConfigProfilesMobileView.tsx | Renders a mobile-responsive CRUD interface for managing configuration profiles with list, detail, and edit views. | exp: ConfigProfilesMobileView | dep: ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../../icon, ../../../api/config-profiles, MobileListView, MobileDetailView, MobileEditView, MobileFAB, Icon, ConfigProfile, CreateConfigProfileRequest ## arch -Compound component pattern with panel/sidebar/mobile view variants, form-based editor with nested array/object state management, and responsive design splitting desktop (sidebar+panel) from mobile (routed views). +Compound component architecture with panel/sidebar split for desktop, dedicated mobile view with state-driven routing, shared state management across list/editor views, and form-based configuration with nested array/object handling for includes, env vars, files, and mounts. ## tags config, mobile, profiles, profile, view, editor, icon, list ## symbols diff --git a/apps/web/src/components/features/git/.pi-map.index.md b/apps/web/src/components/features/git/.pi-map.index.md index 88162db..445acc9 100644 --- a/apps/web/src/components/features/git/.pi-map.index.md +++ b/apps/web/src/components/features/git/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/git ## role -React components providing Git repository management UI including commit, merge, branch operations, and file editing with syntax highlighting. +Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md @@ -10,16 +10,13 @@ map: apps/web/src/components/features/.pi-map.md - ## files - commit-dialog.tsx -- commit-panel.tsx -- file-editor.tsx - git-mount-editor.tsx -- git-toolbar.tsx - merge-dialog.tsx ## links index: apps/web/src/components/features/git/.pi-map.index.md map: apps/web/src/components/features/git/.pi-map.md ## workflows - change git behavior - read: commit-dialog.tsx, commit-panel.tsx, file-editor.tsx + read: commit-dialog.tsx, git-mount-editor.tsx, merge-dialog.tsx ## dirty - diff --git a/apps/web/src/components/features/git/.pi-map.md b/apps/web/src/components/features/git/.pi-map.md index 165fe9d..f1f7aaf 100644 --- a/apps/web/src/components/features/git/.pi-map.md +++ b/apps/web/src/components/features/git/.pi-map.md @@ -4,27 +4,21 @@ dir: apps/web/src/components/features/git index: apps/web/src/components/features/git/.pi-map.index.md ## role -React components providing Git repository management UI including commit, merge, branch operations, and file editing with syntax highlighting. +Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows. ## files - commit-dialog.tsx | A React modal dialog component that displays a diff preview of file changes and allows users to enter a commit message to save those changes. | exp: CommitDialog | dep: react, ../../icon, icon -- commit-panel.tsx | React component that displays git repository changes and provides a form to commit them with a message | exp: CommitPanel | dep: react, ../../../api/git-repositories, api/git-repositories -- file-editor.tsx | A React component that displays and edits repository files with view/edit modes, syntax highlighting, and git commit functionality | exp: FileEditor | dep: react, react-router-dom, ../../../api/client, ../../../state/auth, ../../code-editor, ./commit-dialog, ../../icon, ../../syntax-highlighter, ../../../utils/language, apiClient, useAuth, CodeEditor, CommitDialog, Icon, SyntaxHighlighter, detectLanguage - git-mount-editor.tsx | A React component for editing Git repository mount configurations with URL validation, branch selection, and path mappings. | exp: GitMountEditor | dep: react, ../../icon, ../../../api/config-profiles, icon, config-profiles -- git-toolbar.tsx | React component providing a toolbar UI for Git repository operations including branch management, fetch/pull/push, merge, and status display with polling. | exp: GitToolbar | dep: react, ../../../api/git-repositories, ../../icon, ./merge-dialog - merge-dialog.tsx | A React modal dialog component that allows users to merge Git branches with source/target selection, optional commit message, and loading/error/success state handling. | exp: MergeDialog | dep: react, ../../../api/git-repositories, ../../icon, api/git-repositories, icon ## arch -Feature-based component architecture with modular dialog/panel pattern, form-driven state management, and optimistic UI with polling for async git operations. +Uses modal dialog pattern with form state management, loading/error/success state handling, and controlled inputs for Git-specific operations. ## tags -git, react, commit, dialog, icon, editor, api, merge +dialog, git, react, commit, icon, mount, merge, editor ## symbols - CommitDialog -- CommitPanel -- FileEditor - GitMountEditor -- GitToolbar - MergeDialog ## workflows - change git behavior - read: commit-dialog.tsx, commit-panel.tsx, file-editor.tsx + read: commit-dialog.tsx, git-mount-editor.tsx, merge-dialog.tsx ## dirty - diff --git a/apps/web/src/components/features/mobile/.pi-map.index.md b/apps/web/src/components/features/mobile/.pi-map.index.md index c97d982..2ded892 100644 --- a/apps/web/src/components/features/mobile/.pi-map.index.md +++ b/apps/web/src/components/features/mobile/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/mobile ## role -Provides a complete set of mobile-optimized UI components for building responsive, touch-friendly interfaces across list views, detail views, forms, navigation, modals, and specialized terminal experiences. +Provides mobile-optimized UI components for a responsive web application, covering navigation, lists, detail views, forms, modals, and specialized terminal interfaces. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/mobile/.pi-map.md b/apps/web/src/components/features/mobile/.pi-map.md index decd436..e7d049d 100644 --- a/apps/web/src/components/features/mobile/.pi-map.md +++ b/apps/web/src/components/features/mobile/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components/features/mobile index: apps/web/src/components/features/mobile/.pi-map.index.md ## role -Provides a complete set of mobile-optimized UI components for building responsive, touch-friendly interfaces across list views, detail views, forms, navigation, modals, and specialized terminal experiences. +Provides mobile-optimized UI components for a responsive web application, covering navigation, lists, detail views, forms, modals, and specialized terminal interfaces. ## files - mobile-action-sheet.tsx | Renders a mobile-optimized action sheet modal with title, configurable action buttons, and cancel option. | exp: MobileActionSheetItem, func:MobileActionSheet({ isOpen, onClose, title, actions, }: MobileActionSheetProps), call:useRef, call:useEffect, call:onClose, call:document.addEventListener, call:document.removeEventListener, call:e.stopPropagation, call:actions.map, call:action.onClick | dep: react, ../../icon, icon - mobile-detail-view.tsx | A React component that renders a mobile-optimized detail view with a header (back button, title, edit/delete actions) and a field list supporting multiple value types (text, code, JSON, boolean). | exp: MobileDetailView | dep: ../../icon, react @@ -16,7 +16,7 @@ Provides a complete set of mobile-optimized UI components for building responsiv - mobile-terminal-header.tsx | Renders a mobile-responsive header for a terminal interface with navigation, title, connection status, font size controls, and close actions. | exp: MobileTerminalHeader | dep: react, ../../icon, icon - mobile-terminal-wrapper.tsx | Wraps a terminal component with mobile-specific UI including auto-hiding header, virtual keyboard handling, and special keys interface. | exp: MobileTerminalWrapper | dep: react, ../terminal/terminal, ./mobile-terminal-header, ../terminal/special-keys-strip, ../terminal/special-keys-panel, ../../../hooks/use-mobile-viewport, ../../../hooks/use-virtual-keyboard, ../../../hooks/use-auto-hide, ../../../hooks/use-special-keys ## arch -Follows a feature-based component architecture with consistent mobile-first design patterns including bottom sheets, floating action buttons, auto-hiding headers, virtual keyboard handling, and contextual action menus; each component is self-contained with configurable props for titles, actions, field types, and click handlers, suggesting a reusable component library pattern rather than business-logic containers. +Feature-based component organization with compound mobile UI patterns (action sheets, FABs, bottom sheets, auto-hiding headers) that mirror native mobile app paradigms, using configurable props for customization and likely React Context or hooks for keyboard/virtual terminal state management. ## tags mobile, terminal, view, icon, header, react, sheet, action ## symbols diff --git a/apps/web/src/components/features/notification/.pi-map.index.md b/apps/web/src/components/features/notification/.pi-map.index.md index 6d149a1..0304c08 100644 --- a/apps/web/src/components/features/notification/.pi-map.index.md +++ b/apps/web/src/components/features/notification/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/notification ## role -Provides notification UI components and event-to-toast bridging infrastructure for user-facing alerts and notifications. +Provides notification UI components and event-to-toast bridging logic for the web application. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/notification/.pi-map.md b/apps/web/src/components/features/notification/.pi-map.md index ba6d406..cc5cf77 100644 --- a/apps/web/src/components/features/notification/.pi-map.md +++ b/apps/web/src/components/features/notification/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components/features/notification index: apps/web/src/components/features/notification/.pi-map.index.md ## role -Provides notification UI components and event-to-toast bridging infrastructure for user-facing alerts and notifications. +Provides notification UI components and event-to-toast bridging logic for the web application. ## files - event-toast-bridge.test.tsx | Tests that EventToastBridge correctly filters instance events based on user notification preferences (toast level and muted categories) before triggering toast notifications. | dep: vitest, @testing-library/react, ./event-toast-bridge, ../../../state/events, ../../../api/settings, ../../toast-rules, ../../../types/events, event-toast-bridge, useEventContext, getUserConfig, handleEventToast, InstanceEventPayload - event-toast-bridge.tsx | Bridges event system to toast notifications by filtering events based on user config and processing them through toast rules | exp: func:EventToastBridge() → JSX.Element | null, call:useEventContext, call:useRef, call:useState, call:useEffect, call:getUserConfig() .then((c) => { setConfig({ notification_toast_level: c.notification_toast_level ?? "all", notification_mute_categories: c.notification_mute_categories ?? [], }); }) .catch, call:setConfig, call:window.addEventListener, call:window.removeEventListener, call:processedRef.current.has, call:processedRef.current.add, call:mapEventToCategory, call:mapEventToSeverity, call:config.notification_mute_categories.includes, call:handleEventToast | dep: react, ../../../state/events, ../../toast-rules, ../../../api/settings, useEventContext, toast-rules, settings api @@ -13,7 +13,7 @@ Provides notification UI components and event-to-toast bridging infrastructure f - notification-item.test.tsx | Tests the NotificationItem React component for rendering, styling, and user interaction behaviors. | dep: vitest, @testing-library/react, ./notification-item - notification-item.tsx | Renders a single notification item with expandable metadata, read/dismiss actions, and severity-based icon display. | exp: NotificationItemProps, func:NotificationItem({ notification, onMarkRead, onDismiss, }: NotificationItemProps), call:useState, call:Object.keys, call:formatRelativeTime, call:Object.entries(notification.metadata).map, call:key.replace, call:formatMetadataValue, call:setExpanded, call:onMarkRead, call:onDismiss | dep: react, ../../icon, ../../../utils/time, ../../../api/notifications, ../../../utils/icons, icon, time, notifications, icons ## arch -React component-based architecture with event-driven toast bridging, responsive portal-based dropdowns, and severity-based conditional rendering with comprehensive Vitest test coverage. +React component-based architecture with feature-based directory organization, using portals for dropdown rendering, event-driven toast bridging with user preference filtering, and severity-based visual states. ## tags event, notification, call:use, toast, notifications, listener, react, item ## symbols diff --git a/apps/web/src/components/features/project/.pi-map.index.md b/apps/web/src/components/features/project/.pi-map.index.md index 12fe287..1bd1a10 100644 --- a/apps/web/src/components/features/project/.pi-map.index.md +++ b/apps/web/src/components/features/project/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/project ## role -Provides React components for project management UI including project cards, creation/editing dialogs, and repository settings with CRUD operations. +Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/project/.pi-map.md b/apps/web/src/components/features/project/.pi-map.md index 75f9ce4..5ac9c79 100644 --- a/apps/web/src/components/features/project/.pi-map.md +++ b/apps/web/src/components/features/project/.pi-map.md @@ -4,16 +4,16 @@ dir: apps/web/src/components/features/project index: apps/web/src/components/features/project/.pi-map.index.md ## role -Provides React components for project management UI including project cards, creation/editing dialogs, and repository settings with CRUD operations. +Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations. ## files -- ProjectCard.test.tsx | Unit tests for the ProjectCard component verifying rendering, workspace creation, and delete confirmation behavior. | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./ProjectCard, ../../../types, @testing-library/jest-dom, ProjectCard, types +- ProjectCard.test.tsx | Unit tests for the ProjectCard component verifying rendering, workspace creation, and delete confirmation behavior. | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./ProjectCard, ../../../types, ProjectCard, types - ProjectCard.tsx | Renders an expandable project card displaying project info, repositories, and associated workspaces with CRUD actions. | exp: ProjectCard | dep: ../../icon, ../workspace/workspace-create-form, ../../../types, Icon, WorkspaceCreateForm, ProjectWithRepos, WorkspaceSummary - ProjectDialog.tsx | Renders a modal dialog for creating or editing a project with name/description inputs and cancel/submit actions. | exp: ProjectDialog | dep: ../../icon, React, icon - repositories-settings-tab.test.tsx | Tests the RepositoriesSettingsTab component's repository creation flows including full URL cloning, owner/repo mode with SSH key selection, and SSH URL validation. | dep: @testing-library/react, vitest, ./repositories-settings-tab, ../../../api/git-repositories, ../../../api/ssh-keys, react-router-dom - repositories-settings-tab.tsx | A React component that displays and manages Git repositories for a project, allowing users to list, create, and delete repositories. | exp: RepositoriesSettingsTab | dep: react, react-router-dom, ../../../api/git-repositories, ./repository-create-dialog, ../../icon - repository-create-dialog.tsx | React dialog component for creating or cloning Git repositories with URL validation and SSH key selection. | exp: RepositoryCreateDialog | dep: react, ../../../api/git-repositories, ../../../api/ssh-keys, ../../icon ## arch -Feature-based component architecture with compound component patterns (card + dialog), test co-location, and separation of presentational components from business logic through dialog-based workflows. +React component-based architecture with feature-specific composition, dialog-based modals for forms, and comprehensive test coverage using unit tests for component behavior and user flows. ## tags project, repositories, dialog, react, create, settings, icon, repository ## symbols diff --git a/apps/web/src/components/features/session/.pi-map.md b/apps/web/src/components/features/session/.pi-map.md index 7329737..d3b1133 100644 --- a/apps/web/src/components/features/session/.pi-map.md +++ b/apps/web/src/components/features/session/.pi-map.md @@ -11,7 +11,7 @@ Provides UI components for managing development sessions including creation, lis - session-list.tsx | Renders a list of sessions grouped by active/recent status or as a flat grid, delegating to SessionCard for individual session display. | exp: SessionListProps, func:SessionList({ sessions, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, actionBusyId = null, tunnelHealth = {}, showGrouping = true, activeTitle = "Active Sessions", recentTitle = "Recent Sessions", maxRecent = 5, emptyMessage = "No sessions", }: SessionListProps), call:sessions.filter, call:activeStatuses.includes, call:sessions .filter((s) => recentStatuses.includes(s.status)) .slice, call:recentStatuses.includes, call:sessions.map, call:activeSessions.map, call:recentSessions.map | dep: ../../../api/sessions, ./session-card, Session, SessionCard, InstanceHealth - session-progress-panel.tsx | Renders a panel displaying active and recently completed session operations with step-by-step progress indicators and dismissible notifications. | exp: func:SessionProgressPanel(), call:useSessionOperations, call:useEventContext, call:useEffect, call:updateOperationFromEvent, call:operations.filter, call:Date.now, call:visibleOperations.map, call:dismissOperation | dep: react, ../../../state/session-operations, ../../../state/events, ../../icon, useSessionOperations, useEventContext, Icon ## arch -React component composition with feature-specific grouping, responsive design patterns (mobile/desktop layouts), and status-driven conditional rendering with delegated sub-components. +Feature-based component architecture with compound component pattern (SessionCard/SessionList/SessionProgressPanel), controlled forms with validation, optimistic UI updates for inline editing, responsive design with mobile/desktop layout variants, and compound action menus using dropdowns/sheets. ## tags session, call:use, call:on, api, card, call:set, event, mobile ## symbols diff --git a/apps/web/src/components/features/settings/.pi-map.index.md b/apps/web/src/components/features/settings/.pi-map.index.md index 4c1b178..71bec9a 100644 --- a/apps/web/src/components/features/settings/.pi-map.index.md +++ b/apps/web/src/components/features/settings/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/settings ## role -Provides the UI components for the application's settings interface, enabling users to configure preferences across multiple categorized tabs. +Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/settings/.pi-map.md b/apps/web/src/components/features/settings/.pi-map.md index fd30d95..4193e13 100644 --- a/apps/web/src/components/features/settings/.pi-map.md +++ b/apps/web/src/components/features/settings/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/web/src/components/features/settings index: apps/web/src/components/features/settings/.pi-map.index.md ## role -Provides the UI components for the application's settings interface, enabling users to configure preferences across multiple categorized tabs. +Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout. ## files - GeneralSettingsTab.tsx | Renders a general settings tab with theme, git, editor, and notification preferences using shared outlet context | exp: GeneralSettingsTab | dep: react-router-dom, ../../icon, ../../../api/settings - settings-tab-layout.tsx | Renders a tabbed settings layout with a sidebar navigation and active tab highlighting based on current URL path. | exp: SettingsTabLayout | dep: react, react-router-dom ## arch -Tab-based layout using React Router outlet context for state sharing, with URL-driven navigation and sidebar-based tab switching pattern. +Uses a tabbed layout pattern with URL-based routing for navigation state, shared React context for data access, and compound component structure separating layout shell from content panels. ## tags settings, tab, general, layout, react, renders, router, dom ## symbols diff --git a/apps/web/src/components/features/ssh-keys/.pi-map.index.md b/apps/web/src/components/features/ssh-keys/.pi-map.index.md index b4cefb0..ef625c2 100644 --- a/apps/web/src/components/features/ssh-keys/.pi-map.index.md +++ b/apps/web/src/components/features/ssh-keys/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/ssh-keys ## role -Provides UI components for SSH key lifecycle management including creation and list operations with cryptographic signing/verification features. +Provides UI components for managing SSH keys, including creation and listing with cryptographic operations. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/ssh-keys/.pi-map.md b/apps/web/src/components/features/ssh-keys/.pi-map.md index 0f7bcd9..b27e367 100644 --- a/apps/web/src/components/features/ssh-keys/.pi-map.md +++ b/apps/web/src/components/features/ssh-keys/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/web/src/components/features/ssh-keys index: apps/web/src/components/features/ssh-keys/.pi-map.index.md ## role -Provides UI components for SSH key lifecycle management including creation and list operations with cryptographic signing/verification features. +Provides UI components for managing SSH keys, including creation and listing with cryptographic operations. ## files - SSHKeyCreateForm.tsx | Renders a form for creating/generating a new SSH key with name input and submit button. | exp: SSHKeyCreateForm | dep: ../../icon, React, Icon component - SSHKeyList.tsx | Renders a list of SSH keys with signing and verification capabilities | exp: SSHKeyList | dep: ../../icon, ../../data-states, ../../../api/ssh-keys, Icon, EmptyState, ErrorState, SSHKey type ## arch -Feature-based component composition with form/list separation pattern, likely using React functional components with hooks for state management and API integration. +Feature-based component organization with presentational components following single-responsibility pattern (form vs list separation). ## tags sshkey, form, list, create, ssh, icon, renders, keys ## symbols diff --git a/apps/web/src/components/features/terminal/.pi-map.index.md b/apps/web/src/components/features/terminal/.pi-map.index.md index 18d09f7..643418b 100644 --- a/apps/web/src/components/features/terminal/.pi-map.index.md +++ b/apps/web/src/components/features/terminal/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/terminal ## role -Provides cross-platform terminal UI components with session management, special key input, and WebSocket-backed xterm.js integration for web-based terminal emulation. +Provides cross-platform terminal UI components for desktop and mobile with session management, special key input, and xterm.js WebSocket connectivity. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/terminal/.pi-map.md b/apps/web/src/components/features/terminal/.pi-map.md index 314de6e..7d1a0ec 100644 --- a/apps/web/src/components/features/terminal/.pi-map.md +++ b/apps/web/src/components/features/terminal/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components/features/terminal index: apps/web/src/components/features/terminal/.pi-map.index.md ## role -Provides cross-platform terminal UI components with session management, special key input, and WebSocket-backed xterm.js integration for web-based terminal emulation. +Provides cross-platform terminal UI components for desktop and mobile with session management, special key input, and xterm.js WebSocket connectivity. ## files - DesktopTerminalView.tsx | Renders a desktop-optimized terminal view with session tabs, fullscreen mode, font controls, and reset confirmation dialog | exp: DesktopTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../../api/terminal, React, TerminalComponent, TerminalSessionTabs, TerminalSession type - MobileTerminalView.tsx | Renders a mobile-optimized terminal interface with toolbar, session tabs, terminal output, and special keys input controls. | exp: MobileTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../icon, ./special-keys-strip, ./special-keys-panel, ../../../hooks/use-special-keys, ../../../api/terminal @@ -14,7 +14,7 @@ Provides cross-platform terminal UI components with session management, special - terminal-session-tabs.tsx | Renders a tabbed interface for managing multiple terminal sessions with selection, creation, renaming, and close confirmation features. | exp: TerminalSessionInfo, TerminalSessionTabsProps, TerminalSessionTabs | dep: react, React - terminal.tsx | React component that renders an interactive xterm.js terminal with WebSocket connectivity, mobile touch support, flow control, heartbeat monitoring, and reconnection logic. | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys, React, use-special-keys hook ## arch -Feature-based component architecture with platform-specific view splitting (desktop/mobile), compound component pattern for terminal controls, custom hook-driven WebSocket/xterm.js integration with heartbeat/reconnection logic, and Jest-tested tabbed session management. +Component-based architecture with platform-specific view variants (Desktop/Mobile), shared session tabs state management, modular special key input panels, and a core terminal component handling WebSocket lifecycle with heartbeat/reconnection logic. ## tags terminal, special, keys, session, react, tabs, view, renders ## symbols diff --git a/apps/web/src/components/features/tool-workshop/.pi-map.index.md b/apps/web/src/components/features/tool-workshop/.pi-map.index.md index 1064fb6..2c4a9b9 100644 --- a/apps/web/src/components/features/tool-workshop/.pi-map.index.md +++ b/apps/web/src/components/features/tool-workshop/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/tool-workshop ## role -Provides a complete CRUD interface for managing tool types in a "Tool Workshop" feature with desktop and mobile views +Provides a complete UI for managing custom tool types in a "Tool Workshop" interface with list, edit, and mobile-responsive views. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/tool-workshop/.pi-map.md b/apps/web/src/components/features/tool-workshop/.pi-map.md index f978cc8..c4c2d6f 100644 --- a/apps/web/src/components/features/tool-workshop/.pi-map.md +++ b/apps/web/src/components/features/tool-workshop/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/web/src/components/features/tool-workshop index: apps/web/src/components/features/tool-workshop/.pi-map.index.md ## role -Provides a complete CRUD interface for managing tool types in a "Tool Workshop" feature with desktop and mobile views +Provides a complete UI for managing custom tool types in a "Tool Workshop" interface with list, edit, and mobile-responsive views. ## files - ToolTypeEditorPanel.tsx | Renders a form panel for creating or editing tool types with support for compose, dockerfile, and manifest definition types | exp: ToolTypeFormState, ToolTypeEditorPanel | dep: ../../icon, ../tool/manifest-editor, ../../../api/tool-types, ../../../api/tool-definitions, React, Icon, ManifestEditor - ToolTypeListSidebar.tsx | Renders a sidebar component for listing, selecting, creating, and deleting tool types in a "Tool Workshop" interface. | exp: ToolTypeListSidebar | dep: ../../icon, ../../../api/tool-types, React, Icon component, ToolType type - ToolWorkshopMobileView.tsx | Renders a mobile-responsive view for managing tool types with list, detail, and edit modes | exp: MobileView, ToolWorkshopMobileView | dep: ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../../../api/tool-types, ./ToolTypeEditorPanel, MobileListView, MobileDetailView, MobileEditView, MobileFAB, ToolType, ToolTypeFormState ## arch -Split-pane layout with sidebar list navigation, detail/edit panel, and mobile-responsive view switching using conditional rendering patterns +Uses a split-pane sidebar/detail panel pattern with dedicated mobile breakpoint handling, separating list navigation from form editing concerns across three specialized view components. ## tags tool, mobile, type, view, types, list, panel, editor ## symbols diff --git a/apps/web/src/components/features/tool/.pi-map.index.md b/apps/web/src/components/features/tool/.pi-map.index.md index cbf5e65..122f0cb 100644 --- a/apps/web/src/components/features/tool/.pi-map.index.md +++ b/apps/web/src/components/features/tool/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/tool ## role -Provides UI components for managing containerized development tools, including instance lifecycle operations, manifest editing, and workspace-integrated tool launching. +Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, and workspace-integrated tool launching. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/tool/.pi-map.md b/apps/web/src/components/features/tool/.pi-map.md index d7cbf6f..45fe261 100644 --- a/apps/web/src/components/features/tool/.pi-map.md +++ b/apps/web/src/components/features/tool/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components/features/tool index: apps/web/src/components/features/tool/.pi-map.index.md ## role -Provides UI components for managing containerized development tools, including instance lifecycle operations, manifest editing, and workspace-integrated tool launching. +Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, and workspace-integrated tool launching. ## files - instance-list.tsx | Displays and manages a list of tool instances with CRUD operations, real-time status updates, and configuration profile selection. | exp: InstanceList | dep: react, react-router-dom, ../../icon, ../../../api/sessions, ../../../api/tool-types, ../session/create-session-form, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/events, ../../../state/sessions, icon, api/sessions, api/tool-types, api/config-profiles, api/ssh-keys, state/events, state/sessions - manifest-editor.tsx | A React component that provides a form-based UI for editing container tool definition manifests with fields for base images, packages, user config, environment variables, scripts, mounts, and runtime settings, including compilation preview functionality. | exp: ManifestEditor | dep: react, ../../icon, ../../../utils/errors, ../../../api/tool-definitions, icon, errors, tool-definitions @@ -13,7 +13,7 @@ Provides UI components for managing containerized development tools, including i - tool-starter.tsx | A React component that provides a workspace-first UI for selecting tool types, config profiles, and SSH keys to create and start a new tool instance/session. | exp: ToolStarterProps, func:ToolStarter({ workspace, onStarted, onCancel, }: ToolStarterProps), call:useSessions, call:useSessionOperations, call:useState, call:useEffect, call:listToolTypes, call:setToolTypes, call:setToolTypesError, call:setToolTypesLoading, call:load, call:setProfiles, call:setSelectedProfileId, call:setProfilesLoading, call:listConfigProfiles, call:data.find, call:listSSHKeys, call:setSshKeys, call:setSelectedSshKeyIds, call:console.error, call:setSshKeysLoading, call:sshKeys.find, call:useCallback, call:setError, call:setStarting, call:createInstance, call:displayName.trim, call:startInstance, call:addOrUpdateSession, call:startOperation, call:onStarted, call:setSelectedToolTypeId, call:toolTypes.find, call:setDisplayName, call:toolTypes.map, call:setNameEdited, call:profiles.map, call:sshKeys.map, call:selectedSshKeyIds.includes, call:prev.filter | dep: react, ../../icon, ../../../api/tool-types, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/sessions, ../../../state/session-operations, ../../../types/workspace, ../../../api/sessions, icon, tool-types, config-profiles, ssh-keys, sessions, session-operations, workspace - tools-bottom-sheet.tsx | Renders a mobile bottom sheet navigation menu for tools with active route highlighting | exp: ToolsBottomSheet | dep: react-router-dom, ../../icon, icon ## arch -Feature-based component composition with modal/bottom-sheet navigation patterns, real-time status integration, and form-driven configuration management with preview capabilities. +Feature-based component architecture with modal/sheet UI patterns, form-driven configuration editing, and workspace-contextual tool orchestration with mobile-responsive navigation. ## tags tool, call:set, types, call:use, api, start, ssh, icon ## symbols diff --git a/apps/web/src/components/features/workspace/.pi-map.index.md b/apps/web/src/components/features/workspace/.pi-map.index.md index 64f3a66..6a15a2e 100644 --- a/apps/web/src/components/features/workspace/.pi-map.index.md +++ b/apps/web/src/components/features/workspace/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/workspace ## role -Provides React components for workspace UI features including creation, navigation, file management, Git integration, tool management, and settings display. +Provides React UI components for workspace management, navigation, and detail views in a web-based development environment. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md diff --git a/apps/web/src/components/features/workspace/.pi-map.md b/apps/web/src/components/features/workspace/.pi-map.md index 147ecbd..3b26997 100644 --- a/apps/web/src/components/features/workspace/.pi-map.md +++ b/apps/web/src/components/features/workspace/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/components/features/workspace index: apps/web/src/components/features/workspace/.pi-map.index.md ## role -Provides React components for workspace UI features including creation, navigation, file management, Git integration, tool management, and settings display. +Provides React UI components for workspace management, navigation, and detail views in a web-based development environment. ## files - workspace-card.tsx | React card component that displays workspace information with status, metadata, and action buttons | exp: WorkspaceCardProps, func:WorkspaceCard({ workspace, loading = false, onStartTool, onSync, onDelete, }: WorkspaceCardProps), call:onStartTool, call:onSync, call:onDelete | dep: react-router-dom, ../../icon, ./workspace-instance-chips, ../../../types/workspace - workspace-create-form.tsx | React form component for creating workspaces with cascading project/repository/branch selectors and support for both contextual and standalone modes | exp: WorkspaceCreateFormProps, func:WorkspaceCreateForm({ onSubmit, onCancel, defaultProjectId, defaultRepoId, }: WorkspaceCreateFormProps), call:Boolean, call:useState, call:useGitRepo, call:useEffect, call:git.branches.includes, call:setSelectedBranch, call:setIsNewBranch, call:useCallback, call:listProjects, call:setProjects, call:setSelectedProject, call:setError, call:setFetchingProjects, call:loadProjects, call:setRepos, call:setSelectedRepo, call:listRepositories, call:loadRepos, call:setNewBranchName, call:e.preventDefault, call:name.trim, call:newBranchName.trim, call:setSubmitting, call:createWorkspaceTopLevel, call:onSubmit, call:projects.map, call:repos.map, call:setName, call:handleBranchChange, call:git.branches.map | dep: react, ../../icon, ../../../api/projects, ../../../api/git-repositories, ../../../api/workspaces, ../../../hooks/use-git-repo, ../../../types, icon, api/projects, api/git-repositories, api/workspaces, hooks/use-git-repo, types @@ -13,11 +13,11 @@ Provides React components for workspace UI features including creation, navigati - workspace-git-panel.tsx | Renders a Git panel for a workspace detail page that displays branch selection and commit history. | exp: func:WorkspaceGitPanel({ workspaceId }: WorkspaceGitPanelProps), call:useWorkspaceGit, call:checkout, call:branches.map, call:history.map, call:commit.hash.slice | dep: ../../../hooks/use-workspace-git, react, use-workspace-git hook - workspace-header.tsx | Renders a workspace header component displaying project info with navigation links to history and settings pages. | exp: WorkspaceHeader | dep: react-router-dom, ../../icon, icon - workspace-instance-chips.tsx | Displays running tool instances for a workspace as clickable status chips with external links. | exp: func:WorkspaceInstanceChips({ workspaceId, }: WorkspaceInstanceChipsProps), call:useState, call:useEffect, call:listWorkspaceInstances, call:setInstances, call:setLoading, call:load, call:instances.map, call:e.stopPropagation | dep: react, ../../../api/workspace-instances, ../../../api/sessions -- workspace-settings-panel.tsx | Displays read-only workspace information in a settings panel on the workspace detail page. | exp: func:WorkspaceSettingsPanel({ workspace, }: WorkspaceSettingsPanelProps) | dep: ../../../types/workspace, react +- workspace-settings-panel.tsx | Displays a read-only settings panel showing workspace information details | exp: func:WorkspaceSettingsPanel({ workspace, }: WorkspaceSettingsPanelProps) | dep: ../../../types/workspace, React, Workspace type - workspace-tab-bar.tsx | Renders desktop and mobile tab bar components for workspace navigation with files, git, tools, and settings tabs. | exp: WorkspaceTab, func:WorkspaceTabBar({ active, onChange }: WorkspaceTabBarProps), call:TABS.map, call:onChange, func:WorkspaceMobileTabBar({ active, onChange, }: WorkspaceTabBarProps), call:TABS.map, call:onChange | dep: ../../icon, react - workspace-tools-panel.tsx | Renders a tools management panel for a workspace that displays running tool instances and allows starting new tools via a modal | exp: func:WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps), call:useWorkspaceInstances, call:useState, call:setShowModal, call:instances.map, call:e.stopPropagation, call:refresh | dep: react, ../../icon, ../tool/tool-starter, ../../../hooks/use-workspace-instances, ../../../types/workspace, icon, tool-starter, use-workspace-instances, workspace types ## arch -Feature-based component composition with page-specific layout components (header, panels, tab bar) and functional sub-components, following a detail-page architecture with tabbed navigation and modal-based tool interactions. +Feature-based component organization with page-specific composite components (header/detail/settings) and reusable atomic pieces (cards, chips, forms), following a panel/tab architecture for workspace detail layout. ## tags workspace, call:set, call:use, panel, git, branch, react, call:on ## symbols diff --git a/apps/web/src/hooks/.pi-map.index.md b/apps/web/src/hooks/.pi-map.index.md index 0074078..999581e 100644 --- a/apps/web/src/hooks/.pi-map.index.md +++ b/apps/web/src/hooks/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/hooks ## role -Provides reusable React custom hooks that encapsulate UI state management, side effects, API integrations, and domain-specific logic for the web application frontend. +A collection of custom React hooks providing reusable state management, API integration, and UI behavior logic for the web application. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md @@ -20,7 +20,6 @@ map: apps/web/src/.pi-map.md - use-notifications.test.tsx - use-notifications.ts - use-projects.ts -- use-repo-workspace.ts - use-special-keys.ts - use-ssh-keys.ts - use-start-tool.ts diff --git a/apps/web/src/hooks/.pi-map.md b/apps/web/src/hooks/.pi-map.md index ec1f586..a5d09ac 100644 --- a/apps/web/src/hooks/.pi-map.md +++ b/apps/web/src/hooks/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/hooks index: apps/web/src/hooks/.pi-map.index.md ## role -Provides reusable React custom hooks that encapsulate UI state management, side effects, API integrations, and domain-specific logic for the web application frontend. +A collection of custom React hooks providing reusable state management, API integration, and UI behavior logic for the web application. ## files - use-async-data.ts | A custom React hook that manages asynchronous data fetching with loading, error, and ready states, plus a manual reload capability. | exp: func:useAsyncData(fetcher: () => Promise, deps: React.DependencyList) → UseAsyncDataResult, call:useState, call:useCallback, call:setStatus, call:setError, call:fetcher, call:setData, call:load, call:useEffect | dep: react - use-auto-hide.ts | A React custom hook that automatically hides an element after a specified timeout and provides manual controls for showing, hiding, and toggling visibility. | exp: func:useAutoHide(options: AutoHideOptions), call:useState, call:useRef, call:Date.now, call:useCallback, call:setIsVisible, call:clearTimeout, call:setTimeout, call:hide, call:show, call:useEffect | dep: react @@ -17,7 +17,6 @@ Provides reusable React custom hooks that encapsulate UI state management, side - use-notifications.test.tsx | Tests the useNotifications custom React hook with mocked API calls, covering optimistic updates, polling behavior, and error handling. | dep: vitest, @testing-library/react, ./use-notifications, ../state/notifications, ../api/notifications, use-notifications - use-notifications.ts | Custom React hook that provides access to notification state and ensures it's used within a NotificationProvider | exp: func:useNotifications(), call:useContext, raise:Error | dep: react, ../state/notifications - use-projects.ts | Custom React hook for managing project CRUD operations, workspace management, and dialog state for a project management UI | exp: useProjects | dep: react, ../api/projects, ../api/workspaces, ./use-async-data, ../types -- use-repo-workspace.ts | A React custom hook that manages workspace state for a repository-based project, including loading project data, repositories, branches, git status, and tool types while synchronizing selection state with URL search parameters. | exp: Project, useRepoWorkspace | dep: react, react-router-dom, ../api/client, ../api/git-repositories, ../api/tool-types - use-special-keys.ts | Maps special keys and modifier+character combinations to ANSI escape sequences for terminal input simulation. | exp: SpecialKey, ModifierKey, func:getSequenceWithModifier(key: SpecialKey, activeModifier: ModifierKey | null) → { sequence: string; clearModifier: boolean } | null, call:char.toLowerCase, func:applyModifierToChar(char: string, modifier: ModifierKey) → string | null, call:char.toLowerCase - use-ssh-keys.ts | A React custom hook that manages SSH key operations including listing, generating, deleting, signing payloads, and verifying signatures. | exp: useSSHKeys | dep: react, ../api/ssh-keys, ./use-async-data - use-start-tool.ts | React hook for managing the state and API calls to create and start a tool instance on a workspace. | exp: UseStartToolResult, func:useStartTool() → UseStartToolResult, call:useState, call:useCallback, call:setStarting, call:setError, call:createInstance, call:startInstance | dep: react, ../api/sessions, ../types/workspace @@ -32,9 +31,9 @@ Provides reusable React custom hooks that encapsulate UI state management, side - use-workspace-instances.ts | Custom React hook for managing workspace instances with CRUD operations, loading states, and error handling. | exp: UseWorkspaceInstancesResult, func:useWorkspaceInstances(workspaceId: string) → UseWorkspaceInstancesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceInstances, call:setInstances, call:createWorkspaceInstance, call:refresh, call:useEffect | dep: react, ../api/workspace-instances, ../api/sessions - use-workspaces.ts | Custom React hook that fetches and manages workspace data with loading and error states. | exp: UseWorkspacesResult, func:useWorkspaces(projectId: string, repoId: string) → UseWorkspacesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaces, call:listAllWorkspaces, call:setWorkspaces, call:useEffect, call:refresh | dep: react, ../api/workspaces, ../types/workspace ## arch -Layered utility hooks following React composition patterns, with separation between generic UI behavior hooks (async data, auto-hide, viewport, theme), infrastructure hooks (SSE, terminal, keyboard), and domain-specific data/operation hooks (workspace, git, SSH, projects, instances) that wrap API calls with loading/error states and optimistic updates. +Follows a feature-based composition pattern where each hook encapsulates a specific domain concern (data fetching, CRUD operations, terminal/session management, UI interactions), often combining React state with API calls, side effects, and provider context integration. ## tags -call:set, call:use, workspace, react, state, terminal, api, git +call:set, call:use, workspace, react, state, terminal, api, callback ## symbols - useAsyncData - useAutoHide diff --git a/apps/web/src/pages/.pi-map.index.md b/apps/web/src/pages/.pi-map.index.md index eef69f8..534123c 100644 --- a/apps/web/src/pages/.pi-map.index.md +++ b/apps/web/src/pages/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/pages ## role -Contains all top-level page components for the web application, serving as route endpoints that compose domain-specific UI for workspaces, projects, sessions, git, settings, and other core features. +Contains top-level page components that serve as route endpoints for the web application, each rendering distinct feature areas of the developer workspace platform. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/pages/.pi-map.md b/apps/web/src/pages/.pi-map.md index d2a6a86..1c874a5 100644 --- a/apps/web/src/pages/.pi-map.md +++ b/apps/web/src/pages/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/pages index: apps/web/src/pages/.pi-map.index.md ## role -Contains all top-level page components for the web application, serving as route endpoints that compose domain-specific UI for workspaces, projects, sessions, git, settings, and other core features. +Contains top-level page components that serve as route endpoints for the web application, each rendering distinct feature areas of the developer workspace platform. ## files - ConfigProfilesPage.tsx | Renders a responsive configuration profiles management page with sidebar list and editor panel for desktop, and a dedicated mobile view for creating, editing, and managing config profiles. | exp: ConfigProfilesPage | dep: react, ../components/data-states, ../hooks/use-mobile-viewport, ../hooks/use-config-profiles, ../components/features/config-profiles/ConfigProfileListSidebar, ../components/features/config-profiles/ConfigProfileEditorPanel, ../components/features/config-profiles/ConfigProfilesMobileView - DashboardPage.test.tsx | Tests the DashboardPage (HomePage) component's rendering, loading states, and error handling with retry functionality | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./DashboardPage, ../state/sessions, ../state/session-operations, ../api/dashboard, ../api/sessions, ../api/projects, ../api/git-repositories, ../api/tool-types @@ -25,7 +25,7 @@ Contains all top-level page components for the web application, serving as route - WorkspaceDetailPage.tsx | Renders a workspace detail page with tab-based navigation for files, git, tools, and settings panels, with mobile-responsive layout. | exp: func:WorkspaceDetailPage(), call:useParams, call:useState, call:useMobileViewport, call:useWorkspaces, call:workspaces.find | dep: react, react-router-dom, ../hooks/use-workspaces, ../hooks/use-mobile-viewport, ../components/features/workspace/workspace-detail-header, ../components/features/workspace/workspace-tab-bar, ../components/features/workspace/workspace-file-panel, ../components/features/workspace/workspace-git-panel, ../components/features/workspace/workspace-tools-panel, ../components/features/workspace/workspace-settings-panel, use-workspaces, use-mobile-viewport, workspace-detail-header, workspace-tab-bar, workspace-file-panel, workspace-git-panel, workspace-tools-panel, workspace-settings-panel - WorkspacesPage.tsx | Renders a responsive workspaces management page with separate mobile (list/detail/create views) and desktop (grid with cards) layouts, supporting CRUD operations and tool launching. | exp: func:WorkspacesPage(), call:useMobileViewport, call:useState, call:useWorkspaces, call:useWorkspaceActions, call:actions.delete, call:actions.sync, call:setMobileView, call:refresh, call:setStartWorkspace, call:handleDelete, call:setSelectedWorkspace, call:workspaces.map, call:workspaces.find, call:e.stopPropagation, call:setShowCreate | dep: react, ../components/icon, ../hooks/use-mobile-viewport, ../hooks/use-workspaces, ../hooks/use-workspace-actions, ../components/features/workspace/workspace-card, ../components/features/workspace/workspace-create-form, ../components/features/mobile/mobile-list-view, ../components/features/mobile/mobile-detail-view, ../components/features/mobile/mobile-fab, ../components/features/tool/tool-starter, ../types/workspace ## arch -Follows a page-based routing architecture with responsive mobile/desktop split layouts, tabbed navigation patterns, CRUD-heavy screens with polling/health checks, and test coverage for critical pages using API mocking. +Follows a React Router-based page-level architecture with responsive dual-layout patterns (mobile/desktop), tabbed navigation, CRUD operations with API integration, polling mechanisms, and nested outlet routing for complex settings/workspace detail views. ## tags page, components, workspace, features, react, mobile, settings, hooks ## symbols diff --git a/apps/web/src/state/.pi-map.index.md b/apps/web/src/state/.pi-map.index.md index e650614..ebcc25a 100644 --- a/apps/web/src/state/.pi-map.index.md +++ b/apps/web/src/state/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/state ## role -Centralized React state management layer providing application-wide contexts for authentication, real-time events, notifications, session operations, user sessions, and toast notifications. +Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/state/.pi-map.md b/apps/web/src/state/.pi-map.md index 5213a8a..a6b7f5f 100644 --- a/apps/web/src/state/.pi-map.md +++ b/apps/web/src/state/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web/src/state index: apps/web/src/state/.pi-map.index.md ## role -Centralized React state management layer providing application-wide contexts for authentication, real-time events, notifications, session operations, user sessions, and toast notifications. +Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback. ## files - auth.tsx | Provides React authentication context for managing user session state with login status, user data, and session refresh/logout operations. | exp: AuthProvider, useAuth | dep: react, ../api/client, ../types - events.tsx | Creates a React context provider for real-time event data with connection status and reconnection tracking | exp: func:EventProvider({ children }: { children: React.ReactNode }), call:useEvents, call:useMemo, func:useEventContext(), call:useContext | dep: react, ../hooks/use-events, ../types/events @@ -13,7 +13,7 @@ Centralized React state management layer providing application-wide contexts for - sessions.tsx | Provides a React context that manages user sessions state with server polling, local CRUD operations, and loading/error handling. | exp: SessionsContextType, SessionsProvider, useSessions | dep: react, ../api/sessions - toast.tsx | Implements a React toast notification system with context-based state management, auto-dismiss timers, and imperative API shortcuts. | exp: ToastSeverity, ToastItem, toast, func:ToastProvider({ children }: { children: React.ReactNode }), call:useState, call:useRef, call:useCallback, call:setToasts, call:prev.filter, call:timersRef.current.get, call:clearTimeout, call:timersRef.current.delete, call:Date.now, call:setTimeout, call:removeToast, call:timersRef.current.set, call:useEffect, call:addToast, func:useToast(), call:useContext, raise:Error | dep: react, React ## arch -Context-based state architecture using React Context API with providers for dependency injection, combining optimistic updates, server polling, event-driven updates, and imperative APIs for cross-cutting concerns. +React Context API pattern with separate providers per domain, combining optimistic updates, server polling, event-driven state synchronization, and imperative APIs for cross-cutting concerns like toast notifications. ## tags call:use, context, toast, provider, react, call:set, notification, operations ## symbols diff --git a/apps/web/src/styles/.pi-map.index.md b/apps/web/src/styles/.pi-map.index.md index 157fb88..a70c37e 100644 --- a/apps/web/src/styles/.pi-map.index.md +++ b/apps/web/src/styles/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/styles ## role -Houses the complete CSS styling system for a web application, providing global styles, design tokens, syntax highlighting, and utility classes. +Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, syntax highlighting, and utility classes. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/styles/.pi-map.md b/apps/web/src/styles/.pi-map.md index ab1a9c3..8d2a86b 100644 --- a/apps/web/src/styles/.pi-map.md +++ b/apps/web/src/styles/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/web/src/styles index: apps/web/src/styles/.pi-map.index.md ## role -Houses the complete CSS styling system for a web application, providing global styles, design tokens, syntax highlighting, and utility classes. +Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, syntax highlighting, and utility classes. ## files - global.css | Defines global CSS styles for a web application shell layout, navigation, cards, forms, dialogs, settings pages, and responsive design patterns. | dep: CSS custom properties (CSS variables: --border, --panel, --brand, --muted, --ink, --bg, --danger, --success, --warning, --font-size-xs, --font-size-sm, --space-2, --space-3, --space-4, --space-5) - syntax-highlight.css | Stylesheet for a syntax highlighting component with toolbar, line numbers, code display, and Prism.js theme integration | dep: Prism.js - tokens.css | Defines a comprehensive CSS design token system with light/dark themes, spacing scales, breakpoints, and fluid typography for a web application. - utilities.css | Provides a comprehensive responsive CSS utility system including layout primitives, mobile-first breakpoints, terminal styling, session management UI, and touch-target accessibility patterns for a web application. | dep: CSS custom properties (var(--space-*), var(--border), var(--bg), var(--primary), var(--danger), etc.), xterm.js (terminal rendering) ## arch -Layered CSS architecture using design tokens (tokens.css), global base styles (global.css), component-specific styles (syntax-highlight.css), and utility-first responsive utilities (utilities.css) with light/dark theme support and mobile-first breakpoints. +CSS custom properties-based design token architecture with light/dark theme support, mobile-first responsive breakpoint system, utility-first CSS patterns, and modular separation of concerns across global, component-specific, token, and utility layers. ## tags space, var(, global, css, web, application, syntax, defines ## symbols diff --git a/apps/web/src/styles/pages/.pi-map.index.md b/apps/web/src/styles/pages/.pi-map.index.md index ecd54db..0450269 100644 --- a/apps/web/src/styles/pages/.pi-map.index.md +++ b/apps/web/src/styles/pages/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/styles/pages ## role -Contains page-specific CSS stylesheets for distinct application views in the web frontend. +Contains page-specific CSS stylesheets for individual application views in the web frontend. ## parent index: apps/web/src/styles/.pi-map.index.md map: apps/web/src/styles/.pi-map.md @@ -11,7 +11,6 @@ map: apps/web/src/styles/.pi-map.md ## files - git-history.css - projects.css -- repo-workspace.css - sessions.css - ssh-keys.css - workspace-detail.css diff --git a/apps/web/src/styles/pages/.pi-map.md b/apps/web/src/styles/pages/.pi-map.md index bd7cdd6..9cd5f2f 100644 --- a/apps/web/src/styles/pages/.pi-map.md +++ b/apps/web/src/styles/pages/.pi-map.md @@ -4,19 +4,18 @@ dir: apps/web/src/styles/pages index: apps/web/src/styles/pages/.pi-map.index.md ## role -Contains page-specific CSS stylesheets for distinct application views in the web frontend. +Contains page-specific CSS stylesheets for individual application views in the web frontend. ## files - git-history.css | Stylesheet for a Git history visualization page with commit list, branch selector, and detail panel layout | dep: CSS custom properties (var(--border), var(--panel), var(--ink), var(--brand), var(--muted)) - projects.css | Stylesheet for a projects page UI featuring expandable project toggles, repository listings, workspace grids, and repository creation radio controls. | dep: CSS custom properties (variables) -- repo-workspace.css | Stylesheet for a repository workspace UI with git integration, file management, and code editing components | dep: CSS custom properties (variables), IBM Plex Mono font - sessions.css | Stylesheet for session management UI components including cards, dropdowns, forms, and responsive mobile layouts. | dep: CSS custom properties/variables (var(--border), var(--panel), var(--text), var(--space-*), var(--danger), var(--color-border)) - ssh-keys.css | Styles a responsive SSH key list component that stacks vertically on mobile and switches to horizontal layout on larger screens | dep: CSS custom properties (var(--space-3), var(--space-2), var(--space-4), var(--bg), var(--border)) - workspace-detail.css | Stylesheet for a workspace detail page with tabbed interface including files, git, tools, and settings views, plus a workspace creation form | dep: CSS custom properties (variables for colors, spacing, typography) - workspaces.css | Stylesheet for a workspaces page featuring a responsive grid of workspace cards with status badges, hover effects, and mobile adaptations. | dep: CSS custom properties (var(--space-*), var(--border), var(--panel), var(--muted), var(--success), var(--warning), var(--danger)) ## arch -Modular page-scoped styling architecture with responsive design patterns (mobile-first breakpoints, grid/flex layouts, component-based organization) and consistent UI system conventions (cards, tabs, forms, badges, hover states). +Modular page-scoped styling using dedicated CSS files per route/page, with responsive design patterns (mobile-first breakpoints, grid/flex layouts) and component-oriented class naming. ## tags -var(, workspace, stylesheet, git, space, page, detail, history +var(, workspace, stylesheet, space, git, page, detail, history ## symbols - ## workflows diff --git a/apps/web/src/test/.pi-map.md b/apps/web/src/test/.pi-map.md index e429fb4..315f32a 100644 --- a/apps/web/src/test/.pi-map.md +++ b/apps/web/src/test/.pi-map.md @@ -8,7 +8,7 @@ Provides shared testing infrastructure and configuration for the web application ## files - setup.ts | Configures Vitest testing environment with Jest DOM matchers for enhanced DOM assertions | dep: @testing-library/jest-dom/vitest ## arch -Minimal utility module pattern - single configuration file exporting Vitest setup with Jest DOM matchers integration +Minimal utility layer using Vitest with Jest DOM matchers for browser-like DOM assertion capabilities ## tags dom, vitest, jest, setup, configures, testing, environment, matchers ## symbols diff --git a/apps/web/src/types/.pi-map.index.md b/apps/web/src/types/.pi-map.index.md index b77a684..fc929e7 100644 --- a/apps/web/src/types/.pi-map.index.md +++ b/apps/web/src/types/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/types ## role -Defines shared TypeScript type definitions and interfaces for data models used across the web application. +Provides shared TypeScript type definitions for event-driven communication and workspace management across the web application. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/types/.pi-map.md b/apps/web/src/types/.pi-map.md index 45d8f2e..fc98968 100644 --- a/apps/web/src/types/.pi-map.md +++ b/apps/web/src/types/.pi-map.md @@ -4,12 +4,12 @@ dir: apps/web/src/types index: apps/web/src/types/.pi-map.index.md ## role -Defines shared TypeScript type definitions and interfaces for data models used across the web application. +Provides shared TypeScript type definitions for event-driven communication and workspace management across the web application. ## files - events.ts | Defines TypeScript interfaces for instance event metadata and payload structures used in event-driven system communication. | exp: InstanceEventMetadata, InstanceEventPayload - workspace.ts | Defines TypeScript interfaces for workspace data models, requests, and sync results in a workspace management feature. | exp: Workspace, CreateWorkspaceRequest, SyncResult ## arch -Simple barrel-style type package with domain-oriented interface modules (events, workspace) for compile-time type safety and API contract enforcement. +Pure type declaration layer using TypeScript interfaces for compile-time contracts, with no runtime logic or dependencies. ## tags workspace, event, instance, metadata, payload, sync, defines, typescript ## symbols diff --git a/apps/web/src/utils/.pi-map.index.md b/apps/web/src/utils/.pi-map.index.md index 3fb2712..dca5290 100644 --- a/apps/web/src/utils/.pi-map.index.md +++ b/apps/web/src/utils/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/utils ## role -Shared utility functions providing cross-cutting concerns for error handling, icon types, syntax highlighting, and time formatting across the web application. +Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative time formatting across the web application. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/utils/.pi-map.md b/apps/web/src/utils/.pi-map.md index 9291bab..94b73a1 100644 --- a/apps/web/src/utils/.pi-map.md +++ b/apps/web/src/utils/.pi-map.md @@ -4,14 +4,14 @@ dir: apps/web/src/utils index: apps/web/src/utils/.pi-map.index.md ## role -Shared utility functions providing cross-cutting concerns for error handling, icon types, syntax highlighting, and time formatting across the web application. +Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative time formatting across the web application. ## files - errors.ts | Extracts a human-readable error message from an unknown error object, specifically handling axios-style errors with string or array detail fields | exp: extractErrorMessage - icons.ts | Re-exports the IconName type from the icon component for external consumption | dep: ../components/icon - language.ts | Maps file extensions to Prism.js language identifiers and provides utilities for syntax highlighting with lazy language loading. | exp: detectLanguage, highlightCode, loadLanguage | dep: prismjs - time.ts | Formats a date string into a human-readable relative time string (e.g., "2h ago", "3d ago") | exp: func:formatRelativeTime(dateStr: string) → string, call:Math.max, call:Math.floor, call:now.getTime, call:date.getTime ## arch -Flat barrel-style utility module with pure functions, lazy loading for heavy dependencies (Prism), and thin abstraction layers over third-party libraries. +Lightweight functional utilities organized by domain concern with no internal dependencies, using pattern matching (error types), lazy loading (language imports), and pure string/date transformations. ## tags time, language, error, message, errors, string, relative, human ## symbols diff --git a/docs/.pi-map.index.md b/docs/.pi-map.index.md index 334db75..2ca5a0f 100644 --- a/docs/.pi-map.index.md +++ b/docs/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs ## role -Central documentation hub and knowledge base for the Headquarter platform, providing navigation and access to all project guides, API references, and technical resources. +Provides user-facing documentation and knowledge base for the Headquarter platform. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/docs/.pi-map.md b/docs/.pi-map.md index a81d6fc..f9ec4aa 100644 --- a/docs/.pi-map.md +++ b/docs/.pi-map.md @@ -4,11 +4,11 @@ dir: docs index: docs/.pi-map.index.md ## role -Central documentation hub and knowledge base for the Headquarter platform, providing navigation and access to all project guides, API references, and technical resources. +Provides user-facing documentation and knowledge base for the Headquarter platform. ## files - README.md | Serves as the main index and navigation hub for the Headquarter platform documentation, organizing links to feature guides, API docs, architecture, deployment, and development resources. ## arch -Static documentation structure using markdown-based content organization with hierarchical topic grouping (features, API, architecture, deployment, development) and a single-entry-point index pattern. +Static documentation site using markdown files organized hierarchically with a central README index. ## tags readme, serves, main, index, navigation, hub, headquarter, platform ## symbols diff --git a/docs/api/.pi-map.index.md b/docs/api/.pi-map.index.md index 91d683a..b12edba 100644 --- a/docs/api/.pi-map.index.md +++ b/docs/api/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/api ## role -Provides comprehensive API documentation for a FastAPI-based Headquarter REST API covering authentication, project management, repositories, SSH keys, terminal access, tool types, and user profiles. +Provides comprehensive API documentation for the Headquarter platform's REST and WebSocket endpoints, covering authentication, project management, infrastructure tooling, and interactive terminal access. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/api/.pi-map.md b/docs/api/.pi-map.md index b52ad8f..114b0e0 100644 --- a/docs/api/.pi-map.md +++ b/docs/api/.pi-map.md @@ -4,7 +4,7 @@ dir: docs/api index: docs/api/.pi-map.index.md ## role -Provides comprehensive API documentation for a FastAPI-based Headquarter REST API covering authentication, project management, repositories, SSH keys, terminal access, tool types, and user profiles. +Provides comprehensive API documentation for the Headquarter platform's REST and WebSocket endpoints, covering authentication, project management, infrastructure tooling, and interactive terminal access. ## files - README.md | API documentation for a FastAPI-based Headquarter REST API describing authentication, endpoints, and testing | dep: FastAPI, REST API, session cookie authentication, JSON - auth.md | Documents OAuth2 authentication API endpoints for Authentik-based login flow with session management | dep: Authentik, OAuth2, session cookies @@ -16,7 +16,7 @@ Provides comprehensive API documentation for a FastAPI-based Headquarter REST AP - tool-types.md | Documents REST API endpoints for managing Docker Compose-based tool types with template variable support - users.md | Documents a REST API for user profile management, avatar uploads, and user-configurable settings. ## arch -Standard REST API documentation structure organized by domain/resource with OAuth2/Authentik authentication, WebSocket for real-time terminal sessions, and git-backed configuration profile system with merge/override semantics. +Documentation-as-code structure organized by domain entity with FastAPI-style endpoint documentation, following standard HTTP method conventions (GET/POST/PUT/DELETE) with WebSocket extensions for real-time features, and OAuth2/session-based authentication patterns. ## tags api, documents, rest, tool, terminal, endpoints, management, profile ## symbols diff --git a/docs/architecture/.pi-map.index.md b/docs/architecture/.pi-map.index.md index 10fb05c..31f98c2 100644 --- a/docs/architecture/.pi-map.index.md +++ b/docs/architecture/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/architecture ## role -Documents the technical architecture and system design for the "Headquarter" full-stack application across all layers. +Provides technical documentation for the "Headquarter" application's system architecture across all layers. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/architecture/.pi-map.md b/docs/architecture/.pi-map.md index eaadcf5..c1d930f 100644 --- a/docs/architecture/.pi-map.md +++ b/docs/architecture/.pi-map.md @@ -4,14 +4,14 @@ dir: docs/architecture index: docs/architecture/.pi-map.index.md ## role -Documents the technical architecture and system design for the "Headquarter" full-stack application across all layers. +Provides technical documentation for the "Headquarter" application's system architecture across all layers. ## files - backend.md | Documents the layered backend architecture of a FastAPI application with authentication, real-time monitoring, and service management. | dep: FastAPI, SQLAlchemy, asyncpg, Pydantic, Alembic, httpx, pytest, Authentik, Docker - database.md | Documents the PostgreSQL database schema, relationships, and operational procedures for a "Headquarter" application managing users, projects, git repositories, SSH keys, user configs, and tool types. | dep: PostgreSQL, SQLAlchemy ORM, Alembic, Authentik, Docker Compose - deployment.md | Documents the containerized deployment architecture, infrastructure components, and operational strategies for a web application called "Headquarter" | dep: Docker, Traefik, React, Vite, nginx, FastAPI, Python 3.11, PostgreSQL 15, Redis 7, Authentik, PgBouncer, alembic - frontend.md | Documents the frontend architecture for a React-based SPA called "Headquarter" with modular design patterns, real-time SSE events, and OAuth authentication. | dep: React, React Router, Vite, TypeScript, Vitest, React Testing Library, Authentik OAuth ## arch -Markdown-based architectural decision records (ADRs) organized by domain (backend/frontend/database/deployment) using layered architecture patterns for a FastAPI+React+PostgreSQL stack with real-time capabilities and containerized deployment. +Documentation-as-code approach with markdown files organized by architectural concern (backend, database, deployment, frontend) covering a full-stack FastAPI/React/PostgreSQL system with real-time features and containerized deployment. ## tags documents, backend, architecture, fastapi, application, alembic, authentik, database ## symbols diff --git a/docs/architecture/decisions/.pi-map.index.md b/docs/architecture/decisions/.pi-map.index.md index dc02f43..d343065 100644 --- a/docs/architecture/decisions/.pi-map.index.md +++ b/docs/architecture/decisions/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/architecture/decisions ## role -Documents key architectural decisions for the project, providing rationale and context for technology choices around authentication and database access patterns. +Documents key architectural decisions made during the project's development to provide historical context and rationale for technology choices. ## parent index: docs/architecture/.pi-map.index.md map: docs/architecture/.pi-map.md diff --git a/docs/architecture/decisions/.pi-map.md b/docs/architecture/decisions/.pi-map.md index a65bc2e..4e52b3e 100644 --- a/docs/architecture/decisions/.pi-map.md +++ b/docs/architecture/decisions/.pi-map.md @@ -4,12 +4,12 @@ dir: docs/architecture/decisions index: docs/architecture/decisions/.pi-map.index.md ## role -Documents key architectural decisions for the project, providing rationale and context for technology choices around authentication and database access patterns. +Documents key architectural decisions made during the project's development to provide historical context and rationale for technology choices. ## files - adr-001-session-auth.md | Documents the architectural decision to use session-based authentication with HMAC-signed httpOnly cookies for OAuth2 flow instead of JWT alternatives | dep: Authentik, Traefik, OAuth2, HMAC-SHA256 - adr-002-async-sqlalchemy.md | Architecture decision record documenting the choice to use SQLAlchemy 2.0 with async PostgreSQL via asyncpg for an async-capable Python application | dep: SQLAlchemy 2.0, PostgreSQL, asyncpg, Alembic ## arch -Lightweight ADR (Architecture Decision Record) pattern using Markdown files with sequential numbering, each capturing context, decision, consequences, and alternatives considered for major technical choices. +Lightweight ADR (Architecture Decision Record) pattern using numbered, markdown-formatted documents with consistent structure covering context, decision, consequences, and status. ## tags adr, async, session, sqlalchemy, decision, hmac, oauth2, 001 ## symbols diff --git a/docs/deployment/.pi-map.index.md b/docs/deployment/.pi-map.index.md index 3826d95..a2e8f1e 100644 --- a/docs/deployment/.pi-map.index.md +++ b/docs/deployment/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/deployment ## role -Provides deployment documentation and operational guides for installing, configuring, and running the Headquarter application in production environments. +Provides operational documentation for deploying, configuring, and securing the Headquarter application in production environments. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/deployment/.pi-map.md b/docs/deployment/.pi-map.md index 4ff0f6f..5e5b7e1 100644 --- a/docs/deployment/.pi-map.md +++ b/docs/deployment/.pi-map.md @@ -4,14 +4,14 @@ dir: docs/deployment index: docs/deployment/.pi-map.index.md ## role -Provides deployment documentation and operational guides for installing, configuring, and running the Headquarter application in production environments. +Provides operational documentation for deploying, configuring, and securing the Headquarter application in production environments. ## files - authentik.md | Documents how to configure Authentik as an OAuth2 provider for the Headquarter application | dep: Authentik, Headquarter, OAuth2, Python - docker.md | Provides deployment instructions for a multi-container "Headquarter" application using Docker Compose in development and production environments | dep: Docker, Docker Compose, FastAPI, React, Vite, PostgreSQL, Redis, Traefik, Alembic, Authentik, Let's Encrypt - environment.md | Documents all environment variables used by the Headquarter application, including their defaults, construction rules, and security requirements. - traefik.md | Documents how to configure and deploy Traefik as a reverse proxy with automatic HTTPS for a "Headquarter" application using Docker Compose and Docker labels. | dep: Traefik, Docker, Docker Compose, Let's Encrypt, DNS ## arch -Documentation-as-code approach using Markdown files organized by infrastructure component (reverse proxy, identity provider, container orchestration, configuration management), following a modular microservices deployment pattern with Docker Compose. +Documentation-as-code pattern covering containerized deployment (Docker Compose), reverse proxy routing (Traefik), identity federation (Authentik OAuth2), and environment-based configuration management. ## tags docker, authentik, headquarter, traefik, application, documents, environment, configure ## symbols diff --git a/docs/development/.pi-map.index.md b/docs/development/.pi-map.index.md index e15d0e6..a8c2548 100644 --- a/docs/development/.pi-map.index.md +++ b/docs/development/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/development ## role -Developer onboarding and contribution standards documentation for the Headquarter full-stack web application project. +Developer documentation hub providing setup, contribution, quality, and testing guidelines for the Headquarter full-stack project. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/development/.pi-map.md b/docs/development/.pi-map.md index b234ccc..dbef3c4 100644 --- a/docs/development/.pi-map.md +++ b/docs/development/.pi-map.md @@ -4,14 +4,14 @@ dir: docs/development index: docs/development/.pi-map.index.md ## role -Developer onboarding and contribution standards documentation for the Headquarter full-stack web application project. +Developer documentation hub providing setup, contribution, quality, and testing guidelines for the Headquarter full-stack project. ## files - contributing.md | Provides guidelines and workflows for contributing to the Headquarter project | dep: git, ruff, mypy, pytest, npm, React, TypeScript, Python - quality-gates.md | Defines mandatory quality gates (linting, type checking, testing, security, build) for backend (Python) and frontend (TypeScript) code before merge, including CI/CD integration and IDE setup. | dep: ruff, mypy, pytest, bandit, safety, TypeScript, ESLint, Vitest, pre-commit, npm, make - setup.md | Provides step-by-step instructions for setting up a full-stack development environment for a FastAPI/React application with PostgreSQL, Redis, and optional Authentik authentication. | dep: Python 3.11+, Node.js 18+, PostgreSQL 15+, Redis 7+, Git, Docker, FastAPI, React, Alembic, uvicorn, npm, Authentik - testing.md | Documents testing practices, frameworks, and guidelines for both backend (Python/pytest) and frontend (React/Vitest) of a web application called "Headquarter" | dep: pytest, pytest-asyncio, httpx, factory-boy, vitest, react-testing-library, jsdom, playwright, asyncpg, postgresql, authentik, github-actions ## arch -Documentation-as-code approach with structured markdown files covering environment setup, quality assurance gates, testing standards, and contribution workflows for a FastAPI/React/PostgreSQL/Redis stack. +Static markdown documentation organized by concern (setup, contributing, quality, testing) with explicit FastAPI/Python backend and React/TypeScript frontend toolchain boundaries. ## tags pytest, react, testing, contributing, npm, typescript, python, quality ## symbols diff --git a/docs/features/.pi-map.index.md b/docs/features/.pi-map.index.md index 60128a6..8b481ab 100644 --- a/docs/features/.pi-map.index.md +++ b/docs/features/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/features ## role -User-facing documentation for features of the "Headquarter" developer platform application, covering authentication, project/repository management, git tools, web-based terminals, and workspace editing. +User-facing documentation for features of a web-based development platform called "Headquarter" that provides project management, Git repositories, containerized development tools, and browser-based IDE capabilities. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/features/.pi-map.md b/docs/features/.pi-map.md index d58e9c6..9219fd1 100644 --- a/docs/features/.pi-map.md +++ b/docs/features/.pi-map.md @@ -4,7 +4,7 @@ dir: docs/features index: docs/features/.pi-map.index.md ## role -User-facing documentation for features of the "Headquarter" developer platform application, covering authentication, project/repository management, git tools, web-based terminals, and workspace editing. +User-facing documentation for features of a web-based development platform called "Headquarter" that provides project management, Git repositories, containerized development tools, and browser-based IDE capabilities. ## files - auth.md | Documents the OAuth2 authentication system using Authentik for the Headquarter application | dep: Authentik, OAuth2, session cookies - git-history.md | Documents a Git history visualization UI feature showing commit graphs, branch filtering, and commit details with diff viewing | dep: Git, repositories API, branch selector UI component, diff syntax highlighter @@ -17,7 +17,7 @@ User-facing documentation for features of the "Headquarter" developer platform a - tool-types.md | Documents how to define, manage, and use development tool types in Headquarter using Docker Compose templates | dep: Docker Compose, YAML, git, VS Code Server, Jupyter Notebook - workspace.md | Documents a repository workspace file browser interface with repository/branch selection, file tree navigation, file viewing with syntax highlighting, and quick editing capabilities. | dep: Git, Repositories API, Git History, Git Repositories ## arch -Flat markdown documentation structure organized by feature domain, with each file independently documenting a specific subsystem; no code or cross-references, purely descriptive end-user guides for a containerized development environment platform. +Feature-oriented documentation structure with each markdown file independently documenting a distinct system capability; content follows a consistent pattern of overview, usage instructions, and UI element descriptions; docs cover a full-stack developer platform spanning authentication (OAuth2/Authentik), Git operations, Docker-based tooling, and in-browser terminals/editors. ## tags git, terminal, documents, functionality, headquarter, application, ssh, tool ## symbols diff --git a/docs/guides/.pi-map.index.md b/docs/guides/.pi-map.index.md index 3cb6775..c9b5407 100644 --- a/docs/guides/.pi-map.index.md +++ b/docs/guides/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/guides ## role -Provides user-facing documentation for advanced configuration features +Provides user-facing documentation for advanced configuration features of the platform. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/guides/.pi-map.md b/docs/guides/.pi-map.md index 9a880c1..0befb2c 100644 --- a/docs/guides/.pi-map.md +++ b/docs/guides/.pi-map.md @@ -4,11 +4,11 @@ dir: docs/guides index: docs/guides/.pi-map.index.md ## role -Provides user-facing documentation for advanced configuration features +Provides user-facing documentation for advanced configuration features of the platform. ## files - config-profiles-git-mounts.md | Documents how to mount files and directories from git repositories into tool instances via config profiles | dep: Git, container runtime (bind mounts), glob pattern matching ## arch -Simple documentation-as-code with markdown files organized by feature topic +Flat markdown documentation structure with topic-specific guides. ## tags git, config, profiles, mounts, documents, mount, directories, repositories ## symbols diff --git a/docs/superpowers/.pi-map.index.md b/docs/superpowers/.pi-map.index.md index c0946a3..eeb0793 100644 --- a/docs/superpowers/.pi-map.index.md +++ b/docs/superpowers/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers ## role -Documentation directory for special capabilities or advanced features of the project. +Documentation directory for specialized or advanced capabilities/features of the project. ## parent index: docs/.pi-map.index.md map: docs/.pi-map.md diff --git a/docs/superpowers/.pi-map.md b/docs/superpowers/.pi-map.md index 449a95b..cd2d16b 100644 --- a/docs/superpowers/.pi-map.md +++ b/docs/superpowers/.pi-map.md @@ -4,10 +4,10 @@ dir: docs/superpowers index: docs/superpowers/.pi-map.index.md ## role -Documentation directory for special capabilities or advanced features of the project. +Documentation directory for specialized or advanced capabilities/features of the project. ## files ## arch -N/A (empty directory - no files to analyze) +Static documentation storage with no executable code architecture; likely contains markdown or text files describing enhanced functionality. ## tags - ## symbols diff --git a/docs/superpowers/plans/.pi-map.index.md b/docs/superpowers/plans/.pi-map.index.md index fa7caa2..d849815 100644 --- a/docs/superpowers/plans/.pi-map.index.md +++ b/docs/superpowers/plans/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers/plans ## role -Contains dated implementation planning documents that specify step-by-step technical approaches for major system features and infrastructure setup. +Contains implementation planning documents for core infrastructure, authentication, database modeling, and UI feature development. ## parent index: docs/superpowers/.pi-map.index.md map: docs/superpowers/.pi-map.md diff --git a/docs/superpowers/plans/.pi-map.md b/docs/superpowers/plans/.pi-map.md index 1e484ce..e4fd3ce 100644 --- a/docs/superpowers/plans/.pi-map.md +++ b/docs/superpowers/plans/.pi-map.md @@ -4,14 +4,14 @@ dir: docs/superpowers/plans index: docs/superpowers/plans/.pi-map.index.md ## role -Contains dated implementation planning documents that specify step-by-step technical approaches for major system features and infrastructure setup. +Contains implementation planning documents for core infrastructure, authentication, database modeling, and UI feature development. ## files - 2024-05-16-docker-infrastructure.md | Defines a step-by-step implementation plan for setting up a complete Docker-based development infrastructure with multi-service orchestration including PostgreSQL, Redis, Traefik, Authentik, FastAPI backend, and React frontend. | dep: Docker, Docker Compose, Make, Python 3.11, Node.js 20, PostgreSQL, Redis, Traefik, Authentik, FastAPI, React, Vite, nginx, alembic, uvicorn, SQLAlchemy, pydantic, structlog - 2026-05-17-auth-oauth.md | Implementation plan for adding Authentik-backed OIDC authentication with JWT access tokens and DB-backed refresh tokens to a FastAPI application | dep: FastAPI, SQLAlchemy, Alembic, python-jose, httpx, pytest, Authentik, PostgreSQL - 2026-05-17-database-models.md | Define an implementation plan for building SQLAlchemy 2.0 async database models, Alembic migrations, and seed data for a FastAPI backend. | dep: SQLAlchemy 2.x, asyncpg, Alembic, pytest, pytest-asyncio, Pydantic Settings, PostgreSQL, FastAPI - 2026-05-24-session-branch-selection.md | Implementation plan for replacing free-text branch input with a dropdown of available branches and adding "Create new branch" functionality in a session creation form | dep: React, TypeScript, FastAPI, Python, Git subprocess, Pydantic, API client ## arch -Chronological planning document store using markdown files with ISO date prefixes; each plan follows a consistent structure of problem statement, proposed solution, implementation steps, and verification criteria, serving as architectural decision records and work specifications before code implementation. +Markdown-based technical specification documents using date-prefixed naming convention, each detailing phased implementation steps for specific system capabilities with technology stack integration points. ## tags 05, fastapi, 2026, implementation, plan, docker, postgresql, authentik ## symbols diff --git a/docs/superpowers/specs/.pi-map.index.md b/docs/superpowers/specs/.pi-map.index.md index 27cb6b4..7667df9 100644 --- a/docs/superpowers/specs/.pi-map.index.md +++ b/docs/superpowers/specs/.pi-map.index.md @@ -2,7 +2,7 @@ dir: docs/superpowers/specs ## role -Contains technical design specifications for planned system features, serving as architectural decision records and implementation blueprints for authentication and session management capabilities. +Contains design specification documents for planned system features, serving as architectural decision records for authentication and session management capabilities. ## parent index: docs/superpowers/.pi-map.index.md map: docs/superpowers/.pi-map.md diff --git a/docs/superpowers/specs/.pi-map.md b/docs/superpowers/specs/.pi-map.md index 67932f1..3427747 100644 --- a/docs/superpowers/specs/.pi-map.md +++ b/docs/superpowers/specs/.pi-map.md @@ -4,12 +4,12 @@ dir: docs/superpowers/specs index: docs/superpowers/specs/.pi-map.index.md ## role -Contains technical design specifications for planned system features, serving as architectural decision records and implementation blueprints for authentication and session management capabilities. +Contains design specification documents for planned system features, serving as architectural decision records for authentication and session management capabilities. ## files - 2026-05-17-auth-oauth-design.md | Design document for implementing OAuth2/OIDC authentication with Authentik, internal JWT access tokens, and database-backed refresh token rotation. | dep: Authentik, JWKS, JWT, database/PostgreSQL, cookies, pytest, mypy, ruff - 2026-05-24-session-branch-selection-design.md | Design document for replacing free-text branch input with a dropdown of available branches and adding the ability to create a new local branch at clone time in a session creation UI. | dep: React/TypeScript frontend, Python/FastAPI backend, Git, API client, ToolInstance database model ## arch -Markdown-based design documentation following a date-prefixed naming convention, with each spec detailing problem statements, proposed solutions, data models, API contracts, and security considerations for discrete feature increments. +Markdown-based technical design documentation following a chronological naming convention (YYYY-MM-DD-feature-name-design.md) with no executable code, using a lightweight specification format for capturing requirements, decisions, and implementation plans before development. ## tags design, 2026, 05, branch, session, document, authentik, jwt ## symbols diff --git a/docs/templates/.pi-map.md b/docs/templates/.pi-map.md index 85854c5..589983a 100644 --- a/docs/templates/.pi-map.md +++ b/docs/templates/.pi-map.md @@ -10,7 +10,7 @@ Provides standardized markdown templates for consistent documentation of APIs, a - architecture.md | Provides a markdown template for documenting system architecture with standardized sections for components, data flow, technology stack, and operational considerations. - feature-doc.md | Markdown template for documenting software features with standardized sections ## arch -Template library pattern using structured markdown files with predefined section conventions to enforce documentation uniformity and reduce authoring overhead. +Template-based documentation system using structured markdown files with predefined sections to enforce uniformity and completeness in technical documentation. ## tags standardized, markdown, template, documenting, api, sections, architecture, provides ## symbols diff --git a/e2e/.pi-map.index.md b/e2e/.pi-map.index.md index 3d0be48..691fda2 100644 --- a/e2e/.pi-map.index.md +++ b/e2e/.pi-map.index.md @@ -2,7 +2,7 @@ dir: e2e ## role -Provides automated end-to-end browser testing for the headquarter application using Playwright. +End-to-end testing package for the "headquarter" project using Playwright to validate full application workflows across multiple browsers. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/e2e/.pi-map.md b/e2e/.pi-map.md index 7e07c04..cb81d13 100644 --- a/e2e/.pi-map.md +++ b/e2e/.pi-map.md @@ -4,12 +4,12 @@ dir: e2e index: e2e/.pi-map.index.md ## role -Provides automated end-to-end browser testing for the headquarter application using Playwright. +End-to-end testing package for the "headquarter" project using Playwright to validate full application workflows across multiple browsers. ## files - package.json | Defines an end-to-end testing package for a "headquarter" project using Playwright | dep: @playwright/test - playwright.config.ts | Configures Playwright test runner with parallel execution, CI-specific settings, and multi-browser project definitions. | dep: @playwright/test ## arch -Test automation framework with parallel execution, CI-optimized configuration, and cross-browser testing matrix (Chromium/Firefox/WebKit). +Standard Playwright testing architecture with configuration-driven parallel test execution, CI-optimized settings, and multi-browser project matrix (Chromium/Firefox/WebKit) for cross-browser compatibility testing. ## tags package, test, end, project, playwright, @playwright, playwright.config, defines ## symbols diff --git a/e2e/tests/.pi-map.index.md b/e2e/tests/.pi-map.index.md index 1ee988c..ec6ff1a 100644 --- a/e2e/tests/.pi-map.index.md +++ b/e2e/tests/.pi-map.index.md @@ -2,7 +2,7 @@ dir: e2e/tests ## role -End-to-end test suite for authentication flows using Playwright +End-to-end testing suite for authentication flows using Playwright. ## parent index: e2e/.pi-map.index.md map: e2e/.pi-map.md diff --git a/e2e/tests/.pi-map.md b/e2e/tests/.pi-map.md index 35acc3a..696f3d5 100644 --- a/e2e/tests/.pi-map.md +++ b/e2e/tests/.pi-map.md @@ -4,11 +4,11 @@ dir: e2e/tests index: e2e/tests/.pi-map.index.md ## role -End-to-end test suite for authentication flows using Playwright +End-to-end testing suite for authentication flows using Playwright. ## files - login.spec.ts | End-to-end tests for authentication flow using Playwright, verifying login page accessibility, OAuth redirect behavior, and protected route enforcement. | dep: @playwright/test ## arch -Specification-style testing with Playwright page object model, covering OAuth redirect flows and route protection guards +Spec-based test organization with Playwright test runner, following page-object pattern for browser automation and scenario-based test isolation. ## tags end, login.spec, tests, authentication, flow, playwright, verifying, login ## symbols