Source Classification

Source classification reference — category, location, lock state, and anonymous trials.

Every package source in Stackie carries two independent labels:

The two axes are orthogonal. A source’s category does not determine its location, and vice versa.

Category

Category encodes how closely a source is tied to a specific language toolchain.

When multiple sources can satisfy a block, Stackie picks the lowest-rank (most-preferred) applicable source. Ecosystem sources are preferred because they install into project-local directories that do not affect other tooling on the machine.

Why ecosystem beats managed

An npm install writes to node_modules/ inside your project. A Homebrew install writes to /usr/local/Cellar or /opt/homebrew. If both could provide Node.js, choosing npm keeps the installation contained. The managed source is a fallback when no ecosystem source applies.

Native sources run last because they typically fetch pre-built binaries from a remote URL or cache — they work everywhere but bypass ecosystem conventions.

Location

Location describes where packages land after installation.

Scoop is the only Managed source that supports Isolated installs — it uses per-user app directories on Windows. On macOS and Linux, Scoop is not available, so it does not appear.

Location is used by the sandbox to decide whether to bind-mount the source directory or rely on host-wide paths. Sources with supports_isolation = false always write to System paths and cannot be fully scoped to a sandbox.

Complete source reference

Lock state

Source preferences start locked when Stackie is first installed. Locked state preserves Stackie’s default ordering — category-ranked, then alphabetical within category.

When locked:

• Reordering sources via stackie source list or the dashboard returns a PreferencesLocked error.
• Enabling or disabling individual sources is also blocked.
• A banner is shown in both the TUI (stackie source list) and the dashboard Sources view.

Locked state is a UI-level guard, not a security boundary. It prevents accidental changes to the default ordering. It is not access control.

To change the source order, unlock first. In the TUI, navigate to the lock banner at the top of the screen and press Enter to toggle it off.

# TUI — navigate to the lock banner and press Enter to toggle
stackie source list

# Or edit your preferences file directly
~/.stackie/stackie.yaml

After unlocking, you can drag sources to a new position in the TUI, or edit the YAML:

sources:
  preferences:
    macos: [brew, npm, pip, gem]
    linux: [brew, npm, pip, gem]
    windows: [winget, npm, pip, gem]
  locked: false

To restore defaults, re-lock — Stackie resets the order to the category-ranked default:

stackie source list  # toggle lock back on via the TUI banner

Anonymous trial

When you run stackie auth anonymous, Stackie mints a temporary identity scoped to your current machine. Because anonymous sessions cannot persist preferences, they always use the category-ranked default order described above. The anonymous identity:

• Uses the locked default source ordering (Ecosystem > Managed > Native).
• Cannot persist custom source preferences across sessions — preferences are tied to a full account.
• Expires after a fixed period; sign in with a full account to keep your configuration.

See stackie auth anonymous --help for options.

Listing sources

# Show all registered sources with category and platform availability
stackie source list

# Verbose view: includes location and isolation support flag
stackie source list --verbose

The TUI view (stackie source list without --verbose) groups sources by category and shows the lock banner if preferences are locked.