123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# Repository Instructions
|
|
|
|
## SHD design-system maintenance
|
|
|
|
Treat `docs/DESIGN_SYSTEM.md` and the shared tokens and patterns in `src/app.css`
|
|
as maintained parts of the product.
|
|
|
|
Whenever a change makes a significant visual or interaction-design decision,
|
|
update the design system in the same change. This includes:
|
|
|
|
- introducing or changing colors, typography, spacing, borders, elevation, or motion;
|
|
- creating a new reusable layout, navigation, table, editor, form, card, status, or feedback pattern;
|
|
- materially changing dashboard density, hierarchy, responsive behavior, or accessibility behavior;
|
|
- changing the semantic meaning of an existing visual state;
|
|
- establishing a pattern that future pages or components should follow.
|
|
|
|
For significant design changes:
|
|
|
|
1. Reuse or extend the CSS custom properties in `src/app.css`; do not scatter
|
|
near-duplicate hard-coded values throughout new components.
|
|
2. Update `docs/DESIGN_SYSTEM.md` with the new or revised rule, token, pattern,
|
|
usage guidance, and responsive or accessibility considerations.
|
|
3. Refactor repeated UI into a reusable component when that makes the pattern
|
|
clearer and reduces divergence.
|
|
4. Preserve the SHD design principles: tactical but restrained, data-first,
|
|
square and engineered, orange reserved for action and emphasis, and explicit
|
|
textual state indicators.
|
|
5. Verify hover, pressed, focus-visible, pending, disabled, error, success, and
|
|
reduced-motion behavior where applicable.
|
|
6. Run `npm run check` and `npm run build` before completing the change.
|
|
|
|
Minor alignment fixes, isolated bug fixes, and corrections that do not introduce
|
|
or revise a reusable design decision do not require a documentation update.
|
|
|
|
If uncertain whether a visual change is significant, update the design system.
|
|
|
|
## ISAC editor lifecycle
|
|
|
|
All ISAC data-management editors must follow the same successful-save behavior:
|
|
|
|
1. Saving an edit to an existing record closes the editor and returns the user
|
|
to the registry.
|
|
2. Saving a newly added record keeps the editor open with a fresh blank record
|
|
so consecutive data entry remains fast.
|
|
3. Validation errors keep the editor open and preserve the entered values.
|
|
4. Server actions must return the add/edit mode and a unique result token;
|
|
client-side reactive handling must consume each token only once to avoid
|
|
repeated state updates.
|
|
|
|
Apply this convention whenever an ISAC editor is added or materially changed.
|
|
|
|
## ISAC audit logging
|
|
|
|
Every successful server-side mutation performed through ISAC must create an
|
|
append-only audit event. Audit coverage is a required part of implementing or
|
|
changing any ISAC module, action, endpoint, bulk operation, moderation control,
|
|
identity operation, access-policy change, archive action, or destructive action.
|
|
|
|
Follow these rules:
|
|
|
|
1. Use the shared audit utilities in `src/lib/server/audit.ts`; do not invent
|
|
module-specific audit formats or write directly to `audit_log` in new code.
|
|
2. Record the authenticated operator ID, stable category, specific action,
|
|
target entity ID, timestamp, and useful before/after snapshots.
|
|
3. Categories describe durable operational domains such as `game_data`,
|
|
`user_access`, `user_moderation`, `identity`, and `role_management`.
|
|
Actions describe the exact event in namespaced past tense, such as
|
|
`weapon.updated`, `attribute.archived`, or `moderation.blocked`.
|
|
4. Capture relationship changes as well as the primary row. When an action
|
|
replaces permission sets, compatible brands, talents, effects, tiers, or
|
|
other linked records, include the meaningful previous and resulting sets.
|
|
5. Create audit records only after validation succeeds and the requested
|
|
mutation has completed. Rejected, unauthorized, or validation-failed
|
|
requests must not appear as successful mutation events.
|
|
6. Never include password hashes, session tokens, magic-link tokens, OAuth
|
|
state, passkey public-key bytes, SMTP credentials, environment secrets, or
|
|
other authentication secrets in audit snapshots. Minimize personal data to
|
|
what is necessary for security, support, and accountability.
|
|
7. Audit visibility is controlled by `audit.view`. The read-only `Auditor` role
|
|
grants `isac.access` and `audit.view`; it must not implicitly grant mutation,
|
|
moderation, identity-management, or user-access permissions.
|
|
8. New audit categories and actions must remain searchable in the Audit History
|
|
registry. Update its grouped filters when a new durable operational domain is
|
|
introduced.
|
|
9. Preserve audit history during normal record archival and soft deletion.
|
|
Never add an ISAC action that edits or deletes audit records without an
|
|
explicit retention policy, legal review, and separately audited authority.
|
|
10. Tests and handoff verification for an ISAC mutation must include confirming
|
|
that its audit event contains the correct actor, category, action, target,
|
|
and change evidence.
|
|
11. Audit reversion is a separately authorized compensating action, never a
|
|
history rewrite. Require `audit.revert`, an explicit confirmation
|
|
interaction, current-state comparison against the original after-snapshot,
|
|
relationship validation, and a new `audit.reverted` event referencing the
|
|
original event. Block stale, already-reverted, unsupported, destructive
|
|
identity, and incomplete-snapshot events rather than guessing.
|
|
|
|
## Database preservation
|
|
|
|
Development data is valuable and may be entered by non-technical contributors.
|
|
Treat embedded database files as persistent user data, not disposable build
|
|
artifacts.
|
|
|
|
Before deleting, replacing, recreating, renaming, or destructively migrating a
|
|
database—and before any major schema change—create a timestamped JSON backup
|
|
with `npm run db:backup`.
|
|
|
|
Database work must follow these rules:
|
|
|
|
1. Confirm which environment and exact database path are in scope.
|
|
2. Stop processes that hold the embedded database lock before backup or restore.
|
|
3. Create and verify a JSON backup before destructive work.
|
|
4. Never overwrite or delete the only available backup.
|
|
5. Keep backups out of Git; they can contain user records and password hashes.
|
|
6. Prefer additive, repeatable schema migrations over database recreation.
|
|
7. After a restore, run the schema migration and verify record counts and
|
|
critical entities before resuming data entry.
|
|
8. Report the backup path when completing database-destructive work.
|
|
|
|
Use `npm run db:restore -- <backup-file>` only with an empty, migrated target
|
|
database. The restore script intentionally refuses to merge into a populated
|
|
database.
|