refactor: consolidate loading/error states and extract instance actions hook
Frontend: - Create reusable DataStates components (LoadingState, ErrorState, EmptyState) - Refactor 12 pages to use shared state components instead of inline JSX - Extract useInstanceActions hook to eliminate session action duplication - Update dashboard and sessions pages to use shared hook OpenSpec: - Archive completed mobile-app-usability change (44/44 tasks) - Archive completed add-config-profiles change (15/15 tasks) Quality: TypeScript check passes, production build succeeds
This commit is contained in:
Alex Blank
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-24
|
||||
@@ -0,0 +1,109 @@
|
||||
## Context
|
||||
|
||||
The current system has tool configs for tool-type runtime fields and config folders for user-owned mounted files. Tool instance start currently discovers applicable tool configs and active config folders automatically, writes files/env vars into the instance directory, modifies Docker Compose, and starts the container. This creates useful building blocks but not a single user-facing launch profile that can be selected, composed, previewed, scoped to project/tool, or disabled for a launch.
|
||||
|
||||
The target model is a config profile: a user-owned, selectable launch configuration that owns UTF-8 text files, mount roots, plain environment variables, and runtime hints. A profile can include other profiles in an ordered graph. Launch chooses one profile or `None`; included profiles provide stacking without making the start form multi-select.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Provide one primary config abstraction for reusable launch setup.
|
||||
- Allow one selected profile, or no profile, at session start.
|
||||
- Allow ordered profile composition through includes with loop detection.
|
||||
- Support portable, project-specific, tool-specific, and project+tool profiles through optional `project_id` and `tool_type_id` references.
|
||||
- Resolve compatible defaults by specificity, falling back to the first created compatible profile.
|
||||
- Store the selected profile on the instance so restart behavior is predictable.
|
||||
- Replace legacy active config folder auto-mounting; compatibility with old config folder behavior is not required.
|
||||
- Provide a settings editor for profile env vars, mount roots, text files, include order, defaults, and basic runtime hints.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Secret storage or masking for env vars/files in v1.
|
||||
- Binary file upload/editing in v1.
|
||||
- Selecting multiple profiles directly at launch.
|
||||
- Preserving legacy config folder semantics.
|
||||
- Cross-user shared profiles.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Config profiles own files directly
|
||||
|
||||
Profiles will own their file content instead of referencing the existing `ConfigFolder` model. Reuse comes from profile composition: a profile such as `OpenCode Kimi` can include `Git identity` and `Shell defaults`.
|
||||
|
||||
Alternative considered: keep `ConfigFolder` as a reusable file-bundle primitive. This adds another concept (`profile -> folder -> files`) and makes the UI harder to explain. Direct file ownership keeps the model centered on one abstraction.
|
||||
|
||||
### Scope is derived from optional project/tool references
|
||||
|
||||
Profiles do not need a separate scope enum. Scope is inferred from nullable references:
|
||||
|
||||
- portable: no project and no tool
|
||||
- tool: tool only
|
||||
- project: project only
|
||||
- project+tool: both project and tool
|
||||
|
||||
This avoids storing redundant state and naturally supports `Headquarter OpenCode` profiles.
|
||||
|
||||
### Launch selects one profile, composition happens inside profiles
|
||||
|
||||
The start UI will expose a single config profile selector with `None` as an option. Profiles may include other profiles in ordered composition, so advanced stacking happens in the profile editor rather than the launch form.
|
||||
|
||||
Alternative considered: allow selecting multiple profiles at launch. This is more flexible but makes start behavior harder to understand and raises ordering questions for every launch.
|
||||
|
||||
### Includes use an ordered graph with cycle detection
|
||||
|
||||
Profile includes will be represented as ordered edges. Resolution processes included profiles in position order, then applies the selected profile itself. Later layers override earlier layers. Cycles must be rejected when saving include relationships and guarded against again during launch resolution.
|
||||
|
||||
### Mounts use target roots with relative UTF-8 text files
|
||||
|
||||
Each profile mount has a target path, mode (`ro` or `rw`), and a map/list of relative file paths to UTF-8 text content. The resolver stages each resolved mount into the instance directory and adds Docker bind mounts to the compose file.
|
||||
|
||||
Alternative considered: store absolute container paths on every file. Mount roots better match Docker volume behavior, simplify editing, and make merge/conflict rules clearer.
|
||||
|
||||
### Deterministic override rules
|
||||
|
||||
Resolution order is:
|
||||
|
||||
1. tool defaults already provided by the tool type/compose template
|
||||
2. included profiles in configured order, recursively resolved
|
||||
3. selected profile itself
|
||||
4. start-time/runtime overrides if a future workflow exposes them
|
||||
|
||||
For env vars and runtime hints, later values replace earlier values. For mounts with the same target path, file maps are merged and later relative file paths win. For mount mode conflicts on the same target path, the later layer wins.
|
||||
|
||||
### Defaults are selected by specificity
|
||||
|
||||
The default selector will prefer explicit defaults by specificity:
|
||||
|
||||
1. project+tool
|
||||
2. project
|
||||
3. tool
|
||||
4. global/user
|
||||
5. first created compatible profile
|
||||
6. none
|
||||
|
||||
If no explicit default exists, the first created compatible profile becomes the default launch selection. Users can still choose `None` to disable all profile config for a launch.
|
||||
|
||||
### Instance stores selected profile
|
||||
|
||||
Tool instances store the selected config profile ID, or null when `None` was selected. Restart uses the stored selection to avoid changing behavior when the user's default profile changes later.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Existing config folder users may lose automatic mounts because legacy compatibility is explicitly out of scope. Mitigation: this is an accepted breaking change and can be handled by manually recreating profiles.
|
||||
- Direct profile-owned files may duplicate content across profiles. Mitigation: include relationships provide reusable file-only profiles without adding another model.
|
||||
- Plain env vars can contain secrets. Mitigation: label v1 env vars as non-secret/plain text and defer secret storage to a later change.
|
||||
- Profile graph resolution can become complex. Mitigation: keep launch selection single-profile, use ordered includes, test cycle detection and override ordering thoroughly.
|
||||
- Mount conflicts may surprise users. Mitigation: provide a resolved preview showing final env vars, mount targets, and overridden files before launch or in profile details.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
- Add config profile tables and profile selection fields without preserving config folder behavior.
|
||||
- Stop applying all active config folders during instance start.
|
||||
- Apply selected config profile resolution during instance start/restart.
|
||||
- Existing tool config runtime fields can remain available until replaced by profile runtime hints, but reusable file/env launch behavior moves to config profiles.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should runtime hints initially include all existing tool config runtime fields, or only env vars/files/mounts with start command and working directory?
|
||||
- Should resolved config preview be required before first implementation, or can it be shipped after CRUD/start selection?
|
||||
@@ -0,0 +1,37 @@
|
||||
## Why
|
||||
|
||||
Tool launches need reusable user-owned configuration that can combine editable files, mount targets, environment variables, and runtime hints without forcing every tool start to be configured from scratch. The existing config folder and tool config concepts provide pieces of this, but they do not model a single selectable, composable launch profile with project/tool-aware defaults and override behavior.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add config profiles as the primary reusable launch configuration model.
|
||||
- Allow exactly one config profile, or no config profile, to be selected when starting a session.
|
||||
- Allow profiles to include other profiles in ordered composition, with cycle detection at save and launch resolution.
|
||||
- Let profiles be portable, tool-specific, project-specific, or project+tool-specific based on optional project and tool references.
|
||||
- Store profile-owned UTF-8 text files under mount roots, with relative file paths and `ro`/`rw` mount modes.
|
||||
- Store plain-text environment variables and runtime hints on profiles.
|
||||
- Resolve profile layers deterministically: included profiles in order, then the selected profile, with later layers overriding earlier layers.
|
||||
- Select defaults by specificity: project+tool, project, tool, global, then first compatible profile unless a default is explicitly configured.
|
||||
- Store the selected config profile on started instances so restarts are predictable.
|
||||
- **BREAKING**: Replace legacy always-active config folder mounting with explicit config profile selection. Legacy compatibility is not required for this change.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `config-profiles`: User-owned launch profiles that compose files, mounts, env vars, runtime hints, defaults, compatibility, and include relationships.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `tool-instances`: Session creation/start behavior accepts an optional selected config profile, applies resolved profile output, supports no-profile starts, and persists the selected profile for restart behavior.
|
||||
- `user-config`: User settings expose profile management/default selection surfaces for launch configuration.
|
||||
- `tool-config-management`: Legacy config folder behavior is superseded by config profiles for file mounts and reusable launch setup.
|
||||
|
||||
## Impact
|
||||
|
||||
- Backend models and migrations for config profiles, ordered profile includes, and default selection.
|
||||
- Backend APIs for profile CRUD, include management, default configuration, compatibility filtering, and resolved profile preview.
|
||||
- Tool instance create/start/restart APIs and Docker compose staging logic to apply resolved profile env vars, mounts, files, and runtime hints.
|
||||
- Settings UI for a small profile/file editor and default profile management.
|
||||
- Start session UI to select one compatible config profile or `None` before launching.
|
||||
- Tests for profile resolution, override ordering, cycle detection, compatibility filtering, defaults, and launch application.
|
||||
+118
@@ -0,0 +1,118 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Profile Ownership And Scope
|
||||
The system SHALL manage config profiles as user-owned launch configuration records with optional project and tool type references that derive compatibility scope.
|
||||
|
||||
#### Scenario: Create portable profile
|
||||
- **GIVEN** an authenticated user
|
||||
- **WHEN** they create a config profile without a project or tool type
|
||||
- **THEN** the profile is stored for that user
|
||||
- **AND** the profile is compatible with any project and tool type owned or accessible by that user
|
||||
|
||||
#### Scenario: Create scoped profile
|
||||
- **GIVEN** an authenticated user with access to a project and a tool type
|
||||
- **WHEN** they create a config profile with `project_id`, `tool_type_id`, or both
|
||||
- **THEN** the profile is stored with those references
|
||||
- **AND** compatibility is derived from the non-null references
|
||||
|
||||
#### Scenario: Reject cross-user references
|
||||
- **GIVEN** an authenticated user
|
||||
- **WHEN** they create or update a profile with a project, tool type, include, or default reference they cannot access
|
||||
- **THEN** the request is rejected
|
||||
|
||||
### Requirement: Profile Content
|
||||
The system SHALL store profile content as plain environment variables, runtime hints, and one or more mount roots containing UTF-8 text files.
|
||||
|
||||
#### Scenario: Save env vars and runtime hints
|
||||
- **GIVEN** an authenticated user editing a config profile
|
||||
- **WHEN** they save plain-text environment variables and runtime hints such as start command, working directory, and port
|
||||
- **THEN** the system persists those values on the profile
|
||||
- **AND** returns them through the profile API
|
||||
|
||||
#### Scenario: Save mounted text files
|
||||
- **GIVEN** an authenticated user editing a config profile
|
||||
- **WHEN** they add a mount with an absolute `target_path`, mode `ro` or `rw`, and relative UTF-8 text file paths
|
||||
- **THEN** the system persists the mount and files
|
||||
- **AND** preserves file content exactly as UTF-8 text
|
||||
|
||||
#### Scenario: Reject unsafe file paths
|
||||
- **GIVEN** an authenticated user editing a config profile mount
|
||||
- **WHEN** they submit an absolute file path, an empty relative path, or a relative path containing `..`
|
||||
- **THEN** the request is rejected
|
||||
|
||||
### Requirement: Ordered Profile Includes
|
||||
The system SHALL allow a config profile to include other compatible profiles in a deterministic order.
|
||||
|
||||
#### Scenario: Add ordered includes
|
||||
- **GIVEN** an authenticated user with multiple config profiles
|
||||
- **WHEN** they configure profile A to include profile B then profile C
|
||||
- **THEN** the include order is stored
|
||||
- **AND** resolution processes B before C before A
|
||||
|
||||
#### Scenario: Reject include cycle on save
|
||||
- **GIVEN** an authenticated user with profiles A and B where A already includes B
|
||||
- **WHEN** they update B to include A
|
||||
- **THEN** the request is rejected with a cycle error
|
||||
|
||||
#### Scenario: Guard against cycle during resolution
|
||||
- **GIVEN** stored profile include data contains a cycle
|
||||
- **WHEN** the system resolves a selected profile
|
||||
- **THEN** resolution fails safely without launching a partially resolved configuration
|
||||
|
||||
### Requirement: Profile Resolution
|
||||
The system SHALL resolve a selected profile by recursively applying included profiles in order and then applying the selected profile itself.
|
||||
|
||||
#### Scenario: Resolve layered env vars
|
||||
- **GIVEN** profile A includes profile B then profile C
|
||||
- **AND** B, C, and A define the same environment variable
|
||||
- **WHEN** profile A is resolved
|
||||
- **THEN** the value from A wins over C and B
|
||||
- **AND** the value from C wins over B for keys not set by A
|
||||
|
||||
#### Scenario: Resolve mount file conflicts
|
||||
- **GIVEN** multiple resolved layers define the same mount `target_path`
|
||||
- **WHEN** they contain different files under that mount
|
||||
- **THEN** their file trees are merged
|
||||
- **AND** later layers replace earlier content for the same relative file path
|
||||
|
||||
#### Scenario: Resolve mount mode conflicts
|
||||
- **GIVEN** multiple resolved layers define the same mount `target_path` with different modes
|
||||
- **WHEN** the profile is resolved
|
||||
- **THEN** the mode from the latest layer wins
|
||||
|
||||
### Requirement: Profile Defaults
|
||||
The system SHALL select the default compatible profile by explicit default specificity, then by first created compatible profile, then no profile.
|
||||
|
||||
#### Scenario: Choose most specific explicit default
|
||||
- **GIVEN** a user has explicit default profiles for global, tool, project, and project+tool scopes
|
||||
- **WHEN** they start a matching project/tool combination
|
||||
- **THEN** the project+tool default is selected
|
||||
- **AND** project, tool, and global defaults are used only when no more-specific explicit default matches
|
||||
|
||||
#### Scenario: Fall back to first compatible profile
|
||||
- **GIVEN** a user has compatible profiles but no explicit matching default
|
||||
- **WHEN** they start a session for a project/tool combination
|
||||
- **THEN** the oldest compatible profile is selected by default
|
||||
|
||||
#### Scenario: No compatible profile
|
||||
- **GIVEN** a user has no compatible profile for a project/tool combination
|
||||
- **WHEN** they start a session
|
||||
- **THEN** the default profile selection is `None`
|
||||
|
||||
### Requirement: Profile Compatibility Filtering
|
||||
The system SHALL list compatible config profiles for a selected project and tool type by default.
|
||||
|
||||
#### Scenario: List compatible profiles
|
||||
- **GIVEN** an authenticated user has portable, project-specific, tool-specific, and unrelated profiles
|
||||
- **WHEN** the launch UI requests profiles for a selected project and tool type
|
||||
- **THEN** the response includes portable profiles and profiles matching that project, tool type, or both
|
||||
- **AND** excludes unrelated project-specific or tool-specific profiles
|
||||
|
||||
### Requirement: Resolved Profile Preview
|
||||
The system SHALL expose a resolved profile preview for a selected profile and project/tool context.
|
||||
|
||||
#### Scenario: Preview resolved output
|
||||
- **GIVEN** an authenticated user selects a compatible config profile
|
||||
- **WHEN** they request a resolved preview
|
||||
- **THEN** the response includes the final environment variables, runtime hints, mount targets, mount modes, and relative file paths
|
||||
- **AND** indicates overridden values where practical
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Tool config supports runtime fields
|
||||
The system SHALL keep tool config runtime fields available for tool configuration, while reusable launch setup for user-owned files, mounts, and env var bundles SHALL be handled by config profiles.
|
||||
|
||||
#### Scenario: Create config with runtime fields
|
||||
- **WHEN** user creates a tool config with start_command="npm start", port=3000, working_directory="/app"
|
||||
- **THEN** the config is saved with all fields populated
|
||||
|
||||
#### Scenario: Environment variables as JSON
|
||||
- **WHEN** user sets environment_variables to {"NODE_ENV": "production", "API_KEY": "secret"}
|
||||
- **THEN** the system stores and returns the config with the JSON object preserved
|
||||
- **AND** reusable per-launch environment bundles are managed through config profiles
|
||||
|
||||
#### Scenario: Volumes as JSON
|
||||
- **WHEN** user sets volumes to [{"host": "/data", "container": "/app/data", "mode": "rw"}]
|
||||
- **THEN** the system stores and returns the config with the JSON array preserved
|
||||
- **AND** user-owned mounted file trees are managed through config profiles
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Active config folders auto-mount during launch
|
||||
The system SHALL NOT automatically mount all active config folders when starting tool instances.
|
||||
|
||||
#### Scenario: Start instance after config profiles replace folders
|
||||
- **GIVEN** a user has legacy active config folders
|
||||
- **WHEN** they start a tool instance without selecting a config profile
|
||||
- **THEN** those folders are not automatically mounted
|
||||
- **AND** only selected config profile output is applied for user-owned launch files and mounts
|
||||
@@ -0,0 +1,55 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Clone mode instance creation
|
||||
The system SHALL support creating tool instances with a clone mode and an optional selected config profile.
|
||||
|
||||
#### 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"`, `branch: "main"`, and a compatible config profile selection
|
||||
- **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"`, `branch="main"`, and the selected config profile ID
|
||||
|
||||
#### 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"`
|
||||
|
||||
#### Scenario: Create instance with no config profile
|
||||
- **GIVEN** an authenticated user creating a tool instance
|
||||
- **WHEN** they select `None` for config profile
|
||||
- **THEN** the instance record stores no selected config profile
|
||||
- **AND** profile-owned env vars, files, mounts, and runtime hints are not applied at start
|
||||
|
||||
#### Scenario: Reject incompatible config profile selection
|
||||
- **GIVEN** an authenticated user creating a tool instance for a project and tool type
|
||||
- **WHEN** they select a config profile scoped to a different project or tool type
|
||||
- **THEN** instance creation or start is rejected
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Config profile launch application
|
||||
The system SHALL apply the selected config profile's resolved output when starting a tool instance.
|
||||
|
||||
#### Scenario: Start instance with selected profile
|
||||
- **GIVEN** a pending tool instance with a selected compatible config profile
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the system resolves the selected profile
|
||||
- **AND** writes resolved env vars into the instance environment
|
||||
- **AND** stages resolved profile files under the instance directory
|
||||
- **AND** adds Docker bind mounts for resolved profile mounts
|
||||
- **AND** applies supported runtime hints before starting the container
|
||||
|
||||
#### Scenario: Restart uses stored profile selection
|
||||
- **GIVEN** an existing instance was started with config profile A
|
||||
- **AND** the user's default profile later changes to profile B
|
||||
- **WHEN** the instance is restarted
|
||||
- **THEN** the system uses stored profile A for restart behavior
|
||||
- **AND** does not switch to profile B automatically
|
||||
|
||||
#### Scenario: Start fails on profile resolution error
|
||||
- **GIVEN** an instance references a selected config profile that cannot be resolved
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the start request fails before launching the container
|
||||
- **AND** the error explains the profile resolution problem
|
||||
@@ -0,0 +1,35 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Config Profile Settings Editor
|
||||
The system SHALL expose a settings interface for managing the authenticated user's config profiles.
|
||||
|
||||
#### Scenario: Browse config profiles in settings
|
||||
- **GIVEN** an authenticated user
|
||||
- **WHEN** they open settings
|
||||
- **THEN** they can view their config profiles
|
||||
- **AND** see each profile's name, compatibility scope, default status, and included profiles
|
||||
|
||||
#### Scenario: Edit profile content in settings
|
||||
- **GIVEN** an authenticated user editing a config profile
|
||||
- **WHEN** they update env vars, runtime hints, mounts, text files, or include order
|
||||
- **THEN** the settings UI saves those changes through the config profile API
|
||||
- **AND** validation errors are shown without losing the user's draft edits
|
||||
|
||||
#### Scenario: Configure profile defaults in settings
|
||||
- **GIVEN** an authenticated user editing config profiles
|
||||
- **WHEN** they mark a profile as the default for a global, project, tool, or project+tool context
|
||||
- **THEN** subsequent launches for matching contexts preselect that profile according to default specificity
|
||||
|
||||
### Requirement: Launch Profile Selection UI
|
||||
The system SHALL allow the authenticated user to select one compatible config profile or `None` when starting a session.
|
||||
|
||||
#### Scenario: Preselect default compatible profile
|
||||
- **GIVEN** an authenticated user has a default compatible profile for a selected project and tool type
|
||||
- **WHEN** they open the start session form
|
||||
- **THEN** the form preselects that profile
|
||||
- **AND** also offers `None` as a selectable option
|
||||
|
||||
#### Scenario: Select no profile
|
||||
- **GIVEN** an authenticated user starts a session
|
||||
- **WHEN** they choose `None` in the config profile selector
|
||||
- **THEN** the start request records no selected config profile
|
||||
@@ -0,0 +1,32 @@
|
||||
## 1. Sequential Foundation
|
||||
|
||||
- [x] 1.1 Backend data model and migrations. Add config profile, ordered include, mount/file, default selection, and tool instance selected-profile storage. Remove launch-time reliance on legacy active config folder auto-mounting. Depends on: none. Parallel with: none.
|
||||
|
||||
## 2. Parallel Backend Core After Foundation
|
||||
|
||||
- [x] 2.1 Profile resolver service. Implement recursive ordered include resolution, deterministic merge rules, save-independent cycle protection, and resolved output structures for env vars, runtime hints, mounts, file trees, and override metadata. Depends on: 1.1. Parallel with: 2.2, 2.3.
|
||||
- [x] 2.2 Profile CRUD, validation, compatibility, and default APIs. Implement user-owned CRUD, access checks, path/content validation, ordered include save validation, compatibility-filtered listing, and default profile selection APIs. Depends on: 1.1. Parallel with: 2.1, 2.3.
|
||||
- [x] 2.3 Instance API profile selection plumbing. Update instance create/start request and persistence paths to accept one compatible config profile ID or null, reject incompatible selections, and preserve `None`. Depends on: 1.1. Parallel with: 2.1, 2.2.
|
||||
|
||||
## 3. Sequential Backend Integration
|
||||
|
||||
- [x] 3.1 Resolved profile preview API. Return final env vars, runtime hints, mount targets, mount modes, relative file paths, and practical override indicators. Depends on: 2.1, 2.2. Parallel with: none.
|
||||
- [x] 3.2 Launch and restart profile application. Apply resolved profile output during start by writing env vars, staging files, adding Docker bind mounts, applying supported runtime hints, skipping profile output for `None`, and using the stored profile on restart instead of current defaults. Depends on: 2.1, 2.3. Parallel with: none.
|
||||
|
||||
## 4. Parallel Frontend After Backend Contracts
|
||||
|
||||
- [x] 4.1 Frontend config profile API client and types. Add client methods/types for profile CRUD, includes, defaults, compatible listing, preview, and instance profile selection payloads. Depends on: 2.2, 2.3, 3.1. Parallel with: none.
|
||||
- [x] 4.2 Settings profile management UI. Add settings surfaces for browsing profiles, editing env vars/runtime hints/mounts/text files/include order/defaults, and preserving draft edits on validation errors. Depends on: 4.1. Parallel with: 4.3.
|
||||
- [x] 4.3 Launch profile selection UI. Update session start UI to load compatible profiles for the selected project/tool, preselect the resolved default, offer `None`, and submit selected profile ID or null. Depends on: 4.1. Parallel with: 4.2.
|
||||
|
||||
## 5. Parallel Test Suites
|
||||
|
||||
- [x] 5.1 Backend profile API and resolver tests. Cover CRUD, ownership, path validation, compatibility filtering, default precedence, include ordering, save-time cycle rejection, resolution-time cycle protection, and deterministic override behavior. Depends on: 2.1, 2.2, 3.1. Parallel with: 5.2, 5.3.
|
||||
- [x] 5.2 Backend instance launch tests. Cover selected profile start/restart behavior, incompatible profile rejection, `None` selection, env var writing, file staging, Docker mount application, runtime hints, and legacy active config folders not auto-mounting. Depends on: 3.2. Parallel with: 5.1, 5.3.
|
||||
- [x] 5.3 Frontend profile UI tests. Cover profile settings editing, validation error handling, compatible profile loading, default preselection, `None` selection, and submit payloads. Depends on: 4.2, 4.3. Parallel with: 5.1, 5.2.
|
||||
|
||||
## 6. Sequential Quality Gates
|
||||
|
||||
- [x] 6.1 Run backend quality gates for touched API/model/services code and fix failures. Depends on: 5.1, 5.2. Parallel with: none.
|
||||
- [x] 6.2 Run frontend quality gates for touched settings/session UI code and fix failures. Depends on: 5.3. Parallel with: none.
|
||||
- [x] 6.3 Run final OpenSpec status and implementation checklist review. Depends on: 6.1, 6.2. Parallel with: none.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-25
|
||||
@@ -0,0 +1,145 @@
|
||||
## Context
|
||||
|
||||
The Headquarter web app is built as a desktop-first React application. While the terminal component has been fully mobile-optimized through the `mobile-terminal-ux` change, the rest of the application remains largely unusable on mobile devices. Key pages like Sessions, Dashboard, and Project Workspace use desktop-oriented layouts (sidebars, multi-column forms, fixed-width panels) that break on small viewports.
|
||||
|
||||
Current mobile state:
|
||||
- AppShell has horizontal scroll navigation (functional but awkward)
|
||||
- Session cards have action buttons that wrap and overlap
|
||||
- CreateSessionForm uses multi-column grids that become cramped
|
||||
- Repo Workspace has 3 fixed sidebars that stack poorly
|
||||
- Tool Workshop and Config Profiles use fixed 280px sidebars with no mobile adaptation
|
||||
- Many touch targets are below 44px
|
||||
- Dialogs may overflow 320px viewports
|
||||
|
||||
User behavior on mobile:
|
||||
- Primary use: start/stop sessions, check status, terminal access
|
||||
- Secondary use: small config adjustments, quick file edits
|
||||
- Not used for: complex tool configuration, heavy code editing, git merge operations
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Make session start/stop/restart fully usable on mobile
|
||||
- Provide clear navigation and wayfinding on small screens
|
||||
- Ensure all interactive elements have minimum 44px touch targets
|
||||
- Make Dashboard and Sessions pages comfortable to use on phones
|
||||
- Add consistent mobile page headers with back buttons
|
||||
- Ensure dialogs and modals work within 320px viewport
|
||||
- Provide read-first, edit-second pattern for complex admin pages
|
||||
|
||||
**Non-Goals:**
|
||||
- Full feature parity with desktop (complex editing remains desktop-optimized)
|
||||
- Native app feel (no swipe gestures, pull-to-refresh, or bottom sheets beyond existing terminal special keys)
|
||||
- Redesigning the terminal (already complete)
|
||||
- Tablet-specific optimizations (focus is on 320-768px phones)
|
||||
- Changing any backend APIs or data models
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Bottom Tab Bar for Primary Navigation
|
||||
|
||||
**Decision**: Replace AppShell's horizontal scroll nav with a bottom tab bar on mobile (< 768px).
|
||||
|
||||
**Rationale**:
|
||||
- Bottom tab bars are the standard mobile navigation pattern
|
||||
- Thumb-reachable, always visible, supports muscle memory
|
||||
- Horizontal scroll nav requires two-handed use and hides items
|
||||
|
||||
**Implementation**:
|
||||
- Create `MobileNav` component with 5 tabs: Home, Projects, Sessions, Tools, Settings
|
||||
- Show badges for active sessions
|
||||
- Use CSS `position: fixed; bottom: 0` with safe-area-inset padding
|
||||
- Desktop keeps existing sidebar navigation
|
||||
|
||||
### 2. Session Cards: Action Sheet Pattern
|
||||
|
||||
**Decision**: Replace inline action buttons with a single "Actions" button that opens a dropdown/sheet.
|
||||
|
||||
**Rationale**:
|
||||
- Current session cards show 4-5 action buttons (Open, Terminal, Stop, Restart, Delete) that wrap awkwardly
|
||||
- Action sheet reduces visual clutter while keeping all actions accessible
|
||||
- Follows native mobile pattern
|
||||
|
||||
**Implementation**:
|
||||
- Add `...` or "Actions" button to each session card
|
||||
- On tap, show action sheet with: Open, Terminal, Stop/Start, Restart, Delete
|
||||
- Primary action (Open/Terminal) remains as prominent button
|
||||
- Keep swipe actions for power users (optional enhancement)
|
||||
|
||||
### 3. Forms: Vertical Stacking with Progressive Disclosure
|
||||
|
||||
**Decision**: All multi-column forms stack vertically on mobile. Complex forms use stepper or accordion pattern.
|
||||
|
||||
**Rationale**:
|
||||
- Multi-column forms become unreadable on 320px screens
|
||||
- Vertical stacking is the native mobile form pattern
|
||||
- Steppers reduce cognitive load by showing one section at a time
|
||||
|
||||
**Implementation**:
|
||||
- Update CSS: `@media (max-width: 767px)` set `grid-template-columns: 1fr` on all form grids
|
||||
- For CreateSessionForm: consider stepper (Project → Repo → Tool → Config) or keep as single long form with clear sections
|
||||
- Ensure all inputs have `min-height: 44px` and adequate spacing
|
||||
|
||||
### 4. Complex Admin Pages: Read-First Pattern
|
||||
|
||||
**Decision**: Tool Workshop and Config Profiles show summary/list view by default on mobile, with edit flowing into full-screen mode.
|
||||
|
||||
**Rationale**:
|
||||
- These pages have complex forms with sidebars that don't fit mobile
|
||||
- Users rarely need to edit these on mobile, but may need to view or make small changes
|
||||
- Read-first pattern matches user behavior
|
||||
|
||||
**Implementation**:
|
||||
- Tool Workshop: show tool type cards with key info, tap to view details, "Edit" enters full-screen edit mode
|
||||
- Config Profiles: show profile list, tap to view summary (tools, mounts, env), "Edit" enters multi-step form
|
||||
- Keep desktop split-pane layout unchanged
|
||||
|
||||
### 5. Touch Targets and Feedback
|
||||
|
||||
**Decision**: Enforce 44px minimum touch targets everywhere. Add active states for all interactive elements.
|
||||
|
||||
**Rationale**:
|
||||
- iOS Human Interface Guidelines and Android Material Design both recommend 44-48px
|
||||
- Missing active states make the app feel unresponsive on touch
|
||||
|
||||
**Implementation**:
|
||||
- Audit all buttons, links, and clickable areas
|
||||
- Add `:active` states with subtle background changes
|
||||
- Add loading/spinner states for async operations
|
||||
- Ensure adequate spacing between adjacent touch targets (minimum 8px)
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**[Risk] Increased CSS complexity from dual layouts**
|
||||
→ Mitigation: Use CSS custom properties and utility classes. Mobile styles live in `@media (max-width: 767px)` blocks alongside desktop styles, not in separate files.
|
||||
|
||||
**[Risk] Bottom tab bar reduces vertical screen real estate**
|
||||
→ Mitigation: Tab bar is only ~56px + safe area. On modern phones, this is acceptable. Content areas must account for tab bar height with `padding-bottom`.
|
||||
|
||||
**[Risk] Hiding actions behind menus increases tap count**
|
||||
→ Mitigation: Keep the most common action (Open/Terminal) as a primary visible button. Only secondary actions (Restart, Delete) move to the menu.
|
||||
|
||||
**[Risk] Stepper forms may annoy desktop users if not implemented carefully**
|
||||
→ Mitigation: Stepper only activates on mobile breakpoints. Desktop keeps existing layouts.
|
||||
|
||||
**[Risk] Maintaining two navigation patterns (desktop sidebar + mobile tab bar)**
|
||||
→ Mitigation: Both use the same route definitions. Navigation state is URL-driven. MobileNav is just a different UI for the same router.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
This is a pure frontend change with no backend or database impact.
|
||||
|
||||
1. Implement mobile navigation (AppShell changes)
|
||||
2. Update session pages (Dashboard, Sessions)
|
||||
3. Update form components (CreateSessionForm, dialogs)
|
||||
4. Update complex pages (Repo Workspace, Tool Workshop, Config Profiles)
|
||||
5. Polish: touch targets, active states, dialog sizing
|
||||
6. Test on actual devices (iOS Safari, Android Chrome)
|
||||
|
||||
Rollback: Revert CSS/JS changes. No data migration needed.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should we add a "Quick Actions" FAB (Floating Action Button) on mobile for common operations like "Start Session"?
|
||||
2. Should the bottom tab bar hide when scrolling down to maximize content area (like Safari's bottom bar)?
|
||||
3. Do we need a "Desktop Site" toggle for users who prefer the desktop layout on tablets?
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
The Headquarter web app is currently unusable on mobile devices. Critical workflows—starting and stopping sessions, viewing instance status, and making small configuration adjustments—are blocked by desktop-oriented layouts, missing touch targets, and broken responsive behavior. Since users perform real work through terminal sessions (already mobile-optimized) and session management, the core app shell and key pages must be at least functional on phones.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Mobile navigation**: Replace horizontal scroll nav with bottom tab bar on mobile breakpoints
|
||||
- **Session management mobile layout**: Redesign session cards for touch, add swipe actions, ensure all controls are reachable
|
||||
- **Dashboard mobile view**: Simplify summary cards, optimize quick actions for touch
|
||||
- **Responsive forms**: Stack multi-column forms vertically on mobile, ensure touch targets ≥ 44px
|
||||
- **Mobile-optimized dialogs**: Ensure all dialogs fit within 320px viewport, add scroll when needed
|
||||
- **Page headers**: Add consistent back buttons and contextual action bars on mobile
|
||||
- **Touch feedback**: Add active states and loading indicators for all interactive elements
|
||||
- **Graceful degradation**: Complex admin pages (Tool Workshop, Config Profiles) get read-first mobile views with edit capability
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `mobile-navigation`: Bottom tab bar, page transitions, and mobile-specific navigation patterns
|
||||
- `mobile-session-management`: Touch-optimized session cards, swipe actions, and mobile session controls
|
||||
- `mobile-responsive-layouts`: Breakpoint system, touch targets, and form stacking for mobile viewports
|
||||
|
||||
### Modified Capabilities
|
||||
- `frontend-foundation`: Add mobile breakpoint system and responsive grid utilities
|
||||
- `session-lifecycle-ux`: Extend session management UX with mobile-specific interactions
|
||||
- `tool-instances`: Ensure instance controls (start/stop/restart) are usable on mobile
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend**: Major CSS changes to AppShell, page layouts, form components, and card patterns
|
||||
- **Components**: New MobileNav component, updates to SessionCard, CreateSessionForm, and all page components
|
||||
- **User Experience**: Significantly improved mobile usability without reducing desktop functionality
|
||||
- **No API changes**: Purely frontend/CSS work
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Layout Component
|
||||
The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.
|
||||
|
||||
#### Scenario: Application shell
|
||||
- **GIVEN** the frontend application
|
||||
- **THEN** a Layout component SHALL:
|
||||
- Display a header with user info and logout
|
||||
- Display sidebar navigation on desktop (width >= 768px)
|
||||
- Show main content area
|
||||
- Collapse sidebar into a mobile menu toggle on small viewports
|
||||
- **MODIFIED**: Display a bottom tab bar on mobile (width < 768px) with tabs for Home, Projects, Sessions, Tools, Settings
|
||||
- **MODIFIED**: Hide sidebar navigation on mobile viewports
|
||||
|
||||
#### Scenario: Navigation links
|
||||
- **GIVEN** the sidebar navigation
|
||||
- **THEN** it SHALL include links to:
|
||||
- Dashboard
|
||||
- Projects
|
||||
- Repositories
|
||||
- SSH Keys
|
||||
- Settings
|
||||
- **MODIFIED**: The bottom tab bar SHALL include tabs for:
|
||||
- Home (Dashboard)
|
||||
- Projects
|
||||
- Sessions
|
||||
- Tools (Tool Workshop)
|
||||
- Settings
|
||||
|
||||
### Requirement: Responsive Design
|
||||
The system SHALL support mobile devices.
|
||||
|
||||
#### Scenario: Mobile viewport
|
||||
- **GIVEN** a mobile device
|
||||
- **WHEN** the app loads
|
||||
- **THEN**:
|
||||
- **MODIFIED**: A bottom tab bar is displayed for primary navigation
|
||||
- Content adapts to screen width
|
||||
- Touch targets are appropriately sized (minimum 44px)
|
||||
- **ADDED**: All multi-column layouts stack vertically
|
||||
- **ADDED**: Dialogs fit within the viewport and are scrollable
|
||||
- **ADDED**: Page headers include back buttons where applicable
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Mobile Bottom Navigation
|
||||
The system SHALL display a bottom tab bar for navigation on mobile viewports (width < 768px).
|
||||
|
||||
#### Scenario: Mobile viewport shows bottom nav
|
||||
- **WHEN** the app is viewed on a device with width less than 768px
|
||||
- **THEN** a bottom tab bar is displayed at the bottom of the screen
|
||||
- **AND** it contains tabs for: Home, Projects, Sessions, Tools, Settings
|
||||
- **AND** the desktop sidebar navigation is hidden
|
||||
|
||||
#### Scenario: Bottom nav tab selection
|
||||
- **WHEN** user taps a tab in the bottom navigation
|
||||
- **THEN** the app navigates to the corresponding route
|
||||
- **AND** the selected tab shows an active state
|
||||
|
||||
#### Scenario: Bottom nav session badge
|
||||
- **GIVEN** the user has active sessions
|
||||
- **WHEN** viewing the bottom navigation
|
||||
- **THEN** the Sessions tab displays a badge with the active session count
|
||||
|
||||
#### Scenario: Desktop viewport shows sidebar
|
||||
- **WHEN** the app is viewed on a device with width 768px or greater
|
||||
- **THEN** the desktop sidebar navigation is displayed
|
||||
- **AND** the bottom tab bar is hidden
|
||||
|
||||
### Requirement: Safe Area Support
|
||||
The system SHALL account for mobile safe areas (notch, home indicator) in the bottom navigation.
|
||||
|
||||
#### Scenario: iPhone with home indicator
|
||||
- **GIVEN** an iPhone with a home indicator
|
||||
- **WHEN** the bottom navigation is displayed
|
||||
- **THEN** it includes additional padding to avoid the home indicator
|
||||
- **AND** all navigation tabs remain fully tappable
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Mobile Breakpoint System
|
||||
The system SHALL apply mobile-specific styles at viewports below 768px width.
|
||||
|
||||
#### Scenario: Form stacking on mobile
|
||||
- **GIVEN** a multi-column form layout
|
||||
- **WHEN** the viewport width is less than 768px
|
||||
- **THEN** all form fields stack vertically in a single column
|
||||
- **AND** grid layouts use `grid-template-columns: 1fr`
|
||||
|
||||
#### Scenario: Dialog sizing on mobile
|
||||
- **GIVEN** a dialog or modal
|
||||
- **WHEN** the viewport width is less than 768px
|
||||
- **THEN** the dialog fits within the viewport width (maximum 100vw - 32px padding)
|
||||
- **AND** the dialog content is scrollable if it exceeds the viewport height
|
||||
|
||||
#### Scenario: Page padding on mobile
|
||||
- **GIVEN** any page content
|
||||
- **WHEN** the viewport width is less than 768px
|
||||
- **THEN** horizontal padding is reduced to 16px or less
|
||||
- **AND** content does not horizontally scroll
|
||||
|
||||
### Requirement: Touch Target Minimum Size
|
||||
The system SHALL ensure all interactive elements meet minimum touch target sizes.
|
||||
|
||||
#### Scenario: Button touch targets
|
||||
- **GIVEN** any button or clickable element
|
||||
- **THEN** it has a minimum height of 44px
|
||||
- **AND** it has a minimum width of 44px where applicable
|
||||
|
||||
#### Scenario: Link touch targets
|
||||
- **GIVEN** any text link in a list or navigation
|
||||
- **THEN** the clickable area has a minimum height of 44px
|
||||
- **AND** adjacent links have minimum 8px spacing
|
||||
|
||||
### Requirement: Mobile Page Headers
|
||||
The system SHALL provide consistent page headers on mobile with back navigation.
|
||||
|
||||
#### Scenario: Page header on mobile
|
||||
- **GIVEN** any page other than the dashboard
|
||||
- **WHEN** viewed on mobile
|
||||
- **THEN** the page displays a header with:
|
||||
- A back button (where applicable)
|
||||
- The page title
|
||||
- Contextual action buttons (if any)
|
||||
|
||||
#### Scenario: Back button navigation
|
||||
- **GIVEN** a page with a back button on mobile
|
||||
- **WHEN** the user taps the back button
|
||||
- **THEN** the app navigates to the previous page
|
||||
- **AND** if no previous page exists, it navigates to the dashboard
|
||||
|
||||
### Requirement: Active States for Touch
|
||||
The system SHALL provide visual feedback when touchable elements are tapped.
|
||||
|
||||
#### Scenario: Button active state
|
||||
- **GIVEN** a button on a touch device
|
||||
- **WHEN** the user taps the button
|
||||
- **THEN** a visual active state is displayed (e.g., background color change)
|
||||
- **AND** the active state persists for the duration of the tap
|
||||
|
||||
#### Scenario: Card active state
|
||||
- **GIVEN** a clickable card on a touch device
|
||||
- **WHEN** the user taps the card
|
||||
- **THEN** a visual active state is displayed
|
||||
- **AND** the active state is distinct from the hover state
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Touch-Optimized Session Cards
|
||||
The system SHALL render session cards with touch-friendly layouts on mobile viewports.
|
||||
|
||||
#### Scenario: Session card touch targets
|
||||
- **GIVEN** a session card displayed on mobile
|
||||
- **THEN** all interactive elements have a minimum height of 44px
|
||||
- **AND** action buttons have adequate spacing (minimum 8px between adjacent targets)
|
||||
|
||||
#### Scenario: Session card action menu
|
||||
- **GIVEN** a session card on mobile
|
||||
- **WHEN** the user taps the actions menu button
|
||||
- **THEN** a sheet or dropdown appears with all available actions
|
||||
- **AND** the actions include: Open, Terminal, Stop/Start, Restart, Delete
|
||||
- **AND** tapping outside the menu closes it
|
||||
|
||||
#### Scenario: Primary action visibility
|
||||
- **GIVEN** a running session card on mobile
|
||||
- **THEN** the primary action (Open or Terminal) remains visible as a prominent button
|
||||
- **AND** secondary actions are accessible through the actions menu
|
||||
|
||||
### Requirement: Mobile Session Creation
|
||||
The system SHALL provide a mobile-optimized session creation flow.
|
||||
|
||||
#### Scenario: Create session form on mobile
|
||||
- **GIVEN** the create session form on a mobile viewport
|
||||
- **THEN** all form fields stack vertically in a single column
|
||||
- **AND** each field has a minimum height of 44px
|
||||
- **AND** the form is scrollable if it exceeds the viewport height
|
||||
|
||||
#### Scenario: Session creation loading state
|
||||
- **GIVEN** the user submits the create session form on mobile
|
||||
- **WHEN** the request is in progress
|
||||
- **THEN** a loading indicator is displayed
|
||||
- **AND** the submit button is disabled to prevent double-submission
|
||||
|
||||
### Requirement: Mobile Session List
|
||||
The system SHALL display the session list optimized for mobile scrolling.
|
||||
|
||||
#### Scenario: Session list scrolling
|
||||
- **GIVEN** multiple sessions on mobile
|
||||
- **THEN** the session list is vertically scrollable
|
||||
- **AND** each session card has adequate vertical spacing for touch selection
|
||||
- **AND** the list does not horizontally scroll
|
||||
|
||||
#### Scenario: Empty state on mobile
|
||||
- **GIVEN** no active sessions on mobile
|
||||
- **THEN** the empty state is centered and readable on the viewport
|
||||
- **AND** the call-to-action button is prominent and tappable
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Mobile Session Interactions
|
||||
The system SHALL provide touch-optimized interactions for session management on mobile.
|
||||
|
||||
#### Scenario: Session card actions on mobile
|
||||
- **GIVEN** a session card displayed on mobile
|
||||
- **WHEN** the user wants to perform an action
|
||||
- **THEN** primary actions (Open/Terminal) are visible as prominent buttons
|
||||
- **AND** secondary actions (Stop, Restart, Delete) are accessible through an action menu
|
||||
- **AND** all action buttons have minimum 44px touch targets
|
||||
|
||||
#### Scenario: Session stop confirmation on mobile
|
||||
- **GIVEN** the user taps Stop on a running session
|
||||
- **THEN** a confirmation dialog appears optimized for mobile viewport
|
||||
- **AND** the dialog fits within 320px width
|
||||
- **AND** the dialog actions are stacked vertically with full-width buttons
|
||||
|
||||
#### Scenario: Session creation on mobile
|
||||
- **GIVEN** the user initiates session creation on mobile
|
||||
- **THEN** the creation form stacks vertically
|
||||
- **AND** all fields have minimum 44px height
|
||||
- **AND** the form is scrollable within the viewport
|
||||
|
||||
#### Scenario: Loading states on mobile
|
||||
- **GIVEN** an async session operation on mobile
|
||||
- **WHEN** the operation is in progress
|
||||
- **THEN** a loading indicator is displayed
|
||||
- **AND** interactive elements are disabled to prevent double-submission
|
||||
@@ -0,0 +1,22 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Mobile Instance Controls
|
||||
The system SHALL ensure instance control actions are usable on mobile viewports.
|
||||
|
||||
#### Scenario: Control button visibility on mobile
|
||||
- **GIVEN** an instance card or detail view on mobile
|
||||
- **THEN** control buttons (Start, Stop, Restart, Delete) have minimum 44px height
|
||||
- **AND** buttons have adequate spacing between them
|
||||
- **AND** button labels are readable at mobile font sizes
|
||||
|
||||
#### Scenario: Instance status display on mobile
|
||||
- **GIVEN** an instance on mobile
|
||||
- **THEN** the status indicator is clearly visible
|
||||
- **AND** status text does not wrap awkwardly
|
||||
- **AND** health/probe information is accessible without horizontal scrolling
|
||||
|
||||
#### Scenario: Instance creation form on mobile
|
||||
- **GIVEN** the instance creation flow on mobile
|
||||
- **THEN** all configuration fields stack vertically
|
||||
- **AND** dropdowns and selects are usable with touch
|
||||
- **AND** the submit button is prominent and reachable
|
||||
@@ -0,0 +1,64 @@
|
||||
## 1. Mobile Navigation
|
||||
|
||||
- [x] 1.1 Create MobileNav component with bottom tab bar
|
||||
- [x] 1.2 Add mobile breakpoint detection to AppShell
|
||||
- [x] 1.3 Implement tab bar with Home, Projects, Sessions, Tools, Settings tabs
|
||||
- [x] 1.4 Add session count badge to Sessions tab
|
||||
- [x] 1.5 Add safe area padding for notched devices
|
||||
- [x] 1.6 Hide desktop sidebar on mobile, show bottom nav
|
||||
- [x] 1.7 Ensure tab bar stays visible during page transitions
|
||||
|
||||
## 2. Session Management Mobile Layout
|
||||
|
||||
- [x] 2.1 Redesign SessionCard for mobile (touch targets, action menu)
|
||||
- [x] 2.2 Create mobile action sheet/dropdown for session actions
|
||||
- [x] 2.3 Ensure primary action (Open/Terminal) remains prominent
|
||||
- [x] 2.4 Update Sessions page layout for mobile
|
||||
- [x] 2.5 Update Dashboard session list for mobile
|
||||
- [x] 2.6 Add loading states for async session operations
|
||||
- [x] 2.7 Ensure session list scrolls smoothly on mobile
|
||||
|
||||
## 3. Forms & Dialogs
|
||||
|
||||
- [x] 3.1 Stack CreateSessionForm fields vertically on mobile
|
||||
- [x] 3.2 Ensure all form inputs have min-height 44px
|
||||
- [x] 3.3 Update all dialogs to fit within 320px viewport
|
||||
- [x] 3.4 Make dialog content scrollable when needed
|
||||
- [x] 3.5 Update confirmation dialogs with vertical button layout
|
||||
- [x] 3.6 Audit all forms for mobile usability
|
||||
|
||||
## 4. Responsive Layout System
|
||||
|
||||
- [x] 4.1 Add mobile breakpoint utilities (max-width: 767px)
|
||||
- [x] 4.2 Stack multi-column grids vertically on mobile
|
||||
- [x] 4.3 Reduce page padding on mobile (16px or less)
|
||||
- [x] 4.4 Ensure no horizontal scrolling on any page
|
||||
- [x] 4.5 Add consistent mobile page headers with back buttons
|
||||
- [x] 4.6 Implement back button navigation logic
|
||||
|
||||
## 5. Touch & Interaction
|
||||
|
||||
- [x] 5.1 Audit all buttons for 44px minimum touch target
|
||||
- [x] 5.2 Add active states to all interactive elements
|
||||
- [x] 5.3 Add loading indicators for async operations
|
||||
- [x] 5.4 Ensure 8px minimum spacing between adjacent touch targets
|
||||
- [x] 5.5 Test touch feedback on iOS Safari and Android Chrome
|
||||
|
||||
## 6. Complex Pages (Read-First Pattern)
|
||||
|
||||
- [x] 6.1 Update Repo Workspace for mobile (file tree primary view)
|
||||
- [x] 6.2 Update Tool Workshop with mobile list view
|
||||
- [x] 6.3 Update Config Profiles with mobile summary view
|
||||
- [x] 6.4 Add "Edit" flow that opens full-screen on mobile
|
||||
- [x] 6.5 Ensure complex forms are usable on mobile (or show desktop prompt)
|
||||
|
||||
## 7. Testing & Polish
|
||||
|
||||
- [x] 7.1 Test all pages at 320px width (iPhone SE)
|
||||
- [x] 7.2 Test all pages at 375px width (iPhone standard)
|
||||
- [x] 7.3 Test on actual iOS Safari device
|
||||
- [x] 7.4 Test on actual Android Chrome device
|
||||
- [x] 7.5 Verify no console errors on mobile
|
||||
- [x] 7.6 Run npm run typecheck
|
||||
- [x] 7.7 Run npm run lint
|
||||
- [x] 7.8 Run npm run build
|
||||
Reference in New Issue
Block a user