core-utils

Clipboard's core libraries and utilities. See individual package `README`s for specific library details.

Table of contents

• Libraries
• Moved libraries
• Local development commands
• Shared Renovate presets
• Adding or porting libraries
• Contributing

Libraries

• ai-rules: Pre-built AI agent rules for consistent coding standards.
• analytics: Type-safe analytics wrapper around our third-party analytics provider for user identification and event tracking.
• background-jobs-adapter: Minimal adapter interface for background jobs operations supporting Mongo and Postgres implementations.
• clearance: Localhost HTTP/HTTPS egress proxy with hostname allow-listing, plus a macOS Safehouse integration for sandboxed agent processes.
• config: Type-safe static configuration management: a pure function to resolve, validate against a Zod schema, and freeze configuration values.
• contract-core: Shared Zod schemas for Clipboard's contracts.
• embedex: Embed shared text and code snippets from source files into destination files.
• eslint-config: Our ESLint configuration.
• eslint-plugin: Clipboard's ESLint Plugin
• example-nestjs: A NestJS application using our libraries, primarily for end-to-end testing.
• execution-context: A lightweight Node.js utility for managing execution contexts and metadata aggregation using AsyncLocalStorage.
• json-api: TypeScript-friendly utilities for adhering to the JSON:API specification.
• json-api-nestjs: TypeScript-friendly utilities for adhering to the JSON:API specification with NestJS.
• notifications: Send notifications through third-party providers.
• nx-plugin: An Nx plugin with generators to manage libraries and applications.
• oxlint-config: Shared Oxlint configuration for Clipboard Health repositories.
• oxlint-plugin: Clipboard's Oxlint plugin.
• phone-number: Phone number utility functions.
• playwright-flake-linter: Shared configurable checks for Playwright flake anti-patterns.
• playwright-reporter-llm: Playwright reporter that outputs structured JSON for LLM agents. Minimal console output, flat schema, easy to filter to failures.
• playwright-toolkit: Shared anti-flake primitives for Clipboard Health Playwright suites.
• rules-engine: A pure functional rules engine to keep logic-dense code simple, reliable, understandable, and explainable.
• testing-core: TypeScript-friendly testing utilities.
• usa-states: Canonical US state and territory list, StateCode and StateName types, and name/code normalizers.
• util-ts: TypeScript utilities.

Moved libraries

• groundcrew: now lives in its own repository.

Local development commands

See package.json scripts for a complete list of commands.

See Nx CLI Commands for options or npx nx --help.

# Install dependencies
npm clean-install

# Build, lint, and test only changed files from `main`, helpful prior to opening PRs
node --run affected

# For the paranoid: build, lint, and test everything
node --run verify

# Install a dependency in a specific package
npm install --workspace packages/[PROJECT_NAME] [DEPENDENCY]

# Run specific commands against a specific packages
npx nx run [PROJECT_NAME]:[COMMAND]

# Upgrade Nx
npx nx migrate latest && \
  npx syncpack fix && \
  npm install && \
  npx nx migrate --runMigrations --ifExists

Shared Renovate presets

Clipboard repositories can extend the default shared configuration with github>ClipboardHealth/core-utils.

Repositories that should use Renovate only for published schema packages can instead extend the opt-in schema-packages preset:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["github>ClipboardHealth/core-utils:schema-packages"]
}

The preset manages @clipboard-health/contract-*, @clipboard-health/flag-*, and @clipboard-health/message-*. It opens pull requests for new releases, automerges minor and patch updates after checks pass, and leaves major updates for human review.

Adding or porting libraries

See our Nx generator plugin.

Contributing

See CONTRIBUTING.md.