officecat 0.1.0__tar.gz

officecat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff mypy
+      - run: ruff check officecat/
+      - run: mypy officecat/ --ignore-missing-imports
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+          - macos-latest
+          - windows-latest
+          - windows-11-arm
+        python-version: ["3.10", "3.12", "3.13"]
+        exclude:
+          - os: windows-11-arm
+            python-version: "3.10"
+          - os: ubuntu-24.04-arm
+            python-version: "3.10"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .
+      - run: officecat --help
+      - run: officecat tests/fixtures/sample.csv --plain
+      - run: officecat tests/fixtures/sample.docx --plain
+      - run: officecat tests/fixtures/sample.pptx --plain
+      - run: officecat tests/fixtures/sample.xlsx --plain
+      - run: officecat tests/fixtures/sample.tsv --plain
+      - run: officecat tests/fixtures/sample.csv --json
+      - run: officecat tests/fixtures/empty.docx --plain

officecat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release & Publish
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Get version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag exists
+        id: check
+        run: |
+          if git rev-parse "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create release
+        if: steps.check.outputs.exists == 'false'
+        run: |
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "${{ steps.version.outputs.tag }}" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

officecat-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution
+*.tar.gz
+*.zip
+
+# Environment
+.env
+.env.*
+dist/

officecat-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: officecat
+Version: 0.1.0
+Summary: View Office files in the terminal
+Project-URL: Homepage, https://github.com/mubbie/officecat
+Project-URL: Repository, https://github.com/mubbie/officecat
+Project-URL: Issues, https://github.com/mubbie/officecat/issues
+Author: Mubbie Idoko
+License: MIT
+Keywords: cli,csv,docx,office,pptx,terminal,viewer,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: python-calamine>=0.2
+Requires-Dist: python-docx>=1.0
+Requires-Dist: python-pptx>=0.6
+Requires-Dist: rich
+Requires-Dist: textual>=0.50
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# officecat 🐱
+
+A CLI tool to view Office files in the terminal. Think `cat` but for `.docx`, `.pptx`, `.xlsx`, `.csv`, and `.tsv` files.
+
+Every supported format is converted to markdown internally, then rendered through a single unified pipeline.
+
+## Installation
+
+```bash
+pip install officecat
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mubbie/officecat.git
+cd officecat
+pip install -e .
+```
+
+## Usage
+
+```bash
+officecat report.docx              # colored formatted output (default)
+officecat budget.xlsx              # spreadsheet as markdown table
+officecat slides.pptx              # presentation content
+officecat data.csv                 # CSV and TSV
+officecat report.docx --tui        # interactive full-screen viewer
+officecat budget.xlsx | head       # plain text (auto-detected pipe)
+officecat slides.pptx --json       # JSON output
+```
+
+### Output Modes
+
+- **Rich** (default): Colored, formatted output to stdout. Works with `less -R`.
+- **TUI** (`--tui`): Full-screen interactive viewer with scrolling.
+- **Plain** (auto when piped, or `--plain`): Raw markdown for piping to `grep`, `head`, `awk`.
+- **JSON** (`--json`): `{"source": "...", "markdown": "..."}` for scripting.
+
+### Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--tui` | `-t` | Interactive full-screen viewer |
+| `--plain` | `-p` | Raw markdown text, no colors |
+| `--json` | `-j` | JSON output |
+| `--head N` | `-n N` | Show first N lines |
+| `--sheet S` | `-s S` | Select sheet by name or 1-based index (xlsx only) |
+| `--slide N` | | Show only slide N (pptx only) |
+| `--headers N` | `-h N` | Promote row N as headers (xlsx/csv, default: 1, 0 to disable) |
+| `--all` | `-a` | Disable the default 500-row cap |
+
+### TUI Key Bindings
+
+| Key | Action |
+|---|---|
+| `q` | Quit |
+| `Up` / `Down` | Scroll |
+| `PgUp` / `PgDn` | Page scroll |
+| `Home` / `End` | Jump to top/bottom |
+
+### Examples
+
+```bash
+# Quick view of a document
+officecat report.docx
+
+# Browse interactively
+officecat report.docx --tui
+
+# Specific sheet
+officecat budget.xlsx --sheet "Q4 Summary"
+
+# Specific slide
+officecat deck.pptx --slide 3
+
+# First 10 lines
+officecat budget.xlsx --head 10
+
+# JSON output
+officecat report.docx --json | jq '.markdown'
+
+# Pipe to grep
+officecat data.xlsx --plain | grep "revenue"
+```
+
+## Supported Formats
+
+- Word (.docx): headings, paragraphs, lists, tables in document order
+- PowerPoint (.pptx): slides, shapes, images, speaker notes, hidden slides
+- Excel (.xlsx): all sheets, row cap, header promotion
+- CSV (.csv): auto-delimited
+- TSV (.tsv): tab-delimited
+
+Legacy binary formats (`.doc`, `.ppt`, `.xls`) show a conversion hint.
+
+## Known Limitations
+
+- All content is rendered as markdown. Spreadsheet tables are markdown tables, not interactive grids.
+- DOCX list detection is style-name-based and may miss custom list styles.
+- PPTX grouped shapes and embedded tables show as placeholders.
+- PPTX charts and SmartArt are not extracted.
+- XLSX formulas show cached/computed values, not formula strings.
+- Large spreadsheets are capped at 500 rows by default. Use `--all` to show everything.
+- TUI enforces a 1000-line cap with `--all` for performance. Use `--plain` for full output.
+- No decryption of password-protected files.
+- Legacy binary formats (.doc, .ppt, .xls) are not supported.

officecat-0.1.0/README.md

@@ -0,0 +1,107 @@
+# officecat 🐱
+
+A CLI tool to view Office files in the terminal. Think `cat` but for `.docx`, `.pptx`, `.xlsx`, `.csv`, and `.tsv` files.
+
+Every supported format is converted to markdown internally, then rendered through a single unified pipeline.
+
+## Installation
+
+```bash
+pip install officecat
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mubbie/officecat.git
+cd officecat
+pip install -e .
+```
+
+## Usage
+
+```bash
+officecat report.docx              # colored formatted output (default)
+officecat budget.xlsx              # spreadsheet as markdown table
+officecat slides.pptx              # presentation content
+officecat data.csv                 # CSV and TSV
+officecat report.docx --tui        # interactive full-screen viewer
+officecat budget.xlsx | head       # plain text (auto-detected pipe)
+officecat slides.pptx --json       # JSON output
+```
+
+### Output Modes
+
+- **Rich** (default): Colored, formatted output to stdout. Works with `less -R`.
+- **TUI** (`--tui`): Full-screen interactive viewer with scrolling.
+- **Plain** (auto when piped, or `--plain`): Raw markdown for piping to `grep`, `head`, `awk`.
+- **JSON** (`--json`): `{"source": "...", "markdown": "..."}` for scripting.
+
+### Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--tui` | `-t` | Interactive full-screen viewer |
+| `--plain` | `-p` | Raw markdown text, no colors |
+| `--json` | `-j` | JSON output |
+| `--head N` | `-n N` | Show first N lines |
+| `--sheet S` | `-s S` | Select sheet by name or 1-based index (xlsx only) |
+| `--slide N` | | Show only slide N (pptx only) |
+| `--headers N` | `-h N` | Promote row N as headers (xlsx/csv, default: 1, 0 to disable) |
+| `--all` | `-a` | Disable the default 500-row cap |
+
+### TUI Key Bindings
+
+| Key | Action |
+|---|---|
+| `q` | Quit |
+| `Up` / `Down` | Scroll |
+| `PgUp` / `PgDn` | Page scroll |
+| `Home` / `End` | Jump to top/bottom |
+
+### Examples
+
+```bash
+# Quick view of a document
+officecat report.docx
+
+# Browse interactively
+officecat report.docx --tui
+
+# Specific sheet
+officecat budget.xlsx --sheet "Q4 Summary"
+
+# Specific slide
+officecat deck.pptx --slide 3
+
+# First 10 lines
+officecat budget.xlsx --head 10
+
+# JSON output
+officecat report.docx --json | jq '.markdown'
+
+# Pipe to grep
+officecat data.xlsx --plain | grep "revenue"
+```
+
+## Supported Formats
+
+- Word (.docx): headings, paragraphs, lists, tables in document order
+- PowerPoint (.pptx): slides, shapes, images, speaker notes, hidden slides
+- Excel (.xlsx): all sheets, row cap, header promotion
+- CSV (.csv): auto-delimited
+- TSV (.tsv): tab-delimited
+
+Legacy binary formats (`.doc`, `.ppt`, `.xls`) show a conversion hint.
+
+## Known Limitations
+
+- All content is rendered as markdown. Spreadsheet tables are markdown tables, not interactive grids.
+- DOCX list detection is style-name-based and may miss custom list styles.
+- PPTX grouped shapes and embedded tables show as placeholders.
+- PPTX charts and SmartArt are not extracted.
+- XLSX formulas show cached/computed values, not formula strings.
+- Large spreadsheets are capped at 500 rows by default. Use `--all` to show everything.
+- TUI enforces a 1000-line cap with `--all` for performance. Use `--plain` for full output.
+- No decryption of password-protected files.
+- Legacy binary formats (.doc, .ppt, .xls) are not supported.

officecat-0.1.0/officecat/__init__.py

@@ -0,0 +1,3 @@
+"""officecat — View Office files in the terminal."""
+
+__version__ = "0.1.0"

officecat-0.1.0/officecat/cli.py

@@ -0,0 +1,152 @@
+"""CLI entry point — read and render pipeline."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+app = typer.Typer(add_completion=False)
+
+# Formats that support tabular flags
+_TABULAR_FMTS = {"xlsx", "csv"}
+
+
+@app.command()
+def run(
+    file: Annotated[
+        Path, typer.Argument(help="File to view.")
+    ],
+    tui: Annotated[
+        bool, typer.Option("--tui", "-t", help="Interactive viewer.")
+    ] = False,
+    plain: Annotated[
+        bool, typer.Option("--plain", "-p", help="Raw markdown, no colors.")
+    ] = False,
+    json: Annotated[
+        bool, typer.Option("--json", "-j", help="JSON output.")
+    ] = False,
+    head: Annotated[
+        Optional[int], typer.Option("--head", "-n", help="Show first N lines.")
+    ] = None,
+    sheet: Annotated[
+        Optional[str],
+        typer.Option("--sheet", "-s", help="Sheet by name or index (xlsx)."),
+    ] = None,
+    slide: Annotated[
+        Optional[int],
+        typer.Option("--slide", help="Show only slide N (pptx)."),
+    ] = None,
+    headers: Annotated[
+        int,
+        typer.Option("--headers", "-h", help="Row N as headers (default: 1)."),
+    ] = 1,
+    show_all: Annotated[
+        bool, typer.Option("--all", "-a", help="Disable the row cap.")
+    ] = False,
+) -> None:
+    """View Office files in the terminal.
+
+    Supports .docx, .pptx, .xlsx, .csv, and .tsv files.
+    """
+    # ── Validate output flags ──
+    output_flags = sum([tui, plain, json])
+    if output_flags > 1:
+        _error("--tui, --plain, and --json are mutually exclusive.")
+
+    if not file.exists():
+        _error(f"File '{file}' not found.")
+
+    # ── Validate format ──
+    from officecat.detect import detect_format
+    fmt = detect_format(file)
+
+    # ── Validate format-specific flags ──
+    fmt_name = fmt.value
+    if sheet is not None and fmt_name not in ("xlsx", "csv"):
+        _error("--sheet is only valid for xlsx, csv, and tsv files.")
+    if slide is not None and fmt_name != "pptx":
+        _error("--slide is only valid for pptx files.")
+    if headers != 1 and fmt_name not in ("xlsx", "csv"):
+        _error("--headers is only valid for xlsx, csv, and tsv files.")
+
+    # ── Mode resolution ──
+    if json:
+        mode = "json"
+    elif plain:
+        mode = "plain"
+    elif tui:
+        mode = "tui"
+    elif sys.stdout.isatty():
+        mode = "rich"
+    else:
+        mode = "plain"
+
+    # ── Build reader options ──
+    reader_opts: dict = {}
+    if fmt_name in ("xlsx", "csv"):
+        reader_opts["headers"] = headers
+        reader_opts["show_all"] = show_all
+        if sheet is not None:
+            reader_opts["sheet"] = sheet
+    if fmt_name == "pptx" and slide is not None:
+        reader_opts["slide"] = slide
+    if head is not None and fmt_name in ("docx", "pptx"):
+        reader_opts["head"] = head
+
+    # For tabular formats, pass head as row limit to reader
+    if head is not None and fmt_name in ("xlsx", "csv"):
+        reader_opts["head"] = head
+
+    # ── Convert (with spinner for TTY) ──
+    from officecat.readers import convert
+
+    if sys.stderr.isatty() and mode != "tui":
+        from rich.console import Console
+        console = Console(stderr=True)
+        with console.status(f"Reading {file.name}...", spinner="dots"):
+            markdown = convert(file, **reader_opts)
+    else:
+        markdown = convert(file, **reader_opts)
+
+    if not markdown or not markdown.strip():
+        print("Document is empty.")
+        return
+
+    # ── TUI guardrail for large tables ──
+    if mode == "tui" and show_all and fmt_name in ("xlsx", "csv"):
+        line_count = markdown.count("\n")
+        if line_count > 1000:
+            # Truncate to ~1000 lines for TUI performance
+            lines = markdown.splitlines()
+            markdown = "\n".join(lines[:1000])
+            markdown += (
+                "\n\n*TUI limited to first 1000 lines."
+                " Use --plain with --all to view everything.*"
+            )
+
+    # ── Render ──
+    if mode == "tui":
+        from officecat.tui.app import OfficeCatApp
+        tui_app = OfficeCatApp(source=str(file), markdown=markdown)
+        tui_app.run()
+    elif mode == "rich":
+        from officecat.renderers.rich import render
+        render(markdown, head=head)
+    elif mode == "json":
+        from officecat.renderers.json_ import render
+        render(str(file), markdown)
+    else:
+        from officecat.renderers.plain import render
+        render(markdown, head=head)
+
+
+def _error(msg: str) -> None:
+    print(f"Error: {msg}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def main() -> None:
+    app()

officecat-0.1.0/officecat/detect.py

@@ -0,0 +1,58 @@
+"""File type detection and validation."""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+from pathlib import Path
+
+
+class FileFormat(Enum):
+    DOCX = "docx"
+    PPTX = "pptx"
+    XLSX = "xlsx"
+    CSV = "csv"
+
+
+EXTENSION_MAP: dict[str, FileFormat] = {
+    ".docx": FileFormat.DOCX,
+    ".pptx": FileFormat.PPTX,
+    ".xlsx": FileFormat.XLSX,
+    ".csv": FileFormat.CSV,
+    ".tsv": FileFormat.CSV,
+}
+
+LEGACY_FORMATS: dict[str, str] = {
+    ".doc": "docx",
+    ".ppt": "pptx",
+    ".xls": "xlsx",
+}
+
+SUPPORTED_EXTENSIONS = ", ".join(sorted(EXTENSION_MAP.keys()))
+
+
+def detect_format(path: Path) -> FileFormat:
+    """Detect file format from extension. Exits on error."""
+    ext = path.suffix.lower()
+
+    if ext in LEGACY_FORMATS:
+        target = LEGACY_FORMATS[ext]
+        print(
+            f"Error: Legacy binary format ({ext}) is not supported.\n"
+            f"Convert to .{target} using LibreOffice: "
+            f"libreoffice --headless --convert-to {target} {path.name}\n"
+            f"Or use specialized tools like antiword or catdoc.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    fmt = EXTENSION_MAP.get(ext)
+    if fmt is None:
+        print(
+            f"Error: Unsupported file type '{ext}'. "
+            f"Supported: {SUPPORTED_EXTENSIONS}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    return fmt

officecat-0.1.0/officecat/readers/__init__.py

@@ -0,0 +1,31 @@
+"""Reader dispatch — routes a file path to the correct format reader."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from officecat.detect import FileFormat, detect_format
+
+
+def convert(path: Path, **options) -> str:
+    """Convert a file to a markdown string.
+
+    Args:
+        path: Path to the file.
+        **options: Format-specific options (head, sheet, slide, headers, show_all).
+
+    Returns:
+        A markdown string.
+    """
+    fmt = detect_format(path)
+
+    if fmt == FileFormat.CSV:
+        from officecat.readers.csv_ import to_markdown
+    elif fmt == FileFormat.XLSX:
+        from officecat.readers.xlsx import to_markdown
+    elif fmt == FileFormat.DOCX:
+        from officecat.readers.docx import to_markdown
+    elif fmt == FileFormat.PPTX:
+        from officecat.readers.pptx import to_markdown
+
+    return to_markdown(path, **options)

officecat-0.1.0/officecat/readers/csv_.py

@@ -0,0 +1,100 @@
+"""CSV/TSV to markdown reader."""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+DEFAULT_ROW_CAP = 500
+
+
+def _escape_pipe(text: str) -> str:
+    """Escape pipe characters for markdown tables."""
+    return text.replace("|", "\\|")
+
+
+def _col_letter(index: int) -> str:
+    """Convert 0-based index to Excel-style letter (A, B, ... Z, AA, ...)."""
+    result = ""
+    i = index
+    while True:
+        result = chr(65 + i % 26) + result
+        i = i // 26 - 1
+        if i < 0:
+            break
+    return result
+
+
+def to_markdown(
+    path: Path,
+    *,
+    head: int | None = None,
+    headers: int = 1,
+    show_all: bool = False,
+    **_kwargs,
+) -> str:
+    """Convert a CSV/TSV file to a markdown table string."""
+    is_tsv = path.suffix.lower() == ".tsv"
+
+    with open(path, newline="", encoding="utf-8-sig") as f:
+        if is_tsv:
+            delimiter = "\t"
+        else:
+            first_line = f.readline()
+            f.seek(0)
+            # Only sniff if comma-split yields a single column
+            if len(first_line.split(",")) <= 1:
+                try:
+                    dialect = csv.Sniffer().sniff(first_line)
+                    delimiter = dialect.delimiter
+                except csv.Error:
+                    delimiter = ","
+            else:
+                delimiter = ","
+
+        reader = csv.reader(f, delimiter=delimiter)
+
+        header_row: list[str] = []
+        rows: list[list[str]] = []
+        total_rows = 0
+        row_cap = head if head is not None else (None if show_all else DEFAULT_ROW_CAP)
+
+        for i, row in enumerate(reader, start=1):
+            if headers > 0 and i == headers:
+                header_row = [_escape_pipe(c) for c in row]
+                continue
+
+            total_rows += 1
+            if row_cap is not None and len(rows) >= row_cap:
+                continue  # keep counting total_rows
+            rows.append([_escape_pipe(c) for c in row])
+
+    if not header_row and rows:
+        col_count = max(len(r) for r in rows)
+        header_row = [_col_letter(i) for i in range(col_count)]
+
+    if not header_row and not rows:
+        return ""
+
+    return _build_table(header_row, rows, total_rows)
+
+
+def _build_table(
+    headers: list[str], rows: list[list[str]], total_rows: int
+) -> str:
+    """Build a markdown pipe table from headers and rows."""
+    col_count = len(headers)
+    lines: list[str] = []
+
+    lines.append("| " + " | ".join(headers) + " |")
+    lines.append("| " + " | ".join(["---"] * col_count) + " |")
+
+    for row in rows:
+        padded = row + [""] * (col_count - len(row))
+        lines.append("| " + " | ".join(padded[:col_count]) + " |")
+
+    if total_rows > len(rows):
+        lines.append("")
+        lines.append(f"*Showing {len(rows)} of {total_rows:,} rows.*")
+
+    return "\n".join(lines)

officecat-0.1.0/officecat/readers/docx.py

@@ -0,0 +1,120 @@
+"""Word (.docx) to markdown reader."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def _classify_style(style_name: str | None) -> str | None:
+    """Map a docx paragraph style name to a markdown heading prefix or None."""
+    if style_name is None:
+        return None
+    name = style_name.lower()
+    if "heading 1" in name or name == "title":
+        return "# "
+    if "heading 2" in name:
+        return "## "
+    if "heading 3" in name:
+        return "### "
+    if "heading 4" in name or "heading 5" in name or "heading 6" in name:
+        return "#### "
+    if "list" in name:
+        return "- "
+    return None
+
+
+def _escape_pipe(text: str) -> str:
+    return text.replace("|", "\\|")
+
+
+def _table_to_markdown(table) -> str:
+    """Convert a docx Table object to a markdown pipe table."""
+    rows: list[list[str]] = []
+    for row in table.rows:
+        cells = row.cells
+        row_text: list[str] = []
+        prev_tc = None
+        for cell in cells:
+            if prev_tc is not None and cell._tc is prev_tc:
+                continue
+            row_text.append(_escape_pipe(cell.text.strip()))
+            prev_tc = cell._tc
+        rows.append(row_text)
+
+    if not rows:
+        return ""
+
+    col_count = max(len(r) for r in rows)
+    headers = rows[0] + [""] * (col_count - len(rows[0]))
+
+    lines: list[str] = []
+    lines.append("| " + " | ".join(headers[:col_count]) + " |")
+    lines.append("| " + " | ".join(["---"] * col_count) + " |")
+
+    for row in rows[1:]:
+        padded = row + [""] * (col_count - len(row))
+        lines.append("| " + " | ".join(padded[:col_count]) + " |")
+
+    return "\n".join(lines)
+
+
+def to_markdown(path: Path, *, head: int | None = None, **_kwargs) -> str:
+    """Convert a docx file to markdown, preserving paragraph/table order."""
+    from docx import Document
+    from docx.opc.exceptions import PackageNotFoundError
+    from docx.table import Table as DocxTable
+    from docx.text.paragraph import Paragraph
+
+    try:
+        doc = Document(str(path))
+    except PackageNotFoundError:
+        print(
+            f"Error: '{path.name}' appears to be corrupt or invalid.",
+            file=sys.stderr,
+        )
+        raise SystemExit(3)
+    except Exception as e:
+        msg = str(e).lower()
+        if "password" in msg or "encrypt" in msg:
+            print(
+                f"Error: '{path.name}' is password-protected. "
+                f"officecat cannot open encrypted files.",
+                file=sys.stderr,
+            )
+            raise SystemExit(3)
+        raise
+
+    blocks: list[str] = []
+    block_count = 0
+
+    # Walk body children to preserve interleaved order
+    for child in doc.element.body:
+        tag = child.tag.split("}")[-1] if "}" in child.tag else child.tag
+
+        if tag == "p":
+            para = Paragraph(child, doc)
+            text = para.text.strip()
+            if not text:
+                continue
+
+            prefix = _classify_style(para.style.name if para.style else None)
+            if prefix:
+                blocks.append(f"{prefix}{text}")
+            else:
+                blocks.append(text)
+
+            block_count += 1
+            if head is not None and block_count >= head:
+                break
+
+        elif tag == "tbl":
+            table = DocxTable(child, doc)
+            md_table = _table_to_markdown(table)
+            if md_table:
+                blocks.append(md_table)
+                block_count += 1
+                if head is not None and block_count >= head:
+                    break
+
+    return "\n\n".join(blocks)

officecat-0.1.0/officecat/readers/pptx.py

@@ -0,0 +1,106 @@
+"""PowerPoint (.pptx) to markdown reader."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def to_markdown(
+    path: Path,
+    *,
+    head: int | None = None,
+    slide: int | None = None,
+    **_kwargs,
+) -> str:
+    """Convert a pptx file to markdown."""
+    from pptx import Presentation
+    from pptx.enum.shapes import MSO_SHAPE_TYPE
+    from pptx.exc import PackageNotFoundError
+
+    try:
+        prs = Presentation(str(path))
+    except PackageNotFoundError:
+        print(
+            f"Error: '{path.name}' appears to be corrupt or invalid.",
+            file=sys.stderr,
+        )
+        raise SystemExit(3)
+    except Exception as e:
+        msg = str(e).lower()
+        if "password" in msg or "encrypt" in msg:
+            print(
+                f"Error: '{path.name}' is password-protected. "
+                f"officecat cannot open encrypted files.",
+                file=sys.stderr,
+            )
+            raise SystemExit(3)
+        raise
+
+    total_slides = len(prs.slides)
+
+    if slide is not None:
+        if slide < 1 or slide > total_slides:
+            print(
+                f"Error: Slide {slide} not found. "
+                f"Document has {total_slides} slides.",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+
+    sections: list[str] = []
+
+    for i, sld in enumerate(prs.slides, start=1):
+        if slide is not None and i != slide:
+            continue
+
+        # Check if slide is hidden
+        show_attr = sld._element.get("show")
+        is_hidden = show_attr == "0"
+
+        title_shape = sld.shapes.title
+        title_text = title_shape.text.strip() if title_shape else None
+        title_shape_id = title_shape.shape_id if title_shape else None
+
+        hidden_tag = " (Hidden)" if is_hidden else ""
+        if title_text:
+            heading = f"## Slide {i}{hidden_tag}: {title_text}"
+        else:
+            heading = f"## Slide {i}{hidden_tag}"
+
+        body_lines: list[str] = [heading, ""]
+
+        for shape in sld.shapes:
+            if title_shape_id is not None and shape.shape_id == title_shape_id:
+                continue
+
+            st = shape.shape_type
+            if st == MSO_SHAPE_TYPE.PICTURE:
+                body_lines.append(f"*[Image: {shape.name}]*")
+            elif st == MSO_SHAPE_TYPE.GROUP:
+                body_lines.append("*[Grouped content]*")
+            elif hasattr(shape, "has_table") and shape.has_table:
+                tbl = shape.table
+                rows = len(tbl.rows)
+                cols = len(tbl.columns)
+                body_lines.append(f"*[Table: {rows}x{cols}]*")
+            elif shape.has_text_frame:
+                text = shape.text_frame.text.strip()
+                if text:
+                    body_lines.append(text)
+
+        # Notes
+        if sld.has_notes_slide:
+            notes_text = sld.notes_slide.notes_text_frame.text.strip()
+            if notes_text:
+                body_lines.append("")
+                body_lines.append(f"> **Notes:** {notes_text}")
+
+        sections.append("\n".join(body_lines))
+
+        if slide is not None:
+            break
+        if head is not None and len(sections) >= head:
+            break
+
+    return "\n\n---\n\n".join(sections)

officecat-0.1.0/officecat/readers/xlsx.py

@@ -0,0 +1,144 @@
+"""Excel (.xlsx) to markdown reader using python-calamine."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+DEFAULT_ROW_CAP = 500
+
+
+def _escape_pipe(text: str) -> str:
+    return text.replace("|", "\\|")
+
+
+def _col_letter(index: int) -> str:
+    result = ""
+    i = index
+    while True:
+        result = chr(65 + i % 26) + result
+        i = i // 26 - 1
+        if i < 0:
+            break
+    return result
+
+
+def _format_cell(value: object) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, float) and value == int(value):
+        return str(int(value))
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    return str(value)
+
+
+def to_markdown(
+    path: Path,
+    *,
+    head: int | None = None,
+    sheet: str | None = None,
+    headers: int = 1,
+    show_all: bool = False,
+    **_kwargs,
+) -> str:
+    """Convert an xlsx file to markdown tables."""
+    from python_calamine import CalamineWorkbook
+
+    try:
+        wb = CalamineWorkbook.from_path(str(path))
+    except Exception as e:
+        msg = str(e).lower()
+        if "password" in msg or "encrypt" in msg:
+            print(
+                f"Error: '{path.name}' is password-protected. "
+                f"officecat cannot open encrypted files.",
+                file=sys.stderr,
+            )
+            raise SystemExit(3)
+        if "zip" in msg or "invalid" in msg or "corrupt" in msg:
+            print(
+                f"Error: '{path.name}' appears to be corrupt or invalid.",
+                file=sys.stderr,
+            )
+            raise SystemExit(3)
+        raise
+
+    all_sheet_names = wb.sheet_names
+
+    if sheet is not None:
+        # Try as 1-based index
+        try:
+            idx = int(sheet)
+            if 1 <= idx <= len(all_sheet_names):
+                sheets_to_read = [all_sheet_names[idx - 1]]
+            else:
+                print(
+                    f"Error: Sheet index {idx} out of range. "
+                    f"Available: {', '.join(all_sheet_names)}",
+                    file=sys.stderr,
+                )
+                raise SystemExit(1)
+        except ValueError:
+            if sheet in all_sheet_names:
+                sheets_to_read = [sheet]
+            else:
+                print(
+                    f"Error: Sheet '{sheet}' not found. "
+                    f"Available: {', '.join(all_sheet_names)}",
+                    file=sys.stderr,
+                )
+                raise SystemExit(1)
+    else:
+        sheets_to_read = list(all_sheet_names)
+
+    row_cap = head if head is not None else (None if show_all else DEFAULT_ROW_CAP)
+    sections: list[str] = []
+
+    for sheet_name in sheets_to_read:
+        ws = wb.get_sheet_by_name(sheet_name)
+        header_row: list[str] = []
+        data_rows: list[list[str]] = []
+        total_rows = 0
+
+        for i, row in enumerate(ws.iter_rows(), start=1):
+            if headers > 0 and i == headers:
+                header_row = [_escape_pipe(_format_cell(c)) for c in row]
+                continue
+
+            total_rows += 1
+            if row_cap is not None and len(data_rows) >= row_cap:
+                continue
+            data_rows.append([_escape_pipe(_format_cell(c)) for c in row])
+
+        if not header_row:
+            if data_rows:
+                col_count = max(len(r) for r in data_rows)
+            else:
+                col_count = 0
+            header_row = [_col_letter(i) for i in range(col_count)]
+
+        section_lines: list[str] = [f"## Sheet: {sheet_name}", ""]
+
+        if not header_row:
+            section_lines.append("*Empty sheet.*")
+        else:
+            col_count = len(header_row)
+            section_lines.append("| " + " | ".join(header_row) + " |")
+            section_lines.append("| " + " | ".join(["---"] * col_count) + " |")
+
+            for row in data_rows:
+                padded = row + [""] * (col_count - len(row))
+                section_lines.append(
+                    "| " + " | ".join(padded[:col_count]) + " |"
+                )
+
+            if total_rows > len(data_rows):
+                section_lines.append("")
+                section_lines.append(
+                    f"*Showing {len(data_rows)} of {total_rows:,} rows.*"
+                )
+
+        sections.append("\n".join(section_lines))
+
+    return "\n\n---\n\n".join(sections)

officecat-0.1.0/officecat/renderers/json_.py

@@ -0,0 +1,11 @@
+"""JSON renderer."""
+
+from __future__ import annotations
+
+import json
+
+
+def render(source: str, markdown_text: str) -> None:
+    """Print JSON with source and markdown keys."""
+    output = {"source": source, "markdown": markdown_text}
+    print(json.dumps(output, indent=2))

officecat-0.1.0/officecat/renderers/plain.py

@@ -0,0 +1,12 @@
+"""Plain text renderer — raw markdown via print()."""
+
+from __future__ import annotations
+
+
+def render(markdown_text: str, head: int | None = None) -> None:
+    """Print raw markdown text to stdout."""
+    lines = markdown_text.splitlines()
+    if head is not None:
+        lines = lines[:head]
+    for line in lines:
+        print(line)

officecat-0.1.0/officecat/renderers/rich.py

@@ -0,0 +1,24 @@
+"""Rich colored markdown renderer."""
+
+from __future__ import annotations
+
+import sys
+
+
+def render(markdown_text: str, head: int | None = None) -> None:
+    """Print colored markdown to stdout."""
+    if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    from rich.console import Console
+    from rich.markdown import Markdown
+
+    text = markdown_text
+    if head is not None:
+        text = "\n".join(text.splitlines()[:head])
+
+    console = Console()
+    console.print(Markdown(text))

officecat-0.1.0/officecat/tui/app.py

@@ -0,0 +1,34 @@
+"""Textual TUI app for officecat — full-screen markdown viewer."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.widgets import Footer, Header, Markdown
+
+
+class OfficeCatApp(App):
+    """Interactive terminal viewer for Office files."""
+
+    CSS = """
+    #md-scroll {
+        height: 1fr;
+    }
+    """
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, source: str, markdown: str, **kwargs: object) -> None:
+        self._source = source
+        self._markdown = markdown
+        super().__init__(**kwargs)
+        self.title = f"officecat — {self._source}"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with VerticalScroll(id="md-scroll"):
+            yield Markdown(self._markdown, id="md-view")
+        yield Footer()

officecat-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "officecat"
+version = "0.1.0"
+description = "View Office files in the terminal"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Mubbie Idoko"},
+]
+keywords = ["office", "cli", "docx", "xlsx", "pptx", "csv", "terminal", "viewer"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9",
+    "textual>=0.50",
+    "python-docx>=1.0",
+    "python-pptx>=0.6",
+    "python-calamine>=0.2",
+    "rich",
+]
+
+[project.urls]
+Homepage = "https://github.com/mubbie/officecat"
+Repository = "https://github.com/mubbie/officecat"
+Issues = "https://github.com/mubbie/officecat/issues"
+
+[project.scripts]
+officecat = "officecat.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

officecat-0.1.0/tests/fixtures/corrupt.xlsx

@@ -0,0 +1 @@
+not a real xlsx

officecat-0.1.0/tests/fixtures/sample.csv

@@ -0,0 +1,6 @@
+Name,Age,City,Role,Salary
+Alice,30,New York,Engineer,120000
+Bob,25,Los Angeles,Designer,95000
+Charlie,35,Chicago,Manager,140000
+Diana,28,Seattle,Engineer,125000
+Eve,32,Boston,Analyst,105000

officecat-0.1.0/tests/fixtures/sample.tsv

@@ -0,0 +1,4 @@
+Name	Age	City	Role	Salary
+Alice	30	New York	Engineer	120000
+Bob	25	Los Angeles	Designer	95000
+Charlie	35	Chicago	Manager	140000