|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This is the LaunchDarkly Integration Framework — a collection of 130+ third-party integration definitions. Integrations are declarative (JSON manifests + Handlebars templates), not imperative code. The framework validates manifests against a JSON Schema and renders templates with sample contexts in tests. |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +- **Run all tests:** `npm test` |
| 12 | +- **Run a single test file:** `npx jest __tests__/validateIntegrationManifests.js` |
| 13 | +- **Run tests matching a pattern:** `npx jest -t "Validate datadog/manifest.json"` |
| 14 | +- **Build schema bundle:** `npm run build` (bundles `schemas/base.json` + `schemas/definitions.json` + `schemas/capabilities/*.json` into `manifest.schema.json`, then generates TypeScript types) |
| 15 | +- **Format code:** `npm run prettier:write` |
| 16 | +- **Check formatting:** `npm run prettier:check` |
| 17 | +- **Preview template rendering:** `npm run preview` (renders templates with sample context data) |
| 18 | +- **Scaffold new integration:** `npx plop` (interactive generator using `plopfile.js`) |
| 19 | +- **Validation server:** `npm run start:server` (Express server on port 3000 for testing integrations) |
| 20 | + |
| 21 | +## Architecture |
| 22 | + |
| 23 | +### Integration structure |
| 24 | + |
| 25 | +Each integration lives in `integrations/<name>/` with: |
| 26 | +- `manifest.json` — declares metadata, form variables, capabilities, and endpoint configuration |
| 27 | +- `assets/square.svg` and `assets/horizontal.svg` — logo files (required) |
| 28 | +- `templates/*.json.hbs` — Handlebars templates for different event types (flag, project, environment, member) |
| 29 | +- `README.md` — optional documentation |
| 30 | + |
| 31 | +### Manifest schema |
| 32 | + |
| 33 | +The manifest schema is composed from multiple files: |
| 34 | +- `schemas/base.json` — top-level manifest properties (name, version, overview, formVariables, capabilities, etc.) |
| 35 | +- `schemas/definitions.json` — shared type definitions |
| 36 | +- `schemas/capabilities/*.json` — per-capability schemas (auditLogEventsHook, trigger, flagLink, syncedSegment, approval, etc.) |
| 37 | +- `manifest.schema.json` — auto-generated bundled/dereferenced schema (do not edit directly) |
| 38 | +- `manifest.schema.d.ts` — auto-generated TypeScript types from the schema |
| 39 | + |
| 40 | +### Capabilities |
| 41 | + |
| 42 | +Integrations declare capabilities in their manifest. Key capability types: |
| 43 | +- `auditLogEventsHook` / `eventsHook` — webhook-style event delivery with templated request bodies |
| 44 | +- `trigger` — LaunchDarkly triggers |
| 45 | +- `flagLink` — deep links to external resources from flags |
| 46 | +- `syncedSegment` — import audience segments from external tools |
| 47 | +- `approval` — external approval workflows |
| 48 | +- `flagCleanup` / `flagImport` — flag lifecycle management |
| 49 | +- `reservedCustomProperties` — custom flag properties for the integration |
| 50 | + |
| 51 | +### Handlebars templates |
| 52 | + |
| 53 | +Templates use Handlebars with custom helpers registered in `helpers/index.js`: |
| 54 | +- `equal` / `equalWithElse` — conditional equality |
| 55 | +- `pathEncode` / `queryEncode` — URL encoding |
| 56 | +- `basicAuthHeaderValue` — Base64 auth header |
| 57 | +- `formatWithOffset` — timestamp formatting (milliseconds, seconds, rfc3339, simple) |
| 58 | + |
| 59 | +Templates rendering is tested with sample contexts from `sample-context/` (flag, project, environment, member events). JSON templates are automatically escaped via `utils/json-escape.js`. |
| 60 | + |
| 61 | +### Test structure |
| 62 | + |
| 63 | +Tests in `__tests__/` validate all integrations automatically: |
| 64 | +- Schema validation of every manifest against `manifest.schema.json` |
| 65 | +- Icon file existence checks |
| 66 | +- Overview must end with a period |
| 67 | +- Template rendering with sample contexts must not throw |
| 68 | +- Form variable references in endpoints/templates must resolve |
| 69 | +- Capability-specific validations (flag links, synced segments, etc.) |
| 70 | + |
| 71 | +Tests iterate over all integration directories using `__tests__/__utils__/index.js` which reads every `integrations/*/manifest.json`. |
| 72 | + |
| 73 | +## Key conventions |
| 74 | + |
| 75 | +- Manifests are validated with AJV against the bundled JSON Schema |
| 76 | +- Template variables come from `formVariables` defined in the manifest |
| 77 | +- The `overview` field must end with a period (enforced by tests) |
| 78 | +- OAuth integrations must be explicitly listed in `OAUTH_INTEGRATIONS` array in `__tests__/validateIntegrationManifests.js` |
| 79 | +- After modifying schemas, run `npm run build` to regenerate `manifest.schema.json` |
0 commit comments