Skip to content

AGENTS.md

Latest commit

 

History

History
51 lines (38 loc) · 2.53 KB

AGENTS.md

File metadata and controls

51 lines (38 loc) · 2.53 KB
Raw

Agent Guide

Read this file first. It tells you where to find context in this repo.

Quick Reference

What you need Where to look
How this repo is structured ARCHITECTURE.md
How to build/test/run CONTRIBUTING.md
Why decisions were made docs/ADRs/
What this repo does README.md
PR review rules .bito/guidelines/
Active specs/work docs/specs/

Sharp Edges & Invariants

  • Never instantiate CMA/CDA clients in this library. contentful-management and contentful are devDependencies for type imports only. Consumers provide their own clients.
  • All public exports must go through lib/index.ts. Do not add internal modules to the barrel without confirming downstream consumers need them.
  • test/ is published to npm (via files field in package.json). Do not put secrets, fixtures with real data, or large binary files in the test directory.
  • build(deps) commits trigger patch releases. Renovate PRs that merge will automatically publish. Be aware that merging a dep bump is equivalent to cutting a release.
  • Breaking changes require feat!: or BREAKING CHANGE footer. The { breaking: true, release: "major" } rule in semantic-release maps these to major versions. Missing this causes silent breaking patches (see ADR-002).
  • Do not downgrade engines.node below >=22. This was a deliberate v11 breaking change; reverting it would break consumers who upgraded.

Key Conventions

  • Commit format: Conventional Commits (enforced by Commitizen config)
  • Branch strategy: master (production) + beta (pre-release channel); feature branches merge to master
  • Test location: test/*.test.js — tests are plain JS using ts-jest preset
  • Module system: Node16 (CommonJS output from TypeScript source)
  • TypeScript: Strict mode, ES2022 target, declarations emitted

Integration Points

Upstream (this repo consumes):

  • contentful-management — type imports only (SysLink, KeyValueMap)
  • listr2 — type imports for task wrapper generics

Downstream (consumes this repo):

  • contentful-import — logging, proxy, task wrapping, sequence headers
  • contentful-export — logging, entity naming utilities
  • contentful-cli — transitively via import/export

Build & Quality

# Quick verification loop
npm ci && npm run build && npm test && npm run lint