convention

Author: alexanderkirtzel

packages/cli/src/__tests__/core/auth.test.ts

@@ -4,6 +4,17 @@ import {
   authenticatedFetch,
 } from '../../core/auth.js';
 
+// Isolate from real ~/.config/walkeros/config.json
+jest.mock('../../lib/config-file.js', () => ({
+  resolveToken: () => {
+    const token = process.env.WALKEROS_TOKEN;
+    if (!token) return null;
+    return { token, source: 'env' as const };
+  },
+  resolveAppUrl: () =>
+    process.env.WALKEROS_APP_URL || 'https://app.walkeros.io',
+}));
+
 describe('auth', () => {
   const originalEnv = process.env;
 

packages/mcp/src/__tests__/tools/get-package-schema.test.ts

@@ -1,8 +1,13 @@
 import { registerGetPackageSchemaTool } from '../../tools/get-package-schema.js';
+import { fetchPackageSchema } from '@walkeros/core';
 
-// Mock fetch globally
-const mockFetch = jest.fn();
-global.fetch = mockFetch;
+jest.mock('@walkeros/core', () => ({
+  fetchPackageSchema: jest.fn(),
+}));
+
+const mockFetchPackageSchema = fetchPackageSchema as jest.MockedFunction<
+  typeof fetchPackageSchema
+>;
 
 function createMockServer() {
   const tools: Record<string, { config: unknown; handler: Function }> = {};
@@ -30,41 +35,23 @@ describe('get-package-schema tool', () => {
   });
 
   it('should fetch package.json then walkerOS.json from jsdelivr', async () => {
-    const mockPkgJson = {
-      name: '@walkeros/web-destination-snowplow',
+    mockFetchPackageSchema.mockResolvedValue({
+      packageName: '@walkeros/web-destination-snowplow',
       version: '0.0.12',
-      walkerOS: {
-        type: 'destination',
-        platform: 'web',
-        schema: './dist/dev/walkerOS.json',
-      },
-    };
-    const mockWalkerOSJson = {
+      type: 'destination',
+      platform: 'web',
       schemas: { settings: { type: 'object', properties: {} } },
       examples: { mapping: {} },
-    };
-
-    mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve(mockPkgJson),
-      })
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve(mockWalkerOSJson),
-      });
+    });
 
     const tool = mockServer.getTool('get-package-schema');
     const result = await tool.handler({
       package: '@walkeros/web-destination-snowplow',
     });
 
-    expect(mockFetch).toHaveBeenCalledTimes(2);
-    expect(mockFetch).toHaveBeenCalledWith(
-      expect.stringContaining(
-        'cdn.jsdelivr.net/npm/@walkeros/web-destination-snowplow',
-      ),
-      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    expect(mockFetchPackageSchema).toHaveBeenCalledWith(
+      '@walkeros/web-destination-snowplow',
+      { version: undefined },
     );
 
     const content = JSON.parse(result.content[0].text);
@@ -74,64 +61,60 @@ describe('get-package-schema tool', () => {
   });
 
   it('should use default schema path when walkerOS field is missing', async () => {
-    mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve({ name: 'some-pkg', version: '1.0.0' }),
-      })
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve({ schemas: { settings: {} } }),
-      });
+    mockFetchPackageSchema.mockResolvedValue({
+      packageName: 'some-pkg',
+      version: '1.0.0',
+      type: undefined,
+      platform: undefined,
+      schemas: { settings: {} },
+      examples: {},
+    });
 
     const tool = mockServer.getTool('get-package-schema');
-    await tool.handler({ package: 'some-pkg' });
+    const result = await tool.handler({ package: 'some-pkg' });
 
-    expect(mockFetch).toHaveBeenNthCalledWith(
-      2,
-      expect.stringContaining('dist/dev/walkerOS.json'),
-      expect.objectContaining({ signal: expect.any(AbortSignal) }),
-    );
+    expect(mockFetchPackageSchema).toHaveBeenCalledWith('some-pkg', {
+      version: undefined,
+    });
+    const content = JSON.parse(result.content[0].text);
+    expect(content.package).toBe('some-pkg');
   });
 
   it('should return error when package not found', async () => {
-    mockFetch.mockResolvedValueOnce({ ok: false, status: 404 });
+    mockFetchPackageSchema.mockRejectedValue(
+      new Error('Package "nonexistent" not found on npm (HTTP 404)'),
+    );
 
     const tool = mockServer.getTool('get-package-schema');
     const result = await tool.handler({ package: 'nonexistent' });
     expect(result.isError).toBe(true);
   });
 
   it('should return error when walkerOS.json not found', async () => {
-    mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve({ name: 'pkg', version: '1.0.0' }),
-      })
-      .mockResolvedValueOnce({ ok: false, status: 404 });
+    mockFetchPackageSchema.mockRejectedValue(
+      new Error('walkerOS.json not found at dist/dev/walkerOS.json (HTTP 404)'),
+    );
 
     const tool = mockServer.getTool('get-package-schema');
     const result = await tool.handler({ package: 'pkg' });
     expect(result.isError).toBe(true);
   });
 
   it('should support version parameter', async () => {
-    mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve({ name: 'pkg', version: '2.0.0' }),
-      })
-      .mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve({ schemas: {} }),
-      });
+    mockFetchPackageSchema.mockResolvedValue({
+      packageName: 'pkg',
+      version: '2.0.0',
+      type: undefined,
+      platform: undefined,
+      schemas: {},
+      examples: {},
+    });
 
     const tool = mockServer.getTool('get-package-schema');
     await tool.handler({ package: 'pkg', version: '2.0.0' });
 
-    expect(mockFetch).toHaveBeenCalledWith(
-      expect.stringContaining('pkg@2.0.0'),
-      expect.objectContaining({ signal: expect.any(AbortSignal) }),
-    );
+    expect(mockFetchPackageSchema).toHaveBeenCalledWith('pkg', {
+      version: '2.0.0',
+    });
   });
 });

skills/walkeros-create-destination/SKILL.md

@@ -227,7 +227,7 @@ discovery.
     "platform": "web",
     "schema": "./dist/dev/walkerOS.json"
   },
-  "keywords": ["walkeros", "walkeros-destination", ...]
+  "keywords": ["walkerOS", "walkerOS-destination", ...]
 }
 ```
 
@@ -249,7 +249,7 @@ time.
 - [ ] `walkerOS` field in package.json with `type: "destination"` and `platform`
 - [ ] `buildDev()` in tsup.config.ts
 - [ ] Build generates `dist/dev/walkerOS.json`
-- [ ] Keywords include `walkeros` and `walkeros-destination`
+- [ ] Keywords include `walkerOS` and `walkerOS-destination`
 
 ---
 

skills/walkeros-create-source/SKILL.md

@@ -237,7 +237,7 @@ discovery.
     "platform": "web",
     "schema": "./dist/dev/walkerOS.json"
   },
-  "keywords": ["walkeros", "walkeros-source", ...]
+  "keywords": ["walkerOS", "walkerOS-source", ...]
 }
 ```
 
@@ -261,7 +261,7 @@ time.
 - [ ] `walkerOS` field in package.json with `type: "source"` and `platform`
 - [ ] `buildDev()` in tsup.config.ts
 - [ ] Build generates `dist/dev/walkerOS.json`
-- [ ] Keywords include `walkeros` and `walkeros-source`
+- [ ] Keywords include `walkerOS` and `walkerOS-source`
 
 ---
 

skills/walkeros-create-transformer/SKILL.md

@@ -19,7 +19,7 @@ Before starting, read these skills:
   structure
 - [testing-strategy](../walkeros-testing-strategy/SKILL.md) - How to test
 - [writing-documentation](../walkeros-writing-documentation/SKILL.md) -
-  Documentation standards (for Phase 6)
+  Documentation standards (for Phase 7)
 
 ## Transformer Categories
 
@@ -35,9 +35,10 @@ Before starting, read these skills:
 1. Research     → Understand use case (validate/enrich/redact)
 2. Examples     → Create event before/after examples FIRST
 3. Scaffold     → Copy template, configure package.json
-4. Implement    → Build transformer with TDD
-5. Test         → Verify against example transformations
-6. Document     → Write README
+4. Convention   → Add walkerOS.json metadata and buildDev
+5. Implement    → Build transformer with TDD
+6. Test         → Verify against example transformations
+7. Document     → Write README
 ```
 
 ## Supporting Files
@@ -162,16 +163,54 @@ packages/transformers/[name]/
 
 ---
 
-## Phase 4: Implement
+## Phase 4: walkerOS.json Convention
+
+Every walkerOS package ships a `walkerOS.json` file for CDN-based schema
+discovery.
+
+### Add `walkerOS` field to package.json
+
+```json
+{
+  "walkerOS": {
+    "type": "transformer"
+  },
+  "keywords": ["walkerOS", "walkerOS-transformer", ...]
+}
+```
+
+### Use `buildDev()` in tsup.config.ts
+
+Replace `buildModules({ entry: ['src/dev.ts'] })` with `buildDev()`:
+
+```typescript
+import { buildDev } from '@walkeros/config/tsup';
+// In defineConfig array:
+buildDev(),
+```
+
+This auto-generates `dist/dev/walkerOS.json` from your Zod schemas at build
+time.
+
+### Gate: Convention Met
+
+- [ ] `walkerOS` field in package.json with `type: "transformer"`
+- [ ] `buildDev()` in tsup.config.ts
+- [ ] Build generates `dist/dev/walkerOS.json`
+- [ ] Keywords include `walkerOS` and `walkerOS-transformer`
+
+---
+
+## Phase 5: Implement
 
 **Now write code to transform examples as expected.**
 
-### 4.1 Define Types
+### 5.1 Define Types
 
 See [templates/validation/types.ts](templates/validation/types.ts) for the
 pattern. Define `Settings` and `Types` interfaces.
 
-### 4.2 Implement Transformer (Context Pattern)
+### 5.2 Implement Transformer (Context Pattern)
 
 Transformers use the **context pattern** - they receive a single `context`
 object containing `config`, `env`, `logger`, `id`, and `collector`.
@@ -188,7 +227,7 @@ complete implementation example.
 3. **Push receives pushContext**: The `push` function gets event + push context
 4. **Return values**: `event` (continue), `void` (passthrough), `false` (cancel)
 
-### 4.3 Export
+### 5.3 Export
 
 `src/index.ts`:
 
@@ -204,7 +243,7 @@ export type { Settings, Types } from './types';
 
 ---
 
-## Phase 5: Test Against Examples
+## Phase 6: Test Against Examples
 
 **Verify implementation produces expected outputs.**
 
@@ -223,7 +262,7 @@ a complete test suite showing:
 
 ---
 
-## Phase 6: Document
+## Phase 7: Document
 
 Follow the [writing-documentation](../walkeros-writing-documentation/SKILL.md)
 skill for:
@@ -251,6 +290,8 @@ requirements (build, test, lint, no `any`):
 - [ ] Examples include before/after event pairs
 - [ ] Return values handle all cases (event, void, false)
 - [ ] Tests use examples for assertions (not hardcoded values)
+- [ ] `walkerOS.json` generated at build time
+- [ ] `walkerOS` field in package.json
 
 ---
 

skills/walkeros-using-cli/SKILL.md

@@ -217,6 +217,20 @@ Exit codes:
   3 = Input error
 ```
 
+### Validate a specific entry
+
+Validate a destination, source, or transformer's settings against its package
+schema:
+
+```bash
+walkeros validate destinations.snowplow
+walkeros validate sources.browser
+walkeros validate transformers.validator
+```
+
+Uses dot-notation: `{section}.{key}`. Fetches the package's `walkerOS.json` from
+CDN and validates `config.settings` against the published schema.
+
 ### Run Command
 
 ```bash

skills/walkeros-writing-documentation/SKILL.md

@@ -165,6 +165,8 @@ export * as examples from './examples';
 - [ ] Follows package/skill/website templates
 - [ ] Terminology matches: walkerOS, collector, destination, source
 - [ ] Headings use sentence case (e.g., "Next steps" not "Next Steps")
+- [ ] `walkerOS.json` convention followed (walkerOS field in package.json,
+      buildDev in tsup)
 
 ---
 
@@ -238,6 +240,23 @@ See [src/types.ts](./src/types.ts) for TypeScript interfaces.
 
 ````
 
+### walkerOS.json
+
+Every package should document its `walkerOS.json` convention in the README:
+
+```json
+{
+  "walkerOS": {
+    "type": "destination",
+    "platform": "web",
+    "schema": "./dist/dev/walkerOS.json"
+  }
+}
+```
+
+Adjust `type` (`destination`, `source`, `transformer`) and `platform` (`web`,
+`server`) to match the package.
+
 ### Website Doc Template (MDX)
 
 ```mdx