Merge pull request #571 from elbwalker/565-ai-readiness

alexanderkirtzel · web-flow · commit b6f4572c3db3 · 2025-12-13T02:04:18.000+01:00
565 ai readiness
diff --git a/packages/collector/src/__tests__/destination-code.test.ts b/packages/collector/src/__tests__/destination-code.test.ts
@@ -44,6 +44,72 @@ describe('destinationCode', () => {
   });
 
   describe('init', () => {
+    it('accepts scripts array in settings', () => {
+      const settings: Settings = {
+        scripts: [
+          'https://example.com/analytics.js',
+          'https://example.com/pixel.js',
+        ],
+        init: "console.log('ready')",
+      };
+      expect(settings.scripts).toHaveLength(2);
+    });
+
+    it('injects script tags for each URL in scripts array', () => {
+      const initialScriptCount =
+        document.head.querySelectorAll('script').length;
+
+      const context: InitContext = {
+        collector: createMockCollector(),
+        config: {
+          settings: {
+            scripts: ['https://example.com/a.js', 'https://example.com/b.js'],
+          },
+        },
+        env: {},
+        logger: createMockLogger(),
+      };
+
+      destinationCode.init!(context);
+
+      const scripts = document.head.querySelectorAll('script');
+      expect(scripts.length).toBe(initialScriptCount + 2);
+
+      const addedScripts = Array.from(scripts).slice(-2);
+      expect(addedScripts[0].src).toBe('https://example.com/a.js');
+      expect(addedScripts[0].async).toBe(true);
+      expect(addedScripts[1].src).toBe('https://example.com/b.js');
+      expect(addedScripts[1].async).toBe(true);
+    });
+
+    it('injects scripts before running init code', () => {
+      const initialScriptCount =
+        document.head.querySelectorAll('script').length;
+      const mockLogger = createMockLogger();
+
+      const context: InitContext = {
+        collector: createMockCollector(),
+        config: {
+          settings: {
+            scripts: ['https://example.com/lib.js'],
+            init: "context.logger.info('init ran')",
+          },
+        },
+        env: {},
+        logger: mockLogger,
+      };
+
+      destinationCode.init!(context);
+
+      // Scripts should be injected
+      const scripts = document.head.querySelectorAll('script');
+      expect(scripts.length).toBe(initialScriptCount + 1);
+      expect(Array.from(scripts).pop()?.src).toBe('https://example.com/lib.js');
+
+      // Init code should also run
+      expect(mockLogger.info).toHaveBeenCalledWith('init ran');
+    });
+
     it('executes init code string', () => {
       const mockLogger = createMockLogger();
       const context: InitContext = {
@@ -62,6 +128,33 @@ describe('destinationCode', () => {
       expect(mockLogger.info).toHaveBeenCalledWith('initialized');
     });
 
+    it('handles empty scripts array gracefully', () => {
+      const initialScriptCount =
+        document.head.querySelectorAll('script').length;
+      const mockLogger = createMockLogger();
+      const context: InitContext = {
+        collector: createMockCollector(),
+        config: {
+          settings: {
+            scripts: [],
+            init: "context.logger.info('init ran')",
+          },
+        },
+        env: {},
+        logger: mockLogger,
+      };
+
+      expect(() => destinationCode.init!(context)).not.toThrow();
+
+      // No scripts should be added
+      expect(document.head.querySelectorAll('script').length).toBe(
+        initialScriptCount,
+      );
+
+      // Init code should still run
+      expect(mockLogger.info).toHaveBeenCalledWith('init ran');
+    });
+
     it('handles missing init code gracefully', () => {
       const context: InitContext = {
         collector: createMockCollector(),
diff --git a/packages/collector/src/destination-code.ts b/packages/collector/src/destination-code.ts
@@ -7,7 +7,21 @@ export const destinationCode: Destination.Instance = {
 
   init(context) {
     const { config, logger } = context;
-    const initCode = (config.settings as Settings | undefined)?.init;
+    const settings = config.settings as Settings | undefined;
+
+    // Inject scripts (fire and forget)
+    const scripts = settings?.scripts;
+    if (scripts && typeof document !== 'undefined') {
+      for (const src of scripts) {
+        const script = document.createElement('script');
+        script.src = src;
+        script.async = true;
+        document.head.appendChild(script);
+      }
+    }
+
+    // Execute init code
+    const initCode = settings?.init;
     if (!initCode) return;
     try {
       const fn = new Function('context', initCode);
diff --git a/packages/collector/src/types/code.ts b/packages/collector/src/types/code.ts
@@ -1,6 +1,7 @@
 import type { Destination, Mapping, On, WalkerOS } from '@walkeros/core';
 
 export interface Settings {
+  scripts?: string[];
   init?: string;
   on?: string;
   push?: string;
diff --git a/skills/create-destination/SKILL.md b/skills/create-destination/SKILL.md
@@ -22,6 +22,14 @@ Before starting, read these skills:
 - [writing-documentation](../writing-documentation/SKILL.md) - Documentation
   standards (for Phase 7)
 
+## Choose Your Template
+
+| Complexity | Template     | When to Use                         |
+| ---------- | ------------ | ----------------------------------- |
+| Simple     | `plausible/` | Single SDK call, minimal config     |
+| Complex    | `gtag/`      | Multiple services, sub-destinations |
+| Server     | `gcp/`       | Server-side, batching, SDK init     |
+
 ## Process Overview
 
 ```
@@ -80,6 +88,24 @@ ls packages/web/destinations/
 # - meta: Pixel with custom events
 ```
 
+### Gate: Research Complete
+
+Before proceeding, confirm:
+
+- [ ] API pattern identified (SDK function / HTTP / pixel)
+- [ ] Auth method documented (API key, token, none)
+- [ ] Event types mapped to walkerOS equivalents
+
+### Checkpoint: Research Review (Optional)
+
+If working with human oversight, pause here to confirm:
+
+- API pattern and auth method correct?
+- Event mapping makes sense for the use case?
+- Any vendor quirks or rate limits to handle?
+
+Continue only after approval.
+
 ---
 
 ## Phase 2: Create Examples (BEFORE Implementation)
@@ -211,6 +237,11 @@ export * as schemas from './schemas';
 export * as examples from './examples';
 ```
 
+### Gate: Examples Valid
+
+- [ ] All example files compile (`npm run build`)
+- [ ] Can trace: input event → expected output for each example
+
 ---
 
 ## Phase 3: Define Mapping
@@ -278,6 +309,11 @@ Input: events.pageView
 Output: Should match outputs.pageViewCall
 ```
 
+### Gate: Mapping Verified
+
+- [ ] Mapping covers: page view + at least one conversion event
+- [ ] Each mapping rule traces correctly to expected output
+
 ---
 
 ## Phase 4: Scaffold
@@ -390,6 +426,11 @@ function addScript(settings: Settings, env?: DestinationWeb.Env) {
 export default destinationVendor;
 ```
 
+### Gate: Implementation Compiles
+
+- [ ] `npm run build` passes
+- [ ] `npm run lint` passes
+
 ---
 
 ## Phase 6: Test Against Examples
@@ -437,6 +478,11 @@ describe('destinationVendor', () => {
 });
 ```
 
+### Gate: Tests Pass
+
+- [ ] `npm run test` passes
+- [ ] Tests verify against example outputs (not hardcoded values)
+
 ---
 
 ## Phase 7: Document
@@ -456,14 +502,15 @@ Key requirements for destination documentation:
 
 ---
 
-## Validation Checklist
+## Destination-Specific Validation
 
-- [ ] `npm run build` passes
-- [ ] `npm run test` passes
-- [ ] `npm run lint` passes
-- [ ] Examples cover main use cases
-- [ ] Tests verify against example outputs
-- [ ] README documents configuration
+Beyond [understanding-development](../understanding-development/SKILL.md)
+requirements (build, test, lint, no `any`):
+
+- [ ] Uses `getEnv(env)` pattern (never direct `window`/`document` access)
+- [ ] `dev.ts` exports `schemas` and `examples`
+- [ ] Examples match type signatures
+- [ ] Tests use examples for assertions (not hardcoded values)
 
 ---
 
diff --git a/skills/create-source/SKILL.md b/skills/create-source/SKILL.md
@@ -48,6 +48,14 @@ for their respective cloud platforms.
 
 Many sources are both - they handle platform transport AND transform data.
 
+## Choose Your Template
+
+| Complexity            | Template       | When to Use                           |
+| --------------------- | -------------- | ------------------------------------- |
+| Simple transformation | `fetch/`       | Generic HTTP handler, data conversion |
+| Platform transport    | `gcp/`, `aws/` | Cloud platform integration            |
+| Browser interception  | `dataLayer/`   | DOM events, array interception        |
+
 ## Process Overview
 
 ```
@@ -119,6 +127,24 @@ ls packages/server/sources/
 # - gcp: Cloud Functions specific
 ```
 
+### Gate: Research Complete
+
+Before proceeding, confirm:
+
+- [ ] Input trigger identified (HTTP, webhook, DOM, dataLayer)
+- [ ] Input schema documented (required/optional fields)
+- [ ] Fields mapped to walkerOS event structure
+
+### Checkpoint: Research Review (Optional)
+
+If working with human oversight, pause here to confirm:
+
+- Input format and trigger mechanism correct?
+- Event name mapping makes sense?
+- Any platform quirks or auth requirements?
+
+Continue only after approval.
+
 ---
 
 ## Phase 2: Create Input Examples (BEFORE Implementation)
@@ -276,6 +302,12 @@ export * as schemas from './schemas';
 export * as examples from './examples';
 ```
 
+### Gate: Examples Valid
+
+- [ ] All example files compile (`npm run build`)
+- [ ] Can trace: input → expected output for each example
+- [ ] Edge cases included (minimal input, invalid input)
+
 ---
 
 ## Phase 3: Define Mapping
@@ -342,6 +374,11 @@ Input: inputs.pageViewInput
 Output: Should match outputs.pageViewEvent
 ```
 
+### Gate: Mapping Verified
+
+- [ ] Event name map covers main input types
+- [ ] Each mapping rule traces correctly to expected output
+
 ---
 
 ## Phase 4: Scaffold
@@ -485,6 +522,11 @@ export async function push(
 export default { transformInput, transformBatch, push };
 ```
 
+### Gate: Implementation Compiles
+
+- [ ] `npm run build` passes
+- [ ] `npm run lint` passes
+
 ---
 
 ## Phase 6: Test Against Examples
@@ -575,6 +617,12 @@ describe('HTTP handler', () => {
 });
 ```
 
+### Gate: Tests Pass
+
+- [ ] `npm run test` passes
+- [ ] Tests verify against example outputs (not hardcoded values)
+- [ ] Invalid input handled gracefully (no crashes)
+
 ---
 
 ## Phase 7: Document
@@ -595,15 +643,15 @@ Key requirements for source documentation:
 
 ---
 
-## Validation Checklist
+## Source-Specific Validation
 
-- [ ] `npm run build` passes
-- [ ] `npm run test` passes
-- [ ] `npm run lint` passes
-- [ ] Examples cover main input patterns
-- [ ] Tests verify against example outputs
-- [ ] Invalid input handled gracefully
-- [ ] README documents input format
+Beyond [understanding-development](../understanding-development/SKILL.md)
+requirements (build, test, lint, no `any`):
+
+- [ ] `dev.ts` exports `schemas` and `examples`
+- [ ] Examples include edge cases (minimal, invalid input)
+- [ ] Invalid input returns gracefully (no crashes, clear error)
+- [ ] Tests use examples for assertions (not hardcoded values)
 
 ---
 
diff --git a/website/docs/contributing.mdx b/website/docs/contributing.mdx
diff --git a/website/docs/destinations/code.mdx b/website/docs/destinations/code.mdx
