tracebase-cli 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,27 @@
1
+ # Python
2
+ __pycache__/
3
+ *.pyc
4
+ .venv/
5
+ .pytest_cache/
6
+ backend/data/
7
+
8
+ # Node
9
+ node_modules/
10
+ frontend/dist/
11
+
12
+ # Demo data is generated by demo/seed.py
13
+ demo/volume1/
14
+
15
+ # IDE
16
+ .idea/
17
+ .vscode/
18
+ *.pdf
19
+
20
+ # build-mode backups inside target projects
21
+ .tracebase/
22
+
23
+ # deployment secrets (admin token)
24
+ deploy/.env
25
+
26
+ # local docs, screenshots and demo media
27
+ docs/
@@ -0,0 +1,105 @@
1
+ # Functional Source License, Version 1.1, ALv2 Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-ALv2
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 Anshu Raj
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the Apache License, Version 2.0 that is effective on the second anniversary of
91
+ the date we make the Software available. On or after that date, you may use the
92
+ Software under the Apache License, Version 2.0, in which case the following
93
+ will apply:
94
+
95
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
+ this file except in compliance with the License.
97
+
98
+ You may obtain a copy of the License at
99
+
100
+ http://www.apache.org/licenses/LICENSE-2.0
101
+
102
+ Unless required by applicable law or agreed to in writing, software distributed
103
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
+ specific language governing permissions and limitations under the License.
@@ -0,0 +1,95 @@
1
+ Metadata-Version: 2.5
2
+ Name: tracebase-cli
3
+ Version: 0.3.0
4
+ Summary: CLI and MCP server for Tracebase: find code you already wrote in your old projects, copy it into the current one, and explain production errors.
5
+ Project-URL: Homepage, https://github.com/anshuraj669/tracebase
6
+ Project-URL: Repository, https://github.com/anshuraj669/tracebase
7
+ Project-URL: Issues, https://github.com/anshuraj669/tracebase/issues
8
+ Project-URL: Demo, https://demo.tracebase.duckdns.org
9
+ Author: Anshu Raj
10
+ License-Expression: LicenseRef-FSL-1.1-ALv2
11
+ License-File: LICENSE.md
12
+ Keywords: ai-agent,claude-code,code-search,developer-tools,logs,mcp,mcp-server,self-hosted
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Topic :: Software Development
19
+ Classifier: Topic :: Software Development :: Debuggers
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: httpx>=0.27
22
+ Requires-Dist: mcp>=1.2
23
+ Requires-Dist: pathspec>=0.12
24
+ Description-Content-Type: text/markdown
25
+
26
+ # tracebase-cli
27
+
28
+ <!-- mcp-name: io.github.anshuraj669/tracebase -->
29
+
30
+ Command line and **MCP server** for [Tracebase](https://github.com/anshuraj669/tracebase), the self-hosted search
31
+ and Q&A over all your past projects and production logs.
32
+
33
+ It lets you, and the AI agent you already use (Claude Code, Codex, Gemini CLI, opencode, Cursor, an Ollama model),
34
+ **find code you already wrote in your old projects and copy it into the current one**, and **explain production
35
+ errors** with the failing code and the commit that changed it. Nothing is written until you approve it.
36
+
37
+ The CLI talks to a running Tracebase server (your own, or the public demo).
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pipx install tracebase-cli # or: uv tool install tracebase-cli
43
+ ```
44
+
45
+ ## Try it against the public demo
46
+
47
+ ```bash
48
+ tracebase login tb_escsEwbpgDuxtXQ9xIxKT30IyXzO3_Mp --url https://demo.tracebase.duckdns.org
49
+ tracebase find "send password reset email"
50
+ tracebase errors
51
+ tracebase why E-1
52
+ ```
53
+
54
+ ## Connect your AI agent (MCP)
55
+
56
+ ```bash
57
+ tracebase connect claude # or: codex, gemini, opencode, cursor, ollama
58
+ ```
59
+
60
+ Then ask your agent things like *"copy the role based access control from my old projects"* or *"why did
61
+ checkout fail last night?"*. The MCP server exposes these tools:
62
+
63
+ | Tool | What it does |
64
+ |---|---|
65
+ | `find_code` | your past implementations of something (repo, path, symbol) |
66
+ | `preview_copy` | what would be copied into this project, with its models, migrations and wiring, as a diff; nothing is written |
67
+ | `apply_copy` | writes an approved copy; asks you directly when the agent supports MCP elicitation |
68
+ | `search_code`, `read_code`, `list_repos`, `get_code_bundle` | search and read your indexed repos |
69
+ | `find_errors`, `explain_error` | grouped production errors; cause, failing code, the commit, a suggested fix |
70
+
71
+ You can also run it by hand: `tracebase mcp` (stdio).
72
+
73
+ ## Commands
74
+
75
+ ```
76
+ tracebase status check the connection to the server
77
+ tracebase find "login logic" your past implementations, with code
78
+ tracebase copy "login logic" find it and copy it into this project (shows the plan first)
79
+ tracebase search "jwt refresh" search across all your repos
80
+ tracebase errors / why E-5 production errors, grouped and explained
81
+ tracebase ingest app.log send log files (or stdin: -)
82
+ tracebase team add priya --repos "freelance/*" team server admin
83
+ ```
84
+
85
+ `tracebase --help` lists everything.
86
+
87
+ ## Run your own server
88
+
89
+ See [the main project](https://github.com/anshuraj669/tracebase): Docker, a NAS, or one small cloud server with
90
+ automatic HTTPS.
91
+
92
+ ## License
93
+
94
+ [FSL-1.1-ALv2](LICENSE.md): free to use, self-host and modify, except to build a competing product. Each
95
+ release becomes Apache 2.0 two years after it's published.
@@ -0,0 +1,70 @@
1
+ # tracebase-cli
2
+
3
+ <!-- mcp-name: io.github.anshuraj669/tracebase -->
4
+
5
+ Command line and **MCP server** for [Tracebase](https://github.com/anshuraj669/tracebase), the self-hosted search
6
+ and Q&A over all your past projects and production logs.
7
+
8
+ It lets you, and the AI agent you already use (Claude Code, Codex, Gemini CLI, opencode, Cursor, an Ollama model),
9
+ **find code you already wrote in your old projects and copy it into the current one**, and **explain production
10
+ errors** with the failing code and the commit that changed it. Nothing is written until you approve it.
11
+
12
+ The CLI talks to a running Tracebase server (your own, or the public demo).
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ pipx install tracebase-cli # or: uv tool install tracebase-cli
18
+ ```
19
+
20
+ ## Try it against the public demo
21
+
22
+ ```bash
23
+ tracebase login tb_escsEwbpgDuxtXQ9xIxKT30IyXzO3_Mp --url https://demo.tracebase.duckdns.org
24
+ tracebase find "send password reset email"
25
+ tracebase errors
26
+ tracebase why E-1
27
+ ```
28
+
29
+ ## Connect your AI agent (MCP)
30
+
31
+ ```bash
32
+ tracebase connect claude # or: codex, gemini, opencode, cursor, ollama
33
+ ```
34
+
35
+ Then ask your agent things like *"copy the role based access control from my old projects"* or *"why did
36
+ checkout fail last night?"*. The MCP server exposes these tools:
37
+
38
+ | Tool | What it does |
39
+ |---|---|
40
+ | `find_code` | your past implementations of something (repo, path, symbol) |
41
+ | `preview_copy` | what would be copied into this project, with its models, migrations and wiring, as a diff; nothing is written |
42
+ | `apply_copy` | writes an approved copy; asks you directly when the agent supports MCP elicitation |
43
+ | `search_code`, `read_code`, `list_repos`, `get_code_bundle` | search and read your indexed repos |
44
+ | `find_errors`, `explain_error` | grouped production errors; cause, failing code, the commit, a suggested fix |
45
+
46
+ You can also run it by hand: `tracebase mcp` (stdio).
47
+
48
+ ## Commands
49
+
50
+ ```
51
+ tracebase status check the connection to the server
52
+ tracebase find "login logic" your past implementations, with code
53
+ tracebase copy "login logic" find it and copy it into this project (shows the plan first)
54
+ tracebase search "jwt refresh" search across all your repos
55
+ tracebase errors / why E-5 production errors, grouped and explained
56
+ tracebase ingest app.log send log files (or stdin: -)
57
+ tracebase team add priya --repos "freelance/*" team server admin
58
+ ```
59
+
60
+ `tracebase --help` lists everything.
61
+
62
+ ## Run your own server
63
+
64
+ See [the main project](https://github.com/anshuraj669/tracebase): Docker, a NAS, or one small cloud server with
65
+ automatic HTTPS.
66
+
67
+ ## License
68
+
69
+ [FSL-1.1-ALv2](LICENSE.md): free to use, self-host and modify, except to build a competing product. Each
70
+ release becomes Apache 2.0 two years after it's published.
@@ -0,0 +1,40 @@
1
+ [project]
2
+ name = "tracebase-cli"
3
+ version = "0.3.0"
4
+ description = "CLI and MCP server for Tracebase: find code you already wrote in your old projects, copy it into the current one, and explain production errors."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "LicenseRef-FSL-1.1-ALv2"
8
+ license-files = ["LICENSE.md"]
9
+ authors = [{ name = "Anshu Raj" }]
10
+ keywords = ["mcp", "mcp-server", "code-search", "self-hosted", "claude-code", "ai-agent", "logs", "developer-tools"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Environment :: Console",
14
+ "Intended Audience :: Developers",
15
+ "Operating System :: OS Independent",
16
+ "Programming Language :: Python :: 3",
17
+ "Topic :: Software Development",
18
+ "Topic :: Software Development :: Debuggers",
19
+ ]
20
+ dependencies = [
21
+ "httpx>=0.27",
22
+ "pathspec>=0.12",
23
+ "mcp>=1.2",
24
+ ]
25
+
26
+ [project.urls]
27
+ Homepage = "https://github.com/anshuraj669/tracebase"
28
+ Repository = "https://github.com/anshuraj669/tracebase"
29
+ Issues = "https://github.com/anshuraj669/tracebase/issues"
30
+ Demo = "https://demo.tracebase.duckdns.org"
31
+
32
+ [project.scripts]
33
+ tracebase = "tracebase_cli.main:main"
34
+
35
+ [build-system]
36
+ requires = ["hatchling>=1.27"]
37
+ build-backend = "hatchling.build"
38
+
39
+ [tool.hatch.build.targets.wheel]
40
+ packages = ["tracebase_cli"]
@@ -0,0 +1,56 @@
1
+ from pathlib import Path
2
+
3
+ import pytest
4
+
5
+ from tracebase_cli import main, project, reuse
6
+
7
+
8
+ def _laravel(tmp: Path) -> Path:
9
+ files = {
10
+ "composer.json": '{"require": {"laravel/framework": "^10.0"}}',
11
+ "app/Models/User.php": "<?php class User {}",
12
+ "app/Models/Booking.php": "<?php class Booking {}",
13
+ "app/Http/Kernel.php": "<?php class Kernel {}",
14
+ "routes/api.php": "<?php Route::get('b', [BookingController::class, 'index']);",
15
+ "app/Http/Controllers/BookingController.php": "<?php class BookingController { function index() {} }",
16
+ "resources/css/app.css": "body{}",
17
+ "vendor/laravel/framework/x.php": "<?php",
18
+ "node_modules/a/index.js": "x",
19
+ "storage/logs/laravel.log": "log",
20
+ ".env": "APP_KEY=secret",
21
+ "public/logo.png": "png",
22
+ "ignored/cache.php": "<?php",
23
+ ".gitignore": "/ignored\n",
24
+ }
25
+ for rel, text in files.items():
26
+ p = tmp / rel
27
+ p.parent.mkdir(parents=True, exist_ok=True)
28
+ p.write_text(text)
29
+ return tmp
30
+
31
+
32
+ def test_tree_skips_vendor_env_binaries_and_gitignored(tmp_path):
33
+ tree = project.scan_tree(_laravel(tmp_path))
34
+ assert "composer.json" in tree and "routes/api.php" in tree
35
+ assert not any(p.startswith(("vendor/", "node_modules/", "storage/", "ignored/")) for p in tree)
36
+ assert ".env" not in tree and "public/logo.png" not in tree
37
+
38
+
39
+ def test_context_picks_relevant_files(tmp_path):
40
+ ctx = project.context(_laravel(tmp_path), "add role based access control")
41
+ assert {"composer.json", "routes/api.php", "app/Http/Kernel.php", "app/Models/User.php"} <= set(ctx["files"])
42
+ assert "resources/css/app.css" not in ctx["files"]
43
+ assert "app/Http/Controllers/BookingController.php" in ctx["files"] # referenced by routes/api.php
44
+ assert ctx["name"] == tmp_path.name
45
+
46
+
47
+ def test_safe_target_refuses_outside(tmp_path):
48
+ assert reuse.safe_target(tmp_path, "app/x.php") == (tmp_path / "app/x.php").resolve()
49
+ with pytest.raises(reuse.CopyError):
50
+ reuse.safe_target(tmp_path, "../x.php")
51
+
52
+
53
+ def test_candidates_one_per_file():
54
+ ex = [{"repo": "a", "path": "x.php"}, {"repo": "a", "path": "x.php"}, {"repo": "b/c", "path": "y.php"}]
55
+ assert [e["path"] for e in main.candidates(ex)] == ["x.php", "y.php"]
56
+ assert [e["repo"] for e in main.candidates(ex, repo="c")] == ["b/c"]
@@ -0,0 +1,59 @@
1
+ """`tracebase data`: the right API calls, confirmation before deleting, private export files."""
2
+ import json
3
+ import os
4
+
5
+ import httpx
6
+
7
+ from tracebase_cli import main
8
+ from tracebase_cli.client import Client
9
+
10
+
11
+ def _client(calls):
12
+ def handler(req: httpx.Request) -> httpx.Response:
13
+ calls.append((req.method, req.url.path, dict(req.url.params), req.content.decode() or None))
14
+ if req.url.path == "/api/data/export":
15
+ lines = [{"type": "export"}, {"type": "log_event", "message": "a"}, {"type": "error_group"}]
16
+ return httpx.Response(200, text="".join(json.dumps(l) + "\n" for l in lines))
17
+ if req.url.path == "/api/data/purge":
18
+ body = json.loads(req.content)
19
+ key = "would_delete" if body["dry_run"] else "deleted"
20
+ return httpx.Response(200, json={key: {"log_events": 3, "error_groups": 1, "alerts": 0}})
21
+ return httpx.Response(200, json={"deleted": {"chunks": 4}, "repo": "x"})
22
+
23
+ api = Client("http://tb.test")
24
+ api.http = httpx.Client(base_url="http://tb.test", transport=httpx.MockTransport(handler))
25
+ return api
26
+
27
+
28
+ def _run(argv, api, monkeypatch):
29
+ monkeypatch.setattr(main, "Client", lambda url=None, **kw: api)
30
+ return main.main(argv)
31
+
32
+
33
+ def test_purge_previews_then_deletes(monkeypatch, capsys):
34
+ calls = []
35
+ api = _client(calls)
36
+ assert _run(["data", "purge", "CUST-10442", "--yes"], api, monkeypatch) == 0
37
+ bodies = [json.loads(c[3]) for c in calls if c[1] == "/api/data/purge"]
38
+ assert [b["dry_run"] for b in bodies] == [True, False]
39
+ assert "Deleted 3 log events, 1 error groups" in capsys.readouterr().out
40
+
41
+
42
+ def test_deletes_need_confirmation(monkeypatch, capsys):
43
+ calls = []
44
+ api = _client(calls)
45
+ monkeypatch.setattr("sys.stdin.isatty", lambda: False)
46
+ assert _run(["data", "forget-repo", "client-a/old"], api, monkeypatch) == 1
47
+ assert _run(["data", "wipe"], api, monkeypatch) == 1
48
+ assert not any(c[0] == "DELETE" or c[1] == "/api/data/wipe" for c in calls)
49
+ assert _run(["data", "forget-service", "payments", "--stop", "-y"], api, monkeypatch) == 0
50
+ assert ("DELETE", "/api/data/services/payments", {"exclude": "true"}, None) in calls
51
+
52
+
53
+ def test_export_writes_an_owner_only_file(monkeypatch, tmp_path):
54
+ calls = []
55
+ out = tmp_path / "x.ndjson"
56
+ assert _run(["data", "export", "--service", "shop-api", "-o", str(out)], _client(calls), monkeypatch) == 0
57
+ assert calls[0][2] == {"service": "shop-api"}
58
+ assert len(out.read_text().splitlines()) == 3
59
+ assert os.stat(out).st_mode & 0o077 == 0
@@ -0,0 +1,52 @@
1
+ """MCP tools for Log Detective: the agent can list production errors and get the full explanation."""
2
+ from tracebase_cli import mcp_server
3
+
4
+ GROUP = {"id": 5, "code": "E-5", "service": "shop-api", "title": 'Undefined array key "coupon"', "status": "new",
5
+ "count": 64, "window_count": 64, "spike": True, "first_seen": "2026-11-08T14:04:04", "last_seen": "2026-11-08T14:53:02",
6
+ "samples": [{"message": 'production.ERROR: Undefined array key "coupon"'}]}
7
+ EXPLAIN = {"cause": "Code reads a key that is missing. Last changed in commit f971906.", "impact": "64 occurrences.",
8
+ "fix": ["In shop-api/app/Services/CartService.php:57 change `$code = $cart['coupon'];` to `$code = $cart['coupon'] ?? null;`"],
9
+ "events": [{"ts": "2026-11-08T13:42:10", "service": "deploy", "message": "deployed shop-api"}],
10
+ "code": [{"repo": "shop-api", "path": "app/Services/CartService.php", "line": 57, "func": None,
11
+ "snippet": [{"n": 56, "text": "$total = $cart['total'];"}, {"n": 57, "text": "$code = $cart['coupon'];"}]}],
12
+ "commit": {"sha": "f971906", "message": "Refactor applyDiscount", "author": "Dev", "date": "2026-11-08 13:42",
13
+ "minutes_before_first_error": 22}}
14
+
15
+
16
+ class FakeApi:
17
+ def __init__(self):
18
+ self.calls = []
19
+
20
+ def errors(self, **kw):
21
+ self.calls.append(("errors", kw))
22
+ return [GROUP]
23
+
24
+ def error(self, gid):
25
+ self.calls.append(("error", gid))
26
+ return GROUP
27
+
28
+ def explain_error(self, gid, refresh=False):
29
+ self.calls.append(("explain", gid))
30
+ return EXPLAIN
31
+
32
+
33
+ def _tool(api, name):
34
+ server = mcp_server.build_server(api=api)
35
+ tools = getattr(server, "_tool_manager", None) or getattr(server, "tool_manager", None)
36
+ return tools.get_tool(name).fn
37
+
38
+
39
+ def test_find_errors_lists_groups():
40
+ api = FakeApi()
41
+ out = _tool(api, "find_errors")(service="shop-api", since="last night")
42
+ assert "E-5" in out and "SPIKING" in out and "count=64" in out
43
+ assert api.calls[0] == ("errors", {"service": "shop-api", "since": "last night", "status": None, "q": None, "limit": 15})
44
+
45
+
46
+ def test_explain_error_gives_cause_code_commit_and_fix():
47
+ api = FakeApi()
48
+ out = _tool(api, "explain_error")(error_id="5")
49
+ assert ("explain", "E-5") in api.calls # "5" is normalised to "E-5"
50
+ assert ">> 57 $code = $cart['coupon'];" in out
51
+ assert "commit f971906" in out and "22 min before the first error" in out
52
+ assert "?? null" in out and "deploy: deployed shop-api" in out