Skip to content

Packaging & install-path cleanup

The tool itself is solid — MCP surface works, pyproject.toml is a disciplined single source of truth for Python deps, extras-based subpackage opt-in is clean. But the umbrella repo is doing three jobs at once (tool code, dev-loop umbrella, research-data mirror), and end users pay for all three on uv tool install git+…. Separating them is small work with large DX gains.

A. uv tool install git+… is broken

uv tool install git+https://github.com/arashshahidi1997/projio fails because uv runs git submodule update --init --recursive by default. Two distinct problems:

  1. packages/figio has a broken URL in .gitmodules: url = ./packages/figio. This is a self-referential repo-relative path, not a standalone repo URL. Recursion into it cannot succeed.
  2. .projio/codio/mirrors/ registers 14 research-data submodules (snakemake, grobid×2, biblio-glutton, oadoi, openalex×6, pyzotero, zotero×2). These aren't runtime deps of projio — they're codio's mirrors of upstream research infra — yet every git-install pulls them.

Severity: high. uv tool install git+… is the natural "install from source" path for a Python CLI in 2026. Today it only completes with --no-recurse-submodules, which isn't advertised anywhere.

Fixes, priority order:

  • [ ] Move .projio/codio/mirrors/* out of the repo. Fetch lazily into ~/.cache/codio/mirrors/ on first use, or via a codio mirrors fetch subcommand. Tool repo should contain tool code.
  • [ ] Fix or drop the packages/figio submodule URL. One-line fix; unblocks users who know to pass --no-recurse-submodules.
  • [ ] Decide what packages/* submodules are for. PyPI extras already pull subpackages (projio[all] → indexio, biblio, notio, codio, pipeio, figio). Submodules duplicate this for the dev loop. Two clean options:
  • Drop from .gitmodules; provide scripts/dev-clone-siblings.sh for contributors.
  • Keep but declare update = none so they're opt-in.

B. pandoc is invisible to pip/uv users

pixi.toml declares pandoc >=3.1; pyproject.toml doesn't. pip/uv users hit opaque runtime errors on pandoc-backed features.

  • [ ] Add a pandoc extra that pulls pypandoc_binary (pandoc bundled as a wheel — no system install needed). Then uv tool install 'projio[all,pandoc]' is fully self-contained. datalad/git-annex stay pixi-only and get documented under "full environment".

C. Release/upgrade story is undocumented

Six subpackages on PyPI with loose >= pins and independent versions. uv tool upgrade projio may or may not pull fresh subpackages.

  • [ ] Document the install matrix in the README (proposed below).
  • [ ] Pick a versioning contract across sibling packages: lockstep (pin ==X.Y.Z) or genuinely independent (current). Flag the choice.
  • [ ] If the git-install path is preserved, document the uv tool upgrade projio --reinstall pitfall (uv doesn't refetch git revs on plain upgrade).

D. Repo hygiene

  • src/ layout — good.
  • pixi.toml correctly defers Python deps to pyproject.toml — keep this, call it out in CONTRIBUTING.md.
  • .gitmodules mixes "dev umbrella" submodules with "research data mirrors" — conflates two concerns. Resolved automatically by the §A cleanup.
  • Consider a config_version field in .projio/config.yml with a warn-on-mismatch check. Prevents "my config looks right but nothing works" tickets from config schema evolution.

E. MCP surface papercuts (non-blocking)

  • No tool returns "which note types have templates for THIS project" vs. globally configured. Would help when note_create fails.
  • No bulk operation surface (e.g., note_update_bulk(filter=..., patch=...)). Triaging 30 open tasks one-at-a-time is tedious.

Proposed README install matrix

Use case Command
End-user, CLI only uv tool install 'projio[all,pandoc]'
End-user, full env w/ datalad clone repo; pixi install
Developing projio git clone --no-recurse-submodules …; uv tool install -e '…/projio[all,pandoc,dev]'
Developing projio + sibling repos scripts/dev-clone-siblings.sh && uv tool install -e '…/projio[all,dev]' --with-editable …/notio …

After the §A fixes, this matrix is actually true. Today it isn't.

Priority ordering

  1. Move .projio/codio/mirrors/* out — biggest single win.
  2. Fix packages/figio submodule URL — one line, unblocks --no-recurse-submodules users.
  3. Add pandoc extra via pypandoc_binary — two-line pyproject change.
  4. Document install matrix + --no-recurse-submodules caveat — README edit.
  5. Drop packages/* from .gitmodules — bigger refactor; do last.

Verification notes (spot-checked against current tree)

  • .gitmodules line 28: url = ./packages/figio — confirmed self-referential.
  • .projio/codio/mirrors/ submodule count: 14 — confirmed.
  • .projio/config.yml line 13: notio.notes_dir: docs/log/ — honored (notes land at docs/log/). An earlier draft of this feedback claimed drift here; there is no drift. config_version recommendation in §D stands on its own merits, not on that example.