@haus-tech/haus-workflow 6.7.0 → 6.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/dist/cli.js +4764 -1767
- package/package.json +3 -1
- package/packages/agents/issue-creator.md +61 -0
- package/packages/configs/eslint/eslint.config.mjs +90 -0
- package/packages/configs/lighthouse/lighthouserc.yml +35 -0
- package/packages/configs/prettier/.prettierignore +28 -0
- package/packages/configs/prettier/prettier.config.cjs +12 -0
- package/packages/packages.yaml +81 -0
- package/packages/skills/adr-decisions/SKILL.md +114 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
- package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
- package/packages/skills/bullmq-patterns/SKILL.md +63 -0
- package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
- package/packages/skills/bullmq-patterns/references/scope.md +30 -0
- package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
- package/packages/skills/i18next-patterns/SKILL.md +62 -0
- package/packages/skills/i18next-patterns/references/conventions.md +32 -0
- package/packages/skills/i18next-patterns/references/scope.md +29 -0
- package/packages/skills/i18next-patterns/references/workflow.md +39 -0
- package/packages/skills/issue-authoring/SKILL.md +191 -0
- package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
- package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
- package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
- package/packages/skills/laravel-nova-patterns/SKILL.md +55 -0
- package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
- package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
- package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
- package/packages/skills/nextauth-patterns/SKILL.md +48 -0
- package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
- package/packages/skills/nextauth-patterns/references/scope.md +33 -0
- package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
- package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
- package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
- package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
- package/packages/skills/qliro-patterns/SKILL.md +48 -0
- package/packages/skills/qliro-patterns/references/conventions.md +28 -0
- package/packages/skills/qliro-patterns/references/scope.md +30 -0
- package/packages/skills/qliro-patterns/references/workflow.md +46 -0
- package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
- package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
- package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
- package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
- package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
- package/packages/skills/strapi-patterns/SKILL.md +63 -0
- package/packages/skills/strapi-patterns/references/conventions.md +33 -0
- package/packages/skills/strapi-patterns/references/scope.md +29 -0
- package/packages/skills/strapi-patterns/references/workflow.md +47 -0
- package/packages/skills/vendure-app-patterns/SKILL.md +44 -0
- package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
- package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
- package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
- package/packages/skills/vendure-plugin-patterns/SKILL.md +55 -0
- package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
- package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
- package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
- package/packages/skills/whats-installed/SKILL.md +53 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
- package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
- package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
- package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
- package/packages/skills/writing-documentation/SKILL.md +161 -0
- package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
- package/packages/skills/writing-documentation/references/claude-template.md +43 -0
- package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
- package/packages/skills/writing-documentation/references/summary-template.md +81 -0
- package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
- package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
- package/packages/templates/agentic-workflow-poc.md +180 -0
- package/packages/templates/agentic-workflow-standard.md +160 -0
- package/packages/templates/decision-template.md +27 -0
- package/packages/templates/decisions-ci-gate.yml +32 -0
- package/packages/templates/lefthook-branch-guard.yml +27 -0
- package/packages/templates/lefthook-lighthouse.yml +28 -0
- package/packages/templates/lefthook-quality.yml +34 -0
- package/packages/templates/lefthook-security.yml +27 -0
- package/packages/templates/start-here.md +72 -0
- /package/{library/global → packages}/agents/request-assessor.md +0 -0
- /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
- /package/{library/global → packages}/agents/request-designer.md +0 -0
- /package/{library/global → packages}/agents/request-scorer.md +0 -0
- /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
- /package/{library/global → packages}/agents/request-specifier.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/SKILL.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/init.md +0 -0
- /package/{library/global → packages}/skills/haus-workflow/references/new.md +0 -0
- /package/{library/global → packages}/skills/request/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
- /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
- /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
- /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
- /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
- /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Install: `yarn add @haus-tech/qliro-plugin` in the Vendure project.
|
|
6
|
+
2. Register `QliroPlugin.init({...})` in `vendure-config.ts` `plugins` array.
|
|
7
|
+
3. Set env vars in `.env`: `QLIRO_MERCHANT_API_KEY`, `QLIRO_MERCHANT_ID`, `QLIRO_API_URL`, `QLIRO_TERMS_URL`.
|
|
8
|
+
4. Confirm sandbox URL is used in dev/staging; live URL only in production.
|
|
9
|
+
5. Storefront: render the Qliro Checkout snippet returned by the plugin's order-creation mutation.
|
|
10
|
+
6. Implement the push handler endpoint (often shipped by the plugin) — ensure it's reachable from Qliro's IPs.
|
|
11
|
+
7. Make the push handler idempotent: check current `qliro_status` on the order before applying state changes.
|
|
12
|
+
8. For refunds, call the plugin's refund service with `orderId`, `amount`, and `reason`.
|
|
13
|
+
9. For new markets, set currency + locale + terms URL per country.
|
|
14
|
+
10. Add a regression test that simulates a Qliro push event and asserts idempotency.
|
|
15
|
+
|
|
16
|
+
## Commands
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# Local plugin dev
|
|
20
|
+
yarn dev # Vendure backend with plugin loaded
|
|
21
|
+
|
|
22
|
+
# Inspect Vendure logs for Qliro push receipts
|
|
23
|
+
grep -i "qliro" logs/vendure-*.log
|
|
24
|
+
|
|
25
|
+
# Verify env vars
|
|
26
|
+
node -e 'console.log(process.env.QLIRO_API_URL)' # confirm sandbox vs prod URL
|
|
27
|
+
|
|
28
|
+
# Test push handler with a sample payload (replace with real Qliro payload shape)
|
|
29
|
+
curl -X POST http://localhost:3000/payments/qliro/push \
|
|
30
|
+
-H "Content-Type: application/json" \
|
|
31
|
+
-d '{"OrderId":"<id>","Status":"Completed"}'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Validation checklist
|
|
35
|
+
|
|
36
|
+
- [ ] `@haus-tech/qliro-plugin` registered in `vendure-config.ts`
|
|
37
|
+
- [ ] All Qliro env vars set per environment with correct sandbox/production separation
|
|
38
|
+
- [ ] `QLIRO_MERCHANT_API_KEY` server-only, never `NEXT_PUBLIC_*`
|
|
39
|
+
- [ ] Push handler endpoint reachable from Qliro IPs (firewall / load balancer rules verified)
|
|
40
|
+
- [ ] Push handler idempotent (re-sending the same event produces no extra side effects)
|
|
41
|
+
- [ ] Push payload signature validated when the plugin exposes a helper
|
|
42
|
+
- [ ] `qliro_order_id` persisted on Vendure `Order` for reconciliation
|
|
43
|
+
- [ ] Currency / locale / terms URL configured per market
|
|
44
|
+
- [ ] Refund flow exercised in sandbox before live deploy
|
|
45
|
+
- [ ] No customer PII (personal numbers, addresses) logged from Qliro payloads
|
|
46
|
+
- [ ] Regression test for push handler idempotency
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: react-router-v7-patterns
|
|
3
|
+
description: React Router v7 router. Use for SSR routes, loaders, actions, and framework-mode config in v7 apps.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# React Router v7 Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes routes, loaders, or actions in a React Router v7 framework-mode app
|
|
11
|
+
- task touches `app/routes.ts`, `app/root.tsx`, `app/routes/*`, or `react-router.config.ts`
|
|
12
|
+
- task introduces or modifies an SSR data-loading boundary
|
|
13
|
+
|
|
14
|
+
## Do not use when
|
|
15
|
+
|
|
16
|
+
- project is Next.js App Router (different framework; no catalog skill covers it)
|
|
17
|
+
- project is Remix v1 (different conventions; not in scope)
|
|
18
|
+
- task is React component-only behavior (use `haus.ecc-react-patterns`)
|
|
19
|
+
|
|
20
|
+
## Inspect first
|
|
21
|
+
|
|
22
|
+
- `react-router.config.ts` for SSR mode, prerender, and basename config
|
|
23
|
+
- `app/routes.ts` (or `app/routes/` filesystem) for current route tree
|
|
24
|
+
- nearest `loader` / `action` and what shape they return
|
|
25
|
+
- `app/root.tsx` for global error and meta export wiring
|
|
26
|
+
- `@react-router/node` server entry (`server.ts` / `entry.server.tsx`) for streaming and hydration
|
|
27
|
+
|
|
28
|
+
## Avoid mistakes
|
|
29
|
+
|
|
30
|
+
- mixing client-only React effects with SSR-loaded data without `clientLoader`
|
|
31
|
+
- returning non-serializable values (Map, Class instance) from `loader` / `action`
|
|
32
|
+
- bypassing route revalidation with imperative `fetch` instead of `useFetcher`/`useSubmit`
|
|
33
|
+
- leaking server-only modules (db drivers, secrets) into client bundles via shared imports
|
|
34
|
+
- assuming Remix v1 APIs — many were renamed or removed in v7
|
|
35
|
+
|
|
36
|
+
## Router
|
|
37
|
+
|
|
38
|
+
1. Load `references/conventions.md` for routing patterns, do/don't, and forbidden imports.
|
|
39
|
+
2. Load `references/scope.md` for in-scope files and stack boundaries.
|
|
40
|
+
3. Load `references/workflow.md` only for SSR diagnosis and prerender flow.
|
|
41
|
+
4. Keep loaders pure, serializable, and SSR-safe.
|
|
42
|
+
|
|
43
|
+
## References
|
|
44
|
+
|
|
45
|
+
- references/conventions.md
|
|
46
|
+
- references/scope.md
|
|
47
|
+
- references/workflow.md
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Route module files: kebab-case under `app/routes/` (e.g. `app/routes/orders.$id.tsx`)
|
|
4
|
+
- Route exports: named `loader`, `action`, `default` (component), `meta`, `links`, `ErrorBoundary`, `headers`
|
|
5
|
+
- Route configuration: `app/routes.ts` exports an array of route objects when using `routes` API
|
|
6
|
+
- Layout routes: file is `_layout.tsx` or directory contains `_layout.tsx`
|
|
7
|
+
- Resource routes (non-UI): no `default` export — only `loader` and/or `action`
|
|
8
|
+
- Server-only modules: `*.server.ts` suffix — never imported from client code
|
|
9
|
+
- Client-only modules: `*.client.ts` suffix — never imported from server code
|
|
10
|
+
- Form names: `<Form>` from `react-router`, not native `<form>` for actions
|
|
11
|
+
|
|
12
|
+
## Do / don't
|
|
13
|
+
|
|
14
|
+
DO: Return plain JSON-serializable objects from `loader` / `action` — DON'T: return Maps, Sets, Class instances, or Dates without an explicit serializer
|
|
15
|
+
DO: Use `clientLoader` for client-only refinement of SSR data — DON'T: gate the initial render on a `useEffect` fetch
|
|
16
|
+
DO: Use `useFetcher` for revalidating mutations — DON'T: call `fetch()` imperatively and try to sync route state manually
|
|
17
|
+
DO: Keep secrets in `.server.ts` modules — DON'T: import a server module from a route component (transitively pulls it into the client bundle)
|
|
18
|
+
DO: Use `<Link prefetch="intent">` for hover-prefetch — DON'T: prefetch every route (defeats the optimization)
|
|
19
|
+
DO: Throw `Response` objects (e.g. `throw new Response(null, { status: 404 })`) — DON'T: return `{ error }` and conditionally render in the component
|
|
20
|
+
DO: Set `headers` export to forward cache hints — DON'T: rely on default headers for cacheable resource routes
|
|
21
|
+
|
|
22
|
+
## Forbidden patterns
|
|
23
|
+
|
|
24
|
+
NEVER: import `@prisma/client`, DB drivers, or `node:fs` into a non-`.server.ts` module — leaks to client bundle
|
|
25
|
+
NEVER: persist mutable module-scope state across requests (in-memory caches without explicit lifecycle) — breaks SSR isolation
|
|
26
|
+
NEVER: read `process.env` directly inside route component — read in `loader` and pass through serialized data
|
|
27
|
+
NEVER: use Remix v1 imports (`@remix-run/*`) — v7 uses `react-router` and `@react-router/*` packages
|
|
28
|
+
NEVER: bypass `useNavigation()` / `useFetcher()` with `window.location` — breaks SPA navigation and pending UI
|
|
29
|
+
NEVER: throw arbitrary error objects — throw `Response` so `ErrorBoundary` receives the correct status
|
|
30
|
+
NEVER: mutate `loader` return shape across deploys without a client-side guard — hydration mismatches crash
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `react-router.config.ts` — SSR mode, prerender list, basename, future flags
|
|
6
|
+
- `app/routes.ts` — explicit route tree (when not using filesystem routing)
|
|
7
|
+
- `app/routes/**/*.tsx` — route modules (loaders, actions, components)
|
|
8
|
+
- `app/root.tsx` — document shell, global meta/links, `ErrorBoundary`
|
|
9
|
+
- `app/entry.client.tsx` / `app/entry.server.tsx` — hydration and streaming entry points
|
|
10
|
+
- `server.ts` / `app/server.ts` — `@react-router/node` server adapter wiring
|
|
11
|
+
- `*.server.ts` modules — server-only utilities (DB, secrets, file I/O)
|
|
12
|
+
- `*.client.ts` modules — client-only utilities (browser APIs, third-party widgets)
|
|
13
|
+
- `vite.config.ts` — when using `@react-router/dev/vite` plugin
|
|
14
|
+
|
|
15
|
+
## Stack boundaries
|
|
16
|
+
|
|
17
|
+
- React Router v7 framework mode: SSR by default, `clientLoader` for refinement, `<Form>` for mutations
|
|
18
|
+
- Not in scope: Next.js App Router (use `nextjs-patterns`)
|
|
19
|
+
- Not in scope: Remix v1 — APIs differ; v1 codebases should migrate or use a separate skill
|
|
20
|
+
- Component-only behavior changes inside route files → combine with `react19-patterns`
|
|
21
|
+
- Build/Vite config → combine with `vite8-patterns`
|
|
22
|
+
- Tests for routes → combine with `vitest-patterns` (unit) or `playwright-patterns` (E2E)
|
|
23
|
+
|
|
24
|
+
## Triggers
|
|
25
|
+
|
|
26
|
+
- Adding or modifying a route, layout, or resource route
|
|
27
|
+
- Changing `loader` / `action` return shape
|
|
28
|
+
- Adding `ErrorBoundary` to a route or `app/root.tsx`
|
|
29
|
+
- Switching SSR mode or adding/removing prerender entries
|
|
30
|
+
- Adding a server-only dependency that risks client-bundle leakage
|
|
31
|
+
- Migrating a route from Remix v1 conventions to v7
|
|
32
|
+
- Adjusting hydration boundary (`clientLoader`, `HydrateFallback`)
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Identify route type: UI route (`default` export + optional `loader`/`action`), layout (`_layout.tsx`), or resource (`loader`/`action` only, no `default`).
|
|
6
|
+
2. Place the file under `app/routes/` using the v7 naming convention; update `app/routes.ts` only if using explicit routes.
|
|
7
|
+
3. Confirm SSR mode in `react-router.config.ts`: `ssr: true` (default) or per-route prerender list.
|
|
8
|
+
4. For data loading, write `loader` first and confirm it returns plain JSON-serializable data; add `clientLoader` only if client refinement is needed.
|
|
9
|
+
5. For mutations, write `action` and submit via `<Form>` or `useFetcher` — never `fetch()` directly.
|
|
10
|
+
6. Keep server-only imports in `*.server.ts` modules; verify the route component does not transitively import them.
|
|
11
|
+
7. Add `ErrorBoundary` export when the route can throw `Response(404)` / `Response(500)`; otherwise rely on `app/root.tsx`.
|
|
12
|
+
8. Set `headers` export for cacheable resource routes (e.g. `Cache-Control: max-age=300`).
|
|
13
|
+
9. Run dev server (`react-router dev`) and verify both initial SSR HTML and post-hydration navigation work.
|
|
14
|
+
10. Add a regression test before fixing a routing/loader bug; confirm it fails first.
|
|
15
|
+
|
|
16
|
+
## Commands
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
yarn react-router dev # local dev with HMR + SSR
|
|
20
|
+
yarn react-router build # production build (client + server bundles)
|
|
21
|
+
yarn react-router-serve ./build/server/index.js # run prod server locally
|
|
22
|
+
yarn typecheck # TS check route modules
|
|
23
|
+
|
|
24
|
+
# route-specific tests
|
|
25
|
+
yarn vitest run app/routes/orders.$id.test.ts
|
|
26
|
+
yarn playwright test e2e/orders-flow.spec.ts
|
|
27
|
+
|
|
28
|
+
# inspect bundle for accidental server leakage
|
|
29
|
+
yarn react-router build && du -sh build/client
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Validation checklist
|
|
33
|
+
|
|
34
|
+
- [ ] `loader` / `action` return JSON-serializable shape (no Map/Set/Date without serializer)
|
|
35
|
+
- [ ] No server-only import (`*.server.ts`, DB driver, `node:fs`) reachable from route component
|
|
36
|
+
- [ ] `ErrorBoundary` present when route throws non-2xx `Response`
|
|
37
|
+
- [ ] Mutations use `<Form>` or `useFetcher`, not raw `fetch()`
|
|
38
|
+
- [ ] `clientLoader` only present when client-side refinement is actually needed
|
|
39
|
+
- [ ] `headers` export set for cacheable resource routes
|
|
40
|
+
- [ ] Dev server (`react-router dev`) renders SSR HTML correctly with JS disabled
|
|
41
|
+
- [ ] Production build (`react-router build`) succeeds and client bundle size has not regressed unexpectedly
|
|
42
|
+
- [ ] No imports from `@remix-run/*` — only `react-router` and `@react-router/*`
|
|
43
|
+
- [ ] Regression test added before bug fix landed
|
|
@@ -163,7 +163,7 @@ export const ANVANDNING = [
|
|
|
163
163
|
|
|
164
164
|
/**
|
|
165
165
|
* Verktygsurvalet per agent, en spegel av `tools:`-raden i
|
|
166
|
-
* `
|
|
166
|
+
* `packages/agents/request-*.md`. En headless `claude -p`-session nekar
|
|
167
167
|
* per default varje verktygsanrop som saknar en matchande allow-regel, och
|
|
168
168
|
* ingen kan svara på frågan: E2E:t (Task 7) förlorade 2,67 USD på att
|
|
169
169
|
* request-scorer nekades läsa sin egen `poangskala.md` och därför vägrade
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: strapi-patterns
|
|
3
|
+
description: Strapi v5 router. Use for content type schemas, controllers, services, policies, and admin plugin work.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Strapi Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes content type schemas (`src/api/<type>/content-types/<type>/schema.json`)
|
|
11
|
+
- task touches controllers, services, routes, policies, or middlewares under `src/api/`
|
|
12
|
+
- task adds or modifies a Strapi plugin (`src/plugins/<name>`)
|
|
13
|
+
- task changes admin customization (`src/admin/app.tsx`, `src/admin/extensions`)
|
|
14
|
+
|
|
15
|
+
## Do not use when
|
|
16
|
+
|
|
17
|
+
- project uses Sanity, WordPress, or another CMS (use the matching skill)
|
|
18
|
+
- task is pure frontend consumer code with no Strapi schema/contract change
|
|
19
|
+
- task is database migration unrelated to Strapi schemas (out of scope; no catalog skill covers generic database migrations)
|
|
20
|
+
|
|
21
|
+
## Inspect first
|
|
22
|
+
|
|
23
|
+
- `src/api/<type>/content-types/<type>/schema.json` — attributes, relations, draftAndPublish
|
|
24
|
+
- `src/api/<type>/controllers/<type>.ts` — default factory wrapper or custom overrides
|
|
25
|
+
- `src/api/<type>/routes/<type>.ts` — exposed endpoints
|
|
26
|
+
- `src/api/<type>/policies/` — per-route auth/permission policies
|
|
27
|
+
- `config/database.ts`, `config/admin.ts`, `config/plugins.ts` — runtime config
|
|
28
|
+
- `package.json` — `@strapi/strapi` version (v5 conventions only here)
|
|
29
|
+
|
|
30
|
+
## Avoid mistakes
|
|
31
|
+
|
|
32
|
+
- editing v4 conventions in a v5 project — controller/service signatures differ
|
|
33
|
+
- bypassing `strapi.entityService` / `strapi.documents` in v5 and using raw Knex queries
|
|
34
|
+
- modifying `schema.json` `kind` (collection vs single) on a populated content type — destroys data
|
|
35
|
+
- forgetting to update permissions in `users-permissions` plugin after adding a new route
|
|
36
|
+
- leaking `STRAPI_ADMIN_JWT_SECRET` or `JWT_SECRET` to client bundles
|
|
37
|
+
|
|
38
|
+
## Router
|
|
39
|
+
|
|
40
|
+
1. Load `references/conventions.md` for schema, controller, and service patterns.
|
|
41
|
+
2. Load `references/scope.md` for in-scope files and v4-vs-v5 stack boundaries.
|
|
42
|
+
3. Load `references/workflow.md` only for content-type lifecycle and migration flow.
|
|
43
|
+
4. Keep schemas declarative, controllers thin, business logic in services.
|
|
44
|
+
|
|
45
|
+
## References
|
|
46
|
+
|
|
47
|
+
- references/conventions.md
|
|
48
|
+
- references/scope.md
|
|
49
|
+
- references/workflow.md
|
|
50
|
+
|
|
51
|
+
## Reference Documentation
|
|
52
|
+
|
|
53
|
+
Up-to-date API docs are cached locally by haus.
|
|
54
|
+
|
|
55
|
+
To refresh (uses etag — fast if unchanged):
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
haus fetch-refs --id haus.strapi-patterns
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then read `.haus-workflow/llms-cache/docs-strapi-io-llms-txt.md` for current API reference.
|
|
62
|
+
|
|
63
|
+
Source: https://docs.strapi.io/llms.txt
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Content type API folder: `src/api/<singular-name>/` (e.g. `src/api/article/`)
|
|
4
|
+
- Schema file: `src/api/<name>/content-types/<name>/schema.json` — `kind` is `collectionType` or `singleType`
|
|
5
|
+
- Schema `singularName` / `pluralName` — lowercase, hyphenated when multi-word
|
|
6
|
+
- Controllers: `src/api/<name>/controllers/<name>.ts` — export `factories.createCoreController(...)` with optional overrides
|
|
7
|
+
- Services: `src/api/<name>/services/<name>.ts` — same `factories.createCoreService` pattern
|
|
8
|
+
- Routes: `src/api/<name>/routes/<name>.ts` — default `factories.createCoreRouter` or custom router object
|
|
9
|
+
- Policies: `src/api/<name>/policies/<policy-name>.ts` — function `(policyContext, config, { strapi }) => boolean | Promise<boolean>`
|
|
10
|
+
- Middlewares: `src/api/<name>/middlewares/<name>.ts` — Koa-style `async (ctx, next) => ...`
|
|
11
|
+
- Plugin: `src/plugins/<plugin-name>/` mirrors top-level layout (`server/` + `admin/`)
|
|
12
|
+
- Lifecycle hooks: `src/api/<name>/content-types/<name>/lifecycles.ts` — `beforeCreate`, `afterUpdate`, etc.
|
|
13
|
+
|
|
14
|
+
## Do / don't
|
|
15
|
+
|
|
16
|
+
DO: Use `strapi.documents("api::article.article")` v5 Document Service API for CRUD — DON'T: use deprecated `strapi.entityService` patterns from v4 tutorials
|
|
17
|
+
DO: Keep business logic in services; controllers only translate HTTP → service call → HTTP — DON'T: cram logic into the controller default override
|
|
18
|
+
DO: Define `populate` strategy explicitly per query — DON'T: `populate: "*"` (deep population kills perf)
|
|
19
|
+
DO: Use lifecycle hooks for cross-cutting concerns (audit logs, denormalization) — DON'T: scatter the same logic across multiple controllers
|
|
20
|
+
DO: Set `draftAndPublish: true` in schema when editors need a publish workflow — DON'T: leave it implicit
|
|
21
|
+
DO: Use `policies` for authorization, `middlewares` for request shaping — DON'T: do auth inside controllers
|
|
22
|
+
DO: Read tokens via `strapi.config.get("plugin::users-permissions.jwt.secret")` — DON'T: hard-code env var names
|
|
23
|
+
|
|
24
|
+
## Forbidden patterns
|
|
25
|
+
|
|
26
|
+
NEVER: write to the DB outside `strapi.documents` / `strapi.db` — bypasses lifecycle hooks and validation
|
|
27
|
+
NEVER: change `kind` from `collectionType` to `singleType` (or vice versa) on populated data — destroys content
|
|
28
|
+
NEVER: rename `singularName` / `pluralName` on a deployed type without a migration plan — breaks API consumers
|
|
29
|
+
NEVER: commit `.env` with `JWT_SECRET` or `API_TOKEN_SALT` — rotate before public push if leaked
|
|
30
|
+
NEVER: ship `populate: "*"` to production — recursive deep populate is the #1 perf killer
|
|
31
|
+
NEVER: skip the `users-permissions` step after adding a custom route — endpoint returns 403 silently
|
|
32
|
+
NEVER: import server-only modules (`@strapi/strapi`) inside `src/admin/` — admin runs in the browser
|
|
33
|
+
NEVER: edit `dist/` or `.cache/` — both are build artifacts; changes vanish on next build
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `src/api/**` — content types, controllers, services, routes, policies, middlewares, lifecycles
|
|
6
|
+
- `src/plugins/**` — local plugins (each with `server/` + `admin/` halves)
|
|
7
|
+
- `src/admin/app.tsx` / `src/admin/extensions/**` — admin UI customization
|
|
8
|
+
- `src/extensions/**` — overrides for core or installed plugins (e.g. `users-permissions`)
|
|
9
|
+
- `config/database.ts` / `config/server.ts` / `config/admin.ts` / `config/plugins.ts` / `config/middlewares.ts`
|
|
10
|
+
- `database/migrations/**` — Strapi-managed migrations (run on boot)
|
|
11
|
+
- `package.json` — `@strapi/strapi` version (v5 only in scope for this skill)
|
|
12
|
+
|
|
13
|
+
## Stack boundaries
|
|
14
|
+
|
|
15
|
+
- Strapi v5: Document Service API, new lifecycle signatures, plugin auth changes
|
|
16
|
+
- Not in scope: Strapi v4 — controller/service signatures differ; use a separate v4 skill
|
|
17
|
+
- Frontend consumer changes (Next.js calling Strapi REST/GraphQL) → combine with `nextjs-patterns`
|
|
18
|
+
- DB schema work beyond Strapi schemas → combine with `database-patterns`
|
|
19
|
+
- Test work → use `vitest-patterns` or `jest-patterns` depending on test runner
|
|
20
|
+
|
|
21
|
+
## Triggers
|
|
22
|
+
|
|
23
|
+
- Adding a new content type or modifying schema attributes/relations
|
|
24
|
+
- Adding a custom route, controller override, or service method
|
|
25
|
+
- Adding a policy, middleware, or lifecycle hook
|
|
26
|
+
- Changing `users-permissions` defaults for public/authenticated roles
|
|
27
|
+
- Modifying `config/plugins.ts` for installed plugin config
|
|
28
|
+
- Admin UI extension or custom field component
|
|
29
|
+
- Strapi v4 → v5 migration tasks
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. For a new content type, prefer the generator: `yarn strapi generate` (then choose `api`) — produces schema + controller + service + route skeleton.
|
|
6
|
+
2. Edit `schema.json` to add attributes; set `draftAndPublish` if editors need staging.
|
|
7
|
+
3. Implement business logic in `services/<name>.ts` via `factories.createCoreService` override; keep controllers thin.
|
|
8
|
+
4. Define explicit `populate` per service method — never `"*"`.
|
|
9
|
+
5. Add policies under `policies/` and reference them in `routes/<name>.ts` for protected endpoints.
|
|
10
|
+
6. For schema renames or removals, write a migration in `database/migrations/<timestamp>-<name>.ts` and test on a dataset copy first.
|
|
11
|
+
7. After adding routes, open the admin UI → Settings → Users & Permissions plugin → Roles → adjust public/authenticated permissions.
|
|
12
|
+
8. Restart `yarn develop` and verify the endpoint via `curl` or the admin UI's API tester.
|
|
13
|
+
9. Add a Vitest/Jest test for the service method using `strapi.factories` or a test bootstrap.
|
|
14
|
+
|
|
15
|
+
## Commands
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
yarn develop # dev server with admin UI hot reload
|
|
19
|
+
yarn start # production server (no admin rebuild)
|
|
20
|
+
yarn build # build admin UI
|
|
21
|
+
yarn strapi generate # interactive generator (api/controller/service/policy/middleware)
|
|
22
|
+
yarn strapi console # REPL with `strapi` global
|
|
23
|
+
yarn strapi ts:generate-types # regenerate `types/generated/`
|
|
24
|
+
yarn strapi configuration:dump # export config snapshot
|
|
25
|
+
yarn strapi configuration:restore # restore from snapshot
|
|
26
|
+
|
|
27
|
+
# Database
|
|
28
|
+
yarn strapi db:migrate # apply pending migrations
|
|
29
|
+
yarn strapi db:seed # run seeders
|
|
30
|
+
|
|
31
|
+
# Plugin
|
|
32
|
+
yarn strapi plugin:build # build a local plugin
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Validation checklist
|
|
36
|
+
|
|
37
|
+
- [ ] Content type schemas use kebab-case singular/plural names consistently
|
|
38
|
+
- [ ] All custom routes have explicit `policies` for non-public access
|
|
39
|
+
- [ ] `users-permissions` roles updated for new endpoints (public 403 check)
|
|
40
|
+
- [ ] No `populate: "*"` in any service or controller — explicit shapes only
|
|
41
|
+
- [ ] Business logic lives in services, not controllers
|
|
42
|
+
- [ ] Lifecycle hooks idempotent — running twice produces same result
|
|
43
|
+
- [ ] `draftAndPublish` set explicitly where the editorial workflow requires it
|
|
44
|
+
- [ ] No raw Knex / `strapi.db.connection.raw` writes that bypass lifecycle hooks
|
|
45
|
+
- [ ] TS types regenerated (`yarn strapi ts:generate-types`) after schema changes
|
|
46
|
+
- [ ] No server-only imports in `src/admin/` (would break admin browser bundle)
|
|
47
|
+
- [ ] Regression test added before bug fix landed
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vendure-app-patterns
|
|
3
|
+
description: Vendure app router. Use for app-level config, workers, jobs, and API extensions in a Vendure application.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vendure App Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task updates Vendure app config, workers, bootstrap, or plugin wiring
|
|
11
|
+
- task touches `vendure-config.*`, `src/index.ts`, `worker.ts`, app bootstrap modules
|
|
12
|
+
|
|
13
|
+
## Do not use when
|
|
14
|
+
|
|
15
|
+
- task is isolated shared plugin package work
|
|
16
|
+
- task is frontend-only storefront/admin UI work
|
|
17
|
+
|
|
18
|
+
## Router
|
|
19
|
+
|
|
20
|
+
1. Load `references/conventions.md` for naming, do/don't, and forbidden patterns.
|
|
21
|
+
2. Inspect app entry/config files before touching plugin code.
|
|
22
|
+
3. Load `references/scope.md` for app module boundaries.
|
|
23
|
+
4. Load `references/workflow.md` only for startup/worker/debug flows.
|
|
24
|
+
5. Validate both server and worker impact for changed behavior.
|
|
25
|
+
|
|
26
|
+
## References
|
|
27
|
+
|
|
28
|
+
- references/conventions.md
|
|
29
|
+
- references/scope.md
|
|
30
|
+
- references/workflow.md
|
|
31
|
+
|
|
32
|
+
## Reference Documentation
|
|
33
|
+
|
|
34
|
+
Up-to-date API docs are cached locally by haus.
|
|
35
|
+
|
|
36
|
+
To refresh (uses etag — fast if unchanged):
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
haus fetch-refs --id haus.vendure-app-patterns
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Then read `.haus-workflow/llms-cache/docs-vendure-io-llms-txt.md` for current API reference.
|
|
43
|
+
|
|
44
|
+
Source: https://docs.vendure.io/llms.txt
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- App server entry: `src/index.ts`; worker entry: `src/worker.ts`
|
|
4
|
+
- Vendure config: `src/vendure-config.ts` exporting `config` of type `VendureConfig`
|
|
5
|
+
- Migration files: TypeORM auto-generated names (`src/migrations/TIMESTAMP-Description.ts`)
|
|
6
|
+
- Plugin directory: `src/plugins/<plugin-name>/` containing `<plugin-name>.plugin.ts`
|
|
7
|
+
- Env var consumption: via `process.env.VAR_NAME` at config level only; referenced in `.env.example`
|
|
8
|
+
|
|
9
|
+
## Do / don't
|
|
10
|
+
|
|
11
|
+
DO: Order plugins in `VendureConfig.plugins` so dependencies come before dependents — DON'T: register plugins in arbitrary order (initialization order matters)
|
|
12
|
+
DO: Add every new env var to `.env.example` with a descriptive comment — DON'T: consume an env var in config without a corresponding `.env.example` entry
|
|
13
|
+
DO: Generate a new TypeORM migration for every schema change — DON'T: edit existing migration files (they may have already run in production)
|
|
14
|
+
DO: Test both server and worker bootstrap after any plugin or config change — DON'T: only verify server starts without checking worker
|
|
15
|
+
DO: Keep `src/vendure-config.ts` free of business logic — DON'T: add conditional logic or data transformations to the config file
|
|
16
|
+
DO: Import from `@vendure/core` public API only — DON'T: import from `@vendure/core/dist/...` internal paths (subject to breaking changes)
|
|
17
|
+
|
|
18
|
+
## Forbidden patterns
|
|
19
|
+
|
|
20
|
+
NEVER: Plugin registered in config without its required env var present in `.env.example` — environment setup will silently fail
|
|
21
|
+
NEVER: Schema change deployed without a corresponding migration — production DB diverges from entity definitions
|
|
22
|
+
NEVER: Destructive migration without a data migration or archival plan — data loss in production
|
|
23
|
+
NEVER: Import from `@vendure/core` internal `dist/` paths — internal API is not stable
|
|
24
|
+
NEVER: Worker-only plugin registered in the server bootstrap (or vice versa) — causes initialization errors
|
|
25
|
+
NEVER: Hard-coded database credentials in `src/vendure-config.ts` — use environment variables
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `src/vendure-config.ts` / `src/vendure-config.js` — main Vendure app configuration
|
|
6
|
+
- `src/index.ts` — server bootstrap (`bootstrapWorker`, `bootstrap`)
|
|
7
|
+
- `src/worker.ts` — worker process bootstrap
|
|
8
|
+
- `src/plugins/**` — app-level plugin wiring (local or imported)
|
|
9
|
+
- `src/migrations/**` — TypeORM migration files for the app DB
|
|
10
|
+
- `src/email/**` — email plugin templates and handlers
|
|
11
|
+
- `.env`, `.env.*` — DB connection strings, auth secrets, plugin API keys
|
|
12
|
+
- `docker-compose.yml` — local service dependencies (Postgres, Redis, Elasticsearch)
|
|
13
|
+
|
|
14
|
+
## Stack boundaries
|
|
15
|
+
|
|
16
|
+
- Vendure 3 app layer: plugin registration, DB config, job queue, asset storage
|
|
17
|
+
- Worker: background job handlers, email processing, search indexing
|
|
18
|
+
- Not in scope: isolated shared plugin package code (use vendure-plugin-patterns)
|
|
19
|
+
- Not in scope: storefront/admin UI React components
|
|
20
|
+
|
|
21
|
+
## Triggers
|
|
22
|
+
|
|
23
|
+
- Adding or removing a plugin from `VendureConfig.plugins`
|
|
24
|
+
- Changing DB connection config or entity schema requiring migration
|
|
25
|
+
- Adding or changing job queue strategy (in-memory, BullMQ, Redis)
|
|
26
|
+
- Changing asset storage strategy (local, S3, GCS)
|
|
27
|
+
- Adding or modifying email handler or template
|
|
28
|
+
- Changing worker-only vs server+worker plugin config split
|
|
29
|
+
- Adding environment variable consumed by app bootstrap
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Open `src/vendure-config.ts` — plugin order matters; place plugins that depend on others after
|
|
6
|
+
2. For new plugin: import and add to `plugins` array; provide required config options from env
|
|
7
|
+
3. For schema changes: generate TypeORM migration after entity change; never edit existing migrations
|
|
8
|
+
4. For worker-only plugins: add to `src/worker.ts` bootstrap; confirm not duplicated in `src/index.ts`
|
|
9
|
+
5. For job queue changes: verify queue strategy config in `VendureConfig.jobQueueOptions`
|
|
10
|
+
6. Start both server and worker locally; confirm startup logs show all plugins initialized
|
|
11
|
+
7. For email changes: test template rendering with Vendure email plugin dev mode
|
|
12
|
+
8. Run migration in dev before testing feature; rollback tested via TypeORM `migration:revert`
|
|
13
|
+
|
|
14
|
+
## Commands
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# Start server + worker locally
|
|
18
|
+
yarn ts-node src/index.ts
|
|
19
|
+
yarn ts-node src/worker.ts
|
|
20
|
+
|
|
21
|
+
# Alternatively with tsx
|
|
22
|
+
yarn tsx src/index.ts
|
|
23
|
+
|
|
24
|
+
# TypeORM migrations
|
|
25
|
+
yarn typeorm migration:generate -- -n MigrationName -d src/vendure-config.ts
|
|
26
|
+
yarn typeorm migration:run -d src/vendure-config.ts
|
|
27
|
+
yarn typeorm migration:revert -d src/vendure-config.ts
|
|
28
|
+
|
|
29
|
+
# Build
|
|
30
|
+
yarn build / npm run build
|
|
31
|
+
|
|
32
|
+
# Tests
|
|
33
|
+
jest --testPathPattern e2e
|
|
34
|
+
jest --testPathPattern spec
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Validation checklist
|
|
38
|
+
|
|
39
|
+
- [ ] Plugin added to `plugins` array in correct position (order-dependent plugins sorted correctly)
|
|
40
|
+
- [ ] Required env vars documented and present in `.env.example`
|
|
41
|
+
- [ ] TypeORM migration generated and reviewed — no destructive column drops without data migration
|
|
42
|
+
- [ ] Worker bootstrap includes plugins that handle background jobs
|
|
43
|
+
- [ ] Server starts without errors: check plugin `init()` and DB connection logs
|
|
44
|
+
- [ ] Worker starts without errors: check job queue connection and registered job handlers
|
|
45
|
+
- [ ] Email templates rendered correctly using dev preview mode
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vendure-plugin-patterns
|
|
3
|
+
description: Vendure 3 plugin router. Use for plugin modules, resolvers, services, entities, and migrations.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vendure Plugin Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes plugin behavior in `packages/*`, `plugins/*`, or `src/plugins/*`
|
|
11
|
+
- task touches `@VendurePlugin`, plugin resolvers, services, or plugin entities
|
|
12
|
+
|
|
13
|
+
## Do not use when
|
|
14
|
+
|
|
15
|
+
- task is storefront-only Next.js/React UI work
|
|
16
|
+
- task is generic NestJS API without Vendure plugin boundaries
|
|
17
|
+
|
|
18
|
+
## Inspect first
|
|
19
|
+
|
|
20
|
+
- `vendure-config.*`, `*.plugin.ts`, `plugin.ts`
|
|
21
|
+
- plugin `api`/`resolvers`/`services`/`entities`/`migrations` files
|
|
22
|
+
- tests near changed feature (`*.spec.ts`, `*.e2e-spec.ts`)
|
|
23
|
+
|
|
24
|
+
## Avoid mistakes
|
|
25
|
+
|
|
26
|
+
- adding resolver fields without schema or migration alignment
|
|
27
|
+
- leaking client-specific behavior into shared `@haus/vendure-*` packages
|
|
28
|
+
- skipping permission/channel checks in admin mutations
|
|
29
|
+
|
|
30
|
+
## Router
|
|
31
|
+
|
|
32
|
+
1. Load `references/conventions.md` for naming, do/don't, and forbidden patterns.
|
|
33
|
+
2. Load `references/scope.md` for plugin file map.
|
|
34
|
+
3. Load `references/workflow.md` only when implementing or debugging flow.
|
|
35
|
+
4. Keep change scoped to one plugin boundary and verify.
|
|
36
|
+
|
|
37
|
+
## References
|
|
38
|
+
|
|
39
|
+
- references/conventions.md
|
|
40
|
+
- references/scope.md
|
|
41
|
+
- references/workflow.md
|
|
42
|
+
|
|
43
|
+
## Reference Documentation
|
|
44
|
+
|
|
45
|
+
Up-to-date API docs are cached locally by haus.
|
|
46
|
+
|
|
47
|
+
To refresh (uses etag — fast if unchanged):
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
haus fetch-refs --id haus.vendure-plugin-patterns
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Then read `.haus-workflow/llms-cache/docs-vendure-io-llms-txt.md` for current API reference.
|
|
54
|
+
|
|
55
|
+
Source: https://docs.vendure.io/llms.txt
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Plugin class: `XxxPlugin` decorated with `@VendurePlugin({ ... })`
|
|
4
|
+
- Resolver: `XxxResolver` decorated with `@Resolver()`
|
|
5
|
+
- Service: `XxxService` decorated with `@Injectable()`
|
|
6
|
+
- Entity: `XxxEntity` extending `VendureEntity`, decorated with `@Entity()`
|
|
7
|
+
- Admin SDL extension: `gqlAdminExtension` constant in `xxx.graphql.ts`
|
|
8
|
+
- Shop SDL extension: `gqlShopExtension` constant in `xxx.graphql.ts`
|
|
9
|
+
- Migration: TypeORM auto-generated name including plugin prefix
|
|
10
|
+
|
|
11
|
+
## Do / don't
|
|
12
|
+
|
|
13
|
+
DO: Apply `@Allow(Permission.xxx)` to all admin API mutations — DON'T: leave admin mutations without a permission check
|
|
14
|
+
DO: Use `TransactionalConnection` for all database access in services — DON'T: inject raw TypeORM `Repository` or `EntityManager` directly
|
|
15
|
+
DO: Define SDL extensions (`gqlAdminExtension` / `gqlShopExtension`) before writing the resolver — DON'T: write resolver methods without the corresponding SDL type/field definition
|
|
16
|
+
DO: Register all plugin entities in `@VendurePlugin({ entities: [XxxEntity] })` — DON'T: define an entity without registering it (TypeORM won't create the table)
|
|
17
|
+
DO: Import only from `@vendure/core` public API — DON'T: import from `@vendure/core/dist/` internal paths
|
|
18
|
+
DO: Generate a migration for every entity schema change — DON'T: rely on `synchronize: true` in production
|
|
19
|
+
|
|
20
|
+
## Forbidden patterns
|
|
21
|
+
|
|
22
|
+
NEVER: Admin API mutation without `@Allow(Permission.xxx)` decorator — unauthenticated admin write access
|
|
23
|
+
NEVER: Shop API mutation that can return or modify another customer's data without ownership check — data exposure
|
|
24
|
+
NEVER: Plugin that directly modifies core Vendure entity definitions — breaks core compatibility and upgrades
|
|
25
|
+
NEVER: Business logic or DB query inside a resolver method — delegate to service layer
|
|
26
|
+
NEVER: Entity not listed in `@VendurePlugin({ entities: [...] })` — TypeORM does not create/migrate the table
|
|
27
|
+
NEVER: Import from `@vendure/core` internal paths — unstable, breaks on Vendure upgrades
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `src/plugins/**/plugin.ts`, `*.plugin.ts` — `@VendurePlugin` decorated module class
|
|
6
|
+
- `src/plugins/**/api/**` — GraphQL API extension files (schema extension, resolvers)
|
|
7
|
+
- `src/plugins/**/services/**` — plugin service classes injected into resolvers
|
|
8
|
+
- `src/plugins/**/entities/**` — TypeORM entity classes for plugin-specific DB tables
|
|
9
|
+
- `src/plugins/**/migrations/**` — TypeORM migrations for plugin entities
|
|
10
|
+
- `src/plugins/**/config/**` — plugin options interface and default config
|
|
11
|
+
- `src/plugins/**/*.spec.ts`, `src/plugins/**/*.e2e-spec.ts` — plugin tests
|
|
12
|
+
- `codegen.ts` (plugin-level) — GraphQL codegen config for generated types
|
|
13
|
+
|
|
14
|
+
## Stack boundaries
|
|
15
|
+
|
|
16
|
+
- Vendure 3 plugin API: `@VendurePlugin`, `PluginCommonModule`, `EventBus`, `JobQueue`
|
|
17
|
+
- API extension: `SchemaExtensionScope` (shop/admin), custom resolver fields, custom mutations
|
|
18
|
+
- Entities: extend `VendureEntity` / use `@Entity()` with plugin-scoped migrations
|
|
19
|
+
- Not in scope: Vendure app-level config changes (use vendure-app-patterns)
|
|
20
|
+
- Not in scope: storefront Next.js/React components
|
|
21
|
+
|
|
22
|
+
## Triggers
|
|
23
|
+
|
|
24
|
+
- Adding a new custom entity with DB migration
|
|
25
|
+
- Adding a new GraphQL mutation or query to shop or admin API
|
|
26
|
+
- Adding or changing plugin service business logic
|
|
27
|
+
- Adding resolver for a new field on existing Vendure type
|
|
28
|
+
- Changing plugin configuration options interface
|
|
29
|
+
- Adding EventBus subscriber to listen for Vendure core events
|
|
30
|
+
- Changing channel or permission checks in admin resolver
|