@x12i/ports-manager

@x12i/ports-manager

Admin-managed local port map for x12i and exellix repos.

Source of truth: port-map.json — edited by org admins only.

Use this package only when a process binds a local TCP port. Import the zone for your repo, take defaults (or env overrides), and never bind ports on the avoid list.

Install

npm install @x12i/ports-manager

Also published as JSON:

node -e "console.log(require.resolve('@x12i/ports-manager/port-map.json'))"

Rules

Rule	Detail
One zone per product repo	Contiguous 20 ports (min–max) from 5100 upward
Tools pool	Shared zone tools = 10000–10999 (1000 ports) for platform kits / ephemeral binds
Even / odd	Even = API, odd = UI
Defaults	Every zone has api + ui; some zones add named defaults (e.g. Memorix, api-simulator)
Avoid	Never bind ports listed in avoid (AirPlay 5000/7000, Postgres 5432, Sonar 9000, …)
Quarantine	Never place or bind in 5000–5099

Memorix (this mono-repo)

Zone id: memorix → 5100–5119

Default	Port	Env
service / api	5100	MEMORIX_SERVICE_PORT
studio / ui	5101	MEMORIX_STUDIO_PORT or VITE_DEV_PORT
opxSource	5102	OPX_SOURCE_PORT
statusHub	5103	STACK_STATUS_PORT
knowxSource	5104	KNOWX_SOURCE_PORT
jobsApp	5105	JOBS_APP_PORT
knowxWorker	5106	(worker)
knowxControlPlane	5110	KNOWX_PORT
knowxApp	5111	KNOWX_APP_PORT
apiPlayground	5113	WORK_APIS_PLAYGROUND_PORT / API_PLAYGROUND_PORT (Work APIs Playground UI)

Local wrapper: scripts/memorix-ports.mjs.

api-simulator

Zone id: api-simulator → 5520–5539

Default	Port
api / libraryDemo	5520
ui / studio	5521
flowstate	5522
playground	5523

Ephemeral / multi-API binds from package simulators should use the tools pool below, not invent ports outside these zones.

memorix-generic-connectors

Zone id: memorix-generic-connectors → 7480–7499 (repo x12i/memorix-generic-connectors, not the memorix mono-repo zone)

Default	Port
api / sourceService	7480
ui / sourceStudio	7481
sourceSimulator	7482
targetService	7484
targetStudio	7485
targetSimulator	7486

memorix-graphier

Zone id: memorix-graphier → 7500–7519 (repo x12i/memorix-graphifier, not the memorix mono-repo zone)

Default	Port
api / service	7500
ui	7501

Additional Graphifier processes should take even/odd ports from 7502–7519 inside this zone (do not invent ports outside the zone).

vulnerabilities-skills (cyber-skills)

Zone id: vulnerabilities-skills → 7520–7539 (repo neociso-skills/vulnerabilities-skills). Aliases: cyber-skills, vulnerability-skills.

There is no GitHub skill x12i/port-manager and no npm package @x12i/port-manager. Agents: install @x12i/ports-manager and read SKILL.md in the package.

Default	Port	Role	Do not keep
api / topology	7520	API (even)	9101
ui / statusUi	7521	UI (odd)	9100
vulnRisk	7522	API (even)	9102

Remaining 7523–7539 are free inside the zone.

npx x12i-ports zone vulnerabilities-skills
npx x12i-ports zone cyber-skills

Tools packages (shared 1000-port pool)

Zone id: tools → 10000–10999

Use this for platform kits that bind only for demos, samples, or ephemeral processes:

• ports-manager
• core-service
• api-live-view
• x12i-docify (demos; product docs serve also has zone docify 7460–7479)

createZonePorts({ zoneId: "tools" });
// defaults.api = 10000, defaults.ui = 10001 — pick unused even/odd ports inside the pool

Do not use 9000–9999 as a tools band — 9000 is on the avoid list (Sonar / common PHP).

API

import {
  createZonePorts,
  loadPortMap,
  isApiPort,
  isUiPort,
} from "@x12i/ports-manager";

const p = createZonePorts({
  zoneId: "memorix", // or "narrix", "servix", "exellix-engine", …
  env: {
    service: "MEMORIX_SERVICE_PORT",
    studio: ["MEMORIX_STUDIO_PORT", "VITE_DEV_PORT"],
    opxSource: "OPX_SOURCE_PORT",
    statusHub: "STACK_STATUS_PORT",
    api: "MEMORIX_SERVICE_PORT",
    ui: "MEMORIX_STUDIO_PORT",
  },
});

p.ports.service; // 5100 unless env set
p.range; // { min: 5100, max: 5119, size: 20 }
p.assertInZone(5100); // throws if avoided / quarantined / outside zone
p.assertRole(5101, "ui"); // odd required
p.origin("127.0.0.1", p.ports.service); // http://127.0.0.1:5100/

Export	Role
loadPortMap()	Parse admin JSON
createZonePorts({ zoneId, env?, map? })	Resolve defaults + helpers for one zone
isApiPort / isUiPort	Even / odd checks

CLI

npx x12i-ports list              # all zones
npx x12i-ports zone memorix      # range + defaults
npx x12i-ports avoid             # never-bind list
npx x12i-ports check memorix 5100

Admins

Edit port-map.json only:

1. Add the product repo under zones with github, min, max, and defaults (api / ui minimum).
2. Keep 20-port product zones contiguous from 5100 upward (next free after vulnerabilities-skills is 7540).
3. Platform tools / ephemeral binds → zone tools (10000–10999); do not carve new 20-port strips for kit packages.
4. Extend avoid when a well-known OS/service port must never be bound.

Do not invent a second map. Historical pointer stub: archived/x12i-port-map/.

License

exellix-license