#Monorepo Structure & Tooling

xtnd-vantage • Multi-Package Architecture, Tooling, Build & Test Suite

#1. Monorepo Organization

The xtnd-vantage repository is organized as an npm workspaces monorepo containing 8 published packages and 2 internal services:

xtnd-vantage/
├── package.json               # Root workspace manifest & orchestrator scripts
├── package-lock.json          # Root lockfile
├── tsconfig.base.json         # Shared TypeScript compiler base configuration
├── tools/
│   └── generate-version.mjs   # Automated Git commit & version metadata generator
├── packages/
│   ├── aegis/                 # @xtnd/vantage-aegis
│   ├── core/                  # @xtnd/vantage-core
│   ├── radar/                 # @xtnd/vantage-radar
│   ├── sentinel/              # @xtnd/vantage-sentinel
│   ├── sonar/                 # @xtnd/vantage-sonar
│   ├── storage-local/         # @xtnd/vantage-storage-local
│   ├── sync-manager/          # @xtnd/vantage-sync-manager
│   └── vantage/               # @xtnd/vantage (Unified facade)
├── tests/                     # Cross-package integration test suite
│   ├── ai-parsers-cost.test.mjs
│   ├── core-eventbus.test.mjs
│   ├── radar-sentinel.test.mjs
│   └── storage-sync.test.mjs
└── examples/                  # Developer sample code & usage demos
    ├── ai-proxy-stream/
    └── web-event-lifecycle/

#2. Shared TypeScript Configuration (tsconfig.base.json)

All packages inherit from tsconfig.base.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Outputs are written to dist/ in each package (dist/index.js and dist/index.d.ts).

#3. Version Generation Tool (tools/generate-version.mjs)

Every monorepo and standalone repository includes an automated build lifecycle script tools/generate-version.mjs.

#Execution Hooks

• Automatically runs on prebuild, pretest, prestart, and postinstall.
• Extracts the current Git short SHA via git rev-parse --short HEAD (with -dirty suffix if uncommitted changes exist).
• Captures current ISO 8601 timestamp in Asia/Bangkok time.
• Emits:
  • src/version.generated.ts: TypeScript constants (VERSION, GIT_SHA, BUILD_TIME).
  • public/version.json (for web services): JSON metadata for dashboard footers and health endpoints.

#4. Root NPM Scripts

{
  "scripts": {
    "generate:version": "node tools/generate-version.mjs",
    "prebuild": "node tools/generate-version.mjs",
    "prestart": "node tools/generate-version.mjs",
    "pretest": "node tools/generate-version.mjs",
    "postinstall": "node tools/generate-version.mjs",
    "bump:patch": "npm version patch --no-git-tag-version",
    "bump:minor": "npm version minor --no-git-tag-version",
    "bump:major": "npm version major --no-git-tag-version",
    "build": "npm run --workspaces --if-present build",
    "test": "node --test tests/core-eventbus.test.mjs tests/storage-sync.test.mjs tests/ai-parsers-cost.test.mjs tests/radar-sentinel.test.mjs"
  }
}

#5. Integration Test Suite (node:test)

XTND Vantage relies exclusively on native Node.js ESM testing (node:test and node:assert), eliminating heavy external test framework dependencies (Jest, Mocha, Vitest).