devin-doctor 0.1.0__tar.gz

devin_doctor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Icaro0310
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devin_doctor-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: devin-doctor
+Version: 0.1.0
+Summary: Diagnose a Devin Desktop installation: stores, schema versions, hooks, MCP servers, disk usage — with fix suggestions.
+Author: Icaro0310
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: devin-internals-spec<0.4.0,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-doctor" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-doctor/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-doctor/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+<a href="https://github.com/Icaro0310/devin-doctor/releases"><img src="https://img.shields.io/github/v/release/Icaro0310/devin-doctor" alt="GitHub release"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-doctor"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-doctor/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+
+
+</div>
+
+# devin-doctor
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+`devin-doctor` diagnoses a Devin Desktop installation — one command that
+checks the local stores, schema versions, config files and disk usage, then
+prints a health report with concrete fix suggestions. Read-only, always.
+
+## The problem
+
+Devin keeps a lot of local state: a versioned `sessions.db`, one
+`acp-messages/*.db` per GUI session, a `state.vscdb` KV store,
+`credentials.toml` and JSONC config files. When any of it breaks or bloats —
+a schema the tooling doesn't know, a locked database, an unreadable hooks
+file, a 700 MiB sessions store — nothing warns you. You find out indirectly:
+missing history, auth errors, disk pressure.
+
+`devin-doctor` is `brew doctor` for that installation.
+
+## Prior art
+
+- `brew doctor` / `flutter doctor` — the genre: one command, many checks,
+  PASS/WARN/FAIL with fix suggestions. This project adapts the pattern; it
+  does not reinvent it.
+- [`devin-internals-spec`](https://github.com/Icaro0310/devin-internals-spec)
+  — provides the schema-version detector, the read-only store parsers and
+  the fixture generator this project builds on.
+
+## What makes it Devin-native
+
+It understands Devin's actual on-disk layout — the `refinery_schema_history`
+migration ledger, the `acp-messages` per-session stores, `state.vscdb`, and
+the `.devin/` hooks/MCP config format — things no generic system check can
+see. Remove Devin and there is nothing to diagnose.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+```bash
+pipx install "devin-doctor @ git+https://github.com/Icaro0310/devin-doctor.git"
+```
+
+(Not published on PyPI yet; the GitHub install above is the supported route.)
+
+## Usage
+
+```bash
+devin-doctor check                    # diagnose the default data dir
+devin-doctor check --data-dir D:\devin-backup
+# Use a separate Devin UI config root (e.g. Linux)
+devin-doctor check --data-dir ~/.local/share/devin --config-dir ~/.config/Devin
+devin-doctor check --json             # machine-readable output
+devin-doctor report --md              # markdown, for pasting into issues
+devin-doctor capabilities             # machine capability profile, JSON
+```
+
+Each check prints `PASS`/`WARN`/`FAIL`, a one-line finding and a `fix:`
+suggestion. Exit code is `0` unless something `FAIL`s (then `1`).
+
+The six checks:
+
+| check | reports |
+|---|---|
+| `stores` | present/missing, sizes and row counts for `sessions.db`, `acp-messages/*.db`, `state.vscdb` |
+| `schema` | schema version vs the supported range (15–17); layout recognition for the ledger-less stores |
+| `health-of-data` | empty sessions, orphan `message_nodes`, sessions idle > `--stale-days`, `SQLITE_BUSY` locks |
+| `config` | `credentials.toml` presence + validity (**values masked**); `.devin/` hooks/MCP config sanity |
+| `hooks-windows` | hooks/MCP commands that would pop a visible console window on Windows (`cmd /c` without a hidden wrapper, `powershell` without `-WindowStyle Hidden`, direct `.bat`/`.ps1`, `python.exe` vs `pythonw.exe`) — each with file, hook event and a wrapper fix |
+| `disk` | total data-dir size, largest DBs, `acp-messages` accumulation trend |
+
+## Capability profile
+
+```bash
+devin-doctor capabilities             # JSON profile, exit 0
+devin-doctor capabilities --probe-network
+```
+
+`capabilities` prints a JSON object — `{"profile": ..., "capabilities":
+{...}}` — describing what the machine can do for the ecosystem (scheduler,
+daemon, local LLM, containers, comms, proxy, ≥24 GiB RAM, …). The profile is
+`corporate` by default (**fail-closed**); `personal` applies only when
+explicitly declared via `DEVIN_ECOSYSTEM_PROFILE=corporate|personal` or
+`devin-profile.json` (`{"profile": "personal"}`) in the Devin config dir —
+the env var wins. All probing is local; `net.outbound`/`net.listener`
+stay `"unknown"` unless `--probe-network` is passed, which performs exactly
+ONE outbound TCP connect (1.1.1.1:443 or the configured `HTTPS_PROXY`, 2 s
+timeout) plus a loopback bind — the only network call this tool can make.
+
+## Works with Devin alone (Devin-only mode)
+
+devin-doctor is a pure local diagnostic: it reads Devin's own data
+directories, writes nothing, and never contacts a network service. No VM, no
+Tailscale, no Ollama, no Slack — just Devin Desktop plus Python. On a
+restricted or corporate machine it is the safest first tool: install, run
+`devin-doctor`, read the report.
+
+## Platform support
+
+Tested on Windows and Linux. On Linux, session data defaults to
+`$XDG_DATA_HOME/devin` (normally `~/.local/share/devin`) and UI stores default
+to `$XDG_CONFIG_HOME/Devin` (normally `~/.config/Devin`). Windows stores use
+`%APPDATA%\devin` and `%APPDATA%\Devin`. Use `--data-dir` and `--config-dir`
+when the stores are elsewhere. macOS paths exist but are not verified.
+
+
+### `devin-doctor plan` — remediation plan, still read-only
+
+`plan` runs the same checks but emits a numbered remediation plan for every
+WARN/FAIL finding (the check's `fix` suggestion) instead of a verdict —
+nothing is executed; execution stays a human decision or another tool's job.
+`--json` gives `{"overall", "steps": [{check, status, finding, fix}]}`.
+This replaced the original `--fix` idea so doctor can keep its
+"read-only, always" guarantee.
+
+## Limitations
+
+- **Version-bound.** Store parsing follows `devin-internals-spec` (schema
+  v15–v17). A newer Devin schema reports FAIL — "unknown version" — by
+  design, rather than silently misreading.
+- **Read-only.** It suggests fixes but never touches the data dir. `--fix`
+  for the safe items is planned (see `STATUS.md`).
+- **Locked stores.** If Devin is running, DBs may report `SQLITE_BUSY` —
+  close Devin and re-run.
+- macOS paths are implemented but not verified in CI.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests run entirely on synthetic fixtures generated by
+`devin_internals.fixtures` — no real session data is ever read or required.
+`scripts/make_fixture.py <dir>` builds a fixture data dir for manual runs.
+
+## When to use this
+
+- Devin misbehaves — missing history, auth errors, disk pressure — and you want one command to localize the cause.
+- You want a health check before debugging: six checks (stores, schema, data health, config, hooks-windows, disk), each with a `fix:` suggestion.
+- You need a paste-able report for a bug report: `devin-doctor report --md`.
+- You are on a restricted machine: it is read-only and never contacts the network.
+
+## When NOT to use this
+
+- You want it to repair things — it is read-only; `--fix` for safe items is planned.
+- Your Devin schema is newer than v17 — it reports "unknown version" FAIL rather than misread.
+- Devin is running and DBs are locked — close Devin and re-run to clear `SQLITE_BUSY`.
+
+## FAQ
+
+**How do I check if my Devin installation's local data is healthy?** Run `devin-doctor check`. It inspects `sessions.db`, `acp-messages/*.db`, `state.vscdb`, `credentials.toml` and disk usage, printing `PASS`/`WARN`/`FAIL` per check with a `fix:` suggestion. Exit code is `0` unless something FAILs.
+
+**Is devin-doctor safe to run? Will it modify my data?** It is strictly read-only — it opens Devin's stores for reading, writes nothing to the data dir, and never contacts a network service. Config check masks credential values in output. Fixes are suggested as text, never applied.
+
+**What does "unknown schema version" mean?** Devin's `sessions.db` schema is versioned; devin-doctor understands v15–v17 via devin-internals-spec. A newer version produces a deliberate FAIL instead of a silent misread — update the tool or devin-internals-spec.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devin_doctor-0.1.0/README.md

@@ -0,0 +1,178 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-doctor" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-doctor/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-doctor/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+<a href="https://github.com/Icaro0310/devin-doctor/releases"><img src="https://img.shields.io/github/v/release/Icaro0310/devin-doctor" alt="GitHub release"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-doctor"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-doctor/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+
+
+</div>
+
+# devin-doctor
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+`devin-doctor` diagnoses a Devin Desktop installation — one command that
+checks the local stores, schema versions, config files and disk usage, then
+prints a health report with concrete fix suggestions. Read-only, always.
+
+## The problem
+
+Devin keeps a lot of local state: a versioned `sessions.db`, one
+`acp-messages/*.db` per GUI session, a `state.vscdb` KV store,
+`credentials.toml` and JSONC config files. When any of it breaks or bloats —
+a schema the tooling doesn't know, a locked database, an unreadable hooks
+file, a 700 MiB sessions store — nothing warns you. You find out indirectly:
+missing history, auth errors, disk pressure.
+
+`devin-doctor` is `brew doctor` for that installation.
+
+## Prior art
+
+- `brew doctor` / `flutter doctor` — the genre: one command, many checks,
+  PASS/WARN/FAIL with fix suggestions. This project adapts the pattern; it
+  does not reinvent it.
+- [`devin-internals-spec`](https://github.com/Icaro0310/devin-internals-spec)
+  — provides the schema-version detector, the read-only store parsers and
+  the fixture generator this project builds on.
+
+## What makes it Devin-native
+
+It understands Devin's actual on-disk layout — the `refinery_schema_history`
+migration ledger, the `acp-messages` per-session stores, `state.vscdb`, and
+the `.devin/` hooks/MCP config format — things no generic system check can
+see. Remove Devin and there is nothing to diagnose.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+```bash
+pipx install "devin-doctor @ git+https://github.com/Icaro0310/devin-doctor.git"
+```
+
+(Not published on PyPI yet; the GitHub install above is the supported route.)
+
+## Usage
+
+```bash
+devin-doctor check                    # diagnose the default data dir
+devin-doctor check --data-dir D:\devin-backup
+# Use a separate Devin UI config root (e.g. Linux)
+devin-doctor check --data-dir ~/.local/share/devin --config-dir ~/.config/Devin
+devin-doctor check --json             # machine-readable output
+devin-doctor report --md              # markdown, for pasting into issues
+devin-doctor capabilities             # machine capability profile, JSON
+```
+
+Each check prints `PASS`/`WARN`/`FAIL`, a one-line finding and a `fix:`
+suggestion. Exit code is `0` unless something `FAIL`s (then `1`).
+
+The six checks:
+
+| check | reports |
+|---|---|
+| `stores` | present/missing, sizes and row counts for `sessions.db`, `acp-messages/*.db`, `state.vscdb` |
+| `schema` | schema version vs the supported range (15–17); layout recognition for the ledger-less stores |
+| `health-of-data` | empty sessions, orphan `message_nodes`, sessions idle > `--stale-days`, `SQLITE_BUSY` locks |
+| `config` | `credentials.toml` presence + validity (**values masked**); `.devin/` hooks/MCP config sanity |
+| `hooks-windows` | hooks/MCP commands that would pop a visible console window on Windows (`cmd /c` without a hidden wrapper, `powershell` without `-WindowStyle Hidden`, direct `.bat`/`.ps1`, `python.exe` vs `pythonw.exe`) — each with file, hook event and a wrapper fix |
+| `disk` | total data-dir size, largest DBs, `acp-messages` accumulation trend |
+
+## Capability profile
+
+```bash
+devin-doctor capabilities             # JSON profile, exit 0
+devin-doctor capabilities --probe-network
+```
+
+`capabilities` prints a JSON object — `{"profile": ..., "capabilities":
+{...}}` — describing what the machine can do for the ecosystem (scheduler,
+daemon, local LLM, containers, comms, proxy, ≥24 GiB RAM, …). The profile is
+`corporate` by default (**fail-closed**); `personal` applies only when
+explicitly declared via `DEVIN_ECOSYSTEM_PROFILE=corporate|personal` or
+`devin-profile.json` (`{"profile": "personal"}`) in the Devin config dir —
+the env var wins. All probing is local; `net.outbound`/`net.listener`
+stay `"unknown"` unless `--probe-network` is passed, which performs exactly
+ONE outbound TCP connect (1.1.1.1:443 or the configured `HTTPS_PROXY`, 2 s
+timeout) plus a loopback bind — the only network call this tool can make.
+
+## Works with Devin alone (Devin-only mode)
+
+devin-doctor is a pure local diagnostic: it reads Devin's own data
+directories, writes nothing, and never contacts a network service. No VM, no
+Tailscale, no Ollama, no Slack — just Devin Desktop plus Python. On a
+restricted or corporate machine it is the safest first tool: install, run
+`devin-doctor`, read the report.
+
+## Platform support
+
+Tested on Windows and Linux. On Linux, session data defaults to
+`$XDG_DATA_HOME/devin` (normally `~/.local/share/devin`) and UI stores default
+to `$XDG_CONFIG_HOME/Devin` (normally `~/.config/Devin`). Windows stores use
+`%APPDATA%\devin` and `%APPDATA%\Devin`. Use `--data-dir` and `--config-dir`
+when the stores are elsewhere. macOS paths exist but are not verified.
+
+
+### `devin-doctor plan` — remediation plan, still read-only
+
+`plan` runs the same checks but emits a numbered remediation plan for every
+WARN/FAIL finding (the check's `fix` suggestion) instead of a verdict —
+nothing is executed; execution stays a human decision or another tool's job.
+`--json` gives `{"overall", "steps": [{check, status, finding, fix}]}`.
+This replaced the original `--fix` idea so doctor can keep its
+"read-only, always" guarantee.
+
+## Limitations
+
+- **Version-bound.** Store parsing follows `devin-internals-spec` (schema
+  v15–v17). A newer Devin schema reports FAIL — "unknown version" — by
+  design, rather than silently misreading.
+- **Read-only.** It suggests fixes but never touches the data dir. `--fix`
+  for the safe items is planned (see `STATUS.md`).
+- **Locked stores.** If Devin is running, DBs may report `SQLITE_BUSY` —
+  close Devin and re-run.
+- macOS paths are implemented but not verified in CI.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests run entirely on synthetic fixtures generated by
+`devin_internals.fixtures` — no real session data is ever read or required.
+`scripts/make_fixture.py <dir>` builds a fixture data dir for manual runs.
+
+## When to use this
+
+- Devin misbehaves — missing history, auth errors, disk pressure — and you want one command to localize the cause.
+- You want a health check before debugging: six checks (stores, schema, data health, config, hooks-windows, disk), each with a `fix:` suggestion.
+- You need a paste-able report for a bug report: `devin-doctor report --md`.
+- You are on a restricted machine: it is read-only and never contacts the network.
+
+## When NOT to use this
+
+- You want it to repair things — it is read-only; `--fix` for safe items is planned.
+- Your Devin schema is newer than v17 — it reports "unknown version" FAIL rather than misread.
+- Devin is running and DBs are locked — close Devin and re-run to clear `SQLITE_BUSY`.
+
+## FAQ
+
+**How do I check if my Devin installation's local data is healthy?** Run `devin-doctor check`. It inspects `sessions.db`, `acp-messages/*.db`, `state.vscdb`, `credentials.toml` and disk usage, printing `PASS`/`WARN`/`FAIL` per check with a `fix:` suggestion. Exit code is `0` unless something FAILs.
+
+**Is devin-doctor safe to run? Will it modify my data?** It is strictly read-only — it opens Devin's stores for reading, writes nothing to the data dir, and never contacts a network service. Config check masks credential values in output. Fixes are suggested as text, never applied.
+
+**What does "unknown schema version" mean?** Devin's `sessions.db` schema is versioned; devin-doctor understands v15–v17 via devin-internals-spec. A newer version produces a deliberate FAIL instead of a silent misread — update the tool or devin-internals-spec.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devin_doctor-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "devin-doctor"
+version = "0.1.0"
+description = "Diagnose a Devin Desktop installation: stores, schema versions, hooks, MCP servers, disk usage — with fix suggestions."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Icaro0310" }]
+dependencies = [
+  "devin-internals-spec>=0.3.0,<0.4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+devin-doctor = "devin_doctor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

devin_doctor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

devin_doctor-0.1.0/src/devin_doctor/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"