feat: --ref affiliate referral code on install and login

[efenocchi]

What

Adds a --ref <code> flag to hivemind install and hivemind login that
carries an affiliate/influencer campaign code so a new signup can be
attributed to the referrer.

npm install -g @deeplake/hivemind && hivemind install --ref mario

The code only matters for a genuinely new registration; the backend ignores it
for already-registered users.

Changes

• src/cli/index.ts — parseRef() (mirrors parseToken), threads the code
  into the install and login paths, documents the flag in USAGE.
• src/cli/auth.ts — ensureLoggedIn(ref) passes it to login.
• src/commands/auth.ts — sends it as the X-Hivemind-Referrer header on
  POST /auth/device/code (same pattern as X-Hivemind-Install-Id). Trimmed
  here; the backend lowercases + validates against its affiliate registry.

The header is omitted entirely when no --ref is given.

Tests

• tests/cli/affiliate-ref.test.ts — header construction (trim / omit) and that
  requestDeviceCode puts X-Hivemind-Referrer on the wire only when a ref is
  given.
• tests/cli/cli-auth.test.ts — asserts the ref threads through to login().
• Full tsc, npm run build, and the cli suite stay green.

Pairs with

The deeplake-api PR that parks the code at /auth/device/code and records the
signup attribution. The flag is inert until that backend ships and codes exist.

Summary by CodeRabbit

• New Features

  • Added support for affiliate/referrer codes via an optional --ref <code> flag for authentication commands (e.g., hivemind install --ref <code> and hivemind login --ref <code>), applying the code during the login flow.

• Tests

  • Added/updated test coverage to verify --ref parsing/forwarding and that the referral header is sent (or omitted) correctly during device-code authorization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dfe913d6-5912-4e81-8e86-169875c9a454

📥 Commits

Reviewing files that changed from the base of the PR and between e19d539 and 340dc60.

📒 Files selected for processing (2)

• src/cli/index.ts
• tests/cli/cli-index.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/cli/index.ts

---

📝 Walkthrough

Walkthrough

Adds an optional --ref affiliate/referral code parameter to the Hivemind CLI's login and install flows. The value is parsed from argv by a new parseRef helper, forwarded through ensureLoggedIn and the full device-flow stack (login → deviceFlowLogin → requestDeviceCode), and emitted as the X-Hivemind-Referrer HTTP header via a new hivemindReferrerHeader helper. Help text and tests are updated accordingly.

Changes

Affiliate ref propagation through CLI login flow

Layer / File(s)	Summary
X-Hivemind-Referrer header and device flow threading src/commands/auth.ts	Adds exported hivemindReferrerHeader(ref?) that returns the X-Hivemind-Referrer header when ref is non-empty. Updates requestDeviceCode, deviceFlowLogin, and login to each accept and forward an optional ref parameter.
CLI arg parsing, ensureLoggedIn, and help text src/cli/auth.ts, src/cli/index.ts	Adds optional ref to ensureLoggedIn and passes it to login. Adds parseRef(args) to extract --ref/--ref=<code> from argv. Wires parseRef into the runAuthGate and login command handlers. Updates USAGE docs for install and login to document --ref <code>.
Tests tests/cli/affiliate-ref.test.ts, tests/cli/cli-auth.test.ts, tests/cli/cli-index.test.ts	Unit tests for hivemindReferrerHeader (valid input, whitespace trimming, missing/blank input). Fetch-stubbed tests for requestDeviceCode confirming the header is only sent when a ref is present. Updated and new ensureLoggedIn tests verifying the ref value is forwarded to login. CLI index tests for --ref argument parsing in the login command.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• activeloopai/hivemind#190: Modifies the same ensureLoggedIn/login call chain in src/cli/auth.ts and install gating in src/cli/index.ts, directly overlapping with the ref parameter propagation added here.
• activeloopai/hivemind#191: Also modifies requestDeviceCode header construction in src/commands/auth.ts to add an additional header (X-Hivemind-Install-Id), the same extension point used here for X-Hivemind-Referrer.

Suggested reviewers

• kaghni

🐇 A little --ref hops down the trail,
Through login, deviceFlow, without fail.
The header appears, X-Hivemind-Referrer set,
The affiliate gets credit — no need to fret!
Tests all pass, the bunny's proud today. 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly summarizes the main feature: adding a --ref affiliate referral code flag to install and login commands.
Description check	✅ Passed	The PR description comprehensively covers what changed, how it works, testing approach, and backend pairing; however, it lacks the Version Bump section from the template.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/affiliate-referral-code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[efenocchi]

Paired backend PR: activeloopai/deeplake-api#272 (parks the code and records the signup).

[github-actions]

Coverage Report

Scope: files changed in this PR. Enforced threshold: 90% per metric (per file via vitest.config.ts).

Status	Category	Percentage	Covered / Total
🟢	Lines	91.11% (🎯 90%)	369 / 405
🟢	Statements	91.58% (🎯 90%)	446 / 487
🟢	Functions	92.59% (🎯 90%)	50 / 54
🔴	Branches	88.96% (🎯 90%)	290 / 326

File Coverage — 3 files changed

File	Stmts	Branches	Functions	Lines
src/cli/auth.ts	🟢 100.0%	🟢 100.0%	🟢 100.0%	🟢 100.0%
src/cli/index.ts	🔴 86.7%	🔴 84.8%	🟢 100.0%	🔴 84.3%
src/commands/auth.ts	🟢 97.7%	🟢 93.4%	🔴 86.7%	🟢 100.0%

_{Generated for commit 5dde712.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/cli/index.ts`:
- Around line 198-205: The parseRef function currently accepts any argument
following the `--ref` flag as a referral code, including other flags. When using
the `--ref` format without an equals sign, add a validation check to ensure the
next argument does not start with `--` before assigning it to the raw variable,
since an argument starting with `--` is another flag and should not be treated
as a referral code value. If the next argument is a flag, return undefined
instead.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4094be62-d871-4f04-a7bc-f576cf0d3459

📥 Commits

Reviewing files that changed from the base of the PR and between df8a4d8 and e19d539.

📒 Files selected for processing (5)

• src/cli/auth.ts
• src/cli/index.ts
• src/commands/auth.ts
• tests/cli/affiliate-ref.test.ts
• tests/cli/cli-auth.test.ts

[khustup2]

Approved. Clean CLI-only change; X-Hivemind-Referrer contract matches the backend (deeplake-api #272, now merged). parseRef correctly rejects a following flag as the code (--ref --skip-auth → undefined), and header trim/omit is right. CI green. Inert until backend ships and affiliate_codes are populated.