Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

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.

Repozytorium
walkerOS ↗
Licencja
MIT
Ostatnia zmiana repozytorium
22.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Overview
  2. Commands
  3. XP Principles (Non-Negotiable)
  4. Folder Structure
  5. Core Package Usage
  6. Editing core Config types
  7. Error visibility contract
  8. Platform boundaries
  9. Testing
  10. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 203 linii, 1 031 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.