diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..94248a3 --- /dev/null +++ b/.env.example @@ -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 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..57c5c05 --- /dev/null +++ b/.github/dependabot.yml @@ -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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..6cc5656 --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..6acf9ab --- /dev/null +++ b/.github/workflows/release.yml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 17c595a..570d2d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,24 @@ # Changelog +## [Unreleased] + +- Backup manifests: each batch run writes `~/.mda/manifests/.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). diff --git a/README.md b/README.md index fc8b845..698f3c1 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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 @@ -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. @@ -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. @@ -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 diff --git a/docs/GAP-ANALYSIS.md b/docs/GAP-ANALYSIS.md index 61da7cc..f4fda73 100644 --- a/docs/GAP-ANALYSIS.md +++ b/docs/GAP-ANALYSIS.md @@ -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) --- diff --git a/docs/LOCAL-DEV.md b/docs/LOCAL-DEV.md new file mode 100644 index 0000000..8d33113 --- /dev/null +++ b/docs/LOCAL-DEV.md @@ -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. diff --git a/docs/RECOMMENDATIONS.md b/docs/RECOMMENDATIONS.md new file mode 100644 index 0000000..f0d6cab --- /dev/null +++ b/docs/RECOMMENDATIONS.md @@ -0,0 +1,160 @@ +# mda-cli Recommendations + +**Baseline:** v0.2.9 (main); stabilization draft in [PR #16](https://github.com/B0LK13/mda-cli/pull/16) (`chore/close-p0-issues`, targets v0.2.10) +**Related:** [ROADMAP.md](ROADMAP.md) · [GAP-ANALYSIS.md](GAP-ANALYSIS.md) · [GitHub Issues](https://github.com/B0LK13/mda-cli/issues) + +This document groups follow-on work by **topic**. Each recommendation has priority **P0/P1/P2** and effort **S/M/L**. Items already tracked as issues [#1–#15](https://github.com/B0LK13/mda-cli/issues) are listed for context only—do not open duplicate issues; link **Related to #N** instead. + +--- + +## Distribution & releases + +GitHub Releases and install hardening are in flight via PR #16. Next steps focus on how users pin versions, install from private assets, and eventually reach PyPI/winget. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **DIST-R1** | P1 | S | Document `pip install` from private GitHub Release wheel URL (PAT, extras `[documents]`) in README and release notes (ROADMAP A10). | [#17](https://github.com/B0LK13/mda-cli/issues/17) | +| **DIST-R2** | P1 | S | Add `docs/RELEASE-CHECKLIST.md` copied from ROADMAP §6 template (ROADMAP A24). | [#18](https://github.com/B0LK13/mda-cli/issues/18) | +| **DIST-R3** | P1 | S | Document version pinning and rollback: `pip install mda-cli==x.y.z`, reinstall scripts (ROADMAP §5e). | [#19](https://github.com/B0LK13/mda-cli/issues/19) | +| **DIST-R4** | P2 | M | Evaluate PyPI publish vs private-only distribution (ROADMAP A11, Q1/Q2). | [#20](https://github.com/B0LK13/mda-cli/issues/20) | +| **DIST-R5** | P2 | L | Draft winget manifest or defer with decision record (ROADMAP A12, Phase 3). | [#21](https://github.com/B0LK13/mda-cli/issues/21) | +| — | P1 | M | Tag-driven wheel/sdist on `v*` tags. | **Related to #8** (PR #16) | +| — | P0 | M | Parameterize Windows Python discovery. | **Related to #5** (PR #16) | +| — | P1 | S | Stop `mda` processes before Windows pip. | **Related to #7** (PR #16) | + +--- + +## CI & quality + +Core CI lands in PR #16. Remaining gaps: install smoke on runners, optional integration, and coverage visibility. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **CI-R1** | P2 | M | Publish pytest coverage summary (and optional `coverage.xml` artifact) on PR CI. | [#22](https://github.com/B0LK13/mda-cli/issues/22) | +| **CI-R2** | P2 | S | Add `ruff format --check` or format job alongside lint (if not already enforced). | [#23](https://github.com/B0LK13/mda-cli/issues/23) | +| — | P0 | M | GitHub Actions: ruff + pytest on push/PR. | **Related to #1** (PR #16) | +| — | P1 | M | CI smoke: `mda --check` after install on Windows and Linux. | **Related to #2** (PR #16) | +| — | P1 | M | Optional CI job for Anthropic integration tests. | **Related to #4** (deferred) | +| — | P2 | S | Dependabot for pip and GitHub Actions. | **Related to #15** (PR #16) | + +--- + +## Security & secrets + +`.env.example` and env-only keys are addressed in PR #16. Focus on rotation process and automated leak prevention. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **SEC-R1** | P0 | S | Add `docs/SECURITY.md`: key rotation steps, never commit `.env`, revoke leaked keys (ROADMAP A03). | [#24](https://github.com/B0LK13/mda-cli/issues/24) | +| **SEC-R2** | P2 | M | CI secret scanning (e.g. gitleaks/trufflehog) on push/PR; fail on high-confidence findings. | [#25](https://github.com/B0LK13/mda-cli/issues/25) | +| **SEC-R3** | P1 | S | Document that CI/workflows must not echo `ANTHROPIC_*` / `OPENROUTER_*`; use GitHub secrets only. | [#26](https://github.com/B0LK13/mda-cli/issues/26) | +| — | P0 | S | Ship `.env.example` for API keys and `MDA_*`. | **Related to #3** (PR #16) | + +--- + +## TUI & UX + +PR #16 adds batch `N/M` progress and inline API errors. Larger UX items remain: skill selection, preview depth, undo, and restore/checkpoints. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **TUI-R1** | P1 | L | TUI skill picker: choose bundled or `MDA_SKILL_DIR` skill without CLI env juggling. | [#27](https://github.com/B0LK13/mda-cli/issues/27) | +| **TUI-R2** | P2 | M | Preview: scrollable buffer and in-preview search for long notes (ROADMAP A15). | [#28](https://github.com/B0LK13/mda-cli/issues/28) | +| **TUI-R3** | P2 | M | Preview: improve PDF rendering (page-aware or thumbnail) beyond plain-text extract cap. | [#29](https://github.com/B0LK13/mda-cli/issues/29) | +| **TUI-R4** | P2 | L | Session-level undo for last in-place write using backup sibling (ROADMAP A16). | [#30](https://github.com/B0LK13/mda-cli/issues/30) | +| **TUI-R5** | P1 | S | Pre-flight confirmation before **P** when file count or estimated tokens exceed thresholds. | [#31](https://github.com/B0LK13/mda-cli/issues/31) | +| — | P1 | M | Batch progress indicator for multi-file **P**. | **Related to #6** (PR #16) | +| — | P1 | S | Show last API error inline (non-blocking). | **Related to #9** (PR #16) | +| — | P2 | L | Backup manifest and `mda restore` for moves and in-place. | **Related to #14** (deferred) | + +--- + +## Vault operations + +Playbook and safer `plan_moves` defaults ship in PR #16. Scale work: TUI pipelines, checkpoints, and batch analytics. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **VAULT-R1** | P1 | L | TUI vault workflow: guided flatten → scan → plan_moves (dry-run) → batch categorize/MDA. | [#32](https://github.com/B0LK13/mda-cli/issues/32) | +| **VAULT-R2** | P2 | M | Promote `scripts/flatten_vault_md.py` to documented `mda script` entry or subcommand wrapper. | [#33](https://github.com/B0LK13/mda-cli/issues/33) | +| **VAULT-R3** | P1 | L | Resume checkpoints for interrupted batch runs (`--checkpoint-dir`, resume flag). | [#34](https://github.com/B0LK13/mda-cli/issues/34) | +| **VAULT-R4** | P2 | M | Export batch summary CSV from `--json-lines` (ROADMAP A32). | [#35](https://github.com/B0LK13/mda-cli/issues/35) | +| — | P1 | M | `docs/VAULT-PLAYBOOK.md` pipeline. | **Related to #10** (PR #16) | +| — | P2 | M | `plan_moves` dry-run by default; `--apply` to move. | **Related to #13** (PR #16) | + +--- + +## Skills & extensibility + +Bundled MDA and categorize skills are stable; external skills need validation, discovery, and a long-term registry story. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **SKILL-R1** | P1 | M | Validate external skill directories (`--skill-dir` / `MDA_SKILL_DIR`): required files, clear errors. | [#36](https://github.com/B0LK13/mda-cli/issues/36) | +| **SKILL-R2** | P2 | S | `mda skills list` (bundled + discovered external paths, versions). | [#37](https://github.com/B0LK13/mda-cli/issues/37) | +| **SKILL-R3** | P2 | L | Design optional third-party skill manifest format (local index; marketplace out of scope). | [#38](https://github.com/B0LK13/mda-cli/issues/38) | + +--- + +## API & cost + +Cost flags exist; users need estimates before spend and structured warnings during batch. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **API-R1** | P1 | M | Dry-run cost estimate: approximate tokens × list price before batch (CLI + TUI). | [#39](https://github.com/B0LK13/mda-cli/issues/39) | +| **API-R2** | P1 | M | Emit budget warnings in `--json-lines` when approaching `--max-tokens` (ROADMAP Phase 2). | [#40](https://github.com/B0LK13/mda-cli/issues/40) | +| **API-R3** | P2 | S | Document provider routing matrix (Anthropic primary, OpenRouter fallback, env flags). | [#41](https://github.com/B0LK13/mda-cli/issues/41) | +| — | P1 | S | Document cost guardrails (`--max-files`, `--max-tokens`). | **Related to #12** (PR #16) | + +--- + +## Documentation + +Troubleshooting and vault playbook land in PR #16. Broader docs site and onboarding media remain. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **DOCS-R1** | P2 | S | Add `docs/README.md` index linking ROADMAP, GAP, playbooks, RECOMMENDATIONS. | [#42](https://github.com/B0LK13/mda-cli/issues/42) | +| **DOCS-R2** | P2 | L | MkDocs or GitHub Pages site (ROADMAP A23, Q5). | [#43](https://github.com/B0LK13/mda-cli/issues/43) | +| **DOCS-R3** | P2 | L | Record short video quickstart: install → TUI → dry-run vault pilot. | [#44](https://github.com/B0LK13/mda-cli/issues/44) | +| — | P1 | M | `docs/TROUBLESHOOTING.md`. | **Related to #11** (PR #16) | + +--- + +## Platform + +Windows and WSL are primary; macOS CI and portable config paths reduce friction on other machines. + +| ID | Priority | Effort | Recommendation | Tracking | +|----|----------|--------|----------------|----------| +| **PLAT-R1** | P1 | M | macOS GitHub Actions job: `install-global.sh` + `mda --check` (ROADMAP A07). | [#45](https://github.com/B0LK13/mda-cli/issues/45) | +| **PLAT-R2** | P1 | M | Portable config directory (`XDG_CONFIG_HOME` / `%APPDATA%/mda-cli`) for skills overrides and checkpoints. | [#46](https://github.com/B0LK13/mda-cli/issues/46) | +| **PLAT-R3** | P2 | S | Document Git Bash on Windows: PATH to `~/.local/bin` or `python -m mda_cli`. | [#47](https://github.com/B0LK13/mda-cli/issues/47) | + +--- + +## Deferred / PR #16 follow-ups + +Work intentionally left open after [PR #16](https://github.com/B0LK13/mda-cli/pull/16). **Do not duplicate** these issues—track progress there. + +| Item | Issue | Notes | +|------|-------|-------| +| CI install smoke (Win + Linux) | [#2](https://github.com/B0LK13/mda-cli/issues/2) | In PR #16 (`smoke-install-*` CI jobs) | +| Optional Anthropic integration CI | [#4](https://github.com/B0LK13/mda-cli/issues/4) | Nightly or `workflow_dispatch`; ROADMAP Q6 | +| Backup manifest + `mda restore` | [#14](https://github.com/B0LK13/mda-cli/issues/14) | Phase 2; pairs with TUI-R4 | +| Post-merge: tag `v0.2.10` and verify release workflow | — | Operational; see PR #16 test plan | +| Close #1–#3, #5–#13, #15, #2 when PR #16 merges | — | Use `Closes #N` in merge commit | + +--- + +## Summary counts + +| Metric | Count | +|--------|------:| +| Topics | 10 | +| New recommendations (issues to file) | 31 | +| Already tracked (#1–#15 / PR #16) | 15 | +| Deferred explicit (#4, #14) | 2 | + +*Last updated: 2026-05-18* diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..32f4439 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,51 @@ +# Troubleshooting + +## Windows: `pip install` fails with WinError 32 on `mda.exe` + +Another process still has `mda` open (often a Cursor terminal or the TUI). + +1. Quit the TUI and close terminals running `mda`. +2. Re-run `pwsh -File scripts\install-global.ps1` (stops `mda` / `mda-cli` / `mda-tui` before pip). +3. Or run `python -m mda_cli` with the same Python used for install. + +## `No module named mda_cli` + +The `mda` on PATH may point at a different Python than the one that installed the package. + +- **Windows:** Re-run `scripts\install-global.ps1`; confirm `mda --check`. +- **WSL/macOS/Linux:** Run `./scripts/install-global.sh` and ensure `~/.local/bin` is on PATH. + +## API key / provider errors + +| Symptom | What to try | +|---------|-------------| +| Missing API key | Set `ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY` (see `.env.example`) | +| 402 / credits | Add credits or set `MDA_PROVIDER=openrouter` | +| 429 / rate limit | Lower `--max-files`; retry; enable `MDA_OPENROUTER_FALLBACK=1` | +| Timeout | Increase `MDA_API_TIMEOUT` (seconds) | + +TUI: the status line under the log shows the **last API error** without blocking the UI. + +## TUI + +| Issue | Fix | +|-------|-----| +| Preview empty for PDF/DOCX | `pip install 'mda-cli[pdf]'` and/or `'mda-cli[docx]'` | +| `.doc` files | Convert to `.docx` first | +| Batch seems stuck | Watch log for `Batch N/M`; check API status line for errors | +| `NoActiveWorker` on jump/filter | Upgrade to latest `mda-cli` (0.2.5+ fix) | + +## CLI batch + +- `--dry-run` is not supported with `--tui`; use batch mode on files/directories. +- `--max-files` requires a directory target, not single-file mode. +- `--backup` only applies with `--in-place`. + +## CI / dev + +```powershell +python -m pip install -e ".[dev]" +ruff check . +pytest -q -m "not integration" +pytest -q -m integration # needs ANTHROPIC_API_KEY +``` diff --git a/docs/VAULT-PLAYBOOK.md b/docs/VAULT-PLAYBOOK.md new file mode 100644 index 0000000..f5f0a89 --- /dev/null +++ b/docs/VAULT-PLAYBOOK.md @@ -0,0 +1,55 @@ +# Obsidian vault playbook (mda-cli) + +Step-by-step workflow for large vaults (e.g. `E:\ObsidianVault7`). **Always dry-run before apply.** + +## 1. Flatten (optional) + +If notes live in nested folders, move `.md` files to the vault root first: + +```powershell +python scripts\flatten_vault_md.py E:\ObsidianVault7 --dry-run +python scripts\flatten_vault_md.py E:\ObsidianVault7 +``` + +## 2. Scan frontmatter + +Inventory YAML coverage and gaps: + +```powershell +mda script scan_vault --skill categorize-vault-notes -- E:\ObsidianVault7 --limit 50 +``` + +## 3. Plan moves (dry-run by default) + +Preview folder moves from `folder:` frontmatter keys: + +```powershell +mda script plan_moves --skill categorize-vault-notes -- E:\ObsidianVault7 +``` + +Apply only after review: + +```powershell +mda script plan_moves --skill categorize-vault-notes -- E:\ObsidianVault7 --apply +``` + +## 4. Categorize / MDA batch + +Start small; increase limits after sign-off: + +```powershell +mda --skill categorize-vault-notes E:\ObsidianVault7 -r --max-files 5 -q +mda E:\ObsidianVault7 -r --max-files 5 --dry-run +``` + +Use the TUI for interactive selection: `mda` → **U** (use folder) → select files → **P**. + +## 5. Verify + +- Spot-check outputs and frontmatter in Obsidian. +- Re-run `scan_vault` to confirm `folder` / `area` / `tags` coverage. +- See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for install and API issues. + +## Cost guardrails + +See README **Cost guardrails** and use `--max-files` / `--max-tokens` on every pilot run. diff --git a/mda_cli/__init__.py b/mda_cli/__init__.py index 1a61a17..0093504 100644 --- a/mda_cli/__init__.py +++ b/mda_cli/__init__.py @@ -1,3 +1,3 @@ """Markdown Document Architect CLI package.""" -__version__ = "0.2.9" +__version__ = "0.2.10" diff --git a/mda_cli/backup.py b/mda_cli/backup.py new file mode 100644 index 0000000..fb5b017 --- /dev/null +++ b/mda_cli/backup.py @@ -0,0 +1,107 @@ +"""Backup manifest tracking for batch runs (issue #14 groundwork). + +Each batch run with ``--backup`` and/or in-place writes can append a JSON manifest +under ``~/.mda/manifests/`` (override with ``MDA_MANIFEST_DIR``). Full +``mda restore`` apply is not implemented yet; use ``mda restore --list`` to inspect. +""" + +from __future__ import annotations + +import json +import os +from datetime import UTC, datetime +from pathlib import Path +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from mda_cli.core import JobResult + +MANIFEST_VERSION = 1 + + +def default_manifest_dir() -> Path: + """Directory where batch manifests are stored.""" + raw = os.environ.get("MDA_MANIFEST_DIR", "").strip() + if raw: + return Path(raw).expanduser() + return Path.home() / ".mda" / "manifests" + + +def new_run_id() -> str: + """UTC timestamp id for a batch run.""" + return datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ") + + +def manifest_entry_from_result(result: JobResult) -> dict[str, object]: + """Serialize one job result for the manifest.""" + return { + "src": str(result.job.src), + "dst": str(result.job.dst), + "ok": result.ok, + "action": result.action, + "changed": result.changed, + "backup_path": str(result.backup_path) if result.backup_path else None, + "error": result.error, + } + + +def write_batch_manifest( + *, + run_id: str, + results: list[JobResult], + skill_id: str, + provider: str | None, + target: Path | None, + in_place: bool, + backup_enabled: bool, + manifest_dir: Path | None = None, +) -> Path: + """Write a JSON manifest for a completed batch run; return its path.""" + root = (manifest_dir or default_manifest_dir()).expanduser() + root.mkdir(parents=True, exist_ok=True) + path = root / f"{run_id}.json" + payload: dict[str, object] = { + "version": MANIFEST_VERSION, + "run_id": run_id, + "created_at": datetime.now(UTC).isoformat(), + "skill_id": skill_id, + "provider": provider, + "target": str(target) if target is not None else None, + "in_place": in_place, + "backup_enabled": backup_enabled, + "job_count": len(results), + "entries": [manifest_entry_from_result(r) for r in results], + } + path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + return path + + +def list_manifest_files(manifest_dir: Path | None = None) -> list[Path]: + """Return manifest JSON paths newest first.""" + root = (manifest_dir or default_manifest_dir()).expanduser() + if not root.is_dir(): + return [] + files = sorted(root.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True) + return [p for p in files if p.is_file()] + + +def load_manifest(path: Path) -> dict[str, object]: + """Load one manifest file.""" + data = json.loads(path.read_text(encoding="utf-8")) + if not isinstance(data, dict): + raise ValueError(f"invalid manifest (expected object): {path}") + return data + + +def summarize_manifest(data: dict[str, object]) -> str: + """One-line summary for ``restore --list``.""" + run_id = data.get("run_id", "?") + created = data.get("created_at", "?") + jobs = data.get("job_count", "?") + skill = data.get("skill_id", "?") + backups = sum( + 1 + for e in data.get("entries", []) + if isinstance(e, dict) and e.get("backup_path") + ) + return f"{run_id} {created} skill={skill} jobs={jobs} backups={backups}" diff --git a/mda_cli/bundled_skills/categorize-vault-notes/SKILL.md b/mda_cli/bundled_skills/categorize-vault-notes/SKILL.md index 637349f..0b59cb6 100644 --- a/mda_cli/bundled_skills/categorize-vault-notes/SKILL.md +++ b/mda_cli/bundled_skills/categorize-vault-notes/SKILL.md @@ -51,11 +51,12 @@ Run via `mda script` (see mda-cli README): | Script | Purpose | |--------|---------| | `scan_vault.py` | List `.md` files with size and frontmatter keys | -| `plan_moves.py` | Read `folder` from frontmatter and print a move plan (dry-run) | +| `plan_moves.py` | Read `folder` from frontmatter and print a move plan (dry-run by default; `--apply` to move) | Example: ```bash mda script scan_vault -- E:\ObsidianVault7 --limit 20 -mda script plan_moves -- E:\ObsidianVault7 --dry-run +mda script plan_moves -- E:\ObsidianVault7 +mda script plan_moves -- E:\ObsidianVault7 --apply ``` diff --git a/mda_cli/bundled_skills/categorize-vault-notes/scripts/plan_moves.py b/mda_cli/bundled_skills/categorize-vault-notes/scripts/plan_moves.py index 9575336..89bd292 100644 --- a/mda_cli/bundled_skills/categorize-vault-notes/scripts/plan_moves.py +++ b/mda_cli/bundled_skills/categorize-vault-notes/scripts/plan_moves.py @@ -25,8 +25,18 @@ def main() -> int: p = argparse.ArgumentParser(description=__doc__) p.add_argument("vault", type=Path, help="Vault root directory") p.add_argument("--recursive", "-r", action="store_true", help="Include subfolders") - p.add_argument("--dry-run", action="store_true", help="Only print planned moves") + p.add_argument( + "--apply", + action="store_true", + help="Perform moves (default is dry-run only)", + ) + p.add_argument( + "--dry-run", + action="store_true", + help=argparse.SUPPRESS, + ) args = p.parse_args() + apply_moves = args.apply and not args.dry_run vault = args.vault.expanduser().resolve() if not vault.is_dir(): print(f"ERROR: not a directory: {vault}") @@ -53,14 +63,17 @@ def main() -> int: continue planned += 1 print(f"{path} -> {dest}") - if not args.dry_run: + if apply_moves: dest.parent.mkdir(parents=True, exist_ok=True) if dest.exists(): print(f" SKIP exists: {dest}") continue path.rename(dest) - print(f"planned={planned} skipped={skipped} dry_run={args.dry_run}") + mode = "apply" if apply_moves else "dry_run" + print(f"planned={planned} skipped={skipped} mode={mode}") + if not apply_moves and planned: + print("No files moved (dry-run). Re-run with --apply to execute moves.") return 0 diff --git a/mda_cli/cli.py b/mda_cli/cli.py index 87cd0bd..a83d3d6 100644 --- a/mda_cli/cli.py +++ b/mda_cli/cli.py @@ -8,6 +8,13 @@ from pathlib import Path from mda_cli import __version__ +from mda_cli.backup import ( + list_manifest_files, + load_manifest, + new_run_id, + summarize_manifest, + write_batch_manifest, +) from mda_cli.core import ( DEFAULT_MAX_TOKENS, DEFAULT_MODEL, @@ -35,6 +42,26 @@ ) +def run_restore_list() -> int: + """List backup manifests written by prior batch runs.""" + paths = list_manifest_files() + if not paths: + print("No backup manifests found (batch runs write to ~/.mda/manifests/).") + return 0 + for path in paths: + try: + data = load_manifest(path) + print(f"{path.name}\t{summarize_manifest(data)}") + except (OSError, ValueError) as e: + print(f"{path.name}\tERROR: {e}", file=sys.stderr) + print( + "\nRestore apply is not implemented yet; copy files from backup_path entries " + "or use git on tracked vaults.", + file=sys.stderr, + ) + return 0 + + def run_check( skill_dir_arg: Path | None, *, @@ -309,6 +336,17 @@ def _parse_script_argv(argv: list[str]) -> argparse.Namespace: def main(argv: list[str] | None = None) -> int: raw_argv = sys.argv[1:] if argv is None else list(argv) + if raw_argv and raw_argv[0] == "restore": + rest = raw_argv[1:] + if rest == ["--list"] or rest == ["-l"]: + return run_restore_list() + print( + "Usage: mda restore --list\n" + " (restore apply not implemented yet; see manifest backup_path entries)", + file=sys.stderr, + ) + return 2 + if raw_argv and raw_argv[0] == "script": args = _parse_script_argv(raw_argv[1:]) script_args = list(args.script_args) @@ -414,6 +452,7 @@ def main(argv: list[str] | None = None) -> int: print(f"Provider: {ctx.provider} (model: {ctx.model})", file=sys.stderr) failures = 0 + results: list[JobResult] = [] for job in jobs: try: result = process_job_with_provider( @@ -426,6 +465,7 @@ def main(argv: list[str] | None = None) -> int: max_attempts=max_attempts, backup_in_place=args.backup, ) + results.append(result) if args.json_lines: print_json_line(job_result_record(result, provider=ctx.provider)) if not result.ok: @@ -434,14 +474,26 @@ def main(argv: list[str] | None = None) -> int: failures += 1 msg = friendly_api_message(e) print(f" FAILED: {job.src}: {msg}", file=sys.stderr) + failed = JobResult(job=job, ok=False, action="failed", error=msg) + results.append(failed) if args.json_lines: print_json_line( - job_result_record( - JobResult(job=job, ok=False, action="failed", error=msg), - provider=ctx.provider, - ) + job_result_record(failed, provider=ctx.provider), ) + run_id = new_run_id() + manifest_path = write_batch_manifest( + run_id=run_id, + results=results, + skill_id=skill_id, + provider=ctx.provider, + target=args.target, + in_place=args.in_place, + backup_enabled=args.backup, + ) + if not args.json_lines: + print(f"Backup manifest: {manifest_path}", file=sys.stderr) + if not args.json_lines: print(f"Done. {len(jobs) - failures}/{len(jobs)} succeeded.", file=sys.stderr) return 0 if failures == 0 else 1 diff --git a/mda_cli/core.py b/mda_cli/core.py index 3d299aa..ddafa88 100644 --- a/mda_cli/core.py +++ b/mda_cli/core.py @@ -340,8 +340,8 @@ def load_system_prompt(skill_dir: Path) -> str: parts.append(read_markdown_text(categories)) else: sys.stderr.write( - f"WARNING: no MDA-STANDARD.md or references/CATEGORIES.md; " - f"system prompt is SKILL.md only.\n" + "WARNING: no MDA-STANDARD.md or references/CATEGORIES.md; " + "system prompt is SKILL.md only.\n" ) result = "".join(parts) _system_prompt_cache[key] = result diff --git a/mda_cli/folder_picker.py b/mda_cli/folder_picker.py index a9683b9..49adc4b 100644 --- a/mda_cli/folder_picker.py +++ b/mda_cli/folder_picker.py @@ -69,7 +69,7 @@ def compose(self) -> ComposeResult: yield Label(id="path-label") yield Label(id="file-count-label") yield Label( - "Enter = open folder | Backspace = up | U = use this folder | H = home | Q = quit", + "Enter = open | Backspace = up | U = use folder | H = home | Q = quit", id="hint", ) yield DataTable(id="listing", zebra_stripes=True, cursor_type="row") diff --git a/mda_cli/providers.py b/mda_cli/providers.py index 82e40fe..a805bfb 100644 --- a/mda_cli/providers.py +++ b/mda_cli/providers.py @@ -16,9 +16,11 @@ DEFAULT_API_TIMEOUT, DEFAULT_MAX_TOKENS, DEFAULT_MODEL, - friendly_api_message as _friendly_anthropic, strip_outer_fence, ) +from mda_cli.core import ( + friendly_api_message as _friendly_anthropic, +) ProviderName = Literal["anthropic", "openrouter"] diff --git a/mda_cli/tui.py b/mda_cli/tui.py index e898b7f..562b806 100644 --- a/mda_cli/tui.py +++ b/mda_cli/tui.py @@ -13,8 +13,19 @@ from textual.screen import ModalScreen from textual.widgets import DataTable, Footer, Header, Input, Label, RichLog, TextArea -from mda_cli.core import Job, find_skill_dir, jobs_from_document_files, load_system_prompt -from mda_cli.document_io import DocumentReadError, is_supported_extension, read_document_text, supported_extensions +from mda_cli.core import ( + Job, + find_skill_dir, + jobs_from_document_files, + list_bundled_skills, + load_system_prompt, +) +from mda_cli.document_io import ( + DocumentReadError, + is_supported_extension, + read_document_text, + supported_extensions, +) from mda_cli.preview import ( DEFAULT_PREVIEW_MAX_CHARS, format_preview_metadata, @@ -113,6 +124,7 @@ class MdaNavigatorApp(App[None]): #preview-meta { height: auto; max-height: 3; text-style: bold; } #preview-body { height: 1fr; min-height: 8; } #log { height: 1fr; min-height: 10; background: $surface; } + #api-status { height: auto; max-height: 3; color: $error; } Label { margin: 0 0 1 0; } """ @@ -128,6 +140,7 @@ class MdaNavigatorApp(App[None]): Binding("f", "filter_listing", "Filter", show=True), Binding("v", "toggle_hidden", "Hidden", show=True), Binding("a", "select_recursive_supported", "Recursive all", show=True), + Binding("s", "cycle_skill", "Skill", show=True), ] def __init__( @@ -165,6 +178,16 @@ def __init__( self._preview_cache: tuple[Path, float, str, str | None] | None = None self._preview_timer = None self._preview_load_id: int = 0 + self._last_api_error: str | None = None + bundled = list_bundled_skills() + self._skill_cycle_ids: list[str] = bundled if bundled else [] + if self.skill_id and self.skill_id not in self._skill_cycle_ids: + self._skill_cycle_ids = [self.skill_id, *self._skill_cycle_ids] + elif not self._skill_cycle_ids and self.skill_id: + self._skill_cycle_ids = [self.skill_id] + self._skill_cycle_index = 0 + if self.skill_id and self.skill_id in self._skill_cycle_ids: + self._skill_cycle_index = self._skill_cycle_ids.index(self.skill_id) def _alloc_row_key(self) -> str: self._row_key_seq += 1 @@ -178,6 +201,7 @@ def compose(self) -> ComposeResult: yield DataTable(id="listing", zebra_stripes=True, cursor_type="row") yield Label(id="selection-label") yield Label(id="mode-label") + yield Label(id="skill-label") yield Label(id="filter-label") yield Input( placeholder="Output folder when mode is out_dir (absolute or ~)", @@ -188,6 +212,7 @@ def compose(self) -> ComposeResult: yield Label("", id="preview-meta") yield TextArea("", id="preview-body", read_only=True) with Vertical(id="right"): + yield Label("", id="api-status") yield RichLog(id="log", highlight=True, markup=True) yield Footer() @@ -201,8 +226,9 @@ def on_mount(self) -> None: f"[dim]Supported:[/] {exts}\n" "[dim]Space[/] toggle file [dim]Enter[/] open dir [dim]Backspace[/] up " "[dim]ctrl+j[/] jump [dim]f[/] filter [dim]v[/] hidden " - "[dim]a[/] recursive select [dim]k/j[/] up/down [dim]I[/] preview pane " - "[dim]O[/] output [dim]P[/] run [dim]G[/] out-folder [dim]H[/] home" + "[dim]a[/] recursive select [dim]S[/] skill [dim]k/j[/] up/down " + "[dim]I[/] preview pane [dim]O[/] output [dim]P[/] run " + "[dim]G[/] out-folder [dim]H[/] home" ) self._apply_preview_pane_visibility() @@ -249,6 +275,20 @@ def on_data_table_row_highlighted(self, event: DataTable.RowHighlighted) -> None def log_msg(self, message: str) -> None: self.query_one("#log", RichLog).write(message) + def _set_api_error(self, message: str | None) -> None: + self._last_api_error = message + label = self.query_one("#api-status", Label) + if message: + short = message if len(message) <= 120 else message[:117] + "..." + label.update(f"Last API error: {short}") + else: + label.update("") + + def _set_batch_progress(self, current: int, total: int, path: Path) -> None: + self.query_one("#selection-label", Label).update( + f"Running batch {current}/{total}: {path.name}" + ) + def _mode_label(self) -> str: if self.output_mode == "sibling": return "Output mode: sibling (*.restructured.md next to source)" @@ -256,6 +296,14 @@ def _mode_label(self) -> str: return "Output mode: in-place (overwrite source)" return "Output mode: out_dir (use input below)" + def _skill_label(self) -> str: + sid = self.skill_id or "(default)" + if self._skill_cycle_ids: + idx = self._skill_cycle_index + 1 + total = len(self._skill_cycle_ids) + return f"Skill: {sid} ({idx}/{total}, press S to cycle)" + return f"Skill: {sid}" + def _selection_label(self) -> str: if not self.selected: return "Selected: (none)" @@ -297,6 +345,7 @@ def refresh_listing(self) -> None: self.query_one("#path-label", Label).update(str(self.cwd)) self.query_one("#mode-label", Label).update(self._mode_label()) + self.query_one("#skill-label", Label).update(self._skill_label()) self.query_one("#selection-label", Label).update(self._selection_label()) self.query_one("#filter-label", Label).update(self._filter_status()) @@ -562,6 +611,15 @@ def action_cycle_output(self) -> None: self.output_mode = order[(i + 1) % len(order)] self.query_one("#mode-label", Label).update(self._mode_label()) + def action_cycle_skill(self) -> None: + if not self._skill_cycle_ids: + self.log_msg("[yellow]No bundled skills to cycle.[/]") + return + self._skill_cycle_index = (self._skill_cycle_index + 1) % len(self._skill_cycle_ids) + self.skill_id = self._skill_cycle_ids[self._skill_cycle_index] + self.query_one("#skill-label", Label).update(self._skill_label()) + self.log_msg(f"[cyan]Skill set to[/] {self.skill_id}") + def action_focus_out_dir(self) -> None: self.query_one("#out-dir", Input).focus() @@ -576,7 +634,11 @@ def thread_log(msg: str) -> None: max_tokens=self.max_tokens, ) ok = 0 - for job in jobs: + total = len(jobs) + self.call_from_thread(self._set_api_error, None) + for index, job in enumerate(jobs, start=1): + self.call_from_thread(self._set_batch_progress, index, total, job.src) + thread_log(f"[cyan]Batch {index}/{total}:[/] {job.src.name}") try: result = process_job_with_provider( job, @@ -590,9 +652,19 @@ def thread_log(msg: str) -> None: ) if result.ok: ok += 1 + else: + err = result.error or "processing failed" + self.call_from_thread(self._set_api_error, err) + thread_log(f"[red]FAILED[/] {job.src}: {err}") except Exception as e: + err = str(e) + self.call_from_thread(self._set_api_error, err) thread_log(f"[red]FAILED[/] {job.src}: {e}") - thread_log(f"[bold]Done.[/] {ok}/{len(jobs)} succeeded.") + self.call_from_thread( + self.query_one("#selection-label", Label).update, + self._selection_label(), + ) + thread_log(f"[bold]Done.[/] {ok}/{total} succeeded.") async def action_run_mda(self) -> None: if not self.selected: diff --git a/pyproject.toml b/pyproject.toml index 152e594..bb4cfe7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "mda-cli" -version = "0.2.9" +version = "0.2.10" description = "CLI wrapper for Markdown Document Architect — restructure Markdown via Anthropic using local SKILL.md + MDA-STANDARD.md" readme = "README.md" requires-python = ">=3.10" diff --git a/scripts/flatten_vault_md.py b/scripts/flatten_vault_md.py index 8141e72..54d6e65 100644 --- a/scripts/flatten_vault_md.py +++ b/scripts/flatten_vault_md.py @@ -76,10 +76,11 @@ def main() -> int: print(f"ERROR {src}: {e}", file=sys.stderr) errors += 1 - print( - f"Done. moved={moved} already_in_root={skipped_root} errors={errors} dry_run={args.dry_run}", - file=sys.stderr, + summary = ( + f"Done. moved={moved} already_in_root={skipped_root} " + f"errors={errors} dry_run={args.dry_run}" ) + print(summary, file=sys.stderr) return 0 if errors == 0 else 1 diff --git a/scripts/inspect_textual.py b/scripts/inspect_textual.py index 81e79e2..b4cbbc4 100644 --- a/scripts/inspect_textual.py +++ b/scripts/inspect_textual.py @@ -1,4 +1,5 @@ import inspect + from textual.app import App print("run_test:", App.run_test) diff --git a/scripts/install-global.ps1 b/scripts/install-global.ps1 index 6fbd102..0ab10b6 100644 --- a/scripts/install-global.ps1 +++ b/scripts/install-global.ps1 @@ -1,14 +1,99 @@ # Install mda-cli and ensure `mda` is on the user PATH (no admin required). # Usage: pwsh -File scripts\install-global.ps1 +# +# Optional: set MDA_PYTHON to a specific python.exe before running. $ErrorActionPreference = 'Stop' -$Python = 'C:\Users\Admin\AppData\Local\Programs\Python\Python313\python.exe' -if (-not (Test-Path $Python)) { - $Python = (Get-Command python -ErrorAction SilentlyContinue)?.Source - if (-not $Python) { throw 'Python not found. Set $Python at the top of this script or install Python 3.10+.' } +function Get-MdaPythonExecutable { + if ($env:MDA_PYTHON) { + $explicit = $env:MDA_PYTHON.Trim().Trim('"') + if (Test-Path $explicit) { + return (Resolve-Path $explicit).Path + } + throw "MDA_PYTHON is set but not found: $explicit" + } + + $seen = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase) + $candidates = [System.Collections.Generic.List[string]]::new() + + function Add-Candidate([string]$Path) { + if ([string]::IsNullOrWhiteSpace($Path)) { return } + try { + $resolved = (Resolve-Path -LiteralPath $Path -ErrorAction Stop).Path + } + catch { + return + } + if ($seen.Add($resolved)) { + [void]$candidates.Add($resolved) + } + } + + $pyCmd = Get-Command py -ErrorAction SilentlyContinue + if ($pyCmd) { + foreach ($ver in @('-3.13', '-3.12', '-3.11', '-3.10')) { + try { + $out = & py $ver -c "import sys; print(sys.executable)" 2>$null + if ($LASTEXITCODE -eq 0 -and $out) { + Add-Candidate ($out.Trim()) + } + } + catch { } + } + } + + foreach ($name in @('python3', 'python')) { + $cmd = Get-Command $name -ErrorAction SilentlyContinue + if ($cmd) { Add-Candidate $cmd.Source } + } + + $localApp = [Environment]::GetFolderPath('LocalApplicationData') + if ($localApp) { + Get-ChildItem -Path (Join-Path $localApp 'Programs\Python') -Filter 'python.exe' -Recurse -ErrorAction SilentlyContinue | + ForEach-Object { Add-Candidate $_.FullName } + } + + foreach ($candidate in $candidates) { + try { + $version = & $candidate -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null + if ($LASTEXITCODE -ne 0) { continue } + $parts = $version.Trim().Split('.') + if ($parts.Count -ge 2) { + $major = [int]$parts[0] + $minor = [int]$parts[1] + if ($major -eq 3 -and $minor -ge 10) { + return $candidate + } + } + } + catch { } + } + + throw @( + 'Python 3.10+ not found.' + 'Install Python, set MDA_PYTHON to python.exe, or ensure `py -3.12` / `python` works.' + ) -join ' ' +} + +function Stop-MdaInstallProcesses { + $stopped = $false + foreach ($procName in @('mda', 'mda-cli', 'mda-tui')) { + $procs = Get-Process -Name $procName -ErrorAction SilentlyContinue + if ($procs) { + $procs | Stop-Process -Force -ErrorAction SilentlyContinue + $stopped = $true + } + } + if ($stopped) { + Write-Host 'Stopped running mda process(es) so pip can replace mda.exe.' + Start-Sleep -Milliseconds 750 + } } +$Python = Get-MdaPythonExecutable +Write-Host "Using Python: $Python" + $RepoRoot = Split-Path -Parent $PSScriptRoot if (-not (Test-Path (Join-Path $RepoRoot 'pyproject.toml'))) { throw "pyproject.toml not found under $RepoRoot" @@ -16,6 +101,8 @@ if (-not (Test-Path (Join-Path $RepoRoot 'pyproject.toml'))) { $ScriptsDir = Join-Path (Split-Path -Parent $Python) 'Scripts' +Stop-MdaInstallProcesses + Write-Host "Installing mda-cli from $RepoRoot ..." & $Python -m pip install -e $RepoRoot if ($LASTEXITCODE -ne 0) { throw "pip install failed (exit $LASTEXITCODE)" } diff --git a/tests/test_backup.py b/tests/test_backup.py new file mode 100644 index 0000000..bf1027e --- /dev/null +++ b/tests/test_backup.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from pathlib import Path + +from mda_cli.backup import ( + list_manifest_files, + load_manifest, + summarize_manifest, + write_batch_manifest, +) +from mda_cli.cli import main +from mda_cli.core import Job, JobResult + + +def test_write_and_list_manifest(tmp_path: Path, monkeypatch) -> None: + monkeypatch.setenv("MDA_MANIFEST_DIR", str(tmp_path)) + job = Job(src=Path("a.md"), dst=Path("a.md")) + result = JobResult( + job=job, + ok=True, + action="wrote", + changed=True, + backup_path=Path("a.md.bak"), + ) + path = write_batch_manifest( + run_id="20260101T120000Z", + results=[result], + skill_id="markdown-document-architect", + provider="anthropic", + target=Path("vault"), + in_place=True, + backup_enabled=True, + manifest_dir=tmp_path, + ) + assert path.is_file() + data = load_manifest(path) + assert data["run_id"] == "20260101T120000Z" + assert data["job_count"] == 1 + entries = data["entries"] + assert isinstance(entries, list) + assert entries[0]["backup_path"] == "a.md.bak" + listed = list_manifest_files(tmp_path) + assert listed == [path] + summary = summarize_manifest(data) + assert "backups=1" in summary + + +def test_restore_list_empty(tmp_path: Path, monkeypatch, capsys) -> None: + monkeypatch.setenv("MDA_MANIFEST_DIR", str(tmp_path / "empty")) + assert main(["restore", "--list"]) == 0 + out = capsys.readouterr().out + assert "No backup manifests" in out + + +def test_restore_list_shows_manifest(tmp_path: Path, monkeypatch, capsys) -> None: + monkeypatch.setenv("MDA_MANIFEST_DIR", str(tmp_path)) + write_batch_manifest( + run_id="20260102T000000Z", + results=[], + skill_id="categorize-vault-notes", + provider=None, + target=None, + in_place=False, + backup_enabled=False, + manifest_dir=tmp_path, + ) + assert main(["restore", "--list"]) == 0 + out = capsys.readouterr().out + assert "20260102T000000Z" in out diff --git a/tests/test_core.py b/tests/test_core.py index 913129b..b19b5cb 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -262,7 +262,7 @@ def test_write_output_text_creates_backup(tmp_path: Path) -> None: changed, backup_path, bytes_out = write_output_text(dst, "new\n", create_backup=True) assert changed is True - assert bytes_out == len("new\n".encode("utf-8")) + assert bytes_out == len(b"new\n") assert backup_path is not None assert backup_path.read_text(encoding="utf-8") == "old\n" assert dst.read_text(encoding="utf-8") == "new\n" @@ -276,7 +276,7 @@ def test_write_output_text_unchanged_skips_rewrite(tmp_path: Path) -> None: assert changed is False assert backup_path is None - assert bytes_out == len("same\n".encode("utf-8")) + assert bytes_out == len(b"same\n") def test_process_job_returns_metadata_and_backup( diff --git a/tests/test_folder_picker.py b/tests/test_folder_picker.py index 5ebaf64..e1f06e6 100644 --- a/tests/test_folder_picker.py +++ b/tests/test_folder_picker.py @@ -24,7 +24,6 @@ async def test_folder_picker_use_folder(tmp_path: Path, monkeypatch: pytest.Monk vault.mkdir() (vault / "one.md").write_text("# One", encoding="utf-8") - cfg_file = tmp_path / "config.json" monkeypatch.setattr("mda_cli.folder_picker.set_last_folder", lambda p: None) app = FolderPickerApp(start=vault) diff --git a/tests/test_plan_moves.py b/tests/test_plan_moves.py new file mode 100644 index 0000000..2e722fe --- /dev/null +++ b/tests/test_plan_moves.py @@ -0,0 +1,62 @@ +from __future__ import annotations + +from pathlib import Path + +import pytest + +from mda_cli.cli import main + +_BUNDLED_CATEGORIZE = ( + Path(__file__).resolve().parents[1] / "mda_cli" / "bundled_skills" / "categorize-vault-notes" +) + + +def test_plan_moves_dry_run_by_default(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + vault = tmp_path / "vault" + vault.mkdir() + note = vault / "note.md" + note.write_text("---\nfolder: inbox\n---\n# Note\n", encoding="utf-8") + dest = vault / "inbox" / "note.md" + + monkeypatch.setenv("MDA_SKILL_DIR", str(_BUNDLED_CATEGORIZE)) + assert ( + main( + [ + "script", + "plan_moves", + "--skill", + "categorize-vault-notes", + "--", + str(vault), + ] + ) + == 0 + ) + assert note.resolve() == (vault / "note.md").resolve() + assert not dest.exists() + + +def test_plan_moves_apply_moves_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + vault = tmp_path / "vault" + vault.mkdir() + note = vault / "note.md" + note.write_text("---\nfolder: inbox\n---\n# Note\n", encoding="utf-8") + dest = vault / "inbox" / "note.md" + + monkeypatch.setenv("MDA_SKILL_DIR", str(_BUNDLED_CATEGORIZE)) + assert ( + main( + [ + "script", + "plan_moves", + "--skill", + "categorize-vault-notes", + "--", + str(vault), + "--apply", + ] + ) + == 0 + ) + assert not note.exists() + assert dest.is_file() diff --git a/tests/test_providers.py b/tests/test_providers.py index 5c3ec28..914a0bf 100644 --- a/tests/test_providers.py +++ b/tests/test_providers.py @@ -13,8 +13,8 @@ build_restructure_client, openrouter_api_key_set, openrouter_fallback_enabled, - resolve_provider_name, resolve_model, + resolve_provider_name, )