@haus-tech/haus-workflow 6.7.1 → 7.0.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 +33 -0
- package/README.md +41 -85
- package/dist/cli.js +17629 -23486
- package/docs/before-you-start.md +17 -22
- package/docs/glossary.md +10 -8
- package/package.json +3 -6
- package/packages/agents/issue-creator.md +59 -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 +113 -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 +53 -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/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
- package/packages/skills/haus-workflow/references/init.md +57 -0
- package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
- package/packages/skills/i18next-patterns/SKILL.md +52 -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 +184 -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 +45 -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 +53 -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 +34 -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 +45 -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 +55 -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 +153 -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 +170 -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/catalog/decisions-triggers.json +0 -26
- package/library/catalog/haus-lock.schema.json +0 -4
- package/library/catalog/manifest.json +0 -5941
- package/library/catalog/validation-rules.json +0 -169
- package/library/global/settings-fragments/hooks.json +0 -53
- package/library/global/skills/haus-workflow/references/init.md +0 -88
- package/scripts/postinstall.mjs +0 -62
- /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/references/clone.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,33 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `auth.ts` / `auth.config.ts` — Auth.js v5 entry and split config
|
|
6
|
+
- `app/api/auth/[...nextauth]/route.ts` — v4 catch-all route handler
|
|
7
|
+
- `app/api/auth/[...nextauth]/options.ts` — v4 options module
|
|
8
|
+
- `middleware.ts` — route protection wiring at root
|
|
9
|
+
- `types/next-auth.d.ts` — module augmentation for typed `session.user`
|
|
10
|
+
- `app/auth/**` — custom sign-in / sign-out / error pages
|
|
11
|
+
- `lib/auth.ts` — re-export helpers and server-side session readers
|
|
12
|
+
- `.env` / `.env.example` — `AUTH_SECRET` / `NEXTAUTH_SECRET`, `AUTH_URL`, provider env vars
|
|
13
|
+
- adapter config when present: `lib/db.ts` for Prisma/Drizzle adapter
|
|
14
|
+
|
|
15
|
+
## Stack boundaries
|
|
16
|
+
|
|
17
|
+
- NextAuth v4 vs Auth.js v5: APIs differ — verify version via `package.json` before applying patterns
|
|
18
|
+
- Edge runtime: middleware must use `auth.config.ts` (no adapter, no Node-only imports)
|
|
19
|
+
- Adapter persistence → combine with `prisma-patterns` (curated opt-in, gated to Prisma projects) or DB skill
|
|
20
|
+
- OAuth provider setup → provider docs are authoritative for scopes/claims
|
|
21
|
+
- Laravel/PHP auth → use `auth-oidc-azure-bankid-patterns`
|
|
22
|
+
- Server-to-server API tokens (no session) → out of scope
|
|
23
|
+
|
|
24
|
+
## Triggers
|
|
25
|
+
|
|
26
|
+
- Adding a new OAuth provider or credentials provider
|
|
27
|
+
- Switching session strategy (`jwt` ↔ `database`)
|
|
28
|
+
- Adding or modifying a callback (`jwt`, `session`, `signIn`, `redirect`)
|
|
29
|
+
- Wiring or modifying `middleware.ts` route protection
|
|
30
|
+
- Adding an adapter (`@auth/prisma-adapter`, `@auth/drizzle-adapter`)
|
|
31
|
+
- Module augmentation to add custom fields to `session.user`
|
|
32
|
+
- Migrating from NextAuth v4 to Auth.js v5
|
|
33
|
+
- Splitting config for edge compatibility
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Confirm version: check `package.json` for `next-auth` (v4) vs `next-auth@beta` / Auth.js v5. APIs differ.
|
|
6
|
+
2. For v5: ensure `auth.ts` exports `{ handlers, auth, signIn, signOut }` from `NextAuth(authConfig)`.
|
|
7
|
+
3. If `middleware.ts` needs auth, split: `auth.config.ts` (edge-safe — no adapter, no Node modules) + `auth.ts` (full).
|
|
8
|
+
4. Add providers to the `providers` array; pull client IDs/secrets from env (`process.env.GOOGLE_CLIENT_ID` etc.).
|
|
9
|
+
5. For credentials provider, hash passwords with `bcrypt` or `argon2` in `authorize`; never accept plaintext.
|
|
10
|
+
6. Add adapter only when using `database` session strategy or persisting users; remove if using pure `jwt`.
|
|
11
|
+
7. Augment types in `types/next-auth.d.ts` to expose custom fields on `session.user`.
|
|
12
|
+
8. In `redirect` callback, validate `url` is same-origin or in an allowlist before returning.
|
|
13
|
+
9. Set `AUTH_SECRET` in every environment (`openssl rand -base64 32`).
|
|
14
|
+
10. Test the flow end-to-end: sign in, refresh page, sign out — confirm session reads in server components via `await auth()`.
|
|
15
|
+
|
|
16
|
+
## Commands
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
yarn dev # Next dev server (auth flow available at /api/auth/*)
|
|
20
|
+
yarn build && yarn start # production build + run (sanity check edge bundle)
|
|
21
|
+
|
|
22
|
+
# Auth.js v5 env setup
|
|
23
|
+
openssl rand -base64 32 # generate AUTH_SECRET
|
|
24
|
+
yarn next telemetry status # confirm telemetry preference (unrelated but commonly asked)
|
|
25
|
+
|
|
26
|
+
# Provider checks
|
|
27
|
+
curl -I "$AUTH_URL/api/auth/providers" # list configured providers
|
|
28
|
+
curl -I "$AUTH_URL/api/auth/session" # current session (unauthenticated returns {})
|
|
29
|
+
|
|
30
|
+
# Common diagnostic: edge bundling
|
|
31
|
+
yarn build 2>&1 | grep -i "module not found" # catches Node-only imports leaking into middleware
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Validation checklist
|
|
35
|
+
|
|
36
|
+
- [ ] Version pinned and patterns match v4 vs v5 conventions
|
|
37
|
+
- [ ] `AUTH_SECRET` (v5) or `NEXTAUTH_SECRET` (v4) set in all environments
|
|
38
|
+
- [ ] Middleware imports `auth.config.ts`, not `auth.ts` (no adapter in edge bundle)
|
|
39
|
+
- [ ] Credentials provider hashes passwords with `bcrypt` / `argon2`, never plaintext
|
|
40
|
+
- [ ] `redirect` callback validates same-origin or allowlist before returning
|
|
41
|
+
- [ ] Session strategy matches adapter use (`database` ↔ adapter present; `jwt` ↔ no adapter persistence)
|
|
42
|
+
- [ ] `session.user` custom fields typed via `types/next-auth.d.ts` module augmentation
|
|
43
|
+
- [ ] No `console.log` of session or JWT payload
|
|
44
|
+
- [ ] OAuth secrets only in env vars (no `NEXT_PUBLIC_*` leakage)
|
|
45
|
+
- [ ] End-to-end flow tested: sign in → server-side `auth()` returns session → sign out clears
|
|
46
|
+
- [ ] Regression test added before fixing an auth bug (e.g. integration test that hits `/api/auth/session`)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nx-tag-conventions
|
|
3
|
+
description: Haus-specific Nx project tag, module-boundary, and generator-placement conventions. Use alongside the official nx-workspace/nx-generate skills, not instead of them.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Nx Tag Conventions
|
|
7
|
+
|
|
8
|
+
This supplements `haus.nx-nx-workspace` and `haus.nx-nx-generate` (official, generic Nx
|
|
9
|
+
guidance) with conventions specific to Haus-managed workspaces that those skills don't cover.
|
|
10
|
+
|
|
11
|
+
## Use when
|
|
12
|
+
|
|
13
|
+
- naming or applying `tags` on a new or existing Nx project
|
|
14
|
+
- adding a custom generator or executor
|
|
15
|
+
- enforcing or reviewing `enforce-module-boundaries` lint rules
|
|
16
|
+
|
|
17
|
+
## Conventions
|
|
18
|
+
|
|
19
|
+
- Library tags: `scope:<feature>` for domain ownership, `type:ui` / `type:data` / `type:util` /
|
|
20
|
+
`type:feature` for layer — apply both dimensions to every project.
|
|
21
|
+
- Generated executors live at `tools/executors/<executor-name>/executor.ts`.
|
|
22
|
+
- Generated generators live at `tools/generators/<generator-name>/generator.ts`.
|
|
23
|
+
- Enforce tag constraints via `nx.json`'s `enforce-module-boundaries` rule — never commit a
|
|
24
|
+
change that removes an existing boundary constraint without an explicit decision to widen it.
|
|
25
|
+
- Prefer local workspace generators over external plugin generators when both could satisfy a
|
|
26
|
+
request (matches `haus.nx-nx-generate`'s guidance, called out here because it's easy to miss
|
|
27
|
+
once local generators exist in `tools/generators/`).
|
|
28
|
+
|
|
29
|
+
## Do not use when
|
|
30
|
+
|
|
31
|
+
- exploring workspace structure or running generators — use the official
|
|
32
|
+
`haus.nx-nx-workspace` / `haus.nx-nx-generate` skills for that.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: package-manager-yarn4-pnpm89
|
|
3
|
+
description: Package manager router for Yarn 4 and pnpm 8.9 workspaces, constraints, and lockfile behavior.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Package Manager Yarn4 Pnpm89
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes dependency graph, workspace linking, or lockfile behavior
|
|
11
|
+
- task touches `.yarnrc.yml`, `pnpm-workspace.yaml`, root package manager scripts
|
|
12
|
+
|
|
13
|
+
## Do not use when
|
|
14
|
+
|
|
15
|
+
- task is feature implementation with no dependency/workspace impact
|
|
16
|
+
- repo package manager differs from yarn4/pnpm89
|
|
17
|
+
|
|
18
|
+
## Inspect first
|
|
19
|
+
|
|
20
|
+
- root `package.json`, lockfile, and manager-specific config files
|
|
21
|
+
- workspace definitions and nohoist/public-hoist rules if present
|
|
22
|
+
- scripts invoking manager-specific commands
|
|
23
|
+
|
|
24
|
+
## Avoid mistakes
|
|
25
|
+
|
|
26
|
+
- mixing npm install paths in yarn/pnpm managed repos
|
|
27
|
+
- manual lockfile edits that break deterministic installs
|
|
28
|
+
- dependency version drift across workspace packages
|
|
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 manager-specific targets.
|
|
34
|
+
3. Load `references/workflow.md` only for install/lock/debug flow.
|
|
35
|
+
4. Keep lockfile and workspace resolution deterministic.
|
|
36
|
+
|
|
37
|
+
## References
|
|
38
|
+
|
|
39
|
+
- references/conventions.md
|
|
40
|
+
- references/scope.md
|
|
41
|
+
- references/workflow.md
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Workspace package names: follow root naming convention (e.g. `@scope/package-name`)
|
|
4
|
+
- Patch files: `patches/<package-name>@<version>.patch` in root `patches/` directory
|
|
5
|
+
- `.yarnrc.yml` (Yarn 4): `nodeLinker`, `yarnPath`, and `plugins` entries
|
|
6
|
+
- `.npmrc` (pnpm): `shamefully-hoist`, `strict-peer-dependencies`, workspace catalog entries
|
|
7
|
+
- `packageManager` field in root `package.json`: pinned with exact version via corepack (e.g. `"yarn@4.5.0"`)
|
|
8
|
+
|
|
9
|
+
## Do / don't
|
|
10
|
+
|
|
11
|
+
DO: Use `workspace:*` (or `workspace:^`) protocol for all internal package dependencies — DON'T: use a fixed version number for workspace deps (breaks in-repo resolution)
|
|
12
|
+
DO: Pin the package manager version in `package.json#packageManager` and use `corepack` to enforce it — DON'T: rely on globally installed package manager versions that differ per developer
|
|
13
|
+
DO: Commit the lockfile (`yarn.lock` / `pnpm-lock.yaml`) on every dependency change — DON'T: add lockfiles to `.gitignore`
|
|
14
|
+
DO: Keep shared dependency versions aligned from a single source of truth — DON'T: duplicate version strings across multiple `package.json` files. (Note: `pnpm catalog:` entries automate this but require pnpm v9+ — the pnpm 8.9 line this skill pins predates them, so align versions manually or upgrade pnpm first.)
|
|
15
|
+
DO: Run install (`yarn install` / `pnpm install`) after any `package.json` change to keep lockfile in sync — DON'T: edit `package.json` without refreshing the lockfile
|
|
16
|
+
DO: Use `--frozen-lockfile` (pnpm) or `--immutable` (Yarn 4) in all CI install steps — DON'T: allow CI to silently update the lockfile during install
|
|
17
|
+
|
|
18
|
+
## Forbidden patterns
|
|
19
|
+
|
|
20
|
+
NEVER: `npm install` in a Yarn or pnpm workspace — overwrites lockfile with wrong format
|
|
21
|
+
NEVER: Manual edits to `yarn.lock` or `pnpm-lock.yaml` — breaks integrity checksums
|
|
22
|
+
NEVER: Change `nodeLinker` in `.yarnrc.yml` without a full `yarn install` and CI validation — breaks module resolution silently
|
|
23
|
+
NEVER: `--frozen-lockfile` / `--immutable` skipped in CI — allows lockfile drift between branches
|
|
24
|
+
NEVER: Publish a workspace package while still referencing `workspace:*` in its `dependencies` — published package becomes uninstallable by consumers
|
|
25
|
+
NEVER: `--ignore-scripts` in install without documented reason — may silently skip required postinstall build steps
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `package.json` (root and workspace packages) — dependencies, scripts, workspaces field
|
|
6
|
+
- `yarn.lock` / `pnpm-lock.yaml` — deterministic lockfiles (do not edit manually)
|
|
7
|
+
- `.yarnrc.yml` — Yarn 4 configuration (nodeLinker, plugins, npmRegistryServer, pnpMode)
|
|
8
|
+
- `pnpm-workspace.yaml` — pnpm workspace glob definitions
|
|
9
|
+
- `.npmrc` — registry auth, scoped registry config (pnpm reads this)
|
|
10
|
+
- `.pnp.cjs`, `.pnp.loader.mjs` — Yarn PnP manifests (generated, do not edit)
|
|
11
|
+
- `.yarn/` — Yarn 4 cache, releases, plugins, sdks
|
|
12
|
+
- `patches/` — `patch-package` or Yarn patch: entries
|
|
13
|
+
|
|
14
|
+
## Stack boundaries
|
|
15
|
+
|
|
16
|
+
- Yarn 4: PnP mode vs `node-modules` linker; Zero-Installs caching; Corepack version pinning
|
|
17
|
+
- pnpm 8/9: `shamefully-hoist`, `public-hoist-pattern`, workspace protocol (`workspace:*`)
|
|
18
|
+
- Workspace management: adding/removing packages, cross-package dependencies
|
|
19
|
+
- Not in scope: package contents/feature implementation
|
|
20
|
+
- Not in scope: npm-managed projects (no `yarn.lock` or `pnpm-lock.yaml`)
|
|
21
|
+
|
|
22
|
+
## Triggers
|
|
23
|
+
|
|
24
|
+
- Adding, removing, or upgrading a dependency
|
|
25
|
+
- Adding a new workspace package
|
|
26
|
+
- Changing `nodeLinker` in `.yarnrc.yml` (PnP ↔ node-modules)
|
|
27
|
+
- Adding or removing a `patch:` entry in `package.json`
|
|
28
|
+
- Changing `pnpm-workspace.yaml` glob patterns
|
|
29
|
+
- Pinning or upgrading package manager version via Corepack
|
|
30
|
+
- Adding scoped registry or auth token configuration
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Confirm which manager the repo uses: check for `yarn.lock` (Yarn) or `pnpm-lock.yaml` (pnpm)
|
|
6
|
+
2. Check Corepack version pin in `package.json` `packageManager` field — use matching version
|
|
7
|
+
3. For dependency additions: use the correct workspace flag to target the right package
|
|
8
|
+
|
|
9
|
+
### Yarn 4
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
yarn add <pkg> # add to root
|
|
13
|
+
yarn workspace <ws-name> add <pkg> # add to specific workspace
|
|
14
|
+
yarn workspaces foreach run build # run build in all workspaces
|
|
15
|
+
yarn plugin import @yarnpkg/plugin-sdks # one-time: install sdks plugin
|
|
16
|
+
yarn sdks vscode # update editor SDK (requires plugin above)
|
|
17
|
+
yarn dedupe # deduplicate lockfile entries
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### pnpm 8/9
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add <pkg> # add to root
|
|
24
|
+
pnpm add <pkg> --filter <ws-name> # add to specific workspace
|
|
25
|
+
pnpm install # install after lockfile change
|
|
26
|
+
pnpm run --filter <ws-name> build # run target in one workspace
|
|
27
|
+
pnpm -r run build # run build in all workspaces
|
|
28
|
+
pnpm dedupe # deduplicate lockfile
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Validation checklist
|
|
32
|
+
|
|
33
|
+
- [ ] Never run `npm install` in a Yarn/pnpm managed repo — it corrupts lockfile
|
|
34
|
+
- [ ] `yarn.lock` / `pnpm-lock.yaml` committed after every dependency change
|
|
35
|
+
- [ ] Cross-workspace dependencies use `workspace:*` protocol — not `file:` paths
|
|
36
|
+
- [ ] No manually edited lockfile entries
|
|
37
|
+
- [ ] `.yarnrc.yml` `nodeLinker` unchanged unless intentional migration
|
|
38
|
+
- [ ] Corepack `packageManager` field matches CI toolchain version
|
|
39
|
+
- [ ] PnP mode: all tools work with PnP loader (check `.yarn/sdks` for editor support)
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: qliro-patterns
|
|
3
|
+
description: Qliro Checkout router. Use for `@haus-tech/qliro-plugin` integration in Vendure storefronts.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Qliro Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task wires Qliro Checkout via `@haus-tech/qliro-plugin` in a Vendure backend or Next.js storefront
|
|
11
|
+
- task touches Qliro order callbacks, refund flow, or merchant API config
|
|
12
|
+
- task adds or modifies Qliro webhook handlers (order status updates)
|
|
13
|
+
|
|
14
|
+
## Do not use when
|
|
15
|
+
|
|
16
|
+
- payment provider is Stripe / Klarna / Adyen (use the matching skill)
|
|
17
|
+
- task is generic e-commerce checkout UX with no Qliro API contact
|
|
18
|
+
- project does not use `@haus-tech/qliro-plugin`
|
|
19
|
+
|
|
20
|
+
## Inspect first
|
|
21
|
+
|
|
22
|
+
- `@haus-tech/qliro-plugin` install + config in Vendure's `vendure-config.ts`
|
|
23
|
+
- env vars: `QLIRO_MERCHANT_API_KEY`, `QLIRO_MERCHANT_ID`, `QLIRO_API_URL` (production vs sandbox URL differs)
|
|
24
|
+
- storefront integration: where Qliro Checkout HTML / iframe snippet is rendered
|
|
25
|
+
- order callback / push notification endpoint (Qliro pushes order status changes)
|
|
26
|
+
- refund flow: server-side endpoint hitting Qliro API with proper auth
|
|
27
|
+
|
|
28
|
+
## Avoid mistakes
|
|
29
|
+
|
|
30
|
+
- mixing sandbox + production env vars — order corruption
|
|
31
|
+
- exposing `QLIRO_MERCHANT_API_KEY` to client — full merchant compromise
|
|
32
|
+
- treating order push as authoritative without idempotency — Qliro retries on 5xx
|
|
33
|
+
- relying on user-side checkout completion redirect — push notifications are the source of truth
|
|
34
|
+
- skipping signature validation on Qliro push payloads
|
|
35
|
+
- hard-coding currency / locale — Nordic markets have per-country requirements
|
|
36
|
+
|
|
37
|
+
## Router
|
|
38
|
+
|
|
39
|
+
1. Load `references/conventions.md` for plugin config, push, and refund patterns.
|
|
40
|
+
2. Load `references/scope.md` for in-scope files and Vendure-vs-storefront boundaries.
|
|
41
|
+
3. Load `references/workflow.md` only for order push diagnosis and refund flow.
|
|
42
|
+
4. Keep merchant key server-only; push handlers idempotent; respect sandbox/production split.
|
|
43
|
+
|
|
44
|
+
## References
|
|
45
|
+
|
|
46
|
+
- references/conventions.md
|
|
47
|
+
- references/scope.md
|
|
48
|
+
- references/workflow.md
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Plugin config: registered in `vendure-config.ts` `plugins` array as `QliroPlugin.init({...})`
|
|
4
|
+
- Env vars: `QLIRO_MERCHANT_API_KEY` (server-only), `QLIRO_MERCHANT_ID`, `QLIRO_API_URL`, `QLIRO_TERMS_URL`
|
|
5
|
+
- Order metadata: `qliro_order_id` and `qliro_status` columns on `Order` entity
|
|
6
|
+
- Push handler route: `/payments/qliro/push` (POST) — accepts Qliro callbacks
|
|
7
|
+
- Refund flow: `qliroRefund(orderId, amount, reason)` service method, never inlined in controller
|
|
8
|
+
|
|
9
|
+
## Do / don't
|
|
10
|
+
|
|
11
|
+
DO: Use the official `@haus-tech/qliro-plugin` — DON'T: implement Qliro Checkout from scratch in Vendure code
|
|
12
|
+
DO: Store `qliro_order_id` on the Vendure `Order` for reconciliation — DON'T: rely on user session alone
|
|
13
|
+
DO: Make the push handler idempotent (check current `qliro_status` before mutating) — DON'T: assume each push is a new event
|
|
14
|
+
DO: Use sandbox `QLIRO_API_URL` (`https://pago.qit.nu` etc.) in dev/staging — DON'T: hit live API from non-production
|
|
15
|
+
DO: Validate push payload signature where the plugin exposes a verification helper — DON'T: trust raw body
|
|
16
|
+
DO: Surface Qliro's localized error copy back to checkout UI — DON'T: replace with English fallbacks (Nordic UX expects native language)
|
|
17
|
+
DO: Pin Qliro plugin version explicitly — DON'T: track `latest`
|
|
18
|
+
|
|
19
|
+
## Forbidden patterns
|
|
20
|
+
|
|
21
|
+
NEVER: ship `QLIRO_MERCHANT_API_KEY` to client bundle
|
|
22
|
+
NEVER: trust browser-side checkout completion as the order-finalize trigger — Qliro push is authoritative
|
|
23
|
+
NEVER: mutate order state on push without idempotency guard — Qliro retries cause double-completion
|
|
24
|
+
NEVER: log Qliro payloads containing customer personal numbers / addresses — Nordic PII regulations
|
|
25
|
+
NEVER: hard-code currency to SEK — Qliro supports multiple Nordic currencies; read from order
|
|
26
|
+
NEVER: skip the sandbox/production env split — order ledger corruption
|
|
27
|
+
NEVER: deploy without a working push endpoint (404 / 500 means Qliro retries forever)
|
|
28
|
+
NEVER: roll your own Qliro API client when the plugin exposes one — duplicates auth + retry logic
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `vendure-config.ts` — `QliroPlugin.init({...})` registration
|
|
6
|
+
- `src/plugins/qliro/**` — local overrides or extensions of the Qliro plugin behavior
|
|
7
|
+
- Storefront Qliro integration: page/component that renders Qliro Checkout snippet
|
|
8
|
+
- Push handler route exposed by the plugin (typically `/payments/qliro/push`)
|
|
9
|
+
- Refund / cancel service code using `@haus-tech/qliro-plugin` exports
|
|
10
|
+
- `.env` / `.env.example` — Qliro env vars
|
|
11
|
+
- `package.json` — `@haus-tech/qliro-plugin` version pin
|
|
12
|
+
|
|
13
|
+
## Stack boundaries
|
|
14
|
+
|
|
15
|
+
- Requires Vendure backend (`@vendure/core`) and `@haus-tech/qliro-plugin`
|
|
16
|
+
- Storefront can be Next.js, Remix, React Router v7 — same Qliro snippet pattern
|
|
17
|
+
- Not in scope: non-Vendure Qliro integrations (custom Qliro API client)
|
|
18
|
+
- Not in scope: Stripe / Klarna / Adyen (separate skills)
|
|
19
|
+
- Database side → combine with `database-patterns`
|
|
20
|
+
- Vendure plugin development beyond Qliro → `vendure-plugin-patterns`
|
|
21
|
+
|
|
22
|
+
## Triggers
|
|
23
|
+
|
|
24
|
+
- Adding Qliro to a Vendure project
|
|
25
|
+
- Modifying Qliro plugin config (`init({...})` options)
|
|
26
|
+
- Adding refund / cancel flow
|
|
27
|
+
- Switching sandbox ↔ production
|
|
28
|
+
- Adjusting push handler logic (status transitions, side effects)
|
|
29
|
+
- Upgrading `@haus-tech/qliro-plugin` major version
|
|
30
|
+
- Adding new Qliro market (currency, locale, terms URL)
|
|
@@ -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,53 @@
|
|
|
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
|
+
For the current API reference, fetch https://docs.strapi.io/llms.txt (an llms.txt index of the official docs) and follow the links it lists for the topic at hand.
|