vantage-md 0.4.1__tar.gz

vantage_md-0.4.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

vantage_md-0.4.1/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+Brief description of the changes.
+
+## Motivation
+
+Why is this change needed?
+
+## Changes
+
+- List of changes made
+
+## Testing
+
+- [ ] Ran `just check` (format, lint, typecheck, tests)
+- [ ] Added/updated tests for new functionality
+- [ ] Tested manually in browser
+
+## Screenshots
+
+If applicable, add screenshots of UI changes.

vantage_md-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  secrets-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: TruffleHog secret scan
+        uses: trufflesecurity/trufflehog@main
+        with:
+          extra_args: --only-verified
+
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # setuptools-scm needs tags
+
+      - name: Install mise
+        uses: jdx/mise-action@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python dependencies
+        run: uv sync
+
+      - name: Build vantage-md package
+        run: cd packages/vantage-md && npm ci && npx tsup
+
+      - name: Install Node dependencies
+        run: cd frontend && npm ci
+
+      - name: Lint Python
+        run: uv run ruff check .
+
+      - name: Format check Python
+        run: uv run ruff format --check .
+
+      - name: Type check Python
+        run: uv run basedpyright src/ --warnings || true
+
+      - name: Lint JavaScript
+        run: cd frontend && npm run lint
+
+      - name: Type check TypeScript
+        run: cd frontend && npx tsc --noEmit
+
+      - name: Test Python
+        run: uv run pytest tests/ -v
+
+      - name: Test JavaScript
+        run: cd frontend && npm run test
+
+      - name: Build frontend
+        run: cd frontend && npm run build

vantage_md-0.4.1/.github/workflows/publish.yml

@@ -0,0 +1,187 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to (re)publish to the homebrew tap, e.g. 0.4.0. PyPI upload is skipped — must already be on PyPI."
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    # Skip on workflow_dispatch — dispatch only re-runs the brew job to
+    # backfill or recover; the package must already be on PyPI.
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # setuptools-scm needs tags
+
+      - name: Install mise
+        uses: jdx/mise-action@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python dependencies
+        run: uv sync
+
+      # The frontend imports from the local `vantage-md` package; build it
+      # first so TypeScript + Vite can resolve the module.
+      - name: Build local vantage-md package
+        run: cd packages/vantage-md && npm ci && npx tsup
+
+      - name: Install frontend deps
+        run: cd frontend && npm ci
+
+      - name: Build frontend
+        run: cd frontend && npm run build
+
+      - name: Bundle frontend into Python package
+        run: python3 -c "import shutil; from pathlib import Path; dst=Path('src/vantage/frontend_dist'); shutil.rmtree(dst, ignore_errors=True); shutil.copytree('frontend/dist', dst)"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        run: uv publish dist/* --check-url https://pypi.org/simple/
+
+  brew:
+    # Run after publish-pypi on release events, or standalone on workflow_dispatch.
+    # `always()` is required so the job still runs when upstream jobs are
+    # skipped (manual dispatch); the inner condition gates on either PyPI
+    # having succeeded, or the event being manual.
+    if: |
+      always() &&
+      (github.event_name == 'workflow_dispatch' ||
+       needs.publish-pypi.result == 'success')
+    needs: [publish-pypi]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Determine version
+        id: version
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = "release" ]; then
+            VERSION="${GITHUB_REF_NAME#v}"
+          else
+            VERSION="${{ github.event.inputs.version }}"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Publishing vantage-md ${VERSION} to homebrew tap"
+
+      - name: Check out homebrew tap
+        uses: actions/checkout@v6
+        with:
+          repository: mschulkind-oss/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: tap
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install homebrew-pypi-poet + vantage-md from PyPI
+        run: |
+          python -m venv /tmp/poet-venv
+          # poet still uses the deprecated pkg_resources API, which was removed
+          # in setuptools 81. Pin below that for the lifetime of this job.
+          /tmp/poet-venv/bin/pip install --quiet 'setuptools<81' homebrew-pypi-poet
+          # Retry the vantage-md install in case PyPI index replication lags
+          # behind the publish step (rare but documented).
+          VERSION="${{ steps.version.outputs.version }}"
+          for i in 1 2 3 4 5 6; do
+            if /tmp/poet-venv/bin/pip install --quiet "vantage-md==${VERSION}"; then
+              echo "Installed vantage-md==${VERSION}"
+              break
+            fi
+            echo "PyPI not ready yet, retrying in 15s..."
+            sleep 15
+          done
+
+      - name: Generate + patch formula
+        run: |
+          set -euo pipefail
+          /tmp/poet-venv/bin/poet -f vantage-md > /tmp/formula.rb
+
+          # Poet leaves placeholder fields — patch them here instead of
+          # maintaining a separate template that could drift from poet's output.
+          python3 <<'PY'
+          from pathlib import Path
+
+          f = Path("/tmp/formula.rb")
+          text = f.read_text()
+
+          text = text.replace(
+              'desc "Shiny new formula"',
+              'desc "Beautiful local Markdown viewer with live reload and Git awareness"',
+          )
+          text = text.replace(
+              'homepage "None"',
+              'homepage "https://github.com/mschulkind-oss/vantage"\n  license "Apache-2.0"',
+          )
+
+          # vantage-md's pyproject.toml requires Python >=3.13.
+          text = text.replace(
+              'depends_on "python3"',
+              'depends_on "python@3.13"',
+          )
+
+          # Replace poet's `false` test stub with a real smoke test.
+          # `--version` exits 0 without binding a port or loading a repo.
+          text = text.replace(
+              "  test do\n    false\n  end",
+              '  test do\n    assert_match "vantage-md", shell_output("#{bin}/vantage-md --version")\n  end',
+          )
+
+          f.write_text(text)
+          PY
+
+          echo "--- Generated formula ---"
+          cat /tmp/formula.rb
+
+      - name: Commit and push to tap
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.version.outputs.version }}"
+          mkdir -p tap/Formula
+          cp /tmp/formula.rb tap/Formula/vantage-md.rb
+          cd tap
+          git config user.name "vantage-md release bot"
+          git config user.email "noreply@github.com"
+          git add Formula/vantage-md.rb
+          if git diff --cached --quiet; then
+            echo "Formula unchanged; nothing to commit."
+            exit 0
+          fi
+          git commit -m "vantage-md ${VERSION}"
+          git push

vantage_md-0.4.1/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"            # Full release: v0.3.5
+      - "vantage-md@*"  # npm-only release: vantage-md@0.1.5
+
+permissions:
+  contents: write  # gh release create
+  id-token: write  # npm provenance (OIDC trusted publishing)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # setuptools-scm needs tags to compute the version
+
+      - name: Install mise
+        uses: jdx/mise-action@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Setup Node with npm registry
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+
+      - name: Install Python dependencies
+        run: uv sync
+
+      - name: Build vantage-md
+        run: cd packages/vantage-md && npm ci && npx tsup
+
+      - name: Install frontend deps
+        run: cd frontend && npm ci
+
+      # --- npm publish with provenance ---
+      # Skip if the version in package.json is already on the registry. This
+      # lets `v*` tags (Python releases) ride past a stale npm version without
+      # failing the whole workflow; only `vantage-md@*` tags or v* tags that
+      # also bumped npm actually publish.
+      - name: Check if npm version needs publishing
+        id: npm_check
+        run: |
+          set -euo pipefail
+          pkg_version=$(node -p "require('./packages/vantage-md/package.json').version")
+          if npm view "vantage-md@${pkg_version}" version > /dev/null 2>&1; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "vantage-md@${pkg_version} is already on npm; skipping publish."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "Publishing vantage-md@${pkg_version}."
+          fi
+
+      - name: Publish vantage-md to npm
+        if: steps.npm_check.outputs.skip == 'false'
+        run: cd packages/vantage-md && npm publish --provenance --access public
+
+      # --- Python build + GitHub release (only for v* tags) ---
+      - name: Build frontend
+        if: startsWith(github.ref_name, 'v')
+        run: cd frontend && npm run build
+
+      - name: Bundle frontend into Python package
+        if: startsWith(github.ref_name, 'v')
+        run: python3 -c "import shutil; from pathlib import Path; dst=Path('src/vantage/frontend_dist'); shutil.rmtree(dst, ignore_errors=True); shutil.copytree('frontend/dist', dst)"
+
+      - name: Build Python wheel
+        if: startsWith(github.ref_name, 'v')
+        run: uv build
+
+      - name: Create GitHub release
+        if: startsWith(github.ref_name, 'v')
+        run: |
+          gh release create "${{ github.ref_name }}" dist/*.whl dist/*.tar.gz \
+            --title "${{ github.ref_name }}" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

vantage_md-0.4.1/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+env/
+venv/
+*.egg-info/
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Python build artifacts
+build/
+dist/
+*.egg-info/
+pyproject.toml.bak
+
+# Environment
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Coverage reports
+htmlcov/
+.coverage
+# Overmind
+.overmind.sock
+.overmind.pid
+overmind.log
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Frontend build
+frontend/dist/
+src/vantage/frontend_dist/
+
+# Built docs output
+dist/docs/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+/.chrome-state/
+
+# YOLO Jail workspace state
+.yolo/

vantage_md-0.4.1/.mise.toml

@@ -0,0 +1,4 @@
+[tools]
+just = "latest"
+node = "22"
+python = "3.13"

vantage_md-0.4.1/.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+# Pre-commit hooks for Vantage
+# See https://pre-commit.com for more information
+repos:
+  # Python: Ruff for formatting and linting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.5
+    hooks:
+      # Run the formatter
+      - id: ruff-format
+        name: ruff format (Python)
+        types_or: [python, pyi]
+      # Run the linter
+      - id: ruff
+        name: ruff lint (Python)
+        types_or: [python, pyi]
+        args: [--fix]
+
+  # JavaScript/TypeScript: Prettier for formatting
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        name: prettier (JS/TS)
+        types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]
+        exclude: ^(package-lock\.json|.*\.lock|\.chrome-state/|frontend/node_modules/)
+        additional_dependencies:
+          - prettier@3.4.2
+
+  # JavaScript/TypeScript: ESLint for linting (must run from frontend/)
+  - repo: local
+    hooks:
+      - id: eslint-frontend
+        name: eslint (JS/TS in frontend/)
+        entry: bash -c 'cd frontend && npx eslint --fix $(echo "$@" | sed "s|frontend/||g")' --
+        language: system
+        files: ^frontend/.*\.(js|ts|jsx|tsx)$
+        types: [file]
+
+  # General: trailing whitespace, end of file, YAML validation
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^(\.chrome-state/|frontend/node_modules/)
+      - id: end-of-file-fixer
+        exclude: ^(\.chrome-state/|frontend/node_modules/)
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-merge-conflict

vantage_md-0.4.1/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "endOfLine": "lf"
+}

vantage_md-0.4.1/.python-version

@@ -0,0 +1 @@
+3.13

vantage_md-0.4.1/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to Vantage will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] - 2026-04-06
+
+### Fixed
+
+- `just deploy` now works after `git pull` without needing `just setup` — the build bootstraps its own environment.
+- `just setup` no longer modifies lockfiles (`uv sync --frozen`, `npm ci`).
+- `just build` safely patches `pyproject.toml` for dev versioning via backup+restore instead of fragile `git checkout` trap.
+
+## [0.3.0] - 2026-04-06
+
+### Added
+
+- **Review mode** — Toggle review mode on any markdown file to select text and leave inline comments. Comments are highlighted in the document and stored server-side for persistence across sessions.
+- **Outdated comment detection** — When the document changes and a comment's selected text no longer matches, it appears as an amber "Outdated" block near the changed section with a Dismiss button — similar to GitHub's outdated review comments.
+- **Auto-snapshots & revision history** — While in review mode, each file change automatically snapshots the previous version. Navigate revisions with `← Rev N of M →` controls.
+- **Block-level change highlights** — Changed paragraphs between revisions are marked with a purple left border for quick scanning.
+- **Copy all comments** — One-click export of all active review comments as markdown quotes, ready to paste back to an AI agent.
+- **TOML frontmatter support** — Zola-style `+++` TOML frontmatter is now parsed and displayed, with taxonomies and extra fields flattened into tag pills.
+- **Collapsible sidebar** — Click the collapse button to hide the file tree and maximize content area. State persists across sessions.
+- **Show hidden / gitignored files** — New filter toggles in the sidebar to reveal hidden files and gitignored files.
+- **Mermaid error handling** — Broken mermaid diagrams now show a friendly error message instead of crashing.
+- **`disable_whats_new` config** — Suppress the What's New popup entirely via server config.
+
+### Changed
+
+- **Startup performance** — Significantly faster initial load with background tree fetching, repo caching, and loading gate.
+- **Auto-discover repos** — `source_dirs` now recursively discovers git repos without explicit enumeration.
+
+### Fixed
+
+- Suppress What's New popup in static export mode.
+- Show directory index and README on root path in static mode.
+- Replace bundled GitHub SVG icon with inline SVG to avoid asset issues.
+
+## [0.2.0] - 2026-03-25
+
+### Added
+
+- **Global file search** — Press `T` (Shift+T) from anywhere to search files across all projects. Press `t` on the project picker page to do the same.
+- **Project picker shortcut** — Press `P` from anywhere to fuzzy-search project names and quickly switch between repos.
+- **Recent file search** — Press `r` to search recently modified files in the current project, or `R` to search recents across all projects.
+- **Copy file path** — Press `y` or click the "Path" button to copy the current file's absolute filesystem path to the clipboard.
+- **Changelog & What's New** — A built-in changelog with a "What's New" popup that appears when new features are available. Opt out anytime via settings.
+- **Source directories** — Configure `source_dirs` in your config to auto-discover git repos from specified directories.
+- **Repo sorting** — Toggle between alphabetical and recent-activity sorting on the project picker page.
+
+### Changed
+
+- **Project picker redesign** — Full-page layout without sidebar, cleaner table with repo names and relative timestamps.
+- **Repo age display** — Project picker now shows the age of the newest file in each repo rather than the last git commit.
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Markdown rendering with GitHub-flavored markdown, syntax highlighting, and KaTeX math support.
+- Mermaid diagram rendering with click-to-zoom.
+- Live reload via WebSocket — files update automatically when saved.
+- Git integration — view commit history, diffs, and file status.
+- Jujutsu (jj) support — view revisions, evolution log, and diffs.
+- Fuzzy file picker with `t` keyboard shortcut.
+- Dark mode with `Shift+D` toggle.
+- Vim-style keyboard navigation (`j`/`k` scroll, `g g`/`G` jump, `g h` home).
+- Multi-repo daemon mode with TOML configuration.
+- Static site export for hosting on Cloudflare Pages, GitHub Pages, etc.
+- Print-optimized stylesheet.