feat(directory): manage environments

[zerob13]

Summary

• Add durable directory environment preferences with ordering, archive, restore, and remove lifecycle.
• Add Settings and sidebar project-group reorder UX without a separate grip handle.
• Filter archived, removed, and missing directories from new-chat project selection.
• Complete locale copy and document build preflight refresh behavior.
• Address PR review comments for reorder errors, route validation, e2e scoping, and Vietnamese Temp copy.

Validation

• pnpm run format
• pnpm run i18n
• pnpm run lint
• pnpm run typecheck:node
• pnpm run typecheck:web
• pnpm exec vitest run test/renderer/components/EnvironmentsSettings.test.ts test/renderer/stores/projectStore.test.ts test/main/routes/contracts.test.ts
• pnpm run build
• Local-data snapshot e2e: test/e2e/specs/21-project-readonly-route.smoke.spec.ts
• Independent subagent review: no correctness/regression findings

Closes #1785

Summary by CodeRabbit

Release Notes

New Features

• Added directory lifecycle management: archive, restore, and remove (removed items are excluded from lists without deleting the underlying folder/sessions).
• Added active vs archived Environments views with reorderable active list and move-to controls; ordering persists.
• Added project-mode sidebar group reordering, with updates propagating to related views.

Documentation

• Published the complete “complete directory management” spec, technical plans, and implementation checklist, plus a build preflight refresh note.

Localization

• Added/updated UI translations for archived and reordering/lifecycle actions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 15bb0f42-0140-4c33-9cff-1ebb1b0f7b32

📥 Commits

Reviewing files that changed from the base of the PR and between 44595f3 and 4af2b0d.

📒 Files selected for processing (10)

• docs/features/complete-directory-management/tasks.md
• resources/model-db/providers.json
• src/renderer/settings/components/EnvironmentsSettings.vue
• src/renderer/src/i18n/vi-VN/settings.json
• src/renderer/src/stores/ui/project.ts
• src/shared/contracts/routes/project.routes.ts
• test/e2e/specs/21-project-readonly-route.smoke.spec.ts
• test/main/routes/contracts.test.ts
• test/renderer/components/EnvironmentsSettings.test.ts
• test/renderer/stores/projectStore.test.ts

✅ Files skipped from review due to trivial changes (2)

• docs/features/complete-directory-management/tasks.md
• src/renderer/src/i18n/vi-VN/settings.json

🚧 Files skipped from review as they are similar to previous changes (6)

• src/shared/contracts/routes/project.routes.ts
• test/e2e/specs/21-project-readonly-route.smoke.spec.ts
• test/renderer/components/EnvironmentsSettings.test.ts
• test/renderer/stores/projectStore.test.ts
• src/renderer/src/stores/ui/project.ts
• src/renderer/settings/components/EnvironmentsSettings.vue

---

📝 Walkthrough

Walkthrough

Implements a complete environment directory lifecycle management system. A new SQLite new_environment_preferences table persists active/archived/removed status and sort order per directory path. ProjectPresenter gains archive, restore, remove, and reorder methods that integrate with optional configPresenter to clear default paths. Four new IPC routes and a project:environments-changed event propagate changes to the renderer, where the project store and EnvironmentsSettings.vue (with vuedraggable drag-and-drop) and WindowSideBar.vue (project-group reordering) consume them. i18n strings are added across 20+ locales.

Changes

Complete Directory Management

Layer / File(s)	Summary
Feature planning docs and build notes AGENTS.md, docs/features/complete-directory-management/spec.md, docs/features/complete-directory-management/plan.md, docs/features/complete-directory-management/sidebar-frontend-technical-plan.md, docs/features/complete-directory-management/tasks.md	Adds a build-refresh note to AGENTS.md and introduces four feature documents: product spec (acceptance criteria, lifecycle behavior, UX examples), implementation plan (SQLite schema, shared contracts, presenter/renderer/sidebar wiring), sidebar frontend technical plan (drag gating, ordering model, event conflicts, accessibility), and tasks checklist.
ACP registry version and distribution artifact updates resources/acp-registry/registry.json	Updates agent version numbers and corresponding distribution package/binary artifact references across 18 agent entries (auggie, claude-acp, cline, codebuddy-code, cursor, devin, dimcode, dirac, factory-droid, gemini, github-copilot-cli, goose, grok-build, junie, mistral-vibe, opencode, pi-acp, qwen-code).
SQLite: NewEnvironmentPreferencesTable with status/sort/timestamp schema src/main/presenter/sqlitePresenter/tables/newEnvironmentPreferences.ts	Defines NewEnvironmentPreferencesTable with status/sort_order/archived_at/removed_at/updated_at columns, CHECK constraint on status, indexes on path/status, and version-32 migration. Implements list()/get() for reads, markActive()/markArchived()/markRemoved() for state transitions, and reorderActive() transaction-based upsert that updates only existing active rows with new sort order.
SQLite: clearProjectDir for session unlinking and table wiring src/main/presenter/sqlitePresenter/tables/newSessions.ts, src/main/presenter/sqlitePresenter/index.ts, src/main/presenter/sqlitePresenter/schemaCatalog.ts	Adds clearProjectDir method to NewSessionsTable that clears project_dir from regular sessions matching a normalized path and returns affected session IDs. Registers newEnvironmentPreferencesTable in SQLitePresenter, adds its table creation, migration SQL, schema catalog entry, and extends clearNewAgentData() to delete preference rows.
Shared contracts: EnvironmentStatus type, schemas, route definitions, and event src/shared/types/agent-interface.d.ts, src/shared/types/presenters/project.presenter.d.ts, src/shared/contracts/domainSchemas.ts, src/shared/contracts/routes/project.routes.ts, src/shared/contracts/routes.ts, src/shared/contracts/events/project.events.ts, src/shared/contracts/events.ts	Adds EnvironmentStatus type (active/archived/removed), extends Project with exists boolean, extends EnvironmentSummary with status, sortOrder, archivedAt, removedAt; adds EnvironmentStatusSchema Zod enum; defines four new route contracts for reorder/archive/restore/remove; defines and registers projectEnvironmentsChangedEvent with action/path/version payload.
ProjectPresenter: lifecycle operations, enriched environment reads, filtering, and Presenter wiring src/main/presenter/projectPresenter/index.ts, src/main/presenter/index.ts	ProjectPresenter accepts optional configPresenter for default-path clearing; filters removed entries from getProjects/getRecentProjects and adds exists field; enriches getEnvironments with status/sort metadata and optional status filter; implements reorderEnvironments (persist sort order), archiveEnvironment (mark archived, clear default if matched), restoreEnvironment (mark active), removeEnvironment (DB transaction clearing sessions/project, marking removed, clearing default). Helpers compute environment summaries with custom sorting per status.
IPC route dispatcher: environment lifecycle routes and event publication src/main/routes/index.ts	Imports environment routes (archive, remove, reorder, restore), adds dispatch cases for listEnvironments (status-filtered), reorderEnvironments, archiveEnvironment, restoreEnvironment, removeEnvironment that each invoke the matching projectPresenter method and publish projectEnvironmentsChangedEvent with corresponding action/path/version.
Renderer: ProjectClient API for environment mutations and change events src/renderer/api/ProjectClient.ts	Updates listEnvironments to accept optional status filter; adds reorderEnvironments, archiveEnvironment, restoreEnvironment, removeEnvironment methods that invoke corresponding routes; adds onEnvironmentsChanged event subscription with typed listener payload.
Project store: environment subsets, mutations, optimistic updates, and cross-window reactivity src/renderer/src/stores/ui/project.ts	Tracks archivedEnvironments and removedEnvironments state alongside environments; fetches all three subsets via separate API calls; implements reorderEnvironments (optimistic local reorder with rollback on failure), archiveEnvironment, restoreEnvironment, removeEnvironment (calls backend, updates local state, clears selection if matched); listens to backend environment-change events to refresh data and clear selection on remove.
EnvironmentsSettings.vue: active/archived tabs with drag-and-drop reorder and lifecycle confirmations src/renderer/settings/components/EnvironmentsSettings.vue	Adds active/archived tab toggles showing environment counts; implements vuedraggable drag-reorder for active items with helpers to reconcile visible-subset changes and preserve hidden order; adds move-target (top/up/down/bottom) controls; introduces typed pendingAction confirmation flow with handleArchive/handleRemove and error toasts; refactors row rendering via EnvironmentRow render-function component with conditional UI (drag handles, default-set/clear vs restore, archive/restore/remove menu options) per active/archived view.
WindowSideBar.vue: project-group drag-and-drop reordering with gating and scroll management src/renderer/src/components/WindowSideBar.vue	Wraps project-group rendering in vuedraggable with dedicated folder-identity drag handle; derives group ordering/ranking from projectStore environment metadata; gates reordering via canReorderProjectGroups (false during active search, drag in progress, pin operations, initial page load); captures/restores scroll position during drag; fetches environment metadata on mount; suppresses scroll pagination and auto-fill checks during active drag; resets drag state on unmount.
NewThreadPage: project picker filtering by lifecycle status and existence src/renderer/src/pages/NewThreadPage.vue	Computes selectableProjects by filtering projectStore.projects to exclude archived/removed/missing path entries (derived from environment state) and invalid-selected projects; updates dropdown menu scrolling props.
i18n: environment lifecycle and project-group reorder strings (20+ locales) src/renderer/src/i18n/{da-DK,de-DE,en-US,es-ES,fa-IR,fr-FR,he-IL,id-ID,it-IT,ja-JP,ko-KR,ms-MY,pl-PL,pt-BR,ru-RU,tr-TR,vi-VN,zh-CN,zh-HK,zh-TW}/{chat,settings}.json	Adds projectGroupActions, moveProjectGroupTop, moveProjectGroupUp, moveProjectGroupDown, moveProjectGroupBottom labels to all chat locale files; extends environments.actions with drag/reorder/move/archive/restore/remove labels; expands environments.meta (archivedAt, never), empty (archived state), errors (archive/restore/remove/reorder failures), tabs (active/archived counts), confirm (archive/remove dialog titles and descriptions across all 20 locales).
Tests: SQLite, presenter, route dispatcher, client, UI components, store, and e2e test/main/presenter/sqlitePresenter/newEnvironmentPreferencesTable.test.ts, test/main/presenter/sqlitePresenter/newSessionsTable.test.ts, test/main/presenter/projectPresenter/projectPresenter.test.ts, test/main/routes/dispatcher.test.ts, test/renderer/api/clients.test.ts, test/renderer/components/EnvironmentsSettings.test.ts, test/renderer/components/WindowSideBar.test.ts, test/renderer/stores/projectStore.test.ts, test/renderer/components/NewThreadPage*.test.ts, test/renderer/pages/NewThreadPage.test.ts, test/e2e/specs/21-project-readonly-route.smoke.spec.ts	Adds unit tests for NewEnvironmentPreferencesTable (reorder deduplication, status immutability, timestamp independence), NewSessionsTable.clearProjectDir; expands ProjectPresenter tests for lifecycle methods, filtering, sorting; updates route dispatcher with environment route assertions; extends ProjectClient tests; adds EnvironmentsSettings tests for reorder/archive/restore/remove with confirmation and error toasts; adds WindowSideBar drag tests with gating conditions and visibility reconciliation; expands store tests for optimistic mutations and cross-window remove events; updates NewThreadPage mocks and filtering; e2e validates active/archived tab UI switching.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant EnvironmentsSettings
  participant ProjectStore
  participant ProjectClient
  participant RoutesDispatcher
  participant ProjectPresenter
  participant NewEnvironmentPreferencesTable
  participant EventBus
  User->>EnvironmentsSettings: drag reorder / archive / restore / remove
  EnvironmentsSettings->>ProjectStore: reorderEnvironments(paths) / archiveEnvironment(path) / removeEnvironment(path)
  ProjectStore->>ProjectClient: invoke route with action + path
  ProjectClient->>RoutesDispatcher: IPC invoke project.*Environment route
  RoutesDispatcher->>ProjectPresenter: reorderEnvironments / archiveEnvironment / restoreEnvironment / removeEnvironment
  ProjectPresenter->>NewEnvironmentPreferencesTable: reorderActive / markArchived / markRemoved (+ clearProjectDir tx)
  NewEnvironmentPreferencesTable-->>ProjectPresenter: done / clearedSessionIds[]
  ProjectPresenter-->>RoutesDispatcher: result
  RoutesDispatcher->>EventBus: publishProjectEnvironmentsChanged(action, path, version)
  EventBus-->>ProjectStore: onEnvironmentsChanged → refreshProjectData
  RoutesDispatcher-->>ProjectClient: result
  ProjectClient-->>ProjectStore: resolve promise
  ProjectStore->>ProjectStore: update local state / rollback on error
  ProjectStore-->>EnvironmentsSettings: environments / archivedEnvironments / removedEnvironments updated
  EnvironmentsSettings-->>User: re-render tabs with updated data

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• ThinkInAIXYZ/deepchat#1361: ProjectPresenter now accepts an optional configPresenter to clear the default project path during archive/remove operations — this directly builds on the ConfigPresenter default-path infrastructure introduced in that PR.

Poem

🐇 Hop hop, the folders are sorted with care,
Each path gets a status — active or bare!
Drag them to order, archive with a click,
Remove from DeepChat (no folders we flick).
The SQLite bunny has timestamped it all,
No directory lost, none left to fall! 🗂️

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(directory): manage environments' accurately summarizes the main feature being added—environment/directory management capabilities including reordering, archiving, restoring, and removal.
Linked Issues check	✅ Passed	The PR fully implements all coding-related requirements from issue #1785: drag-and-drop reordering with persistence, lifecycle management (archive/restore/remove), archived directory visibility, data compatibility, and filtered project selection.
Out of Scope Changes check	✅ Passed	All changes are within scope of the linked issue. Registry version updates and preflight refresh notes are necessary supporting updates, and all code changes directly implement the directory management feature.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-1785-directory-management-plan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

src/main/presenter/projectPresenter/index.ts (1)

46-50: ⚡ Quick win

Make recency ordering explicit before applying the limit.

getRecentProjects currently slices after filtering but does not sort by last_accessed_at in-method. This makes “recent” behavior depend on newProjectsTable.getAll() implementation details.

Proposed fix

   async getRecentProjects(limit: number = 10): Promise<Project[]> {
     const rows = this.sqlitePresenter.newProjectsTable.getAll()
     return rows
       .filter((row) => !this.isRemovedEnvironment(row.path))
+      .sort((left, right) => right.last_accessed_at - left.last_accessed_at)
       .slice(0, limit)
       .map((row) => ({
         path: row.path,
         name: row.name,
         icon: row.icon,
         lastAccessedAt: row.last_accessed_at
       }))
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/main/presenter/projectPresenter/index.ts` around lines 46 - 50, The
getRecentProjects method in projectPresenter currently filters and slices the
projects without explicitly sorting by recency, making the "recent" behavior
dependent on implementation details of getAll(). Add an explicit sort step after
filtering but before slicing that orders the rows by last_accessed_at in
descending order to ensure the most recently accessed projects are returned
first, making the recency ordering explicit and deterministic.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/renderer/settings/components/EnvironmentsSettings.vue`:
- Around line 330-332: The `reorderActivePaths` function is async and can
reject, but callers invoke it without awaiting or handling errors
(fire-and-forget pattern), creating unhandled promise rejections and loss of
error feedback. Add a try-catch block inside the `reorderActivePaths` function
body to catch any errors thrown by `projectStore.reorderEnvironments(paths)`,
and handle the error appropriately with user-facing error feedback (such as
displaying an error notification or logging the failure).

In `@src/renderer/src/i18n/vi-VN/settings.json`:
- Line 2001: The hideTemp translation in the Vietnamese settings file is
currently set to "Ẩn nhiệt độ" which means "hide temperature", but in the
context of the settings UI this key refers to hiding the Temp folder, not
temperature. Locate the hideTemp key in the settings.json file and change its
value from "Ẩn nhiệt độ" to "Ẩn Temp" to accurately reflect that this feature
pertains to the Temp folder rather than temperature.

In `@src/renderer/src/stores/ui/project.ts`:
- Around line 214-227: The reorderEnvironments call sends the unfiltered
normalizedPaths which may contain paths that were excluded by the filter on the
previous line, causing backend failures. In the
projectClient.reorderEnvironments() call, replace the normalizedPaths argument
with orderedPaths instead, which contains only the actively persisted
environment paths that have corresponding entries in the byPath collection.

In `@src/shared/contracts/routes/project.routes.ts`:
- Around line 29-33: The route validation in the projectReorderEnvironmentsRoute
(and other similar routes at lines 39-43, 49-53, and 59-63) accepts
whitespace-only strings because z.string().min(1) only checks length, not actual
content. Update the Zod schema definitions for the paths array validation across
all mentioned route contracts to properly reject strings that are empty or
contain only whitespace by adding validation that either trims the input first
or uses a custom refinement to ensure at least one non-whitespace character
exists in each path string.

In `@test/e2e/specs/21-project-readonly-route.smoke.spec.ts`:
- Around line 23-28: The assertion for archived tab content is too broad because
the locator matching environments-archived-empty or environment-row can find
elements anywhere on the page, not just within the archived-tab content area. To
fix this, scope the locator to only search within the archived tab container by
chaining the locator selection (first locate the archived-tab element or its
content container, then find the environments-archived-empty or environment-row
descendants within it), or alternatively verify the archived tab is in an
active/selected state before checking for the empty or row visibility to ensure
the test specifically validates archived-tab rendering.

---

Nitpick comments:
In `@src/main/presenter/projectPresenter/index.ts`:
- Around line 46-50: The getRecentProjects method in projectPresenter currently
filters and slices the projects without explicitly sorting by recency, making
the "recent" behavior dependent on implementation details of getAll(). Add an
explicit sort step after filtering but before slicing that orders the rows by
last_accessed_at in descending order to ensure the most recently accessed
projects are returned first, making the recency ordering explicit and
deterministic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 276a73dd-8e1b-4857-8490-1501ae3ea0d2

📥 Commits

Reviewing files that changed from the base of the PR and between 3ea9771 and fde0f19.

📒 Files selected for processing (76)

• AGENTS.md
• docs/features/complete-directory-management/plan.md
• docs/features/complete-directory-management/sidebar-frontend-technical-plan.md
• docs/features/complete-directory-management/spec.md
• docs/features/complete-directory-management/tasks.md
• src/main/presenter/index.ts
• src/main/presenter/projectPresenter/index.ts
• src/main/presenter/sqlitePresenter/index.ts
• src/main/presenter/sqlitePresenter/schemaCatalog.ts
• src/main/presenter/sqlitePresenter/tables/newEnvironmentPreferences.ts
• src/main/presenter/sqlitePresenter/tables/newSessions.ts
• src/main/routes/index.ts
• src/renderer/api/ProjectClient.ts
• src/renderer/settings/components/EnvironmentsSettings.vue
• src/renderer/src/components/WindowSideBar.vue
• src/renderer/src/i18n/da-DK/chat.json
• src/renderer/src/i18n/da-DK/settings.json
• src/renderer/src/i18n/de-DE/chat.json
• src/renderer/src/i18n/de-DE/settings.json
• src/renderer/src/i18n/en-US/chat.json
• src/renderer/src/i18n/en-US/settings.json
• src/renderer/src/i18n/es-ES/chat.json
• src/renderer/src/i18n/es-ES/settings.json
• src/renderer/src/i18n/fa-IR/chat.json
• src/renderer/src/i18n/fa-IR/settings.json
• src/renderer/src/i18n/fr-FR/chat.json
• src/renderer/src/i18n/fr-FR/settings.json
• src/renderer/src/i18n/he-IL/chat.json
• src/renderer/src/i18n/he-IL/settings.json
• src/renderer/src/i18n/id-ID/chat.json
• src/renderer/src/i18n/id-ID/settings.json
• src/renderer/src/i18n/it-IT/chat.json
• src/renderer/src/i18n/it-IT/settings.json
• src/renderer/src/i18n/ja-JP/chat.json
• src/renderer/src/i18n/ja-JP/settings.json
• src/renderer/src/i18n/ko-KR/chat.json
• src/renderer/src/i18n/ko-KR/settings.json
• src/renderer/src/i18n/ms-MY/chat.json
• src/renderer/src/i18n/ms-MY/settings.json
• src/renderer/src/i18n/pl-PL/chat.json
• src/renderer/src/i18n/pl-PL/settings.json
• src/renderer/src/i18n/pt-BR/chat.json
• src/renderer/src/i18n/pt-BR/settings.json
• src/renderer/src/i18n/ru-RU/chat.json
• src/renderer/src/i18n/ru-RU/settings.json
• src/renderer/src/i18n/tr-TR/chat.json
• src/renderer/src/i18n/tr-TR/settings.json
• src/renderer/src/i18n/vi-VN/chat.json
• src/renderer/src/i18n/vi-VN/settings.json
• src/renderer/src/i18n/zh-CN/chat.json
• src/renderer/src/i18n/zh-CN/settings.json
• src/renderer/src/i18n/zh-HK/chat.json
• src/renderer/src/i18n/zh-HK/settings.json
• src/renderer/src/i18n/zh-TW/chat.json
• src/renderer/src/i18n/zh-TW/settings.json
• src/renderer/src/pages/NewThreadPage.vue
• src/renderer/src/stores/ui/project.ts
• src/shared/contracts/domainSchemas.ts
• src/shared/contracts/events.ts
• src/shared/contracts/events/project.events.ts
• src/shared/contracts/routes.ts
• src/shared/contracts/routes/project.routes.ts
• src/shared/types/agent-interface.d.ts
• src/shared/types/presenters/project.presenter.d.ts
• test/e2e/specs/21-project-readonly-route.smoke.spec.ts
• test/main/presenter/projectPresenter/projectPresenter.test.ts
• test/main/presenter/sqlitePresenter/newEnvironmentPreferencesTable.test.ts
• test/main/presenter/sqlitePresenter/newSessionsTable.test.ts
• test/main/routes/dispatcher.test.ts
• test/renderer/api/clients.test.ts
• test/renderer/components/EnvironmentsSettings.test.ts
• test/renderer/components/NewThreadPage.onboarding.test.ts
• test/renderer/components/NewThreadPage.test.ts
• test/renderer/components/WindowSideBar.test.ts
• test/renderer/pages/NewThreadPage.test.ts
• test/renderer/stores/projectStore.test.ts