npm package: @rerise/core
Description: Framework-agnostic commerce core for Rerise applications.
Latest version: 1.0.6

# `@rerise/core`

Framework-agnostic commerce core for Rerise applications.

This package is designed to stay independent from the monorepo itself while
serving multiple apps such as `admin`, `store`, `blog`, and `workflow`.

## Why this package exists

`@rerise/core` should hold only the logic that is shared across applications:

- domain types and contracts
- pure business logic
- runtime validation schemas
- normalized helpers for payments, shipping, auth, and MongoDB

It should not contain:

- `Next.js` route handlers or server actions
- UI components
- provider-specific SDK implementations
- application-specific code that is used by only one app

## Included modules

- `@rerise/core/auth`
- `@rerise/core/commerce`
- `@rerise/core/mongodb`
- `@rerise/core/payments`
- `@rerise/core/shipping`
- `@rerise/core/utils`
- `@rerise/core/validation`

## Why `Rollup`

This package is a library, not a frontend app. `Rollup` is used here because it
fits library publishing well:

- reliable `ESM + CJS` outputs
- clean subpath exports
- predictable package structure

If you later want a visual sandbox or UI playground, add a separate
`playground/` app with `Vite`, `Storybook`, or `Ladle` instead of mixing that
concern into the core package.

## Runtime validation with `Zod`

TypeScript only protects you at compile time. This package now exports `Zod`
schemas for runtime validation at system boundaries:

- payment webhooks
- shipping payloads
- query/input parsing
- data crossing app boundaries

Example:

```ts
import { CartTotalsInputSchema, calculateCartTotals } from "@rerise/core/commerce";

const input = CartTotalsInputSchema.parse(requestBody);
const totals = calculateCartTotals(input);
```

## Development

```bash
npm install
npm run dev
npm run test:watch
npm run typecheck
```

## CLI

After installation, the package exposes a small CLI:

```bash
npx @rerise/core init
npx @rerise/core doctor
npx @rerise/core skills
npx @rerise/core skills list
```

If the package is already installed locally, these also work:

```bash
rerise-core help
rerise-core doctor
rerise-core skills
```

The install output is intentionally informative but non-interactive. It points
developers to the CLI instead of blocking `npm install`.

`skills` is now the interactive installer for local agent skills.

`init` and `skills` both scaffold a local `.agent` directory and write:

- `.agent/agent.json`
- `.agent/skills/<skill-name>/SKILL.md`

`init` is interactive by default and asks for:

- app targets
- agent runtime: `codex`, `cursor`, or `antigravity`
- skill templates to install

Use `npx @rerise/core skills list` if you only want to inspect the available
skill templates without starting the installer.

If you want the default setup without any questions, use:

```bash
npx @rerise/core init --yes
```

## Verification

```bash
npm run validate
```

This runs:

- type checking
- tests
- build
- package validation

## Versioning and publishing

This repository uses `Changesets`.

Create a release note:

```bash
npm run changeset
```

Apply version updates:

```bash
npm run version-packages
```

Publish to npm:

```bash
npm run release
```

## Local Agent Output

The generated `.agent` folder is intended for project-local agent setup and
skill scaffolding. Each installed skill is written as a standalone `SKILL.md`
file so it can be reviewed and customized inside the project.