mdb-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/.gitignore

@@ -304,3 +304,6 @@ docs/assets/interactive-demo.js
 
 # mdb databases (tool-managed)
 .mdb/
+
+# mdb lock sidecar files
+*.md.lock

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Markdown table workflows w/ SQLite powers ✨
 Project-URL: Homepage, https://atomanoid.github.io/mdb/
 Project-URL: Repository, https://github.com/atomanoid/mdb
@@ -89,15 +89,16 @@ Place inline query markers above tables in your markdown file using the followin
 | `🌀`      | 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.
+> Under the hood, datasets are dynamically backed by SQLite 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) |
+| Subcommand                | Behavior                                                                                                               |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `mdb push`                | process all `🌀` markers first (pulls), then all `💎` markers after (pushes) — reports only changed markers by default |
+| `mdb push <sql-mutation>` | process all `🌀` markers first (pulls), execute the mutation, then all `🌀` and `💎` markers after (pushes)            |
+| `mdb pull <sql-query>`    | process all `🌀` markers first (pulls), then outputs SQL query results in CSV format                                   |
+| `mdb status`              | inspects all `🌀` and `💎` markers, then reports metadata and warnings                                                 |
 
 ### Example
 
@@ -181,7 +182,9 @@ We can also mutate data directly. Running:
 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:
+The 🌀 (feed) marker again ingests the snacks data into the dataset, applies the UPDATE, then both 🌀 (feed) and 💎 (tap) markers push fresh results back out.
+
+So then in the updated `snacks.md`:
 
 ```markdown
 ## Inventory
@@ -206,11 +209,29 @@ The 🌀 (feed) marker again ingests the snacks data into the dataset, applies t
 
 Takis got restocked to 27 and dropped off the low-stock list — all from a single command.
 
+---
+
+We can also inspect the current landscape of markers. Running:
+
+```bash
+mdb status
+```
+
+We'll get a snapshot of the available data:
+
+```
+OK   🌀 snacks (3 cols, 4 rows) [snacks.md:5]
+OK   💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty (2 cols, 2 rows) [snacks.md:15]
+Inspected 1 files, 2 markers: 0 problems
+```
+
+🌀 (feed) and 💎 (tap) markers show table dimensions, query text — and any problems (missing tables, conflicts) are flagged.
+
 ## Agent Support
 
 `mdb-cli` includes a built-in agent skill. Install it:
 
-```
+```bash
 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
@@ -218,3 +239,7 @@ 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.
+
+## Configuration
+
+`mdb init` also generates a `.mdbrc` configuration file in the project root. Edit it to set project-level defaults for CLI flags (`include`, `compaction`, `verbose`). CLI flags always override `.mdbrc` values. See [CLI Usage](https://atomanoid.github.io/mdb/cli-usage/) for details.

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/README.md

@@ -61,15 +61,16 @@ Place inline query markers above tables in your markdown file using the followin
 | `🌀`      | 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.
+> Under the hood, datasets are dynamically backed by SQLite 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) |
+| Subcommand                | Behavior                                                                                                               |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `mdb push`                | process all `🌀` markers first (pulls), then all `💎` markers after (pushes) — reports only changed markers by default |
+| `mdb push <sql-mutation>` | process all `🌀` markers first (pulls), execute the mutation, then all `🌀` and `💎` markers after (pushes)            |
+| `mdb pull <sql-query>`    | process all `🌀` markers first (pulls), then outputs SQL query results in CSV format                                   |
+| `mdb status`              | inspects all `🌀` and `💎` markers, then reports metadata and warnings                                                 |
 
 ### Example
 
@@ -153,7 +154,9 @@ We can also mutate data directly. Running:
 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:
+The 🌀 (feed) marker again ingests the snacks data into the dataset, applies the UPDATE, then both 🌀 (feed) and 💎 (tap) markers push fresh results back out.
+
+So then in the updated `snacks.md`:
 
 ```markdown
 ## Inventory
@@ -178,11 +181,29 @@ The 🌀 (feed) marker again ingests the snacks data into the dataset, applies t
 
 Takis got restocked to 27 and dropped off the low-stock list — all from a single command.
 
+---
+
+We can also inspect the current landscape of markers. Running:
+
+```bash
+mdb status
+```
+
+We'll get a snapshot of the available data:
+
+```
+OK   🌀 snacks (3 cols, 4 rows) [snacks.md:5]
+OK   💎 SELECT name, qty FROM snacks WHERE qty < 10 ORDER BY qty (2 cols, 2 rows) [snacks.md:15]
+Inspected 1 files, 2 markers: 0 problems
+```
+
+🌀 (feed) and 💎 (tap) markers show table dimensions, query text — and any problems (missing tables, conflicts) are flagged.
+
 ## Agent Support
 
 `mdb-cli` includes a built-in agent skill. Install it:
 
-```
+```bash
 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
@@ -190,3 +211,7 @@ 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.
+
+## Configuration
+
+`mdb init` also generates a `.mdbrc` configuration file in the project root. Edit it to set project-level defaults for CLI flags (`include`, `compaction`, `verbose`). CLI flags always override `.mdbrc` values. See [CLI Usage](https://atomanoid.github.io/mdb/cli-usage/) for details.

mdb_cli-0.1.1/mdb/config.py

@@ -0,0 +1,198 @@
+"""Configuration file (.mdbrc) support for mdb.
+
+Handles JSONC parsing, config loading/validation, and template generation
+for the .mdbrc project-level configuration file.
+"""
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class MdbConfig:
+    """Parsed .mdbrc configuration."""
+    include: str | None = None
+    compaction: str = "full"
+    verbose: bool = False
+
+
+MDBRC_TEMPLATE = """\
+{
+    // \u2699\ufe0f uncomment below to change defaults
+
+    // "include": "**/*.md", // (string|null)
+    // "compaction": "full", // ("full"|"fit")
+    // "verbose": false, // (bool, default false)
+}
+"""
+
+_RECOGNIZED_KEYS = {"include", "compaction", "verbose"}
+
+
+def strip_jsonc_comments(text: str) -> str:
+    """Remove // line comments from JSONC text, preserving // inside strings.
+
+    Also strips trailing commas before } and ] to handle JSONC trailing comma
+    syntax that json.loads() rejects.
+
+    Uses a character-by-character state machine to correctly handle string
+    literals containing // sequences.
+    """
+    result = []
+    i = 0
+    in_string = False
+    length = len(text)
+
+    while i < length:
+        ch = text[i]
+
+        if in_string:
+            result.append(ch)
+            if ch == '\\' and i + 1 < length:
+                # Escaped character inside string -- consume next char too
+                i += 1
+                result.append(text[i])
+            elif ch == '"':
+                in_string = False
+            i += 1
+            continue
+
+        # Outside string
+        if ch == '"':
+            in_string = True
+            result.append(ch)
+            i += 1
+            continue
+
+        if ch == '/' and i + 1 < length and text[i + 1] == '/':
+            # Line comment -- skip to end of line
+            while i < length and text[i] != '\n':
+                i += 1
+            continue
+
+        result.append(ch)
+        i += 1
+
+    stripped = ''.join(result)
+
+    # Remove trailing commas before } and ]
+    # Match: comma, optional whitespace/newlines, then } or ]
+    import re
+    stripped = re.sub(r',(\s*[}\]])', r'\1', stripped)
+
+    return stripped
+
+
+def load_config(cwd: str | None = None) -> 'MdbConfig | None':
+    """Load and validate .mdbrc from the given directory.
+
+    Args:
+        cwd: Directory to search for .mdbrc. Defaults to os.getcwd().
+
+    Returns:
+        MdbConfig with parsed values, or None if no .mdbrc exists.
+        Calls sys.exit(1) on hard errors (invalid JSON, bad values, etc.).
+    """
+    config_dir = cwd or os.getcwd()
+    config_path = os.path.join(config_dir, ".mdbrc")
+
+    if not os.path.exists(config_path):
+        return None
+
+    # FR-016: Must be a regular file
+    if not os.path.isfile(config_path):
+        print("Error: .mdbrc is not a regular file", file=sys.stderr)
+        sys.exit(1)
+
+    # FR-017: Must be valid UTF-8
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            raw = f.read()
+    except UnicodeDecodeError:
+        print("Error: .mdbrc contains non-UTF-8 content", file=sys.stderr)
+        sys.exit(1)
+    except OSError as e:
+        print(f"Error: Cannot read .mdbrc: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # FR-007: Announce config discovery
+    print("Using .mdbrc", file=sys.stderr)
+
+    # Strip JSONC comments
+    stripped = strip_jsonc_comments(raw)
+
+    # FR-015: Empty/comments-only treated as empty object
+    if not stripped.strip():
+        return MdbConfig()
+
+    # FR-011: Parse JSON
+    try:
+        data = json.loads(stripped)
+    except json.JSONDecodeError as e:
+        print(f"Error: .mdbrc contains invalid JSON: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # CHK023: Root must be an object (dict)
+    if not isinstance(data, dict):
+        print("Error: .mdbrc root must be a JSON object", file=sys.stderr)
+        sys.exit(1)
+
+    # FR-012: Warn on unrecognized keys
+    for key in data:
+        if key not in _RECOGNIZED_KEYS:
+            print(f"Warning: .mdbrc contains unrecognized key: {key}", file=sys.stderr)
+
+    # FR-013: Validate recognized keys
+    config = MdbConfig()
+
+    if "include" in data:
+        val = data["include"]
+        if val is not None and not isinstance(val, str):
+            print("Error: .mdbrc 'include' must be a string or null", file=sys.stderr)
+            sys.exit(1)
+        config.include = val
+
+    if "compaction" in data:
+        val = data["compaction"]
+        if val not in ("full", "fit"):
+            print(f"Error: .mdbrc 'compaction' must be \"full\" or \"fit\", got: {val!r}", file=sys.stderr)
+            sys.exit(1)
+        config.compaction = val
+
+    if "verbose" in data:
+        val = data["verbose"]
+        if not isinstance(val, bool):
+            print(f"Error: .mdbrc 'verbose' must be a boolean, got: {val!r}", file=sys.stderr)
+            sys.exit(1)
+        config.verbose = val
+
+    return config
+
+
+def generate_mdbrc(cwd: str | None = None) -> bool:
+    """Generate .mdbrc template file in the given directory.
+
+    Args:
+        cwd: Directory to write .mdbrc into. Defaults to os.getcwd().
+
+    Returns:
+        True on success (created or preserved), False on error.
+    """
+    config_dir = cwd or os.getcwd()
+    config_path = os.path.join(config_dir, ".mdbrc")
+
+    # FR-003: Never overwrite existing
+    if os.path.exists(config_path):
+        print(".mdbrc already exists (preserved)")
+        return True
+
+    try:
+        with open(config_path, "w", encoding="utf-8") as f:
+            f.write(MDBRC_TEMPLATE)
+        print("Created .mdbrc")
+        return True
+    except OSError as e:
+        print(f"Error: Cannot write .mdbrc: {e}", file=sys.stderr)
+        return False

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/mdb/data/SKILL.md

@@ -51,10 +51,23 @@ mdb pull -i "docs/" "SELECT * FROM t"                      # restrict to directo
 
 Pull rules: only SELECT permitted; DML rejected.
 
+### `mdb status`
+
+Read-only marker inventory. Reports structural metadata and detects problems
+
+```bash
+mdb status                        # scan all markdown files
+mdb status -i "docs/"             # restrict to directory
+```
+
 ### Common flags
 
 `-i "path1/ path2/"` — restrict markdown file discovery to specific directories (default: recurse from CWD).
 
+### `.mdbrc` configuration
+
+A `.mdbrc` file in the project root provides default values for CLI flags, generated by `mdb init`. Supported keys: `include`, `compaction`, `verbose`. CLI flags always override `.mdbrc` values.
+
 ## Key Behaviors
 
 - 🌀 markers across all files execute first (pull phase), then 💎 markers (push phase)

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/mdb/discovery.py

@@ -29,7 +29,7 @@ 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/*"]).
+        patterns: List of glob pattern strings (e.g., ["**/*.md"], ["docs/*"]).
 
     Returns:
         Tuple of (files, warnings):

{mdb_cli-0.1.0 → mdb_cli-0.1.1}/mdb/filelock.py

@@ -1,5 +1,6 @@
 """Advisory file locking for concurrency safety."""
 
+import os
 import sys
 import time
 from contextlib import contextmanager
@@ -53,24 +54,38 @@ else:
 def batch_lock(filepaths):
     """Context manager: acquire exclusive locks on all filepaths in sorted order.
 
+    Uses separate .lock sidecar files so that atomic_write (which replaces the
+    data file via os.replace) does not invalidate the lock fd's inode — avoids
+    EIO on close() in overlayfs / container environments.
+
     On timeout or error, releases all previously acquired locks.
     """
     sorted_paths = sorted(filepaths)
-    held = []  # list of open file objects
+    held = []  # list of (lock_path, open file object)
     try:
         for filepath in sorted_paths:
-            fd = open(filepath, "r")
+            if not os.path.exists(filepath):
+                raise FileNotFoundError(f"No such file: '{filepath}'")
+            lock_path = filepath + ".lock"
+            fd = open(lock_path, "a")
             try:
                 _lock(fd)
             except BaseException:
                 fd.close()
                 raise
-            held.append(fd)
+            held.append((lock_path, fd))
         yield
     finally:
-        for fd in reversed(held):
+        for lock_path, fd in reversed(held):
             try:
                 _unlock(fd)
             except OSError:
                 pass
-            fd.close()
+            try:
+                fd.close()
+            except OSError:
+                pass
+            try:
+                os.unlink(lock_path)
+            except OSError:
+                pass