headquarter/docs/superpowers/plans/tool-container-home-directory.md

# Implementation Plan: Tool Container Home Directory

## Overview

Make `/home/user` the configurable, default workspace/home directory for all tool containers, preserve the repository/workspace directory name in the mount target, migrate legacy tool types, and keep `/workspace` as a compatibility symlink.

## Goals

- Add a `home_directory` field to `ToolType` and the manifest schema.
- Use that field to control workspace mount target, `HOME`, `WORKDIR`, and `~`/`$HOME` expansion.
- Preserve `{repo_name}` / `{workspace_name}` in the mount target.
- Migrate legacy Dockerfile/Compose templates via Alembic.
- Keep `/workspace` symlink for backward compatibility.
- Add an entrypoint permission fixer for runtime-mounted paths.
- Validate with unit and integration tests.

## Phases

### Phase 1: Database and model changes

**Files:**
- `apps/api/src/models/tool/tool_type.py`
- `apps/api/alembic/versions/<new>_add_tool_type_home_directory.py`

**Tasks:**
1. Add `home_directory: Mapped[str]` column to `ToolType`, non-nullable with server default `"/home/user"`.
2. Create Alembic migration that:
   - Adds the column.
   - Updates existing rows to `/home/user`.
   - Rewrites `compose_template` and `dockerfile_template` to replace `/workspace` with `/home/user/{{WORKSPACE_NAME}}` (or a compatible template variable).
3. Provide downgrade that reverses template rewrites and drops the column.

**Quality gate:**
- `cd apps/api && alembic upgrade head` succeeds.
- `alembic downgrade -1` succeeds and restores `/workspace` strings.
- Existing tests still pass.

### Phase 2: Manifest schema and compiler

**Files:**
- `apps/api/src/services/build/manifest_compiler.py`
- `apps/api/src/services/tool/instance_service.py`
- `apps/api/src/api/tool/tool_types_validation.py` (if schema validation is added)

**Tasks:**
1. Accept `home_directory` in the manifest schema (optional; fallback to ToolType value).
2. In `compile_dockerfile()`:
   - Set `ENV HOME={home_directory}` and `ENV USER={user.name}`.
   - Set `WORKDIR {home_directory}` (unless `runtime.working_dir` is present).
   - Create the home directory and pre-create `.config`, `.local/share`, `.cache` under it.
   - Add a step to create `/workspace` as a symlink to `{home_directory}/{repo_name}` (placeholder or startup-time).
3. In `compile_compose()`:
   - Use `{home_directory}/{repo_name}` as the default repo mount target when the manifest has no explicit repo mount.
   - Keep `~`/`$HOME` expansion base equal to `home_directory`.
4. Update `get_manifest_home_dir()` to honor `manifest.home_directory` before deriving from `user.name`.
5. Pass `home_directory` through the manifest-based instance lifecycle.

**Quality gate:**
- `compile_dockerfile()` output contains `ENV HOME=/home/user` and `WORKDIR /home/user` for default manifests.
- `compile_compose()` output mounts repo at `/home/user/{repo_name}` when no explicit repo mount exists.

### Phase 3: Legacy instance generation

**Files:**
- `apps/api/src/services/tool/instance_service.py`
- `apps/api/src/services/docker/compose.py`

**Tasks:**
1. In `create_tool_instance()` for `definition_type == "dockerfile"`:
   - Read `tool_type.home_directory` (default `/home/user`).
   - Mount `{repo_path}:{home_directory}/{repo_name}` instead of `{repo_path}:/workspace`.
   - Generate or adjust Dockerfile/Compose to create `/workspace` symlink.
2. For `definition_type == "compose"`:
   - Render `{home_directory}` and `{WORKSPACE_NAME}` into the template.
   - Validate that `{WORKSPACE_NAME}` is available as a template variable.
3. Add `WORKSPACE_NAME` to the render variables in `render_compose_template()`.

**Quality gate:**
- Legacy `dockerfile` instance compose mounts repo at `/home/user/{repo_name}`.
- Legacy `compose` template with `/home/user/{{WORKSPACE_NAME}}` renders correctly.

### Phase 4: Config-profile and git mount expansion

**Files:**
- `apps/api/src/services/config/config_profile_resolver.py`
- `apps/api/src/services/tool/instance_service.py`

**Tasks:**
1. Ensure `expand_container_path()` uses the resolved `home_directory` (already present; verify it is threaded through).
2. In `start_tool_instance()`, compute `home_dir` from ToolType/manifest and pass it to:
   - `apply_resolved_profile()`
   - `resolve_git_mounts()` / `resolve_git_mount_mappings()`
3. Confirm workspace/repo name is used as the mount target, not a generic `workspace` string.

**Quality gate:**
- Config profile mount target `~/config` expands to `/home/user/config`.
- Git mount target `~/repo` expands to `/home/user/repo`.

### Phase 5: Entrypoint permission fixer

**Files:**
- `apps/api/src/services/build/manifest_compiler.py`
- `apps/api/src/services/shared/permission_fixer.py`
- `tool-images/base.dockerfile` or generated entrypoint

**Tasks:**
1. Generate an entrypoint script that, before switching to the runtime user:
   - Detects the container user name/uid.
   - Runs `chown` on `{home_directory}` and key mount points.
   - Creates `/workspace` symlink if it does not yet exist.
   - Avoids recursive chown of large subtrees; target top-level dirs and runtime-created files.
2. Ensure manifest-generated Dockerfiles install `sudo` and configure passwordless sudo for the runtime user (already partially done).
3. Consider updating `tool-images/base.dockerfile` to include `sudo` and an entrypoint hook, or keep the fixer entirely in generated images.

**Quality gate:**
- Container starts successfully.
- Container user can write to `{home_directory}` and mounted config/git directories.
- `/workspace` symlink resolves to the repo/workspace directory.

### Phase 6: Tests

**Files:**
- `apps/api/tests/unit/test_home_path_expansion.py`
- `apps/api/tests/unit/test_manifest_compiler.py`
- `apps/api/tests/unit/test_instance_service.py` (new or expanded)
- `apps/api/tests/integration/test_tool_instance_lifecycle.py` (new or expanded)

**Tasks:**
1. Unit tests:
   - `expand_container_path` with `~`, `$HOME`, absolute, and relative paths.
   - `get_manifest_home_dir` with and without `home_directory`, with and without `user.name`.
   - `compile_dockerfile` includes correct `ENV HOME`, `WORKDIR`, and `/workspace` symlink step.
   - `compile_compose` defaults repo mount to `/home/user/{repo_name}` when no explicit repo mount exists.
   - Explicit manifest repo mount target is preserved.
2. Integration tests:
   - Create a manifest tool instance and verify the running container has `HOME=/home/user`, repo at `/home/user/{repo_name}`, and `/workspace` symlink.
   - Verify a config-profile mount under `~` is writable by the container user.
   - Verify git mount under `~` is writable.
   - Verify legacy dockerfile tool uses `/home/user/{repo_name}` after migration.

**Quality gate:**
- `cd apps/api && pytest tests/unit/... tests/integration/... -xvs` passes.
- `cd apps/web && npm run typecheck` passes.

## Dependencies

- The existing `home-path-expansion` helpers (`expand_container_path`) must already be in place.
- Alembic migration infrastructure must be working.
- Manifest compiler must support generated entrypoints (already partially implemented).

## Risks and Mitigations

| Risk | Mitigation |
|------|-----------|
| Alembic migration rewrites commands/env vars that contain `/workspace` | Scope the replacement to volume mount lines only; add tests for edge cases. |
| `/workspace` symlink target missing at build time | Create placeholder directory in Dockerfile; finalize symlink in entrypoint at startup. |
| Entrypoint chown slow on large repos | Chown top-level directories only; rely on runtime user for new files. |
| Base image `USER user` cannot run sudo | Either install `sudo` in base image or keep entrypoint running as root before `su`/`gosu` to runtime user. |
| Legacy templates without `{{WORKSPACE_NAME}}` break | Migration injects the variable; validation rejects missing required variables. |

## OpenSpec Task Update

After this plan is accepted, update or replace `openspec/tasks/home-path-expansion.md` to reflect the expanded scope (configurable `home_directory`, repo-name mount target, migration, compatibility symlink, permission fixer, tests).

## Rollout

1. Merge Phase 1 (schema + migration) first so the column exists.
2. Merge Phase 2 and 3 (compiler + legacy generation) next.
3. Merge Phase 4 and 5 (profile/git mounts + permission fixer).
4. Merge Phase 6 (tests) with the previous phases as appropriate.
5. Run migration in production during a maintenance window; validate a few existing tool types before full rollout.