> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Understanding walkerOS Development

## Overview[​](#overview "Direct link to Overview")

walkerOS follows extreme programming principles with strict conventions. This skill is your foundation before writing any code.

**Core principle:** DRY, KISS, YAGNI. Test first. Verify before claiming complete.

## Commands[​](#commands "Direct link to Commands")

| Command          | Purpose                     |
| ---------------- | --------------------------- |
| `npm install`    | Install all dependencies    |
| `npm run dev`    | Watch mode for all packages |
| `npm run build`  | Build all packages          |
| `npm run format` | Prettier formatting         |

**Verification cheatsheet:**

* While iterating (L1, touched package): `npm run verify:touched -- <pkg>`
* At plan completion (L2, affected since `origin/main`): `npm run verify:affected`

See `/workspaces/developer/AGENT.md` rule 11 for the full doctrine.

## XP Principles (Non-Negotiable)[​](#xp-principles-non-negotiable "Direct link to XP Principles (Non-Negotiable)")

| Principle    | In Practice                                              |
| ------------ | -------------------------------------------------------- |
| **DRY**      | Use `@walkeros/core` utilities, don't reimplement        |
| **KISS**     | Minimal code to solve the problem                        |
| **YAGNI**    | Only implement what's requested                          |
| **TDD**      | Test first, watch it fail, then implement                |
| **No `any`** | Never use `any` in production code (tests are exception) |

## Folder Structure[​](#folder-structure "Direct link to Folder Structure")

```
packages/

├── core/           # Platform-agnostic types, utilities, schemas

├── collector/      # Central event processing engine

├── config/         # Shared config (eslint, jest, tsconfig, tsup)

├── web/

│   ├── core/       # Web-specific utilities

│   ├── sources/    # browser, dataLayer

│   └── destinations/ # gtag, meta, api, piwikpro, plausible

└── server/

    ├── core/       # Server-specific utilities

    ├── sources/    # gcp

    └── destinations/ # aws, gcp, meta



apps/

├── walkerjs/       # Ready-to-use browser bundle

├── quickstart/     # Code examples (source of truth for patterns)

└── demos/          # Demo applications
```

## Core Package Usage[​](#core-package-usage "Direct link to Core Package Usage")

**Always import from `@walkeros/core`:**

```
// Types

import type { WalkerOS } from '@walkeros/core';



// Utilities

import {

  getEvent,

  createEvent, // Event creation

  getMappingEvent,

  getMappingValue, // Transformations

  isString,

  isObject,

  isDefined, // Type checking

  assign,

  clone, // Object operations

  tryCatch,

  tryCatchAsync, // Error handling

} from '@walkeros/core';
```

**Config package for shared tooling:**

* ESLint config: `@walkeros/config/eslint`
* Jest config: `@walkeros/config/jest`
* TSConfig: `@walkeros/config/tsconfig`
* Tsup config: `@walkeros/config/tsup`

## Editing core Config types[​](#editing-core-config-types "Direct link to Editing core Config types")

Core component configs live in two places:

* TS interface: `packages/core/src/types/{destination,source,transformer,store,collector}.ts`
* Zod schema: `packages/core/src/schemas/{destination,source,transformer,store,collector}.ts`

Both are hand-written and mirror each other. TS stays authoritative because Zod's inferencer collapses recursive types (`Routes`, `MatchExpression`, `Value`) to `unknown`. Zod drives runtime validation, JSON Schema emission, and website Configuration reference tables.

When adding, renaming, or removing a Config field, update BOTH files. A compile-time drift guard at `packages/core/src/schemas/__tests__/config-drift.test-d.ts` fails `tsc` if the key sets diverge. The guard checks keys only; value types may differ (recursion, generic slots). Run `npm run verify:touched -- core` to verify.

## Error visibility contract[​](#error-visibility-contract "Direct link to Error visibility contract")

Top-level boundaries in the collector (`createPush` in `push.ts`, `createCommand` in `command.ts`) wrap their inner pipeline in `tryCatchAsync`. The `onError` callback MUST do two things:

* log a structured error via `collector.logger.error(message, { ... })` with enough context to reproduce (event/ingest for push, command/data for command),
* increment `collector.status.failed`.

An empty `onError` is a defect: it swallows the exception, returns `{ ok: false }` silently, and leaves the operator blind. Use `packages/collector/src/push.ts` and `packages/collector/src/command.ts` as the canonical pattern.

Two categories of caught error:

1. **Internal walkerOS pipeline failures** (push, command, mapping outer wrap in `mapping.ts`, source factory / init / queueOn flush in `source.ts`, transformer init in `transformer.ts`, destination init in `destination.ts`): log AND `status.failed++`.
2. **User-supplied callbacks** (mapping `condition` / `fn` / `validate`, `on` subscriptions in `on.ts`): log only. `status.failed` stays a pipeline-health signal; user-code visibility goes via logs.

For invariant violations or operator-initiated aborts that must crash the host process, throw `FatalError` (exported from `@walkeros/core`). `FatalError` bypasses every boundary catch in both categories so a supervisor can terminate cleanly. Standard `Error` is absorbed, logged, and (for category 1) counted.

The log message verb identifies the site: `'mapping condition failed'`, `'source factory failed'`, `'transformer init failed'`, `'on callback failed'`, etc. Operators grep for the verb. No `kind` field is required except in `on.ts`, where seven sites share one verb and disambiguate via a typed `kind` field on the structured payload.

## Testing[​](#testing "Direct link to Testing")

**REQUIRED SKILL:** Use `testing-strategy` for detailed testing patterns.

Quick reference:

* Use `env` pattern for mocking (not Jest mocks)
* Import from `dev.ts` for examples
* Test first, watch it fail
* Verify before claiming complete

## Related Skills[​](#related-skills "Direct link to Related Skills")

* [walkeros-testing-strategy](https://www.walkeros.io/skills/walkeros-testing-strategy.md) - Testing patterns and env mocking

**Source Files:**

* [packages/core/](https://github.com/elbwalker/walkerOS/blob/main/packages/core) - Core utilities
* [packages/config/](https://github.com/elbwalker/walkerOS/blob/main/packages/config) - Shared configuration
* [apps/quickstart/](https://github.com/elbwalker/walkerOS/blob/main/apps/quickstart) - Validated examples