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
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## [Unreleased]

- Backup manifests: each batch run writes `~/.mda/manifests/<run_id>.json` (override with `MDA_MANIFEST_DIR`); `mda restore --list` shows runs (apply not implemented yet).
- TUI: press **S** to cycle bundled skills (`markdown-document-architect`, `categorize-vault-notes`).
- Docs: `docs/LOCAL-DEV.md` for local branch workflow without GitHub CI.
- README: note that integration tests need `ANTHROPIC_API_KEY`.

## [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
35 changes: 29 additions & 6 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 Expand Up @@ -172,10 +193,12 @@ The installer uses **pipx** when available, writes `~/.config/mda-cli/python`, a
## Tests

```powershell
python -m pip install -e ".[dev]"
python -m pytest -q
python -m pip install -e ".[dev,documents]"
python -m pytest -q -m "not integration"
```

Unit tests run without API keys. **Integration tests** (`pytest -m integration`) call the live Anthropic API and require `ANTHROPIC_API_KEY` in the environment; they are skipped when the key is unset.

## Vault flatten helper

```powershell
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
71 changes: 71 additions & 0 deletions docs/LOCAL-DEV.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Local development (no GitHub CI)

Use this workflow when GitHub Actions billing is blocked or you want to work entirely on your machine.

## Branch

Active feature work lives on **`chore/close-p0-issues`** (v0.2.10, CI configs, docs, TUI fixes, `plan_moves` dry-run default).

```powershell
cd C:\Users\Admin\Projects\mda-cli
git fetch origin
git checkout chore/close-p0-issues
```

Optional: merge into local `main` for day-to-day use (do not push unless you intend to):

```powershell
git checkout main
git merge chore/close-p0-issues
```

Stay on `chore/close-p0-issues` if you are still landing changes before merging locally.

## Install

Python 3.10+ (this machine uses 3.13):

```powershell
& "C:\Users\Admin\AppData\Local\Programs\Python\Python313\python.exe" -m pip install -e ".[dev,documents]"
```

Or after `scripts\install-global.ps1`, the `mda` on PATH uses whichever Python installed the package.

## Verify

```powershell
mda --check
python -m pytest -q -m "not integration"
```

Integration tests (live API) are optional:

```powershell
$env:ANTHROPIC_API_KEY = "sk-..."
python -m pytest -q -m integration
```

## `mda` and environment

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Anthropic provider |
| `OPENROUTER_API_KEY` | OpenRouter provider / fallback |
| `MDA_SKILL` / `mda --skill` | Active skill id |
| `MDA_SKILL_DIR` | Override skill folder |
| `MDA_PROVIDER` | `anthropic` or `openrouter` |
| `MDA_MANIFEST_DIR` | Backup manifest directory (default `~/.mda/manifests`) |

Examples:

```powershell
mda --check
mda path\to\note.md --dry-run
mda path\to\vault --in-place --backup
mda restore --list
mda --tui
```

## GitHub CI

Pushes and PRs normally run `.github/workflows/ci.yml`. While billing is blocked, rely on local `pytest` and `mda --check` above. Re-enable remote CI when billing is fixed, then merge `chore/close-p0-issues` via PR as usual.
Loading
Loading