Skip to content

docs: install instructions don't warn about multiple distribution channels causing PATH conflicts #314

Description

@ajianaz

Documentation gap

The README/install docs describe how to install cora but don't warn users that three distribution channels exist simultaneously and can conflict on the same machine:

  1. GitHub release binary (~/.local/bin/cora or similar)
  2. cargo install cora-cli (~/.cargo/bin/cora)
  3. npm @codecora/cli (~/.bun/bin/cora or ~/.npm-global/bin/cora — currently v0.2.4, far behind)

Observed problem

On a real developer machine, all three were present simultaneously:

$ ls ~/.local/bin/cora ~/.cargo/bin/cora ~/.bun/bin/cora
/Users/mis-puragroup/.local/bin/cora   # v0.6.0 (binary release, but killed by Gatekeeper)
/Users/mis-puragroup/.cargo/bin/cora   # v0.6.0 (cargo build)
/Users/mis-puragroup/.bun/bin/cora     # v0.2.4 (stale npm)

which cora resolved to whichever appeared first in $PATH, which in this case was the stale npm v0.2.4, silently — no warning, no error. The user thinks they're on the current version.

Suggested doc improvement

Add a short "Installation" section that:

  1. Lists all supported install methods and recommends one primary method per platform.
  2. Includes a "Check your install" snippet:
    which cora && cora --version
    # If you see anything other than the latest version (currently 0.6.0),
    # remove the older binary or adjust your PATH.
  3. Warns that the npm package is currently stale (cross-link to the npm-staleness issue).
  4. Documents the macOS Gatekeeper workaround for the binary release (cross-link to the macOS-quarantine issue).

Context

Surfaced while trying to run cora scan on a downstream project and getting confusing results because v0.2.4 was silently being invoked. Cleaner install docs would have prevented a half-hour of debugging.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions