pythia-plsql 0.3.5__tar.gz → 0.4.1__tar.gz

{pythia_plsql-0.3.5/scripts/pythia_plsql.egg-info → pythia_plsql-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.3.5
+Version: 0.4.1
 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
@@ -115,13 +115,19 @@ and WSL are all CI-tested.
 | `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
 | `args` signatures | `invalid` everything broken | `unistr` exact non-ASCII literals |
 | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `agent-user` least-privilege setup |
-| `cols` columns + types | `similar` programs named like this | |
+| `cols` columns + types | `similar` programs named like this | `history` every captured version |
 | `grep` search all source | | |
 | `sql` free query (SELECT/WITH only) | | |
 
 Every command takes `--json` (machine output), `--conn` (pick a connection), and
 caps output with explicit truncation markers so context windows stay intact.
 
+**The safety net covers hand edits too**: `src` and `impact` snapshot the
+object silently into the journal, each with a runnable rollback file, so a
+change made later in SQL Developer still has something to go back to —
+`pythia history <OBJECT>` lists the versions. Source that moved with no
+apply behind it is reported as drift.
+
 **Your house style is config, not folklore**: put naming patterns in
 `.pythia/conventions.json` and apply previews warn when a new object's name
 drifts; put the prose rules in `.pythia/conventions.md` and the skills make

{pythia_plsql-0.3.5 → pythia_plsql-0.4.1}/README.md

@@ -101,13 +101,19 @@ and WSL are all CI-tested.
 | `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
 | `args` signatures | `invalid` everything broken | `unistr` exact non-ASCII literals |
 | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `agent-user` least-privilege setup |
-| `cols` columns + types | `similar` programs named like this | |
+| `cols` columns + types | `similar` programs named like this | `history` every captured version |
 | `grep` search all source | | |
 | `sql` free query (SELECT/WITH only) | | |
 
 Every command takes `--json` (machine output), `--conn` (pick a connection), and
 caps output with explicit truncation markers so context windows stay intact.
 
+**The safety net covers hand edits too**: `src` and `impact` snapshot the
+object silently into the journal, each with a runnable rollback file, so a
+change made later in SQL Developer still has something to go back to —
+`pythia history <OBJECT>` lists the versions. Source that moved with no
+apply behind it is reported as drift.
+
 **Your house style is config, not folklore**: put naming patterns in
 `.pythia/conventions.json` and apply previews warn when a new object's name
 drifts; put the prose rules in `.pythia/conventions.md` and the skills make

{pythia_plsql-0.3.5 → pythia_plsql-0.4.1}/pyproject.toml

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

@@ -42,6 +42,7 @@ you always know whether you saw everything.
   pythia journal restore <id>
   pythia policy
   pythia install
+  pythia history MY_PACKAGE
   pythia unistr "Nhóm không được để trống"
   pythia agent-user --save
 """
@@ -631,6 +632,84 @@ def load_settings(root):
         sys.exit(f"Cannot parse {path}: {e}")
 
 
+def source_sha(text):
+    import hashlib
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+
+
+def fetch_source(conn, schema, name):
+    """Current source of an object, as ALL_SOURCE holds it. ('', None) when
+    the name is not a source object (a table, say)."""
+    _, rows = run_query(conn, load_query("source.sql"), {"s": schema, "n": name})
+    if not rows:
+        return "", None
+    return "".join(cell(r[2]) for r in rows), rows[0][0]
+
+
+def last_known_state(root, name):
+    """What the database held, as far as the journal knows: the newest entry
+    for this object, and the source that entry says was really there.
+    A preview wrote nothing, so its `before` is the real state."""
+    for eid in list_journal_entries(root):        # newest first
+        e = read_journal_entry(root, eid)
+        m = e["meta"]
+        if str(m.get("object", "")).upper() != name.upper():
+            continue
+        real = e["after"] if (m.get("applied") or m.get("snapshot")) else e["before"]
+        return real, eid, m
+    return None, None, None
+
+
+def auto_snapshot(conn, schema, name, ns):
+    """Capture an object's source the moment an agent focuses on it, so a
+    later hand-edit outside pythia still has something to go back to.
+
+    Silent by design: writing to the journal costs the agent no context, and
+    a line of "snapshot taken" on every read would cost it on every read.
+    The one thing worth saying is drift — the source moved without an apply
+    of ours explaining it — and that goes to stderr, so --json stays clean.
+
+    Returns a drift warning, or None.
+    """
+    root = getattr(ns, "project_root", None)
+    if root is None or not load_settings(root).get("auto_snapshot", True):
+        return None
+    try:
+        text, otype = fetch_source(conn, schema, name)
+        if not text.strip():
+            return None                    # not a source object; nothing to keep
+        known, eid, meta = last_known_state(root, name)
+        if known is not None and source_sha(known) == source_sha(text):
+            return None                    # unchanged — no entry, no output
+        write_journal_entry(root, otype or "OBJECT", name.upper(), text, text,
+                            {"schema": schema, "connection": ns.conn_name,
+                             "snapshot": True, "applied": False,
+                             "sha": source_sha(text)})
+        if known is None:
+            return None                    # first sighting is a baseline
+        rollback = journal_root(root) / eid / "restore.sql"
+        return (f"! {name.upper()} changed outside pythia since {eid}.\n"
+                f"  Rollback file for the previous version: {rollback}\n"
+                f"  All versions: {invocation()} history {name.upper()}")
+    except Exception:                      # noqa: BLE001
+        return None                        # a safety net must never break a read
+
+
+def report_drift(msg):
+    if msg:
+        print(paint(msg, "yellow", color_enabled(sys.stderr)), file=sys.stderr)
+
+
+def journaled_objects(root):
+    names = {}
+    for eid in list_journal_entries(root):        # newest first
+        m = read_journal_entry(root, eid)["meta"]
+        n = str(m.get("object", "")).upper()
+        if n and n != "STATEMENT" and n not in names:
+            names[n] = eid[:19]                   # the entry's timestamp
+    return names
+
+
 def undo_group_action(ns):
     """Undoing a CREATE is a DROP, which is `structural` — so the policy on
     that group decides whether the restore command we print can run."""
@@ -827,6 +906,43 @@ def cmd_check(conn, schema, ns):
     if warn:
         print("\n" + paint(warn, "yellow", color_enabled(sys.stderr)),
               file=sys.stderr)
+    report_drift(drift_summary(conn, schema, ns))
+
+
+def drift_summary(conn, schema, ns):
+    """One line, only when objects pythia knows have moved since it last saw
+    them. Uses LAST_DDL_TIME — a single query for every journaled object,
+    instead of re-reading every source.
+    ponytail: LAST_DDL_TIME also ticks on a bare recompile, so this is a
+    'go look' signal; `history` and the src/impact hash comparison are the
+    precise ones."""
+    root = getattr(ns, "project_root", None)
+    if root is None:
+        return None
+    try:
+        known = journaled_objects(root)
+        if not known:
+            return None
+        names = sorted(known)[:200]        # one query, bounded
+        binds = {"s": schema}
+        placeholders = []
+        for i, n in enumerate(names):
+            binds[f"n{i}"] = n
+            placeholders.append(f":n{i}")
+        _, rows = run_query(
+            conn, "select object_name, to_char(last_ddl_time,"
+            "'yyyy-mm-dd\"T\"hh24-mi-ss') from all_objects "
+            f"where owner = :s and object_name in ({','.join(placeholders)})",
+            binds)
+        moved = [r[0] for r in rows if str(r[1]) > known.get(str(r[0]), "")]
+        if not moved:
+            return None
+        shown = ", ".join(moved[:3]) + ("…" if len(moved) > 3 else "")
+        return (f"! {len(moved)} object(s) changed since pythia last saw them: "
+                f"{shown}\n  Versions and restores: {invocation()} history "
+                f"<NAME>")
+    except Exception:                      # noqa: BLE001
+        return None
 
 
 def cmd_ls(conn, schema, ns):
@@ -846,8 +962,10 @@ def cmd_src(conn, schema, ns):
     if not rows:
         sys.exit(f"No source found for {ns.name!r} in schema {schema}.")
     total = len(rows)
+    drift = auto_snapshot(conn, schema, ns.name, ns)
     shown, truncated = clip(rows, ns.max_lines, ns.offset)
     emit_source(ns, shown, truncated, total)
+    report_drift(drift)
 
 
 def cmd_args(conn, schema, ns):
@@ -955,19 +1073,26 @@ def cmd_deps(conn, schema, ns):
 def cmd_impact(conn, schema, ns):
     cols, rows = run_query(conn, load_query("impact.sql"),
                            {"s": schema, "n": ns.name, "depth": ns.depth})
+    # impact is mandatory before any change, so it is the surest "about to
+    # touch this" signal there is — the best possible place to capture a
+    # before-state the developer never had to ask for
+    drift = auto_snapshot(conn, schema, ns.name, ns)
     shown, truncated = clip(rows, ns.limit)
     if ns.json:
         print(json_envelope(ns.command, ns.conn_name, ns.schema, cols, shown, truncated,
                             summary=impact_summary(rows)))
+        report_drift(drift)
         return
     if not rows:
         print(f"-- nothing depends on {ns.name.upper()} "
               f"(within {schema}, depth {ns.depth})")
+        report_drift(drift)
         return
     sys.stdout.write(render_tree(shown, f"{schema}.{ns.name.upper()}"))
     if truncated:
         print(f"-- truncated at {len(shown)} rows (raise --limit, or --limit 0 for no cap)")
     print(impact_summary(rows))
+    report_drift(drift)
 
 
 def cmd_similar(conn, schema, ns):
@@ -1212,6 +1337,11 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                 print(f"  {paint_diff_line(ln, en)}")
         print(paint(f"\n  Snapshot saved: {journal_root(ns.project_root) / entry}",
                     "dim", en))
+        if not confirmed:
+            print(paint("  Rollback file for the current database version — "
+                        "use it if this is\n  run by hand instead: "
+                        f"{journal_root(ns.project_root) / entry / 'restore.sql'}",
+                        "dim", en))
         if not confirmed:
             print(f"\n  To apply:\n    "
                   + paint(f"{invocation()} apply {ns.file} --confirm {token}",
@@ -1351,6 +1481,48 @@ def cmd_policy(conn, schema, ns):
     print(ROLLBACK_TABLE)
 
 
+def cmd_history(conn, schema, ns):
+    """Every version of one object the journal holds, newest first. Compact
+    on purpose — an agent reads this to choose an id, not to read source."""
+    root = ns.project_root
+    name = ns.name.upper()
+    rows = []
+    for eid in list_journal_entries(root):
+        e = read_journal_entry(root, eid)
+        m = e["meta"]
+        if str(m.get("object", "")).upper() != name:
+            continue
+        real = e["after"] if (m.get("applied") or m.get("snapshot")) else e["before"]
+        kind = ("applied" if m.get("applied") else
+                "snapshot" if m.get("snapshot") else "preview")
+        rows.append({"entry": eid, "kind": kind,
+                     "lines": len(real.splitlines()),
+                     "sha": source_sha(real),
+                     "rollback_file": str(journal_root(root) / eid
+                                          / "restore.sql")})
+    if ns.json:
+        print(json.dumps({"object": name, "versions": rows}))
+        return
+    if not rows:
+        print(f"-- no journal history for {name}. It is captured the first "
+              f"time you run `{invocation()} src {name}` or "
+              f"`{invocation()} impact {name}`.")
+        return
+    prev = None
+    for r in rows:                       # newest first; compare to the older one
+        older = rows[rows.index(r) + 1] if rows.index(r) + 1 < len(rows) else None
+        delta = ""
+        if older and older["sha"] != r["sha"]:
+            n = r["lines"] - older["lines"]
+            delta = f"  {n:+d} lines" if n else "  content changed"
+        print(f"  {r['entry']:<44} {r['kind']:<9} {r['lines']:>5} lines{delta}")
+        prev = r
+    print(f"\n-- every version above has a ready-to-run rollback file:")
+    print(f"     {journal_root(root)}\\<entry>\\restore.sql")
+    print(f"-- through pythia (previews first, you approve):")
+    print(f"     {invocation()} journal restore <entry>")
+
+
 def cmd_journal(conn, schema, ns):
     root = ns.project_root
     if ns.action == "list":
@@ -1369,15 +1541,29 @@ def cmd_journal(conn, schema, ns):
     if ns.action == "prune":
         import shutil
         removed = 0
-        for eid in list_journal_entries(root):
-            if not read_journal_entry(root, eid)["meta"].get("applied"):
+        # A preview wrote nothing to the database, but its restore.sql holds
+        # the version that was live at the time — the only rollback there is
+        # for a change the developer then ran by hand. So drop a preview only
+        # when its rollback is byte-identical to one a newer entry already
+        # keeps: redundant captures go, unique ones never do.
+        kept = {}
+        for eid in list_journal_entries(root):        # newest first
+            e = read_journal_entry(root, eid)
+            meta, obj = e["meta"], str(e["meta"].get("object", ""))
+            if meta.get("applied") or meta.get("snapshot"):
+                kept.setdefault(obj, set()).add(e["restore"])
+                continue
+            if e["restore"] in kept.get(obj, set()):
                 shutil.rmtree(journal_root(root) / eid)
                 removed += 1
+            else:
+                kept.setdefault(obj, set()).add(e["restore"])
         if ns.json:
             print(json.dumps({"pruned": removed}))
         else:
-            print(f"-- pruned {removed} preview-only entries; applied entries "
-                  "(the real snapshots) are all kept")
+            print(f"-- pruned {removed} redundant previews; applied entries, "
+                  "snapshots, and any preview holding a rollback nothing "
+                  "else has are all kept")
         return
     if not ns.id:
         sys.exit(f"Usage: {invocation()} journal "
@@ -1752,9 +1938,11 @@ COMMANDS = {"check": cmd_check, "ls": cmd_ls, "src": cmd_src, "args": cmd_args,
             "impact": cmd_impact, "similar": cmd_similar, "plscope": cmd_plscope,
             "policy": cmd_policy, "journal": cmd_journal, "apply": cmd_apply,
             "conventions": cmd_conventions, "install": cmd_install,
-            "unistr": cmd_unistr, "agent-user": cmd_agent_user}
+            "unistr": cmd_unistr, "agent-user": cmd_agent_user,
+            "history": cmd_history}
 
-NO_DB_COMMANDS = {"policy", "journal", "conventions", "install", "unistr"}
+NO_DB_COMMANDS = {"policy", "journal", "conventions", "install", "unistr",
+                  "history"}
 
 
 # --- CLI ---------------------------------------------------------------------
@@ -1860,6 +2048,10 @@ def build_parser():
     s.add_argument("--save", action="store_true",
                    help="add the new credential as <conn>_agent and make it "
                         "the default connection")
+    s = sub.add_parser("history", parents=[common()],
+                       help="every captured version of one object, newest "
+                            "first — pick one to restore")
+    s.add_argument("name")
     s = sub.add_parser("unistr", parents=[common()],
                        help="Oracle unistr('...') literal for non-ASCII text "
                             "(Vietnamese messages stay exact)")

{pythia_plsql-0.3.5 → pythia_plsql-0.4.1/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.3.5
+Version: 0.4.1
 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
@@ -115,13 +115,19 @@ and WSL are all CI-tested.
 | `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
 | `args` signatures | `invalid` everything broken | `unistr` exact non-ASCII literals |
 | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `agent-user` least-privilege setup |
-| `cols` columns + types | `similar` programs named like this | |
+| `cols` columns + types | `similar` programs named like this | `history` every captured version |
 | `grep` search all source | | |
 | `sql` free query (SELECT/WITH only) | | |
 
 Every command takes `--json` (machine output), `--conn` (pick a connection), and
 caps output with explicit truncation markers so context windows stay intact.
 
+**The safety net covers hand edits too**: `src` and `impact` snapshot the
+object silently into the journal, each with a runnable rollback file, so a
+change made later in SQL Developer still has something to go back to —
+`pythia history <OBJECT>` lists the versions. Source that moved with no
+apply behind it is reported as drift.
+
 **Your house style is config, not folklore**: put naming patterns in
 `.pythia/conventions.json` and apply previews warn when a new object's name
 drifts; put the prose rules in `.pythia/conventions.md` and the skills make

{pythia_plsql-0.3.5 → pythia_plsql-0.4.1}/skills/pythia-apply/SKILL.md

@@ -31,6 +31,21 @@ Three moves are FORBIDDEN for agents, and the CLI enforces the first two
   your turn; the token is only used after the developer's approval
   arrives as a NEW message.
 
+## When the change will NOT go through apply
+
+Sometimes the developer runs the file themselves — a DBA executes it, a
+release process owns it, or policy denies the group. The preview still ran,
+so a rollback file for the version currently live already exists. Hand it
+over in the same message as the .sql file, by path:
+
+```
+.pythia/journal/<entry>/restore.sql
+```
+
+Never let a change leave your hands for manual execution without naming
+that file. `pythia history <OBJECT>` lists every captured version if an
+older one is wanted.
+
 ## The Workflow
 
 **Before step 1:** if this conversation has not yet seen a standalone impact

{pythia_plsql-0.3.5 → pythia_plsql-0.4.1}/tests/test_phase3.py

@@ -540,25 +540,42 @@ def test_privilege_warning_speaks_proxy():
         FakeConn(direct), "APP", "APP")
 
 
-def test_journal_prune_keeps_applied_entries():
+def test_prune_drops_only_redundant_previews():
+    """A preview wrote nothing, but its restore.sql is the live version at
+    that moment — the only rollback for a change run by hand. Prune may drop
+    it only when a newer entry already keeps the identical rollback."""
     import argparse
+    import contextlib
     import datetime
+    import io
     with tempfile.TemporaryDirectory() as td:
-        base = datetime.datetime(2026, 8, 26, 12, 0, 0)
-        pythia.write_journal_entry(td, "PROCEDURE", "P_PREVIEW", "a", "b",
+        base = datetime.datetime(2026, 8, 27, 9, 0, 0)
+        # two previews of the same object, same live version -> one is spare
+        pythia.write_journal_entry(td, "PROCEDURE", "P_A", "old", "new1",
                                    {"applied": False}, now=base)
-        kept = pythia.write_journal_entry(
-            td, "PROCEDURE", "P_APPLIED", "a", "b", {"applied": True},
+        keep_dup = pythia.write_journal_entry(
+            td, "PROCEDURE", "P_A", "old", "new2", {"applied": False},
             now=base.replace(minute=1))
+        # a preview of another object, unique rollback -> must survive
+        lone = pythia.write_journal_entry(
+            td, "PROCEDURE", "P_B", "only_copy", "x", {"applied": False},
+            now=base.replace(minute=2))
+        applied = pythia.write_journal_entry(
+            td, "PROCEDURE", "P_C", "a", "b", {"applied": True},
+            now=base.replace(minute=3))
+        snap = pythia.write_journal_entry(
+            td, "PROCEDURE", "P_D", "a", "a",
+            {"snapshot": True, "applied": False}, now=base.replace(minute=4))
         ns = argparse.Namespace(action="prune", project_root=td, json=False,
                                 id=None)
-        import contextlib
-        import io
         buf = io.StringIO()
         with contextlib.redirect_stdout(buf):
             pythia.cmd_journal(None, None, ns)
-        assert "pruned 1" in buf.getvalue()
-        assert pythia.list_journal_entries(td) == [kept]
+        left = pythia.list_journal_entries(td)
+        assert "pruned 1" in buf.getvalue(), buf.getvalue()
+        assert applied in left and snap in left      # never touched
+        assert lone in left                          # unique rollback survives
+        assert keep_dup in left                      # newest of the pair kept
 
 
 def test_agent_user_alter_form_and_warning_prediction():
@@ -687,6 +704,61 @@ def test_report_admits_a_created_objects_undo_is_blocked():
         assert "will be refused" not in buf.getvalue().lower()
 
 
+def test_auto_snapshot_captures_silently_and_writes_a_rollback_file():
+    """Every captured version leaves a runnable rollback file — that is the
+    whole point for work done by hand, outside pythia. And capturing costs
+    the agent no context: nothing is printed when nothing moved."""
+    import argparse
+    import contextlib
+    import io
+    src = "PROCEDURE P_X AS\nBEGIN\n  NULL;\nEND;\n"
+    script = {"from all_source": ([("TYPE", "LINE", "TEXT")],
+                                  [("PROCEDURE", i + 1, ln + "\n")
+                                   for i, ln in enumerate(src.splitlines())])}
+    with tempfile.TemporaryDirectory() as td:
+        ns = argparse.Namespace(project_root=td, conn_name="DEV")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            drift = pythia.auto_snapshot(FakeConn(script), "APP", "P_X", ns)
+        assert drift is None                      # first sighting: a baseline
+        assert buf.getvalue() == ""               # and not one token of output
+        ids = pythia.list_journal_entries(td)
+        assert len(ids) == 1
+        e = pythia.read_journal_entry(td, ids[0])
+        assert e["meta"]["snapshot"] is True
+        rollback = e["restore"]
+        assert rollback.startswith("CREATE OR REPLACE PROCEDURE P_X")
+        assert (pythia.journal_root(td) / ids[0] / "restore.sql").is_file()
+
+        # reading it again unchanged must not create a second entry
+        assert pythia.auto_snapshot(FakeConn(script), "APP", "P_X", ns) is None
+        assert pythia.list_journal_entries(td) == ids
+
+
+def test_auto_snapshot_reports_drift_and_keeps_the_old_rollback():
+    """Source moved with no apply of ours behind it — say so once, and point
+    at the rollback file for the version that was there before."""
+    import argparse
+    old_src = "PROCEDURE P_X AS\nBEGIN\n  NULL;\nEND;\n"
+    new_src = "PROCEDURE P_X AS\nBEGIN\n  other_thing;\nEND;\n"
+
+    def script(text):
+        return {"from all_source": ([("TYPE", "LINE", "TEXT")],
+                                    [("PROCEDURE", i + 1, ln + "\n")
+                                     for i, ln in enumerate(text.splitlines())])}
+    with tempfile.TemporaryDirectory() as td:
+        ns = argparse.Namespace(project_root=td, conn_name="DEV")
+        pythia.auto_snapshot(FakeConn(script(old_src)), "APP", "P_X", ns)
+        first = pythia.list_journal_entries(td)[0]
+        drift = pythia.auto_snapshot(FakeConn(script(new_src)), "APP", "P_X", ns)
+        assert drift and "changed outside pythia" in drift
+        assert "restore.sql" in drift
+        # the older version's rollback is still on disk and still runnable
+        old_rollback = pythia.read_journal_entry(td, first)["restore"]
+        assert "NULL;" in old_rollback
+        assert len(pythia.list_journal_entries(td)) == 2
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):