pythia-plsql 0.15.2__tar.gz → 0.15.4__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.
Files changed (66) hide show
  1. {pythia_plsql-0.15.2/scripts/pythia_plsql.egg-info → pythia_plsql-0.15.4}/PKG-INFO +11 -3
  2. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/README.md +10 -2
  3. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/pyproject.toml +1 -1
  4. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia.py +251 -43
  5. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4/scripts/pythia_plsql.egg-info}/PKG-INFO +11 -3
  6. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-setup/SKILL.md +4 -3
  7. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-setup/reference/environment.md +8 -3
  8. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_install.py +161 -0
  9. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_phase6.py +161 -0
  10. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/LICENSE +0 -0
  11. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/comment-current.sql +0 -0
  12. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/compile-errors.sql +0 -0
  13. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/current-schema.sql +0 -0
  14. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/db-nls.sql +0 -0
  15. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/db-version.sql +0 -0
  16. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/dependencies.sql +0 -0
  17. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/explain-display.sql +0 -0
  18. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/impact.sql +0 -0
  19. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/invalid-objects.sql +0 -0
  20. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/name-occupants.sql +0 -0
  21. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/object-names.sql +0 -0
  22. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/object-source.sql +0 -0
  23. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/plscope-enabled.sql +0 -0
  24. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/plscope-statements.sql +0 -0
  25. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/plscope-usages.sql +0 -0
  26. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/schema-settings.sql +0 -0
  27. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/session-privileges.sql +0 -0
  28. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/similar-candidates.sql +0 -0
  29. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/source.sql +0 -0
  30. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/table-comments.sql +0 -0
  31. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/table-indexes.sql +0 -0
  32. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/table-stats.sql +0 -0
  33. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/queries/unindexed-fks.sql +0 -0
  34. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia_plsql.egg-info/SOURCES.txt +0 -0
  35. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia_plsql.egg-info/dependency_links.txt +0 -0
  36. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia_plsql.egg-info/entry_points.txt +0 -0
  37. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia_plsql.egg-info/requires.txt +0 -0
  38. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/scripts/pythia_plsql.egg-info/top_level.txt +0 -0
  39. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/setup.cfg +0 -0
  40. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-apply/SKILL.md +0 -0
  41. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-autopilot/SKILL.md +0 -0
  42. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-comment/SKILL.md +0 -0
  43. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-conventions/SKILL.md +0 -0
  44. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-deploy/SKILL.md +0 -0
  45. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-explore/SKILL.md +0 -0
  46. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-explore/reference/data-dictionary.md +0 -0
  47. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-impact/SKILL.md +0 -0
  48. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-package/SKILL.md +0 -0
  49. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-package/reference/plsql-standards.md +0 -0
  50. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-review/SKILL.md +0 -0
  51. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-review/reference/antipatterns.md +0 -0
  52. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-skill-author/SKILL.md +0 -0
  53. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-spec/SKILL.md +0 -0
  54. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-table/SKILL.md +0 -0
  55. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-table/reference/ddl-standards.md +0 -0
  56. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-tune/SKILL.md +0 -0
  57. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-tune/reference/tuning-checklist.md +0 -0
  58. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-verify/SKILL.md +0 -0
  59. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-write/SKILL.md +0 -0
  60. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/pythia-write/reference/patterns.md +0 -0
  61. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/skills/using-pythia/SKILL.md +0 -0
  62. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_mcp.py +0 -0
  63. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_phase1.py +0 -0
  64. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_phase2.py +0 -0
  65. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_phase3.py +0 -0
  66. {pythia_plsql-0.15.2 → pythia_plsql-0.15.4}/tests/test_phase5.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pythia-plsql
3
- Version: 0.15.2
3
+ Version: 0.15.4
4
4
  Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
5
5
  License: MIT
6
6
  Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -20,7 +20,7 @@ Dynamic: license-file
20
20
 
21
21
  > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
22
22
 
23
- **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
23
+ **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)** · **[Website →](https://thaildhe172591.github.io/pythia/)**
24
24
 
25
25
  [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
26
26
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -191,6 +191,11 @@ each agent needs you to finish by hand.
191
191
  - a `deny` rule so the agent cannot forge a grant, and the MCP server
192
192
  enabled.
193
193
 
194
+ It scaffolds `.pythia/connections.json` (mode 600) and adds it to the
195
+ project's `.gitignore` — commit that line — and warns if git already
196
+ tracks the file: its passwords are then in the history, so untrack it and
197
+ change them.
198
+
194
199
  It also writes the harness into **`CLAUDE.md`** — the file Claude Code
195
200
  itself loads every session — in a marker-delimited block, leaving your own
196
201
  text untouched. The rules hold even with `--no-hooks`, before a restart,
@@ -206,7 +211,10 @@ each agent needs you to finish by hand.
206
211
  the absolute interpreter, and the MCP approver to Claude Code's local scope
207
212
  (`claude mcp add --scope local`); your teammates never get a path from your
208
213
  machine. `pythia doctor` starts every launcher it finds and fails the ones
209
- that cannot import pythia.
214
+ that cannot import pythia — except where this machine's own launcher
215
+ already serves the same hooks: then the team's shared copy erroring here
216
+ is a warning (keep it for teammates or remove it). Codex's session hook is
217
+ a warning too: it carries only the session guide, and AGENTS.md the rules.
210
218
 
211
219
  Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
212
220
  2. **Restart the Claude Code session** so the hooks and the MCP server load.
@@ -6,7 +6,7 @@
6
6
 
7
7
  > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
8
8
 
9
- **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
9
+ **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)** · **[Website →](https://thaildhe172591.github.io/pythia/)**
10
10
 
11
11
  [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
12
12
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -177,6 +177,11 @@ each agent needs you to finish by hand.
177
177
  - a `deny` rule so the agent cannot forge a grant, and the MCP server
178
178
  enabled.
179
179
 
180
+ It scaffolds `.pythia/connections.json` (mode 600) and adds it to the
181
+ project's `.gitignore` — commit that line — and warns if git already
182
+ tracks the file: its passwords are then in the history, so untrack it and
183
+ change them.
184
+
180
185
  It also writes the harness into **`CLAUDE.md`** — the file Claude Code
181
186
  itself loads every session — in a marker-delimited block, leaving your own
182
187
  text untouched. The rules hold even with `--no-hooks`, before a restart,
@@ -192,7 +197,10 @@ each agent needs you to finish by hand.
192
197
  the absolute interpreter, and the MCP approver to Claude Code's local scope
193
198
  (`claude mcp add --scope local`); your teammates never get a path from your
194
199
  machine. `pythia doctor` starts every launcher it finds and fails the ones
195
- that cannot import pythia.
200
+ that cannot import pythia — except where this machine's own launcher
201
+ already serves the same hooks: then the team's shared copy erroring here
202
+ is a warning (keep it for teammates or remove it). Codex's session hook is
203
+ a warning too: it carries only the session guide, and AGENTS.md the rules.
196
204
 
197
205
  Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
198
206
  2. **Restart the Claude Code session** so the hooks and the MCP server load.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pythia-plsql"
7
- version = "0.15.2"
7
+ version = "0.15.4"
8
8
  description = "PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback."
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -61,7 +61,7 @@ import pathlib
61
61
  import re
62
62
  import sys
63
63
 
64
- __version__ = "0.15.2" # kept equal to pyproject.toml (tests/test_install.py)
64
+ __version__ = "0.15.4" # kept equal to pyproject.toml (tests/test_install.py)
65
65
 
66
66
  READONLY = re.compile(r"^\s*(select|with)\b", re.I)
67
67
  CONFIG_DIR = ".pythia"
@@ -4008,47 +4008,68 @@ def register_local_mcp(project_root, launcher, which=None, run=None, home=None):
4008
4008
  return ("updated" if have is not None else "added"), shown
4009
4009
 
4010
4010
 
4011
- def launcher_health(launcher, cwd=None, which=None, env=None, starts=None,
4012
- shared=False):
4013
- """(status, message) for one launcher found in the harness files. A bare
4014
- name is resolved on this PATH and run; a path (an interpreter's, or a
4015
- pythia.py's) is run only from a machine's own files — in a shared file it
4016
- is reported, never executed."""
4011
+ def launcher_verdict(launcher, which=None, env=None, starts=None, shared=False):
4012
+ """(status, code, detail) for one launcher found in the harness files —
4013
+ what doctor knows before a word is chosen. code: not-plain | shared-path |
4014
+ not-on-path | cannot-start | venv-only | ok; detail: the reason, or the
4015
+ active environment. A bare name is resolved on this PATH and run; a path
4016
+ (an interpreter's, or a pythia.py's) is run only from a machine's own
4017
+ files — in a shared file it is the repository's to choose, so it is
4018
+ named, never executed."""
4017
4019
  which = which or path_lookup
4018
4020
  env = os.environ if env is None else env
4019
4021
  starts = starts or launcher_starts
4020
4022
  argv = plain_launcher(launcher)
4021
4023
  if argv is None:
4022
- return ("warn", f"`{launcher}` is not a plain launcher (an interpreter "
4023
- "plus -m pythia, or an absolute pythia.py path) — doctor does "
4024
- "not run it")
4024
+ return "warn", "not-plain", ""
4025
4025
  bare = not re.search(r"[/\\]", argv[0])
4026
4026
  if shared and not (bare and argv[1:] == ["-m", "pythia"]):
4027
- # a path in a shared file is the repository's to choose — the
4028
- # interpreter's or the pythia.py it is pointed at — so it is named,
4029
- # never run
4030
- return ("warn", f"`{launcher}` is a path on one machine, in a file the "
4031
- "team shares — teammates' hooks will not find it, and doctor "
4032
- f"does not run it; `{invocation()} install` keeps a machine's "
4033
- "own launcher in .claude/settings.local.json")
4027
+ return "warn", "shared-path", ""
4034
4028
  resolved = which(argv[0]) if bare else argv[0]
4035
4029
  if bare and not resolved:
4036
- return ("fail", f"`{argv[0]}` is not on PATH, so `{launcher}` cannot "
4037
- "start — the guard and the approval doors it serves are off; "
4038
- f"re-run `{invocation()} install`")
4030
+ return "fail", "not-on-path", f"`{argv[0]}` is not on PATH"
4039
4031
  ok, why = starts(launcher)
4040
4032
  if not ok:
4041
- return ("fail", f"`{launcher}` cannot start pythia here ({why}) — the "
4042
- "guard and the approval doors it serves are off; re-run "
4043
- f"`{invocation()} install`, which picks an interpreter that can")
4033
+ return "fail", "cannot-start", why
4044
4034
  venv = env.get("VIRTUAL_ENV") or env.get("CONDA_PREFIX")
4045
4035
  if bare and venv and os.path.normcase(os.path.abspath(resolved)).startswith(
4046
4036
  os.path.normcase(os.path.abspath(venv)) + os.sep):
4047
- return ("warn", f"`{argv[0]}` finds pythia only while the virtual "
4048
- f"environment {venv} is active — Claude Code started from a "
4037
+ return "warn", "venv-only", venv
4038
+ return "ok", "ok", ""
4039
+
4040
+
4041
+ def launcher_message(launcher, code, detail, broken=None):
4042
+ """The words for a verdict. `broken` replaces what follows a launcher
4043
+ that cannot start — what it leaves off, and the fix — when the caller
4044
+ knows more than the launcher does (which file it is in, what else on
4045
+ this machine serves the same hooks)."""
4046
+ if code == "not-plain":
4047
+ return (f"`{launcher}` is not a plain launcher (an interpreter plus -m "
4048
+ "pythia, or an absolute pythia.py path) — doctor does not run it")
4049
+ if code == "shared-path":
4050
+ return (f"`{launcher}` is a path on one machine, in a file the team "
4051
+ "shares — teammates' hooks will not find it, and doctor does "
4052
+ f"not run it; `{invocation()} install` keeps a machine's own "
4053
+ "launcher in .claude/settings.local.json")
4054
+ if code in ("not-on-path", "cannot-start"):
4055
+ return (f"`{launcher}` cannot start pythia here ({detail}) — " + (
4056
+ broken or "the guard and the approval doors it serves are off; "
4057
+ f"re-run `{invocation()} install`, which picks an interpreter that "
4058
+ "can"))
4059
+ if code == "venv-only":
4060
+ return (f"`{launcher}` finds pythia only while the virtual environment "
4061
+ f"{detail} is active — Claude Code or Codex started from a "
4049
4062
  f"desktop app or IDE will not; re-run `{invocation()} install`, "
4050
4063
  "which pins this interpreter in .claude/settings.local.json")
4051
- return "ok", f"`{launcher}` starts pythia"
4064
+ return f"`{launcher}` starts pythia"
4065
+
4066
+
4067
+ def launcher_health(launcher, cwd=None, which=None, env=None, starts=None,
4068
+ shared=False, broken=None):
4069
+ """(status, message) for one launcher — launcher_verdict in words."""
4070
+ st, code, detail = launcher_verdict(launcher, which=which, env=env,
4071
+ starts=starts, shared=shared)
4072
+ return st, launcher_message(launcher, code, detail, broken)
4052
4073
 
4053
4074
 
4054
4075
  def exclude_local_settings(project_root):
@@ -4074,6 +4095,117 @@ def exclude_local_settings(project_root):
4074
4095
  return exclude
4075
4096
 
4076
4097
 
4098
+ SECRET_REL = f"{CONFIG_DIR}/{CONFIG_NAME}"
4099
+
4100
+
4101
+ def git_ignore_source(root, rel):
4102
+ """How git treats `rel` under root: ("shared", source) when a .gitignore
4103
+ in the repository ignores it — every clone; ("local", source) when only
4104
+ this machine does (.git/info/exclude, a personal excludes file);
4105
+ ("none", "") when `git add -A` would take it. None outside a repository
4106
+ or without git. The index is not consulted: tracked is git_tracks()."""
4107
+ import subprocess
4108
+ git = path_lookup("git")
4109
+ if not git:
4110
+ return None
4111
+ try:
4112
+ r = subprocess.run([git, "-C", str(root), "check-ignore", "-v",
4113
+ "--no-index", "--", rel], stdin=subprocess.DEVNULL,
4114
+ capture_output=True, text=True, encoding="utf-8",
4115
+ errors="replace", timeout=15)
4116
+ except (OSError, subprocess.SubprocessError):
4117
+ return None
4118
+ if r.returncode not in (0, 1):
4119
+ return None
4120
+ # <source>:<line>:<pattern>TAB<path>; a match on "!pattern" un-ignores it
4121
+ m = re.match(r"(.+?):(\d+):(.*?)\t", r.stdout)
4122
+ if r.returncode == 1 or not m or m.group(3).startswith("!"):
4123
+ return "none", ""
4124
+ src = m.group(1)
4125
+ shared = (not _is_abs_path(src)
4126
+ and os.path.basename(src.replace("\\", "/")) == ".gitignore")
4127
+ return ("shared" if shared else "local"), src
4128
+
4129
+
4130
+ def _gitignore_covers(path, rel):
4131
+ """Read as text where git cannot answer: does the last rule in `path`
4132
+ naming rel (or its folder) ignore it?"""
4133
+ if not path.is_file():
4134
+ return False
4135
+ folder = rel.split("/")[0]
4136
+ names = {rel, folder, folder + "/", folder + "/*", folder + "/**"}
4137
+ covered = False
4138
+ for ln in path.read_text(encoding="utf-8", errors="replace").splitlines():
4139
+ s = ln.strip()
4140
+ neg = s.startswith("!")
4141
+ body = (s[1:] if neg else s).lstrip("/")
4142
+ if body in names:
4143
+ covered = not neg
4144
+ return covered
4145
+
4146
+
4147
+ def ignore_connections(project_root):
4148
+ """Keep .pythia/connections.json — the passwords — out of every clone:
4149
+ append it to the project's .gitignore unless a rule there already ignores
4150
+ it. A rule only this machine has is not enough, and outside git the line
4151
+ is written anyway, so a later `git init` starts safe. Returns the
4152
+ .gitignore written, or None."""
4153
+ root = pathlib.Path(project_root)
4154
+ gi = root / ".gitignore"
4155
+ state = git_ignore_source(root, SECRET_REL)
4156
+ if state is not None and state[0] == "shared":
4157
+ return None
4158
+ if _gitignore_covers(gi, SECRET_REL):
4159
+ return None # written already; a rule deeper down overrides it
4160
+ data = gi.read_bytes() if gi.is_file() else b""
4161
+ with open(gi, "ab") as f: # their bytes stay theirs
4162
+ f.write((b"\n" if data and not data.endswith(b"\n") else b"")
4163
+ + b"# pythia: database passwords, never committed\n"
4164
+ + SECRET_REL.encode("utf-8") + b"\n")
4165
+ return gi
4166
+
4167
+
4168
+ def report_connections_ignore(project_root):
4169
+ root = pathlib.Path(project_root)
4170
+ try:
4171
+ gi = ignore_connections(root)
4172
+ except OSError as e: # a safeguard, never a reason to abort
4173
+ gi = None
4174
+ print(f"WARNING: could not write {root / '.gitignore'} ({e}) — "
4175
+ f"add {SECRET_REL} to it by hand; the file holds passwords.")
4176
+ if gi is not None:
4177
+ print(f"Added {SECRET_REL} to {gi} — it holds passwords; commit the "
4178
+ ".gitignore so every clone keeps it out")
4179
+ if git_tracks(root, SECRET_REL):
4180
+ print(f"WARNING: git already tracks {SECRET_REL}, so its passwords are "
4181
+ f"in the repository. Run `git rm --cached {SECRET_REL}`, commit, "
4182
+ "and change those passwords — the history keeps the old ones.")
4183
+
4184
+
4185
+ def credentials_check(root):
4186
+ """doctor's row for the password file: fail when git tracks it, warn
4187
+ when git would commit it, ok when a shared rule keeps it out."""
4188
+ state = git_ignore_source(root, SECRET_REL)
4189
+ if state is None:
4190
+ return ("info", "credentials", f"{SECRET_REL} not checked — no git "
4191
+ "repository here (or git is not on PATH)")
4192
+ if git_tracks(root, SECRET_REL):
4193
+ return ("fail", "credentials", f"git tracks {SECRET_REL} — its "
4194
+ f"passwords are in the repository; `git rm --cached "
4195
+ f"{SECRET_REL}`, commit, then change those passwords (the "
4196
+ "history keeps the old ones)")
4197
+ kind, src = state
4198
+ fix = f"{invocation()} install adds it to .gitignore"
4199
+ if kind == "shared":
4200
+ return ("ok", "credentials", f"{SECRET_REL} is git-ignored ({src})")
4201
+ if kind == "local":
4202
+ return ("warn", "credentials", f"{SECRET_REL} is ignored only on this "
4203
+ f"machine ({src}) — a teammate's clone would commit theirs; "
4204
+ + fix)
4205
+ return ("warn", "credentials", f"{SECRET_REL} is not git-ignored — one "
4206
+ f"`git add -A` commits the passwords; " + fix)
4207
+
4208
+
4077
4209
  def git_common_dir(root):
4078
4210
  """The directory holding info/exclude: .git itself, or — in a worktree or
4079
4211
  a submodule, where .git is a file — the gitdir it names (a worktree's
@@ -4632,6 +4764,7 @@ def cmd_install(conn, schema, ns):
4632
4764
  return
4633
4765
  path, created = scaffold_config(ns.project_root)
4634
4766
  print(f"{'Created' if created else 'Kept existing'} {path}")
4767
+ report_connections_ignore(ns.project_root)
4635
4768
  if global_pack_present():
4636
4769
  print("Skill pack found in the global install — it already serves "
4637
4770
  "this project,\nso no project copy is made (a second copy "
@@ -6989,32 +7122,98 @@ def ask_question_breakers(project_root, home=None, plugin_limit=400):
6989
7122
  return found
6990
7123
 
6991
7124
 
7125
+ # what each pythia hook does, the two gates first — a launcher that cannot
7126
+ # start leaves exactly these off
7127
+ HOOK_JOBS = (("hook pre-tool", "the sqlplus guard"),
7128
+ ("approve --hook", "the AskUserQuestion approval"),
7129
+ ("hook session-start", "the session guide"),
7130
+ ("hook post-tool", "the verdict reminders"))
7131
+
7132
+
7133
+ def _and_list(words):
7134
+ words = list(words)
7135
+ return words[0] if len(words) == 1 else ", ".join(words[:-1]) + " and " + words[-1]
7136
+
7137
+
6992
7138
  def launch_checks(root, home, settings, local_settings):
6993
- """One row per launcher the harness files start pythia with: can it?
6994
- A hook that cannot start fails open, so this is a fail, not a warning."""
7139
+ """One row per launcher the harness files start pythia with: can it? A
7140
+ Claude hook that cannot start fails open, so the row names exactly which
7141
+ jobs (HOOK_JOBS) no other launcher that starts on this machine still
7142
+ does: a gate among them (the guard, the approval hook) is a fail; only
7143
+ the session guide or the reminders, a warning; nothing at all — the
7144
+ team's copy erroring here while this machine's own launcher serves the
7145
+ same hooks — a warning that leaves keep-or-remove to the developer.
7146
+ Codex's hook carries only the session guide: a warning either way."""
6995
7147
  tracked = bool(local_settings.get("hooks")) and git_tracks(
6996
7148
  root, ".claude/settings.local.json")
6997
- sources = [(".claude/settings.json", settings.get("hooks"), True),
6998
- (".claude/settings.local.json", local_settings.get("hooks"), tracked),
7149
+ # role: shared (the team's file), own (this machine's), user (~/.claude,
7150
+ # every project of this user), codex (shared, the session guide only)
7151
+ sources = [(".claude/settings.json", settings.get("hooks"), "shared"),
7152
+ (".claude/settings.local.json", local_settings.get("hooks"),
7153
+ "shared" if tracked else "own"),
6999
7154
  ("~/.claude/settings.json",
7000
7155
  (_read_json(home / ".claude" / "settings.json") or {}).get("hooks"),
7001
- False),
7156
+ "user"),
7002
7157
  (".codex/hooks.json",
7003
7158
  (_read_json(root / ".codex" / "hooks.json") or {}).get("hooks"),
7004
- True)]
7005
- out = []
7006
- for where, hooks, shared in sources:
7007
- launchers = []
7159
+ "codex")]
7160
+ found = []
7161
+ for where, hooks, role in sources:
7162
+ marks = {}
7008
7163
  for ev in (hooks or {}).values() if isinstance(hooks, dict) else []:
7009
7164
  for e in ev if isinstance(ev, list) else []:
7010
7165
  for h in (e.get("hooks") or []) if isinstance(e, dict) else []:
7011
7166
  cmd = str(h.get("command", "")) if isinstance(h, dict) else ""
7012
7167
  mark = _hook_mark(cmd)
7013
7168
  if mark:
7014
- launchers.append(cmd[:cmd.index(mark)].strip())
7015
- for launcher in dict.fromkeys(launchers):
7016
- st, msg = launcher_health(launcher, shared=shared)
7017
- out.append((st, "hook launch", f"{where}: {msg}"))
7169
+ marks.setdefault(cmd[:cmd.index(mark)].strip(), set()).add(
7170
+ LEGACY_HOOK_COMMANDS.get(mark, mark))
7171
+ for launcher, served in marks.items():
7172
+ found.append((where, role, launcher, served) + launcher_verdict(
7173
+ launcher, shared=role in ("shared", "codex")))
7174
+ out = []
7175
+ for i, (where, role, launcher, served, st, code, detail) in enumerate(found):
7176
+ broken = None
7177
+ if code in ("not-on-path", "cannot-start") and role == "codex":
7178
+ st = "warn"
7179
+ broken = ("Codex then misses only its session guide and live state; "
7180
+ "AGENTS.md still carries the rules. The .codex/ files are "
7181
+ f"shared and stay portable — `{invocation()} install` says "
7182
+ "what this machine's ~/.codex/config.toml needs")
7183
+ elif code in ("not-on-path", "cannot-start"):
7184
+ # what the other Claude launchers that do start already serve
7185
+ others = [(w, s) for j, (w, r, _, s, _, c, _) in enumerate(found)
7186
+ if j != i and r != "codex" and c == "ok"]
7187
+ covered = set().union(*[s for _, s in others]) if others else set()
7188
+ off = [label for mark, label in HOOK_JOBS if mark in served - covered]
7189
+ here = {"shared": ".claude/settings.json",
7190
+ "own": ".claude/settings.local.json",
7191
+ "user": "~/.claude/settings.json"}[role]
7192
+ if not off:
7193
+ st = "warn"
7194
+ names = list(dict.fromkeys(w for w, s in others if s & served))
7195
+ keep = ("Teammates may rely on them — keep them, or remove them "
7196
+ "from .claude/settings.json" if role == "shared" else
7197
+ f"Remove them from {here}")
7198
+ broken = (f"these hooks show an error on every call they match, "
7199
+ f"while {' and '.join(names)} "
7200
+ f"{'serve' if len(names) > 1 else 'serves'} the same "
7201
+ f"hooks with a launcher that starts. {keep}")
7202
+ else:
7203
+ gate = any(m in served - covered for m, _ in HOOK_JOBS[:2])
7204
+ st = "fail" if gate else "warn"
7205
+ fix = {"shared": f"re-run `{invocation()} install` — it adds this "
7206
+ "machine's own launcher to "
7207
+ ".claude/settings.local.json and leaves the "
7208
+ "shared file to the team",
7209
+ "own": f"re-run `{invocation()} install`, which picks an "
7210
+ "interpreter that can",
7211
+ "user": f"re-run `{invocation()} install -g`"}[role]
7212
+ broken = (f"{_and_list(off)} {'is' if len(off) == 1 else 'are'} "
7213
+ f"off {'in every project' if role == 'user' else 'on this machine'}"
7214
+ f"; {fix}")
7215
+ out.append((st, "hook launch",
7216
+ f"{where}: {launcher_message(launcher, code, detail, broken)}"))
7018
7217
  return out
7019
7218
 
7020
7219
 
@@ -7039,6 +7238,7 @@ def harness_checks(project_root, home=None):
7039
7238
  + ("" if filled else f" — fill in {cfg}")))
7040
7239
  except ValueError:
7041
7240
  out.append(("fail", "connections", f"{cfg} is not valid JSON"))
7241
+ out.append(credentials_check(root))
7042
7242
  else:
7043
7243
  out.append(("warn", "connections", f"no {CONFIG_DIR}/{CONFIG_NAME} — "
7044
7244
  f"{invocation()} install"))
@@ -7060,7 +7260,11 @@ def harness_checks(project_root, home=None):
7060
7260
  mcp = _read_json(root / ".mcp.json") or {}
7061
7261
  local = local_mcp_entry(root, home_dir)
7062
7262
  if local is not None:
7063
- st, msg = launcher_health(mcp_launcher(local) or str(local.get("command")))
7263
+ st, msg = launcher_health(
7264
+ mcp_launcher(local) or str(local.get("command")),
7265
+ broken="the pythia_approve door stays closed (AskUserQuestion and "
7266
+ f"the console remain); re-run `{invocation()} install`, which "
7267
+ "registers it again with a launcher that starts")
7064
7268
  out.append((st, "approval door", "pythia_approve MCP tool registered in "
7065
7269
  f"Claude Code's local scope (overrides .mcp.json) — {msg}"))
7066
7270
  elif "pythia" in (mcp.get("mcpServers") or {}):
@@ -7069,7 +7273,11 @@ def harness_checks(project_root, home=None):
7069
7273
  entry = mcp["mcpServers"]["pythia"]
7070
7274
  st, msg = launcher_health(mcp_launcher(entry) or str(
7071
7275
  (entry or {}).get("command") if isinstance(entry, dict) else entry),
7072
- shared=True)
7276
+ shared=True,
7277
+ broken="the pythia_approve door stays closed (AskUserQuestion and "
7278
+ f"the console remain); re-run `{invocation()} install` — it "
7279
+ "registers this machine's launcher in Claude Code's local "
7280
+ "scope, which overrides .mcp.json")
7073
7281
  out.append((st, "approval door", "pythia_approve MCP tool registered in "
7074
7282
  ".mcp.json" + ("" if trusted else
7075
7283
  " (approve the server once in /mcp)")
@@ -7178,8 +7386,8 @@ def cmd_doctor(conn, schema, ns):
7178
7386
  print(f" {paint(f'{s:<4}', color[s], en)} {a:<15} {m}")
7179
7387
  bad = sum(1 for s, _, _ in rows if s == "fail")
7180
7388
  if bad:
7181
- print(paint(f"\n {bad} problem(s) will stop approvals or the guard "
7182
- "from working.", "red", en))
7389
+ print(paint(f"\n {bad} problem(s) to fix first — each fail line "
7390
+ "names its fix.", "red", en))
7183
7391
  if conn is None:
7184
7392
  print(f"\n Database environment: {invocation()} doctor --db")
7185
7393
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pythia-plsql
3
- Version: 0.15.2
3
+ Version: 0.15.4
4
4
  Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
5
5
  License: MIT
6
6
  Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -20,7 +20,7 @@ Dynamic: license-file
20
20
 
21
21
  > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
22
22
 
23
- **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
23
+ **English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)** · **[Website →](https://thaildhe172591.github.io/pythia/)**
24
24
 
25
25
  [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
26
26
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -191,6 +191,11 @@ each agent needs you to finish by hand.
191
191
  - a `deny` rule so the agent cannot forge a grant, and the MCP server
192
192
  enabled.
193
193
 
194
+ It scaffolds `.pythia/connections.json` (mode 600) and adds it to the
195
+ project's `.gitignore` — commit that line — and warns if git already
196
+ tracks the file: its passwords are then in the history, so untrack it and
197
+ change them.
198
+
194
199
  It also writes the harness into **`CLAUDE.md`** — the file Claude Code
195
200
  itself loads every session — in a marker-delimited block, leaving your own
196
201
  text untouched. The rules hold even with `--no-hooks`, before a restart,
@@ -206,7 +211,10 @@ each agent needs you to finish by hand.
206
211
  the absolute interpreter, and the MCP approver to Claude Code's local scope
207
212
  (`claude mcp add --scope local`); your teammates never get a path from your
208
213
  machine. `pythia doctor` starts every launcher it finds and fails the ones
209
- that cannot import pythia.
214
+ that cannot import pythia — except where this machine's own launcher
215
+ already serves the same hooks: then the team's shared copy erroring here
216
+ is a warning (keep it for teammates or remove it). Codex's session hook is
217
+ a warning too: it carries only the session guide, and AGENTS.md the rules.
210
218
 
211
219
  Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
212
220
  2. **Restart the Claude Code session** so the hooks and the MCP server load.
@@ -25,8 +25,9 @@ applies:
25
25
  top-level `"default": "<name>"`. Ambiguity is an error, never a guess.
26
26
  - `--conn NAME` and `PYTHIA_CONNECTION` override everything; the
27
27
  `PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN` variables bypass the file.
28
- - The file holds credentials: it is gitignored — keep it that way, and keep
29
- it out of chat and screenshots.
28
+ - The file holds credentials: install writes it into `.gitignore` (commit
29
+ that line) — keep it that way, and keep it out of chat and screenshots.
30
+ `pythia doctor` fails if git tracks it.
30
31
 
31
32
  Verify with `pythia check`: it prints who you are connected as and object
32
33
  counts. A failure names the connection and what to check.
@@ -89,7 +90,7 @@ until you want it.
89
90
 
90
91
  | File | Created by | What it does |
91
92
  |---|---|---|
92
- | `connections.json` | `pythia install` | Where to connect. **Holds passwords — never open it**; `pythia connections` lists names, users, schemas and targets with no secrets. Gitignored. |
93
+ | `connections.json` | `pythia install` | Where to connect. **Holds passwords — never open it**; `pythia connections` lists names, users, schemas and targets with no secrets. Install adds it to `.gitignore`. |
93
94
  | `journal/` | first write or snapshot | Every captured version, with a runnable rollback per entry. |
94
95
  | `conventions.json` | `pythia conventions --init` | Naming patterns per object type. Every apply preview warns when a new name drifts. |
95
96
  | `conventions.md` | `pythia conventions --init` | The house rules in prose. **`pythia-write` reads this before writing anything**, and it outranks the generic patterns this pack ships with. |
@@ -88,9 +88,14 @@ then only happen at the developer's console (`pythia approve <token>`), or
88
88
  through an autopilot lease started there (`pythia autopilot on`).
89
89
 
90
90
  After `pythia install`: restart the session, run `pythia doctor`, and fix
91
- every `fail` line — each one is a setting that will stop approvals from
92
- arriving. A `fail` on **hook launch** means a hook's interpreter cannot import
91
+ every `fail` line — each one names its fix. Most are a setting that will stop
92
+ approvals from arriving; a `fail` on **credentials** means git tracks
93
+ `.pythia/connections.json`: `git rm --cached` it, commit, and change those
94
+ passwords. A `fail` on **hook launch** means a hook's interpreter cannot import
93
95
  pythia, so the guard is off: common when pythia lives in a venv or pipx and
94
96
  Claude Code starts from a desktop app or IDE. Re-run `pythia install` — it pins
95
97
  that machine's interpreter in `.claude/settings.local.json` and Claude Code's
96
- local MCP scope, never in the shared files.
98
+ local MCP scope, never in the shared files. A `warn` naming
99
+ `.claude/settings.json` is the team's shared copy failing on this machine
100
+ while your own launcher already serves the same hooks: keep it for teammates
101
+ or remove it.
@@ -4,6 +4,7 @@ no network, no npx needed.
4
4
 
5
5
  Run: python tests/test_install.py
6
6
  """
7
+ import contextlib
7
8
  import io
8
9
  import json
9
10
  import os
@@ -48,6 +49,142 @@ def test_scaffold_creates_the_config_readable_by_its_owner_only():
48
49
  assert created and path.stat().st_mode & 0o777 == 0o600
49
50
 
50
51
 
52
+ SECRET = ".pythia/connections.json"
53
+
54
+
55
+ @contextlib.contextmanager
56
+ def hermetic_git():
57
+ """git with no system or personal config: a developer's own excludes file
58
+ must not decide what these tests see."""
59
+ keys = ("GIT_CONFIG_NOSYSTEM", "GIT_CONFIG_GLOBAL", "XDG_CONFIG_HOME", "HOME")
60
+ old = {k: os.environ.get(k) for k in keys}
61
+ with tempfile.TemporaryDirectory() as home:
62
+ empty = os.path.join(home, "gitconfig")
63
+ open(empty, "w").close()
64
+ os.environ.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=empty,
65
+ XDG_CONFIG_HOME=home, HOME=home)
66
+ try:
67
+ yield
68
+ finally:
69
+ for k, v in old.items():
70
+ if v is None:
71
+ os.environ.pop(k, None)
72
+ else:
73
+ os.environ[k] = v
74
+
75
+
76
+ def git_init(td):
77
+ """A fresh repository at td; None where git is absent (the test skips)."""
78
+ import subprocess
79
+ git = pythia.path_lookup("git")
80
+ if git:
81
+ subprocess.run([git, "init", "-q", str(td)], check=True,
82
+ stdin=subprocess.DEVNULL)
83
+ return git
84
+
85
+
86
+ def test_install_keeps_the_password_file_out_of_every_clone():
87
+ """GUIDE and SECURITY said connections.json is "gitignored by the
88
+ scaffold", but nothing wrote the rule: in the 0.15.3 field test `git
89
+ status` listed `.pythia/`, one `git add -A` away from committing the
90
+ passwords. The rule goes in the project's .gitignore, so it reaches every
91
+ clone — .git/info/exclude would protect this machine only."""
92
+ with hermetic_git(), tempfile.TemporaryDirectory() as td:
93
+ if git_init(td) is None:
94
+ return
95
+ root = pathlib.Path(td)
96
+ gi = root / ".gitignore"
97
+ gi.write_bytes(b"node_modules") # no final newline: theirs stays
98
+ pythia.scaffold_config(root)
99
+ assert pythia.git_ignore_source(root, SECRET)[0] == "none"
100
+ assert pythia.ignore_connections(root) == gi
101
+ text = gi.read_text(encoding="utf-8")
102
+ assert text.startswith("node_modules\n") and SECRET in text.splitlines()
103
+ assert pythia.git_ignore_source(root, SECRET)[0] == "shared"
104
+ assert pythia.ignore_connections(root) is None # once
105
+ assert gi.read_text(encoding="utf-8") == text
106
+
107
+
108
+ def test_install_trusts_a_shared_rule_but_not_a_negated_or_private_one():
109
+ with hermetic_git(), tempfile.TemporaryDirectory() as td:
110
+ if git_init(td) is None:
111
+ return
112
+ root = pathlib.Path(td)
113
+ gi = root / ".gitignore"
114
+ gi.write_text(".pythia/\n", encoding="utf-8")
115
+ assert pythia.ignore_connections(root) is None # covered already
116
+ assert gi.read_text(encoding="utf-8") == ".pythia/\n"
117
+ # a later negation un-ignores it: the appended rule comes last and wins
118
+ gi.write_text(".pythia/*\n!.pythia/connections.json\n", encoding="utf-8")
119
+ assert pythia.git_ignore_source(root, SECRET)[0] == "none"
120
+ assert pythia.ignore_connections(root) == gi
121
+ assert pythia.git_ignore_source(root, SECRET)[0] == "shared"
122
+ # ignored on this machine only: a teammate's clone would still commit it
123
+ gi.unlink()
124
+ exclude = root / ".git" / "info" / "exclude"
125
+ exclude.parent.mkdir(exist_ok=True)
126
+ exclude.write_text(SECRET + "\n", encoding="utf-8")
127
+ state, source = pythia.git_ignore_source(root, SECRET)
128
+ assert state == "local" and "exclude" in source
129
+ assert pythia.ignore_connections(root) == gi
130
+ assert pythia.git_ignore_source(root, SECRET)[0] == "shared"
131
+
132
+
133
+ def test_install_writes_the_rule_outside_git_too():
134
+ """No repository yet, or no git at all: the rule is written anyway, so a
135
+ later `git init` starts safe — and read back as text, written once."""
136
+ with hermetic_git(), tempfile.TemporaryDirectory() as td:
137
+ root = pathlib.Path(td)
138
+ assert pythia.git_ignore_source(root, SECRET) is None
139
+ assert pythia.ignore_connections(root) == root / ".gitignore"
140
+ assert pythia.ignore_connections(root) is None
141
+ real = pythia.path_lookup
142
+ pythia.path_lookup = lambda *a, **k: None
143
+ try:
144
+ with tempfile.TemporaryDirectory() as td:
145
+ root = pathlib.Path(td)
146
+ (root / ".gitignore").write_text("/.pythia/connections.json\n",
147
+ encoding="utf-8")
148
+ assert pythia.ignore_connections(root) is None
149
+ (root / ".gitignore").write_text(
150
+ ".pythia\n!.pythia/connections.json\n", encoding="utf-8")
151
+ assert pythia.ignore_connections(root) == root / ".gitignore"
152
+ finally:
153
+ pythia.path_lookup = real
154
+
155
+
156
+ def test_install_warns_when_git_already_tracks_the_password_file():
157
+ """A rule cannot untrack a committed file; the passwords are already in
158
+ the history. Say so, with the commands, at install time."""
159
+ import subprocess
160
+ with hermetic_git(), tempfile.TemporaryDirectory() as td:
161
+ git = git_init(td)
162
+ if git is None:
163
+ return
164
+ root = pathlib.Path(td)
165
+ pythia.scaffold_config(root)
166
+ subprocess.run([git, "-C", td, "add", "-f", SECRET], check=True,
167
+ stdin=subprocess.DEVNULL)
168
+ buf = io.StringIO()
169
+ with contextlib.redirect_stdout(buf):
170
+ pythia.report_connections_ignore(root)
171
+ out = buf.getvalue()
172
+ assert f"git rm --cached {SECRET}" in out and "password" in out, out
173
+
174
+
175
+ def test_install_survives_a_gitignore_it_cannot_write():
176
+ """The rule is a safeguard, not a reason to abort the install: say what
177
+ to add by hand and carry on."""
178
+ with tempfile.TemporaryDirectory() as td:
179
+ root = pathlib.Path(td)
180
+ (root / ".gitignore").mkdir()
181
+ buf = io.StringIO()
182
+ with contextlib.redirect_stdout(buf):
183
+ pythia.report_connections_ignore(root)
184
+ out = buf.getvalue()
185
+ assert "WARNING" in out and f"add {SECRET}" in out, out
186
+
187
+
51
188
  def test_a_readable_config_is_warned_about_once_per_process():
52
189
  if os.name != "posix":
53
190
  return
@@ -208,6 +345,27 @@ def test_devnull_stdin_is_not_a_human():
208
345
  assert not (pathlib.Path(td) / ".pythia" / "policy.json").is_file()
209
346
 
210
347
 
348
+ def test_the_website_states_what_the_code_is():
349
+ """site/ is published to GitHub Pages. What it states — the release, the
350
+ counts, every skill by name — must be what this commit is, so a version
351
+ bump or a new skill that forgets the site fails here, not in public."""
352
+ site = ROOT / "site"
353
+ html = (site / "index.html").read_text(encoding="utf-8")
354
+ v = pythia.__version__
355
+ assert f'data-version="{v}"' in html
356
+ assert set(re.findall(r'class="ver">([^<]+)<', html)) == {v}
357
+ skills = sorted(p.parent.name for p in (ROOT / "skills").glob("*/SKILL.md"))
358
+ want = {"commands": len(pythia.COMMANDS), "skills": len(skills),
359
+ "queries": len(list((ROOT / "queries").glob("*.sql"))),
360
+ "lint": len(pythia.LINT_RULES)}
361
+ for key, n in want.items():
362
+ assert set(re.findall(rf'data-count="{key}">(\d+)<', html)) == {str(n)}, key
363
+ for name in skills:
364
+ assert f"<b>{name}</b>" in html, name
365
+ for f in ("logo.webp", "logo.png", "favicon.png"): # what the page loads
366
+ assert (site / f).is_file(), f
367
+
368
+
211
369
  def test_one_version_across_every_manifest():
212
370
  """pyproject, plugin.json, marketplace.json and npm/package.json must all
213
371
  carry the same version — the release workflow publishes from one tag."""
@@ -273,6 +431,9 @@ def test_cmd_install_runs_end_to_end():
273
431
  out = buf.getvalue()
274
432
  assert (pathlib.Path(td) / ".pythia" / "connections.json").is_file()
275
433
  assert "Next: fill in" in out
434
+ gi = pathlib.Path(td) / ".gitignore"
435
+ assert SECRET in gi.read_text(encoding="utf-8").splitlines()
436
+ assert f"Added {SECRET} to" in out
276
437
  assert env is not None
277
438
 
278
439
 
@@ -20,6 +20,7 @@ sys.path.insert(0, str(HERE.parent / "scripts"))
20
20
  sys.path.insert(0, str(HERE))
21
21
  import pythia # noqa: E402
22
22
  import test_phase3 as p3 # noqa: E402 (fakes only; its tests are not re-run)
23
+ import test_install as ti # noqa: E402 (git helpers only; its tests are not re-run)
23
24
 
24
25
  FakeConn, base_script, apply_ns, expect_exit = (
25
26
  p3.FakeConn, p3.base_script, p3.apply_ns, p3.expect_exit)
@@ -1173,6 +1174,61 @@ def test_doctor_reports_the_wiring_after_install():
1173
1174
  and "shares" in m for s, a, m in rows), rows
1174
1175
 
1175
1176
 
1177
+ def _cred(rows):
1178
+ found = [(s, m) for s, a, m in rows if a == "credentials"]
1179
+ assert len(found) == 1, rows
1180
+ return found[0]
1181
+
1182
+
1183
+ def test_doctor_fails_a_password_file_git_tracks():
1184
+ """Not ignored is a risk (warn); tracked is a leak (fail) — the passwords
1185
+ are in the repository already, and a .gitignore line cannot take them
1186
+ back out. The fix names the commands and the rotation."""
1187
+ import subprocess
1188
+ with ti.hermetic_git(), tempfile.TemporaryDirectory() as td, \
1189
+ tempfile.TemporaryDirectory() as home:
1190
+ git = ti.git_init(td)
1191
+ if git is None:
1192
+ return
1193
+ root = pathlib.Path(td)
1194
+ pythia.scaffold_config(root)
1195
+ st, msg = _cred(pythia.harness_checks(td, home))
1196
+ assert st == "warn" and "git add -A" in msg and "install" in msg, msg
1197
+ pythia.ignore_connections(root)
1198
+ assert _cred(pythia.harness_checks(td, home))[0] == "ok"
1199
+ subprocess.run([git, "-C", td, "add", "-f", ti.SECRET], check=True,
1200
+ stdin=subprocess.DEVNULL)
1201
+ st, msg = _cred(pythia.harness_checks(td, home))
1202
+ assert st == "fail", msg
1203
+ assert f"git rm --cached {ti.SECRET}" in msg and "password" in msg, msg
1204
+
1205
+
1206
+ def test_doctor_warns_a_rule_only_this_machine_has():
1207
+ with ti.hermetic_git(), tempfile.TemporaryDirectory() as td, \
1208
+ tempfile.TemporaryDirectory() as home:
1209
+ if ti.git_init(td) is None:
1210
+ return
1211
+ root = pathlib.Path(td)
1212
+ pythia.scaffold_config(root)
1213
+ exclude = root / ".git" / "info" / "exclude"
1214
+ exclude.parent.mkdir(exist_ok=True)
1215
+ exclude.write_text(ti.SECRET + "\n", encoding="utf-8")
1216
+ st, msg = _cred(pythia.harness_checks(td, home))
1217
+ assert st == "warn" and "only on this machine" in msg, msg
1218
+
1219
+
1220
+ def test_doctor_says_plainly_when_there_is_no_git_to_ask():
1221
+ with ti.hermetic_git(), tempfile.TemporaryDirectory() as td, \
1222
+ tempfile.TemporaryDirectory() as home:
1223
+ pythia.scaffold_config(pathlib.Path(td))
1224
+ st, msg = _cred(pythia.harness_checks(td, home))
1225
+ assert st == "info" and "git" in msg, msg
1226
+ # no password file, nothing to protect: no row at all
1227
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1228
+ assert not [a for _, a, _ in pythia.harness_checks(td, home)
1229
+ if a == "credentials"]
1230
+
1231
+
1176
1232
  def test_install_registers_the_mcp_approver_once_and_keeps_other_servers():
1177
1233
  with tempfile.TemporaryDirectory() as td:
1178
1234
  path = pathlib.Path(td) / ".mcp.json"
@@ -1621,6 +1677,111 @@ def test_doctor_never_runs_a_script_path_from_a_shared_file():
1621
1677
  assert len(named) == 3, rows
1622
1678
 
1623
1679
 
1680
+ # Field test of 0.15.2: right after an install from a venv, doctor reported
1681
+ # `fail` for the team's shared hooks ("the guard is off") although
1682
+ # settings.local.json served every one of them, and `fail` for Codex's session
1683
+ # hook, which carries no guard at all — and advised a re-run of install that
1684
+ # cannot change either, since install leaves shared files alone.
1685
+
1686
+ GONE = "python3.99 -m pythia" # a bare interpreter on no PATH
1687
+
1688
+
1689
+ def _launch_rows(rows, prefix):
1690
+ return [(s, m) for s, a, m in rows if a == "hook launch" and m.startswith(prefix)]
1691
+
1692
+
1693
+ def test_doctor_a_shared_hook_this_machine_already_covers_is_a_warning():
1694
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1695
+ pythia.install_claude_hooks(td, launcher=GONE) # the team's
1696
+ pythia.install_claude_hooks(td, launcher=_good_launcher(), local=True)
1697
+ rows = pythia.harness_checks(td, home)
1698
+ shared = _launch_rows(rows, ".claude/settings.json")
1699
+ assert len(shared) == 1 and shared[0][0] == "warn", rows
1700
+ msg = shared[0][1]
1701
+ assert ".claude/settings.local.json" in msg # what serves them here
1702
+ assert "keep" in msg and "remove" in msg # the developer's call
1703
+ assert "error" in msg # what they will see
1704
+ assert not [r for r in rows if r[0] == "fail"], rows
1705
+
1706
+
1707
+ def test_doctor_a_shared_hook_nothing_here_covers_stays_a_fail_with_a_real_fix():
1708
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1709
+ pythia.install_claude_hooks(td, launcher=GONE)
1710
+ local = pathlib.Path(td) / ".claude" / "settings.local.json"
1711
+ local.write_text(json.dumps({"hooks": {"PreToolUse": [ # the guard only
1712
+ {"matcher": "Bash", "hooks": [{"type": "command",
1713
+ "command": f"{_good_launcher()} hook pre-tool"}]}]}}), encoding="utf-8")
1714
+ rows = pythia.harness_checks(td, home)
1715
+ shared = _launch_rows(rows, ".claude/settings.json")
1716
+ assert len(shared) == 1 and shared[0][0] == "fail", rows
1717
+ msg = shared[0][1]
1718
+ assert "not on PATH" in msg and "install" in msg
1719
+ assert ".claude/settings.local.json" in msg # where the fix lands
1720
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1721
+ pythia.install_claude_hooks(td, launcher=GONE) # no local file at all
1722
+ assert _launch_rows(pythia.harness_checks(td, home),
1723
+ ".claude/settings.json")[0][0] == "fail"
1724
+
1725
+
1726
+ def test_doctor_names_exactly_what_a_broken_hook_leaves_off():
1727
+ """~/.claude (install -g) serves the guard and the approval hook but no
1728
+ SessionStart: the team's broken copy then leaves off only the session
1729
+ guide — a warning that says so, not "the guard is off"."""
1730
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1731
+ pythia.install_claude_hooks(td, launcher=GONE)
1732
+ pythia.install_claude_hooks(home, events=("PreToolUse", "PostToolUse"),
1733
+ launcher=_good_launcher())
1734
+ rows = pythia.harness_checks(td, home)
1735
+ shared = _launch_rows(rows, ".claude/settings.json")
1736
+ assert len(shared) == 1 and shared[0][0] == "warn", rows
1737
+ assert "session guide" in shared[0][1] and "guard" not in shared[0][1]
1738
+ assert not [r for r in rows if r[0] == "fail"], rows
1739
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1740
+ pythia.install_claude_hooks(td, launcher=GONE)
1741
+ local = pathlib.Path(td) / ".claude" / "settings.local.json"
1742
+ local.write_text(json.dumps({"hooks": {"PreToolUse": [
1743
+ {"matcher": "Bash", "hooks": [{"type": "command",
1744
+ "command": f"{_good_launcher()} hook pre-tool"}]}]}}), encoding="utf-8")
1745
+ msg = _launch_rows(pythia.harness_checks(td, home), ".claude/settings.json")[0][1]
1746
+ assert "AskUserQuestion approval" in msg and "sqlplus guard" not in msg
1747
+
1748
+
1749
+ def test_doctor_codex_session_hook_names_its_real_scope():
1750
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1751
+ p = pathlib.Path(td) / ".codex" / "hooks.json"
1752
+ p.parent.mkdir()
1753
+ p.write_text(json.dumps({"hooks": {"SessionStart": [{"hooks": [
1754
+ {"type": "command", "command": f"{GONE} hook session-start"}]}]}}),
1755
+ encoding="utf-8")
1756
+ rows = pythia.harness_checks(td, home)
1757
+ codex = _launch_rows(rows, ".codex/hooks.json")
1758
+ assert len(codex) == 1 and codex[0][0] == "warn", rows
1759
+ assert "AGENTS.md" in codex[0][1] and "session" in codex[0][1]
1760
+ assert "guard" not in codex[0][1] # it carries none
1761
+ assert not [r for r in rows if r[0] == "fail"], rows
1762
+
1763
+
1764
+ def test_doctor_names_what_a_broken_mcp_launcher_closes():
1765
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1766
+ (pathlib.Path(td) / ".mcp.json").write_text(json.dumps({"mcpServers": {
1767
+ "pythia": {"command": "python3.99", "args": ["-m", "pythia", "mcp"]}}}),
1768
+ encoding="utf-8")
1769
+ door = [(s, m) for s, a, m in pythia.harness_checks(td, home)
1770
+ if a == "approval door"]
1771
+ assert len(door) == 1 and door[0][0] == "fail", door
1772
+ assert "pythia_approve" in door[0][1] and "local scope" in door[0][1]
1773
+ assert "guard" not in door[0][1] # a door, not the guard
1774
+
1775
+
1776
+ def test_doctor_sends_a_broken_global_hook_to_install_dash_g():
1777
+ with tempfile.TemporaryDirectory() as td, tempfile.TemporaryDirectory() as home:
1778
+ pythia.install_claude_hooks(home, events=("PreToolUse", "PostToolUse"),
1779
+ launcher='"/nonexistent/bin/python" -m pythia')
1780
+ user = _launch_rows(pythia.harness_checks(td, home), "~/.claude/settings.json")
1781
+ assert len(user) == 1 and user[0][0] == "fail", user
1782
+ assert "install -g" in user[0][1]
1783
+
1784
+
1624
1785
  def test_doctor_warns_a_bare_launcher_that_lives_in_the_active_virtualenv():
1625
1786
  ok = lambda l, cwd=None: (True, "") # noqa: E731
1626
1787
  with tempfile.TemporaryDirectory() as venv:
File without changes
File without changes