@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