headquarter/openspec/specs/tool-instances/spec.md at debug/mobile-terminal-scroll

Files

T

Fusion 063a839790 feat: implement repository clone mode with SSH key support

- Add clone_mode and branch fields to tool_instances
- Add ssh_key_id to git_repositories for per-repo SSH key assignment
- Implement host-side git cloning with branch selection (default: main)
- Mount SSH keys into containers for git operations in clone mode
- Add dirty state check on clone-mode instance deletion with confirmation
- Update SessionsPage with mount/clone selector, branch input, SSH key display
- Add SSH key selector to repository creation form
- Add dirty delete confirmation modal with changed files list
- Update API schemas and endpoints for new fields
- Sync delta specs to main specs (git-repo, tool-instances, repo-clone-mode)
- Archive completed OpenSpec change: repo-clone-mode-with-ssh
- Document git requirement for custom tool types

Quality gates: Frontend typecheck and build passed
OpenSpec: repo-clone-mode-with-ssh archived with all tasks complete

2026-05-22 22:56:35 +02:00

4.2 KiB

Raw Permalink Blame History

MODIFIED Requirements

Requirement: Status Monitoring

The system SHALL track tool status with startup and health states.

Scenario: Status check with health details

GIVEN a tool instance
WHEN status is queried
THEN the real-time container status is returned:
- pending: Instance created, container not yet started
- starting: Container is running, readiness probe in progress
- running: Container is running and probe passed (or terminal tool)
- unhealthy: Container is running but probe failed/timed out
- stopped: Container was stopped by user
- error: Container failed to start or crashed

ADDED Requirements

Requirement: Health check endpoint enhancement

The system SHALL provide detailed health information through the health check endpoint.

Scenario: Health check with container and tunnel status

GIVEN a running instance
WHEN GET /instances/{id}/health is called
THEN the response includes:
- healthy: boolean - overall health
- container_status: "running", "exited", "restarting", or "not_found"
- tunnel_status: "healthy", "unreachable", "error_response", or "not_applicable"
- tunnel_status_code: HTTP status code or null
- probe_status: "passed", "failed", "pending", or "not_configured"
- last_probe_output: string or null

Requirement: Smart tunnel recreation

The system SHALL only allow tunnel recreation when the tunnel itself is broken.

Scenario: Recreate tunnel for unreachable tunnel

GIVEN an instance with tunnel_status: "unreachable"
WHEN the recreate tunnel endpoint is called
THEN the tunnel is recreated
AND the new URL is returned

Scenario: Block recreation for application errors

GIVEN an instance with tunnel_status: "error_response" (e.g., HTTP 502)
WHEN the recreate tunnel endpoint is called
THEN the request is rejected with 400 Bad Request
AND the error message explains the tunnel is working but the application is returning errors

Requirement: Clone mode instance creation

The system SHALL support creating tool instances with a clone mode that clones the repository into the instance directory.

Scenario: Create instance in clone mode

GIVEN an authenticated user with a repository that has an SSH key and remote URL
WHEN they create an instance with clone_mode: "clone" and branch: "main"
THEN the system clones the repository into the instance directory
AND the compose file uses the clone path as REPO_PATH
AND the instance record stores clone_mode="clone" and branch="main"

Scenario: Create instance in mount mode

GIVEN an authenticated user with a repository
WHEN they create an instance with clone_mode: "mount" (or omit the field)
THEN the compose file uses the host repository path as REPO_PATH
AND the instance record stores clone_mode="mount"

Requirement: SSH key mounting for git operations

The system SHALL mount the repository's SSH key into clone-mode containers for git operations.

Scenario: Start clone-mode instance

GIVEN a clone-mode instance with an associated SSH key
WHEN the instance is started
THEN the SSH key is decrypted and written to instance_dir/.ssh/
AND the .ssh directory is mounted into the container
AND the container can perform git push/pull operations

Requirement: Dirty check on clone deletion

The system SHALL check for uncommitted changes before deleting a clone-mode instance.

Scenario: Delete clean clone

GIVEN a clone-mode instance with no uncommitted changes
WHEN the user requests deletion
THEN the instance is deleted successfully

Scenario: Delete dirty clone with confirmation

GIVEN a clone-mode instance with uncommitted changes
WHEN the user requests deletion
THEN the system returns a warning with change details
AND the user must confirm deletion

Scenario: Force delete dirty clone

GIVEN a clone-mode instance with uncommitted changes
WHEN the user requests deletion with force=true
THEN the instance is deleted regardless of uncommitted changes

REMOVED Requirements

None.

4.2 KiB Raw Permalink Blame History