pythia-plsql 0.4.7__tar.gz → 0.4.9__tar.gz

{pythia_plsql-0.4.7/scripts/pythia_plsql.egg-info → pythia_plsql-0.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.7
+Version: 0.4.9
 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.7 → pythia_plsql-0.4.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.4.7"
+version = "0.4.9"
 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.7 → pythia_plsql-0.4.9}/scripts/pythia.py

@@ -209,12 +209,43 @@ def offer_path_fix(scripts_dir, interactive, forced=False):
         print(f"Could not update your PATH: {e}")
         return False
     print(NL + f"  {'Added' if changed else 'Already in'} your user PATH: {scripts_dir}")
+    warn = path_length_warning(os.environ.get("PATH", ""))
+    if warn:
+        print("  " + warn)
     print("  Open a NEW terminal for it to take effect — an already-running")
     print("  one keeps the environment it started with, and so do its tabs.")
     print(f"  Until then: {pathlib.Path(sys.executable).stem} -m pythia <command>")
     return True
 
 
+def path_length_warning(combined):
+    """Windows tooling still truncates PATH around 2047 characters, and a
+    freshly appended entry sits last -- so it is the first thing lost, and it
+    is lost silently. The usual cause is a PATH that had the system entries
+    copied into the user's."""
+    n = len(combined or "")
+    if n < 1900:
+        return None
+    return (f"Your PATH is {n} characters; Windows truncates near 2047, and the "
+            "entry just added is last in line.\n"
+            "  The usual cause is duplicate entries — the system PATH copied "
+            "into the user PATH by\n"
+            "  a `$env:PATH` one-liner. Compare the two scopes and remove what "
+            "appears in both.")
+
+
+def stored_path_has(directory):
+    """Is the directory in the PATH as *stored*, rather than the one this
+    process inherited? The two differ for every terminal opened before the
+    last change, which is the common confusion."""
+    if not directory or os.name != "nt":
+        return False
+    try:
+        return path_contains(_read_user_path(), directory)
+    except OSError:
+        return False
+
+
 def path_contains(path_value, directory):
     """Is this directory already listed in a PATH string? Compared the way
     the platform does: case-insensitively on Windows, ignoring trailing
@@ -280,7 +311,7 @@ def installed_scripts_dir():
     return candidates[-1] if candidates else None
 
 
-def entry_point_hint(found, scripts_dir):
+def entry_point_hint(found, scripts_dir, in_stored_path=False):
     """What to say when `pythia` will not resolve as a command. pip installs
     the executable into a scripts directory that is often not on PATH — the
     default for `pip install --user` on Windows — and the shell's
@@ -288,6 +319,21 @@ def entry_point_hint(found, scripts_dir):
     step immediately after the install the docs tell you to run."""
     if found:
         return None
+    if in_stored_path:
+        # The directory is in the stored PATH but not in this process: the
+        # terminal started before the change. Sending someone to re-run the
+        # install here wastes their time -- it already worked.
+        return (NL.join([
+            "`pythia` is already on your PATH — this terminal just started "
+            "before that was true.",
+            "  Open a NEW terminal WINDOW. A new tab is not enough: tabs "
+            "inherit the",
+            "  environment of the window that spawned them, so if you use "
+            "Windows Terminal,",
+            "  VS Code or Cursor, restart the application itself.",
+            "  In this one, keep using: "
+            + pathlib.Path(sys.executable).stem + " -m pythia <command>",
+        ]))
     out = ["`pythia` is installed but not on your PATH."]
     if scripts_dir:
         out.append("  It lives in: " + str(scripts_dir))
@@ -921,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.")
 
@@ -2055,11 +2137,13 @@ def cmd_install(conn, schema, ns):
             clean_legacy_skills(ns.project_root)
     print(f"\nNext: fill in {path}")
     print(f"Then: {invocation()} check")
-    hint = entry_point_hint(shutil.which("pythia"), installed_scripts_dir())
+    scripts_dir = installed_scripts_dir()
+    hint = entry_point_hint(shutil.which("pythia"), scripts_dir,
+                            in_stored_path=stored_path_has(scripts_dir))
     if hint:
         print()
         print(hint)
-        offer_path_fix(installed_scripts_dir(), interactive,
+        offer_path_fix(scripts_dir, interactive,
                        getattr(ns, "add_to_path", False))
 
 
@@ -2250,7 +2334,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.7 → pythia_plsql-0.4.9/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.7
+Version: 0.4.9
 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.7 → pythia_plsql-0.4.9}/tests/test_install.py

@@ -295,6 +295,36 @@ def test_add_to_user_path_handles_an_empty_and_untidy_value():
     assert written == [USERBIN + os.pathsep + SCRIPTS]   # no doubled separator
 
 
+def test_hint_tells_a_stale_shell_apart_from_an_unconfigured_one():
+    """The directory being in the stored PATH while the running process
+    cannot see it means one thing only: this terminal started earlier. Saying
+    "not on your PATH" there sends people to re-run an install that already
+    worked -- which is exactly what happened in the field."""
+    stale = pythia.entry_point_hint(found=None, scripts_dir=SCRIPTS,
+                                    in_stored_path=True)
+    assert "already" in stale.lower()
+    assert "new" in stale.lower() and "tab" in stale.lower()   # window, not tab
+    assert "--add-to-path" not in stale        # nothing to redo
+    unconfigured = pythia.entry_point_hint(found=None, scripts_dir=SCRIPTS,
+                                           in_stored_path=False)
+    assert SCRIPTS in unconfigured and "-m pythia" in unconfigured
+    # how you fix it is platform-specific: pythia can edit the registry on
+    # Windows, while a POSIX shell profile is the developer's to edit
+    assert ("--add-to-path" if os.name == "nt" else "profile") in unconfigured
+    # and once the command resolves, still silence
+    assert pythia.entry_point_hint(found="/x/pythia", scripts_dir=SCRIPTS,
+                                   in_stored_path=True) is None
+
+
+def test_long_path_is_flagged_before_it_silently_truncates():
+    """Windows tooling still truncates PATH near 2047 characters, and the
+    entry we just appended is the last one -- the first to be lost."""
+    assert pythia.path_length_warning("x" * 1000) is None
+    w = pythia.path_length_warning("x" * 2040)
+    assert w is not None and "2047" in w
+    assert "duplicate" in w.lower()      # names the usual cause
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.4.7 → pythia_plsql-0.4.9}/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()):