mdb-cli 0.1.0__py3-none-any.whl

mdb/atomic.py

@@ -0,0 +1,25 @@
+"""Atomic file write via temp-file-then-rename."""
+
+import os
+import tempfile
+
+
+def atomic_write(filepath: str, content: str) -> None:
+    """Write content to filepath atomically.
+
+    Creates a temporary file in the same directory, writes content,
+    then atomically replaces the target via os.replace().
+    On failure, cleans up the temp file and re-raises.
+    """
+    dir_ = os.path.dirname(filepath) or "."
+    fd, tmp = tempfile.mkstemp(dir=dir_, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp, filepath)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

mdb/data/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: mdb
+description: Use mdb to query, mutate, and sync markdown table data via SQL. Invoke when working with markdown files containing mdb markers, or when the user asks to add, query, update, or report on tabular data in markdown.
+user-invocable: true
+---
+
+# mdb Reference
+
+`mdb` makes markdown tables data-driven and queryable via SQL, using specialized co-located markers `💾 ...` with some embedded inline SQL queries to define and dynamically view project-level data. Under the hood, datasets are ingested into SQLite backing databases on which SQL queries are actually run.
+
+Interpret `$ARGUMENTS` as the user's intent and perform the appropriate mdb operation. If no arguments, show: `mdb push | mdb pull "<query>" | mdb --help`
+
+## Marker Syntax
+
+Markers are backtick-delimited code spans on their own line:
+
+```
+`💾 [scope] <directive> <sql-query>`
+```
+
+- **scope** (optional): Named scope resolving to `.mdb/<md5(scope)>.db`. Omit for implicit scope `.mdb/_.db`.
+- **🌀** (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).
+
+For 🌀 markers, a table **must** be present after the marker -- it defines the column schema (source of truth). For 💎 markers, the table is optional -- if absent, `mdb push` auto-generates one from query results. Column types default to TEXT; annotate with `:type` suffix (e.g. `id:integer`, `salary:real`). Valid types: TEXT, INTEGER, REAL, NUMERIC, BLOB.
+
+## Commands
+
+### `mdb push [query]`
+
+Process all 🌀 markers first (pulls), then all 💎 markers after (pushes). With a DML query, mutates data between pull and push phases.
+
+```bash
+mdb push                          # standard pull-then-push
+mdb push "INSERT INTO t VALUES (1, 'x')"           # mutate implicit scope
+mdb push "mydb 🌀 DELETE FROM t WHERE id = 1"      # mutate named scope
+mdb push -i "docs/" "UPDATE t SET x = 1"            # restrict to directory
+```
+
+Push-query rules: only DML (INSERT/UPDATE/DELETE); SELECT and DDL rejected. Multi-statement queries run in a single transaction.
+
+### `mdb pull "<query>"`
+
+Process all 🌀 markers first (pulls), then outputs SQL query results in CSV format.
+
+```bash
+mdb pull "SELECT avg(salary) FROM employees"              # implicit scope
+mdb pull "company 💎 SELECT avg(salary) FROM employees"   # named scope
+mdb pull -i "docs/" "SELECT * FROM t"                      # restrict to directory
+```
+
+Pull rules: only SELECT permitted; DML rejected.
+
+### Common flags
+
+`-i "path1/ path2/"` — restrict markdown file discovery to specific directories (default: recurse from CWD).
+
+## Key Behaviors
+
+- 🌀 markers across all files execute first (pull phase), then 💎 markers (push phase)
+- Cross-file write conflict: two 🌀 markers in **different files** targeting the same table → error. Same file → last wins.
+- Push-query mutations update both 🌀 source tables and 💎 derived tables
+- Database must already exist for 💎 markers (created by 🌀 pull)
+
+## Example: Mixed Marker File
+
+```markdown
+# Employees
+
+`💾 company 🌀 SELECT * FROM employees`
+
+| id:integer | name  | department  | salary:real |
+| ---------- | ----- | ----------- | ----------- |
+| 1          | Alice | Engineering | 95000       |
+| 2          | Bob   | Marketing   | 78000       |
+
+## Engineering Report
+
+`💾 company 💎 SELECT name, salary FROM employees WHERE department = 'Engineering'`
+```
+
+`mdb push` pulls seed data, then auto-generates the report table from query results.
+
+## Error Quick Reference
+
+| Error                     | Fix                                                                               |
+| ------------------------- | --------------------------------------------------------------------------------- |
+| Database not found        | 💎 needs an existing DB — run a 🌀 pull first, or check scope name                |
+| Write conflict            | Two 🌀 markers in different files write same table — consolidate to one file      |
+| No table below 🌀 marker  | Add markdown table with column headers after the 🌀 marker (required for pull)    |
+| No data sources found     | No 🌀 markers match the scope — check scope name or use `-i`                      |
+| Only SELECT/DML permitted | pull accepts SELECT only; push accepts DML only                                   |
+| Invalid column type       | Use TEXT, INTEGER, REAL, NUMERIC, or BLOB                                         |
+| Database is locked        | Another mdb process holds the lock — wait and retry, or check for stuck processes |
+| mdb: command not found    | Run `pipx install mdb-cli` or equivalent from the repo root                       |

mdb/discovery.py

@@ -0,0 +1,70 @@
+"""Path resolution and file discovery for mdb CLI.
+
+Pure-function module for resolving CLI glob patterns into a deduplicated,
+sorted list of markdown file paths. This module has no knowledge of markers,
+databases, or processing logic -- it operates purely on filesystem paths.
+"""
+
+import glob
+import os
+import os.path
+import pathlib
+import sys
+
+
+def _has_hidden_segment(path: str) -> bool:
+    """Check if any component of a path is a hidden directory (starts with '.').
+
+    Args:
+        path: File path string (relative or absolute).
+
+    Returns:
+        True if any path component starts with '.' (excluding '.' itself).
+    """
+    parts = pathlib.PurePosixPath(path).parts
+    return any(p.startswith(".") and p != "." for p in parts)
+
+
+def resolve_paths(patterns: list[str]) -> tuple[list[str], list[str]]:
+    """Resolve a list of glob patterns into deduplicated, sorted markdown file paths.
+
+    Args:
+        patterns: List of glob pattern strings (e.g., ["**"], ["docs/*"]).
+
+    Returns:
+        Tuple of (files, warnings):
+            files: Deduplicated, sorted list of resolved absolute .md file paths.
+            warnings: List of warning messages (e.g., patterns matching zero files).
+    """
+    file_set: set[str] = set()
+    warnings: list[str] = []
+
+    for pattern in patterns:
+        expanded = glob.glob(pattern, recursive=True)
+        matched = False
+        for path in expanded:
+            if not os.path.isfile(path):
+                continue
+            if not _is_markdown_file(path):
+                continue
+            if _has_hidden_segment(path):
+                continue
+            file_set.add(os.path.realpath(path))
+            matched = True
+        if not matched:
+            warnings.append(f"Pattern matched no markdown files: {pattern}")
+
+    sorted_files = sorted(file_set)
+    return (sorted_files, warnings)
+
+
+def _is_markdown_file(path: str) -> bool:
+    """Check if a path has a markdown file extension.
+
+    Args:
+        path: File path string.
+
+    Returns:
+        True if the path ends with .md (case-insensitive).
+    """
+    return os.path.splitext(path)[1].lower() == ".md"

mdb/filelock.py

@@ -0,0 +1,76 @@
+"""Advisory file locking for concurrency safety."""
+
+import sys
+import time
+from contextlib import contextmanager
+
+LOCK_TIMEOUT = 3  # seconds
+LOCK_RETRY_INTERVAL = 1  # second
+LOCK_ERROR_MSG = "mdb: file locked by another process"
+
+if sys.platform == "win32":
+    import msvcrt
+
+    def _lock(fd):
+        """Acquire non-blocking exclusive lock (Windows)."""
+        deadline = time.monotonic() + LOCK_TIMEOUT
+        while True:
+            try:
+                msvcrt.locking(fd.fileno(), msvcrt.LK_NBLCK, 1)
+                return
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise OSError(LOCK_ERROR_MSG)
+                time.sleep(LOCK_RETRY_INTERVAL)
+
+    def _unlock(fd):
+        """Release exclusive lock (Windows)."""
+        try:
+            msvcrt.locking(fd.fileno(), msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+else:
+    import fcntl
+
+    def _lock(fd):
+        """Acquire non-blocking exclusive lock (Unix/macOS)."""
+        deadline = time.monotonic() + LOCK_TIMEOUT
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise OSError(LOCK_ERROR_MSG)
+                time.sleep(LOCK_RETRY_INTERVAL)
+
+    def _unlock(fd):
+        """Release exclusive lock (Unix/macOS)."""
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+@contextmanager
+def batch_lock(filepaths):
+    """Context manager: acquire exclusive locks on all filepaths in sorted order.
+
+    On timeout or error, releases all previously acquired locks.
+    """
+    sorted_paths = sorted(filepaths)
+    held = []  # list of open file objects
+    try:
+        for filepath in sorted_paths:
+            fd = open(filepath, "r")
+            try:
+                _lock(fd)
+            except BaseException:
+                fd.close()
+                raise
+            held.append(fd)
+        yield
+    finally:
+        for fd in reversed(held):
+            try:
+                _unlock(fd)
+            except OSError:
+                pass
+            fd.close()

mdb/formatter.py

@@ -0,0 +1,101 @@
+"""Markdown table generation from query result data."""
+
+
+def format_markdown_table(
+    columns: list[str],
+    rows: list[list[str]],
+    compaction: str = "full",
+) -> str:
+    """Generate a formatted markdown table string from columns and rows.
+
+    Args:
+        columns: Column header names.
+        rows: Row data (list of cell value lists).
+        compaction: Compaction mode - "full" (no padding) or "fit" (aligned).
+
+    When compaction="fit":
+    - Column widths based on max of header and cell widths (minimum 3 chars)
+    - Left-aligned, padded with spaces
+    - Zero rows produces header + separator only
+    - No trailing newline
+
+    When compaction="full":
+    - No column width calculation for alignment purposes
+    - Non-empty cells: ``| value |`` (single space before and after content)
+    - Empty cells: ``||`` (no spaces, no content)
+    - Separator row: ``| --- |`` per column (exactly 3 dashes, space-padded)
+    - No trailing newline
+    """
+    if compaction == "fit":
+        return _format_fit(columns, rows)
+    # Default to "full" for any value (including unknown values)
+    return _format_full(columns, rows)
+
+
+def _format_fit(columns: list[str], rows: list[list[str]]) -> str:
+    """Format a markdown table with aligned columns (fit compaction)."""
+    # Calculate column widths
+    widths = [max(3, len(col)) for col in columns]
+    for row in rows:
+        for i, cell in enumerate(row):
+            if i < len(widths):
+                widths[i] = max(widths[i], len(cell))
+
+    # Build header row
+    header_cells = [col.ljust(widths[i]) for i, col in enumerate(columns)]
+    header = "| " + " | ".join(header_cells) + " |"
+
+    # Build separator row
+    sep_cells = ["-" * widths[i] for i in range(len(columns))]
+    separator = "| " + " | ".join(sep_cells) + " |"
+
+    # Build data rows
+    lines = [header, separator]
+    for row in rows:
+        data_cells = []
+        for i in range(len(columns)):
+            cell = row[i] if i < len(row) else ""
+            data_cells.append(cell.ljust(widths[i]))
+        lines.append("| " + " | ".join(data_cells) + " |")
+
+    return "\n".join(lines)
+
+
+def _format_full(columns: list[str], rows: list[list[str]]) -> str:
+    """Format a markdown table with no alignment padding (full compaction)."""
+    # Build header row -- non-empty cells get single space padding
+    header_parts = []
+    for col in columns:
+        if col:
+            header_parts.append(f"| {col} ")
+        else:
+            header_parts.append("||")
+    header = "".join(header_parts) + "|" if header_parts else "|"
+    # Fix: if last part was a non-empty cell, it already ends with space
+    # We just need trailing |
+    # Actually, let's build it more carefully
+    header_cells = []
+    for col in columns:
+        if col:
+            header_cells.append(f" {col} ")
+        else:
+            header_cells.append("")
+    header = "|" + "|".join(header_cells) + "|"
+
+    # Build separator row -- exactly 3 dashes per column, space-padded
+    sep_cells = [" --- "] * len(columns)
+    separator = "|" + "|".join(sep_cells) + "|"
+
+    # Build data rows
+    lines = [header, separator]
+    for row in rows:
+        data_cells = []
+        for i in range(len(columns)):
+            cell = row[i] if i < len(row) else ""
+            if cell:
+                data_cells.append(f" {cell} ")
+            else:
+                data_cells.append("")
+        lines.append("|" + "|".join(data_cells) + "|")
+
+    return "\n".join(lines)

mdb/init.py

@@ -0,0 +1,150 @@
+"""Initialize the mdb skill in the current project.
+
+Copies the bundled SKILL.md file into <dir>/mdb/SKILL.md relative
+to the current working directory, where <dir> defaults to .mdb/skills.
+"""
+
+import importlib.resources
+import os
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class InitResult:
+    """Outcome of an init operation."""
+    success: bool
+    target_path: str
+    action: str  # "created", "updated", "up_to_date", "skipped", "error"
+    error: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Helper functions (T004, T005)
+# ---------------------------------------------------------------------------
+
+def _load_bundled_skill() -> str | None:
+    """Load the bundled SKILL.md content from the package data directory.
+
+    Returns the content as a string, or None if the file cannot be loaded.
+    """
+    try:
+        return (
+            importlib.resources.files("mdb.data")
+            .joinpath("SKILL.md")
+            .read_text(encoding="utf-8")
+        )
+    except Exception:
+        return None
+
+
+def _prompt_overwrite(rel_path: str) -> bool:
+    """Prompt the user for confirmation to overwrite an existing file.
+
+    Returns True if the user confirms (y/yes, case-insensitive),
+    False otherwise (including empty input, n, or EOFError).
+    """
+    print(
+        f"{rel_path} already exists and differs "
+        "from the bundled version."
+    )
+    try:
+        response = input("Overwrite? [y/N]: ")
+    except EOFError:
+        return False
+    return response.strip().lower() in ("y", "yes")
+
+
+# ---------------------------------------------------------------------------
+# Main orchestration (T006)
+# ---------------------------------------------------------------------------
+
+def init_skill(target_dir: str = ".mdb/skills", force: bool = False) -> InitResult:
+    """Install the bundled mdb skill file into the current project.
+
+    Args:
+        target_dir: Parent directory for the skill file. The tool always
+            appends mdb/SKILL.md to this directory.
+        force: If True, overwrite existing file without prompting.
+
+    Returns:
+        InitResult with success status and action taken.
+    """
+    # Step 1: Load bundled skill file
+    bundled_content = _load_bundled_skill()
+    if bundled_content is None:
+        error = ("Could not load bundled skill file: "
+                 "package installation may be corrupted")
+        print(f"Error: {error}", file=sys.stderr)
+        return InitResult(success=False, target_path="", action="error",
+                          error=error)
+
+    # Step 2: Determine target path
+    target_path = os.path.join(
+        os.getcwd(), target_dir, "mdb", "SKILL.md"
+    )
+    display_path = os.path.join(target_dir, "mdb", "SKILL.md")
+    target_parent = os.path.dirname(target_path)
+
+    # Step 3: Check existing file
+    if os.path.exists(target_path):
+        if not os.path.isfile(target_path):
+            error = f"{display_path} exists but is not a file"
+            print(f"Error: {error}", file=sys.stderr)
+            return InitResult(success=False, target_path=target_path,
+                              action="error", error=error)
+
+        try:
+            with open(target_path, "r", encoding="utf-8") as f:
+                existing_content = f.read()
+        except OSError as e:
+            error = f"Cannot read {display_path}: {e}"
+            print(f"Error: {error}", file=sys.stderr)
+            return InitResult(success=False, target_path=target_path,
+                              action="error", error=error)
+
+        if existing_content == bundled_content:
+            print(f"mdb skill is already up to date at "
+                  f"{display_path}")
+            return InitResult(success=True, target_path=target_path,
+                              action="up_to_date")
+
+        # Content differs
+        if not force:
+            if not _prompt_overwrite(display_path):
+                print("Skipped (no changes made)")
+                return InitResult(success=True, target_path=target_path,
+                                  action="skipped")
+
+        is_update = True
+    else:
+        is_update = False
+
+    # Step 4: Create directory structure
+    try:
+        os.makedirs(target_parent, exist_ok=True)
+    except OSError as e:
+        error = f"Cannot create directory {os.path.dirname(display_path)}/: {e}"
+        print(f"Error: {error}", file=sys.stderr)
+        return InitResult(success=False, target_path=target_path,
+                          action="error", error=error)
+
+    # Step 5: Write skill file
+    try:
+        with open(target_path, "w", encoding="utf-8") as f:
+            f.write(bundled_content)
+    except OSError as e:
+        error = f"Cannot write to {display_path}: {e}"
+        print(f"Error: {error}", file=sys.stderr)
+        return InitResult(success=False, target_path=target_path,
+                          action="error", error=error)
+
+    # Step 6: Print status and return
+    if is_update:
+        print(f"Updated mdb skill at {display_path}")
+        return InitResult(success=True, target_path=target_path,
+                          action="updated")
+    else:
+        print(f"Installed mdb skill to {display_path}")
+        return InitResult(success=True, target_path=target_path,
+                          action="created")