walkeros-understanding-development
/walkeros-understanding-development
Wyjaśnia konwencje wkładu w walkerOS: przepływ build, test i lint, zasady XP, strukturę katalogów i korzystanie z pakietów, przed pisaniem kodu.
- Autor
- elbwalker ↗
- Repozytorium
- walkerOS ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 22.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Wyjaśnia konwencje wkładu w walkerOS: przepływ build, test i lint, zasady XP, strukturę katalogów i korzystanie z pakietów, przed pisaniem kodu.
Oryginalny opis (EN)
Use when contributing to walkerOS, before writing code, or when unsure about project conventions. Covers build/test/lint workflow, XP principles, folder structure, and package usage.
Jak działa
- Overview
- Commands
- XP Principles (Non-Negotiable)
- Folder Structure
- Core Package Usage
- Editing core Config types
- Error visibility contract
- Platform boundaries
- Testing
- Related Skills
Podgląd SKILL.md
---
name: walkeros-understanding-development
description:
Use when contributing to walkerOS, before writing code, or when unsure about
project conventions. Covers build/test/lint workflow, XP principles, folder
structure, and package usage.
---
# Understanding walkerOS Development
## 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
| 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)
| 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
```
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/ # Zero-config browser file for GTM
├── quickstart/ # Code examples (source of truth for patterns)
└── demos/ # Demo applications
```
## Core Package Usage
**Always import from `@walkeros/core`:**
```typescript
// 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
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
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.
## Platform boundaries
Every package is one platform: web, server, or neutral (usable on both, like
`@walkeros/core` and `@walkeros/collector`). Neutral code ships inside walker.js
and runs on a server too, so it uses neither platform's APIs.
- **Where it is declared.** A step package sets `walkerOS.platform` in its
`package.json`: `["web"]`, `["server"]`, or both for neutral. Every other
package and published app is in the `declared` table of
`packages/config/scripts/check-platform.mjs`. A package declared nowhere fails
the check.
- **Presets.** `base.json` is neutral (`lib: es2020`), `web.json` adds `dom`,
`node.json` is `es2022`. All set `types` to `node` and `jest`, so no other
`@types` package can bring the DOM back in. A package tsconfig may add only an
allowlisted ambient vendor type (`gtag.js`, `facebook-pixel`).
- **What each may use.** Web: browser globals, no Node globals or builtins
(`Buffer`, `process`, `fs`, `node:*`). Server: Node, no browser globals.
Neutral: neither, and no `globalThis`, no `jsdom` import and no
`/// <reference lib or types>` in any file, tests included. ESLint holds these
lines where TypeScript cannot: `@walkeros/config/eslint/web`, `/node` (its
`nodePlatform` block) and `/neutral`.
- **API floor.** Neutral and web code may use ES2020 APIs at most; ES2021 and
later (for example the `cause` argument of `new Error`) fail typecheck, so
errors assign `cause` themselves.
- **Needing the other platform.** A neutral package that needs something only
the web has defines a small interface in `@walkeros/core` (a port), web-core
implements it, and the web caller passes it in explicitly. Examples:
`ObserveSlot` (`pageObserveSlot()` from `@walkeros/web-core`) and
`Flow.StepPage` (`page` from `@walkeros/web-core/dev`). Node-only code of core
lives in `@walkeros/core/node`.
- **Check.** `npm run check:platform` from the walkerOS root fails for any drift
in a preset, `lib`, `types`, eslint config or declaration. CI runs it on every
run, outside the turbo cache.
## 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
- [walkeros-testing-strategy](../walkeros-testing-strategy/SKILL.md) - Testing
patterns and env mocking
**Source Files:**
- [packages/core/](../../packages/core/) - Core utilities
- [packages/config/](../../packages/config/) - Shared configuration
- [apps/quickstart/](../../apps/quickstart/) - Validated examples
Wersje
W bazie nie ma innych skilli o nazwie walkeros-understanding-development.
Migawka bazy z 13.11.2026 · wersja paczki 675559213056 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 95walkeros-understanding-flow
Wyjaśnia architekturę walkerOS i przepływ danych we wzorcu Source, Collector, Destination oraz podział odpowiedzialności przy projektowaniu potoków zdarzeń. - 100walkeros-testing-strategy
Prowadzi pisanie i przegląd testów pakietów walkerOS, obejmując wzorzec env, przykłady deweloperskie i strategie dla poszczególnych pakietów. - 84contributing
Przypomina zasady wkładu w ekosystem IOWarp/Clio: przepływ pracy w gicie, standardy kodu i architekturę projektu. - 100contributing
Prowadzi przez workflow wkładu w Race Condition: konfigurację hooków pre-commit, testy przed PR i wymagania dotyczące stylu kodu. - 100output-dev-folder-structure
Opisuje konwencje struktury folderów workflow w Output SDK przy tworzeniu nowych workflow i porządkowaniu plików. - 100repo-understanding-repository-architecture
Opisuje sześciowarstwową hierarchię zarządzania repozytorium: od wizji przez zasady, konwencje i rozwój, po agentów i przepływy pracy.