mdb-cli 0.1.0__py3-none-any.whl

mdb/puller.py

@@ -0,0 +1,212 @@
+"""SQLite pull-phase operations: query execution and feed ingestion."""
+
+import hashlib
+import os
+import sqlite3
+
+from mdb.models import FeedResult, TapMarker, TapResult
+
+
+def execute_tap_query(db_path: str, query: str) -> TapResult:
+    """Execute a SELECT query against a SQLite database in read-only mode.
+
+    Opens the database via file: URI with mode=ro.
+    Returns TapResult with columns, rows, and success/error status.
+    Always closes the connection.
+    """
+    # Create a dummy marker for the result
+    marker = TapMarker(line_number=0, scope=db_path, raw_query=query)
+    conn = None
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        conn = sqlite3.connect(uri, uri=True)
+        cursor = conn.execute(query)
+        columns = [desc[0] for desc in cursor.description]
+        raw_rows = cursor.fetchall()
+        rows = [
+            [str(cell) if cell is not None else "" for cell in row]
+            for row in raw_rows
+        ]
+        return TapResult(
+            marker=marker,
+            success=True,
+            columns=columns,
+            rows=rows,
+        )
+    except Exception as e:
+        return TapResult(
+            marker=marker,
+            success=False,
+            error=str(e),
+        )
+    finally:
+        if conn:
+            conn.close()
+
+
+def compute_content_hash(
+    columns: list[str],
+    column_types: list[str],
+    rows: list[list[str]],
+) -> str:
+    """Compute a deterministic SHA-256 hash from column names, types, and row values.
+
+    Returns a 64-character lowercase hexadecimal string.
+    """
+    parts = []
+    # Column definitions: name:TYPE joined by \0
+    col_defs = "\0".join(f"{name}:{typ}" for name, typ in zip(columns, column_types))
+    parts.append(col_defs)
+    # Section separator
+    parts.append("\0\0")
+    # Row data: cells joined by \0, each row terminated by \n
+    for row in rows:
+        parts.append("\0".join(row))
+        parts.append("\n")
+    serialized = "".join(parts)
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def ingest_feed_table(db_path: str, table_name: str, columns: list[str], rows: list[list[str]], column_types: list[str] | None = None) -> FeedResult:
+    """Drop and recreate a table in the SQLite database, inserting all rows.
+
+    Creates the database file if it does not exist.
+    Wraps DROP + CREATE + INSERT in a single transaction.
+    When column_types is provided, uses specified types; otherwise defaults to TEXT.
+    """
+    try:
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        conn = sqlite3.connect(db_path)
+        try:
+            # Quote column names to handle spaces and reserved words
+            quoted_cols = [f'"{col}"' for col in columns]
+            types_for_hash = column_types if column_types is not None else ["TEXT"] * len(columns)
+            if column_types is not None:
+                col_defs = ", ".join(
+                    f'{qc} {ct}' for qc, ct in zip(quoted_cols, column_types)
+                )
+            else:
+                col_defs = ", ".join(f'{qc} TEXT' for qc in quoted_cols)
+            col_list = ", ".join(quoted_cols)
+            placeholders = ", ".join("?" for _ in columns)
+
+            conn.execute("BEGIN TRANSACTION")
+
+            # Ensure metadata table exists
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS _mdb_meta "
+                "(table_name TEXT PRIMARY KEY, content_hash TEXT NOT NULL)"
+            )
+
+            # Compute content hash
+            computed_hash = compute_content_hash(columns, types_for_hash, rows)
+
+            # Look up stored hash
+            cursor = conn.execute(
+                "SELECT content_hash FROM _mdb_meta WHERE table_name = ?",
+                (table_name,),
+            )
+            row_result = cursor.fetchone()
+
+            # Skip if hash matches
+            if row_result is not None and row_result[0] == computed_hash:
+                return FeedResult(
+                    task=None,
+                    success=True,
+                    skipped=True,
+                    rows_written=0,
+                )
+
+            # Hash mismatch or no stored hash: full write
+            conn.execute(f'DROP TABLE IF EXISTS "{table_name}"')
+            conn.execute(f'CREATE TABLE "{table_name}" ({col_defs})')
+
+            if rows:
+                conn.executemany(
+                    f'INSERT INTO "{table_name}" ({col_list}) VALUES ({placeholders})',
+                    rows,
+                )
+
+            # Store hash
+            conn.execute(
+                "INSERT OR REPLACE INTO _mdb_meta (table_name, content_hash) VALUES (?, ?)",
+                (table_name, computed_hash),
+            )
+
+            conn.commit()
+
+            return FeedResult(
+                task=None,
+                success=True,
+                rows_written=len(rows),
+            )
+        except Exception as e:
+            conn.rollback()
+            return FeedResult(
+                task=None,
+                success=False,
+                error=str(e),
+                rows_written=0,
+            )
+        finally:
+            conn.close()
+    except Exception as e:
+        return FeedResult(
+            task=None,
+            success=False,
+            error=str(e),
+            rows_written=0,
+        )
+
+
+def cleanup_stale_tables(db_path: str, discovered_tables: set[str]) -> list[str]:
+    """Remove orphaned tables and their metadata from a database.
+
+    Compares tracked tables in _mdb_meta against the set of table names
+    declared by markers in the known universe. Tables present in _mdb_meta
+    but not in discovered_tables are dropped and their metadata removed.
+
+    Returns sorted list of removed table names, or [] if no cleanup needed.
+    Never raises exceptions to caller.
+    """
+    if not os.path.exists(db_path):
+        return []
+
+    try:
+        conn = sqlite3.connect(db_path)
+        try:
+            # Check if _mdb_meta exists
+            cursor = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='_mdb_meta'"
+            )
+            if cursor.fetchone() is None:
+                return []
+
+            # Get tracked table names
+            cursor = conn.execute("SELECT table_name FROM _mdb_meta")
+            tracked = set(row[0] for row in cursor.fetchall())
+
+            # Compute orphans
+            orphaned = tracked - discovered_tables
+            if not orphaned:
+                return []
+
+            # Remove orphans in a single transaction
+            removed = sorted(orphaned)
+            conn.execute("BEGIN TRANSACTION")
+            for name in removed:
+                conn.execute(f'DROP TABLE IF EXISTS "{name}"')
+                conn.execute("DELETE FROM _mdb_meta WHERE table_name = ?", (name,))
+            conn.commit()
+
+            return removed
+        except Exception:
+            try:
+                conn.rollback()
+            except Exception:
+                pass
+            return []
+        finally:
+            conn.close()
+    except Exception:
+        return []

mdb/validators.py

@@ -0,0 +1,46 @@
+"""SQL query validators for mdb."""
+
+import re
+
+# Write keywords to reject (case-insensitive, word boundary match)
+_WRITE_KEYWORDS_RE = re.compile(
+    r'\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE)\b',
+    re.IGNORECASE,
+)
+
+
+def validate_dql(query: str) -> str | None:
+    """Validate that a SQL query contains only read-only (DQL) operations.
+
+    Returns None if valid (read-only), error message string if invalid.
+    """
+    match = _WRITE_KEYWORDS_RE.search(query)
+    if match:
+        keyword = match.group(1).upper()
+        return f"Query contains write operation: {keyword}"
+    return None
+
+
+def validate_dml(query: str) -> str | None:
+    """Validate that all statements in a query are DML.
+
+    Returns None if all statements are valid DML.
+    Error message string if any statement is invalid.
+    """
+    _DML_KEYWORDS = {"INSERT", "UPDATE", "DELETE"}
+    _SELECT_KEYWORDS = {"SELECT"}
+    _DDL_KEYWORDS = {"CREATE", "DROP", "ALTER"}
+
+    statements = query.split(";")
+    for stmt in statements:
+        stripped = stmt.strip()
+        if not stripped:
+            continue
+        first_word = stripped.split()[0].upper()
+        if first_word in _SELECT_KEYWORDS:
+            return "Only mutative queries (INSERT, UPDATE, DELETE) are permitted with push. For SELECT queries, use mdb pull."
+        if first_word in _DDL_KEYWORDS:
+            return "Only DML statements are permitted. DDL (CREATE, DROP, ALTER) is not supported."
+        if first_word not in _DML_KEYWORDS:
+            return f"Unrecognized statement keyword: {first_word}. Only INSERT, UPDATE, DELETE are permitted."
+    return None

mdb_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: mdb-cli
+Version: 0.1.0
+Summary: Markdown table workflows w/ SQLite powers ✨
+Project-URL: Homepage, https://atomanoid.github.io/mdb/
+Project-URL: Repository, https://github.com/atomanoid/mdb
+Project-URL: Documentation, https://atomanoid.github.io/mdb/
+Author: atomanoid
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <!-- <img src="https://raw.githubusercontent.com/atomanoid/mdb/main/docs/assets/floppy.svg" alt="floppy disk" width="128"> -->
+  <img src="https://raw.githubusercontent.com/gist/atomanoid/2e8135956d498969842907b1b149c72f/raw/f9d3aa40f4ebf7b347de617263ac1c7492bd6203/mdb-floppy.svg" alt="floppy disk" width="128">
+
+</p>
+
+<h1 align="center"><code>mdb-cli</code></h1>
+
+<h3 align="center">Markdown table workflows w/ SQLite powers ✨</h3>
+
+`mdb-cli` provides the `mdb` command-line tool to make markdown tables data-driven and queryable via SQL, using specialized co-located markers `💾 ...` with some embedded inline SQL queries to **define and dynamically view** our project-level data.
+
+- **Zero runtime dependencies** -- standard library only
+- **Simple integration** -- add markers and get running
+- **Python 3.11+** required
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/mdb-cli/):
+
+```bash
+# Using pipx (recommended)
+pipx install mdb-cli
+
+# Using uv (recommended)
+uv tool install mdb-cli
+
+# Using pip
+pip install mdb-cli
+```
+
+After installation, verify the tool is available:
+
+```bash
+mdb --help
+```
+
+For development installation, see [CONTRIBUTING.md](https://github.com/atomanoid/mdb/blob/main/CONTRIBUTING.md).
+
+## Basic Usage
+
+### Marker Syntax
+
+Place inline query markers above tables in your markdown file using the following format:
+
+```
+`💾 [scope] <directive> <sql-query>`
+```
+
+| Component     | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `💾`          | Marker prefix -- identifies the line as an `mdb` marker |
+| `[scope]`     | Optional named scope identifier of the dataset          |
+| `<directive>` | Directive: `🌀` (feed) or `💎` (tap)                    |
+| `<sql-query>` | SQL query to execute against the dataset                |
+
+## Directives
+
+| Directive | Name | Instruction                                                                                                       |
+| --------- | ---- | ----------------------------------------------------------------------------------------------------------------- |
+| `🌀`      | feed | Include the table below me as part of the dataset                                                                 |
+| `💎`      | tap  | Execute my SQL query on the dataset and render the results as the table below me (table auto-generated if absent) |
+
+> Under the hood, datasets are ingested into SQLite backing databases on which SQL queries are actually run.
+
+### Subcommands
+
+| Subcommand                | Behavior                                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `mdb pull <sql-query>`    | process all `🌀` markers first (pulls), then outputs SQL query results in CSV format                        |
+| `mdb push`                | process all `🌀` markers first (pulls), then all `💎` markers after (pushes)                                |
+| `mdb push <sql-mutation>` | process all `🌀` markers first (pulls), execute the mutation, then all `🌀` and `💎` markers after (pushes) |
+
+### Example
+
+Given a project file `snacks.md` with the following content:
+
+```markdown
+# Snacks
+
+## Inventory
+
+`💾 🌀 SELECT * FROM snacks`
+
+| name               | vibe               | qty |
+| ------------------ | ------------------ | --- |
+| Hot Cheese Popcorn | chaos energy       | 3   |
+| Pocky              | elegant simplicity | 12  |
+| Takis              | rolled-up danger   | 7   |
+| Goldfish           | the people's snack | 41  |
+
+## Low stock
+
+`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`
+```
+
+After running:
+
+```bash
+mdb push
+```
+
+We'll have the `snacks.md` updated to the following content:
+
+```markdown
+# Snacks
+
+## Inventory
+
+`💾 🌀 SELECT * FROM snacks`
+
+| name               | vibe               | qty |
+| ------------------ | ------------------ | --- |
+| Hot Cheese Popcorn | chaos energy       | 3   |
+| Pocky              | elegant simplicity | 12  |
+| Takis              | rolled-up danger   | 7   |
+| Goldfish           | the people's snack | 41  |
+
+## Low stock
+
+`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`
+
+| name               | qty |
+| ------------------ | --- |
+| Hot Cheese Popcorn | 3   |
+| Takis              | 7   |
+```
+
+The 🌀 (feed) marker ingests the snacks data into the (unscoped) dataset, then the 💎 (tap) marker executes the query and surfaces only the snacks running low in stock.
+
+---
+
+Additionally, after running:
+
+```bash
+mdb pull "SELECT SUM(qty) as total_snacks FROM snacks"
+```
+
+We'll get the output:
+
+```
+total_snacks
+63
+```
+
+The 🌀 (feed) marker again ingests the snacks data into the dataset, but the 💎 (tap) marker is not processed.
+
+---
+
+We can also mutate data directly. Running:
+
+```bash
+mdb push "UPDATE snacks SET qty = qty + 20 WHERE name = 'Takis'"
+```
+
+The 🌀 (feed) marker again ingests the snacks data into the dataset, applies the UPDATE, then both 🌀 (feed) and 💎 (tap) markers push fresh results back:
+
+```markdown
+## Inventory
+
+`💾 🌀 SELECT * FROM snacks`
+
+| name               | vibe               | qty |
+| ------------------ | ------------------ | --- |
+| Hot Cheese Popcorn | chaos energy       | 3   |
+| Pocky              | elegant simplicity | 12  |
+| Takis              | rolled-up danger   | 27  |
+| Goldfish           | the people's snack | 41  |
+
+## Low stock
+
+`💾 💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty`
+
+| name               | qty |
+| ------------------ | --- |
+| Hot Cheese Popcorn | 3   |
+```
+
+Takis got restocked to 27 and dropped off the low-stock list — all from a single command.
+
+## Agent Support
+
+`mdb-cli` includes a built-in agent skill. Install it:
+
+```
+mdb init                          # default: .mdb/skills/mdb/SKILL.md
+mdb init .claude/skills           # Claude Code: .claude/skills/mdb/SKILL.md
+mdb init .opencode/skills         # OpenCode: .opencode/skills/mdb/SKILL.md
+mdb init path/to/agent/skills     # any agent: path/to/agent/skills/mdb/SKILL.md
+```
+
+Within a session, invoke the `/mdb` slash command to access a comprehensive reference covering marker syntax, subcommand workflows, templates for common operations, and an error reference guide. The skill provides everything an AI coding assistant needs to construct and debug mdb markers without leaving the editor.

mdb_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+mdb/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdb/atomic.py,sha256=xnmxwGPWdFGZQIMLZ9uuOS6tZCZb6YayaVLj1dzCcqo,719
+mdb/discovery.py,sha256=Y7sD9Xvcga6RGsOKhptLOjM2Gsb3vRPVbWXD2LYvKhw,2139
+mdb/filelock.py,sha256=Lp4WYbA6Vt_-7SUffSAXhNGeuALDCXMQPkAeiVpEpYQ,2159
+mdb/formatter.py,sha256=pWpllujgZQy4JAkjbLP7EJJtVl2c9cKlye6lJEJc-70,3486
+mdb/init.py,sha256=CqeF8pqjmZ363sgU6Cymmmd6jMqkb8mnpHzZuirQYiw,5352
+mdb/mdb.py,sha256=Zd_W64ZP3FVHD0SIYMw0SkIRu5zFrNKeKx73QMzgsGU,46314
+mdb/models.py,sha256=TBPVvA5IcWLWriX5klQdgaLlIZgZR2K1Jhc2qcOtKoo,1871
+mdb/parser.py,sha256=jgwIYTCoBgDAkeBxLj7UyTm75U1K5aNzuULU71U90gI,21661
+mdb/puller.py,sha256=AiW0vjl5Mm4YRGNhPZbD24M4IjikJQO1-48r_ZnJ9Ds,7058
+mdb/validators.py,sha256=quvEieq1_LGbFzV4K4zxLrLLgEFeYLTHqDEwHHUF6dU,1619
+mdb/data/SKILL.md,sha256=0R5afekElV7QDdS9AETKqjz1MzVzNkbFJ3sDKM8DsUA,4776
+mdb/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdb_cli-0.1.0.dist-info/METADATA,sha256=Q6M7nrayK9j0aX1bPP9SJcOffUFv5-6SaPCLn69lOrk,7657
+mdb_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mdb_cli-0.1.0.dist-info/entry_points.txt,sha256=jpkNA_RSyT0mb_bbnqohVCrcm_ymAkFMRA6q2YqTkbA,37
+mdb_cli-0.1.0.dist-info/licenses/LICENSE,sha256=0tfi6n8q7wQbUQ47en8pj6Kq4SLQwZ5qfNRbTg-mUyo,1077
+mdb_cli-0.1.0.dist-info/RECORD,,

mdb_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdb_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mdb = mdb.mdb:main

mdb_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdb-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.