etemaro-strategy-validator · diff
v1.2.0 to v2.0.0
43 added, 53 removed. Audit A to A.
---
name: etemaro-strategy-validator
description: >
Validate Etemaro strategy JSON files through the Etemaro CLI and report whether each
- strategy is valid or invalid, plus which fields are unknown/legacy and will therefore be
+ strategy is valid or invalid, plus which fields are unknown and will therefore be
ignored by the runtime. Use this skill whenever the user asks to validate, lint, check, or
sanity-check a strategy JSON file (config/shared/strategy-library.json, an agent strategy
entry, or a pasted strategy object), asks "is this strategy valid?", "why is my strategy
field ignored?", "check the strategy schema", or "does this strategy have unknown fields?".
- Also trigger when a strategy behaves as if a field is missing — that is usually a silently
- dropped snake_case key. Trigger even without the word "validate": pointing at a strategy JSON
- and asking what is wrong or what will be used is this skill.
+ Trigger even without the word "validate": pointing at a strategy JSON and asking what is
+ wrong or what will be used is this skill.
metadata:
- version: 1.2.0
+ version: 2.0.0
---
# Etemaro Strategy Validator
Validates strategy JSON against the canonical `Strategy` schema using the **Etemaro CLI** as
the single source of truth. Never re-implement the schema in a script — call the command.
User config uses the same CLI and the same report format (`etemaro config validate`).
Why this matters: `StrategyLibraryManager.loadMerged()` casts the JSON straight to `Strategy`
- with no normalisation. A snake_case key like `lp_strategy` does not throw; it is silently
- dropped and code reading `strategy.lpStrategy` sees `undefined`. The command surfaces that.
+ with no normalisation. Unknown fields or misplaced keys are silently dropped and code reading
+ them sees `undefined`. The command surfaces that.
## Run it
Prefer the global binary; fall back to the project scripts. Run from the repository root.
```bash
# strategy library / single strategy
etemaro strategy validate config/shared/strategy-library.json
npm run validate:strategy -- config/shared/strategy-library.json
# active-strategy check (requires smartWalletListId when the loaded config needs it)
etemaro strategy validate --active config/shared/strategy-library.json
# user config (same report format)
etemaro config validate
etemaro config validate --env-optional
npm run validate:config --env-optional
# machine-readable / strict
etemaro strategy validate config/shared/strategy-library.json --json
etemaro strategy validate config/shared/strategy-library.json --strict
```
Flags:
| Flag | Command | Effect |
|------|---------|--------|
- | `--active` | strategy | Enforce the active-strategy gate: error when `screening.entrySource=smart_wallets` and the strategy lacks `smartWalletListId`; warn when `smartWalletScoreBonus>0` without a list (optional boost) |
+ | `--active` | strategy | Enforce active-strategy gate: error when `screening.entrySource=smart_wallets` and strategy lacks `smartWalletListId`; warn when `smartWalletScoreBonus>0` without a list |
| `--strict` | strategy | Treat unknown top-level fields as errors |
| `--env-optional` | config | Downgrade unset `env.*` references to warnings (structure-only validation) |
| `--json` | both | Machine-readable report |
To target a specific instance config:
```bash
AGENT_CONFIG_PATH=config/instances/agent-config.copy_trade_lag.v260830-1.json \
etemaro strategy validate --active config/shared/strategy-library.json
```
- (Use the env var, not `--config <path>`, when you also need positional file arguments —
- `--config` is a global flag resolved before subcommand parsing.)
-
## Reading the report
Both commands use this format:
```
File: <path>
Validation: <config | strategy-id>
Status: VALID|INVALID
Errors: ...
Warnings: ...
Notes: ...
Unknown (unused) fields: <comma list>
Field usage: <field → consumed/descriptive> (strategy only)
Totals: N valid, M invalid
```
- **Status** — INVALID means at least one error (fix before deploying).
- - **Errors** — missing required fields, wrong types, legacy snake_case keys, unknown config
- keys, broken `smartWalletListId`.
+ - **Errors** — missing required fields, wrong types, unknown config keys, broken `smartWalletListId`.
- **Warnings** — unknown strategy fields ("will be ignored"), bad enums, unparsable dates, or
unset env refs under `--env-optional`.
- **Unknown (unused) fields** — the explicit answer to "what will not be in use?".
- **Field usage** — for each strategy field, whether current code consumes it or it is
descriptive only.
Exit code is `0` when valid, `1` otherwise.
- Report back to the user with: file, entry id, VALID/INVALID, errors first, then the
- unknown/unused fields, then one line noting that descriptive-only fields do not affect deploy
- decisions. Keep it terse; do not restate the whole field-usage table unless asked.
+ Report back to the user with: file, entry id, VALID/INVALID, errors first, then unknown/unused fields, then notes on descriptive fields. Keep it terse.
## Accepted input shapes
- A strategy library `{ "strategies": { "<id>": { ... } } }` — validates every entry.
- A single strategy object `{ "id": "...", "name": "...", ... }`.
- A config JSON file (for `config validate`).
- ## Canonical schema (for interpreting the report)
+ ## Exact Canonical Schema
+ All keys are strictly **camelCase**.
+
Required strategy keys: `id`, `name`.
- | Key | Type | Consumed? |
- |-----|------|-----------|
- | `id` | string | yes — library key + active pointer |
- | `name` | string | yes — logs, lists, LLM strategy context |
+ | Key | Type | Consumed by Runtime? |
+ |-----|------|----------------------|
+ | `id` | string | **yes** — library key + active pointer |
+ | `name` | string | **yes** — logs, lists, LLM strategy context |
| `author` | string | stored/descriptive |
| `smartWalletListId` | string | **yes** — startup validation + smart-wallet screening |
- | `lpStrategy` | string (`bid_ask`/`spot`/`curve`/`mixed`/`any`) | descriptive — deploy uses `config.strategy.strategyMeteora` |
- | `tokenCriteria` | object | descriptive — not read by screening |
- | `entry` | object | partial — `condition`/`notes` feed the LLM context; `singleSide` is not consumed |
- | `range` | object | descriptive — not read at deploy |
- | `exit` | object | partial — `notes` feed the LLM context; `takeProfitPct` is not consumed |
- | `bestFor` | string | yes — LLM strategy context + lists |
+ | `lpStrategy` | string (`bid_ask`\|`spot`\|`curve`\|`mixed`\|`any`) | stored/descriptive (deploy uses `config.strategy.strategyMeteora`) |
+ | `tokenCriteria` | object | stored/descriptive (not read by screening) |
+ | `entry` | object | partial — `condition`/`notes` feed LLM context; `singleSide` not consumed |
+ | `range` | object | stored/descriptive (not read at deploy) |
+ | `exit` | object | partial — `notes` feed LLM context; `takeProfitPct` not consumed |
+ | `bestFor` | string | **yes** — LLM strategy context + lists |
| `raw` | string | stored/descriptive |
| `addedAt` / `updatedAt` | ISO date string | stored/descriptive |
- Known nested subfields: `tokenCriteria` (`min_mcap`, `min_age_days`, `requires_kol`, `notes`),
- `entry` (`condition`, `price_change_threshold_pct`, `singleSide` `sol|token`, `notes`),
- `range` (`type`, `binsBelowPct`, `notes`), `exit` (`takeProfitPct`, `notes`).
-
- ## Legacy snake_case → camelCase
-
- These keys silently do nothing; the command reports each as an error:
+ ### Exact Nested Field Specifications
- | Legacy (ignored) | Canonical |
- |------------------|-----------|
- | `lp_strategy` | `lpStrategy` |
- | `token_criteria` | `tokenCriteria` |
- | `best_for` | `bestFor` |
- | `added_at` | `addedAt` |
- | `updated_at` | `updatedAt` |
- | `entry.single_side` | `entry.singleSide` |
- | `range.bins_below_pct` | `range.binsBelowPct` |
- | `exit.take_profit_pct` | `exit.takeProfitPct` |
+ - **`entry`**:
+ - `condition`: string (describes entry logic)
+ - `singleSide`: `"sol"` | `"token"` | null
+ - `price_change_threshold_pct`: number
+ - `notes`: string
+ - **`range`**:
+ - `type`: `"tight"` | `"default"` | `"wide"` | `"panda"` | `"custom"`
+ - `binsBelowPct`: number
+ - `notes`: string
+ - **`exit`**:
+ - `takeProfitPct`: number
+ - `notes`: string
+ - **`tokenCriteria`**:
+ - `min_mcap`: number
+ - `min_age_days`: number
+ - `requires_kol`: boolean
+ - `notes`: string
## Pre-commit
`.husky/pre-commit` runs both validators before every commit:
- `validate:config --env-optional`, the private strategy library with `--active`, and the shared
- strategy library. If a commit is blocked, run the same commands locally and fix the reported
- errors.
+ `validate:config --env-optional`, private strategy library with `--active`, and shared strategy library. Blocked commits must be corrected to follow canonical camelCase schema.
- ## Keeping the schema current
+ ## Source of Truth
- The strategy schema lives in `packages/core/src/domain/strategy-validation.ts`; the config
- validator wraps `UserConfigSchema` in `packages/core/src/config/config-validation.ts`. Both are
- exported through `@etemaro/core` and surfaced by the CLI. Update those files when
- `shared/types.ts` (`Strategy`), `strategy-library.ts`, `config/schema.ts`, or
- `ToolDefinitions.ts` changes — never fork the schema into a skill script.
+ The strategy schema lives in `packages/core/src/domain/strategy-validation.ts`; config validator wraps `UserConfigSchema` in `packages/core/src/config/config-validation.ts`. Both are exported through `@etemaro/core` and surfaced by the CLI.