local

Utilities for local deployment.

The following files are expected to exist:

In the directory above the server’s root directory: mSTConfig.json, mIDConfig.json, mITConfig.json, sumoLog.json, kinesisLog.json, s3Log.json, customerConfig.json, key.json, and locationConfig.json. If they don’t exist when the script launches, defaults will be set up.

The service's package.json must provide the following fields. Setup exits with code 1 and lists every missing field otherwise:

 {
   "name": "Package name",
   "version": "Package version",
   "mimik": {
     "type": "Package type of the service, e.g., `mST`, `mIT`, `mID`, or a custom service type"
   },
   "swaggerFile": {
     "account": "Bitbucket workspace or SwaggerHub owner holding the API definition",
     "name": "Repository or API name of the API definition",
     "version": "Version of the API definition",
     "provider": "`bitbucket` (default) or `swaggerhub`"
   }
 }

• For mSTConfig.json:

 {
   "basePath": "Base path of the mST server, e.g., `/mST/v1`",
   "protocol": "Protocol for the mST server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mST server",
   "port": "Port for the mST server, e.g., `8025`",
   "passphrase": "Passphrase used to generate the public/private key pair; if not present, mST will use a regular key",
   "update": "Whether mST should be updated (default: `false`). If the address is localhost, mST will be updated.",
   "admin": {
     "clientId": "Client ID used to obtain an mST admin token, e.g., `12345`",
     "clientSecret": "Client secret used to obtain an mST admin token, e.g., `timeForSecret`"
   }
 }

domainName must exist. When domainName is localhost, port must also exist. When domainName is localhost, the local IP will replace localhost. When domainName is different from localhost, port is ignored.

• For mIDConfig.json:

 {
   "basePath": "Base path of the mID server, e.g., `/mID/v1`",
   "protocol": "Protocol for the mID server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mID server",
   "port": "Port for the mID server, e.g., `8015`",
   "implicit": {
     "key": "Key to sign and verify the signature of a user token, e.g., `timeForSecret`",
     "audience": "URL defining the audience used in the user token, e.g., `https://mimik`"
   }
 }

The same domainName/port rules as in mSTConfig.json apply.

• For mITConfig.json:

 {
   "basePath": "Base path of the mIT server, e.g., `/mIT/v1`",
   "protocol": "Protocol for the mIT server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mIT server",
   "port": "Port for the mIT server, e.g., `8050`"
 }

The same domainName/port rules as in mSTConfig.json apply.

• For sumoLog.json:

 {
   "<packageType>": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   },
   "default": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   }
 }

• For kinesisLog.json:

 {
   "region": "Region of the Kinesis implementation",
   "accessKeyId": "Access key ID for Kinesis",
   "secretAccessKey": "Secret access key for Kinesis",
   "streamNameInfo": "Name of the Kinesis stream for info",
   "streamNameError": "Name of the Kinesis stream for errors",
   "streamNameOther": "Name of the Kinesis stream for all other levels",
   "maxEvents": "Number of events buffered before sending to Kinesis",
   "timeout": "Number of minutes before a timeout triggers sending to Kinesis",
   "maxSize": "Maximum size in bytes before sending to Kinesis",
   "maxRetries": "Maximum retries to connect to Kinesis",
   "httpOptions": {
      "socketTimeout": "Socket timeout for the HTTP handler (in milliseconds)",
      "connectionTimeout": "Connection timeout for the HTTP handler (in milliseconds)"
   }
 }

• For s3Log.json:

 {
   "region": "Region of the S3 implementation",
   "accessKeyId": "Access key ID for S3",
   "secretAccessKey": "Secret access key for S3",
   "bucketname": "Name of the S3 bucket used to store information",
   "maxEvents": "Number of events buffered before sending to S3",
   "timeout": "Number of minutes before a timeout triggers sending to S3",
   "maxSize": "Maximum size in bytes before sending to S3"
 }

• For key.json:

 {
   "bitbucket": {
     "username": "Username to access the Bitbucket account",
     "password": "Password to access the Bitbucket account"
   },
   "swaggerhub": "Key to access private APIs on SwaggerHub"
 }

• For locationConfig.json:

 {
   "url": "URL of the location provider",
   "key": "API key used to make requests to the location provider"
 }

In sumoLog.json, a property may be defined for each package type involved (the mimik.type value of the service's package.json, not SERVER_TYPE). If the package type does not exist, the default entry is used.

• For customerConfig.json: see mST README.md file for an example of a customer configuration. This may have to be updated to reflect the new server.
• In the local directory under the server's root directory, two files (start.json and testStart.json) drive per-invocation configuration. start.json is used when npm start is executed; testStart.json is used when npm test is executed. They are created automatically on first run if missing: start.json is seeded from start-example.json, and testStart.json is seeded from start-example.json merged with testStart-example.json (values in testStart-example.json take precedence). The configuration of these files depends on the server's configuration parameters.

Example start.json for mIT:

 {
   "NODE_ENV": "local",
   "LOG_LEVEL": "debug",
   "CONSOLE_LEVEL": "silly",
   "DATABASE_NAME": "itResources",
   "SERVER_PORT": 8050,
   "IP_LOCATION_PROVIDER": "http://localhost:9000/json",
   // "LOCATION_PROVIDER": "http://ip-api.com/json",
   // "DEBUG": "swagger-tools:middleware.*",
   "SERVER_SECURITY_SET": "off"
 }

Although all files use the .json extension, you may still add // comments to make them more explicit or to remove parameters.

Reserved environment variables used by the library for configuration:

• oauthImplicitNeeded: set to 'yes' when the service handles user tokens. Seeds OAUTH_IMPLICIT_AUDIENCE, OAUTH_IMPLICIT_KEY, and OAUTH_IMPLICIT_ISSUER from the mID configuration.
• mIDNeeded: if the service targets mID
• locationNeeded: if location translation is needed
• standAlone: if the service must operate without other services (if the service has targets, 500 errors are likely)
• MST_SET: when set to 'off', the service runs without any mST interaction (similar to standAlone, but keeps the provided customerConfig). Any other value — or omission — leaves mST enabled.
• SERVER_TYPE: the type under which the service registers with mST and resolves its customer targets. Defaults to the package type (mimik.type). A service whose package type is not mST, mIT, or mID may set it in start.json/testStart.json to run the same package under another type; ADMIN_EXTERNAL_ID, the mST client, and the customer targets then follow SERVER_TYPE, while sumoLog.json is still looked up by package type. For mST, mIT, and mID a provided value is ignored with a warning.
• LOG_MODE: comma-separated list selecting log targets from sumologic, awsS3, awsKinesis, all, none. When omitted, defaults to sumologic. all expands to sumologic,awsS3. none cannot be combined with other modes.

If SERVER_ID is not set in start.json or testStart.json, it will be assigned using randomUUID() from node:crypto.

Bundled toolchain

@mimik/local deliberately lists its toolchain in dependencies rather than devDependencies, so a consumer service gets it transitively from this single package: ESLint and the plugins used by the shipped preset, husky for the generated hooks, the test stack assumed by the scripts installed by scripts() (mocha, mochawesome, c8, chai, sinon), and jsdoc-to-markdown for the docs script. This relies on package hoisting. With pnpm, or any strict node_modules layout, add the packages your service imports directly to its own package.json.

Preset + service overrides

dotFiles() uses a preset + override split for two generated files so the shared presets can evolve without losing service-specific exceptions.

ESLint

• eslint.config.js — managed entry, always overwritten on every npm install. It is a thin wrapper that imports @mimik/local/dotFiles/eslint.preset.js and merges eslint.overrides.js. Do not edit it by hand.
• eslint.overrides.js — developer-owned, seeded only if missing. Commit it. Add flat-config objects here; they are merged after the preset (last write wins).

Example eslint.overrides.js:

export default [
  {
    files: ['src/legacy/**'],
    rules: {
      'no-magic-numbers': ['off'],
    },
  },
];

.gitignore

• .gitignore — managed, always regenerated. Written as the gitIgnore.txt preset followed by the contents of .gitignore.local. Do not edit it by hand.
• .gitignore.local — developer-owned, seeded only if missing. Commit it. Add service-specific ignore patterns here.

Workflow (both splits)

1. npm install → managed files are (re)generated, override files are seeded once if missing.
2. Edit only the *.overrides.js / *.local files for service-specific exceptions and commit them.
3. When another developer clones and runs npm install, the managed files are refreshed from the package while the committed overrides are preserved.

The .husky/* hooks are always overwritten on every install — they have no override mechanism.

For tests, a JSON file (server-test.json) is created in the project root (.). This file contains information needed to start the tests:

 {
   "start": "Information needed to set environment variables for the test",
   "CUSTOMER_NAME": "Customer name used to set up customer config",
   "CUSTOMER_CODE": "Customer code used to set up customer config (`not available for mST`)",
   "BASE_PATH": "Base path of the API",
   "MST_TOKEN": "mST admin token for creating clients (`not available in standAlone`)",
   "ADMIN_TOKEN": "Admin token of the service (`not available in standAlone`)",
   "MID_TOKEN": "mID admin token for creating users when `oauthImplicitNeeded` is set (`not available in standAlone`)"
 }

In standAlone mode, the test can obtain tokens using oauth-helper-temp.

Example

// Default import
import local from '@mimik/local';

Example

// Named imports
import { mSTTestSetup, mSTSetup, mITTestSetup, mITSetup, testSetup, setup, dotFiles, scripts, unScripts, commitCheckMsg, start2process, testJsonFile } from '@mimik/local';

• local
  • static
    • .testJsonFile : string
  • inner
    • async
      • ~mSTTestSetup() ⇒ Promise.<void>
      • ~mSTSetup() ⇒ Promise.<void>
      • ~mITTestSetup() ⇒ Promise.<void>
      • ~mITSetup() ⇒ Promise.<void>
      • ~testSetup() ⇒ Promise.<void>
      • ~setup() ⇒ Promise.<void>
      • ~commitCheckMsg() ⇒ Promise
    • sync
      • ~dotFiles() ⇒ void
      • ~scripts() ⇒ void
      • ~unScripts() ⇒ void
      • ~start2process(start) ⇒ void

local.testJsonFile : string

Path to the JSON test file.

Kind: static constant of local

local~mSTTestSetup() ⇒ Promise.<void>

Set up mST for tests.

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Actions performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Generate a JSON object and store it in a file in the project root (.) to enable tests.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/testStart.json | Local configuration (if it does not exist, start-example.json will be used to create testStart.json)
Category: async

local~mSTSetup() ⇒ Promise.<void>

Set up mST.

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Actions performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Generate a shell script in the project root (.) to start the server.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/start.json | Local configuration (if it does not exist, start-example.json will be used to create start.json)
Category: async

local~mITTestSetup() ⇒ Promise.<void>

Set up mIT for tests.

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Two modes are available:

1. Standalone
2. With mST

The standAlone: 'yes' key in start.json/testStart.json selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Register a dummy server locally; no tokens are issued.
3. Generate a JSON object and store it in a file under the project root (.).

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Register an admin client for the service in mST.
5. Obtain an admin token for the service.
6. Obtain an admin token for mID if needed.
7. Generate a JSON object and store it in a file under the project root (.).

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/testStart.json | Local configuration (if it does not exist, start-example.json will be used to create testStart.json)
Category: async

local~mITSetup() ⇒ Promise.<void>

Set up mIT.

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Two modes are available:

1. Standalone
2. With mST

The standAlone: 'yes' key in start.json/testStart.json selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Register a dummy server locally; no tokens are issued.
3. Generate a shell script in the project root (.) to start the server.

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST is present, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Register an admin client for the service in mST.
5. Obtain an admin token for the service.
6. Generate a shell script in the project root (.) to start the server.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/start.json | Local configuration (if it does not exist, start-example.json will be used to create start.json)
Category: async

local~testSetup() ⇒ Promise.<void>

Set up a service (not mST or mIT) for tests.

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Two modes are available:

1. Standalone
2. With mST/mID and other dependent servers

The standAlone: 'yes' key in start.json/testStart.json selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Register a dummy server locally; no tokens are issued.
3. Generate a JSON object and store it in a file under the project root (.).

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Register an admin client for the service in mST.
6. Obtain an admin token for the service.
7. Obtain an admin token for mID if needed.
8. Generate a JSON object and store it in a file under the project root (.).

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../mIDConfig.json | mID configuration (when needed) | ../customerConfig.json | mST customer configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/testStart.json | Local configuration (if it does not exist, start-example.json will be used to create testStart.json)
Category: async

local~setup() ⇒ Promise.<void>

Set up a service (not mST or mIT).

Kind: inner method of local
Returns: Promise.<void> - On error, logs and calls process.exit(1).

Two modes are available:

1. Standalone
2. With mST/mID and other dependent servers

The standAlone: 'yes' key in start.json/testStart.json selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Register a dummy server locally; no tokens are issued.
3. Generate a shell script to start the server.

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from Bitbucket (the default) or from SwaggerHub, depending on swaggerFile.provider.
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Register an admin client for the service in mST.
6. Obtain an admin token for the service.
7. Generate a shell script in the project root (.) to start the server.

The following files are needed to perform these actions:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumo Logic endpoints and code | ../kinesisLog.json | Kinesis configuration | ../s3Log.json | S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../mIDConfig.json | mID configuration (when needed) | ../customerConfig.json | mST customer configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Bitbucket username and password or SwaggerHub key | ./local/start.json | Local configuration (if it does not exist, start-example.json will be used to create start.json)
Category: async

local~commitCheckMsg() ⇒ Promise

Check the validity of the commit message.

Kind: inner method of local
Category: async
Fulfil: null.

Exits with code 1 if the commit message is not correct or if the branch is not a Jira generated branch.

local~dotFiles() ⇒ void

Utility to create rule files.

Kind: inner method of local
Returns: void - Writes the following files into the consumer project:

• ESLint (preset + overrides split)

  • eslint.config.js — managed entry, always overwritten. Imports the preset shipped by @mimik/local and merges eslint.overrides.js.
  • eslint.overrides.js — developer-owned, seeded only if missing. Commit it; edit it to add service-specific rule exceptions.

• .gitignore (preset + local split)

  • .gitignore — managed, always regenerated as gitIgnore.txt preset followed by the contents of .gitignore.local.
  • .gitignore.local — developer-owned, seeded only if missing. Commit it; edit it to add service-specific ignore patterns.

• Always overwritten on every install (no override mechanism):

  • .husky/pre-commit, .husky/pre-push, .husky/commit-msg
    Category: sync
    

local~scripts() ⇒ void

Utility to add scripts to package.json.

Kind: inner method of local
Returns: void - Adds scripts to package.json. If a script already exists, it will be overwritten.

The installed scripts assume the consumer repo follows these mimik-service conventions:

• docs → jsdoc2md ./src/configuration/config.js > README.md
• pretest → node ./local/testSetup.js
• test → runs mocha against test/normal/ with test/src/set-env.js as a preload file
• test-detached → runs mocha against test/detached/
• prestart → node ./local/setup.js
• start → sh server-start.sh (generated by mSTSetup() / mITSetup() / setup())

If a service uses a different layout it should call scripts() and then overwrite the specific entries in its own package.json, or skip calling scripts() entirely.
Category: sync

local~unScripts() ⇒ void

Utility to remove scripts from package.json.

Kind: inner method of local
Returns: void - Removes scripts from package.json. Only removes the scripts that are in the script file.
Category: sync

local~start2process(start) ⇒ void

Set up the environment variables based on given JSON object.

Kind: inner method of local
Category: sync

| Param | Type | Description | | --- | --- | --- | | start | object | JSON object that is used to configure the environment variables. The comments (starting by //) are ignored. |