Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Copy to .env and fill in values (never commit .env).
# PowerShell: copy .env.example .env
# bash: cp .env.example .env

# --- API keys (at least one required for live runs) ---
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=

# --- Provider selection ---
# MDA_PROVIDER=anthropic
# MDA_USE_OPENROUTER=0
# MDA_OPENROUTER_MODEL=anthropic/claude-sonnet-4
# MDA_OPENROUTER_FALLBACK=1

# --- Model and limits ---
# MDA_MODEL=claude-sonnet-4-20250514
# MDA_MAX_TOKENS=8192
# MDA_MAX_RETRIES=3
# MDA_API_TIMEOUT=600

# --- Skill and inputs ---
# MDA_SKILL=markdown-document-architect
# MDA_SKILL_DIR=
# MDA_EXTENSIONS=.md,.txt,.pdf,.docx

# --- Cost guardrails (CLI also supports --max-files / --max-tokens) ---
# Use --max-files on directory batches to cap file count before API calls.
# Use --max-tokens to cap output tokens per file.

# --- Windows installer override (optional) ---
# MDA_PYTHON=C:\Path\To\python.exe
19 changes: 19 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
version: 2
updates:
- package-ecosystem: pip
directory: "/"
schedule:
interval: weekly
groups:
dev-dependencies:
patterns:
- "pytest*"
- "ruff"
- "mypy"
open-pull-requests-limit: 5

- package-ecosystem: github-actions
directory: "/"
schedule:
interval: weekly
open-pull-requests-limit: 5
76 changes: 76 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
lint-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Install package and dev tools
run: python -m pip install -e ".[dev]"

- name: Ruff
run: ruff check .

- name: Unit tests (exclude integration)
run: pytest -q -m "not integration"

smoke-install-linux:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Smoke install (install-global.sh) and mda --check
env:
MDA_CLI_ROOT: ${{ github.workspace }}
run: |
bash scripts/install-global.sh
export PATH="$HOME/.local/bin:$PATH"
command -v mda
mda --check

smoke-install-windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Smoke install (install-global.ps1) and mda --check
shell: pwsh
run: pwsh -NoProfile -File scripts/install-global.ps1

integration:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
continue-on-error: true
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Install package and dev tools
run: python -m pip install -e ".[dev]"

- name: Integration tests (optional)
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: pytest -q -m integration
31 changes: 31 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Release

on:
push:
tags:
- "v*"

permissions:
contents: write

jobs:
build-and-publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Build wheel and sdist
run: |
python -m pip install build hatchling
python -m build

- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
files: |
dist/*
generate_release_notes: true
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

## [0.2.10]

- GitHub Actions: ruff + unit pytest on push/PR; optional integration job on `main`.
- CI smoke: `install-global.sh` / `install-global.ps1` then `mda --check` on Linux and Windows.
- Tag-driven release workflow uploads wheel/sdist to GitHub Releases.
- `.env.example` for API keys and `MDA_*` variables.
- `install-global.ps1`: dynamic Python 3.10+ discovery (`py`, `python3`, `MDA_PYTHON`); stop `mda` processes before pip.
- `plan_moves`: dry-run by default; `--apply` to move files.
- Docs: `docs/VAULT-PLAYBOOK.md`, `docs/TROUBLESHOOTING.md`, README cost guardrails.
- TUI: batch progress (`Batch N/M`) and inline last API error status line.
- Dependabot for pip and GitHub Actions.

## [0.2.9]

- TUI: live read-only preview of the highlighted supported file (`.md`, `.txt`, `.pdf`, `.docx`, `.doc` listing).
Expand Down
29 changes: 25 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# mda-cli

**Roadmap:** [docs/ROADMAP.md](docs/ROADMAP.md) · **Gap analysis:** [docs/GAP-ANALYSIS.md](docs/GAP-ANALYSIS.md) ([tracked issues](https://github.com/B0LK13/mda-cli/issues))
**Roadmap:** [docs/ROADMAP.md](docs/ROADMAP.md) · **Gap analysis:** [docs/GAP-ANALYSIS.md](docs/GAP-ANALYSIS.md) · **Recommendations:** [docs/RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md) · **Vault playbook:** [docs/VAULT-PLAYBOOK.md](docs/VAULT-PLAYBOOK.md) · **Troubleshooting:** [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) ([tracked issues](https://github.com/B0LK13/mda-cli/issues))

CLI for **Markdown Document Architect (MDA)** and related bundled skills: loads `SKILL.md` and companion standards (bundled by default), calls Anthropic or OpenRouter, and writes restructured output (strips the outer fence when present).

Expand Down Expand Up @@ -62,7 +62,7 @@ Synonyms everywhere: `mda-cli`, `mda-tui`.
python -m pip install -e .
```

2. **Set your API key**:
2. **Set your API key** (copy [.env.example](.env.example) to `.env` locally; never commit secrets):

```powershell
set ANTHROPIC_API_KEY=your-key-here
Expand Down Expand Up @@ -108,7 +108,27 @@ mda path\to\vault --dry-run
mda path\to\file.md --in-place --backup
```

Optional environment variables: `MDA_SKILL` (skill id), `MDA_SKILL_DIR` (explicit skill folder), `MDA_EXTENSIONS`, `MDA_MODEL`, `MDA_MAX_TOKENS`, `MDA_API_TIMEOUT`.
Optional environment variables: `MDA_SKILL` (skill id), `MDA_SKILL_DIR` (explicit skill folder), `MDA_EXTENSIONS`, `MDA_MODEL`, `MDA_MAX_TOKENS`, `MDA_API_TIMEOUT`. See [.env.example](.env.example) for a full template.

### Cost guardrails

Large vaults can burn API credits quickly. Use limits on every pilot:

| Control | Purpose |
|---------|---------|
| `--max-files N` | Stop after N supported files in a directory batch (required before a full vault run) |
| `--max-tokens N` | Cap output tokens per file (default from `MDA_MAX_TOKENS`) |
| `--dry-run` | Batch mode: resolve jobs without calling the API |
| `-q` / quiet | Less console noise during long runs |

Examples:

```powershell
mda E:\ObsidianVault7 -r --max-files 5 -q
mda E:\ObsidianVault7 -r --max-files 20 --max-tokens 4096
```

TUI: select a small set of files manually before pressing **P**. See [docs/VAULT-PLAYBOOK.md](docs/VAULT-PLAYBOOK.md).

**Output naming:** sibling `*.restructured.md` for the default MDA skill (including PDF/DOCX sources). The `categorize-vault-notes` skill writes `*.restructured.txt` for non-Markdown sources.

Expand Down Expand Up @@ -138,7 +158,8 @@ Assign YAML frontmatter and optional folder hints for Obsidian vaults (flat or n
mda --skill categorize-vault-notes E:\ObsidianVault7\note.md
mda script --list --skill categorize-vault-notes
mda script scan_vault --skill categorize-vault-notes -- E:\ObsidianVault7 --limit 20
mda script plan_moves --skill categorize-vault-notes -- E:\ObsidianVault7 --dry-run
mda script plan_moves --skill categorize-vault-notes -- E:\ObsidianVault7
mda script plan_moves --skill categorize-vault-notes -- E:\ObsidianVault7 --apply
```

Pair with `scripts\flatten_vault_md.py` when moving nested notes to the vault root before batch categorization.
Expand Down
2 changes: 1 addition & 1 deletion docs/GAP-ANALYSIS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# mda-cli Gap Analysis

**Baseline:** v0.2.9 (2026-05-18)
**Planned state:** [ROADMAP.md](ROADMAP.md)
**Planned state:** [ROADMAP.md](ROADMAP.md) · **Recommendations:** [RECOMMENDATIONS.md](RECOMMENDATIONS.md)
**Repository:** [B0LK13/mda-cli](https://github.com/B0LK13/mda-cli) (private)

---
Expand Down
Loading
Loading