fix: remove explicit repo mount from pi-agent manifest and derive workspace name from remote URL
The pi-agent manifest still declared an explicit repo mount with
{{WORKSPACE_NAME}}, making the mount target dependent on tool config. The
instance service now synthesizes the repo mount, so the manifest no longer
needs the explicit mount.
- Add Alembic migration 2026_06_15_090500 to remove the source_type: repo
mount from the built-in pi-agent manifest
- Add _get_repository_mount_name() helper to derive the workspace directory
name from the repository remote URL (matching git clone behavior) and
fall back to the user-provided repository name
- Use the helper for WORKSPACE_NAME/REPO_NAME in manifest, legacy dockerfile,
and legacy compose template paths
- Update unit tests for the new migration and helper
Quality gates:
- pytest tests/unit: 218 passed
- ruff: clean on changed files
- mypy: clean on changed files
- alembic heads: single head
This commit is contained in:
Developer
+1
-1
@@ -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 backend API, web frontend, PostgreSQL, Redis, and Traefik reverse proxy integration.
|
||||
Infrastructure and deployment configuration for a self-hosted project management platform with containerized services, SSO integration, and reverse proxy support.
|
||||
## parent
|
||||
-
|
||||
## children
|
||||
|
||||
+2
-2
@@ -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 backend API, web frontend, PostgreSQL, Redis, and Traefik reverse proxy integration.
|
||||
Infrastructure and deployment configuration package for a self-hosted project management platform with containerized services, SSO integration, and reverse proxy support.
|
||||
## 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 environment-driven configuration, externalized secrets via .env files, and reverse proxy pattern for TLS-terminated multi-domain deployment.
|
||||
Docker Compose-based microservices architecture with environment-driven configuration, separating PostgreSQL database, Redis cache, API backend, and web frontend behind Traefik reverse proxy with TLS termination.
|
||||
## tags
|
||||
docker, redis, git, application, postgresql, compose, traefik, project
|
||||
## symbols
|
||||
|
||||
+1
-1
@@ -7,7 +7,7 @@ index: apps/.pi-map.index.md
|
||||
Contains the main application entry points and executable modules for the project.
|
||||
## files
|
||||
## arch
|
||||
Typically follows a modular or microservices architecture where each subdirectory represents an independent deployable application sharing common libraries or frameworks.
|
||||
Typically follows a modular architecture where each subdirectory represents a separate deployable application or service, often with shared libraries extracted to common packages.
|
||||
## tags
|
||||
-
|
||||
## symbols
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api
|
||||
|
||||
## role
|
||||
Self-hosted FastAPI backend API that manages projects, git repositories, and development tools via Docker instances
|
||||
FastAPI-based backend API that manages projects, git repositories, and development tools through Docker-orchestrated instances with PostgreSQL persistence.
|
||||
## parent
|
||||
index: apps/.pi-map.index.md
|
||||
map: apps/.pi-map.md
|
||||
|
||||
+2
-2
@@ -4,7 +4,7 @@ dir: apps/api
|
||||
index: apps/api/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Self-hosted FastAPI backend API that manages projects, git repositories, and development tools via Docker instances
|
||||
FastAPI-based backend API that manages projects, git repositories, and development tools through Docker-orchestrated instances with PostgreSQL persistence.
|
||||
## 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 @@ Self-hosted FastAPI backend API that manages projects, git repositories, and dev
|
||||
- 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
|
||||
Async Python backend with FastAPI, PostgreSQL via Alembic migrations, Docker socket integration, Cloudflare tunneling, and multi-stage containerized deployment with uv dependency management
|
||||
Async Python/FastAPI service using multi-stage Docker containers with Alembic migrations, uv dependency management, and Docker socket access for container orchestration.
|
||||
## tags
|
||||
docker, alembic, python, database, fastapi, postgresql, asyncpg, uvicorn
|
||||
## symbols
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/alembic
|
||||
|
||||
## role
|
||||
Database migration infrastructure for the API application using Alembic with async SQLAlchemy support.
|
||||
Database migration infrastructure for the API application, providing version-controlled schema changes with async SQLAlchemy support.
|
||||
## parent
|
||||
index: apps/api/.pi-map.index.md
|
||||
map: apps/api/.pi-map.md
|
||||
|
||||
@@ -4,12 +4,12 @@ dir: apps/api/alembic
|
||||
index: apps/api/alembic/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Database migration infrastructure for the API application using Alembic with async SQLAlchemy support.
|
||||
Database migration infrastructure for the API application, providing version-controlled schema changes with async SQLAlchemy support.
|
||||
## files
|
||||
- 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-based migration generation with environment configuration for async database operations, following standard Alembic project structure with Mako templating for reproducible schema change scripts.
|
||||
Alembic migration framework with Mako templating for generating migration scripts, configured for async SQLAlchemy operations.
|
||||
## tags
|
||||
migrations, run, sqlalchemy, async, alembic, call:context.configure, call:context.begin, transaction
|
||||
## symbols
|
||||
|
||||
@@ -2,12 +2,14 @@
|
||||
dir: apps/api/alembic/versions
|
||||
|
||||
## role
|
||||
Database schema version control and incremental migration management for the API application, tracking the evolution of tables supporting users, SSH keys, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, notifications, and terminal sessions.
|
||||
Database schema version control and migration management for the API application, tracking incremental schema changes from initial tables through advanced features like workspaces, manifests, and monitoring.
|
||||
## parent
|
||||
index: apps/api/alembic/.pi-map.index.md
|
||||
map: apps/api/alembic/.pi-map.md
|
||||
## children
|
||||
-
|
||||
- apps/api/alembic/versions/.ruff_cache
|
||||
index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
|
||||
map: apps/api/alembic/versions/.ruff_cache/.pi-map.md
|
||||
## files
|
||||
- 0001_initial_schema.py
|
||||
- 0002_refresh_tokens.py
|
||||
@@ -50,6 +52,7 @@ map: apps/api/alembic/.pi-map.md
|
||||
- 2026_06_13_make_clone_mode_nullable.py
|
||||
- 2026_06_14_104415_add_tool_type_home_directory.py
|
||||
- 2026_06_14_182955_fix_pi_agent_home_directory_mount.py
|
||||
- 2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py
|
||||
- 398082499c30_add_tool_config_fields.py
|
||||
- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py
|
||||
- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py
|
||||
@@ -68,5 +71,7 @@ map: apps/api/alembic/versions/.pi-map.md
|
||||
read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
|
||||
- change versions config
|
||||
read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
|
||||
- explore versions subdirectories
|
||||
index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
|
||||
## dirty
|
||||
-
|
||||
|
||||
@@ -4,7 +4,7 @@ dir: apps/api/alembic/versions
|
||||
index: apps/api/alembic/versions/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Database schema version control and incremental migration management for the API application, tracking the evolution of tables supporting users, SSH keys, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, notifications, and terminal sessions.
|
||||
Database schema version control and migration management for the API application, tracking incremental schema changes from initial tables through advanced features like workspaces, manifests, and monitoring.
|
||||
## 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
|
||||
@@ -46,7 +46,8 @@ Database schema version control and incremental migration management for the API
|
||||
- 2026_06_01_add_workspaces.py | Alembic database migration that creates a workspaces table with foreign keys to git_repositories and users, adds indexes, and adds a workspace_id column to tool_instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, call:sa.UniqueConstraint, call:op.create_index, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
|
||||
- 2026_06_13_make_clone_mode_nullable.py | Alembic database migration that makes the `clone_mode` column in `tool_instances` table nullable to support workspace-first cleanup workflow. | exp: func:upgrade() → None, call:op.alter_column, call:sa.String, func:downgrade() → None, call:op.alter_column, call:sa.String | dep: alembic, sqlalchemy
|
||||
- 2026_06_14_104415_add_tool_type_home_directory.py | Alembic database migration that adds a `home_directory` column to `tool_types` table and updates template strings to use a configurable workspace path instead of hardcoded `/workspace` | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, func:downgrade() → None, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, call:op.drop_column | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
|
||||
- 2026_06_14_182955_fix_pi_agent_home_directory_mount.py | Alembic database migration that fixes the pi-agent tool definition manifest by changing repo mount target from /workspace to ~/{{WORKSPACE_NAME}}, updating working directory, and adjusting startup script ownership | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
|
||||
- 2026_06_14_182955_fix_pi_agent_home_directory_mount.py | Alembic database migration that updates the pi-agent tool definition manifest to mount repositories under the home directory instead of /workspace | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
|
||||
- 2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py | Alembic database migration that removes explicit repo mounts from the pi-agent tool definition manifest and synthesizes them via compile_compose instead | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.setdefault, call:any, call:mount.get, call:mounts.append, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
|
||||
- 398082499c30_add_tool_config_fields.py | Alembic database migration that adds five new columns (port_override, start_command, working_directory, environment_variables, volumes) to the tool_configs table with a port range check constraint. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, 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
|
||||
- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py | Alembic database migration that merges two parallel revision branches (removing is_builtin and adding config_profiles) into a single history line | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
|
||||
- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py | Alembic database migration that merges two divergent migration branches (profile resolver and workspaces) into a single head | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
|
||||
@@ -56,7 +57,7 @@ Database schema version control and incremental migration management for the API
|
||||
- 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
|
||||
- fc8f1a20cbf6_merge_home_directory_and_pi_agent_mount_.py | Alembic database migration that merges two divergent migration branches (home directory cleanup and pi agent mount cleanup) into a single revision history | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
|
||||
## arch
|
||||
Linear and branched Alembic migration history with merge migrations reconciling divergent branches; each migration is an autonomous upgrade/downgrade script using SQLAlchemy operations, with some including data migrations, conditional logic for idempotency, dialect-specific handling (PostgreSQL/SQLite), and direct file-system modifications alongside schema changes.
|
||||
Linear and branched migration history using Alembic's revision system with merge points to reconcile divergent branches; migrations use declarative SQLAlchemy operations with defensive idempotent checks, conditional existence guards, dialect-specific handling (PostgreSQL/SQLite), and in-place data migrations for template/schema evolution.
|
||||
## tags
|
||||
column, table, call:op.drop, alembic, downgrade, upgrade, key, call:sa.text
|
||||
## symbols
|
||||
@@ -75,5 +76,7 @@ column, table, call:op.drop, alembic, downgrade, upgrade, key, call:sa.text
|
||||
read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
|
||||
- change versions config
|
||||
read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
|
||||
- explore versions subdirectories
|
||||
index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
|
||||
## dirty
|
||||
-
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
"""remove pi agent explicit repo mount
|
||||
|
||||
Revision ID: 2026_06_15_090500
|
||||
Revises: 2026_06_14_182955
|
||||
Create Date: 2026-06-15 09:05:00.000000
|
||||
|
||||
"""
|
||||
|
||||
from typing import Sequence, Union
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
from sqlalchemy.sql import column, table
|
||||
|
||||
# revision identifiers, used by Alembic.
|
||||
revision: str = "2026_06_15_090500"
|
||||
down_revision: Union[str, Sequence[str], None] = "2026_06_14_182955"
|
||||
branch_labels: Union[str, Sequence[str], None] = None
|
||||
depends_on: Union[str, Sequence[str], None] = None
|
||||
|
||||
tool_definition_manifests = table(
|
||||
"tool_definition_manifests",
|
||||
column("id", sa.UUID),
|
||||
column("name", sa.String),
|
||||
column("manifest", sa.JSON),
|
||||
)
|
||||
|
||||
|
||||
def _find_pi_agent_manifest(
|
||||
conn: sa.Connection,
|
||||
) -> tuple[Union[str, None], Union[dict, None]]:
|
||||
result = conn.execute(
|
||||
sa.select(
|
||||
tool_definition_manifests.c.id, tool_definition_manifests.c.manifest
|
||||
).where(tool_definition_manifests.c.name == "pi-agent")
|
||||
).fetchone()
|
||||
if result is None:
|
||||
return None, None
|
||||
return result.id, dict(result.manifest)
|
||||
|
||||
|
||||
def _update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) -> None:
|
||||
conn.execute(
|
||||
sa.update(tool_definition_manifests)
|
||||
.where(tool_definition_manifests.c.id == manifest_id)
|
||||
.values(manifest=manifest)
|
||||
)
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
conn = op.get_bind()
|
||||
manifest_id, manifest = _find_pi_agent_manifest(conn)
|
||||
if not manifest_id or not manifest:
|
||||
return
|
||||
|
||||
# The repo mount is now synthesized by compile_compose based on the
|
||||
# instance's repository, so the manifest no longer needs an explicit
|
||||
# repo mount with a {{WORKSPACE_NAME}} placeholder.
|
||||
manifest["mounts"] = [
|
||||
mount
|
||||
for mount in manifest.get("mounts", [])
|
||||
if mount.get("source_type") != "repo"
|
||||
]
|
||||
|
||||
_update_manifest(conn, manifest_id, manifest)
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
conn = op.get_bind()
|
||||
manifest_id, manifest = _find_pi_agent_manifest(conn)
|
||||
if not manifest_id or not manifest:
|
||||
return
|
||||
|
||||
mounts = manifest.setdefault("mounts", [])
|
||||
if not any(mount.get("source_type") == "repo" for mount in mounts):
|
||||
mounts.append(
|
||||
{
|
||||
"name": "workspace",
|
||||
"target": "~/{{WORKSPACE_NAME}}",
|
||||
"source_type": "repo",
|
||||
"writable": True,
|
||||
"owner": "user",
|
||||
}
|
||||
)
|
||||
|
||||
_update_manifest(conn, manifest_id, manifest)
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/src
|
||||
|
||||
## role
|
||||
Core application package for the Headquarter API, providing configuration, database connectivity, structured logging, and FastAPI application initialization.
|
||||
Core initialization and infrastructure package for the Headquarter API, providing centralized configuration, database connectivity, structured logging, and application bootstrap.
|
||||
## parent
|
||||
index: apps/api/.pi-map.index.md
|
||||
map: apps/api/.pi-map.md
|
||||
|
||||
@@ -4,7 +4,7 @@ dir: apps/api/src
|
||||
index: apps/api/src/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Core application package for the Headquarter API, providing configuration, database connectivity, structured logging, and FastAPI application initialization.
|
||||
Core initialization and infrastructure package for the Headquarter API, providing centralized configuration, database connectivity, structured logging, and application bootstrap.
|
||||
## files
|
||||
- __init__.py | Marks the directory as a Python package for the Headquarter API.
|
||||
- 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
|
||||
@@ -12,7 +12,7 @@ Core application package for the Headquarter API, providing configuration, datab
|
||||
- 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 architecture with environment-based Pydantic configuration, async SQLAlchemy with retry resilience, structured JSON logging with correlation ID tracking, and modular FastAPI composition with middleware and background services.
|
||||
Layered infrastructure pattern with environment-aware Pydantic settings, async SQLAlchemy with retry resilience, structured JSON logging with correlation ID tracking, and FastAPI factory composition with middleware pipeline.
|
||||
## tags
|
||||
src, database, logging, call:logger.info, api, middleware, fastapi, filter
|
||||
## symbols
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/src/services
|
||||
|
||||
## role
|
||||
Service layer for business logic encapsulation in the API application
|
||||
This directory serves as the services layer for the API application, intended to contain business logic and service implementations.
|
||||
## parent
|
||||
index: apps/api/src/.pi-map.index.md
|
||||
map: apps/api/src/.pi-map.md
|
||||
|
||||
@@ -4,11 +4,11 @@ dir: apps/api/src/services
|
||||
index: apps/api/src/services/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Service layer for business logic encapsulation in the API application
|
||||
This directory serves as the services layer for the API application, intended to contain business logic and service implementations.
|
||||
## files
|
||||
- __init__.py | Empty file with no functionality
|
||||
## arch
|
||||
Minimal/placeholder package following Python package convention with empty __init__.py, awaiting future service module implementations
|
||||
The package follows a standard Python package structure with an empty `__init__.py` marker file, indicating it is a namespace package ready to house service modules, but currently contains no implemented services.
|
||||
## tags
|
||||
init, empty, functionality
|
||||
## symbols
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/src/services/tool
|
||||
|
||||
## role
|
||||
Manages lifecycle and runtime environment for Docker-based tool execution instances including repository access, configuration, and network connectivity.
|
||||
Provides containerized execution environment for tools with git repository access, configuration management, and secure remote connectivity.
|
||||
## parent
|
||||
index: apps/api/src/services/.pi-map.index.md
|
||||
map: apps/api/src/services/.pi-map.md
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -73,11 +73,29 @@ from src.services.shared.readiness_probe import execute_probe
|
||||
from src.services.shared.ssh_keys import prepare_ssh_key_files
|
||||
from src.services.instance.event_bus import InstanceEventBus
|
||||
from src.services.instance.lifecycle_hooks import publish_lifecycle_event
|
||||
from src.utils.git_url_parser import extract_base_repo_url
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
_event_bus = InstanceEventBus()
|
||||
|
||||
|
||||
def _get_repository_mount_name(repo: GitRepository) -> str:
|
||||
"""Return the directory name a standard git clone would create.
|
||||
|
||||
Prefers the repository name parsed from the remote URL so the container
|
||||
mount matches what users expect from ``git clone``. Falls back to the
|
||||
user-provided repository name when no remote URL is available.
|
||||
"""
|
||||
if repo.remote_url:
|
||||
base_url = extract_base_repo_url(repo.remote_url) or repo.remote_url
|
||||
name = base_url.rstrip("/").split("/")[-1]
|
||||
if name.endswith(".git"):
|
||||
name = name[:-4]
|
||||
if name:
|
||||
return name
|
||||
return repo.name
|
||||
|
||||
|
||||
def _chown_path(path: str, uid: int, gid: int) -> None:
|
||||
"""Recursively chown a path, suppressing permission errors."""
|
||||
try:
|
||||
@@ -889,8 +907,13 @@ async def prepare_manifest_instance(
|
||||
|
||||
# Use the repository name for the workspace/repo mount target, not the
|
||||
# directory name of a workspace/clone path (which may be "main" or similar).
|
||||
# Prefer the name parsed from the remote URL so it matches a standard clone.
|
||||
repo = await session.get(GitRepository, instance.repository_id)
|
||||
repo_name = repo.name if repo else os.path.basename(os.path.normpath(repo_path))
|
||||
repo_name = (
|
||||
_get_repository_mount_name(repo)
|
||||
if repo
|
||||
else os.path.basename(os.path.normpath(repo_path))
|
||||
)
|
||||
variables = {
|
||||
"IMAGE_TAG": image_tag,
|
||||
"INSTANCE_NAME": instance.name.lower(),
|
||||
@@ -1052,7 +1075,8 @@ async def create_tool_instance(
|
||||
)
|
||||
|
||||
home_dir = tool_type.home_directory or "/home/user"
|
||||
workspace_target = f"{home_dir}/{repo.name}"
|
||||
mount_name = _get_repository_mount_name(repo)
|
||||
workspace_target = f"{home_dir}/{mount_name}"
|
||||
|
||||
compose_content = f"""version: "3.8"\nservices:
|
||||
app:
|
||||
@@ -1094,8 +1118,8 @@ async def create_tool_instance(
|
||||
"INSTANCE_DIR": instance_dir,
|
||||
"WORKSPACE_PATH": repo_path,
|
||||
"REPO_PATH": repo_path,
|
||||
"REPO_NAME": repo.name,
|
||||
"WORKSPACE_NAME": repo.name,
|
||||
"REPO_NAME": _get_repository_mount_name(repo),
|
||||
"WORKSPACE_NAME": _get_repository_mount_name(repo),
|
||||
"SSH_PATH": "",
|
||||
"TOOL_PORT": tool_port,
|
||||
"EXTRA_ENV": {},
|
||||
@@ -1116,7 +1140,7 @@ async def create_tool_instance(
|
||||
"TOOL_PORT": tool_port,
|
||||
"USER_ID": str(user_id),
|
||||
"PROJECT_ID": str(project_id),
|
||||
"WORKSPACE_NAME": repo.name,
|
||||
"WORKSPACE_NAME": _get_repository_mount_name(repo),
|
||||
"HOME_DIRECTORY": tool_type.home_directory or "/home/user",
|
||||
}
|
||||
compose_content = render_compose_template(tool_type.compose_template, variables)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/tests
|
||||
|
||||
## role
|
||||
Provides shared testing infrastructure and fixtures for the API application's test suite.
|
||||
Provides shared testing infrastructure and reusable fixtures for the API test suite.
|
||||
## parent
|
||||
index: apps/api/.pi-map.index.md
|
||||
map: apps/api/.pi-map.md
|
||||
|
||||
@@ -4,11 +4,11 @@ dir: apps/api/tests
|
||||
index: apps/api/tests/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Provides shared testing infrastructure and fixtures for the API application's test suite.
|
||||
Provides shared testing infrastructure and reusable fixtures for the API test suite.
|
||||
## files
|
||||
- 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 test database, dependency injection overrides for authentication, and modular helper utilities for common test scenarios.
|
||||
Pytest fixture-based architecture using dependency injection, async context managers, and factory patterns for database/clients/test data setup.
|
||||
## tags
|
||||
call:app.dependency, call:create, overrides.get, call:override, fn, call:gen.asend, call:gen.aclose, user
|
||||
## symbols
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: apps/api/tests/unit
|
||||
|
||||
## role
|
||||
Unit test suite for the API application, covering database migrations, configuration, Docker services, Git operations, file handling, health monitoring, manifest compilation, and notification systems.
|
||||
Comprehensive unit test suite for the API application covering database migrations, configuration, Docker operations, Git services, file management, health monitoring, manifest compilation, and notification systems.
|
||||
## parent
|
||||
index: apps/api/tests/.pi-map.index.md
|
||||
map: apps/api/tests/.pi-map.md
|
||||
|
||||
@@ -4,10 +4,10 @@ dir: apps/api/tests/unit
|
||||
index: apps/api/tests/unit/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Unit test suite for the API application, covering database migrations, configuration, Docker services, Git operations, file handling, health monitoring, manifest compilation, and notification systems.
|
||||
Comprehensive unit test suite for the API application covering database migrations, configuration, Docker operations, Git services, file management, health monitoring, manifest compilation, and notification systems.
|
||||
## files
|
||||
- __init__.py | Empty file with no functionality
|
||||
- test_alembic_migrations.py | Unit tests that verify Alembic database migrations are importable, have correct revision identifiers, and declare expected dependencies without requiring a live database. | exp: func:test_home_directory_migration_imports_and_rewrites() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_merge_migration_resolves_heads() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable | dep: importlib.util, pathlib, pytest, importlib
|
||||
- test_alembic_migrations.py | Unit tests that verify Alembic database migrations are importable, have correct revision identifiers, and declare expected dependencies without requiring a live database. | exp: func:test_home_directory_migration_imports_and_rewrites() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_merge_migration_resolves_heads() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_remove_pi_agent_repo_mount_migration_imports() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable | dep: importlib.util, pathlib, pytest, importlib
|
||||
- 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 | Tests the config profile resolution system including merge helpers, profile inheritance with 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_directory_not_individual_files(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path(volumes[0]["source"]).is_dir, call:(Path(volumes[0]["source"]) / "config.json").exists, call:(Path(volumes[0]["source"]) / "nested" / "file.txt").exists, method:test_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path, call:(Path(volumes[0]["source"]) / "z.json").exists, 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_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:(Path(volumes[0]["source"]) / "app.toml").exists, call:Path, method:test_readonly_mount_sets_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, method:test_writable_mount_does_not_set_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, class:TestCheckIncludeCycle | dep: uuid, pathlib, 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
|
||||
@@ -19,7 +19,7 @@ Unit test suite for the API application, covering database migrations, configura
|
||||
- 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 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_instance_service.py | Unit tests for tool instance service functions that modify docker-compose files and prepare manifest instances with home directory expansion and workspace name resolution. | exp: class:TestModifyComposeFile, method:test_extra_volumes_expand_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, method:test_working_directory_expands_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, class:Result, func:test_prepare_manifest_instance_uses_repo_name_not_workspace_dir(), call:MagicMock, call:AsyncMock, call:Result, call:prepare_manifest_instance, func:session_get(model, obj_id), func:fake_run(cmd), call:Result | dep: unittest.mock, pytest, src.services.tool.instance_service, subprocess, src.services.tool
|
||||
- test_instance_service.py | Unit tests for tool instance service functions including compose file modification, repository mount name resolution, and manifest instance preparation. | exp: class:TestModifyComposeFile, method:test_extra_volumes_expand_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, method:test_working_directory_expands_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, class:TestGetRepositoryMountName, method:test_prefers_remote_url_name_over_user_provided_name(self), call:MagicMock, call:_get_repository_mount_name, method:test_parses_browser_url_to_repo_name(self), call:MagicMock, call:_get_repository_mount_name, method:test_falls_back_to_repo_name_when_remote_url_missing(self), call:MagicMock, call:_get_repository_mount_name, method:test_falls_back_to_repo_name_for_unparseable_url(self), call:MagicMock, call:_get_repository_mount_name, class:Result, func:test_prepare_manifest_instance_uses_repo_name_not_workspace_dir(), call:MagicMock, call:AsyncMock, call:Result, call:prepare_manifest_instance, func:session_get(model, obj_id), func:fake_run(cmd), call:Result | dep: unittest.mock, pytest, src.services.tool.instance_service, subprocess, src.services.tool
|
||||
- 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, docker-compose files, and entrypoint scripts from manifest configurations. | exp: class:TestGetManifestHomeDir, method:test_home_directory_in_manifest_wins(self) → None, call:get_manifest_home_dir, method:test_user_name_derives_home(self) → None, call:get_manifest_home_dir, method:test_root_fallback(self) → None, call:get_manifest_home_dir, method:test_empty_home_directory_falls_back(self) → None, call:get_manifest_home_dir, class:TestCompileDockerfileHomeDirectory, method:test_env_home_and_workdir_use_home_directory(self) → None, call:compile_dockerfile, method:test_workspace_symlink_created(self) → None, call:compile_dockerfile, method:test_runtime_workspace_not_baked_into_image(self) → None, call:compile_dockerfile, method:test_runtime_working_dir_overrides_home_workdir(self) → None, call:compile_dockerfile, method:test_working_dir_expands_tilde(self) → None, call:compile_dockerfile, class:TestCompileComposeHomeDirectory, method:test_default_repo_mount_synthesized(self) → None, call:compile_compose, method:test_explicit_repo_mount_preserved(self) → None, call:compile_compose, method:test_workspace_name_substituted_in_mount_target(self) → None, call:compile_compose, method:test_working_dir_expands_home(self) → None, call:compile_compose, class:TestCompileEntrypoint, method:test_entrypoint_creates_home_and_workspace(self) → None, call:compile_entrypoint, method:test_entrypoint_removes_stale_placeholder_directory(self) → None, call:compile_entrypoint, method:test_entrypoint_uses_root_then_sudo_for_workspace_symlink(self) → None, call:compile_entrypoint, call:entrypoint.find, method:test_entrypoint_fixes_mount_owners(self) → None, call:compile_entrypoint, 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, func:test_compile_dockerfile_uses_user_npm_prefix() → None, call:compile_dockerfile, func:test_compile_dockerfile_starts_as_root_and_drops_privileges() → None, call:compile_dockerfile, call:compile_entrypoint, func:test_compile_compose_runs_as_root() → None, call:compile_compose | 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
|
||||
@@ -30,9 +30,9 @@ Unit test suite for the API application, covering database migrations, configura
|
||||
- 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
|
||||
Standard Python unittest/pytest layout with test modules mirroring production code structure, using mocking for external dependencies (Docker, Git, subprocess, database) and parameterized tests for URL parsing and edge cases.
|
||||
Standard Python unittest/pytest structure with heavy mocking of external dependencies (Docker, Git subprocess, database), organized by service/domain with tests isolating individual components without requiring live infrastructure.
|
||||
## tags
|
||||
test, url, call:notification, git, home, call:, merge, call:db
|
||||
test, url, call:notification, git, call:, home, merge, call:db
|
||||
## symbols
|
||||
- TestMergeFunctions
|
||||
- TestResolveProfile
|
||||
|
||||
@@ -47,3 +47,23 @@ def test_merge_migration_resolves_heads() -> None:
|
||||
assert "2026_06_14_104415" in module.down_revision
|
||||
assert "8c6d1dbd4798" in module.down_revision
|
||||
assert callable(module.upgrade)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
def test_remove_pi_agent_repo_mount_migration_imports() -> None:
|
||||
migration_path = Path(__file__).parent.parent.parent / (
|
||||
"alembic/versions/2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py"
|
||||
)
|
||||
assert migration_path.exists()
|
||||
|
||||
spec = importlib.util.spec_from_file_location(
|
||||
"remove_repo_mount_migration", migration_path
|
||||
)
|
||||
assert spec is not None and spec.loader is not None
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
|
||||
assert module.revision == "2026_06_15_090500"
|
||||
assert module.down_revision == "2026_06_14_182955"
|
||||
assert callable(module.upgrade)
|
||||
assert callable(module.downgrade)
|
||||
|
||||
@@ -4,7 +4,11 @@ from unittest.mock import MagicMock, AsyncMock
|
||||
|
||||
import pytest
|
||||
|
||||
from src.services.tool.instance_service import modify_compose_file, prepare_manifest_instance
|
||||
from src.services.tool.instance_service import (
|
||||
_get_repository_mount_name,
|
||||
modify_compose_file,
|
||||
prepare_manifest_instance,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
@@ -14,7 +18,7 @@ class TestModifyComposeFile:
|
||||
def test_extra_volumes_expand_home_dir(self, tmp_path):
|
||||
compose_path = tmp_path / "docker-compose.yml"
|
||||
compose_path.write_text(
|
||||
'services:\n app:\n image: test:latest\n volumes: []\n'
|
||||
"services:\n app:\n image: test:latest\n volumes: []\n"
|
||||
)
|
||||
|
||||
modify_compose_file(
|
||||
@@ -32,9 +36,7 @@ class TestModifyComposeFile:
|
||||
|
||||
def test_working_directory_expands_home_dir(self, tmp_path):
|
||||
compose_path = tmp_path / "docker-compose.yml"
|
||||
compose_path.write_text(
|
||||
'services:\n app:\n image: test:latest\n'
|
||||
)
|
||||
compose_path.write_text("services:\n app:\n image: test:latest\n")
|
||||
|
||||
modify_compose_file(
|
||||
str(compose_path),
|
||||
@@ -46,11 +48,41 @@ class TestModifyComposeFile:
|
||||
assert "working_dir: /home/user/workspace" in content
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
class TestGetRepositoryMountName:
|
||||
"""Tests for _get_repository_mount_name."""
|
||||
|
||||
def test_prefers_remote_url_name_over_user_provided_name(self):
|
||||
repo = MagicMock()
|
||||
repo.name = "src"
|
||||
repo.remote_url = "git@git.example.com:acme/headquarter.git"
|
||||
assert _get_repository_mount_name(repo) == "headquarter"
|
||||
|
||||
def test_parses_browser_url_to_repo_name(self):
|
||||
repo = MagicMock()
|
||||
repo.name = "src"
|
||||
repo.remote_url = "https://github.com/acme/headquarter/tree/main"
|
||||
assert _get_repository_mount_name(repo) == "headquarter"
|
||||
|
||||
def test_falls_back_to_repo_name_when_remote_url_missing(self):
|
||||
repo = MagicMock()
|
||||
repo.name = "my-cool-repo"
|
||||
repo.remote_url = None
|
||||
assert _get_repository_mount_name(repo) == "my-cool-repo"
|
||||
|
||||
def test_falls_back_to_repo_name_for_unparseable_url(self):
|
||||
repo = MagicMock()
|
||||
repo.name = "my-cool-repo"
|
||||
repo.remote_url = ""
|
||||
assert _get_repository_mount_name(repo) == "my-cool-repo"
|
||||
|
||||
|
||||
@pytest.mark.unit
|
||||
async def test_prepare_manifest_instance_uses_repo_name_not_workspace_dir():
|
||||
"""WORKSPACE_NAME must be the repository name, not the workspace path basename."""
|
||||
repo = MagicMock()
|
||||
repo.name = "my-cool-repo"
|
||||
repo.name = "src"
|
||||
repo.remote_url = "git@git.example.com:acme/headquarter.git"
|
||||
repo.path = "/data/repos/main"
|
||||
|
||||
tool_type = MagicMock()
|
||||
@@ -63,13 +95,12 @@ async def test_prepare_manifest_instance_uses_repo_name_not_workspace_dir():
|
||||
"base_image": "ubuntu:24.04",
|
||||
"interface_type": "terminal",
|
||||
"user": {"name": "user", "uid": 1001, "gid": 1001},
|
||||
"mounts": [{"name": "workspace", "target": "~/{{WORKSPACE_NAME}}", "source_type": "repo"}],
|
||||
}
|
||||
manifest_def.base_definition_id = None
|
||||
|
||||
instance = MagicMock()
|
||||
instance.id = "instance-uuid"
|
||||
instance.name = "pi-agent-my-cool-repo-abc123"
|
||||
instance.name = "pi-agent-headquarter-abc123"
|
||||
instance.repository_id = "repo-uuid"
|
||||
instance.tool_type_id = "tooltype-uuid"
|
||||
instance.port = 0
|
||||
@@ -95,16 +126,23 @@ async def test_prepare_manifest_instance_uses_repo_name_not_workspace_dir():
|
||||
from src.services.tool import instance_service
|
||||
|
||||
original_run = subprocess.run
|
||||
|
||||
def fake_run(cmd, **kwargs):
|
||||
class Result:
|
||||
returncode = 0
|
||||
stdout = "image-id"
|
||||
stderr = ""
|
||||
|
||||
return Result()
|
||||
|
||||
instance_service.subprocess.run = fake_run
|
||||
try:
|
||||
image_tag, compose_content, manifest, home_dir = await prepare_manifest_instance(
|
||||
(
|
||||
image_tag,
|
||||
compose_content,
|
||||
manifest,
|
||||
home_dir,
|
||||
) = await prepare_manifest_instance(
|
||||
session=session,
|
||||
instance=instance,
|
||||
instance_dir="/tmp/instance",
|
||||
@@ -116,5 +154,5 @@ async def test_prepare_manifest_instance_uses_repo_name_not_workspace_dir():
|
||||
finally:
|
||||
instance_service.subprocess.run = original_run
|
||||
|
||||
assert "WORKSPACE_NAME: my-cool-repo" in compose_content
|
||||
assert "/data/repos/main:/home/user/my-cool-repo" in compose_content
|
||||
assert "WORKSPACE_NAME: headquarter" in compose_content
|
||||
assert "/data/repos/main:/home/user/headquarter" in compose_content
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: openspec
|
||||
|
||||
## role
|
||||
Defines the OpenSpec methodology and configuration for managing software requirements, specifications, and task tracking as living documentation within a project repository.
|
||||
Defines a living documentation methodology and configuration framework for managing software requirements, specifications, and task tracking within a Docker-based coding agent platform.
|
||||
## parent
|
||||
index: ./.pi-map.index.md
|
||||
map: ./.pi-map.md
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: openspec/changes
|
||||
|
||||
## role
|
||||
Manages change tracking and history for OpenAPI specification modifications
|
||||
Manages change tracking and versioning for OpenAPI specification modifications
|
||||
## parent
|
||||
index: openspec/.pi-map.index.md
|
||||
map: openspec/.pi-map.md
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
dir: openspec/changes/fix-pi-container-mount-permissions
|
||||
|
||||
## role
|
||||
Documents a bug fix for container mount path permissions in a Raspberry Pi agent development environment.
|
||||
This is a change request/bug fix package for resolving filesystem permission issues with pi-agent container repository mounts and npm updates.
|
||||
## parent
|
||||
index: openspec/changes/.pi-map.index.md
|
||||
map: openspec/changes/.pi-map.md
|
||||
|
||||
@@ -4,14 +4,14 @@ dir: openspec/changes/fix-pi-container-mount-permissions
|
||||
index: openspec/changes/fix-pi-container-mount-permissions/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Documents a bug fix for container mount path permissions in a Raspberry Pi agent development environment.
|
||||
This is a change request/bug fix package for resolving filesystem permission issues with pi-agent container repository mounts and npm updates.
|
||||
## files
|
||||
- change.md | Documents a bug fix for pi-agent container repository mount paths and npm update permissions in a containerized development environment. | dep: Alembic, Docker/container tooling, npm, Python (manifest_compiler.py, instance_service.py), pytest
|
||||
- tasks.md | Tracks completion status of tasks for fixing a Pi container repository mount and npm update permissions issue
|
||||
- change.md | Documents a bug fix for pi-agent container repository mount paths and npm update permissions involving multiple code changes across manifest compilation, instance service, and database migrations. | dep: Alembic, manifest_compiler.py, instance_service.py, pytest, ruff, mypy, npm
|
||||
- tasks.md | Tracks completion status of tasks for fixing a pi container's repository mount and npm update permissions in a software project
|
||||
## arch
|
||||
Simple documentation-based change tracking using markdown files (change.md for specifications, tasks.md for progress tracking) without code implementation.
|
||||
Issue-tracking documentation structure using lightweight markdown-based change management with separate change specification and task tracking files.
|
||||
## tags
|
||||
npm, tasks, container, repository, mount, update, permissions, change
|
||||
npm, tasks, container, repository, mount, update, permissions, py
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
|
||||
@@ -29,14 +29,19 @@ After implementing configurable tool container home directories, new `pi-agent`
|
||||
- Do not create mount target directories or the `/workspace` symlink in the image when they depend on the runtime `{{WORKSPACE_NAME}}` placeholder.
|
||||
- Remove any stale literal `{{WORKSPACE_NAME}}` directory left over from older images at container startup.
|
||||
3. Update `instance_service.py` to pass `REPO_NAME` and `WORKSPACE_NAME` into manifest compilation.
|
||||
4. Update unit tests for the new behavior.
|
||||
4. Remove the explicit repo mount from the built-in `pi-agent` manifest so the repo mount is synthesized by `compile_compose` rather than depending on tool config. Add a follow-up Alembic data migration that strips the `source_type: repo` mount from the manifest.
|
||||
5. Add `_get_repository_mount_name()` helper to derive the workspace directory name from the repository's remote URL (matching standard `git clone` behavior) and fall back to the user-provided repository name.
|
||||
6. Update unit tests for the new behavior.
|
||||
|
||||
## Affected files
|
||||
|
||||
- `apps/api/alembic/versions/<new>_fix_pi_agent_home_directory_mount.py`
|
||||
- `apps/api/alembic/versions/2026_06_14_182955_fix_pi_agent_home_directory_mount.py`
|
||||
- `apps/api/alembic/versions/2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py`
|
||||
- `apps/api/src/services/build/manifest_compiler.py`
|
||||
- `apps/api/src/services/tool/instance_service.py`
|
||||
- `apps/api/tests/unit/test_manifest_compiler.py`
|
||||
- `apps/api/tests/unit/test_instance_service.py`
|
||||
- `apps/api/tests/unit/test_alembic_migrations.py`
|
||||
|
||||
## Verification
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
- [x] Create Alembic data migration to update pi-agent manifest
|
||||
- [x] Update manifest_compiler.py: {{WORKSPACE_NAME}} substitution, env var, entrypoint runtime var, npm prefix
|
||||
- [x] Update instance_service.py to pass REPO_NAME/WORKSPACE_NAME
|
||||
- [x] Remove explicit repo mount from pi-agent manifest; synthesize mount in compile_compose
|
||||
- [x] Add _get_repository_mount_name() helper to derive workspace name from remote URL
|
||||
- [x] Update unit tests
|
||||
- [x] Run quality gates (pytest unit, ruff, mypy)
|
||||
- [ ] Commit and push
|
||||
|
||||
Reference in New Issue
Block a user