pythia-plsql 0.3.4__tar.gz → 0.4.0__tar.gz

{pythia_plsql-0.3.4/scripts/pythia_plsql.egg-info → pythia_plsql-0.4.0}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.3.4"
+version = "0.4.0"
 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.4 → pythia_plsql-0.4.0}/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):
@@ -1351,6 +1476,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":
@@ -1370,14 +1537,17 @@ def cmd_journal(conn, schema, ns):
         import shutil
         removed = 0
         for eid in list_journal_entries(root):
-            if not read_journal_entry(root, eid)["meta"].get("applied"):
-                shutil.rmtree(journal_root(root) / eid)
-                removed += 1
+            meta = read_journal_entry(root, eid)["meta"]
+            if meta.get("applied") or meta.get("snapshot"):
+                continue      # applied = a real write; snapshot = the only
+                              # undo a hand-edit outside pythia will ever have
+            shutil.rmtree(journal_root(root) / eid)
+            removed += 1
         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} preview-only entries; applied "
+                  "entries and snapshots are all kept")
         return
     if not ns.id:
         sys.exit(f"Usage: {invocation()} journal "
@@ -1752,9 +1922,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 +2032,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.4 → pythia_plsql-0.4.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.3.4
+Version: 0.4.0
 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.4 → pythia_plsql-0.4.0}/skills/pythia-explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pythia-explore
-description: Use when you need to understand anything in an Oracle schema - finding objects, reading PL/SQL source, signatures, table columns, DDL, searching code, or asking who uses what. ALSO use when a .sql file, dump, export, migration script or repo copy of an object appears to answer the question already, including when the developer points you at one: those files drift from the database and are wrong in ways that read as correct. The database is the only source of truth.
+description: Use when you need to understand anything in an Oracle schema - finding objects, reading PL/SQL source, signatures, table columns, DDL, searching code, or asking who uses what. ALSO use when a .sql file, dump, export, migration script or repo copy of an object appears to answer the question already, including one the developer points you at - because those files drift from the database and are wrong in ways that read as correct. The database is the only source of truth.
 ---
 
 # Exploring the Schema

{pythia_plsql-0.3.4 → pythia_plsql-0.4.0}/tests/test_phase3.py

@@ -687,6 +687,81 @@ 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 test_prune_never_eats_a_snapshot():
+    import argparse
+    import contextlib
+    import io
+    import datetime
+    with tempfile.TemporaryDirectory() as td:
+        base = datetime.datetime(2026, 8, 27, 9, 0, 0)
+        pythia.write_journal_entry(td, "PROCEDURE", "P_A", "a", "b",
+                                   {"applied": False}, now=base)
+        snap = pythia.write_journal_entry(
+            td, "PROCEDURE", "P_B", "a", "a", {"snapshot": True,
+                                               "applied": False},
+            now=base.replace(minute=1))
+        ns = argparse.Namespace(action="prune", project_root=td, json=False,
+                                id=None)
+        with contextlib.redirect_stdout(io.StringIO()):
+            pythia.cmd_journal(None, None, ns)
+        assert pythia.list_journal_entries(td) == [snap]
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.3.4 → pythia_plsql-0.4.0}/tests/test_phase5.py

@@ -54,6 +54,33 @@ def test_frontmatter_is_valid_and_triggering():
         assert len(desc) <= 1024, f"{name}: description too long ({len(desc)})"
 
 
+def test_frontmatter_is_parseable_yaml():
+    """A description holding an unquoted ": " is not valid YAML, and the
+    agent harness then falls back to the H1 heading — the skill keeps its
+    name but loses its trigger, so it silently stops firing. This shipped
+    once; it does not ship twice. Checked without PyYAML: the suites run on
+    the stdlib alone.
+    """
+    for name in sorted(EXPECTED):
+        path = SKILLS / name / "SKILL.md"
+        if not path.is_file():
+            continue
+        m = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"),
+                     re.S)
+        assert m, f"{name}: no YAML frontmatter"
+        for line in m.group(1).splitlines():
+            km = re.match(r"^([A-Za-z_][\w.]*):\s+(.*)$", line)
+            if not km:
+                continue            # continuation or nested line
+            value = km.group(2)
+            if value[:1] in "\"'":
+                continue            # quoted: a colon inside is fine
+            assert ": " not in value, (
+                f"{name}: frontmatter '{km.group(1)}' holds an unquoted "
+                f"': ' — YAML reads that as a nested mapping and the field "
+                f"is lost. Rephrase or quote the value.")
+
+
 def test_skill_bodies_stay_within_budget():
     for name in sorted(EXPECTED):
         path = SKILLS / name / "SKILL.md"