Skip to content

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

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:

~/.local/bin/cora   # v0.6.0 (binary release, but killed by Gatekeeper — see #313)
~/.cargo/bin/cora   # v0.6.0 (cargo build)
~/.bun/bin/cora     # v0.2.4 (stale npm — see #314)

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 docs: install instructions don't warn about multiple distribution channels causing PATH conflicts #314).

  4. Documents the macOS Gatekeeper workaround for the binary release (cross-link to bug: macOS binary release killed by Gatekeeper quarantine (com.apple.quarantine/provenance) #313).

Context

Surfaced while trying to run cora scan on a downstream project (codecoradev/rungu) 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