@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,29 @@
|
|
|
1
|
+
# Recording approval
|
|
2
|
+
|
|
3
|
+
Loaded on demand from `SKILL.md`: the evidence a `Status` line edit requires, the exact
|
|
4
|
+
approved-status format, and the read-modify-write recipe that keeps the edit from wiping
|
|
5
|
+
the technical section.
|
|
6
|
+
|
|
7
|
+
The header edit is a _record of_ approval, never an assertion of it. NEVER edit
|
|
8
|
+
the `Status` line without named evidence that a human approved: an approving
|
|
9
|
+
comment on the issue, an approval label a human applied, or a human instruction
|
|
10
|
+
that names this issue number. Record the evidence in the line itself:
|
|
11
|
+
`> **Status:** Approved by @<human> <YYYY-MM-DD> (<comment link / label / instruction>).`
|
|
12
|
+
|
|
13
|
+
**If no such evidence exists, do NOT edit the header and do NOT start work.**
|
|
14
|
+
Being handed "work on #157" counts only when the human saying it is the approver;
|
|
15
|
+
an agent that approves its own proposal deletes the gate this skill exists for.
|
|
16
|
+
|
|
17
|
+
`gh issue edit` has no partial-body edit — `--body` / `--body-file` replace the
|
|
18
|
+
whole body, so a naive edit wipes the technical section. Read, modify, write:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
f=$(mktemp)
|
|
22
|
+
gh issue view <n> --json body --jq .body > "$f" # edit ONLY the Status line in "$f"
|
|
23
|
+
gh issue edit <n> --body-file "$f" --remove-label needs-triage
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Dropping `needs-triage` is a label write: check `viewerCanLabel` first (capability
|
|
27
|
+
query in `native-metadata.md`). If `false`, run the edit without `--remove-label` —
|
|
28
|
+
a 403 on the label takes the body edit down with it — and report the issue as
|
|
29
|
+
untriaged.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: laravel-nova-patterns
|
|
3
|
+
description: Laravel Nova router. Use for admin resources, actions, fields, filters, and policies.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Laravel Nova Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes Nova admin resources, fields, actions, cards, or filters
|
|
11
|
+
- task touches `app/Nova/*`, resource policies, or Nova tool integration
|
|
12
|
+
|
|
13
|
+
## Do not use when
|
|
14
|
+
|
|
15
|
+
- task is customer-facing API/domain change without admin UI impact
|
|
16
|
+
- task belongs to non-Laravel admin stacks
|
|
17
|
+
|
|
18
|
+
## Inspect first
|
|
19
|
+
|
|
20
|
+
- `app/Nova/*` resource classes and custom fields/actions
|
|
21
|
+
- linked Eloquent model + policy files
|
|
22
|
+
- validation rules and lens/filter query logic
|
|
23
|
+
|
|
24
|
+
## Avoid mistakes
|
|
25
|
+
|
|
26
|
+
- exposing sensitive fields in index/detail views
|
|
27
|
+
- writing expensive unbounded queries in filters/lenses
|
|
28
|
+
- mismatching resource field rules vs model validation/policies
|
|
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 Nova file targets.
|
|
34
|
+
3. Load `references/workflow.md` only for resource lifecycle flow.
|
|
35
|
+
4. Verify admin authorization and data visibility before handoff.
|
|
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.laravel-nova-patterns
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Then read `.haus-workflow/llms-cache/nova-laravel-com-docs-llms-txt.md` for current API reference.
|
|
54
|
+
|
|
55
|
+
Source: https://nova.laravel.com/docs/llms.txt
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Nova resource files: `app/Nova/Order.php` — filename matches Eloquent model exactly
|
|
4
|
+
- Nova actions: `app/Nova/Actions/ExportOrders.php` — verb-noun, PascalCase
|
|
5
|
+
- Nova filters: `app/Nova/Filters/OrderStatusFilter.php` — noun + `Filter` suffix
|
|
6
|
+
- Nova lenses: `app/Nova/Lenses/PendingOrdersLens.php` — adjective/noun + `Lens` suffix
|
|
7
|
+
- Nova metrics: `app/Nova/Metrics/NewOrdersCount.php` — noun + metric type suffix (`Count`, `Trend`, `Partition`)
|
|
8
|
+
- Policy files: `app/Policies/OrderPolicy.php` — model name + `Policy`
|
|
9
|
+
|
|
10
|
+
## Do / don't
|
|
11
|
+
|
|
12
|
+
DO: Use `canSee()` / `canRun()` callbacks to hide or restrict fields/actions by role — DON'T: expose sensitive fields (e.g. `password`, `remember_token`, `secret`) in Nova resources
|
|
13
|
+
DO: Add database indexes for all columns used in filter or lens queries — DON'T: create filter queries with unindexed `LIKE '%x%'` (full table scan)
|
|
14
|
+
DO: Register a policy for every Nova resource in `AuthServiceProvider` — DON'T: leave a Nova resource without an associated policy
|
|
15
|
+
DO: Limit rows returned in lens queries (`->limit()`) — DON'T: write unbounded `orderBy` in lens without a `LIMIT`
|
|
16
|
+
DO: Use `canRun($request, $model)` on destructive or batch actions — DON'T: allow destructive Nova actions without authorization check
|
|
17
|
+
DO: Test Nova resource with a seeded user that has the expected role — DON'T: test Nova only as admin (misses `canSee` bugs)
|
|
18
|
+
DO: Use `BelongsTo` / `HasMany` Nova field types for relations — DON'T: query relations manually inside field callbacks
|
|
19
|
+
|
|
20
|
+
## Forbidden patterns
|
|
21
|
+
|
|
22
|
+
NEVER: Nova action with no `canRun` or `authorizedToRun` check — any authenticated user can execute
|
|
23
|
+
NEVER: Filter query with `LIKE '%x%'` on unindexed column — degrades to full table scan at scale
|
|
24
|
+
NEVER: Nova resource without a registered policy — allows unauthorized view/edit/delete
|
|
25
|
+
NEVER: Return `password` or raw token fields in any Nova resource — credential exposure
|
|
26
|
+
NEVER: Nova lens with no row limit on unbounded table — OOM or timeout risk
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Scope
|
|
2
|
+
|
|
3
|
+
## In-scope files and dirs
|
|
4
|
+
|
|
5
|
+
- `app/Nova/**/*.php` — Nova resource classes, custom fields, actions, lenses, cards
|
|
6
|
+
- `app/Policies/**/*.php` — model policies used by Nova authorization
|
|
7
|
+
- `app/Nova/Actions/**` — queued and inline Nova actions
|
|
8
|
+
- `app/Nova/Filters/**` — Nova filter classes
|
|
9
|
+
- `app/Nova/Lenses/**` — Nova lens classes
|
|
10
|
+
- `app/Nova/Fields/**` — custom field implementations
|
|
11
|
+
- `routes/nova.php` — custom Nova routes (if present)
|
|
12
|
+
- `config/nova.php` — Nova configuration (auth guard, path, middleware)
|
|
13
|
+
- `resources/views/nova/**` — custom Nova Blade views
|
|
14
|
+
|
|
15
|
+
## Stack boundaries
|
|
16
|
+
|
|
17
|
+
- Nova resources: fields, rules, relatable, searchable, filterable config
|
|
18
|
+
- Nova actions: `handle()` method, action fields, queued execution
|
|
19
|
+
- Nova authorization: `authorizedToCreate`, `authorizedToUpdate`, policy gates
|
|
20
|
+
- Not in scope: customer-facing API routes without admin panel impact
|
|
21
|
+
- Not in scope: Eloquent model logic not surfaced via Nova resource
|
|
22
|
+
|
|
23
|
+
## Triggers
|
|
24
|
+
|
|
25
|
+
- Adding or modifying `fields()`, `actions()`, `filters()`, `lenses()` on a resource
|
|
26
|
+
- Changing field visibility rules (`showOnIndex`, `showOnDetail`, `hideWhenUpdating`)
|
|
27
|
+
- Adding or changing Nova action with side effects (email, job dispatch, model update)
|
|
28
|
+
- Modifying policy method (`viewAny`, `create`, `update`, `delete`) used by Nova
|
|
29
|
+
- Adding searchable/relatable configuration on BelongsTo/MorphTo fields
|
|
30
|
+
- Changing Nova config (middleware, auth guard, pagination)
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
## Implementation steps
|
|
4
|
+
|
|
5
|
+
1. Locate or create Nova resource in `app/Nova/` — name matches Eloquent model
|
|
6
|
+
2. Define `fields()`: use typed field classes (`Text`, `Number`, `BelongsTo`, `HasMany`)
|
|
7
|
+
3. Set field visibility explicitly — default is shown everywhere; narrow with `showOnIndex`/`showOnDetail`
|
|
8
|
+
4. Add `rules()` and `creationRules()`/`updateRules()` for validation
|
|
9
|
+
5. For actions: implement `handle(ActionFields $fields, Collection $models)` — add `->canRun()` policy check
|
|
10
|
+
6. For filters: implement `apply(Request $request, Builder $query, $value)` — avoid unbounded scans
|
|
11
|
+
7. Verify policy: confirm `app/Policies/*Policy.php` has correct gates and is registered in `AuthServiceProvider`
|
|
12
|
+
8. Test in Nova UI: create, update, delete, run action — confirm authorization blocks unauthorized users
|
|
13
|
+
9. Run PHPUnit feature tests covering the changed resource behavior
|
|
14
|
+
|
|
15
|
+
## Commands
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
php artisan nova:resource ModelName # generate Nova resource
|
|
19
|
+
php artisan nova:action ActionName # generate action class
|
|
20
|
+
php artisan nova:filter FilterName # generate filter class
|
|
21
|
+
php artisan nova:lens LensName # generate lens class
|
|
22
|
+
|
|
23
|
+
php artisan test --filter=Nova # run Nova-related tests
|
|
24
|
+
php artisan route:list | grep nova # inspect registered Nova routes
|
|
25
|
+
php artisan policy:make ModelPolicy # generate policy
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Validation checklist
|
|
29
|
+
|
|
30
|
+
- [ ] Sensitive fields (password, token, PII) excluded from index view
|
|
31
|
+
- [ ] All filter/lens queries use indexed columns — check with EXPLAIN
|
|
32
|
+
- [ ] Action `canRun()` gates checked; unauthorized users cannot execute
|
|
33
|
+
- [ ] BelongsTo / relatable fields have `searchable()` if model count is large
|
|
34
|
+
- [ ] Policy registered in `AuthServiceProvider::$policies`
|
|
35
|
+
- [ ] Nova resource `$model` property matches correct Eloquent class
|
|
36
|
+
- [ ] Queued actions use correct queue connection from config
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nextauth-patterns
|
|
3
|
+
description: NextAuth.js / Auth.js router. Use for provider setup, session strategy, callbacks, JWT, and route protection in Next.js.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# NextAuth Patterns
|
|
7
|
+
|
|
8
|
+
## Use when
|
|
9
|
+
|
|
10
|
+
- task changes `next-auth` / `@auth/core` provider config (`auth.ts`, `auth.config.ts`, `app/api/auth/[...nextauth]/route.ts`)
|
|
11
|
+
- task touches session strategy (`jwt` vs `database`), callbacks, or events
|
|
12
|
+
- task adds or modifies route protection via `auth()` / `middleware.ts`
|
|
13
|
+
- task wires a new OAuth provider (Google, GitHub, Azure AD) or credentials provider
|
|
14
|
+
|
|
15
|
+
## Do not use when
|
|
16
|
+
|
|
17
|
+
- project is Laravel / PHP auth (use `auth-oidc-azure-bankid-patterns`)
|
|
18
|
+
- task is server-to-server API token auth with no session lifecycle
|
|
19
|
+
- task is OIDC outside Next.js (use `auth-oidc-azure-bankid-patterns`)
|
|
20
|
+
|
|
21
|
+
## Inspect first
|
|
22
|
+
|
|
23
|
+
- `auth.ts` (Auth.js v5) or `app/api/auth/[...nextauth]/route.ts` (v4) — provider list, adapter, callbacks
|
|
24
|
+
- `middleware.ts` — protected paths and `auth()` invocation
|
|
25
|
+
- `app/api/auth/[...nextauth]/options.ts` or `auth.config.ts` — config split for edge runtime compatibility
|
|
26
|
+
- env vars: `NEXTAUTH_SECRET` (v4) / `AUTH_SECRET` (v5), `NEXTAUTH_URL` / `AUTH_URL`, provider client IDs/secrets
|
|
27
|
+
- adapter config when persisting sessions/users to DB (`@auth/prisma-adapter`, `@auth/drizzle-adapter`)
|
|
28
|
+
|
|
29
|
+
## Avoid mistakes
|
|
30
|
+
|
|
31
|
+
- mixing v4 and v5 APIs — imports, callback shapes, and route handlers differ
|
|
32
|
+
- importing the full `auth.ts` (with adapter) inside `middleware.ts` — Node-only modules break edge runtime
|
|
33
|
+
- forgetting `AUTH_SECRET` in production — sessions fail silently in dev, hard-fail in prod
|
|
34
|
+
- exposing OAuth client secrets in `NEXT_PUBLIC_*` env vars
|
|
35
|
+
- using `jwt` session strategy with an adapter — adapter writes aren't read back
|
|
36
|
+
|
|
37
|
+
## Router
|
|
38
|
+
|
|
39
|
+
1. Load `references/conventions.md` for provider, session, and callback patterns.
|
|
40
|
+
2. Load `references/scope.md` for in-scope files and v4-vs-v5 boundaries.
|
|
41
|
+
3. Load `references/workflow.md` only for auth flow tracing and edge-runtime diagnosis.
|
|
42
|
+
4. Keep secrets server-only; split config for edge compatibility.
|
|
43
|
+
|
|
44
|
+
## References
|
|
45
|
+
|
|
46
|
+
- references/conventions.md
|
|
47
|
+
- references/scope.md
|
|
48
|
+
- references/workflow.md
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
## Naming conventions
|
|
2
|
+
|
|
3
|
+
- Auth.js v5: `auth.ts` at project root exports `{ handlers, auth, signIn, signOut }` from `NextAuth(...)`
|
|
4
|
+
- Auth.js v5 split config: `auth.config.ts` (edge-safe, no adapter) + `auth.ts` (full, imports config + adapter)
|
|
5
|
+
- NextAuth v4: `app/api/auth/[...nextauth]/route.ts` exports `GET` / `POST` from `NextAuth(authOptions)`
|
|
6
|
+
- v4 options module: `app/api/auth/[...nextauth]/options.ts` exports `authOptions`
|
|
7
|
+
- Providers array: keep ordered consistently across environments (UI shows them in order)
|
|
8
|
+
- Callbacks: `jwt`, `session`, `signIn`, `redirect` — typed with `JWT`, `Session`, `User` from `next-auth`
|
|
9
|
+
- Adapter: import from `@auth/<orm>-adapter` (v5) or `@next-auth/<orm>-adapter` (v4)
|
|
10
|
+
- Custom pages: `pages: { signIn: "/auth/sign-in", error: "/auth/error" }` — file paths under `app/auth/`
|
|
11
|
+
- Middleware: `middleware.ts` at root exports default `auth` (v5) or `withAuth` (v4)
|
|
12
|
+
|
|
13
|
+
## Do / don't
|
|
14
|
+
|
|
15
|
+
DO: Use `auth()` (v5) to read session in server components — DON'T: call `getServerSession()` in v5 code
|
|
16
|
+
DO: Split config when middleware needs auth — `auth.config.ts` is edge-safe, `auth.ts` is full — DON'T: import `auth.ts` from `middleware.ts`
|
|
17
|
+
DO: Pin `AUTH_SECRET` in all environments via env var — DON'T: rely on dev fallback in production
|
|
18
|
+
DO: Use `database` session strategy when you need server-side session invalidation — DON'T: combine `jwt` strategy with an adapter (adapter writes ignored)
|
|
19
|
+
DO: Type `session.user` with module augmentation in `types/next-auth.d.ts` — DON'T: cast `as any` in callbacks
|
|
20
|
+
DO: Validate redirect targets in `redirect` callback — DON'T: trust `url` parameter blindly (open redirect)
|
|
21
|
+
DO: Use `signIn` callback to return `false` or a URL string to deny — DON'T: throw inside `signIn` (becomes a generic error)
|
|
22
|
+
DO: Set `trustHost: true` in v5 only when behind a proxy with `AUTH_URL` set — DON'T: enable blindly
|
|
23
|
+
|
|
24
|
+
## Forbidden patterns
|
|
25
|
+
|
|
26
|
+
NEVER: import `auth.ts` (with Prisma/Drizzle adapter) inside `middleware.ts` — edge runtime fails to bundle Node-only modules
|
|
27
|
+
NEVER: expose `AUTH_SECRET`, OAuth client secrets, or DB credentials via `NEXT_PUBLIC_*`
|
|
28
|
+
NEVER: store password hashes via the credentials provider without `bcrypt`/`argon2` — plaintext or weak hashing is a critical bug
|
|
29
|
+
NEVER: log full session or JWT payloads — leaks user PII and tokens
|
|
30
|
+
NEVER: return raw `User` from `authorize` callback (credentials provider) — sanitize to only fields needed in session
|
|
31
|
+
NEVER: skip the `redirect` callback validation — open redirect via `?callbackUrl=` parameter
|
|
32
|
+
NEVER: hard-code provider client IDs/secrets in `auth.config.ts` — env vars only
|
|
33
|
+
NEVER: silently downgrade `database` strategy to `jwt` — session invalidation expectations break
|
|
@@ -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)
|