feat: projects and worktree management (#62)

2026-01-07 17:45:05 +04:00
parent 1178b738df
commit aa078258ea
28 changed files with 1735 additions and 144 deletions
@@ -0,0 +1,135 @@
+# Projects and Worktrees
+
+This doc covers project aliases, worktree behavior, and how Takopi resolves run
+context from messages.
+
+## Overview
+
+Projects let you give a repo an alias (used as `/alias` in messages) and opt into
+worktree-based runs via `@branch`.
+
+- If no projects are configured, Takopi runs in the startup working directory.
+- If a project is configured, `@branch` resolves/creates a git worktree and runs
+  the task in that worktree.
+- Progress/final messages include a `ctx:` footer when project context is active.
+
+## Config schema
+
+All config lives in `~/.takopi/takopi.toml`.
+
+```toml
+default_engine = "codex"       # optional
+default_project = "z80"        # optional
+bot_token = "..."              # required
+chat_id = 123                  # required
+
+[projects.z80]
+path = "~/dev/z80"             # required (repo root)
+worktrees_dir = ".worktrees"   # optional, default ".worktrees"
+default_engine = "codex"       # optional, per-project override
+worktree_base = "master"       # optional, base for new branches
+```
+
+Validation rules:
+
+- `projects` is optional.
+- Each project entry must include `path` (string, non-empty).
+- `default_project` must match a configured project alias.
+- Project aliases cannot collide with engine ids or reserved commands (`/cancel`).
+- `default_engine` and per-project `default_engine` must be valid engine ids.
+
+## `takopi init`
+
+`takopi init <alias>` registers the current repo as a project alias.
+
+Important behavior:
+
+- The stored `path` is the **main checkout** of the repo, even if you run
+  `takopi init` inside a worktree. Takopi resolves the repo root via the git
+  common dir and writes that path to `[projects.<alias>].path`.
+- `worktree_base` is set from the current repo using this resolution order:
+  `origin/HEAD` → current branch → `master` → `main`.
+
+## Directives and context resolution
+
+Takopi parses the first non-empty line of a message for a directive prefix.
+
+Supported directives:
+
+- `/engine` or `/engine@bot`: chooses the engine
+- `/project`: chooses a project alias
+- `@branch`: chooses a git branch/worktree
+
+Rules:
+
+- Directives must be a contiguous prefix of the line; parsing stops at the first
+  non-directive token.
+- At most one engine directive, one project directive, and one `@branch` are
+  allowed (duplicates are errors).
+- If a reply contains a `ctx:` line, Takopi **ignores new directives** and uses
+  the reply context.
+
+## Context footer (`ctx:`)
+
+When a run has project context, Takopi appends a footer line rendered as inline
+code (backticked):
+
+- With branch: `` `ctx: <project> @ <branch>` ``
+- Without branch: `` `ctx: <project>` ``
+
+The `ctx:` line is parsed from replies and takes precedence over new directives.
+
+## Worktree resolution
+
+When `@branch` is present:
+
+```
+worktrees_root = <project.path> / <worktrees_dir>
+worktree_path = worktrees_root / <branch>
+```
+
+Branch validation:
+
+- Must be non-empty
+- Must not start with `/`
+- Must not contain `..` path segments
+- May include `/` (nested directories)
+- The resolved worktree path must stay within `worktrees_root`
+
+Worktree creation rules:
+
+1) If `worktree_path` exists:
+   - It must be a git worktree or Takopi errors.
+2) If it does not exist:
+   - If local branch exists: `git worktree add <path> <branch>`
+   - Else if remote `origin/<branch>` exists:
+     `git worktree add -b <branch> <path> origin/<branch>`
+   - Else:
+     `git worktree add -b <branch> <path> <base>`
+
+Base branch selection:
+
+1) `projects.<alias>.worktree_base` (if set)
+2) `origin/HEAD` (if present)
+3) current checked out branch
+4) `master` if it exists
+5) `main` if it exists
+6) otherwise error
+
+When `@branch` is omitted:
+
+- Takopi runs in `<project.path>` (the main checkout).
+
+## Examples
+
+Start a new thread in a worktree:
+
+```
+/z80 @feat/streaming fix flaky test
+```
+
+Reply to a progress message to continue in the same context:
+
+```
+ctx: z80 @ feat/streaming
+```