@vtex/faststore-plugin-buyer-portal 1.3.84 → 1.3.85

package/.agents/skills/create-page/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: create-page
+description: >
+  Scaffolds a new page in the faststore-plugin-buyer-portal following the
+  project's 4-layer architecture (types → loader → component → export).
+  Use when the user says "create a page", "add a new page", "cria a página",
+  "adiciona a página", or runs /create-page.
+---
+
+# Create Page
+
+Scaffold a new page in the buyer-portal plugin by adapting an existing canonical
+example. Do NOT copy blindly — read the canonical, understand each layer, then
+adapt it to the new context.
+
+## Step 1: Gather Input
+
+Determine (ask the user if not clear from context):
+
+- **Page name** — kebab-case. Example: `cost-centers` → file `src/pages/cost-centers.tsx`
+- **Feature name** — the domain folder under `src/features/`. Usually the same as the page name.
+- **Page type** — one of:
+  - `list` — listing with search and pagination (e.g. users, org-units, addresses)
+  - `detail` — single-item detail view, receives an ID in the query (e.g. user-details, address-details)
+  - `redirect` — simple redirect or entry point (e.g. home)
+
+## Step 2: Check Whether the Feature Exists
+
+Run from the project root:
+
+```bash
+ls src/features/<feature-name>/ 2>/dev/null && echo "EXISTS" || echo "NEW"
+```
+
+- **EXISTS** → go to Step 4a (create page + layout only)
+- **NEW** → go to Step 4b (scaffold full feature structure)
+
+## Step 3: Read the Canonical Example
+
+Before creating any file, read the canonical that matches the page type:
+
+| Type | Canonical page | Canonical layout |
+|------|---------------|-----------------|
+| `list` | `src/pages/users.tsx` | `src/features/users/layouts/UsersLayout/UsersLayout.tsx` |
+| `detail` | `src/pages/user-details.tsx` | `src/features/users/layouts/UserDetailsLayout/UserDetailsLayout.tsx` |
+| `redirect` | `src/pages/home.tsx` | — |
+
+Read both files completely. Pay particular attention to the layout file's import structure and the props it receives. Understand the four layers:
+
+1. **Type definitions** — `<Name>PageQuery` (URL params) and `<Name>PageData` (loader output)
+2. **Loader** — `withAuthLoader` enforcing auth + `withLoaderErrorBoundary` for error propagation
+3. **Component** — checks `hasError`; renders `ErrorTabsLayout` on error, feature layout otherwise
+4. **Export** — `withProviders(withErrorBoundary(Component, { tags: { ... } }))`
+
+> **Note for `redirect` pages:** The `redirect` canonical (`home.tsx`) does not follow layers 1–3. Its component simply calls a router method and returns `null`. Read `home.tsx` directly and adapt it as-is — do not apply the type/loader/hasError pattern to redirect pages.
+
+## Step 4a: Feature EXISTS — Create Page + Layout
+
+Create these files, adapting from the canonical (rename types, adjust query params, fix imports):
+
+**`src/pages/<page-name>.tsx`**
+Adapt the canonical page file. Replace every occurrence of the canonical feature name
+with the new feature name (types, imports, service calls, layout references). Keep the
+four-layer structure intact.
+
+**`src/features/<feature-name>/layouts/<FeatureName>Layout/<FeatureName>Layout.tsx`**
+Minimal layout component. It must:
+- Accept `data` typed as `<Name>PageData['data']` (not the full page data)
+- Return a placeholder `<div>` or a minimal FastStore UI shell — no business logic yet
+
+**`src/features/<feature-name>/layouts/<FeatureName>Layout/<feature-name>-layout.scss`**
+Empty SCSS file. Just create it so the import in the layout resolves.
+
+**`src/features/<feature-name>/layouts/index.ts`**
+If this file does not exist, create it:
+```typescript
+export { <FeatureName>Layout } from './<FeatureName>Layout/<FeatureName>Layout'
+```
+If it already exists, add the export line for the new layout.
+
+## Step 4b: Feature NEW — Scaffold Full Structure
+
+Create all files from Step 4a, plus:
+
+**`src/features/<feature-name>/types/index.ts`**
+```typescript
+// Replace with real domain types as the feature is implemented
+export type <FeatureName>Data = Record<string, unknown>
+```
+
+**`src/features/<feature-name>/services/.gitkeep`**
+Empty file. Services will be added when data fetching is implemented.
+
+**`src/features/<feature-name>/hooks/.gitkeep`**
+Empty file. Hooks will be added as needed.
+
+**`src/features/<feature-name>/layouts/index.ts`**
+If this file does not exist, create it:
+```typescript
+export { <FeatureName>Layout } from './<FeatureName>Layout/<FeatureName>Layout'
+```
+If it already exists, add the export line for the new layout.
+
+## Step 5: Register the Route
+
+**Ask the user** for the route path and URL params if not already provided.
+
+**`plugin.config.js`** — add an entry inside the `pages` object:
+
+```js
+"<page-name>": {
+  path: "/pvt/organization-account/<your-path>/[param1]/[param2]",
+  appLayout: false,
+},
+```
+
+Follow the existing conventions:
+- List pages typically use `/pvt/organization-account/<name>/[orgUnitId]` or `[orgUnitId]/[contractId]`
+- Detail pages typically add the entity ID at the end: `[orgUnitId]/[contractId]/[<entityId>]`
+- All entries must have `appLayout: false`
+
+**`src/features/shared/utils/buyerPortalRoutes.ts`** — add a typed helper to the `buyerPortalRoutes` object:
+
+```typescript
+// camelCase name, matching the pattern of existing entries
+<camelCaseName>: (params: { orgUnitId: string; /* add other params */ }) =>
+  replaceParams(`${base}/<your-path>/[orgUnitId]/[...]`, params),
+```
+
+Use an arrow function with a typed params object for parameterized routes. Use a plain string (like `b2bAgent`) only for routes with no dynamic segments.
+
+## Step 6: Validate
+
+Run:
+
+```bash
+make typecheck
+```
+
+Then verify manually:
+
+- [ ] `<Name>PageData` is exported from the page file
+- [ ] `loader` is a named export (`export const loader`)
+- [ ] The default export is `withProviders(withErrorBoundary(<Component>, { tags: { component: '<Name>Page', errorType: '<feature>_error' } }))`
+- [ ] The component checks `hasError` and renders `<ErrorTabsLayout>` on error
+- [ ] The layout receives only `data` (typed as `<Name>PageData['data']`), not the full page object
+- [ ] No broken imports (`make typecheck` must pass with zero errors)
+
+## Step 7: Commit
+
+```bash
+git add src/pages/<page-name>.tsx src/features/<feature-name>/
+git commit -m "feat: add <page-name> page"
+```

package/.agents/skills/create-page/metadata.json

@@ -0,0 +1,14 @@
+{
+  "name": "create-page",
+  "description": "Scaffolds a new page in the faststore-plugin-buyer-portal following the project's 4-layer architecture (types → loader → component → export). Adaptive: creates full feature structure for new features, or just page + layout for existing ones. Reads canonical examples from the codebase instead of using hardcoded templates.",
+  "version": "1.0.0",
+  "triggers": [
+    "/create-page",
+    "create a page",
+    "add a new page",
+    "add a page",
+    "nova página",
+    "cria a página",
+    "adiciona a página"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

package/.env.example

@@ -0,0 +1,3 @@
+# Optional — Node environment. Affects error detail visibility in dev tools.
+# Valid values: development | production | test
+NODE_ENV=development

package/.github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: Lint
+name: Lint and Test
 
 on:
   pull_request:
@@ -9,30 +9,32 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "yarn"
 
-    strategy:
-      matrix:
-        node-version: [20.x]
+      - name: Install dependencies
+        run: make install
+
+      - name: Lint
+        run: make lint
 
+  test:
+    runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: "20.x"
           cache: "yarn"
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: Run ESLint
-        run: yarn lint
+        run: make install
 
-      - name: Check for ESLint errors
-        run: |
-          if yarn lint 2>&1 | grep -q "error"; then
-            echo "ESLint found errors. Please fix them before merging."
-            exit 1
-          fi
+      - name: Test
+        run: make test

package/.specify/memory/constitution.md

@@ -0,0 +1,83 @@
+<!-- SYNC IMPACT REPORT
+Version change: (template) → 1.0.0
+Added sections: Core Principles (I–V), Technical Standards, Development Workflow, Governance
+Removed sections: none (first version)
+Templates updated:
+  ✅ .specify/memory/constitution.md — this file
+  ✅ .specify/templates/plan-template.md — no constitution-specific references to update
+  ✅ .specify/templates/spec-template.md — no constitution-specific references to update
+  ✅ .specify/templates/tasks-template.md — no constitution-specific references to update
+Deferred TODOs: none
+-->
+
+# FastStore Plugin Buyer Portal Constitution
+
+## Core Principles
+
+### I. Plugin Encapsulation (NON-NEGOTIABLE)
+All functionality MUST be delivered as a FastStore plugin. Routes MUST be registered in
+`plugin.config.js`. No logic may leak outside the plugin boundary or assume a specific
+host store structure. The plugin must be linkable via `yarn link` and must not break the
+host store's build.
+
+### II. Feature-per-Domain Structure
+Source code is organized under `src/features/<domain>/`. Each domain (org-units, users,
+roles, budgets, buying-policies, credit-cards, contracts, etc.) MUST be self-contained:
+its own components, hooks, services, types, and mocks. Cross-domain dependencies MUST go
+through `src/features/shared/`. No domain may import directly from another domain.
+
+### III. Type Safety (NON-NEGOTIABLE)
+TypeScript strict mode is always on. Code MUST compile with zero errors under
+`tsc --noEmit`. Use of `any` MUST be explicitly justified with a comment. Pre-commit hooks
+enforce lint and type-safe imports via Husky + lint-staged. All new code MUST pass
+`make lint` and `make typecheck` before merge.
+
+### IV. Test Coverage
+Unit tests (Vitest) MUST cover core domain logic — pure functions, transformations, and
+shared utilities. E2E tests (Cypress) cover critical buyer portal flows. `make test` MUST
+exit 0 in CI. New features MUST ship with at least one unit test; new API integrations
+MUST include an integration test for the happy path.
+
+### V. Spec-Driven Development
+All non-trivial features MUST start with a spec before any implementation begins. Use
+`/speckit-specify` to draft the spec, `/speckit-plan` for the implementation plan, and
+`/speckit-tasks` for task breakdown. Specs live in `specs/` and MUST be approved before
+the first commit of implementation code.
+
+## Technical Standards
+
+> Principles, feature flags flow, Makefile commands, and key files are documented in
+> [`docs/conventions.md`](../../docs/conventions.md).
+
+- **Package manager**: Yarn (enforced via `packageManager` field — do not use npm or pnpm)
+- **Node target**: ES2022, NodeNext module resolution
+- **Release toolchain**: `release-it` with Keep a Changelog format; version bumps update
+  both `package.json` and `src/features/shared/utils/constants.ts`
+- **Import order**: builtin → external → internal (enforced by eslint-plugin-import).
+  React imports MUST precede other externals.
+
+## Development Workflow
+
+1. Create a spec with `/speckit-specify` for any feature or bugfix larger than a one-liner.
+2. Get spec approved before writing implementation code.
+3. Run `make install` on a fresh clone to set up the environment.
+4. Run `make check` (lint + typecheck + test) before opening a PR.
+5. All PRs target `main`. The `golden-path/` prefix is reserved for SDLC infrastructure
+   branches.
+6. Changelog MUST be updated in the `[Unreleased]` section for every PR that ships
+   user-visible changes.
+7. Releases are cut via `yarn release` (stable) or `yarn release:beta`. Never bump the
+   version manually.
+
+## Governance
+
+This constitution supersedes all other informal practices. Amendments require:
+1. A PR modifying this file with the version bumped per semantic rules (MAJOR for
+   principle removals/redefinitions, MINOR for additions, PATCH for clarifications).
+2. Review and approval by at least one team member.
+3. A migration note if existing code violates the new principle.
+
+All PRs MUST be verified for compliance with the principles above before merge. Complexity
+that conflicts with these principles MUST be justified in the PR description.
+
+**Version**: 1.0.0 | **Ratified**: 2026-05-11 | **Last Amended**: 2026-05-11

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md — FastStore Plugin Buyer Portal
+
+This file provides guidance for AI agents working in this repository.
+
+## What this project is
+
+`@vtex/faststore-plugin-buyer-portal` is a **FastStore plugin** that delivers a B2B buyer
+organization portal (also called "Organization Account"). It is consumed by FastStore
+storefronts via `yarn link` and exposes pages for managing org units, users, roles,
+budgets, buying policies, credit cards, contracts, and more.
+
+It is **not** a standalone application — it is a plugin. There is no `yarn dev` in this
+repo. Testing UI changes requires linking it to a host store (see [docs/README.md](docs/README.md)).
+
+## Orientation
+
+```
+src/
+  features/
+    <domain>/          # self-contained per domain (components, hooks, services, types)
+    shared/            # cross-domain utilities, constants, routes
+  pages/               # one file per buyer portal route
+  apis/                # custom API routes
+docs/                  # runbook, feature flags guide, troubleshooting
+.specify/              # spec-kit config, constitution, templates
+.agents/skills/        # SDD Lite agent skills
+.claude/skills/        # spec-kit Claude skills
+```
+
+Key files:
+- `plugin.config.js` — route registration (required for new pages)
+- `src/features/shared/utils/constants.ts` — shared constants including plugin version
+- `src/features/shared/utils/buyerPortalRoutes.ts` — all route definitions
+- `.specify/memory/constitution.md` — project principles (read before making changes)
+
+## How to set up
+
+```bash
+make install    # install dependencies
+make check      # lint + typecheck + test (must pass before any PR)
+make setup-tools  # install spec-kit v0.6.0 (first time only, requires uv)
+```
+
+For UI development, see [docs/README.md](docs/README.md) — requires linking to
+`vtex-sites/b2bfaststoredev.store`.
+
+## Development rules
+
+See [docs/conventions.md](docs/conventions.md) for the canonical principles (plugin boundary, feature-per-domain, type safety, tests, spec-first), feature flags flow, Makefile reference, and key files.
+
+## How to add a new page
+
+> Use `/create-page` to scaffold steps 1–3 automatically (it will ask you for the route path). Step 4 must always be done manually.
+
+1. Create `src/pages/<page-name>.tsx`
+2. Create `src/features/<domain>/` with components, hooks, services, types
+3. Register the route in `plugin.config.js`
+4. Add the route constant to `src/features/shared/utils/buyerPortalRoutes.ts`
+
+## Feature flags
+
+See [docs/conventions.md](docs/conventions.md#feature-flags).
+
+## Skills available
+
+| Skill | Purpose |
+|-------|---------|
+| `/speckit-specify` | Draft a spec for a new feature |
+| `/speckit-plan` | Generate an implementation plan from a spec |
+| `/speckit-tasks` | Break a plan into actionable tasks |
+| `/speckit-implement` | Execute an approved spec |
+| `/speckit-constitution` | Update the project constitution |
+| `/specification` | SDD Lite — write a spec document |
+| `/implementing` | SDD Lite — implement an approved spec |
+| `/create-page` | Scaffold a new page (adaptive: full feature or page+layout only) |
+
+## CI
+
+| Workflow | Trigger | What it runs |
+|----------|---------|--------------|
+| `lint.yml` | PR + push to main | `make lint`, `make typecheck`, `make test` |
+| `ci.yml` | PR labeled `run-tests` | Cypress E2E against `b2bfaststoredev.store` |
+| `changelog.yml` | PR | Validates changelog entry |
+| `release.yaml` | Manual | Publishes to npm |

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.85] - 2026-05-13
+
+### Added
+
+- VTEX Golden Path — AI-friendly workspace setup: `.editorconfig`, `.env.example`, Vitest test framework with unit tests, `Makefile` with canonical targets (`install`, `test`, `coverage`, `lint`, `typecheck`, `check`, `clean`), `setup-tools` target for spec-kit v0.6.0, SDD Lite skills (`specification`, `implementing`, `sdlc-ai-ready-repo`, `sdlc-golden-path`)
+- Updated CI workflow to use Makefile targets and added unit test job
+
 ## [1.3.84] - 2026-05-07
 
 ### Fixed
@@ -621,7 +628,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CHANGELOG file
 - Add README file
 
-[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.84...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/1.3.85...HEAD
 [1.3.55]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.54...v1.3.55
 [1.3.54]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.53...v1.3.54
 [1.3.53]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.52...v1.3.53
@@ -704,3 +711,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.3.72]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.71...v1.3.72
 [1.3.71]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.70...v1.3.71
 [1.3.70]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.69...v1.3.70
+
+[1.3.85]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/1.3.85