improvement(api): scope folders to resource paths

[TheodoreSpeaks]

Summary

• move folder CRUD under workflows, files, knowledge, and tables using canonical path identifiers
• add exact folderPath filtering and serialize path resolution with resource mutations
• remove the standalone v2 folders API and public archive/restore operations
• update shared contracts, OpenAPI specs, audits, and tests

Type of Change

• Improvement

Testing

• 530 v2 API tests passing
• 174 folder and orchestration tests passing
• TypeScript compilation passing
• Lint, OpenAPI validation, API boundary validation, and all CI audit checks passing

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 5, 2026 5:58am

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit 3df2837. Configure here.}

[TheodoreSpeaks]

@greptile-apps

[greptile-apps]

Greptile Summary

This PR replaces the standalone v2 folder API with resource-scoped, canonical-path folder operations and serializes folder resolution with related resource mutations.

• Adds /folders operations beneath workflows, files, knowledge, and tables.
• Replaces public folder identifiers with canonical folderPath values across contracts, routes, and OpenAPI specifications.
• Adds advisory locking around folder-tree mutations and path resolution.
• Removes public archive/restore operations and updates audits, orchestration, tests, and client integrations.

Confidence Score: 5/5

The PR appears safe to merge based on the eligible follow-up-review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/folders/paths.ts	Defines canonical folder-path parsing, encoding, validation, indexing, and public path projections.
apps/sim/lib/folders/orchestration.ts	Adds path-addressed folder creation, relocation, and deletion while integrating tree-level mutation serialization.
apps/sim/lib/folders/locks.ts	Introduces transaction-scoped advisory locking keyed by workspace and folder resource type.
apps/sim/app/api/v2/lib/folders.ts	Centralizes path resolution, folder response projection, and mutation-error mapping for resource-scoped routes.
apps/sim/lib/workspace-files/orchestration/file-folder-lifecycle.ts	Coordinates file mutations with canonical folder resolution under the shared folder-tree lock.
apps/sim/app/api/v2/files/folders/route.ts	Exposes resource-scoped file-folder listing and path-based create, relocate, and delete operations.
apps/sim/app/api/v2/workflows/folders/route.ts	Adds path-based workflow-folder CRUD beneath the workflows API.
apps/sim/app/api/v2/knowledge/folders/route.ts	Adds path-based knowledge-folder CRUD beneath the knowledge API.
apps/sim/app/api/v2/tables/folders/route.ts	Adds path-based table-folder CRUD beneath the tables API.
apps/sim/lib/api/contracts/v2/shared.ts	Defines shared canonical-path folder request schemas and public response contracts.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[API client] --> ResourceAPI[Resource-scoped v2 endpoint]
  ResourceAPI --> Auth[Workspace access check]
  Auth --> Lock[Acquire workspace and resource-type folder lock]
  Lock --> Resolve[Resolve canonical folder path]
  Resolve --> Mutation[Apply folder or resource mutation]
  Mutation --> DB[(Postgres)]
  Mutation --> Audit[Record path-based audit event]
  Mutation --> Notify[Invalidate resource views]

Loading

_{Reviews (3): Last reviewed commit: "fix(files): release folder lock before u..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile-apps

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile-apps

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6d30efa. Configure here.}