Skip to content

refactor(scripts): compute worktree slots and ports in one place - #3248

Merged
kodiakhq[bot] merged 4 commits into
mainfrom
dev-slots-refactor
Sep 30, 2026
Merged

kodiakhq[bot] merged 4 commits into
mainfrom
dev-slots-refactor

Conversation

@karl-power

Copy link
Copy Markdown
Contributor

Why

Each worktree gets a slot (0-99), and every service's port is a fixed base number plus that slot. The slot formula, cksum of the folder name mod 100, was copied into dev-env.sh, test-e2e.sh, the Makefile and seed-alerts.ts, and the port numbers were repeated alongside it. The copies could drift, and one already had: the dev portal added up character codes instead of using cksum, so it computed the wrong slot for its own worktree.

Tools that only needed the ports had a second problem. hdx-eval got them by sourcing dev-env.sh, which also clears packages/app/.next and registers the stack with the dev portal. Doing that while yarn dev is running disrupts the running stack.

Separately, worktrees that share a folder name (a/hyperdx, b/hyperdx) always got the same slot, so their stacks clashed.

What changed

  • scripts/slots.sh is now the only place slots and ports are computed: hdx_dev_ports, hdx_ci_ports, hdx_e2e_ports. Sourcing it only sets and exports variables. It writes, starts and prints nothing.
  • scripts/with-slots.sh <command> runs a command with this worktree's dev ports set. seed:alerts now uses it.
  • Callers switched to slots.sh: dev-env.sh, test-e2e.sh, the Makefile, hdx-eval's env.sh, and the dev portal. This fixes the portal's wrong slot, and hdx-eval no longer touches a running stack.
  • HDX_SLOT_FROM=path is a new opt-in setting that hashes the worktree's full path instead of its folder name. Set it in your shell profile if your worktrees share a folder name. Without it, nothing changes.

Default ports are unchanged

With HDX_SLOT_FROM unset, every slot and port value is the same as on main, so existing stacks and their .volumes/*_<slot> data folders keep working. One small difference: the slot is now hashed from the repo's top folder name, not the name of whatever folder the command runs in. From the repo root, where yarn dev and make run, both are the same name (hyperdx → slot 96). Run from a subfolder like packages/api, main would have hashed api and picked the wrong slot; this branch still hashes hyperdx.

The slot formula (cksum of the folder name, mod 100) was copied into
dev-env.sh, test-e2e.sh, the Makefile and seed-alerts.ts. The dev
portal used a different formula, so it picked the wrong slot.

Add scripts/slots.sh (hdx_dev_ports, hdx_ci_ports, hdx_e2e_ports) as
the only place slots and ports are computed. It has no side effects.
Add scripts/with-slots.sh for tools that need the dev ports. Every
caller now uses them. Default ports are unchanged.

Add HDX_SLOT_FROM=path, which hashes the worktree's full path instead
of its folder name, for worktrees that share a name (a/hyperdx,
b/hyperdx)
@changeset-bot

changeset-bot Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 7ce7b20

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel

vercel Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Sep 30, 2026 1:56pm UTC
hyperdx-storybook Ready Ready Preview Sep 30, 2026 1:56pm UTC

Request Review

@karl-power
karl-power requested review from a team and pulpdrew and removed request for a team September 30, 2026 10:27
@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 314 production lines changed (Tier 2 max: < 250)

Additional context: 1 file(s) in private internal-tooling packages, excluded from the line count

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 10
  • Production lines changed: 314 (+ 219 in test files, excluded from tier calculation)
  • Branch: dev-slots-refactor
  • Author: karl-power

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 128 in total (1.82%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

Comment thread Makefile Resolved
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

4 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 4 minor

1 posted as inline comment(s) on the changed lines. 3 listed below.

Findings outside the changed lines

3 minor
  • 🔵 scripts/dev-portal/server.js:390 — Dev portal still hardcodes E2E and integration port bases (21000, 21300, 19000), so slots.sh isn't the only source of ports → The PR and agent_docs/development.md say slots.sh is the only place ports are computed, but ENV_LOCAL_SERVICES in this file still adds its own basePort + slot, and the diff touches this file without fixing it. Either get the ports from slots.sh (hdx_e2e_ports/hdx_ci_ports with the slot pinned via HDX_E2E_SLOT/HDX_CI_SLOT) or add a comment naming slots.sh as the twin that must be kept in sync.
  • 🔵 scripts/__tests__/slots.test.mjs:563 — The 'no other code derives a slot' guard only greps for cksum, so it would miss the exact drift this PR fixes → The dev-portal bug this PR fixes summed char codes and never called cksum, so this test would not have caught it. Hardcoded port bases like server.js:390-393 also get past it. Also grep for the base-port literals (e.g. 30100|18123|21000|21300|19000) outside slots.sh, or rename the test so it doesn't claim more than it checks.
  • 🔵 Makefile:56 — Makefile still carries its own copy of the dev port table, which the PR removed everywhere else → The PR deleted the port-mapping comments from dev-env.sh, test-e2e.sh and the CI section so that slots.sh is the only reference, but the 30100 + slot … 31100 + slot table at Makefile:56-71 is still there. Replace it with a pointer to scripts/slots.sh, as the CI section above now does.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@greptile-apps

greptile-apps Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Medium risk] Consolidates slot and port computation into shared scripts.

The PR is not ready to merge while the outstanding repository comment requirement remains unmet.

Summary

This PR centralizes worktree slot and port calculation in scripts/slots.sh and switches development, test, portal, and tooling callers to it.

  • Adds an opt-in full-path slot key for worktrees with the same folder name.
  • Adds a side-effect-free command wrapper for tools that need dev-stack ports.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  W[Worktree] --> S[scripts/slots.sh]
  S --> D[Dev stack and tools]
  S --> C[Integration tests]
  S --> E[E2E tests]
  S --> P[Dev portal]
Loading

Reviews (4) · Last reviewed commit: "Merge branch 'main' into dev-slots-refac..."

Comment thread scripts/__tests__/slots.test.mjs Resolved
Comment thread scripts/__tests__/slots.test.mjs Resolved
Comment thread Makefile Resolved
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a dev-tooling refactor (shell, Makefile, Node portal, one TS script). Nothing touches production runtime, auth, or persisted product data. The core promise — default slots/ports byte-for-byte unchanged from main — is corroborated by scripts/__tests__/slots.test.mjs (e.g. hyperdx → slot 96, hyperdx-ee → slot 44) and holds across the caller paths I traced. The three prior review threads (Makefile 6→1 shell, cksum tripwire scoped to tracked files, node:test runner) are addressed in the current tree.

🟡 P2 — recommended

  • .github/actions/e2e-setup/action.yml:12 — The E2E base ports (20320, 20500, 20600, 21000, 21100, 21200, 21300) are hardcoded here and duplicated from hdx_e2e_ports in scripts/slots.sh, tied together only by a comment; the no other code derives a slot test guards the cksum formula but not these port bases, so editing an E2E base in slots.sh without updating this file silently desyncs CI from local runs.
    • Fix: Add a check (or reuse slots.sh at slot 0 in the action) that fails when the action's E2E base ports diverge from slots.sh.
🔵 P3 nitpicks (4)
  • packages/api/scripts/seed-alerts.ts:127 — devSlotMongoUri() rejects empty/undefined HDX_DEV_MONGO_PORT but interpolates any other value straight into the Mongo URI without checking it is numeric, so a malformed env value produces an opaque connection error instead of a clear message.
    • Fix: Validate HDX_DEV_MONGO_PORT parses to a positive integer before building the URI and throw the same actionable error otherwise.
  • scripts/dev-portal/server.js:700 — localSlot = Number(execFileSync(...)) yields 0 for empty output or NaN for non-numeric output; since localSlot is later compared with slot === localSlot, a 0 result could match slot-0 history and mislabel its fallback worktree.
    • Fix: Parse into a temporary, assign localSlot only when Number.isInteger holds, and leave it null otherwise.
  • scripts/with-slots.sh:12 — exec "$@" with no command argument makes the script exit 0 silently, giving no signal that the wrapper was misused.
    • Fix: Error out with a short usage message when $# is 0.
  • scripts/__tests__/slots.test.mjs:194 — The no other code derives a slot guard fails make ci-unit for any future tracked *.sh/*.js/*.mjs/*.ts/Makefile/*.yml file that legitimately mentions the word cksum, requiring a manual exclusion edit.
    • Fix: Acceptable as an intentional tripwire; consider matching the full slot expression rather than the bare word to reduce false positives.

Reviewers (8): correctness, testing, maintainability, project-standards, adversarial, performance, kieran-typescript, previous-comments.

Testing gaps:

  • with-slots.sh is tested from the repo root but not from packages/api via the real ../../scripts/with-slots.sh path that yarn seed:alerts uses.
  • seed-alerts.ts's throw-when-HDX_DEV_MONGO_PORT-unset path has no test.
  • The dev-portal localSlot computation via slots.sh (the char-code-sum bug fix) is not covered by a test.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 389 passed • 1 skipped • 1571s

Status Count
✅ Passed 389
❌ Failed 0
⚠️ Flaky 0
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

- Makefile: compute the integration test slot and ports in one shell
  instead of six. The block runs on every make invocation; an empty
  target drops from ~190ms to ~78ms.
- slots.test.mjs: scan tracked files only, so a local scratch file that
  mentions cksum no longer fails `make ci-unit`.
Comment thread scripts/dev-portal/server.js Resolved
Comment thread scripts/slots.sh Resolved
@kodiakhq
kodiakhq Bot merged commit e1c9ddd into main Sep 30, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the dev-slots-refactor branch September 30, 2026 14:03

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 7ce7b20f Deployed Sep 30, 2026 by vercel[bot]
Preview – hyperdx-storybook — 7ce7b20f Deployed Sep 30, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants