# Build, Tooling & CI/CD

# Build, Tooling & CI/CD

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [.github/workflows/ci.yml](.github/workflows/ci.yml)
- [package.json](package.json)
- [tsconfig.json](tsconfig.json)

</details>



This page provides a high-level overview of the `@primebrick/sdk` build pipeline, the tooling ecosystem, and the automated release workflow. The SDK is built using TypeScript with a focus on modern ECMAScript standards and secure, automated publishing via GitHub Actions.

## Build Pipeline Overview

The SDK utilizes `pnpm` as its package manager and the TypeScript compiler (`tsc`) for its build process [package.json:24-25, 46](). The pipeline transforms source files from `src/` into a distributable `dist/` directory containing JavaScript modules, type definitions, and source maps [tsconfig.json:7-8, 14-16]().

### Source to Distribution Mapping

The following diagram illustrates the relationship between the source code entities and the generated build artifacts.

**Build Artifact Mapping**
```mermaid
graph TD
    subgraph "Source Space (src/)"
        A["index.ts"]
        B["Module Logic (e.g., config/, nats/)"]
        C["Tests (*.test.ts)"]
    end

    subgraph "Tooling"
        TSC["tsc (TypeScript Compiler)"]
        PNPM["pnpm build"]
    end

    subgraph "Distribution Space (dist/)"
        D["index.js (ESM)"]
        E["index.d.ts (Types)"]
        F["index.d.ts.map (Declaration Maps)"]
    end

    A --> TSC
    B --> TSC
    PNPM --> TSC
    TSC --> D
    TSC --> E
    TSC --> F
    C -. "Excluded via tsconfig" .-> TSC
```
**Sources:** [package.json:17-24](), [tsconfig.json:7-8, 14-16, 19]()

For detailed information on compiler flags, target environments, and why certain strict checks are modified for Dependency Injection patterns, see **[TypeScript Build Configuration](#4.1)**.

## Tooling & Dependency Management

The project is configured as a modern Node.js ESM (ECMAScript Module) package [package.json:5](). It leverages `pnpm` for efficient, deterministic dependency resolution via `pnpm-lock.yaml`.

### Key Tooling Components
*   **Runtime Target:** ES2022 with `NodeNext` module resolution [tsconfig.json:3-5]().
*   **Package Manager:** `pnpm` (v9.15.9) [package.json:46]().
*   **Testing:** `vitest` for unit and integration testing [package.json:26-27, 44]().
*   **Peer Dependencies:** `nats` is treated as an optional peer dependency, allowing consumers to use the SDK without forcing a NATS installation if messaging is not required [package.json:34-39]().

**Sources:** [package.json:5, 34-46](), [tsconfig.json:3-5]()

## CI/CD & Automated Release

The SDK employs a fully automated release workflow triggered by version tags. This process ensures that every published version has passed type-checking and build gates.

### Release Workflow Logic
The release process is governed by GitHub Actions and utilizes **OIDC (OpenID Connect) Trusted Publishing**. This eliminates the need for long-lived `NPM_TOKEN` secrets by allowing GitHub to authenticate directly with npmjs.com [ci.yml:9-14]().

**CI/CD Pipeline Flow**
```mermaid
graph LR
    subgraph "GitHub Repository"
        TAG["git tag v*.*.*"]
        WORKFLOW[".github/workflows/ci.yml"]
    end

    subgraph "Release Job"
        INSTALL["pnpm install --frozen-lockfile"]
        BUILD["pnpm run build"]
        CHECK["npx tsc --noEmit"]
        PUBLISH["npm publish --provenance"]
    end

    subgraph "External Registries"
        NPM["npmjs.com"]
    end

    TAG --> WORKFLOW
    WORKFLOW --> INSTALL
    INSTALL --> BUILD
    BUILD --> CHECK
    CHECK --> PUBLISH
    PUBLISH --> NPM
```
**Sources:** [.github/workflows/ci.yml:1-47]()

### Security & Provenance
The workflow uses `npm publish --provenance` to provide supply-chain attestation, linking the published package directly to the source code and the specific GitHub Action run that generated it [ci.yml:47]().

For a deep dive into the OIDC configuration, the least-privilege permissions model, and the specific steps in the release job, see **[CI/CD & NPM Publishing](#4.2)**.

---