toolkit-ng

CLI and Ink TUI for managing ECEF and WMS Docker stacks.

Requirements

• Node.js 20+

Install

If you publish this package without a scope:

npm install -g toolkit-ng

If you publish it under a user or organization scope, replace the package name accordingly:

npm install -g @your-scope/toolkit-ng

Usage

Initialize from the directory that should contain the generated workspace. The workspace root is created as ./<server_name> and contains config/session.json. The toolkit only reads config/version.json if an external process creates it.

toolkit --help
toolkit init --name unidad-01 --type unit --state jalisco --seq 01 --env dev
toolkit init --name central-01 --type central --seq 01 --env dev
toolkit init --name unidad-01 --type unit --state jalisco --seq 01 --env qa --net custom-net --ecef-sync http://ecef-sync.local --wms-sync http://wms-sync.local
cd unidad-01 && toolkit
toolkit --print-instance-root
toolkit env ecef
toolkit start ecef
toolkit stop ecef

toolkit init requires --name, --type and --seq. Units also require --state; central servers may omit it and are stored as central. --env defaults to dev, --net defaults to <server_name>-net, and --ecef-sync/--wms-sync are optional registration URLs stored in projects.<project>.config.sync.registration_url.

State catalog

Bootstrap stores both system.state and system.state_prefix. Unit base prefixes use the two-letter RENAPO/CURP entity codes. The persisted prefix appends sequence_id without leading zeroes while preserving sequence_id itself; for example, puebla/01, jalisco/09, chihuahua/10 and central/01 produce PL1, JC9, CH10 and CT1. central uses the internal base prefix CT because it is not a federal entity.

| State | Base prefix | State | Base prefix | |---|---:|---|---:| | aguascalientes | AS | baja-california | BC | | baja-california-sur | BS | campeche | CC | | chiapas | CS | chihuahua | CH | | ciudad-de-mexico | DF | coahuila | CL | | colima | CM | durango | DG | | guanajuato | GT | guerrero | GR | | hidalgo | HG | jalisco | JC | | estado-de-mexico | MC | michoacan | MN | | morelos | MS | nayarit | NT | | nuevo-leon | NL | oaxaca | OC | | puebla | PL | queretaro | QT | | quintana-roo | QR | san-luis-potosi | SP | | sinaloa | SL | sonora | SR | | tabasco | TC | tamaulipas | TS | | tlaxcala | TL | veracruz | VZ | | yucatan | YN | zacatecas | ZS | | central | CT | | |

The generated ECEF and WMS .env files expose the composed value as STATE_PREFIX inside CONFIGURACION BASE. Metadata without state_prefix derives it from the known state and numeric sequence_id; an explicit prefix must match that composition. Legacy cdmx, mexico and estado-mexico state values are supported only for read-time state resolution.

Sources: the CURP normative instructions published by DOF, their 2021 amendment, and the official CURP service.

Generated config files use the shared ECEF root while keeping one .env per project, for example /etc/erillamhc/ecef/unidad-01/ecef/.env and /etc/erillamhc/ecef/unidad-01/wms/.env. Project data is separated by project, for example /var/lib/erillamhc/ecef/unidad-01/ecef/files and /var/lib/erillamhc/ecef/unidad-01/wms/files.

Without --action and without --non-interactive, the command opens the Ink TUI.

Development

From the repository:

npm install
npm run build
npm start -- --help

Inspect the Ink TUI

Ink supports React DevTools. Use two terminals with the toolkit package scripts:

npm run dev:inspect

npm run devtools

dev:inspect keeps the TUI running with tsx watch and DEV=true; devtools opens the existing standalone React DevTools inspector for the Ink component tree.

From an instance root that does not contain package.json, run the same scripts through the repo path:

npm --prefix <repo>/toolkit-ng run dev:inspect

npm --prefix <repo>/toolkit-ng run devtools

Publish

Review the package and publish it manually:

npm login
npm run release:check
npm publish

If you change the package name to a scoped name such as @your-scope/toolkit-ng, publish it as public:

npm publish --access public

The test suite includes the state catalog, role validation, metadata fallback, and STATE_PREFIX rendering contract. release:check still runs build and package validation; execute npm test separately.