Skip to content

Commit 9b0a6dd

Browse files
Bullish-DesignBullish-Design
authored
Merge pull request #31 from Bullish-Design/codex/create-documentation-and-update-file-structure
Add docs, CI tooling, and reorganize tests
2 parents e7c81a2 + 9ef3dde commit 9b0a6dd

13 files changed

Lines changed: 226 additions & 11 deletions

‎README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,13 @@ Minimal workspace orchestrator for tmuxp + Claude Code + Neovim.
1717
./cli/devman
1818
```
1919

20+
## Documentation
21+
22+
- [Getting started](docs/getting-started.md)
23+
- [Workspace schema](docs/workspace-schema.md)
24+
- [Claude integration](docs/claude-integration.md)
25+
- [Troubleshooting](docs/troubleshooting.md)
26+
2027
## NixOS + Home Manager (flakes)
2128

2229
Use a flake input pinned with `git+` to avoid GitHub API rate limits.
@@ -66,9 +73,3 @@ Use `cli/setup_config.py` to validate `.env.example`, `.toml.example`, or
6673
```bash
6774
uv run ./cli/setup_config.py validate .env.example
6875
```
69-
70-
## Templates
71-
72-
- `templates/workspace-min`: starter `.devman/` layout for a single repo.
73-
- `templates/workspace-nixos-collection`: example multi-repo NixOS workspace
74-
with tmuxp + mini.sessions defaults.

‎docs/claude-integration.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Claude Code integration
2+
3+
## Requirements
4+
5+
Claude Code integration requires the `claude` CLI to be installed and available
6+
on your `PATH`. You can verify this with:
7+
8+
```bash
9+
claude --version
10+
```
11+
12+
## Workspace configuration
13+
14+
Configure Claude Code in `.devman/devman.toml`:
15+
16+
```toml
17+
[claude_code]
18+
interaction = "interaction.md" # optional
19+
emit_project_config = false # optional
20+
```
21+
22+
- `interaction` points to the interaction guide used by Claude Code.
23+
- `emit_project_config` controls whether devman writes `.claude/project.json`
24+
and an optional `CLAUDE.md` to the workspace root.
25+
26+
## What devman writes
27+
28+
When enabled, devman will:
29+
30+
- Create `.claude/settings.json` with workspace metadata.
31+
- Optionally emit `.claude/project.json` plus `CLAUDE.md` instructions so Claude
32+
Code can load workspace-specific context.
33+
34+
## Helpful commands
35+
36+
```bash
37+
./cli/devman doctor
38+
./cli/devman up
39+
./cli/devman bootstrap
40+
```
41+
42+
If the CLI is missing, these commands will surface a message pointing you to
43+
https://claude.ai/code.

‎docs/getting-started.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Getting Started
2+
3+
## Overview
4+
5+
devman is a minimal workspace orchestrator for tmuxp, Claude Code, and Neovim.
6+
It discovers `.devman/` workspaces, builds an index, and launches tmux sessions
7+
with the right editor context.
8+
9+
## Prerequisites
10+
11+
- **Python 3.11+** (use `uv` for environments).
12+
- **tmux** + **tmuxp** for session management.
13+
- **Neovim** (`nvim`) if you want editor/session bootstrapping.
14+
- **Claude Code** (`claude`) is required for Claude integration.
15+
16+
## Create a workspace
17+
18+
A workspace is any project root that contains a `.devman/` directory. The
19+
minimum requirement is the directory itself, but a `devman.toml` file provides
20+
metadata and paths.
21+
22+
Example `.devman/devman.toml`:
23+
24+
```toml
25+
[workspace]
26+
name = "my-app"
27+
28+
[tmuxp]
29+
workspace = "workspace.tmuxp.yaml"
30+
session_name = "my-app"
31+
32+
[claude_code]
33+
interaction = "interaction.md"
34+
emit_project_config = false
35+
36+
[nvim]
37+
init = "nvim/init.lua"
38+
listen = ".devman/.state/nvim.sock"
39+
sessions_dir = "sessions"
40+
default_session = "home.vim"
41+
```
42+
43+
For the full schema, see [`docs/workspace-schema.md`](workspace-schema.md).
44+
45+
## Build the index
46+
47+
```bash
48+
./cli/devman index rebuild
49+
```
50+
51+
## Launch devman
52+
53+
```bash
54+
./cli/devman
55+
```
56+
57+
## Switch workspaces
58+
59+
```bash
60+
./cli/devman switch <name|tag|path>
61+
```
62+
63+
## Next steps
64+
65+
- Review the workspace schema in [`docs/workspace-schema.md`](workspace-schema.md).
66+
- Configure Claude Code in [`docs/claude-integration.md`](claude-integration.md).
67+
- If something fails, check [`docs/troubleshooting.md`](troubleshooting.md).

‎docs/troubleshooting.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Troubleshooting
2+
3+
## Verify external tools
4+
5+
Run the doctor command to check for required dependencies:
6+
7+
```bash
8+
./cli/devman doctor
9+
```
10+
11+
Ensure these tools are installed:
12+
13+
- `tmux`
14+
- `tmuxp`
15+
- `nvim` (if you use Neovim integration)
16+
- `claude`
17+
18+
## Workspace not found
19+
20+
- Confirm the workspace root contains a `.devman/` directory.
21+
- Rebuild the index:
22+
23+
```bash
24+
./cli/devman index rebuild
25+
```
26+
27+
## tmuxp session issues
28+
29+
- Verify the `workspace.tmuxp.yaml` path in `.devman/devman.toml`.
30+
- Confirm the file exists relative to `.devman/`.
31+
32+
## Claude Code not detected
33+
34+
- Ensure the `claude` CLI is on your `PATH`.
35+
- Re-run `./cli/devman doctor` to confirm availability.

‎docs/workspace-schema.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Workspace schema
2+
3+
This document defines the `.devman/devman.toml` schema used by devman.
4+
5+
## Overview
6+
7+
- **Required** fields are listed explicitly.
8+
- All paths are relative to the `.devman/` directory unless noted.
9+
- TOML overrides `.env` values if both are present.
10+
11+
## Schema
12+
13+
```toml
14+
[workspace]
15+
name = "my-app" # required
16+
tags = ["api", "web"] # optional
17+
group = "client-x" # optional
18+
19+
[tmuxp]
20+
workspace = "workspace.tmuxp.yaml" # optional
21+
session_name = "my-app" # optional
22+
23+
[claude_code]
24+
interaction = "interaction.md" # optional
25+
emit_project_config = false # optional
26+
27+
[nvim]
28+
init = "nvim/init.lua" # optional
29+
listen = ".devman/.state/nvim.sock" # optional (relative to workspace root)
30+
sessions_dir = "sessions" # optional
31+
default_session = "home.vim" # optional
32+
```
33+
34+
## Precedence rules
35+
36+
1. `.devman/devman.toml` is the primary configuration source.
37+
2. `.devman/.env` may supply environment toggles for:
38+
- `DEVMAN_TMUXP_WORKSPACE`
39+
- `DEVMAN_SESSION_NAME`
40+
3. If TOML fields are present they always override `.env` values.
41+
42+
## Required files
43+
44+
A workspace is valid if `.devman/` exists. The following files are optional but
45+
recommended for full functionality:
46+
47+
- `.devman/devman.toml`
48+
- `.devman/interaction.md`
49+
- `.devman/workspace.tmuxp.yaml`
50+
- `.devman/nvim/init.lua`
51+
- `.devman/sessions/home.vim`

‎pyproject.toml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,13 @@ warn_unused_configs = true
7272
disallow_untyped_defs = true
7373

7474
[tool.pytest.ini_options]
75-
testpaths = ["src/tests"]
75+
testpaths = ["tests/unit", "tests/integration"]
7676
addopts = "-v --cov=src/devman --cov-report=html"
7777
python_files = ["test_*.py", "*_test.py"]
78+
markers = [
79+
"unit: fast, isolated tests",
80+
"integration: integration or external dependency coverage",
81+
]
7882

7983
[tool.coverage.report]
8084
exclude_lines = [

src/tests/run_tests.py renamed to scripts/run_tests.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
# ]
1111
# ///
1212

13-
# tests/run_tests.py
13+
# scripts/run_tests.py
1414
"""Test runner script for devman library."""
1515

1616
from __future__ import annotations
@@ -22,8 +22,9 @@
2222

2323
def main() -> None:
2424
"""Run pytest with coverage and formatting."""
25-
test_dir = Path(__file__).parent
26-
src_dir = test_dir.parent / "src"
25+
repo_root = Path(__file__).resolve().parent.parent
26+
test_dir = repo_root / "tests"
27+
src_dir = repo_root / "src"
2728

2829
cmd = [
2930
sys.executable,

‎scripts/test.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
uv sync --extra dev
5+
uv run pytest

src/tests/conftest.py renamed to tests/conftest.py

File renamed without changes.

‎tests/fixtures/.gitkeep‎

Whitespace-only changes.

0 commit comments

Comments
 (0)