webiny-js

# Context

Read `AGENTS.md`.

# Claude Project Guidelines

This file is read by Claude Code on every run. Keep it up to date with your project's conventions.

# Reading code

NEVER call Read or Grep to understand code structure or locate symbols.
You MUST use codegraph_context, codegraph_search, or codegraph_callers first.
Only call Read if codegraph explicitly returns no results AND you explain why in your response.

## Development Commands

Always suppress verbose output to keep token usage low.
Redirect stdout to `/dev/null` for noisy commands and capture only stderr,
or use `tail` to capture just the last few lines when you need a summary.

```bash
# Install dependencies  (suppress all output – it's noise)
yarn > /dev/null 2>&1

# Run tests  (keep output – failures matter, but cap at last 50 lines)
yarn test packages/{package-name} 2>&1 | tail -50

# Build all changed packages  (capture last 30 lines to see result without full log)
yarn build 2>&1 | tail -30

# Build a single package  (capture last 30 lines to see result without full log)
yarn build -p @webiny/api-core 2>&1 | tail -30
```

## Before Commit

Before each commit, run the following commands:

```
# Stage all changed files
git add .

# Ensure yarn.lock is up to date
yarn > /dev/null 2>&1

# Update all tsconfig files
node scripts/generateTsConfigsInPackages.js

# Make sure all package.json deps are configured correctly
yarn adio

# Format changed files
yarn format > /dev/null 2>&1

# Run oxlint
yarn lint

# Make sure dependencies are in sync
yarn webiny sync-dependencies

# Stage all changed files (again!)
git add .
```

If any of the steps fail, and you fix anything, you must rerun all scripts from the beginning.

## Code Conventions

- **Formatting:** oxfmt with project defaults (`.oxfmtrc.json`)
- **Linting:** Oxlint with project config (`.oxlintrc.json`)
- **Commit style:** Conventional Commits (`feat:`, `fix:`, `chore:`, etc.)
- **Branch naming:** `claude/issue-<number>` for Claude-generated branches
- **PR titles:** Mirror the commit style

## Webiny

This project uses the Webiny framework.
A `webiny` MCP server is available.
When helping with Webiny-related tasks, call `get_started()` first.

## Exploration

- DO NOT read code in `dist` folders.

## Persist Learnings

When new backend features are discovered, update `ai-context/core-features-reference.md` with the new feature reference. DO NOT update this file with React features.

## Code

Code-style rules live in `ai-context/code-style/`, one rule per file (ESLint-style `do this / don't do this`). Read every rule in that folder before writing or editing code; see `ai-context/code-style/README.md` for the index. When adding a new rule, create a new `*.md` file there and add it to the index.

- When generating code, once done, run `git add .` to stage all changes.

## Building

- When type checking, use `yarn check -p <package-name>`, e.g., `yarn check -p @webiny/api-core`
- When building a single package, use `yarn build -p <package-name> --safe-replace`, e.g., `yarn build -p @webiny/api-core --safe-replace`. We use "--safe-replace" in order to not have our active bundling watch process break.
- To build all packages, simply run `yarn build`.
- To build all packages without caching, use `yarn build --no-cache `.

## Testing

- To test a package, use `yarn test packages/<package-name>`, e.g., `yarn test packages/api-core`

## Commits

- Always run the full pre-commit checklist and commit after every code change — do not wait to be asked:
  ```bash
  git add .
  yarn > /dev/null 2>&1
  node scripts/generateTsConfigsInPackages.js
  yarn adio
  yarn format > /dev/null 2>&1
  yarn lint
  yarn webiny sync-dependencies
  git add .
  ```
  If any step fixes something, rerun from the top before committing.
- Avoid overly verbose descriptions or unnecessary details.
- Use conventional commit message formats like:
  - feat: for new features
  - fix: for bug fixes
  - docs: for documentation changes

## Entry Data Factory Pattern (`api-headless-cms`)

Entry data factories are injectable features, not imported functions. When writing use cases in `packages/api-headless-cms` that need to produce domain entry objects:

- **Do not** import from `~/crud/contentEntry/entryDataFactories/`
- **Do** inject the factory token via `createImplementation` dependencies and call `this.xyzFactory.create(...)`
- Factories live in `packages/api-headless-cms/src/features/contentEntry/entryDataFactories/`
- Token scope: `"Cms/Entry/<FactoryName>"` (e.g. `"Cms/Entry/CreateEntryDataFactory"`)
- All factories are singletons

Available factories:

- `CreateEntryDataFactory` — new entry from raw input
- `UpdateEntryDataFactory` — update existing entry
- `CreateEntryRevisionFromDataFactory` — new revision from existing entry
- `CreatePublishEntryDataFactory` — transition to published state
- `CreateUnpublishEntryDataFactory` — transition to unpublished state
- `CreateRepublishEntryDataFactory` — re-publish with refreshed references

## Webiny

This project uses the Webiny framework.
A `webiny` MCP server is available.
When helping with Webiny-related tasks:

1. Call `list_webiny_skills` to see available skills.
2. Call `get_webiny_skill` with the relevant topic before writing code.

## CI/CD - GitHub Actions

When working on GitHub Actions workflows, when possible, we always want to make modifications on `.github/workflows/wac` TS files first, and then emit YAML files via `yarn ci-workflows:build`. Only work on YAML files if a corresponding .wac.ts file does not exist.