Defines new path manager

[leoyala]

Summary

This PR defines a new path manager functionality to resolve the root directory of the local store. This also introduces a new local store directory creation, which creates the directory based on a template.

Changes

• New path manager submodule.
• New mechanism to create local store path based on directory templates.

Test plan

• uv run pytest passes.
• Run dstrack init multiple times and check the created directory.

Summary by CodeRabbit

• New Features

  • Added local store root discovery that checks an explicit root, an environment override, or walks upward from the current folder to find the existing store.
  • Store initialization now uses a declarative template to create the expected directory structure and .gitignore contents.

• Bug Fixes

  • Added a clear error when no local store can be resolved, with guidance on recovery.
  • Prevents partial store creation by only creating/moving the final destination after successful template materialization.

• Tests

  • Expanded coverage for store-path resolution and template materialization behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fb1f0694-9ff3-4093-b237-0e9d26c0857f

📥 Commits

Reviewing files that changed from the base of the PR and between 9265d7e and 215729e.

📒 Files selected for processing (1)

• src/dstrack/_store_template.py

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

• src/dstrack/_store_template.py

---

📝 Walkthrough

Walkthrough

This PR adds declarative store template materialization, rewrites local store initialization to build in a temporary directory before renaming into place, and adds store-root resolution with a new exception type and upward .dstrack search.

Changes

Store template, initialization, and root resolution

Layer / File(s)	Summary
Store template primitives and materialize() src/dstrack/_store_template.py, tests/test_store_template.py	Adds TemplateFile/TemplateDir, STORE_TEMPLATE, and recursive materialize() behavior, with tests for structure, nesting, and overwrite handling.
CLI init via temp materialization src/dstrack/_cli.py, tests/test_cli.py	init_local_store() now materializes the store in a temp directory and renames it into place, with tests covering failure rollback and the destination remaining absent until the build completes.
Store root resolution src/dstrack/errors.py, src/dstrack/paths.py, tests/test_paths.py	Adds StoreNotFoundError, _find_store_root(), and resolve_store_root() with explicit-root, env-var, and upward-search resolution, plus tests for discovery and boundary handling.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant init_local_store as init_local_store
  participant materialize as materialize
  participant filesystem as filesystem

  init_local_store->>filesystem: create temp dir under invocation path
  init_local_store->>materialize: materialize(STORE_TEMPLATE, tmp_dir)
  materialize->>filesystem: create directories and files
  alt materialize fails
    materialize-->>init_local_store: raise exception
    init_local_store-->>init_local_store: raise StoreInitError
  else success
    materialize-->>init_local_store: return built_path
    init_local_store->>filesystem: rename built_path to .dstrack
  end

Loading

Possibly related issues

• path manager #30: Adds store-root resolution via --root, DSTRACK_ROOT_PATH, and upward .dstrack discovery, matching the new path resolution flow.

Possibly related PRs

• leoyala/dstrack#22: Also changes src/dstrack/_cli.py store initialization and its rollback behavior, overlapping the same local-store setup path.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the main addition of a new path resolution module, though it omits the store-template refactor.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 30-path-manager

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Test Results

   48 files  ±  0     48 suites  ±0   35s ⏱️ +2s
   59 tests + 10     59 ✅ + 10  0 💤 ±0  0 ❌ ±0 
1 416 runs  +240  1 416 ✅ +240  0 💤 ±0  0 ❌ ±0 

Results for commit 215729e. ± Comparison against base commit 383e2e3.

This pull request removes 3 and adds 13 tests. Note that renamed tests count towards both.

tests.test_cli ‑ test_init_local_store_gitignore_creates_file
tests.test_cli ‑ test_init_local_store_gitignore_raises_if_exists
tests.test_cli ‑ test_init_local_store_rolls_back_on_gitignore_failure

tests.test_cli ‑ test_init_local_store_does_not_touch_destination_until_built
tests.test_cli ‑ test_init_local_store_rolls_back_on_template_failure
tests.test_paths ‑ test_find_store_root_error_message_mentions_overrides
tests.test_paths ‑ test_find_store_root_stops_at_filesystem_boundary
tests.test_paths ‑ test_resolve_store_root_finds_dstrack_in_ancestor
tests.test_paths ‑ test_resolve_store_root_finds_dstrack_in_cwd
tests.test_paths ‑ test_resolve_store_root_raises_when_not_found
tests.test_paths ‑ test_resolve_store_root_uses_env_var_when_no_cli_root
tests.test_paths ‑ test_resolve_store_root_uses_root_when_given
tests.test_store_template ‑ test_materialize_creates_expected_structure
…

♻️ This comment has been updated with latest results.

[coderabbitai]

Actionable comments posted: 1

🤖 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/dstrack/_store_template.py`:
- Around line 46-57: materialize() currently only enforces exclusive creation
for directories, while TemplateFile entries are still written with write_text()
and can silently overwrite existing content, which contradicts the docstring and
promised FileExistsError behavior. Update materialize() so it checks whether
each file path already exists before writing (and raises FileExistsError
consistently for both files and directories), using the existing path/template
handling in materialize(), TemplateDir, and the per-entry write logic to
preserve exclusive-create semantics for all entries.

🪄 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 Plus

Run ID: 4edef2ad-1514-4d89-8235-683c3da5e409

📥 Commits

Reviewing files that changed from the base of the PR and between 383e2e3 and 9265d7e.

📒 Files selected for processing (7)

• src/dstrack/_cli.py
• src/dstrack/_store_template.py
• src/dstrack/errors.py
• src/dstrack/paths.py
• tests/test_cli.py
• tests/test_paths.py
• tests/test_store_template.py