phantomknight287/saturn

public

The operating system for your freelance business.

feat: here comes the money442302e7 months ago147 lines · 4.8 KB

1	---
2	name: create-evlog-enricher
3	description: Create a new built-in evlog enricher to add derived context to wide events. Use when adding a new enricher (e.g., for deployment metadata, tenant context, feature flags, etc.) to the evlog package. Covers source code, tests, and all documentation.
4	---
5
6	# Create evlog Enricher
7
8	Add a new built-in enricher to evlog. Every enricher follows the same architecture. This skill walks through all 6 touchpoints. Every single touchpoint is mandatory -- do not skip any.
9
10	## PR Title
11
12	Recommended format for the pull request title:
13
14	```
15	feat: add {name} enricher
16	```
17
18	The exact wording may vary depending on the enricher (e.g., `feat: add user agent enricher`, `feat: add geo enricher`), but it should always follow the
19
20	## Touchpoints Checklist
21
22	\| # \| File \| Action \|
23	\|---\|------\|--------\|
24	\| 1 \| `packages/evlog/src/enrichers/index.ts` \| Add enricher source
25	\| 2 \| `packages/evlog/test/enrichers.test.ts` \| Add tests
26	\| 3 \| `apps/docs/content/4.enrichers/2.built-in.md` \| Add enricher to built-in docs
27	\| 4 \| `apps/docs/content/4.enrichers/1.overview.md` \| Add enricher to overview cards
28	\| 5 \| `AGENTS.md` \| Add enricher to the "Built-in Enrichers" table
29	\| 6 \| `README.md` + `packages/evlog/README.md
30
31	Important: Do NOT consider the task complete until all 6 touchpoints have been addressed.
32
33	## Naming Conventions
34
35	Use these placeholders consistently:
36
37	\| Placeholder \| Example (UserAgent) \| Usage \|
38	\|-------------\|---------------------\|-------\|
39	\| `{name}` \| `userAgent
40	\| `{Name}` \| `UserAgent
41	\| `{DISPLAY}` \| `User Agent
42
43	## Step 1: Enricher Source
44
45	Add the enricher to `packages/evlog/src/enrichers/index.ts`.
46
47	Read [references/enricher-template.md](references/enricher-template.md
48
49	Key architecture rules:
50
51	1. Info interface -- define the shape of the enricher output (e.g.,
52	2. Factory function --
53	3. **Uses `EnricherOptions
54	4. **Uses `mergeEventField()
55	5. **Uses `getHeader()
56	6. Sets a single event field --
57	7. Early return -- skip enrichment if required headers are missing
58	8. No side effects -- enrichers only mutate
59
60	## Step 2: Tests
61
62	Add tests to `packages/evlog/test/enrichers.test.ts`.
63
64	Required test categories:
65
66	1. Sets field from headers -- verify the enricher populates the event field correctly
67	2. Skips when header missing -- verify no field is set when the required header is absent
68	3. Preserves existing data -- verify
69	4. Overwrites when requested -- verify
70	5. Handles edge cases -- empty strings, malformed values, case-insensitive header names
71
72	Follow the existing test structure in `enrichers.test.ts` -- each enricher has its own `describe` block.
73
74	## Step 3: Update Built-in Docs
75
76	Edit `apps/docs/content/4.enrichers/2.built-in.md` to add a new section for the enricher.
77
78	Each enricher section follows this structure:
79
80	```markdown
81	## {DISPLAY}
82
83	[One-sentence description of what the enricher does.]
84
85	Sets: `event.{name}
86
87	\`\`\`typescript
88	const enrich = create{Name}Enricher()
89	\`\`\`
90
91	Output shape:
92
93	\`\`\`typescript
94	interface {Name}Info {
95	// fields
96	}
97	\`\`\`
98
99	Example output:
100
101	\`\`\`json
102	{
103	"{name}": {
104	// example values
105	}
106	}
107	\`\`\`
108	```
109
110	Add any relevant callouts for platform-specific notes or limitations.
111
112	## Step 4: Update Overview Page
113
114	Edit `apps/docs/content/4.enrichers/1.overview.md` to add a card for the new enricher in the `::card-group` section (before the Custom card):
115
116	```markdown
117	:::card
118	---
119	icon: i-lucide-{icon}
120	title: {DISPLAY}
121	to: /enrichers/built-in#{anchor}
122	---
123	[Short description.]
124	:::
125	```
126
127	## Step 5: Update AGENTS.md
128
129	Add the new enricher to the "Built-in Enrichers" table in the root `
130
131	```markdown
132	\| {DISPLAY} \| `evlog/enrichers` \|
133	```
134
135	## Step 6: Update README
136
137	Add the enricher to the enrichers section in `packages/evlog/README.md` (the root `README.md` is a symlink to it). Add the enricher to the enrichers table with its event field and output shape.
138
139	## Verification
140
141	After completing all steps, run:
142
143	```bash
144	cd packages/evlog
145	bun run build #
146	bun run test #
147	```