Workspace directory independence

[tonythethompson]

Goal

Workspaces become self-contained: each stores its own Directory. ProjectShortcutId is removed from runtime behavior and persisted JSON after one-time migration. Create from shortcut copies a normalized folder path at selection time; it does not create a lasting link.

flowchart LR
  subgraph before [Current]
    WS1[Workspace] -->|ProjectShortcutId| SC[Shortcut]
    SC --> DIR1[Directory]
  end
  subgraph after [Target]
    WS2[Workspace] --> DIR2[Directory]
    SC2[Shortcut] -.->|copy on create only| WS2
  end

Loading

Binding product decisions

• Directory is required on a workspace and is the launch source of truth.
• Creating from a shortcut copies a normalized path only; it creates no runtime link.
• Shortcut context menus discover related workspaces by normalized directory equality.
• Deleting a shortcut never affects workspaces.
• Workspace entries continue to inherit one shared workspace directory.
• No sequential launch, process supervision, readiness checks, or linked-shortcut sync in this pass.

Work plan

1. Data model and path utilities

• Add Workspace.Directory and remove runtime use of ProjectShortcutId.
• Add WorkspacePath to centralize normalization, existence checks, and normalized equality. Delegate to the existing shortcut path validation/WSL-aware resolver rather than duplicating path rules.
• Update WorkspaceDisplay.ToLaunchShortcut to accept string directory.
• Show workspace.Directory in display and search subtitles.

2. Load-time migration

In WorkspaceRepository.NormalizeAll during load:

• When Directory is empty and legacy ProjectShortcutId is present, resolve the shortcut once and copy its normalized Directory.
• If the shortcut no longer exists, retain the workspace with an empty directory for repair UX.
• Prefer an existing Directory over any legacy ID.
• Normalize existing directories in place.
• Persist only the directory-based schema after a successful migration.
• Apply the same normalization path to imported legacy JSON.
• Update workspaces.example.json.

3. Validation and persistence

• Remove project-shortcut existence requirements.
• Require a configured, normalizable directory.
• Require an existing directory at save and launch, consistent with shortcut behavior.
• Normalize Directory before persistence.
• Preserve global home-keyword uniqueness against shortcuts.

4. Launch behavior

Update OpenWorkspaceCommand and OpenWorkspaceEntryCommand:

• Empty directory: Workspace needs a project folder. Edit the workspace to choose one.
• Missing directory: Folder not found: {path}.
• Otherwise launch each entry using WorkspaceDisplay.ToLaunchShortcut(entry, workspace.Directory).
• Preserve current partial-launch behavior.

5. Creation and editor UX

• Shortcut-picker creation copies the normalized shortcut directory into the draft and suggests {shortcut.Name} — Agents.
• Add a first-class Project folder field in the workspace editor, with text entry, Browse, Paste, and Choose from shortcut.
• Choosing a shortcut updates only the draft directory.
• Rename/remove project-shortcut-specific navigation state and picker modes.
• Do not save until the user explicitly saves the workspace.

6. Broken-state UX

Add WorkspaceHealth:

• NeedsFolder: directory empty.
• FolderMissing: configured directory does not exist.

List/editor subtitles should show the shortened directory when healthy, and clear warnings such as ⚠ Choose project folder or ⚠ Folder missing when not. Broken workspaces remain visible and editable.

7. Discovery and shortcut context menus

• Replace GetByProjectShortcutId with GetByDirectory using WorkspacePath.PathsEqual.
• Shortcut context menus retain Create workspace from this shortcut and list matching workspaces by normalized directory equality.
• Search matches workspace name, keyword, entry labels/commands, and directory.

8. Remove delete coupling

• Remove all workspace guards from DeleteShortcutCommand and related delete paths.
• Deleting or renaming a shortcut has no effect on workspaces.

9. Import/export and cleanup

• Workspace export is self-contained.
• Invalid imported paths are retained as repairable broken states rather than crashing or being discarded.
• Update clone, fallback page, list item, validation, and display paths to use Directory.
• Remove dead ProjectShortcutId code, project-link messages, and obsolete editor navigation helpers.

Verification

1. Create from shortcut saves a copied Directory and launches entries in that folder.
2. Save with no folder fails validation.
3. Launch against a missing folder shows a clear error and opens nothing.
4. A valid legacy ProjectShortcutId migrates to Directory and is not persisted afterward.
5. A dead legacy ID produces a repairable broken workspace.
6. Deleting a formerly referenced shortcut leaves a workspace launchable.
7. Shortcut context menus show workspaces with the same normalized path.
8. Multiple workspaces may share one directory and launch independently.
9. WSL paths normalize and launch through existing terminal behavior.
10. Cross-machine imports with invalid paths load as broken, not fatal.
11. Search finds workspaces by directory fragment.
12. Run dotnet build QuickShell.sln and the relevant automated tests, then complete the manual matrix above.

Out of scope

• Optional linked-shortcut synchronization.
• Combined shortcuts/workspaces backup format.
• Automatic path repair or relative paths.
• Process sequencing, supervision, or readiness management.

[tonythethompson]

Plan feedback — approved direction, with binding revisions

The independence model is right: a Workspace owns its Directory; shortcut selection is copy-on-create only. The plan has the right product boundary and should proceed with the following requirements treated as architecture, not polish.

1. Make legacy-field deserialization explicit

Removing ProjectShortcutId from Workspace means normal JSON deserialization will discard it before NormalizeAll can inspect it. Do not leave this implicit.

Use one of these concrete mechanisms:

• a versioned/legacy disk DTO that includes ProjectShortcutId, then maps into the runtime Workspace; or
• a custom converter / deserialization-only legacy property that can read the field but is never written back.

NormalizeAll must receive both the deserialized Directory and the legacy ID. A load with Directory present always uses Directory; fall back to the legacy ID only when Directory is empty.

2. Separate repairable-load state from user-save validation

The plan intentionally retains migrated or imported workspaces whose directories are empty, missing, or invalid so the user can repair them. Ordinary Upsert validation cannot reject those same objects during load/import persistence.

Define two paths clearly:

• Load/import normalization: retain the workspace, normalize lexically where possible, mark it broken, and allow it to be persisted as a repairable state.
• Interactive save: require a configured, normalizable, existing directory.
• Launch: require an existing directory.

Do not call the normal interactive TryValidate path when performing migration persistence or importing a broken workspace. Otherwise a dead legacy ID cannot be written back as an editable broken item, contradicting the migration plan.

3. Define path comparison as lexical canonicalization, not physical resolution

WorkspacePath.PathsEqual should normalize and compare strings without requiring the path to exist. It must handle case-insensitive Windows paths, redundant separators, . / .., root trailing separators, UNC paths, and \\wsl$ paths. It should return false rather than throw when either path cannot be normalized.

Do not resolve symlinks, network shares, or WSL distributions merely to populate menus or search results. Physical checks belong only in the explicit health/launch validation path.

4. Avoid synchronous existence probes in list/search rendering

Directory.Exists and WSL/UNC-aware probes can block on unavailable network shares or stopped WSL distributions. WorkspaceHealth must not make the Command Palette list feel stalled by synchronously probing every workspace on every refresh/search.

Use cached health state, bounded refreshes, or a cheap lexical first pass. The launch path may perform the definitive existence check. A stale health badge is acceptable; a blocked palette is not.

5. Keep GetByDirectory independent

The proposed API should be:

IReadOnlyList<Workspace> GetByDirectory(string directory);

Remove the optional IShortcutRepository parameter. Directory-based discovery is deliberately independent of shortcut lifecycle. The repository may retain shortcut access only where the one-time legacy migration actually needs it.

6. Migration persistence must remain crash-safe

When a load migration changes data, persist through the repository’s existing mutex/atomic-write/backup mechanism. Parse and normalize the complete source before replacing the in-memory snapshot; do not partially rewrite a workspace file if one entry is malformed or resolution fails.

A failed migration write should not discard the original legacy JSON. Retain the loaded in-memory state for the current session and leave the on-disk file recoverable for the next attempt.

7. Add targeted automated coverage

The manual matrix is good, but add unit tests for:

• legacy ID is actually available to migration after deserialization;
• Directory wins over legacy ID when both fields are present;
• a dead legacy ID survives as a repairable workspace;
• import of a broken path is retained while interactive save rejects it;
• PathsEqual handles case, trailing separators, dot segments, UNC, and WSL forms without touching the filesystem;
• GetByDirectory does not require a shortcut repository;
• delete-shortcut behavior no longer reads or mutates workspaces.

Everything else in the issue follows naturally from these constraints. In particular, retain the folder-first editor, copy-on-select behavior, directory-based shortcut-menu discovery, no sequential/process orchestration, and no optional sync link in this pass.