@neoimpulse/cap-js-bootstrap

SICP-compliant CAP multi-service bootstrap — startet lokale SAP-CAP-Entwicklungsumgebungen mit mehreren Services plus AppRouter.

Node.js ≥ 22

Installation

npm install @neoimpulse/cap-js-bootstrap

Verwendung

npx cap-js-bootstrap [options]

CLI-Parameter

| Flag | Beschreibung | |------|-------------| | --help | Hilfe anzeigen | | --debug | Node.js Debug-Modus für Services (Port + 1000) | | --with-bindings-update | Cloud-Foundry-Bindings & default-env.json aktualisieren | | --no-bindings | Bindings-Update deaktivieren (überschreibt withBindingsUpdate) | | --parallel | Services parallel starten (schneller) | | --verbose | Ausführliche Ausgabe aller Child-Prozesse | | --profile <name> | CDS-Profil (z. B. hybrid, pg) | | --runtime <js\|ts> | Runtime: js → cds, ts → cds-ts |

Neu: Fehler-Output (Stacktraces etc.) wird auch ohne --verbose angezeigt.

package.json: bootstrap-Konfiguration

{
  "bootstrap": {
    "debug": false,
    "withBindingsUpdate": false,
    "parallel": false,
    "verboseOutput": false,
    "profile": "hybrid",
    "runtime": "ts",
    "basePath": "./",
    "approuterPath": "router",
    "services": [
      {
        "path": "srv",
        "name": "my-srv",
        "port": 4004,
        "addPoolConfiguration": false,
        "boundServices": ["uaa", "destination", "connectivity"]
      }
    ]
  }
}

Felder

| Feld | Typ | Beschreibung | |------|-----|-------------| | debug | boolean | Debug-Ausgabe (per --debug überschreibbar) | | withBindingsUpdate | boolean | cds bind/default-env vor Start (per --with-bindings-update / --no-bindings) | | parallel | boolean | Parallelstart (per --parallel) | | verboseOutput | boolean | Detaillierte Logs (per --verbose) | | profile | string | CDS-Profil (per --profile) | | runtime | "js" \| "ts" | ts → cds-ts, js → cds | | basePath | string | Basisverzeichnis für Service-Pfade | | approuterPath | string | Pfad zum AppRouter relativ zu basePath | | services[].path | string | Relativer Pfad des Service | | services[].name | string | Service-Name für default-env/Bindings | | services[].port | number | HTTP-Port | | services[].boundServices | string[] | Externe CF-Services zum Binden | | services[].addPoolConfiguration | boolean | DB-Pool-Config in .cdsrc-private.json |

Ablauf

1. Stale-Orphan-Cleanup — Killt Prozesse des vorherigen Laufs via PID-File (.bootstrap.pids), verhindert Port-Konflikte
2. CF-Login-Check — Prüft ob cf services erfolgreich ist
3. Credentials (optional) — default-env.js + cds bind -2 für gebundene Services, mit isAlreadyBound-Check
4. Port-Bereinigung — fuser + PGID-Kill für alle Service-Ports + AppRouter (8008)
5. CAP-Services — cds watch pro Service, sequenziell oder parallel
6. AppRouter — cds bind --exec -- npm start
7. PID-Save — .bootstrap.pids für sauberen nächsten Start
8. Shutdown — SIGTERM → SIGKILL Fallback, löscht PID-File

Entwicklung

npm install
npm run build
npm test

# TypeScript direkt ausführen (ohne Build)
npx tsx src/index.ts --verbose

Scripts

| Script | Beschreibung | |--------|-------------| | npm run build | TypeScript → dist/ | | npm run typecheck | tsc --noEmit | | npm test | 60 Unit-Tests (node:test + tsx) | | npm run clean | rm -rf dist | | npm run rebuild | clean + build |

Architektur

Vier-Schichten-Architektur nach SICP-Prinzipien:

Layer 4: I/O & Orchestration   handlers/
Layer 3: Domain (Pure)         domain/
Layer 2: Generic Utils (Pure)  lib/
Layer 1: Language Primitives   JS/TS built-ins

Ordnerstruktur

src/
├── types.ts
├── index.ts                         # Main Entry Point
├── lib/                             # Layer 2: Pure Utility Functions
│   ├── result-helpers.ts
│   ├── array-utils.ts
│   └── string-utils.ts
├── domain/                          # Layer 3: Pure Domain Logic
│   ├── transformation.ts            # formatLine/Chunk, makePrefix, parseUserArgs, buildServiceTask
│   ├── calculation.ts               # calculateDebugPort, buildCdsWatchArgs, calculateStartupTime
│   └── validation.ts                # matchFirst, findMatchingPattern, hasRejectPattern
└── handlers/                        # Layer 4: I/O & Orchestration
    ├── process-operations.ts        # spawnProcess, waitForProcessOutput
    ├── process-cleanup.ts           # PID-Tracking (savePids, killStaleOrphans), Port-Bereinigung (freePorts)
    ├── service-operations.ts        # loadService, loadApprouter
    ├── cloud-foundry.ts             # checkCfLogin, downloadDefaultEnv, bindServiceToCds
    ├── binding-orchestration.ts     # isAlreadyBound, bindServices, downloadCredentials
    ├── file-operations.ts           # readTextFile, readJsonFile, writeJsonFile
    ├── configuration.ts             # addPoolConfiguration
    ├── shutdown.ts                  # createShutdownHandler
    ├── logging.ts                   # createLogger, logMessage
    └── help.ts                      # showHelp, showTroubleshootingHints

tests/
└── bootstrap.test.ts                # 60 Unit-Tests

Dependency Graph

graph TD
    A[index.ts] --> B[binding-orchestration.ts]
    A --> C[service-operations.ts]
    A --> D[shutdown.ts]
    A --> E[help.ts]
    A --> PC[process-cleanup.ts]

    B --> F[cloud-foundry.ts]
    B --> G[configuration.ts]
    B --> H[file-operations.ts]

    C --> I[process-operations.ts]
    C --> J[logging.ts]
    C --> CALC[calculation.ts]

    F --> I
    F --> J

    G --> H

    I --> K[validation.ts]
    I --> L[transformation.ts]
    J --> L

    D --> PC

    K --> M[result-helpers.ts]
    L --> M

Troubleshooting

Ports belegt

# Liste laufende cds-watch-Prozesse
pgrep -f "@sap/cds-dk/lib/watch/watched" -a

# Graceful
pgrep -f "@sap/cds-dk/lib/watch/watched" | xargs kill

# Force
pgrep -f "@sap/cds-dk/lib/watch/watched" | xargs kill -9

Parallel-Mode & File-Watcher-Limits (Linux)

echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches