30 KiB
30 KiB
Boilerplate-Inventur: Foundation & Querschnitt
Faktische Inventur der Querschnitts-Pakete im Boilerplate-Monorepo (
/Users/raffaelsheikh/Documents/GitHub/boilerplate). Nachschlagewerk für die Modul-Abgleich-Agenten (HiveGrid M001–M017). Alle Pfade absolut. Stand der Quellen: Boilerplate-Repo, gelesen ohne Änderungen.
Überblick
| Paket | npm-Name | Pfad | Zweck (1 Satz) |
|---|---|---|---|
| foundation | @toolctrl/foundation |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation |
Reine, DB-/Framework-agnostische Querschnitt-Primitiven (Errors, Audit, Permissions, Flags, Idempotency, Adapters, Notifications, Workflows, Concurrency, sichere Outbound-HTTP). |
| view-models | @toolctrl/view-models |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models |
VM-State-Maschine, Action-Callbacks und Registry-Gate/Shell-Registry-Typen für UI-ViewModels. |
| entitlements | @toolctrl/entitlements |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/entitlements |
Feature-Gate-Registry, Entitlement-Auswertung, Standard-Pläne, Produkt-Blueprints, AI-Quotas/Overage. |
| feature-flags | @toolctrl/feature-flags |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/feature-flags |
Feature-Flag-Engine v2: Targeting-Regeln, Evaluation, Cache, Invalidierung, React-Client-Hooks. |
| i18n | @toolctrl/i18n |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n |
Locale-Config, Intl-Formatter (Zahl/Währung/Datum/Liste), ICU-MessageFormat, RTL, useTranslate-Factory. |
| logger | @toolctrl/logger |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/logger |
Pino-Logger-Factory mit Redaction sensibler Felder. |
| observability | @toolctrl/observability |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/observability |
PII-scrubbender OpenTelemetry-SpanProcessor (framework-agnostisch). |
| metrics | @toolctrl/metrics |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/metrics |
prom-client Registry/Default-Metriken, Token-Auth für /metrics, AI-Cost-Counter mit Cardinality-Disziplin. |
| error-reporter | @toolctrl/error-reporter |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/error-reporter |
Error-Reporter-Interface, Sanitizer, Sentry-Adapter, OTel-Tracing-Bootstrap. |
| url | @toolctrl/url |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/url |
Kanonische Pfad-/URL-Builder (app/admin/api, host-aware). |
| config | @toolctrl/config |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/config |
Env-Variablen-Katalog + Validierung, Web/API/Worker-Config-Loader, Domain-Routing, Session-Cookie-Policy, Secret-Validatoren. |
| shared | @toolctrl/shared |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/shared |
Aktuell leer (src/index.ts enthält nur export {}). Platzhalter für künftige dependency-freie Cross-Cutting-Typen/Utils. |
Konventionen über alle Pakete:
"type": "module","sideEffects": false,"private": true,version0.0.0.- Exports zeigen auf
./src/*.ts(kein Build-Step;build=typecheck). - Interne Imports verwenden
.js-Endungen (ESM/NodeNext), z. B.export * from "./errors.js". - Tests liegen als
*.test.ts(x)neben der Quelle;pnpm test=vitest run src. - Pakete sind bewusst Prisma-/Framework-frei: DB-Zugriff wird per strukturell typisiertem Client-Parameter (
*Client) bzw. Loader-Callback injiziert.
@toolctrl/foundation
Zweck: Zentrale, reine Querschnitt-Bausteine ohne harte DB-/HTTP-Framework-Abhängigkeit. Prisma-Tabellen werden über strukturell typisierte Client-Interfaces erwartet (Dependency Injection statt Import).
Zentrale Dateien
- Barrel:
/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/index.ts(re-exportiert errors, audit, permissions, flags, idempotency, adapters, notifications, workflows, concurrency). package.jsonexportiert zusätzlich./outbound-http.
Haupt-Exporte je Modul
| Datei (absolut) | Exporte | HiveGrid-Relevanz |
|---|---|---|
…/packages/foundation/src/errors.ts |
CatalogError (Klasse), CatalogErrorDefinition, catalogRegistry (leer-frozen), foundationErrors (forbidden 403, notFound 404, idempotencyConflict 409, idempotencyInProgress 409), toPinoLogObject(error), Typen JsonValue/JsonPrimitive |
Querschnitt „Klartext-Diagnostik/CatalogError" — strukturierter Fehler mit code/status/i18nKey/details für alle Module M001–M017. toPinoLogObject für Logger-Integration. |
…/packages/foundation/src/audit.ts |
auditEvent(input, client), withAuditMiddleware(handler, buildEvent, client), Typen AuditEventInput, AuditEventClient |
Querschnitt „Audit-Middleware". withAuditMiddleware wrappt Service-Handler und schreibt nach Erfolg ein AuditEvent. Relevant für jede mutierende Aktion (M001–M017). |
…/packages/foundation/src/permissions.ts |
requirePermission(ctx, permission), withTenantScope(tenantId, value), withPermission(permission, getContext, handler), withOwnerCheck(ctx, value), Typ PermissionContext |
Querschnitt „withTenantScope/withPermission/withOwnerCheck". Tenant-Scoping + Permission-/Owner-Gating für alle Tenant-Module. Bei Fehlschlag CatalogError(notFound) (404, nicht 403 — Existenz-Versteckung). |
…/packages/foundation/src/flags.ts |
defineFlag(def), featureFlag(input), selectFlagRecord(input), normalizeFlagScope(record), Typen FlagDefinition, FlagRecord, FlagResolutionInput, NormalizedFlagScope |
Querschnitt „defineFlag/featureFlag". Leichtgewichtige Flag-Auflösung (user > tenant > global, override). Für einfache Gates ohne Targeting-Engine. |
…/packages/foundation/src/idempotency.ts |
withIdempotency(input, client, operation), Typen IdempotencyClient, IdempotencyResponse |
Querschnitt „IdempotencyClient". Replay-sichere Mutationen (scope+key), In-Process-Lock, stabiler Fingerprint-Hash, 409-Konflikt bei Hash-Mismatch / In-Progress. Für POST-Endpunkte mit Idempotency-Key in jedem Modul. |
…/packages/foundation/src/adapters.ts |
defineAdapter(def), getAdapter(key), Typen AdapterDefinition, AdapterStatus (not_configured/configured/healthy/degraded/unavailable) |
Querschnitt „defineAdapter/getAdapter". Globales Adapter-Register (Provider-Slots) mit Status. getAdapter liefert Fallback not_configured. Für Provider-/Integrations-Module. |
…/packages/foundation/src/notifications.ts |
notify(input, client, prefs), notifyMany(...), bundleNotifications(inputs), isNotificationEnabled(input, prefs), assertI18nKey(key), Typen NotificationInput, NotificationClient, NotificationPreference, NotificationBundle, NotificationPreferenceChannel (IN_APP/EMAIL), NotificationDeliveryStatus (PENDING/SENT/FAILED/SKIPPED/READ) |
Querschnitt „notify/bundleNotifications". Tenant-pflichtige Notifications mit Preference-Check, Upsert per sourceKey, Metadata-Sanitizing (Redaction sensibler Keys), Bundling pro Tenant/User/Channel/Category. assertI18nKey erzwingt i18n-Key-Form. |
…/packages/foundation/src/workflows.ts |
workflowBlockContracts, getWorkflowBlockContract(value), CORE_/PRO_WORKFLOW_BLOCK_TYPES, NATIVE_WORKFLOW_TRIGGER_SUPPORTED_BLOCK_TYPES, extractWorkflowReferences(wf), getMissingWorkflowReferences(...), validateWorkflowRequiredInputs(wf), preflightWorkflow(input), getNativeWorkflowTriggerCapabilityErrors(blocks), Typen WorkflowBlockType, WorkflowBlockContract, WorkflowPreflightResult u. a. |
Workflow-/Automation-Domäne (Block-Verträge, Referenz-Extraktion, Preflight). Relevant für ein evtl. Workflow-/Automations-Modul; ansonsten Querschnitt für Template-Variablen-Validierung. |
…/packages/foundation/src/concurrency.ts |
mapWithConcurrency(items, concurrency, worker) |
Querschnitt-Utility: begrenzte parallele Verarbeitung (Batch-Jobs, Imports). |
…/packages/foundation/src/outbound-http.ts (Subpath @toolctrl/foundation/outbound-http) |
fetchOutboundHttpWithRedirects(input, init, options), readLimitedResponseText(response, limit), validateOutboundHttpUrl(endpoint), Klasse OutboundHttpUrlValidationError, Typen OutboundHttpFetchOptions, OutboundHttpAddressResolver, LimitedResponseBody |
Querschnitt-Sicherheit: SSRF-Schutz (Block private/internal IPs v4+v6, DNS-Resolve-Check, Redirect-Limit, Timeout, Response-Size-Limit). Für jede ausgehende HTTP-Aktion (Webhooks, httpRequest-Block, Integrationen). |
Abhängigkeit: @toolctrl/i18n (workspace).
Genutzte Prisma-Modelle (per Client-Injection erwartet, Definition siehe unten):
AuditEvent—/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma:55IdempotencyKey—…/prisma/schema/core.prisma:84(Unique@@unique([scope, key], name: "idempotency_key_scope_key"), passt exakt zurIdempotencyClient-Where-Form)NotificationDelivery/UserNotificationPreference—…/prisma/schema/notifications.prisma:14/:41
@toolctrl/view-models
Zweck: Reine Typ-/Helper-Schicht für UI-ViewModels — VM-State-Maschine, Action-Callbacks, Registry-Gate und Shell-Registry-Item-Typen.
Zentrale Datei: /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/src/index.ts (einziges Quellmodul).
| Export | Beschreibung | HiveGrid-Relevanz |
|---|---|---|
VMState<T> (Union), VMStatus (idle/loading/ready/empty/error) |
Diskriminierte Status-Maschine; error trägt { messageKey; code? } (i18n-Key, kein Klartext) |
Querschnitt „VMState" — einheitlicher Loader-/Empty-/Error-State für alle Listen-/Detail-VMs in M001–M017. |
ActionCallbacks<T> (onCreate/onUpdate/onDelete/onRefresh) |
Standard-CRUD-Callback-Vertrag | Querschnitt „ActionCallbacks" — konsistente Action-Verdrahtung. |
RegistryGate ({ permission?; flag? }), I18nLabel ({ labelKey; descriptionKey? }) |
Gating-/Label-Bausteine | Querschnitt „RegistryGate" — Sidebar/Breadcrumb/Mobile/Portal-Einträge per Permission + Flag gaten. |
SidebarRegistryItem, BreadcrumbRegistryItem, MobileRegistryItem, PortalRegistryItem, ShellRegistries |
Shell-Navigations-Registry-Typen (alle mit RegistryGate + I18nLabel) |
Navigations-Registries für die App-Shell; jedes Modul registriert seine Einträge gegated. |
ready<T>(data), empty<T>() |
Konstruktoren für VMState |
Helper. |
assertI18nLabel(label) |
Erzwingt i18n-Key-Form für labelKey/descriptionKey (wirft sonst) |
i18n-Disziplin in Registries. |
Keine Runtime-Dependencies.
@toolctrl/entitlements
Zweck: Single Source of Truth für Feature-Gates, Plan-Stubs, Produkt-Blueprints und AI-Quotas/Overage; reine Entitlement-Auswertung.
Zentrale Datei (Barrel): /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/entitlements/src/index.ts
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/src/features.ts |
featureKeys (19 Keys: crm-basic, support-tickets, knowledge-base-read/-tenant, users, email-marketing, imported-lists, crm-based-lists, onboarding, api, workflow-engine, mcp, advanced-builder, import-export, rate-limit-per-minute/-second, priority-support, ai-credits, private-generations), featureGateRegistry, getFeatureGate, isFeatureKey, assertKnownFeatureKey; Typen FeatureKey, FeatureCategory, FeatureLimitType (not-included/included/monthly/max/unlimited) |
Querschnitt Entitlements: kanonische Feature-Keys + Limit-Typen für Gating in allen Modulen. |
…/src/evaluate.ts |
evaluateEntitlement(input), entitlementLimitTypes (numerisch 0–4), Typen EntitlementDecision, EntitlementDecisionReason, EvaluateEntitlementInput |
Kern-Entscheidung „darf der Tenant?" inkl. Trial-/Subscription-/Usage-Logik (max/monthly mit remaining). |
…/src/plans.ts |
entitlementPlanIds, standardEntitlementPlans, getStandardEntitlementPlan, listStandardEntitlementPlanIds, getStripeProductPlaceholder/getStripePricePlaceholder; Typen EntitlementPlanStub, EntitlementPlanFeatureAssignment u. a. |
Standard-Plan-Stubs + Stripe-Placeholder-Mapping (Billing-Querschnitt). |
…/src/blueprints.ts |
productBlueprints, productBlueprintIds, getProductBlueprint, getDefaultProductBlueprint; Typen ProductBlueprintDefinition, ProductBlueprintFeatureDefinition |
Produkt-Blueprints (Feature-Bündel pro Produkttyp). |
…/src/product-access.ts |
evaluateProductAccess(input); Typen ProductAccessInput, ProductAccessDecision, TenantFeatureOverride (enabled/disabled/inherit) |
Produkt-Zugriffsentscheidung inkl. Tenant-Override. |
…/src/ai-quotas.ts |
aiQuotaCapabilityKeys, standardAIQuotaDefaults, getAIQuotaPlanDefaults, resolveTenantAIQuota, parseTenantAIQuotaOverride; Typen AIQuotaPlanDefaults, ResolvedTenantAIQuota, TenantAIQuotaOverride |
AI-Quoten pro Plan/Tenant — relevant falls HiveGrid AI-Capabilities gated. |
…/src/ai-overage.ts |
resolveTenantAIOverage, computeMarkedUpCostCents, roundUpToBlock, getAIOveragePlanDefaults, Defaults-Konstanten (AI_OVERAGE_DEFAULT_MULTIPLIER 1.5, …_BLOCK_CENTS 10, Min-Werte) |
AI-Overage-Billing (Markup/Block-Rundung). |
Keine Runtime-Dependencies (rein, testbar). Verknüpfte Prisma-Modelle: SubscriptionFeature (…/prisma/schema/subscriptions.prisma:65), PortalSubscriptionFeature (…/prisma/schema/portals.prisma:149).
@toolctrl/feature-flags
Zweck: Feature-Flag-Engine v2 mit Targeting-Regelbaum, zeit-/abhängigkeitsbasierter Evaluation, Variant-Bucketing, Eval-Cache und Cross-Process-Invalidierung; optionaler React-Client.
Subpath-Exports (package.json): . (Barrel), ./targeting, ./cache, ./client.
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/packages/feature-flags/src/index.ts |
re-exportiert targeting + evaluateFlag, getFeatureFlagVariant, Cache- und Publisher-API |
Haupteinstieg. |
…/src/evaluate.ts |
evaluateFlag(name, ctx, options), getFeatureFlagVariant(...), Typen StoredFeatureFlag, FlagVariant, FlagLoader, EvaluateFlagResult (reason: u. a. flag-not-found/disabled/parent-disabled/time-window-future/matched), EvaluateFlagOptions |
Querschnitt Feature-Flags (mächtige Variante zu foundation/flags): Zeitfenster, Parent-Dependency (Zyklus-Schutz maxDepth 8), sticky Variant-Bucketing. DB-frei via FlagLoader-Callback. |
…/src/targeting/types.ts |
Regel-Union TargetingRule (boolean/allowlist/percentage/plan-tier/role-based/time-based/composite), EvaluationContext (tenantId/userId/email/planTier/roles/now) |
Targeting-Modell — Rollouts pro Tenant/Plan/Rolle/Prozent für jedes Modul. |
…/src/targeting/evaluator.ts |
evaluateRule(rule, ctx) |
Reine Regel-Auswertung (kein I/O). |
…/src/targeting/percentage.ts |
computeBucket(key, salt), isInRolloutBucket(...) |
Sticky Percentage-Rollout. |
…/src/cache.ts |
createFlagEvalCache(...), buildCacheKey, hashContext, FEATURE_FLAGS_INVALIDATION_CHANNEL ("feature-flags:invalidate"), Typ FlagEvalCache |
Eval-Cache + Invalidierungs-Channel-Konstante. |
…/src/publisher.ts |
publishFeatureFlagInvalidationViaStore(...), publishFeatureFlagInvalidationOnce(...), Typ PublishFeatureFlagInvalidationOptions |
Cross-Process-Cache-Invalidierung (via shared-store). |
…/src/client/context.tsx (Subpath ./client) |
FeatureFlagProvider, useFeatureFlag, useFeatureFlagEnabled, useFeatureFlagVariant, Typen FeatureFlagProviderProps, FeatureFlagsHydration |
React-Hooks/SSR-Hydration für Flag-gegatete UI. |
Dependencies: @toolctrl/shared-store (Pub/Sub); optionale Peers @toolctrl/logger, react.
Prisma-Modelle: FeatureFlag, FeatureFlagFilter, FeatureFlagAudit (append-only Audit-Trail) — /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/featureFlags.prisma:1/32/44. StoredFeatureFlag spiegelt eine Teilmenge der FeatureFlag-Row, bleibt aber Prisma-frei.
@toolctrl/i18n
Zweck: Locale-Konfiguration, SSR-sichere Intl-Formatter, ICU-MessageFormat-Pluralisierung, RTL-Erkennung und useTranslate-Hook-Factory.
Subpath-Exports: . (Barrel), ./intl, ./icu, ./useTranslate.
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/packages/i18n/src/index.ts |
defaultLocale ("de"), supportedLocales (["de","en"]), i18nNamespaces (translations, errors, mail, common, settings, billing, crm, auth, emailMarketing), i18nConfig, isSupportedLocale, getDirection, isRTL; re-exportiert Intl + ICU + useTranslate |
Querschnitt i18n: Namespaces/Locales als SSOT; assertI18nKey/assertI18nLabel (in foundation/view-models) erzwingen Key-Form passend zu diesen Namespaces. |
…/src/intl/index.ts → number.ts/currency.ts/date.ts/list.ts |
formatNumber, formatPercent, formatCompactNumber, formatCurrency, formatDate, formatRelativeTime, formatList (+ Options-Typen) |
Einheitliche, locale-explizite Formatierung server- wie clientseitig (Listen, Detail-Views, Mails). |
…/src/icu/index.ts → plural.ts |
formatIcu, createIcuFormatter, Typen IcuValues, IcuOptions, IcuFormatter |
ICU-Plurale/Select für korrekte mehrsprachige Texte. |
…/src/useTranslate.ts |
createUseTranslate(deps, defaults), isIcuMessage, Typen Translator, ReactI18nextLike, UseTranslateOptions |
React-useTranslate-Factory mit automatischer ICU-Erkennung; react-i18next wird injiziert (kein harter Dep). |
Dependencies: i18next, intl-messageformat.
Konvention (Querschnitt „i18n-assert"): i18n-Keys folgen dem Muster ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$ — durchgesetzt von assertI18nKey (foundation/notifications.ts) und assertI18nLabel (view-models). Fehler-Objekte tragen statt Klartext einen i18nKey (siehe CatalogError, VMState.error.messageKey).
@toolctrl/logger
Zweck: Pino-Logger-Factory mit eingebautem Redaction sensibler Felder.
Zentrale Datei: /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/logger/src/index.ts
| Export | Beschreibung | HiveGrid-Relevanz |
|---|---|---|
createLogger(options?) |
Erzeugt Pino-Logger; redact.paths deckt authorization, cookie, password, token, secret, apiKey, redisUrl, connectionString (inkl. *.-Wildcards) ab, Censor [Redacted] |
Querschnitt Logging: sicheres, strukturiertes Logging für alle Module. Spielt mit toPinoLogObject (foundation/errors) zusammen. |
createChildLogger(logger, bindings) |
Child-Logger mit Bindings (z. B. requestId, tenantId) |
Request-/Tenant-Scoped Logging. |
resolveLogLevel(env?) |
Liest TOOLCTRL_LOG_LEVEL/LOG_LEVEL (Default info) |
Env-getriebenes Level. |
defaultLogger |
Vorinstanziierter Default | — |
Typen LogLevel, ToolctrlLogger, CreateLoggerOptions |
— | — |
Dependency: pino.
@toolctrl/observability
Zweck: Framework-agnostischer PII-scrubbender OpenTelemetry-SpanProcessor (Decorator über bestehenden Processor; keine harte OTel-SDK-Dependency).
Zentrale Datei: /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/observability/src/pii-span-processor.ts (Barrel: …/src/index.ts).
| Export | Beschreibung | HiveGrid-Relevanz |
|---|---|---|
PIISpanProcessor |
Wrappt Delegate-Processor, redigiert Attribute in onEnd() |
Querschnitt Observability: verhindert PII-Leak in Traces für alle Module. |
HEADER_ALLOWLIST |
Erlaubte Header-Attribute (Rest, u. a. authorization/cookie/x-api-key, wird gedroppt) |
— |
redactSpanAttributes, scrubDbStatement, scrubUrlQuery, isHeaderAttribute |
Einzel-Scrubber (Query-String → ?[scrubbed], DB-Literale → ?) |
— |
Typen DelegateSpanProcessor, PiiScrubableSpan |
Strukturelle OTel-Shapes (keine SDK-Bindung) | — |
Keine Runtime-Dependencies.
@toolctrl/metrics
Zweck: prom-client basierte Metrics-Registry, Default-HTTP-Metriken, Token-Auth für den /metrics-Endpoint und cardinality-disziplinierter AI-Cost-Counter.
Zentrale Datei (Barrel): /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/metrics/src/index.ts
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/src/registry.ts |
createMetricsRegistry(options), Typen MetricsRegistry, CreateMetricsRegistryOptions |
Querschnitt Metrics: zentrale Registry je App. |
…/src/defaults.ts |
createDefaultMetrics(registry), HISTOGRAM_BUCKETS_SECONDS, Typen DefaultMetrics, LatencyHistogramOptions |
Standard-Latenz-/Request-Metriken. |
…/src/auth.ts |
isMetricsEnabled(env), validateMetricsTokenAuth(options), redactMetricsToken(token), Typen MetricsTokenAuthResult, MetricsTokenAuthOptions |
Schützt /metrics-Endpoint per Token. |
…/src/ai-cost.ts |
recordAICostCents(input, registry), resetAICostMetricsForTests(), Konstanten MAX_TENANT_BUCKETS (100), OTHER_BUCKET, ANONYMOUS_BUCKET, Typ AICostMetricInput |
AI-Kosten-Counter ai_cost_cents_total{tenant_bucket,provider,model,capability} mit Top-N+Other-Bucketing (Cardinality-Schutz). |
Dependency: prom-client.
@toolctrl/error-reporter
Zweck: Provider-agnostisches Error-Reporting (Interface + No-op + Sentry-Adapter), Sanitizing sensibler Daten und optionaler OTel-Tracing-Bootstrap.
Zentrale Datei (Barrel): /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/error-reporter/src/index.ts
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/src/index.ts |
reportError(reporter, event) (schluckt Reporter-Fehler), createNoopErrorReporter(), Typen ErrorReporter, ErrorReportEvent, ErrorReportContext, ErrorReportSeverity |
Querschnitt Error-Reporting: einheitliches Melden inkl. component/operation/requestId/tenant-Kontext. Sanitisiert vor Versand. |
…/src/sanitize.ts |
sanitizeErrorReportValue(value), __internal |
Entfernt sensible Felder vor Reporting. |
…/src/sentry.ts |
createSentryErrorReporter(options), sanitizeSentryEvent(raw), SENTRY_HEADER_ALLOWLIST, SENTRY_DROP_EXCEPTION_TYPES, Typen SentryErrorReporterOptions, SentryLikeModule, SentryInitOptions |
Optionaler Sentry-Adapter (Sentry-SDK strukturell injiziert). |
…/src/tracing.ts |
initializeTracing(options), shutdownTracing(), Typen TracingOptions, NodeSdkLikeModule, OtlpExporterLikeModule |
OTel-NodeSDK-Bootstrap mit OTLP-Exporter; OTel-Pakete via dynamic import optional. |
Keine festen Runtime-Dependencies (SDKs strukturell/optional).
@toolctrl/url
Zweck: Kanonische, host-aware Pfad- und URL-Builder für App-/Admin-/API-Surfaces (multi-tenant Subdomains).
Zentrale Datei: /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/url/src/canonical.ts (Barrel: …/src/index.ts).
| Export | Beschreibung | HiveGrid-Relevanz |
|---|---|---|
appPath/appUrl (mit tenantSlug), adminPath/adminUrl, apiPath/apiUrl (mit version v1), default |
Bauen relative Pfade bzw. absolute URLs (mode: "host-aware", Default-Protokoll https) |
Querschnitt Routing/Links: konsistente Tenant-App-, Admin- und API-Links für alle Module (M001–M017). |
Typen AppUrlOptions, AdminUrlOptions, ApiUrlOptions, CanonicalUrlMode, ApiVersion, PathInput u. a. |
— | — |
Keine Runtime-Dependencies.
@toolctrl/config
Zweck: Typisierter Env-Variablen-Katalog (SSOT für Doku/Drift), Validierungs-Helfer, Web/API/Worker-Config-Loader, Domain-Routing und Session-Cookie-Policy.
Zentrale Datei (Barrel): /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/config/src/index.ts
| Datei (absolut) | Schlüssel-Exporte | HiveGrid-Relevanz |
|---|---|---|
…/src/index.ts |
listEnvVariables(opts), getEnvVariableDefinition(name), groupEnvVariablesByClassification(), getRequiredEnvVariableNames(opts), validateEnv(input, opts), envVariableDefinitions |
Querschnitt Konfiguration: Env-Anforderungen pro Runtime-Target ableiten/validieren. |
…/src/catalog.ts |
envVariableDefinitions (große Liste; jede mit classification, targets, kind, source, requiredInProduction) |
Single Source of Truth aller Env-Variablen. |
…/src/types.ts |
Typen RuntimeTarget (shared/web/api/worker), EnvClassification (6 Klassen), EnvVariableDefinition, Web/Api/Worker-Config-Shapes (WebConfig, ApiConfig, WorkerConfig, …) |
Config-Vertrag. |
…/src/web.ts / api.ts / worker.ts |
loadWebConfig/loadRequiredWebConfig (+ WebConfigError); analog API/Worker |
Runtime-Config-Loader mit Diagnostics. |
…/src/routing.ts |
getDomainRoutingConfig, hostMatches, normalizeHost, Typen DomainRoutingConfig, DomainRoutingEnv |
Multi-Tenant Domain-Routing (passt zu @toolctrl/url). |
…/src/session-cookie.ts |
resolveSessionCookiePolicy, resolveApiSessionCookiePolicy, Typen SessionCookiePolicy, SessionCookieSameSite |
Sichere Session-Cookie-Policy. |
…/src/secret-validator.ts |
validateRequiredSecretString, validateOptionalSecretString, validateOptionalSecretUrl, validateBooleanFlag |
Secret-/Flag-Validierung mit Diagnostics. |
…/src/plugin-lifecycle.ts |
resolvePluginLifecycleRuntimeEnv, Typ PluginLifecycleRuntimeEnv |
Plugin-Lifecycle-Env. |
Keine deklarierten Runtime-Dependencies. README dokumentiert die Klassifikation und das vollständige Inventar (…/packages/config/README.md).
@toolctrl/shared
Zweck: Reservierter Platz für dependency-freie, app-übergreifende Typen/Konstanten/Utilities.
Status: Leer. /Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/shared/src/index.ts enthält ausschließlich export {};. README (…/packages/shared/README.md) beschreibt nur geplante Kandidaten und die Regel „kein web/API/worker/provider/DB-spezifischer Code". Für M001–M017 derzeit ohne nutzbaren Inhalt.
Relevante Prisma-Modelle (Querschnitt) — exakte Pfade
| Modell | Pfad | Genutzt von |
|---|---|---|
AuditEvent |
/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/core.prisma:55 |
foundation audit.ts (AuditEventClient). Felder u. a. tenantId, actorType (req.), action, targetType/Id, requestId, outcome (Default success), dataSensitivity, regulatoryScope[], metadata, previousHash/eventHash (Hash-Chain). |
IdempotencyKey |
…/prisma/schema/core.prisma:84 |
foundation idempotency.ts. @@unique([scope, key], name: "idempotency_key_scope_key") deckt die IdempotencyClient-Where-Form, expiresAt-Index für Cleanup. |
NotificationDelivery |
…/prisma/schema/notifications.prisma:14 |
foundation notifications.ts. Enums NotificationDeliveryStatus/NotificationPreferenceChannel; @@unique([tenantId, userId, channel, sourceKey]) für Upsert. |
UserNotificationPreference |
…/prisma/schema/notifications.prisma:41 |
foundation notifications.ts (NotificationPreference). |
FeatureFlag / FeatureFlagFilter / FeatureFlagAudit |
…/prisma/schema/featureFlags.prisma:1 / :32 / :44 |
feature-flags-Paket (StoredFeatureFlag spiegelt Teilmenge; v2-Felder rules/variants/enabledFrom/enabledUntil/parentFlagId). |
SubscriptionFeature |
…/prisma/schema/subscriptions.prisma:65 |
entitlements (Plan-Feature-Zuordnung). |
PortalSubscriptionFeature |
…/prisma/schema/portals.prisma:149 |
entitlements (Portal-Features). |
CI-/Verify-Scripts (Querschnitt-relevant)
Pfade: /Users/raffaelsheikh/Documents/GitHub/boilerplate/scripts/…; npm-Scripts in …/boilerplate/package.json.
| Script (npm) | Datei | Bezug |
|---|---|---|
verify:i18n |
scripts/i18n-check.ts + scripts/verify-hardcoded-strings.mjs + ESLint über packages/ui-* |
i18n-Disziplin (Querschnitt i18n / i18n-assert). |
verify:env-drift |
scripts/check-env-drift.mjs |
Prüft @toolctrl/config-Katalog gegen .env*-Beispiele + Code. |
| (Baseline) | scripts/i18n-audit.mjs |
Baseline-Scan hardcodierter DE/EN-Strings (zählt, erzwingt nicht). |
verify:audit-cascade-guard (Datei vorhanden) |
scripts/verify-audit-cascade-guard.mjs |
Schützt Audit-Cascade-Verhalten (prisma/schema/accounts.prisma). |
verify:workflow-outbox-native |
u. a. packages/foundation/src/workflows.test.ts |
Workflow-Block-/Preflight-Verträge (foundation workflows.ts). |
verify:tenant-isolation-report |
scripts/tenant-isolation-report.ts |
Tenant-Scoping-Report (passt zu withTenantScope). |
Zusätzlich besitzt jedes Paket pnpm test (vitest über src) und pnpm typecheck. Test-Dateien liegen jeweils neben der Quelle (z. B. audit.test.ts, idempotency-Coverage in index.test.ts/concurrency.test.ts, evaluate.test.ts, pii-span-processor.test.ts, secret-validator.test.ts).
Kurz-Mapping „angefragte Querschnitt-Patterns → Fundort"
| Angefragtes Pattern | Fundort (Export → Datei) |
|---|---|
| Audit-Middleware | withAuditMiddleware, auditEvent → …/foundation/src/audit.ts |
| Klartext-Diagnostik / CatalogError | CatalogError, foundationErrors, catalogRegistry, toPinoLogObject → …/foundation/src/errors.ts |
| i18n-assert | assertI18nKey → …/foundation/src/notifications.ts; assertI18nLabel → …/view-models/src/index.ts; Key-Regex; verify:i18n |
| withTenantScope / withPermission / withOwnerCheck | alle → …/foundation/src/permissions.ts (+ requirePermission) |
| defineFlag / featureFlag | → …/foundation/src/flags.ts (leichtgewichtig); mächtige Engine: evaluateFlag → …/feature-flags/src/evaluate.ts |
| IdempotencyClient | withIdempotency, IdempotencyClient → …/foundation/src/idempotency.ts |
| defineAdapter / getAdapter | → …/foundation/src/adapters.ts |
| notify / bundleNotifications | notify, notifyMany, bundleNotifications, isNotificationEnabled → …/foundation/src/notifications.ts |
| VMState / ActionCallbacks / RegistryGate | alle → …/view-models/src/index.ts |