mdb-cli 0.1.0__py3-none-any.whl

mdb/mdb.py

@@ -0,0 +1,1214 @@
+"""Unified CLI entry point for mdb: push, pull subcommands."""
+
+import argparse
+import csv
+import os
+import sqlite3
+import sys
+from mdb.models import FileMarkers, FeedConflict
+from mdb.parser import find_tap_markers, find_feed_markers, find_adjacent_table, parse_markdown_table, resolve_scope_path, parse_header_types_with_annotation_flags, parse_cast_types, resolve_column_types, parse_post_pull_tap_query, parse_pre_push_feed_query
+from mdb.formatter import format_markdown_table
+from mdb.puller import execute_tap_query, ingest_feed_table, cleanup_stale_tables
+from mdb.validators import validate_dql, validate_dml
+from mdb.discovery import resolve_paths
+from mdb.atomic import atomic_write
+from mdb.filelock import batch_lock
+
+
+# ---------------------------------------------------------------------------
+# Helpers (T002, T003, T004)
+# ---------------------------------------------------------------------------
+
+def _collect_file_markers(filepath, include_taps, include_feeds):
+    """Parse a single markdown file and extract relevant markers.
+
+    Returns FileMarkers or None on file read error.
+    """
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+    except UnicodeDecodeError:
+        print(f"Error [{filepath}]: File is not valid UTF-8", file=sys.stderr)
+        return None
+    except FileNotFoundError:
+        print(f"Error [{filepath}]: File not found", file=sys.stderr)
+        return None
+    except OSError as e:
+        print(f"Error [{filepath}]: {e}", file=sys.stderr)
+        return None
+
+    lines = content.splitlines()
+    tap_markers = find_tap_markers(content) if include_taps else []
+    feed_markers = find_feed_markers(content) if include_feeds else []
+
+    return FileMarkers(
+        filepath=filepath,
+        content=content,
+        lines=lines,
+        tap_markers=tap_markers,
+        feed_markers=feed_markers,
+    )
+
+
+def _print_summary(files_processed, markers_found, succeeded, failed):
+    """Print the final summary line."""
+    print(
+        f"Processed {files_processed} files, {markers_found} markers: "
+        f"{succeeded} succeeded, {failed} failed"
+    )
+
+
+def _discover_files(include_arg: str | None) -> list[str]:
+    """Unified file discovery: convert --include CLI arg to sorted list of .md paths.
+
+    Args:
+        include_arg: Raw --include argument value, or None if not provided.
+
+    Returns:
+        Sorted, deduplicated list of absolute .md file paths.
+    """
+    if include_arg and include_arg.strip():
+        patterns = include_arg.split()
+    else:
+        patterns = ["**"]
+
+    files, warnings = resolve_paths(patterns)
+    for w in warnings:
+        print(w, file=sys.stderr)
+    return files
+
+
+def _normalize_include_for_hash(include_arg: str | None) -> str | None:
+    """Normalize include_arg for database path hashing.
+
+    Returns None if include_arg is unset, empty, or equivalent to the default '**'.
+    Otherwise returns the raw include_arg for hashing.
+    """
+    if not include_arg or not include_arg.strip():
+        return None
+    tokens = include_arg.split()
+    if tokens == ["**"]:
+        return None
+    return include_arg
+
+
+# ---------------------------------------------------------------------------
+# Conflict detection (T005)
+# ---------------------------------------------------------------------------
+
+def _detect_feed_conflicts(all_file_markers, include_paths=None):
+    """Detect cross-file feed conflicts.
+
+    Groups all 🌀 markers by (resolved_path, table_name).
+    If markers from more than one file target the same key, that is a conflict.
+    Returns list of FeedConflict objects.
+    """
+    # key: (resolved_path, table_name) -> list of (filepath, line_number)
+    groups = {}
+    scope_for_key = {}
+    for fm in all_file_markers:
+        for wm in fm.feed_markers:
+            if wm.table_name is None:
+                continue
+            resolved = resolve_scope_path(wm.scope, fm.filepath, include_paths)
+            key = (resolved, wm.table_name)
+            groups.setdefault(key, []).append((fm.filepath, wm.line_number))
+            scope_for_key[key] = wm.scope
+
+    conflicts = []
+    for (resolved_path, table_name), entries in groups.items():
+        # Check if entries come from more than one file
+        files_seen = set(fp for fp, _ in entries)
+        if len(files_seen) > 1:
+            conflicts.append(FeedConflict(
+                scope=scope_for_key[(resolved_path, table_name)],
+                resolved_path=resolved_path,
+                table_name=table_name,
+                conflicting=entries,
+            ))
+    return conflicts
+
+
+def _conflicted_keys(conflicts):
+    """Return a set of (resolved_path, table_name) that are conflicted."""
+    return set((c.resolved_path, c.table_name) for c in conflicts)
+
+
+# ---------------------------------------------------------------------------
+# Push subcommand (T006, T007)
+# ---------------------------------------------------------------------------
+
+def _run_push(filepaths, compaction="full", verbose=False, include_paths=None):
+    """Execute the push subcommand: pull phase (all 🌀 markers) first, then push phase (all 💎 markers)."""
+    with batch_lock(filepaths):
+        return _run_push_locked(filepaths, compaction, verbose, include_paths)
+
+
+def _run_push_locked(filepaths, compaction="full", verbose=False, include_paths=None):
+    """Execute push with all filepaths already locked."""
+    pull_succeeded = 0
+    pull_failed = 0
+    push_succeeded = 0
+    push_failed = 0
+    files_processed = 0
+
+    # Collect all markers from all files (both feed and tap)
+    all_fm = []
+    for filepath in filepaths:
+        fm = _collect_file_markers(filepath, include_taps=True, include_feeds=True)
+        if fm is None:
+            pull_failed += 1
+            files_processed += 1
+            continue
+        files_processed += 1
+        all_fm.append(fm)
+
+    # --- Pull phase: detect conflicts and execute all 🌀 markers ---
+    conflicts = _detect_feed_conflicts(all_fm, include_paths)
+    conflict_keys = _conflicted_keys(conflicts)
+
+    for conflict in conflicts:
+        parts = [f"{fp}:{ln}" for fp, ln in conflict.conflicting]
+        locations = " and ".join(parts)
+        print(
+            f"CONFLICT {conflict.scope} 💾 {conflict.table_name} - "
+            f"conflicting writes from {locations}"
+        )
+        pull_failed += len(conflict.conflicting)
+
+    # Collect declared table names per db_path for orphan cleanup (FR-006, FR-013)
+    discovered_by_db = {}
+    for fm in all_fm:
+        for marker in fm.feed_markers:
+            if marker.table_name is None:
+                continue
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+            discovered_by_db.setdefault(resolved, set()).add(marker.table_name)
+
+    # Orphan cleanup BEFORE writes (FR-013)
+    for db_path, discovered_tables in discovered_by_db.items():
+        cleanup_stale_tables(db_path, discovered_tables)
+
+    for fm in all_fm:
+        for marker in fm.feed_markers:
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            if marker.table_name is None:
+                msg = f"Could not parse table name from query: {marker.raw_query}"
+                print(
+                    f"FAIL {marker.scope} 🌀 (unknown) - {msg} "
+                    f"[{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {msg}",
+                    file=sys.stderr,
+                )
+                pull_failed += 1
+                continue
+
+            if (resolved, marker.table_name) in conflict_keys:
+                continue
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+            if table is None:
+                msg = "No markdown table found after marker"
+                print(
+                    f"WARN {marker.scope} 🌀 {marker.table_name} - {msg} "
+                    f"[{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {msg}",
+                    file=sys.stderr,
+                )
+                pull_failed += 1
+                continue
+
+            col_names, col_types, was_annotated, type_warnings, type_errors = \
+                parse_header_types_with_annotation_flags(table.columns)
+
+            for warn in type_warnings:
+                print(
+                    f"WARN {warn} [{fm.filepath}:{marker.line_number}]",
+                    file=sys.stderr,
+                )
+
+            if type_errors:
+                for err in type_errors:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{err} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {err}",
+                        file=sys.stderr,
+                    )
+                pull_failed += 1
+                continue
+
+            cast_types, cast_errors = parse_cast_types(marker.raw_query)
+
+            if cast_errors:
+                for err in cast_errors:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{err} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {err}",
+                        file=sys.stderr,
+                    )
+                pull_failed += 1
+                continue
+
+            final_types = resolve_column_types(
+                col_types, cast_types, len(col_names), was_annotated
+            )
+
+            try:
+                result = ingest_feed_table(
+                    db_path=resolved,
+                    table_name=marker.table_name,
+                    columns=col_names,
+                    rows=table.rows,
+                    column_types=final_types,
+                )
+                if result.success:
+                    if result.skipped and verbose:
+                        print(
+                            f"SKIP {marker.scope} 🌀 {marker.table_name} "
+                            f"(unchanged) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    elif result.skipped:
+                        print(
+                            f"OK   {marker.scope} 🌀 {marker.table_name} "
+                            f"({len(table.rows)} rows) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    else:
+                        print(
+                            f"OK   {marker.scope} 🌀 {marker.table_name} "
+                            f"({result.rows_written} rows) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    pull_succeeded += 1
+                else:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{result.error} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {result.error}",
+                        file=sys.stderr,
+                    )
+                    pull_failed += 1
+            except Exception as e:
+                print(
+                    f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                    f"{e} [{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {e}",
+                    file=sys.stderr,
+                )
+                pull_failed += 1
+
+    # --- Push phase: execute all 💎 markers ---
+    file_replacements = {}
+
+    for fm in all_fm:
+        replacements = []
+
+        for marker in fm.tap_markers:
+            db_path = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            validation_error = validate_dql(marker.raw_query)
+            if validation_error:
+                print(
+                    f"FAIL {marker.scope} 💎 {marker.raw_query} - "
+                    f"{validation_error} [{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {validation_error}",
+                    file=sys.stderr,
+                )
+                push_failed += 1
+                continue
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+
+            result = execute_tap_query(db_path, marker.raw_query)
+            if not result.success:
+                print(
+                    f"FAIL {marker.scope} 💎 {marker.raw_query} - "
+                    f"{result.error} [{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {result.error}",
+                    file=sys.stderr,
+                )
+                push_failed += 1
+                continue
+
+            new_table_str = format_markdown_table(
+                result.columns, result.rows, compaction=compaction
+            )
+            new_table_lines = new_table_str.split("\n")
+
+            if table is None:
+                # Dangling tap marker: insert new table after marker/fence
+                insert_after = marker.end_line_number if marker.end_line_number else marker.line_number
+                insert_idx = insert_after  # 0-based index after marker line
+                new_lines = [""] + new_table_lines  # blank line before table
+                replacements.append((insert_idx, insert_idx - 1, new_lines))
+            else:
+                table_start_idx = table.start_line - 1
+                table_end_idx = table.end_line - 1
+                replacements.append((table_start_idx, table_end_idx, new_table_lines))
+
+            row_count = len(result.rows)
+            print(
+                f"OK   {marker.scope} 💎 {marker.raw_query} "
+                f"({row_count} rows) [{fm.filepath}:{marker.line_number}]"
+            )
+            push_succeeded += 1
+
+        if replacements:
+            file_replacements[fm.filepath] = (fm, replacements)
+
+    # Apply read replacements to files
+    for filepath, (fm, replacements) in file_replacements.items():
+        replacements.sort(key=lambda r: r[0], reverse=True)
+        lines = list(fm.lines)
+        for start_idx, end_idx, new_lines in replacements:
+            lines[start_idx:end_idx + 1] = new_lines
+
+        new_content = "\n".join(lines)
+        if fm.content.endswith("\n"):
+            new_content += "\n"
+        atomic_write(filepath, new_content)
+
+    succeeded = pull_succeeded + push_succeeded
+    failed = pull_failed + push_failed
+    total_markers = succeeded + failed
+    _print_summary(files_processed, total_markers, succeeded, failed)
+
+    if failed > 0:
+        return 1
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Pull subcommand (T009, T010)
+# ---------------------------------------------------------------------------
+
+def _run_pull(filepaths, verbose=False, include_paths=None):
+    """Execute the pull subcommand: process 🌀 markers (md-to-db)."""
+    succeeded = 0
+    failed = 0
+    files_processed = 0
+
+    # Collect all file markers first (for conflict detection)
+    all_fm = []
+    for filepath in filepaths:
+        fm = _collect_file_markers(filepath, include_taps=False, include_feeds=True)
+        if fm is None:
+            failed += 1
+            files_processed += 1
+            continue
+        files_processed += 1
+        all_fm.append(fm)
+
+    # Detect cross-file feed conflicts
+    conflicts = _detect_feed_conflicts(all_fm, include_paths)
+    conflict_keys = _conflicted_keys(conflicts)
+
+    # Report conflicts
+    for conflict in conflicts:
+        parts = [f"{fp}:{ln}" for fp, ln in conflict.conflicting]
+        locations = " and ".join(parts)
+        print(
+            f"CONFLICT {conflict.scope} 💾 {conflict.table_name} - "
+            f"conflicting writes from {locations}"
+        )
+        failed += len(conflict.conflicting)
+
+    # Collect declared table names per db_path for orphan cleanup (FR-006, FR-013)
+    discovered_by_db = {}
+    for fm in all_fm:
+        for marker in fm.feed_markers:
+            if marker.table_name is None:
+                continue
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+            discovered_by_db.setdefault(resolved, set()).add(marker.table_name)
+
+    # Orphan cleanup BEFORE writes (FR-013)
+    for db_path, discovered_tables in discovered_by_db.items():
+        cleanup_stale_tables(db_path, discovered_tables)
+
+    # Process each file's feed markers
+    for fm in all_fm:
+        for marker in fm.feed_markers:
+            # Resolve DB path relative to markdown file
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            # Check table name extraction
+            if marker.table_name is None:
+                msg = f"Could not parse table name from query: {marker.raw_query}"
+                print(
+                    f"FAIL {marker.scope} 🌀 (unknown) - {msg} "
+                    f"[{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {msg}",
+                    file=sys.stderr,
+                )
+                failed += 1
+                continue
+
+            # Check if this marker is part of a conflict
+            if (resolved, marker.table_name) in conflict_keys:
+                # Already reported as CONFLICT above; skip
+                continue
+
+            # Find adjacent table
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+            if table is None:
+                msg = "No markdown table found after marker"
+                print(
+                    f"WARN {marker.scope} 🌀 {marker.table_name} - {msg} "
+                    f"[{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {msg}",
+                    file=sys.stderr,
+                )
+                failed += 1
+                continue
+
+            # Parse type annotations from headers
+            col_names, col_types, was_annotated, type_warnings, type_errors = \
+                parse_header_types_with_annotation_flags(table.columns)
+
+            # Report warnings to stderr
+            for warn in type_warnings:
+                print(
+                    f"WARN {warn} [{fm.filepath}:{marker.line_number}]",
+                    file=sys.stderr,
+                )
+
+            # Report errors and skip marker
+            if type_errors:
+                for err in type_errors:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{err} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {err}",
+                        file=sys.stderr,
+                    )
+                failed += 1
+                continue
+
+            # Parse cast types from query marker
+            cast_types, cast_errors = parse_cast_types(marker.raw_query)
+
+            if cast_errors:
+                for err in cast_errors:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{err} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {err}",
+                        file=sys.stderr,
+                    )
+                failed += 1
+                continue
+
+            # Resolve final column types (header precedence over cast)
+            final_types = resolve_column_types(
+                col_types, cast_types, len(col_names), was_annotated
+            )
+
+            # Write to database
+            try:
+                result = ingest_feed_table(
+                    db_path=resolved,
+                    table_name=marker.table_name,
+                    columns=col_names,
+                    rows=table.rows,
+                    column_types=final_types,
+                )
+                if result.success:
+                    if result.skipped and verbose:
+                        print(
+                            f"SKIP {marker.scope} 🌀 {marker.table_name} "
+                            f"(unchanged) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    elif result.skipped:
+                        print(
+                            f"OK   {marker.scope} 🌀 {marker.table_name} "
+                            f"({len(table.rows)} rows) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    else:
+                        print(
+                            f"OK   {marker.scope} 🌀 {marker.table_name} "
+                            f"({result.rows_written} rows) [{fm.filepath}:{marker.line_number}]"
+                        )
+                    succeeded += 1
+                else:
+                    print(
+                        f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                        f"{result.error} [{fm.filepath}:{marker.line_number}]"
+                    )
+                    print(
+                        f"Error [{fm.filepath}:{marker.line_number}]: {result.error}",
+                        file=sys.stderr,
+                    )
+                    failed += 1
+            except Exception as e:
+                print(
+                    f"FAIL {marker.scope} 🌀 {marker.table_name} - "
+                    f"{e} [{fm.filepath}:{marker.line_number}]"
+                )
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {e}",
+                    file=sys.stderr,
+                )
+                failed += 1
+
+    total_markers = succeeded + failed
+    _print_summary(files_processed, total_markers, succeeded, failed)
+
+    if failed > 0:
+        return 1
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Post-pull-tap-query subcommand (027-pull-query)
+# ---------------------------------------------------------------------------
+
+def _run_pull_with_tap_query(query, include_paths, cwd, verbose=False):
+    """Execute the post-pull-tap-query subcommand: discover markers, pull to DB, run query, output CSV."""
+    # Parse scope from query argument
+    scope_name, sql_query = parse_post_pull_tap_query(query)
+
+    # File discovery
+    filepaths = _discover_files(include_paths)
+
+    if not filepaths:
+        if scope_name:
+            print(f"Error: No markers found for scope '{scope_name}'", file=sys.stderr)
+        else:
+            print("Error: No data sources found for default scope", file=sys.stderr)
+        return 1
+
+    normalized_include = _normalize_include_for_hash(include_paths)
+    with batch_lock(filepaths):
+        return _run_pull_with_tap_query_locked(filepaths, scope_name, sql_query, normalized_include, verbose)
+
+
+def _run_pull_with_tap_query_locked(filepaths, scope_name, sql_query, include_paths, verbose=False):
+    """Execute post-pull-tap-query with all filepaths already locked."""
+    # Collect feed markers from all discovered files
+    all_fm = []
+    for filepath in filepaths:
+        fm = _collect_file_markers(filepath, include_taps=False, include_feeds=True)
+        if fm is None:
+            continue
+        all_fm.append(fm)
+
+    # Scope filtering
+    filtered_fm = []
+    for fm in all_fm:
+        filtered_markers = []
+        for marker in fm.feed_markers:
+            if scope_name == "":
+                # Implicit scope: only markers with empty/whitespace scope
+                if marker.scope.strip() == "":
+                    filtered_markers.append(marker)
+            else:
+                # Explicit scope: only markers with exact scope name match
+                if marker.scope.strip() == scope_name:
+                    filtered_markers.append(marker)
+        if filtered_markers:
+            # Create a copy of FileMarkers with only matching feed markers
+            filtered_fm.append(FileMarkers(
+                filepath=fm.filepath,
+                content=fm.content,
+                lines=fm.lines,
+                tap_markers=[],
+                feed_markers=filtered_markers,
+            ))
+
+    if not filtered_fm:
+        if scope_name:
+            print(f"Error: No markers found for scope '{scope_name}'", file=sys.stderr)
+        else:
+            print("Error: No data sources found for default scope", file=sys.stderr)
+        return 1
+
+    # Conflict detection
+    conflicts = _detect_feed_conflicts(filtered_fm, include_paths)
+    conflict_keys = _conflicted_keys(conflicts)
+
+    for conflict in conflicts:
+        parts = [f"{fp}:{ln}" for fp, ln in conflict.conflicting]
+        locations = " and ".join(parts)
+        print(
+            f"CONFLICT {conflict.scope} \U0001f4be {conflict.table_name} - "
+            f"conflicting writes from {locations}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Collect declared table names per db_path for orphan cleanup (FR-006, FR-013)
+    discovered_by_db = {}
+    for fm in filtered_fm:
+        for marker in fm.feed_markers:
+            if marker.table_name is None:
+                continue
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+            discovered_by_db.setdefault(resolved, set()).add(marker.table_name)
+
+    # Orphan cleanup BEFORE writes (FR-013)
+    for db_path, discovered_tables in discovered_by_db.items():
+        cleanup_stale_tables(db_path, discovered_tables)
+
+    # Pull phase: feed markers to DB
+    pull_failed = 0
+    for fm in filtered_fm:
+        for marker in fm.feed_markers:
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            if marker.table_name is None:
+                msg = f"Could not parse table name from query: {marker.raw_query}"
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {msg}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            if (resolved, marker.table_name) in conflict_keys:
+                continue
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+            if table is None:
+                msg = "No markdown table found after marker"
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {msg}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            col_names, col_types, was_annotated, type_warnings, type_errors = \
+                parse_header_types_with_annotation_flags(table.columns)
+
+            for warn in type_warnings:
+                print(f"WARN {warn} [{fm.filepath}:{marker.line_number}]", file=sys.stderr)
+
+            if type_errors:
+                for err in type_errors:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {err}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            cast_types, cast_errors = parse_cast_types(marker.raw_query)
+
+            if cast_errors:
+                for err in cast_errors:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {err}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            final_types = resolve_column_types(
+                col_types, cast_types, len(col_names), was_annotated
+            )
+
+            try:
+                result = ingest_feed_table(
+                    db_path=resolved,
+                    table_name=marker.table_name,
+                    columns=col_names,
+                    rows=table.rows,
+                    column_types=final_types,
+                )
+                if not result.success:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {result.error}", file=sys.stderr)
+                    pull_failed += 1
+            except Exception as e:
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {e}", file=sys.stderr)
+                pull_failed += 1
+
+    if pull_failed > 0:
+        return 1
+
+    # Determine target DB path
+    target_db_path = resolve_scope_path(scope_name, "", include_paths)
+
+    # Read-only validation
+    validation_error = validate_dql(sql_query)
+    if validation_error:
+        print(f"Error: Only SELECT queries are permitted. Found: {validation_error.split(': ')[-1]}", file=sys.stderr)
+        return 1
+
+    # Query execution
+    result = execute_tap_query(target_db_path, sql_query)
+    if not result.success:
+        print(f"Error: {result.error}", file=sys.stderr)
+        return 1
+
+    # CSV output
+    writer = csv.writer(sys.stdout)
+    writer.writerow(result.columns)
+    writer.writerows(result.rows)
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Pre-push-feed-query subcommand (028-push-query)
+# ---------------------------------------------------------------------------
+
+def _run_push_with_feed_query(scope_name, sql_query, include_paths, compaction, cwd, verbose=False):
+    """Execute the pre-push-feed-query pipeline: discover -> pull -> mutate -> push back."""
+    # File discovery
+    filepaths = _discover_files(include_paths)
+
+    if not filepaths:
+        if scope_name:
+            print(f"Error: No markers found for scope '{scope_name}'", file=sys.stderr)
+        else:
+            print("Error: No data sources found for default scope", file=sys.stderr)
+        return 1
+
+    normalized_include = _normalize_include_for_hash(include_paths)
+    with batch_lock(filepaths):
+        return _run_push_with_feed_query_locked(filepaths, scope_name, sql_query, normalized_include, compaction, verbose)
+
+
+def _run_push_with_feed_query_locked(filepaths, scope_name, sql_query, include_paths, compaction, verbose=False):
+    """Execute pre-push-feed-query with all filepaths already locked."""
+    # Collect both feed and tap markers from all discovered files
+    all_fm = []
+    for filepath in filepaths:
+        fm = _collect_file_markers(filepath, include_taps=True, include_feeds=True)
+        if fm is None:
+            continue
+        all_fm.append(fm)
+
+    # Scope filtering: filter both 🌀 and 💎 markers by scope
+    filtered_fm = []
+    for fm in all_fm:
+        filtered_feed = []
+        filtered_tap = []
+        for marker in fm.feed_markers:
+            if scope_name == "":
+                if marker.scope.strip() == "":
+                    filtered_feed.append(marker)
+            else:
+                if marker.scope.strip() == scope_name:
+                    filtered_feed.append(marker)
+        for marker in fm.tap_markers:
+            if scope_name == "":
+                if marker.scope.strip() == "":
+                    filtered_tap.append(marker)
+            else:
+                if marker.scope.strip() == scope_name:
+                    filtered_tap.append(marker)
+        if filtered_feed or filtered_tap:
+            filtered_fm.append(FileMarkers(
+                filepath=fm.filepath,
+                content=fm.content,
+                lines=fm.lines,
+                tap_markers=filtered_tap,
+                feed_markers=filtered_feed,
+            ))
+
+    # Check for feed markers (needed for pull phase)
+    has_feed_markers = any(fm.feed_markers for fm in filtered_fm)
+    if not has_feed_markers:
+        if scope_name:
+            print(f"Error: No markers found for scope '{scope_name}'", file=sys.stderr)
+        else:
+            print("Error: No data sources found for default scope", file=sys.stderr)
+        return 1
+
+    # Conflict detection on feed markers
+    conflicts = _detect_feed_conflicts(filtered_fm, include_paths)
+    if conflicts:
+        for conflict in conflicts:
+            parts = [f"{fp}:{ln}" for fp, ln in conflict.conflicting]
+            locations = " and ".join(parts)
+            print(
+                f"CONFLICT {conflict.scope} \U0001f4be {conflict.table_name} - "
+                f"conflicting writes from {locations}",
+                file=sys.stderr,
+            )
+        return 1
+
+    # Collect declared table names per db_path for orphan cleanup (FR-006, FR-013)
+    discovered_by_db = {}
+    for fm in filtered_fm:
+        for marker in fm.feed_markers:
+            if marker.table_name is None:
+                continue
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+            discovered_by_db.setdefault(resolved, set()).add(marker.table_name)
+
+    # Orphan cleanup BEFORE writes (FR-013)
+    for db_path, discovered_tables in discovered_by_db.items():
+        cleanup_stale_tables(db_path, discovered_tables)
+
+    # Pull phase: feed 🌀 marker data to DB (re-pull from markdown)
+    pull_failed = 0
+    for fm in filtered_fm:
+        for marker in fm.feed_markers:
+            resolved = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            if marker.table_name is None:
+                msg = f"Could not parse table name from query: {marker.raw_query}"
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {msg}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+            if table is None:
+                msg = "No markdown table found after marker"
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {msg}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            col_names, col_types, was_annotated, type_warnings, type_errors = \
+                parse_header_types_with_annotation_flags(table.columns)
+
+            for warn in type_warnings:
+                print(f"WARN {warn} [{fm.filepath}:{marker.line_number}]", file=sys.stderr)
+
+            if type_errors:
+                for err in type_errors:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {err}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            cast_types, cast_errors = parse_cast_types(marker.raw_query)
+
+            if cast_errors:
+                for err in cast_errors:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {err}", file=sys.stderr)
+                pull_failed += 1
+                continue
+
+            final_types = resolve_column_types(
+                col_types, cast_types, len(col_names), was_annotated
+            )
+
+            try:
+                result = ingest_feed_table(
+                    db_path=resolved,
+                    table_name=marker.table_name,
+                    columns=col_names,
+                    rows=table.rows,
+                    column_types=final_types,
+                )
+                if result.success and result.skipped and verbose:
+                    print(
+                        f"SKIP {marker.scope} 🌀 {marker.table_name} "
+                        f"(unchanged) [{fm.filepath}:{marker.line_number}]",
+                        file=sys.stderr,
+                    )
+                elif not result.success:
+                    print(f"Error [{fm.filepath}:{marker.line_number}]: {result.error}", file=sys.stderr)
+                    pull_failed += 1
+            except Exception as e:
+                print(f"Error [{fm.filepath}:{marker.line_number}]: {e}", file=sys.stderr)
+                pull_failed += 1
+
+    if pull_failed > 0:
+        return 1
+
+    # Determine target DB path
+    target_db_path = resolve_scope_path(scope_name, "", include_paths)
+
+    # Execute mutative query in a single transaction
+    conn = None
+    try:
+        conn = sqlite3.connect(target_db_path)
+        conn.execute("BEGIN TRANSACTION")
+        for stmt in sql_query.split(";"):
+            stripped = stmt.strip()
+            if stripped:
+                conn.execute(stripped)
+        conn.commit()
+    except Exception as e:
+        if conn:
+            conn.rollback()
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    finally:
+        if conn:
+            conn.close()
+
+    # Push-back phase: re-execute queries for both 💎 and 🌀 markers
+    file_replacements = {}
+
+    for fm in filtered_fm:
+        replacements = []
+
+        # Push-back 💎 tap markers
+        for marker in fm.tap_markers:
+            db_path = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            validation_error = validate_dql(marker.raw_query)
+            if validation_error:
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {validation_error}",
+                    file=sys.stderr,
+                )
+                continue
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+
+            result = execute_tap_query(db_path, marker.raw_query)
+            if not result.success:
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {result.error}",
+                    file=sys.stderr,
+                )
+                continue
+
+            new_table_str = format_markdown_table(
+                result.columns, result.rows, compaction=compaction
+            )
+            new_table_lines = new_table_str.split("\n")
+
+            if table is None:
+                # Dangling tap marker: insert new table after marker/fence
+                insert_after = marker.end_line_number if marker.end_line_number else marker.line_number
+                insert_idx = insert_after  # 0-based index after marker line
+                new_lines = [""] + new_table_lines  # blank line before table
+                replacements.append((insert_idx, insert_idx - 1, new_lines))
+            else:
+                table_start_idx = table.start_line - 1
+                table_end_idx = table.end_line - 1
+                replacements.append((table_start_idx, table_end_idx, new_table_lines))
+
+        # Push-back 🌀 feed markers (conditionally bidirectional)
+        for marker in fm.feed_markers:
+            db_path = resolve_scope_path(marker.scope, fm.filepath, include_paths)
+
+            table, table_line_idx = find_adjacent_table(
+                fm.lines, marker.line_number, marker.end_line_number
+            )
+            if table is None:
+                continue
+
+            # Re-execute the marker's original SELECT query against mutated DB
+            result = execute_tap_query(db_path, marker.raw_query)
+            if not result.success:
+                print(
+                    f"Error [{fm.filepath}:{marker.line_number}]: {result.error}",
+                    file=sys.stderr,
+                )
+                continue
+
+            new_table_str = format_markdown_table(
+                result.columns, result.rows, compaction=compaction
+            )
+            new_table_lines = new_table_str.split("\n")
+
+            table_start_idx = table.start_line - 1
+            table_end_idx = table.end_line - 1
+            replacements.append((table_start_idx, table_end_idx, new_table_lines))
+
+        if replacements:
+            file_replacements[fm.filepath] = (fm, replacements)
+
+    # Write all modified files
+    for filepath, (fm, replacements) in file_replacements.items():
+        replacements.sort(key=lambda r: r[0], reverse=True)
+        lines = list(fm.lines)
+        for start_idx, end_idx, new_lines in replacements:
+            lines[start_idx:end_idx + 1] = new_lines
+
+        new_content = "\n".join(lines)
+        if fm.content.endswith("\n"):
+            new_content += "\n"
+        atomic_write(filepath, new_content)
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# ASCII art banner (009-ascii-art-help)
+# ---------------------------------------------------------------------------
+
+MDB_ASCII_ART = r"""
+▒▒██▓▓█▒▙                _ _
+▒▒██▓▓█▒▒  _ __ ___   __| | |__
+▒▒▒▒▒▒▒▒▒ | '_ ` _ \ / _` | '_ \
+▒███████▒ | | | | | | (_| | |_) |
+▒▓▓▓▓▓▓▓▒ |_| |_| |_|\__,_|_.__/
+""".strip()
+
+
+# ---------------------------------------------------------------------------
+# Main entry point (T001)
+# ---------------------------------------------------------------------------
+
+def main(argv=None):
+    """Entry point for the unified mdb CLI tool."""
+    parser = argparse.ArgumentParser(
+        prog="mdb",
+        description="Push and pull markdown tables with SQLite databases.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  mdb push                            pull 🌀, then push 💎
+  mdb push -i "docs/**"              restrict to docs/ (recursive)
+  mdb push -i "docs/*"               restrict to docs/ (shallow)
+  mdb pull "SELECT * FROM t"          query markdown data (CSV output)
+  mdb pull -i "docs/**" "SELECT ..."  restrict discovery to docs/
+  mdb push "INSERT INTO t ..."        mutate + push back
+  mdb push "scope 🌀 DELETE ..."      scoped mutate + push back
+  mdb pull "scope 💎 SELECT ..."      scoped query
+""",
+    )
+
+    subparsers = parser.add_subparsers(dest="subcommand")
+
+    # push subcommand
+    push_parser = subparsers.add_parser(
+        "push",
+        help="Process all markers: feed (🌀) first, then tap (💎). Optionally run a mutative query.",
+    )
+    push_parser.add_argument(
+        "-i", "--include",
+        type=str,
+        default=None,
+        help="Space-separated glob patterns to restrict file discovery (default: **)",
+    )
+    push_parser.add_argument(
+        "-c", "--compaction",
+        choices=["full", "fit"],
+        default="full",
+        help="Table compaction mode: full (no padding, default) or fit (aligned columns)",
+    )
+    push_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        default=False,
+        help="Show detailed output including skipped tables",
+    )
+    push_parser.add_argument(
+        "query",
+        nargs="?",
+        default=None,
+        help='Optional: DML query or "<scope_name> 🌀 <dml_query>"',
+    )
+
+    # pull subcommand (027-pull-query: query-based interface)
+    pull_parser = subparsers.add_parser(
+        "pull",
+        help="Query markdown table data via SQL",
+    )
+    pull_parser.add_argument(
+        "-i", "--include",
+        type=str,
+        default=None,
+        help="Space-separated glob patterns to restrict file discovery (default: **)",
+    )
+    pull_parser.add_argument(
+        "query",
+        help='SQL query or "<scope_name> 💎 <sql_query>"',
+    )
+
+    # init subcommand (014-init-command, 045-init-skill-path)
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Install the mdb skill into the current project",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  mdb init                       write to .mdb/skills/mdb/SKILL.md (default)
+  mdb init .claude/skills        write to .claude/skills/mdb/SKILL.md
+  mdb init path/to/skills        write to path/to/skills/mdb/SKILL.md
+  mdb init --force               overwrite without prompting
+""",
+    )
+    init_parser.add_argument(
+        "dir",
+        nargs="?",
+        default=".mdb/skills",
+        metavar="DIR",
+        help="Parent directory for the skill file (default: .mdb/skills). "
+             "The tool writes to DIR/mdb/SKILL.md.",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing skill file without prompting",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.subcommand is None:
+        parser.print_help()
+        return 2
+
+    # Init subcommand: dispatch BEFORE resolve_paths() since init
+    # does not use path resolution (014-init-command)
+    if args.subcommand == "init":
+        print(MDB_ASCII_ART)
+        print()
+        from mdb.init import init_skill
+        result = init_skill(target_dir=args.dir, force=args.force)
+        return 0 if result.success else 1
+
+    # Pull subcommand: dispatch BEFORE resolve_paths() since pull
+    # uses its own discovery logic (027-pull-query)
+    if args.subcommand == "pull":
+        if not args.query.strip():
+            print("Error: Query argument is empty", file=sys.stderr)
+            return 1
+        return _run_pull_with_tap_query(args.query, args.include, os.getcwd())
+
+    # Push subcommand: uses its own discovery logic (028-push-query)
+    if args.subcommand == "push":
+        # Empty query validation (FR-011)
+        if args.query is not None and args.query.strip() == "":
+            print("Error: Query argument is empty", file=sys.stderr)
+            return 1
+
+        if args.query is not None:
+            # Push-query mode: parse scope, validate DML, run pipeline
+            scope_name, sql_query = parse_pre_push_feed_query(args.query)
+            dml_error = validate_dml(sql_query)
+            if dml_error:
+                print(f"Error: {dml_error}", file=sys.stderr)
+                return 1
+            return _run_push_with_feed_query(scope_name, sql_query, args.include, args.compaction, os.getcwd(), verbose=args.verbose)
+        else:
+            # Standard push: discover files, run pull-then-push
+            filepaths = _discover_files(args.include)
+
+            if not filepaths:
+                print("No markdown files found")
+                return 0
+
+            normalized_include = _normalize_include_for_hash(args.include)
+            return _run_push(filepaths, compaction=args.compaction, verbose=args.verbose, include_paths=normalized_include)
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())