diff --git a/astro.config.mjs b/astro.config.mjs index e9e1446..44b7511 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,13 +1,13 @@ -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; -import starlightLinksValidator from 'starlight-links-validator'; -import starlightThemeRapide from 'starlight-theme-rapide'; -import starlightSidebarTopics from 'starlight-sidebar-topics'; -import svelte from '@astrojs/svelte'; -import tailwindcss from '@tailwindcss/vite'; -import mermaid from 'astro-mermaid'; +import { defineConfig } from "astro/config"; +import starlight from "@astrojs/starlight"; +import starlightLinksValidator from "starlight-links-validator"; +import starlightThemeRapide from "starlight-theme-rapide"; +import starlightSidebarTopics from "starlight-sidebar-topics"; +import svelte from "@astrojs/svelte"; +import tailwindcss from "@tailwindcss/vite"; +import mermaid from "astro-mermaid"; -import { posthogCode } from './posthog.mjs'; +import { posthogCode } from "./posthog.mjs"; const isProd = import.meta.env.PROD; @@ -15,18 +15,18 @@ const isProd = import.meta.env.PROD; let head = [ // OG image { - tag: 'meta', + tag: "meta", attrs: { - property: 'og:image', - content: 'https://docs.endor.dev/og.webp' - } + property: "og:image", + content: "https://docs.endor.dev/og.webp", + }, }, ]; if (isProd) { head.push({ - tag: 'script', - content: posthogCode + tag: "script", + content: posthogCode, }); } @@ -34,173 +34,191 @@ if (isProd) { export default defineConfig({ redirects: { // MCP redirects - '/mcp/overview': { + "/mcp/overview": { status: 302, - destination: '/cli/mcp/overview', + destination: "/cli/mcp/overview", }, - '/mcp/claude-code': { + "/mcp/claude-code": { status: 302, - destination: '/cli/mcp/claude-code', + destination: "/cli/mcp/claude-code", }, - '/mcp/cursor': { + "/mcp/cursor": { status: 302, - destination: '/cli/mcp/cursor', + destination: "/cli/mcp/cursor", }, - '/mcp/goose': { + "/mcp/goose": { status: 302, - destination: '/cli/mcp/goose', + destination: "/cli/mcp/goose", }, - '/mcp/vscode': { + "/mcp/vscode": { status: 302, - destination: '/cli/mcp/vscode', + destination: "/cli/mcp/vscode", }, - '/mcp/windsurf': { + "/mcp/windsurf": { status: 302, - destination: '/cli/mcp/windsurf', + destination: "/cli/mcp/windsurf", }, // Rover redirects - '/rover/overview': { + "/rover/overview": { status: 301, - destination: '/rover/intro/overview', + destination: "/rover/intro/overview", }, - '/rover/quickstart': { + "/rover/quickstart": { status: 301, - destination: '/rover/intro/quickstart', + destination: "/rover/intro/quickstart", }, - '/rover/common-workflows': { + "/rover/common-workflows": { status: 301, - destination: '/rover/intro/quickstart', + destination: "/rover/intro/quickstart", }, - '/rover/vscode-extension': { + "/rover/vscode-extension": { status: 301, - destination: '/rover/intro/vscode-extension', + destination: "/rover/intro/vscode-extension", }, - '/rover/command-reference': { + "/rover/command-reference": { status: 301, - destination: '/rover/reference/cli-reference/', + destination: "/rover/reference/cli-reference/", }, }, integrations: [ // @see https://github.com/joesaby/astro-mermaid?tab=readme-ov-file#integration-order-important mermaid({ - theme: 'forest', - autoTheme: true + theme: "forest", + autoTheme: true, }), starlight({ - title: 'Endor Documentation', + title: "Endor Documentation", plugins: [ starlightLinksValidator(), starlightThemeRapide(), starlightSidebarTopics([ { - label: 'Rover', - link: '/rover/intro/overview', - icon: 'seti:bicep', + label: "Rover", + link: "/rover/intro/overview", + icon: "seti:bicep", items: [ { - label: 'Introduction', - autogenerate: { directory: 'rover/intro' }, + label: "Introduction", + autogenerate: { directory: "rover/intro" }, + }, + { + label: "Key Concepts", + autogenerate: { directory: "rover/concepts" }, }, { - label: 'Key Concepts', - autogenerate: { directory: 'rover/concepts' }, + label: "Guides", + autogenerate: { directory: "rover/guides" }, }, { - label: 'Guides', - autogenerate: { directory: 'rover/guides' }, + label: "Advanced", + autogenerate: { directory: "rover/advanced" }, }, { - label: 'Reference', - autogenerate: { directory: 'rover/reference' }, + label: "Reference", + autogenerate: { directory: "rover/reference" }, }, { - label: 'Troubleshooting', - autogenerate: { directory: 'rover/troubleshooting' }, - } + label: "Troubleshooting", + autogenerate: { directory: "rover/troubleshooting" }, + }, ], }, { - label: 'Endor CLI', - link: '/cli/overview', - icon: 'forward-slash', + label: "Endor CLI", + link: "/cli/overview", + icon: "forward-slash", items: [ { - label: 'CLI', + label: "CLI", items: [ { - label: 'Overview', - link: '/cli/overview', + label: "Overview", + link: "/cli/overview", }, { - label: 'Setup', - link: '/cli/setup', + label: "Setup", + link: "/cli/setup", }, { - label: 'MCP', - autogenerate: { directory: 'cli/mcp' } + label: "MCP", + autogenerate: { directory: "cli/mcp" }, }, { - label: 'Networking', - link: '/cli/networking', + label: "Networking", + link: "/cli/networking", }, { - label: 'Volumes', - link: '/cli/volumes', + label: "Volumes", + link: "/cli/volumes", }, { - label: 'Commands', - link: '/cli/commands', + label: "Commands", + link: "/cli/commands", }, { - label: 'Open a Shell', - link: '/cli/shell', + label: "Open a Shell", + link: "/cli/shell", }, { - label: 'Services', - autogenerate: { directory: 'cli/services' }, - } + label: "Services", + autogenerate: { directory: "cli/services" }, + }, ], - } + }, ], }, { - label: 'Endor Web', - link: '/faq/', - icon: 'seti:html', + label: "Endor Web", + link: "/faq/", + icon: "seti:html", items: [ { - label: 'FAQ', - autogenerate: { directory: 'faq' }, + label: "FAQ", + autogenerate: { directory: "faq" }, }, { - label: 'Reference', - autogenerate: { directory: 'reference' }, + label: "Reference", + autogenerate: { directory: "reference" }, }, { - label: 'Guides', - autogenerate: { directory: 'guides' }, + label: "Guides", + autogenerate: { directory: "guides" }, }, ], }, ]), ], head, - customCss: [ - './src/styles/global.css' - ], + customCss: ["./src/styles/global.css"], logo: { - dark: './src/assets/logo-text-dark.png', - light: './src/assets/logo-text.png', - alt: 'Endor Logo', + dark: "./src/assets/logo-text-dark.png", + light: "./src/assets/logo-text.png", + alt: "Endor Logo", replacesTitle: true, }, social: [ - { icon: 'github', label: 'GitHub', href: 'https://github.com/endorhq' }, - { icon: 'mastodon', label: 'Mastodon', href: 'https://mastodon.social/@endorhq' }, - { icon: 'twitter', label: 'X', href: 'https://x.com/endorhq' }, - { icon: 'blueSky', label: 'BlueSky', href: 'https://bsky.app/profile/endorhq.bsky.social' }, - { icon: 'youtube', label: 'YouTube', href: 'https://www.youtube.com/@endorhq' }, - { icon: 'linkedin', label: 'LinkedIn', href: 'https://www.linkedin.com/company/endorhq' }, + { icon: "github", label: "GitHub", href: "https://github.com/endorhq" }, + { + icon: "mastodon", + label: "Mastodon", + href: "https://mastodon.social/@endorhq", + }, + { icon: "twitter", label: "X", href: "https://x.com/endorhq" }, + { + icon: "blueSky", + label: "BlueSky", + href: "https://bsky.app/profile/endorhq.bsky.social", + }, + { + icon: "youtube", + label: "YouTube", + href: "https://www.youtube.com/@endorhq", + }, + { + icon: "linkedin", + label: "LinkedIn", + href: "https://www.linkedin.com/company/endorhq", + }, ], }), svelte(), @@ -209,4 +227,4 @@ export default defineConfig({ vite: { plugins: [tailwindcss()], }, -}); \ No newline at end of file +}); diff --git a/src/content/docs/rover/advanced/global-store.mdx b/src/content/docs/rover/advanced/global-store.mdx new file mode 100644 index 0000000..1c0516f --- /dev/null +++ b/src/content/docs/rover/advanced/global-store.mdx @@ -0,0 +1,189 @@ +--- +title: Global Store +description: Understand where Rover stores task metadata, logs, and results. +sidebar: + order: 1 +--- + +import { FileTree } from '@astrojs/starlight/components'; + +Rover maintains a global store for configuration, task metadata, workspaces, and logs. Each [project](/rover/concepts/project) has its own separate folder. This guide explains the directory structure, files, and how to troubleshoot common issues. + +## Global Store Location + +The global store location depends on your operating system: + +| Platform | Location | +|----------|----------| +| macOS | `~/.rover` | +| Linux | `~/.rover` | +| Windows | `%APPDATA%\Rover` | + +The global store is created automatically the first time you run a Rover command. All directories are created with restricted permissions (mode `0700`) to protect your data. + +To verify your global store exists: + +```bash +# macOS/Linux +ls -la ~/.rover + +# Windows (PowerShell) +Get-Item "$env:APPDATA\Rover" +``` + +## Inspecting the Global Store + +Use the `rover info` command to view information about your global store and all registered projects: + +```sh +rover info + +# Rover Store Information +# ----------------------- +# · Store Path: /home/user/.rover/data +# · Registered Projects: 2 +# +# Projects +# -------- +# +# user/my-app +# ├── ID: user-my-app-a1b2c3d4 +# ├── Path: /home/user/projects/my-app +# └── Tasks: 5 +# +# user/api-server +# ├── ID: user-api-server-e5f6g7h8 +# ├── Path: /home/user/work/api-server +# └── Tasks: 3 +``` + +The command displays: +- **Store Path**: Location of the global data directory +- **Registered Projects**: Total number of projects Rover is tracking +- **Per-project details**: ID, filesystem path, and task count for each project + +For scripting and automation, use the `--json` flag to get machine-readable output: + +```sh +rover info --json +``` + +## Directory Structure Overview + +The global store contains three main directories: + + +- ~/.rover/ + - config/ Global configuration + - rover.json Main configuration file + - data/ Task and project data + - projects/ Per-project storage + - \/ Individual project folders + - tasks/ Task metadata + - workspaces/ Git worktrees + - logs/ Execution logs + - cache/ Temporary cached data + + +| Directory | Purpose | +|-----------|---------| +| `config/` | Global configuration including registered projects and user preferences | +| `data/` | Project data including tasks, workspaces, and logs | +| `cache/` | Temporary data that can be safely deleted | + +**Note:** On Windows, the cache directory is stored separately at `%LOCALAPPDATA%\Rover\cache`. + +## Configuration Directory (config/) + +The `config/` directory contains Rover's global configuration file and other elements like [workflows](/rover/concepts/workflow). The files in this folder applies to all the projects in your system. + +- **`rover.json`**: the main configuration file containing user preferences and project registrations. +- **`workflows`**: folder that contains global workflows for all projects. + +This directory is created on first Rover CLI use, along with a default `rover.json` file. + +### Global Configuration File (rover.json) + +The `rover.json` file is the central configuration file for Rover. It stores user preferences, AI agent settings, and the registry of all projects you've used with Rover. This file is auto-generated and managed by the Rover CLI, so you don't need to edit it. + +If you want to customize a specific project, create a [Project Configuration](/rover/intro/configuration) file. + +### Project Registry + +Each project you use with Rover is registered. Registration happens automatically when you run Rover commands in a project directory. + +#### Project ID Generation + +Project IDs use the format: `-` + +- **clean-name**: Repository name with invalid filename characters replaced by hyphens +- **hash**: First 8 characters of SHA256 hash of the project path + +This ensures unique IDs even for projects with the same name as long as they are in different locations. + +**Example:** +- Project path: `/Users/developer/projects/my-app` +- Repository name: `my-app` +- Generated ID: `my-app-a1b2c3d4` + +## Data Directory (data/) + +The `data/` directory stores all runtime data for your projects, including tasks, Git worktrees, and logs. + + +- ~/.rover/data/ + - projects/ + - \/ + - tasks/ + - workspaces/ + - logs/ + + +### Project Data Structure + +Each registered project has its own subdirectory under `data/projects/`, named using the project ID: + +| Subdirectory | Purpose | +|--------------|---------| +| `tasks/` | Task metadata (description.json files) | +| `workspaces/` | Git worktrees for isolated task execution | +| `logs/` | Execution logs for each task | + +### Task Storage + +Each task is stored in its own numbered folder under `tasks/`: + + +- ~/.rover/data/projects/\/tasks/ + - 1/ + - description.json + - iterations/ + - 1/ + - 2/ + - 2/ + - description.json + - iterations/ + - 3/ + - description.json + + +Task IDs are sequential integers starting from 1 for each project. + +## Cache Directory (cache/) + +The cache directory stores temporary data that Rover uses to improve performance. This data can be safely deleted without losing important information. + +| Platform | Location | +|----------|----------| +| macOS/Linux | `~/.rover/cache` | +| Windows | `%LOCALAPPDATA%\Rover\cache` | + +To clear the cache: + +```bash +# macOS/Linux +rm -rf ~/.rover/cache + +# Windows (PowerShell) +Remove-Item -Recurse "$env:LOCALAPPDATA\Rover\cache" +``` diff --git a/src/content/docs/rover/concepts/project.mdx b/src/content/docs/rover/concepts/project.mdx new file mode 100644 index 0000000..f3138b7 --- /dev/null +++ b/src/content/docs/rover/concepts/project.mdx @@ -0,0 +1,131 @@ +--- +title: Project +description: Understand how Rover identifies and manages your git repositories +sidebar: + order: 1 +--- + +import { FileTree } from '@astrojs/starlight/components'; +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +A **project** in Rover is a git repository on your filesystem. Projects are the top-level organizational unit. Each project contains its own [tasks](/rover/concepts/task), [workspaces](/rover/concepts/workspace), and execution logs. You can work with multiple projects simultaneously, as Rover keeps everything organized for you. + +## What is a Project? + +Every local git repository you use with Rover becomes a registered project. Each project is identified by: + +- **Filesystem path**: The absolute path to the repository on your machine +- **Project ID**: A unique identifier generated automatically (e.g., `my-app-a1b2c3d4`) +- **Repository name**: Derived from the git remote URL or directory name + +Projects are independent from each other. You can create tasks, run agents, and manage workspaces in multiple projects at the same time without interference. + +## Automatic Registration + +Rover uses a zero-configuration approach for project management. **Projects register automatically** when you run any Rover command inside a git repository. Custom project configuration is optional. + +When you run a command like `rover task` in a new repository, Rover: + +1. Detects the git repository root +2. Derives the project name from the git remote (or uses the directory name as fallback) +3. Detects your development environment (languages, package managers, task runners) +4. Generates a unique project ID +5. Creates project directories in the [global store](/rover/advanced/global-store) + +```sh +# Navigate to any git repository +cd ~/projects/my-app + +# Run any Rover command - the project registers automatically +rover task "Add input validation to the login form" +``` + +After registration, the project appears in your global project list and all task data is stored centrally. + +## Project Identification + +Each project receives a unique ID using the format: `{repository-name}-{hash}` + +- **repository-name**: The name from your git remote (e.g., `user/repo` becomes `user-repo`), with special characters replaced by hyphens +- **hash**: First 8 characters of a SHA256 hash of the absolute filesystem path + +This format ensures unique IDs even when you have repositories with the same name in different locations: + +| Repository Path | Project ID | +|-----------------|------------| +| `/home/user/work/api` | `api-3f8a2b1c` | +| `/home/user/personal/api` | `api-9d4e7f2a` | + +You can reference projects by their ID, repository name, or filesystem path when using the `--project` flag. + +## Environment Detection + +When a project is registered, Rover automatically detects your development environment. This information helps Rover provide better context to AI agents. + +| Category | Detected | +|----------|----------| +| **Languages** | TypeScript, JavaScript, Python, Go, Rust, PHP, Ruby | +| **Package Managers** | npm, pnpm, yarn, pip, poetry, cargo | +| **Task Runners** | make, just, task | + +Detection is based on configuration files in your repository (like `package.json`, `Cargo.toml`, `pyproject.toml`, etc.). + +## Where Project Data Lives + +Rover stores all project data in a central location on your machine, keeping your repository clean. Task metadata, workspaces, and logs are stored in the global store at `~/.rover/` (or `%APPDATA%\Rover` on Windows). + + +- ~/.rover/ + - config/ + - rover.json Global configuration with project registry + - data/ + - projects/ + - \/ + - tasks/ Task metadata and iterations + - workspaces/ Git worktrees for isolated execution + - logs/ Execution logs + + +This centralized approach means: +- Your repository stays clean (no need to add `.rover/` folder to gitignore) +- Task data persists even if you delete and re-clone the repository +- You can manage all projects from a single location + +For a detailed breakdown of the global store structure, see the [Global Store](/rover/advanced/global-store) advanced guide. + +## Working with Multiple Projects + +Rover makes it easy to work across multiple projects: + +**List tasks from all projects:** +```sh +rover list +``` + +**Target a specific project:** +```sh +# By project ID +rover list --project my-app-a1b2c3d4 + +# By repository name +rover list --project my-app + +# By path +rover list --project ~/projects/my-app +``` + +**Set a default project via environment variable:** +```sh +export ROVER_PROJECT=my-app +rover list # Uses my-app project +``` + +When you run Rover commands outside a git repository, Rover operates in **global mode** and shows an interactive project selector if needed. + +## Next Steps + + + + + + diff --git a/src/content/docs/rover/concepts/sandbox.mdx b/src/content/docs/rover/concepts/sandbox.mdx index bffd2f1..17df197 100644 --- a/src/content/docs/rover/concepts/sandbox.mdx +++ b/src/content/docs/rover/concepts/sandbox.mdx @@ -2,7 +2,7 @@ title: Sandbox description: Explore the isolated containerized environment where Rover executes tasks sidebar: - order: 2 + order: 3 --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; @@ -113,8 +113,8 @@ The sandbox includes the [`package-manager-mcp` server](https://github.com/endor ## Next Steps - + - \ No newline at end of file + diff --git a/src/content/docs/rover/concepts/task.mdx b/src/content/docs/rover/concepts/task.mdx index b95420e..6d148fa 100644 --- a/src/content/docs/rover/concepts/task.mdx +++ b/src/content/docs/rover/concepts/task.mdx @@ -2,7 +2,7 @@ title: Task description: Learn how Rover manages tasks as units of work for AI coding agents sidebar: - order: 1 + order: 2 --- import { FileTree } from '@astrojs/starlight/components'; @@ -19,31 +19,34 @@ Rover manages your requests as tasks. Each task is an unit of work for Rover and Tasks can run in parallel, and **you can create as many as you want**. Each task is independent from the others, so you can stop, restart, inspect, debug, or delete them individually. -## Local Structure +## Task Storage -Rover uses a local folder structure to manage tasks. Each task has its own folder inside the `.rover/tasks/` directory. The `.rover` folder lives in your project's root directory, and it's created automatically when you run `rover init`. You shouldn't commit this folder to the reposistory, as it contains user-specific and local task information. - -You will find multiple folders in `.rover/tasks/`. The folder name is the unique task ID assigned when you create it. +Rover stores all task data in the [global store](/rover/advanced/global-store), keeping your repository clean. Each task has its own folder inside `~/.rover/data/projects//tasks/`. The folder name is the unique task ID assigned when you create it. -- .rover/ +- ~/.rover/data/projects/\/ - tasks/ - 1/ - 2/ - description.json - - entrypoint.sh - - inputs.json - - workflow.yml - iterations/ - 1/ + - entrypoint.sh + - inputs.json + - workflow.yml - iteration.json - status.json - summary.md - ... + - 2/ - ... - - workspace/ - 3/ - ... + - workspaces/ + - 1/ + - 2/ Git worktree for task 2 + - 3/ + - logs/ ### Task files @@ -51,17 +54,20 @@ You will find multiple folders in `.rover/tasks/`. The folder name is the unique | Name | Description | |------|-------------| | `description.json` | Contains the original task description, selected agent, and metadata | -| `entrypoint.sh` | Script that starts the task execution inside the sandbox | -| `inputs.json` | Input data provided to the coding agent | -| `workflow.yml` | The [workflow](/rover/concepts/workflow) guiding the coding agent to complete the task | | `iterations/` | Folder containing each iteration made by the coding agent | -| `workspace/` | The [workspace](/rover/concepts/workspace) where the coding agent applies changes | + +The [workspace](/rover/concepts/workspace) for each task is stored separately in the `workspaces/` directory. ### Iteration files +Each iteration has its own folder with the files needed to run the task in the sandbox: + | Name | Description | |------|-------------| -| `iteration.json` | Details of a specific iteration, including changes made and agent messages | +| `entrypoint.sh` | Script that starts the task execution inside the sandbox | +| `inputs.json` | Input data provided to the coding agent | +| `workflow.yml` | The [workflow](/rover/concepts/workflow) guiding the coding agent to complete the task | +| `iteration.json` | Details of the iteration, including changes made and agent messages | | `status.json` | Current status of the iteration (e.g., in-progress, completed) | @@ -69,7 +75,7 @@ You will find multiple folders in `.rover/tasks/`. The folder name is the unique Each task goes through a lifecycle with different states. Rover ensuses that tasks progress through these states as coding agents work on them. The Rover agent running in the [sandboxed environment](/rover/concepts/sandbox) updates the task status as the coding agents complete each step. -You can find the current status of a task in the `status.json` file inside the `.rover/tasks//iterations//` folder. +You can find the current status of a task in the `status.json` file inside the task's `iterations//` folder in the [global store](/rover/advanced/global-store). ```mermaid stateDiagram-v2 @@ -92,8 +98,8 @@ stateDiagram-v2 ## Next Steps - + - \ No newline at end of file + diff --git a/src/content/docs/rover/concepts/workflow.mdx b/src/content/docs/rover/concepts/workflow.mdx index e560ddb..28eb7f0 100644 --- a/src/content/docs/rover/concepts/workflow.mdx +++ b/src/content/docs/rover/concepts/workflow.mdx @@ -2,7 +2,7 @@ title: Workflow description: Discover how workflows guide AI coding agents through structured processes sidebar: - order: 3 + order: 4 --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; @@ -46,7 +46,7 @@ If you want to check a full workflow definition, checkout the Workflow File Refe ## Processing workflow -When you create a task, Rover copies the selected workflow into the [task folder](/rover/concepts/task/#local-structure). Then, the Rover agent manager that runs in the [sandboxed environment](/rover/concepts/sandbox) reads the workflow file and executes each step sequentially. +When you create a task, Rover copies the selected workflow into the [task folder](/rover/concepts/task/#task-storage). Then, the Rover agent manager that runs in the [sandboxed environment](/rover/concepts/sandbox) reads the workflow file and executes each step sequentially. This tool ensures that the coding agent follows the defined process, using the specified inputs and producing the expected outputs. It validates each step's completion before moving to the next one. @@ -96,8 +96,8 @@ rover logs ## Next Steps - + - \ No newline at end of file + diff --git a/src/content/docs/rover/concepts/workspace.mdx b/src/content/docs/rover/concepts/workspace.mdx index b0412a7..8a40154 100644 --- a/src/content/docs/rover/concepts/workspace.mdx +++ b/src/content/docs/rover/concepts/workspace.mdx @@ -2,7 +2,7 @@ title: Workspace description: Understand how Rover creates isolated workspaces using git worktrees for each task sidebar: - order: 2 + order: 3 --- import { FileTree } from '@astrojs/starlight/components'; @@ -18,27 +18,29 @@ A git worktree is a separate checkout of your repository, sharing the same `.git ## Workspace structure -When you create a new task, Rover will create a new worktree in the `.rover/tasks//workspace/` folder. This workspace starts from the branch you specify when [creating the task](/rover/reference/cli-reference/#task) (defaulting to the current branch). The coding agent will then apply changes directly in this workspace. +When you create a new task, Rover creates a new worktree in the [global store](/rover/advanced/global-store) at `~/.rover/data/projects//workspaces//`. This workspace starts from the branch you specify when [creating the task](/rover/reference/cli-reference/#task) (defaulting to the current branch). The coding agent will then apply changes directly in this workspace. -- .rover/ +- ~/.rover/data/projects/\/ - tasks/ - 1/ - 2/ - - description.json + - ... + - workspaces/ + - 1/ Git worktree for task 1 + - README.md + - src/ - ... - - workspace/ - - YOUR_README.md - - ... - - 3/ + - 2/ Git worktree for task 2 - ... + - logs/ ## Deleting a workspace -When you delete a task using `rover delete `, Rover will also remove the associated workspace, cleaning up the worktree and all its files. +When you delete a task using `rover delete `, Rover will also remove the associated workspace, cleaning up the worktree and all its files. -If you delete the `.rover/tasks/X/workspace/` folder manually, you will need to prune the git worktree references using: +If you delete the workspace folder manually from the global store, you will need to prune the git worktree references using: ```sh git worktree prune @@ -47,7 +49,7 @@ git worktree prune ## Next steps - + diff --git a/src/content/docs/rover/troubleshooting/permission-issues.mdx b/src/content/docs/rover/troubleshooting/permission-issues.mdx new file mode 100644 index 0000000..9c0db9d --- /dev/null +++ b/src/content/docs/rover/troubleshooting/permission-issues.mdx @@ -0,0 +1,84 @@ +--- +title: Permission Issues +description: Identify and solve permission issues on Rover +sidebar: + order: 1 +--- + +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +### Verify the Global Store Exists + +```bash +# macOS/Linux +ls -la ~/.rover + +# Windows (PowerShell) +Get-Item "$env:APPDATA\Rover" -ErrorAction SilentlyContinue +``` + +If the directory doesn't exist, run any Rover command to create it automatically. + +### Check File Permissions + +The global store should have restricted permissions. If you encounter permission errors: + +```bash +# macOS/Linux - fix permissions +chmod 700 ~/.rover +chmod 700 ~/.rover/config +chmod 700 ~/.rover/data +chmod 600 ~/.rover/config/rover.json +``` + +#### File Ownership in Workspaces + +When running Rover with Docker rootless mode, file ownership in your [workspace](/rover/concepts/workspace/) may temporarily change during task execution. This is expected behavior. Rover adjusts ownership to allow containers to read and write files properly, and will restore the original ownership at the end of the worfklow execution. + +**Before running `chown` commands**, check if any tasks are currently running: + +```bash +rover list +``` + +If a task is in progress, changing file ownership may cause it to fail. Wait for the task to complete before modifying ownership. Once tasks finish, Rover restores the original ownership automatically. + +If you need to manually restore ownership after all tasks have completed: + +```bash +# Restore ownership to your user and group +chown -R $(whoami):$(id -gn) ~/.rover/data/projects +``` + +### Corrupted Configuration + +If `rover.json` becomes corrupted: + +1. **Back up the current file:** + ```bash + cp ~/.rover/config/rover.json ~/.rover/config/rover.json.backup + ``` + +2. **Delete the corrupted file:** + ```bash + rm ~/.rover/config/rover.json + ``` + +3. **Run any Rover command** to regenerate a default configuration. + +**Note:** Deleting `rover.json` removes your project registrations. You'll need to re-register projects, but task data in `data/projects/` is preserved. + +### Reset the Global Store + +To completely reset Rover's global store: + +```bash +# macOS/Linux +rm -rf ~/.rover + +# Windows (PowerShell) +Remove-Item -Recurse "$env:APPDATA\Rover" +Remove-Item -Recurse "$env:LOCALAPPDATA\Rover" +``` + +**Warning:** This deletes all configuration, project registrations, tasks, and workspaces. Only do this as a last resort.