pythia-plsql 0.4.8__tar.gz → 0.4.10__tar.gz

{pythia_plsql-0.4.8/scripts/pythia_plsql.egg-info → pythia_plsql-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.8
+Version: 0.4.10
 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.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.4.8"
+version = "0.4.10"
 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."
 readme = "README.md"
 license = { text = "MIT" }

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/scripts/pythia.py

@@ -967,10 +967,46 @@ def json_envelope(command, connection, schema, cols, rows, truncated, **extra):
 
 # --- database access ---------------------------------------------------------
 
-def connect_failure_message(exc, conn_name):
-    """A failure to connect should say which entry failed and what to check —
-    a driver stack trace tells the reader nothing actionable."""
-    return (f"Could not connect using connection {conn_name!r}: {exc}\n"
+def authenticating_account(user):
+    """The Oracle account that actually authenticates. With proxy
+    authentication the connect string is `agent[owner]` and it is the agent
+    whose password is checked, whose account locks, and whose name a DBA
+    needs — not the schema in front of you."""
+    if not user:
+        return None
+    return str(user).split("[", 1)[0].strip().upper()
+
+
+def connect_failure_message(exc, conn_name, user=None):
+    """A failure to connect should say which entry failed and what to do. For
+    the three errors Oracle has already diagnosed precisely, generic advice
+    wastes the reader's time, so name the actual next step instead."""
+    text = str(exc)
+    account = authenticating_account(user)
+    who = account or "<the connecting user>"
+    head = f"Could not connect using connection {conn_name!r}: {text}"
+    if "ORA-28000" in text:
+        return (f"{head}\n"
+                f"The account {who} is locked. A DBA or superuser unlocks it:\n"
+                f"  ALTER USER {who} ACCOUNT UNLOCK;\n"
+                "Then find out why, or it locks again — a run of wrong "
+                "passwords trips\nFAILED_LOGIN_ATTEMPTS:\n"
+                f"  SELECT account_status, lock_date, profile FROM dba_users "
+                f"WHERE username = '{who}';")
+    if "ORA-28001" in text or "ORA-28002" in text:
+        return (f"{head}\n"
+                f"The password for {who} has expired. A DBA sets a new one:\n"
+                f"  ALTER USER {who} IDENTIFIED BY \"<new password>\";\n"
+                "Update it in connections.json in the same breath. To stop the "
+                "clock for a\nservice account, put it on a profile with "
+                "PASSWORD_LIFE_TIME UNLIMITED.")
+    if "ORA-01017" in text:
+        return (f"{head}\n"
+                f"Wrong username or password for {who}. Check the entry in "
+                "connections.json —\nand check it before retrying: repeated "
+                "attempts trip FAILED_LOGIN_ATTEMPTS and\nlock the account, "
+                "which needs a DBA to undo.")
+    return (f"{head}\n"
             "Check host/port/service_name, the credentials, and that the database "
             "is reachable from here. Use --conn NAME to try a different entry.")
 
@@ -1296,6 +1332,78 @@ def cmd_plscope(conn, schema, ns):
         emit_table(ns, stmt_cols, *clip(stmt_rows, ns.limit))
 
 
+CONVENTIONS_TEMPLATE = """{
+  "naming": {
+    "TABLE": "^T_[A-Z0-9_]+$",
+    "PROCEDURE": "^P_[A-Z0-9_]+$",
+    "FUNCTION": "^F_[A-Z0-9_]+$",
+    "PACKAGE": "^PKG_[A-Z0-9_]+$",
+    "SEQUENCE": "^S_[A-Z0-9_]+$",
+    "TRIGGER": "^TRG_[A-Z0-9_]+$"
+  }
+}
+"""
+
+CONVENTIONS_PROSE_TEMPLATE = """# Project conventions
+
+Rules for anyone — human or agent — writing PL/SQL in this schema. Agents are
+told to read this before writing, and it outranks the generic patterns the
+skill pack ships with.
+
+`conventions.json` next to this file holds the naming patterns as regexes;
+every `pythia apply` preview warns when a new object's name does not match.
+Keep the two in step: this file explains, that file enforces.
+
+## Naming
+
+Replace the patterns in `conventions.json` with yours, then describe them
+here so the reasoning survives. `pythia similar <A_TYPICAL_NAME>` shows what
+the schema already does — copy that rather than inventing a scheme.
+
+| Kind | Rule | Example |
+|---|---|---|
+| Table | | |
+| Procedure | | |
+| Function | | |
+
+## Rules that carry a cost when broken
+
+State the consequence, not just the rule — a rule with a named cost gets
+followed. For example: which parameter prefixes the calling layer depends on,
+which column every query must filter by, where a transaction may commit.
+
+| Rule | Cost of breaking it |
+|---|---|
+| | |
+
+## Known exceptions
+
+Objects that break the pattern on purpose, and why renaming them is worse
+than the warning they produce on every apply.
+"""
+
+
+def scaffold_conventions(root):
+    """Write the conventions pair, skipping anything that already exists.
+    Returns the paths actually created.
+
+    The docs used to say "copy examples/conventions.example.json", which is
+    no help to anyone who installed the wheel: there is no examples directory
+    there. The tool carries the templates instead.
+    """
+    d = pathlib.Path(root) / CONFIG_DIR
+    made = []
+    for name, body in (("conventions.json", CONVENTIONS_TEMPLATE),
+                       ("conventions.md", CONVENTIONS_PROSE_TEMPLATE)):
+        path = d / name
+        if path.is_file():
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body, encoding="utf-8")
+        made.append(path)
+    return made
+
+
 def load_conventions(root):
     """Project house style from .pythia/conventions.json — the machine half of
     the customization surface (the prose half is conventions.md, for agents).
@@ -1754,23 +1862,39 @@ def cmd_journal(conn, schema, ns):
 
 
 def cmd_conventions(conn, schema, ns):
-    conv = load_conventions(ns.project_root)
+    root = ns.project_root
+    if getattr(ns, "init", False):
+        made = scaffold_conventions(root)
+        for path in made:
+            print(f"Created {path}")
+        if not made:
+            print(f"Both files already exist in "
+                  f"{pathlib.Path(root) / CONFIG_DIR} — left untouched.")
+        else:
+            print(NL + "Edit the patterns to match this schema — "
+                  f"`{invocation()} similar <A_TYPICAL_NAME>` shows what "
+                  "it already does." + NL + "Every apply preview then "
+                  "warns when a name drifts from them.")
+        return
+    conv = load_conventions(root)
     if ns.json:
         print(json.dumps(conv or {}))
         return
     if not conv:
         print("No project conventions configured.")
-        print(f"Create {pathlib.Path(ns.project_root) / CONFIG_DIR / 'conventions.json'} "
-              "(see examples/conventions.example.json) and apply previews will "
-              "warn when a new object's name drifts from your patterns.\n"
-              "Put the prose rules in conventions.md next to it for your agents.")
+        print(f"Create the starter pair with: {invocation()} conventions --init")
+        print("  conventions.json  naming patterns; apply previews warn on drift")
+        print("  conventions.md    the prose rules your agents read first")
         return
     print("Naming patterns — apply previews warn when a name drifts:")
     for otype, pattern in conv.get("naming", {}).items():
         print(f"  {otype:<13} {pattern}")
-    md = pathlib.Path(ns.project_root) / CONFIG_DIR / "conventions.md"
+    md = pathlib.Path(root) / CONFIG_DIR / "conventions.md"
     if md.is_file():
-        print(f"\nProse rules for agents: {md}")
+        print(NL + f"Prose rules for agents: {md}")
+    else:
+        print(NL + f"No conventions.md yet — {invocation()} conventions "
+              "--init writes one.")
 
 
 AGENT_USER_SQL = """\
@@ -2218,8 +2342,11 @@ def build_parser():
                    help="apply without stopping; the full preview still prints and journals")
     s.add_argument("--depth", type=int, default=3,
                    help="impact depth for the preview (default 3)")
-    sub.add_parser("conventions", parents=[common()],
+    s = sub.add_parser("conventions", parents=[common()],
                    help="show the project's house-style naming patterns")
+    s.add_argument("--init", action="store_true",
+                   help="write starter conventions.json and conventions.md "
+                        "into .pythia/ (never overwrites)")
     s = sub.add_parser("agent-user", parents=[common()],
                        help="SQL for a least-privilege proxy agent user; "
                             "--save adds it to connections.json")
@@ -2298,7 +2425,7 @@ def main(argv=None):
     except (oracledb.Error, OSError) as e:
         # OSError too: a DNS or socket failure arrives raw from the socket layer,
         # not wrapped as an oracledb.Error.
-        sys.exit(connect_failure_message(e, name))
+        sys.exit(connect_failure_message(e, name, c.get("user")))
     try:
         if ns.command == "journal":           # only restore reaches here
             if not ns.id:

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.8
+Version: 0.4.10
 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.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/skills/pythia-setup/SKILL.md

@@ -75,6 +75,29 @@ server: command `sql -mcp`. Example client config:
   `V$SESSION.ACTION` the LLM's name; generated SQL carries an
   `/* LLM in use */` comment.
 
+## 4. What lives in `.pythia/`, and what creates it
+
+Only `connections.json` is written by `install`. The rest appear when you ask
+for them, so an empty `.pythia/` is a working one — nothing here is missing
+until you want it.
+
+| File | Created by | What it does |
+|---|---|---|
+| `connections.json` | `pythia install` | Where to connect. Holds credentials; gitignored. |
+| `journal/` | first write or snapshot | Every captured version, with a runnable rollback per entry. |
+| `conventions.json` | `pythia conventions --init` | Naming patterns per object type. Every apply preview warns when a new name drifts. |
+| `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. |
+| `policy.json` | `pythia policy set <group> <value>` | Pins the write policy. Absent means the built-in defaults, which are already the safe ones. |
+| `settings.json` | you, by hand | Optional switches, e.g. `{"auto_snapshot": false}`. |
+
+**Capturing a team's house style is the highest-value optional step.** Run
+`pythia conventions --init`, then replace the placeholder patterns with the
+real ones — `pythia similar <A_TYPICAL_NAME>` shows what the schema already
+does, which beats inventing a scheme. Fill in `conventions.md` with the rules
+that carry a cost when broken, and say what the cost is; a rule with a named
+consequence gets followed. Commit both files to the project repo so the whole
+team and every agent session works from the same rules.
+
 ## Done when
 
 - `pythia check` connects, shows the right schema, and prints **no**

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/skills/pythia-write/SKILL.md

@@ -9,7 +9,9 @@ description: Use when writing or modifying PL/SQL source - a procedure, function
 
 **Before anything:** if the project has `.pythia/conventions.md`, read it —
 house rules there outrank every generic pattern below, and
-`pythia conventions` shows the naming patterns the apply preview will check.
+`pythia conventions` shows the naming patterns the apply preview will check. If the project has none and the developer
+describes a house style, offer `pythia conventions --init` — captured once,
+it applies to every future session instead of being re-explained.
 
 A codebase with thousands of procedures has already decided how procedures
 look. Your job is to write one that a maintainer cannot tell from the

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/tests/test_install.py

@@ -7,6 +7,7 @@ Run: python tests/test_install.py
 import json
 import os
 import pathlib
+import re
 import sys
 import tempfile
 
@@ -325,6 +326,28 @@ def test_long_path_is_flagged_before_it_silently_truncates():
     assert "duplicate" in w.lower()      # names the usual cause
 
 
+def test_conventions_init_writes_both_halves_and_never_clobbers():
+    """Telling a pip user to copy examples/conventions.example.json is no help:
+    the wheel does not ship an examples directory. The tool writes the pair."""
+    import json
+    with tempfile.TemporaryDirectory() as td:
+        made = pythia.scaffold_conventions(td)
+        d = pathlib.Path(td) / ".pythia"
+        assert sorted(p.name for p in made) == ["conventions.json",
+                                                "conventions.md"]
+        rules = json.loads((d / "conventions.json").read_text(encoding="utf-8"))
+        assert "naming" in rules and rules["naming"]        # usable as written
+        for otype, pattern in rules["naming"].items():
+            re.compile(pattern)                             # every one valid
+        assert pythia.load_conventions(td) is not None      # accepted by the loader
+        prose = (d / "conventions.md").read_text(encoding="utf-8")
+        assert "conventions.json" in prose                  # the halves reference
+        # a second run leaves existing files alone
+        (d / "conventions.json").write_text('{"naming": {}}', encoding="utf-8")
+        assert pythia.scaffold_conventions(td) == []
+        assert (d / "conventions.json").read_text(encoding="utf-8") == '{"naming": {}}'
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.4.8 → pythia_plsql-0.4.10}/tests/test_phase1.py

@@ -301,6 +301,32 @@ def test_json_envelope():
     assert d["rows"] == [{"A": 1, "B": "2026-01-02"}]
 
 
+def test_connect_failure_names_the_fix_for_common_oracle_errors():
+    """Generic advice is useless for an error Oracle already diagnosed. The
+    three that actually strand people each have one specific next step."""
+    locked = pythia.connect_failure_message(
+        Exception("ORA-28000: The account is locked."), "dev", user="agent[owner]")
+    assert "ACCOUNT UNLOCK" in locked and "AGENT" in locked   # the real account
+    assert "DBA" in locked or "superuser" in locked.lower()
+
+    expired = pythia.connect_failure_message(
+        Exception("ORA-28001: the password has expired"), "dev", user="agent")
+    assert "PASSWORD EXPIRE" in expired or "new password" in expired.lower()
+
+    wrong = pythia.connect_failure_message(
+        Exception("ORA-01017: invalid username/password"), "dev", user="agent")
+    assert "lock the account" in wrong.lower()   # warn before they retry into one
+
+    plain = pythia.connect_failure_message(OSError("getaddrinfo failed"), "dev")
+    assert "ORA-" not in plain and "dev" in plain     # unchanged for the rest
+
+
+def test_oracle_account_taken_from_a_proxy_connect_string():
+    assert pythia.authenticating_account("agent[owner]") == "AGENT"
+    assert pythia.authenticating_account("plain_user") == "PLAIN_USER"
+    assert pythia.authenticating_account(None) is None
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):