diff --git a/AGENTS.md b/AGENTS.md index 6629032a066..6088422d254 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,17 +15,9 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work. ## Map -- Core TS: `src/`, `ui/`, `packages/` -- Bundled plugins: `extensions/` -- Public SDK: `src/plugin-sdk/*` -- Channel internals: `src/channels/*` -- Plugin loader/contracts: `src/plugins/*` -- Gateway protocol: `src/gateway/protocol/*` -- Docs: `docs/` -- Apps: `apps/`, `Swabble/` -- Installers: sibling `../openclaw.ai` - -Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/`, `src/gateway/`, `src/gateway/protocol/`, `src/agents/`, `test/helpers/`, `test/helpers/channels/`, `docs/`, `ui/`, `scripts/`. +- Core TS: `src/`, `ui/`, `packages/`; plugins: `extensions/`; SDK: `src/plugin-sdk/*`; channels: `src/channels/*`; loader: `src/plugins/*`; protocol: `src/gateway/protocol/*`; docs/apps: `docs/`, `apps/`, `Swabble/`. +- Installers: sibling `../openclaw.ai`. +- Scoped guides exist in: `extensions/`, `src/{plugin-sdk,channels,plugins,gateway,gateway/protocol,agents}/`, `test/helpers*/`, `docs/`, `ui/`, `scripts/`. ## Architecture @@ -48,19 +40,14 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/` - Runtime: Node 22+. Keep Node + Bun paths working. - Install: `pnpm install` (keep Bun lock/patches aligned if touched). -- CLI: `pnpm openclaw ...` or `pnpm dev` -- Build: `pnpm build` -- Smart gate: `pnpm check:changed`; explain with `pnpm changed:lanes --json`; staged preview `pnpm check:changed --staged`. -- Prod sweep: `pnpm check` (prod type/lint/guards, no tests). -- Tests: `pnpm test`; changed `pnpm test:changed`; serial `pnpm test:serial`; coverage `pnpm test:coverage`. -- Extension tests: `pnpm test:extensions` / `pnpm test extensions` / `pnpm test extensions/`. +- CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`. +- Smart gate: `pnpm check:changed`; explain `pnpm changed:lanes --json`; staged preview `pnpm check:changed --staged`. +- Prod sweep: `pnpm check`; tests: `pnpm test`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`. +- Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/`. - Targeted tests: `pnpm test [vitest args...]`; never raw `vitest`. -- Shard timings: `.artifacts/vitest-shard-timings.json`; disable `OPENCLAW_TEST_PROJECTS_TIMINGS=0`. -- Format: `pnpm format:check` / `pnpm format`. -- Typecheck: `pnpm tsgo`, `pnpm tsgo:prod`, `pnpm check:test-types`/`pnpm tsgo:test`, `pnpm tsgo:all`; profile `pnpm tsgo:profile [...]`. -- Type policy: use `tsgo`; do not add `tsc --noEmit`, `typecheck`, `check:types`. `tsc` only for declaration/package-boundary emit gaps. -- Lint: `pnpm lint`, `pnpm lint:core`, `pnpm lint:extensions`, `pnpm lint:scripts`, `pnpm lint:apps`, `pnpm lint:all`. -- Local heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`. +- Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); do not add `tsc --noEmit`, `typecheck`, `check:types`. +- Format/lint: `pnpm format:check`/`pnpm format`; `pnpm lint*` lanes. +- Heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`. - Local first. Use repo `pnpm` lanes before Blacksmith/Testbox. Remote only for parity-only failures, secrets/services, or explicit ask. ## GitHub / CI @@ -112,17 +99,13 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/` ## Tests -- Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`. -- Example models: `sonnet-4.6`, `gpt-5.4`. +- Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`; example models `sonnet-4.6`, `gpt-5.4`. - Clean timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` safe. -- Hot tests: avoid per-test `vi.resetModules()` + heavy imports. Prefer static/`beforeAll` imports + direct state reset. -- Measure first: `pnpm test:perf:imports `, `pnpm test:perf:hotspots --limit N`. -- Seam depth: unit-test pure helpers/contracts; one integration smoke per boundary. -- Mock expensive seams directly: scanners, manifests, package registries, fs crawls, provider SDKs, network/process launch. -- Prefer injection over module mocks; if mocking modules, mock narrow local `*.runtime.ts`, not broad barrels. -- Share fixtures/builders. Do not recreate temp/plugin workspaces per case unless isolation needs it. -- Delete duplicate assertions. Assert behavior that can regress here. -- Avoid broad `importOriginal()` / `openclaw/plugin-sdk/*` partial mocks; add narrow runtime seam. +- Hot tests: avoid per-test `vi.resetModules()` + heavy imports. Measure with `pnpm test:perf:imports ` / `pnpm test:perf:hotspots --limit N`. +- Seam depth: pure helper/contract unit tests; one integration smoke per boundary. +- Mock expensive seams directly: scanners, manifests, registries, fs crawls, provider SDKs, network/process launch. +- Prefer injection; if module mocking, mock narrow local `*.runtime.ts`, not broad barrels or `openclaw/plugin-sdk/*`. +- Share fixtures/builders; delete duplicate assertions; assert behavior that can regress here. - Do not edit baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval. - Test workers max 16. Memory pressure: `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`. - Live: `OPENCLAW_LIVE_TEST=1 pnpm test:live`; verbose `OPENCLAW_LIVE_TEST_QUIET=0`. @@ -161,17 +144,14 @@ Scoped guides: `extensions/`, `src/plugin-sdk/`, `src/channels/`, `src/plugins/` - Before simulator/emulator testing, check real iOS/Android devices. - "restart iOS/Android apps" = rebuild/reinstall/relaunch, not kill/launch. - SwiftUI: Observation (`@Observable`, `@Bindable`) over new `ObservableObject`. -- Mac gateway: use app or `openclaw gateway restart/status --deep`; no ad-hoc tmux gateway. Rebuild mac app locally. -- Mac logs: `./scripts/clawlog.sh`. +- Mac gateway: use app or `openclaw gateway restart/status --deep`; no ad-hoc tmux gateway. Logs: `./scripts/clawlog.sh`. - Version bump touches: `package.json`, `apps/android/app/build.gradle.kts`, `apps/ios/version.json` + `pnpm ios:version:sync`, macOS `Info.plist`, `docs/install/updating.md`. Appcast only for Sparkle release. -- iOS Team ID: `security find-identity -p codesigning -v`; fallback `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`. - Mobile LAN pairing: plaintext `ws://` loopback-only. Private-network `ws://` needs `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`; Tailscale/public use `wss://` or tunnel. - A2UI hash `src/canvas-host/a2ui/.bundle.hash`: generated; ignore unless running `pnpm canvas:a2ui:bundle`; commit separately. ## Ops / Footguns -- Remote install docs: `docs/install/exe-dev.md`, `docs/install/fly.md`, `docs/install/hetzner.md`. -- Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`. +- Remote install docs: `docs/install/{exe-dev,fly,hetzner}.md`. Parallels smoke: `$openclaw-parallels-smoke`; Discord roundtrip: `parallels-discord-roundtrip`. - Rebrand/migration/config warnings: run `openclaw doctor`. - Never edit `node_modules`. - Local-only `.agents` ignores: `.git/info/exclude`, not repo `.gitignore`.