From 2e27c8dc8f676ead7c7d7be98380a961e1a8ebca Mon Sep 17 00:00:00 2001 From: Fernando Frizzatti Date: Fri, 1 May 2026 17:50:39 -0300 Subject: [PATCH] docs: add AGENTS.md cross-linking the canonical migration policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit apps-start lives downstream of deco-start, where the canonical migration tooling policy and plan live. AGENTS.md gives contributors a discovery path from this repo — covering the three-layer architecture, D1–D5 decisions as they constrain commerce code, the 3+ sites bar for promotion (D4), and the standard PR / CI / commit discipline. Closes Wave 12-G from MIGRATION_TOOLING_PLAN.md. Co-authored-by: Cursor --- AGENTS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3cd2dfb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +# AGENTS.md — `@decocms/apps` + +Guidance for AI assistants and human contributors working inside the +`@decocms/apps` (apps-start) repository. + +## What this repo is + +`@decocms/apps` is the commerce layer for Deco storefronts on +**TanStack Start + React 19 + Cloudflare Workers**. It ships VTEX and +Shopify loaders / actions / hooks plus shared commerce types +(schema.org Product, Offer, BreadcrumbList, etc.). + +It depends on `@decocms/start` (the framework layer). It is consumed +by every Deco storefront published on the new stack. + +## Common Commands + +```bash +npm run typecheck # tsc --noEmit +npm run check # typecheck + unused export detection +npm run lint # biome check . — must be 0 errors before push +npx vitest run # full test suite +``` + +There is no dev server: this is a library. Storefronts run their own +`vite dev` and consume the published package. + +## Three-layer architecture + +| Layer | Repo | Responsibility | +|-------|------|---------------| +| **Framework** | [`decocms/deco-start`](https://github.com/decocms/deco-start) | CMS bridge, admin protocol, worker entry, edge caching, rendering | +| **Commerce** | this repo | VTEX/Shopify loaders, actions, hooks, types, SDK helpers | +| **Site** | per-customer storefront repos | UI components, hooks, routes, styles, contexts | + +Commerce code lives here, not in `deco-start`. Framework code lives +in `deco-start`, not here. Site-specific code lives in the customer +repo, not in either. + +## Migration tooling policy + +The canonical policy that governs all migration tooling work — across +`@decocms/start`, `@decocms/apps`, and customer storefront repos — +lives in **`decocms/deco-start`**: + +- **Rule (always-applied):** [`.cursor/rules/migration-tooling-policy.mdc`](https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc) +- **Plan (living tracker):** [`MIGRATION_TOOLING_PLAN.md`](https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md) + +Key decisions ratified there (D1–D5) that constrain work in +`apps-start` too: + +| ID | Decision | Implication for this repo | +|----|----------|---------------------------| +| **D1** | Force convergence — no fork support layer | Site customisations live in `src/apps/local/`, or open a PR to canonical here. We do not ship per-fork override hooks. | +| **D2** | Rewrite HTMX on migration — no HTMX runtime | Don't add HTMX-aware loaders or hooks here. Migration codemods + skills handle the rewrite. | +| **D3** | Generated stubs throw at runtime | Anything stub-shaped that would otherwise return `null` / `{}` / identity-cast must throw with a clear message. Real impls stay real. | +| **D4** | Site-local apps by default, promote at 3+ sites | A pattern only earns a place in `vtex/` / `shopify/` / `commerce/` once it has shown up on three customer sites. Until then it lives site-local. | +| **D5** | Failed migrations: `rm -rf` and re-run | We don't carry a `--restart` mode in scripts. | + +## When to add to apps-start + +Per **D4**, a piece of code earns a place in `vtex/`, `shopify/`, or +`commerce/` when it is needed by **3+ customer sites**. Below that +threshold it lives site-local (typically in `src/apps/local/`). + +Concrete pattern (mirrors how `createUseCart` / `createUseUser` / +`createUseWishlist` got promoted from baggagio + casaevideo): build it +twice in two different sites first, validate the abstraction, then +promote. + +## Process + +- **PR-only.** No direct pushes to `main`. Self-merge after CI is + green is fine for routine work; loop in a human for behavioural + shifts in the public surface (new exported types, signature + changes, breaking removes). +- **Conventional commits** (`feat`, `fix`, `chore`, `docs`, + `refactor`, `test`, `perf`). Imperative, lowercase, no trailing + period. +- **CI must be green before merge.** Lint is enforced (\`npm run + lint\` → 0 errors). TypeScript must pass. Tests must pass. +- **Plan updates ship with the work.** Whenever a Wave step lands, + update `MIGRATION_TOOLING_PLAN.md` (in deco-start) in the same PR + body so the tracker stays accurate.