Skip to main content

Coding style

This guide owns the coding conventions for WednesdayAI core. For the PR gate and contribution workflow, see Contributing. For test conventions, see Testing.

Principles

Follow the Development Principles in Contributing. In short:
  • Reuse maintained packages already in the stack instead of building from scratch.
  • Fix bug classes rather than instances. Use real parsers, not regex, for structured formats.
  • Assert causes in tests.
  • Keep scope to the goal.
  • Block reviews only on in-scope correctness and security.

Language and structure

  • Language: TypeScript ESM with strict: true. No @ts-nocheck. Do not disable no-explicit-any; fix the root cause.
  • Style: functional and module pattern dominant. Use classes for channel adapters and stateful lifecycle managers.
  • Dependency injection: createDefaultDeps() in src/cli/deps.ts returns a plain dependency object. Commands receive it as a parameter. There is no IoC framework.
  • No prototype mutation: never use applyPrototypeMixins, Object.defineProperty on .prototype, or Class.prototype exports. Use explicit inheritance or composition. Get explicit approval first.
  • Comments: write them only for non-obvious logic such as hidden constraints, workarounds, and subtle invariants. Do not write docblocks that restate what the code does.
  • File size: keep files under 500 lines of code. pnpm check:loc (part of pnpm check) runs scripts/check-core-loc.ts, the core LOC per-file ratchet from ADR 1440: it blocks a core src/ file over 800 lines that is not grandfathered in scripts/core-loc-baseline.json, and a grandfathered file that grew past its recorded ceiling. The core total is reported, not gated (ADR 1967). pnpm check:loc --update only lowers per-file entries; raising one needs a written justification in the PR.
  • Formatting: run pnpm check before committing. Resolve formatting-only diffs without asking.
  • Naming: use WednesdayAI in user-facing docs and headings. wednesdayai is the primary binary name and openclaw is a backward-compatible legacy alias under staged removal (ADR 2057). Config keys and internal identifiers stay openclaw.
  • Imports: use the .js extension for relative ESM imports, import type { X } for type-only imports, and import directly from the original module. Do not create files that only re-export another file.
  • Process-scoped state across the SDK bundle: gateway and conformance plugin loads hand the plugin the host’s own SDK instances through jiti virtualModules (ADR 1032), but a load that skips that handoff, for example a direct loadOpenClawPlugins call, still runs the plugin against its own jiti copy of the published wednesdayai/plugin-sdk tsdown bundle; plain module-scope mutable state would then split per copy. Any module-scope mutable state reachable through the SDK must use resolveProcessScopedMap (from wednesdayai/plugin-sdk/process-scoped-map) or be routed through an api.runtime member instead. Vitest aliases the SDK to src/, so test suites run one module graph and cannot see the split: guard split-sensitive bindings with vi.resetModules() plus a dynamic re-import in a *.process-scope.test.ts test (conformance example: extensions/telegram/src/conformance.split-graph.test.ts). The legacy openclaw/plugin-sdk specifier still loads (ADR 2057).

Do not duplicate helpers

Before writing a formatter, utility, or helper, search for an existing implementation and import it. If a function already exists, do not create a copy in another file. Never create local formatAge, formatDuration, or formatElapsedTime functions.

Script entry points

Scripts under scripts/ decide whether to run main() with isDirectRun(import.meta.url) from scripts/lib/direct-run.mjs. Guards built on scripts/lib/ts-guard-utils.mjs get it through runAsScript(import.meta.url, main). Do not compare import.meta.url with process.argv[1] directly. Node resolves symlinks in import.meta.url but keeps process.argv[1] as the caller typed it. A script launched through a symlinked path (the macOS temp directory /var is a symlink to /private/var, or a symlinked checkout) then skips main() and exits 0 without doing anything. isDirectRun resolves both sides with realpathSync. pnpm lint:scripts:direct-run (part of pnpm check) runs scripts/check-scripts-direct-run.mjs. It fails on any process.argv[1] read in scripts/ outside the helper and test files.

Colors and terminal output

Two modules split the work. src/terminal/palette.ts holds the color tokens. src/terminal/theme.ts wraps chalk around those tokens and exposes the semantic helpers. Use theme for output and never hardcode ANSI escapes.

Logging

Create one subsystem logger at module top and use it instead of console.log in production code:

Tool input schemas (TypeBox)

Tool input schemas use @sinclair/typebox. Several model providers reject schema constructs that TypeBox can produce, so keep schemas flat:
  • No Type.Union, and no anyOf, oneOf, or allOf in tool input schemas.
  • Use stringEnum and optionalStringEnum (a Type.Unsafe enum, in src/agents/schema/typebox.ts) for string enumerations.
  • Use Type.Optional(...) instead of ... | null.
  • Never use format as a raw property name. Some validators reject it.

Toolchain

Notes:
  • extensions/ is excluded from Oxlint (ignorePatterns). Extensions manage their own lint.
  • pnpm build does not type-check. Run pnpm tsgo for that.
  • pnpm check runs format check, tsgo, tsgo:web, tsgo:control, Oxlint, the custom lint scripts below, the contract-surface check (lint:contracts:surface), the installer-host guard, the version-source guard (version:guard), and the core LOC per-file ratchet (check:loc). The pre-push hook runs it (ADR 0118).
  • lint:extensions:no-core-tables (part of pnpm check) runs scripts/check-extension-core-table-access.ts. It fails on any reference from extensions/ to a core session table. Plugins own their tables (Postgres schema plugin_<id>, SQLite prefix plugin_<id>_) and read conversation data through the plugin-sdk; allowlist entries are test-harness only, each naming the finding that tracks its removal.
  • lint:sessions:no-sessionkey-identity-parse (part of pnpm check) runs scripts/check-no-sessionkey-identity-parse.mjs. It fails on non-test code under src/, extensions/, and apps/ that derives channel, account, peer kind/id, group, or user identity from sessionKey text: splitting, regex matching, or identity-segment string probes on the key, or any access on parseAgentSessionKey(...).rest. Identity comes from the persisted session actor (and the SDK runtimeIdentity fields), never from parsing the key; sessionKey is an opaque bucket id. The rule lives in ADR 0081 (dev-docs/adr/0081-config-independent-actor-identity.md); plugin-facing guidance is Session identity keying. A failure prints one - <path>:<line> <rule> line per violation (R1/R2/R3); a file the guard cannot scan reports <path>:0 SCAN-ERROR and must be fixed or reported, not ignored. The structural owner files (src/sessions/session-key-utils.ts, src/routing/session-key.ts, src/config/sessions/ctx-identity-backfill.ts, src/shared/session-visibility.ts, apps/web/src/ui/session-key-shape.ts) are exempt.
  • lint:adr:unique-numbers (part of pnpm check) runs scripts/check-adr-numbers.mjs. It fails when two files in dev-docs/adr/ share a number, or when a file there is not a flat <N>-<lowercase-slug>.md. A new ADR’s number is the WednesdayAI-core issue or PR number that carries the decision, zero-padded to 4 digits; ADRs 0001–0122 keep their sequential numbers (ADR 1577, dev-docs/adr/1577-adr-numbers-are-github-numbers.md). If the guard fails on your branch, rename your ADR to your issue or PR number.
  • version:guard (part of pnpm check) runs scripts/check-version-source.ts. It fails when the package.json version differs from the version at the merge base of HEAD and origin/main (GITHUB_BASE_REF overrides main); only the release-please PR bumps versions, and release-please--* branches are skipped. It fetches origin/<base> when that ref is missing, and refreshes it once before reporting a mismatch so a stale local ref cannot cause a false failure. It never fetches with --depth, so it cannot make a clone shallow (ADR 2403). Every failure, including a missing or invalid package.json in the working tree or at the merge base, exits 1 with one Version-source guard FAILED: line.