Skip to content

Commit 030de7a

Browse files
matheusbuniottomatheusbuniotto
authored
Merge pull request #1 from matheusbuniotto/fix/open-permissions-and-set-key
fix: opt-in --dangerously-skip-permissions on mind open; add mind set-key
2 parents 47a9a63 + a9a426e commit 030de7a

31 files changed

Lines changed: 2094 additions & 67 deletions

‎.github/workflows/ci.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, dev]
6+
pull_request:
7+
branches: [main, dev]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.11", "3.12"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Install uv
20+
uses: astral-sh/setup-uv@v4
21+
with:
22+
version: "latest"
23+
24+
- name: Set up Python ${{ matrix.python-version }}
25+
run: uv python install ${{ matrix.python-version }}
26+
27+
- name: Install dependencies
28+
run: uv sync --all-groups
29+
30+
- name: Run tests
31+
run: uv run pytest tests/ -v
32+
33+
lint:
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- uses: actions/checkout@v4
38+
39+
- name: Install uv
40+
uses: astral-sh/setup-uv@v4
41+
with:
42+
version: "latest"
43+
44+
- name: Install dependencies
45+
run: uv sync --all-groups
46+
47+
- name: Lint with ruff
48+
run: uv run ruff check mind/ tests/

‎CONTRIBUTING.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Contributing to mind
2+
3+
## Dev setup
4+
5+
```bash
6+
git clone https://github.com/matheusbuniotto/mind-cli
7+
cd mind-cli
8+
uv sync --all-groups # installs deps + dev deps (pytest, ruff)
9+
uv tool install . --editable # editable install so `mind` picks up local changes
10+
```
11+
12+
Verify:
13+
14+
```bash
15+
mind --version
16+
uv run pytest tests/ -v
17+
uv run ruff check mind/ tests/
18+
```
19+
20+
## Running tests
21+
22+
```bash
23+
uv run pytest tests/ -v # all tests
24+
uv run pytest tests/test_claude_code_adapter.py -v # one module
25+
```
26+
27+
Fixtures live in `tests/fixtures/` as JSONL files — add new ones there when writing adapter tests.
28+
29+
## Adding a new adapter
30+
31+
1. Create `mind/adapters/<source>.py` implementing the `SessionAdapter` protocol from `mind/adapters/base.py`:
32+
33+
```python
34+
class MySourceAdapter:
35+
name = "my-source"
36+
37+
def discover(self, cwd: str) -> list[SessionRef]: ...
38+
def active_context(self, cwd: str, sessions, *, max_chars) -> list[str]: ...
39+
def card_candidates(self, cwd, sessions, *, session_limit) -> list[SessionCardCandidate]: ...
40+
def inspect_stats(self, cwd, sessions, *, session_limit) -> AdapterInspectStats: ...
41+
```
42+
43+
2. Register it in `mind/adapters/registry.py` by adding it to the list in `get_adapters()`.
44+
45+
3. Add a fixture JSONL in `tests/fixtures/` and a `tests/test_<source>_adapter.py` following the pattern in `test_claude_code_adapter.py`.
46+
47+
Third-party adapters (outside this repo) can register via the `mind.adapters` entry-point group:
48+
49+
```toml
50+
[project.entry-points."mind.adapters"]
51+
my-source = "my_package.adapters:MySourceAdapter"
52+
```
53+
54+
See `mind/adapters/base.py` for the full contract and `ADAPTERS.md` for design notes.
55+
56+
## Project structure
57+
58+
```
59+
mind/
60+
adapters/ # one file per session source
61+
base.py # SessionAdapter protocol + shared dataclasses
62+
registry.py # built-in list + entry-point loader
63+
commands/ # one file per CLI command group
64+
display.py # all Rich TUI rendering
65+
store.py # SQLite access (digests, session cards, notes)
66+
sync.py # orchestration: discover → card candidates → digest
67+
check.py # staleness checks for SessionStart hooks (no LLM)
68+
tests/
69+
fixtures/ # sample JSONL files for adapter tests
70+
```
71+
72+
## Pull requests
73+
74+
- Keep PRs focused — one concern per PR.
75+
- All tests must pass (`uv run pytest tests/`).
76+
- Lint must pass (`uv run ruff check mind/ tests/`).
77+
- New adapters need at least one fixture and one test class.
78+
79+
## Good first issues
80+
81+
- Add a Cursor session adapter test with a fixture JSONL.
82+
- Add a `mind update` command that re-runs `uv tool install`.
83+
- Add a `--json` flag to `mind ls` for scripting.
84+
- Improve the `_decode_project_dir` function to handle paths with hyphens (currently ambiguous).

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Matheus Buniotto
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎OPEN_SOURCE_ADOPTION.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -185,9 +185,9 @@ If I were prioritizing for adoption, I would do this in order:
185185
| 2 | Trust and safety | P0 | M | Add `--inspect` / dry-run, make data provenance visible, document storage vs model-bound data, and introduce redaction rules. | done |
186186
| 3 | Proof of value in the output | P0 | M | Tighten the restore brief, emphasize blockers / next actions, and add a compact “changed since last sync” section. | done |
187187
| 4 | Adapter extensibility | P1 | L | Define adapter contracts, add a registry, move built-ins behind the interface, and document how to add `pi-agent`, `opencode`, or future sources. | done |
188-
| 5 | Reliability and verifiability | P1 | M | Add fixture-based tests for adapters and snapshots, then wire CI around the core flow. | to-do |
189-
| 6 | Distribution and package polish | P1 | S | Add `--version`, public install docs, release checklist, and complete package metadata for broader distribution. | to-do |
190-
| 7 | Contribution surface | P2 | S | Add `CONTRIBUTING.md`, fixture docs, and clearly scoped good-first issues for adapters and tests. | to-do |
188+
| 5 | Reliability and verifiability | P1 | M | Add fixture-based tests for adapters and snapshots, then wire CI around the core flow. | done |
189+
| 6 | Distribution and package polish | P1 | S | Add `--version`, public install docs, release checklist, and complete package metadata for broader distribution. | done |
190+
| 7 | Contribution surface | P2 | S | Add `CONTRIBUTING.md`, fixture docs, and clearly scoped good-first issues for adapters and tests. | done |
191191

192192
### Status rules
193193

@@ -197,17 +197,19 @@ If I were prioritizing for adoption, I would do this in order:
197197

198198
## Concrete next work items
199199

200-
- add fixture-based tests for the adapters and snapshot rendering
201-
- add a CI workflow
202-
- add a minimal contributor guide
203-
- tighten restore output for “proof of value” (item 3)
200+
All adoption backlog items are done. Remaining polish:
204201

205-
## Notes on current gaps
202+
- publish to PyPI (`uv build && uv publish`)
203+
- tag v0.1.0 release on GitHub
204+
- open “good first issue” tickets for the items listed in `CONTRIBUTING.md`
206205

207-
The repo currently has:
206+
## Notes on current state
208207

209-
- no `tests/` directory
210-
- no CI workflow
211-
- no visible sample output fixtures (beyond `mind doctor --demo`)
208+
The repo now has:
212209

213-
That means the core product is present, but several adoption and contribution mechanics are still missing.
210+
- `tests/` with fixture-based adapter and snapshot tests (37 passing)
211+
- `.github/workflows/ci.yml` running pytest + ruff on Python 3.11 and 3.12
212+
- `LICENSE` (MIT)
213+
- `CONTRIBUTING.md` with dev setup, adapter guide, and good-first-issue list
214+
- `mind --version` reading from package metadata
215+
- public install instructions in `README.md` (PyPI + from source)

‎README.md‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,56 @@ Implemented today:
4646

4747
## Install
4848

49-
This project is meant to be installed locally from the repo:
49+
```bash
50+
# from PyPI (recommended)
51+
uv tool install mind-cli
52+
# or with pip
53+
pip install mind-cli
54+
```
55+
56+
```bash
57+
# from source (dev / latest)
58+
git clone https://github.com/matheusbuniotto/mind-cli
59+
uv tool install ./mind-cli
60+
```
61+
62+
```bash
63+
mind init # first time: config wizard + skill + hooks
64+
# after upgrading mind:
65+
mind install -y # refresh skill + hooks only
66+
```
67+
68+
### Agent integrations (skill + hook)
69+
70+
`mind` ships a **mind-recap** skill and a **session-start hook** that runs `mind check` (no LLM — only git/session staleness).
71+
72+
| Command | When |
73+
|---------|------|
74+
| `mind init` | First run — config wizard + install skill/hooks |
75+
| `mind install -y` | After `uv tool install` upgrade — refresh skill/hooks only |
5076

5177
```bash
52-
uv tool install /Users/matheus/Awesome-tools/mind
78+
mind install -y # refresh skill + hook (auto-detect agents)
79+
mind install --skill # skill only
80+
mind install --hook # hook only
81+
mind init --no-agents # config only, skip skill/hooks
5382
```
5483

84+
| Agent | Skill path | Hook |
85+
|-------|------------|------|
86+
| Claude Code | `~/.claude/skills/mind-recap/` | `SessionStart` → `~/.claude/hooks/mind-check.sh` |
87+
| Cursor | `~/.cursor/skills/mind-recap/` | `sessionStart` → `~/.cursor/hooks/mind-check.sh` |
88+
| Codex | `~/.codex/skills/` + `~/.agents/skills/` | `SessionStart` → `~/.codex/hooks/mind-check.sh` |
89+
90+
**Without the `mind` CLI** — install the skill from [matheusbuniotto/skills-library](https://github.com/matheusbuniotto/skills-library):
91+
92+
```bash
93+
npx skills add matheusbuniotto/skills-library --skill mind-recap -a claude-code -a cursor -a codex -g -y
94+
```
95+
96+
When the user asks for a recap, the skill runs `mind restore` and asks before `mind sync`.
97+
Hooks nudge on session start when the digest is missing, old, or git/sessions drifted (run `/hooks` in Codex to trust new hooks).
98+
5599
## Usage
56100

57101
### Restore context
@@ -84,6 +128,14 @@ By default, sync summarizes the 2 most recent sessions, plus all Claude compacti
84128

85129
`--inspect` prints the same local file inventory `sync` would use, **without** writing SQLite rows or calling a model.
86130

131+
### Check context freshness (no API)
132+
133+
```bash
134+
mind check
135+
mind check --quiet # for scripts / hooks
136+
mind check --json
137+
```
138+
87139
### First-run diagnostics
88140

89141
```bash

0 commit comments

Comments
 (0)