diff --git a/.ai/skills/README.md b/.ai/skills/README.md new file mode 100644 index 0000000..eeb0dbe --- /dev/null +++ b/.ai/skills/README.md @@ -0,0 +1,27 @@ +# Agent Skills (Cursor + Codex) + +This directory contains project-level skills for AI coding agents. + +## Structure + +``` +.ai/skills/ + plugin-docs-authoring/ + SKILL.md + template-blocks-architecture/ + SKILL.md + release-pr-hygiene/ + SKILL.md + medusa-plugin-context/ + SKILL.md +``` + +## Linking to Cursor and Codex + +Use a single source (`.ai/skills`) and symlink it for each tool: + +```bash +mkdir -p .cursor .codex +ln -sfn ../.ai/skills .cursor/skills +ln -sfn ../.ai/skills .codex/skills +``` diff --git a/.ai/skills/docs/SKILL.md b/.ai/skills/docs/SKILL.md new file mode 100644 index 0000000..f3feda3 --- /dev/null +++ b/.ai/skills/docs/SKILL.md @@ -0,0 +1,66 @@ +--- +name: plugin-docs-authoring +description: Rules for writing and updating plugin documentation. Use when creating new docs pages, updating existing docs (README, docs/*.md), or reviewing documentation changes. +--- + +## Prerequisites + +Read `AGENTS.md` first for terminology, architecture, and template types. +This skill only covers documentation-specific rules. + +## File Responsibilities + +Each file has a strict scope. Do not mix responsibilities between files. + +| File | Scope | Tone | +|------|-------|------| +| `README.md` | High-level overview, install, basic setup, links to docs | Short, navigational | +| `docs/configuration.md` | Plugin options only (`customTranslations`, `extend.services`, `backend_url`) | Technical, example-driven | +| `docs/templates.md` | Template types, resolve/render flow, workflows, API endpoints | Technical reference | +| `docs/blocks.md` | Block types, DB model vs final render model, block catalog | Technical reference | +| `docs/translations.md` | i18n system, interpolation, custom translations, adding locales | Technical reference | +| `docs/admin.md` | Admin panel user guide — what you can do, typical workflow | User-facing, no endpoints | +| `docs/contributing/creating-templates.md` | Step-by-step guide for contributors creating new templates | Tutorial | + +## Writing Rules + +### Structure + +1. Start every page with a one-sentence summary of what the page covers. +2. Use `##` for main sections, `###` for subsections. Do not go deeper than `####`. +3. Put "what the user can do" before technical details. +4. End pages with a `## See Also` section linking to related docs. + +### Style + +1. Write in English. +2. Use short sentences and short paragraphs. +3. Prefer bullet lists over long prose. +4. Use code blocks for every example — never inline large snippets. +5. Do not use emojis. + +### Cross-referencing + +1. Do not duplicate content between files — link to the authoritative page. +2. If you remove a page, update all references across docs and README. +3. Keep all internal links relative (`./blocks.md`, `../blocks.md`). + +## Checklist (run before finishing) + +- [ ] Does the content match the current architecture? +- [ ] Are examples correct for the template type (`system`/`db`/`external`)? +- [ ] Is `docs/admin.md` still non-technical (no raw endpoints)? +- [ ] Is `README.md` still short and navigational? +- [ ] Are there any dead links? +- [ ] Is there duplicated content between files? + +## Workflow + +When asked to update or create docs: + +1. Read this skill first. +2. Identify which files are affected (use the File Responsibilities table). +3. Read the current state of those files. +4. Make changes following the rules above. +5. Run the checklist. +6. Report: list of changed files + short summary of what and why. diff --git a/.gitignore b/.gitignore index 97d8bcf..b273edf 100755 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,9 @@ build/ # IDE .vscode/ .idea/ +.cursor/ +.codex/ +.claude/ *.swp *.swo *~ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0ab3794 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,180 @@ +# AGENTS.md + +Instructions for AI coding agents working on this repository. + +## Project Overview + +Medusa plugin for building and sending transactional notifications. +Renders notification content through workflows. +Delivery is handled by Medusa notification providers. + +- Package: `@codee-sh/medusa-plugin-notification-emails` +- Medusa: `>= 2.8.8` +- Node.js: `>= 20` +- Package manager: `yarn` (v3, see `.yarnrc.yml`) + +## Scripts + +```bash +yarn install # install dependencies +yarn build # build plugin (medusa plugin:build) +yarn dev # develop plugin (medusa plugin:develop) +yarn prepublishOnly # build before publish (medusa plugin:build) +yarn publish-local # publish locally (npx medusa plugin:publish) +yarn publish-package # publish to npm (dotenv npm publish --access public) +yarn email:dev # preview email templates (react-email dev server) +``` + +## Code Style + +- Prettier: 60-char print width, no semicolons, double quotes, trailing commas (es5) +- Config: `.prettierrc` +- TypeScript: ES2021, Node16 modules, strict null checks, decorators enabled +- Config: `tsconfig.json` + +## Branch Model + +- `main` — release-ready, every commit is tagged and deployable +- `develop` — nightly builds and upcoming release work +- Topic branches: `feat/`, `fix/`, `chore/`, `docs/` +- PRs target `develop` by default +- Hotfixes branch from `main`, merge back to `main` and `develop` + +## Versioning and Release + +- Uses [Changesets](https://github.com/changesets/changesets) for version management +- Add changeset: `yarn changeset` +- Version bump: `yarn changeset version` +- Release: merge release branch to `main`, tag is created automatically +- CI: GitHub Actions for PR labeling and release-on-merge + +## Architecture + +### High-Level Flow + +``` +Event (e.g. order.placed) + → Subscriber + → Rendering Workflow (emailServiceWorkflow / slackServiceWorkflow) + → Template resolve (system / db / external) + → Block interpolation ({{data.*}}, {{translations.*}}) + → Channel-specific render (HTML for email, Block Kit for Slack) + → Medusa Notification Module (delivery) +``` + +### Source Tree + +``` +src/ +├── admin/ # Admin panel UI (React, builder, routes, widgets) +├── api/ # Admin API routes (/api/admin/mpn/...) +├── hooks/ # React hooks for API calls +├── modules/ +│ └── mpn-builder/ # Core module: models, services, migrations +├── subscribers/ # Medusa event subscribers (order-placed, order-completed) +├── templates/ +│ ├── emails/ # Email templates (system) + React Email block components +│ ├── slack/ # Slack templates (system) + Block Kit format +│ └── shared/ # Shared template utilities, theme, abstract services +├── utils/ # Helpers: i18n, transforms, data modules, DnD +└── workflows/ + ├── mpn-builder/ # Template CRUD workflows + ├── mpn-builder-services/ # Rendering workflows (email-service, slack-service) + ├── order/ # Order data workflows + ├── region/ # Region data workflows + └── store/ # Store data workflows +``` + +### Key Modules + +| Module | Path | Purpose | +|--------|------|---------| +| `mpn-builder` | `src/modules/mpn-builder/` | Core: DB models, template services, migrations | +| Email service | `src/modules/mpn-builder/services-local/email-template-service.ts` | System email templates + block schema definitions | +| Slack service | `src/modules/mpn-builder/services-local/slack-template-service.ts` | System Slack templates + block schema definitions | +| Email workflows | `src/workflows/mpn-builder-services/email-service.ts` | `emailServiceWorkflow` — render email templates | +| Slack workflows | `src/workflows/mpn-builder-services/slack-service.ts` | `slackServiceWorkflow` — render Slack templates | + +### Template Types + +| Type | Prefix | Source | Editable in Admin | +|------|--------|--------|-------------------| +| `system` | `system_*` | Code (`src/templates/`) | No (read-only) | +| `db` | (any other ID) | Database via Admin builder | Yes | +| `external` | `external_*` | External packages via config | No | + +### Template Resolution + +- `template_id` starting with `system_` → code registry +- Other IDs → DB lookup +- `external` templates available in service registry when registered in plugin config + +### Blocks + +- DB model is channel-agnostic: `type`, `position`, `parent_id`, `metadata` +- Final render is channel-specific (email → React Email HTML, Slack → Block Kit JSON) +- Email block types: `section`, `heading`, `text`, `row`, `separator`, `group`, `repeater`, `product-item` +- Slack block types: `header`, `section`, `actions`, `divider` (Block Kit standard) + +### Interpolation + +Two-prefix system processed recursively: +- `{{data.*}}` — values from template input data +- `{{translations.*}}` — values from translation dictionaries (system/external templates) + +For `db` templates: use `{{data.*}}` and literal text in block `metadata`. +Do not rely on `{{translations.*}}`. + +### i18n + +- Translation files: JSON with `general` wrapper, auto-flattened +- Location: `src/templates//