✨ feat: enhance medialib image handling and add asset URL resolution
- Implemented `resolveApiAssetUrl` function to normalize asset URLs based on API base. - Updated `MedialibImage` component to utilize new asset URL resolution and added support for alt text and class properties. - Enhanced image loading behavior with improved width measurement and focal point handling. - Added placeholder image handling and improved accessibility with alt text. - Introduced new test script for auditing broken links in skill documentation. - Expanded seeded test content to include medialib entries and updated related tests for pagebuilder previews. - Improved global setup and teardown logging for clarity on seeded content management.
This commit is contained in:
@@ -0,0 +1,222 @@
|
||||
---
|
||||
name: troubleshooting-and-debugging
|
||||
description: Diagnose common tibi website-project failures. Covers config loading, auth and permission mistakes, hook/goja errors, upload and CORS issues, and a practical debugging order so later agents do not thrash across unrelated layers.
|
||||
---
|
||||
|
||||
# troubleshooting-and-debugging
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- a tibi project is failing in a way that is not obviously tied to one file
|
||||
- hooks, config, permissions, uploads, or routing behave unexpectedly
|
||||
- a project worked before and now fails after configuration or integration changes
|
||||
- you need a practical debugging order instead of ad-hoc guessing
|
||||
|
||||
## Goal
|
||||
|
||||
Help later agents debug the stack systematically.
|
||||
|
||||
The main value of this skill is not “more tips”. It is the order of operations: isolate the failing layer first, then inspect the right tool surface for that layer.
|
||||
|
||||
## Source of truth
|
||||
|
||||
Use these sources when debugging:
|
||||
|
||||
- `tibi-server/docs/15-troubleshooting.md`
|
||||
- `tibi-server/docs/06-hooks.md`
|
||||
- `tibi-server/docs/05-authentication.md`
|
||||
- `tibi-server/docs/17-field-level-permissions.md`
|
||||
- `tibi-server/internal/models/eval_context.go` when hook API exposure is in doubt
|
||||
- `tibi-server/internal/hook/context_*.go` when helper registration is in doubt
|
||||
- `.agents/skills/tibi-hook-authoring/SKILL.md`
|
||||
- `.agents/skills/security-hardening-and-token-strategy/SKILL.md`
|
||||
- `.agents/skills/tibi-ssr-caching/SKILL.md`
|
||||
|
||||
## Debugging order
|
||||
|
||||
Start in this order unless a more specific failure anchor already exists:
|
||||
|
||||
1. reachability and environment
|
||||
2. auth/token/permission layer
|
||||
3. config loading and YAML shape
|
||||
4. hook/goja behavior
|
||||
5. uploads/media pathing
|
||||
6. SSR/routing/publication behavior
|
||||
7. CORS or browser-integration issues
|
||||
|
||||
This order prevents chasing frontend symptoms when the real issue is project registration, token scope, or a broken config reload.
|
||||
|
||||
## Layer 1 — Reachability and environment
|
||||
|
||||
Check first:
|
||||
|
||||
- website URL responds
|
||||
- admin URL responds
|
||||
- API responds with JSON where expected
|
||||
- Docker services are actually up
|
||||
|
||||
If `/api/...` returns HTML, do not debug application logic yet. Fix the environment/proxy path first.
|
||||
|
||||
## Layer 2 — Auth and permission mistakes
|
||||
|
||||
Common patterns:
|
||||
|
||||
- `401 Unauthorized` → missing/invalid JWT or wrong auth surface
|
||||
- `403 Forbidden` → collection/action permissions wrong, user not assigned correctly, or token permission mismatch
|
||||
- static `Token` works for one surface but not another → wrong header type for the requested operation
|
||||
|
||||
Check:
|
||||
|
||||
- `X-Auth-Token` vs `Token` vs `X-Admin-Token`
|
||||
- collection/action permissions
|
||||
- project/user assignment
|
||||
- field-level readonly/hidden behavior if writes fail unexpectedly
|
||||
|
||||
Important current note:
|
||||
|
||||
- current upstream troubleshooting and auth docs still describe MD5-managed passwords; do not debug login failures by assuming the active username/password flow has already moved to bcrypt
|
||||
|
||||
## Layer 3 — Config and reload problems
|
||||
|
||||
Common patterns:
|
||||
|
||||
- project not loading after config change
|
||||
- env vars not resolving
|
||||
- CORS behaving differently than expected
|
||||
|
||||
Check:
|
||||
|
||||
- YAML syntax
|
||||
- whether the correct config file is being loaded
|
||||
- whether project reload actually ran
|
||||
- whether env placeholders use `${VAR_NAME}` format
|
||||
|
||||
When the problem smells like “the server ignores my config change”, verify reload and active config path before editing more files.
|
||||
|
||||
## Layer 4 — Hook and goja errors
|
||||
|
||||
Common patterns:
|
||||
|
||||
- `require is not defined`
|
||||
- `async`/`await` assumptions in hooks
|
||||
- wrong context object assumptions
|
||||
- timeouts or infinite loops
|
||||
|
||||
Remember:
|
||||
|
||||
- hooks run in goja, not Node.js
|
||||
- no `require()` or npm runtime
|
||||
- no normal async/await model
|
||||
- hook behavior often depends on the exact lifecycle step
|
||||
- tibi hook surfaces are accessed through `context`, including request and registered packages such as `context.request()`, `context.db.find()`, `context.http.fetch()`, `context.smtp.sendMail()`, `context.debug.dump()`, or `context.exec.command()`
|
||||
|
||||
Use the hook skill for step-specific quirks such as `context.data` timing or `context.filter` behavior.
|
||||
|
||||
## Layer 5 — Upload and media failures
|
||||
|
||||
Common patterns:
|
||||
|
||||
- files not being saved
|
||||
- media URLs render incorrectly
|
||||
- image filters return 404
|
||||
|
||||
Check:
|
||||
|
||||
- collection `uploadPath`
|
||||
- file field type
|
||||
- base64/data-URI or multipart expectations
|
||||
- filter names in collection config
|
||||
- whether frontend/admin preview code expects `_lookup` or raw IDs
|
||||
|
||||
## Layer 6 — SSR, routing, and publication failures
|
||||
|
||||
Common patterns:
|
||||
|
||||
- route works in browser but not in SSR
|
||||
- SSR returns empty page or wrong status
|
||||
- unpublished or inactive entries disappear unexpectedly
|
||||
|
||||
Check:
|
||||
|
||||
- route model and language-prefix handling
|
||||
- `ssrValidatePath()`
|
||||
- `publishedFilter`
|
||||
- lookup usage for page-critical relations
|
||||
- cache invalidation after mutations
|
||||
|
||||
Do not debug SSR only through browser navigation. Use the SSR endpoint directly when the failure is SSR-shaped.
|
||||
|
||||
## Layer 7 — Browser integration and CORS
|
||||
|
||||
Common patterns:
|
||||
|
||||
- browser form fails while direct API call works
|
||||
- preflight fails
|
||||
- credentials or auth headers do not cross origins correctly
|
||||
|
||||
Check:
|
||||
|
||||
- which layer owns CORS config
|
||||
- `allowOrigins`, `allowMethods`, `allowHeaders`, `allowCredentials`
|
||||
- whether the real deployment even needs cross-origin calls
|
||||
|
||||
## Useful debugging tools
|
||||
|
||||
### Hook-side debug helpers
|
||||
|
||||
```js
|
||||
context.debug.dump(context.data, "payload")
|
||||
context.debug.dump(context.request().header("Authorization"), "auth-header")
|
||||
```
|
||||
|
||||
### Request inspection
|
||||
|
||||
```js
|
||||
const req = context.request()
|
||||
context.debug.dump({
|
||||
method: req.method,
|
||||
path: req.path,
|
||||
url: req.url,
|
||||
host: req.host,
|
||||
clientIp: req.clientIp,
|
||||
})
|
||||
```
|
||||
|
||||
### Database inspection from hooks
|
||||
|
||||
```js
|
||||
const rows = context.db.find("content", { limit: 5 })
|
||||
context.debug.dump(rows, "sample-content")
|
||||
```
|
||||
|
||||
### Direct endpoint debugging
|
||||
|
||||
Prefer targeted `curl` probes for:
|
||||
|
||||
- API JSON responses
|
||||
- SSR endpoint behavior
|
||||
- auth header behavior
|
||||
- audit endpoint behavior when relevant
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- jumping between frontend, hooks, and config without isolating the failing layer
|
||||
- assuming a browser symptom proves a frontend bug
|
||||
- trying to fix permissions only in the UI
|
||||
- debugging SSR without the SSR endpoint
|
||||
- relying on outdated assumptions from old stack behavior
|
||||
|
||||
## What an LLM should inspect first
|
||||
|
||||
When asked to debug a tibi project with unclear failure ownership, inspect in this order:
|
||||
|
||||
1. current failing command or URL
|
||||
2. environment reachability
|
||||
3. auth/permission boundary
|
||||
4. config/reload state
|
||||
5. hook/runtime layer
|
||||
6. SSR/publication layer if the failure is page-related
|
||||
|
||||
This keeps debugging local and falsifiable instead of turning into broad repo wandering.
|
||||
Reference in New Issue
Block a user