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

{pythia_plsql-0.4.9/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.9
+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.9 → pythia_plsql-0.4.10}/pyproject.toml

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

@@ -1332,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).
@@ -1790,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 = """\
@@ -2254,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")

{pythia_plsql-0.4.9 → 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.9
+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.9 → 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.9 → 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.9 → 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()):