@fluentcommerce/fluent-mcp-extn 0.1.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing Guide
+
+This guide defines how to safely change `fluent-mcp-extn` while keeping
+behavior predictable for all clients.
+
+## 1) Core principles
+
+- Keep the extension **client-agnostic** (no client-specific names in code/docs).
+- Prefer **typed boundaries** and avoid unscoped `any`.
+- Keep tool responses consistent:
+  - success: `{ "ok": true, ... }`
+  - failure: `{ "ok": false, "error": { ... } }`
+- Route Fluent API calls through `FluentClientAdapter` only.
+
+## 2) Local setup
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## 3) Change workflow
+
+1. Make focused changes.
+2. Add or update tests.
+3. Run `npm run build`.
+4. Run `npm test`.
+5. Run `npm run e2e:smoke -- --skip-real-send` when touching tool runtime (requires `FLUENT_BASE_URL` + auth env, or `--profile`).
+6. Update docs if tool behavior/config changed.
+
+## 4) Adding a new tool (required checklist)
+
+When adding a tool, update all of the following:
+
+1. `src/tools.ts`
+   - add zod schema
+   - add `TOOL_DEFINITIONS` entry
+   - add handler branch
+2. `src/index.ts`
+   - add tool name to startup log list
+3. tests
+   - add/adjust unit tests in `test/`
+4. docs
+   - update `docs/TOOL_REFERENCE.md`
+   - update `docs/E2E_TESTING.md` if smoke flow changes
+
+## 5) Error handling standards
+
+- Throw `ToolError` for domain/runtime failures.
+- Do not return raw thrown errors directly.
+- Let `toToolFailure()` convert unknown errors into normalized error payloads.
+- Use specific error codes where possible (`AUTH_ERROR`, `VALIDATION_ERROR`, etc.).
+
+## 6) Resilience standards
+
+- Keep retry/timeout policy centralized via:
+  - `withTimeout()`
+  - `withRetry()`
+- Avoid per-tool custom retry loops.
+- Use config-driven values (`FLUENT_REQUEST_TIMEOUT_MS`, retry env vars).
+- Preserve idempotency boundaries:
+  - read operations can use retry/backoff
+  - non-idempotent write operations must not auto-retry
+- Keep SDK retry disabled and adapter retry as the single control plane.
+
+## 7) Security and secrets
+
+- Never log secrets or token values.
+- Use redacted summaries via `toSafeConfigSummary()`.
+- Prefer profile, `TOKEN_COMMAND`, or OAuth over static tokens in shared environments.
+
+## 8) Documentation standards
+
+- Keep docs concise and task-oriented.
+- Include at least one valid request example when changing tool inputs.
+- Update all cross-links in `README.md` when adding new docs.
+- For behavior changes, update all affected docs end-to-end:
+  - `README.md`
+  - `docs/TOOL_REFERENCE.md`
+  - `docs/RUNBOOK.md`
+  - `docs/E2E_TESTING.md`
+
+## 9) Pull request quality bar
+
+A change is ready only if:
+
+- build passes
+- tests pass
+- smoke runner passes (or is intentionally skipped with rationale)
+- no lint errors introduced
+- docs updated for behavior/interface changes
+- no client-specific wording added
+
+## 10) CI expectations
+
+- CI workflow file: `.github/workflows/ci.yml`
+- `build-and-test` must pass for every PR.
+- `e2e-smoke` is manual (`workflow_dispatch`) and requires repository secrets.
+